undici 8.6.0 → 8.8.0

package/README.md

@@ -408,6 +408,11 @@ For more information about their behavior, please reference the body mixin from
 
 This section documents our most commonly used API methods. Additional APIs are documented in their own files within the [docs](./docs/) folder and are accessible via the navigation list on the left side of the docs site.
 
+For the top-level APIs below, the `url` argument supplies the request origin and
+path. Do not pass `origin` or `path` in the second `options` argument. The linked
+`Dispatcher` option types include those fields because dispatcher methods are
+lower-level APIs that do not receive a separate `url` argument.
+
 ### `undici.request([url, options]): Promise`
 
 Arguments:

package/docs/docs/api/Client.md

@@ -49,6 +49,10 @@ added: v1.0.0
   * `headersTimeout` {number|null} The timeout, in milliseconds, the parser
     waits to receive the complete HTTP headers before the request times out. Use
     `0` to disable it entirely. **Default:** `300e3`.
+    HTTP/1.1 headers/body parser timeouts are not guaranteed to fire with exact
+    millisecond precision: delays up to 1000ms use native timers, while larger
+    delays use undici's lower-overhead fast timers with a target resolution
+    around 500ms.
   * `connectTimeout` {number|null} The timeout, in milliseconds, for
     establishing a socket connection. Use `0` to disable it entirely.
     **Default:** `10e3`.

package/docs/docs/api/Dispatcher.md

@@ -228,6 +228,10 @@ added: v4.0.0
   * `bodyTimeout` {number|null} The time, in milliseconds, after which the request
     times out while receiving body data. Monitors the time between body chunks.
     Use `0` to disable it entirely. Defaults to 300 seconds.
+    HTTP/1.1 headers/body parser timeouts are not guaranteed to fire with exact
+    millisecond precision: delays up to 1000ms use native timers, while larger
+    delays use undici's lower-overhead fast timers with a target resolution
+    around 500ms.
   * `reset` {boolean} Whether the request should establish a keep-alive
     connection. **Default:** `false`.
   * `expectContinue` {boolean} For HTTP/2, appends the `expect: 100-continue`
@@ -729,6 +733,8 @@ await client.request({ path: '/', method: 'GET' })
 ```
 
 For the full list of built-in interceptors provided by undici, see [Interceptors](Interceptors.md).
+For an example of a custom interceptor that wraps handler callbacks, see
+[Custom interceptors](Interceptors.md#custom-interceptors).
 
 ### Event: `'connect'`
 

package/docs/docs/api/Interceptors.md

@@ -32,6 +32,65 @@ const client = new Client('https://example.com').compose(
 
 ---
 
+## Custom interceptors
+
+Custom interceptors use the same shape as
+[`dispatcher.compose()`](./Dispatcher.md#dispatchercomposeinterceptors-interceptor):
+an interceptor takes a `dispatch` function and returns another dispatch-like
+function with the same `(options, handler)` signature.
+
+When an interceptor wraps the handler, forward the callbacks that it does not
+handle itself. The complete handler callback list is documented under
+[`dispatcher.dispatch(options, handler)`](./Dispatcher.md#dispatcherdispatchoptions-handler).
+
+```js
+import { Agent } from 'undici'
+
+const timingInterceptor = dispatch => {
+  return (options, handler) => {
+    const started = performance.now()
+
+    return dispatch(options, {
+      ...handler,
+      onResponseStart (controller, statusCode, headers, statusMessage) {
+        const duration = Math.round(performance.now() - started)
+        const method = options.method ?? 'GET'
+        const origin = options.origin ?? ''
+
+        console.log(`${method} ${origin}${options.path} -> ${statusCode} in ${duration}ms`)
+
+        return handler.onResponseStart?.(
+          controller,
+          statusCode,
+          headers,
+          statusMessage
+        )
+      },
+      onResponseError (controller, error) {
+        const duration = Math.round(performance.now() - started)
+
+        console.error(`request failed after ${duration}ms`, error)
+
+        return handler.onResponseError?.(controller, error)
+      }
+    })
+  }
+}
+
+const dispatcher = new Agent().compose(timingInterceptor)
+
+const { body } = await dispatcher.request({
+  origin: 'https://example.com',
+  path: '/',
+  method: 'GET'
+})
+
+await body.dump()
+await dispatcher.close()
+```
+
+---
+
 ## `interceptors.dump([opts])`
 
 Reads and discards the response body up to a configurable size limit. Useful

package/docs/docs/api/MockAgent.md

@@ -17,6 +17,13 @@ registered on the {MockClient} or {MockPool} instances returned by
 `MockAgent` is set as the dispatcher (for example through
 [`setGlobalDispatcher()`][] or a per-request `dispatcher` option).
 
+> [!NOTE]
+> [`setGlobalDispatcher()`][] only affects undici APIs that use the global
+> dispatcher, such as `request()` and `fetch()`. It does not replace or
+> monkeypatch {Pool} or {Client} instances that were created separately. To test
+> code that accepts or creates a pool/client directly, pass the {MockPool} or
+> {MockClient} returned by [`mockAgent.get(origin)`][] into that code.
+
 ```mjs
 import { MockAgent } from 'undici'
 
