
# タイムアウト

時間を制限するプロパティは三つあります。`server.connection-timeout` (ネットワークが沈黙している)、`server.request-timeout` (アプリケーションが遅い)、`spring.mvc.async.request-timeout` (`SseEmitter` が開いたまま) です。

## 使う理由

いつまでも待つサーバーは、誰にでも足止めされてしまいます。

- ボディを送り始めてから何も送らなくなったクライアントは、接続とリクエストを開いたままにします。
- アイドル状態のキープアライブ接続が積み上がります。
- 遅いデータベースや遅いリモートサービスを待つハンドラーは、とっくに諦めたクライアントを待たせ続けます。

各プロパティは、これらのケースの一つを扱います。互いの代わりにはなりません。

| プロパティ | 制限するもの | デフォルト | 超えると |
|---|---|---|---|
| `server.connection-timeout` | リクエストボディを読む間の沈黙、アイドル状態のキープアライブ接続 | `60s` | `408` で接続が閉じる。アイドル接続は閉じる |
| `server.request-timeout` | フィルターとハンドラーが応答を始めるまでの時間 | 制限なし | `503`。リクエストの `RequestDeadline` が過ぎている |
| `spring.mvc.async.request-timeout` | 独自のタイムアウトを持たない `SseEmitter` の寿命 | 制限なし | `onTimeout` コールバックの後、エミッターが完了する |

## 例

```yaml
# lib/resources/application.yml
server:
  connection-timeout: 30s
  request-timeout: 10s
spring:
  mvc:
    async:
      request-timeout: 30m
```

```properties
server.connection-timeout=30s
server.request-timeout=10s
spring.mvc.async.request-timeout=30m
```

ステップの間で期限を読むハンドラー:

```dart
import 'package:spring_boot_starter_web/spring_boot_starter_web.dart';

@RestController()
@RequestMapping('/api/reports')
class ReportController {
  ReportController(this.sales, this.stock);
  final SalesClient sales;   // Feign クライアント: リクエストの期限で止まる
  final StockService stock;

  @GetMapping('/daily')
  Future<Report> daily() async {
    final totals = await sales.totals();
    RequestDeadline.current?.check(); // もう誰も待っていない: ここで止める
    final levels = await stock.levels();
    return Report(totals, levels);
  }
}
```

## `server.connection-timeout`

- **型:** `Duration` (`60s`、`500ms`、`PT1M`。単なる数値は **ミリ秒**)。**デフォルト:** `60s`。
- **制限なし:** Tomcat と同じく、`0` または任意の負の値 (`-1`)。
- **動作 1: 停滞したボディ。** リクエストボディを読む間、チャンクが届くたびにタイマーが再開します。この時間何も届かないと、読み込みは `408 Request Timeout` の `ProblemDetail` (詳細 `The request body did not arrive in time`) で失敗し、応答の後に接続が閉じられます。読む側自身が止まっている時間 (バックプレッシャー) は数えません。
- **動作 2: アイドル接続。** この時間リクエストのないキープアライブ接続は閉じられます。これは `dart:io` の `idleTimeout` です。Tomcat のキープアライブのタイムアウトも、その接続タイムアウトです。
- **しないこと:** 遅いハンドラー、遅い応答、送り続けているアップロードの合計時間は制限しません。ハンドラーは `server.request-timeout` で制限されます。
- **変更する理由:** 公開サーバーでは引き下げ (`10s`)、沈黙したクライアントが早く接続を解放するようにする。非常に遅い回線で長い中断を挟みながら大きなファイルをアップロードするクライアントのためには引き上げる。
- **例:** `server.connection-timeout=20s`。
- **注意:** `server.connection-timeout=60` は 60 秒ではなく 60 ミリ秒です。単位を書いてください。

## `server.request-timeout`

- **型:** `Duration`。**デフォルト:** 未設定、つまり制限なし。`0` や負の値も制限なしです。
- **動作:** フィルターとハンドラーは、この時間内に応答を始めなければなりません。先に時間が過ぎると:
  - クライアントは `503 Service Unavailable`、詳細 `The request did not complete in time.` の `ProblemDetail` を受け取ります。制限やハンドラーが何をしていたかには触れません。
  - その後ハンドラーがレスポンスに対して行うことは破棄されます。二つ目の応答もエラーもありません。
  - 503 は、他の 5xx の応答と同じく、同じ種類について 10 秒に最大 1 回、警告としてログに記録されます。
- **期限。** リクエストは、その長さの (`spring_web_dart` の) `RequestDeadline` の下で実行されます。これはトランザクションと同じく `Zone` で運ばれるので、`await` を追跡します。リクエストが呼ぶコードはそれを読めます。

| メンバー | 内容 |
|---|---|
| `RequestDeadline.current` | 現在実行中のコードの期限、または `null` |
| `budget` | 与えられた長さ |
| `remaining` | 残り時間。負になることはない |
| `isExpired` | 時間が過ぎたかどうか |
| `check()` | 時間が過ぎていれば `RequestDeadlineExceededException` を投げる |
| `RequestDeadline.run(budget, body)` | 独自の期限の下で `body` を実行する。別の期限の中では、早く終わるほうが採用される |

- **Feign クライアントはこれを尊重します。** コントローラーが Feign クライアントを通して行う呼び出しは、リクエストの期限で止まります。呼び出しの制限は、自身の `call-timeout` と残り時間のうち早いほうです。その後、呼び出しは例外を投げ、リクエストは 503 で応答されます。
- **期限でのエラーは 503 です。** `RequestDeadlineExceededException`、または期限の最後の 10 ms に投げられたエラーは、503 で応答されます (プロパティなしで独自の `RequestDeadline.run` が投げた `RequestDeadlineExceededException` も)。その他のエラーは自身の応答 (400、500) を保ちます。
- **フィルターも数えます。** フィルター (セキュリティのフィルターチェーンも) は予算の中で実行されます。フィルターが使った時間はハンドラーの分から引かれます。
- **変更する理由:** クライアントがどのみち数秒で諦める公開 API。呼び出し側が独自のタイムアウトを持つバックエンド (それより少し小さく設定する)。遅いリモート呼び出しが積み上がるのを止めるため。
- **例:** `server.request-timeout=10s`。

