Registry / http-networking / http-terminator

http-terminator

library3.2.0jsnpmunverified

http-terminator provides a robust solution for gracefully shutting down Node.js HTTP(S) servers. Unlike the native `server.close()` method, which simply stops accepting new connections but leaves existing connections open indefinitely (potentially hanging due to keep-alive or long-running requests), this library actively tracks and terminates all connections after a configurable timeout. It ensures that in-flight requests complete their responses and communicates shutdown intent to clients. The current stable version is `3.2.0`, with a release cadence that includes minor and patch updates every few months, reflecting ongoing maintenance and feature additions. Key differentiators include its explicit handling of all connection types, including `http`, `https`, and `http2` servers (since v3.2.0), and its rewrite to TypeScript in v3.0.0, providing robust type definitions.

http-networking

npm install http-terminator

github ↗package ↗

INSTALL

IMPORT

SIG · HTTP-TERMINATOR

http-terminator

http-networkingjavascriptv3.2.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

createHttpTerminator

✓ import { createHttpTerminator } from 'http-terminator';

✗ const createHttpTerminator = require('http-terminator');

The package is ESM-first since v3.0.0. Use `import` syntax.

HttpTerminatorType

✓ import type { HttpTerminatorType } from 'http-terminator';

✗ import { HttpTerminatorType } from 'http-terminator';

This is a type definition. Use `import type` for clarity and to prevent it from being bundled as a runtime dependency.

HttpTerminatorConfigurationInputType

✓ import type { HttpTerminatorConfigurationInputType } from 'http-terminator';

This type defines the configuration object for `createHttpTerminator`. It's primarily used for type-checking when defining the configuration.

This example demonstrates how to set up a basic HTTP server, integrate `http-terminator` for graceful shutdown, and respond to common OS signals (SIGTERM, SIGINT). It includes a simulated asynchronous request to showcase the termination timeout.

import http from 'http'; import { createHttpTerminator } from 'http-terminator'; const server = http.createServer((req, res) => { console.log(`Received request: ${req.method} ${req.url}`); // Simulate some async work that might take time setTimeout(() => { res.writeHead(200, { 'Content-Type': 'text/plain' }); res.end('Hello, World!\n'); }, Math.random() * 1000 + 500); // Between 0.5s and 1.5s }); server.listen(3000, () => { console.log('Server listening on port 3000. Try curl http://localhost:3000'); }); const httpTerminator = createHttpTerminator({ server, gracefulTerminationTimeout: 10000 // Allow up to 10 seconds for requests to complete }); async function gracefulShutdown() { console.log('Initiating graceful shutdown...'); try { await httpTerminator.terminate(); console.log('Server gracefully terminated. All connections closed.'); process.exit(0); } catch (error) { console.error('Error during graceful shutdown:', error); process.exit(1); } } // Handle OS signals for graceful shutdown process.on('SIGTERM', gracefulShutdown); process.on('SIGINT', gracefulShutdown); console.log('Press Ctrl+C or send SIGTERM to shut down gracefully.');

Debug

Known issues

breakingVersion 3.0.0 migrated the entire codebase from Flow to TypeScript. This may require adjustments in projects that rely on Flow types or the internal structure of the package.

fix

Update your project's type definitions to use TypeScript if upgrading from a pre-v3 version. Review any custom type extensions for compatibility.

affects: >=3.0.0

breakingSupport for Node.js v10 was dropped in version 3.1.0, raising the minimum required Node.js version to v12 (though the package.json specifies `>=14`).

fix

Ensure your project is running on Node.js v14 or newer to use http-terminator v3.1.0 and above.

affects: >=3.1.0

gotchaCalling `server.close()` directly on an `http.Server` instance will stop it from accepting new connections but will not forcefully close existing ones, leading to potential indefinite hangs, especially with keep-alive connections.

fix

Always use `httpTerminator.terminate()` provided by this library for a proper graceful shutdown that handles existing connections and in-flight requests.

affects: all

gotchaSince version 3.0.0, `http-terminator` is primarily an ESM (ECMAScript Module) package. Attempting to use `require()` in a CommonJS module might lead to import errors in some Node.js environments or configurations.

fix

Adopt `import` statements for `http-terminator`. If your project is CommonJS, consider transpiling or using dynamic `import()`.

affects: >=3.0.0

gotchaThe `gracefulTerminationTimeout` option defaults to 5000 milliseconds (5 seconds). If your server has long-running requests or slow external dependencies, this default might be too short, leading to connections being forcefully closed prematurely.

fix

Configure `gracefulTerminationTimeout` to a value appropriate for your application's expected maximum request duration: `createHttpTerminator({ server, gracefulTerminationTimeout: 30000 })`.

affects: all

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/http-terminator/dist/index.js from ... not supported.

`http-terminator` v3+ is an ES Module, but you are trying to import it using CommonJS `require()` syntax.

fix

Change your import statement to `import { createHttpTerminator } from 'http-terminator';` and ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`).

Server is not shutting down, processes are hanging after receiving termination signals (SIGTERM/SIGINT).

You are likely calling the native `server.close()` method or no termination logic at all, which does not handle existing connections.

fix

Implement graceful shutdown using `http-terminator.terminate()` in your `SIGTERM`/`SIGINT` handlers, ensuring `httpTerminator` is initialized with your `http.Server` instance.

UnhandledPromiseRejectionWarning: Error: Server termination timed out. Some connections may have been forcefully closed.

The `gracefulTerminationTimeout` period expired before all active HTTP connections could complete their requests or close naturally.

fix

Increase the `gracefulTerminationTimeout` option when calling `createHttpTerminator()` to allow more time for requests to finish, or investigate why requests are taking so long.

Upgrade

Version history

3.2.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/gajus/http-terminator ↗

packagehttps://www.npmjs.com/package/http-terminator ↗