HTTP Shutdown

Common errors

• `server.shutdown is not a function`

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

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

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

Warnings

• gotcha The 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.
• gotcha Mixing 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.
• gotcha Calling `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`.
• gotcha As 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.

Install

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

Imports

• httpShutdown (function)
  wrong:

  import { httpShutdown } from 'http-shutdown';

  correct:

  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()
  wrong:

  import { extend } from 'http-shutdown';

  correct:

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

  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.

Quickstart

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);
  });
});