Graceful HTTP Server Shutdown

Common errors

• Error: server.close() callback not firing or taking too long

  cause `server.close()` appears to hang or the callback takes longer than expected to execute, indicating connections are not being released.
  fix Verify that `httpClose` is correctly applied to your `http.Server` instance. Ensure you've set an appropriate `timeout` option that allows pending requests to complete while also forcing closure within acceptable bounds. Long-running requests might still delay shutdown until their timeout is reached.

• Client received unexpected 500 Internal Server Error during server shutdown

  cause During graceful shutdown, `http-close` sends a 500 status code to pending requests where HTTP headers have not yet been sent, if the socket times out.
  fix This is expected behavior for requests that cannot complete within the specified `httpClose` timeout during shutdown. Inform clients about scheduled maintenance periods, or increase the `timeout` if these requests are critical and must always attempt to complete gracefully.

• TypeError: Cannot read properties of undefined (reading 'close') or similar errors related to `httpClose`

  cause This typically occurs if the `httpClose` function is not correctly imported or required, or if `server` is not a valid `http.Server` instance when passed to `httpClose`.
  fix For ESM, use `import httpClose from 'http-close';`. For CommonJS, `const httpClose = require('http-close');`. Always ensure a valid instance of `http.createServer()` result is passed as the second argument: `httpClose({ timeout: 5000 }, yourHttpServerInstance);`.

Warnings

• gotcha The `http-close` module augments the behavior of `server.close()` but does not replace it. You must still explicitly call `server.close()` on your `http.Server` instance to initiate the shutdown process; `http-close` then hooks into this event to manage active sockets.
  Fix: Always ensure you call `server.close()` when you intend to shut down your server. `httpClose({ timeout: X }, server)` should be called once after server creation but before `server.close()` is invoked.
• gotcha The default socket timeout implemented by `http-close` is 5 seconds for pending requests after `server.close()` is called. This default might be too short for applications with long-running requests or too long for scenarios requiring very rapid server shutdowns.
  Fix: Consider setting an explicit `timeout` option when initializing `httpClose`. For example: `httpClose({ timeout: 10000 }, server)` for 10 seconds, or `httpClose({ timeout: 1000 }, server)` for 1 second.
• gotcha This package appears to be in maintenance mode, with its latest version being 1.0.0 and no significant updates observed in recent years. While stable for its defined purpose, it may not actively address new Node.js features, HTTP protocol changes, or complex edge cases that newer, more actively maintained server shutdown solutions might cover.
  Fix: Evaluate if its functionality meets all requirements for modern Node.js applications. Consider alternatives if your project requires active development support, advanced features, or is highly sensitive to the latest platform changes.
• gotcha `http-close` is designed to immediately destroy any idle keep-alive sockets (i.e., those without an active HTTP response in progress) once `server.close()` is called. This is an intentional behavior to prevent the server from hanging on unused connections, but it's important to note that clients expecting persistent connections to remain open until explicitly closed by the client will have their idle connections terminated.
  Fix: Ensure client applications are designed to gracefully handle connection termination during server shutdown, especially for services relying heavily on HTTP keep-alive. This behavior is part of the graceful shutdown strategy.

Install

• npm install http-close npm
• yarn add http-close yarn
• pnpm add http-close pnpm

Imports

• httpClose

  import httpClose from 'http-close';

  This package ships TypeScript types and primarily uses a default export for its main function, aligning with modern ESM practices.
• httpClose
  wrong:

  import { httpClose } from 'http-close';

  correct:
  The primary export is a default function; attempting to import it as a named export will result in `undefined`.
• httpClose
  wrong:

  const httpClose = require('http-close');

  correct:
  While this CommonJS `require` syntax works, using `import` is preferred in modern TypeScript and ESM-based Node.js projects.

Quickstart

This example sets up an HTTP server with `http-close` to manage graceful shutdown. It simulates asynchronous request handling and demonstrates how to hook `http-close` to the server and trigger shutdown via `server.close()` in response to OS signals (SIGTERM/SIGINT), ensuring open connections are handled gracefully with a specified timeout.

import http from 'http';
import httpClose from 'http-close';

const server = http.createServer((req, res) => {
  // Simulate some async work that might keep the connection open
  setTimeout(() => {
    res.writeHead(200, { 'Content-Type': 'text/plain' });
    res.end('Hello, World!\n');
  }, Math.random() * 500); // Random delay up to 500ms
});

// Add http-close hook with a custom timeout of 3 seconds
httpClose({ timeout: 3000 }, server);

server.listen(3000, () => {
  console.log('Server listening on port 3000. Try hitting it with requests.');
  console.log('Then, press Ctrl+C to initiate graceful shutdown.');
});

// Handle graceful shutdown on process termination signals
process.on('SIGTERM', () => {
  console.log('SIGTERM received. Initiating graceful shutdown...');
  server.close(() => {
    console.log('Server closed. Exiting process.');
    process.exit(0);
  });
});

process.on('SIGINT', () => {
  console.log('SIGINT received. Initiating graceful shutdown...');
  server.close(() => {
    console.log('Server closed. Exiting process.');
    process.exit(0);
  });
});