Graceful shutdown for Node.js HTTP servers

import type { Server } from "node:http";

type Cleanup = () => Promise<void> | void;

type Options = {
  /** Force exit after this long; keep it below the orchestrator's grace period */
  timeoutMs?: number;
  /** Run after the server stops accepting requests, e.g. close DB pools */
  cleanup?: Cleanup[];
};

export function enableGracefulShutdown(
  server: Server,
  { timeoutMs = 25_000, cleanup = [] }: Options = {},
) {
  let shuttingDown = false;

  const shutdown = async (signal: NodeJS.Signals) => {
    if (shuttingDown) return;
    shuttingDown = true;
    console.info(`${signal} received, draining connections`);

    // Hard deadline so one stuck request can't block the deploy forever
    const timer = setTimeout(() => {
      console.error("Graceful shutdown timed out, forcing exit");
      process.exit(1);
    }, timeoutMs);
    timer.unref();

    try {
      // Stop accepting connections; resolves once in-flight requests finish
      const closed = new Promise<void>((resolve, reject) =>
        server.close((err) => (err ? reject(err) : resolve())),
      );
      server.closeIdleConnections(); // drop idle keep-alive sockets now
      await closed;

      for (const fn of cleanup) await fn();
      process.exit(0);
    } catch (err) {
      console.error("Error during shutdown", err);
      process.exit(1);
    }
  };

  process.once("SIGTERM", shutdown);
  process.once("SIGINT", shutdown);

  return { isShuttingDown: () => shuttingDown };
}