feat: http/2 listener support

package.json

@@ -53,6 +53,7 @@
     "sse": "^0.0.8",
     "typescript": "^6.0.2",
     "unbuild": "^3.6.1",
+    "undici": "^7.24.6",
     "vitest": "^4.1.1",
     "ws": "^8.20.0"
   },

src/_utils.ts

@@ -1,8 +1,8 @@
 import httpNative from "node:http";
 import httpsNative from "node:https";
 import net from "node:net";
-import type tls from "node:tls";
 import type { ProxyAddr, ProxyServerOptions, ProxyTarget, ProxyTargetDetailed } from "./types.ts";
+import type { Http2ServerRequest } from "node:http2";
 
 const upgradeHeader = /(^|,)\s*upgrade\s*($|,)/i;
 
@@ -11,6 +11,15 @@ const upgradeHeader = /(^|,)\s*upgrade\s*($|,)/i;
  */
 export const isSSL = /^https|wss/;
 
+/**
+ * Node.js HTTP/2 accepts pseudo headers and it may conflict
+ * with request options.
+ *
+ * Let's just blacklist those potential conflicting pseudo
+ * headers.
+ */
+const HTTP2_HEADER_BLACKLIST = [":method", ":path", ":scheme", ":authority"];
+
 /**
  * Copies the right headers from `options` and `req` to
  * `outgoing` which is then used to fire the proxied
@@ -38,7 +47,7 @@ export function setupOutgoing(
     ca?: string;
     method?: string;
   },
-  req: httpNative.IncomingMessage,
+  req: httpNative.IncomingMessage | Http2ServerRequest,
   forward?: "forward" | "target",
 ): httpNative.RequestOptions | httpsNative.RequestOptions {
   outgoing.port =
@@ -64,10 +73,23 @@ export function setupOutgoing(
   outgoing.method = options.method || req.method;
   outgoing.headers = { ...req.headers };
 
+  // before clean up HTTP/2 blacklist header, we might wanna override host first
+  if (req.headers?.[":authority"]) {
+    outgoing.headers.host = req.headers[":authority"] as string;
+  }
+  // host override must happen before composing/merging the final outgoing headers
+
   if (options.headers) {
     outgoing.headers = { ...outgoing.headers, ...options.headers };
   }
 
+  if (req.httpVersionMajor > 1) {
+    // ignore potential conflicting HTTP/2 pseudo headers
+    for (const header of HTTP2_HEADER_BLACKLIST) {
+      delete outgoing.headers[header];
+    }
+  }
+
   if (options.auth) {
     outgoing.auth = options.auth;
   }
@@ -181,8 +203,9 @@ export function setupSocket(socket: net.Socket): net.Socket {
  *
  * @api private
  */
