Registry / http-networking / configurable-http-proxy

configurable-http-proxy

library0.4.0jsnpmunverified

`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.

http-networking devops

npm install configurable-http-proxy

github ↗package ↗

INSTALL

IMPORT

SIG · CONFIGURABLE-HTTP-

configurable-http-proxy

http-networkingjavascriptv0.4.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ConfigurableProxy

✓ import ConfigurableProxy from 'configurable-http-proxy';

✗ import { ConfigurableProxy } from 'configurable-http-proxy'; const ConfigurableProxy = require('configurable-http-proxy').ConfigurableProxy;

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.

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"

configurable-http-proxy --version

Debug

Known issues

breakingconfigurable-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.

affects: >=5.0.0

gotchaThe 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>`.

affects: >=1.0.0

gotchaBy 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.

affects: >=1.0.0

gotchaWhen 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.

affects: >=1.0.0

gotchaThe 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.

affects: >=1.0.0

Errors

Common errors & fixes

Error: listen EADDRINUSE :::[port]

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: HTTP 401 Unauthorized

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`.

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

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: No default target configured and no route found for /

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.

Upgrade

Version history

0.4.0latest on npm

Audit

Dependencies

node-http-proxyrequiredCore proxying library that configurable-http-proxy wraps and extends.

node-commanderrequiredUsed for command-line interface parsing.

node-winstonrequiredUsed for logging within the proxy.

Agent activity

18 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/jupyterhub/configurable-http-proxy ↗

packagehttps://www.npmjs.com/package/configurable-http-proxy ↗