Configuration

The shutdown-check config is a JSON file named shutdown-check.json. It tells the CLI how to start your service, wait for readiness, create active work, send SIGTERM, and decide whether the shutdown passed.

Create the starter file

Run:

npx shutdown-check init

The command writes this complete config and refuses to overwrite an existing file:

{
  "command": ["node", "server.js"],
  "cwd": ".",
  "baseUrl": "http://127.0.0.1:3000",
  "readiness": { "path": "/health", "status": 200, "timeoutMs": 10000 },
  "workload": {
    "path": "/slow",
    "method": "GET",
    "status": 200,
    "started": { "type": "response-headers", "timeoutMs": 5000 }
  },
  "shutdown": { "deadlineMs": 10000, "exitCode": 0 }
}

Before the first run, change the command, port, readiness path, and workload path. The quick start includes a server that matches this file.

Configuration rules

• The CLI accepts JSON only. Comments and trailing commas are invalid.
• Every numeric value must be an integer inside its documented range.
• Validation stops at the first invalid value.
• Invalid config prints shutdown-check: <message> and exits with code 2.
• Unknown fields are ignored. A misspelled optional field therefore falls back to its default instead of raising an error.
• Route paths must stay on baseUrl; full URLs and //host/path are rejected.

All fields

The generated table above contains every type and default. The sections below explain how the fields work together and what to choose in a real service.

Command, cwd, and env

{
  "command": ["node", "dist/server.js"],
  "cwd": ".",
  "env": {
    "PORT": "3510",
    "NODE_ENV": "production"
  }
}

command

Write the executable and each argument as separate array items. shutdown-check does not use a shell.

Prefer the real server process:

{ "command": ["node", "dist/server.js"] }

Avoid a shell string or wrapper when possible:

{ "command": ["npm", "start"] }

A wrapper may receive SIGTERM without forwarding it. It may also exit while its child server keeps the port open, which produces SC302.

cwd

cwd is resolved from the folder containing the config file. If it is omitted, the command runs in that folder.

For config/shutdown-check.json, this starts the command from the project root:

{ "cwd": ".." }

env

env adds to or overrides the environment inherited by the CLI. All values must be strings. Use it to give each test a dedicated port or enable test-only routes.

{
  "env": {
    "PORT": "3510",
    "ENABLE_TEST_ROUTES": "1"
  }
}

baseUrl

baseUrl is the origin used for readiness, workload, probe, and new-request paths. It must be plain HTTP on the local machine.

Reserve the port for one test. shutdown-check requires it to be free before launch and closed after exit. Parallel tests must use different ports.

Readiness

Readiness tells shutdown-check when startup has completed.

{
  "readiness": {
    "path": "/health",
    "status": 200,
    "timeoutMs": 30000,
    "intervalMs": 100
  }
}

The tool polls until the route returns exactly status. A refused connection or another status is retried. If the process stays alive without becoming ready, the result is SC100. If it exits first, the result is SC101.

The same route is used after SIGTERM when readiness withdrawal is enabled.

Workload

The workload is the request that must be active when SIGTERM arrives.

{
  "workload": {
    "path": "/reports/export",
    "method": "POST",
    "headers": { "content-type": "application/json" },
    "body": "{\"rows\":5000}",
    "status": 200,
    "bodyIncludes": "export complete",
    "concurrent": 3,
    "started": {
      "type": "response-headers",
      "timeoutMs": 5000
    }
  }
}

Choose a safe route that takes long enough to receive the signal. Use bodyIncludes when a successful status alone does not prove that the work completed. shutdown-check captures up to 1 MiB of each response body.

After SIGTERM, each request must finish before the deadline. A timeout, interruption, wrong status, or wrong body produces SC200 through SC203.

Start barrier

The start barrier prevents a false pass with work that ended before the signal. Choose one of two types.

response-headers

{
  "started": {
    "type": "response-headers",
    "timeoutMs": 5000
  }
}

Every workload request must receive headers while its body remains open. This barrier supports 1 to 20 concurrent requests. The test route normally calls response.flushHeaders() and finishes the body later.

