
# シャットダウン

アプリケーションが閉じると、サーバーは停止します。`server.shutdown=graceful` (デフォルト) は、処理中のリクエストを先に完了させます。`server.shutdown=immediate` はそれらを打ち切ります。

## 使う理由

デプロイ、再起動、スケールダウンは、クライアントにサービスしている最中にプロセスを止めます。サーバーが即座に閉じると、そのクライアントは壊れた接続を受け取ります。注文が半分だけ保存されたり、アップロードが失われたりするかもしれません。グレースフルシャットダウンは、新しい接続の受け付けを止め、実行中のリクエストを待ち、それから閉じます。その間、ロードバランサーは新しいリクエストを他のインスタンスに送ります。

待つ価値のあるものがない場合、つまりテスト、ツール、開発では `immediate` を使ってください。

## 例

```yaml
# lib/resources/application.yml
server:
  shutdown: graceful
spring:
  main:
    register-shutdown-hook: true      # Ctrl+C と SIGTERM でコンテキストを閉じる
  lifecycle:
    timeout-per-shutdown-phase: 20s   # 実行中のリクエストにかけられる時間
```

```properties
server.shutdown=graceful
spring.main.register-shutdown-hook=true
spring.lifecycle.timeout-per-shutdown-phase=20s
```

一つのリクエストがまだ実行中のときのグレースフルな停止のログ:

```text
INFO  Commencing graceful shutdown. Waiting for active requests
INFO  Graceful shutdown complete
INFO  Web server stopped
```

## プロパティ

| キー | 型 | デフォルト | 意味 |
|---|---|---|---|
| `server.shutdown` | `graceful` / `immediate` | `graceful` | サーバーの停止方法。 |
| `spring.lifecycle.timeout-per-shutdown-phase` | `Duration` | `30s` | グレースフルな停止が実行中のリクエストを待つ時間。`spring_boot_dart` のキー。 |
| `spring.main.register-shutdown-hook` | `bool` | `false` | SIGINT と SIGTERM でコンテキストを閉じる。`spring_boot_dart` のキー。 |

### `server.shutdown`

- **型:** enum。**デフォルト:** `graceful`。

| 値 | 動作 |
|---|---|
| `graceful` | 新しい接続は受け付けない。実行中のリクエストは、最大 `spring.lifecycle.timeout-per-shutdown-phase` まで完了できる。その後、残ったものは閉じられる。 |
| `immediate` | すべての接続が即座に閉じられる。実行中のリクエストは打ち切られ、そのクライアントには壊れた接続が見える。 |

- **変更する理由:** 素早く止まるべきテストやツールには `immediate`。
- **例:** `server.shutdown=immediate`。
- **誤った値:** `server.shutdown=never` は、`server.shutdown` を名指しするバインディングの失敗で起動を止めます。

### `spring.lifecycle.timeout-per-shutdown-phase`

- **型:** `Duration`。**デフォルト:** `30s`。
- **ここでの動作:** グレースフルな停止が実行中のリクエストを待つ最長の時間。
- **さらに:** Spring Boot と同じく、コンテキストのライフサイクルプロセッサーの各フェーズのタイムアウトでもあります。そのため、Bean はリクエストが完了した (または時間切れになった) 後にだけ破棄されます。まだデータベース接続を使っているリクエストの下で、プールが閉じられることはありません。
- **変更する理由:** プラットフォームがより早くプロセスを殺す場合は短くする (Kubernetes は `terminationGracePeriodSeconds` (デフォルト 30 秒) の後に SIGKILL を送ります。このキーはそれより小さくしてください)。リクエストが長い場合 (レポート、アップロード) は長くする。
- **例:** `spring.lifecycle.timeout-per-shutdown-phase=20s`。

### `spring.main.register-shutdown-hook`

- **型:** `bool`。**デフォルト:** `false` (Spring Boot: `true`)。
- **動作:** プロセスが SIGINT (`Ctrl+C`) または SIGTERM (`docker stop`、Kubernetes) を受け取ると、コンテキストを閉じます。その後、サーバーは `server.shutdown` の指定どおりに停止し、`@PreDestroy` メソッドが実行されます。VM のみです。
- **設定しない場合、** シグナルでプロセスは即座に終了します。グレースフルシャットダウンはまったく行われません。シグナルを待ち受けると Dart のプログラムが生き続けるため、デフォルトでは無効です。
- **すべてのサーバーアプリケーションで `true` にしてください。**