@@ -139,6 +146,26 @@ for await (const data of body) {
 }
 ```
 
+```mjs displayName="Testing code that accepts a pool"
+import { MockAgent } from 'undici'
+
+async function getStatus (pool) {
+  const { statusCode } = await pool.request({
+    path: '/foo',
+    method: 'GET'
+  })
+
+  return statusCode
+}
+
+const mockAgent = new MockAgent()
+const mockPool = mockAgent.get('http://localhost:3000')
+
+mockPool.intercept({ path: '/foo', method: 'GET' }).reply(200)
+
+console.log(await getStatus(mockPool)) // 200
+```
+
 ```mjs displayName="Returning a MockClient"
 import { MockAgent, request } from 'undici'
 

package/docs/docs/api/MockPool.md

@@ -136,7 +136,8 @@ The reply behaviour of a matching request is defined through the returned
   computing all reply options dynamically rather than just the body.
   * `callback` {Function} A `(opts: MockResponseCallbackOptions) =>
     { statusCode, data, responseOptions }` function invoked with the incoming
-    request.
+    request. The callback may be asynchronous; a returned promise is awaited
+    and must resolve to the same shape.
   * Returns: {MockScope}
 * `replyWithError(error)` {Function} Defines an error for a matching request to
   throw.
@@ -263,6 +264,32 @@ for await (const data of body) {
 }
 ```
 
+```mjs displayName="Reply with an asynchronous options callback"
+import { readFile } from 'node:fs/promises'
+import { MockAgent, setGlobalDispatcher, request } from 'undici'
+
+const mockAgent = new MockAgent()
+setGlobalDispatcher(mockAgent)
+
+const mockPool = mockAgent.get('http://localhost:3000')
+
+mockPool.intercept({
+  path: '/fixture',
+  method: 'GET'
+}).reply(async ({ path }) => ({
+  statusCode: 200,
+  data: await readFile(new URL('./fixture.json', import.meta.url))
+}))
+
+const { statusCode, body } = await request('http://localhost:3000/fixture')
+
+console.log('response received', statusCode) // response received 200
+
+for await (const data of body) {
+  console.log('data', data.toString('utf8')) // contents of fixture.json
+}
+```
+
 ```mjs displayName="Multiple intercepts"
 import { MockAgent, setGlobalDispatcher, request } from 'undici'
 

package/docs/docs/api/ProxyAgent.md

@@ -62,12 +62,19 @@ added: v4.8.2
     * `origin` {URL} The proxy origin.
     * `opts` {Object} The resolved options for the dispatcher.
     * Returns: {Dispatcher}
