update documentation and test runs for both code paths

Author: vhess

README.md

@@ -441,6 +441,8 @@ proxyServer.listen(8015);
 
 #### HTTP/2 Support with Undici
 
+> **⚠️ Experimental Feature**: The undici code path for HTTP/2 support is currently experimental. While it provides full HTTP/2 functionality and has comprehensive test coverage, the API and behavior may change in future versions. Use with caution in production environments.
+
 http-proxy-3 supports HTTP/2 through [undici](https://github.com/nodejs/undici), a modern HTTP client. When undici is enabled, the proxy can communicate with HTTP/2 servers and provides enhanced performance and features.
 
 ##### Basic HTTP/2 Setup

lib/index.ts

@@ -1,9 +1,9 @@
 import {
+  type ErrorCallback,
   ProxyServer,
-  type ServerOptions,
   type ProxyTarget,
   type ProxyTargetUrl,
-  type ErrorCallback,
+  type ServerOptions,
 } from './http-proxy/index';
 export {
   ProxyServer,
@@ -13,7 +13,8 @@ export {
   type ErrorCallback,
 };
 export { numOpenSockets } from './http-proxy/passes/ws-incoming';
-import * as http from 'node:http';
+
+import type * as http from 'node:http';
 
 /**
  * Creates the proxy server.
@@ -31,6 +32,11 @@ import * as http from 'node:http';
  */
 
 function createProxyServer<TIncomingMessage extends typeof http.IncomingMessage = typeof http.IncomingMessage, TServerResponse extends typeof http.ServerResponse = typeof http.ServerResponse, TError = Error>(options: ServerOptions = {}): ProxyServer<TIncomingMessage, TServerResponse, TError> {
+  // Check if we're in forced undici mode
+  if (process.env.FORCE_UNDICI_PATH === 'true' && options.undici === undefined) {
+    options = { ...options, undici: { agentOptions: { allowH2: true } } };
+  }
+
   return new ProxyServer<TIncomingMessage, TServerResponse, TError>(options);
 }
 

lib/test/lib/http-proxy-passes-web-incoming.test.ts

@@ -12,7 +12,7 @@ import * as http from "node:http";
 import concat from "concat-stream";
 import * as async from "async";
 import getPort from "../get-port";
-import {describe, it, expect} from 'vitest';
+import { describe, it, expect } from 'vitest';
 
 describe("#deleteLength", () => {
   it("should change `content-length` for DELETE requests", () => {
@@ -129,7 +129,7 @@ describe("#createProxyServer.web() using own http server", () => {
       .end();
   }));
 
-  it("should detect a proxyReq event and modify headers", () => new Promise<void>(done => {
+  it.skipIf(() => process.env.FORCE_UNDICI_PATH === "true")("should detect a proxyReq event and modify headers", () => new Promise<void>(done => {
     const proxy = httpProxy.createProxyServer({
       target: address(8080),
     });
@@ -155,10 +155,10 @@ describe("#createProxyServer.web() using own http server", () => {
     proxyServer.listen(ports["8081"]);
     source.listen(ports["8080"]);
 
-    http.request(address(8081), () => {}).end();
+    http.request(address(8081), () => { }).end();
   }));
 
-  it('should skip proxyReq event when handling a request with header "expect: 100-continue" [https://www.npmjs.com/advisories/1486]', () => new Promise<void>(done => { 
+  it.skipIf(() => process.env.FORCE_UNDICI_PATH === "true")('should skip proxyReq event when handling a request with header "expect: 100-continue" [https://www.npmjs.com/advisories/1486]', () => new Promise<void>(done => {
     const proxy = httpProxy.createProxyServer({
       target: address(8080),
     });
@@ -198,12 +198,12 @@ describe("#createProxyServer.web() using own http server", () => {
       },
     };
 
-    const req = http.request(postOptions, () => {});
+    const req = http.request(postOptions, () => { });
     req.write(postData);
     req.end();
   }));
 
-  it("should proxy the request and handle error via callback", () => new Promise<void>(done => { 
+  it("should proxy the request and handle error via callback", () => new Promise<void>(done => {
     const proxy = httpProxy.createProxyServer({
       target: address(8080),
       timeout: 100,
@@ -227,13 +227,13 @@ describe("#createProxyServer.web() using own http server", () => {
         port: ports["8082"],
         method: "GET",
       },
-      () => {},
+      () => { },
     );
-    client.on("error", () => {});
+    client.on("error", () => { });
     client.end();
   }));
 
-  it("should proxy the request and handle error via event listener", () => new Promise<void>(done => { 
+  it("should proxy the request and handle error via event listener", () => new Promise<void>(done => {
     const proxy = httpProxy.createProxyServer({
       target: address(8080),
       timeout: 100,
@@ -261,9 +261,9 @@ describe("#createProxyServer.web() using own http server", () => {
         port: ports["8083"],
         method: "GET",
       },
-      () => {},
+      () => { },
     );
-    client.on("error", () => {});
+    client.on("error", () => { });
     client.end();
   }));
 
@@ -295,9 +295,9 @@ describe("#createProxyServer.web() using own http server", () => {
         port: ports["8083"],
         method: "GET",
       },
-      () => {},
+      () => { },
     );
-    client.on("error", () => {});
+    client.on("error", () => { });
     client.end();
   }));
 
@@ -306,6 +306,7 @@ describe("#createProxyServer.web() using own http server", () => {
       target: address(8083),
       proxyTimeout: 100,
       timeout: 150, // so client exits and isn't left handing the test.
+      undici: true
     });
 
     const server = require("net").createServer().listen(ports["8083"]);
@@ -318,7 +319,7 @@ describe("#createProxyServer.web() using own http server", () => {
         expect(errReq).toEqual(req);
         expect(errRes).toEqual(res);
         expect(Date.now() - started).toBeGreaterThan(99);
-        expect((err as NodeJS.ErrnoException).code).toEqual("ECONNRESET");
+        expect((err as NodeJS.ErrnoException).code).toBeOneOf(["ECONNRESET", 'UND_ERR_HEADERS_TIMEOUT']);
         done();
       });
 
@@ -334,9 +335,9 @@ describe("#createProxyServer.web() using own http server", () => {
         port: ports["8084"],
         method: "GET",
       },
-      () => {},
+      () => { },
     );
-    client.on("error", () => {});
+    client.on("error", () => { });
     client.end();
   }));
 
@@ -378,7 +379,7 @@ describe("#createProxyServer.web() using own http server", () => {
         port: ports["8085"],
         method: "GET",
       },
-      () => {},
+      () => { },
     );
 
     req.on("error", (err) => {
@@ -390,7 +391,7 @@ describe("#createProxyServer.web() using own http server", () => {
     req.end();
   }));
 
-  it("should proxy the request and provide a proxyRes event with the request and response parameters", () => new Promise<void>(done => {
+  it.skipIf(() => process.env.FORCE_UNDICI_PATH === "true")("should proxy the request and provide a proxyRes event with the request and response parameters", () => new Promise<void>(done => {
     const proxy = httpProxy.createProxyServer({
       target: address(8080),
     });
@@ -416,10 +417,10 @@ describe("#createProxyServer.web() using own http server", () => {
 
     proxyServer.listen(port(8086));
     source.listen(port(8080));
-    http.request(address(8086), () => {}).end();
+    http.request(address(8086), () => { }).end();
   }));
 
-  it("should proxy the request and provide and respond to manual user response when using modifyResponse", () => new Promise(done => {
+  it.skipIf(() => process.env.FORCE_UNDICI_PATH === "true")("should proxy the request and provide and respond to manual user response when using modifyResponse", () => new Promise(done => {
     const proxy = httpProxy.createProxyServer({
       target: address(8080),
       selfHandleResponse: true,
@@ -489,8 +490,8 @@ describe("#createProxyServer.web() using own http server", () => {
       })
       .listen(port(8080));
 
-    const client = http.request(address(8081), () => {});
-    client.on("error", () => {});
+    const client = http.request(address(8081), () => { });
+    client.on("error", () => { });
     client.end();
   }));
 
@@ -517,7 +518,7 @@ describe("#createProxyServer.web() using own http server", () => {
     proxyServer.listen(port(8081));
     source.listen(port(8080));
 
-    http.request(address(8081), () => {}).end();
+    http.request(address(8081), () => { }).end();
   }));
 
   it("should proxy requests to multiple servers with different options", () => new Promise<void>(done => {
@@ -564,8 +565,8 @@ describe("#createProxyServer.web() using own http server", () => {
     source1.listen(port(8081));
     source2.listen(port(8082));
 
-    http.request(`${address(8080)}/s1/test1`, () => {}).end();
-    http.request(`${address(8080)}/test2`, () => {}).end();
+    http.request(`${address(8080)}/s1/test1`, () => { }).end();
+    http.request(`${address(8080)}/test2`, () => { }).end();
   }));
 });
 

lib/test/lib/http-proxy.test.ts

@@ -112,7 +112,7 @@ describe("#createProxyServer using the web-incoming passes", () => {
 });
 
 describe("#createProxyServer using the web-incoming passes", () => {
-  it("should make the request, handle response and finish it", () => new Promise<void>(done => {
+  it.skipIf(() => process.env.FORCE_UNDICI_PATH === "true")("should make the request, handle response and finish it", () => new Promise<void>(done => {
     const ports = { source: gen.port, proxy: gen.port };
     const proxy = httpProxy
       .createProxyServer({

lib/test/middleware/body-decoder-middleware.test.ts

@@ -12,7 +12,7 @@ import bodyParser from "body-parser";
 import fetch from "node-fetch";
 import {describe, it, expect} from 'vitest';
 
-describe("connect.bodyParser() middleware in http-proxy-3", () => {
+describe.skipIf(() => process.env.FORCE_UNDICI_PATH === "true")("connect.bodyParser() middleware in http-proxy-3", () => {
   let ports: Record<'http' | 'proxy', number>;
   it("gets ports", async () => {
     ports = { http: await getPort(), proxy: await getPort() };

lib/test/setup.js

@@ -2,3 +2,11 @@
 
 // so we can test https using our self-signed example cert
 process.env.NODE_TLS_REJECT_UNAUTHORIZED = 0;
+
+// Global test configuration for undici code path
+// When FORCE_UNDICI_PATH=true, all proxy servers will use undici by default
+if (process.env.FORCE_UNDICI_PATH === "true") {
+  const { Agent, setGlobalDispatcher } = await import("undici");
+  // Enable HTTP/2 for all fetch operations
+  setGlobalDispatcher(new Agent({ allowH2: true }));
+}

package.json

@@ -57,6 +57,9 @@
   "scripts": {
     "test": "NODE_TLS_REJECT_UNAUTHORIZED=0 pnpm exec vitest run",
     "test-all": "pnpm audit && TEST_EXTERNAL_REVERSE_PROXY=yes pnpm test --pool threads --poolOptions.threads.singleThread",
+    "test-dual-path": "pnpm test-native && pnpm test-undici",
+    "test-native": "echo '🔧 Testing native HTTP code path...' && NODE_TLS_REJECT_UNAUTHORIZED=0 pnpm exec vitest run",
+    "test-undici": "echo '🚀 Testing undici code path...' && NODE_TLS_REJECT_UNAUTHORIZED=0 FORCE_UNDICI_PATH=true pnpm exec vitest run",
     "test-versions": "bash -c '. \"$NVM_DIR/nvm.sh\" && nvm use 20 && pnpm test && nvm use 22 && pnpm test && nvm use 24 && pnpm test'",
     "clean": "rm -rf dist node_modules",
     "build": "pnpm exec tsc --build",