stoppable

library1.1.0jsnpmunverified

Stoppable is a Node.js library that decorates standard `http.Server` and `https.Server` instances with a `stop()` method, addressing a long-standing behavior of Node.js's native `server.close()` that often leaves existing connections open indefinitely. This library ensures a graceful shutdown by stopping new connections, allowing in-flight requests to complete, and then closing existing idle connections, optionally with a grace period for force-closing. The current stable version is 1.1.0, last updated in 2017. While widely adopted and stable for its intended purpose, it is no longer actively maintained. Its key differentiator is providing a reliable, explicit mechanism for graceful server shutdown that was historically missing from Node.js core, with minimal performance overhead. Alternatives like `http-terminator` offer similar functionality with different design choices, often avoiding monkey-patching.

http-networking

npm install stoppable

github ↗package ↗

INSTALL

IMPORT

SIG · STOPPABLE

stoppable

http-networkingjavascriptv1.1.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.

stoppable

✓ const stoppable = require('stoppable');

✗ import stoppable from 'stoppable';

Primarily a CommonJS module. While Node.js's ESM interop allows `import stoppable from 'stoppable';`, the package itself is not ESM-native.

stoppable

✓ import stoppable from 'stoppable';

✗ import { stoppable } from 'stoppable';

When using ESM syntax with CommonJS interop, `stoppable` is the default export, not a named export. The package does not have named exports.

This quickstart demonstrates how to create an HTTP server, make it stoppable with a grace period, and handle `SIGTERM`/`SIGINT` signals for graceful shutdown, allowing in-flight requests to complete.

import http from 'http'; import stoppable from 'stoppable'; const handler = (req, res) => { console.log(`Request received for: ${req.url}`); setTimeout(() => { res.writeHead(200, { 'Content-Type': 'text/plain' }); res.end('Hello from stoppable server!\n'); }, 500); // Simulate some work }; // Create a standard HTTP server and make it stoppable with a 2-second grace period. const server = stoppable(http.createServer(handler), 2000); server.listen(3000, () => { console.log('Server listening on http://localhost:3000'); console.log('Press Ctrl+C to initiate graceful shutdown...'); }); process.on('SIGTERM', () => { console.log('\nSIGTERM received. Initiating graceful shutdown...'); server.stop((err, gracefully) => { if (err) { console.error('Server failed to stop:', err); process.exit(1); } else if (gracefully) { console.log('Server stopped gracefully.'); process.exit(0); } else { console.warn('Server stopped, but not all connections were closed gracefully.'); process.exit(0); } }); }); process.on('SIGINT', () => { console.log('\nSIGINT received. Initiating graceful shutdown...'); server.stop((err, gracefully) => { if (err) { console.error('Server failed to stop:', err); process.exit(1); } else if (gracefully) { console.log('Server stopped gracefully.'); process.exit(0); } else { console.warn('Server stopped, but not all connections were closed gracefully.'); process.exit(0); } }); });

Debug

Known issues

gotchaThe `grace` parameter, which specifies milliseconds to wait before force-closing connections, defaults to `Infinity`. If you omit this parameter, the server will never force-close open connections, potentially causing your application to hang indefinitely if clients maintain persistent connections or requests.

fix

Always explicitly pass a finite `grace` period (e.g., `stoppable(server, 5000)`) or `0` for immediate termination, depending on your application's requirements.

affects: >=1.0.0

gotchaStoppable achieves its functionality by 'decorating' (monkey-patching) the server instance. While this provides a clean API, it involves modifying Node.js internals, which could theoretically lead to conflicts with other libraries that also modify the same server methods or with future Node.js versions.

fix

Be aware of potential conflicts when combining `stoppable` with other server-modifying libraries. Thorough testing is recommended, especially after Node.js version upgrades.

affects: >=1.0.0

gotchaThe package has not been updated since October 2017 (v1.1.0). While it addresses a core Node.js issue that still exists to some extent, newer Node.js versions (e.g., Node.js 18.2.0+) introduced `server.closeIdleConnections` which aims to mitigate similar problems, potentially reducing the need for or altering the behavior of `stoppable`.

fix

For applications on modern Node.js versions, consider native Node.js solutions or more actively maintained alternatives like `http-terminator` that may provide more robust or contemporary approaches to graceful shutdown without monkey-patching. Evaluate `stoppable`'s continued relevance and compatibility with your target Node.js runtime.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: server.stop is not a function

The `stoppable` function was not applied to the `http.Server` instance, or the result of `stoppable(server)` was not assigned back to the `server` variable (or a new one).

fix

Ensure you correctly decorate the server: `const server = stoppable(http.createServer(handler));` or `stoppable(serverInstance);` if `serverInstance` is already defined.

My server hangs indefinitely after calling server.stop() / connections are not closing

This typically happens if the `grace` period was set to its default (`Infinity`) or a very high value, and active connections are not naturally closing, or if new requests are still being made on existing keep-alive connections after `stop()` is called.

fix

When calling `stoppable(server, grace)`, ensure `grace` is set to a finite number of milliseconds (e.g., 5000 for 5 seconds) to force-close connections after the grace period. Set `grace` to `0` to kill all sockets immediately without waiting.

Upgrade

Version history

1.1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

8 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/hunterloftis/stoppable ↗

packagehttps://www.npmjs.com/package/stoppable ↗