Configurable HTTP Proxy

5.2.0 verified Thu Apr 23 auth: no javascript

`configurable-http-proxy` (CHP) is a robust HTTP proxy designed to dynamically manage routing tables via either a command-line interface or a REST API. Built as a wrapper around `node-http-proxy`, it extends the underlying library's capabilities to include WebSocket support, making it suitable for reverse proxies and load balancers. The package is a core component in JupyterHub deployments, enabling flexible routing for multi-user environments. The current stable version is 5.2.0, requiring Node.js 20 or newer. Releases typically align with JupyterHub's development cycle, focusing on stability, security, and integration within the Jupyter ecosystem. Its key differentiator is the on-the-fly reconfigurability of routes and its robust API for programmatic control, allowing for complex, dynamic proxying scenarios. It operates with distinct public-facing and inward-facing REST API servers, each with configurable IPs and ports.

Common errors

error Error: listen EADDRINUSE :::[port] ↓

cause The specified public-facing port (--port) or API port (--api-port) is already in use by another process on the system.

fix

Choose an available port or terminate the process currently using the port. You can find processes using a port with lsof -i :[port] (Linux/macOS) or netstat -ano | findstr :[port] (Windows).

error Error: HTTP 401 Unauthorized ↓

cause An API request was made to `configurable-http-proxy` without a valid `Authorization: token <TOKEN>` header, or the provided token does not match `CONFIGPROXY_AUTH_TOKEN`.

fix

Ensure the CONFIGPROXY_AUTH_TOKEN environment variable is correctly set when starting the proxy. For API calls, include the Authorization header with the correct token: curl -H "Authorization: token $CONFIGPROXY_AUTH_TOKEN" http://localhost:8001/api/routes.

error SyntaxError: Unexpected token 'catch' (or similar Node.js engine error) ↓

cause Running `configurable-http-proxy` on an incompatible Node.js version, especially one older than 20, leading to syntax errors from newer JavaScript features.

fix

Upgrade your Node.js installation to version 20 or newer. Use a Node Version Manager like nvm install 20 && nvm use 20 to manage versions.

error Error: No default target configured and no route found for / ↓

cause The proxy received a request for a path that does not have an explicit route configured, and no `--default-target` was specified when the proxy was started.

fix

Restart the proxy with a --default-target option, e.g., configurable-http-proxy --default-target=http://localhost:8000 ... to direct unrouted traffic to a fallback service.

Warnings

breaking configurable-http-proxy version 5.x and newer requires Node.js version 20 or greater. Attempting to run on older Node.js versions will result in a runtime error. ↓

fix Upgrade your Node.js environment to version 20 or newer. Consider using a Node Version Manager (nvm) for easy switching between versions.

gotcha The REST API for `configurable-http-proxy` requires a security token for authentication, set via the `CONFIGPROXY_AUTH_TOKEN` environment variable. Failing to set this token or providing an incorrect one will prevent API access and route management. ↓

fix Ensure the `CONFIGPROXY_AUTH_TOKEN` environment variable is set with a strong, secret token before starting the proxy. For API calls, include this token in the `Authorization` header as `token <YOUR_TOKEN>`.

gotcha By default, `configurable-http-proxy` runs two distinct HTTP(S) servers: a public-facing interface (--ip, --port) and an inward-facing REST API (--api-ip, --api-port). The API defaults to listening on localhost. Exposing the API publicly (e.g., `--api-ip=0.0.0.0`) without proper network-level access control is a significant security risk, especially with an improperly managed token. ↓

fix Always bind the API to a restricted IP address (e.g., `127.0.0.1` or a private network interface) and ensure network firewalls restrict access to the API port. Only expose the public-facing proxy as needed.

gotcha When no specific route matches an incoming request, `configurable-http-proxy` uses a `--default-target`. If no default target is set and no route matches, the proxy will return a 404 error. This can be problematic if you expect all traffic to be handled or redirected. ↓

fix Always specify a `--default-target` when starting the proxy, pointing to a fallback service (e.g., a JupyterHub instance or an error page server) to gracefully handle unrouted requests.

gotcha The README suggests global installation via `npm install -g configurable-http-proxy`. While convenient, global Node.js packages can lead to version conflicts and inconsistencies across different projects or environments. ↓

fix For project-specific deployments, consider installing `configurable-http-proxy` as a development dependency (`npm install --save-dev configurable-http-proxy`) and running it via `npx` or a script defined in `package.json` to ensure version isolation.

Install

npm install configurable-http-proxy

yarn add configurable-http-proxy

pnpm add configurable-http-proxy

Imports

ConfigurableProxy
wrong
```
import { ConfigurableProxy } from 'configurable-http-proxy';
const ConfigurableProxy = require('configurable-http-proxy').ConfigurableProxy;
```
correct
```
import ConfigurableProxy from 'configurable-http-proxy';
```
The package primarily exposes the ConfigurableProxy class as a default export for programmatic use. It is predominantly used as a standalone CLI tool or service, with direct programmatic instantiation being less common.

Quickstart

This script demonstrates how to start `configurable-http-proxy` as a standalone service, setting up a default routing target and configuring both the public-facing and REST API interfaces with a security token.

#!/usr/bin/env bash

# Set a token for API authentication (important for security)
export CONFIGPROXY_AUTH_TOKEN="$(head /dev/urandom | tr -dc A-Za-z0-9_ | head -c 32)"

# Install globally if not already installed
# npm install -g configurable-http-proxy

# Start the configurable-http-proxy with a default target
# and distinct public/API ports.
# The public-facing proxy listens on port 8080.
# The REST API for configuration listens on port 8001.
# All traffic not matching a route will be forwarded to http://localhost:8000.
configurable-http-proxy \
  --default-target=http://localhost:8000 \
  --api-ip=127.0.0.1 \
  --api-port=8001 \
  --port=8080 \
  --ip=0.0.0.0 \
  --log-level=debug

echo "Proxy started. Public interface on http://localhost:8080. API on http://127.0.0.1:8001."
echo "Use CONFIGPROXY_AUTH_TOKEN for API requests: $CONFIGPROXY_AUTH_TOKEN"