サーバー側

これらは、Web サーバーとアプリケーションが出会うインターフェースです。Web スターターの dart:io のサーバーとその MockMvc はどちらもこれらを実装しているため、フィルター、コントローラー、WebSocket のエンドポイントは、背後にどのサーバーがあるかを知ることはありません。フィルターやハンドラーを手で書くとき、あるいはサーバーに組み込むライブラリを書くときに使います。

使う理由

ServerHttpRequest に対して書いたフィルターは、本物のサーバーでも MockMvc のテストでも同じように動きます。リクエストの Zone に載せた期限は、コードのどこにあっても、そのリクエストが行うすべての呼び出しを制限します。

例

final pattern = PathPattern.parse('/books/{isbn}');
pattern.match('/books/978-0')?.variables; // {isbn: 978-0}
pattern.matches('/books/');               // false: Spring 6 と同じく末尾のスラッシュは意味を持つ

// どのコントローラーも調べる前に応答するヘルスチェック。
final class HealthMapping implements HandlerMapping {
  @override
  HttpHandler? getHandler(ServerHttpRequest request) => request.path == '/health'
      ? FunctionHttpHandler((request, response) => response.send(200, 'UP'))
      : null;
}

// 中の呼び出しが何をしようと、チェックアウト全体で最大 2 秒。
final order = await RequestDeadline.run(const Duration(seconds: 2), () => checkout(basket));

型

型 Spring 内容
ServerHttpRequest ServerHttpRequest method、uri、path、headers、queryParameters、cookies、remoteAddress、isSecure、attributes、principal。readBodyBytes、readBodyText、contentType を伴う body (一度だけ読めるストリーム)。isWebSocketUpgrade、upgradeToWebSocket。
ServerHttpResponse ServerHttpResponse statusCode と headers (isCommitted まで)、addCookie(ResponseCookie(...))、add、write、flush、addStream、close、done (閉じたか、クライアントが去った)。send(status, text)。
ServerHttpRequestDecorator、ServerHttpResponseDecorator 同じ すべてをデリゲートに転送する。パスやプリンシパルを変えるフィルターで、継承して一つのメンバーだけをオーバーライドする。
ResponseCookie ResponseCookie Set-Cookie の値: maxAge、domain、path、secure、httpOnly、sameSite、partitioned。
Principal java.security.Principal リクエストを送った者 (name)。認証フィルターが設定する。
HttpHandler、FunctionHttpHandler HttpHandler 一つのリクエストに応答する。Web スターターのディスパッチャーはその一つ。
HandlerMapping HandlerMapping リクエストのハンドラーを見つける (getHandler、または null)。Web スターターはすべての HandlerMapping の Bean に @Order の順で問い合わせる。
RequestContextHolder RequestContextHolder currentRequest: 処理中のリクエスト。その処理のどこからでも。各リクエストは自分の Zone で実行される。
RequestDeadline なし リクエストの全処理の時間制限 (下記)。
PathPattern PathPattern パスパターン (下記)。
AllowedOrigins CorsConfiguration のオリジンのチェック サーバーが許可するブラウザーのオリジン (下記)。

RequestDeadline

リクエストの全処理の時間制限で、Zone を通して見つかります。

メンバー 意味
RequestDeadline.run(budget, body) 現在から budget 後を期限として body を実行する。入れ子のものは 2 つのうち早い方で終わり、決して遅くはならない。
RequestDeadline.runUntil(instant, body) 同じことを終了時刻で。
RequestDeadline.current 有効な期限。どの期限の外でも null。
remaining、isExpired 残り時間。
check() 期限が過ぎていれば RequestDeadlineExceededException を投げる。

Web スターターはリクエストをその下で実行し (server.request-timeout)、Feign スターターの呼び出しはそこで止まります。ブラウザーでも動きます。Spring に対応するものはありません。そのタイムアウトは呼び出しごとです。

PathPattern

Spring 6 が解析するとおりのパスパターン: /books/{isbn}、{isbn:\d+}、{*rest}、*、?、**。

メンバー 意味
PathPattern.parse(text) パターンを解析する。
match(path)?.variables パス変数。一致しなければ null。
matches(path) 一致するかどうか。
combine(other) クラスのパターンとメソッドのパターンを結合する。
compareTo 最も具体的なものを先に並べる。

Spring 6 と同じく、末尾のスラッシュは意味を持ちます。

AllowedOrigins

サーバーが許可するブラウザーのオリジンで、Spring が allowedOrigins と allowedOriginPatterns をチェックするのと同じ方法でチェックします。checkOrigin(origin) は Access-Control-Allow-Origin の値か null を返します。Web スターターの CORS と WebSocket スターターのハンドシェイクのチェックは、どちらもこれを使います。

Spring (Java) との対応

名前は Spring WebFlux の ServerHttpRequest / ServerHttpResponse と Spring MVC の HandlerMapping に従います。RequestDeadline は追加されたものです。リクエストはスレッドではなく Zone で実行されます。

関連項目