Implement graceful shutdown for zero-downtime deploys

This skill implements graceful shutdown in servers, workers, and long-running processes: in-flight requests complete, background jobs finish or checkpoint, database connections close cleanly, and the process exits with a proper status code. It works through five steps: register SIGTERM/SIGINT handlers early with a flag guarding against double-shutdown; stop accepting new connections immediately (server.close() for HTTP servers, stop polling for queue workers) and mark readiness as not-ready so load balancers stop routing; drain in-flight work against a hard deadline shorter than the orchestrator's kill timeout, so the process never hangs indefinitely; implement separate liveness (/healthz) and readiness (/readyz) probes, keeping liveness healthy while the listener is still available and flipping only readiness to 503 during shutdown; and track active connections with a once-guarded listener on both finish and close events, since an aborted client connection may never fire finish.

Use it when building an HTTP server or background queue worker that must not drop active work during deploys, when deploying to Kubernetes, Docker, or any environment that sends SIGTERM before killing a process, or when implementing /healthz//readyz endpoints for an orchestrator. It does not replace environment-specific validation, testing, or expert review, and it has real gaps: WebSocket and SSE connections need application-level close frames before severing, since server.close() alone won't end them gracefully; clustered/multi-process setups (Node's cluster module) require each worker to handle signals independently; and some platforms like Heroku or Railway send SIGTERM with very short grace periods (10-30s) that need shorter drain timeouts than a typical Kubernetes deployment.

For a framework that owns its own shutdown sequence, such as FastAPI under Uvicorn, the skill's rule is to not fight it: Uvicorn stops accepting connections, drains existing ones up to --timeout-graceful-shutdown, and only then fires the ASGI lifespan shutdown event, so an application should not replace Uvicorn's signal handler or wait for requests again inside lifespan - that hook should only release resources like a database pool after Uvicorn's own drain completes. For a Kubernetes deployment, the health-check wiring looks like this:

apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      terminationGracePeriodSeconds: 30
      containers:
        - name: app
          livenessProbe:
            httpGet:
              path: /healthz
              port: 3000
            initialDelaySeconds: 5
            periodSeconds: 10
          readinessProbe:
            httpGet:
              path: /readyz
              port: 3000
            initialDelaySeconds: 2
            periodSeconds: 5

A drain timeout should always be set shorter than the orchestrator's kill timeout (Kubernetes' terminationGracePeriodSeconds defaults to 30s, so a 25s drain leaves margin), responses sent during draining should carry Connection: close so HTTP/1.1 clients don't reuse the socket, and the force-exit timer should be unref'd so it doesn't keep the event loop alive once work is actually done.

The skill covers three worked patterns: an Express.js server that rejects new requests with 503 during drain and tracks in-flight request count via finish/close listeners; a Python FastAPI app under Uvicorn using the lifespan hook correctly for post-drain cleanup; and a background worker that checkpoints its current job before exiting on SIGTERM. It flags common pitfalls directly: drain-rejection middleware accidentally turning liveness into 503 as well as readiness, a drain that hangs until timeout because only finish (not close) was tracked, and a terminationGracePeriodSeconds set too short for the application's longest request.

Backend developers deploying HTTP servers or background workers to Kubernetes, Docker, ECS, systemd, or PM2 who need zero-downtime deploys without dropped requests or corrupted in-progress jobs.