HTTP Proxy 3

Common errors

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

  cause The port the proxy server is trying to listen on is already in use by another process.
  fix Change the proxy's listening port to an available one, or stop the process currently using the port (e.g., `kill -9 <PID>` on Linux/macOS or `netstat -ano | findstr :<PORT>` followed by `taskkill /PID <PID> /F` on Windows).

• Error: connect ECONNREFUSED 127.0.0.1:9000

  cause The proxy server could not connect to the target server because the target server is not running or its address/port is incorrect.
  fix Ensure the target server is running and accessible at the configured `target` address and port. Verify no firewalls are blocking the connection between the proxy and target.

• Proxy Error: Could not proxy request /socket.io/?EIO=3&transport=websocket to ws://localhost:9000/socket.io/?EIO=3&transport=websocket (ECONNREFUSED)

  cause The proxy failed to establish a WebSocket connection to the target server, often because the target does not support WebSockets or the WebSocket server isn't running.
  fix Confirm that the target server correctly implements and listens for WebSocket connections. Ensure `ws: true` is set in the `createProxyServer` options if you intend to proxy WebSockets.

• HTTP/1.1 407 Proxy Authentication Required

  cause The proxy itself (or an upstream proxy) requires authentication before it will forward the request.
  fix Provide the necessary authentication credentials in the proxy configuration if `http-proxy-3` is acting as a client to another authenticated proxy, or ensure your client accessing `http-proxy-3` provides valid credentials if `http-proxy-3` is configured to require them.

• Error: Parse Error: HPE_INVALID_HEADER_TOKEN

  cause The target server returned a malformed HTTP header, which Node.js's HTTP parser cannot interpret.
  fix Inspect the responses from your target server for invalid characters or formatting in HTTP headers. This often indicates an issue with the target server's HTTP implementation.

Warnings

• breaking http-proxy-3 requires Node.js version 18 or higher. Applications running on older Node.js runtimes must upgrade their environment before adopting this package.
  Fix: Upgrade Node.js to version 18 or newer.
• breaking This library is a complete rewrite of `http-proxy`, addressing many longstanding issues including socket leaks and uncatchable WebSocket errors in the original package. While API compatible, direct migration from `http-proxy` may expose subtle behavioral changes or require updating code that relied on deprecated/insecure APIs (e.g., `URL` instead of `parse`).
  Fix: Thoroughly test existing proxy configurations after upgrading from `http-proxy`. Review and update any custom request/response handling logic that might rely on older Node.js or `http-proxy` internals.
• gotcha The README notes that using the proxy server introduces a performance penalty, with proxied operations potentially taking 'about twice as long' compared to direct connections. This should be considered for highly performance-sensitive applications.
  Fix: Benchmark your application's specific use case to determine the impact. Optimize backend services or consider alternative architectures if the performance overhead is unacceptable.
• gotcha HTTP/2 support in http-proxy-3 is achieved via the `fetch` API and is currently marked as 'experimental'. While functional and tested, the API and behavior may change in future versions.
  Fix: Use HTTP/2 features with caution in production environments. Monitor release notes for changes related to HTTP/2 support and be prepared to adapt configurations as the feature matures.
• breaking http-proxy-3 fixes a significant security vulnerability (related to issue #1647 in the original http-party/node-http-proxy). Using older, unmaintained versions of `http-proxy` exposes applications to this vulnerability.
  Fix: Immediately upgrade to http-proxy-3 to benefit from this and other security patches.

Install

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

Imports

• createProxyServer
  wrong:

  const httpProxy = require('http-proxy-3'); const proxy = httpProxy.createProxyServer();

  correct:

  import { createProxyServer } from 'http-proxy-3';

  http-proxy-3 is primarily designed for ES Modules, though CommonJS `require` might work with transpilation or specific Node.js loader configurations. `createProxyServer` is the main factory function.
• ProxyServerOptions

  import type { ProxyServerOptions } from 'http-proxy-3';

  This type definition is crucial for TypeScript users to correctly configure the proxy server instance.
• ProxyServer

  import type { ProxyServer } from 'http-proxy-3';

  Represents the instance returned by `createProxyServer`, useful for type annotations when working with proxy event listeners or methods like `web()` and `ws()`.

Quickstart

This quickstart sets up a basic HTTP and WebSocket proxy that forwards requests from port 8000 to a target server running on port 9000, demonstrating core proxying functionality and error handling.

import * as http from 'node:http';
import { createProxyServer, type ProxyServerOptions } from 'http-proxy-3';

// Create a target HTTP server
const targetServer = http.createServer((req, res) => {
  console.log(`Target received: ${req.method} ${req.url}`);
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('Hello from the target server!');
});

targetServer.listen(9000, () => {
  console.log('Target server listening on http://localhost:9000');
});

// Create a basic HTTP proxy server
const proxyOptions: ProxyServerOptions = {
  target: 'http://localhost:9000',
  ws: true // Enable websocket proxying
};

const proxy = createProxyServer(proxyOptions);

// Handle proxy errors
proxy.on('error', (err, req, res) => {
  console.error('Proxy Error:', err);
  if (res && res.writeHead) {
    res.writeHead(500, { 'Content-Type': 'text/plain' });
    res.end('Something went wrong with the proxy.');
  }
});

// Create a proxy listening server
const proxyServer = http.createServer((req, res) => {
  console.log(`Proxying request: ${req.method} ${req.url}`);
  proxy.web(req, res);
});

proxyServer.on('upgrade', (req, socket, head) => {
  console.log(`Proxying websocket upgrade: ${req.url}`);
  proxy.ws(req, socket, head);
});

proxyServer.listen(8000, () => {
  console.log('Proxy server listening on http://localhost:8000');
  console.log('Test with: curl http://localhost:8000');
  console.log('Test websockets with a client connecting to ws://localhost:8000');
});