httpxy

A ProxyTarget specifies the destination for proxied requests. It can be provided in three formats:

1. String: A URL string (e.g., 'http://localhost:3000').
2. URL: A standard JavaScript URL object.
3. ProxyTargetDetailed: A configuration object for fine-grained control over the connection, including protocol, host, port, and SSL/TLS settings.

Use ProxyTargetDetailed when you need to specify specific SSL certificates (cert, key, ca), ciphers, or socket paths for Unix domain sockets.

// Example using a string
const target: ProxyTarget = 'https://api.example.com';

// Example using ProxyTargetDetailed for SSL
const detailedTarget: ProxyTarget = {
  protocol: 'https',
  host: 'api.example.com',
  port: 443,
  cert: 'path/to/cert.pem',
  key: 'path/to/key.pem'
};

You can intercept a request before it is sent to the target by listening to the proxyReq event on the ProxyServer instance. This allows you to inject custom headers into the outgoing request.

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

const proxy = createProxyServer({ target: "http://localhost:8080" });

proxy.on("proxyReq", (proxyReq) => {
  proxyReq.setHeader("X-Forwarded-By", "httpxy");
});

const server = createServer(async (req, res) => {
  await proxy.web(req, res);
});

server.listen(3000);

If you don't need to integrate with an existing HTTP server, you can use proxy.listen() to start a standalone proxy server directly.

import { createProxyServer } from "httpxy";

const proxy = createProxyServer({
  target: "http://localhost:8080",
  changeOrigin: true,
});

proxy.listen(3000);

To run a proxy server over HTTPS, pass an ssl object containing your key and cert to the createProxyServer options. You can also use the secure option to allow self-signed certificates.

import { readFileSync } from "node:fs";
import { createProxyServer } from "httpxy";

const proxy = createProxyServer({
  ssl: {
    key: readFileSync("server-key.pem", "utf8"),
    cert: readFileSync("server-cert.pem", "utf8"),
  },
  target: "https://localhost:8443",
  secure: false, // allow self-signed certificates
});

proxy.listen(3000);

Use createProxyServer to create a managed proxy instance. You can then use the .web() method to proxy standard HTTP requests to a target address. This is useful when integrating proxying logic into an existing Node.js HTTP server.

Example of integrating with a custom server:

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

const proxy = createProxyServer({});

const server = createServer(async (req, res) => {
  try {
    await proxy.web(req, res, {
      target: "http://127.0.0.1:8080", // target address
    });
  } catch (error) {
    console.error(error);
    res.statusCode = 500;
    res.end("Proxy error: " + error.toString());
  }
});

server.listen(3000);

proxyUpgrade is a standalone WebSocket upgrade proxy. It allows you to forward upgrade requests to a target server without needing a full ProxyServer instance. It returns a Promise<Socket> that resolves with the upstream proxy socket once the connection is established.

It accepts the same address formats as proxyFetch ("http://host:port", "unix:/path", or { host, port } / { socketPath }).

import { createServer } from "node:http";
import { proxyUpgrade } from "httpxy";

const server = createServer((req, res) => {
  // Handle regular HTTP requests...
});

server.on("upgrade", (req, socket, head) => {
  proxyUpgrade("http://127.0.0.1:8080", req, socket, head);
});

server.listen(3000);

The XHeaders middleware within the WebSocket stack automatically populates x-forwarded-* headers if the xfwd option is enabled in your configuration. It sets the following headers based on the incoming connection:

• x-forwarded-for: The remote address of the client.
• x-forwarded-port: The port of the incoming request.
• x-forwarded-proto: The protocol (ws or wss) based on whether the connection is encrypted.

These headers are only added if they do not already exist in the request.