@linn-cloud/graceful-shutdown

Drains in-flight requests when a node HTTP service is told to stop, instead of severing them.

Without this, every ECS task replacement cuts whatever the service was serving and the load balancer reports it to callers as 502/504.

Use

Two calls, and the order matters.

const gracefulShutdown = require("@linn-cloud/graceful-shutdown");

// FIRST, before requiring anything heavy.
gracefulShutdown.holdSignalsUntilInstalled();

const app = require("../app");
const server = require("http").createServer(app);

server.keepAliveTimeout = 65000;
gracefulShutdown.install(server, {
  drainTimeoutMs: 20000,
  exitFlushTimeoutMs: 2000,
  log,
});
server.listen(port);

Why holdSignalsUntilInstalled() comes first

Node running as PID 1 — which is what a container ENTRYPOINT ["node", "..."] gives you — ignores SIGTERM while nothing is listening for it. It does not die; the signal is discarded and the task serves on until the platform SIGKILLs it. Loading a service's dependencies takes hundreds of milliseconds, which is a wide window to leave open, so the recorder goes above them.

The values are yours, not this package's

drainTimeoutMs must sit below your platform's own stop timeout — on ECS, the task definition's StopTimeout — with room for exitFlushTimeoutMs on top. Exceed it and the container is SIGKILLed mid-drain, severing exactly what the drain exists to protect. They are not defaulted because they are properties of a deployment.

keepAliveTimeout is likewise yours, and belongs on the server rather than here: it must exceed the load balancer's idle timeout (60s by default on an AWS ALB), or the balancer dispatches onto a socket node has just retired and reports the reset as a 502.

This does not remove the need to fix your entrypoint

If your image runs ENTRYPOINT ["npm", "run-script"], npm spawns sh -c node ..., the shell does not exec away, and node ends up a grandchild of PID 1. The signal npm forwards stops at that shell and never reaches node — so this package is inert. Run node directly:

ENTRYPOINT [ "node", "./bin/www" ]

What it does, and why it is not two lines

• server.close() alone never finishes. It waits for every connection to end but does not retire a keep-alive connection that falls idle after the close was requested — measured on node 24 at 66s with a 65s keep-alive. The drain sweeps closeIdleConnections(); a single sweep at signal time does not help, because the connections that matter are still serving a request at that moment.
• Responses answered during the drain are marked Connection: close, so the balancer retires the socket rather than dispatching onto one about to be destroyed.
• process.exit() discards queued stdout. Through a real pipe with a reader that is behind, an immediate exit delivered none of 262KB — losing the one line saying how the drain ended. The exit waits for the flush, bounded.
• Three named outcomes, not a boolean: drained, timed-out, not-running. "Nothing was listening" and "everything finished" both leave cleanly, but only one drained anything.

Notes

tsconfig.json sets "types": ["node"]. This is the first package in the workspace to touch node's own runtime — http.Server, process, signals — where the others are pure domain logic, so it is declared here rather than in tsconfig.base.json.