HTTP/2 & HTTP/1.1 Proxy for Node.js

Common errors

• TypeError: proxy.web is not a function

  cause This error often occurs when attempting to use CommonJS `require` to import the library, and then trying to access `web` as a named export directly from the module. The package's primary export is a default object containing `web` and `ws` methods, especially in an ESM context.
  fix When using ESM, use `import proxy from 'http2-proxy';`. When using CommonJS, if ESM default export is not properly handled, try `const { default: proxy } = require('http2-proxy');` or ensure your `require` statement assigns the default export to `proxy`.

• (node:XXXXX) UnhandledPromiseRejectionWarning: [error message]

  cause Proxy operations (especially `onReq` or `onRes` hooks) might involve asynchronous code that throws an error or returns a rejected promise, which is not caught or awaited, leading to an unhandled rejection.
  fix Ensure all asynchronous operations within `onReq`, `onRes`, or other custom handlers are properly awaited using `await` or handled with `.catch()` clauses. Additionally, confirm that your `defaultWebHandler` and `defaultWsHandler` are robustly catching and processing any errors passed to them by the proxy functions.

Warnings

• gotcha http2-proxy requires Node.js v10.0.0 or higher. Running on older Node.js versions may lead to unexpected behavior or runtime errors due to missing API features.
  Fix: Upgrade your Node.js environment to version 10.0.0 or newer.
• breaking The significant jump from v1.x to v5.x likely introduced breaking changes in the API and internal implementation. While specific changes are not detailed in the provided README excerpt, users upgrading from v1.x should review release notes for a comprehensive list of breaking changes.
  Fix: Consult the official GitHub repository's release notes or changelog for specific migration instructions when upgrading across major versions.
• gotcha Errored proxy responses are not automatically cleaned up. Users must implement explicit error handlers (like `finalhandler`) to prevent resource leaks and ensure proper client response, even for non-idempotent methods.
  Fix: Provide a callback function to `proxy.web` and `proxy.ws` that handles errors, typically using `finalhandler` or a custom error handling middleware, to gracefully close connections or send error responses.
• deprecated While callback-based API usage is still supported, it is officially discouraged in favor of async/await patterns. Relying heavily on callbacks may lead to less readable or harder-to-maintain code.
  Fix: Refactor your proxy implementation to leverage Node.js's async/await syntax for better error handling and control flow.

Install

• npm install http2-proxy npm
• yarn add http2-proxy yarn
• pnpm add http2-proxy pnpm

Imports

• proxy
  wrong:

  const proxy = require('http2-proxy')

  correct:

  import proxy from 'http2-proxy'

  Since v5.x, the package is primarily ESM-first. While CommonJS `require` might work for the default export, `import` is the recommended and safest approach for consistency across Node.js environments.
• proxy.web
  wrong:

  import { web } from 'http2-proxy'

  correct:

  import proxy from 'http2-proxy'; proxy.web(req, res, options, handler)

  `web` is a method of the default `proxy` export, not a direct named export from the package.
• proxy.ws
  wrong:

  import { ws } from 'http2-proxy'

  correct:

  import proxy from 'http2-proxy'; proxy.ws(req, socket, head, options, handler)

  `ws` is a method of the default `proxy` export, not a direct named export from the package.

Quickstart

This code sets up an HTTP/2 server that also accepts HTTP/1.1 connections. It then proxies both HTTP and WebSocket requests to a specified target hostname and port, demonstrating error handling and optional request/response modification.

import http2 from 'http2';
import proxy from 'http2-proxy';
import finalhandler from 'finalhandler';

const port = 8000;
const targetHostname = 'localhost';
const targetPort = 9001; // Ensure a backend server is running on this port for testing

const defaultWebHandler = (err, req, res) => {
  if (err) {
    console.error('HTTP proxy error:', err.message); // Log error message for clarity
    if (!res.headersSent) {
      finalhandler(req, res)(err);
    } else {
      // If headers already sent, just end the response to prevent further errors
      res.end();
    }
  }
};

const defaultWsHandler = (err, req, socket, head) => {
  if (err) {
    console.error('WebSocket proxy error:', err.message);
    socket.destroy();
  }
};

const server = http2.createServer({ allowHTTP1: true });

server.on('request', (req, res) => {
  proxy.web(req, res, {
    hostname: targetHostname,
    port: targetPort,
    // Optional: Add custom headers to the request sent to the target
    onReq: (proxyReq, options) => {
      options.headers['x-forwarded-for'] = req.socket.remoteAddress;
      options.headers['x-custom-proxy-header'] = 'http2-proxy-example';
    },
    // Optional: Modify the response from the target before sending to client
    onRes: (req, res, proxyRes) => {
      res.setHeader('x-proxied-by', 'http2-proxy');
      res.writeHead(proxyRes.statusCode, proxyRes.headers);
      proxyRes.pipe(res);
    }
  }, defaultWebHandler);
});

server.on('upgrade', (req, socket, head) => {
  proxy.ws(req, socket, head, {
    hostname: targetHostname,
    port: targetPort
  }, defaultWsHandler);
});

server.listen(port, () => {
  console.log(`Proxy server listening on port ${port}`);
  console.log(`Proxying HTTP and WebSocket requests to ${targetHostname}:${targetPort}`);
});