feat: upgrade to undici@8

.github/workflows/nodejs.yml

@@ -41,7 +41,7 @@ jobs:
       fail-fast: false
       matrix:
         os: ['ubuntu-latest', 'macos-latest', 'windows-latest']
-        node: ['22', '24', '25']
+        node: ['22', '24', '26']
 
     name: Test (${{ matrix.os }}, ${{ matrix.node }})
     runs-on: ${{ matrix.os }}

codecov.yml

@@ -0,0 +1,14 @@
+# Patch coverage stays strict (new/changed lines must be covered).
+# Project coverage tolerates small fluctuations from external-network tests
+# and undici behaviour changes (e.g. an error branch reachable only on a
+# different protocol path).
+coverage:
+  status:
+    project:
+      default:
+        target: auto
+        threshold: 1%
+    patch:
+      default:
+        target: auto
+        threshold: 0%

package.json

@@ -75,7 +75,7 @@
     "mime-types": "^2.1.35",
     "qs": "^6.15.0",
     "type-fest": "^4.41.0",
-    "undici": "^7.24.0",
+    "undici": "^8.4.1",
     "ylru": "^2.0.0"
   },
   "devDependencies": {
@@ -110,7 +110,7 @@
     }
   },
   "engines": {
-    "node": ">= 22.0.0"
+    "node": ">= 22.19.0"
   },
   "packageManager": "pnpm@11.6.0"
 }

src/HttpClient.ts

@@ -74,7 +74,7 @@ const debug = debuglog('urllib:HttpClient');
 
 export type ClientOptions = {
   defaultArgs?: RequestOptions;
-  /** Allow to use HTTP2 first. Default is `false` */
+  /** Negotiate HTTP/2 with capable servers via ALPN. Enabled by default since undici@8; set `false` to force HTTP/1.1. */
   allowH2?: boolean;
   /** Custom DNS lookup function, default is `dns.lookup`. */
   lookup?: LookupFunction;
@@ -205,8 +205,9 @@ export class HttpClient extends EventEmitter {
         connect: clientOptions.connect,
         allowH2: clientOptions.allowH2,
       });
-    } else if (clientOptions?.allowH2) {
-      // Support HTTP2
+    } else if (clientOptions?.allowH2 !== undefined) {
+      // Pin the protocol when allowH2 is set explicitly: `true` enables HTTP/2,
+      // `false` forces HTTP/1.1 instead of following undici@8's HTTP/2 default.
       this.#dispatcher = new Agent({
         allowH2: clientOptions.allowH2,
       });

src/Request.ts

@@ -14,7 +14,7 @@ export type RequestURL = string | URL;
 export type FixJSONCtlCharsHandler = (data: string) => string;
 export type FixJSONCtlChars = boolean | FixJSONCtlCharsHandler;
 
