undici 7.13.0 → 7.14.0

package/README.md

@@ -622,11 +622,11 @@ and `undici.Agent`) which will enable the family autoselection algorithm when es
 
 Undici aligns with the Node.js LTS schedule. The following table shows the supported versions:
 
-| Version | Node.js     | End of Life |
-|---------|-------------|-------------|
-| 5.x     | v18.x       | 2024-04-30  |
-| 6.x     | v20.x v22.x | 2026-04-30  |
-| 7.x     | v24.x       | 2027-04-30  |
+| Undici Version | Bundled in Node.js | Node.js Versions Supported | End of Life |
+|----------------|-------------------|----------------------------|-------------|
+| 5.x           | 18.x              | ≥14.0 (tested: 14, 16, 18) | 2024-04-30  |
+| 6.x           | 20.x, 22.x       | ≥18.17 (tested: 18, 20, 21, 22) | 2026-04-30  |
+| 7.x           | 24.x              | ≥20.18.1 (tested: 20, 22, 24) | 2027-04-30  |
 
 ## License
 

package/docs/docs/api/DiagnosticsChannel.md

@@ -169,14 +169,38 @@ This message is published after the client has successfully connected to a serve
 ```js
 import diagnosticsChannel from 'diagnostics_channel'
 
-diagnosticsChannel.channel('undici:websocket:open').subscribe(({ address, protocol, extensions, websocket }) => {
+diagnosticsChannel.channel('undici:websocket:open').subscribe(({ 
+  address,           // { address: string, family: string, port: number }
+  protocol,          // string - negotiated subprotocol
+  extensions,        // string - negotiated extensions
+  websocket,         // WebSocket - the WebSocket instance
+  handshakeResponse  // object - HTTP response that upgraded the connection
+}) => {
   console.log(address) // address, family, and port
   console.log(protocol) // negotiated subprotocols
   console.log(extensions) // negotiated extensions
   console.log(websocket) // the WebSocket instance
+  
+  // Handshake response details
+  console.log(handshakeResponse.status) // 101 for successful WebSocket upgrade
+  console.log(handshakeResponse.statusText) // 'Switching Protocols'
+  console.log(handshakeResponse.headers) // Object containing response headers
 })
 ```
 
+### Handshake Response Object
+
+The `handshakeResponse` object contains the HTTP response that upgraded the connection to WebSocket:
+
+- `status` (number): The HTTP status code (101 for successful WebSocket upgrade)
+- `statusText` (string): The HTTP status message ('Switching Protocols' for successful upgrade)
+- `headers` (object): The HTTP response headers from the server, including:
+  - `upgrade: 'websocket'`
+  - `connection: 'upgrade'`
+  - `sec-websocket-accept` and other WebSocket-related headers
+
+This information is particularly useful for debugging and monitoring WebSocket connections, as it provides access to the initial HTTP handshake response that established the WebSocket connection.
+
 ## `undici:websocket:close`
 
 This message is published after the connection has closed.

package/lib/dispatcher/proxy-agent.js

@@ -1,7 +1,6 @@
 'use strict'
 
 const { kProxy, kClose, kDestroy, kDispatch } = require('../core/symbols')
-const { URL } = require('node:url')
 const Agent = require('./agent')
 const Pool = require('./pool')
 const DispatcherBase = require('./dispatcher-base')
@@ -208,7 +207,7 @@ class ProxyAgent extends DispatcherBase {
   }
 
   /**
-   * @param {import('../types/proxy-agent').ProxyAgent.Options | string | URL} opts
+   * @param {import('../../types/proxy-agent').ProxyAgent.Options | string | URL} opts
    * @returns {URL}
    */
   #getUrl (opts) {

package/lib/handler/cache-handler.js

@@ -15,6 +15,15 @@ const HEURISTICALLY_CACHEABLE_STATUS_CODES = [
   200, 203, 204, 206, 300, 301, 308, 404, 405, 410, 414, 501
 ]
 
