HTTP Simple Proxy Daemon

Common errors

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

  cause Another process is already occupying the specified port (e.g., port 80 or 443).
  fix Stop the conflicting process, or configure http-simple-proxy to listen on a different, available port.

• Proxy error: Error: SSL_CTX_use_PrivateKey_file:EE_KEY_TOO_SMALL

  cause The provided SSL private key is invalid, corrupted, or too short (e.g., 512-bit key).
  fix Generate a new, valid SSL private key (e.g., 2048-bit or higher) and ensure it matches the certificate. Verify the paths to the key and certificate files are correct.

• TypeError: Cannot read properties of undefined (reading 'router')

  cause The configuration object passed to `init()` is malformed, specifically lacking the expected `router` property within a port definition, or `ports` itself is missing.
  fix Double-check your configuration object structure. Ensure that `ports` is an object, and each port number within it contains an object that defines a `router` key.

• Requests are not being routed to the expected backend.

  cause Misconfiguration in the `router` rules, such as incorrect domain names, port numbers, or overlapping/incorrect regular expression patterns.
  fix Review your router configuration rules carefully. Ensure domain names match exactly (or use correct wildcards), target ports are correct, and the order of rules for complex routing is as intended (most specific rules should often come before more general ones).

Warnings

• breaking http-simple-proxy is a simpler rewrite of `http-master`. Users migrating from `http-master` should expect significant differences in configuration options and available features, requiring a complete review and rewrite of proxy configurations.
  Fix: Do not attempt to port `http-master` configurations directly. Refer to the http-simple-proxy README for specific syntax and supported features.
• gotcha The configuration object for `init()` can become complex, especially with nested `ports` and `router` definitions. Pay close attention to the specific keys and their expected values (e.g., numbers for ports, strings for hosts, or objects for advanced rules).
  Fix: Always validate your configuration object structure against the documentation examples. Start with simple rules and progressively add complexity. Use an object literal for the main configuration, and ensure `ports` is a top-level key within it.
• gotcha Setting up SSL (HTTPS) requires providing valid `key` and `cert` paths within the `ssl` object for the respective port. Omitting or providing incorrect paths will prevent the HTTPS server from starting or cause certificate errors for clients.
  Fix: Ensure `ssl.key` and `ssl.cert` point to existing, readable SSL private key and certificate files (e.g., using `fs.readFileSync` or providing paths for an internal mechanism). Test SSL configuration thoroughly.
• gotcha Wildcard domain matching behavior can be subtle. `*.domain.com` matches subdomains but not `domain.com` itself, while `*?.domain.com` matches both subdomains and `domain.com`.
  Fix: Carefully review your wildcard domain rules. If you intend to catch both the root domain and its subdomains, use the `*?.domain.com` pattern. Test with various host headers to ensure correct routing.

Install

• npm install http-simple-proxy npm
• yarn add http-simple-proxy yarn
• pnpm add http-simple-proxy pnpm

Imports

• HttpSimpleProxy
  wrong:

  import { HttpSimpleProxy } from 'http-simple-proxy';

  correct:

  const HttpSimpleProxy = require('http-simple-proxy');

  This package primarily uses CommonJS `require()`. Direct ESM `import` is not officially supported and will likely fail without a transpiler or specific Node.js configuration.
• HttpSimpleProxy
  wrong:

  const proxy = HttpSimpleProxy();

  correct:

  const proxy = new HttpSimpleProxy();

  The imported `HttpSimpleProxy` is a class constructor and must be instantiated with `new` before use.
• Configuration Object
  wrong:

  proxy.init(portsConfig, callback);

  correct:

  proxy.init({ ports: { ... } }, callback);

  The `init` method expects a configuration object with a top-level `ports` key. Passing the ports configuration directly will lead to errors.

Quickstart

This quickstart demonstrates how to install http-simple-proxy and configure it to listen on ports 80 and 443, routing incoming requests to different backend services based on the domain name, including basic SSL configuration.

const HttpSimpleProxy = require('http-simple-proxy');
const httpSimpleProxy = new HttpSimpleProxy();

const config = {
  ports: {
    80: {
      router: {
        // Proxy requests for 'domain1.com' to port 3333
        "domain1.com": 3333,
        // Proxy requests for 'www.domain1.com' to port 3334
        "www.domain1.com": 3334,
        // Proxy all other requests on port 80 to a default backend on port 4080
        "*": 4080
      }
    },
    443: {
      router: {
        // Example for HTTPS, assuming SSL certificates are configured separately
        "secure.domain.com": 5000
      },
      ssl: {
        key: process.env.SSL_KEY_PATH ?? '', // Path to your SSL private key file
        cert: process.env.SSL_CERT_PATH ?? '' // Path to your SSL certificate file
      }
    }
  }
};

httpSimpleProxy.init(config, function(err) {
  if (err) {
    console.error('Proxy initialization error:', err);
  } else {
    console.info('http-simple-proxy started successfully');
    console.info('Listening on ports 80 and 443');
  }
});