undici 8.2.0 → 8.4.0

package/README.md

@@ -21,28 +21,65 @@ npm i undici
 
 ## Benchmarks
 
-The benchmark is a simple getting data [example](https://github.com/nodejs/undici/blob/main/benchmarks/benchmark.js) using a
-50 TCP connections with a pipelining depth of 10 running on Node 22.11.0.
+The benchmark is a simple getting data [example](https://github.com/nodejs/undici/blob/main/benchmarks/benchmark.js) using
+50 TCP connections with a pipelining depth of 10 running on Node 24.14.1.
+
+### HTTP/1.1
 
 ```
 ┌────────────────────────┬─────────┬────────────────────┬────────────┬─────────────────────────┐
 │  Tests                 │ Samples │ Result             │ Tolerance  │ Difference with slowest │
 ├────────────────────────┼─────────┼────────────────────┼────────────┼─────────────────────────┤
-│  'axios'               │ 15      │ '5708.26 req/sec'  │ '± 2.91 %' │ '-'                     │
-│  'http - no keepalive' │ 10      │ '5809.80 req/sec'  │ '± 2.30 %' │ '+ 1.78 %'              │
-│  'request'             │ 30      │ '5828.80 req/sec'  │ '± 2.91 %' │ '+ 2.11 %'              │
-│  'undici - fetch'      │ 40      │ '5903.78 req/sec'  │ '± 2.87 %' │ '+ 3.43 %'              │
-│  'node-fetch'          │ 10      │ '5945.40 req/sec'  │ '± 2.13 %' │ '+ 4.15 %'              │
-│  'got'                 │ 35      │ '6511.45 req/sec'  │ '± 2.84 %' │ '+ 14.07 %'             │
-│  'http - keepalive'    │ 65      │ '9193.24 req/sec'  │ '± 2.92 %' │ '+ 61.05 %'             │
-│  'superagent'          │ 35      │ '9339.43 req/sec'  │ '± 2.95 %' │ '+ 63.61 %'             │
-│  'undici - pipeline'   │ 50      │ '13364.62 req/sec' │ '± 2.93 %' │ '+ 134.13 %'            │
-│  'undici - stream'     │ 95      │ '18245.36 req/sec' │ '± 2.99 %' │ '+ 219.63 %'            │
-│  'undici - request'    │ 50      │ '18340.17 req/sec' │ '± 2.84 %' │ '+ 221.29 %'            │
-│  'undici - dispatch'   │ 40      │ '22234.42 req/sec' │ '± 2.94 %' │ '+ 289.51 %'            │
+│  'node-fetch'          │ 50      │ '4711.86 req/sec'  │ '± 2.92 %' │ '-'                     │
+│  'undici - fetch'      │ 75      │ '5438.50 req/sec'  │ '± 2.97 %' │ '+ 15.42 %'             │
+│  'axios'               │ 45      │ '5448.08 req/sec'  │ '± 2.98 %' │ '+ 15.62 %'             │
+│  'request'             │ 65      │ '5809.63 req/sec'  │ '± 2.90 %' │ '+ 23.30 %'             │
+│  'http - no keepalive' │ 35      │ '5910.77 req/sec'  │ '± 2.87 %' │ '+ 25.44 %'             │
+│  'got'                 │ 50      │ '6047.80 req/sec'  │ '± 2.91 %' │ '+ 28.35 %'             │
+│  'superagent'          │ 60      │ '7534.53 req/sec'  │ '± 2.97 %' │ '+ 59.91 %'             │
+│  'http - keepalive'    │ 75      │ '9343.41 req/sec'  │ '± 2.90 %' │ '+ 98.30 %'             │
+│  'undici - pipeline'   │ 65      │ '13470.70 req/sec' │ '± 2.93 %' │ '+ 185.89 %'            │
+│  'undici - request'    │ 80      │ '16850.87 req/sec' │ '± 2.93 %' │ '+ 257.63 %'            │
+│  'undici - stream'     │ 101     │ '18488.56 req/sec' │ '± 3.81 %' │ '+ 292.38 %'            │
+│  'undici - dispatch'   │ 101     │ '20786.44 req/sec' │ '± 3.08 %' │ '+ 341.15 %'            │
 └────────────────────────┴─────────┴────────────────────┴────────────┴─────────────────────────┘
 ```
 
+### HTTP/1.1 over HTTPS
+
+Using [benchmark-https.js](https://github.com/nodejs/undici/blob/main/benchmarks/benchmark-https.js) against an h1-over-TLS server (50 connections, pipelining depth 10, Node 24.14.1).
+
+```
+┌────────────────────────┬─────────┬───────────────────┬────────────┬─────────────────────────┐
+│  Tests                 │ Samples │ Result            │ Tolerance  │ Difference with slowest │
+├────────────────────────┼─────────┼───────────────────┼────────────┼─────────────────────────┤
+│  'https - no keepalive'│ 10      │ '1358.40 req/sec' │ '± 1.99 %' │ '-'                     │
+│  'undici - fetch'      │ 30      │ '3721.76 req/sec' │ '± 2.97 %' │ '+ 173.98 %'            │
+│  'https - keepalive'   │ 35      │ '5633.91 req/sec' │ '± 2.84 %' │ '+ 314.75 %'            │
+│  'undici - pipeline'   │ 15      │ '6254.05 req/sec' │ '± 2.80 %' │ '+ 360.40 %'            │
+│  'undici - request'    │ 25      │ '6669.80 req/sec' │ '± 2.73 %' │ '+ 391.01 %'            │
+│  'undici - stream'     │ 25      │ '7019.04 req/sec' │ '± 2.77 %' │ '+ 416.71 %'            │
+│  'undici - dispatch'   │ 20      │ '7361.85 req/sec' │ '± 2.90 %' │ '+ 441.95 %'            │
+└────────────────────────┴─────────┴───────────────────┴────────────┴─────────────────────────┘
+```
+
+### HTTP/2
+
+Using [benchmark-http2.js](https://github.com/nodejs/undici/blob/main/benchmarks/benchmark-http2.js) against an h2 server (50 connections, pipelining depth 10, Node 24.14.1).
+
+```
+┌────────────────────────┬─────────┬───────────────────┬────────────┬─────────────────────────┐
+│  Tests                 │ Samples │ Result            │ Tolerance  │ Difference with slowest │
+├────────────────────────┼─────────┼───────────────────┼────────────┼─────────────────────────┤
+│  'undici - fetch'      │ 45      │ '3499.03 req/sec' │ '± 2.93 %' │ '-'                     │
+│  'native - http2'      │ 25      │ '4904.58 req/sec' │ '± 2.81 %' │ '+ 40.17 %'             │
+│  'undici - pipeline'   │ 60      │ '5836.82 req/sec' │ '± 2.99 %' │ '+ 66.81 %'             │
+│  'undici - request'    │ 65      │ '6831.25 req/sec' │ '± 2.83 %' │ '+ 95.23 %'             │
+│  'undici - stream'     │ 55      │ '6874.30 req/sec' │ '± 2.91 %' │ '+ 96.46 %'             │
+│  'undici - dispatch'   │ 55      │ '7791.23 req/sec' │ '± 2.96 %' │ '+ 122.67 %'            │
+└────────────────────────┴─────────┴───────────────────┴────────────┴─────────────────────────┘
+```
+
 ## Undici vs. Fetch
 
 ### Overview
@@ -200,7 +237,9 @@ await fetch('https://example.com', {
 ```
 
 `install()` replaces the global `fetch`, `Headers`, `Response`, `Request`, and
-`FormData` implementations with undici's versions, so they all match.
+`FormData` implementations with undici's versions, so they all match. It also
+installs undici's `WebSocket`, `CloseEvent`, `ErrorEvent`, `MessageEvent`, and
+`EventSource` globals.
 
 Avoid mixing a global `FormData` with `undici.fetch()`, or `undici.FormData`
 with the built-in global `fetch()`.
@@ -283,12 +322,12 @@ const data2 = await getData();
 
 ## Global Installation
 
-Undici provides an `install()` function to add all WHATWG fetch classes to `globalThis`, making them available globally:
+Undici provides an `install()` function to add fetch-related and other web API classes to `globalThis`, making them available globally:
 
 ```js
 import { install } from 'undici'
 
-// Install all WHATWG fetch classes globally
+// Install undici's global web APIs
 install()
 
 // Now you can use fetch classes globally without importing
@@ -316,8 +355,9 @@ The `install()` function adds the following classes to `globalThis`:
 
 When you call `install()`, these globals come from the same undici
 implementation. For example, global `fetch` and global `FormData` will both be
-undici's versions, which is the recommended setup if you want to use undici
-through globals.
+undici's versions, and `WebSocket` and `EventSource` will also come from
+undici, which is the recommended setup if you want to use undici through
+globals.
 
 This is useful for:
 - Polyfilling environments that don't have fetch
@@ -337,6 +377,9 @@ The `body` mixins are the most common way to format the request/response body. M
 > [!NOTE]
 > The body returned from `undici.request` does not implement `.formData()`.
 
+> [!WARNING]
+> Calling `body.formData()` on a fetch response causes undici to buffer and parse the entire body. Since this is dictated by the spec, `body.formData()` must only be called on responses from trusted servers.
+
 Example usage:
 
 ```js
@@ -737,10 +780,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:
 
 | 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  |
+|----------------|--------------------|----------------------------|-------------|
+| 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) | 2027-04-30  |
+| 7.x            | 24.x               | ≥20.18.1 (tested: 20, 22, 24) | 2028-04-30  |
+| 8.x            | 26.x               | ≥22.19.0 (tested: 22, 24, 26) | 2029-04-30  |
 
 ## License
 

package/docs/docs/api/Agent.md

@@ -21,6 +21,9 @@ Extends: [`PoolOptions`](/docs/docs/api/Pool.md#parameter-pooloptions)
 * **factory** `(origin: URL, opts: Object) => Dispatcher` - Default: `(origin, opts) => new Pool(origin, opts)`
 * **maxOrigins** `number` (optional) - Default: `Infinity` - Limits the total number of origins that can receive requests at a time, throwing an `MaxOriginsReachedError` error when attempting to dispatch when the max is reached. If `Infinity`, no limit is enforced.
 
+> [!NOTE]
+> Like `Pool`, `Agent` inherits all [`ClientOptions`](/docs/docs/api/Client.md#parameter-clientoptions). `allowH2` defaults to `true` and `maxConcurrentStreams` to `100`. The per-origin `Pool` it creates uses the default unlimited `connections`, so concurrent requests to the same origin land on separate `Client` instances and separate TCP/TLS sockets — HTTP/2 multiplexing on a shared session does not apply unless `connections` is set to a small value. See [`PoolOptions`](/docs/docs/api/Pool.md#parameter-pooloptions).
+
 ## Instance Properties
 
 ### `Agent.closed`

package/docs/docs/api/Client.md

@@ -26,14 +26,16 @@ Returns: `Client`
 * **maxResponseSize** `number | null` (optional) - Default: `-1` - The maximum length of response body in bytes. Set to `-1` to disable.
 * **webSocket** `WebSocketOptions` (optional) - WebSocket-specific configuration options.
   * **maxPayloadSize** `number` (optional) - Default: `134217728` (128 MB) - Maximum allowed payload size in bytes for WebSocket messages. Applied to uncompressed messages, compressed frame payloads, and decompressed (permessage-deflate) messages. Set to 0 to disable the limit.
-* **pipelining** `number | null` (optional) - Default: `1` - The amount of concurrent requests to be sent over the single TCP/TLS connection according to [RFC7230](https://tools.ietf.org/html/rfc7230#section-6.3.2). Carefully consider your workload and environment before enabling concurrent requests as pipelining may reduce performance if used incorrectly. Pipelining is sensitive to network stack settings as well as head of line blocking caused by e.g. long running requests. Set to `0` to disable keep-alive connections.
-* **connect** `ConnectOptions | Function | null` (optional) - Default: `null`.
+* **pipelining** `number | null` (optional) - Default: `1` - The amount of concurrent requests to be sent over the single TCP/TLS connection according to [RFC7230](https://tools.ietf.org/html/rfc7230#section-6.3.2). Carefully consider your workload and environment before enabling concurrent requests as pipelining may reduce performance if used incorrectly. Pipelining is sensitive to network stack settings as well as head of line blocking caused by e.g. long running requests. Set to `0` to disable keep-alive connections. This option has no effect once HTTP/2 is negotiated — see `maxConcurrentStreams` for the h2 dispatch ceiling.
+* **connect** `ConnectOptions | Function | null` (optional) - Default: `null` - Configures how undici establishes TCP/TLS connections. Accepts two forms:
+  * **Object (`ConnectOptions`)**: Options passed directly to the internal [`buildConnector()`](/docs/docs/api/Connector.md). This is the simplest way to customize TLS or socket behavior (e.g., setting `rejectUnauthorized`, `ca`, `socketPath`). See [`ConnectOptions`](#parameter-connectoptions) for available fields.
+  * **Function**: A custom connector with the signature `(options, callback)`, where `options` contains `{ hostname, host, protocol, port, servername, localAddress, httpSocket }` and `callback` follows `(error, socket)`. Useful when you need full control over socket creation, such as adding custom validation or proxy logic. When a function is provided, undici wraps it to automatically inject `socketPath` and `allowH2` into the `options` argument if those values are set on the client.
 * **strictContentLength** `Boolean` (optional) - Default: `true` - Whether to treat request content length mismatches as errors. If true, an error is thrown when the request content-length header doesn't match the length of the request body. **Security Warning:** Disabling this option can expose your application to HTTP Request Smuggling attacks, where mismatched content-length headers cause servers and proxies to interpret request boundaries differently. This can lead to cache poisoning, credential hijacking, and bypassing security controls. Only disable this in controlled environments where you fully trust the request source.
 * **autoSelectFamily**: `boolean` (optional) - Default: depends on local Node version, on Node 18.13.0 and above is `false`. Enables a family autodetection algorithm that loosely implements section 5 of [RFC 8305](https://tools.ietf.org/html/rfc8305#section-5). See [here](https://nodejs.org/api/net.html#socketconnectoptions-connectlistener) for more details. This option is ignored if not supported by the current Node version.
 * **autoSelectFamilyAttemptTimeout**: `number` - Default: depends on local Node version, on Node 18.13.0 and above is `250`. The amount of time in milliseconds to wait for a connection attempt to finish before trying the next address when using the `autoSelectFamily` option. See [here](https://nodejs.org/api/net.html#socketconnectoptions-connectlistener) for more details.
 * **allowH2**: `boolean` - Default: `true`. Enables support for H2 if the server has assigned bigger priority to it through ALPN negotiation.
 * **useH2c**: `boolean` - Default: `false`. Enforces h2c for non-https connections.
-* **maxConcurrentStreams**: `number` - Default: `100`. Dictates the maximum number of concurrent streams for a single H2 session. It can be overridden by a SETTINGS remote frame.
+* **maxConcurrentStreams**: `number` - Default: `100`. The maximum number of concurrent HTTP/2 streams per session. When `allowH2` negotiates h2, this — not `pipelining` (which is HTTP/1.1 only, per [RFC7230](https://tools.ietf.org/html/rfc7230#section-6.3.2)) — is the ceiling the Client uses to dispatch in-flight requests on a shared session. The same value is advertised to the server as `peerMaxConcurrentStreams`, capping how many streams the server may push back. The initial value is replaced by the server's `SETTINGS_MAX_CONCURRENT_STREAMS` whenever the server sends one, so a user-supplied value acts as a pre-`SETTINGS` default rather than a hard cap.
 * **initialWindowSize**: `number` (optional) - Default: `262144` (256KB). Sets the HTTP/2 stream-level flow-control window size (SETTINGS_INITIAL_WINDOW_SIZE). Must be a positive integer greater than 0. This default is higher than Node.js core's default (65535 bytes) to improve throughput, Node's choice is very conservative for current high-bandwith networks. See [RFC 7540 Section 6.9.2](https://datatracker.ietf.org/doc/html/rfc7540#section-6.9.2) for more details.
 * **connectionWindowSize**: `number` (optional) - Default `524288` (512KB). Sets the HTTP/2 connection-level flow-control window size using `ClientHttp2Session.setLocalWindowSize()`. Must be a positive integer greater than 0. This provides better flow control for the entire connection across multiple streams. See [Node.js HTTP/2 documentation](https://nodejs.org/api/http2.html#clienthttp2sessionsetlocalwindowsize) for more details.
 * **pingInterval**: `number` - Default: `60e3`. The time interval in milliseconds between PING frames sent to the server. Set to `0` to disable PING frames. This is only applicable for HTTP/2 connections. This will emit a `ping` event on the client with the duration of the ping in milliseconds.
@@ -72,9 +74,43 @@ import { Client } from 'undici'
 const client = new Client('http://localhost:3000')
 ```
 
-### Example - Custom connector
+### Example - Connect with TLS options (object form)
 
-This will allow you to perform some additional check on the socket that will be used for the next request.
+Pass a `ConnectOptions` object to customize the TLS connection. The options are forwarded to the internal `buildConnector()`.
+
+```js
+'use strict'
+import { Client } from 'undici'
+import fs from 'node:fs'
+
+const client = new Client('https://localhost:3000', {
+  connect: {
+    rejectUnauthorized: false,
+    ca: fs.readFileSync('./ca-cert.pem')
+  }
+})
+```
+
+### Example - Connect via Unix domain socket
+
+Use the `socketPath` option to connect through an IPC endpoint instead of a TCP connection.
+
+```js
+'use strict'
+import { Client } from 'undici'
+
+const client = new Client('http://localhost:3000', {
+  connect: {
+    socketPath: '/var/run/docker.sock'
+  }
+})
+```
+
+### Example - Custom connector (function form)
+
+Pass a function for full control over socket creation. This allows you to perform additional checks on the socket, use a proxy, or implement custom connection logic.
+
+> **Note:** When a function is provided, undici wraps it to automatically inject `socketPath` and `allowH2` into the first argument (`options`) when those values are set on the client.
 
 ```js
 'use strict'
@@ -97,6 +133,8 @@ const client = new Client('https://localhost:3000', {
 })
 ```
 
+For more details on building custom connectors, see [Connector](/docs/docs/api/Connector.md).
+
 ## Instance Methods
 
 ### `Client.close([callback])`

package/docs/docs/api/Connector.md

@@ -13,6 +13,7 @@ Every Tls option, see [here](https://nodejs.org/api/tls.html#tls_tls_connect_opt
 Furthermore, the following options can be passed:
 
 * **socketPath** `string | null` (optional) - Default: `null` - An IPC endpoint, either Unix domain socket or Windows named pipe.
+* **preferH2** `boolean` (optional) - Default: `false` - Only effective together with `allowH2`. When `true`, ALPN is offered as `['h2', 'http/1.1']` (HTTP/2 first) instead of the default `['http/1.1', 'h2']`. Use this when the server selects the ALPN protocol by *client* preference (e.g. some load balancers) so that HTTP/2 is negotiated whenever the server supports it. If the server does not support HTTP/2, ALPN transparently falls back to `http/1.1`.
 * **maxCachedSessions** `number | null` (optional) - Default: `100` - Maximum number of TLS cached sessions. Use 0 to disable TLS session caching. Default: `100`.
 * **timeout** `number | null` (optional) -  In milliseconds. Default `10e3`.
 * **servername** `string | null` (optional)

package/docs/docs/api/Dispatcher.md

@@ -991,6 +991,13 @@ The `redirect` interceptor allows you to customize the way your dispatcher handl
 
 It accepts the same arguments as the [`RedirectHandler` constructor](/docs/docs/api/RedirectHandler.md).
 
+Options:
+
+- **maxRedirections** `number` - Maximum number of redirections allowed.
+- **throwOnMaxRedirect** `boolean` - Throw when the maximum number of redirections is reached.
+- **stripHeadersOnRedirect** `string[]` - Header names to remove from all redirected requests.
+- **stripHeadersOnCrossOriginRedirect** `string[]` - Header names to remove from cross-origin redirected requests.
+
 **Example - Basic Redirect Interceptor**
 
 ```js

package/docs/docs/api/Errors.md

@@ -27,8 +27,20 @@ import { errors } from 'undici'
 | `ResponseExceededMaxSizeError`       | `UND_ERR_RES_EXCEEDED_MAX_SIZE`       | response body exceed the max size allowed                                 |
 | `SecureProxyConnectionError`         | `UND_ERR_PRX_TLS`                     | tls connection to a proxy failed                                          |
 | `MessageSizeExceededError`           | `UND_ERR_WS_MESSAGE_SIZE_EXCEEDED`    | WebSocket decompressed message exceeded the maximum allowed size          |
+| `AbortError`                         | `UND_ERR_ABORT`                       | the operation was aborted (base class of `RequestAbortedError`).          |
+| `RequestRetryError`                  | `UND_ERR_REQ_RETRY`                   | request failed and could not be retried; carries `statusCode`, `headers` and `data`. |
+| `ResponseError`                      | `UND_ERR_RESPONSE`                    | response returned an error status code; carries `statusCode`, `headers` and `body`.  |
+| `MaxOriginsReachedError`             | `UND_ERR_MAX_ORIGINS_REACHED`         | the maximum number of allowed origins has been reached.                   |
+| `BalancedPoolMissingUpstreamError`   | `UND_ERR_BPL_MISSING_UPSTREAM`        | no upstream has been added to the `BalancedPool`.                         |
+| `Socks5ProxyError`                   | `UND_ERR_SOCKS5*`                     | an error occurred during SOCKS5 proxy negotiation.                        |
+| `HTTPParserError`                    | `HPE_*`                               | an error occurred while parsing the HTTP response (extends `Error`, not `UndiciError`). |
 
 Be aware of the possible difference between the global dispatcher version and the actual undici version you might be using. We recommend to avoid the check `instanceof errors.UndiciError` and seek for the `error.code === '<error_code>'` instead to avoid inconsistencies.
+
+### `ConnectTimeoutError`
+
+When `autoSelectFamily` is enabled and every attempted address fails with a timeout, Node raises an `AggregateError`. Undici surfaces these multi-address timeouts as `ConnectTimeoutError` (so the error shape is the same regardless of whether Node's family-attempt timer or undici's `connectTimeout` wins the race); the original `AggregateError` is preserved on `error.cause`.
+
 ### `SocketError`
 
 The `SocketError` has a `.socket` property which holds socket metadata:

package/docs/docs/api/EventSource.md

@@ -7,7 +7,7 @@ for [Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server
 
 ## Instantiating EventSource
 
-Undici exports a EventSource class. You can instantiate the EventSource as
+Undici exports an EventSource class. You can instantiate the EventSource as
 follows:
 
 ```mjs
@@ -19,9 +19,57 @@ eventSource.onmessage = (event) => {
 }
 ```
 
+## Receiving events from a server
+
+EventSource connects to an HTTP endpoint that responds with a `text/event-stream`
+content type. The connection stays open and receives events as the server writes
+them.
+
+```mjs
+import { createServer } from 'node:http'
+import { EventSource } from 'undici'
+
+const server = createServer((request, response) => {
+  response.writeHead(200, {
+    'content-type': 'text/event-stream',
+    'cache-control': 'no-cache',
+    connection: 'keep-alive'
+  })
+
+  response.write('event: ping\n')
+  response.write('data: connected\n\n')
+
+  const interval = setInterval(() => {
+    response.write(`data: ${Date.now()}\n\n`)
+  }, 1000)
+
+  request.on('close', () => clearInterval(interval))
+})
+
+server.listen(3000, () => {
+  const eventSource = new EventSource('http://localhost:3000')
+
+  eventSource.addEventListener('ping', (event) => {
+    console.log('ping:', event.data)
+  })
+
+  eventSource.onmessage = (event) => {
+    console.log('message:', event.data)
+  }
+
+  eventSource.onerror = () => {
+    eventSource.close()
+    server.close()
+  }
+})
+```
+
+The `message` event receives events without an explicit `event:` field. Use
+`addEventListener()` to subscribe to named events.
+
 ## Using a custom Dispatcher
 
-undici allows you to set your own Dispatcher in the EventSource constructor.
+Undici allows you to set your own Dispatcher in the EventSource constructor.
 
 An example which allows you to modify the request headers is:
 
@@ -38,7 +86,6 @@ class CustomHeaderAgent extends Agent {
 const eventSource = new EventSource('http://localhost:3000', {
   dispatcher: new CustomHeaderAgent()
 })
-
 ```
 
 More information about the EventSource API can be found on

package/docs/docs/api/Fetch.md

@@ -41,7 +41,9 @@ This API is implemented as per the standard, you can find documentation on [MDN]
 - [`.json()`](https://fetch.spec.whatwg.org/#dom-body-json)
 - [`.text()`](https://fetch.spec.whatwg.org/#dom-body-text)
 
-There is an ongoing discussion regarding `.formData()` and its usefulness and performance in server environments. It is recommended to use a dedicated library for parsing `multipart/form-data` bodies, such as [Busboy](https://www.npmjs.com/package/busboy) or [@fastify/busboy](https://www.npmjs.com/package/@fastify/busboy).
+There is an ongoing discussion regarding `body.formData()` and its usefulness, performance, and security in server environments. Calling `body.formData()` causes undici to buffer and parse the entire body. Because multipart parsing has inherent security risks, `body.formData()` must only be called on responses from trusted servers.
+
+For responses from untrusted or user-controlled servers, use a dedicated streaming library for parsing `multipart/form-data` bodies, such as [Busboy](https://www.npmjs.com/package/busboy) or [@fastify/busboy](https://www.npmjs.com/package/@fastify/busboy), and apply application-specific limits.
 
 These libraries can be interfaced with fetch with the following example code:
 

package/docs/docs/api/GlobalInstallation.md

@@ -1,17 +1,17 @@
 # Global Installation
 
-Undici provides an `install()` function to add all WHATWG fetch classes to `globalThis`, making them available globally without requiring imports.
+Undici provides an `install()` function to add fetch-related and other web API classes to `globalThis`, making them available globally without requiring imports.
 
 ## `install()`
 
-Install all WHATWG fetch classes globally on `globalThis`.
+Install undici's global web APIs on `globalThis`.
 
 **Example:**
 
 ```js
 import { install } from 'undici'
 
-// Install all WHATWG fetch classes globally  
+// Install undici's global web APIs
 install()
 
 // Now you can use fetch classes globally without importing
@@ -74,6 +74,8 @@ await fetch('https://example.com', {
 
 After `install()`, `fetch`, `Headers`, `Response`, `Request`, and `FormData`
 all come from the installed `undici` package, so they work as a matching set.
+`WebSocket`, `CloseEvent`, `ErrorEvent`, `MessageEvent`, and `EventSource`
+also come from the installed `undici` package.
 
 If you do not want to install globals, import both from `undici` instead:
 
@@ -135,5 +137,5 @@ test('fetch API test', async () => {
 
 - The `install()` function overwrites any existing global implementations
 - Classes installed are undici's implementations, not Node.js built-ins
-- This provides access to undici's latest features and performance improvements
-- The global installation persists for the lifetime of the process
+- This provides access to undici's latest fetch, WebSocket, and EventSource features and performance improvements
+- The global installation persists for the lifetime of the process

package/docs/docs/api/H2CClient.md

@@ -46,8 +46,8 @@ Returns: `H2CClient`
 - **keepAliveTimeoutThreshold** `number | null` (optional) - Default: `2e3` - A number of milliseconds subtracted from server _keep-alive_ hints when overriding `keepAliveTimeout` to account for timing inaccuracies caused by e.g. transport latency. Defaults to 2 seconds.
 - **maxHeaderSize** `number | null` (optional) - Default: `--max-http-header-size` or `16384` - The maximum length of request headers in bytes. Defaults to Node.js' --max-http-header-size or 16KiB.
 - **maxResponseSize** `number | null` (optional) - Default: `-1` - The maximum length of response body in bytes. Set to `-1` to disable.
-- **maxConcurrentStreams**: `number` - Default: `100`. Dictates the maximum number of concurrent streams for a single H2 session. It can be overridden by a SETTINGS remote frame.
-- **pipelining** `number | null` (optional) - Default to `maxConcurrentStreams` - The amount of concurrent requests sent over a single HTTP/2 session in accordance with [RFC-7540](https://httpwg.org/specs/rfc7540.html#StreamsLayer) Stream specification. Streams can be closed up by remote server at any time.
+- **maxConcurrentStreams**: `number` - Default: `100`. The maximum number of concurrent HTTP/2 streams per session — also advertised to the server as `peerMaxConcurrentStreams` (the cap on streams the server may push back). The initial value is replaced by the server's `SETTINGS_MAX_CONCURRENT_STREAMS` whenever the server sends one, so a user-supplied value acts as a pre-`SETTINGS` default rather than a hard cap.
+- **pipelining** `number | null` (optional) - Default to `maxConcurrentStreams` - The amount of concurrent requests sent over a single HTTP/2 session in accordance with [RFC-7540](https://httpwg.org/specs/rfc7540.html#StreamsLayer) Stream specification. Streams can be closed up by remote server at any time. Unlike on a regular [`Client`](/docs/docs/api/Client.md), `H2CClient` aliases `pipelining` to `maxConcurrentStreams` at construction time, so the two move together.
 - **pingInterval**: `number` - Default: `60e3`. The time interval in milliseconds between PING frames sent to the server. Set to `0` to disable PING frames. This is only applicable for HTTP/2 connections.
 - **connect** `ConnectOptions | null` (optional) - Default: `null`.
 - **strictContentLength** `Boolean` (optional) - Default: `true` - Whether to treat request content length mismatches as errors. If true, an error is thrown when the request content-length header doesn't match the length of the request body. **Security Warning:** Disabling this option can expose your application to HTTP Request Smuggling attacks, where mismatched content-length headers cause servers and proxies to interpret request boundaries differently. This can lead to cache poisoning, credential hijacking, and bypassing security controls. Only disable this in controlled environments where you fully trust the request source.

package/docs/docs/api/Pool.md

@@ -21,6 +21,9 @@ Extends: [`ClientOptions`](/docs/docs/api/Client.md#parameter-clientoptions)
 * **connections** `number | null` (optional) - Default: `null` - The number of `Client` instances to create. When set to `null`, the `Pool` instance will create an unlimited amount of `Client` instances.
 * **clientTtl** `number | null` (optional) - Default: `null` - The amount of time before a `Client` instance is removed from the `Pool` and closed.   When set to `null`, `Client` instances will not be removed or closed based on age.
 
+> [!NOTE]
+> `Pool` inherits all [`ClientOptions`](/docs/docs/api/Client.md#parameter-clientoptions), including `allowH2` (default `true`) and `maxConcurrentStreams` (default `100`). With the unlimited default of `connections`, `Pool` will open a new `Client` — and therefore a new TCP/TLS socket — per concurrent dispatch, which defeats HTTP/2 multiplexing on a shared session. To benefit from h2 multiplexing on a single session, cap `connections` (e.g. `connections: 1`) so that concurrent requests share a session up to `maxConcurrentStreams`.
+
 ## Instance Properties
 
 ### `Pool.closed`

package/docs/docs/api/RedirectHandler.md

@@ -8,7 +8,7 @@ Arguments:
 
 - **dispatch** `function` - The dispatch function to be called after every retry.
 - **maxRedirections** `number` - Maximum number of redirections allowed.
-- **opts** `object` - Options for handling redirection.
+- **opts** `object` - Options for handling redirection. Supports `throwOnMaxRedirect`, `stripHeadersOnRedirect`, and `stripHeadersOnCrossOriginRedirect`.
 - **handler** `object` - An object containing handlers for different stages of the request lifecycle.
 
 Returns: `RedirectHandler`
@@ -18,6 +18,9 @@ Returns: `RedirectHandler`
 - **dispatch** `(options: Dispatch.DispatchOptions, handlers: Dispatch.DispatchHandler) => Promise<Dispatch.DispatchResponse>` (required) - Dispatch function to be called after every redirection.
 - **maxRedirections** `number` (required) - Maximum number of redirections allowed.
 - **opts** `object` (required) - Options for handling redirection.
+  - **throwOnMaxRedirect** `boolean` - Throw when the maximum number of redirections is reached.
+  - **stripHeadersOnRedirect** `string[]` - Header names to remove from all redirected requests.
+  - **stripHeadersOnCrossOriginRedirect** `string[]` - Header names to remove from cross-origin redirected requests.
 - **handler** `object` (required) - Handlers for different stages of the request lifecycle.
 
 ### Properties

package/docs/docs/api/SnapshotAgent.md

@@ -27,7 +27,9 @@ new SnapshotAgent([options])
   - **ignoreHeaders** `Array<String>` - Headers to ignore during request matching
   - **excludeHeaders** `Array<String>` - Headers to exclude from snapshots (for security)
   - **matchBody** `Boolean` - Whether to include request body in matching. Default: `true`
+  - **normalizeBody** `Function` - Optional function `(body) => string` to normalize the request body before matching (e.g. strip volatile fields like timestamps). Only used when `matchBody` is `true`.
   - **matchQuery** `Boolean` - Whether to include query parameters in matching. Default: `true`
+  - **normalizeQuery** `Function` - Optional function `(query: URLSearchParams) => string` to normalize query parameters before matching (e.g. strip volatile params like cache-busters). Only used when `matchQuery` is `true`.
   - **caseSensitive** `Boolean` - Whether header matching is case-sensitive. Default: `false`
   - **shouldRecord** `Function` - Callback to determine if a request should be recorded
   - **shouldPlayback** `Function` - Callback to determine if a request should be played back
@@ -108,6 +110,27 @@ await agent.saveSnapshots('./custom-snapshots.json')
 
 ## Advanced Configuration
 
+### Body Matching
+
+By default (`matchBody: true`) the full request body string is included in the snapshot key. Set it to `false` to ignore the body entirely, or use `normalizeBody` to strip volatile fields (like timestamps) before matching:
+
+```javascript
+const agent = new SnapshotAgent({
+  mode: 'playback',
+  snapshotPath: './snapshots.json',
+
+  // Match on everything except the timestamp field
+  normalizeBody: (body) => {
+    if (!body) return ''
+    const parsed = JSON.parse(String(body))
+    delete parsed.timestamp
+    return JSON.stringify(parsed)
+  }
+})
+```
+
+`normalizeBody` receives the raw body (`string | Buffer | null | undefined`) and must return a `string`. It runs at both record and playback time so the hash is consistent. Two requests match the same snapshot whenever their normalized strings are identical.
+
 ### Header Filtering
 
 Control which headers are used for request matching and what gets stored in snapshots:

package/lib/api/api-pipeline.js

@@ -13,6 +13,7 @@ const {
   RequestAbortedError
 } = require('../core/errors')
 const util = require('../core/util')
+const { kBodyUsed } = require('../core/symbols')
 const { addSignal, removeSignal } = require('./abort-signal')
 
 function noop () {}
@@ -24,6 +25,9 @@ class PipelineRequest extends Readable {
     super({ autoDestroy: true })
 
     this[kResume] = null
+    // Pipeline request bodies come from a live writable side and cannot be
+    // replayed across redirects or retries, even before any bytes are read.
+    this[kBodyUsed] = true
   }
 
   _read () {

package/lib/api/api-stream.js

@@ -1,7 +1,6 @@
 'use strict'
 
 const assert = require('node:assert')
-const { finished } = require('node:stream')
 const { AsyncResource } = require('node:async_hooks')
 const { InvalidArgumentError, InvalidReturnValueError } = require('../core/errors')
 const util = require('../core/util')
@@ -9,6 +8,54 @@ const { addSignal, removeSignal } = require('./abort-signal')
 
 function noop () {}
 
+function getWritableError (stream) {
+  return stream.errored ?? stream.writableErrored ?? stream._writableState?.errored
+}
+
+function createPrematureCloseError () {
+  const err = new Error('Premature close')
+  err.code = 'ERR_STREAM_PREMATURE_CLOSE'
+  return err
+}
+
+function trackWritableLifecycle (stream, callback) {
+  let done = false
+
+  const cleanup = () => {
+    stream.removeListener('close', onClose)
+    stream.removeListener('error', onError)
+    stream.removeListener('finish', onFinish)
+  }
+
+  const finish = (err, fromErrorEvent = false) => {
+    if (done) {
+      return
+    }
+
+    done = true
+    cleanup()
+    callback(err, fromErrorEvent)
+  }
+
+  const onClose = () => {
+    const err = getWritableError(stream)
+    finish(err ?? (!stream.writableFinished ? createPrematureCloseError() : undefined))
+  }
+
+  const onError = (err) => finish(err, true)
+  const onFinish = () => finish()
+
+  stream.on('close', onClose)
+  stream.on('error', onError)
+  stream.on('finish', onFinish)
+
+  if (stream.closed) {
+    process.nextTick(onClose)
+  } else if (stream.writableFinished) {
+    process.nextTick(onFinish)
+  }
+}
+
 class StreamHandler extends AsyncResource {
   constructor (opts, factory, callback) {
     if (!opts || typeof opts !== 'object') {
@@ -117,20 +164,19 @@ class StreamHandler extends AsyncResource {
       throw new InvalidReturnValueError('expected Writable')
     }
 
-    // TODO: Avoid finished. It registers an unnecessary amount of listeners.
-    finished(res, { readable: false }, (err) => {
+    trackWritableLifecycle(res, (err, fromErrorEvent) => {
       const { callback, res, opaque, trailers, abort } = this
 
       this.res = null
       if (err || !res?.readable) {
-        util.destroy(res, err)
+        util.destroy(res, fromErrorEvent ? undefined : err)
       }
 
       this.callback = null
       this.runInAsyncScope(callback, null, err || null, { opaque, trailers })
 
       if (err) {
-        abort()
+        abort(err)
       }
     })