Registry / http-networking / http-shutdown

http-shutdown

library1.2.2jsnpmunverified

http-shutdown is a Node.js library designed for gracefully shutting down HTTP servers, addressing shortcomings of the native `server.close()` method. Unlike `server.close()` which only terminates the listening socket and waits for existing connections, `http-shutdown` actively closes idle keep-alive sockets and waits for all in-flight requests to complete before closing their associated sockets. This ensures no new requests are accepted and all current requests finish cleanly. The library, currently at version 1.2.2, appears to be in a maintenance phase with infrequent but stable releases. It offers two primary integration methods: explicitly wrapping an `http.Server` instance or extending the `http.Server` prototype with a `withShutdown()` method. It ships with TypeScript types, facilitating its use in modern TypeScript projects.

http-networking web-framework devops

npm install http-shutdown

github ↗package ↗

INSTALL

IMPORT

SIG · HTTP-SHUTDOWN

http-shutdown

http-networkingjavascriptv1.2.2

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.

httpShutdown (function)

✓ import httpShutdown from 'http-shutdown';

✗ import { httpShutdown } from 'http-shutdown';

The package is primarily a CommonJS module. For ESM, use a default import. It's a function that takes an `http.Server` instance and returns an augmented server.

extend()

✓ import httpShutdown from 'http-shutdown'; httpShutdown.extend();

✗ import { extend } from 'http-shutdown';

The `extend` method modifies the `http.Server.prototype` globally to add a `.withShutdown()` method. It is not a named export.

WithShutdownServer (type)

✓ import type { WithShutdownServer } from 'http-shutdown';

Use this type for `http.Server` instances that have been augmented with `http-shutdown` functionality, providing access to the `.shutdown()` method.

Demonstrates how to explicitly wrap an `http.Server` instance with `http-shutdown` for graceful termination. This example includes simulating a long-running request, initiating shutdown after a delay, and correctly handling common OS termination signals (`SIGINT`, `SIGTERM`) to ensure all connections are closed cleanly.

import * as http from 'http'; import httpShutdown, { WithShutdownServer } from 'http-shutdown'; // Create the http server let server: http.Server | WithShutdownServer = http.createServer((req, res) => { if (req.url === '/heavy-task') { // Simulate a long-running request console.log('Incoming heavy task request...'); setTimeout(() => { res.writeHead(200, { 'Content-Type': 'text/plain' }); res.end('Heavy task completed!'); console.log('Heavy task finished.'); }, 2500); } else { res.writeHead(200, { 'Content-Type': 'text/plain' }); res.end('Hello from http-shutdown!'); } }); // Wrap the server object with additional functionality. server = httpShutdown(server); const PORT = 3000; // Listen on a port and start taking requests. server.listen(PORT, () => { console.log(`Server listening on http://localhost:${PORT}`); console.log('Try accessing / and /heavy-task. Server will attempt graceful shutdown in 7 seconds...'); // Sometime later... initiate graceful shutdown. setTimeout(() => { console.log('Initiating graceful shutdown...'); (server as WithShutdownServer).shutdown((err) => { if (err) { console.error('Shutdown failed:', err.message); process.exit(1); return; } console.log('Everything is cleanly shutdown.'); process.exit(0); }); }, 7000); }); // Handle common process termination signals for robust shutdown process.on('SIGTERM', () => { console.log('SIGTERM received, initiating shutdown.'); (server as WithShutdownServer).shutdown((err) => { if (err) { console.error('Shutdown failed on SIGTERM:', err.message); process.exit(1); return; } console.log('Everything is cleanly shutdown after SIGTERM.'); process.exit(0); }); }); process.on('SIGINT', () => { console.log('SIGINT received, initiating shutdown.'); (server as WithShutdownServer).shutdown((err) => { if (err) { console.error('Shutdown failed on SIGINT:', err.message); process.exit(1); return; } console.log('Everything is cleanly shutdown after SIGINT.'); process.exit(0); }); });

Debug

Known issues

gotchaThe library is primarily designed for `http.Server`. While it often works with `https.Server` due to underlying `net.Server` wrapping, ensure thorough testing for your specific HTTPS configuration.

fix

Thoroughly test `http-shutdown` with your `https.Server` setup. The core logic typically applies, but any HTTPS-specific connection management or protocol nuances might require extra consideration.

affects: >=1.0.0

gotchaMixing the `extend()` method with direct server wrapping (`server = httpShutdown(server)`) can lead to confusing behavior or conflicts.

fix

Choose one integration method: either explicitly wrap each `http.Server` instance (`server = httpShutdown(server);`) or use `require('http-shutdown').extend();` once to augment the `http.Server.prototype` globally, then call `.withShutdown()` on your server instances. Do not do both for the same server or in the same application.

affects: >=1.0.0

gotchaCalling `shutdown()` too early (e.g., before the server is fully listening) or multiple times on the same instance can lead to unexpected behavior or redundant operations.

fix

Ensure the `http.Server` is in a listening state before invoking `shutdown()`. While the library generally handles multiple calls gracefully, it's best practice to design your application's shutdown logic to trigger `shutdown()` only once, typically in response to process signals like `SIGINT` or `SIGTERM`.

affects: >=1.0.0

gotchaAs a CommonJS-first library, direct ESM named imports might not work as expected without proper configuration or bundler handling.

fix

For ESM environments, use the default import syntax: `import httpShutdown from 'http-shutdown';`. If you need to access `.extend()`, call it from the default import: `httpShutdown.extend();`. Ensure your `tsconfig.json` or bundler settings (e.g., `esModuleInterop`) are configured correctly for interoperability.

affects: >=1.0.0

Errors

Common errors & fixes

`server.shutdown is not a function`

The `http.Server` instance was not properly augmented with `http-shutdown` functionality.

fix

Ensure you have either explicitly wrapped your server with `server = httpShutdown(server);` or called `require('http-shutdown').extend();` and subsequently `server = http.createServer(...).withShutdown();` before attempting to call `server.shutdown()`.

`TypeError: Cannot read properties of undefined (reading 'shutdown')` (or similar related to `withShutdown`)

When using the `extend()` method, the `withShutdown()` method was not chained onto the `http.Server` instance, or `extend()` itself was not called globally.

fix

Make sure you call `require('http-shutdown').extend();` (or `httpShutdown.extend();` for ESM) once at the application's entry point, and then chain `.withShutdown()` directly after creating your server: `server = http.createServer(...).withShutdown();`.

Server `close` event fires unexpectedly early, before all connections are handled by `http-shutdown`.

Relying on the native `server.on('close', ...)` event for post-shutdown cleanup logic can cause race conditions, as `server.close()` might be called internally before `http-shutdown` has finished closing all active and idle connections.

fix

Always rely exclusively on the callback provided to `httpShutdown.shutdown(callback)` for knowing when the server has gracefully and completely shut down. Place all post-shutdown cleanup logic within this callback.

Upgrade

Version history

1.2.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/thedillonb/http-shutdown ↗

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