Shutdown Check

Search documentation

Find a page or section

About

shutdown-checkv1.0.1View as Markdown

The problem it tests, the boundary of the project, and how to get help.

shutdown-check is a black-box test for one deployment question: will a Node.js HTTP service finish active requests and exit cleanly after SIGTERM?

Why does the project exist?

A shutdown handler can look correct in a code review and still fail in the real process. The start command may add a wrapper, the framework may handle sockets differently than expected, a request may still depend on a closing resource, or a timer may keep Node.js alive.

Unit tests are valuable, but they often call the handler directly and mock the parts that fail during deployment. shutdown-check runs the actual command, opens a real HTTP connection, delivers the operating-system signal, and waits for the real exit.

What shutdown-check is

  • A CLI and typed Node.js API.
  • A test for local HTTP/1 services.
  • A real process and signal test.
  • A check for active responses, optional traffic draining, process exit, and port closure.
  • A tool for local development and CI on macOS and Linux.

What shutdown-check is not

  • It is not a shutdown-handler library.
  • It does not modify your application.
  • It is not tied to Express, Fastify, NestJS, or another framework.
  • It does not run a Kubernetes cluster or load balancer.
  • It does not inspect databases, queues, WebSockets, or HTTP/2 sessions.
  • It does not support native Windows signal behavior.

The comparison page explains how it fits with shutdown libraries, unit tests, scripts, and staging tests.

Design principles

Test the real boundary

The test observes the same inputs and outputs a deployment platform uses: command, port, HTTP, signal, and exit status.

Do not create false passes

Work must be proven active before SIGTERM. The port must be free before launch and closed after exit. Optional checks are performed only while the state they claim to test still exists.

Make failures actionable

Every planned failure has a stable SC code, a message, a timeline, and a page with causes and fixes. The CLI keeps the tail of service output for the same reason.

Keep configuration explicit

The config describes the command, routes, expected response, deadline, and drain behavior. It does not guess which endpoint or exit code is correct for your service.

Project scope

The current release focuses on:

  • SIGTERM;
  • local plain HTTP/1;
  • Node.js 22 or later;
  • macOS and Linux;
  • ESM and CommonJS;
  • text, JSON, and JUnit output.

See compatibility and limits before designing a test for protocols or environments outside that scope.

Maintainer and license

shutdown-check is maintained by Sohail Khan and released under the MIT license. The source, issue history, and releases are developed in public.

The license allows use, modification, and distribution under its terms. Read the LICENSE file in the package or repository for the complete text.

Report a problem

Before opening an issue:

  1. Run the latest version.
  2. Read the page for the diagnostic code.
  3. Check troubleshooting.
  4. Reduce the problem to a small server and config when possible.

Include:

  • shutdown-check version;
  • Node.js version;
  • operating system;
  • the command you ran;
  • config with secrets removed;
  • full result code, message, and timeline;
  • relevant captured stdout and stderr;
  • a reproduction repository or small server when available.

Never include passwords, tokens, connection strings, private URLs, customer data, or other secrets. Replace them with clear placeholders.