Node.js Destroyable Server

Common errors

• TypeError: server.destroy is not a function

  cause You are attempting to call `destroy()` on a server object that has not been enhanced by `makeDestroyable`.
  fix Ensure you have called `server = makeDestroyable(server);` (or similar assignment) on your server instance before attempting to invoke `server.destroy()`.

• Error: listen EADDRINUSE: address already in use :::PORT

  cause A previous server instance on the same port was not fully shut down before a new one attempted to bind to the port. This often happens when `server.destroy()` was called but not awaited, or if the process exited before the cleanup completed.
  fix Always `await server.destroy()` during shutdown routines to guarantee that all connections are closed and the port is released before attempting to restart the server or exit the process.

Warnings

• gotcha The `makeDestroyable` function mutates the server object passed to it, adding internal tracking for connections and the `destroy()` method directly to the instance. Be aware that the original server object reference will be modified.
  Fix: While the mutation is intended behavior, developers should treat the return value of `makeDestroyable` as the primary reference for the enhanced server, as shown in `server = makeDestroyable(server);`.
• gotcha The `server.destroy()` method returns a Promise that resolves once all connections are terminated and the server is fully closed. Failing to `await` this promise can lead to premature process exits or other cleanup logic running before all resources are released, potentially causing resource leaks or 'address already in use' errors on restart.
  Fix: Always use `await server.destroy();` when initiating a shutdown to ensure complete resource cleanup before continuing or exiting the process.
• gotcha This module is specifically designed for `net.Server` instances and objects following its patterns. Attempting to use `makeDestroyable` on objects that are not `net.Server` instances or lack the necessary underlying socket management may lead to unexpected behavior or errors.
  Fix: Ensure that the object passed to `makeDestroyable` is an instance of `net.Server` or a compatible derivative like `http.Server` or `https.Server`.

Install

• npm install destroyable-server npm
• yarn add destroyable-server yarn
• pnpm add destroyable-server pnpm

Imports

• makeDestroyable
  wrong:

  import makeDestroyable from 'destroyable-server';

  correct:

  import { makeDestroyable } from 'destroyable-server';

  This package uses named exports. A default import is incorrect.
• makeDestroyable
  wrong:

  const makeDestroyable = require('destroyable-server');

  correct:

  const { makeDestroyable } = require('destroyable-server');

  CommonJS requires destructuring for the named export. Importing the entire module directly would result in an object containing the function.
• MakeDestroyable

  import type { MakeDestroyable } from 'destroyable-server';

  TypeScript users can import the `MakeDestroyable` type for explicit type annotations on server instances that have been made destroyable.

Quickstart

This quickstart demonstrates creating a Node.js TCP server, making it destroyable, and then gracefully shutting it down by forcibly closing all active connections after a delay.

import { createServer } from 'net';
import { makeDestroyable } from 'destroyable-server';

const PORT = process.env.PORT ?? 8000;

// Create a basic TCP server
let server = createServer((socket) => {
  console.log('Client connected.');

  socket.write('Hello from destroyable-server!\n');
  socket.on('end', () => {
    console.log('Client disconnected.');
  });

  // Example: close connection after 5 seconds
  setTimeout(() => {
    if (!socket.destroyed) {
      socket.end('Server closing connection.\n');
    }
  }, 5000);
});

// Make the server destroyable
server = makeDestroyable(server);

server.listen(PORT, () => {
  console.log(`Server listening on port ${PORT}.`);
});

// Simulate a shutdown after 10 seconds
setTimeout(async () => {
  console.log('Initiating server shutdown...');
  try {
    await server.destroy();
    console.log('Server and all connections destroyed successfully.');
  } catch (error) {
    console.error('Error during server destruction:', error);
  }
  // In a real application, you might then exit the process: process.exit(0);
}, 10000);