/graceful-shutdown

name: graceful-shutdown
description: >
  Implement graceful shutdown procedures to handle SIGTERM signals, drain
  connections, complete in-flight requests, and clean up resources properly. Use
  when deploying containerized applications, handling server restarts, or
  ensuring zero-downtime deployments.

Graceful Shutdown

Table of Contents

• [Overview](#overview)
• [When to Use](#when-to-use)
• [Quick Start](#quick-start)
• [Reference Guides](#reference-guides)
• [Best Practices](#best-practices)

Overview

Implement proper shutdown procedures to ensure all requests are completed, connections are closed, and resources are released before process termination.

When to Use

• Kubernetes/Docker deployments
• Rolling updates and deployments
• Server restarts
• Load balancer drain periods
• Zero-downtime deployments
• Process managers (PM2, systemd)
• Long-running background jobs
• Database connection cleanup

Quick Start

Minimal working example:

import express from "express";
import http from "http";

class GracefulShutdownServer {
  private app: express.Application;
  private server: http.Server;
  private isShuttingDown = false;
  private activeConnections = new Set<any>();
  private shutdownTimeout = 30000; // 30 seconds

  constructor() {
    this.app = express();
    this.server = http.createServer(this.app);
    this.setupMiddleware();
    this.setupRoutes();
    this.setupShutdownHandlers();
  }

  private setupMiddleware(): void {
    // Track active connections
    this.app.use((req, res, next) => {
      if (this.isShuttingDown) {
        res.set("Connection", "close");
        return res.status(503).json({
          error: "Server is shutting down",
// ... (see reference guides for full implementation)

Reference Guides

Detailed implementations in the `references/` directory:

| Guide | Contents | |---|---| | [Express.js Graceful Shutdown](references/expressjs-graceful-shutdown.md) | Express.js Graceful Shutdown | | [Kubernetes-Aware Shutdown](references/kubernetes-aware-shutdown.md) | Kubernetes-Aware Shutdown | | [Worker Process Shutdown](references/worker-process-shutdown.md) | Worker Process Shutdown | | [Database Connection Pool Shutdown](references/database-connection-pool-shutdown.md) | Database Connection Pool Shutdown | | [PM2 Graceful Shutdown](references/pm2-graceful-shutdown.md) | PM2 Graceful Shutdown | | [Python/Flask Graceful Shutdown](references/pythonflask-graceful-shutdown.md) | Python/Flask Graceful Shutdown |

Best Practices

✅ DO

• Handle SIGTERM and SIGINT signals
• Stop accepting new requests immediately
• Wait for in-flight requests to complete
• Set reasonable shutdown timeouts
• Close database connections properly
• Flush logs and metrics
• Fail health checks during shutdown
• Test shutdown procedures
• Log shutdown progress
• Use graceful shutdown in containers

❌ DON'T

• Ignore shutdown signals
• Force kill processes without cleanup
• Set unreasonably long timeouts
• Skip resource cleanup
• Forget to close connections
• Block shutdown indefinitely