Compatibility and limits

shutdown-check 1.0.1 runs on Node.js 22 or later on macOS and Linux. It can test any local HTTP/1 service because it works with the service process and port instead of importing framework code.

Support matrix

Node.js version

The machine running shutdown-check needs Node.js 22 or later. The tool uses modern Node.js APIs and declares this requirement in its package metadata.

The service is started by your configured command. In practice, it normally uses the same Node.js installation as the check. CI examples therefore select Node.js 22 explicitly.

Operating systems

Only macOS and Linux are supported. shutdown-check relies on POSIX behavior:

• SIGTERM delivery;
• detached process groups;
• signaling a process group during cleanup;
• local TCP connection behavior.

Windows does not provide the same signal and process-group model. Run the test inside WSL, a Linux container, or a Linux CI runner instead of native Windows.

HTTP and network limits

baseUrl must use plain HTTP and a loopback host:

http://localhost:3000
http://127.0.0.1:3000
http://[::1]:3000

The tool does not connect to remote hosts. It also rejects credentials, query strings, fragments, and a path in baseUrl. Put paths in readiness, workload, start-probe, and new-request fields.

The following are outside the current protocol support:

• HTTPS and TLS termination;
• HTTP/2 streams;
• WebSocket connections;
• Unix sockets;
• remote staging or production URLs.

Test the local HTTP server behind a reverse proxy, not the proxy itself.

Framework compatibility

shutdown-check has no framework adapter. If the service starts from a command, listens on local HTTP, and handles SIGTERM, it can be tested.

The framework still controls the shutdown behavior. For example:

• node:http and Express use the underlying server.close();
• Fastify provides fastify.close();
• NestJS requires shutdown hooks to be enabled and awaited;
• a custom framework must stop accepting work and close resources itself.

Use the Node.js graceful shutdown guide for node:http, Express, and Fastify examples.

Module support

The package provides ESM and CommonJS entry points with TypeScript types.

import { checkShutdown } from "shutdown-check";

const { checkShutdown } = require("shutdown-check");

CommonJS support and the --version flag were added in 1.0.1.

Signal support

Only SIGTERM is accepted. This is the normal graceful-stop signal used by Linux process managers, container runtimes, and Kubernetes.

SIGINT, custom signals, and Windows console events are not supported. A config with another signal is rejected before the test starts.

The optional repeatSignalAfterMs sends SIGTERM a second time. It does not change the signal type.

What the test can verify

The tool can directly observe:

• whether the service starts and becomes ready;
• whether a request is active before the signal;
• whether active responses finish with the expected status and body;
• whether readiness changes;
• whether new HTTP work is rejected;
• whether the process exits with the expected code and deadline;
• whether the HTTP port closes;
• whether a wrapper leaves a child server running.

What the test cannot see directly

An HTTP response does not reveal every internal operation. shutdown-check does not directly verify:

• database transactions after the response;
• queue message acknowledgement;
• background jobs;
• file flushes;
• external service cleanup;
• WebSocket or HTTP/2 session draining;
• container endpoint removal;
• load-balancer propagation;
• a Kubernetes preStop hook.

Use workload.bodyIncludes when the response can prove success. Add application-specific integration tests for work that continues after the response.

Container support

The test can run inside a Linux container when:

• Node.js 22 or later is installed;
• the package is available;
• child processes can be created and signaled;
• the service binds to a loopback port inside the same container.

That setup tests the server in the image, but not Kubernetes endpoint updates, preStop, or the cluster grace period. Test those separately in a staging cluster. See Kubernetes and containers.

Resource and safety limits

• workload.concurrent supports 1 to 20 requests.
• Response bodies are captured up to 1 MiB.
• Service stdout and stderr retain their last 8 KiB.
• All timeouts have documented bounds up to 300000 ms.
• Every request path must remain on the configured local origin.
• Failed runs force-kill the process group during cleanup.

Do not point the workload at destructive production behavior. Use isolated test data and test-only routes where appropriate.

Related

• Configuration reference
• Graceful shutdown in Node.js
• Kubernetes and containers
• In-flight work
• About shutdown-check