deps: update undici to 8.5.0

Author: nodejs-github-bot

deps/undici/src/docs/docs/GettingStarted.md

@@ -0,0 +1,278 @@
+# Getting Started
+
+## Installation
+
+```bash
+npm install undici
+```
+
+## Fetch
+
+The quickest way to get started is with `fetch`, which follows the
+[Fetch Standard](https://fetch.spec.whatwg.org/) and works the same way as
+the browser API:
+
+```js
+import { fetch } from 'undici'
+
+const res = await fetch('https://example.com')
+const data = await res.json()
+console.log(data)
+```
+
+### Using the Request object
+
+undici also exports a `Request` class that follows the Fetch Standard:
+
+```js
+import { fetch, Request } from 'undici'
+
+const req = new Request('https://example.com', {
+  method: 'POST',
+  headers: { 'content-type': 'application/json' },
+  body: JSON.stringify({ hello: 'world' })
+})
+const res = await fetch(req)
+console.log(res.status)
+```
+
+### Streaming the response
+
+`res.body` is a web `ReadableStream`. Use `pipeline` from
+`node:stream/promises` to stream it to a file:
+
+```js
+import { fetch } from 'undici'
+import { pipeline } from 'node:stream/promises'
+import { createWriteStream } from 'node:fs'
+
+const res = await fetch('https://example.com/large-file.zip')
+await pipeline(res.body, createWriteStream('./file.zip'))
+```
+
+> Always consume or cancel the response body. In Node.js, garbage collection
+> is not aggressive enough to release connections promptly, so leaving a body
+> unread can cause connection leaks and stalled requests. See
+> [Specification Compliance - Garbage Collection](/docs/#garbage-collection)
+> for details.
+
+For more on `fetch`, see [API Reference: Fetch](/docs/docs/api/Fetch.md).
+
+## Dispatchers: Connection reuse and pooling
+
+By default, `fetch`, `request`, `stream`, and `pipeline` create a new connection
+for each call. For applications that make many requests to the same origin,
+this is wasteful. undici provides **dispatchers** that manage connections
+internally.
+
+### `Agent` — for requests to multiple origins
+
+`Agent` is the most general-purpose dispatcher. It pools connections per-origin
+and is the recommended default for most applications. Use it with
+`setGlobalDispatcher` to affect all undici calls globally:
+
+```js
+import { Agent, setGlobalDispatcher, fetch } from 'undici'
+
+const agent = new Agent({
+  keepAliveTimeout: 30_000,
+  keepAliveMaxTimeout: 600_000
+})
+setGlobalDispatcher(agent)
+
+// All subsequent fetch/request/stream/pipeline calls reuse connections
+const res = await fetch('https://api.example.com/data')
+```
+
+You can also pass a dispatcher per-request:
+
+```js
+await fetch('https://api.example.com/data', { dispatcher: agent })
+```
+
+### `Pool` — for requests to a single origin
+
+`Pool` manages a fixed set of connections to one origin. It gives you explicit
+control over concurrency:
+
+```js
+import { Pool, request } from 'undici'
+
+const pool = new Pool('https://api.example.com', { connections: 10 })
+
+const { body } = await request('https://api.example.com/data', {
+  dispatcher: pool
+})
+const data = await body.json()
+
+pool.close()
+```
+
+### `Client` — for a single connection
+
+`Client` maps to a single TCP connection. It supports pipelining (sending
+multiple requests before responses arrive):
+
+```js
+import { Client } from 'undici'
+
+const client = new Client('https://api.example.com', {
+  pipelining: 5
+})
+
+const { body } = await client.request({ path: '/', method: 'GET' })
+await body.dump()
+
+client.close()
+```
+
+For more on dispatcher options and lifecycle, see:
+- [API Reference: Agent](/docs/docs/api/Agent.md)
+- [API Reference: Pool](/docs/docs/api/Pool.md)
+- [API Reference: Client](/docs/docs/api/Client.md)
+
+## Timeouts
+
+undici applies timeouts at two levels:
+
+- **`headersTimeout`** — time to wait for response headers (default: 300s).
+- **`bodyTimeout`** — time between consecutive body chunks (default: 300s).
+
+Set these on the dispatcher or per-request:
+
+```js
+import { Agent, setGlobalDispatcher } from 'undici'
+
+const agent = new Agent({
+  headersTimeout: 5_000,
+  bodyTimeout: 30_000
+})
+
+setGlobalDispatcher(agent)
+```
+
+Timeout errors are thrown as `HeadersTimeoutError` and `BodyTimeoutError`.
+See [API Reference: Errors](/docs/docs/api/Errors.md) for the full list.
+
+## Error handling
+
+undici exposes structured errors via `error.code`:
+
+```js
+import { request, errors } from 'undici'
+
+try {
+  const { body } = await request('https://example.com')
+  await body.json()
+} catch (err) {
+  switch (err.code) {
+    case 'UND_ERR_CONNECT_TIMEOUT':
+      console.error('Connection timed out')
+      break
+    case 'UND_ERR_HEADERS_TIMEOUT':
+      console.error('Headers timed out')
+      break
+    case 'UND_ERR_BODY_TIMEOUT':
+      console.error('Body timed out')
+      break
+    case 'UND_ERR_ABORTED':
+      console.error('Request was aborted')
+      break
+    default:
+      console.error(err)
+  }
+}
+```
+
+### Aborting requests
+
+```js
+import { request } from 'undici'
+
+const ac = new AbortController()
+
+setTimeout(() => ac.abort(), 1000)
+
+try {
+  const { body } = await request('https://example.com', {
+    signal: ac.signal
+  })
+  await body.dump()
+} catch (err) {
+  console.error(err.code) // UND_ERR_ABORTED
+}
+```
+
+## Common patterns
+
+### Proxies
+
+Use `ProxyAgent` for HTTP(S) proxies, or `EnvHttpProxyAgent` to pick up
+proxy settings from environment variables:
+
+```js
+import { ProxyAgent, setGlobalDispatcher } from 'undici'
+
+const proxy = new ProxyAgent('http://proxy.internal:8080')
+setGlobalDispatcher(proxy)
+```
+
+See [Best Practices: Proxy](/docs/docs/best-practices/proxy.md) and
+[API Reference: ProxyAgent](/docs/docs/api/ProxyAgent.md).
+
+### Mocking in tests
+
+```js
+import { MockAgent, setGlobalDispatcher, request } from 'undici'
+
+const mockAgent = new MockAgent()
+setGlobalDispatcher(mockAgent)
+
+const mockPool = mockAgent.get('https://api.example.com')
+mockPool.intercept({ path: '/users' }).reply(200, [{ id: 1 }])
+
+const { body } = await request('https://api.example.com/users')
+console.log(await body.json())
+```
+
+See [Best Practices: Mocking Request](/docs/docs/best-practices/mocking-request.md)
+and [API Reference: MockAgent](/docs/docs/api/MockAgent.md).
+
+### Testing with undici
+
+For test suites, set short keep-alive timeouts to avoid slow teardowns:
+
+```js
+import { Agent, setGlobalDispatcher } from 'undici'
+
+const agent = new Agent({
+  keepAliveTimeout: 10,
+  keepAliveMaxTimeout: 10
+})
+setGlobalDispatcher(agent)
+```
+
+See [Best Practices: Writing Tests](/docs/docs/best-practices/writing-tests.md).
+
+### Customizing the global fetch
+
+You can override Node.js's built-in globals with `install()`:
+
+```js
+import { install } from 'undici'
+
+install()
+
+// Global fetch, Headers, Response, Request, and FormData
+// now come from undici, not the Node.js bundle
+const res = await fetch('https://example.com')
+```
+
+See [API Reference: Global Installation](/docs/docs/api/GlobalInstallation.md).
+
+## Further reading
+
+- [Undici vs. Built-in Fetch](/docs/docs/best-practices/undici-vs-builtin-fetch.md) —
+  when to install undici vs using Node.js built-in fetch
+- [API Reference](/docs/docs/api/Dispatcher.md) — full dispatcher API documentation
+- [Examples](/docs/examples/) — runnable code examples

deps/undici/src/docs/docs/api/BalancedPool.md

@@ -34,7 +34,7 @@ Implements [Client.closed](/docs/docs/api/Client.md#clientclosed)
 
 Implements [Client.destroyed](/docs/docs/api/Client.md#clientdestroyed)
 
-### `Pool.stats`
+### `BalancedPool.stats`
 
 Returns [`PoolStats`](/docs/docs/api/PoolStats.md) instance for this pool.
 

deps/undici/src/docs/docs/api/Client.md

@@ -25,6 +25,7 @@ Returns: `Client`
 * **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.
 * **webSocket** `WebSocketOptions` (optional) - WebSocket-specific configuration options.
+  * **maxFragments** `number` (optional) - Default: `131072` - Maximum number of fragments in a message. Set to 0 to disable the limit.
   * **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. 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:

deps/undici/src/docs/docs/api/Cookies.md

@@ -10,7 +10,7 @@
 * **path** `string` (optional)
 * **secure** `boolean` (optional)
 * **httpOnly** `boolean` (optional)
-* **sameSite** `'String'|'Lax'|'None'` (optional)
+* **sameSite** `'Strict'|'Lax'|'None'` (optional)
 * **unparsed** `string[]` (optional) Left over attributes that weren't parsed.
 
 ## `deleteCookie(headers, name[, attributes])`
@@ -80,6 +80,33 @@ Arguments:
 
 Returns: `Cookie[]`
 
+## `parseCookie(cookie)`
+
+Parses a single `Set-Cookie` header value into a `Cookie` object.
+
+```js
+import { parseCookie } from 'undici'
+
+console.log(parseCookie('undici=getSetCookies; Secure; SameSite=Lax'))
+// {
+//   name: 'undici',
+//   value: 'getSetCookies',
+//   secure: true,
+//   sameSite: 'Lax'
+// }
+```
+
+Notes:
+
+* The cookie value is returned as it appears in the header. Percent-encoded sequences such as `%20` or `%0D%0A` are **not** decoded.
+* `sameSite` is only set for exact case-insensitive matches of `Strict`, `Lax`, or `None`.
+
+Arguments:
+
+* **cookie** `string`
+
+Returns: `Cookie | null`
+
 ## `setCookie(headers, cookie)`
 
 Appends a cookie to the `Set-Cookie` header.