# About

> About shutdown-check: why it exists, what it is and is not, who maintains it, its MIT license, and how to report a problem with a useful, secret-free issue.

Source: https://shutdown.jscrate.dev/docs/about
Last updated: 2026-09-23

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](https://shutdown.jscrate.dev/docs/comparison) 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](https://shutdown.jscrate.dev/docs/compatibility) 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](https://shutdown.jscrate.dev/docs/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.

## Related

- [Quick start](https://shutdown.jscrate.dev/docs/quick-start)
- [How shutdown-check works](https://shutdown.jscrate.dev/docs/how-it-works)
- [Compatibility and limits](https://shutdown.jscrate.dev/docs/compatibility)
- [Comparison](https://shutdown.jscrate.dev/docs/comparison)
- [Releases](https://shutdown.jscrate.dev/docs/releases)