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/HttpAgent.ts

@@ -66,7 +66,10 @@ export class HttpAgent extends BaseAgent {
     };
     super({
       ...baseOpts,
-      connect: { ...options.connect, lookup: lookupFunction, allowH2: options.allowH2 },
+      // Keep allowH2 at the top level only. undici builds the connector as
+      // `buildConnector({ allowH2, ...connect })`, so an allowH2 inside `connect`
+      // would shadow the top-level/per-request value and defeat `allowH2: false`.
+      connect: { ...options.connect, lookup: lookupFunction },
     });
     this.#checkAddress = options.checkAddress;
   }

src/HttpClient.ts

@@ -18,7 +18,7 @@ import { createGunzip, createBrotliDecompress, gunzipSync, brotliDecompressSync
 import FormStream from 'formstream';
 import mime from 'mime-types';
 import qs from 'qs';
-import { request as undiciRequest, Dispatcher, Agent, getGlobalDispatcher, Pool } from 'undici';
+import { request as undiciRequest, Dispatcher, Agent, getGlobalDispatcher, MockAgent, Pool } from 'undici';
 // eslint-disable-next-line @typescript-eslint/ban-ts-comment
 // @ts-ignore
 import undiciSymbols from 'undici/lib/core/symbols.js';
@@ -38,7 +38,11 @@ import { parseJSON, digestAuthHeader, globalId, performanceTime, isReadable, upd
 type Exists<T> = T extends undefined ? never : T;
 type UndiciRequestOption = Exists<Parameters<typeof undiciRequest>[1]>;
 type PropertyShouldBe<T, K extends keyof T, V> = Omit<T, K> & { [P in K]: V };
-type IUndiciRequestOption = PropertyShouldBe<UndiciRequestOption, 'headers', IncomingHttpHeaders>;
+// undici reads `allowH2` per dispatch (Agent picks an http1-only pool when false),
+// but it is not part of the public request options type, so add it explicitly.
+type IUndiciRequestOption = PropertyShouldBe<UndiciRequestOption, 'headers', IncomingHttpHeaders> & {
+  allowH2?: boolean;
+};
 
 export const PROTO_RE: RegExp = /^https?:\/\//i;
 
@@ -74,7 +78,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;
@@ -171,6 +175,32 @@ export interface PoolStat {
   size: number;
 }
 
+// undici@8 keys http1-only pools (allowH2: false) as `${origin}#http1-only`;
+// expose them under their plain origin so callers can look up stats by URL.
+// MockAgent may use RegExp/function origin matchers, so keys are not always strings.
+export function normalizePoolStatsKey(key: unknown): string {
+  if (typeof key !== 'string') {
+    return String(key);
+  }
+  const index = key.indexOf('#http1-only');
+  return index === -1 ? key : key.slice(0, index);
+}
+
+// When both an HTTP/2 and an http1-only pool exist for the same origin, sum
+// their stats so a single origin entry reflects every client. undici ClientStats
+// (Agent with connections: 1) omit free/queued, so treat absent counters as 0.
+export function mergePoolStat(existing: PoolStat | undefined, stats: Partial<PoolStat>): PoolStat {
+  const base = existing ?? { connected: 0, free: 0, pending: 0, queued: 0, running: 0, size: 0 };
+  return {
+    connected: base.connected + (stats.connected ?? 0),
+    free: base.free + (stats.free ?? 0),
+    pending: base.pending + (stats.pending ?? 0),
+    queued: base.queued + (stats.queued ?? 0),
+    running: base.running + (stats.running ?? 0),
+    size: base.size + (stats.size ?? 0),
+  };
+}
+
 // https://developer.mozilla.org/en-US/docs/Web/HTTP/Redirections
 const RedirectStatusCodes = [
   301, // Moved Permanently
@@ -189,10 +219,14 @@ const CrossOriginSensitiveHeaders = new Set(['authorization', 'cookie', 'proxy-a
 export class HttpClient extends EventEmitter {
   #defaultArgs?: RequestOptions;
   #dispatcher?: Dispatcher;
+  #allowH2?: boolean;
 
   constructor(clientOptions?: ClientOptions) {
     super();
     this.#defaultArgs = clientOptions?.defaultArgs;
+    // Remember the client-level protocol preference so it can be applied per
+    // request (mainly for `allowH2: false`, which has no dedicated agent).
+    this.#allowH2 = clientOptions?.allowH2;
     if (clientOptions?.lookup || clientOptions?.checkAddress) {
       this.#dispatcher = new HttpAgent({
         lookup: clientOptions.lookup,
@@ -206,7 +240,8 @@ export class HttpClient extends EventEmitter {
         allowH2: clientOptions.allowH2,
       });
     } else if (clientOptions?.allowH2) {
-      // Support HTTP2
+      // Support HTTP/2 with a dedicated agent. `allowH2: false` is handled
+      // per request instead, so it does not bypass the active dispatcher.
       this.#dispatcher = new Agent({
         allowH2: clientOptions.allowH2,
       });
@@ -236,14 +271,10 @@ export class HttpClient extends EventEmitter {
       const stats = pool?.stats ?? pool?.dispatcher?.stats;
       if (!stats) continue;
 
-      poolStatsMap[key] = {
-        connected: stats.connected,
-        free: stats.free,
-        pending: stats.pending,
-        queued: stats.queued,
-        running: stats.running,
-        size: stats.size,
-      } satisfies PoolStat;
+      // undici@8 keys http1-only pools (allowH2: false) as `${origin}#http1-only`,
+      // expose them by their origin so callers can look up stats by URL.
+      const origin = normalizePoolStatsKey(key);
+      poolStatsMap[origin] = mergePoolStat(poolStatsMap[origin], stats);
     }
     return poolStatsMap;
   }
@@ -441,6 +472,18 @@ export class HttpClient extends EventEmitter {
         signal: args.signal,
         reset: false,
       };
+      const allowH2 = args.allowH2 ?? this.#allowH2;
+      if (typeof allowH2 === 'boolean') {
+        // Apply the protocol preference per request so the active dispatcher
+        // (global, proxy, ...) is honored instead of being bypassed by a
+        // dedicated HTTP/1.1-only agent. Skip it for MockAgent: it keys clients
+        // as `${origin}#http1-only` and would miss interceptors registered on
+        // the plain origin (protocol negotiation is moot when mocking anyway).
+        const activeDispatcher = requestOptions.dispatcher ?? getGlobalDispatcher();
+        if (!(activeDispatcher instanceof MockAgent)) {
+          requestOptions.allowH2 = allowH2;
+        }
+      }
       if (typeof args.highWaterMark === 'number') {
         requestOptions.highWaterMark = args.highWaterMark;
       }

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'. */
@@ -141,6 +141,11 @@ export type RequestOptions = {
   ctx?: unknown;
   /** Request dispatcher, default is getGlobalDispatcher() */
   dispatcher?: Dispatcher;
+  /**
+   * Negotiate HTTP/2 with capable servers via ALPN. Enabled by default since undici@8; set `false` to force HTTP/1.1
+   * for this request without bypassing the active dispatcher.
+   */
+  allowH2?: boolean;
   /** Unix domain socket file path */
   socketPath?: string | null;
   /** Whether the request should stablish a keep-alive or not. Default `false`, try to keep alive by default */

src/fetch.ts

@@ -16,7 +16,7 @@ import { initDiagnosticsChannel } from './diagnosticsChannel.js';
 import type { FetchOpaque } from './FetchOpaqueInterceptor.js';
 import { HttpAgent } from './HttpAgent.js';
 import type { HttpAgentOptions } from './HttpAgent.js';
-import { channels } from './HttpClient.js';
+import { channels, mergePoolStat, normalizePoolStatsKey } from './HttpClient.js';
 import type {
   ClientOptions,
   PoolStat,
@@ -77,8 +77,9 @@ export class FetchFactory {
         allowH2: clientOptions.allowH2,
       } as HttpAgentOptions;
       dispatcherClazz = BaseAgent;
-    } 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.
       dispatcherOption = {
         ...dispatcherOption,
         allowH2: clientOptions.allowH2,
@@ -111,14 +112,10 @@ export class FetchFactory {
       const stats = pool?.stats ?? pool?.dispatcher?.stats;
       if (!stats) continue;
 
-      poolStatsMap[key] = {
-        connected: stats.connected,
-        free: stats.free,
-        pending: stats.pending,
-        queued: stats.queued,
-        running: stats.running,
-        size: stats.size,
-      } satisfies PoolStat;
+      // undici@8 keys http1-only pools (allowH2: false) as `${origin}#http1-only`,
+      // expose them by their origin so callers can look up stats by URL.
+      const origin = normalizePoolStatsKey(key);
+      poolStatsMap[origin] = mergePoolStat(poolStatsMap[origin], stats as PoolStat);
     }
     return poolStatsMap;
   }