undici 8.0.1 → 8.0.3

package/docs/docs/api/Dispatcher.md

@@ -533,7 +533,7 @@ The `RequestOptions.method` property should not be value `'CONNECT'`.
 
 `body` contains the following additional extensions:
 
-- `dump({ limit: Integer })`, dump the response by reading up to `limit` bytes without killing the socket (optional) - Default: 262144.
+- `dump({ limit: Integer })`, dump the response by reading up to `limit` bytes without killing the socket (optional) - Default: 131072.
 
 Note that body will still be a `Readable` even if it is empty, but attempting to deserialize it with `json()` will result in an exception. Recommended way to ensure there is a body to deserialize is to check if status code is not 204, and `content-type` header starts with `application/json`.
 
@@ -1031,7 +1031,7 @@ const client = new Client("http://service.example").compose(
 The `dump` interceptor enables you to dump the response body from a request upon a given limit.
 
 **Options**
-- `maxSize` - The maximum size (in bytes) of the response body to dump. If the size of the request's body exceeds this value then the connection will be closed. Default: `1048576`.
+- `maxSize` - The maximum size (in bytes) of the response body to dump. If the size of the response's body exceeds this value then the connection will be closed. Default: `1048576`.
 
 > The `Dispatcher#options` also gets extended with the options `dumpMaxSize`, `abortOnDumped`, and `waitForTrailers` which can be used to configure the interceptor at a request-per-request basis.
 

package/docs/docs/best-practices/migrating-from-v7-to-v8.md

@@ -0,0 +1,231 @@
+# Migrating from Undici 7 to 8
+
+This guide covers the changes you are most likely to hit when upgrading an
+application or library from Undici v7 to v8.
+
+## Before you upgrade
+
+- Make sure your runtime is Node.js `>= 22.19.0`.
+- If you have custom dispatchers, interceptors, or handlers, review the
+  handler API changes before updating.
+- If you rely on HTTP/1.1-only behavior, plan to set `allowH2: false`
+  explicitly.
+
+## 1. Update your Node.js version
+
+Undici v8 requires Node.js `>= 22.19.0`.
+
+If you are still on Node.js 20 or an older Node.js 22 release, upgrade Node.js
+first:
+
+```bash
+node -v
+```
+
+If that command prints a version lower than `v22.19.0`, upgrade Node.js before
+installing Undici v8.
+
+## 2. Migrate custom dispatcher handlers to the v2 API
+
+Undici v8 uses the newer dispatcher handler API consistently.
+
+If you implemented custom dispatchers, interceptors, or wrappers around
+`dispatch()`, update legacy callbacks such as `onConnect`, `onHeaders`, and
+`onComplete` to the newer callback names.
+
+### Old handler callbacks vs. v8 callbacks
+
+| Undici 7 style | Undici 8 style |
+|---|---|
+| `onConnect(abort, context)` | `onRequestStart(controller, context)` |
+| `onHeaders(statusCode, rawHeaders, resume, statusText)` | `onResponseStart(controller, statusCode, headers, statusText)` |
+| `onData(chunk)` | `onResponseData(controller, chunk)` |
+| `onComplete(trailers)` | `onResponseEnd(controller, trailers)` |
+| `onError(err)` | `onResponseError(controller, err)` |
+| `onUpgrade(statusCode, rawHeaders, socket)` | `onRequestUpgrade(controller, statusCode, headers, socket)` |
+
+### Example
+
+Before:
+
+```js
+client.dispatch(options, {
+  onConnect (abort) {
+    this.abort = abort
+  },
+  onHeaders (statusCode, headers, resume) {
+    this.resume = resume
+    return true
+  },
+  onData (chunk) {
+    chunks.push(chunk)
+    return true
+  },
+  onComplete (trailers) {
+    console.log(trailers)
+  },
+  onError (err) {
+    console.error(err)
+  }
+})
+```
+
+After:
+
+```js
+client.dispatch(options, {
+  onRequestStart (controller) {
+    this.controller = controller
+  },
+  onResponseStart (controller, statusCode, headers, statusText) {
+    console.log(statusCode, statusText, headers)
+  },
+  onResponseData (controller, chunk) {
+    chunks.push(chunk)
+  },
+  onResponseEnd (controller, trailers) {
+    console.log(trailers)
+  },
+  onResponseError (controller, err) {
+    console.error(err)
+  }
+})
+```
+
+### Pause, resume, and abort now go through the controller
+
+In Undici v7, legacy handlers could return `false` or keep references to
+`abort()` and `resume()` callbacks. In Undici v8, use the controller instead:
+
+```js
+onRequestStart (controller) {
+  this.controller = controller
+}
+
+onResponseData (controller, chunk) {
+  controller.pause()
+  setImmediate(() => controller.resume())
+}
+
+onResponseError (controller, err) {
+  controller.abort(err)
+}
+```
+
+### Raw headers and trailers moved to the controller
+
+If you need the raw header arrays, read them from the controller:
+
+- `controller.rawHeaders`
+- `controller.rawTrailers`
+
+## 3. Update `onBodySent()` handlers
+
+If you implemented `onBodySent()`, note that its signature changed.
+
+Before, handlers received counters:
+
+```js
+onBodySent (chunkSize, totalBytesSent) {}
+```
+
+In Undici v8, handlers receive the actual chunk:
+
+```js
+onBodySent (chunk) {}
+```
+
+If you need a notification that the whole body has been sent, use
+`onRequestSent()`:
+
+```js
+onRequestSent () {
+  console.log('request body fully sent')
+}
+```
+
+## 4. If you need HTTP/1.1 only, disable HTTP/2 explicitly
+
+Undici v8 enables HTTP/2 by default when a TLS server negotiates it via ALPN.
+
+If your application depends on HTTP/1.1-specific behavior, set `allowH2: false`
+explicitly.
+
+Before:
+
+```js
+const client = new Client('https://example.com')
+```
+
+After, to keep HTTP/1.1 only:
+
+```js
+const client = new Client('https://example.com', {
+  allowH2: false
+})
+```
+
+The same applies when you configure an `Agent`:
+
+```js
+const agent = new Agent({
+  allowH2: false
+})
+```
+
+## 5. Use real `Blob` and `File` instances
+
+Undici v8 no longer accepts fake Blob-like values that only imitate `Blob` or
+`File` via properties such as `Symbol.toStringTag`.
+
+If you were passing custom objects that looked like `Blob`s, replace them with
+actual `Blob` or `File` instances:
+
+```js
+const body = new Blob(['hello'])
+```
+
+## 6. Avoid depending on the internal global dispatcher symbol
+
+`setGlobalDispatcher()` and `getGlobalDispatcher()` remain the public APIs and
+should continue to be used.
+
+Internally, Undici v8 stores its dispatcher under
+`Symbol.for('undici.globalDispatcher.2')` and mirrors a v1-compatible wrapper
+for legacy consumers such as Node.js built-in `fetch`.
+
+If your code was reading or writing `Symbol.for('undici.globalDispatcher.1')`
+directly, migrate to the public APIs instead:
+
+```js
+import { setGlobalDispatcher, getGlobalDispatcher, Agent } from 'undici'
+
+setGlobalDispatcher(new Agent())
+const dispatcher = getGlobalDispatcher()
+```
+
+If you must expose a dispatcher to legacy v1 handler consumers, wrap it with
+`Dispatcher1Wrapper`:
+
+```js
+import { Agent, Dispatcher1Wrapper } from 'undici'
+
+const legacyCompatibleDispatcher = new Dispatcher1Wrapper(new Agent())
+```
+
+## 7. Verify the upgrade
+
+After moving to Undici v8, it is worth checking these paths in your test suite:
+
+- requests that use a custom `dispatcher`
+- `setGlobalDispatcher()` behavior
+- any custom interceptor or retry handler
+- uploads that use `Blob`, `File`, or `FormData`
+- integrations that depend on HTTP/1.1-only behavior
+
+## Related documentation
+
+- [Dispatcher](/docs/api/Dispatcher.md)
+- [Client](/docs/api/Client.md)
+- [Global Installation](/docs/api/GlobalInstallation.md)
+- [Undici Module vs. Node.js Built-in Fetch](/docs/best-practices/undici-vs-builtin-fetch.md)

package/index.js

@@ -105,14 +105,14 @@ function makeDispatcher (fn) {
       url = util.parseURL(url)
     }
 
-    const { agent, dispatcher = getGlobalDispatcher() } = opts
+    const { agent, dispatcher = getGlobalDispatcher(), ...restOpts } = opts
 
     if (agent) {
       throw new InvalidArgumentError('unsupported opts.agent. Did you mean opts.client?')
     }
 
     return fn.call(dispatcher, {
-      ...opts,
+      ...restOpts,
       origin: url.origin,
       path: url.search ? `${url.pathname}${url.search}` : url.pathname,
       method: opts.method || (opts.body ? 'PUT' : 'GET')

package/lib/core/util.js

@@ -12,8 +12,6 @@ const { InvalidArgumentError, ConnectTimeoutError } = require('./errors')
 const { headerNameLowerCasedRecord } = require('./constants')
 const { tree } = require('./tree')
 
-const [nodeMajor, nodeMinor] = process.versions.node.split('.', 2).map(v => Number(v))
-
 class BodyAsyncIterable {
   constructor (body) {
     this[kBody] = body
@@ -323,7 +321,7 @@ function isIterable (obj) {
  */
 function hasSafeIterator (obj) {
   const prototype = Object.getPrototypeOf(obj)
-  const ownIterator = Object.prototype.hasOwnProperty.call(obj, Symbol.iterator)
+  const ownIterator = Object.hasOwn(obj, Symbol.iterator)
   return ownIterator || (prototype != null && prototype !== Object.prototype && typeof obj[Symbol.iterator] === 'function')
 }
 
@@ -989,8 +987,6 @@ module.exports = {
   normalizedMethodRecords,
   isValidPort,
   isHttpOrHttpsPrefixed,
-  nodeMajor,
-  nodeMinor,
   safeHTTPMethods: Object.freeze(['GET', 'HEAD', 'OPTIONS', 'TRACE']),
   wrapRequestBody,
   setupConnectTimeout,

package/lib/dispatcher/agent.js

@@ -72,14 +72,17 @@ class Agent extends DispatcherBase {
   }
 
   [kDispatch] (opts, handler) {
-    let key
+    let origin
     if (opts.origin && (typeof opts.origin === 'string' || opts.origin instanceof URL)) {
-      key = String(opts.origin)
+      origin = String(opts.origin)
     } else {
       throw new InvalidArgumentError('opts.origin must be a non-empty string or URL.')
     }
 
-    if (this[kOrigins].size >= this[kOptions].maxOrigins && !this[kOrigins].has(key)) {
+    const allowH2 = opts.allowH2 ?? this[kOptions].allowH2
+    const key = allowH2 === false ? `${origin}#http1-only` : origin
+
+    if (this[kOrigins].size >= this[kOptions].maxOrigins && !this[kOrigins].has(origin)) {
       throw new MaxOriginsReachedError()
     }
 
@@ -96,10 +99,23 @@ class Agent extends DispatcherBase {
               result.dispatcher.close()
             }
           }
-          this[kOrigins].delete(key)
+
+          let hasOrigin = false
+          for (const entry of this[kClients].values()) {
+            if (entry.origin === origin) {
+              hasOrigin = true
+              break
+            }
+          }
+
+          if (!hasOrigin) {
+            this[kOrigins].delete(origin)
+          }
         }
       }
-      dispatcher = this[kFactory](opts.origin, this[kOptions])
+      dispatcher = this[kFactory](opts.origin, allowH2 === false
+        ? { ...this[kOptions], allowH2: false }
+        : this[kOptions])
         .on('drain', this[kOnDrain])
         .on('connect', (origin, targets) => {
           const result = this[kClients].get(key)
@@ -117,8 +133,8 @@ class Agent extends DispatcherBase {
           this[kOnConnectionError](origin, targets, err)
         })
 
-      this[kClients].set(key, { count: 0, dispatcher })
-      this[kOrigins].add(key)
+      this[kClients].set(key, { count: 0, dispatcher, origin })
+      this[kOrigins].add(origin)
     }
 
     return dispatcher.dispatch(opts, handler)

package/lib/dispatcher/balanced-pool.js

@@ -57,9 +57,6 @@ class BalancedPool extends PoolBase {
     super()
 
     this[kOptions] = { ...util.deepClone(opts) }
-    this[kOptions].interceptors = opts.interceptors
-      ? { ...opts.interceptors }
-      : undefined
     this[kIndex] = -1
     this[kCurrentWeight] = 0
 

package/lib/dispatcher/client.js

@@ -235,9 +235,13 @@ class Client extends DispatcherBase {
         ...(typeof autoSelectFamily === 'boolean' ? { autoSelectFamily, autoSelectFamilyAttemptTimeout } : undefined),
         ...connect
       })
-    } else if (socketPath != null) {
+    } else {
       const customConnect = connect
-      connect = (opts, callback) => customConnect({ ...opts, socketPath }, callback)
+      connect = (opts, callback) => customConnect({
+        ...opts,
+        ...(socketPath != null ? { socketPath } : null),
+        ...(allowH2 != null ? { allowH2 } : null)
+      }, callback)
     }
 
     this[kUrl] = util.parseOrigin(url)

package/lib/dispatcher/dispatcher-base.js

@@ -138,6 +138,10 @@ class DispatcherBase extends Dispatcher {
         throw new InvalidArgumentError('opts must be an object.')
       }
 
+      if (opts.dispatcher) {
+        throw new InvalidArgumentError('opts.dispatcher is not supported by instance methods. Pass opts.dispatcher to the top-level undici functions or call the dispatcher instance method directly.')
+      }
+
       if (this[kDestroyed] || this[kOnDestroyed]) {
         throw new ClientDestroyedError()
       }

package/lib/dispatcher/dispatcher1-wrapper.js

@@ -86,6 +86,12 @@ class Dispatcher1Wrapper extends Dispatcher {
   }
 
   dispatch (opts, handler) {
+    // Legacy (v1) consumers do not support HTTP/2, so force HTTP/1.1.
+    // See https://github.com/nodejs/undici/issues/4989
+    if (opts.allowH2 !== false) {
+      opts = { ...opts, allowH2: false }
+    }
+
     return this.#dispatcher.dispatch(opts, Dispatcher1Wrapper.wrapHandler(handler))
   }
 

package/lib/dispatcher/env-http-proxy-agent.js

@@ -10,22 +10,6 @@ const DEFAULT_PORTS = {
   'https:': 443
 }
 
-/**
- * Normalizes a proxy URL by prepending a scheme if one is missing.
- * This matches the behavior of curl and Go's httpproxy package, which
- * assume http:// for scheme-less proxy values.
- *
- * @param {string} proxyUrl - The proxy URL to normalize
- * @param {string} defaultScheme - The scheme to prepend if missing ('http' or 'https')
- * @returns {string} The normalized proxy URL
- */
-function normalizeProxyUrl (proxyUrl, defaultScheme) {
-  if (!proxyUrl) return proxyUrl
-  // If the value already contains a scheme (e.g. http://, https://, socks5://), return as-is
-  if (/^[a-z][a-z0-9+\-.]*:\/\//i.test(proxyUrl)) return proxyUrl
-  return `${defaultScheme}://${proxyUrl}`
-}
-
 class EnvHttpProxyAgent extends DispatcherBase {
   #noProxyValue = null
   #noProxyEntries = null
@@ -39,20 +23,14 @@ class EnvHttpProxyAgent extends DispatcherBase {
 
     this[kNoProxyAgent] = new Agent(agentOpts)
 
-    const HTTP_PROXY = normalizeProxyUrl(
-      httpProxy ?? process.env.http_proxy ?? process.env.HTTP_PROXY,
-      'http'
-    )
+    const HTTP_PROXY = httpProxy ?? process.env.http_proxy ?? process.env.HTTP_PROXY
     if (HTTP_PROXY) {
       this[kHttpProxyAgent] = new ProxyAgent({ ...agentOpts, uri: HTTP_PROXY })
     } else {
       this[kHttpProxyAgent] = this[kNoProxyAgent]
     }
 
-    const HTTPS_PROXY = normalizeProxyUrl(
-      httpsProxy ?? process.env.https_proxy ?? process.env.HTTPS_PROXY,
-      'https'
-    )
+    const HTTPS_PROXY = httpsProxy ?? process.env.https_proxy ?? process.env.HTTPS_PROXY
     if (HTTPS_PROXY) {
       this[kHttpsProxyAgent] = new ProxyAgent({ ...agentOpts, uri: HTTPS_PROXY })
     } else {

package/lib/dispatcher/h2c-client.js

@@ -15,7 +15,7 @@ class H2CClient extends Client {
       )
     }
 
-    const { connect, maxConcurrentStreams, pipelining, ...opts } =
+    const { maxConcurrentStreams, pipelining, ...opts } =
             clientOpts ?? {}
     let defaultMaxConcurrentStreams = 100
     let defaultPipelining = 100

package/lib/dispatcher/pool.js

@@ -68,9 +68,6 @@ class Pool extends PoolBase {
     this[kConnections] = connections || null
     this[kUrl] = util.parseOrigin(origin)
     this[kOptions] = { ...util.deepClone(options), connect, allowH2, clientTtl, socketPath }
-    this[kOptions].interceptors = options.interceptors
-      ? { ...options.interceptors }
-      : undefined
     this[kFactory] = factory
 
     this.on('connect', (origin, targets) => {

package/lib/dispatcher/proxy-agent.js

@@ -16,6 +16,7 @@ const kProxyHeaders = Symbol('proxy headers')
 const kRequestTls = Symbol('request tls settings')
 const kProxyTls = Symbol('proxy tls settings')
 const kConnectEndpoint = Symbol('connect endpoint function')
+const kConnectEndpointHTTP1 = Symbol('connect endpoint function (http/1.1 only)')
 const kTunnelProxy = Symbol('tunnel proxy')
 
 function defaultProtocolPort (protocol) {
@@ -103,7 +104,7 @@ class ProxyAgent extends DispatcherBase {
       throw new InvalidArgumentError('Proxy opts.clientFactory must be a function.')
     }
 
-    const { proxyTunnel = true } = opts
+    const { proxyTunnel = true, connectTimeout } = opts
 
     super()
 
@@ -127,8 +128,9 @@ class ProxyAgent extends DispatcherBase {
       this[kProxyHeaders]['proxy-authorization'] = `Basic ${Buffer.from(`${decodeURIComponent(username)}:${decodeURIComponent(password)}`).toString('base64')}`
     }
 
-    const connect = buildConnector({ ...opts.proxyTls })
-    this[kConnectEndpoint] = buildConnector({ ...opts.requestTls })
+    const connect = buildConnector({ timeout: connectTimeout, ...opts.proxyTls })
+    this[kConnectEndpoint] = buildConnector({ timeout: connectTimeout, ...opts.requestTls })
+    this[kConnectEndpointHTTP1] = buildConnector({ timeout: connectTimeout, ...opts.requestTls, allowH2: false })
 
     const agentFactory = opts.factory || defaultAgentFactory
     const factory = (origin, options) => {
@@ -216,7 +218,11 @@ class ProxyAgent extends DispatcherBase {
           } else {
             servername = opts.servername
           }
-          this[kConnectEndpoint]({ ...opts, servername, httpSocket: socket }, callback)
+          const connectEndpoint = opts.allowH2 === false
+            ? this[kConnectEndpointHTTP1]
+            : this[kConnectEndpoint]
+
+          connectEndpoint({ ...opts, servername, httpSocket: socket }, callback)
         } catch (err) {
           if (err.code === 'ERR_TLS_CERT_ALTNAME_INVALID') {
             // Throw a custom error to avoid loop in client.js#connect

package/lib/dispatcher/round-robin-pool.js

@@ -69,9 +69,6 @@ class RoundRobinPool extends PoolBase {
     this[kConnections] = connections || null
     this[kUrl] = util.parseOrigin(origin)
     this[kOptions] = { ...util.deepClone(options), connect, allowH2, clientTtl, socketPath }
-    this[kOptions].interceptors = options.interceptors
-      ? { ...options.interceptors }
-      : undefined
     this[kFactory] = factory
     this[kIndex] = -1