+// Status codes which semantic is not handled by the cache
+// https://datatracker.ietf.org/doc/html/rfc9111#section-3
+// This list should not grow beyond 206 and 304 unless the RFC is updated
+// by a newer one including more. Please introduce another list if
+// implementing caching of responses with the 'must-understand' directive.
+const NOT_UNDERSTOOD_STATUS_CODES = [
+  206, 304
+]
+
 const MAX_RESPONSE_AGE = 2147483647000
 
 /**
@@ -241,10 +250,19 @@ class CacheHandler {
  * @param {import('../../types/cache-interceptor.d.ts').default.CacheControlDirectives} cacheControlDirectives
  */
 function canCacheResponse (cacheType, statusCode, resHeaders, cacheControlDirectives) {
-  // Allow caching for status codes 200 and 307 (original behavior)
-  // Also allow caching for other status codes that are heuristically cacheable
-  // when they have explicit cache directives
-  if (statusCode !== 200 && statusCode !== 307 && !HEURISTICALLY_CACHEABLE_STATUS_CODES.includes(statusCode)) {
+  // Status code must be final and understood.
+  if (statusCode < 200 || NOT_UNDERSTOOD_STATUS_CODES.includes(statusCode)) {
+    return false
+  }
+  // Responses with neither status codes that are heuristically cacheable, nor "explicit enough" caching
+  // directives, are not cacheable. "Explicit enough": see https://www.rfc-editor.org/rfc/rfc9111.html#section-3
+  if (!HEURISTICALLY_CACHEABLE_STATUS_CODES.includes(statusCode) && !resHeaders['expires'] &&
+    !cacheControlDirectives.public &&
+    cacheControlDirectives['max-age'] === undefined &&
+    // RFC 9111: a private response directive, if the cache is not shared
+    !(cacheControlDirectives.private && cacheType === 'private') &&
+    !(cacheControlDirectives['s-maxage'] !== undefined && cacheType === 'shared')
+  ) {
     return false
   }
 

package/lib/interceptor/cache.js

@@ -6,7 +6,7 @@ const util = require('../core/util')
 const CacheHandler = require('../handler/cache-handler')
 const MemoryCacheStore = require('../cache/memory-cache-store')
 const CacheRevalidationHandler = require('../handler/cache-revalidation-handler')
-const { assertCacheStore, assertCacheMethods, makeCacheKey, normaliseHeaders, parseCacheControlHeader } = require('../util/cache.js')
+const { assertCacheStore, assertCacheMethods, makeCacheKey, normalizeHeaders, parseCacheControlHeader } = require('../util/cache.js')
 const { AbortError } = require('../core/errors.js')
 
 /**
@@ -326,7 +326,7 @@ module.exports = (opts = {}) => {
 
       opts = {
         ...opts,
-        headers: normaliseHeaders(opts)
+        headers: normalizeHeaders(opts)
       }
 
       const reqCacheControl = opts.headers?.['cache-control']

package/lib/mock/snapshot-agent.js

@@ -5,6 +5,7 @@ const MockAgent = require('./mock-agent')
 const { SnapshotRecorder } = require('./snapshot-recorder')
 const WrapHandler = require('../handler/wrap-handler')
 const { InvalidArgumentError, UndiciError } = require('../core/errors')
+const { validateSnapshotMode } = require('./snapshot-utils')
 
 const kSnapshotRecorder = Symbol('kSnapshotRecorder')
 const kSnapshotMode = Symbol('kSnapshotMode')
@@ -12,7 +13,7 @@ const kSnapshotPath = Symbol('kSnapshotPath')
 const kSnapshotLoaded = Symbol('kSnapshotLoaded')
 const kRealAgent = Symbol('kRealAgent')
 
-// Static flag to ensure warning is only emitted once
+// Static flag to ensure warning is only emitted once per process
 let warningEmitted = false
 
 class SnapshotAgent extends MockAgent {
@@ -26,26 +27,24 @@ class SnapshotAgent extends MockAgent {
       warningEmitted = true
     }
 
-    const mockOptions = { ...opts }
-    delete mockOptions.mode
-    delete mockOptions.snapshotPath
+    const {
+      mode = 'record',
+      snapshotPath = null,
+      ...mockAgentOpts
+    } = opts
 
-    super(mockOptions)
+    super(mockAgentOpts)
 
-    // Validate mode option
-    const validModes = ['record', 'playback', 'update']
-    const mode = opts.mode || 'record'
-    if (!validModes.includes(mode)) {
-      throw new InvalidArgumentError(`Invalid snapshot mode: ${mode}. Must be one of: ${validModes.join(', ')}`)
-    }
+    validateSnapshotMode(mode)
 
     // Validate snapshotPath is provided when required
-    if ((mode === 'playback' || mode === 'update') && !opts.snapshotPath) {
+    if ((mode === 'playback' || mode === 'update') && !snapshotPath) {
       throw new InvalidArgumentError(`snapshotPath is required when mode is '${mode}'`)
     }
 
     this[kSnapshotMode] = mode
-    this[kSnapshotPath] = opts.snapshotPath
+    this[kSnapshotPath] = snapshotPath
+
     this[kSnapshotRecorder] = new SnapshotRecorder({
       snapshotPath: this[kSnapshotPath],
       mode: this[kSnapshotMode],
@@ -85,7 +84,7 @@ class SnapshotAgent extends MockAgent {
       // Ensure snapshots are loaded
       if (!this[kSnapshotLoaded]) {
         // Need to load asynchronously, delegate to async version
-        return this._asyncDispatch(opts, handler)
+        return this.#asyncDispatch(opts, handler)
       }
 
       // Try to find existing snapshot (synchronous)
@@ -93,10 +92,10 @@ class SnapshotAgent extends MockAgent {
 
       if (snapshot) {
         // Use recorded response (synchronous)
-        return this._replaySnapshot(snapshot, handler)
+        return this.#replaySnapshot(snapshot, handler)
       } else if (mode === 'update') {
         // Make real request and record it (async required)
-        return this._recordAndReplay(opts, handler)
+        return this.#recordAndReplay(opts, handler)
       } else {
         // Playback mode but no snapshot found
         const error = new UndiciError(`No snapshot found for ${opts.method || 'GET'} ${opts.path}`)
@@ -108,16 +107,14 @@ class SnapshotAgent extends MockAgent {
       }
     } else if (mode === 'record') {
       // Record mode - make real request and save response (async required)
-      return this._recordAndReplay(opts, handler)
-    } else {
-      throw new InvalidArgumentError(`Invalid snapshot mode: ${mode}. Must be 'record', 'playback', or 'update'`)
+      return this.#recordAndReplay(opts, handler)
     }
   }
 
   /**
    * Async version of dispatch for when we need to load snapshots first
    */
-  async _asyncDispatch (opts, handler) {
+  async #asyncDispatch (opts, handler) {
     await this.loadSnapshots()
     return this.dispatch(opts, handler)
   }
@@ -125,7 +122,7 @@ class SnapshotAgent extends MockAgent {
   /**
    * Records a real request and replays the response
    */
-  _recordAndReplay (opts, handler) {
+  #recordAndReplay (opts, handler) {
     const responseData = {
       statusCode: null,
       headers: {},
@@ -180,45 +177,46 @@ class SnapshotAgent extends MockAgent {
 
   /**
    * Replays a recorded response
+   *
+   * @param {Object} snapshot - The recorded snapshot to replay.
+   * @param {Object} handler - The handler to call with the response data.
+   * @returns {void}
    */
-  _replaySnapshot (snapshot, handler) {
-    return new Promise((resolve) => {
-      // Simulate the response
-      setImmediate(() => {
-        try {
-          const { response } = snapshot
-
-          const controller = {
-            pause () {},
-            resume () {},
-            abort (reason) {
-              this.aborted = true
-              this.reason = reason
-            },
-
-            aborted: false,
-            paused: false
-          }
-
-          handler.onRequestStart(controller)
-
-          handler.onResponseStart(controller, response.statusCode, response.headers)
-
-          // Body is always stored as base64 string
-          const body = Buffer.from(response.body, 'base64')
-          handler.onResponseData(controller, body)
-
-          handler.onResponseEnd(controller, response.trailers)
-          resolve()
-        } catch (error) {
-          handler.onError?.(error)
-        }
-      })
-    })
+  #replaySnapshot (snapshot, handler) {
+    try {
+      const { response } = snapshot
+
+      const controller = {
+        pause () { },
+        resume () { },
+        abort (reason) {
+          this.aborted = true
+          this.reason = reason
+        },
+
+        aborted: false,
+        paused: false
+      }
+
+      handler.onRequestStart(controller)
+
+      handler.onResponseStart(controller, response.statusCode, response.headers)
+
+      // Body is always stored as base64 string
+      const body = Buffer.from(response.body, 'base64')
+      handler.onResponseData(controller, body)
+
+      handler.onResponseEnd(controller, response.trailers)
+    } catch (error) {
+      handler.onError?.(error)
+    }
   }
 
   /**
    * Loads snapshots from file
+   *
+   * @param {string} [filePath] - Optional file path to load snapshots from.
+   * @returns {Promise<void>} - Resolves when snapshots are loaded.
    */
   async loadSnapshots (filePath) {
     await this[kSnapshotRecorder].loadSnapshots(filePath || this[kSnapshotPath])
@@ -226,12 +224,15 @@ class SnapshotAgent extends MockAgent {
 
     // In playback mode, set up MockAgent interceptors for all snapshots
     if (this[kSnapshotMode] === 'playback') {
-      this._setupMockInterceptors()
+      this.#setupMockInterceptors()
     }
   }
 
   /**
    * Saves snapshots to file
+   *
+   * @param {string} [filePath] - Optional file path to save snapshots to.
+   * @returns {Promise<void>} - Resolves when snapshots are saved.
    */
   async saveSnapshots (filePath) {
     return this[kSnapshotRecorder].saveSnapshots(filePath || this[kSnapshotPath])
@@ -248,9 +249,9 @@ class SnapshotAgent extends MockAgent {
    *
    * Called automatically when loading snapshots in playback mode.
    *
-   * @private
+   * @returns {void}
    */
-  _setupMockInterceptors () {
+  #setupMockInterceptors () {
     for (const snapshot of this[kSnapshotRecorder].getSnapshots()) {
       const { request, responses, response } = snapshot
       const url = new URL(request.url)
@@ -275,6 +276,7 @@ class SnapshotAgent extends MockAgent {
 
   /**
    * Gets the snapshot recorder
+   * @return {SnapshotRecorder} - The snapshot recorder instance
    */
   getRecorder () {
     return this[kSnapshotRecorder]
@@ -282,6 +284,7 @@ class SnapshotAgent extends MockAgent {
 
   /**
    * Gets the current mode
+   * @return {import('./snapshot-utils').SnapshotMode} - The current snapshot mode
    */
   getMode () {
     return this[kSnapshotMode]
@@ -289,6 +292,7 @@ class SnapshotAgent extends MockAgent {
 
   /**
    * Clears all snapshots
+   * @returns {void}
    */
   clearSnapshots () {
     this[kSnapshotRecorder].clear()
@@ -296,6 +300,7 @@ class SnapshotAgent extends MockAgent {
 
   /**
    * Resets call counts for all snapshots (useful for test cleanup)
+   * @returns {void}
    */
   resetCallCounts () {
     this[kSnapshotRecorder].resetCallCounts()
@@ -303,6 +308,8 @@ class SnapshotAgent extends MockAgent {
 
   /**
    * Deletes a specific snapshot by request options
+   * @param {import('./snapshot-recorder').SnapshotRequestOptions} requestOpts - Request options to identify the snapshot
+   * @return {Promise<boolean>} - Returns true if the snapshot was deleted, false if not found
    */
   deleteSnapshot (requestOpts) {
     return this[kSnapshotRecorder].deleteSnapshot(requestOpts)
@@ -310,6 +317,7 @@ class SnapshotAgent extends MockAgent {
 
   /**
    * Gets information about a specific snapshot
+   * @returns {import('./snapshot-recorder').SnapshotInfo|null} - Snapshot information or null if not found
    */
   getSnapshotInfo (requestOpts) {
     return this[kSnapshotRecorder].getSnapshotInfo(requestOpts)
@@ -317,13 +325,19 @@ class SnapshotAgent extends MockAgent {
 
   /**
    * Replaces all snapshots with new data (full replacement)
+   * @param {Array<{hash: string; snapshot: import('./snapshot-recorder').SnapshotEntryshotEntry}>|Record<string, import('./snapshot-recorder').SnapshotEntry>} snapshotData - New snapshot data to replace existing snapshots
+   * @returns {void}
    */
   replaceSnapshots (snapshotData) {
     this[kSnapshotRecorder].replaceSnapshots(snapshotData)
   }
 
+  /**
+   * Closes the agent, saving snapshots and cleaning up resources.
+   *
+   * @returns {Promise<void>}
+   */
   async close () {
-    // Close recorder (saves snapshots and cleans up timers)
     await this[kSnapshotRecorder].close()
     await this[kRealAgent]?.close()
     await super.close()