## 一つずつ見る動作

1. **コンテキストが閉じます。** そのライフサイクルプロセッサーが、`SmartLifecycle` Bean をフェーズごとに、大きいフェーズから停止します。サーバーのフェーズは `SmartLifecycle.defaultPhase - 2048` なので、デフォルトのフェーズの Bean はそれより先に停止します。
2. **新しい接続はありません。** サーバーは待ち受けソケットを閉じます。
3. **長く続くやり取りは、どちらのモードでもここで終わります。**
   - 開いている WebSocket セッションは、`1001` (going away)、理由 `Server stopping` で閉じられます。
   - 開いているイベントストリーム (`text/event-stream`) と NDJSON ストリーム (`application/x-ndjson`) は閉じられます。それらは自分では終わらないので、待ってもタイムアウトを使い切るだけです。ブラウザーの `EventSource` は別のインスタンスに再接続します。
4. **グレースフル:** サーバーは、実行中のすべてのリクエストが完了してレスポンスが送られ、接続がアイドルになるまで待ちます。待つのは最大 `spring.lifecycle.timeout-per-shutdown-phase` です。
   - リクエストが実行中だった場合は、`Commencing graceful shutdown. Waiting for active requests`、続いて `Graceful shutdown complete` と記録します。
   - 時間切れになると、`Graceful shutdown aborted with one or more requests still active` と記録し、すべての接続を強制的に閉じます。そのクライアントには壊れた接続が見えます。
   - 実行中のリクエストがなければ、これらの行なしで閉じます。
5. **immediate:** すべての接続がすぐに強制的に閉じられます。
6. **完了。** `Web server stopped` と記録されます。停止に失敗した場合は `Web server failed to stop` が警告として記録され、シャットダウンは続行します。
7. **Bean が破棄されます** (`@PreDestroy`、`close()`)。フェーズが終わった後です。

バイトストリームや `StreamingResponseBody` は、ここでは通常のリクエストです。グレースフルな停止は、タイムアウトの範囲でそれを待ちます。

## ルールと特殊なケース

- グレースフルな停止によって **実行中のハンドラーが中断されることはありません。** Dart は実行中のコードを止められません。リクエストは時間内に完了するか、時間切れになったときに接続が閉じられるかのどちらかです。
- **サーバーの起動中の停止** は、ソケットが開くのを待ってから閉じます。待ち受けたまま残るサーバーはありません。
- **Flutter アプリでは**、アプリがバックグラウンドに移るとコンテキストが一時停止します。サーバーは同じように停止し (ポートを解放し)、アプリが戻ると再び起動します。`spring.flutter.lifecycle.pause-in-background=false` で動かし続けられます。
- **テストでは**、テストがリクエストを開いたままにした場合、`server.shutdown=immediate` で各テストのコンテキストが早く閉じます。

## Spring (Java) との対応

```properties
server.shutdown=graceful
spring.lifecycle.timeout-per-shutdown-phase=20s
```

重要な違い:

- キーとデフォルトは同じです。Spring Boot 3.4 以降と同じく、グレースフルシャットダウンがデフォルトです。
- `spring.main.register-shutdown-hook` はデフォルトで `false` です。設定しないと、シグナルはグレースフルな停止なしにプロセスを終了させます。
- 開いているイベントストリームと WebSocket セッションは、どちらのモードでもシャットダウンの開始時に閉じられます。Spring ではそれらはコンテナーに任されます。
- Spring Boot は処理を二つの Bean、`WebServerStartStopLifecycle` と `WebServerGracefulShutdownLifecycle` に分けます。ここでは一つの Bean、`webServerStartStopLifecycle` が両方を行います。

## 関連項目

- [組み込みサーバー](index.md)
- [タイムアウト](timeouts.md)
- [WebSocket](websocket.md)
- [サーバー送信イベント](../streaming/sse.md)
- [すべてのプロパティ](../properties.md)
- [ライフサイクル](../../spring-core-dart/beans/lifecycle.md)
- [@PreDestroy](../../spring-core-dart/beans/pre-destroy.md)
- [Durations](../../spring-core-dart/conversion/durations.md)
