@noodleseed/one 0.22.0 → 0.23.0

package/node_modules/undici/docs/docs/api/Interceptors.md

@@ -0,0 +1,355 @@
+# Interceptors
+
+Undici ships with a set of built-in interceptors that can be composed via
+`dispatcher.compose()` to add cross-cutting behaviour such as automatic
+retries, response decompression, redirect following, DNS caching, and more.
+
+## Usage
+
+```js
+import { Agent, interceptors } from 'undici'
+
+const { retry, redirect, decompress, dump, responseError, dns, cache, deduplicate } = interceptors
+
+const agent = new Agent().compose([
+  retry({ maxRetries: 3 }),
+  redirect({ maxRedirections: 5 }),
+  decompress()
+])
+
+const response = await agent.request({ origin: 'https://example.com', path: '/', method: 'GET' })
+```
+
+You can also apply interceptors to a single `Client` or `Pool`:
+
+```js
+import { Client, interceptors } from 'undici'
+
+const client = new Client('https://example.com').compose(
+  interceptors.retry({ maxRetries: 2 })
+)
+```
+
+---
+
+## `interceptors.dump([opts])`
+
+Reads and discards the response body up to a configurable size limit. Useful
+for keeping a connection alive after an error response without reading the
+body yourself.
+
+**Parameters**
+
+* `opts` {Object} (optional)
+  * `maxSize` {number} Maximum number of bytes to read and discard. Responses
+    whose `Content-Length` exceeds this value are aborted. **Default:**
+    `1_048_576` (1 MiB).
+
+Per-request override: set `dumpMaxSize` on the dispatch options to override
+the global `maxSize` for a specific request.
+
+**Returns:** {Dispatcher.DispatcherComposeInterceptor}
+
+**Example**
+
+```js
+import { Agent, interceptors } from 'undici'
+
+const agent = new Agent().compose(
+  interceptors.dump({ maxSize: 128 * 1024 }) // discard up to 128 KiB
+)
+```
+
+---
+
+## `interceptors.retry([opts])`
+
+Automatically retries failed requests using the same options accepted by
+[`RetryHandler`](./RetryHandler.md).
+
+**Parameters**
+
+* `opts` {RetryHandler.RetryOptions} (optional) Global retry options applied
+  to every request. Individual requests can override via `opts.retryOptions`.
+  See [`RetryOptions`](./RetryHandler.md#retryoptions) for the full list of
+  accepted fields.
+
+**Returns:** {Dispatcher.DispatcherComposeInterceptor}
+
+**Example**
+
+```js
+import { Agent, interceptors } from 'undici'
+
+const agent = new Agent().compose(
+  interceptors.retry({
+    maxRetries: 5,
+    minTimeout: 200,
+    maxTimeout: 5000,
+    timeoutFactor: 2,
+    statusCodes: [429, 502, 503, 504]
+  })
+)
+```
+
+---
+
+## `interceptors.redirect([opts])`
+
+Follows HTTP redirects (3xx responses) automatically.
+
+**Parameters**
+
+* `opts` {Object} (optional)
+  * `maxRedirections` {number} Maximum number of redirects to follow. Passing
+    `0` disables redirect following entirely. **Default:** `undefined`
+    (inherits from the per-request `maxRedirections` option).
+  * `throwOnMaxRedirect` {boolean} When `true`, throws an error once the
+    redirect limit is reached instead of returning the final redirect response.
+    **Default:** `false`.
+  * `stripHeadersOnRedirect` {string[]} List of header names to remove from
+    the request when following any redirect. **Default:** `[]`.
+  * `stripHeadersOnCrossOriginRedirect` {string[]} List of header names to
+    remove from the request when following a cross-origin redirect (i.e. the
+    redirect target has a different origin). Useful for stripping
+    `Authorization` on cross-origin hops. **Default:** `[]`.
+
+Per-request override: any of the four options above can also be set directly
+on the dispatch options to override the interceptor defaults for a specific
+request.
+
+**Returns:** {Dispatcher.DispatcherComposeInterceptor}
+
+**Example**
+
+```js
+import { Agent, interceptors } from 'undici'
+
+const agent = new Agent().compose(
+  interceptors.redirect({
+    maxRedirections: 10,
+    throwOnMaxRedirect: true,
+    stripHeadersOnCrossOriginRedirect: ['authorization', 'cookie']
+  })
+)
+```
+
+---
+
+## `interceptors.decompress([opts])`
+
+Automatically decompresses response bodies encoded with `gzip`, `x-gzip`,
+`br` (Brotli), `deflate`, `compress`, `x-compress`, or `zstd`.
+
+> **Experimental:** This interceptor is experimental and subject to change.
+> A one-time `ExperimentalWarning` is emitted on first use.
+
+**Parameters**
+
+* `opts` {Object} (optional)
+  * `skipStatusCodes` {number[]} Status codes for which decompression is
+    skipped. **Default:** `[204, 304]`.
+  * `skipErrorResponses` {boolean} When `true`, responses with a status code
+    >= 400 are not decompressed. **Default:** `true`.
+
+**Returns:** {Dispatcher.DispatcherComposeInterceptor}
+
+**Example**
+
+```js
+import { Agent, interceptors } from 'undici'
+
+const agent = new Agent().compose(
+  interceptors.decompress({
+    skipStatusCodes: [204, 304],
+    skipErrorResponses: false // decompress error bodies too
+  })
+)
+```
+
+---
+
+## `interceptors.responseError([opts])`
+
+Converts 4xx/5xx responses into thrown `ResponseError` instances, making it
+easy to handle HTTP errors with a standard `try/catch` block.
+
+The error body is automatically decoded for `application/json` and
+`text/plain` responses. For JSON responses the body is parsed and exposed as
+`error.body`.
+
+**Parameters**
+
+* `opts` {Object} (optional) — currently reserved for future use; may be
+  omitted.
+
+**Returns:** {Dispatcher.DispatcherComposeInterceptor}
+
+**Example**
+
+```js
+import { Agent, interceptors, errors } from 'undici'
+
+const agent = new Agent().compose(interceptors.responseError())
+
+try {
+  await agent.request({ origin: 'https://example.com', path: '/not-found', method: 'GET' })
+} catch (err) {
+  if (err instanceof errors.ResponseError) {
+    console.error(err.status, err.body)
+  }
+}
+```
+
+---
+
+## `interceptors.dns([opts])`
+
+Caches DNS lookups so that repeated requests to the same origin reuse the
+resolved IP address instead of performing a fresh lookup every time. Supports
+dual-stack (IPv4 + IPv6) and custom lookup/storage implementations.
+
+**Parameters**
+
+* `opts` {Object} (optional)
+  * `maxTTL` {number} Maximum number of milliseconds a DNS record is cached,
+    regardless of the TTL returned by the resolver. **Default:** `0`
+    (use the TTL from the DNS record).
+  * `maxItems` {number} Maximum number of origins to cache simultaneously.
+    Oldest entries are evicted when the limit is reached. **Default:**
+    `Infinity`.
+  * `dualStack` {boolean} When `true`, both IPv4 (`A`) and IPv6 (`AAAA`)
+    records are looked up and the interceptor picks between them based on
+    `affinity`. **Default:** `true`.
+  * `affinity` {4 | 6 | null} Preferred IP family when `dualStack` is
+    enabled. `null` lets the interceptor alternate between families.
+    **Default:** `null`.
+  * `lookup` {Function} (optional) Custom DNS resolution function with the
+    same signature as `node:dns`'s `lookup` callback form:
+    `(origin, options, callback) => void`.
+  * `pick` {Function} (optional) Custom record-selection function called with
+    `(origin, records, affinity)` to choose which resolved address to use.
+  * `storage` {DNSStorage} (optional) Custom storage backend. Must implement
+    `get`, `set`, `delete`, `full`, and `size`.
+
+**`DNSStorage` interface**
+
+```ts
+interface DNSStorage {
+  size: number
+  get(origin: string): DNSInterceptorOriginRecords | null
+  set(origin: string, records: DNSInterceptorOriginRecords | null, options: { ttl: number }): void
+  delete(origin: string): void
+  full(): boolean
+}
+```
+
+**Returns:** {Dispatcher.DispatcherComposeInterceptor}
+
+**Example**
+
+```js
+import { Agent, interceptors } from 'undici'
+
+const agent = new Agent().compose(
+  interceptors.dns({
+    maxTTL: 60_000, // cache for at most 60 seconds
+    dualStack: true,
+    affinity: 4     // prefer IPv4
+  })
+)
+```
+
+---
+
+## `interceptors.cache([opts])`
+
+Caches HTTP responses according to RFC 9111 (HTTP Caching). See
+[`CacheStore`](./CacheStore.md) for information on providing a custom
+backing store.
+
+**Parameters**
+
+* `opts` {CacheHandler.CacheOptions} (optional) See the
+  [`CacheStore`](./CacheStore.md) documentation for accepted fields.
+
+**Returns:** {Dispatcher.DispatcherComposeInterceptor}
+
+**Example**
+
+```js
+import { Agent, interceptors, cacheStores } from 'undici'
+
+const agent = new Agent().compose(
+  interceptors.cache({ store: new cacheStores.MemoryCacheStore() })
+)
+```
+
+---
+
+## `interceptors.deduplicate([opts])`
+
+Deduplicates concurrent identical requests so that only one is sent over the
+wire. All waiting callers receive the same response once the in-flight request
+completes. Only safe HTTP methods (e.g. `GET`, `HEAD`) may be deduplicated.
+
+**Parameters**
+
+* `opts` {Object} (optional)
+  * `methods` {string[]} HTTP methods to deduplicate. Must be safe HTTP
+    methods (`GET`, `HEAD`, `OPTIONS`, `TRACE`). **Default:** `['GET']`.
+  * `skipHeaderNames` {string[]} Header names whose presence in a request
+    causes it to bypass deduplication entirely. Matching is
+    case-insensitive. **Default:** `[]`.
+  * `excludeHeaderNames` {string[]} Header names to exclude from the
+    deduplication key. Requests that differ only in these headers are still
+    deduplicated together. Useful for headers like `x-request-id` that vary
+    per request but should not prevent deduplication. Matching is
+    case-insensitive. **Default:** `[]`.
+  * `maxBufferSize` {number} Maximum number of bytes buffered per paused
+    waiting handler. If a waiting handler exceeds this threshold it is failed
+    with an `AbortError` to prevent unbounded memory growth. **Default:**
+    `5_242_880` (5 MiB).
+
+**Returns:** {Dispatcher.DispatcherComposeInterceptor}
+
+**Example**
+
+```js
+import { Agent, interceptors } from 'undici'
+
+const agent = new Agent().compose(
+  interceptors.deduplicate({
+    methods: ['GET', 'HEAD'],
+    excludeHeaderNames: ['x-request-id', 'x-trace-id'],
+    maxBufferSize: 2 * 1024 * 1024
+  })
+)
+```
+
+---
+
+## Composing multiple interceptors
+
+Interceptors are applied in the order they appear in the `compose()` call.
+The first interceptor in the array wraps the outermost layer.
+
+```js
+import { Agent, interceptors } from 'undici'
+
+const agent = new Agent().compose([
+  interceptors.dns({ maxTTL: 30_000 }),
+  interceptors.retry({ maxRetries: 3 }),
+  interceptors.redirect({ maxRedirections: 5 }),
+  interceptors.decompress(),
+  interceptors.responseError()
+])
+```
+
+In the example above the request flow is:
+
+1. **dns** — resolves and caches the target IP
+2. **retry** — retries the dispatch on transient failures
+3. **redirect** — follows any 3xx redirects
+4. **decompress** — decompresses the response body
+5. **responseError** — converts 4xx/5xx into thrown errors