REserve: Regex-Configurable HTTP Server

Common errors

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

  cause The specified port (e.g., 8080) is already being used by another application or a previously failed server instance.
  fix Change the `port` in your `reserve` configuration to an unused port, or terminate the process currently occupying the port (e.g., using `lsof -i :8080` and `kill <PID>` on Linux/macOS, or Resource Monitor on Windows).

• 404 Not Found (from reserve server)

  cause No mapping in the `reserve` configuration matched the incoming request URL, or a `file` handler pointed to a non-existent file.
  fix Review your `mappings` array. Ensure your `match` regular expressions correctly capture the intended URLs. Check `file` handler paths for correctness relative to the server's working directory or use absolute paths.

• Property 'on' does not exist on type 'void' or 'Promise<void>'

  cause Attempting to chain `.on()` calls directly after `serve()` without correctly handling its return type or in a context where `serve` is awaited prematurely.
  fix Ensure you are calling `.on()` methods directly on the `serve` function's return value, which is an event emitter (Promise-like with `.on()` methods). Do not `await serve(config)` if you intend to chain `.on()` immediately. If using `async/await`, await after chaining events, or capture the returned instance.

Warnings

• breaking The `static` option for `file` handlers now defaults to `false` instead of `true`. If your configuration relied on `static: true` by default, explicitly set it in your mappings.
  Fix: Update your `file` handler mappings to explicitly include `"static": true` if you intend for directory listings or other static file behaviors.
• gotcha Regular expression matching is fundamental to `reserve` configuration. Incorrect or overly broad regex patterns can lead to unexpected routing, resource exposure, or 404 errors. Carefully test your `match` patterns.
  Fix: Use online regex testers or Node.js `RegExp` to validate your patterns. Start with simple matches and incrementally increase complexity. Ensure patterns are anchored (e.g., `^/path/(.*)$`) to prevent partial matches.
• gotcha In earlier versions, `Server.close()` might not have forcefully closed all pending connections, potentially leading to processes hanging. Version 2.3.0 introduced options to force closing.
  Fix: Upgrade to `reserve@2.3.0` or higher to utilize the `force` option with `serverInstance.close({ force: true })` for more reliable server shutdowns.

Install

• npm install reserve npm
• yarn add reserve yarn
• pnpm add reserve pnpm

Imports

• serve
  wrong:

  const serve = require('reserve')

  correct:

  import { serve } from 'reserve'

  The `serve` function is the primary export for embedding the server. CommonJS `require` works but ESM `import` is preferred in modern Node.js.
• Configuration

  import { Configuration } from 'reserve'

  TypeScript type for defining the server's configuration object. Essential for type-safe server setup.
• Server

  import { Server } from 'reserve'

  TypeScript type for the object returned by `serve()`, which exposes event emitters and the `close` method.

Quickstart

Demonstrates how to embed and start a `reserve` HTTP server in a TypeScript application with basic static file serving, including event handling for ready, error, and graceful shutdown on process signals.

import { serve, Configuration, Server } from 'reserve';
import * as path from 'path';

const config: Configuration = {
  port: 8080,
  mappings: [
    {
      // Serve files from the current working directory
      match: '^/(.*)',
      file: path.join(process.cwd(), '$1') // Ensures serving from the correct absolute path
    },
    {
      // Default catch-all for unmatched requests
      status: 404
    }
  ]
};

let serverInstance: Server | null = null; // To hold the server instance for graceful shutdown

serve(config)
  .on('ready', ({ url }: { url: string }) => {
    serverInstance = serverInstance; // Capture the instance
    console.log(`REserve server running at ${url}`);
    console.log(`Try accessing http://localhost:${config.port}/package.json if this file exists in your current directory.`);
  })
  .on('error', (error: Error) => {
    console.error('REserve server encountered an error:', error.message);
  })
  .on('abort', () => {
    console.log('REserve server aborted.');
  });

// Implement graceful shutdown on process termination signals
process.on('SIGINT', async () => {
  console.log('SIGINT received. Shutting down REserve server...');
  if (serverInstance) {
    try {
      await serverInstance.close();
      console.log('REserve server gracefully closed.');
    } catch (err) {
      console.error('Error closing REserve server:', err);
    }
  }
  process.exit(0);
});

process.on('SIGTERM', async () => {
  console.log('SIGTERM received. Shutting down REserve server...');
  if (serverInstance) {
    try {
      await serverInstance.close();
      console.log('REserve server gracefully closed.');
    } catch (err) {
      console.error('Error closing REserve server:', err);
    }
  }
  process.exit(0);
});