### しないこと

- **実行中のコードは止めません。** Dart は関数を中断できません。期限を読まないハンドラーは 503 の後も実行を続け、その遅れた応答は破棄されます。ステップの間で `RequestDeadline.current?.check()` を呼ぶか、期限を読むクライアントを使ってください。
- **ストリームは切られません。** ストリーミングを始めたレスポンス (Server-Sent Events、`SseEmitter`、NDJSON、バイトストリーム、`StreamingResponseBody`) は、始まった時点で期限から離れます。ストリームがその後に行うことは、期限なしで実行されます。イベントストリームには `spring.mvc.async.request-timeout` または `SseEmitter(timeout:)` を使ってください。
- **すでに送信中のレスポンスには手を出しません。** ステータスとヘッダーが送られた後は、タイマーは何もしません。
- **WebSocket ハンドシェイクは計測されません。**
- **`@ExceptionHandler` メソッドはこの 503 を見ません。** ハンドラーがまだ実行中だからです。
- **アップロードも数えます。** ハンドラーが遅いアップロードを読むのにかかる時間は数えます。何も送らないボディは、引き続き `server.connection-timeout` が終わらせます。
- **すべてのリクエストに一つの値です。** ルートごとの値はまだありません。
- **カスタマイザーでは変更できません。** ディスパッチャーがプロパティから読みます。`WebServerFactoryCustomizer` では変更できません。

## `spring.mvc.async.request-timeout`

- **型:** `Duration`。**デフォルト:** 未設定、つまり制限なし。
- **動作:** タイムアウトなしで作られた `SseEmitter` (`SseEmitter()`) のタイムアウト。レスポンスが始まった時点から数えます。過ぎると、エミッターの `onTimeout` コールバックが実行され、その後エミッターが完了してストリームが終わります。
- **独自のタイムアウトを持つエミッター** (`SseEmitter(timeout: const Duration(minutes: 5))`) はそれを保ちます。
- **`Stream` や `EventStream` の戻り値はこれで制限されません。** ストリームが終わったとき、クライアントが去ったとき、またはサーバーが停止したときに終わります。
- **変更する理由:** すべてのエミッターに最大寿命を与え、忘れられたエミッターがいつまでも開いたままにならないようにする。ブラウザーの `EventSource` は自分で再接続します。
- **例:** `spring.mvc.async.request-timeout=30m`。

```dart
@GetMapping('/api/orders/updates')
SseEmitter updates() {
  final emitter = SseEmitter(); // spring.mvc.async.request-timeout の後に終わる
  emitter.onTimeout(() => emitter.send('bye'));
  orders.watch(emitter);
  return emitter;
}
```

[サーバー送信イベント](../streaming/sse.md) を参照してください。

## 組み合わせたときの動作

- クライアントが遅い回線で 50 MB のファイルをアップロードし、2 分間止まる: `server.connection-timeout` (60 秒) が 408 で終わらせます。
- 同じアップロードが送り続けるが全体で 3 分かかり、`server.request-timeout=30s` の場合: ボディを読むハンドラーがまだ応答していないので、30 秒で 503 になります。
- `server.request-timeout=10s` で、ハンドラーが Feign の呼び出しを 20 秒待つ: 呼び出しは 10 秒で止まり、クライアントは 503 を受け取ります。
- `server.request-timeout=10s` で、イベントストリームが一時間開いたまま: 始まった時点で期限から離れたので、切られません。`spring.mvc.async.request-timeout=30m` なら、`SseEmitter` は 30 分後に終わります。
- クライアントがリクエストを送らずに接続を開いたままにする: `server.connection-timeout` の後に閉じられます。

シャットダウン時は、`spring.lifecycle.timeout-per-shutdown-phase` が、実行中のリクエストにまだかけられる時間を制限します。[シャットダウン](shutdown.md) を参照してください。

## Spring (Java) との対応

```properties
server.tomcat.connection-timeout=30s
spring.mvc.async.request-timeout=30m
```

重要な違い:

- `server.connection-timeout` は Spring Boot 2.0 にあったキーです。Spring Boot 3 と 4 は `server.tomcat.connection-timeout` (または Jetty や Undertow のキー) を使います。
- 停滞したボディは、ここでは 408 になります。Tomcat では読み込みが失敗し、Spring は 400 で応答します。
- `server.request-timeout` と `RequestDeadline` は拡張です。Spring には同期リクエストの制限がなく、リクエストが行う呼び出しに付いていく制限もありません。
- `spring.mvc.async.request-timeout` は、ここでは `SseEmitter` にだけ適用されます。Spring ではすべての非同期リクエスト (`DeferredResult`、`Callable`、`ResponseBodyEmitter`) に適用され、設定しなければコンテナーのデフォルト (Tomcat: 30 秒) が適用されます。ここでは、設定しなければエミッターはタイムアウトしません。

## 関連項目

- [組み込みサーバー](index.md)
- [過負荷](overload.md)
- [シャットダウン](shutdown.md)
- [サーバー送信イベント](../streaming/sse.md)
- [アップロード](../streaming/uploads.md)
- [ストリーミングレスポンスボディ](../streaming/streaming-response-body.md)
- [すべてのプロパティ](../properties.md)
- [Durations](../../spring-core-dart/conversion/durations.md)