-  * `proxyTunnel` {boolean} Forces tunneling through the proxy. When `false`,
-    requests where both the proxy and the endpoint use the insecure `http:`
-    protocol are sent directly to the proxy with the absolute request URI rather
-    than through a `CONNECT` tunnel, matching `curl` behavior. Secure
-    connections always use a tunnel regardless of this option. **Default:**
-    `true`.
+  * `proxyTunnel` {boolean} Forces tunneling through the proxy. By default,
+    Undici detects tunneling based on the request protocol. If the target
+    endpoint uses HTTPS, Undici establishes a `CONNECT` tunnel through the proxy
+    (after the TLS handshake to the proxy itself when the proxy URL is HTTPS).
+    If the target endpoint uses plain HTTP, Undici forwards the request to the
+    proxy using an HTTP/1.1 absolute-form request target (over TLS when the
+    proxy URL is HTTPS), as required by
+    [RFC 9112 §3.2.2](https://www.rfc-editor.org/rfc/rfc9112.html#name-absolute-form).
+    This non-tunneled forwarding path does not negotiate HTTP/2 with the proxy.
+    Set `proxyTunnel` to `true` to force tunneling for plain HTTP requests as
+    well. Currently, there is no way to facilitate HTTP/1.1 IP tunneling as
+    described in
+    [RFC 9484](https://www.rfc-editor.org/rfc/rfc9484.html#name-http-11-request).
 
 Throws an {InvalidArgumentError} when no proxy URI is provided, when
 `clientFactory` is not a function, or when both `auth` and `token` are supplied.

package/docs/docs/best-practices/mocking-request.md

@@ -102,7 +102,7 @@ setGlobalDispatcher(mockAgent)
 // this call is made (not intercepted)
 await fetch(`http://localhost:3000/endpoint?query='hello'`, {
   method: 'POST',
-  headers: { 'content-type': 'application/json' }
+  headers: { 'content-type': 'application/json' },
   body: JSON.stringify({ data: '' })
 })
 

package/docs/docs/index.md

@@ -410,6 +410,11 @@ For more information about their behavior, please reference the body mixin from
 
 This section documents our most commonly used API methods. Additional APIs are documented in their own files within the [docs](./docs/) folder and are accessible via the navigation list on the left side of the docs site.
 
+For the top-level APIs below, the `url` argument supplies the request origin and
+path. Do not pass `origin` or `path` in the second `options` argument. The linked
+`Dispatcher` option types include those fields because dispatcher methods are
+lower-level APIs that do not receive a separate `url` argument.
+
 ### `undici.request([url, options])`
 
 * `url` {string|URL|UrlObject}

package/lib/api/readable.js

@@ -587,6 +587,10 @@ function consumeEnd (consume, encoding) {
  * @returns {void}
  */
 function consumePush (consume, chunk) {
+  if (consume.body === null) {
+    return
+  }
+
   consume.length += chunk.length
   consume.body.push(chunk)
 }

package/lib/core/request.js

@@ -173,7 +173,7 @@ class Request {
 
     this.method = method
 
-    this.typeOfService = typeOfService ?? 0
+    this.typeOfService = typeOfService
 
     this.abort = null
 

package/lib/core/util.js

@@ -370,7 +370,12 @@ function destroy (stream, err) {
       stream.socket = null
     }
 
-    stream.destroy(err)
+    try {
+      stream.destroy(err)
+    } catch {
+      // stream.destroy may throw on managed sockets (e.g., http2).
+      // Silently ignore — the socket lifecycle is handled by the subsystem.
+    }
   } else if (err) {
     queueMicrotask(() => {
       stream.emit('error', err)
@@ -919,11 +924,32 @@ function onConnectTimeout (socket, opts) {
   destroy(socket, new ConnectTimeoutError(message))
 }
 
+let lastUrlString = null
+let lastProtocol = null
+
 /**
  * @param {string} urlString
  * @returns {string}
  */
 function getProtocolFromUrlString (urlString) {
+  // Requests are typically dispatched against the same origin over and over,
+  // so cache the last (urlString, protocol) pair to skip re-parsing.
+  if (urlString === lastUrlString) {
+    return lastProtocol
+  }
+
+  const protocol = getProtocolFromUrlStringSlow(urlString)
+  lastUrlString = urlString
+  lastProtocol = protocol
+
+  return protocol
+}
+
+/**
+ * @param {string} urlString
+ * @returns {string}
+ */
+function getProtocolFromUrlStringSlow (urlString) {
   if (
     urlString[0] === 'h' &&
     urlString[1] === 't' &&

package/lib/dispatcher/agent.js

@@ -107,15 +107,15 @@ class Agent extends DispatcherBase {
         }
 
         let hasOrigin = false
-        for (const client of this[kClients].values()) {
-          if (client[kUrl].origin === dispatcher[kUrl].origin) {
+        for (const k of this[kClients].keys()) {
+          if (k === origin || k === `${origin}#http1-only`) {
             hasOrigin = true
             break
           }
         }
 
         if (!hasOrigin) {
-          this[kOrigins].delete(dispatcher[kUrl].origin)
+          this[kOrigins].delete(origin)
         }
       }
 

package/lib/dispatcher/client-h1.js

@@ -60,6 +60,7 @@ const removeAllListeners = util.removeAllListeners
 const kIdleSocketValidation = Symbol('kIdleSocketValidation')
 const kIdleSocketValidationTimeout = Symbol('kIdleSocketValidationTimeout')
 const kSocketUsed = Symbol('kSocketUsed')
+const kTypeOfService = Symbol('kTypeOfService')
 
 let extractBody
 
@@ -1050,7 +1051,7 @@ function onSocketClose () {
 
 function clearIdleSocketValidation (socket) {
   if (socket[kIdleSocketValidationTimeout]) {
-    clearTimeout(socket[kIdleSocketValidationTimeout])
+    clearImmediate(socket[kIdleSocketValidationTimeout])
     socket[kIdleSocketValidationTimeout] = null
   }
 
@@ -1059,14 +1060,14 @@ function clearIdleSocketValidation (socket) {
 
 function scheduleIdleSocketValidation (client, socket) {
   socket[kIdleSocketValidation] = 1
-  socket[kIdleSocketValidationTimeout] = setTimeout(() => {
+  socket[kIdleSocketValidationTimeout] = setImmediate(() => {
     socket[kIdleSocketValidationTimeout] = null
     socket[kIdleSocketValidation] = 2
 
     if (client[kSocket] === socket && !socket.destroyed) {
       client[kResume]()
     }
-  }, 0)
+  })
   socket[kIdleSocketValidationTimeout].unref?.()
 }
 
@@ -1134,6 +1135,32 @@ function shouldSendContentLength (method) {
   return method !== 'GET' && method !== 'HEAD' && method !== 'OPTIONS' && method !== 'TRACE' && method !== 'CONNECT'
 }
 
+function setTypeOfService (socket, request) {
+  if (typeof socket.setTypeOfService !== 'function') {
+    return
+  }
+
+  const typeOfService = request.typeOfService
+
+  if (typeOfService === undefined) {
+    return
+  }
+
+  const currentTypeOfService = socket[kTypeOfService]
+
+  if (currentTypeOfService === typeOfService) {
+    return
+  }
+
+  try {
+    socket.setTypeOfService(typeOfService)
+    socket[kTypeOfService] = typeOfService
+  } catch {
+    // QoS marking is best-effort. setTypeOfService() can throw synchronously on
+    // some platforms depending on socket state, but that must not abort the request.
+  }
+}
+
 /**
  * @param {import('./client.js')} client
  * @param {import('../core/request.js')} request
@@ -1265,9 +1292,7 @@ function writeH1 (client, request) {
     socket[kBlocking] = true
   }
 
-  if (socket.setTypeOfService) {
-    socket.setTypeOfService(request.typeOfService)
-  }
+  setTypeOfService(socket, request)
 
   let header = `${method} ${path} HTTP/1.1\r\n`