undici 8.7.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/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/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)

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`
 

package/lib/dispatcher/client-h2.js

@@ -157,9 +157,10 @@ function completeRequest (client, request, resetPendingIdx = false) {
   const queue = client[kQueue]
   const runningIdx = client[kRunningIdx]
 
-  // In-order completion: advance the running index instead of splicing.
-  // The client's resume loop compacts the queue once the index grows.
+  // In-order completion: clear the request and advance without splicing.
+  // The client's resume loop compacts cleared slots once the index grows.
   if (runningIdx < client[kPendingIdx] && queue[runningIdx] === request) {
+    queue[runningIdx] = null
     client[kRunningIdx] = runningIdx + 1
     return
   }
@@ -246,7 +247,6 @@ function connectH2 (client, socket) {
 
   util.addListener(session, 'error', onHttp2SessionError)
   util.addListener(session, 'frameError', onHttp2FrameError)
-  util.addListener(session, 'end', onHttp2SessionEnd)
   util.addListener(session, 'goaway', onHttp2SessionGoAway)
   util.addListener(session, 'close', onHttp2SessionClose)
   util.addListener(session, 'remoteSettings', onHttp2RemoteSettings)
@@ -322,16 +322,6 @@ function connectH2 (client, socket) {
           // Don't dispatch an upgrade until all preceding requests have completed.
           // Possibly, we do not have remote settings confirmed yet.
           if ((request.upgrade === 'websocket' || request.method === 'CONNECT') && session[kRemoteSettings] === false) return true
-          // Request with stream or iterator body can error while other requests
-          // are inflight and indirectly error those as well.
-          // Ensure this doesn't happen by waiting for inflight
-          // to complete before dispatching.
-
-          // Request with stream or iterator body cannot be retried.
-          // Ensure that no other requests are inflight and
-          // could cause failure.
-          if (util.bodyLength(request.body) !== 0 &&
-            (util.isStream(request.body) || util.isAsyncIterable(request.body) || util.isFormDataLike(request.body))) return true
         } else {
           return (request.upgrade === 'websocket' || request.method === 'CONNECT') && session[kRemoteSettings] === false
         }
@@ -505,12 +495,6 @@ function onHttp2FrameError (type, code, id) {
   }
 }
 
-function onHttp2SessionEnd () {
-  const err = new SocketError('other side closed', util.getSocketInfo(this[kSocket]))
-  this.destroy(err)
-  util.destroy(this[kSocket], err)
-}
-
 /**
  * This is the root cause of #3011
  * We need to handle GOAWAY frames properly, and trigger the session close
@@ -654,7 +638,7 @@ function onHttp2SocketError (err) {
     return
   }
 
-  this[kClient][kOnError](err)
+  this[kHTTP2Session]?.[kClient]?.[kOnError](err)
 }
 
 function onHttp2SocketEnd () {
@@ -688,20 +672,24 @@ function onUpgradeStreamClose () {
   closeStreamSession(this)
 }
 
-function onRequestStreamClose () {
+// Idempotent terminal cleanup, called from both 'end' and 'close': the
+// null-state guard no-ops the later call.
+function completeRequestStream () {
   const state = this[kRequestStreamState]
 
-  if (state) {
-    // Release the stream first so request references are cleared,
-    // then complete the response with trailers if available.
-    releaseRequestStream(this)
+  if (state == null) {
+    return
+  }
+
+  // Release the stream first so request references are cleared,
+  // then complete the response with trailers if available.
+  releaseRequestStream(this)
 
-    if (state.pendingEnd && !state.request.aborted && !state.request.completed) {
-      state.request.onResponseEnd(state.trailers || {})
-      finalizeRequest(state)
-    }
+  if (state.pendingEnd && !state.request.aborted && !state.request.completed) {
+    state.request.onResponseEnd(state.trailers || {})
   }
 
+  finalizeRequest(state)
   closeStreamSession(this)
   this[kRequestStreamState] = null
 }
@@ -943,14 +931,14 @@ function writeH2 (client, request) {
       // close() alone leaves cleanup waiting on the 'close' event; on a busy,
       // long-lived multiplexed session that event can fail to fire, leaving the
       // native Http2Stream (and the whole request graph it pins) alive for the
-      // session's life. Destroy the stream to release the handle
-      // deterministically, but defer it by a setImmediate so the RST_STREAM
-      // frame queued by close() gets a chance to be written first.
-      setImmediate(() => {
-        if (!stream.destroyed) {
-          util.destroy(stream)
-        }
-      })
+      // session's life. Destroy the stream synchronously to release the handle
+      // deterministically. Deferring the destroy (e.g. via setImmediate) leaks
+      // the same way when the event loop is stalled and the callback never runs
+      // under abort churn (#5558); close() has already queued the RST_STREAM
+      // frame on the native session, so a synchronous destroy still sends it.
+      if (!stream.destroyed) {
+        util.destroy(stream)
+      }
 
       // We move the running index to the next request
       client[kOnError](err)
@@ -1137,7 +1125,7 @@ function writeH2 (client, request) {
   }
 
   stream[kHTTP2Session] = session
-  stream.on('close', onRequestStreamClose)
+  stream.on('close', completeRequestStream)
 
   bindRequestToStream(request, stream, releaseRequestStream)
   if (expectContinue) {
@@ -1280,13 +1268,16 @@ function onEnd () {
 
   stream.off('end', onEnd)
 
-  // If we received a response, this is a normal completion.
-  // Defer actual completion to onRequestStreamClose so that
-  // onTrailers (which may fire after 'end' on Windows) can
-  // store trailers first.
+  // onTrailers (which may fire after 'end' on Windows) has already stored
+  // trailers on the state by now, so completing here still delivers them.
   if (state.responseReceived) {
     if (!request.aborted && !request.completed) {
       state.pendingEnd = true
+
+      // Complete on 'end': a blocked event loop can keep the stream's 'close'
+      // from firing, stranding its buffers until OOM. Idempotent, so a later
+      // 'close' no-ops.
+      completeRequestStream.call(stream)
     }
   } else {
     // Stream ended without receiving a response - this is an error
@@ -1357,7 +1348,7 @@ function onTrailers (trailers) {
     return
   }
 
-  // Store trailers for onRequestStreamClose to use when completing
+  // Store trailers for completeRequestStream to use when completing
   state.trailers = trailers
 }
 

package/lib/handler/cache-handler.js

@@ -26,6 +26,10 @@ const NOT_UNDERSTOOD_STATUS_CODES = [
 
 const MAX_RESPONSE_AGE = 2147483647000
 
+// Retention for revalidation-only entries (zero freshness lifetime but a
+//  validator present); each successful revalidation re-stores the entry.
+const REVALIDATION_ONLY_RETENTION = 86400000 // 24 hours
+
 /**
  * @typedef {import('../../types/dispatcher.d.ts').default.DispatchHandler} DispatchHandler
  *
@@ -118,6 +122,7 @@ class CacheHandler {
       } catch {
         // Fail silently
       }
+      this.#deleteLocationHeaderEntries(resHeaders)
       return downstreamOnHeaders()
     }
 
@@ -150,8 +155,12 @@ class CacheHandler {
       ? parseHttpDate(resHeaders.date)
       : undefined
 
+    const hasValidator =
+      (typeof resHeaders.etag === 'string' && isEtagUsable(resHeaders.etag)) ||
+      typeof resHeaders['last-modified'] === 'string'
+
     const staleAt =
-      determineStaleAt(this.#cacheType, now, resAge, resHeaders, resDate, cacheControlDirectives) ??
+      determineStaleAt(this.#cacheType, now, resAge, resHeaders, resDate, cacheControlDirectives, hasValidator) ??
       this.#cacheByDefault
     if (staleAt === undefined || (resAge && resAge > staleAt)) {
       return downstreamOnHeaders()
@@ -159,7 +168,11 @@ class CacheHandler {
 
     const baseTime = resDate ? resDate.getTime() : now
     const absoluteStaleAt = staleAt + baseTime
-    if (now >= absoluteStaleAt) {
+    // Zero freshness lifetime but a validator: stale from the start, yet still
+    //  storable since each reuse is preceded by a revalidation request.
+    //  https://www.rfc-editor.org/rfc/rfc9111.html#section-5.2.2.4
+    const revalidationOnly = staleAt === 0 && hasValidator
+    if (now >= absoluteStaleAt && !revalidationOnly) {
       // Response is already stale
       return downstreamOnHeaders()
     }
@@ -314,6 +327,58 @@ class CacheHandler {
     }
   }
 
+  /**
+   * Deletes the cache entries for the URIs in the response's Location and
+   * Content-Location headers when they share the request URI's origin
+   *  https://www.rfc-editor.org/rfc/rfc9111.html#section-4.4
+   *
+   * @param {import('../../types/header.d.ts').IncomingHttpHeaders} resHeaders
+   */
+  #deleteLocationHeaderEntries (resHeaders) {
+    let requestUrl
+    try {
+      requestUrl = new URL(this.#cacheKey.path, this.#cacheKey.origin)
+    } catch {
+      // Can't resolve the request URI, don't invalidate anything else
+      return
+    }
+
+    const invalidatedPaths = new Set([this.#cacheKey.path])
+
+    for (const headerName of ['location', 'content-location']) {
+      const header = resHeaders[headerName]
+      const value = Array.isArray(header) ? header[0] : header
+      if (typeof value !== 'string' || value === '') {
+        continue
+      }
+
+      let url
+      try {
+        url = new URL(value, requestUrl)
+      } catch {
+        continue
+      }
+
+      if (url.origin !== requestUrl.origin) {
+        // Only invalidate URIs sharing the request URI's origin, invalidating
+        //  cross-origin URIs could be used for cache poisoning
+        continue
+      }
+
+      const path = `${url.pathname}${url.search}`
+      if (invalidatedPaths.has(path)) {
+        continue
+      }
+      invalidatedPaths.add(path)
+
+      try {
+        this.#store.delete({ ...this.#cacheKey, path })?.catch?.(noop)
+      } catch {
+        // Fail silently
+      }
+    }
+  }
+
   onResponseData (controller, chunk) {
     if (this.#writeStream?.write(chunk) === false) {
       controller.pause()
@@ -422,23 +487,35 @@ function getAge (ageHeader) {
  * @param {import('../../types/header.d.ts').IncomingHttpHeaders} resHeaders
  * @param {Date | undefined} responseDate
  * @param {import('../../types/cache-interceptor.d.ts').default.CacheControlDirectives} cacheControlDirectives
+ * @param {boolean} hasValidator whether the response has a validator (etag or
+ *  last-modified) that revalidation requests can be made with
  *
  * @returns {number | undefined} time that the value is stale at in seconds or undefined if it shouldn't be cached
  */
-function determineStaleAt (cacheType, now, age, resHeaders, responseDate, cacheControlDirectives) {
+function determineStaleAt (cacheType, now, age, resHeaders, responseDate, cacheControlDirectives, hasValidator) {
   if (cacheType === 'shared') {
     // Prioritize s-maxage since we're a shared cache
     //  s-maxage > max-age > Expire
     //  https://www.rfc-editor.org/rfc/rfc9111.html#section-5.2.2.10-3
     const sMaxAge = cacheControlDirectives['s-maxage']
     if (sMaxAge !== undefined) {
-      return sMaxAge > 0 ? sMaxAge * 1000 : undefined
+      if (sMaxAge > 0) {
+        return sMaxAge * 1000
+      }
+
+      // Immediately stale, but storable if we can revalidate it before reuse.
+      return sMaxAge === 0 && hasValidator ? 0 : undefined
     }
   }
 
   const maxAge = cacheControlDirectives['max-age']
   if (maxAge !== undefined) {
-    return maxAge > 0 ? maxAge * 1000 : undefined
+    if (maxAge > 0) {
+      return maxAge * 1000
+    }
+
+    // Immediately stale, but storable if we can revalidate it before reuse.
+    return maxAge === 0 && hasValidator ? 0 : undefined
   }
 
   if (typeof resHeaders.expires === 'string') {
@@ -482,6 +559,12 @@ function determineStaleAt (cacheType, now, age, resHeaders, responseDate, cacheC
     return 31536000000
   }
 
+  if (cacheControlDirectives['no-cache'] === true && hasValidator) {
+    // No freshness source, but a validator lets us revalidate before reuse.
+    //  https://www.rfc-editor.org/rfc/rfc9111.html#section-5.2.2.4
+    return 0
+  }
+
   return undefined
 }
 
@@ -518,6 +601,11 @@ function determineDeleteAt (baseTime, cachedAt, cacheControlDirectives, staleAt)
   // revalidated.
   if (staleWhileRevalidate === -Infinity && staleIfError === -Infinity && immutable === -Infinity) {
     const freshnessLifetime = staleAt - baseTime
+    if (freshnessLifetime <= 0) {
+      // Revalidation-only entry: no freshness lifetime to size the buffer on,
+      //  so retain it for a bounded window instead.
+      return cachedAt + REVALIDATION_ONLY_RETENTION
+    }
     const datePrecisionPadding = Math.min(Math.max(cachedAt - baseTime, 0), 1000)
     return staleAt + freshnessLifetime + datePrecisionPadding
   }

package/lib/handler/cache-revalidation-handler.js

@@ -109,6 +109,16 @@ class CacheRevalidationHandler {
     }
 
     if (this.#callback) {
+      // Serve the stale cached response on a connection error, per stale-if-error:
+      //  RFC 5861 counts an unreachable origin (a would-be 5xx) as an error.
+      // https://datatracker.ietf.org/doc/html/rfc5861#section-4
+      if (this.#allowErrorStatusCodes) {
+        this.#successful = true
+        this.#callback(true, this.#context)
+        this.#callback = null
+        return
+      }
+
       this.#callback(false)
       this.#callback = null
     }

package/lib/handler/redirect-handler.js

@@ -52,6 +52,8 @@ class RedirectHandler {
       throw new Error('max redirects')
     }
 
+    let removeContentHeaders = statusCode === 303
+
     // https://tools.ietf.org/html/rfc7231#section-6.4.2
     // https://fetch.spec.whatwg.org/#http-redirect-fetch
     // In case of HTTP 301 or 302 with POST, change the method to GET
@@ -62,6 +64,7 @@ class RedirectHandler {
         util.destroy(this.opts.body.on('error', noop))
       }
       this.opts.body = null
+      removeContentHeaders = true
     }
 
     // https://tools.ietf.org/html/rfc7231#section-6.4.4
@@ -101,9 +104,9 @@ class RedirectHandler {
     }
 
     // Remove headers referring to the original URL.
-    // By default it is Host only, unless it's a 303 (see below), which removes also all Content-* headers.
+    // By default it is Host only. A 303 or a 301/302 POST-to-GET redirect also removes all Content-* headers.
     // https://tools.ietf.org/html/rfc7231#section-6.4
-    this.opts.headers = cleanRequestHeaders(this.opts.headers, statusCode === 303, this.opts.origin !== origin, this.stripHeadersOnRedirect, this.stripHeadersOnCrossOriginRedirect)
+    this.opts.headers = cleanRequestHeaders(this.opts.headers, removeContentHeaders, this.opts.origin !== origin, this.stripHeadersOnRedirect, this.stripHeadersOnCrossOriginRedirect)
     this.opts.path = path
     this.opts.origin = origin
     this.opts.query = null

package/lib/handler/retry-handler.js

@@ -11,7 +11,7 @@ const {
 
 function calculateRetryAfterHeader (retryAfter) {
   const retryTime = new Date(retryAfter).getTime()
-  return isNaN(retryTime) ? 0 : retryTime - Date.now()
+  return isNaN(retryTime) ? null : retryTime - Date.now()
 }
 
 // A stable controller handed to the downstream handler for the lifetime of the
@@ -211,9 +211,11 @@ class RetryHandler {
     }
 
     const retryTimeout =
-      retryAfterHeader > 0
-        ? Math.min(retryAfterHeader, maxTimeout)
-        : Math.min(minTimeout * timeoutFactor ** (counter - 1), maxTimeout)
+      retryAfterHeader === 0
+        ? 0
+        : retryAfterHeader > 0
+          ? Math.min(retryAfterHeader, maxTimeout)
+          : Math.min(minTimeout * timeoutFactor ** (counter - 1), maxTimeout)
 
     setTimeout(() => cb(null), retryTimeout)
   }

package/lib/interceptor/cache.js

@@ -57,16 +57,33 @@ function needsRevalidation (result, cacheControlDirectives, { headers = {} }) {
   return false
 }
 
+/**
+ * must-revalidate (proxy-revalidate for shared caches) forbids serving a stale
+ * response without successful validation, overriding max-stale and stale-if-error.
+ * https://www.rfc-editor.org/rfc/rfc9111.html#section-5.2.2.2
+ * https://www.rfc-editor.org/rfc/rfc9111.html#section-5.2.2.8
+ * @param {import('../../types/cache-interceptor.d.ts').default.GetResult} result
+ * @param {'shared' | 'private'} cacheType
+ * @returns {boolean}
+ */
+function forbidsServingStale (result, cacheType) {
+  return Boolean(
+    result.cacheControlDirectives?.['must-revalidate'] ||
+    (cacheType === 'shared' && result.cacheControlDirectives?.['proxy-revalidate'])
+  )
+}
+
 /**
  * @param {import('../../types/cache-interceptor.d.ts').default.GetResult} result
  * @param {import('../../types/cache-interceptor.d.ts').default.CacheControlDirectives | undefined} cacheControlDirectives
+ * @param {'shared' | 'private'} cacheType
  * @returns {boolean}
  */
-function isStale (result, cacheControlDirectives) {
+function isStale (result, cacheControlDirectives, cacheType) {
   const now = Date.now()
   if (now > result.staleAt) {
     // Response is stale
-    if (cacheControlDirectives?.['max-stale']) {
+    if (cacheControlDirectives?.['max-stale'] && !forbidsServingStale(result, cacheType)) {
       // There's a threshold where we can serve stale responses, let's see if
       //  we're in it
       // https://www.rfc-editor.org/rfc/rfc9111.html#name-max-stale
@@ -286,7 +303,7 @@ function handleResult (
     return dispatch(opts, handler)
   }
 
-  const stale = isStale(result, reqCacheControl)
+  const stale = isStale(result, reqCacheControl, globalOpts.type)
   const revalidate = needsRevalidation(result, reqCacheControl, opts)
 
   // Check if the response is stale
@@ -345,7 +362,7 @@ function handleResult (
 
     let withinStaleIfErrorThreshold = false
     const staleIfErrorExpiry = result.cacheControlDirectives['stale-if-error'] ?? reqCacheControl?.['stale-if-error']
-    if (staleIfErrorExpiry) {
+    if (staleIfErrorExpiry && !forbidsServingStale(result, globalOpts.type)) {
       withinStaleIfErrorThreshold = now < (result.staleAt + (staleIfErrorExpiry * 1000))
     }
 

package/lib/interceptor/decompress.js

@@ -276,6 +276,10 @@ function createDecompressInterceptor (options = {}) {
 
   return (dispatch) => {
     return (opts, handler) => {
+      if (opts.method === 'HEAD') {
+        return dispatch(opts, handler)
+      }
+
       const decompressHandler = new DecompressHandler(handler, options)
       return dispatch(opts, decompressHandler)
     }

package/lib/mock/mock-interceptor.js

@@ -12,6 +12,11 @@ const {
 } = require('./mock-symbols')
 const { InvalidArgumentError } = require('../core/errors')
 const { serializePathWithQuery } = require('../core/util')
+const {
+  types: {
+    isPromise
+  }
+} = require('node:util')
 
 /**
  * Defines the scope API for an interceptor reply
@@ -117,13 +122,9 @@ class MockInterceptor {
     // Values of reply aren't available right now as they
     // can only be available when the reply callback is invoked.
     if (typeof replyOptionsCallbackOrStatusCode === 'function') {
-      // We'll first wrap the provided callback in another function,
-      // this function will properly resolve the data from the callback
-      // when invoked.
-      const wrappedDefaultsCallback = (opts) => {
-        // Our reply options callback contains the parameter for statusCode, data and options.
-        const resolvedData = replyOptionsCallbackOrStatusCode(opts)
-
+      // Resolves the data returned by a reply options callback into
+      // dispatch data, validating its format along the way.
+      const resolveReplyCallbackData = (resolvedData) => {
         // Check if it is in the right format
         if (typeof resolvedData !== 'object' || resolvedData === null) {
           throw new InvalidArgumentError('reply options callback must return an object')
@@ -138,6 +139,23 @@ class MockInterceptor {
         }
       }
 
+      // We'll first wrap the provided callback in another function,
+      // this function will properly resolve the data from the callback
+      // when invoked.
+      const wrappedDefaultsCallback = (opts) => {
+        // Our reply options callback contains the parameter for statusCode, data and options.
+        const resolvedData = replyOptionsCallbackOrStatusCode(opts)
+
+        // An asynchronous reply options callback resolves to the reply
+        // parameters, so the dispatch data can only be resolved once the
+        // returned promise settles.
+        if (isPromise(resolvedData)) {
+          return resolvedData.then(resolveReplyCallbackData)
+        }
+
+        return resolveReplyCallbackData(resolvedData)
+      }
+
       // Add usual dispatch data, but this time set the data parameter to function that will eventually provide data.
       const newMockDispatch = addMockDispatch(this[kDispatches], this[kDispatchKey], wrappedDefaultsCallback, { ignoreTrailingSlash: this[kIgnoreTrailingSlash] })
       return new MockScope(newMockDispatch)

package/lib/mock/mock-utils.js

@@ -292,25 +292,54 @@ function mockDispatch (opts, handler) {
   // Get mock dispatch from built key
   const key = buildKey(opts)
   const mockDispatch = getMockDispatch(this[kDispatches], key)
+  const mockDispatches = this[kDispatches]
 
   mockDispatch.timesInvoked++
 
+  const { timesInvoked, times } = mockDispatch
+
+  // If it's used up and not persistent, mark as consumed
+  mockDispatch.consumed = !mockDispatch.persist && timesInvoked >= times
+  mockDispatch.pending = timesInvoked < times
+
   // Here's where we resolve a callback if a callback is present for the dispatch data.
   if (mockDispatch.data.callback) {
-    mockDispatch.data = { ...mockDispatch.data, ...mockDispatch.data.callback(opts) }
+    const callbackResult = mockDispatch.data.callback(opts)
+
+    // An asynchronous reply options callback resolves to the reply data, so
+    // the dispatch can only continue once the returned promise settles.
+    // A rejection cannot be thrown synchronously from the dispatch at that
+    // point, so it is surfaced as a response error instead.
+    if (isPromise(callbackResult)) {
+      callbackResult.then(
+        (resolvedData) => {
+          mockDispatch.data = { ...mockDispatch.data, ...resolvedData }
+          dispatchMockReply(mockDispatches, mockDispatch, key, opts, handler)
+        },
+        (error) => {
+          deleteMockDispatch(mockDispatches, key)
+          handler.onResponseError(null, error)
+        }
+      )
+      return true
+    }
+
+    mockDispatch.data = { ...mockDispatch.data, ...callbackResult }
   }
 
-  // Parse mockDispatch data
-  const { data: { statusCode, data, headers, trailers, error }, delay, persist } = mockDispatch
-  const { timesInvoked, times } = mockDispatch
+  return dispatchMockReply(mockDispatches, mockDispatch, key, opts, handler)
+}
 
-  // If it's used up and not persistent, mark as consumed
-  mockDispatch.consumed = !persist && timesInvoked >= times
-  mockDispatch.pending = timesInvoked < times
+/**
+ * Replies to a request once the mock dispatch data is fully resolved
+ */
+function dispatchMockReply (mockDispatches, mockDispatch, key, opts, handler) {
+  // Parse mockDispatch data
+  const { data: { statusCode, data, headers, trailers, error }, delay } = mockDispatch
 
   // If specified, trigger dispatch error
   if (error !== null) {
-    deleteMockDispatch(this[kDispatches], key)
+    deleteMockDispatch(mockDispatches, key)
     handler.onResponseError(null, error)
     return true
   }
@@ -353,10 +382,10 @@ function mockDispatch (opts, handler) {
   if (typeof delay === 'number' && delay > 0) {
     timer = setTimeout(() => {
       timer = null
-      handleReply(this[kDispatches])
+      handleReply(mockDispatches)
     }, delay)
   } else {
-    handleReply(this[kDispatches])
+    handleReply(mockDispatches)
   }
 
   function handleReply (mockDispatches, _data = data) {

package/lib/util/cache.js

@@ -42,15 +42,57 @@ function normalizeHeaders (opts) {
     headers = {}
 
     if (hasSafeIterator(opts.headers)) {
-      for (const x of opts.headers) {
-        if (!Array.isArray(x)) {
-          throw new Error('opts.headers is not a valid header map')
+      if (Array.isArray(opts.headers)) {
+        // Array format: could be flat alternating [k, v, k, v, ...]
+        //  or array-of-pairs [[k, v], ...]
+        const first = opts.headers[0]
+        if (Array.isArray(first)) {
+          for (const x of opts.headers) {
+            if (!Array.isArray(x)) {
+              throw new Error('opts.headers is not a valid header map')
+            }
+            const [key, val] = x
+            if (typeof key !== 'string' || typeof val !== 'string') {
+              throw new Error('opts.headers is not a valid header map')
+            }
+            headers[key.toLowerCase()] = val
+          }
+        } else {
+          // Flat alternating array [k, v, k, v, ...]
+          const len = opts.headers.length
+          if (len % 2 !== 0) {
+            throw new Error('opts.headers is not a valid header map')
+          }
+          for (let i = 0; i < len; i += 2) {
+            const key = opts.headers[i]
+            const val = opts.headers[i + 1]
+            if (typeof key !== 'string' || (typeof val !== 'string' && !Array.isArray(val))) {
+              throw new Error('opts.headers is not a valid header map')
+            }
+            if (typeof val === 'string') {
+              headers[key.toLowerCase()] = val
+            } else {
+              const mapped = []
+              for (let j = 0; j < val.length; j++) {
+                const v = val[j]
+                mapped.push(typeof v === 'string' ? v : v.toString('latin1'))
+              }
+              headers[key.toLowerCase()] = mapped
+            }
+          }
         }
-        const [key, val] = x
-        if (typeof key !== 'string' || typeof val !== 'string') {
-          throw new Error('opts.headers is not a valid header map')
+      } else {
+        // Non-array iterable (e.g. Map) — use original iteration logic
+        for (const x of opts.headers) {
+          if (!Array.isArray(x)) {
+            throw new Error('opts.headers is not a valid header map')
+          }
+          const [key, val] = x
+          if (typeof key !== 'string' || typeof val !== 'string') {
+            throw new Error('opts.headers is not a valid header map')
+          }
+          headers[key.toLowerCase()] = val
         }
-        headers[key.toLowerCase()] = val
       }
     } else {
       for (const key of Object.keys(opts.headers)) {

package/lib/web/fetch/body.js

@@ -16,6 +16,7 @@ const { serializeAMimeType } = require('./data-url')
 const { multipartFormDataParser } = require('./formdata-parser')
 const { parseJSONFromBytes } = require('../infra')
 const { utf8DecodeBytes } = require('../../encoding')
+const { ReadableStreamTee } = require('node:stream/web')
 
 const textEncoder = new TextEncoder()
 function noop () {}
@@ -279,7 +280,7 @@ function cloneBody (body) {
   // https://fetch.spec.whatwg.org/#concept-body-clone
 
   // 1. Let « out1, out2 » be the result of teeing body’s stream.
-  const { 0: out1, 1: out2 } = body.stream.tee()
+  const { 0: out1, 1: out2 } = ReadableStreamTee?.(body.stream, true) ?? body.stream.tee()
 
   // 2. Set body’s stream to out1.
   body.stream = out1

package/lib/web/fetch/response.js

@@ -45,9 +45,7 @@ class Response {
   static json (data, init = undefined) {
     webidl.argumentLengthCheck(arguments, 1, 'Response.json')
 
-    if (init !== null) {
-      init = webidl.converters.ResponseInit(init)
-    }
+    init = webidl.converters.ResponseInit(init)
 
     // 1. Let bytes the result of running serialize a JavaScript value to JSON bytes on data.
     const bytes = textEncoder.encode(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "undici",
-  "version": "8.7.0",
+  "version": "8.8.0",
   "description": "An HTTP/1.1 client, written from scratch for Node.js",
   "homepage": "https://undici.nodejs.org",
   "bugs": {
@@ -116,7 +116,7 @@
     "@types/node": "^22.0.0",
     "abort-controller": "^3.0.0",
     "borp": "^1.0.0",
-    "c8": "^11.0.0",
+    "c8": "^12.0.0",
     "cross-env": "^10.0.0",
     "dns-packet": "^5.4.0",
     "esbuild": "^0.28.0",

package/types/client.d.ts

@@ -33,7 +33,7 @@ export declare namespace Client {
   export interface Options {
     /** The maximum length of request headers in bytes. Default: Node.js' `--max-http-header-size` or `16384` (16KiB). */
     maxHeaderSize?: number;
-    /** The amount of time, in milliseconds, the parser will wait to receive the complete HTTP headers (Node 14 and above only). Default: `300e3` milliseconds (300s). */
+    /** The amount of time, in milliseconds, the parser will wait to receive the complete HTTP headers (Node 14 and above only). Default: `300e3` milliseconds (300s). HTTP/1.1 parser timeouts are not guaranteed to fire with exact millisecond precision: delays up to 1000ms use native timers, while larger delays use lower-overhead fast timers with a target resolution around 500ms. */
     headersTimeout?: number;
     /** @deprecated unsupported socketTimeout, use headersTimeout & bodyTimeout instead */
     socketTimeout?: never;
@@ -41,7 +41,7 @@ export declare namespace Client {
     requestTimeout?: never;
     /** The timeout for establishing a socket connection, in milliseconds. Use `0` to disable it entirely. Default: `10e3` milliseconds (10s). */
     connectTimeout?: number;
-    /** The timeout after which a request will time out, in milliseconds. Monitors time between receiving body data. Use `0` to disable it entirely. Default: `300e3` milliseconds (300s). */
+    /** The timeout after which a request will time out, in milliseconds. Monitors time between receiving body data. Use `0` to disable it entirely. Default: `300e3` milliseconds (300s). HTTP/1.1 parser timeouts are not guaranteed to fire with exact millisecond precision: delays up to 1000ms use native timers, while larger delays use lower-overhead fast timers with a target resolution around 500ms. */
     bodyTimeout?: number;
     /** @deprecated unsupported idleTimeout, use keepAliveTimeout instead */
     idleTimeout?: never;

package/types/dispatcher.d.ts

@@ -111,13 +111,13 @@ declare namespace Dispatcher {
     idempotent?: boolean;
     /** Whether the response is expected to take a long time and would end up blocking the pipeline. When this is set to `true` further pipelining will be avoided on the same connection until headers have been received. Defaults to `method !== 'HEAD'`. */
     blocking?: boolean;
-    /** The IP Type of Service (ToS) value for the request socket. Must be an integer between 0 and 255. Default: `0` */
+    /** The IP Type of Service (ToS) value for the request socket. Must be an integer between 0 and 255. */
     typeOfService?: number | null;
     /** Upgrade the request. Should be used to specify the kind of upgrade i.e. `'Websocket'`. Default: `method === 'CONNECT' || null`. */
     upgrade?: boolean | string | null;
-    /** The amount of time, in milliseconds, the parser will wait to receive the complete HTTP headers. Defaults to 300 seconds. */
+    /** The amount of time, in milliseconds, the parser will wait to receive the complete HTTP headers. Defaults to 300 seconds. HTTP/1.1 parser timeouts are not guaranteed to fire with exact millisecond precision: delays up to 1000ms use native timers, while larger delays use lower-overhead fast timers with a target resolution around 500ms. */
     headersTimeout?: number | null;
-    /** The timeout after which a request will time out, in milliseconds. Monitors time between receiving body data. Use 0 to disable it entirely. Defaults to 300 seconds. */
+    /** The timeout after which a request will time out, in milliseconds. Monitors time between receiving body data. Use 0 to disable it entirely. Defaults to 300 seconds. HTTP/1.1 parser timeouts are not guaranteed to fire with exact millisecond precision: delays up to 1000ms use native timers, while larger delays use lower-overhead fast timers with a target resolution around 500ms. */
     bodyTimeout?: number | null;
     /** Whether the request should stablish a keep-alive or not. Default `false` */
     reset?: boolean;

package/types/mock-interceptor.d.ts

@@ -75,9 +75,13 @@ declare namespace MockInterceptor {
     opts: MockResponseCallbackOptions
   ) => TData | Buffer | string
 
+  export type MockReplyOptions<TData extends object = object> = {
+    statusCode: number, data?: TData | Buffer | string, responseOptions?: MockResponseOptions
+  }
+
   export type MockReplyOptionsCallback<TData extends object = object> = (
     opts: MockResponseCallbackOptions
-  ) => { statusCode: number, data?: TData | Buffer | string, responseOptions?: MockResponseOptions }
+  ) => MockReplyOptions<TData> | Promise<MockReplyOptions<TData>>
 }
 
 interface Interceptable extends Dispatcher {