PSGI application and sidecar proxy: which layer should own connection draining for zero-downtime deploys?

Proxy owns the drain sequence. The Plack server should not. Put drain control in Envoy or HAProxy and keep the PSGI app server version-agnostic. A single in-process drain protocol cannot be made portable across Starman, Twiggy and Corona without server-specific forks.

Confirmed facts

• The PSGI specification and Plack define no standard shutdown or drain contract.
• Starman, Twiggy and Corona implement graceful shutdown with different signals and semantics. No single /drain endpoint works across all three without server-specific code.
• None of the three servers drain WebSocket or long-poll connections by default.

Likely explanation

A sidecar proxy can stop sending new requests to the old instance while letting in-flight HTTP requests complete, independent of the PSGI server implementation. Moving drain logic into the proxy centralizes it, avoids rewriting every server adapter, and keeps the application portable.

Readiness signaling when proxy owns draining

Expose a simple health-check endpoint, e.g. /health, that returns HTTP 200 only after the worker pool has bound its port and is ready to serve PSGI requests. The proxy adds new instances to rotation only after health checks pass and drains old instances before the old process is stopped.

Rolling swap steps for this case

1. Start new version of the PSGI app behind Starman/Twiggy/Corona on a new port or pod.
2. Wait for proxy active health checks to succeed on /health.
3. Mark the old backend as draining in the proxy. Envoy supports drain mode; HAProxy can mark the server down or use drain mode via health checks.
4. Wait for active connections to finish or for the proxy drain timeout to elapse, then stop the old process.

Verification needed

• Confirm the exact graceful-shutdown signal and timeout behavior for the Starman, Twiggy and Corona versions in use.
• Verify the health-check endpoint returns 200 only when ready, not during startup.
• In staging, mark the old instance draining and confirm new requests route to the new instance while existing requests to the old instance complete.

One diagnostic detail that changes the recommendation: do you have persistent WebSocket or long-poll connections in production? If yes, the proxy drain timeout must exceed the maximum expected connection lifetime, otherwise those connections will be dropped.