Node.js Process-Based HTTP Proxy

Common errors

• ReferenceError: require is not defined in ES module scope

  cause Attempting to use `require()` syntax in a Node.js environment configured for ES Modules (e.g., `"type": "module"` in package.json).
  fix This package is strictly CommonJS. Change your project to CommonJS (remove `"type": "module"` from `package.json`) or use `createRequire` for interoperability (not recommended for an abandoned package).

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

  cause The specified proxy port (default 8123) is already being used by another application on your system.
  fix Stop the application using the port or configure `node-http-proxy` to use a different port (e.g., `new ProxyMaster({port: 9000})`).

• Error: The "url" argument must be of type string. Received undefined

  cause An upstream proxy request or configuration is missing a target URL, which might stem from outdated internal dependencies or misconfigurations for HTTP client interactions within the proxy.
  fix This error often indicates deep incompatibility with modern Node.js `http` modules or internal issues within this specific, old package. There's no straightforward fix; it reinforces the recommendation to migrate to a maintained proxy library.

Warnings

• breaking This package is extremely old (v0.2.4) and abandoned. It is fundamentally incompatible with modern Node.js versions (e.g., Node.js 12+), which have deprecated or removed features it relies on, such as old OpenSSL versions or specific internal Node.js APIs. Running it will likely result in runtime errors.
  Fix: Do not use this package. Consider modern alternatives like `http-proxy` (from `http-party`) or `http-proxy-middleware`.
• gotcha This specific `node-http-proxy` (by 'wddqing') is distinct from the popular and actively maintained `http-proxy` (by `http-party`). Using this abandoned version will lead to compatibility, security, and maintenance issues. Always verify the GitHub repository and npm publisher for proxy libraries.
  Fix: Ensure you are installing and using `http-proxy` from the `http-party` organization (npm: `http-proxy`) if you need a current, maintained proxy library. If you need a middleware for Express/Connect, `http-proxy-middleware` is also an excellent choice.
• breaking Due to its age and reliance on CommonJS, this package will not work directly in Node.js ES Module environments without a CommonJS wrapper or specific build configurations (e.g., using `createRequire`).
  Fix: If forced to use this package in an ESM context (not recommended), you would need to use `import { createRequire } from 'module'; const require = createRequire(import.meta.url);` before your `require()` calls. However, overall compatibility issues remain. Prioritize migration to a modern proxy solution.
• gotcha The package's lack of maintenance implies potential unfixed security vulnerabilities. Using it in production could expose your application to risks such as proxy-related attacks, denial of service, or data breaches.
  Fix: Migrate to a actively maintained HTTP proxy library that receives regular security updates and patches. This package should not be used in any security-sensitive environment.

Install

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

Imports

• ProxyMaster
  wrong:

  import { ProxyMaster } from 'node-http-proxy';

  correct:

  const { proxyMaster: ProxyMaster } = require('node-http-proxy');

  This package uses CommonJS (CJS) modules exclusively due to its age. ES Modules (ESM) syntax like `import` will not work. The export `proxyMaster` is nested within the main module object.
• nproxy CLI
  wrong:

  node node_modules/node-http-proxy/bin/nproxy.js start

  correct:

  npm install -g node-http-proxy && nproxy start -p 9999 -i 1

  The primary CLI entry point `nproxy` is available after global installation. Direct execution might require specific paths.

Quickstart

Demonstrates how to programmatically start a `node-http-proxy` server with a configurable port and number of worker instances.

const { proxyMaster: ProxyMaster } = require('node-http-proxy');

const port = process.env.PROXY_PORT ? parseInt(process.env.PROXY_PORT) : 8123;
const instances = process.env.PROXY_INSTANCES ? parseInt(process.env.PROXY_INSTANCES) : 1;

console.log(`Starting Node HTTP Proxy on port ${port} with ${instances} instance(s)...`);

const proxymaster = new ProxyMaster({
  instance: instances,
  port: port
});

proxymaster.start();

// Example of how to stop the server (optional, for demonstration)
// setTimeout(() => {
//   console.log('Stopping proxy master...');
//   // Note: The original package's stop mechanism is primarily CLI-driven.
//   // Programmatic stopping might require deeper inspection or process killing.
// }, 10000);

console.log('Proxy server initialized. Use `curl -x 127.0.0.1:' + port + ' http://www.google.com/` to test.');