probe

{
  "started": {
    "type": "probe",
    "path": "/test/work-active",
    "inactiveStatus": 204,
    "activeStatus": 200,
    "timeoutMs": 5000,
    "intervalMs": 50
  }
}

Before the workload, the probe must return inactiveStatus. While the request is still open, it must change to activeStatus. The statuses must differ.

A probe supports exactly one workload request. Use it for handlers that do not send response headers until their work is complete. Keep the route test-only if it exposes internal application state.

See in-flight work and start barriers for complete server examples and failure output.

Shutdown

The shutdown object defines the contract after the first SIGTERM.

{
  "shutdown": {
    "signal": "SIGTERM",
    "deadlineMs": 15000,
    "exitCode": 0,
    "readinessWithdrawal": true,
    "newRequests": {
      "path": "/test/new-work",
      "rejectStatuses": [503],
      "allowConnectionRefused": true
    },
    "repeatSignalAfterMs": 500
  }
}

signal

Only SIGTERM is supported. Omit the field unless you want the config to state the signal explicitly.

deadlineMs

The default is 10000 ms. The timer begins with the first signal and covers active responses, traffic-draining checks, and process exit. Set it above the slowest valid request and cleanup time, but below the platform's termination deadline.

exitCode

The default is 0. The process must exit with this exact code. A process ended by a signal has no exit code and does not match.

readinessWithdrawal

When true, the readiness route must stop returning readiness.status before the deadline. Another status or a refused connection passes. A timeout does not.

newRequests

This check requires readinessWithdrawal: true. After readiness changes and while the original workload is still active, shutdown-check sends one GET to newRequests.path.

The request passes when it returns a status in rejectStatuses, or when the connection is refused and allowConnectionRefused is true. A timeout or a normal success response fails.

Use a safe test route because the request is real. The readiness and draining guide shows both the 503 and closed-listener patterns.

repeatSignalAfterMs

When set, shutdown-check sends a second SIGTERM while work is still active. The value must be shorter than deadlineMs and the test workload duration. Use it to catch handlers that force an early exit after a repeated signal.

A complete strict config

This example checks three requests, response content, readiness withdrawal, new-request rejection, a repeated signal, process exit, and port closure:

{
  "command": ["node", "dist/server.js"],
  "cwd": ".",
  "env": { "PORT": "3510", "NODE_ENV": "production" },
  "baseUrl": "http://127.0.0.1:3510",
  "readiness": { "path": "/health", "status": 200, "timeoutMs": 30000 },
  "workload": {
    "path": "/slow",
    "status": 200,
    "bodyIncludes": "work complete",
    "concurrent": 3,
    "started": { "type": "response-headers", "timeoutMs": 5000 }
  },
  "shutdown": {
    "deadlineMs": 15000,
    "exitCode": 0,
    "readinessWithdrawal": true,
    "newRequests": {
      "path": "/test/new-work",
      "rejectStatuses": [503],
      "allowConnectionRefused": true
    },
    "repeatSignalAfterMs": 500
  }
}

The workload must stay open long enough for readiness polling, the new request, and the repeated signal, while still finishing before the deadline.

Common validation errors

The v0.1 text is the literal message in package version 1.0.1. See troubleshooting for errors grouped by symptom.

Can I use TypeScript instead of JSON?

The CLI reads JSON only. In a test or script, create a typed object with defineConfig() and pass it to checkShutdown():

import { checkShutdown, defineConfig } from "shutdown-check";
 
const config = defineConfig({
  command: ["node", "dist/server.js"],
  baseUrl: "http://127.0.0.1:3510",
  readiness: { path: "/health" },
  workload: {
    path: "/slow",
    started: { type: "response-headers" },
  },
  shutdown: { readinessWithdrawal: true },
});
 
const result = await checkShutdown(config);

The object follows the same rules and defaults. See the Node API for validation and result handling.

Related

• Quick start
• CLI reference
• Node API
• In-flight work and start barriers
• Diagnostic codes