HTTP and WebSocket Proxy for Node.js

Common errors

• Proxy error: connect ECONNREFUSED

  cause The target server that the `httpxy` instance is configured to proxy requests to is either not running, not listening on the specified address/port, or is unreachable due to network configuration or firewalls.
  fix Verify that the target server (e.g., `http://127.0.0.1:8080` in examples) is actively running and listening on the correct host and port. Ensure network connectivity between the `httpxy` server and the target server.

• Error: WebSocket was closed before the connection was established.

  cause When using `proxyUpgrade`, this error indicates that the target server for the WebSocket upgrade request did not properly respond to the WebSocket handshake, or the connection was terminated prematurely.
  fix Ensure the target server specified in `proxyUpgrade` is correctly configured to handle WebSocket upgrade requests and that no intermediate proxies or firewalls are interfering with the WebSocket handshake. Check server logs for errors related to WebSocket connections.

• Applications on high load exhibit poor performance or excessive socket creation.

  cause This can occur if the default `keepAlive` connection pooling (introduced in v0.5.0) is inadvertently disabled, or if using an older version of `httpxy` that predates this feature.
  fix For `httpxy` versions >= v0.5.0, ensure that `agent: false` is *not* set in your `ProxyServer` or `proxyFetch` options if you intend to leverage the default keep-alive connection pooling. If more granular control is needed, provide a custom `http.Agent` or `https.Agent` instance configured with `keepAlive: true`.

Warnings

• breaking Starting with v0.5.0, `ProxyServer` and `proxyFetch` now utilize shared `http.Agent`/`https.Agent` instances with `keepAlive: true` by default. This enables connection pooling (256 max sockets, 64 max free sockets) instead of creating a new socket per request. This change significantly affects resource usage and connection behavior.
  Fix: To revert to the pre-v0.5.0 behavior of creating a new socket per request, set `agent: false` in the options for `proxy.web` (e.g., `proxy.web(req, res, { target, agent: false })`) or `proxyFetch` (e.g., `proxyFetch(target, url, { agent: false })`).
• breaking The v0.2.0 release included a significant 'Code improvements' refactor, marked with a breaking change warning. While specific API breakages were not detailed, this suggests potential changes in internal behavior or less common use cases. Developers upgrading from pre-v0.2.0 should proceed with caution.
  Fix: Thoroughly review your proxy configurations and test applications when upgrading from versions prior to v0.2.0. Consult the changelog for any subtle behavioral changes that might impact your specific use case, though no explicit API changes were documented.
• gotcha The `followRedirects` option has seen evolving support and default behavior across different versions and proxy methods. It was initially noted as unsupported in v0.1.6, then native support was added in v0.3.0, and `proxyFetch` gained explicit `followRedirects` options in v0.4.0. For `proxyFetch`, redirects are handled manually by default, meaning automatic following requires explicit configuration.
  Fix: When using `proxyFetch`, explicitly set the `followRedirects` option if automatic redirect following is desired. For `ProxyServer`, consult the latest documentation for the specific `followRedirects` behavior and its configuration, as defaults and availability might vary.

Install

• npm install httpxy npm
• yarn add httpxy yarn
• pnpm add httpxy pnpm

Imports

• proxyFetch
  wrong:

  const { proxyFetch } = require('httpxy');

  correct:

  import { proxyFetch } from 'httpxy';

  httpxy is an ESM-first package and ships with TypeScript types. Use named imports.
• proxyUpgrade
  wrong:

  const proxyUpgrade = require('httpxy').proxyUpgrade;

  correct:

  import { proxyUpgrade } from 'httpxy';

  Used for standalone WebSocket upgrade proxying, it's a named export.
• createProxyServer
  wrong:

  const createProxyServer = require('httpxy');
  const proxy = createProxyServer({});

  correct:

  import { createProxyServer } from 'httpxy';

  `createProxyServer` is a factory function and a named export. Ensure to use named imports.

Quickstart

This quickstart demonstrates setting up a basic HTTP proxy server using `createProxyServer`. It listens on a specified port and forwards incoming requests to a configurable target URL, handling potential proxy errors gracefully.

import { createServer } from 'node:http';
import { createProxyServer } from 'httpxy';

const proxy = createProxyServer({});

const server = createServer(async (req, res) => {
  try {
    // Replace with your target server's address
    const targetAddress = process.env.PROXY_TARGET_URL ?? 'http://127.0.0.1:8080';
    await proxy.web(req, res, {
      target: targetAddress
    });
  } catch (error) {
    console.error('Proxy error:', error);
    res.statusCode = 500;
    res.end('Proxy error: ' + String(error));
  }
});

const port = process.env.PORT ?? 3000;
server.listen(port, () => {
  console.log(`Proxy is listening on http://localhost:${port}`);
  console.log('Ensure a target server is running at', process.env.PROXY_TARGET_URL || 'http://127.0.0.1:8080');
});