rate-proxy is a small configurable HTTP/HTTPS reverse proxy for Node.js. It maps source paths to upstream paths and can pace requests by starting them at a fixed minimum interval.

• HTTP and HTTPS upstream support with streaming request and response bodies.
• Configurable source-to-destination path mappings from CLI arguments or JSON.
• Multiple routes with automatic priority for longer, more specific prefixes.
• Fixed-interval request pacing with a bounded queue.
• Configurable upstream timeout with 502 Bad Gateway and 504 Gateway Timeout handling.
• CORS headers and automatic preflight OPTIONS responses.
• Hop-by-hop header filtering and managed X-Forwarded-* headers.
• Optional verbose request and upstream-error logging.

• Node.js 20 or newer
• pnpm (recommended) or npm

pnpm install

The safe defaults listen on 127.0.0.1:8080, forward to http://localhost, and start at most one request every 500 ms:

pnpm start

Forward /api/* to /v1/* on another server:

node index.js --host http://localhost:3000 --map /api:/v1

Available options:

• -v, --verbose: log proxied requests and upstream errors.
• -c, --config <file>: load routes from a JSON file.
• -t, --timeout <ms>: minimum interval between request starts; use 0 to disable pacing (default: 500).
• -H, --host <host>: upstream origin used by CLI mappings (default: http://localhost).
• -l, --listen-host <host>: local interface (default: 127.0.0.1).
• -p, --port <port>: local port (default: 8080).
• -m, --map <source:destination>: path mapping; may be supplied more than once.
• -q, --max-queue <num>: maximum queued requests (default: 1000).
• --max-queue-wait <ms>: maximum queue wait before a 503 response (default: 30000).
• --upstream-timeout <ms>: upstream timeout before a 504 response (default: 30000).
• -C, --cors <origin>: set an allowed CORS origin and answer preflight requests.

The server binds only to loopback by default. Use --listen-host 0.0.0.0 only when access from other machines is intended and protected by appropriate firewall and authentication controls.

{
  "routes": [
    {
      "srcPath": "/api",
      "destPath": "/v1",
      "destHost": "http://localhost:3000"
    },
    {
      "srcPath": "/",
      "destPath": "/",
      "destHost": "https://example.com"
    }
  ]
}

Routes with longer source prefixes take priority. destHost accepts http:// and https://; a host without a scheme is treated as HTTP for compatibility. Credentials in destHost are rejected.

The proxy removes hop-by-hop headers and supplies X-Forwarded-For, X-Forwarded-Host, and X-Forwarded-Proto. It does not provide authentication or TLS termination for incoming connections.

pnpm check
pnpm audit --prod

The test suite starts temporary local upstream and proxy servers and verifies routing, streaming request bodies, CORS, request pacing, and upstream timeouts.

MIT