サーバー側
これらは、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 スターターのハンドシェイクのチェックは、どちらもこれを使います。
- オリジンは大文字小文字を区別せずに、パターンは区別して比較されます。
- パターンは
*(https://*.shop.example。*は Spring の.*と同じく任意のテキストに一致するため、*.shop.exampleは任意のスキームに一致します) と、末尾のポートリスト (http://localhost:[3000,3001]、[*]: 任意のポート、またはポートなし) を受け取ります。 - 値にはカンマで区切って複数を列挙でき、末尾の
/は無視されます。 - Spring との違いが一つあります。
maxOriginLength(1024) 文字を超えるオリジンは決して許可されません。パターンは、オリジンの長さに比例して増える時間で照合されます (バックトラックする正規表現は使いません)。
Spring (Java) との対応
名前は Spring WebFlux の ServerHttpRequest / ServerHttpResponse と Spring MVC の HandlerMapping に従います。RequestDeadline は追加されたものです。リクエストはスレッドではなく Zone で実行されます。