undici 7.13.0 → 7.15.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/docs/docs/api/Dispatcher.md

@@ -1094,6 +1094,65 @@ await client.request({
 });
 ```
 
+##### `decompress`
+
+⚠️ The decompress interceptor is experimental and subject to change.
+
+The `decompress` interceptor automatically decompresses response bodies that are compressed with gzip, deflate, brotli, or zstd compression. It removes the `content-encoding` and `content-length` headers from decompressed responses and supports RFC-9110 compliant multiple encodings.
+
+**Options**
+
+- `skipErrorResponses` - Whether to skip decompression for error responses (status codes >= 400). Default: `true`.
+- `skipStatusCodes` - Array of status codes to skip decompression for. Default: `[204, 304]`.
+
+**Example - Basic Decompress Interceptor**
+
+```js
+const { Client, interceptors } = require("undici");
+const { decompress } = interceptors;
+
+const client = new Client("http://example.com").compose(
+  decompress()
+);
+
+// Automatically decompresses gzip/deflate/brotli/zstd responses
+const response = await client.request({
+  method: "GET",
+  path: "/"
+});
+```
+
+**Example - Custom Options**
+
+```js
+const { Client, interceptors } = require("undici");
+const { decompress } = interceptors;
+
+const client = new Client("http://example.com").compose(
+  decompress({
+    skipErrorResponses: false, // Decompress 5xx responses
+    skipStatusCodes: [204, 304, 201] // Skip these status codes
+  })
+);
+```
+
+**Supported Encodings**
+
+- `gzip` / `x-gzip` - GZIP compression
+- `deflate` / `x-compress` - DEFLATE compression  
+- `br` - Brotli compression
+- `zstd` - Zstandard compression
+- Multiple encodings (e.g., `gzip, deflate`) are supported per RFC-9110
+
+**Behavior**
+
+- Skips decompression for status codes < 200 or >= 400 (configurable)
+- Skips decompression for 204 No Content and 304 Not Modified by default
+- Removes `content-encoding` and `content-length` headers when decompressing
+- Passes through unsupported encodings unchanged
+- Handles case-insensitive encoding names
+- Supports streaming decompression without buffering
+
 ##### `Cache Interceptor`
 
 The `cache` interceptor implements client-side response caching as described in

package/index.js

@@ -46,7 +46,8 @@ module.exports.interceptors = {
   retry: require('./lib/interceptor/retry'),
   dump: require('./lib/interceptor/dump'),
   dns: require('./lib/interceptor/dns'),
-  cache: require('./lib/interceptor/cache')
+  cache: require('./lib/interceptor/cache'),
+  decompress: require('./lib/interceptor/decompress')
 }
 
 module.exports.cacheStores = {

package/lib/core/util.js

@@ -102,13 +102,24 @@ function isBlobLike (object) {
   }
 }
 
+/**
+ * @param {string} url The path to check for query strings or fragments.
+ * @returns {boolean} Returns true if the path contains a query string or fragment.
+ */
+function pathHasQueryOrFragment (url) {
+  return (
+    url.includes('?') ||
+    url.includes('#')
+  )
+}
+
 /**
  * @param {string} url The URL to add the query params to
  * @param {import('node:querystring').ParsedUrlQueryInput} queryParams The object to serialize into a URL query string
  * @returns {string} The URL with the query params added
  */
 function serializePathWithQuery (url, queryParams) {
-  if (url.includes('?') || url.includes('#')) {
+  if (pathHasQueryOrFragment(url)) {
     throw new Error('Query params cannot be passed when url already contains "?" or "#".')
   }
 
@@ -924,6 +935,7 @@ module.exports = {
   assertRequestHandler,
   getSocketInfo,
   isFormDataLike,
+  pathHasQueryOrFragment,
   serializePathWithQuery,
   addAbortListener,
   isValidHTTPToken,

package/lib/dispatcher/agent.js

@@ -45,27 +45,14 @@ class Agent extends DispatcherBase {
     }
 
     this[kOnConnect] = (origin, targets) => {
-      const result = this[kClients].get(origin)
-      if (result) {
-        result.count += 1
-      }
       this.emit('connect', origin, [this, ...targets])
     }
 
     this[kOnDisconnect] = (origin, targets, err) => {
-      const result = this[kClients].get(origin)
-      if (result) {
-        result.count -= 1
-        if (result.count <= 0) {
-          this[kClients].delete(origin)
-          result.dispatcher.destroy()
-        }
-      }
       this.emit('disconnect', origin, [this, ...targets], err)
     }
 
     this[kOnConnectionError] = (origin, targets, err) => {
-      // TODO: should this decrement result.count here?
       this.emit('connectionError', origin, [this, ...targets], err)
     }
   }
@@ -89,11 +76,33 @@ class Agent extends DispatcherBase {
     const result = this[kClients].get(key)
     let dispatcher = result && result.dispatcher
     if (!dispatcher) {
+      const closeClientIfUnused = (connected) => {
+        const result = this[kClients].get(key)
+        if (result) {
+          if (connected) result.count -= 1
+          if (result.count <= 0) {
+            this[kClients].delete(key)
+            result.dispatcher.close()
+          }
+        }
+      }
       dispatcher = this[kFactory](opts.origin, this[kOptions])
         .on('drain', this[kOnDrain])
-        .on('connect', this[kOnConnect])
-        .on('disconnect', this[kOnDisconnect])
-        .on('connectionError', this[kOnConnectionError])
+        .on('connect', (origin, targets) => {
+          const result = this[kClients].get(key)
+          if (result) {
+            result.count += 1
+          }
+          this[kOnConnect](origin, targets)
+        })
+        .on('disconnect', (origin, targets, err) => {
+          closeClientIfUnused(true)
+          this[kOnDisconnect](origin, targets, err)
+        })
+        .on('connectionError', (origin, targets, err) => {
+          closeClientIfUnused(false)
+          this[kOnConnectionError](origin, targets, err)
+        })
 
       this[kClients].set(key, { count: 0, dispatcher })
     }

package/lib/dispatcher/client-h1.js

@@ -66,7 +66,7 @@ function lazyllhttp () {
   let mod
   try {
     mod = new WebAssembly.Module(require('../llhttp/llhttp_simd-wasm.js'))
-  } catch (e) {
+  } catch {
     /* istanbul ignore next */
 
     // We could check if the error was caused by the simd option not

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/interceptor/decompress.js

@@ -0,0 +1,253 @@
+'use strict'
+
+const { createInflate, createGunzip, createBrotliDecompress, createZstdDecompress } = require('node:zlib')
+const { pipeline } = require('node:stream')
+const DecoratorHandler = require('../handler/decorator-handler')
+
+/** @typedef {import('node:stream').Transform} Transform */
+/** @typedef {import('node:stream').Transform} Controller */
+/** @typedef {Transform&import('node:zlib').Zlib} DecompressorStream */
+
+/** @type {Record<string, () => DecompressorStream>} */
+const supportedEncodings = {
+  gzip: createGunzip,
+  'x-gzip': createGunzip,
+  br: createBrotliDecompress,
+  deflate: createInflate,
+  compress: createInflate,
+  'x-compress': createInflate,
+  ...(createZstdDecompress ? { zstd: createZstdDecompress } : {})
+}
+
+const defaultSkipStatusCodes = /** @type {const} */ ([204, 304])
+
+let warningEmitted = /** @type {boolean} */ (false)
+
+/**
+ * @typedef {Object} DecompressHandlerOptions
+ * @property {number[]|Readonly<number[]>} [skipStatusCodes=[204, 304]] - List of status codes to skip decompression for
+ * @property {boolean} [skipErrorResponses] - Whether to skip decompression for error responses (status codes >= 400)
+ */
+
+class DecompressHandler extends DecoratorHandler {
+  /** @type {Transform[]} */
+  #decompressors = []
+  /** @type {NodeJS.WritableStream&NodeJS.ReadableStream|null} */
+  #pipelineStream
+  /** @type {Readonly<number[]>} */
+  #skipStatusCodes
+  /** @type {boolean} */
+  #skipErrorResponses
+
+  constructor (handler, { skipStatusCodes = defaultSkipStatusCodes, skipErrorResponses = true } = {}) {
+    super(handler)
+    this.#skipStatusCodes = skipStatusCodes
+    this.#skipErrorResponses = skipErrorResponses
+  }
+
+  /**
+   * Determines if decompression should be skipped based on encoding and status code
+   * @param {string} contentEncoding - Content-Encoding header value
+   * @param {number} statusCode - HTTP status code of the response
+   * @returns {boolean} - True if decompression should be skipped
+   */
+  #shouldSkipDecompression (contentEncoding, statusCode) {
+    if (!contentEncoding || statusCode < 200) return true
+    if (this.#skipStatusCodes.includes(statusCode)) return true
+    if (this.#skipErrorResponses && statusCode >= 400) return true
+    return false
+  }
+
+  /**
+   * Creates a chain of decompressors for multiple content encodings
+   *
+   * @param {string} encodings - Comma-separated list of content encodings
+   * @returns {Array<DecompressorStream>} - Array of decompressor streams
+   */
+  #createDecompressionChain (encodings) {
+    const parts = encodings.split(',')
+
+    /** @type {DecompressorStream[]} */
+    const decompressors = []
+
+    for (let i = parts.length - 1; i >= 0; i--) {
+      const encoding = parts[i].trim()
+      if (!encoding) continue
+
+      if (!supportedEncodings[encoding]) {
+        decompressors.length = 0 // Clear if unsupported encoding
+        return decompressors // Unsupported encoding
+      }
+
+      decompressors.push(supportedEncodings[encoding]())
+    }
+
+    return decompressors
+  }
+
+  /**
+   * Sets up event handlers for a decompressor stream using readable events
+   * @param {DecompressorStream} decompressor - The decompressor stream
+   * @param {Controller} controller - The controller to coordinate with
+   * @returns {void}
+   */
+  #setupDecompressorEvents (decompressor, controller) {
+    decompressor.on('readable', () => {
+      let chunk
+      while ((chunk = decompressor.read()) !== null) {
+        const result = super.onResponseData(controller, chunk)
+        if (result === false) {
+          break
+        }
+      }
+    })
+
+    decompressor.on('error', (error) => {
+      super.onResponseError(controller, error)
+    })
+  }
+
+  /**
+   * Sets up event handling for a single decompressor
+   * @param {Controller} controller - The controller to handle events
+   * @returns {void}
+   */
+  #setupSingleDecompressor (controller) {
+    const decompressor = this.#decompressors[0]
+    this.#setupDecompressorEvents(decompressor, controller)
+
+    decompressor.on('end', () => {
+      super.onResponseEnd(controller, {})
+    })
+  }
+
+  /**
+   * Sets up event handling for multiple chained decompressors using pipeline
+   * @param {Controller} controller - The controller to handle events
+   * @returns {void}
+   */
+  #setupMultipleDecompressors (controller) {
+    const lastDecompressor = this.#decompressors[this.#decompressors.length - 1]
+    this.#setupDecompressorEvents(lastDecompressor, controller)
+
+    this.#pipelineStream = pipeline(this.#decompressors, (err) => {
+      if (err) {
+        super.onResponseError(controller, err)
+        return
+      }
+      super.onResponseEnd(controller, {})
+    })
+  }
+
+  /**
+   * Cleans up decompressor references to prevent memory leaks
+   * @returns {void}
+   */
+  #cleanupDecompressors () {
+    this.#decompressors.length = 0
+    this.#pipelineStream = null
+  }
+
+  /**
+   * @param {Controller} controller
+   * @param {number} statusCode
+   * @param {Record<string, string | string[] | undefined>} headers
+   * @param {string} statusMessage
+   * @returns {void}
+   */
+  onResponseStart (controller, statusCode, headers, statusMessage) {
+    const contentEncoding = headers['content-encoding']
+
+    // If content encoding is not supported or status code is in skip list
+    if (this.#shouldSkipDecompression(contentEncoding, statusCode)) {
+      return super.onResponseStart(controller, statusCode, headers, statusMessage)
+    }
+
+    const decompressors = this.#createDecompressionChain(contentEncoding.toLowerCase())
+
+    if (decompressors.length === 0) {
+      this.#cleanupDecompressors()
+      return super.onResponseStart(controller, statusCode, headers, statusMessage)
+    }
+
+    this.#decompressors = decompressors
+
+    // Remove compression headers since we're decompressing
+    const { 'content-encoding': _, 'content-length': __, ...newHeaders } = headers
+
+    if (this.#decompressors.length === 1) {
+      this.#setupSingleDecompressor(controller)
+    } else {
+      this.#setupMultipleDecompressors(controller)
+    }
+
+    super.onResponseStart(controller, statusCode, newHeaders, statusMessage)
+  }
+
+  /**
+   * @param {Controller} controller
+   * @param {Buffer} chunk
+   * @returns {void}
+   */
+  onResponseData (controller, chunk) {
+    if (this.#decompressors.length > 0) {
+      this.#decompressors[0].write(chunk)
+      return
+    }
+    super.onResponseData(controller, chunk)
+  }
+
+  /**
+   * @param {Controller} controller
+   * @param {Record<string, string | string[]> | undefined} trailers
+   * @returns {void}
+   */
+  onResponseEnd (controller, trailers) {
+    if (this.#decompressors.length > 0) {
+      this.#decompressors[0].end()
+      this.#cleanupDecompressors()
+      return
+    }
+    super.onResponseEnd(controller, trailers)
+  }
+
+  /**
+   * @param {Controller} controller
+   * @param {Error} err
+   * @returns {void}
+   */
+  onResponseError (controller, err) {
+    if (this.#decompressors.length > 0) {
+      for (const decompressor of this.#decompressors) {
+        decompressor.destroy(err)
+      }
+      this.#cleanupDecompressors()
+    }
+    super.onResponseError(controller, err)
+  }
+}
+
+/**
+ * Creates a decompression interceptor for HTTP responses
+ * @param {DecompressHandlerOptions} [options] - Options for the interceptor
+ * @returns {Function} - Interceptor function
+ */
+function createDecompressInterceptor (options = {}) {
+  // Emit experimental warning only once
+  if (!warningEmitted) {
+    process.emitWarning(
+      'DecompressInterceptor is experimental and subject to change',
+      'ExperimentalWarning'
+    )
+    warningEmitted = true
+  }
+
+  return (dispatch) => {
+    return (opts, handler) => {
+      const decompressHandler = new DecompressHandler(handler, options)
+      return dispatch(opts, decompressHandler)
+    }
+  }
+}
+
+module.exports = createDecompressInterceptor

package/lib/llhttp/constants.d.ts

@@ -15,7 +15,7 @@ export declare const H_METHOD_MAP: {
     [k: string]: number;
 };
 export declare const STATUSES_HTTP: number[];
-export type CharList = Array<string | number>;
+export type CharList = (string | number)[];
 export declare const ALPHA: CharList;
 export declare const NUM_MAP: {
     0: number;
@@ -95,3 +95,101 @@ export declare const SPECIAL_HEADERS: {
     'transfer-encoding': number;
     upgrade: number;
 };
+declare const _default: {
+    ERROR: IntDict;
+    TYPE: IntDict;
+    FLAGS: IntDict;
+    LENIENT_FLAGS: IntDict;
+    METHODS: IntDict;
+    STATUSES: IntDict;
+    FINISH: IntDict;
+    HEADER_STATE: IntDict;
+    ALPHA: CharList;
+    NUM_MAP: {
+        0: number;
+        1: number;
+        2: number;
+        3: number;
+        4: number;
+        5: number;
+        6: number;
+        7: number;
+        8: number;
+        9: number;
+    };
+    HEX_MAP: {
+        0: number;
+        1: number;
+        2: number;
+        3: number;
+        4: number;
+        5: number;
+        6: number;
+        7: number;
+        8: number;
+        9: number;
+        A: number;
+        B: number;
+        C: number;
+        D: number;
+        E: number;
+        F: number;
+        a: number;
+        b: number;
+        c: number;
+        d: number;
+        e: number;
+        f: number;
+    };
+    NUM: CharList;
+    ALPHANUM: CharList;
+    MARK: CharList;
+    USERINFO_CHARS: CharList;
+    URL_CHAR: CharList;
+    HEX: CharList;
+    TOKEN: CharList;
+    HEADER_CHARS: CharList;
+    CONNECTION_TOKEN_CHARS: CharList;
+    QUOTED_STRING: CharList;
+    HTAB_SP_VCHAR_OBS_TEXT: CharList;
+    MAJOR: {
+        0: number;
+        1: number;
+        2: number;
+        3: number;
+        4: number;
+        5: number;
+        6: number;
+        7: number;
+        8: number;
+        9: number;
+    };
+    MINOR: {
+        0: number;
+        1: number;
+        2: number;
+        3: number;
+        4: number;
+        5: number;
+        6: number;
+        7: number;
+        8: number;
+        9: number;
+    };
+    SPECIAL_HEADERS: {
+        connection: number;
+        'content-length': number;
+        'proxy-connection': number;
+        'transfer-encoding': number;
+        upgrade: number;
+    };
+    METHODS_HTTP: number[];
+    METHODS_ICE: number[];
+    METHODS_RTSP: number[];
+    METHOD_MAP: IntDict;
+    H_METHOD_MAP: {
+        [k: string]: number;
+    };
+    STATUSES_HTTP: number[];
+};
+export default _default;