-type AbortSignal = unknown;
+type AbortSignal = globalThis.AbortSignal;
 
 export type RequestOptions = {
   /** Request method, defaults to GET. Could be GET, POST, DELETE or PUT. Alias 'type'. */

src/index.ts

@@ -6,13 +6,15 @@ import type { HttpClientResponse } from './Response.js';
 
 let httpClient: HttpClient;
 let allowH2HttpClient: HttpClient;
+let disallowH2HttpClient: HttpClient;
 let allowUnauthorizedHttpClient: HttpClient;
 let allowH2AndUnauthorizedHttpClient: HttpClient;
+let disallowH2AndUnauthorizedHttpClient: HttpClient;
 const domainSocketHttpClients = new LRU(50);
 
 export function getDefaultHttpClient(rejectUnauthorized?: boolean, allowH2?: boolean): HttpClient {
   if (rejectUnauthorized === false) {
-    if (allowH2) {
+    if (allowH2 === true) {
       if (!allowH2AndUnauthorizedHttpClient) {
         allowH2AndUnauthorizedHttpClient = new HttpClient({
           allowH2,
@@ -24,6 +26,18 @@ export function getDefaultHttpClient(rejectUnauthorized?: boolean, allowH2?: boo
       return allowH2AndUnauthorizedHttpClient;
     }
 
+    if (allowH2 === false) {
+      if (!disallowH2AndUnauthorizedHttpClient) {
+        disallowH2AndUnauthorizedHttpClient = new HttpClient({
+          allowH2,
+          connect: {
+            rejectUnauthorized,
+          },
+        });
+      }
+      return disallowH2AndUnauthorizedHttpClient;
+    }
+
     if (!allowUnauthorizedHttpClient) {
       allowUnauthorizedHttpClient = new HttpClient({
         connect: {
@@ -34,7 +48,7 @@ export function getDefaultHttpClient(rejectUnauthorized?: boolean, allowH2?: boo
     return allowUnauthorizedHttpClient;
   }
 
-  if (allowH2) {
+  if (allowH2 === true) {
     if (!allowH2HttpClient) {
       allowH2HttpClient = new HttpClient({
         allowH2,
@@ -43,6 +57,15 @@ export function getDefaultHttpClient(rejectUnauthorized?: boolean, allowH2?: boo
     return allowH2HttpClient;
   }
 
+  if (allowH2 === false) {
+    if (!disallowH2HttpClient) {
+      disallowH2HttpClient = new HttpClient({
+        allowH2,
+      });
+    }
+    return disallowH2HttpClient;
+  }
+
   if (!httpClient) {
     httpClient = new HttpClient();
   }
@@ -55,7 +78,7 @@ interface UrllibRequestOptions extends RequestOptions {
    * verification fails. Default: `true`
    */
   rejectUnauthorized?: boolean;
-  /** Allow to use HTTP2 first. Default is `false` */
+  /** Negotiate HTTP/2 with capable servers via ALPN. Enabled by default since undici@8; set `false` to force HTTP/1.1. */
   allowH2?: boolean;
 }
 

test/HttpClient.test.ts

@@ -2,14 +2,15 @@ import { strict as assert } from 'node:assert';
 import dns from 'node:dns';
 import { once } from 'node:events';
 import { sensitiveHeaders, createSecureServer } from 'node:http2';
+import { createServer as createSecureHttp1Server } from 'node:https';
 import type { AddressInfo } from 'node:net';
 import { PerformanceObserver } from 'node:perf_hooks';
 import { setTimeout as sleep } from 'node:timers/promises';
 
 import selfsigned from 'selfsigned';
 import { describe, it, beforeAll, afterAll } from 'vite-plus/test';
 
-import { HttpClient, getGlobalDispatcher } from '../src/index.js';
+import { HttpClient, getDefaultHttpClient, getGlobalDispatcher } from '../src/index.js';
 import type { RawResponseWithMeta } from '../src/index.js';
 import { startServer } from './fixtures/server.js';
 
@@ -121,7 +122,9 @@ describe('HttpClient.test.ts', () => {
         httpClient.request(_url),
       ]);
       // console.log(httpClient.getDispatcherPoolStats());
-      assert.equal(httpClient.getDispatcherPoolStats()['https://registry.npmmirror.com'].connected, 4);
+      // undici@8 negotiates HTTP/2 with h2-capable servers, so all requests are
+      // multiplexed over a single connection instead of opening one per request.
+      assert.equal(httpClient.getDispatcherPoolStats()['https://registry.npmmirror.com'].connected, 1);
       assert(httpClient.getDispatcherPoolStats()[_url.substring(0, _url.length - 1)].connected > 1);
     });
 
@@ -247,6 +250,105 @@ describe('HttpClient.test.ts', () => {
     });
   });
 
+  describe('protocol negotiation', () => {
+    it('should use HTTP/1.1 when the server only supports HTTP/1.1', async () => {
+      const server = createSecureHttp1Server(
+        {
+          key: pems.private,
+          cert: pems.cert,
+        },
+        (req, res) => {
+          res.writeHead(200, { 'content-type': 'text/plain; charset=utf-8' });
+          res.end(`hello http/${req.httpVersion}!`);
+        },
+      );
+      server.listen(0);
+      await once(server, 'listening');
+      const url = `https://localhost:${(server.address() as AddressInfo).port}`;
+
+      const httpClient = new HttpClient({
+        connect: { rejectUnauthorized: false },
+      });
+      try {
+        const response = await httpClient.request<string>(url, { dataType: 'text' });
+        assert.equal(response.status, 200);
+        assert.equal(response.data, 'hello http/1.1!');
+      } finally {
+        await httpClient.getDispatcher().close();
+        await new Promise<void>((resolve) => server.close(() => resolve()));
+      }
+    });
+
+    it('should negotiate HTTP/2 by default when the server supports it', async () => {
+      // undici@8 enables allowH2 by default, so urllib negotiates HTTP/2 via ALPN.
+      const server = createSecureServer({
+        allowHTTP1: true,
+        key: pems.private,
+        cert: pems.cert,
+      });
+      server.on('request', (req, res) => {
+        res.writeHead(200, { 'content-type': 'text/plain; charset=utf-8' });
+        res.end(`hello http/${req.httpVersion}!`);
+      });
+      server.listen(0);
+      await once(server, 'listening');
+      const url = `https://localhost:${(server.address() as AddressInfo).port}`;
+
+      const httpClient = new HttpClient({
+        connect: { rejectUnauthorized: false },
+      });
+      try {
+        const response = await httpClient.request<string>(url, { dataType: 'text' });
+        assert.equal(response.status, 200);
+        assert.equal(response.data, 'hello http/2.0!');
+      } finally {
+        await httpClient.getDispatcher().close();
+        await new Promise<void>((resolve) => server.close(() => resolve()));
+      }
+    });
+
+    it('should force HTTP/1.1 with allowH2 = false even if the server supports HTTP/2', async () => {
+      const server = createSecureServer({
+        allowHTTP1: true,
+        key: pems.private,
+        cert: pems.cert,
+      });
+      server.on('request', (req, res) => {
+        res.writeHead(200, { 'content-type': 'text/plain; charset=utf-8' });
+        res.end(`hello http/${req.httpVersion}!`);
+      });
+      server.listen(0);
+      await once(server, 'listening');
+      const url = `https://localhost:${(server.address() as AddressInfo).port}`;
+
+      const httpClient = new HttpClient({
+        allowH2: false,
+        connect: { rejectUnauthorized: false },
+      });
+      try {
+        const response = await httpClient.request<string>(url, { dataType: 'text' });
+        assert.equal(response.status, 200);
+        assert.equal(response.data, 'hello http/1.1!');
+      } finally {
+        await httpClient.getDispatcher().close();
+        await new Promise<void>((resolve) => server.close(() => resolve()));
+      }
+    });
+
+    it('should pin a dedicated dispatcher when allowH2 is set explicitly', () => {
+      // allowH2: false must not fall back to undici@8's HTTP/2-enabled global dispatcher
+      assert.notEqual(new HttpClient({ allowH2: false }).getDispatcher(), getGlobalDispatcher());
+      assert.notEqual(new HttpClient({ allowH2: true }).getDispatcher(), getGlobalDispatcher());
+    });
+
+    it('should cache distinct default clients per allowH2 value', () => {
+      assert.equal(getDefaultHttpClient(undefined, false), getDefaultHttpClient(undefined, false));
+      assert.notEqual(getDefaultHttpClient(undefined, false), getDefaultHttpClient(undefined, true));
+      assert.notEqual(getDefaultHttpClient(undefined, false), getDefaultHttpClient(undefined, undefined));
+      assert.notEqual(getDefaultHttpClient(false, false), getDefaultHttpClient(false, true));
+    });
+  });
+
   describe('clientOptions.defaultArgs', () => {
     it('should work with custom defaultArgs', async () => {
       const httpclient = new HttpClient({ defaultArgs: { timeout: 1000 } });