-export function getPort(req: httpNative.IncomingMessage): string {
-  const res = req.headers.host ? req.headers.host.match(/:(\d+)/) : "";
+export function getPort(req: httpNative.IncomingMessage | Http2ServerRequest): string {
+  const hostHeader = (req.headers[":authority"] as string | undefined) || req.headers.host;
+  const res = hostHeader ? hostHeader.match(/:(\d+)/) : "";
   if (res) {
     return res[1]!;
   }
@@ -198,11 +221,11 @@ export function getPort(req: httpNative.IncomingMessage): string {
  *
  * @api private
  */
-export function hasEncryptedConnection(req: httpNative.IncomingMessage): boolean {
-  return Boolean(
-    // req.connection.pair probably does not exist anymore
-    (req.connection as tls.TLSSocket).encrypted || (req.connection as any).pair,
-  );
+export function hasEncryptedConnection(
+  req: httpNative.IncomingMessage | Http2ServerRequest,
+): boolean {
+  const socket = req.socket;
+  return !!socket && "encrypted" in socket && socket.encrypted;
 }
 
 /**

src/middleware/_utils.ts

@@ -2,25 +2,26 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 import type { Socket } from "node:net";
 import type { ProxyServer } from "../server.ts";
 import type { ProxyServerOptions, ProxyTargetDetailed } from "../types.ts";
+import type { Http2ServerRequest, Http2ServerResponse } from "node:http2";
 
 export type ResOfType<T extends "web" | "ws"> = T extends "ws"
   ? T extends "web"
-    ? ServerResponse | Socket
+    ? ServerResponse | Http2ServerResponse | Socket
     : Socket
   : T extends "web"
-    ? ServerResponse
+    ? ServerResponse | Http2ServerResponse
     : never;
 
-export type ProxyMiddleware<T extends ServerResponse | Socket> = (
-  req: IncomingMessage,
+export type ProxyMiddleware<T extends ServerResponse | Http2ServerResponse | Socket> = (
+  req: IncomingMessage | Http2ServerRequest,
   res: T,
   opts: ProxyServerOptions & {
     target: URL | ProxyTargetDetailed;
     forward: URL;
   },
-  server: ProxyServer,
+  server: ProxyServer<IncomingMessage | Http2ServerRequest, ServerResponse | Http2ServerResponse>,
   head?: Buffer,
-  callback?: (err: any, req: IncomingMessage, socket: T, url?: any) => void,
+  callback?: (err: any, req: IncomingMessage | Http2ServerRequest, socket: T, url?: any) => void,
 ) => void | true;
 
 export function defineProxyMiddleware<T extends ServerResponse | Socket = ServerResponse>(
@@ -30,8 +31,8 @@ export function defineProxyMiddleware<T extends ServerResponse | Socket = Server
 }
 
 export type ProxyOutgoingMiddleware = (
-  req: IncomingMessage,
-  res: ServerResponse,
+  req: IncomingMessage | Http2ServerRequest,
+  res: ServerResponse | Http2ServerResponse,
   proxyRes: IncomingMessage,
   opts: ProxyServerOptions & {
     target: URL | ProxyTargetDetailed;

src/middleware/web-incoming.ts

@@ -52,7 +52,8 @@ export const XHeaders = defineProxyMiddleware((req, res, options) => {
       values[header];
   }
 
-  req.headers["x-forwarded-host"] = req.headers["x-forwarded-host"] || req.headers.host || "";
+  req.headers["x-forwarded-host"] =
+    req.headers["x-forwarded-host"] || req.headers[":authority"] || req.headers.host || "";
 });
 
 /**

src/middleware/web-outgoing.ts

@@ -4,23 +4,29 @@ import { type ProxyOutgoingMiddleware, defineProxyOutgoingMiddleware } from "./_
 const redirectRegex = /^201|30([1278])$/;
 
 /**
- * If is a HTTP 1.0 request, remove chunk headers
+ * Remove chunked transfer-encoding for HTTP/1.0 and HTTP/2 requests
  */
 export const removeChunked = defineProxyOutgoingMiddleware((req, res, proxyRes) => {
-  if (req.httpVersion === "1.0") {
+  // HTTP/1.0 and HTTP/2 do not have transfer-encoding: chunked
+  if (req.httpVersion === "1.0" || req.httpVersionMajor >= 2) {
     delete proxyRes.headers["transfer-encoding"];
   }
 });
 
 /**
  * If is a HTTP 1.0 request, set the correct connection header
  * or if connection header not present, then use `keep-alive`
+ *
+ * If is a HTTP/2 request, remove connection header no matter what,
+ * this avoids sending connection header to the underlying http2 client
  */
 export const setConnection = defineProxyOutgoingMiddleware((req, res, proxyRes) => {
   if (req.httpVersion === "1.0") {
     proxyRes.headers.connection = req.headers.connection || "close";
-  } else if (req.httpVersion !== "2.0" && !proxyRes.headers.connection) {
+  } else if (req.httpVersionMajor < 2 && !proxyRes.headers.connection) {
     proxyRes.headers.connection = req.headers.connection || "keep-alive";
+  } else if (req.httpVersionMajor >= 2) {
+    delete proxyRes.headers.connection;
   }
 });
 
@@ -42,8 +48,12 @@ export const setRedirectHostRewrite = defineProxyOutgoingMiddleware(
 
       if (options.hostRewrite) {
         u.host = options.hostRewrite;
-      } else if (options.autoRewrite && req.headers.host) {
-        u.host = req.headers.host;
+      } else if (options.autoRewrite) {
+        if (req.headers[":authority"]) {
+          u.host = req.headers[":authority"] as string;
+        } else if (req.headers.host) {
+          u.host = req.headers.host;
+        }
       }
       if (options.protocolRewrite) {
         u.protocol = options.protocolRewrite;
@@ -116,13 +126,16 @@ export const writeHeaders = defineProxyOutgoingMiddleware((req, res, proxyRes, o
  */
 export const writeStatusCode = defineProxyOutgoingMiddleware((req, res, proxyRes) => {
   // From Node.js docs: response.writeHead(statusCode[, statusMessage][, headers])
-  if (proxyRes.statusMessage) {
-    // @ts-expect-error
-    res.statusCode = proxyRes.statusCode;
+
+  // @ts-expect-error
+  res.statusCode = proxyRes.statusCode;
+
+  if (
+    proxyRes.statusMessage &&
+    // Only HTTP/1.0 and HTTP/1.1 support statusMessage
+    req.httpVersionMajor < 2
+  ) {
     res.statusMessage = proxyRes.statusMessage;
-  } else {
-    // @ts-expect-error
-    res.statusCode = proxyRes.statusCode;
   }
 });
 

src/server.ts

@@ -1,5 +1,6 @@
 import http from "node:http";
 import https from "node:https";
+import http2 from "node:http2";
 import { EventEmitter } from "node:events";
 import { webIncomingMiddleware } from "./middleware/web-incoming.ts";
 import { websocketIncomingMiddleware } from "./middleware/ws-incoming.ts";
@@ -8,8 +9,8 @@ import type { ProxyMiddleware, ResOfType } from "./middleware/_utils.ts";
 import type net from "node:net";
 
 export interface ProxyServerEventMap<
-  Req extends http.IncomingMessage = http.IncomingMessage,
-  Res extends http.ServerResponse = http.ServerResponse,
+  Req extends http.IncomingMessage | http2.Http2ServerRequest = http.IncomingMessage,
+  Res extends http.ServerResponse | http2.Http2ServerResponse = http.ServerResponse,
 > {
   error: [err: Error, req?: Req, res?: Res | net.Socket, target?: URL | ProxyTarget];
   start: [req: Req, res: Res, target: URL | ProxyTarget];
@@ -32,29 +33,20 @@ export interface ProxyServerEventMap<
 
 // eslint-disable-next-line unicorn/prefer-event-target
 export class ProxyServer<
-  Req extends http.IncomingMessage = http.IncomingMessage,
-  Res extends http.ServerResponse = http.ServerResponse,
+  Req extends http.IncomingMessage | http2.Http2ServerRequest = http.IncomingMessage,
+  Res extends http.ServerResponse | http2.Http2ServerResponse = http.ServerResponse,
 > extends EventEmitter<ProxyServerEventMap<Req, Res>> {
-  private _server?: http.Server | https.Server;
+  // we use http2.Http2Server to handle HTTP/1.1 HTTPS as well (with allowHTTP1 enabled)
+  private _server?: http.Server | https.Server | http2.Http2SecureServer;
 
   _webPasses: ProxyMiddleware<http.ServerResponse>[] = [...webIncomingMiddleware];
   _wsPasses: ProxyMiddleware<net.Socket>[] = [...websocketIncomingMiddleware];
 
   options: ProxyServerOptions;
 
-  web: (
-    req: http.IncomingMessage,
-    res: http.ServerResponse,
-    opts?: ProxyServerOptions,
-    head?: any,
-  ) => Promise<void>;
+  web: (req: Req, res: Res, opts?: ProxyServerOptions, head?: any) => Promise<void>;
 
-  ws: (
-    req: http.IncomingMessage,
-    socket: net.Socket,
-    opts: ProxyServerOptions,
-    head?: any,
-  ) => Promise<void>;
+  ws: (req: Req, socket: net.Socket, opts: ProxyServerOptions, head?: any) => Promise<void>;
 
   /**
    * Creates the proxy server with specified options.
@@ -76,18 +68,27 @@ export class ProxyServer<
    * @param hostname - The hostname to listen on
    */
   listen(port: number, hostname?: string) {
-    const closure = (req: http.IncomingMessage, res: http.ServerResponse) => {
-      this.web(req, res);
+    const closure = (
+      req: http.IncomingMessage | http2.Http2ServerRequest,
+      res: http.ServerResponse | http2.Http2ServerResponse,
+    ) => {
+      return this.web(req as Req, res as Res);
     };
 
-    this._server = this.options.ssl
-      ? https.createServer(this.options.ssl, closure)
-      : http.createServer(closure);
+    if (this.options.http2) {
+      if (!this.options.ssl) {
+        throw new Error("HTTP/2 requires ssl option");
+      }
+      this._server = http2.createSecureServer({ ...this.options.ssl, allowHTTP1: true }, closure);
+    } else if (this.options.ssl) {
+      this._server = https.createServer(this.options.ssl, closure);
+    } else {
+      this._server = http.createServer(closure);
+    }
 
     if (this.options.ws) {
       this._server.on("upgrade", (req, socket, head) => {
-        // @ts-expect-error
-        this.ws(req, socket, head).catch(() => {});
+        this.ws(req, socket, this.options, head).catch(() => {});
       });
     }
 
@@ -181,12 +182,15 @@ export function createProxyServer(options: ProxyServerOptions = {}) {
 
 // --- Internal ---
 
-function _createProxyFn<Type extends "web" | "ws">(type: Type, server: ProxyServer) {
-  type Res = ResOfType<Type>;
+function _createProxyFn<
+  Type extends "web" | "ws",
+  ProxyServerReq extends http.IncomingMessage | http2.Http2ServerRequest,
+  ProxyServerRes extends http.ServerResponse | http2.Http2ServerResponse,
+>(type: Type, server: ProxyServer<ProxyServerReq, ProxyServerRes>) {
   return function (
-    this: ProxyServer,
-    req: http.IncomingMessage,
-    res: Res,
+    this: ProxyServer<ProxyServerReq, ProxyServerRes>,
+    req: ProxyServerReq,
+    res: ResOfType<Type>,
     opts?: ProxyServerOptions,
     head?: any,
   ): Promise<void> {
@@ -222,11 +226,14 @@ function _createProxyFn<Type extends "web" | "ws">(type: Type, server: ProxyServ
         req,
         res,
         requestOptions as ProxyServerOptions & { target: URL; forward: URL },
-        server,
+        server as ProxyServer<
+          http.IncomingMessage | http2.Http2ServerRequest,
+          http.ServerResponse | http2.Http2ServerResponse
+        >,
         head,
         (error) => {
           if (server.listenerCount("error") > 0) {
-            server.emit("error", error, req, res);
+            server.emit("error", error, req, res as ProxyServerRes | net.Socket);
             _resolve();
           } else {
             _reject(error);

src/types.ts

@@ -29,7 +29,11 @@ export interface ProxyServerOptions {
   forward?: ProxyTarget;
   /** Object to be passed to http(s).request. */
   agent?: any;
-  /** Object to be passed to https.createServer(). */
+  /** Enable HTTP/2 listener, default is `false` */
+  http2?: boolean;
+  /** Object to be passed to https.createServer()
+   * or http2.createSecureServer() if the `http2` option is enabled
+   */
   ssl?: any;
   /** If you want to proxy websockets. */
   ws?: boolean;

test/_stubs.ts

@@ -22,7 +22,14 @@ export function createOutgoing(): OutgoingOptions {
 // --- IncomingMessage stubs ---
 
 export function stubIncomingMessage(overrides: Record<string, unknown> = {}): IncomingMessage {
-  return { method: "GET", url: "/", headers: {}, ...overrides } as unknown as IncomingMessage;
+  return {
+    method: "GET",
+    url: "/",
+    headers: {},
+    httpVersion: "1.1",
+    httpVersionMajor: 1,
+    ...overrides,
+  } as unknown as IncomingMessage;
 }
 
 // --- ServerResponse stub ---
@@ -50,6 +57,6 @@ export function stubMiddlewareOptions(overrides: Record<string, unknown> = {}):
 
 // --- ProxyServer stub ---
 
-export function stubProxyServer(overrides: Record<string, unknown> = {}): ProxyServer {
+export function stubProxyServer(overrides: Record<string, unknown> = {}): ProxyServer<any, any> {
   return overrides as unknown as ProxyServer;
 }