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

# 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
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:

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

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.

spring.lifecycle.timeout-per-shutdown-phase

spring.main.register-shutdown-hook

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

In Spring (Java)

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

Differences that matter:

See also