
# Shutdown

When the application closes, the server stops. `server.shutdown=graceful` (the default) lets the requests in progress finish first. `server.shutdown=immediate` cuts them.

## Why

A deployment, a restart or a scale-down stops the process while clients are being served. If the server closes at once, those clients get a broken connection: an order may be half saved, an upload lost. A graceful shutdown stops taking new connections, waits for the running requests, and only then closes. The load balancer sends new requests to the other instances in the meantime.

Use `immediate` when nothing is worth waiting for: in tests, in a tool, in development.

## Example

```yaml
# lib/resources/application.yml
server:
  shutdown: graceful
spring:
  main:
    register-shutdown-hook: true      # Ctrl+C and SIGTERM close the context
  lifecycle:
    timeout-per-shutdown-phase: 20s   # how long running requests may take
```

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

The log of a graceful stop with one request still running:

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

## Properties

| Key | Type | Default | Meaning |
|---|---|---|---|
| `server.shutdown` | `graceful` / `immediate` | `graceful` | How the server stops. |
| `spring.lifecycle.timeout-per-shutdown-phase` | `Duration` | `30s` | How long a graceful stop waits for running requests. A key of `spring_boot_dart`. |
| `spring.main.register-shutdown-hook` | `bool` | `false` | Close the context on SIGINT and SIGTERM. A key of `spring_boot_dart`. |

### `server.shutdown`

- **Type:** enum. **Default:** `graceful`.

| Value | What happens |
|---|---|
| `graceful` | No new connections. Running requests may finish, for up to `spring.lifecycle.timeout-per-shutdown-phase`. Then whatever is left is closed. |
| `immediate` | Every connection is closed at once. Running requests are cut: their clients see a broken connection. |

- **Why change it:** `immediate` for tests and tools that should stop fast.
- **Example:** `server.shutdown=immediate`.
- **Wrong value:** `server.shutdown=never` stops the start with a binding failure that names `server.shutdown`.

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

- **Type:** `Duration`. **Default:** `30s`.
- **What it does here:** the longest a graceful stop waits for the running requests.
- **Also:** it is the timeout of each phase of the context's lifecycle processor, as in Spring Boot. So the beans are destroyed only after the requests finished (or the time ran out). A request that still uses a database connection does not see the pool closed under it.
- **Why change it:** shorter when your platform kills the process sooner (Kubernetes sends SIGKILL after `terminationGracePeriodSeconds`, 30 s by default: keep this key below it); longer when requests are long (reports, uploads).
- **Example:** `spring.lifecycle.timeout-per-shutdown-phase=20s`.

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

- **Type:** `bool`. **Default:** `false` (Spring Boot: `true`).
- **What it does:** closes the context when the process gets SIGINT (`Ctrl+C`) or SIGTERM (`docker stop`, Kubernetes). Then the server stops as `server.shutdown` says, and `@PreDestroy` methods run. VM only.
- **Without it,** a signal ends the process at once: no graceful shutdown at all. Listening for signals keeps a Dart program alive, which is why it is off by default.
- **Set it to `true` in every server application.**

## What happens, step by step

1. **The context closes.** Its lifecycle processor stops the `SmartLifecycle` beans phase by phase, highest phase first. The server's phase is `SmartLifecycle.defaultPhase - 2048`, so the beans of the default phase stop before it.
2. **No new connections.** The server closes its listening socket.
3. **Long-lived exchanges end now, in both modes:**
   - open WebSocket sessions are closed with `1001` (going away), reason `Server stopping`;
   - open event streams (`text/event-stream`) and NDJSON streams (`application/x-ndjson`) are closed. They never end by themselves, so waiting for them would only use up the timeout. Browsers' `EventSource` reconnects, to another instance.
4. **Graceful:** the server waits until every running request has finished and its response is out, and the connections are idle. It waits at most `spring.lifecycle.timeout-per-shutdown-phase`.
   - When requests were running, it logs `Commencing graceful shutdown. Waiting for active requests`, then `Graceful shutdown complete`.
   - When the time runs out, it logs `Graceful shutdown aborted with one or more requests still active` and closes every connection by force. Those clients see a broken connection.
   - When no request was running, it closes without these lines.
5. **Immediate:** every connection is closed by force right away.
6. **Done.** `Web server stopped` is logged. If stopping fails, `Web server failed to stop` is logged as a warning, and the shutdown goes on.
7. **The beans are destroyed** (`@PreDestroy`, `close()`), after the phase finished.

A byte stream or a `StreamingResponseBody` is an ordinary request here: a graceful stop waits for it, within the timeout.

## Rules and edge cases

- **Running handlers are not interrupted** by a graceful stop: Dart cannot stop running code. A request either finishes in time, or its connection is closed under it when the time runs out.
- **A stop while the server is still starting** waits for the socket to open, then closes it. No server is left listening.
- **In a Flutter app** the context pauses when the app goes to the background. The server stops in the same way (and frees its port), then starts again when the app comes back. `spring.flutter.lifecycle.pause-in-background=false` keeps it running.
- **In tests**, `server.shutdown=immediate` makes each test's context close faster when a test leaves a request open.

## In Spring (Java)

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

Differences that matter:

- The same keys and defaults. Graceful shutdown is the default, as in Spring Boot 3.4 and later.
- `spring.main.register-shutdown-hook` is `false` by default. Set it, or signals end the process without a graceful stop.
- Open event streams and WebSocket sessions are closed at the start of the shutdown, in both modes. In Spring they are left to the container.
- Spring Boot splits the work into two beans, `WebServerStartStopLifecycle` and `WebServerGracefulShutdownLifecycle`. Here one bean, `webServerStartStopLifecycle`, does both.

## See also

- [The embedded server](index.md)
- [Timeouts](timeouts.md)
- [WebSocket](websocket.md)
- [Server-sent events](../streaming/sse.md)
- [All properties](../properties.md)
- [Lifecycle](../../spring-core-dart/beans/lifecycle.md)
- [@PreDestroy](../../spring-core-dart/beans/pre-destroy.md)
- [Durations](../../spring-core-dart/conversion/durations.md)
