Graceful HTTP Server Termination

Common errors

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

  cause `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).

  cause 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.

  cause 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.

Warnings

• breaking Version 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.
• breaking Support 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.
• gotcha Calling `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.
• gotcha Since 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()`.
• gotcha The `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 })`.

Install

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

Imports

• createHttpTerminator
  wrong:

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

  correct:

  import { createHttpTerminator } from 'http-terminator';

  The package is ESM-first since v3.0.0. Use `import` syntax.
• HttpTerminatorType
  wrong:

  import { HttpTerminatorType } from 'http-terminator';

  correct:

  import type { 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.

Quickstart

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.');