Why I Added Graceful Shutdown to Every Node.js Project

pm2 start dist/index.js --name "$PM2_APP_NAME"

Active Traffic  →  SIGTERM Received  →  Stop Accepting New Requests  →  Finish Active Work  →  Close DB Sockets  →  Clean Exit

server.close((err) => {
  if (err) {
    console.error("Error closing HTTP server:", err);
    process.exit(1);
  }
  console.log("HTTP server closed.");
});

io.close(() => {
  console.log("Socket.io server closed.");
});

let activeJobs = 0;

function trackJob(promise: Promise<void>) {
  activeJobs++;
  return promise.finally(() => {
    activeJobs--;
  });
}

module.exports = {
  apps: [{
    name: "api-service",
    script: "./dist/index.js",
    kill_timeout: 10000, // Wait 10 seconds before force-killing
    listen_timeout: 5000,
    wait_ready: true
  }]
};

import http from "node:http";
import mongoose from "mongoose";
import { Server as SocketServer } from "socket.io";
import express from "express";

const app = express();
const server = http.createServer(app);
const io = new SocketServer(server);

// Keep track of active requests and background jobs
let activeConnections = 0;
let isShuttingDown = false;

// Middleware to track active HTTP requests and block traffic during shutdown
app.use((req, res, next) => {
  if (isShuttingDown) {
    res.setHeader("Connection", "close");
    res.status(503).send("Server is shutting down.");
    return;
  }
  
  activeConnections++;
  res.on("finish", () => {
    activeConnections--;
  });
  next();
});

app.get("/api/data", async (req, res) => {
  // Simulate a database read
  await new Promise((resolve) => setTimeout(resolve, 500));
  res.json({ status: "ok" });
});

// Graceful shutdown orchestrator
async function gracefulShutdown(signal: string) {
  if (isShuttingDown) {
    console.log("Shutdown already in progress.");
    return;
  }
  
  isShuttingDown = true;
  console.log(`Received ${signal}. Starting graceful shutdown...`);

  // 1. Force exit timeout (fail-safe)
  const forceExitTimeout = setTimeout(() => {
    console.error("Graceful shutdown timed out. Force exiting.");
    process.exit(1);
  }, 15000); // 15 seconds limit

  try {
    // 2. Close Socket.io server
    if (io) {
      console.log("Closing Socket.io server...");
      io.close();
    }

    // 3. Close HTTP server
    console.log("Closing HTTP server...");
    await new Promise<void>((resolve, reject) => {
      server.close((err) => {
        if (err) return reject(err);
        resolve();
      });
      // Forcefully close idle connections (Node v18.2.0+)
      if (typeof server.closeIdleConnections === "function") {
        server.closeIdleConnections();
      }
    });
    console.log("HTTP server stopped accepting connections.");

    // 4. Wait for active connections / background jobs to drain
    while (activeConnections > 0) {
      console.log(`Waiting for ${activeConnections} active requests to finish...`);
      await new Promise((resolve) => setTimeout(resolve, 500));
    }
    console.log("All active requests completed.");

    // 5. Close database connections
    if (mongoose.connection.readyState !== 0) {
      console.log("Closing database connection...");
      await mongoose.connection.close();
      console.log("Database connection closed.");
    }

    clearTimeout(forceExitTimeout);
    console.log("Graceful shutdown completed successfully.");
    process.exit(0);
  } catch (error) {
    console.error("Error during graceful shutdown:", error);
    clearTimeout(forceExitTimeout);
    process.exit(1);
  }
}

// Intercept OS termination signals
process.on("SIGTERM", () => gracefulShutdown("SIGTERM"));
process.on("SIGINT", () => gracefulShutdown("SIGINT"));

// Start server
const PORT = process.env.PORT || 3000;
server.listen(PORT, () => {
  console.log(`Server listening on port ${PORT}`);
  // If running under PM2 with wait_ready, signal readiness
  if (typeof process.send === "function") {
    process.send("ready");
  }
});