
# サーバー側

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

## 使う理由

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

## 例

```dart
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` で実行されます。

## 関連項目

- [Web スターターのフィルター](../spring-boot-starter-web/filters.md)
- [ハンドラーマッピング](../spring-boot-starter-web/server/handler-mappings.md)
- [タイムアウト](../spring-boot-starter-web/server/timeouts.md)
