erik/projektuebersicht
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Plan Checker, Wochenbericht-Fokus-Modus und Wandtafel-Dashboard-Feinschliff

Browse Source 
Plan Checker (neues Studenten-Werkzeug, Seitenleiste + Admin → Plan-Checker-
Merkmale): lädt einen Bauplan als PDF hoch und lässt ChatGPT oder Claude ihn
gegen eine gepflegte Merkmalsliste prüfen. PDF-Rendering (pdf.js +
@napi-rs/canvas) berücksichtigt jetzt Ebenen (Optional Content Groups) und
WASM-Decoder korrekt, sendet eine Übersicht plus mehrere hochaufgelöste
Kachel-Ausschnitte statt eines einzelnen, zu groben Bilds, und beide Anbieter
bekommen dasselbe Bildmaterial. Jedes Prüfergebnis kann auf eines der
gesendeten Bilder als Beleg verweisen (bildIndex) — als Screenshot im
Ergebnis anklickbar, öffnet vergrößert in einem Modal statt eines von Chrome
blockierten target=_blank-Links auf eine data:-URL. KI-Modellname ist jetzt
pro Konto überschreibbar (Einstellungen → Mein Konto) für Drittanbieter mit
abweichendem Modell-Katalog.

Wochenbericht: dichte Kartenansicht bekommt einen Fokus-Modus — nur der
Kommentar liegt offen, Leistungsphasen und Beteiligte stecken in
aufklappbaren Abschnitten statt dauerhaft nebeneinander zu stehen.

Projektbereich: Terminplan-Auslastung rechnet jetzt exakt wie der
Auslastungs-Tab/die Wandtafel (statt einer unabhängigen, tageweisen
Schätzung); die LPH-Fortschrittsliste im Dashboard zeigt nur noch die
beauftragten Leistungsphasen.

Wandtafel: Dashboard-Kopf mit Kennzahlen-Reihe und Panel-Reihe neu
strukturiert, in den Blautönen des Firmenlogos; dieselbe Palette wurde
anschließend auf den gesamten App-weiten Dark Mode übernommen.

Dateibereinigung: nicht mehr benötigte Test-Uploads/Backups entfernt.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
erikandClaude Sonnet 5 committed 2026-10-05 14:01:41 +02:00
1 parent db63a29365
commit 6ba93b2a92
308 files changed
+64441 -743
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

node_modules/undici/docs/docs/api/BalancedPool.md
Generated Vendored
+297
View File
@@ -0,0 +1,297 @@
# BalancedPool
<!--introduced_in=v4.8.0-->
<!--type=module-->
<!-- source_link=lib/dispatcher/balanced-pool.js -->
> Stability: 2 - Stable
A `BalancedPool` distributes requests across a set of {Pool} instances, each
connected to a different upstream. It uses a weighted round-robin algorithm:
every upstream starts with the same weight, and the weight is adjusted up on
successful connections and down on connection errors, so that healthy upstreams
receive a larger share of traffic.
Requests are not guaranteed to be dispatched in the order they are issued.
```mjs
import { BalancedPool } from 'undici'
const pool = new BalancedPool([
'http://localhost:3000',
'http://localhost:3001',
'http://localhost:3002',
])
const { statusCode, body } = await pool.request({
path: '/',
method: 'GET',
})
console.log('response received', statusCode)
for await (const chunk of body) {
console.log('data', chunk.toString())
}
```
## Class: `BalancedPool`
<!-- YAML
added: v4.8.0
changes:
- version: v4.10.4
pr-url: https://github.com/nodejs/undici/pull/1114
description: Introduced the `BalancedPool` class.
-->
* Extends: {Dispatcher}
A pool of {Pool} instances connected to multiple upstreams.
### `new BalancedPool(upstreams[, options])`
<!-- YAML
added: v4.8.0
changes:
- version: v4.15.0
pr-url: https://github.com/nodejs/undici/pull/1237
description: Added the `factory` option.
-->
* `upstreams` {URL|string|URL[]|string[]} One or more upstream origins. Each
value should only include the **protocol, hostname, and port**. **Default:**
`[]`.
* `options` {BalancedPoolOptions} (optional)
The options passed to the constructor are forwarded to every {Pool} instance
that is created for an upstream.
#### Parameter: `BalancedPoolOptions`
Extends: {PoolOptions}
In addition to all {PoolOptions}, the following options are supported:
* `factory` {Function} A function used to create the {Pool} instance for each
upstream. **Default:** `(origin, opts) => new Pool(origin, opts)`.
* `origin` {URL|string} The upstream origin.
* `opts` {Object} The options object derived from the constructor options.
* Returns: {Dispatcher}
* `maxWeightPerServer` {number} The maximum weight any single upstream can
reach. Successful connections increase an upstream's weight up to this value.
**Default:** `100`.
* `errorPenalty` {number} The amount by which an upstream's weight is decreased
on a connection error and increased on a successful connection. **Default:**
`15`.
### `balancedPool.addUpstream(upstream)`
<!-- YAML
added: v4.8.0
-->
* `upstream` {URL|string} The upstream origin to add. It should only include the
**protocol, hostname, and port**.
* Returns: {BalancedPool} The `BalancedPool` instance, for chaining.
Adds an upstream. If an open, non-destroyed upstream with the same origin is
already present, the call is a no-op.
### `balancedPool.removeUpstream(upstream)`
<!-- YAML
added: v4.8.0
-->
* `upstream` {URL|string} The upstream origin to remove. It should only include
the **protocol, hostname, and port**.
* Returns: {BalancedPool} The `BalancedPool` instance, for chaining.
Removes an upstream that was previously added. If no matching upstream is found,
the call is a no-op.
### `balancedPool.getUpstream(upstream)`
<!-- YAML
added: v7.17.0
-->
* `upstream` {URL|string} The upstream origin to look up. It should only include
the **protocol, hostname, and port**.
* Returns: {Pool|undefined} The {Pool} instance managing the given upstream, or
`undefined` if it is not present.
Returns the {Pool} instance for the given upstream origin, if it is open and not
destroyed.
### `balancedPool.upstreams`
<!-- YAML
added: v4.8.0
-->
* Type: {string[]} The origins of the upstreams that are currently open and not
destroyed.
### `balancedPool.closed`
<!-- YAML
added: v4.8.0
changes:
- version: v4.10.4
pr-url: https://github.com/nodejs/undici/pull/1114
description: Introduced the `BalancedPool` class.
-->
* Type: {boolean} `true` after `balancedPool.close()` has been called.
Implements [`client.closed`][].
### `balancedPool.destroyed`
<!-- YAML
added: v4.8.0
changes:
- version: v4.10.4
pr-url: https://github.com/nodejs/undici/pull/1114
description: Introduced the `BalancedPool` class.
-->
* Type: {boolean} `true` after `balancedPool.destroy()` has been called, or after
`balancedPool.close()` has been called and the shutdown has completed.
Implements [`client.destroyed`][].
### `balancedPool.stats`
<!-- YAML
added: v4.8.0
-->
* Type: {PoolStats}
Returns a {PoolStats} instance aggregating the statistics of the underlying
pools.
### `balancedPool.close([callback])`
<!-- YAML
added: v4.8.0
-->
Implements [`Dispatcher.close([callback])`][].
### `balancedPool.destroy([error[, callback]])`
<!-- YAML
added: v4.8.0
-->
Implements [`Dispatcher.destroy([error, callback])`][].
### `balancedPool.connect(options[, callback])`
<!-- YAML
added: v4.8.0
-->
See [`Dispatcher.connect(options[, callback])`][].
### `balancedPool.dispatch(options, handlers)`
<!-- YAML
added: v4.8.0
changes:
- version: v4.10.4
pr-url: https://github.com/nodejs/undici/pull/1114
description: Introduced the `BalancedPool` class.
-->
Implements [`Dispatcher.dispatch(options, handler)`][].
### `balancedPool.pipeline(options, handler)`
<!-- YAML
added: v4.8.0
-->
See [`Dispatcher.pipeline(options, handler)`][].
### `balancedPool.request(options[, callback])`
<!-- YAML
added: v4.8.0
-->
See [`Dispatcher.request(options[, callback])`][].
### `balancedPool.stream(options, factory[, callback])`
<!-- YAML
added: v4.8.0
-->
See [`Dispatcher.stream(options, factory[, callback])`][].
### `balancedPool.upgrade(options[, callback])`
<!-- YAML
added: v4.8.0
-->
See [`Dispatcher.upgrade(options[, callback])`][].
### Event: `'connect'`
<!-- YAML
added: v4.8.0
changes:
- version: v4.10.4
pr-url: https://github.com/nodejs/undici/pull/1114
description: Introduced the `BalancedPool` class.
- version: v5.8.0
pr-url: https://github.com/nodejs/undici/pull/1069
description: Adopted weighted round-robin selection across upstreams.
-->
See [Dispatcher Event: `'connect'`][].
### Event: `'disconnect'`
<!-- YAML
added: v4.8.0
changes:
- version: v4.10.4
pr-url: https://github.com/nodejs/undici/pull/1114
description: Introduced the `BalancedPool` class.
- version: v5.8.0
pr-url: https://github.com/nodejs/undici/pull/1069
description: Adopted weighted round-robin selection across upstreams.
-->
See [Dispatcher Event: `'disconnect'`][].
### Event: `'drain'`
<!-- YAML
added: v4.8.0
changes:
- version: v4.10.4
pr-url: https://github.com/nodejs/undici/pull/1114
description: Introduced the `BalancedPool` class.
-->
See [Dispatcher Event: `'drain'`][].
[Dispatcher Event: `'connect'`]: Dispatcher.md#event-connect
[Dispatcher Event: `'disconnect'`]: Dispatcher.md#event-disconnect
[Dispatcher Event: `'drain'`]: Dispatcher.md#event-drain
[`Dispatcher.close([callback])`]: Dispatcher.md#dispatcherclosecallback-promise
[`Dispatcher.connect(options[, callback])`]: Dispatcher.md#dispatcherconnectoptions-callback
[`Dispatcher.destroy([error, callback])`]: Dispatcher.md#dispatcherdestroyerror-callback-promise
[`Dispatcher.dispatch(options, handler)`]: Dispatcher.md#dispatcherdispatchoptions-handler
[`Dispatcher.pipeline(options, handler)`]: Dispatcher.md#dispatcherpipelineoptions-handler
[`Dispatcher.request(options[, callback])`]: Dispatcher.md#dispatcherrequestoptions-callback
[`Dispatcher.stream(options, factory[, callback])`]: Dispatcher.md#dispatcherstreamoptions-factory-callback
[`Dispatcher.upgrade(options[, callback])`]: Dispatcher.md#dispatcherupgradeoptions-callback
[`client.closed`]: Client.md#clientclosed
[`client.destroyed`]: Client.md#clientdestroyed
node_modules/undici/docs/docs/api/CacheStorage.md
Generated Vendored
+188
View File
@@ -0,0 +1,188 @@
# CacheStorage
<!--introduced_in=v5.22.1-->
<!--type=module-->
<!-- source_link=lib/web/cache/cachestorage.js -->
> Stability: 2 - Stable
undici provides a spec-compliant implementation of the [W3C Service Worker
`CacheStorage`][] and [`Cache`][] interfaces. A `CacheStorage` is a named
collection of [`Cache`][] objects, each of which stores `Request`/`Response`
pairs.
The class itself is not exported; instead, undici exposes a single shared
`CacheStorage` instance named `caches`. Import it from `'undici'`:
```mjs
import { caches } from 'undici'
const cache = await caches.open('v1')
```
```cjs
const { caches } = require('undici')
caches.open('v1').then((cache) => {
// ...
})
```
## `caches`
<!-- YAML
added: v5.22.1
-->
* Type: {CacheStorage}
The shared [`CacheStorage`](#class-cachestorage) instance exported by undici.
All caches opened through `caches` live for the lifetime of the process.
```mjs
import { caches } from 'undici'
await caches.open('v1')
console.log(await caches.keys()) // ['v1']
```
## Class: `CacheStorage`
<!-- YAML
added: v5.22.1
-->
Represents the storage for [`Cache`][] objects. Each `CacheStorage` keeps a
mapping of cache names to their backing list of cached responses.
The constructor is not public: attempting to instantiate `CacheStorage`
directly throws a `TypeError`. Use the exported [`caches`](#caches) instance
instead.
### `caches.match(request[, options])`
<!-- YAML
added: v5.22.1
-->
* `request` {Request|string} The request to match against. A string is treated
as a URL.
* `options` {Object} (optional)
* `ignoreSearch` {boolean} When `true`, ignores the query string of the URL
when matching. **Default:** `false`.
* `ignoreMethod` {boolean} When `true`, prevents matching operations from
validating the `Request` `http` method. **Default:** `false`.
* `ignoreVary` {boolean} When `true`, ignores the `Vary` header when matching.
**Default:** `false`.
* `cacheName` {string} When set, restricts the search to the cache with this
name. **Default:** `undefined`.
* Returns: {Promise} Fulfills with the first matching {Response}, or
`undefined` if no response matched.
Searches the caches for a response matching `request`. When `options.cacheName`
is provided, only that cache is searched; otherwise every cache is searched in
insertion order and the first match is returned.
```mjs
import { caches } from 'undici'
const response = await caches.match('https://example.com/data', {
cacheName: 'v1'
})
```
### `caches.has(cacheName)`
<!-- YAML
added: v5.22.1
-->
* `cacheName` {string} The name of the cache to look up.
* Returns: {Promise} Fulfills with `true` if a cache named `cacheName` exists,
otherwise `false`.
Checks whether a cache with the given name exists in the storage.
```mjs
import { caches } from 'undici'
await caches.open('v1')
console.log(await caches.has('v1')) // true
console.log(await caches.has('v2')) // false
```
### `caches.open(cacheName)`
<!-- YAML
added: v5.22.1
-->
* `cacheName` {string} The name of the cache to open.
* Returns: {Promise} Fulfills with the {Cache} named `cacheName`.
Opens the cache named `cacheName`, creating it if it does not already exist.
Each call returns a new [`Cache`][] object, but caches opened with the same name
share their underlying list of cached responses. As a result, a response stored
through one instance is visible through another instance with the same name.
```mjs
import { caches } from 'undici'
import assert from 'node:assert'
const cache1 = await caches.open('v1')
const cache2 = await caches.open('v1')
// open() returns distinct objects,
assert(cache1 !== cache2)
// but they share the same cached responses.
assert.deepStrictEqual(await cache1.match('/req'), await cache2.match('/req'))
```
### `caches.delete(cacheName)`
<!-- YAML
added: v5.22.1
-->
* `cacheName` {string} The name of the cache to delete.
* Returns: {Promise} Fulfills with `true` if the cache existed and was deleted,
otherwise `false`.
Removes the cache named `cacheName` from the storage. Any [`Cache`][] objects
already obtained for that name, along with the `Request`/`Response` pairs they
returned, remain usable after deletion.
```mjs
import { caches } from 'undici'
const cache = await caches.open('v1')
const response = await cache.match('/req')
await caches.delete('v1')
// The already-retrieved response is still usable.
await response.text()
```
### `caches.keys()`
<!-- YAML
added: v5.22.1
-->
* Returns: {Promise} Fulfills with a {string[]} of cache names in insertion
order.
Returns the names of all caches currently held by the storage.
```mjs
import { caches } from 'undici'
await caches.open('v1')
await caches.open('v2')
console.log(await caches.keys()) // ['v1', 'v2']
```
[W3C Service Worker `CacheStorage`]: https://w3c.github.io/ServiceWorker/#cachestorage-interface
[`Cache`]: https://w3c.github.io/ServiceWorker/#cache-interface
node_modules/undici/docs/docs/api/CacheStore.md
Generated Vendored
+360
View File
@@ -0,0 +1,360 @@
# Cache Store
<!--introduced_in=v7.0.0-->
<!--type=module-->
<!-- source_link=lib/cache/memory-cache-store.js -->
> Stability: 2 - Stable
A cache store is the storage backend used by the cache interceptor to persist
and retrieve cached responses. A store decides which stored response to serve
for a request by comparing the request against the response's `Vary` header, and
is expected to be compliant with [RFC&nbsp;9111][].
undici ships two stores. `MemoryCacheStore` keeps responses in memory, while
`SqliteCacheStore` persists them to a SQLite database. Both are available under
the `cacheStores` export:
```mjs
import { cacheStores } from 'undici'
const { MemoryCacheStore, SqliteCacheStore } = cacheStores
```
`SqliteCacheStore` requires the [`node:sqlite`][] API. The class is always
exported, but constructing one throws if `node:sqlite` is not available in the
running Node.js version.
A cache store implements three methods — `get(key)`, `createWriteStream(key,
value)`, and `delete(key)` — that operate on a [`CacheKey`](#cachekey) and a
[`CacheValue`](#cachevalue). Any object implementing this contract can be passed
to the cache interceptor, so custom stores (for example, backed by Redis or a
remote service) are supported as well.
## Class: `MemoryCacheStore`
<!-- YAML
added: v7.0.0
-->
* Extends: {EventEmitter}
Stores cached responses in memory. The store enforces upper bounds on the total
number of responses, the total size of all responses, and the size of any single
response. When a limit is exceeded, the store evicts approximately half of its
entries and emits a [`'maxSizeExceeded'`](#event-maxsizeexceeded) event.
```mjs
import { interceptors, cacheStores, Agent, setGlobalDispatcher } from 'undici'
const store = new cacheStores.MemoryCacheStore({ maxSize: 50 * 1024 * 1024 })
setGlobalDispatcher(
new Agent().compose(interceptors.cache({ store }))
)
```
### `new MemoryCacheStore([options])`
<!-- YAML
added: v7.0.0
-->
* `options` {Object} (optional)
* `maxCount` {number} The maximum number of responses to store. **Default:**
`1024`.
* `maxSize` {number} The maximum total size, in bytes, of all stored
responses. **Default:** `104857600` (100 MiB).
* `maxEntrySize` {number} The maximum size, in bytes, of a single response
body. Responses whose body exceeds this value are not cached. **Default:**
`5242880` (5 MiB).
* `errorCallback` {Function} A callback invoked with any error raised by the
store. (optional)
* `err` {Error}
Each of `maxCount`, `maxSize`, and `maxEntrySize` must be a non-negative
integer; a `TypeError` is thrown otherwise.
### `memoryCacheStore.size`
<!-- YAML
added: v7.0.0
-->
* Type: {number}
The current total size, in bytes, of all stored response bodies.
### `memoryCacheStore.isFull()`
<!-- YAML
added: v7.0.0
-->
* Returns: {boolean} `true` when the store has reached its `maxSize` or
`maxCount` limit, `false` otherwise.
### `memoryCacheStore.get(key)`
<!-- YAML
added: v7.0.0
-->
* `key` {CacheKey} The request to look up. See [`CacheKey`](#cachekey).
* Returns: {GetResult|undefined} The matching cached response, or `undefined`
when there is no fresh entry for `key`. See [`GetResult`](#getresult).
Looks up a cached response for `key`. A stored entry matches only when its
`method` equals `key.method`, its `deleteAt` time is in the future, and every
header listed in its `vary` map matches the corresponding header in
`key.headers`.
### `memoryCacheStore.createWriteStream(key, value)`
<!-- YAML
added: v7.0.0
-->
* `key` {CacheKey} The request the response is being cached for. See
[`CacheKey`](#cachekey).
* `value` {CacheValue} The response metadata to store. See
[`CacheValue`](#cachevalue).
* Returns: {Writable|undefined} A writable stream that the response body is
written to, or `undefined` when the response cannot be cached.
Returns a {Writable} stream used to write the response body into the store. When
the stream finishes, the entry is committed; if its accumulated size exceeds
`maxEntrySize`, the stream is destroyed and nothing is stored. Writing a new
entry whose `key` matches an existing one replaces that entry.
### `memoryCacheStore.delete(key)`
<!-- YAML
added: v7.0.0
-->
* `key` {CacheKey} The request whose cached responses should be removed. See
[`CacheKey`](#cachekey).
* Returns: {undefined}
Removes every cached response stored for `key.origin` and `key.path`. Throws a
`TypeError` if `key` is not an object.
### Event: `'maxSizeExceeded'`
<!-- YAML
added: v7.10.0
-->
* `data` {Object}
* `size` {number} The current total size, in bytes, of all stored responses.
* `maxSize` {number} The configured `maxSize` limit.
* `count` {number} The current number of stored responses.
* `maxCount` {number} The configured `maxCount` limit.
Emitted when the store exceeds its `maxSize` or `maxCount` limit, immediately
before entries are evicted. The event fires only once per overflow; it is not
emitted again until the store drops back below both limits.
## Class: `SqliteCacheStore`
<!-- YAML
added: v7.0.0
-->
Stores cached responses in a SQLite database using the [`node:sqlite`][] API.
The constructor throws when [`node:sqlite`][] is not available.
```mjs
import { interceptors, cacheStores, Agent, setGlobalDispatcher } from 'undici'
const store = new cacheStores.SqliteCacheStore({ location: './cache.db' })
setGlobalDispatcher(
new Agent().compose(interceptors.cache({ store }))
)
```
### `new SqliteCacheStore([options])`
<!-- YAML
added: v7.0.0
-->
* `options` {Object} (optional)
* `location` {string} The location of the SQLite database. Use `':memory:'`
for an in-memory database. **Default:** `':memory:'`.
* `maxCount` {number} The maximum number of responses to store. **Default:**
`Infinity`.
* `maxEntrySize` {number} The maximum size, in bytes, of a single response
body. Responses whose body exceeds this value are not cached. Must not
exceed `2000000000` (2 GB). **Default:** `2000000000` (2 GB).
`maxCount` and `maxEntrySize` must be non-negative integers; a `TypeError` is
thrown otherwise, or if `maxEntrySize` is greater than 2 GB.
### `sqliteCacheStore.close()`
<!-- YAML
added: v7.0.0
-->
* Returns: {undefined}
Closes the connection to the underlying SQLite database.
### `sqliteCacheStore.size`
<!-- YAML
added: v7.0.0
-->
* Type: {number}
The number of responses currently stored in the database.
### `sqliteCacheStore.get(key)`
<!-- YAML
added: v7.0.0
-->
* `key` {CacheKey} The request to look up. See [`CacheKey`](#cachekey).
* Returns: {GetResult|undefined} The matching cached response, or `undefined`
when there is no fresh entry for `key`. The returned `body` is a {Buffer}.
See [`GetResult`](#getresult).
Looks up a cached response for `key`, comparing the request method and every
header named in the stored `vary` map.
### `sqliteCacheStore.set(key, value)`
<!-- YAML
added: v7.0.0
-->
* `key` {CacheKey} The request the response is being cached for. See
[`CacheKey`](#cachekey).
* `value` {CacheValue} The response to store, with its `body` set to a {Buffer},
an {Array} of {Buffer}, or `null`. See [`CacheValue`](#cachevalue).
* Returns: {undefined}
Writes a response into the database directly, without going through a stream. If
the body exceeds `maxEntrySize`, nothing is stored. When an entry already exists
for `key` it is overwritten; otherwise a new row is inserted and old entries are
pruned to honour `maxCount`. This method is used internally by
[`sqliteCacheStore.createWriteStream()`](#sqlitecachestorecreatewritestreamkey-value).
### `sqliteCacheStore.createWriteStream(key, value)`
<!-- YAML
added: v7.0.0
-->
* `key` {CacheKey} The request the response is being cached for. See
[`CacheKey`](#cachekey).
* `value` {CacheValue} The response metadata to store. See
[`CacheValue`](#cachevalue).
* Returns: {Writable|undefined} A writable stream that the response body is
written to, or `undefined` when the response cannot be cached.
Returns a {Writable} stream used to write the response body into the store. When
the stream finishes, the buffered body is committed via
[`sqliteCacheStore.set()`](#sqlitecachestoresetkey-value). If the body exceeds
`maxEntrySize`, the stream is destroyed and nothing is stored.
### `sqliteCacheStore.delete(key)`
<!-- YAML
added: v7.0.0
-->
* `key` {CacheKey} The request whose cached responses should be removed. See
[`CacheKey`](#cachekey).
* Returns: {undefined}
Removes every cached response stored for the URL derived from `key.origin` and
`key.path`. Throws a `TypeError` if `key` is not an object.
## Implementing a custom cache store
A cache store is any object that implements the `CacheStore` interface:
* `get(key)` — Look up a response. Returns a [`GetResult`](#getresult),
`undefined`, or a {Promise} resolving to either.
* `createWriteStream(key, value)` — Return a {Writable} to receive the response
body, or `undefined` if the response cannot be stored.
* `delete(key)` — Remove all responses for `key`. May return a {Promise}.
Returning a {Promise} from `get` or `delete` lets a store be backed by an
asynchronous resource; the cache interceptor awaits these values, including on
the revalidation and stale-while-revalidate paths.
### `CacheKey`
The request a response is being looked up or stored for.
* `origin` {string} The request origin.
* `method` {string} The request method.
* `path` {string} The request path.
* `headers` {Record<string, string|string[]>} The request headers, used to
satisfy `Vary`. (optional)
### `CacheValue`
The metadata of a cached response, excluding its body.
* `statusCode` {number} The response's HTTP status code.
* `statusMessage` {string} The response's HTTP status message.
* `headers` {Record<string, string|string[]>} The response headers.
* `vary` {Record<string, string|string[]|null>} The header names listed in the
response's `Vary` header mapped to the values they had in the original
request. A value is `null` when that header was absent from the original
request. (optional)
* `etag` {string} The response's entity tag. (optional)
* `cacheControlDirectives` {Object} The parsed `Cache-Control` directives of the
response. (optional)
* `cachedAt` {number} The time, in milliseconds, at which the response was
cached.
* `staleAt` {number} The time, in milliseconds, at which the response becomes
stale.
* `deleteAt` {number} The time, in milliseconds, at which the response must be
evicted. A store must not return a response once this time has passed.
The `vary` map drives response selection. For a response such as:
```http
Vary: content-encoding, accept
content-encoding: utf8
accept: application/json
```
the recorded map is:
```js
{
'content-encoding': 'utf8',
accept: 'application/json'
}
```
If the original request did not include the `accept` header, its value is
recorded as `null`:
```js
{
'content-encoding': 'utf8',
accept: null
}
```
### `GetResult`
The value returned by `get`. It contains every field of
[`CacheValue`](#cachevalue) plus the response body.
* `body` {Readable|Iterable|AsyncIterable|Buffer|string} The cached response
body. (optional)
[RFC&nbsp;9111]: https://www.rfc-editor.org/rfc/rfc9111.html
[`node:sqlite`]: https://nodejs.org/api/sqlite.html
node_modules/undici/docs/docs/api/Client.md
Generated Vendored
+533
View File
@@ -0,0 +1,533 @@
# Client
<!--introduced_in=v1.0.0-->
<!--type=module-->
<!-- source_link=lib/dispatcher/client.js -->
> Stability: 2 - Stable
A basic HTTP/1.1 client mapped on top of a single TCP/TLS connection. When the
server supports HTTP/2 and selects it during ALPN negotiation, the same
connection is used for HTTP/2. Pipelining is disabled by default.
`Client` extends [`Dispatcher`][] and is the lowest-level dispatcher in undici:
it manages exactly one origin over one connection. For pooling across multiple
connections use [`Pool`][], and for routing across multiple origins use
[`Agent`][]. Requests are not guaranteed to be dispatched in the order in which
they are invoked.
```mjs
import { Client } from 'undici'
const client = new Client('http://localhost:3000')
const { statusCode, body } = await client.request({ path: '/', method: 'GET' })
```
## Class: `Client`
<!-- YAML
added: v1.0.0
-->
* Extends: {Dispatcher}
### `new Client(url[, options])`
<!-- YAML
added: v1.0.0
-->
* `url` {URL|string} The origin to connect to. Only the protocol, hostname, and
port are used.
* `options` {Object} (optional)
* `bodyTimeout` {number|null} The timeout, in milliseconds, after which a
request times out while receiving body data. Monitors the time between
consecutive body chunks. Use `0` to disable it entirely. **Default:**
`300e3`.
* `headersTimeout` {number|null} The timeout, in milliseconds, the parser
waits to receive the complete HTTP headers before the request times out. Use
`0` to disable it entirely. **Default:** `300e3`.
HTTP/1.1 headers/body parser timeouts are not guaranteed to fire with exact
millisecond precision: delays up to 1000ms use native timers, while larger
delays use undici's lower-overhead fast timers with a target resolution
around 500ms.
* `connectTimeout` {number|null} The timeout, in milliseconds, for
establishing a socket connection. Use `0` to disable it entirely.
**Default:** `10e3`.
* `keepAliveTimeout` {number|null} The timeout, in milliseconds, after which a
socket with no active requests times out. Monitors the time between activity
on a connected socket. This value may be overridden by *keep-alive* hints
from the server. **Default:** `4e3`.
* `keepAliveMaxTimeout` {number|null} The maximum allowed `keepAliveTimeout`,
in milliseconds, when overridden by *keep-alive* hints from the server.
**Default:** `600e3`.
* `keepAliveTimeoutThreshold` {number|null} A number of milliseconds
subtracted from server *keep-alive* hints when overriding `keepAliveTimeout`,
to account for timing inaccuracies caused by e.g. transport latency.
**Default:** `2e3`.
* `maxHeaderSize` {number|null} The maximum length of request headers, in
bytes. **Default:** the value of Node.js' `--max-http-header-size` or
`16384` (16 KiB).
* `maxResponseSize` {number|null} The maximum length of a response body, in
bytes. Set to `-1` to disable it. **Default:** `-1`.
* `maxRequestsPerClient` {number|null} The maximum number of requests to send
over a single connection before the socket is reset. Use `0` to disable this
limit. **Default:** `null`.
* `localAddress` {string|null} The local IP address the socket should connect
from. **Default:** `null`.
* `pipelining` {number|null} The number of concurrent requests sent over the
single connection, per [RFC 7230, section 6.3.2][]. Only enable values
greater than `1` when the remote server is trusted. Set to `0` to disable
keep-alive connections. Has no effect once HTTP/2 is negotiated; see
`maxConcurrentStreams` for the HTTP/2 dispatch ceiling. **Default:** `1`.
* `connect` {Object|Function|null} Configures how connections are established.
Either a `ConnectOptions` object passed to the built-in
[`buildConnector`][] (every [`tls.connect()`][] option is accepted, plus the
fields below), or a custom connector function with the signature
`(options, callback)`. **Default:** `null`.
* `socketPath` {string|null} An IPC endpoint, either a Unix domain socket or
a Windows named pipe. **Default:** `null`.
* `maxCachedSessions` {number|null} The maximum number of cached TLS
sessions. Use `0` to disable TLS session caching. **Default:** `100`.
* `timeout` {number|null} The connection timeout, in milliseconds.
**Default:** `10e3`.
* `servername` {string|null} The TLS server name used for SNI.
* `keepAlive` {boolean|null} Whether TCP keep-alive is enabled on the socket.
**Default:** `true`.
* `keepAliveInitialDelay` {number|null} The TCP keep-alive interval for the
socket, in milliseconds. **Default:** `60000`.
* `strictContentLength` {boolean} Whether to throw when the request
`content-length` header does not match the length of the request body.
Disabling this exposes the application to HTTP request smuggling; only do so
in controlled environments where the request source is fully trusted.
**Default:** `true`.
* `autoSelectFamily` {boolean} Enables a family autodetection algorithm that
loosely implements section 5 of [RFC 8305][]. Ignored if unsupported by the
current Node.js version. **Default:** `false`.
* `autoSelectFamilyAttemptTimeout` {number} The time, in milliseconds, to wait
for a connection attempt to finish before trying the next address when
`autoSelectFamily` is enabled. **Default:** `250`.
* `allowH2` {boolean} Enables HTTP/2 support when the server assigns it a
higher priority through ALPN negotiation. **Default:** `true`.
* `useH2c` {boolean} _Deprecated: use h2Options.useH2c instead_ Enforces h2c (HTTP/2 cleartext) for non-HTTPS
connections. **Default:** `false`.
* `maxConcurrentStreams` {number} _Deprecated: use h2Options.useH2c instead_ The maximum number of concurrent HTTP/2
streams for a single session. Once h2 is negotiated this — not `pipelining`,
which is HTTP/1.1 only — is the ceiling used to dispatch in-flight requests.
It may be overridden by the server's `SETTINGS_MAX_CONCURRENT_STREAMS`
frame. **Default:** `100`.
* `connectionWindowSize` {number} _Deprecated: use h2Options.connectionWindowSize instead_ The HTTP/2 connection-level flow-control
window size set via `ClientHttp2Session.setLocalWindowSize()`. Must be a
positive integer. **Default:** `524288`.
* `pingInterval` {number} _Deprecated: use h2Options.pingInterval instead_ The time interval, in milliseconds, between HTTP/2
PING frames. Set to `0` to disable PING frames. Applies only to HTTP/2
connections and emits a `ping` event on the client. **Default:** `60e3`.
* `h2Options` {object} Set of options for HTTP/2 sessions
* `useH2c` {boolean} Enforces h2c (HTTP/2 cleartext) for non-HTTPS
connections. **Default:** `false`.
* `maxConcurrentStreams` {number} The maximum number of concurrent HTTP/2
streams for a single session. Once h2 is negotiated this — not `pipelining`,
which is HTTP/1.1 only — is the ceiling used to dispatch in-flight requests.
It may be overridden by the server's `SETTINGS_MAX_CONCURRENT_STREAMS`
frame. **Default:** `100`.
* `connectionWindowSize` {number} The HTTP/2 connection-level flow-control
window size set via `ClientHttp2Session.setLocalWindowSize()`. Must be a
positive integer. **Default:** `524288`.
* `pingInterval` {number} The time interval, in milliseconds, between HTTP/2
PING frames. Set to `0` to disable PING frames. Applies only to HTTP/2
connections and emits a `ping` event on the client. **Default:** `60e3`.
* `settings` {object} `SETTINGS` frame options. For full reference, take a
look to [HTTP/2#Settings Object](https://nodejs.org/api/http2.html#settings-object)
* `webSocket` {Object} (optional) WebSocket-specific configuration.
* `maxFragments` {number} The maximum number of fragments in a message. Set
to `0` to disable the limit. **Default:** `131072`.
* `maxPayloadSize` {number} The 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. **Default:** `134217728`.
* `eventSource` {Object} (optional) EventSource-specific configuration.
* `maxEventSize` {number} The maximum allowed event size, in bytes, for
EventSource messages. Set to `0` to disable the limit.
**Default:** `buffer.kStringMaxLength`.
* Returns: {Client}
Instantiating a `Client` does not open a connection; the connection is
established lazily once a request is queued. Call `client.connect()` to connect
eagerly.
> Notes about HTTP/2:
>
> * Pseudo headers (`:path`, `:method`, `:scheme`, `:authority`) are attached
> automatically and overwrite any user-provided values.
> * The server must support HTTP/2 and select it during ALPN negotiation, and
> must not give HTTP/1.1 a higher priority than HTTP/2.
> * `PUSH` frames are not supported.
```mjs displayName="Basic instantiation"
import { Client } from 'undici'
const client = new Client('http://localhost:3000')
```
```mjs displayName="TLS options (object connector)"
import { Client } from 'undici'
import { readFileSync } from 'node:fs'
const client = new Client('https://localhost:3000', {
connect: {
rejectUnauthorized: false,
ca: readFileSync('./ca-cert.pem')
}
})
```
```mjs displayName="Unix domain socket"
import { Client } from 'undici'
const client = new Client('http://localhost:3000', {
connect: {
socketPath: '/var/run/docker.sock'
}
})
```
```mjs displayName="Custom DNS lookup"
import { Client } from 'undici'
import dns from 'node:dns'
const client = new Client('https://example.com', {
connect: {
lookup (hostname, options, callback) {
dns.lookup(hostname, { ...options, family: 4 }, callback)
}
}
})
```
```mjs displayName="Custom connector (function)"
import { Client, buildConnector } from 'undici'
const connector = buildConnector({ rejectUnauthorized: false })
const client = new Client('https://localhost:3000', {
connect (opts, cb) {
connector(opts, (err, socket) => {
if (err) {
cb(err)
} else {
cb(null, socket)
}
})
}
})
```
When a connector function is provided, undici wraps it to automatically inject
`socketPath` and `allowH2` into the `options` argument when those values are set
on the client. See [`Connector`][] for details on building custom connectors.
### `client.close([callback])`
<!-- YAML
added: v1.0.0
-->
Implements [`dispatcher.close([callback])`][]. Closes the client gracefully,
waiting for enqueued requests to complete before resolving.
### `client.destroy([error[, callback]])`
<!-- YAML
added: v1.0.0
-->
Implements [`dispatcher.destroy([error[, callback]])`][]. Destroys the client
abruptly, aborting all pending and running requests, and waits until the socket
is closed before invoking `callback` (or resolving the returned promise).
### `client.connect(options[, callback])`
<!-- YAML
added: v1.0.0
-->
* `options` {Object} The connect options, identical to
[`dispatcher.connect()`][] except that `origin` is omitted because the client
is bound to a single origin.
* `callback` {Function} (optional)
* Returns: {Promise|void} A promise when `callback` is not provided.
Starts a connection to the client's origin and tunnels a connection through it,
as defined by [`dispatcher.connect()`][].
### `client.dispatch(options, handlers)`
<!-- YAML
added: v1.0.0
-->
Implements [`dispatcher.dispatch(options, handler)`][]. This is the lowest-level
API used by all other request methods; prefer `client.request()` for most use
cases.
### `client.pipeline(options, handler)`
<!-- YAML
added: v1.0.0
-->
See [`dispatcher.pipeline(options, handler)`][]. Sends a request and returns a
{Duplex} stream that the request body is written to and the response body is
read from.
### `client.request(options[, callback])`
<!-- YAML
added: v1.0.0
-->
* `options` {Object}
* `callback` {Function} (optional)
* Returns: {Promise|void} A promise resolving to the response data when
`callback` is not provided.
See [`dispatcher.request(options[, callback])`][]. Performs an HTTP request and
returns its status code, headers, trailers, and a readable body stream.
```mjs
import { Client } from 'undici'
const client = new Client('http://localhost:3000')
const { statusCode, headers, body } = await client.request({
path: '/',
method: 'GET'
})
console.log(statusCode)
for await (const chunk of body) {
console.log(chunk.toString())
}
```
### `client.stream(options, factory[, callback])`
<!-- YAML
added: v1.0.0
-->
* `options` {Object}
* `factory` {Function} Returns a {Writable} the response body is piped into.
* `callback` {Function} (optional)
* Returns: {Promise|void} A promise when `callback` is not provided.
See [`dispatcher.stream(options, factory[, callback])`][]. A faster alternative
to `client.request()` when the destination of the response body is known in
advance.
### `client.upgrade(options[, callback])`
<!-- YAML
added: v1.0.0
-->
* `options` {Object}
* `callback` {Function} (optional)
* Returns: {Promise|void} A promise when `callback` is not provided.
See [`dispatcher.upgrade(options[, callback])`][]. Upgrades a connection to a
different protocol, such as for WebSocket or HTTP `CONNECT`.
### `client.closed`
<!-- YAML
added: v1.0.0
-->
* Type: {boolean}
`true` after `client.close()` has been called.
### `client.destroyed`
<!-- YAML
added: v1.0.0
-->
* Type: {boolean}
`true` after `client.destroy()` has been called, or after `client.close()` has
been called and the client shutdown has completed.
### `client.pipelining`
<!-- YAML
added: v1.0.0
-->
* Type: {number}
The pipelining factor. This property can be read and written to adjust the
number of concurrent requests sent over the connection. Only enable pipelining
with trusted remote servers.
### `client.stats`
<!-- YAML
added: v7.9.0
-->
* Type: {ClientStats}
Aggregate statistics for the client. See [`ClientStats`][].
### Event: `'connect'`
<!-- YAML
added: v1.0.0
-->
* `origin` {URL}
* `targets` {Array<Dispatcher>}
Emitted when a socket has been created and connected. The client connects once
`client.size > 0`. See [`Dispatcher` Event: `'connect'`][].
```mjs
import { createServer } from 'node:http'
import { Client } from 'undici'
import { once } from 'node:events'
const server = createServer((request, response) => {
response.end('Hello, World!')
}).listen()
await once(server, 'listening')
const client = new Client(`http://localhost:${server.address().port}`)
client.on('connect', (origin) => {
console.log(`Connected to ${origin}`)
})
const { body } = await client.request({ path: '/', method: 'GET' })
body.setEncoding('utf8')
body.on('data', console.log)
client.close()
server.close()
```
### Event: `'disconnect'`
<!-- YAML
added: v1.0.0
changes:
- version: v4.0.0
pr-url: https://github.com/nodejs/undici/pull/771
description: The event is only emitted if the client had previously
connected.
-->
* `origin` {URL}
* `targets` {Array<Dispatcher>}
* `error` {Error}
Emitted when a socket has disconnected. The `error` argument is the error that
caused the disconnection. The client reconnects if or once `client.size > 0`.
See [`Dispatcher` Event: `'disconnect'`][].
```mjs
import { createServer } from 'node:http'
import { Client } from 'undici'
import { once } from 'node:events'
const server = createServer((request, response) => {
response.destroy()
}).listen()
await once(server, 'listening')
const client = new Client(`http://localhost:${server.address().port}`)
client.on('disconnect', (origin) => {
console.log(`Disconnected from ${origin}`)
})
try {
await client.request({ path: '/', method: 'GET' })
} catch (error) {
console.error(error.message)
} finally {
client.close()
server.close()
}
```
### Event: `'drain'`
<!-- YAML
added: v1.0.0
-->
* `origin` {URL}
Emitted when the pipeline is no longer busy. See
[`Dispatcher` Event: `'drain'`][].
```mjs
import { createServer } from 'node:http'
import { Client } from 'undici'
import { once } from 'node:events'
const server = createServer((request, response) => {
response.end('Hello, World!')
}).listen()
await once(server, 'listening')
const client = new Client(`http://localhost:${server.address().port}`)
client.on('drain', () => {
console.log('drain event')
client.close()
server.close()
})
await Promise.all([
client.request({ path: '/', method: 'GET' }),
client.request({ path: '/', method: 'GET' }),
client.request({ path: '/', method: 'GET' })
])
```
### Event: `'error'`
<!-- YAML
added: v1.0.0
-->
* `error` {Error}
Emitted for user errors, such as throwing inside an `onResponseError` handler.
[RFC 7230, section 6.3.2]: https://tools.ietf.org/html/rfc7230#section-6.3.2
[RFC 8305]: https://tools.ietf.org/html/rfc8305#section-5
[`Agent`]: Agent.md#class-agent
[`ClientStats`]: ClientStats.md
[`Connector`]: Connector.md
[`Dispatcher` Event: `'connect'`]: Dispatcher.md#event-connect
[`Dispatcher` Event: `'disconnect'`]: Dispatcher.md#event-disconnect
[`Dispatcher` Event: `'drain'`]: Dispatcher.md#event-drain
[`Dispatcher`]: Dispatcher.md#class-dispatcher
[`Pool`]: Pool.md#class-pool
[`buildConnector`]: Connector.md
[`dispatcher.close([callback])`]: Dispatcher.md#dispatcherclosecallback
[`dispatcher.connect()`]: Dispatcher.md#dispatcherconnectoptions-callback
[`dispatcher.destroy([error[, callback]])`]: Dispatcher.md#dispatcherdestroyerror-callback
[`dispatcher.dispatch(options, handler)`]: Dispatcher.md#dispatcherdispatchoptions-handler
[`dispatcher.pipeline(options, handler)`]: Dispatcher.md#dispatcherpipelineoptions-handler
[`dispatcher.request(options[, callback])`]: Dispatcher.md#dispatcherrequestoptions-callback
[`dispatcher.stream(options, factory[, callback])`]: Dispatcher.md#dispatcherstreamoptions-factory-callback
[`dispatcher.upgrade(options[, callback])`]: Dispatcher.md#dispatcherupgradeoptions-callback
[`tls.connect()`]: https://nodejs.org/api/tls.html#tlsconnectoptions-callback
node_modules/undici/docs/docs/api/ClientStats.md
Generated Vendored
+93
View File
@@ -0,0 +1,93 @@
# ClientStats
<!--introduced_in=v7.9.0-->
<!--type=module-->
<!-- source_link=lib/util/stats.js -->
> Stability: 2 - Stable
A `ClientStats` is a point-in-time snapshot of the connection and request
state of a single [`Client`][]. Instances are not created directly; a fresh
snapshot is produced each time the [`client.stats`][] getter is read.
```mjs
import { Client } from 'undici'
const client = new Client('http://localhost:3000')
const stats = client.stats
console.log(stats.connected, stats.running)
```
```cjs
const { Client } = require('undici')
const client = new Client('http://localhost:3000')
const stats = client.stats
console.log(stats.connected, stats.running)
```
## Class: `ClientStats`
<!-- YAML
added: v7.9.0
-->
Captures the connection and request counters of a [`Client`][] at the moment
the snapshot is taken. The values are read from the client at construction time
and do not update afterwards; read [`client.stats`][] again for current values.
### `new ClientStats(client)`
<!-- YAML
added: v7.9.0
-->
* `client` {Client} The client to read the statistics from.
Creates a snapshot from the supplied `client`. This constructor is used
internally by the [`client.stats`][] getter and is not normally invoked by
application code.
### `clientStats.connected`
<!-- YAML
added: v7.9.0
-->
* Type: {boolean}
`true` when the client currently has an open socket connection.
### `clientStats.pending`
<!-- YAML
added: v7.9.0
-->
* Type: {number}
Number of open socket connections of this client that do not have an active
request.
### `clientStats.running`
<!-- YAML
added: v7.9.0
-->
* Type: {number}
Number of currently active requests of this client.
### `clientStats.size`
<!-- YAML
added: v7.9.0
-->
* Type: {number}
Number of active, pending, or queued requests of this client.
[`Client`]: Client.md#class-client
[`client.stats`]: Client.md#clientstats
node_modules/undici/docs/docs/api/Connector.md
Generated Vendored
+198
View File
@@ -0,0 +1,198 @@
# Connector
<!--introduced_in=v4.3.0-->
<!--type=module-->
<!-- source_link=lib/core/connect.js -->
> Stability: 2 - Stable
undici opens the underlying socket for every request through a *connector*. By
default this is handled internally, so most applications never interact with the
connector directly. When a request needs additional control over the socket —
for example to inspect a TLS certificate, pin a CA fingerprint, or tunnel the
connection — a custom connector can be supplied through the `connect` option of
a [`Dispatcher`][].
Use the `buildConnector` helper to construct a connector with sensible defaults
and then wrap it:
```mjs
import { buildConnector } from 'undici'
const connector = buildConnector({ rejectUnauthorized: false })
```
`buildConnector` accepts the same TLS options as
[`tls.connect()`][tls.connect] in addition to the undici-specific options listed
below, and returns a [`connector`](#connectoroptions-callback) function that
undici invokes for each new connection.
## `buildConnector([options])`
<!-- YAML
added: v5.23.4
-->
* `options` {buildConnector.BuildOptions} (optional) Connection options. In
addition to every [`tls.connect()`][tls.connect] option, the following fields
are supported:
* `allowH2` {boolean} Whether to offer HTTP/2 (`h2`) during TLS ALPN
negotiation. **Default:** `true`.
* `preferH2` {boolean} 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 (for example, 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`. **Default:** `false`.
* `maxCachedSessions` {number|null} Maximum number of TLS sessions to cache for
reuse. Use `0` to disable TLS session caching. Must be a non-negative
integer. **Default:** `100`.
* `socketPath` {string|null} An IPC endpoint, either a Unix domain socket or a
Windows named pipe. **Default:** `null`.
* `timeout` {number|null} The connection timeout in milliseconds. A
[`ConnectTimeoutError`][] is raised when the socket fails to connect within
this period. **Default:** `10e3`.
* `port` {number} The port to connect to when one is not provided to the
connector. Defaults to `443` for `https:` and `80` otherwise.
* `keepAlive` {boolean|null} Whether to enable TCP keep-alive on the socket.
**Default:** `true`.
* `keepAliveInitialDelay` {number|null} The delay in milliseconds before the
first TCP keep-alive probe is sent on an idle socket. **Default:** `60e3`.
* `typeOfService` {number|null} The IP Type of Service (ToS) value to set on
the socket. **Default:** `null`.
* Returns: {buildConnector.connector} A
[`connector`](#connectoroptions-callback) function bound to the supplied
options.
Builds a connector function. `maxCachedSessions` must be a non-negative integer
or an [`InvalidArgumentError`][] is thrown.
The returned function may be passed directly as the `connect` option of a
[`Dispatcher`][], or wrapped to perform extra validation on each socket before it
is handed back to undici.
```mjs
import { Client, buildConnector } from 'undici'
const connector = buildConnector({ rejectUnauthorized: false })
const client = new Client('https://localhost:3000', {
connect (opts, cb) {
connector(opts, (err, socket) => {
if (err) {
cb(err)
} else if (/* assertion */ false) {
socket.destroy()
cb(new Error('kaboom'))
} else {
cb(null, socket)
}
})
}
})
```
## `connector(options, callback)`
<!-- YAML
added: v4.3.0
-->
* `options` {Object} Per-connection options provided by undici.
* `hostname` {string} The host to connect to.
* `host` {string} (optional) The value of the request `Host` header, used to
derive the TLS `servername` when one is not supplied.
* `protocol` {string} The request protocol, for example `'https:'` or
`'http:'`. A value of `'https:'` establishes a TLS connection.
* `port` {string} The port to connect to. Defaults to `443` for `https:` and
`80` otherwise.
* `servername` {string} (optional) The TLS Server Name Indication (SNI) value.
Derived from `host` when omitted.
* `localAddress` {string|null} (optional) The local address the socket should
connect from.
* `httpSocket` {Socket} (optional) An existing socket on which to establish the
secure connection rather than creating a new one. May only be supplied for a
TLS upgrade (`protocol` of `'https:'`).
* `callback` {Function} Called once the socket has connected or failed.
* `err` {Error|null} The connection error, or `null` on success.
* `socket` {Socket|TLSSocket|null} The connected socket, or `null` on failure.
* Returns: {Socket|TLSSocket} The socket being established.
The function returned by [`buildConnector()`](#buildconnectoroptions). undici
calls it for every new connection. It opens a [`net.Socket`][] for `http:`
targets or a [`tls.TLSSocket`][] for `https:` targets, applies TCP keep-alive and
the connect timeout, and invokes `callback` once the socket connects or errors.
The socket is also returned synchronously.
When connecting over TLS, established sessions are cached (subject to
`maxCachedSessions`) and reused for subsequent connections to the same
`servername` or `hostname`.
### Example: validate the CA fingerprint
A custom connector is a convenient place to verify the server certificate before
any request is sent over the socket.
```mjs
import { Client, buildConnector } from 'undici'
const caFingerprint = 'FO:OB:AR'
const connector = buildConnector({ rejectUnauthorized: false })
const client = new Client('https://localhost:3000', {
connect (opts, cb) {
connector(opts, (err, socket) => {
if (err) {
cb(err)
} else if (getIssuerCertificate(socket).fingerprint256 !== caFingerprint) {
socket.destroy()
cb(new Error('Fingerprint does not match or malformed certificate'))
} else {
cb(null, socket)
}
})
}
})
client.request({
path: '/',
method: 'GET'
}, (err, data) => {
if (err) throw err
const bufs = []
data.body.on('data', (buf) => {
bufs.push(buf)
})
data.body.on('end', () => {
console.log(Buffer.concat(bufs).toString('utf8'))
client.close()
})
})
function getIssuerCertificate (socket) {
let certificate = socket.getPeerCertificate(true)
while (certificate && Object.keys(certificate).length > 0) {
// Invalid certificate.
if (certificate.issuerCertificate == null) {
return null
}
// We have reached the root certificate. In case of self-signed
// certificates, `issuerCertificate` may be a circular reference.
if (certificate.fingerprint256 === certificate.issuerCertificate.fingerprint256) {
break
}
certificate = certificate.issuerCertificate
}
return certificate
}
```
[`ConnectTimeoutError`]: Errors.md#class-connecttimeouterror
[`Dispatcher`]: Dispatcher.md#class-dispatcher
[`InvalidArgumentError`]: Errors.md#class-invalidargumenterror
[`net.Socket`]: https://nodejs.org/api/net.html#class-netsocket
[`tls.TLSSocket`]: https://nodejs.org/api/tls.html#class-tlstlssocket
[tls.connect]: https://nodejs.org/api/tls.html#tlsconnectoptions-callback
node_modules/undici/docs/docs/api/ContentType.md
Generated Vendored
+97
View File
@@ -0,0 +1,97 @@
# MIME Type Parsing
<!--introduced_in=v4.13.0-->
<!--type=module-->
<!-- source_link=lib/web/fetch/data-url.js -->
> Stability: 2 - Stable
undici exposes helpers for parsing and serializing MIME types according to the
WHATWG [MIME Sniffing Standard][]. These are the same primitives undici uses
internally to interpret `Content-Type` headers and `data:` URLs.
Import the functions from `'undici'`:
```mjs
import { parseMIMEType, serializeAMimeType } from 'undici'
```
A parsed MIME type is represented as a plain object with the following shape:
* `type` {string} The lowercased type, for example `'text'`.
* `subtype` {string} The lowercased subtype, for example `'html'`.
* `parameters` {Map<string, string>} The parameters, keyed by lowercased
parameter name.
* `essence` {string} The concatenation of `type`, `'/'`, and `subtype`, for
example `'text/html'`.
## `parseMIMEType(input)`
<!-- YAML
added: v4.13.0
-->
* `input` {string} The MIME type string to parse.
* Returns: {Object|string} A parsed MIME type record, or the string literal
`'failure'` when `input` cannot be parsed.
* `type` {string} The lowercased type.
* `subtype` {string} The lowercased subtype.
* `parameters` {Map<string, string>} The parsed parameters, keyed by
lowercased parameter name.
* `essence` {string} The MIME type essence, `` `${type}/${subtype}` ``.
Implements the WHATWG [parse a MIME type][] algorithm. The `type` and `subtype`
are lowercased, and only the first occurrence of a duplicate parameter name is
retained. When `input` is empty, lacks a `/`, or otherwise violates the grammar,
the string literal `'failure'` is returned instead of a record.
```mjs
import { parseMIMEType } from 'undici'
parseMIMEType('text/html; charset=gbk')
// {
// type: 'text',
// subtype: 'html',
// parameters: Map(1) { 'charset' => 'gbk' },
// essence: 'text/html'
// }
parseMIMEType('not a mime type')
// 'failure'
```
## `serializeAMimeType(mimeType)`
<!-- YAML
added: v5.11.0
-->
* `mimeType` {Object} A MIME type record, as returned by [`parseMIMEType()`][].
* `type` {string} The type.
* `subtype` {string} The subtype.
* `parameters` {Map<string, string>} The parameters to serialize, in
insertion order.
* `essence` {string} The MIME type essence, `` `${type}/${subtype}` ``.
* Returns: {string} The serialized MIME type.
Implements the WHATWG [serialize a MIME type][] algorithm. The essence is
emitted followed by each parameter as `;name=value`. A parameter value that
contains characters outside the HTTP token set is quoted, and any `"` or `\`
characters within it are escaped.
```mjs
import { serializeAMimeType } from 'undici'
serializeAMimeType({
type: 'text',
subtype: 'html',
parameters: new Map([['charset', 'gbk']]),
essence: 'text/html'
})
// 'text/html;charset=gbk'
```
[MIME Sniffing Standard]: https://mimesniff.spec.whatwg.org/
[`parseMIMEType()`]: #parsemimetypeinput
[parse a MIME type]: https://mimesniff.spec.whatwg.org/#parse-a-mime-type
[serialize a MIME type]: https://mimesniff.spec.whatwg.org/#serialize-a-mime-type
node_modules/undici/docs/docs/api/Cookies.md
Generated Vendored
+179
View File
@@ -0,0 +1,179 @@
# Cookies
<!--introduced_in=v5.15.0-->
<!--type=module-->
<!-- source_link=lib/web/cookies/index.js -->
> Stability: 2 - Stable
A set of helpers for reading and writing HTTP cookies on a [`Headers`][]
instance, following the [RFC 6265bis][] cookie parsing and serialization
algorithm. They operate on the `Cookie` request header and the `Set-Cookie`
response header.
```mjs
import { getCookies, setCookie, deleteCookie, getSetCookies, parseCookie } from 'undici'
```
These functions do not manage a cookie jar or perform any network activity; they
only read from and mutate the supplied `Headers` object.
## `Cookie`
The `Cookie` object describes a single cookie and its attributes. It is the
return shape of [`parseCookie()`][] and [`getSetCookies()`][], and the input
shape accepted by [`setCookie()`][].
* `name` {string} The cookie name.
* `value` {string} The cookie value.
* `expires` {Date|number} The cookie expiry time, as a `Date` or a Unix
timestamp in seconds. (optional)
* `maxAge` {number} The number of seconds until the cookie expires. (optional)
* `domain` {string} The hosts the cookie is sent to. (optional)
* `path` {string} The URL path that must exist for the cookie to be sent.
(optional)
* `secure` {boolean} Whether the cookie is only sent over HTTPS. (optional)
* `httpOnly` {boolean} Whether the cookie is inaccessible to client-side
JavaScript. (optional)
* `sameSite` {string} Controls whether the cookie is sent with cross-site
requests. One of `'Strict'`, `'Lax'`, or `'None'`. (optional)
* `unparsed` {string[]} Any attributes that were present in the `Set-Cookie`
header but not recognized, each formatted as `` `name=value` ``. (optional)
## `getCookies(headers)`
<!-- YAML
added: v5.15.0
-->
* `headers` {Headers} The `Headers` to read the `Cookie` header from.
* Returns: {Record<string, string>} A map of cookie names to values.
Parses the `Cookie` header of `headers` and returns its name/value pairs as a
plain object. An empty object is returned when no `Cookie` header is present.
```mjs
import { getCookies, Headers } from 'undici'
const headers = new Headers({
cookie: 'get=cookies; and=attributes'
})
console.log(getCookies(headers)) // { get: 'cookies', and: 'attributes' }
```
## `deleteCookie(headers, name[, attributes])`
<!-- YAML
added: v5.15.0
-->
* `headers` {Headers} The `Headers` to append the expiring cookie to.
* `name` {string} The name of the cookie to delete.
* `attributes` {Object} (optional)
* `path` {string} The path the cookie was scoped to. **Default:** `null`.
* `domain` {string} The domain the cookie was scoped to. **Default:** `null`.
* Returns: {undefined}
Appends a `Set-Cookie` header to `headers` that expires the named cookie by
setting its expiry time to the Unix epoch, causing a client to delete it on
receipt. The optional `path` and `domain` must match those of the cookie being
removed.
```mjs
import { deleteCookie, Headers } from 'undici'
const headers = new Headers()
deleteCookie(headers, 'name')
console.log(headers.get('set-cookie')) // name=; Expires=Thu, 01 Jan 1970 00:00:00 GMT
```
## `getSetCookies(headers)`
<!-- YAML
added: v5.15.0
-->
* `headers` {Headers} The `Headers` to read the `Set-Cookie` headers from.
* Returns: {Cookie[]} The parsed cookies, or an empty array when none are
present.
Parses every `Set-Cookie` header of `headers` and returns the resulting
[`Cookie`][] objects. A header that fails to parse yields a `null` entry at its
position in the returned array.
```mjs
import { getSetCookies, Headers } from 'undici'
const headers = new Headers({ 'set-cookie': 'undici=getSetCookies; Secure' })
console.log(getSetCookies(headers))
// [
// {
// name: 'undici',
// value: 'getSetCookies',
// secure: true
// }
// ]
```
## `setCookie(headers, cookie)`
<!-- YAML
added: v5.15.0
-->
* `headers` {Headers} The `Headers` to append the `Set-Cookie` header to.
* `cookie` {Cookie} The cookie to serialize. See [`Cookie`][].
* Returns: {undefined}
Serializes `cookie` and appends it to the `Set-Cookie` header of `headers`. When
the cookie name is empty, serialization yields no value and no header is
appended.
```mjs
import { setCookie, Headers } from 'undici'
const headers = new Headers()
setCookie(headers, { name: 'undici', value: 'setCookie' })
console.log(headers.get('Set-Cookie')) // undici=setCookie
```
## `parseCookie(cookie)`
<!-- YAML
added: v7.0.0
-->
* `cookie` {string} A `Set-Cookie` header value.
* Returns: {Cookie|null} The parsed cookie, or `null` if `cookie` is invalid.
Parses a single `Set-Cookie` header value into a [`Cookie`][] object. `null` is
returned when the value contains control characters or otherwise cannot be
parsed.
```mjs
import { parseCookie } from 'undici'
console.log(parseCookie('undici=getSetCookies; Secure; SameSite=Lax'))
// {
// name: 'undici',
// value: 'getSetCookies',
// secure: true,
// sameSite: 'Lax'
// }
```
The cookie value is returned exactly as it appears in the header; percent-encoded
sequences such as `%20` or `%0D%0A` are not decoded. The `sameSite` attribute is
only set when the value is a case-insensitive match for `Strict`, `Lax`, or
`None`.
[RFC 6265bis]: https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis
[`Cookie`]: #cookie
[`Headers`]: https://developer.mozilla.org/en-US/docs/Web/API/Headers
[`getSetCookies()`]: #getsetcookiesheaders
[`parseCookie()`]: #parsecookiecookie
[`setCookie()`]: #setcookieheaders-cookie
node_modules/undici/docs/docs/api/Debug.md
Generated Vendored
+78
View File
@@ -0,0 +1,78 @@
# Debug
<!--type=misc-->
Undici emits human-readable debug logs through Node.js' built-in
[`util.debuglog()`][]. The logs are disabled by default and are turned on by
listing one or more namespaces in the `NODE_DEBUG` environment variable. Because
`util.debuglog()` reads `NODE_DEBUG` once, when the namespace is first used, the
variable must be set before the process starts.
Each log line is prefixed with the namespace (uppercased) and the process id,
for example `UNDICI 16241: connecting to nodejs.org using https:h1`. Multiple
namespaces can be enabled at once by separating them with commas, for example
`NODE_DEBUG=undici,websocket`.
The following sections describe the namespaces exposed by undici.
## `undici`
Enables debug logs for the core undici library, covering connection setup,
request dispatch, responses, and trailers. The `fetch` and `websocket` APIs are
built on top of this core, so enabling `undici` also surfaces activity that
originates from them.
```console
$ NODE_DEBUG=undici node script.js
UNDICI 16241: connecting to nodejs.org using https:h1
UNDICI 16241: connecting to nodejs.org using https:h1
UNDICI 16241: connected to nodejs.org using https:h1
UNDICI 16241: sending request to GET https://nodejs.org/
UNDICI 16241: received response to GET https://nodejs.org/ - HTTP 307
UNDICI 16241: connecting to nodejs.org using https:h1
UNDICI 16241: trailers received from GET https://nodejs.org/
UNDICI 16241: connected to nodejs.org using https:h1
UNDICI 16241: sending request to GET https://nodejs.org/en
UNDICI 16241: received response to GET https://nodejs.org/en - HTTP 200
UNDICI 16241: trailers received from GET https://nodejs.org/en
```
## `fetch`
Enables debug logs scoped to the `fetch` API. The output mirrors the `undici`
namespace but is emitted only for requests made through [`fetch()`][], which
makes it useful for isolating `fetch` traffic from other undici activity.
```console
$ NODE_DEBUG=fetch node script.js
FETCH 16241: connecting to nodejs.org using https:h1
FETCH 16241: connecting to nodejs.org using https:h1
FETCH 16241: connected to nodejs.org using https:h1
FETCH 16241: sending request to GET https://nodejs.org/
FETCH 16241: received response to GET https://nodejs.org/ - HTTP 307
FETCH 16241: connecting to nodejs.org using https:h1
FETCH 16241: trailers received from GET https://nodejs.org/
FETCH 16241: connected to nodejs.org using https:h1
FETCH 16241: sending request to GET https://nodejs.org/en
FETCH 16241: received response to GET https://nodejs.org/en - HTTP 200
FETCH 16241: trailers received from GET https://nodejs.org/en
```
## `websocket`
Enables debug logs scoped to the [`WebSocket`][] API, covering the opening
handshake and connection lifecycle. When the `undici` or `fetch` namespace is
also enabled, some lines may appear under both namespaces because the handshake
is performed through the core library.
```console
$ NODE_DEBUG=websocket node script.js
WEBSOCKET 18309: connecting to echo.websocket.org using https:h1
WEBSOCKET 18309: connected to echo.websocket.org using https:h1
WEBSOCKET 18309: sending request to GET https://echo.websocket.org/
WEBSOCKET 18309: connection opened <ip_address>
```
[`WebSocket`]: WebSocket.md#class-websocket
[`fetch()`]: Fetch.md
[`util.debuglog()`]: https://nodejs.org/api/util.html#utildebuglogsection-callback
node_modules/undici/docs/docs/api/DiagnosticsChannel.md
Generated Vendored
+518
View File
@@ -0,0 +1,518 @@
# Diagnostics Channel Support
<!--introduced_in=v6.3.0-->
<!--type=misc-->
> Stability: 1 - Experimental
Undici is instrumented with Node.js' built-in [`diagnostics_channel`][] module.
It is the preferred way to observe undici's internal behaviour without patching
the library, and it backs the human-readable [debug logs][Debug].
Each integration point is exposed as a named channel. To observe an event,
obtain the channel by name and subscribe to it:
```mjs
import diagnosticsChannel from 'node:diagnostics_channel'
diagnosticsChannel.channel('undici:request:create').subscribe(({ request }) => {
console.log(request.method, request.origin, request.path)
})
```
```cjs
const diagnosticsChannel = require('node:diagnostics_channel')
diagnosticsChannel.channel('undici:request:create').subscribe(({ request }) => {
console.log(request.method, request.origin, request.path)
})
```
The message published to a channel is always a single object whose shape depends
on the channel. The sections below describe every channel and the object it
publishes. Subscriber callbacks run synchronously inside undici, so they should
be fast and must not throw.
The same `request` object is shared across all `undici:request:*` channels for a
given request, so a subscriber may correlate the lifecycle of one request by
identity.
## Event: `'undici:request:create'`
<!-- YAML
added: v6.3.0
-->
Published when a new outgoing request is created, before it is dispatched.
* `message` {Object}
* `request` {Object} The request being created.
* `origin` {string|URL} The origin the request is sent to.
* `completed` {boolean} Whether the request has completed. `false` at this
point.
* `method` {string} The HTTP method, e.g. `'GET'`.
* `path` {string} The request path, including any query string.
* `headers` {string[]} The request headers as a flat array of strings,
alternating between header name and value.
The `request` object also exposes an `addHeader(name, value)` method that
appends a header before the request is sent.
```mjs
import diagnosticsChannel from 'node:diagnostics_channel'
diagnosticsChannel.channel('undici:request:create').subscribe(({ request }) => {
console.log('origin', request.origin)
console.log('completed', request.completed)
console.log('method', request.method)
console.log('path', request.path)
console.log('headers', request.headers)
request.addHeader('hello', 'world')
})
```
A request is only loosely bound to a given socket at this stage.
## Event: `'undici:request:bodyChunkSent'`
<!-- YAML
added: v7.11.0
-->
Published each time a chunk of the request body is written to the socket.
* `message` {Object}
* `request` {Object} The same object published by
[`'undici:request:create'`][].
* `chunk` {Uint8Array|string} The body chunk being sent.
```mjs
import diagnosticsChannel from 'node:diagnostics_channel'
diagnosticsChannel.channel('undici:request:bodyChunkSent').subscribe(({ request, chunk }) => {
console.log('sent', chunk.length, 'bytes')
})
```
## Event: `'undici:request:bodySent'`
<!-- YAML
added: v6.3.0
-->
Published after the request body has been fully sent.
* `message` {Object}
* `request` {Object} The same object published by
[`'undici:request:create'`][].
```mjs
import diagnosticsChannel from 'node:diagnostics_channel'
diagnosticsChannel.channel('undici:request:bodySent').subscribe(({ request }) => {
// request is the same object as in 'undici:request:create'
})
```
## Event: `'undici:request:headers'`
<!-- YAML
added: v6.3.0
-->
Published after the response headers have been received. This includes a
successful CONNECT or protocol upgrade response.
* `message` {Object}
* `request` {Object} The same object published by
[`'undici:request:create'`][].
* `response` {Object} The response being received.
* `statusCode` {number} The HTTP status code.
* `statusText` {string} The HTTP status message.
* `headers` {Buffer[]|Object} HTTP/1.1 response headers are an array of
buffers alternating between header name and value. HTTP/2 response
headers are an object.
```mjs
import diagnosticsChannel from 'node:diagnostics_channel'
diagnosticsChannel.channel('undici:request:headers').subscribe(({ request, response }) => {
console.log('statusCode', response.statusCode)
console.log(response.statusText)
console.log(response.headers)
})
```
## Event: `'undici:request:bodyChunkReceived'`
<!-- YAML
added: v7.11.0
-->
Published each time a chunk of the response body is received.
* `message` {Object}
* `request` {Object} The same object published by
[`'undici:request:create'`][].
* `chunk` {Buffer} The body chunk that was received.
```mjs
import diagnosticsChannel from 'node:diagnostics_channel'
diagnosticsChannel.channel('undici:request:bodyChunkReceived').subscribe(({ request, chunk }) => {
console.log('received', chunk.length, 'bytes')
})
```
## Event: `'undici:request:trailers'`
<!-- YAML
added: v6.3.0
-->
Published once the response has fully completed. After an upgraded socket has
been passed to the request handler, this event is published with an empty
`trailers` array.
* `message` {Object}
* `request` {Object} The same object published by
[`'undici:request:create'`][]. `request.completed` is now `true`.
* `trailers` {Buffer[]} The raw response trailers as an array of buffers,
alternating between header name and value.
```mjs
import diagnosticsChannel from 'node:diagnostics_channel'
diagnosticsChannel.channel('undici:request:trailers').subscribe(({ request, trailers }) => {
console.log('completed', request.completed)
console.log(trailers.map((x) => x.toString()))
})
```
## Event: `'undici:request:error'`
<!-- YAML
added: v6.3.0
-->
Published when the request is about to error, before the error is surfaced to
the caller.
* `message` {Object}
* `request` {Object} The same object published by
[`'undici:request:create'`][].
* `error` {Error} The error the request is about to fail with.
```mjs
import diagnosticsChannel from 'node:diagnostics_channel'
diagnosticsChannel.channel('undici:request:error').subscribe(({ request, error }) => {
console.error(error)
})
```
## Event: `'undici:client:sendHeaders'`
<!-- YAML
added: v6.3.0
changes:
- version: v7.0.0
pr-url: https://github.com/nodejs/undici/pull/3585
description: Refactor the diagnostics channel internals.
-->
Published immediately before the first byte of the request is written to the
socket. The headers are published exactly as they will be sent to the server, in
raw form.
* `message` {Object}
* `request` {Object} The same object published by
[`'undici:request:create'`][].
* `headers` {string} The request headers as a single raw string, with lines
separated by `\r\n`.
* `socket` {net.Socket} The socket the request is written to.
```mjs
import diagnosticsChannel from 'node:diagnostics_channel'
diagnosticsChannel.channel('undici:client:sendHeaders').subscribe(({ request, headers, socket }) => {
console.log(`Full headers list: ${headers.split('\r\n')}`)
})
```
## Event: `'undici:client:beforeConnect'`
<!-- YAML
added: v6.3.0
changes:
- version: v7.0.0
pr-url: https://github.com/nodejs/undici/pull/3585
description: Refactor the diagnostics channel internals.
-->
Published before a new connection is opened for any request. This event cannot be
attributed to a specific request, because connections are pooled and shared.
* `message` {Object}
* `connectParams` {Object} The parameters used to open the connection.
* `host` {string} The connection host, including the port if present.
* `hostname` {string} The connection hostname.
* `protocol` {string} The protocol, e.g. `'https:'`.
* `port` {string} The connection port.
* `servername` {string|null} The TLS server name, or `null`.
* `connector` {Function} The function that creates the socket.
```mjs
import diagnosticsChannel from 'node:diagnostics_channel'
diagnosticsChannel.channel('undici:client:beforeConnect').subscribe(({ connectParams, connector }) => {
const { host, hostname, protocol, port, servername } = connectParams
// connector is the function that creates the socket
})
```
## Event: `'undici:client:connected'`
<!-- YAML
added: v6.3.0
changes:
- version: v7.0.0
pr-url: https://github.com/nodejs/undici/pull/3585
description: Refactor the diagnostics channel internals.
-->
Published after a connection has been successfully established.
* `message` {Object}
* `socket` {net.Socket} The newly connected socket.
* `connectParams` {Object} The parameters used to open the connection. See
[`'undici:client:beforeConnect'`][] for the field descriptions.
* `connector` {Function} The function that created the socket.
```mjs
import diagnosticsChannel from 'node:diagnostics_channel'
diagnosticsChannel.channel('undici:client:connected').subscribe(({ socket, connectParams, connector }) => {
const { host, hostname, protocol, port, servername } = connectParams
})
```
## Event: `'undici:client:connectError'`
<!-- YAML
added: v6.3.0
changes:
- version: v7.0.0
pr-url: https://github.com/nodejs/undici/pull/3585
description: Refactor the diagnostics channel internals.
-->
Published when a connection could not be established.
* `message` {Object}
* `error` {Error} The error that prevented the connection.
* `socket` {net.Socket} The socket associated with the failed attempt.
* `connectParams` {Object} The parameters used to open the connection. See
[`'undici:client:beforeConnect'`][] for the field descriptions.
* `connector` {Function} The function that created the socket.
```mjs
import diagnosticsChannel from 'node:diagnostics_channel'
diagnosticsChannel.channel('undici:client:connectError').subscribe(({ error, socket, connectParams, connector }) => {
console.error(`Connect failed with ${error.message}`)
})
```
## Event: `'undici:websocket:open'`
<!-- YAML
added: v6.3.0
-->
Published after a [`WebSocket`][] has successfully connected to a server.
* `message` {Object}
* `address` {Object|null} The remote socket address, as returned by
[`socket.address()`][], or `null` if it cannot be determined. When present,
it contains `address`, `family`, and `port`.
* `protocol` {string} The negotiated subprotocol.
* `extensions` {string} The negotiated extensions.
* `websocket` {WebSocket} The `WebSocket` instance.
* `handshakeResponse` {Object} The HTTP response that upgraded the connection.
* `status` {number} The HTTP status code: `101` for an HTTP/1.1 upgrade, or
`200` for an HTTP/2 extended `CONNECT`.
* `statusText` {string} The HTTP status message: `'Switching Protocols'` for
HTTP/1.1, and commonly `'OK'` for HTTP/2.
* `headers` {Object} The response headers from the server. The `upgrade` and
`connection` headers are only present for HTTP/1.1 handshakes.
```mjs
import diagnosticsChannel from 'node:diagnostics_channel'
diagnosticsChannel.channel('undici:websocket:open').subscribe(({
address,
protocol,
extensions,
websocket,
handshakeResponse
}) => {
console.log(address)
console.log(protocol)
console.log(extensions)
console.log(handshakeResponse.status)
console.log(handshakeResponse.headers)
})
```
## Event: `'undici:websocket:close'`
<!-- YAML
added: v6.3.0
-->
Published after the [`WebSocket`][] connection has closed.
* `message` {Object}
* `websocket` {WebSocket} The `WebSocket` instance.
* `code` {number} The closing status code.
* `reason` {string} The closing reason.
```mjs
import diagnosticsChannel from 'node:diagnostics_channel'
diagnosticsChannel.channel('undici:websocket:close').subscribe(({ websocket, code, reason }) => {
console.log(code, reason)
})
```
## Event: `'undici:websocket:socket_error'`
<!-- YAML
added: v6.3.0
-->
Published when the underlying WebSocket socket experiences an error. Unlike the
other WebSocket channels, the published message is the error itself.
* `error` {Error} The socket error.
```mjs
import diagnosticsChannel from 'node:diagnostics_channel'
diagnosticsChannel.channel('undici:websocket:socket_error').subscribe((error) => {
console.error(error)
})
```
## Event: `'undici:websocket:ping'`
<!-- YAML
added: v6.3.0
-->
Published after the client receives a ping frame.
* `message` {Object}
* `payload` {Buffer|undefined} The optional application data carried by the
frame.
* `websocket` {WebSocket} The `WebSocket` instance.
```mjs
import diagnosticsChannel from 'node:diagnostics_channel'
diagnosticsChannel.channel('undici:websocket:ping').subscribe(({ payload, websocket }) => {
console.log(payload)
})
```
## Event: `'undici:websocket:pong'`
<!-- YAML
added: v6.3.0
-->
Published after the client receives a pong frame.
* `message` {Object}
* `payload` {Buffer|undefined} The optional application data carried by the
frame.
* `websocket` {WebSocket} The `WebSocket` instance.
```mjs
import diagnosticsChannel from 'node:diagnostics_channel'
diagnosticsChannel.channel('undici:websocket:pong').subscribe(({ payload, websocket }) => {
console.log(payload)
})
```
## Event: `'undici:proxy:connected'`
<!-- YAML
added: v7.17.0
-->
Published after a [`ProxyAgent`][] has established a tunnel to the proxy server.
* `message` {Object}
* `socket` {net.Socket} The socket connected to the proxy.
* `connectParams` {Object} The parameters used to establish the tunnel.
* `origin` {string|URL} The proxy origin.
* `port` {string} The proxy port.
* `path` {string} The requested tunnel target, e.g. `'example.com:443'`.
* `signal` {AbortSignal|undefined} The signal associated with the request.
* `headers` {Object} The headers sent in the `CONNECT` request.
* `servername` {string|undefined} The TLS server name used for the proxy.
```mjs
import diagnosticsChannel from 'node:diagnostics_channel'
diagnosticsChannel.channel('undici:proxy:connected').subscribe(({ socket, connectParams }) => {
const { origin, port, path, signal, headers, servername } = connectParams
})
```
## Event: `'undici:request:pending-requests'`
<!-- YAML
added: v6.3.0
-->
Published when the [`dedupe`][] interceptor's set of pending requests changes.
The interceptor coalesces concurrent identical requests so that only one reaches
the origin; this channel exposes that bookkeeping for monitoring and debugging.
* `message` {Object}
* `type` {string} Either `'added'` when a new pending request is registered, or
`'removed'` when a pending request completes, whether successfully or with an
error.
* `size` {number} The number of pending requests after the change.
* `key` {string} The deduplication key for the request, composed of the origin,
method, path, and request headers.
```mjs
import diagnosticsChannel from 'node:diagnostics_channel'
diagnosticsChannel.channel('undici:request:pending-requests').subscribe(({ type, size, key }) => {
if (type === 'added') {
console.log(`New pending request: ${key} (${size} total pending)`)
} else {
console.log(`Request completed: ${key} (${size} remaining)`)
}
})
```
This is useful for verifying that deduplication is working, monitoring the number
of concurrent in-flight requests, and debugging deduplication behaviour in
production.
[`'undici:client:beforeConnect'`]: #event-undiciclientbeforeconnect
[`'undici:request:create'`]: #event-undicirequestcreate
[`'undici:request:headers'`]: #event-undicirequestheaders
[`ProxyAgent`]: ProxyAgent.md#class-proxyagent
[`WebSocket`]: WebSocket.md#class-websocket
[`dedupe`]: Dispatcher.md#dedupe
[`diagnostics_channel`]: https://nodejs.org/api/diagnostics_channel.html
[`socket.address()`]: https://nodejs.org/api/net.html#socketaddress
[Debug]: Debug.md
node_modules/undici/docs/docs/api/Dispatcher.md
Generated Vendored
+836
View File
@@ -0,0 +1,836 @@
# Dispatcher
<!--introduced_in=v4.0.0-->
<!--type=module-->
<!-- source_link=lib/dispatcher/dispatcher.js -->
> Stability: 2 - Stable
`Dispatcher` is the core abstraction used to dispatch HTTP requests in undici.
It extends [`EventEmitter`][] and defines the low-level [`dispatch()`][] contract
along with the higher-level [`request()`][], [`stream()`][], [`pipeline()`][],
[`connect()`][], and [`upgrade()`][] methods that every concrete dispatcher
provides.
`Dispatcher` itself is abstract: its [`dispatch()`][], [`close()`][], and
[`destroy()`][] methods throw `Error: not implemented`. Concrete dispatchers such
as [`Client`][], [`Pool`][], [`BalancedPool`][], and [`Agent`][] implement the
contract and are what application code instantiates. Requests are not guaranteed
to be dispatched in the order in which they are invoked.
```mjs
import { Dispatcher, Agent } from 'undici'
const dispatcher = new Agent()
console.log(dispatcher instanceof Dispatcher) // true
```
## Class: `Dispatcher`
<!-- YAML
added: v4.0.0
-->
* Extends: {EventEmitter}
Base dispatcher class. Concrete dispatchers extend it and implement the
[`dispatch()`][] method on which the other request helpers are built.
### `dispatcher.close([callback])`
<!-- YAML
added: v4.0.0
-->
* `callback` {Function} (optional) Invoked once the dispatcher is closed.
* `error` {Error|null}
* Returns: {Promise} A `Promise` is returned only when `callback` is omitted. It
resolves with `void` once the dispatcher is closed.
Closes the dispatcher and gracefully waits for enqueued requests to complete
before resolving or invoking `callback`.
```mjs
import { createServer } from 'node:http'
import { Client } from 'undici'
import { once } from 'node:events'
const server = createServer((request, response) => {
response.end('undici')
}).listen()
await once(server, 'listening')
const client = new Client(`http://localhost:${server.address().port}`)
try {
const { body } = await client.request({ path: '/', method: 'GET' })
body.setEncoding('utf8')
body.on('data', console.log)
} catch (error) {}
await client.close()
console.log('Client closed')
server.close()
```
### `dispatcher.connect(options[, callback])`
<!-- YAML
added: v4.0.0
-->
* `options` {Object}
* `origin` {string|URL} The origin to connect to.
* `path` {string} The request path.
* `headers` {UndiciHeaders} Request headers. **Default:** `null`.
* `signal` {AbortSignal|EventEmitter|null} A signal used to abort the request.
**Default:** `null`.
* `opaque` {any} An opaque value passed through to the returned `ConnectData`.
* `responseHeaders` {string|null} Set to `'raw'` to return the response headers
as a raw array instead of an object. **Default:** `null`.
* `callback` {Function} (optional) Invoked when the connection is established.
* `error` {Error|null}
* `data` {Object}
* `statusCode` {number}
* `headers` {Object} The response headers.
* `socket` {Duplex} The established socket.
* `opaque` {any} The `opaque` value passed in `options`.
* Returns: {Promise} A `Promise` is returned only when `callback` is omitted. It
resolves with the `data` object described above.
Starts two-way communications with the requested resource using the
[HTTP `CONNECT`][] method.
```mjs
import { createServer } from 'node:http'
import { Client } from 'undici'
import { once } from 'node:events'
const server = createServer((request, response) => {
throw new Error('should never get here')
}).listen()
server.on('connect', (req, socket, head) => {
socket.write('HTTP/1.1 200 Connection established\r\n\r\n')
let data = head.toString()
socket.on('data', (buf) => {
data += buf.toString()
})
socket.on('end', () => {
socket.end(data)
})
})
await once(server, 'listening')
const client = new Client(`http://localhost:${server.address().port}`)
try {
const { socket } = await client.connect({ path: '/' })
const wanted = 'Body'
let data = ''
socket.on('data', d => { data += d })
socket.on('end', () => {
console.log(`Data received: ${data.toString()} | Data wanted: ${wanted}`)
client.close()
server.close()
})
socket.write(wanted)
socket.end()
} catch (error) {}
```
### `dispatcher.destroy([error[, callback]])`
<!-- YAML
added: v4.0.0
-->
* `error` {Error|null} (optional) The error with which pending requests are
rejected. **Default:** `null`.
* `callback` {Function} (optional) Invoked once the socket is closed.
* Returns: {Promise} A `Promise` is returned only when `callback` is omitted. It
resolves with `void` once the dispatcher is destroyed.
Destroys the dispatcher abruptly with the given `error`. All pending and running
requests are asynchronously aborted and rejected. Because the operation is
dispatched asynchronously, dispatched requests may still make some progress
before being aborted.
Both arguments are optional, so the method can be called in four ways:
```mjs
dispatcher.destroy() // -> Promise
dispatcher.destroy(new Error()) // -> Promise
dispatcher.destroy(() => {}) // -> void
dispatcher.destroy(new Error(), () => {}) // -> void
```
```mjs
import { createServer } from 'node:http'
import { Client } from 'undici'
import { once } from 'node:events'
const server = createServer((request, response) => {
response.end()
}).listen()
await once(server, 'listening')
const client = new Client(`http://localhost:${server.address().port}`)
try {
const request = client.request({ path: '/', method: 'GET' })
client.destroy()
.then(() => {
console.log('Client destroyed')
server.close()
})
await request
} catch (error) {
console.error(error)
}
```
### `dispatcher.dispatch(options, handler)`
<!-- YAML
added: v4.0.0
-->
* `options` {Object}
* `origin` {string|URL} (optional) The origin to dispatch the request to.
* `path` {string} The request path.
* `method` {string} The HTTP method, e.g. `'GET'` or `'POST'`.
* `body` {string|Buffer|Uint8Array|Readable|FormData|null} The request body.
**Default:** `null`.
* `headers` {UndiciHeaders} Request headers. **Default:** `null`.
* `query` {Object} Query string parameters embedded into the request URL. Both
keys and values are encoded with `encodeURIComponent`. **Default:** `null`.
* `idempotent` {boolean} Whether the request can be safely retried. If `false`,
the request is not sent until all preceding requests in the pipeline have
completed. **Default:** `true` when `method` is `'HEAD'` or `'GET'`.
* `blocking` {boolean} Whether the response is expected to block the pipeline.
When `true`, further pipelining on the same connection is avoided until
headers have been received. **Default:** `method !== 'HEAD'`.
* `typeOfService` {number|null} The IP Type of Service (ToS) value for the
request socket. Must be an integer between `0` and `255`. **Default:** `0`.
* `upgrade` {boolean|string|null} Upgrades the request, e.g. to `'Websocket'`.
**Default:** `null`, or the request method when it is `'CONNECT'`.
* `headersTimeout` {number|null} The time, in milliseconds, the parser waits to
receive the complete HTTP headers. Defaults to 300 seconds.
* `bodyTimeout` {number|null} The time, in milliseconds, after which the request
times out while receiving body data. Monitors the time between body chunks.
Use `0` to disable it entirely. Defaults to 300 seconds.
HTTP/1.1 headers/body parser timeouts are not guaranteed to fire with exact
millisecond precision: delays up to 1000ms use native timers, while larger
delays use undici's lower-overhead fast timers with a target resolution
around 500ms.
* `reset` {boolean} Whether the request should establish a keep-alive
connection. **Default:** `false`.
* `expectContinue` {boolean} For HTTP/2, appends the `expect: 100-continue`
header and halts the request body until a `100 Continue` is received from the
remote server. **Default:** `false`.
* `handler` {Object} A set of callbacks invoked over the request lifecycle.
* `onRequestStart` {Function} Invoked before the request is dispatched on the
socket. May be invoked multiple times when the request is retried.
* `controller` {DispatchController}
* `context` {any}
* `onRequestUpgrade` {Function} (optional) Invoked when the request is upgraded.
Required when `options.upgrade` is set or `options.method` is `'CONNECT'`.
* `controller` {DispatchController}
* `statusCode` {number}
* `headers` {Object}
* `socket` {Duplex}
* `onResponseStart` {Function} (optional) Invoked when the status code and
headers have been received. May be invoked multiple times for 1xx
informational responses. Not used for `upgrade` requests.
* `controller` {DispatchController}
* `statusCode` {number}
* `headers` {Object}
* `statusMessage` {string} (optional)
* `onResponseData` {Function} (optional) Invoked when response payload data is
received. Not used for `upgrade` requests.
* `controller` {DispatchController}
* `chunk` {Buffer}
* `onResponseEnd` {Function} (optional) Invoked when the response payload and
trailers have been received and the request has completed. Not used for
`upgrade` requests.
* `controller` {DispatchController}
* `trailers` {Object}
* `onResponseError` {Function} (optional) Invoked when an error occurs. Must not
throw.
* `controller` {DispatchController}
* `error` {Error}
* `onResponseStarted` {Function} (optional) Invoked when the response is
received, before headers have been read.
* `onBodySent` {Function} (optional) Invoked when a chunk of the request body is
sent. May be invoked multiple times for chunked requests.
* `chunk` {Buffer}
* `onRequestSent` {Function} (optional) Invoked after the request body is fully
sent.
* Returns: {boolean} `false` when the dispatcher is busy and further `dispatch()`
calls will make no progress until the [`'drain'`][] event is emitted.
This is the low-level API on which all the higher-level methods are built. This
API is expected to evolve through semver-major versions and is less stable than
the higher-level methods. It is primarily intended for library developers who
implement higher-level APIs on top of it.
The `controller` passed to each handler is a `DispatchController` with the
following shape:
* `aborted` {boolean} Whether the request has been aborted.
* `paused` {boolean} Whether the request is paused.
* `reason` {Error|null} The reason the request was aborted, if any.
* `rawHeaders` {Buffer[]|string[]|Object|null} The raw response headers,
preserving duplicates and casing.
* `rawTrailers` {Buffer[]|string[]|Object|null} The raw response trailers.
* `abort(reason)` Aborts the request with the given `reason`.
* `pause()` Pauses the response stream.
* `resume()` Resumes the response stream.
Call `controller.pause()` and `controller.resume()` to apply backpressure rather
than returning `false` from a handler.
```mjs
import { createServer } from 'node:http'
import { Client } from 'undici'
import { once } from 'node:events'
const server = createServer((request, response) => {
response.end('Hello, World!')
}).listen()
await once(server, 'listening')
const client = new Client(`http://localhost:${server.address().port}`)
const data = []
client.dispatch({
path: '/',
method: 'GET',
headers: { 'x-foo': 'bar' }
}, {
onRequestStart: () => {
console.log('Connected!')
},
onResponseError: (_controller, error) => {
console.error(error)
},
onResponseStart: (_controller, statusCode, headers) => {
console.log(`statusCode: ${statusCode} | headers: ${JSON.stringify(headers)}`)
},
onResponseData: (_controller, chunk) => {
data.push(chunk)
},
onResponseEnd: (_controller, trailers) => {
console.log(`trailers: ${JSON.stringify(trailers)}`)
console.log(`Data: ${Buffer.concat(data).toString('utf8')}`)
client.close()
server.close()
}
})
```
### `dispatcher.pipeline(options, handler)`
<!-- YAML
added: v4.0.0
-->
* `options` {Object} Accepts every field of [`dispatcher.request()`][]'s
`options`, plus:
* `objectMode` {boolean} Set to `true` when `handler` returns an object stream.
**Default:** `false`.
* `handler` {Function} Returns a `Readable` from which the result is read.
* `data` {Object}
* `statusCode` {number}
* `headers` {Object} The response headers.
* `opaque` {any} The `opaque` value passed in `options`.
* `body` {Readable} The response body.
* `context` {Object}
* Returns: {Readable}
* Returns: {Duplex} A duplex stream that writes to the request and reads from the
response.
For easy use with [`stream.pipeline()`][]. The `handler` should return a
`Readable` from which the result is read. Usually it returns the `body` directly,
unless a transformation is needed based on, for example, `headers` or
`statusCode`. The `handler` should validate the response and save any required
state; if there is an error, it should be thrown.
```mjs
import { Readable, Writable, PassThrough, pipeline } from 'node:stream'
import { createServer } from 'node:http'
import { Client } from 'undici'
import { once } from 'node:events'
const server = createServer((request, response) => {
request.pipe(response)
}).listen()
await once(server, 'listening')
const client = new Client(`http://localhost:${server.address().port}`)
let res = ''
pipeline(
new Readable({
read () {
this.push(Buffer.from('undici'))
this.push(null)
}
}),
client.pipeline({ path: '/', method: 'GET' }, ({ statusCode, headers, body }) => {
console.log(`response received ${statusCode}`)
console.log('headers', headers)
return pipeline(body, new PassThrough(), () => {})
}),
new Writable({
write (chunk, _, callback) {
res += chunk.toString()
callback()
},
final (callback) {
console.log(`Response pipelined to writable: ${res}`)
callback()
}
}),
error => {
if (error) {
console.error(error)
}
client.close()
server.close()
}
)
```
### `dispatcher.request(options[, callback])`
<!-- YAML
added: v4.0.0
-->
* `options` {Object} Accepts every field of [`dispatcher.dispatch()`][]'s
`options`, plus:
* `opaque` {any} A value passed through to the returned response data.
**Default:** `null`.
* `signal` {AbortSignal|EventEmitter|null} A signal used to abort the request.
**Default:** `null`.
* `onInfo` {Function|null} Invoked for each informational (1xx) response
received. **Default:** `null`.
* `info` {Object}
* `statusCode` {number}
* `headers` {Object}
* `responseHeaders` {string|null} Set to `'raw'` to return the response headers
as a raw array. **Default:** `null`.
* `highWaterMark` {number} The high water mark of the response body stream.
**Default:** `65536` (64 KiB).
* `callback` {Function} (optional) Invoked when the response is received.
* `error` {Error|null}
* `data` {Object}
* `statusCode` {number}
* `statusText` {string} The status message, e.g. `'OK'` or `'Not Found'`.
* `headers` {Object} The response headers. All keys are lower-cased.
* `body` {Readable} The response body, which also implements the
[body mixin][] from the Fetch Standard.
* `trailers` {Object} Starts out empty and is mutated to contain the trailers
after `body` emits `'end'`.
* `opaque` {any} The `opaque` value passed in `options`.
* `context` {Object}
* Returns: {Promise} A `Promise` is returned only when `callback` is omitted. It
resolves with the `data` object described above.
Performs an HTTP request. `options.method` must not be `'CONNECT'`.
Non-idempotent requests are not pipelined, to avoid indirect failures. Idempotent
requests are automatically retried if they fail due to an indirect failure from
the request at the head of the pipeline; this does not apply to idempotent
requests with a stream request body. All response bodies must always be fully
consumed or destroyed.
The `body` exposes the following [body mixin][] methods and properties:
[`.arrayBuffer()`][], [`.blob()`][], [`.bytes()`][], [`.json()`][],
[`.text()`][], `body`, and `bodyUsed`. A body cannot be consumed twice; for
example, calling `text()` after `json()` throws a `TypeError`. The body also
provides `dump({ limit })`, which discards up to `limit` bytes (default
`131072`) without destroying the socket.
> [!WARNING]
> The `arrayBuffer()`, `blob()`, `bytes()`, `json()`, and `text()` methods buffer
> the entire body in memory before returning. Where applicable, they also decode
> or parse the payload and retain that representation in memory. Calling these
> methods therefore means trusting that the body is small enough to fit in the
> available memory. Do not use them for bodies received from untrusted or
> user-controlled sources. Instead, process `body` as a `Readable` stream and
> enforce an application-specific size limit.
The body is always a `Readable`, even when empty. Deserializing an empty body
with `json()` throws. To guard against this, verify the status code is not `204`
and the `content-type` header starts with `application/json` before calling
`json()`.
```mjs
import { createServer } from 'node:http'
import { Client } from 'undici'
import { once } from 'node:events'
const server = createServer((request, response) => {
response.end('Hello, World!')
}).listen()
await once(server, 'listening')
const client = new Client(`http://localhost:${server.address().port}`)
try {
const { body, headers, statusCode, statusText, trailers } = await client.request({
path: '/',
method: 'GET'
})
console.log(`response received ${statusCode}`)
console.log('headers', headers)
body.setEncoding('utf8')
body.on('data', console.log)
body.on('error', console.error)
body.on('end', () => {
console.log('trailers', trailers)
})
client.close()
server.close()
} catch (error) {
console.error(error)
}
```
A request can be aborted with an `AbortSignal`, with any `EventEmitter` that
emits an `'abort'` event, or by destroying the response body:
```mjs
import { Client } from 'undici'
const client = new Client('http://localhost:3000')
const abortController = new AbortController()
try {
client.request({ path: '/', method: 'GET', signal: abortController.signal })
} catch (error) {
console.error(error) // RequestAbortedError
}
abortController.abort()
```
When the response body is conditionally read, always fully consume it otherwise:
```mjs
const { body, statusCode } = await client.request({ path: '/', method: 'GET' })
if (statusCode === 200) {
return await body.arrayBuffer()
}
await body.dump()
return null
```
### `dispatcher.stream(options, factory[, callback])`
<!-- YAML
added: v4.0.0
-->
* `options` {Object} Accepts the same fields as [`dispatcher.request()`][]'s
`options`.
* `factory` {Function} Returns the `Writable` to which the response is written.
* `data` {Object}
* `statusCode` {number}
* `headers` {Object} The response headers.
* `opaque` {any} The `opaque` value passed in `options`.
* `context` {Object}
* Returns: {Writable}
* `callback` {Function} (optional) Invoked when the request has completed.
* `error` {Error|null}
* `data` {Object}
* `opaque` {any} The `opaque` value passed in `options`.
* `trailers` {Object}
* Returns: {Promise} A `Promise` is returned only when `callback` is omitted. It
resolves with the `data` object described above.
A faster version of [`dispatcher.request()`][]. The `factory` returns a
[`Writable`][] to which the response is written, which avoids creating an
intermediate [`Readable`][] when the caller intends to pipe the response body
directly to a `Writable`.
Use `options.opaque` to avoid creating a closure for the `factory` method. This
pattern works well with Node.js web frameworks such as [Fastify][].
```mjs
import { createServer } from 'node:http'
import { Client } from 'undici'
import { once } from 'node:events'
import { Writable } from 'node:stream'
const server = createServer((request, response) => {
response.end('Hello, World!')
}).listen()
await once(server, 'listening')
const client = new Client(`http://localhost:${server.address().port}`)
const bufs = []
try {
await client.stream({
path: '/',
method: 'GET',
opaque: { bufs }
}, ({ statusCode, headers, opaque: { bufs } }) => {
console.log(`response received ${statusCode}`)
console.log('headers', headers)
return new Writable({
write (chunk, encoding, callback) {
bufs.push(chunk)
callback()
}
})
})
console.log(Buffer.concat(bufs).toString('utf-8'))
client.close()
server.close()
} catch (error) {
console.error(error)
}
```
### `dispatcher.upgrade(options[, callback])`
<!-- YAML
added: v4.0.0
-->
* `options` {Object}
* `path` {string} The request path.
* `method` {string} The HTTP method. **Default:** `'GET'`.
* `headers` {UndiciHeaders} Request headers. **Default:** `null`.
* `protocol` {string} A comma-separated list of protocols, in descending
preference order. **Default:** `'Websocket'`.
* `signal` {AbortSignal|EventEmitter|null} A signal used to abort the request.
**Default:** `null`.
* `responseHeaders` {string|null} Set to `'raw'` to return the response headers
as a raw array. **Default:** `null`.
* `callback` {Function} (optional) Invoked when the upgrade completes.
* `error` {Error|null}
* `data` {Object}
* `headers` {Object} The response headers.
* `socket` {Duplex} The upgraded socket.
* `opaque` {any}
* Returns: {Promise} A `Promise` is returned only when `callback` is omitted. It
resolves with the `data` object described above.
Upgrades to a different protocol. See
[MDN: Protocol upgrade mechanism][] for more details.
```mjs
import { createServer } from 'node:http'
import { Client } from 'undici'
import { once } from 'node:events'
const server = createServer((request, response) => {
response.statusCode = 101
response.setHeader('connection', 'upgrade')
response.setHeader('upgrade', request.headers.upgrade)
response.end()
}).listen()
await once(server, 'listening')
const client = new Client(`http://localhost:${server.address().port}`)
try {
const { headers, socket } = await client.upgrade({ path: '/' })
socket.on('end', () => {
console.log(`upgrade: ${headers.upgrade}`) // upgrade: Websocket
client.close()
server.close()
})
socket.end()
} catch (error) {
console.error(error)
client.close()
server.close()
}
```
### `dispatcher.compose(interceptors[, interceptor])`
<!-- YAML
added: v6.9.0
-->
* `interceptors` {Array|Function} An array of interceptor functions, or the first
of several interceptors passed as separate arguments.
* `...interceptor` {Function} Additional interceptors when passed as separate
arguments.
* Returns: {Dispatcher} A new dispatcher that applies the interceptors over the
current dispatcher's [`dispatch()`][] method.
Composes a new dispatcher from the current dispatcher and the given
interceptors. Each interceptor is a function that takes a `dispatch` method and
returns a `dispatch`-like function with the same signature
(`(options, handler)`).
The order of the interceptors matters: the last interceptor in the chain is the
first to be called. Forking the chain of interceptors can lead to unexpected
results.
```text
compose([interceptor1, interceptor2, interceptor3])
Request flow:
Request -> interceptor3 -> interceptor2 -> interceptor1 -> dispatcher.dispatch
(called first) (called second) (called last)
```
```mjs
import { Client, RedirectHandler } from 'undici'
const redirectInterceptor = dispatch => {
return (opts, handler) => {
const { maxRedirections } = opts
if (!maxRedirections) {
return dispatch(opts, handler)
}
const redirectHandler = new RedirectHandler(dispatch, maxRedirections, opts, handler)
opts = { ...opts, maxRedirections: 0 } // Stop the sub-dispatcher from also redirecting.
return dispatch(opts, redirectHandler)
}
}
const client = new Client('http://localhost:3000').compose(redirectInterceptor)
await client.request({ path: '/', method: 'GET' })
```
Interceptors can be chained by calling `compose()` repeatedly:
```mjs
import { Client } from 'undici'
const client = new Client('http://localhost:3000')
.compose(redirectInterceptor)
.compose(retryInterceptor)
await client.request({ path: '/', method: 'GET' })
```
For the full list of built-in interceptors provided by undici, see [Interceptors](Interceptors.md).
For an example of a custom interceptor that wraps handler callbacks, see
[Custom interceptors](Interceptors.md#custom-interceptors).
### Event: `'connect'`
<!-- YAML
added: v4.0.0
-->
* `origin` {URL}
* `targets` {Array<Dispatcher>}
Emitted when the dispatcher has connected to the origin.
### Event: `'disconnect'`
<!-- YAML
added: v4.0.0
-->
* `origin` {URL}
* `targets` {Array<Dispatcher>}
* `error` {Error}
Emitted when the dispatcher has been disconnected from the origin.
For HTTP/2, this event is also emitted when the dispatcher receives a
[GOAWAY frame][], with an error whose message is `HTTP/2: "GOAWAY" frame received`
and whose code is `UND_ERR_INFO`. Because of the binary-framing nature of the
protocol, a request may hang if a frame is received between the `HEADER` and
`DATA` frames. It is recommended to handle this event and close the dispatcher to
create a new HTTP/2 session.
### Event: `'connectionError'`
<!-- YAML
added: v4.0.0
-->
* `origin` {URL}
* `targets` {Array<Dispatcher>}
* `error` {Error}
Emitted when the dispatcher fails to connect to the origin.
### Event: `'drain'`
<!-- YAML
added: v4.0.0
-->
* `origin` {URL}
Emitted when the dispatcher is no longer busy and further [`dispatch()`][] calls
can make progress.
## Pre-built interceptors
For the full reference of built-in interceptors (`dump`, `retry`, `redirect`,
`decompress`, `responseError`, `dns`, `cache`, `deduplicate`) and their options,
see [Interceptors](Interceptors.md).
[Fastify]: https://fastify.dev
[GOAWAY frame]: https://webconcepts.info/concepts/http2-frame-type/0x7
[HTTP `CONNECT`]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/CONNECT
[MDN: Protocol upgrade mechanism]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Protocol_upgrade_mechanism
[`.arrayBuffer()`]: https://fetch.spec.whatwg.org/#dom-body-arraybuffer
[`.blob()`]: https://fetch.spec.whatwg.org/#dom-body-blob
[`.bytes()`]: https://fetch.spec.whatwg.org/#dom-body-bytes
[`.json()`]: https://fetch.spec.whatwg.org/#dom-body-json
[`.text()`]: https://fetch.spec.whatwg.org/#dom-body-text
[`'drain'`]: #event-drain
[`Agent`]: Agent.md#class-agent
[`BalancedPool`]: BalancedPool.md#class-balancedpool
[`Client`]: Client.md#class-client
[`EventEmitter`]: https://nodejs.org/api/events.html#class-eventemitter
[`Pool`]: Pool.md#class-pool
[`Readable`]: https://nodejs.org/api/stream.html#class-streamreadable
[`Writable`]: https://nodejs.org/api/stream.html#class-streamwritable
[`close()`]: #dispatcherclosecallback
[`connect()`]: #dispatcherconnectoptions-callback
[`destroy()`]: #dispatcherdestroyerror-callback
[`dispatch()`]: #dispatcherdispatchoptions-handler
[`dispatcher.compose()`]: #dispatchercomposeinterceptors-interceptor
[`dispatcher.dispatch()`]: #dispatcherdispatchoptions-handler
[`dispatcher.request()`]: #dispatcherrequestoptions-callback
[`pipeline()`]: #dispatcherpipelineoptions-handler
[`request()`]: #dispatcherrequestoptions-callback
[`stream()`]: #dispatcherstreamoptions-factory-callback
[`stream.pipeline()`]: https://nodejs.org/api/stream.html#streampipelinesource-transforms-destination-options
[`upgrade()`]: #dispatcherupgradeoptions-callback
[body mixin]: https://fetch.spec.whatwg.org/#body-mixin
node_modules/undici/docs/docs/api/EnvHttpProxyAgent.md
Generated Vendored
+171
View File
@@ -0,0 +1,171 @@
# EnvHttpProxyAgent
<!--introduced_in=v6.14.0-->
<!--type=module-->
<!-- source_link=lib/dispatcher/env-http-proxy-agent.js -->
> Stability: 2 - Stable
`EnvHttpProxyAgent` is a [`Dispatcher`][] that reads its proxy configuration from
the `http_proxy`, `https_proxy`, and `no_proxy` environment variables and routes
requests through the appropriate proxy automatically. Import it from `undici`:
```mjs
import { EnvHttpProxyAgent } from 'undici'
```
When `http_proxy` and `https_proxy` are both set, `http_proxy` is used for HTTP
requests and `https_proxy` is used for HTTPS requests. If only `http_proxy` is
set, it is used for both HTTP and HTTPS requests. If only `https_proxy` is set,
it is used only for HTTPS requests.
`no_proxy` is a comma- or space-separated list of hosts that must not be
proxied. Each entry may include a leading dot or `*.` wildcard (for example
`.example.com`) to match subdomains, and an optional `:port` suffix to restrict
the match to a specific port. A request bypasses the proxy when its host equals
an entry or is a subdomain of one. A trailing dot is ignored on both sides, so
`example.com.` and `example.com` match each other. Setting `no_proxy` to `*`
bypasses the proxy for every request.
The uppercase variants `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` are also
honored. When both the lowercase and uppercase forms of a variable are set, the
lowercase form takes precedence and the uppercase form is ignored. The `no_proxy`
value is re-read from the environment on demand, so changes to it after the agent
is created take effect on subsequent requests; this does not apply when `noProxy`
is passed as an option.
## Class: `EnvHttpProxyAgent`
<!-- YAML
added: v6.14.0
-->
* Extends: {Dispatcher}
### `new EnvHttpProxyAgent([options])`
<!-- YAML
added: v6.14.0
-->
* `options` {EnvHttpProxyAgentOptions} Extends the [`ProxyAgent`][] options
(except `uri`). (optional)
* `httpProxy` {string} When set, overrides the `http_proxy` and `HTTP_PROXY`
environment variables. (optional)
* `httpsProxy` {string} When set, overrides the `https_proxy` and
`HTTPS_PROXY` environment variables. (optional)
* `noProxy` {string} When set, overrides the `no_proxy` and `NO_PROXY`
environment variables. (optional)
* Returns: {EnvHttpProxyAgent}
Creates a new `EnvHttpProxyAgent`. Any options other than `httpProxy`,
`httpsProxy`, and `noProxy` are forwarded to the underlying [`Agent`][] and
[`ProxyAgent`][] instances. Constructing the agent only configures it; it does
not affect any request until it is registered as a dispatcher, either globally
with `setGlobalDispatcher()` or per-request through the `dispatcher` option.
```mjs
import { EnvHttpProxyAgent } from 'undici'
const envHttpProxyAgent = new EnvHttpProxyAgent()
// or, overriding the environment variables explicitly:
const envHttpProxyAgentWithOpts = new EnvHttpProxyAgent({
httpProxy: 'my.proxy.server:8080',
httpsProxy: 'my.proxy.server:8443',
noProxy: 'localhost'
})
```
#### Example - Proxied `fetch()` with the global dispatcher
```mjs
import { setGlobalDispatcher, fetch, EnvHttpProxyAgent } from 'undici'
const envHttpProxyAgent = new EnvHttpProxyAgent()
setGlobalDispatcher(envHttpProxyAgent)
const response = await fetch('http://localhost:3000/foo')
console.log('response received', response.status) // response received 200
const data = await response.json() // data { foo: 'bar' }
```
#### Example - Proxied `request()` with the global dispatcher
```mjs
import { setGlobalDispatcher, request, EnvHttpProxyAgent } from 'undici'
const envHttpProxyAgent = new EnvHttpProxyAgent()
setGlobalDispatcher(envHttpProxyAgent)
const { statusCode, body } = await request('http://localhost:3000/foo')
console.log('response received', statusCode) // response received 200
for await (const data of body) {
console.log('data', data.toString('utf8')) // data foo
}
```
#### Example - Proxied `request()` with a local dispatcher
```mjs
import { EnvHttpProxyAgent, request } from 'undici'
const envHttpProxyAgent = new EnvHttpProxyAgent()
const { statusCode, body } = await request('http://localhost:3000/foo', {
dispatcher: envHttpProxyAgent
})
console.log('response received', statusCode) // response received 200
for await (const data of body) {
console.log('data', data.toString('utf8')) // data foo
}
```
#### Example - Proxied `fetch()` with a local dispatcher
```mjs
import { EnvHttpProxyAgent, fetch } from 'undici'
const envHttpProxyAgent = new EnvHttpProxyAgent()
const response = await fetch('http://localhost:3000/foo', {
dispatcher: envHttpProxyAgent
})
console.log('response received', response.status) // response received 200
const data = await response.json() // data { foo: 'bar' }
```
### `envHttpProxyAgent.dispatch(options, handler)`
<!-- YAML
added: v6.14.0
-->
* `options` {AgentDispatchOptions}
* `origin` {string|URL}
* `handler` {DispatchHandler}
* Returns: {boolean}
Dispatches a request through the proxy selected for `options.origin`. The origin's
protocol, host, and port are compared against the `no_proxy` configuration: when
the host should be proxied, the request is routed to the HTTPS proxy agent for
`https:` origins or the HTTP proxy agent otherwise; when the host is excluded by
`no_proxy`, the request is sent directly through a non-proxying [`Agent`][].
This method is not normally called directly. Use the higher-level
[`Dispatcher`][] methods such as [`dispatcher.request()`][] or the top-level
`request()` and `fetch()` helpers instead.
[`Agent`]: Agent.md#class-agent
[`Dispatcher`]: Dispatcher.md#class-dispatcher
[`ProxyAgent`]: ProxyAgent.md#class-proxyagent
[`dispatcher.request()`]: Dispatcher.md#dispatcherrequestoptions-callback
node_modules/undici/docs/docs/api/Errors.md
Generated Vendored
+549
View File
@@ -0,0 +1,549 @@
# Errors
<!--introduced_in=v1.0.0-->
<!--type=module-->
<!-- source_link=lib/core/errors.js -->
> Stability: 2 - Stable
undici raises typed error objects so that failures can be distinguished
programmatically. Every error class is exposed through the `errors` namespace of
the package:
```js
import { errors } from 'undici'
if (err instanceof errors.ConnectTimeoutError) {
// handle connect timeout
}
```
All errors, except [`HTTPParserError`][], extend [`UndiciError`][]. Each error
carries a stable `code` string (for example `UND_ERR_CONNECT_TIMEOUT`) and a
`name`.
Because the bundled (global) dispatcher may come from a different undici version
than the one you import directly, prefer matching on `error.code` rather than
`instanceof errors.UndiciError`:
```js
if (err.code === 'UND_ERR_CONNECT_TIMEOUT') {
// handle connect timeout
}
```
## Class: `UndiciError`
<!-- YAML
added: v1.0.0
changes:
- version: v7.16.0
pr-url: https://github.com/nodejs/undici/pull/4472
description: Made `UndiciError` and its subclasses reliable with `instanceof`
across realms and undici versions.
-->
* Extends: {Error}
The base class for all undici errors. It is reliable with `instanceof` even when
the error originates from a different undici version, because the check is based
on a well-known symbol rather than the prototype chain.
* `name` {string} Always `'UndiciError'`.
* `code` {string} Always `'UND_ERR'`.
## Class: `ConnectTimeoutError`
<!-- YAML
added: v1.0.0
changes:
- version: v7.16.0
pr-url: https://github.com/nodejs/undici/pull/4472
description: Made the error reliable with `instanceof`.
-->
* Extends: {UndiciError}
The socket was destroyed because establishing the connection exceeded the
`connectTimeout` option.
* `name` {string} Always `'ConnectTimeoutError'`.
* `code` {string} Always `'UND_ERR_CONNECT_TIMEOUT'`.
When `autoSelectFamily` is enabled and every attempted address times out, Node.js
raises an `AggregateError`. undici normalizes these multi-address timeouts into a
`ConnectTimeoutError` so that the error shape is the same regardless of whether
Node.js's per-address timer or undici's `connectTimeout` wins the race. The
original `AggregateError` is preserved on `error.cause`.
## Class: `HeadersTimeoutError`
<!-- YAML
added: v1.0.0
changes:
- version: v7.16.0
pr-url: https://github.com/nodejs/undici/pull/4472
description: Made the error reliable with `instanceof`.
-->
* Extends: {UndiciError}
The socket was destroyed because receiving the response headers exceeded the
`headersTimeout` option.
* `name` {string} Always `'HeadersTimeoutError'`.
* `code` {string} Always `'UND_ERR_HEADERS_TIMEOUT'`.
## Class: `HeadersOverflowError`
<!-- YAML
added: v1.0.0
changes:
- version: v7.16.0
pr-url: https://github.com/nodejs/undici/pull/4472
description: Made the error reliable with `instanceof`.
-->
* Extends: {UndiciError}
The socket was destroyed because the response headers exceeded the maximum
allowed size.
* `name` {string} Always `'HeadersOverflowError'`.
* `code` {string} Always `'UND_ERR_HEADERS_OVERFLOW'`.
## Class: `BodyTimeoutError`
<!-- YAML
added: v1.0.0
changes:
- version: v7.16.0
pr-url: https://github.com/nodejs/undici/pull/4472
description: Made the error reliable with `instanceof`.
-->
* Extends: {UndiciError}
The socket was destroyed because reading the response body exceeded the
`bodyTimeout` option.
* `name` {string} Always `'BodyTimeoutError'`.
* `code` {string} Always `'UND_ERR_BODY_TIMEOUT'`.
## Class: `InvalidArgumentError`
<!-- YAML
added: v1.0.0
changes:
- version: v7.16.0
pr-url: https://github.com/nodejs/undici/pull/4472
description: Made the error reliable with `instanceof`.
-->
* Extends: {UndiciError}
An invalid argument was passed to an undici API.
* `name` {string} Always `'InvalidArgumentError'`.
* `code` {string} Always `'UND_ERR_INVALID_ARG'`.
## Class: `InvalidReturnValueError`
<!-- YAML
added: v1.0.0
changes:
- version: v7.16.0
pr-url: https://github.com/nodejs/undici/pull/4472
description: Made the error reliable with `instanceof`.
-->
* Extends: {UndiciError}
A user-supplied callback or interceptor returned an invalid value.
* `name` {string} Always `'InvalidReturnValueError'`.
* `code` {string} Always `'UND_ERR_INVALID_RETURN_VALUE'`.
## Class: `AbortError`
<!-- YAML
added: v1.0.0
changes:
- version: v7.16.0
pr-url: https://github.com/nodejs/undici/pull/4472
description: Made the error reliable with `instanceof`.
-->
* Extends: {UndiciError}
The operation was aborted. This is the base class of [`RequestAbortedError`][].
* `name` {string} Always `'AbortError'`.
* `code` {string} Always `'UND_ERR_ABORT'`.
## Class: `RequestAbortedError`
<!-- YAML
added: v1.0.0
changes:
- version: v7.16.0
pr-url: https://github.com/nodejs/undici/pull/4472
description: Made the error reliable with `instanceof`.
-->
* Extends: {AbortError}
The request was aborted by the user, typically through an `AbortSignal`.
* `name` {string} Always `'AbortError'`.
* `code` {string} Always `'UND_ERR_ABORTED'`.
## Class: `InformationalError`
<!-- YAML
added: v1.0.0
changes:
- version: v7.16.0
pr-url: https://github.com/nodejs/undici/pull/4472
description: Made the error reliable with `instanceof`.
-->
* Extends: {UndiciError}
An expected error carrying a reason, used internally to surface a cause for a
failed or retried request (for example as the `cause` of another error).
* `name` {string} Always `'InformationalError'`.
* `code` {string} Always `'UND_ERR_INFO'`.
## Class: `RequestContentLengthMismatchError`
<!-- YAML
added: v1.0.0
changes:
- version: v7.16.0
pr-url: https://github.com/nodejs/undici/pull/4472
description: Made the error reliable with `instanceof`.
-->
* Extends: {UndiciError}
The length of the request body did not match the `content-length` header.
* `name` {string} Always `'RequestContentLengthMismatchError'`.
* `code` {string} Always `'UND_ERR_REQ_CONTENT_LENGTH_MISMATCH'`.
## Class: `ResponseContentLengthMismatchError`
<!-- YAML
added: v1.0.0
changes:
- version: v7.16.0
pr-url: https://github.com/nodejs/undici/pull/4472
description: Made the error reliable with `instanceof`.
-->
* Extends: {UndiciError}
The length of the response body did not match the `content-length` header.
* `name` {string} Always `'ResponseContentLengthMismatchError'`.
* `code` {string} Always `'UND_ERR_RES_CONTENT_LENGTH_MISMATCH'`.
## Class: `ClientDestroyedError`
<!-- YAML
added: v1.0.0
changes:
- version: v7.16.0
pr-url: https://github.com/nodejs/undici/pull/4472
description: Made the error reliable with `instanceof`.
-->
* Extends: {UndiciError}
An operation was attempted on a client that has already been destroyed.
* `name` {string} Always `'ClientDestroyedError'`.
* `code` {string} Always `'UND_ERR_DESTROYED'`.
## Class: `ClientClosedError`
<!-- YAML
added: v1.0.0
changes:
- version: v7.16.0
pr-url: https://github.com/nodejs/undici/pull/4472
description: Made the error reliable with `instanceof`.
-->
* Extends: {UndiciError}
An operation was attempted on a client that has already been closed.
* `name` {string} Always `'ClientClosedError'`.
* `code` {string} Always `'UND_ERR_CLOSED'`.
## Class: `SocketError`
<!-- YAML
added: v1.0.0
changes:
- version: v7.16.0
pr-url: https://github.com/nodejs/undici/pull/4472
description: Made the error reliable with `instanceof`.
-->
* Extends: {UndiciError}
An error occurred on the underlying socket.
* `name` {string} Always `'SocketError'`.
* `code` {string} Always `'UND_ERR_SOCKET'`.
* `socket` {SocketInfo|null} Metadata about the socket at the time of the error,
or `null` when no socket information is available.
The `socket` property, when present, holds the following fields:
```ts
interface SocketInfo {
localAddress?: string
localPort?: number
remoteAddress?: string
remotePort?: number
remoteFamily?: string
timeout?: number
bytesWritten?: number
bytesRead?: number
}
```
## Class: `NotSupportedError`
<!-- YAML
added: v1.0.0
changes:
- version: v7.16.0
pr-url: https://github.com/nodejs/undici/pull/4472
description: Made the error reliable with `instanceof`.
-->
* Extends: {UndiciError}
Unsupported functionality was requested.
* `name` {string} Always `'NotSupportedError'`.
* `code` {string} Always `'UND_ERR_NOT_SUPPORTED'`.
## Class: `BalancedPoolMissingUpstreamError`
<!-- YAML
added: v1.0.0
changes:
- version: v7.16.0
pr-url: https://github.com/nodejs/undici/pull/4472
description: Made the error reliable with `instanceof`.
-->
* Extends: {UndiciError}
No upstream has been added to the [`BalancedPool`][].
* `name` {string} Always `'MissingUpstreamError'`.
* `code` {string} Always `'UND_ERR_BPL_MISSING_UPSTREAM'`.
## Class: `HTTPParserError`
<!-- YAML
added: v4.0.0
-->
* Extends: {Error}
An error occurred while parsing the HTTP response. Unlike the other error
classes, `HTTPParserError` extends {Error} directly rather than
[`UndiciError`][].
* `name` {string} Always `'HTTPParserError'`.
* `code` {string} An `HPE_`-prefixed parser error code, or `undefined` when no
code was provided.
* `data` {string} The raw data associated with the parser failure, or
`undefined` when none was provided.
## Class: `ResponseExceededMaxSizeError`
<!-- YAML
added: v1.0.0
changes:
- version: v7.16.0
pr-url: https://github.com/nodejs/undici/pull/4472
description: Made the error reliable with `instanceof`.
-->
* Extends: {UndiciError}
The response body exceeded the maximum allowed size.
* `name` {string} Always `'ResponseExceededMaxSizeError'`.
* `code` {string} Always `'UND_ERR_RES_EXCEEDED_MAX_SIZE'`.
## Class: `RequestRetryError`
<!-- YAML
added: v1.0.0
changes:
- version: v7.16.0
pr-url: https://github.com/nodejs/undici/pull/4472
description: Made the error reliable with `instanceof`.
-->
* Extends: {UndiciError}
A request failed and could not be retried, for example because the body is
stateful (a stream or `AsyncIterable`) and cannot be replayed.
* `name` {string} Always `'RequestRetryError'`.
* `code` {string} Always `'UND_ERR_REQ_RETRY'`.
* `statusCode` {number} The HTTP status code of the failed response.
* `data` {Object} Retry metadata.
* `count` {number} The number of retry attempts that were made.
* `headers` {Record<string, string|string[]>} The response headers.
### `new RequestRetryError(message, code, options)`
* `message` {string} The error message.
* `code` {number} The HTTP status code of the failed response.
* `options` {Object}
* `headers` {Object|string[]|null} The response headers. (optional)
* `data` {Object|string|null} Retry metadata. (optional)
## Class: `ResponseError`
<!-- YAML
added: v1.0.0
changes:
- version: v7.16.0
pr-url: https://github.com/nodejs/undici/pull/4472
description: Made the error reliable with `instanceof`.
-->
* Extends: {UndiciError}
The response returned an error status code. This is raised, for example, when the
`throwOnError` option is enabled.
* `name` {string} Always `'ResponseError'`.
* `code` {string} Always `'UND_ERR_RESPONSE'`.
* `statusCode` {number} The HTTP status code of the response.
* `body` {Object|string|null} The response body.
* `headers` {Object|string[]|null} The response headers.
### `new ResponseError(message, code, options)`
* `message` {string} The error message.
* `code` {number} The HTTP status code of the response.
* `options` {Object}
* `headers` {Object|string[]|null} The response headers. (optional)
* `body` {Object|string|null} The response body. (optional)
## Class: `ProxyConnectionError`
<!-- YAML
added: v8.10.1
changes:
- version: v8.10.1
pr-url: https://github.com/nodejs/undici/pull/5707
description: Added to fail the request instead of retrying forever when the proxy connection is torn down.
-->
* Extends: {UndiciError}
A connection to the proxy failed in a way that cannot be recovered on the
same connection, so the request fails instead of being retried.
* `name` {string} Always `'ProxyConnectionError'`.
* `code` {string} Always `'UND_ERR_PRX_CONN'`.
* `cause` {Error} The underlying error that caused the proxy connection to fail.
### `new ProxyConnectionError(cause[, message[, options]])`
* `cause` {Error} The underlying error. (optional)
* `message` {string} The error message. (optional)
* `options` {Object} Additional `Error` options merged with `cause`. (optional)
## Class: `SecureProxyConnectionError`
<!-- YAML
added: v1.0.0
changes:
- version: v7.16.0
pr-url: https://github.com/nodejs/undici/pull/4472
description: Made the error reliable with `instanceof`.
-->
* Extends: {UndiciError}
A TLS connection to a proxy failed.
* `name` {string} Always `'SecureProxyConnectionError'`.
* `code` {string} Always `'UND_ERR_PRX_TLS'`.
* `cause` {Error} The underlying error that caused the proxy connection to fail.
### `new SecureProxyConnectionError(cause[, message[, options]])`
* `cause` {Error} The underlying error. (optional)
* `message` {string} The error message. (optional)
* `options` {Object} Additional `Error` options merged with `cause`. (optional)
## Class: `MaxOriginsReachedError`
<!-- YAML
added: v1.0.0
changes:
- version: v7.16.0
pr-url: https://github.com/nodejs/undici/pull/4365
description: Added to support capping the number of origins in `Agent`.
-->
* Extends: {UndiciError}
The maximum number of allowed origins has been reached.
* `name` {string} Always `'MaxOriginsReachedError'`.
* `code` {string} Always `'UND_ERR_MAX_ORIGINS_REACHED'`.
## Class: `Socks5ProxyError`
<!-- YAML
added: v7.23.0
-->
* Extends: {UndiciError}
An error occurred during SOCKS5 proxy negotiation.
* `name` {string} Always `'Socks5ProxyError'`.
* `code` {string} The error code. **Default:** `'UND_ERR_SOCKS5'`.
### `new Socks5ProxyError([message[, code]])`
* `message` {string} The error message. (optional)
* `code` {string} The error code. **Default:** `'UND_ERR_SOCKS5'`. (optional)
## Class: `MessageSizeExceededError`
<!-- YAML
added: v1.0.0
-->
* Extends: {UndiciError}
A decompressed WebSocket message exceeded the maximum allowed size.
* `name` {string} Always `'MessageSizeExceededError'`.
* `code` {string} Always `'UND_ERR_WS_MESSAGE_SIZE_EXCEEDED'`.
[`BalancedPool`]: BalancedPool.md#class-balancedpool
[`HTTPParserError`]: #class-httpparsererror
[`RequestAbortedError`]: #class-requestabortederror
[`UndiciError`]: #class-undicierror
node_modules/undici/docs/docs/api/EventSource.md
Generated Vendored
+358
View File
@@ -0,0 +1,358 @@
# EventSource
<!--introduced_in=v6.5.0-->
<!--type=module-->
<!-- source_link=lib/web/eventsource/eventsource.js -->
> Stability: 1 - Experimental
`EventSource` is a [WHATWG-conformant][] implementation of the
[server-sent events][] interface. It opens a persistent HTTP connection to a
server that responds with the `text/event-stream` content type and dispatches
the events it receives without closing the connection.
```mjs
import { EventSource } from 'undici'
const eventSource = new EventSource('http://localhost:3000')
eventSource.onmessage = (event) => {
console.log(event.data)
}
```
Constructing an `EventSource` for the first time emits a one-time
`ExperimentalWarning` with the code `'UNDICI-ES'`. The interface is also
installed onto `globalThis` as `globalThis.EventSource`.
## Class: `EventSource`
<!-- YAML
added: v6.5.0
-->
> Stability: 1 - Experimental
* Extends: {EventTarget}
The `EventSource` interface receives server-sent events over an HTTP
connection. Instances are created with the [`new EventSource()`](#new-eventsourceurl-eventsourceinitdict)
constructor and emit [`'open'`](#event-open), [`'message'`](#event-message), and
[`'error'`](#event-error) events.
### `new EventSource(url[, eventSourceInitDict])`
<!-- YAML
added: v6.5.0
-->
> Stability: 1 - Experimental
* `url` {string|URL} The URL of the event stream. Relative URLs are resolved
against the environment's base URL.
* `eventSourceInitDict` {Object} (optional)
* `withCredentials` {boolean} When `true`, the request is made with the
credentials mode set to `include` and CORS attribute state set to
`use-credentials`; otherwise the credentials mode is `same-origin`.
**Default:** `false`.
* `dispatcher` {Dispatcher} The dispatcher used for the underlying request.
**Default:** the global dispatcher.
> Stability: 0 - Deprecated. Use `node.dispatcher` instead.
* `node` {Object} undici-specific extensions to the standard
`EventSourceInit` dictionary.
* `dispatcher` {Dispatcher} The dispatcher used for the underlying request.
**Default:** the global dispatcher.
* `reconnectionTime` {number} The reconnection time, in milliseconds, to
wait before re-establishing a dropped connection. The server may override
this value with a `retry` field. **Default:** `3000`.
EventSource-specific limits can be configured on the dispatcher using the
`eventSource` option. See [`Client`][] for details.
Creates a new `EventSource` and immediately begins connecting to `url`. The
request is sent with the `Accept: text/event-stream` header, a cache mode of
`no-store`, and an initiator type of `other`.
If `url` cannot be parsed, a `SyntaxError` `DOMException` is thrown.
```mjs
import { EventSource } from 'undici'
const eventSource = new EventSource('http://localhost:3000', {
withCredentials: true
})
```
A custom [`Dispatcher`][] can be supplied to control the underlying request, for
example to add request headers:
```mjs
import { EventSource, Agent } from 'undici'
class CustomHeaderAgent extends Agent {
dispatch (opts) {
opts.headers['x-custom-header'] = 'hello world'
return super.dispatch(...arguments)
}
}
const eventSource = new EventSource('http://localhost:3000', {
node: {
dispatcher: new CustomHeaderAgent()
}
})
```
### `eventSource.close()`
<!-- YAML
added: v6.5.0
-->
> Stability: 1 - Experimental
* Returns: {undefined}
Closes the connection, if any, aborts the underlying request, and sets
[`eventSource.readyState`](#eventsourcereadystate) to `CLOSED`. Once closed, the
`EventSource` does not attempt to reconnect. Calling `close()` on an already
closed `EventSource` has no effect.
### `eventSource.readyState`
<!-- YAML
added: v6.5.0
-->
> Stability: 1 - Experimental
* Type: {number}
A read-only number representing the state of the connection. It is one of the
following constants:
* [`EventSource.CONNECTING`](#eventsourceconnecting) (`0`) — the connection has
not yet been established, or it was closed and is being re-established.
* [`EventSource.OPEN`](#eventsourceopen) (`1`) — the connection is open and
events are being dispatched as they are received.
* [`EventSource.CLOSED`](#eventsourceclosed) (`2`) — the connection is not open
and is not being re-established.
### `eventSource.url`
<!-- YAML
added: v6.5.0
-->
> Stability: 1 - Experimental
* Type: {string}
A read-only string providing the URL of the event stream, after resolution
against the environment's base URL.
### `eventSource.withCredentials`
<!-- YAML
added: v6.5.0
-->
> Stability: 1 - Experimental
* Type: {boolean}
A read-only boolean indicating whether the `EventSource` was instantiated with
CORS credentials (`true`), or not (`false`, the default). It reflects the
`withCredentials` option passed to the constructor.
### `eventSource.onopen`
<!-- YAML
added: v6.5.0
-->
> Stability: 1 - Experimental
* Type: {Function|null} **Default:** `null`.
An event handler that is invoked when an [`'open'`](#event-open) event is
dispatched. Assigning a function registers it as the handler; assigning `null`
removes the current handler.
### `eventSource.onmessage`
<!-- YAML
added: v6.5.0
-->
> Stability: 1 - Experimental
* Type: {Function|null} **Default:** `null`.
An event handler that is invoked when a [`'message'`](#event-message) event is
dispatched. Assigning a function registers it as the handler; assigning `null`
removes the current handler.
### `eventSource.onerror`
<!-- YAML
added: v6.5.0
-->
> Stability: 1 - Experimental
* Type: {Function|null} **Default:** `null`.
An event handler that is invoked when an [`'error'`](#event-error) event is
dispatched. Assigning a function registers it as the handler; assigning `null`
removes the current handler.
### `EventSource.CONNECTING`
<!-- YAML
added: v6.5.0
-->
> Stability: 1 - Experimental
* Type: {number}
The numeric constant `0`, representing the `CONNECTING`
[`readyState`](#eventsourcereadystate). It is defined as a read-only,
non-writable property on both the `EventSource` constructor and instances.
### `EventSource.OPEN`
<!-- YAML
added: v6.5.0
-->
> Stability: 1 - Experimental
* Type: {number}
The numeric constant `1`, representing the `OPEN`
[`readyState`](#eventsourcereadystate). It is defined as a read-only,
non-writable property on both the `EventSource` constructor and instances.
### `EventSource.CLOSED`
<!-- YAML
added: v6.5.0
-->
> Stability: 1 - Experimental
* Type: {number}
The numeric constant `2`, representing the `CLOSED`
[`readyState`](#eventsourcereadystate). It is defined as a read-only,
non-writable property on both the `EventSource` constructor and instances.
### Event: `'open'`
<!-- YAML
added: v6.5.0
-->
> Stability: 1 - Experimental
Emitted when the connection is established and the
[`readyState`](#eventsourcereadystate) becomes `OPEN`. The listener receives an
{Event}.
```mjs
import { EventSource } from 'undici'
const eventSource = new EventSource('http://localhost:3000')
eventSource.addEventListener('open', () => {
console.log('connection opened')
})
```
### Event: `'message'`
<!-- YAML
added: v6.15.0
-->
> Stability: 1 - Experimental
Emitted when a message that has no explicit `event` field is received. The
listener receives a {MessageEvent} whose `data`, `lastEventId`, and `origin`
properties are populated from the server-sent event. Named events (those with an
`event` field) are dispatched under their own type and must be subscribed to with
[`addEventListener()`][].
```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')
// Named event, delivered under its own type.
eventSource.addEventListener('ping', (event) => {
console.log('ping:', event.data)
})
// Unnamed event, delivered as 'message'.
eventSource.onmessage = (event) => {
console.log('message:', event.data)
}
})
```
### Event: `'error'`
<!-- YAML
added: v6.5.0
changes:
- version: v7.11.0
pr-url: https://github.com/nodejs/undici/pull/4247
description: The connection is no longer re-established after a network
error; the `EventSource` is closed instead.
-->
> Stability: 1 - Experimental
Emitted when the connection fails or is interrupted. The listener receives an
{Event}. When the failure is recoverable, the `EventSource` transitions back to
`CONNECTING` and retries after the reconnection time; when it is not, the
`EventSource` transitions to `CLOSED` and does not reconnect.
```mjs
import { EventSource } from 'undici'
const eventSource = new EventSource('http://localhost:3000')
eventSource.onerror = () => {
if (eventSource.readyState === EventSource.CLOSED) {
console.log('connection closed')
} else {
console.log('reconnecting')
}
}
```
[WHATWG-conformant]: https://html.spec.whatwg.org/multipage/server-sent-events.html#server-sent-events
[`Client`]: Client.md#new-clienturl-options
[`Dispatcher`]: Dispatcher.md#class-dispatcher
[`addEventListener()`]: https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener
[server-sent events]: https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events
node_modules/undici/docs/docs/api/Fetch.md
Generated Vendored
+721
View File
@@ -0,0 +1,721 @@
# Fetch
<!--introduced_in=v1.0.0-->
<!--type=module-->
<!-- source_link=lib/web/fetch/index.js -->
> Stability: 2 - Stable
undici implements the [WHATWG Fetch Standard][], providing `fetch()` together
with the `Request`, `Response`, `Headers`, and `FormData` classes that mirror
the browser APIs. The implementation follows the standard, so the
[MDN Fetch documentation][] applies as well.
```mjs
import { fetch, Request, Response, Headers, FormData } from 'undici'
const response = await fetch('https://example.com')
const text = await response.text()
```
When mixing these classes, keep them from the same implementation: use the
global `fetch()` with the global `FormData`, `Request`, `Response`, and
`Headers`, and use undici's `fetch()` with undici's classes. Passing a value
created by one implementation to the other can throw.
## `fetch(input[, init])`
<!-- YAML
added: v5.6.0
changes:
- version: v5.6.1
pr-url: https://github.com/nodejs/undici/pull/1529
description: No default value is assigned to `init.method`.
-->
* `input` {string|URL|Request} The resource to fetch. A string or {URL} is
treated as the URL to request; a {Request} is used as the request template.
* `init` {RequestInit} (optional) An options object that customizes the
request.
* `body` {string|Buffer|Uint8Array|Blob|FormData|URLSearchParams|ReadableStream|null}
The request body. **Default:** `null`.
* `cache` {string} The cache mode. One of `'default'`, `'force-cache'`,
`'no-cache'`, `'no-store'`, `'only-if-cached'`, or `'reload'`.
* `credentials` {string} How credentials are sent. One of `'omit'`,
`'include'`, or `'same-origin'`.
* `dispatcher` {Dispatcher} The {Dispatcher} used to perform the request.
**Default:** the global dispatcher.
* `duplex` {string} The duplex mode of the request. Must be `'half'` when a
streaming `body` is provided.
* `headers` {Headers|Object|Array} The request headers, as a {Headers}
instance, a plain object, or an array of `[name, value]` pairs.
* `integrity` {string} The subresource integrity metadata of the request.
* `keepalive` {boolean} Whether the connection may outlive the page.
**Default:** `false`.
* `method` {string} The request method, for example `'GET'` or `'POST'`.
* `mode` {string} The request mode. One of `'cors'`, `'navigate'`,
`'no-cors'`, or `'same-origin'`.
* `redirect` {string} How redirects are handled. One of `'error'`,
`'follow'`, or `'manual'`.
* `referrer` {string} The request referrer.
* `referrerPolicy` {string} The referrer policy. One of `''`,
`'no-referrer'`, `'no-referrer-when-downgrade'`, `'origin'`,
`'origin-when-cross-origin'`, `'same-origin'`, `'strict-origin'`,
`'strict-origin-when-cross-origin'`, or `'unsafe-url'`.
* `signal` {AbortSignal|null} An {AbortSignal} used to abort the request.
**Default:** `null`.
* `window` {null} Can only be `null`; reserved by the standard.
* Returns: {Promise} Fulfills with a {Response} once the response headers have
been received.
Starts the process of fetching a resource from the network and returns a
promise that fulfills with a {Response}. The promise rejects only on network
failures; an HTTP error status such as `404` still fulfills the promise, so
inspect [`response.ok`](#responseok) to detect failures.
```mjs
import { fetch } from 'undici'
const response = await fetch('https://example.com', {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ hello: 'world' }),
})
console.log(response.status)
console.log(await response.json())
```
To route the request through a custom {Dispatcher} (for example a `ProxyAgent`
or `Agent` with specific options), pass it as `init.dispatcher`.
```mjs
import { fetch, Agent } from 'undici'
const response = await fetch('https://example.com', {
dispatcher: new Agent({ connect: { rejectUnauthorized: false } }),
})
```
## Class: `FormData`
<!-- YAML
added: v4.4.4
-->
A set of key/value pairs representing form fields and their values, suitable
for use as a `fetch()` request `body`. The implementation follows the
[WHATWG Fetch Standard][]; see the [MDN `FormData` documentation][].
When using `FormData` as a request body, keep `fetch` and `FormData` from the
same implementation: use the global `FormData` with the global `fetch()`, and
undici's `FormData` with undici's `fetch()`.
### `new FormData()`
<!-- YAML
added: v4.4.4
-->
Creates a new, empty `FormData` instance. Passing any argument other than
`undefined` throws; in particular, an `HTMLFormElement` argument is not
supported in this environment.
### `formData.append(name, value[, filename])`
<!-- YAML
added: v1.0.0
-->
* `name` {string} The name of the field.
* `value` {string|Blob} The value of the field.
* `filename` {string} The filename reported to the server when `value` is a
{Blob}. (optional)
Appends a new value to an existing key, or adds the key if it does not exist.
Unlike [`formData.set()`](#formdatasetname-value-filename), `append()` keeps
any existing values for `name`.
### `formData.delete(name)`
<!-- YAML
added: v1.0.0
-->
* `name` {string} The name of the field to remove.
Deletes all values associated with `name`.
### `formData.get(name)`
<!-- YAML
added: v1.0.0
-->
* `name` {string} The name of the field to read.
* Returns: {string|File|null} The first value associated with `name`, or
`null` if there is none.
### `formData.getAll(name)`
<!-- YAML
added: v1.0.0
-->
* `name` {string} The name of the field to read.
* Returns: {Array} All values associated with `name`, as an array of
{string} and {File} entries.
### `formData.has(name)`
<!-- YAML
added: v1.0.0
-->
* `name` {string} The name of the field to look up.
* Returns: {boolean} `true` if at least one value is associated with `name`.
### `formData.set(name, value[, filename])`
<!-- YAML
added: v1.0.0
-->
* `name` {string} The name of the field.
* `value` {string|Blob} The value of the field.
* `filename` {string} The filename reported to the server when `value` is a
{Blob}. (optional)
Sets a new value for an existing key, or adds the key if it does not exist,
replacing any values previously associated with `name`.
## Class: `Response`
<!-- YAML
added: v4.4.0
-->
* Extends: {BodyMixin}
Represents the response to a request. Instances are typically obtained by
awaiting `fetch()`, but can also be constructed directly. The implementation
follows the [WHATWG Fetch Standard][]; see the
[MDN `Response` documentation][]. `Response` inherits the body-reading methods
described in [Body mixin](#body-mixin).
### `new Response([body[, init]])`
<!-- YAML
added: v4.4.0
-->
* `body` {string|Buffer|Uint8Array|Blob|FormData|URLSearchParams|ReadableStream|null}
The response body. **Default:** `null`.
* `init` {ResponseInit} (optional)
* `status` {number} The response status code. **Default:** `200`.
* `statusText` {string} The response status message. **Default:** `''`.
* `headers` {Headers|Object|Array} The response headers.
Creates a new `Response`.
### Static method: `Response.error()`
<!-- YAML
added: v1.0.0
-->
* Returns: {Response} A network-error response.
Returns a new `Response` representing a network error, with its
[`type`](#responsetype) set to `'error'`.
### Static method: `Response.json(data[, init])`
<!-- YAML
added: v1.0.0
-->
* `data` {any} The value to serialize as JSON.
* `init` {ResponseInit} (optional)
* `status` {number} The response status code. **Default:** `200`.
* `statusText` {string} The response status message. **Default:** `''`.
* `headers` {Headers|Object|Array} The response headers.
* Returns: {Response} A response whose body is the JSON serialization of
`data` and whose `Content-Type` is `application/json`.
```mjs
import { Response } from 'undici'
const response = Response.json({ ok: true }, { status: 201 })
```
### Static method: `Response.redirect(url[, status])`
<!-- YAML
added: v1.0.0
-->
* `url` {string|URL} The URL to redirect to.
* `status` {number} The redirect status code. One of `301`, `302`, `303`,
`307`, or `308`. **Default:** `302`.
* Returns: {Response} A redirect response with the `Location` header set to
`url`.
### `response.clone()`
<!-- YAML
added: v1.0.0
-->
* Returns: {Response} A copy of the response.
Creates a clone of the response. Throws a `TypeError` if the body has already
been read or is locked.
### `response.type`
<!-- YAML
added: v1.0.0
-->
* Type: {string} The response type. One of `'basic'`, `'cors'`, `'default'`,
`'error'`, `'opaque'`, or `'opaqueredirect'`.
### `response.url`
<!-- YAML
added: v1.0.0
-->
* Type: {string} The final URL of the response after any redirects, or the
empty string if not available.
### `response.redirected`
<!-- YAML
added: v1.0.0
-->
* Type: {boolean} `true` if the response is the result of one or more
redirects.
### `response.status`
<!-- YAML
added: v1.0.0
-->
* Type: {number} The HTTP status code of the response.
### `response.ok`
<!-- YAML
added: v1.0.0
-->
* Type: {boolean} `true` when [`status`](#responsestatus) is in the range
`200`–`299`.
### `response.statusText`
<!-- YAML
added: v1.0.0
-->
* Type: {string} The status message corresponding to the status code.
### `response.headers`
<!-- YAML
added: v1.0.0
-->
* Type: {Headers} The {Headers} object associated with the response.
## Class: `Request`
<!-- YAML
added: v1.0.0
-->
* Extends: {BodyMixin}
Represents a resource request. Instances can be passed to `fetch()` in place
of a URL string. The implementation follows the [WHATWG Fetch Standard][]; see
the [MDN `Request` documentation][]. `Request` inherits the body-reading
methods described in [Body mixin](#body-mixin).
### `new Request(input[, init])`
<!-- YAML
added: v1.0.0
-->
* `input` {string|URL|Request} The resource to request, as a URL string,
{URL}, or another {Request} to copy.
* `init` {RequestInit} (optional) An options object with the same fields as
the `init` argument of [`fetch()`](#fetchinput-init).
* Returns: {Request}
Creates a new `Request`.
### `request.clone()`
<!-- YAML
added: v1.0.0
-->
* Returns: {Request} A copy of the request.
Creates a clone of the request. Throws a `TypeError` if the body has already
been read or is locked.
### `request.method`
<!-- YAML
added: v1.0.0
-->
* Type: {string} The request method, for example `'GET'`.
### `request.url`
<!-- YAML
added: v1.0.0
-->
* Type: {string} The serialized URL of the request.
### `request.headers`
<!-- YAML
added: v1.0.0
-->
* Type: {Headers} The {Headers} object associated with the request.
### `request.destination`
<!-- YAML
added: v1.0.0
-->
* Type: {string} The request destination, indicating the type of content being
requested, for example `''`, `'image'`, or `'script'`.
### `request.referrer`
<!-- YAML
added: v1.0.0
-->
* Type: {string} The referrer of the request. May be `'about:client'` or a URL
string.
### `request.referrerPolicy`
<!-- YAML
added: v1.0.0
-->
* Type: {string} The referrer policy of the request.
### `request.mode`
<!-- YAML
added: v1.0.0
-->
* Type: {string} The mode of the request. One of `'cors'`, `'navigate'`,
`'no-cors'`, or `'same-origin'`.
### `request.credentials`
<!-- YAML
added: v1.0.0
-->
* Type: {string} The credentials mode of the request. One of `'omit'`,
`'include'`, or `'same-origin'`.
### `request.cache`
<!-- YAML
added: v1.0.0
-->
* Type: {string} The cache mode of the request.
### `request.redirect`
<!-- YAML
added: v1.0.0
-->
* Type: {string} The redirect mode of the request. One of `'error'`,
`'follow'`, or `'manual'`.
### `request.integrity`
<!-- YAML
added: v1.0.0
-->
* Type: {string} The subresource integrity metadata of the request.
### `request.keepalive`
<!-- YAML
added: v1.0.0
-->
* Type: {boolean} Whether the request may outlive the environment that created
it.
### `request.isReloadNavigation`
<!-- YAML
added: v1.0.0
-->
* Type: {boolean} `true` if the request is a reload navigation.
### `request.isHistoryNavigation`
<!-- YAML
added: v1.0.0
-->
* Type: {boolean} `true` if the request is a history navigation.
### `request.signal`
<!-- YAML
added: v1.0.0
-->
* Type: {AbortSignal} The {AbortSignal} associated with the request.
### `request.duplex`
<!-- YAML
added: v1.0.0
-->
* Type: {string} The duplex mode of the request. Always `'half'`.
## Class: `Headers`
<!-- YAML
added: v4.4.0
-->
Represents the header list of a request or response and provides methods to
read and modify it. The implementation follows the [WHATWG Fetch Standard][];
see the [MDN `Headers` documentation][]. `Headers` is iterable, yielding
`[name, value]` pairs sorted by name.
### `new Headers([init])`
<!-- YAML
added: v4.4.0
-->
* `init` {Headers|Object|Array} (optional) Initial headers, as a {Headers}
instance, a plain object of name/value pairs, or an array of `[name, value]`
pairs.
Creates a new `Headers` object.
### `headers.append(name, value)`
<!-- YAML
added: v1.0.0
-->
* `name` {string} The name of the header.
* `value` {string} The value of the header.
Appends a value to a header, or adds the header if it does not exist. Existing
values for `name` are preserved.
### `headers.delete(name)`
<!-- YAML
added: v1.0.0
-->
* `name` {string} The name of the header to remove.
Removes the header named `name`.
### `headers.get(name)`
<!-- YAML
added: v1.0.0
-->
* `name` {string} The name of the header to read.
* Returns: {string|null} The combined values of the header, or `null` if it is
not present.
### `headers.has(name)`
<!-- YAML
added: v1.0.0
-->
* `name` {string} The name of the header to look up.
* Returns: {boolean} `true` if the header is present.
### `headers.set(name, value)`
<!-- YAML
added: v1.0.0
-->
* `name` {string} The name of the header.
* `value` {string} The value of the header.
Sets a header to a single value, replacing any existing values for `name`.
### `headers.getSetCookie()`
<!-- YAML
added: v1.0.0
-->
* Returns: {string[]} An array of the values of all `Set-Cookie` headers.
Returns each `Set-Cookie` header as a separate string, without combining them.
## Body mixin
`Request` and `Response` both extend {BodyMixin}, which provides methods and
properties for reading a body. Each consuming method reads the body once; after
the body has been consumed, [`bodyUsed`](#bodybodyused) becomes `true` and
calling another consuming method throws a `TypeError`.
> [!WARNING]
> The `arrayBuffer()`, `blob()`, `bytes()`, `formData()`, `json()`, and `text()`
> methods buffer the entire body in memory before returning. Where applicable,
> they also decode or parse the payload and retain that representation in
> memory. Calling these methods therefore means trusting that the body is small
> enough to fit in the available memory. Do not use them for bodies received
> from untrusted or user-controlled sources. Instead, process `body.body` or
> `body.textStream()` incrementally and enforce an application-specific size
> limit.
### `body.arrayBuffer()`
<!-- YAML
added: v1.0.0
-->
* Returns: {Promise} Fulfills with an {ArrayBuffer} containing the body bytes.
### `body.blob()`
<!-- YAML
added: v1.0.0
-->
* Returns: {Promise} Fulfills with a {Blob} containing the body.
### `body.bytes()`
<!-- YAML
added: v1.0.0
-->
* Returns: {Promise} Fulfills with a {Uint8Array} containing the body bytes.
### `body.formData()`
<!-- YAML
added: v1.0.0
-->
> Stability: 0 - Deprecated
* Returns: {Promise} Fulfills with a {FormData} parsed from the body.
Buffers and parses the entire body as `multipart/form-data` or
`application/x-www-form-urlencoded`. Because multipart parsing has inherent
security risks and the whole body is buffered, this method must only be called
on responses from trusted servers.
For responses from untrusted or user-controlled servers, use a dedicated
streaming parser such as [@fastify/busboy][] and apply application-specific
limits:
```mjs
import { Busboy } from '@fastify/busboy'
import { Readable } from 'node:stream'
const response = await fetch('...')
const busboy = new Busboy({
headers: { 'content-type': response.headers.get('content-type') },
})
// Handle the events emitted by `busboy`.
Readable.fromWeb(response.body).pipe(busboy)
```
### `body.json()`
<!-- YAML
added: v1.0.0
-->
* Returns: {Promise} Fulfills with the result of parsing the body as JSON.
### `body.text()`
<!-- YAML
added: v1.0.0
-->
* Returns: {Promise} Fulfills with a {string} containing the body decoded as
UTF-8.
### `body.textStream()`
<!-- YAML
added: v1.0.0
-->
> Stability: 1 - Experimental
* Returns: {ReadableStream} A {ReadableStream} of {string} chunks produced by
decoding the body as UTF-8.
An undici-specific extension that exposes the body as a stream of decoded text
chunks rather than buffering it. It is not part of the [WHATWG Fetch
Standard][].
### `body.body`
<!-- YAML
added: v1.0.0
-->
* Type: {ReadableStream|null} The body as a {ReadableStream}, or `null` if the
message has no body.
### `body.bodyUsed`
<!-- YAML
added: v1.0.0
-->
* Type: {boolean} `true` once the body has been read.
[@fastify/busboy]: https://www.npmjs.com/package/@fastify/busboy
[MDN Fetch documentation]: https://developer.mozilla.org/en-US/docs/Web/API/fetch
[MDN `FormData` documentation]: https://developer.mozilla.org/en-US/docs/Web/API/FormData
[MDN `Headers` documentation]: https://developer.mozilla.org/en-US/docs/Web/API/Headers
[MDN `Request` documentation]: https://developer.mozilla.org/en-US/docs/Web/API/Request
[MDN `Response` documentation]: https://developer.mozilla.org/en-US/docs/Web/API/Response
[WHATWG Fetch Standard]: https://fetch.spec.whatwg.org/
node_modules/undici/docs/docs/api/GlobalInstallation.md
Generated Vendored
+121
View File
@@ -0,0 +1,121 @@
# Global Installation
<!--introduced_in=v7.11.0-->
<!--type=module-->
<!-- source_link=index.js -->
> Stability: 2 - Stable
undici ships its own implementations of several WHATWG web APIs. The `install()`
function assigns those implementations onto `globalThis`, so they can be used
without importing them from `'undici'` first. This is useful for polyfilling
environments, guaranteeing consistent behavior across Node.js versions, and
satisfying third-party libraries that expect the relevant classes to be global.
```mjs
import { install } from 'undici'
install()
// `fetch`, `Headers`, `Response`, `Request`, etc. now resolve to undici's
// implementations.
const response = await fetch('https://example.com')
```
```cjs
const { install } = require('undici')
install()
```
## `install()`
<!-- YAML
added: v7.11.0
-->
* Returns: {undefined}
Overwrites the following properties of `globalThis` with undici's
implementations:
* `globalThis.fetch`
* `globalThis.Headers`
* `globalThis.Response`
* `globalThis.Request`
* `globalThis.FormData`
* `globalThis.WebSocket`
* `globalThis.CloseEvent`
* `globalThis.ErrorEvent`
* `globalThis.MessageEvent`
* `globalThis.EventSource`
Each installed value is the same object exported by `'undici'` under the
matching name, so the global identifiers form a single, self-consistent set.
The assignment is unconditional: any pre-existing global of the same name,
including the Node.js built-in, is replaced. The change persists for the
lifetime of the process. Calling `install()` more than once is safe and simply
re-assigns the same values.
Documentation for each installed class lives on its own page: see
[`fetch`][], [`WebSocket`][], and [`EventSource`][].
```mjs
import { install } from 'undici'
install()
const headers = new Headers([['content-type', 'application/json']])
const request = new Request('https://example.com')
const formData = new FormData()
const ws = new WebSocket('wss://example.com')
const eventSource = new EventSource('https://example.com/events')
```
### Pairing `fetch` and `FormData`
When a request body is a `FormData` instance, the `fetch` and `FormData`
implementations must come from the same source. After `install()`, both globals
resolve to undici, so they always match:
```mjs
import { install } from 'undici'
install()
const body = new FormData()
await fetch('https://example.com', { method: 'POST', body })
```
If global installation is not desired, import the matching pair directly from
`'undici'` instead:
```mjs
import { fetch, FormData } from 'undici'
const body = new FormData()
await fetch('https://example.com', { method: 'POST', body })
```
Mixing a global `FormData` with `undici.fetch()`, or `undici.FormData` with the
built-in global `fetch()`, can produce surprising multipart behavior across
Node.js and undici versions. Keep the two paired.
### Conditional installation
`install()` can be guarded so undici's `fetch` is only installed when no global
`fetch` already exists:
```mjs
import { install } from 'undici'
if (typeof globalThis.fetch === 'undefined') {
install()
}
const response = await fetch('https://example.com')
```
[`EventSource`]: EventSource.md#class-eventsource
[`WebSocket`]: WebSocket.md#class-websocket
[`fetch`]: Fetch.md
node_modules/undici/docs/docs/api/H2CClient.md
Generated Vendored
+385
View File
@@ -0,0 +1,385 @@
# H2CClient
<!--introduced_in=v7.7.0-->
<!--type=module-->
<!-- source_link=lib/dispatcher/h2c-client.js -->
> Stability: 2 - Stable
An `H2CClient` is a [`Dispatcher`][] that speaks HTTP/2 in cleartext (h2c) over a
single TCP connection to an `http:` origin, without the protocol upgrade or prior
knowledge negotiation that a regular [`Client`][] performs. It is a thin
specialization of [`Client`][] that forces `allowH2` and `useH2c` on and aliases
`pipelining` to `maxConcurrentStreams`, so multiple requests are multiplexed as
HTTP/2 streams rather than pipelined HTTP/1.x requests.
Use an `H2CClient` when the server is known to accept cleartext HTTP/2 directly,
for example a service behind a trusted proxy or in a test environment. Only the
`http:` protocol is supported; passing any other protocol throws
`InvalidArgumentError`.
```mjs
import { H2CClient } from 'undici'
const client = new H2CClient('http://localhost:3000')
const { statusCode, body } = await client.request({ path: '/', method: 'GET' })
console.log(statusCode)
console.log(await body.text())
```
## Class: `H2CClient`
<!-- YAML
added: v7.7.0
changes:
- version: v7.17.0
pr-url: https://github.com/nodejs/undici/pull/4690
description: Added support for h2c over Unix domain sockets.
-->
* Extends: {Client}
`H2CClient` inherits the full instance API of [`Client`][] (and therefore of
[`Dispatcher`][]). The sections below cover the surface that is meaningful for an
h2c client; refer to [`Dispatcher`][] for the complete semantics of each method
and event.
### `new H2CClient(url[, options])`
<!-- YAML
added: v7.7.0
-->
* `url` {URL|string} The origin to connect to. Should include only the protocol,
hostname, and port. Only the `http:` protocol is supported.
* `options` {H2CClientOptions} (optional)
* `maxConcurrentStreams` {number} The maximum number of concurrent HTTP/2
streams for the session. It is advertised to the server and may be overridden
by a remote `SETTINGS` frame. Must be a positive integer. **Default:** `100`.
* `pipelining` {number} The number of concurrent requests multiplexed over the
single connection. For an `H2CClient` this is aliased to
`maxConcurrentStreams` and may not exceed it. Must be a positive integer.
**Default:** `100`.
* `maxHeaderSize` {number} The maximum length of request headers in bytes.
**Default:** Node.js' `--max-http-header-size` or `16384` (16 KiB).
* `headersTimeout` {number} The amount of time, in milliseconds, the parser
waits to receive the complete HTTP headers. **Default:** `300e3`.
* `connectTimeout` {number} The timeout for establishing a socket connection,
in milliseconds. Use `0` to disable it entirely. **Default:** `10e3`.
* `bodyTimeout` {number} The timeout, in milliseconds, after which a request
times out. Monitors the time between received body data. Use `0` to disable
it entirely. **Default:** `300e3`.
* `keepAliveTimeout` {number} The timeout, in milliseconds, after which a
socket without active requests times out. May be overridden by _keep-alive_
hints from the server. **Default:** `4e3`.
* `keepAliveMaxTimeout` {number} The maximum allowed `keepAliveTimeout`, in
milliseconds, when overridden by _keep-alive_ hints from the server.
**Default:** `600e3`.
* `keepAliveTimeoutThreshold` {number} A number of milliseconds subtracted from
server _keep-alive_ hints when overriding `keepAliveTimeout`, to account for
timing inaccuracies such as transport latency. **Default:** `1e3`.
* `socketPath` {string} An IPC endpoint, either a Unix domain socket or a
Windows named pipe. **Default:** `null`.
* `strictContentLength` {boolean} If `true`, an error is thrown when the
request `content-length` header does not match the length of the request
body. **Default:** `true`.
* `maxCachedSessions` {number} The maximum number of TLS sessions cached by the
built-in connector. Use `0` to disable TLS session caching. **Default:** `100`.
* `connect` {Object|Function} Connector options passed to `buildConnector`, or
a custom connector function. The `allowH2` option may not be set here.
**Default:** `null`.
* `maxRequestsPerClient` {number} The maximum number of requests to send over
a single connection before it is reset. Use `0` to disable this limit.
**Default:** `null`.
* `localAddress` {string} The local IP address the socket should connect from.
* `maxResponseSize` {number} The maximum allowed response body size in bytes.
Use `-1` to disable. **Default:** `-1`.
* `autoSelectFamily` {boolean} Enables a family autodetection algorithm that
loosely implements section 5 of [RFC 8305][]. Ignored if not supported by the
current Node.js version.
* `autoSelectFamilyAttemptTimeout` {number} The amount of time, in
milliseconds, to wait for a connection attempt to finish before trying the
next address when `autoSelectFamily` is enabled.
Creates a new `H2CClient` for the given origin. The client does not connect until
a request is queued; call [`h2cClient.connect()`](#h2cclientconnectoptions-callback)
to connect eagerly.
```mjs
import { H2CClient } from 'undici'
const client = new H2CClient('http://localhost:3000')
```
### `h2cClient.close([callback])`
<!-- YAML
added: v7.7.0
-->
* `callback` {Function} (optional) Invoked once all queued requests have settled
and the client is closed.
* Returns: {Promise|undefined} A `Promise` that resolves once the client is
closed, when `callback` is not provided.
Closes the client and gracefully waits for enqueued requests to complete before
resolving. See [`dispatcher.close([callback])`][].
### `h2cClient.destroy([error[, callback]])`
<!-- YAML
added: v7.7.0
-->
* `error` {Error} (optional) The error with which to reject pending requests.
**Default:** `null`.
* `callback` {Function} (optional) Invoked once the client is destroyed.
* Returns: {Promise|undefined} A `Promise` that resolves once the client is
destroyed, when `callback` is not provided.
Destroys the client abruptly, aborting any pending requests. Waits until the
socket is closed before invoking `callback` (or resolving the returned `Promise`).
See [`dispatcher.destroy([error[, callback]])`][].
### `h2cClient.connect(options[, callback])`
<!-- YAML
added: v7.7.0
-->
* `options` {Object}
* `path` {string}
* `headers` {Object} (optional) **Default:** `null`.
* `signal` {AbortSignal|EventEmitter|null} (optional) **Default:** `null`.
* `opaque` {any} (optional) An opaque value passed through to the returned
connect data.
* `responseHeaders` {string|null} (optional) Set to `'raw'` to return the
response headers as a raw array instead of an object. **Default:** `null`.
* `callback` {Function} (optional) Invoked with `(err, data)` once the connection
is established. If omitted, a `Promise` is returned instead.
* Returns: {Promise|undefined} A `Promise` resolving to the connect data, when
`callback` is not provided.
Starts an HTTP `CONNECT` request. See [`dispatcher.connect(options[, callback])`][].
### `h2cClient.dispatch(options, handlers)`
<!-- YAML
added: v7.7.0
-->
* `options` {Object} The request options.
* `handlers` {Object} The dispatch handler callbacks.
* Returns: {boolean} `false` if the dispatcher is busy and the caller should wait
for the [`'drain'`](#event-drain) event before dispatching again.
The lowest-level request API. All other request methods are implemented on top of
it. See [`dispatcher.dispatch(options, handler)`][].
### `h2cClient.pipeline(options, handler)`
<!-- YAML
added: v7.7.0
-->
* `options` {Object} The request options.
* `handler` {Function} A handler that receives the response data and returns a
{Readable} body.
* Returns: {Duplex} A duplex stream for the request body and response body.
Sends a request and returns a duplex stream, suitable for piping. See
[`dispatcher.pipeline(options, handler)`][].
### `h2cClient.request(options[, callback])`
<!-- YAML
added: v7.7.0
-->
* `options` {Object} The request options.
* `callback` {Function} (optional) Invoked with `(err, data)` once the response
is received. If omitted, a `Promise` is returned instead.
* Returns: {Promise|undefined} A `Promise` resolving to the response data, when
`callback` is not provided.
Performs an HTTP request. See [`dispatcher.request(options[, callback])`][].
### `h2cClient.stream(options, factory[, callback])`
<!-- YAML
added: v7.7.0
-->
* `options` {Object} The request options.
* `factory` {Function} A factory that returns a {Writable} to which the response
body is written.
* `callback` {Function} (optional) Invoked once the request completes. If
omitted, a `Promise` is returned instead.
* Returns: {Promise|undefined} A `Promise` that resolves once the request
completes, when `callback` is not provided.
Sends a request and writes the response body to the stream returned by `factory`.
See [`dispatcher.stream(options, factory[, callback])`][].
### `h2cClient.upgrade(options[, callback])`
<!-- YAML
added: v7.7.0
-->
* `options` {Object} The request options.
* `callback` {Function} (optional) Invoked with `(err, data)` once the upgrade
completes. If omitted, a `Promise` is returned instead.
* Returns: {Promise|undefined} A `Promise` resolving to the upgrade data, when
`callback` is not provided.
Upgrades a connection to a different protocol. See
[`dispatcher.upgrade(options[, callback])`][].
### `h2cClient.closed`
<!-- YAML
added: v7.7.0
-->
* Type: {boolean}
`true` after [`h2cClient.close()`](#h2cclientclosecallback) has been called.
### `h2cClient.destroyed`
<!-- YAML
added: v7.7.0
-->
* Type: {boolean}
`true` after [`h2cClient.destroy()`](#h2cclientdestroyerror-callback) has been
called, or after [`h2cClient.close()`](#h2cclientclosecallback) has been called
and the client shutdown has completed.
### `h2cClient.pipelining`
<!-- YAML
added: v7.7.0
-->
* Type: {number}
Gets and sets the pipelining factor, i.e. the number of requests multiplexed over
the connection.
### Event: `'connect'`
<!-- YAML
added: v7.7.0
-->
* `origin` {URL}
* `targets` {Array<Dispatcher>}
Emitted when the socket has been created and connected. The client connects once
`client.size > 0`. See [Dispatcher Event: `'connect'`][].
```mjs
import { createServer } from 'node:http2'
import { once } from 'node:events'
import { H2CClient } from 'undici'
const server = createServer((request, response) => {
response.end('Hello, World!')
}).listen()
await once(server, 'listening')
const client = new H2CClient(`http://localhost:${server.address().port}`)
client.on('connect', (origin) => {
console.log(`Connected to ${origin}`)
})
const { body } = await client.request({ path: '/', method: 'GET' })
console.log(await body.text())
client.close()
server.close()
```
### Event: `'disconnect'`
<!-- YAML
added: v7.7.0
-->
* `origin` {URL}
* `targets` {Array<Dispatcher>}
* `error` {Error}
Emitted when the socket has disconnected. The `error` argument is the error that
caused the socket to disconnect. The client reconnects if (or once)
`client.size > 0`. See [Dispatcher Event: `'disconnect'`][].
```mjs
import { createServer } from 'node:http2'
import { once } from 'node:events'
import { H2CClient } from 'undici'
const server = createServer((request, response) => {
response.destroy()
}).listen()
await once(server, 'listening')
const client = new H2CClient(`http://localhost:${server.address().port}`)
client.on('disconnect', (origin) => {
console.log(`Disconnected from ${origin}`)
})
try {
await client.request({ path: '/', method: 'GET' })
} catch (error) {
console.error(error.message)
} finally {
client.close()
server.close()
}
```
### Event: `'drain'`
<!-- YAML
added: v7.7.0
-->
* `origin` {URL}
Emitted when the client is no longer busy and can accept more requests. See
[Dispatcher Event: `'drain'`][].
### Event: `'error'`
<!-- YAML
added: v7.7.0
-->
* `error` {Error}
Emitted for user errors, such as an error thrown from an `onResponseError`
handler.
[RFC 8305]: https://tools.ietf.org/html/rfc8305#section-5
[Dispatcher Event: `'connect'`]: Dispatcher.md#event-connect
[Dispatcher Event: `'disconnect'`]: Dispatcher.md#event-disconnect
[Dispatcher Event: `'drain'`]: Dispatcher.md#event-drain
[`Client`]: Client.md#class-client
[`Dispatcher`]: Dispatcher.md#class-dispatcher
[`dispatcher.close([callback])`]: Dispatcher.md#dispatcherclosecallback
[`dispatcher.connect(options[, callback])`]: Dispatcher.md#dispatcherconnectoptions-callback
[`dispatcher.destroy([error[, callback]])`]: Dispatcher.md#dispatcherdestroyerror-callback
[`dispatcher.dispatch(options, handler)`]: Dispatcher.md#dispatcherdispatchoptions-handler
[`dispatcher.pipeline(options, handler)`]: Dispatcher.md#dispatcherpipelineoptions-handler
[`dispatcher.request(options[, callback])`]: Dispatcher.md#dispatcherrequestoptions-callback
[`dispatcher.stream(options, factory[, callback])`]: Dispatcher.md#dispatcherstreamoptions-factory-callback
[`dispatcher.upgrade(options[, callback])`]: Dispatcher.md#dispatcherupgradeoptions-callback
node_modules/undici/docs/docs/api/Interceptors.md
Generated Vendored
+419
View File
@@ -0,0 +1,419 @@
# 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 })
)
```
---
## Custom interceptors
Custom interceptors use the same shape as
[`dispatcher.compose()`](./Dispatcher.md#dispatchercomposeinterceptors-interceptor):
an interceptor takes a `dispatch` function and returns another dispatch-like
function with the same `(options, handler)` signature.
When an interceptor wraps the handler, forward the callbacks that it does not
handle itself. The complete handler callback list is documented under
[`dispatcher.dispatch(options, handler)`](./Dispatcher.md#dispatcherdispatchoptions-handler).
```js
import { Agent } from 'undici'
const timingInterceptor = dispatch => {
return (options, handler) => {
const started = performance.now()
return dispatch(options, {
...handler,
onResponseStart (controller, statusCode, headers, statusMessage) {
const duration = Math.round(performance.now() - started)
const method = options.method ?? 'GET'
const origin = options.origin ?? ''
console.log(`${method} ${origin}${options.path} -> ${statusCode} in ${duration}ms`)
return handler.onResponseStart?.(
controller,
statusCode,
headers,
statusMessage
)
},
onResponseError (controller, error) {
const duration = Math.round(performance.now() - started)
console.error(`request failed after ${duration}ms`, error)
return handler.onResponseError?.(controller, error)
}
})
}
}
const dispatcher = new Agent().compose(timingInterceptor)
const { body } = await dispatcher.request({
origin: 'https://example.com',
path: '/',
method: 'GET'
})
await body.dump()
await dispatcher.close()
```
---
## `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 declared or received body size 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`.
* `maxSize` {number} Maximum decompressed response size in bytes for each
decompression stage. The request fails with a
`ResponseExceededMaxSizeError` if a stage exceeds this limit. Set to `0` to
disable the limit. **Default:** `0`.
**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
maxSize: 16 * 1024 * 1024 // limit decoded bodies to 16 MiB
})
)
```
---
## `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
node_modules/undici/docs/docs/api/MockAgent.md
Generated Vendored
+622
View File
@@ -0,0 +1,622 @@
# MockAgent
<!--introduced_in=v4.0.0-->
<!--type=module-->
<!-- source_link=lib/mock/mock-agent.js -->
> Stability: 2 - Stable
A `MockAgent` is a {Dispatcher} that intercepts HTTP requests made through
undici and replies with programmed mock responses instead of contacting the
network. It is useful for testing code that performs HTTP requests without
relying on a live server.
A `MockAgent` does not intercept requests on its own. Mock responses are
registered on the {MockClient} or {MockPool} instances returned by
[`mockAgent.get(origin)`][], and requests are routed through them once the
`MockAgent` is set as the dispatcher (for example through
[`setGlobalDispatcher()`][] or a per-request `dispatcher` option).
> [!NOTE]
> [`setGlobalDispatcher()`][] only affects undici APIs that use the global
> dispatcher, such as `request()` and `fetch()`. It does not replace or
> monkeypatch {Pool} or {Client} instances that were created separately. To test
> code that accepts or creates a pool/client directly, pass the {MockPool} or
> {MockClient} returned by [`mockAgent.get(origin)`][] into that code.
```mjs
import { MockAgent } from 'undici'
const mockAgent = new MockAgent()
```
## Class: `MockAgent`
<!-- YAML
added: v4.0.0
-->
* Extends: {Dispatcher}
Intercepts HTTP requests made through undici and returns mocked responses.
### `new MockAgent([options])`
<!-- YAML
added: v4.0.0
changes:
- version: v7.16.0
pr-url: https://github.com/nodejs/undici/pull/4479
description: Mock options are always normalized to an object internally.
-->
* `options` {MockAgentOptions} (optional)
* Returns: {MockAgent}
When instantiated, a `MockAgent` is automatically activated. It does not
intercept any request until mock interceptors are registered on the dispatchers
returned by [`mockAgent.get(origin)`][].
#### Parameter: `MockAgentOptions`
* Extends: {AgentOptions}
* `agent` {Dispatcher} (optional) A custom agent to be encapsulated by the
`MockAgent`. It must implement the `Agent` API (that is, expose a `dispatch`
function). **Default:** a new {Agent} constructed from `options`.
* `ignoreTrailingSlash` {boolean} (optional) Whether trailing slashes in the
request path are ignored when matching interceptors. **Default:** `false`.
* `acceptNonStandardSearchParameters` {boolean} (optional) Whether the matcher
also accepts URLs using non-standard search-parameter syntaxes, such as
multi-value items written with `[]` (for example `param[]=1&param[]=2`) or
comma-separated values (for example `param=1,2,3`). **Default:** `false`.
* `enableCallHistory` {boolean} (optional) Whether call history recording is
enabled. See [`mockAgent.getCallHistory()`][]. **Default:** `false`.
```mjs displayName="Basic instantiation"
import { MockAgent } from 'undici'
const mockAgent = new MockAgent()
```
```mjs displayName="Instantiation with a custom agent"
import { Agent, MockAgent } from 'undici'
const agent = new Agent()
const mockAgent = new MockAgent({ agent })
```
### `mockAgent.get(origin)`
<!-- YAML
added: v4.0.0
-->
* `origin` {string|RegExp|Function} A matcher for the origin to retrieve. The
function form has the signature `(origin) => boolean`.
* Returns: {MockClient|MockPool}
Creates and retrieves the mock dispatcher used to intercept requests for the
given origin. When the `connections` option of the `MockAgent` is `1`, a
{MockClient} is returned; otherwise a {MockPool} is returned. Subsequent calls
with the same origin return the same instance.
The way `origin` is matched against incoming requests depends on its type:
| Matcher type | Condition to pass |
| :----------: | ---------------------------- |
| `string` | Exact match against the value |
| `RegExp` | The regular expression matches |
| `Function` | The function returns `true` |
```mjs displayName="Basic mocked request"
import { MockAgent, setGlobalDispatcher, request } from 'undici'
const mockAgent = new MockAgent()
setGlobalDispatcher(mockAgent)
const mockPool = mockAgent.get('http://localhost:3000')
mockPool.intercept({ path: '/foo' }).reply(200, 'foo')
const { statusCode, body } = await request('http://localhost:3000/foo')
console.log('response received', statusCode) // response received 200
for await (const data of body) {
console.log('data', data.toString('utf8')) // data foo
}
```
```mjs displayName="Mocked request using a local dispatcher"
import { MockAgent, request } from 'undici'
const mockAgent = new MockAgent()
const mockPool = mockAgent.get('http://localhost:3000')
mockPool.intercept({ path: '/foo' }).reply(200, 'foo')
const { statusCode, body } = await request('http://localhost:3000/foo', {
dispatcher: mockAgent
})
console.log('response received', statusCode) // response received 200
for await (const data of body) {
console.log('data', data.toString('utf8')) // data foo
}
```
```mjs displayName="Testing code that accepts a pool"
import { MockAgent } from 'undici'
async function getStatus (pool) {
const { statusCode } = await pool.request({
path: '/foo',
method: 'GET'
})
return statusCode
}
const mockAgent = new MockAgent()
const mockPool = mockAgent.get('http://localhost:3000')
mockPool.intercept({ path: '/foo', method: 'GET' }).reply(200)
console.log(await getStatus(mockPool)) // 200
```
```mjs displayName="Returning a MockClient"
import { MockAgent, request } from 'undici'
const mockAgent = new MockAgent({ connections: 1 })
const mockClient = mockAgent.get('http://localhost:3000')
mockClient.intercept({ path: '/foo' }).reply(200, 'foo')
const { statusCode, body } = await request('http://localhost:3000/foo', {
dispatcher: mockClient
})
console.log('response received', statusCode) // response received 200
for await (const data of body) {
console.log('data', data.toString('utf8')) // data foo
}
```
```mjs displayName="Matching the origin with a regular expression"
import { MockAgent, setGlobalDispatcher, request } from 'undici'
const mockAgent = new MockAgent()
setGlobalDispatcher(mockAgent)
const mockPool = mockAgent.get(new RegExp('http://localhost:3000'))
mockPool.intercept({ path: '/foo' }).reply(200, 'foo')
const { statusCode } = await request('http://localhost:3000/foo')
console.log('response received', statusCode) // response received 200
```
```mjs displayName="Matching the origin with a function"
import { MockAgent, setGlobalDispatcher, request } from 'undici'
const mockAgent = new MockAgent()
setGlobalDispatcher(mockAgent)
const mockPool = mockAgent.get((origin) => origin === 'http://localhost:3000')
mockPool.intercept({ path: '/foo' }).reply(200, 'foo')
const { statusCode } = await request('http://localhost:3000/foo')
console.log('response received', statusCode) // response received 200
```
### `mockAgent.dispatch(options, handler)`
<!-- YAML
added: v4.0.0
-->
* `options` {AgentDispatchOptions}
* `handler` {DispatchHandler}
* Returns: {boolean}
Dispatches a mocked request. This implements
[`Dispatcher.dispatch()`][] for the encapsulated agent: it ensures the mock
dispatcher for `options.origin` exists, records the call in the call history
when enabled, and forwards the request to the underlying agent. It is normally
invoked indirectly through higher-level methods such as
[`mockAgent.request()`][].
```mjs displayName="Using mockAgent.request()"
import { MockAgent } from 'undici'
const mockAgent = new MockAgent()
const mockPool = mockAgent.get('http://localhost:3000')
mockPool.intercept({ path: '/foo' }).reply(200, 'foo')
const { statusCode, body } = await mockAgent.request({
origin: 'http://localhost:3000',
path: '/foo',
method: 'GET'
})
console.log('response received', statusCode) // response received 200
for await (const data of body) {
console.log('data', data.toString('utf8')) // data foo
}
```
### `mockAgent.close()`
<!-- YAML
added: v4.0.0
-->
* Returns: {Promise<void>} Resolves once the agent and its registered mock pools
and clients have closed.
Clears the call history, closes the encapsulated agent, and waits for all
registered mock pools and clients to close.
```mjs displayName="Clean up after tests"
import { MockAgent, setGlobalDispatcher } from 'undici'
const mockAgent = new MockAgent()
setGlobalDispatcher(mockAgent)
await mockAgent.close()
```
### `mockAgent.deactivate()`
<!-- YAML
added: v4.0.0
-->
* Returns: {undefined}
Disables mocking on the `MockAgent`. While deactivated, requests are no longer
intercepted.
```mjs displayName="Deactivate mocking"
import { MockAgent, setGlobalDispatcher } from 'undici'
const mockAgent = new MockAgent()
setGlobalDispatcher(mockAgent)
mockAgent.deactivate()
```
### `mockAgent.activate()`
<!-- YAML
added: v4.0.0
-->
* Returns: {undefined}
Enables mocking on the `MockAgent`. A `MockAgent` is activated automatically
when instantiated, so this method is only required after
[`mockAgent.deactivate()`][] has been called.
```mjs displayName="Re-activate mocking"
import { MockAgent, setGlobalDispatcher } from 'undici'
const mockAgent = new MockAgent()
setGlobalDispatcher(mockAgent)
mockAgent.deactivate()
// No mocking will occur
// Later
mockAgent.activate()
```
### `mockAgent.enableNetConnect([matcher])`
<!-- YAML
added: v4.0.0
-->
* `matcher` {string|RegExp|Function} (optional) A host matcher. When a string is
used it should only contain the hostname and, optionally, the port. The
function form has the signature `(host) => boolean`. When omitted, all
non-matching requests are allowed to perform a real request.
* Returns: {undefined}
Defines host matchers so that requests that are not intercepted by a mock
dispatcher are allowed to perform a real HTTP request. Calling this method
multiple times with a string appends each value to the list of allowed hosts.
```mjs displayName="Allow all non-matching requests"
import { MockAgent, setGlobalDispatcher, request } from 'undici'
const mockAgent = new MockAgent()
setGlobalDispatcher(mockAgent)
mockAgent.enableNetConnect()
await request('http://example.com')
// A real request is made
```
```mjs displayName="Allow requests matching specific hosts"
import { MockAgent, setGlobalDispatcher, request } from 'undici'
const mockAgent = new MockAgent()
setGlobalDispatcher(mockAgent)
mockAgent.enableNetConnect('example-1.com')
mockAgent.enableNetConnect('example-2.com:8080')
await request('http://example-1.com')
// A real request is made
await request('http://example-2.com:8080')
// A real request is made
await request('http://example-3.com')
// Will throw
```
```mjs displayName="Allow requests matching a regular expression or function"
import { MockAgent, setGlobalDispatcher, request } from 'undici'
const mockAgent = new MockAgent()
setGlobalDispatcher(mockAgent)
mockAgent.enableNetConnect(new RegExp('example.com'))
mockAgent.enableNetConnect((host) => host === 'example.org')
await request('http://example.com')
// A real request is made
```
### `mockAgent.disableNetConnect()`
<!-- YAML
added: v4.0.0
-->
* Returns: {undefined}
Causes every request that is not matched by a mock interceptor to throw,
disallowing real HTTP requests.
```mjs displayName="Throw on every non-matching request"
import { MockAgent, request } from 'undici'
const mockAgent = new MockAgent()
mockAgent.disableNetConnect()
await request('http://example.com')
// Will throw
```
### `mockAgent.enableCallHistory()`
<!-- YAML
added: v7.5.0
-->
* Returns: {MockAgent} The same `MockAgent` instance, for chaining.
Enables call history recording. Once enabled, subsequent calls are registered
and can be retrieved through [`mockAgent.getCallHistory()`][]. Call history can
also be enabled at construction time with the `enableCallHistory` option.
```mjs
import { MockAgent } from 'undici'
const mockAgent = new MockAgent()
mockAgent.enableCallHistory()
```
### `mockAgent.disableCallHistory()`
<!-- YAML
added: v7.5.0
-->
* Returns: {MockAgent} The same `MockAgent` instance, for chaining.
Disables call history recording. Subsequent calls are no longer registered.
```mjs
import { MockAgent } from 'undici'
const mockAgent = new MockAgent({ enableCallHistory: true })
mockAgent.disableCallHistory()
```
### `mockAgent.getCallHistory()`
<!-- YAML
added: v7.5.0
-->
* Returns: {MockCallHistory|undefined} The {MockCallHistory} instance, or
`undefined` when call history is not enabled.
Returns the call history instance, which records every request made through the
`MockAgent` (whether intercepted or not). Call history is not enabled by
default; enable it with the `enableCallHistory` option or
[`mockAgent.enableCallHistory()`][].
```mjs displayName="Inspect recorded calls"
import { MockAgent, setGlobalDispatcher, request } from 'undici'
const mockAgent = new MockAgent({ enableCallHistory: true })
setGlobalDispatcher(mockAgent)
await request('http://example.com', { query: { item: 1 } })
mockAgent.getCallHistory()?.firstCall()
// Returns
// MockCallHistoryLog {
// body: undefined,
// headers: undefined,
// method: 'GET',
// origin: 'http://example.com',
// fullUrl: 'http://example.com/?item=1',
// path: '/',
// searchParams: { item: '1' },
// protocol: 'http:',
// host: 'example.com',
// port: ''
// }
```
### `mockAgent.clearCallHistory()`
<!-- YAML
added: v7.5.0
-->
* Returns: {undefined}
Clears the call history, deleting every recorded {MockCallHistoryLog} on the
{MockCallHistory} instance. It is a no-op when call history has never been
enabled.
```mjs
import { MockAgent } from 'undici'
const mockAgent = new MockAgent({ enableCallHistory: true })
mockAgent.clearCallHistory()
```
### `mockAgent.pendingInterceptors()`
<!-- YAML
added: v5.1.0
-->
* Returns: {PendingInterceptor[]} A `PendingInterceptor` is a `MockDispatch`
with an additional `origin` {string} property.
Returns the interceptors registered on the `MockAgent` that are still pending.
An interceptor is pending when it meets one of the following criteria:
* It is registered with neither `.times(<number>)` nor `.persist()` and has not
been invoked.
* It is persistent (registered with `.persist()`) and has not been invoked.
* It is registered with `.times(<number>)` and has not been invoked `<number>`
times.
```mjs displayName="List pending interceptors"
import { MockAgent } from 'undici'
const mockAgent = new MockAgent()
mockAgent.disableNetConnect()
mockAgent
.get('https://example.com')
.intercept({ method: 'GET', path: '/' })
.reply(200)
const pendingInterceptors = mockAgent.pendingInterceptors()
// Returns [
// {
// timesInvoked: 0,
// times: 1,
// persist: false,
// consumed: false,
// pending: true,
// path: '/',
// method: 'GET',
// body: undefined,
// headers: undefined,
// data: {
// error: null,
// statusCode: 200,
// data: '',
// headers: {},
// trailers: {}
// },
// origin: 'https://example.com'
// }
// ]
```
### `mockAgent.assertNoPendingInterceptors([options])`
<!-- YAML
added: v5.1.0
-->
* `options` {Object} (optional)
* `pendingInterceptorsFormatter` {Object} An object exposing a
`format(pendingInterceptors)` method used to render the pending interceptors
in the thrown error message. **Default:** a built-in formatter that prints a
table.
* Returns: {undefined}
Throws an {UndiciError} when the `MockAgent` has any pending interceptors. The
criteria for an interceptor being pending are the same as for
[`mockAgent.pendingInterceptors()`][].
```mjs displayName="Assert there are no pending interceptors"
import { MockAgent } from 'undici'
const mockAgent = new MockAgent()
mockAgent.disableNetConnect()
mockAgent
.get('https://example.com')
.intercept({ method: 'GET', path: '/' })
.reply(200)
mockAgent.assertNoPendingInterceptors()
// Throws an UndiciError with the following message:
//
// 1 interceptor is pending:
//
// ┌─────────┬────────┬───────────────────────┬──────┬─────────────┬────────────┬─────────────┬───────────┐
// │ (index) │ Method │ Origin │ Path │ Status code │ Persistent │ Invocations │ Remaining │
// ├─────────┼────────┼───────────────────────┼──────┼─────────────┼────────────┼─────────────┼───────────┤
// │ 0 │ 'GET' │ 'https://example.com' │ '/' │ 200 │ '❌' │ 0 │ 1 │
// └─────────┴────────┴───────────────────────┴──────┴─────────────┴────────────┴─────────────┴───────────┘
```
### `mockAgent.isMockActive`
<!-- YAML
added: v5.3.0
-->
* Type: {boolean} `true` while mocking is active, `false` after
[`mockAgent.deactivate()`][] has been called.
A read-only property indicating whether mocking is currently active on the
`MockAgent`.
```mjs
import { MockAgent } from 'undici'
const mockAgent = new MockAgent()
console.log(mockAgent.isMockActive) // true
mockAgent.deactivate()
console.log(mockAgent.isMockActive) // false
```
[`Dispatcher.dispatch()`]: Dispatcher.md#dispatcherdispatchoptions-handler
[`mockAgent.deactivate()`]: #mockagentdeactivate
[`mockAgent.enableCallHistory()`]: #mockagentenablecallhistory
[`mockAgent.get(origin)`]: #mockagentgetorigin
[`mockAgent.getCallHistory()`]: #mockagentgetcallhistory
[`mockAgent.pendingInterceptors()`]: #mockagentpendinginterceptors
[`mockAgent.request()`]: Dispatcher.md#dispatcherrequestoptions-callback
[`setGlobalDispatcher()`]: Dispatcher.md#setglobaldispatcherdispatcher
node_modules/undici/docs/docs/api/MockCallHistory.md
Generated Vendored
+371
View File
@@ -0,0 +1,371 @@
# MockCallHistory
<!--introduced_in=v7.5.0-->
<!--type=module-->
<!-- source_link=lib/mock/mock-call-history.js -->
> Stability: 2 - Stable
A `MockCallHistory` records the configuration of every request intercepted by a
[`MockAgent`][] for which call history is enabled. Each recorded request is
stored as a [`MockCallHistoryLog`][], and the `MockCallHistory` exposes helpers
to read and filter those logs in tests.
Instances are not created directly. Enable call history on a [`MockAgent`][] and
retrieve the history with `mockAgent.getCallHistory()`:
```mjs
import { MockAgent } from 'undici'
const mockAgent = new MockAgent({ enableCallHistory: true })
const callHistory = mockAgent.getCallHistory()
```
Call history can also be enabled after construction:
```mjs
import { MockAgent } from 'undici'
const mockAgent = new MockAgent()
mockAgent.enableCallHistory()
const callHistory = mockAgent.getCallHistory()
```
## Class: `MockCallHistory`
<!-- YAML
added: v7.5.0
-->
Tracks the configuration of intercepted requests as an ordered collection of
[`MockCallHistoryLog`][] entries.
A `MockCallHistory` is iterable. Use it with a `for...of` loop, the spread
operator, or any constructor that accepts an iterable:
```mjs
for (const log of mockAgent.getCallHistory()) {
// ...
}
const logs = [...mockAgent.getCallHistory()]
const logSet = new Set(mockAgent.getCallHistory())
```
### `mockCallHistory.calls()`
<!-- YAML
added: v7.5.0
-->
* Returns: {MockCallHistoryLog[]} All recorded logs, in the order the requests
were intercepted.
Returns every recorded [`MockCallHistoryLog`][] as an array.
```mjs
mockAgent.getCallHistory()?.calls()
```
### `mockCallHistory.firstCall()`
<!-- YAML
added: v7.5.0
-->
* Returns: {MockCallHistoryLog|undefined} The first recorded log, or `undefined`
when no request has been recorded.
Returns the first recorded [`MockCallHistoryLog`][].
```mjs
mockAgent.getCallHistory()?.firstCall()
```
### `mockCallHistory.lastCall()`
<!-- YAML
added: v7.5.0
-->
* Returns: {MockCallHistoryLog|undefined} The last recorded log, or `undefined`
when no request has been recorded.
Returns the last recorded [`MockCallHistoryLog`][].
```mjs
mockAgent.getCallHistory()?.lastCall()
```
### `mockCallHistory.nthCall(position)`
<!-- YAML
added: v7.5.0
-->
* `position` {number} The 1-based position of the log to return. Must be a
positive integer.
* Returns: {MockCallHistoryLog|undefined} The log at `position`, or `undefined`
when no log exists at that position.
Returns the [`MockCallHistoryLog`][] at the given 1-based `position`. The index
is 1-based for readability, so `nthCall(1)` is equivalent to `firstCall()`.
Throws an [`InvalidArgumentError`][] when `position` is not a number, not an
integer, or not positive. Use `firstCall()` or `lastCall()` instead of passing a
non-positive value.
```mjs
mockAgent.getCallHistory()?.nthCall(3) // the third recorded log
```
### `mockCallHistory.filterCalls(criteria[, options])`
<!-- YAML
added: v7.5.0
-->
* `criteria` {Function|RegExp|Object} The filter to apply.
* When a {Function} is given, it is used as the predicate of
`Array.prototype.filter` and receives each [`MockCallHistoryLog`][]; logs for
which it returns a truthy value are kept.
* When a {RegExp} is given, a log is kept when the expression matches its
[`mockCallHistoryLog.toString()`][] representation.
* When an {Object} is given, each property is a request field to filter on and
each value is a [filter parameter](#filter-parameter). An empty object
returns every log.
* `protocol` {string|RegExp|null|undefined} Filters by request protocol.
* `host` {string|RegExp|null|undefined} Filters by request host.
* `port` {string|RegExp|null|undefined} Filters by request port.
* `origin` {string|RegExp|null|undefined} Filters by request origin.
* `path` {string|RegExp|null|undefined} Filters by request path.
* `hash` {string|RegExp|null|undefined} Filters by request hash.
* `fullUrl` {string|RegExp|null|undefined} Filters by request full URL.
* `method` {string|RegExp|null|undefined} Filters by request method.
* `options` {Object} Adjusts the filtering behavior. Only applied when `criteria`
is an object. (optional)
* `operator` {string} How to combine multiple object properties. `'OR'` keeps
a log matching any criterion; `'AND'` keeps a log matching every criterion.
The value is case-insensitive. **Default:** `'OR'`.
* Returns: {MockCallHistoryLog[]} The matching logs. Duplicates produced by an
`'OR'` combination are removed.
A convenience method for applying one or several filters at once. It is a more
expressive alternative to the per-field helpers below.
Throws an [`InvalidArgumentError`][] when `criteria` is not a function, regular
expression, or object, or when `options.operator` is neither `'OR'` nor `'AND'`.
```mjs
const callHistory = mockAgent.getCallHistory()
callHistory?.filterCalls((log) =>
log.hash === '#hash' && log.headers?.authorization !== undefined)
callHistory?.filterCalls(/"errors": "wrong body"/)
// Logs with a hash containing `my-hash` OR a path equal to `/endpoint`.
callHistory?.filterCalls({ hash: /my-hash/, path: '/endpoint' })
// Logs with a hash containing `my-hash` AND a path equal to `/endpoint`.
callHistory?.filterCalls(
{ hash: /my-hash/, path: '/endpoint' },
{ operator: 'AND' }
)
```
### `mockCallHistory.filterCallsByProtocol(criteria)`
<!-- YAML
added: v7.5.0
-->
* `criteria` {string|RegExp|null|undefined} See
[filter parameter](#filter-parameter).
* Returns: {MockCallHistoryLog[]} The logs whose protocol matches `criteria`.
Filters the recorded logs by request protocol.
```mjs
mockAgent.getCallHistory()?.filterCallsByProtocol(/https/)
mockAgent.getCallHistory()?.filterCallsByProtocol('https:')
```
### `mockCallHistory.filterCallsByHost(criteria)`
<!-- YAML
added: v7.5.0
-->
* `criteria` {string|RegExp|null|undefined} See
[filter parameter](#filter-parameter).
* Returns: {MockCallHistoryLog[]} The logs whose host matches `criteria`.
Filters the recorded logs by request host.
```mjs
mockAgent.getCallHistory()?.filterCallsByHost(/localhost/)
mockAgent.getCallHistory()?.filterCallsByHost('localhost:3000')
```
### `mockCallHistory.filterCallsByPort(criteria)`
<!-- YAML
added: v7.5.0
-->
* `criteria` {string|RegExp|null|undefined} See
[filter parameter](#filter-parameter).
* Returns: {MockCallHistoryLog[]} The logs whose port matches `criteria`.
Filters the recorded logs by request port.
```mjs
mockAgent.getCallHistory()?.filterCallsByPort(/3000/)
mockAgent.getCallHistory()?.filterCallsByPort('3000')
mockAgent.getCallHistory()?.filterCallsByPort('')
```
### `mockCallHistory.filterCallsByOrigin(criteria)`
<!-- YAML
added: v7.5.0
-->
* `criteria` {string|RegExp|null|undefined} See
[filter parameter](#filter-parameter).
* Returns: {MockCallHistoryLog[]} The logs whose origin matches `criteria`.
Filters the recorded logs by request origin.
```mjs
mockAgent.getCallHistory()?.filterCallsByOrigin(/http:\/\/localhost:3000/)
mockAgent.getCallHistory()?.filterCallsByOrigin('http://localhost:3000')
```
### `mockCallHistory.filterCallsByPath(criteria)`
<!-- YAML
added: v7.5.0
-->
* `criteria` {string|RegExp|null|undefined} See
[filter parameter](#filter-parameter).
* Returns: {MockCallHistoryLog[]} The logs whose path matches `criteria`.
Filters the recorded logs by request path.
```mjs
mockAgent.getCallHistory()?.filterCallsByPath(/api\/v1\/graphql/)
mockAgent.getCallHistory()?.filterCallsByPath('/api/v1/graphql')
```
### `mockCallHistory.filterCallsByHash(criteria)`
<!-- YAML
added: v7.5.0
-->
* `criteria` {string|RegExp|null|undefined} See
[filter parameter](#filter-parameter).
* Returns: {MockCallHistoryLog[]} The logs whose hash matches `criteria`.
Filters the recorded logs by request hash.
```mjs
mockAgent.getCallHistory()?.filterCallsByHash(/hash/)
mockAgent.getCallHistory()?.filterCallsByHash('#hash')
```
### `mockCallHistory.filterCallsByFullUrl(criteria)`
<!-- YAML
added: v7.5.0
-->
* `criteria` {string|RegExp|null|undefined} See
[filter parameter](#filter-parameter).
* Returns: {MockCallHistoryLog[]} The logs whose full URL matches `criteria`.
Filters the recorded logs by request full URL. The full URL contains the
protocol, host, port, path, query parameters, and hash.
```mjs
mockAgent.getCallHistory()?.filterCallsByFullUrl(/https:\/\/localhost:3000\/\?query=value#hash/)
mockAgent.getCallHistory()?.filterCallsByFullUrl('https://localhost:3000/?query=value#hash')
```
### `mockCallHistory.filterCallsByMethod(criteria)`
<!-- YAML
added: v7.5.0
-->
* `criteria` {string|RegExp|null|undefined} See
[filter parameter](#filter-parameter).
* Returns: {MockCallHistoryLog[]} The logs whose method matches `criteria`.
Filters the recorded logs by request method.
```mjs
mockAgent.getCallHistory()?.filterCallsByMethod(/POST/)
mockAgent.getCallHistory()?.filterCallsByMethod('POST')
```
### `mockCallHistory.clear()`
<!-- YAML
added: v7.5.0
-->
* Returns: {undefined}
Removes every recorded [`MockCallHistoryLog`][]. This is performed
automatically when `mockAgent.close()` is called.
```mjs
mockAgent.clearCallHistory()
// Equivalent to:
mockAgent.getCallHistory()?.clear()
```
### `mockCallHistory[Symbol.iterator]()`
<!-- YAML
added: v7.5.0
-->
* Returns: {Generator} A generator yielding each recorded
[`MockCallHistoryLog`][] in order.
Makes a `MockCallHistory` iterable, yielding the same logs returned by
`calls()`. This enables `for...of` iteration, the spread operator, and
constructing other iterables from a history.
```mjs
const callHistory = mockAgent.getCallHistory()
for (const log of callHistory) {
console.log(log.method, log.fullUrl)
}
const logs = [...callHistory]
```
## Filter parameter
The per-field `filterCallsBy*` helpers and the object form of `filterCalls()`
accept a filter parameter that is matched against the corresponding field of each
[`MockCallHistoryLog`][]:
* A {string} keeps a log only when the field is strictly equal to the value.
* `null` keeps a log only when the field is strictly equal to `null`.
* `undefined` keeps a log only when the field is strictly equal to `undefined`.
* A {RegExp} keeps a log only when the expression matches the field.
Any other value throws an [`InvalidArgumentError`][].
[`InvalidArgumentError`]: Errors.md#class-invalidargumenterror
[`MockAgent`]: MockAgent.md#class-mockagent
[`MockCallHistoryLog`]: MockCallHistoryLog.md#class-mockcallhistorylog
[`mockCallHistoryLog.toString()`]: MockCallHistoryLog.md#mockcallhistorylogtostring
node_modules/undici/docs/docs/api/MockCallHistoryLog.md
Generated Vendored
+206
View File
@@ -0,0 +1,206 @@
# MockCallHistoryLog
<!--introduced_in=v7.5.0-->
<!--type=module-->
<!-- source_link=lib/mock/mock-call-history.js -->
> Stability: 2 - Stable
A `MockCallHistoryLog` is an immutable snapshot of the configuration of a single
request that was intercepted by a [`MockAgent`][]. Each property mirrors a part
of the request, with the URL components already parsed by the WHATWG URL parser.
Instances are not created directly. They are produced by a [`MockCallHistory`][]
when call history is enabled on a [`MockAgent`][], and can be retrieved through
the call history helpers such as `firstCall()`, `lastCall()`, `nthCall()`,
`calls()`, and `filterCalls()`.
```mjs
import { MockAgent } from 'undici'
const mockAgent = new MockAgent({ enableCallHistory: true })
// after some requests have been intercepted:
const log = mockAgent.getCallHistory()?.firstCall()
```
## Class: `MockCallHistoryLog`
<!-- YAML
added: v7.5.0
-->
Represents the configuration of one intercepted request.
### `new MockCallHistoryLog(requestInit)`
<!-- YAML
added: v7.5.0
-->
* `requestInit` {DispatchOptions} The dispatch options of the intercepted
request. **Default:** `{}`.
Creates a new `MockCallHistoryLog`. The `body`, `headers`, and `method`
properties are copied directly from `requestInit`, while the URL-derived
properties (`fullUrl`, `origin`, `path`, `searchParams`, `protocol`, `host`,
`port`, and `hash`) are computed from `requestInit.path` and `requestInit.origin`
using the WHATWG URL parser.
This constructor is internal-facing: instances are created by
[`MockCallHistory`][] when a request is intercepted. It is documented because the
class is part of the public API surface.
### `mockCallHistoryLog.body`
<!-- YAML
added: v7.5.0
-->
* Type: {string|null|undefined}
The body of the intercepted request, exactly as supplied to the dispatcher.
### `mockCallHistoryLog.headers`
<!-- YAML
added: v7.5.0
-->
* Type: {Record<string, string|string[]>|null|undefined}
The headers of the intercepted request.
### `mockCallHistoryLog.method`
<!-- YAML
added: v7.5.0
-->
* Type: {string}
The HTTP method of the intercepted request, for example `'GET'` or `'PUT'`.
### `mockCallHistoryLog.fullUrl`
<!-- YAML
added: v7.5.0
-->
* Type: {string}
The full URL of the intercepted request, including protocol, host, path, search
parameters, and hash.
### `mockCallHistoryLog.origin`
<!-- YAML
added: v7.5.0
-->
* Type: {string}
The origin of the intercepted request, comprising the protocol and host, for
example `'https://localhost:4000'`.
### `mockCallHistoryLog.path`
<!-- YAML
added: v7.5.0
-->
* Type: {string}
The pathname of the intercepted request. It always starts with `/` and never
contains search parameters.
### `mockCallHistoryLog.searchParams`
<!-- YAML
added: v7.5.0
-->
* Type: {Record<string, string>}
The search parameters of the intercepted request as a plain object of key/value
pairs.
### `mockCallHistoryLog.protocol`
<!-- YAML
added: v7.5.0
-->
* Type: {string}
The protocol of the intercepted request, including the trailing colon, for
example `'https:'` or `'http:'`.
### `mockCallHistoryLog.host`
<!-- YAML
added: v7.5.0
-->
* Type: {string}
The host of the intercepted request, including the port when present.
### `mockCallHistoryLog.port`
<!-- YAML
added: v7.5.0
-->
* Type: {string}
The port of the intercepted request. It is an empty string when no explicit port
was used, otherwise a string of digits.
### `mockCallHistoryLog.hash`
<!-- YAML
added: v7.5.0
-->
* Type: {string}
The hash fragment of the intercepted request. It is an empty string when absent,
otherwise a string starting with `#`.
### `mockCallHistoryLog.toMap()`
<!-- YAML
added: v7.5.0
-->
* Returns: {Map} A `Map` whose keys are the property names `protocol`, `host`,
`port`, `origin`, `path`, `hash`, `searchParams`, `fullUrl`, `method`, `body`,
and `headers`, each mapped to the corresponding value of this log.
Returns the log as a `Map` of property name to value.
```mjs
mockAgent.getCallHistory()?.firstCall()?.toMap().get('hash')
// '#hash'
```
### `mockCallHistoryLog.toString()`
<!-- YAML
added: v7.5.0
-->
* Returns: {string} A string representation of the log.
Returns a string built from every property name and value pair. Each pair is
joined with `->` and pairs are separated with `|`. Object values such as
`searchParams` and `headers` are serialized with `JSON.stringify()`.
```mjs
mockAgent.getCallHistory()?.firstCall()?.toString()
// protocol->https:|host->localhost:4000|port->4000|origin->https://localhost:4000|path->/endpoint|hash->#here|searchParams->{"query":"value"}|fullUrl->https://localhost:4000/endpoint?query=value#here|method->PUT|body->"{ "data": "hello" }"|headers->{"content-type":"application/json"}
```
[`MockAgent`]: MockAgent.md#class-mockagent
[`MockCallHistory`]: MockCallHistory.md#class-mockcallhistory
node_modules/undici/docs/docs/api/MockClient.md
Generated Vendored
+199
View File
@@ -0,0 +1,199 @@
# MockClient
<!--introduced_in=v4.0.0-->
<!--type=module-->
<!-- source_link=lib/mock/mock-client.js -->
> Stability: 2 - Stable
A `MockClient` is a [`Client`][] that intercepts requests matching registered
routes and replies with mocked responses instead of contacting the network.
It is created by a [`MockAgent`][] when the agent is configured with a single
connection, and it exposes the same interception API as [`MockPool`][].
A `MockClient` is not constructed directly in most cases; instead it is obtained
through [`mockAgent.get(origin)`][] once the agent has `connections` set to `1`.
```mjs
import { MockAgent } from 'undici'
// `connections: 1` makes the agent hand out `MockClient` instances.
const mockAgent = new MockAgent({ connections: 1 })
const mockClient = mockAgent.get('http://localhost:3000')
```
```cjs
const { MockAgent } = require('undici')
const mockAgent = new MockAgent({ connections: 1 })
const mockClient = mockAgent.get('http://localhost:3000')
```
## Class: `MockClient`
<!-- YAML
added: v4.0.0
-->
* Extends: {Client}
Extends [`Client`][] and implements the `Interceptable` interface, allowing
requests made through it to be matched against registered mocks.
### `new MockClient(origin[, options])`
<!-- YAML
added: v4.0.0
-->
* `origin` {string} The origin to associate this mock client with. It should
only include the protocol, hostname, and port.
* `options` {MockClientOptions} Extends the [`Client`][] options.
* Returns: {MockClient}
The `agent` option is required and must implement the `Agent` interface;
otherwise an `InvalidArgumentError` is thrown.
#### Parameter: `MockClientOptions`
Extends: `ClientOptions`
* `agent` {MockAgent} The agent to associate this mock client with.
* `ignoreTrailingSlash` {boolean} Whether trailing slashes should be ignored
when matching the path of intercepted requests. **Default:** `false`.
### `mockClient.intercept(options)`
<!-- YAML
added: v4.0.0
-->
* `options` {MockInterceptor.Options} The matching criteria for the requests to
intercept.
* `path` {string|RegExp|Function} The path to match against. A function
receives the request path as a `string` and returns a `boolean`.
* `method` {string|RegExp|Function} The method to match against. A function
receives the request method as a `string` and returns a `boolean`.
**Default:** `'GET'`.
* `body` {string|RegExp|Function} The body to match against. A function
receives the request body as a `string` and returns a `boolean`.
* `headers` {Object|Function} The headers to match against, as a map of header
name to a `string`, `RegExp`, or matching function, or a single function
that receives all headers and returns a `boolean`.
* `query` {Object} The query parameters to match against.
* `ignoreTrailingSlash` {boolean} Whether a trailing slash on `path` is
ignored when matching. Inherited from the mock client's
`ignoreTrailingSlash` option when not set.
* Returns: {MockInterceptor} The interceptor used to define the mocked reply.
Registers a route on the mock client and returns a [`MockInterceptor`][] for any
matching request that uses the same origin as this mock client. The interceptor
is then used to define the reply, for example with `reply()` or
`replyWithError()`.
```mjs
import { MockAgent } from 'undici'
const mockAgent = new MockAgent({ connections: 1 })
const mockClient = mockAgent.get('http://localhost:3000')
mockClient.intercept({ path: '/foo', method: 'GET' }).reply(200, 'foo')
```
### `mockClient.cleanMocks()`
<!-- YAML
added: v7.11.0
-->
Removes all registered interceptors from the mock client. Pending mocks defined
before this call no longer match incoming requests.
```mjs
import { MockAgent } from 'undici'
const mockAgent = new MockAgent({ connections: 1 })
const mockClient = mockAgent.get('http://localhost:3000')
mockClient.intercept({ path: '/foo' }).reply(200, 'foo')
mockClient.cleanMocks()
```
### `mockClient.close()`
<!-- YAML
added: v4.0.0
-->
* Returns: {Promise} Fulfills with `undefined` once the mock client is closed.
Closes the mock client, gracefully waiting for any enqueued requests to
complete, and removes it from the associated [`MockAgent`][].
```mjs
import { MockAgent } from 'undici'
const mockAgent = new MockAgent({ connections: 1 })
const mockClient = mockAgent.get('http://localhost:3000')
await mockClient.close()
```
### `mockClient.dispatch(options, handlers)`
<!-- YAML
added: v4.0.0
-->
* `options` {DispatchOptions} The request options.
* `handlers` {DispatchHandler} The handlers invoked over the request lifecycle.
* Returns: {boolean} `false` if the dispatcher is busy and the caller should
wait before dispatching further requests, otherwise `true`.
Dispatches a request, matching it against the registered mocks. This override of
[`dispatcher.dispatch(options, handlers)`][] is what drives the mocking
behaviour for every higher-level method such as `request`.
### `mockClient.request(options[, callback])`
<!-- YAML
added: v4.0.0
-->
* `options` {DispatchOptions}
* `callback` {Function} (optional) Invoked with the response when no `Promise`
is requested.
* Returns: {Promise} Fulfills with the mocked response when no `callback` is
provided.
Performs a request and resolves it against the registered mocks. Inherited from
[`Client`][]; see [`dispatcher.request(options[, callback])`][] for the full
parameter and return value documentation.
```mjs
import { MockAgent } from 'undici'
const mockAgent = new MockAgent({ connections: 1 })
const mockClient = mockAgent.get('http://localhost:3000')
mockClient.intercept({ path: '/foo' }).reply(200, 'foo')
const { statusCode, body } = await mockClient.request({
origin: 'http://localhost:3000',
path: '/foo',
method: 'GET'
})
console.log('response received', statusCode) // response received 200
for await (const data of body) {
console.log('data', data.toString('utf8')) // data foo
}
```
[`Client`]: Client.md#class-client
[`MockAgent`]: MockAgent.md#class-mockagent
[`MockInterceptor`]: MockPool.md#return-mockinterceptor
[`MockPool`]: MockPool.md#class-mockpool
[`dispatcher.dispatch(options, handlers)`]: Dispatcher.md#dispatcherdispatchoptions-handler
[`dispatcher.request(options[, callback])`]: Dispatcher.md#dispatcherrequestoptions-callback
[`mockAgent.get(origin)`]: MockAgent.md#mockagentgetorigin
node_modules/undici/docs/docs/api/MockErrors.md
Generated Vendored
+63
View File
@@ -0,0 +1,63 @@
# MockErrors
<!--introduced_in=v4.0.0-->
<!--type=module-->
<!-- source_link=lib/mock/mock-errors.js -->
> Stability: 2 - Stable
undici raises a dedicated error when a mocked request cannot be matched against
any registered interceptor. The mock error classes are exposed through the
`mockErrors` namespace of the package:
```js
import { mockErrors } from 'undici'
if (err instanceof mockErrors.MockNotMatchedError) {
// handle an unmatched mocked request
}
```
Like every other undici error, the classes in this namespace extend
[`UndiciError`][] and carry a stable `code` string, so failures can be
distinguished programmatically without relying on the error message.
## Class: `MockNotMatchedError`
<!-- YAML
added: v4.0.0
-->
* Extends: {UndiciError}
Thrown when a request issued against a [`MockAgent`][] does not match any of the
registered mock dispatches and the agent is configured to disable net connect.
* `name` {string} Always `'MockNotMatchedError'`.
* `code` {string} Always `'UND_MOCK_ERR_MOCK_NOT_MATCHED'`.
### `new MockNotMatchedError([message])`
<!-- YAML
added: v4.0.0
-->
* `message` {string} The error message. **Default:** `'The request does not match any registered mock dispatches'`.
Creates a new `MockNotMatchedError`. When `message` is omitted, a default
message describing the unmatched request is used.
```js
import { mockErrors } from 'undici'
try {
// ... perform a request that no mock matches ...
} catch (err) {
if (err.code === 'UND_MOCK_ERR_MOCK_NOT_MATCHED') {
console.error('No registered mock matched the request')
}
}
```
[`MockAgent`]: MockAgent.md#class-mockagent
[`UndiciError`]: Errors.md#class-undicierror
node_modules/undici/docs/docs/api/MockPool.md
Generated Vendored
+618
View File
@@ -0,0 +1,618 @@
# MockPool
<!--introduced_in=v4.0.0-->
<!--type=module-->
<!-- source_link=lib/mock/mock-pool.js -->
> Stability: 2 - Stable
A `MockPool` is a [`Pool`][] that intercepts requests matching registered routes
and replies with mocked responses instead of contacting the network. It is
created by a [`MockAgent`][] and exposes the same interception API as
[`MockClient`][].
A `MockPool` is not constructed directly in most cases; instead it is obtained
through [`mockAgent.get(origin)`][]. Once registered as the global dispatcher,
any request whose origin matches the pool is matched against the mocks it holds.
```mjs
import { MockAgent } from 'undici'
const mockAgent = new MockAgent()
const mockPool = mockAgent.get('http://localhost:3000')
```
```cjs
const { MockAgent } = require('undici')
const mockAgent = new MockAgent()
const mockPool = mockAgent.get('http://localhost:3000')
```
## Class: `MockPool`
<!-- YAML
added: v4.0.0
-->
* Extends: {Pool}
Extends [`Pool`][] and implements the `Interceptable` interface, allowing
requests made through it to be matched against registered mocks.
### `new MockPool(origin[, options])`
<!-- YAML
added: v4.0.0
-->
* `origin` {string} The origin to associate this mock pool with. It should only
include the protocol, hostname, and port.
* `options` {MockPoolOptions} Extends the [`Pool`][] options.
* Returns: {MockPool}
The `agent` option is required and must implement the `Agent` interface;
otherwise an `InvalidArgumentError` is thrown.
#### Parameter: `MockPoolOptions`
Extends: `PoolOptions`
* `agent` {MockAgent} The agent to associate this mock pool with.
* `ignoreTrailingSlash` {boolean} Whether trailing slashes should be ignored
when matching the path of intercepted requests. **Default:** `false`.
### `mockPool.intercept(options)`
<!-- YAML
added: v4.0.0
-->
* `options` {MockPoolInterceptOptions} The matching criteria for the requests to
intercept.
* Returns: {MockInterceptor} The interceptor used to define the mocked reply.
Registers a route on the mock pool and returns a [`MockInterceptor`][] for any
matching request that uses the same origin as this mock pool. The interceptor is
then used to define the reply, for example with `reply()` or `replyWithError()`.
Each `intercept()` call is consumed by a single matching request. To match more
than one request, call `intercept()` once per expected request, or use
`persist()` or `times()` on the returned [`MockScope`][]. When no registered
mock matches a request, a real request is attempted unless network connections
have been disabled on the [`MockAgent`][], in which case a `MockNotMatchedError`
is thrown.
A request is intercepted only when every defined matcher passes. The accepted
matcher forms behave as follows:
| Matcher type | Condition to pass |
| :----------: | ---------------------------- |
| `string` | Exact match against the value |
| `RegExp` | The expression must match |
| `Function` | The function must return `true` |
#### Parameter: `MockPoolInterceptOptions`
* `path` {string|RegExp|Function} A matcher for the HTTP request path. The
function form has the signature `(path: string) => boolean`. When a `RegExp`
or function is used, it matches against the request path including all query
parameters in alphabetical order. When a `string` is used, query parameters
can instead be supplied through `query`.
* `method` {string|RegExp|Function} A matcher for the HTTP request method. The
function form has the signature `(method: string) => boolean`.
**Default:** `'GET'`.
* `body` {string|RegExp|Function} A matcher for the HTTP request body. The
function form has the signature `(body: string) => boolean`.
* `headers` {Object|Function} A matcher for the HTTP request headers, given
either as a map of header name to a `string`, `RegExp`, or
`(value: string) => boolean` matcher, or as a single function that receives
all headers and returns a `boolean`. When a map is used, the request must
match every defined header; extra headers not listed here do not affect
matching.
* `query` {Object} A matcher for the HTTP request query string parameters. Only
applies when a `string` was provided for `path`.
* `ignoreTrailingSlash` {boolean} Whether a trailing slash on `path` is ignored
when matching. Inherited from the mock pool's `ignoreTrailingSlash` option
when not set.
#### Return: `MockInterceptor`
The reply behaviour of a matching request is defined through the returned
`MockInterceptor`.
* `reply(statusCode[, data[, responseOptions]])` {Function} Defines the reply
for a matching request.
* `statusCode` {number} The status code of the mocked reply.
* `data` {string|Buffer|Object|Function} The body of the mocked reply.
Objects are serialized to JSON; strings and `Buffer`s are sent as-is. The
function form has the signature
`(opts: MockResponseCallbackOptions) => string | Buffer | Object` and is
invoked with the incoming request to compute the reply body.
* `responseOptions` {MockResponseOptions} Additional reply options.
**Default:** `{}`.
* Returns: {MockScope}
* `reply(callback)` {Function} Defines the reply for a matching request,
computing all reply options dynamically rather than just the body.
* `callback` {Function} A `(opts: MockResponseCallbackOptions) =>
{ statusCode, data, responseOptions }` function invoked with the incoming
request. The callback may be asynchronous; a returned promise is awaited
and must resolve to the same shape.
* Returns: {MockScope}
* `replyWithError(error)` {Function} Defines an error for a matching request to
throw.
* `error` {Error} The error thrown when a request matches.
* Returns: {MockScope}
* `defaultReplyHeaders(headers)` {Function} Sets default headers included on
every subsequent reply defined on this interceptor, in addition to any headers
set on a specific reply.
* `headers` {Object} A map of header name to value.
* Returns: {MockInterceptor}
* `defaultReplyTrailers(trailers)` {Function} Sets default trailers included on
every subsequent reply defined on this interceptor, in addition to any
trailers set on a specific reply.
* `trailers` {Object} A map of trailer name to value.
* Returns: {MockInterceptor}
* `replyContentLength()` {Function} Sets an automatically calculated
`content-length` header on every subsequent reply defined on this interceptor.
* Returns: {MockInterceptor}
By default, `reply()` and `replyWithError()` define the behaviour for the first
matching request only; subsequent requests are not affected unless `persist()`
or `times()` is used on the returned [`MockScope`][].
#### Parameter: `MockResponseCallbackOptions`
The argument passed to the `reply()` data and options callbacks.
* `path` {string} The path of the intercepted request.
* `method` {string} The method of the intercepted request.
* `headers` {Object|Headers} The headers of the intercepted request.
* `origin` {string} The origin of the intercepted request.
* `body` {string|null} The body of the intercepted request.
#### Parameter: `MockResponseOptions`
* `headers` {Object} Headers to include on the mocked reply.
* `trailers` {Object} Trailers to include on the mocked reply.
#### Return: `MockScope`
A `MockScope` is associated with a single [`MockInterceptor`][] and configures
how many times the defined reply is used.
* `delay(waitInMs)` {Function} Delays the associated reply by a set amount of
time.
* `waitInMs` {number} The delay in milliseconds.
* Returns: {MockScope}
* `persist()` {Function} Makes the associated reply match indefinitely, so every
matching request receives the defined response.
* Returns: {MockScope}
* `times(repeatTimes)` {Function} Makes the associated reply match a fixed number
of times. This is overridden by `persist()`.
* `repeatTimes` {number} The number of matching requests the reply applies to.
* Returns: {MockScope}
The following examples show common interception patterns.
```mjs displayName="Basic mocked request"
import { MockAgent, setGlobalDispatcher, request } from 'undici'
const mockAgent = new MockAgent()
setGlobalDispatcher(mockAgent)
const mockPool = mockAgent.get('http://localhost:3000')
mockPool.intercept({ path: '/foo' }).reply(200, 'foo')
const { statusCode, body } = await request('http://localhost:3000/foo')
console.log('response received', statusCode) // response received 200
for await (const data of body) {
console.log('data', data.toString('utf8')) // data foo
}
```
```mjs displayName="Reply with a data callback"
import { MockAgent, setGlobalDispatcher, request } from 'undici'
const mockAgent = new MockAgent()
setGlobalDispatcher(mockAgent)
const mockPool = mockAgent.get('http://localhost:3000')
mockPool.intercept({
path: '/echo',
method: 'GET'
}).reply(200, ({ headers }) => ({ message: headers.message }))
const { statusCode, body } = await request('http://localhost:3000/echo', {
headers: { message: 'hello world!' }
})
console.log('response received', statusCode) // response received 200
for await (const data of body) {
console.log('data', data.toString('utf8')) // {"message":"hello world!"}
}
```
```mjs displayName="Reply with an options callback"
import { MockAgent, setGlobalDispatcher, request } from 'undici'
const mockAgent = new MockAgent()
setGlobalDispatcher(mockAgent)
const mockPool = mockAgent.get('http://localhost:3000')
mockPool.intercept({
path: '/echo',
method: 'GET'
}).reply(({ headers }) => ({
statusCode: 200,
data: { message: headers.message }
}))
const { statusCode, body } = await request('http://localhost:3000/echo', {
headers: { message: 'hello world!' }
})
console.log('response received', statusCode) // response received 200
for await (const data of body) {
console.log('data', data.toString('utf8')) // {"message":"hello world!"}
}
```
```mjs displayName="Reply with an asynchronous options callback"
import { readFile } from 'node:fs/promises'
import { MockAgent, setGlobalDispatcher, request } from 'undici'
const mockAgent = new MockAgent()
setGlobalDispatcher(mockAgent)
const mockPool = mockAgent.get('http://localhost:3000')
mockPool.intercept({
path: '/fixture',
method: 'GET'
}).reply(async ({ path }) => ({
statusCode: 200,
data: await readFile(new URL('./fixture.json', import.meta.url))
}))
const { statusCode, body } = await request('http://localhost:3000/fixture')
console.log('response received', statusCode) // response received 200
for await (const data of body) {
console.log('data', data.toString('utf8')) // contents of fixture.json
}
```
```mjs displayName="Multiple intercepts"
import { MockAgent, setGlobalDispatcher, request } from 'undici'
const mockAgent = new MockAgent()
setGlobalDispatcher(mockAgent)
const mockPool = mockAgent.get('http://localhost:3000')
mockPool.intercept({ path: '/foo', method: 'GET' }).reply(200, 'foo')
mockPool.intercept({ path: '/hello', method: 'GET' }).reply(200, 'hello')
const fooResult = await request('http://localhost:3000/foo')
for await (const data of fooResult.body) {
console.log('data', data.toString('utf8')) // data foo
}
const helloResult = await request('http://localhost:3000/hello')
for await (const data of helloResult.body) {
console.log('data', data.toString('utf8')) // data hello
}
```
```mjs displayName="Match query, body, request headers; reply with headers and trailers"
import { MockAgent, setGlobalDispatcher, request } from 'undici'
const mockAgent = new MockAgent()
setGlobalDispatcher(mockAgent)
const mockPool = mockAgent.get('http://localhost:3000')
mockPool.intercept({
path: '/foo?hello=there&see=ya',
method: 'POST',
body: 'form1=data1&form2=data2',
headers: {
'User-Agent': 'undici',
Host: 'example.com'
}
}).reply(200, { foo: 'bar' }, {
headers: { 'content-type': 'application/json' },
trailers: { 'Content-MD5': 'test' }
})
const { statusCode, headers, trailers, body } = await request(
'http://localhost:3000/foo?hello=there&see=ya',
{
method: 'POST',
body: 'form1=data1&form2=data2',
headers: {
foo: 'bar',
'User-Agent': 'undici',
Host: 'example.com'
}
}
)
console.log('response received', statusCode) // response received 200
console.log('headers', headers) // { 'content-type': 'application/json' }
for await (const data of body) {
console.log('data', data.toString('utf8')) // {"foo":"bar"}
}
console.log('trailers', trailers) // { 'content-md5': 'test' }
```
```mjs displayName="Different matcher forms"
import { MockAgent, setGlobalDispatcher, request } from 'undici'
const mockAgent = new MockAgent()
setGlobalDispatcher(mockAgent)
const mockPool = mockAgent.get('http://localhost:3000')
mockPool.intercept({
path: '/foo',
method: /^GET$/,
body: (value) => value === 'form=data',
headers: {
'User-Agent': 'undici',
Host: /^example\.com$/
}
}).reply(200, 'foo')
const { statusCode, body } = await request('http://localhost:3000/foo', {
method: 'GET',
body: 'form=data',
headers: {
foo: 'bar',
'User-Agent': 'undici',
Host: 'example.com'
}
})
console.log('response received', statusCode) // response received 200
for await (const data of body) {
console.log('data', data.toString('utf8')) // data foo
}
```
```mjs displayName="Reply with an error"
import { MockAgent, setGlobalDispatcher, request } from 'undici'
const mockAgent = new MockAgent()
setGlobalDispatcher(mockAgent)
const mockPool = mockAgent.get('http://localhost:3000')
mockPool.intercept({
path: '/foo',
method: 'GET'
}).replyWithError(new Error('kaboom'))
try {
await request('http://localhost:3000/foo', { method: 'GET' })
} catch (error) {
console.error(error.message) // kaboom
}
```
```mjs displayName="Default reply headers"
import { MockAgent, setGlobalDispatcher, request } from 'undici'
const mockAgent = new MockAgent()
setGlobalDispatcher(mockAgent)
const mockPool = mockAgent.get('http://localhost:3000')
mockPool.intercept({ path: '/foo', method: 'GET' })
.defaultReplyHeaders({ foo: 'bar' })
.reply(200, 'foo')
const { headers } = await request('http://localhost:3000/foo')
console.log('headers', headers) // headers { foo: 'bar' }
```
```mjs displayName="Default reply trailers"
import { MockAgent, setGlobalDispatcher, request } from 'undici'
const mockAgent = new MockAgent()
setGlobalDispatcher(mockAgent)
const mockPool = mockAgent.get('http://localhost:3000')
mockPool.intercept({ path: '/foo', method: 'GET' })
.defaultReplyTrailers({ foo: 'bar' })
.reply(200, 'foo')
const { trailers } = await request('http://localhost:3000/foo')
console.log('trailers', trailers) // trailers { foo: 'bar' }
```
```mjs displayName="Automatic content-length"
import { MockAgent, setGlobalDispatcher, request } from 'undici'
const mockAgent = new MockAgent()
setGlobalDispatcher(mockAgent)
const mockPool = mockAgent.get('http://localhost:3000')
mockPool.intercept({ path: '/foo', method: 'GET' })
.replyContentLength()
.reply(200, 'foo')
const { headers } = await request('http://localhost:3000/foo')
console.log('headers', headers) // headers { 'content-length': '3' }
```
```mjs displayName="Persisted reply"
import { MockAgent, setGlobalDispatcher, request } from 'undici'
const mockAgent = new MockAgent()
setGlobalDispatcher(mockAgent)
const mockPool = mockAgent.get('http://localhost:3000')
mockPool.intercept({ path: '/foo', method: 'GET' }).reply(200, 'foo').persist()
await request('http://localhost:3000/foo') // Matches and returns the mock
await request('http://localhost:3000/foo') // Matches again, indefinitely
```
```mjs displayName="Reply a fixed number of times"
import { MockAgent, setGlobalDispatcher, request } from 'undici'
const mockAgent = new MockAgent()
setGlobalDispatcher(mockAgent)
const mockPool = mockAgent.get('http://localhost:3000')
mockPool.intercept({ path: '/foo', method: 'GET' }).reply(200, 'foo').times(2)
await request('http://localhost:3000/foo') // Matches and returns the mock
await request('http://localhost:3000/foo') // Matches and returns the mock
await request('http://localhost:3000/foo') // No match; a real request is attempted
```
```mjs displayName="Match the path with a function"
import { MockAgent, setGlobalDispatcher, request } from 'undici'
import querystring from 'node:querystring'
const mockAgent = new MockAgent()
setGlobalDispatcher(mockAgent)
const mockPool = mockAgent.get('http://localhost:3000')
const matchPath = (requestPath) => {
const [pathname, search] = requestPath.split('?')
const requestQuery = querystring.parse(search)
if (!pathname.startsWith('/foo')) {
return false
}
return requestQuery.foo === 'bar'
}
mockPool.intercept({ path: matchPath, method: 'GET' }).reply(200, 'foo')
await request('http://localhost:3000/foo?foo=bar') // Matches and returns the mock
```
### `mockPool.close()`
<!-- YAML
added: v4.0.0
-->
* Returns: {Promise} Fulfills with `undefined` once the mock pool is closed.
Closes the mock pool, gracefully waiting for any enqueued requests to complete,
and removes it from the associated [`MockAgent`][].
```mjs
import { MockAgent } from 'undici'
const mockAgent = new MockAgent()
const mockPool = mockAgent.get('http://localhost:3000')
await mockPool.close()
```
### `mockPool.dispatch(options, handlers)`
<!-- YAML
added: v4.0.0
-->
* `options` {DispatchOptions} The request options.
* `handlers` {DispatchHandler} The handlers invoked over the request lifecycle.
* Returns: {boolean} `false` if the dispatcher is busy and the caller should
wait before dispatching further requests, otherwise `true`.
Dispatches a request, matching it against the registered mocks. This override of
[`dispatcher.dispatch(options, handlers)`][] is what drives the mocking
behaviour for every higher-level method such as `request`.
### `mockPool.request(options[, callback])`
<!-- YAML
added: v4.0.0
-->
* `options` {DispatchOptions}
* `callback` {Function} (optional) Invoked with the response when no `Promise`
is requested.
* Returns: {Promise} Fulfills with the mocked response when no `callback` is
provided.
Performs a request and resolves it against the registered mocks. Inherited from
[`Pool`][]; see [`dispatcher.request(options[, callback])`][] for the full
parameter and return value documentation.
```mjs
import { MockAgent } from 'undici'
const mockAgent = new MockAgent()
const mockPool = mockAgent.get('http://localhost:3000')
mockPool.intercept({ path: '/foo', method: 'GET' }).reply(200, 'foo')
const { statusCode, body } = await mockPool.request({
origin: 'http://localhost:3000',
path: '/foo',
method: 'GET'
})
console.log('response received', statusCode) // response received 200
for await (const data of body) {
console.log('data', data.toString('utf8')) // data foo
}
```
### `mockPool.cleanMocks()`
<!-- YAML
added: v7.11.0
-->
* Returns: {undefined}
Removes all registered interceptors from the mock pool. Pending mocks defined
before this call no longer match incoming requests.
```mjs
import { MockAgent } from 'undici'
const mockAgent = new MockAgent()
const mockPool = mockAgent.get('http://localhost:3000')
mockPool.intercept({ path: '/foo' }).reply(200, 'foo')
mockPool.cleanMocks()
```
[`MockAgent`]: MockAgent.md#class-mockagent
[`MockClient`]: MockClient.md#class-mockclient
[`MockInterceptor`]: MockPool.md#return-mockinterceptor
[`MockScope`]: MockPool.md#return-mockscope
[`Pool`]: Pool.md#class-pool
[`dispatcher.dispatch(options, handlers)`]: Dispatcher.md#dispatcherdispatchoptions-handler
[`dispatcher.request(options[, callback])`]: Dispatcher.md#dispatcherrequestoptions-callback
[`mockAgent.get(origin)`]: MockAgent.md#mockagentgetorigin
node_modules/undici/docs/docs/api/Pool.md
Generated Vendored
+278
View File
@@ -0,0 +1,278 @@
# Pool
<!--introduced_in=v1.0.0-->
<!--type=module-->
<!-- source_link=lib/dispatcher/pool.js -->
> Stability: 2 - Stable
A pool of [`Client`][] instances connected to the same upstream origin. A `Pool`
spreads requests across several connections to the same host, which allows more
than one request to be in flight at a time without enabling pipelining on a
single connection.
`Pool` extends [`Dispatcher`][]. Each [`Client`][] in the pool is created lazily
through a configurable `factory` and shares the same options. Requests are not
guaranteed to be dispatched in the order in which they are invoked.
```mjs
import { Pool } from 'undici'
const pool = new Pool('http://localhost:3000', { connections: 10 })
const { statusCode, body } = await pool.request({ path: '/', method: 'GET' })
console.log(statusCode, await body.text())
await pool.close()
```
## Class: `Pool`
<!-- YAML
added: v1.0.0
changes:
- version: v4.10.4
pr-url: https://github.com/nodejs/undici/pull/1114
description: Reworked as part of the balanced pool implementation.
-->
* Extends: {Dispatcher}
### `new Pool(url[, options])`
<!-- YAML
added: v1.0.0
-->
* `url` {URL|string} The upstream origin. It should only include the protocol,
hostname, and port.
* `options` {PoolOptions} (optional) Extends {ClientOptions}, so every
[`Client`][] option is also accepted and forwarded to each pooled client.
* `factory` {Function} Creates the [`Client`][] (or other [`Dispatcher`][])
instances used by the pool.
**Default:** `(origin, opts) => new Client(origin, opts)`.
* `origin` {URL} The parsed upstream origin.
* `opts` {Object} The resolved client options.
* Returns: {Dispatcher}
* `connections` {number|null} The maximum number of [`Client`][] instances the
pool may create. When set to `null` the pool creates an unlimited number of
clients. **Default:** `null`.
* `clientTtl` {number|null} The amount of time, in milliseconds, before an idle
[`Client`][] is removed from the pool and closed. When set to `null` clients
are never removed based on age. **Default:** `null`.
Creates a new `Pool` against `url`. If `connections` is provided it must be a
finite, non-negative number, otherwise an [`InvalidArgumentError`][] is thrown.
The `factory` must be a function, and `connect` (inherited from {ClientOptions})
must be a function or an object when provided.
The connection-related {ClientOptions} (`connect`, `connectTimeout`, `tls`,
`maxCachedSessions`, `socketPath`, `autoSelectFamily`,
`autoSelectFamilyAttemptTimeout`, `allowH2`, and `useH2c`) are used to build the
connector shared by every pooled client.
> [!NOTE]
> `Pool` inherits all {ClientOptions}, including `allowH2` and
> `maxConcurrentStreams`. For an h2-capable HTTPS origin, the pool waits for
> the first TLS connection to finish ALPN negotiation before opening more
> clients. If the server selects h2, concurrent requests share that session up
> to `maxConcurrentStreams`. If it selects HTTP/1.1, the pool resumes normal
> connection fan-out up to `connections`.
```mjs
import { Pool } from 'undici'
const pool = new Pool('http://localhost:3000', {
connections: 128,
pipelining: 1
})
```
### `pool.closed`
<!-- YAML
added: v1.0.0
-->
* Type: {boolean}
`true` after [`pool.close()`][] has been called.
### `pool.destroyed`
<!-- YAML
added: v1.0.0
changes:
- version: v2.0.0
pr-url: https://github.com/nodejs/undici/pull/384
description: Reflects the state set by `pool.close()`.
- version: v4.10.4
pr-url: https://github.com/nodejs/undici/pull/1114
description: Reworked as part of the balanced pool implementation.
-->
* Type: {boolean}
`true` after [`pool.destroy()`][] has been called, or after [`pool.close()`][]
has been called and the pool shutdown has completed.
### `pool.stats`
<!-- YAML
added: v1.0.0
-->
* Type: {PoolStats}
Aggregate statistics for the pool. See [`PoolStats`][].
### `pool.close([callback])`
<!-- YAML
added: v1.0.0
-->
Implements [`dispatcher.close([callback])`][]. Gracefully closes the pool and
all of its clients, waiting for in-flight requests to complete. Resolves once
every pooled client has closed.
### `pool.destroy([error[, callback]])`
<!-- YAML
added: v1.0.0
-->
Implements [`dispatcher.destroy([error[, callback]])`][]. Forcefully destroys
the pool and all of its clients, aborting any in-flight requests with `error`.
### `pool.connect(options[, callback])`
<!-- YAML
added: v1.0.0
-->
See [`dispatcher.connect(options[, callback])`][]. Performs an HTTP `CONNECT`
request through one of the pooled clients.
### `pool.dispatch(options, handler)`
<!-- YAML
added: v1.3.0
changes:
- version: v4.10.4
pr-url: https://github.com/nodejs/undici/pull/1114
description: Reworked as part of the balanced pool implementation.
-->
Implements [`dispatcher.dispatch(options, handler)`][]. Selects an available
client - creating a new one through `factory` when none is free and the
`connections` limit has not been reached - and dispatches the request to it.
### `pool.pipeline(options, handler)`
<!-- YAML
added: v1.0.0
-->
See [`dispatcher.pipeline(options, handler)`][]. Sends a request and returns a
{Duplex} stream that pipes the request body to the response body through
`handler`.
### `pool.request(options[, callback])`
<!-- YAML
added: v1.0.0
-->
See [`dispatcher.request(options[, callback])`][]. Performs a request through one
of the pooled clients.
```mjs
import { Pool } from 'undici'
const pool = new Pool('http://localhost:3000', { connections: 10 })
const { statusCode, headers, body } = await pool.request({
path: '/',
method: 'GET'
})
console.log(statusCode, headers)
console.log(await body.text())
await pool.close()
```
### `pool.stream(options, factory[, callback])`
<!-- YAML
added: v1.0.0
-->
See [`dispatcher.stream(options, factory[, callback])`][]. Performs a request and
writes the response body into the {Writable} stream returned by `factory`.
### `pool.upgrade(options[, callback])`
<!-- YAML
added: v1.0.0
-->
See [`dispatcher.upgrade(options[, callback])`][]. Upgrades a connection
(for example to a WebSocket) through one of the pooled clients.
### Event: `'connect'`
<!-- YAML
added: v1.0.0
-->
* `origin` {URL}
* `targets` {Array} The pool followed by the client that connected,
`[pool, ...targets]`.
Emitted by a pooled client when a socket has connected. See
[`Dispatcher` Event: `'connect'`][]. When `clientTtl` is set, the connecting
client's time-to-live timer starts on this event.
### Event: `'disconnect'`
<!-- YAML
added: v1.0.0
-->
* `origin` {URL}
* `targets` {Array} The pool followed by the client that disconnected,
`[pool, ...targets]`.
* `error` {Error}
Emitted by a pooled client when a socket has disconnected. See
[`Dispatcher` Event: `'disconnect'`][].
### Event: `'drain'`
<!-- YAML
added: v1.0.0
-->
* `origin` {URL}
* `targets` {Array} The pool followed by the client that drained,
`[pool, ...targets]`.
Emitted when a pooled client is no longer busy and can accept more requests. See
[`Dispatcher` Event: `'drain'`][].
[`Client`]: Client.md#class-client
[`Dispatcher` Event: `'connect'`]: Dispatcher.md#event-connect
[`Dispatcher` Event: `'disconnect'`]: Dispatcher.md#event-disconnect
[`Dispatcher` Event: `'drain'`]: Dispatcher.md#event-drain
[`Dispatcher`]: Dispatcher.md#class-dispatcher
[`InvalidArgumentError`]: Errors.md#class-invalidargumenterror
[`PoolStats`]: PoolStats.md
[`dispatcher.close([callback])`]: Dispatcher.md#dispatcherclosecallback
[`dispatcher.connect(options[, callback])`]: Dispatcher.md#dispatcherconnectoptions-callback
[`dispatcher.destroy([error[, callback]])`]: Dispatcher.md#dispatcherdestroyerror-callback
[`dispatcher.dispatch(options, handler)`]: Dispatcher.md#dispatcherdispatchoptions-handler
[`dispatcher.pipeline(options, handler)`]: Dispatcher.md#dispatcherpipelineoptions-handler
[`dispatcher.request(options[, callback])`]: Dispatcher.md#dispatcherrequestoptions-callback
[`dispatcher.stream(options, factory[, callback])`]: Dispatcher.md#dispatcherstreamoptions-factory-callback
[`dispatcher.upgrade(options[, callback])`]: Dispatcher.md#dispatcherupgradeoptions-callback
[`pool.close()`]: #poolclosecallback
[`pool.destroy()`]: #pooldestroyerror-callback
node_modules/undici/docs/docs/api/PoolStats.md
Generated Vendored
+141
View File
@@ -0,0 +1,141 @@
# PoolStats
<!--introduced_in=v4.15.0-->
<!--type=module-->
<!-- source_link=lib/util/stats.js -->
> Stability: 2 - Stable
`PoolStats` exposes a read-only snapshot of the aggregate connection and request
counters for a [`Pool`][] or [`BalancedPool`][]. An instance is created lazily
each time the `pool.stats` getter is accessed, so the values reflect the state of
the pool at the moment of access.
`PoolStats` is not constructed directly in normal use; obtain an instance from
the `stats` property of a pool:
```mjs
import { Pool } from 'undici'
const pool = new Pool('http://localhost:3000')
const { stats } = pool
console.log(stats.connected, stats.running, stats.size)
```
## Class: `PoolStats`
<!-- YAML
added: v4.15.0
changes:
- version: v7.9.0
pr-url: https://github.com/nodejs/undici/pull/4157
description: Pool and client stats are exposed through `Agent`.
-->
Each property is a plain number computed from the pool's internal state when the
instance is created. The instance is a snapshot; read `pool.stats` again to
observe later changes.
### `new PoolStats(pool)`
<!-- YAML
added: v4.15.0
changes:
- version: v7.9.0
pr-url: https://github.com/nodejs/undici/pull/4157
description: Pool and client stats are exposed through `Agent`.
-->
* `pool` {Pool|BalancedPool} The pool to read counters from.
Creates a new `PoolStats` instance from the current state of `pool`. Prefer the
`pool.stats` getter, which returns a fresh `PoolStats` on each access.
### `poolStats.connected`
<!-- YAML
added: v4.15.0
changes:
- version: v7.9.0
pr-url: https://github.com/nodejs/undici/pull/4157
description: Pool and client stats are exposed through `Agent`.
-->
* Type: {number}
Number of open socket connections in this pool.
### `poolStats.free`
<!-- YAML
added: v4.15.0
changes:
- version: v7.9.0
pr-url: https://github.com/nodejs/undici/pull/4157
description: Pool and client stats are exposed through `Agent`.
-->
* Type: {number}
Number of open socket connections in this pool that do not have an active
request.
### `poolStats.pending`
<!-- YAML
added: v4.15.0
changes:
- version: v7.9.0
pr-url: https://github.com/nodejs/undici/pull/4157
description: Pool and client stats are exposed through `Agent`.
-->
* Type: {number}
Number of pending requests across all clients in this pool.
### `poolStats.queued`
<!-- YAML
added: v4.15.0
changes:
- version: v7.9.0
pr-url: https://github.com/nodejs/undici/pull/4157
description: Pool and client stats are exposed through `Agent`.
-->
* Type: {number}
Number of queued requests across all clients in this pool.
### `poolStats.running`
<!-- YAML
added: v4.15.0
changes:
- version: v7.9.0
pr-url: https://github.com/nodejs/undici/pull/4157
description: Pool and client stats are exposed through `Agent`.
-->
* Type: {number}
Number of currently active requests across all clients in this pool.
### `poolStats.size`
<!-- YAML
added: v4.15.0
changes:
- version: v7.9.0
pr-url: https://github.com/nodejs/undici/pull/4157
description: Pool and client stats are exposed through `Agent`.
-->
* Type: {number}
Number of active, pending, or queued requests across all clients in this pool.
[`BalancedPool`]: BalancedPool.md#class-balancedpool
[`Pool`]: Pool.md#class-pool
node_modules/undici/docs/docs/api/ProxyAgent.md
Generated Vendored
+248
View File
@@ -0,0 +1,248 @@
# ProxyAgent
<!--introduced_in=v4.8.2-->
<!--type=module-->
<!-- source_link=lib/dispatcher/proxy-agent.js -->
> Stability: 2 - Stable
A `ProxyAgent` routes every request through an HTTP, HTTPS, or SOCKS5 proxy
server. It implements the [`Agent`][] API, so it can be used wherever a
dispatcher is accepted, for example with [`request`][] or [`fetch`][], or
installed globally with [`setGlobalDispatcher`][].
For secure (`https:`) endpoints the proxy connection is established through an
HTTP `CONNECT` tunnel. SOCKS5 proxies (`socks5:` or `socks:` URIs) are handled
by delegating to a [`Socks5ProxyAgent`][].
```mjs
import { ProxyAgent, setGlobalDispatcher } from 'undici'
const proxyAgent = new ProxyAgent('http://localhost:8000')
setGlobalDispatcher(proxyAgent)
```
## Class: `ProxyAgent`
<!-- YAML
added: v4.8.2
-->
* Extends: {Dispatcher}
`ProxyAgent` keeps an internal [`Agent`][] that creates per-origin dispatchers
on demand. The proxy connection is set up lazily when the first request to an
origin is dispatched, then reused for subsequent requests to the same origin.
### `new ProxyAgent(options)`
<!-- YAML
added: v4.8.2
-->
* `options` {ProxyAgentOptions|string|URL} The proxy URI, or an options object.
Required. When a `string` or {URL} is passed it is used as the proxy `uri`.
The options object extends {AgentOptions} (omitting `connect`).
* `uri` {string} The URI of the proxy server. Required when `options` is an
object. Parsed into a {URL} according to the
[WHATWG URL Specification][].
* `token` {string} A pre-formatted `proxy-authorization` header value sent to
the proxy on every request, for example `` `Bearer ${apiKey}` ``.
* `auth` {string} A base64-encoded `username:password` credential sent as a
`Basic` `proxy-authorization` header. Cannot be combined with `token`.
* `headers` {Object} Additional headers sent to the proxy server on the
`CONNECT` request (or on every request for an untunneled HTTP proxy).
**Default:** `{}`.
* `requestTls` {BuildOptions} TLS options for the connection to the request
endpoint, passed to the connector builder.
* `proxyTls` {BuildOptions} TLS options for the connection to the proxy
server, passed to the connector builder.
* `clientFactory` {Function} Builds the {Dispatcher} used to talk to the proxy
server itself. **Default:** `(origin, opts) => new Pool(origin, opts)`.
* `origin` {URL} The proxy origin.
* `opts` {Object} The resolved options for the dispatcher.
* Returns: {Dispatcher}
* `proxyTunnel` {boolean} Forces tunneling through the proxy. By default,
Undici detects tunneling based on the request protocol. If the target
endpoint uses HTTPS, Undici establishes a `CONNECT` tunnel through the proxy
(after the TLS handshake to the proxy itself when the proxy URL is HTTPS).
If the target endpoint uses plain HTTP, Undici forwards the request to the
proxy using an HTTP/1.1 absolute-form request target (over TLS when the
proxy URL is HTTPS), as required by
[RFC 9112 §3.2.2](https://www.rfc-editor.org/rfc/rfc9112.html#name-absolute-form).
This non-tunneled forwarding path does not negotiate HTTP/2 with the proxy.
Set `proxyTunnel` to `true` to force tunneling for plain HTTP requests as
well. Currently, there is no way to facilitate HTTP/1.1 IP tunneling as
described in
[RFC 9484](https://www.rfc-editor.org/rfc/rfc9484.html#name-http-11-request).
Throws an {InvalidArgumentError} when no proxy URI is provided, when
`clientFactory` is not a function, or when both `auth` and `token` are supplied.
The `proxy-authorization` header is derived, in order of precedence, from
`token`, then `auth`, then the `username` and `password` embedded in the proxy
`uri`. Credentials in the URI are URL-decoded before being base64-encoded.
> [!NOTE]
> Unless {AgentOptions} `connections` is set to `0`, the non-standard
> `proxy-connection: keep-alive` header is added to the tunnel `CONNECT`
> request. This includes the default case where `connections` is unset.
The `auth` option is deprecated; use `token` instead.
```mjs
import { ProxyAgent } from 'undici'
// A string or URL is treated as the proxy uri.
const a = new ProxyAgent('http://localhost:8000')
const b = new ProxyAgent(new URL('http://localhost:8000'))
// An options object requires a `uri`.
const c = new ProxyAgent({ uri: 'http://localhost:8000' })
// With proxy TLS settings.
const d = new ProxyAgent({
uri: 'https://secure.proxy.server',
proxyTls: {
signal: AbortSignal.timeout(1000),
},
})
```
#### Example - proxy request with the global dispatcher
```mjs
import { setGlobalDispatcher, request, ProxyAgent } from 'undici'
const proxyAgent = new ProxyAgent('http://localhost:8000')
setGlobalDispatcher(proxyAgent)
const { statusCode, body } = await request('http://localhost:3000/foo')
console.log('response received', statusCode)
console.log('data', await body.text())
```
#### Example - proxy request with a local dispatcher
```mjs
import { ProxyAgent, request } from 'undici'
const proxyAgent = new ProxyAgent('http://localhost:8000')
const { statusCode, body } = await request('http://localhost:3000/foo', {
dispatcher: proxyAgent,
})
console.log('response received', statusCode)
console.log('data', await body.text())
```
#### Example - proxy request with authentication
```mjs
import { setGlobalDispatcher, request, ProxyAgent } from 'undici'
const proxyAgent = new ProxyAgent({
uri: 'http://localhost:8000',
token: `Basic ${Buffer.from('username:password').toString('base64')}`,
})
setGlobalDispatcher(proxyAgent)
const { statusCode } = await request('http://localhost:3000/foo')
console.log('response received', statusCode)
```
### `proxyAgent.dispatch(options, handler)`
<!-- YAML
added: v4.8.2
-->
* `options` {AgentDispatchOptions} Extends {DispatchOptions}.
* `origin` {string|URL} The origin to dispatch the request against. Required.
* `handler` {DispatchHandler}
* Returns: {boolean} `false` if the dispatcher is busy and the caller should
wait for the [`'drain'`][] event before dispatching again.
Dispatches the request through the proxy. Throws an {InvalidArgumentError} if
the request headers contain a `proxy-authorization` header, which must instead
be supplied through the constructor's `token` or `auth` option. A `host` header
is derived from `options.origin` when one is not already present. Implements
[`Dispatcher.dispatch()`][].
### `proxyAgent.close()`
<!-- YAML
added: v4.8.2
changes:
- version: v7.10.0
pr-url: https://github.com/nodejs/undici/pull/4180
description: Untunneled HTTP-to-HTTP proxy connections match `curl` behavior.
-->
* Returns: {Promise<void>}
Closes the proxy agent and waits for its internal agent and proxy client (when
present) to close before resolving. Implements [`Dispatcher.close()`][].
```mjs
import { ProxyAgent, setGlobalDispatcher } from 'undici'
const proxyAgent = new ProxyAgent('http://localhost:8000')
setGlobalDispatcher(proxyAgent)
await proxyAgent.close()
```
### `proxyAgent.request(options[, callback])`
<!-- YAML
added: v5.0.0
-->
See [`Dispatcher.request()`][]. The request is routed through the proxy.
#### Example - proxy request with `fetch`
```mjs
import { ProxyAgent, fetch } from 'undici'
const proxyAgent = new ProxyAgent('http://localhost:8000')
const response = await fetch('http://localhost:3000/foo', {
dispatcher: proxyAgent,
method: 'GET',
})
console.log('response status', response.status)
console.log('response data', await response.text())
```
#### Example - HTTPS tunneling
```mjs
import { ProxyAgent, fetch } from 'undici'
const proxyAgent = new ProxyAgent('https://secure.proxy.server')
const response = await fetch('https://secure.endpoint.com/api/data', {
dispatcher: proxyAgent,
method: 'GET',
})
console.log('response status', response.status)
console.log('response data', await response.json())
```
[WHATWG URL Specification]: https://url.spec.whatwg.org
[`'drain'`]: Dispatcher.md#event-drain
[`Agent`]: Agent.md#class-agent
[`Dispatcher.close()`]: Dispatcher.md#dispatcherclosecallback-promise
[`Dispatcher.dispatch()`]: Dispatcher.md#dispatcherdispatchoptions-handler
[`Dispatcher.request()`]: Dispatcher.md#dispatcherrequestoptions-callback
[`Socks5ProxyAgent`]: Socks5ProxyAgent.md#class-socks5proxyagent
[`fetch`]: Fetch.md
[`request`]: Dispatcher.md#dispatcherrequestoptions-callback
[`setGlobalDispatcher`]: Dispatcher.md#setglobaldispatcherdispatcher
node_modules/undici/docs/docs/api/RedirectHandler.md
Generated Vendored
+276
View File
@@ -0,0 +1,276 @@
# RedirectHandler
<!--introduced_in=v4.0.0-->
<!--type=module-->
<!-- source_link=lib/handler/redirect-handler.js -->
> Stability: 2 - Stable
A dispatch handler that follows HTTP redirects on behalf of another handler. It
wraps a downstream `handler` and a `dispatch` function: when a redirectable
response is received it transparently re-dispatches the request to the new
location, forwarding the lifecycle callbacks to the wrapped `handler` only once a
final (non-redirect) response is reached.
Redirects are followed for the `300`, `301`, `302`, `303`, `307`, and `308`
status codes, up to `maxRedirections` hops. Following the relevant HTTP
specifications, the method is downgraded to `GET` for `301`/`302` `POST`
responses and for `303` responses with any method other than `HEAD`, request
bodies that have already been consumed are not replayed, and headers that refer
to the original URL (such as `host`) are stripped on each hop, with additional
credential headers removed on cross-origin redirects.
```mjs
import { RedirectHandler } from 'undici'
```
```cjs
const { RedirectHandler } = require('undici')
```
Most users do not construct `RedirectHandler` directly. The `maxRedirections`
option on [`Dispatcher`][] methods and the higher-level clients use it
internally.
## Class: `RedirectHandler`
<!-- YAML
added: v4.0.0
-->
* Extends: {DispatchHandler}
Implements the [`DispatchHandler`][] interface, delegating every callback to the
wrapped `handler` while intercepting redirect responses.
### `new RedirectHandler(dispatch, maxRedirections, opts, handler)`
<!-- YAML
added: v4.0.0
-->
* `dispatch` {Function} The dispatch function used to issue the original request
and every subsequent redirect. Called as `dispatch(options, handler)`.
* `maxRedirections` {number|null} The maximum number of redirects to follow. Must
be a non-negative integer or `null`. When `null` or `0`, no redirects are
followed and redirect responses are passed through to the wrapped `handler`.
* `opts` {DispatchOptions} The dispatch options for the request. In addition to
the standard dispatch options, the following redirect-specific fields are
recognized:
* `throwOnMaxRedirect` {boolean} When `true`, an error is thrown once
`maxRedirections` is reached instead of returning the last redirect response.
**Default:** `false`.
* `stripHeadersOnRedirect` {string[]} Header names to remove from the request on
every redirect hop. **Default:** `null`.
* `stripHeadersOnCrossOriginRedirect` {string[]} Additional header names to
remove from the request when a redirect points to a different origin.
**Default:** `null`.
* `handler` {DispatchHandler} The downstream handler that receives the lifecycle
callbacks for the final response.
Throws an [`InvalidArgumentError`][] when `maxRedirections` is not a non-negative
integer, when `throwOnMaxRedirect` is not a boolean, or when either
`stripHeadersOnRedirect` or `stripHeadersOnCrossOriginRedirect` is not an array of
header-name strings.
```mjs
import { Client, RedirectHandler } from 'undici'
const client = new Client('http://example.com')
const dispatch = client.dispatch.bind(client)
const handler = new RedirectHandler(dispatch, 5, {
method: 'GET',
path: '/',
origin: 'http://example.com',
}, {
onRequestStart () {},
onResponseStart (controller, statusCode, headers) {
console.log(statusCode)
},
onResponseData (controller, chunk) {},
onResponseEnd () {},
})
dispatch({ method: 'GET', path: '/', origin: 'http://example.com' }, handler)
```
### Static method: `RedirectHandler.buildDispatch(dispatcher, maxRedirections)`
<!-- YAML
added: v7.0.0
-->
* `dispatcher` {Dispatcher} The dispatcher whose `dispatch` method is wrapped.
* `maxRedirections` {number|null} The maximum number of redirects to follow. Must
be a non-negative integer or `null`.
* Returns: {Function} A `dispatch(options, handler)` function that wraps each call
in a `RedirectHandler` before delegating to `dispatcher`.
Builds a redirect-aware dispatch function from an existing dispatcher. The
returned function has the same shape as `dispatcher.dispatch` but follows
redirects automatically. Throws an [`InvalidArgumentError`][] when
`maxRedirections` is not a non-negative integer.
```mjs
import { Client, RedirectHandler } from 'undici'
const client = new Client('http://example.com')
const dispatch = RedirectHandler.buildDispatch(client, 5)
dispatch({ method: 'GET', path: '/', origin: 'http://example.com' }, {
onRequestStart () {},
onResponseStart (controller, statusCode) {
console.log(statusCode)
},
onResponseData () {},
onResponseEnd () {},
})
```
### `redirectHandler.onRequestStart(controller, context)`
<!-- YAML
added: v7.0.0
-->
* `controller` {DispatchController} The controller for the in-flight request.
* `context` {Object} The dispatch context.
Forwards the request-start event to the wrapped `handler`, augmenting `context`
with the current redirect `history`.
### `redirectHandler.onRequestUpgrade(controller, statusCode, headers, socket)`
<!-- YAML
added: v7.0.0
-->
* `controller` {DispatchController} The controller for the in-flight request.
* `statusCode` {number} The HTTP status code of the upgrade response.
* `headers` {Object} The response headers.
* `socket` {Duplex} The upgraded socket.
Forwards a connection upgrade to the wrapped `handler`.
### `redirectHandler.onResponseStart(controller, statusCode, headers, statusMessage)`
<!-- YAML
added: v7.0.0
-->
* `controller` {DispatchController} The controller for the in-flight request.
* `statusCode` {number} The HTTP status code of the response.
* `headers` {Object} The response headers.
* `statusMessage` {string} The HTTP status message.
Inspects the response headers to decide whether to follow a redirect. When the
status code is redirectable, the `maxRedirections` limit has not been reached, and
the request body has not been consumed, the `location` property is set, the method
and headers are adjusted for the next hop, and the response is not forwarded.
Otherwise the event is forwarded to the wrapped `handler`.
Throws when `throwOnMaxRedirect` is `true` and the number of recorded redirects
has reached `maxRedirections`, and throws an [`InvalidArgumentError`][] if a
redirect loop is detected (for example when a [`Client`][] or [`Pool`][] is used
for a cross-origin redirect; use an [`Agent`][] instead).
### `redirectHandler.onResponseData(controller, chunk)`
<!-- YAML
added: v7.0.0
-->
* `controller` {DispatchController} The controller for the in-flight request.
* `chunk` {Buffer} A chunk of the response body.
Forwards body data to the wrapped `handler`. While a redirect is pending
(`location` is set), the `3xx` response body is ignored.
### `redirectHandler.onResponseEnd(controller, trailers)`
<!-- YAML
added: v7.0.0
-->
* `controller` {DispatchController} The controller for the in-flight request.
* `trailers` {Object} The response trailers.
Completes the response. When a redirect is pending, the request is re-dispatched
to the new `location`; otherwise the end event is forwarded to the wrapped
`handler`.
### `redirectHandler.onResponseError(controller, error)`
<!-- YAML
added: v7.0.0
-->
* `controller` {DispatchController} The controller for the in-flight request.
* `error` {Error} The error that occurred.
Forwards the error to the wrapped `handler`.
### `redirectHandler.location`
<!-- YAML
added: v4.0.0
-->
* Type: {string|null}
The `Location` header value of the redirect currently being followed, or `null`
when no redirect is pending and the response is being passed through to the
wrapped `handler`.
### `redirectHandler.opts`
<!-- YAML
added: v7.12.0
-->
* Type: {DispatchOptions}
A copy of the dispatch options for the next request. It excludes the redirect
control fields (`maxRedirections`, `stripHeadersOnRedirect`, and
`stripHeadersOnCrossOriginRedirect`) and is mutated on each hop to reflect the
updated method, path, origin, and headers.
### `redirectHandler.maxRedirections`
<!-- YAML
added: v4.0.0
-->
* Type: {number|null}
The maximum number of redirects this handler will follow.
### `redirectHandler.handler`
<!-- YAML
added: v4.0.0
-->
* Type: {DispatchHandler}
The wrapped downstream handler that receives the lifecycle callbacks for the final
response.
### `redirectHandler.history`
<!-- YAML
added: v4.0.0
-->
* Type: {URL[]}
The ordered list of URLs visited while following redirects. It is used to enforce
`maxRedirections` and to detect redirect loops.
[`Agent`]: Agent.md#class-agent
[`Client`]: Client.md#class-client
[`Dispatcher`]: Dispatcher.md#class-dispatcher
[`DispatchHandler`]: Dispatcher.md#parameter-dispatchhandler
[`InvalidArgumentError`]: Errors.md#class-invalidargumenterror
[`Pool`]: Pool.md#class-pool
node_modules/undici/docs/docs/api/RetryAgent.md
Generated Vendored
+136
View File
@@ -0,0 +1,136 @@
# RetryAgent
<!--introduced_in=v6.7.0-->
<!--type=module-->
<!-- source_link=lib/dispatcher/retry-agent.js -->
> Stability: 2 - Stable
A [`Dispatcher`][] that automatically retries failed requests by wrapping
another dispatcher with the retry logic of [`RetryHandler`][]. Requests that fail
with a retryable status code or transport error are re-dispatched according to
the configured retry policy.
```mjs
import { RetryAgent } from 'undici'
```
## Class: `RetryAgent`
<!-- YAML
added: v6.7.0
-->
* Extends: {Dispatcher}
Wraps an existing dispatcher and applies retry behaviour to every request it
dispatches. Lifecycle methods such as [`retryAgent.close()`][] and
[`retryAgent.destroy()`][] are forwarded to the wrapped dispatcher.
### `new RetryAgent(dispatcher[, options])`
<!-- YAML
added: v6.7.0
-->
* `dispatcher` {Dispatcher} The dispatcher to wrap and add retry behaviour to.
* `options` {RetryOptions} (optional)
* `throwOnError` {boolean} When `true`, an error is thrown on the final retry
attempt, preventing the following handlers from being called and destroying
the socket. Disable it when you need the response body for error responses
or when you provide a custom error handler. **Default:** `true`.
* `retry` {Function} Callback invoked on every retry iteration. It receives the
error, the current retry state, and a callback. Pass an error to the callback
to stop retrying, or call it with no argument to perform the retry.
* `err` {Error} The error that caused the retry attempt.
* `context` {RetryContext} The current retry context.
* `state` {RetryState} The mutable retry state.
* `counter` {number} The number of retries performed so far.
* `opts` {Object} The options passed to the retry handler, combining the
dispatch options with `retryOptions`.
* `callback` {Function} Called to continue. Pass an `Error` to stop retrying,
or `null`/`undefined` to perform the next retry.
* `maxRetries` {number} Maximum number of retries to allow. **Default:** `5`.
* `maxTimeout` {number} Maximum number of milliseconds to wait between retries.
**Default:** `30000` (30 seconds).
* `minTimeout` {number} Initial number of milliseconds to wait before the first
retry. **Default:** `500` (half a second).
* `timeoutFactor` {number} Factor by which the timeout is multiplied between
retries. **Default:** `2`.
* `retryAfter` {boolean} When `true`, the delay between retries is inferred from
the `Retry-After` response header when present. **Default:** `true`.
* `methods` {string[]} HTTP methods that are eligible for retry.
**Default:** `['GET', 'HEAD', 'OPTIONS', 'PUT', 'DELETE', 'TRACE']`.
* `statusCodes` {number[]} HTTP status codes that trigger a retry.
**Default:** `[500, 502, 503, 504, 429]`.
* `errorCodes` {string[]} Transport error codes that trigger a retry.
**Default:** `['ECONNRESET', 'ECONNREFUSED', 'ENOTFOUND', 'ENETDOWN', 'ENETUNREACH', 'EHOSTDOWN', 'EHOSTUNREACH', 'EPIPE', 'UND_ERR_SOCKET']`.
Creates a new `RetryAgent` that wraps `dispatcher`. The `options` are stored and
used to construct a [`RetryHandler`][] for each dispatched request.
```mjs
import { Agent, RetryAgent } from 'undici'
const agent = new RetryAgent(new Agent(), {
maxRetries: 3,
minTimeout: 1000,
timeoutFactor: 2,
})
const res = await agent.request({
method: 'GET',
origin: 'http://example.com',
path: '/',
})
console.log(res.statusCode)
console.log(await res.body.text())
```
### `retryAgent.dispatch(options, handler)`
<!-- YAML
added: v6.7.0
-->
* `options` {DispatchOptions} The dispatch options, identical to
[`dispatcher.dispatch()`][].
* `handler` {DispatchHandler} The dispatch handler.
* Returns: {boolean}
Dispatches `options` through the wrapped dispatcher, installing a
[`RetryHandler`][] that applies the configured retry policy before delegating to
`handler`. Returns `false` if the dispatcher is busy and the caller should wait
before dispatching again, otherwise `true`.
### `retryAgent.close()`
<!-- YAML
added: v6.7.0
-->
* Returns: {Promise} Resolves when the wrapped dispatcher has closed.
Gracefully closes the wrapped dispatcher, waiting for in-flight requests to
complete. Equivalent to calling [`dispatcher.close()`][] on the wrapped
dispatcher.
### `retryAgent.destroy()`
<!-- YAML
added: v6.7.0
-->
* Returns: {Promise} Resolves when the wrapped dispatcher has been destroyed.
Forcefully destroys the wrapped dispatcher, aborting all pending requests.
Equivalent to calling [`dispatcher.destroy()`][] on the wrapped dispatcher.
[`Dispatcher`]: Dispatcher.md#class-dispatcher
[`RetryHandler`]: RetryHandler.md#class-retryhandler
[`dispatcher.close()`]: Dispatcher.md#dispatcherclosecallback
[`dispatcher.destroy()`]: Dispatcher.md#dispatcherdestroyerror-callback
[`dispatcher.dispatch()`]: Dispatcher.md#dispatcherdispatchoptions-handler
[`retryAgent.close()`]: #retryagentclose
[`retryAgent.destroy()`]: #retryagentdestroy
node_modules/undici/docs/docs/api/RetryHandler.md
Generated Vendored
+200
View File
@@ -0,0 +1,200 @@
# RetryHandler
<!--introduced_in=v5.28.0-->
<!--type=module-->
<!-- source_link=lib/handler/retry-handler.js -->
> Stability: 2 - Stable
A [`Dispatcher`][] handler that automatically retries a request when it fails
with a recoverable network error or an eligible HTTP status code. It wraps an
inner handler and re-dispatches the request, applying an exponential backoff and
honouring the `Retry-After` response header. When a response is partially
consumed before the failure, the handler resumes the download with a `Range`
request guarded by the original `ETag`.
The handler is most often used indirectly through [`RetryAgent`][], but it can
also be supplied directly to [`dispatcher.dispatch()`][] for fine-grained
control over the retry behaviour.
```mjs
import { RetryHandler } from 'undici'
```
## Class: `RetryHandler`
<!-- YAML
added: v5.28.0
-->
* Extends: {DispatchHandler}
Implements the [`DispatchHandler`][] interface. An instance is consumed by a
single dispatch call and forwards the dispatch lifecycle to the inner `handler`,
re-issuing the request through the supplied `dispatch` function whenever a retry
is warranted.
> **Note:** The `RetryHandler` does not retry over stateful bodies (for example
> streams or `AsyncIterable`), because once consumed they cannot be replayed. In
> these situations the body is identified as stateful and the request is rejected
> with the `UND_ERR_REQ_RETRY` error instead of being retried.
### `new RetryHandler(options, retryHandlers)`
<!-- YAML
added: v5.28.0
changes:
- version: v7.0.0
pr-url: https://github.com/nodejs/undici/pull/3883
description: Reimplemented on top of the new dispatch lifecycle hooks.
-->
* `options` {DispatchOptions} The dispatch options for the request, extended with
an optional `retryOptions` field. Type is
`DispatchOptions & { retryOptions?: RetryOptions }`.
* `retryOptions` {RetryOptions} (optional) Configuration controlling when and
how the request is retried. See [`RetryOptions`](#retryoptions).
* `retryHandlers` {RetryHandlers} The handlers used to drive the retry loop. See
[`RetryHandlers`](#parameter-retryhandlers).
* Returns: {RetryHandler}
#### `RetryOptions`
* `throwOnError` {boolean} When `true`, an error is thrown on the last retry
attempt and propagated to the inner handler; when `false`, the failing response
is passed through instead, which is useful when the error body is needed or a
custom error handler is in place. **Default:** `true`.
* `retry` {Function} Callback invoked on every retry iteration to decide whether
another attempt should be made. It receives the error, the retry context, and a
callback. Call the callback with an `Error` to stop retrying, or with `null` to
schedule another attempt. **Default:** the built-in retry strategy described
below.
* `err` {Error} The error that triggered the retry.
* `context` {RetryContext} The current retry context. See
[`RetryContext`](#retrycontext).
* `callback` {Function} Signals the outcome of this iteration.
* `result` {Error|null} (optional) An `Error` to abort retrying, or `null` to
retry.
* `maxRetries` {number} Maximum number of retries allowed. **Default:** `5`.
* `maxTimeout` {number} Maximum number of milliseconds to wait between retries.
**Default:** `30000` (30 seconds).
* `minTimeout` {number} Initial number of milliseconds to wait before the first
retry. **Default:** `500` (half a second).
* `timeoutFactor` {number} Multiplier applied to the timeout between successive
retries to produce an exponential backoff. **Default:** `2`.
* `retryAfter` {boolean} When `true`, the delay before the next retry is inferred
from the `Retry-After` response header when present. **Default:** `true`.
* `methods` {string[]} HTTP methods that are eligible for retrying. **Default:**
`['GET', 'HEAD', 'OPTIONS', 'PUT', 'DELETE', 'TRACE']`.
* `statusCodes` {number[]} HTTP status codes that trigger a retry. **Default:**
`[500, 502, 503, 504, 429]`.
* `errorCodes` {string[]} Network error codes that trigger a retry. **Default:**
`['ECONNRESET', 'ECONNREFUSED', 'ENOTFOUND', 'ENETDOWN', 'ENETUNREACH', 'EHOSTDOWN', 'EHOSTUNREACH', 'EPIPE', 'UND_ERR_SOCKET']`.
The default `retry` strategy computes the delay before the next attempt as
`minTimeout * timeoutFactor ** (counter - 1)`, capped at `maxTimeout`. When a
`Retry-After` header is present it takes precedence (interpreted as seconds, or as
an HTTP date), still capped at `maxTimeout`. The default strategy stops retrying
once `counter` exceeds `maxRetries`, when the error code is not in `errorCodes`,
when the method is not in `methods`, or when the response status code is not in
`statusCodes`.
#### `RetryContext`
* `state` {RetryState} The current retry state. See [`RetryState`](#retrystate).
* `opts` {DispatchOptions} The dispatch options passed to the handler, including
the resolved `retryOptions`. Type is
`DispatchOptions & { retryOptions?: RetryOptions }`.
The context object passed as the second argument to the `retry` callback.
#### `RetryState`
* `counter` {number} The current retry attempt, starting at `1` for the first
retry.
Represents the retry state for a given request.
#### Parameter: `RetryHandlers`
* `dispatch` {Function} The dispatch function called to (re-)issue the request on
every attempt. Type is `(options, handler) => boolean`.
* `handler` {DispatchHandler} The inner handler invoked once the request succeeds
or the retries are exhausted.
### Examples
```mjs
import { Client, RetryHandler } from 'undici'
const client = new Client(`http://localhost:${server.address().port}`)
const chunks = []
const handler = new RetryHandler(
{
...dispatchOptions,
retryOptions: {
// Custom retry decision function.
retry (err, { state, opts }, callback) {
if (err.code === 'UND_ERR_DESTROYED') {
callback(err)
return
}
if (err.statusCode === 206) {
callback(err)
return
}
setTimeout(() => callback(null), 1000)
}
}
},
{
dispatch (...args) {
return client.dispatch(...args)
},
handler: {
onRequestStart () {},
onResponseStart (controller, status, headers) {
// Do something with the response headers.
},
onResponseData (controller, chunk) {
chunks.push(chunk)
},
onResponseEnd () {},
onResponseError (controller, err) {
// Handle the error.
}
}
}
)
client.dispatch(dispatchOptions, handler)
```
A minimal handler that relies entirely on the default retry options:
```mjs
import { Client, RetryHandler } from 'undici'
const client = new Client(`http://localhost:${server.address().port}`)
const handler = new RetryHandler(dispatchOptions, {
dispatch: client.dispatch.bind(client),
handler: {
onRequestStart () {},
onResponseStart (controller, status, headers) {},
onResponseData (controller, chunk) {},
onResponseEnd () {},
onResponseError (controller, err) {}
}
})
client.dispatch(dispatchOptions, handler)
```
[`Dispatcher`]: Dispatcher.md#class-dispatcher
[`DispatchHandler`]: Dispatcher.md#parameter-dispatchhandler
[`RetryAgent`]: RetryAgent.md#class-retryagent
[`dispatcher.dispatch()`]: Dispatcher.md#dispatcherdispatchoptions-handler
node_modules/undici/docs/docs/api/RoundRobinPool.md
Generated Vendored
+239
View File
@@ -0,0 +1,239 @@
# RoundRobinPool
<!--introduced_in=v7.17.0-->
<!--type=module-->
<!-- source_link=lib/dispatcher/round-robin-pool.js -->
> Stability: 2 - Stable
A pool of [`Client`][] instances connected to the same upstream target that
selects clients in a round-robin fashion.
Unlike [`Pool`][], which always reuses the first available client,
`RoundRobinPool` cycles through its clients so that requests are distributed
evenly across every open connection. This is useful when the upstream target is
fronted by a load balancer that distributes TCP connections across multiple
backend servers (for example, a Kubernetes Service): each connection is pinned
to a backend by the load balancer, and `RoundRobinPool` spreads requests across
those connections so every backend receives a comparable share of traffic.
Requests are not guaranteed to be dispatched in the order they were invoked.
```mjs
import { RoundRobinPool } from 'undici'
const pool = new RoundRobinPool('http://localhost:3000', { connections: 10 })
```
`RoundRobinPool` distributes HTTP requests evenly across TCP connections, not
across backend servers directly. Even backend distribution therefore depends on
the load balancer assigning different connections to different backends (for
example, round-robin, random, or least-connections without client affinity). If
the load balancer pins all connections from one source to the same backend (for
example, source-IP affinity or sticky sessions), consider [`BalancedPool`][]
with the individual backend addresses instead.
## Class: `RoundRobinPool`
<!-- YAML
added: v7.17.0
-->
* Extends: {Dispatcher}
### `new RoundRobinPool(url[, options])`
<!-- YAML
added: v7.17.0
-->
* `url` {URL|string} The upstream target. It should only include the
**protocol, hostname, and port**.
* `options` {RoundRobinPoolOptions} (optional)
#### Parameter: `RoundRobinPoolOptions`
Extends: {ClientOptions}
* `factory` {Function} A function used to create the underlying {Client}
instances. **Default:** `(origin, opts) => new Client(origin, opts)`.
* `origin` {URL}
* `opts` {Object}
* Returns: {Dispatcher}
* `connections` {number|null} (optional) The maximum number of {Client}
instances to create. When set to `null`, the `RoundRobinPool` instance creates
an unlimited number of {Client} instances. **Default:** `null`.
* `clientTtl` {number|null} (optional) The amount of time, in milliseconds,
before a {Client} instance is removed from the `RoundRobinPool` and closed.
When set to `null`, {Client} instances are not removed or closed based on age.
**Default:** `null`.
`RoundRobinPool` inherits all [`Client`][] options. A [`Client`][] instance is
created lazily on the first dispatch and additional instances are created on
demand, up to `connections`, when every existing client is busy.
### `roundRobinPool.closed`
<!-- YAML
added: v7.17.0
-->
* Type: {boolean}
`true` after `roundRobinPool.close()` has been called.
### `roundRobinPool.destroyed`
<!-- YAML
added: v7.17.0
-->
* Type: {boolean}
`true` after `roundRobinPool.destroy()` has been called, or after
`roundRobinPool.close()` has been called and the pool shutdown has completed.
### `roundRobinPool.stats`
<!-- YAML
added: v7.17.0
-->
* Type: {PoolStats}
Aggregate connection statistics for the pool. See [`PoolStats`][].
### `roundRobinPool.close([callback])`
<!-- YAML
added: v7.17.0
-->
Closes the pool and gracefully waits for enqueued requests to complete before
resolving. Implements [`dispatcher.close([callback])`][].
### `roundRobinPool.destroy([error[, callback]])`
<!-- YAML
added: v7.17.0
-->
Destroys the pool abruptly. All pending and running requests are aborted with
the given `error`. Implements [`dispatcher.destroy([error[, callback]])`][].
### `roundRobinPool.connect(options[, callback])`
<!-- YAML
added: v7.17.0
-->
Starts two-way communications with the requested resource using
[HTTP CONNECT][]. See [`dispatcher.connect(options[, callback])`][].
### `roundRobinPool.dispatch(options, handler)`
<!-- YAML
added: v7.17.0
-->
Dispatches a request through the next client selected in round-robin order.
Implements [`dispatcher.dispatch(options, handler)`][].
### `roundRobinPool.pipeline(options, handler)`
<!-- YAML
added: v7.17.0
-->
For easy use with [`stream.pipeline`][]. See
[`dispatcher.pipeline(options, handler)`][].
### `roundRobinPool.request(options[, callback])`
<!-- YAML
added: v7.17.0
-->
Performs an HTTP request. See [`dispatcher.request(options[, callback])`][].
### `roundRobinPool.stream(options, factory[, callback])`
<!-- YAML
added: v7.17.0
-->
A faster version of [`roundRobinPool.request()`][]. See
[`dispatcher.stream(options, factory[, callback])`][].
### `roundRobinPool.upgrade(options[, callback])`
<!-- YAML
added: v7.17.0
-->
Upgrades a connection to a different protocol. See
[`dispatcher.upgrade(options[, callback])`][].
### Event: `'connect'`
<!-- YAML
added: v7.17.0
-->
See [Dispatcher Event: `'connect'`][].
### Event: `'disconnect'`
<!-- YAML
added: v7.17.0
-->
See [Dispatcher Event: `'disconnect'`][].
### Event: `'drain'`
<!-- YAML
added: v7.17.0
-->
See [Dispatcher Event: `'drain'`][].
## Example
```mjs
import { RoundRobinPool } from 'undici'
const pool = new RoundRobinPool('http://localhost:3000', {
connections: 10
})
// Requests are distributed evenly across all 10 connections.
for (let i = 0; i < 100; i++) {
const { body } = await pool.request({
path: '/api/data',
method: 'GET'
})
console.log(await body.json())
}
await pool.close()
```
[HTTP CONNECT]: https://developer.mozilla.org/docs/Web/HTTP/Methods/CONNECT
[`BalancedPool`]: BalancedPool.md#class-balancedpool
[`Client`]: Client.md#class-client
[`Pool`]: Pool.md#class-pool
[`PoolStats`]: PoolStats.md#class-poolstats
[`dispatcher.close([callback])`]: Dispatcher.md#dispatcherclosecallback-promise
[`dispatcher.connect(options[, callback])`]: Dispatcher.md#dispatcherconnectoptions-callback
[`dispatcher.destroy([error[, callback]])`]: Dispatcher.md#dispatcherdestroyerror-callback-promise
[`dispatcher.dispatch(options, handler)`]: Dispatcher.md#dispatcherdispatchoptions-handler
[`dispatcher.pipeline(options, handler)`]: Dispatcher.md#dispatcherpipelineoptions-handler
[`dispatcher.request(options[, callback])`]: Dispatcher.md#dispatcherrequestoptions-callback
[`dispatcher.stream(options, factory[, callback])`]: Dispatcher.md#dispatcherstreamoptions-factory-callback
[`dispatcher.upgrade(options[, callback])`]: Dispatcher.md#dispatcherupgradeoptions-callback
[`roundRobinPool.request()`]: #roundrobinpoolrequestoptions-callback
[`stream.pipeline`]: https://nodejs.org/api/stream.html#streampipelinesource-transforms-destination-callback
[Dispatcher Event: `'connect'`]: Dispatcher.md#event-connect
[Dispatcher Event: `'disconnect'`]: Dispatcher.md#event-disconnect
[Dispatcher Event: `'drain'`]: Dispatcher.md#event-drain
node_modules/undici/docs/docs/api/SnapshotAgent.md
Generated Vendored
+361
View File
@@ -0,0 +1,361 @@
# SnapshotAgent
<!--introduced_in=v7.13.0-->
<!--type=module-->
<!-- source_link=lib/mock/snapshot-agent.js -->
> Stability: 1 - Experimental
`SnapshotAgent` records real HTTP responses and replays them on later requests,
allowing tests to run against deterministic, captured data instead of a live
network. It extends [`MockAgent`][], so it can be installed with
[`setGlobalDispatcher()`][] or passed explicitly through the `dispatcher`
option, and it works with every undici API (`fetch`, `request`, `stream`,
`pipeline`, and so on).
A `SnapshotAgent` operates in one of three modes. In `'record'` mode it performs
real requests and writes the responses to a snapshot file. In `'playback'` mode
it serves responses from the snapshot file without touching the network. In
`'update'` mode it replays existing snapshots and records any request that has no
matching snapshot.
```mjs
import { SnapshotAgent, setGlobalDispatcher, fetch } from 'undici'
const agent = new SnapshotAgent({
mode: 'record',
snapshotPath: './snapshots/api.json'
})
setGlobalDispatcher(agent)
const response = await fetch('https://api.example.com/users')
const users = await response.json()
await agent.close()
```
Constructing a `SnapshotAgent` emits an `ExperimentalWarning` once per process.
## Class: `SnapshotAgent`
<!-- YAML
added: v7.13.0
-->
* Extends: {MockAgent}
The captured interactions are managed by an internal `SnapshotRecorder`, which
is accessible through [`agent.getRecorder()`][]. Because `SnapshotAgent` extends
[`MockAgent`][], all `MockAgent` and [`Dispatcher`][] methods and events are also
available.
### `new SnapshotAgent([options])`
<!-- YAML
added: v7.13.0
-->
* `options` {Object} (optional) Accepts all [`MockAgent`][] options plus the
following snapshot-specific options.
* `mode` {string} The snapshot mode. One of `'record'`, `'playback'`, or
`'update'`. **Default:** `'record'`.
* `snapshotPath` {string} Path to the snapshot file used for loading and
saving. Required when `mode` is `'playback'` or `'update'`. **Default:**
`null`.
* `maxSnapshots` {number} Maximum number of snapshots to keep in memory.
**Default:** `Infinity`.
* `autoFlush` {boolean} When `true`, snapshots are written to `snapshotPath`
automatically as they are recorded. **Default:** `false`.
* `flushInterval` {number} Interval, in milliseconds, between automatic flushes
when `autoFlush` is enabled. **Default:** `30000`.
* `matchHeaders` {string[]} Names of the only headers to include when matching
a request against a snapshot. When omitted, all headers are matched.
* `ignoreHeaders` {string[]} Header names to ignore when matching a request.
* `excludeHeaders` {string[]} Header names to strip from snapshots entirely,
so that sensitive values are never written to disk.
* `matchBody` {boolean} When `true`, the request body is included in request
matching. **Default:** `true`.
* `normalizeBody` {Function} Normalizes the request body before it is matched
or stored, for example to strip volatile fields such as timestamps. Only
applied when `matchBody` is `true`.
* `body` {string|Buffer|null|undefined} The raw request body.
* Returns: {string} The normalized body used for matching.
* `matchQuery` {boolean} When `true`, query parameters are included in request
matching. **Default:** `true`.
* `normalizeQuery` {Function} Normalizes the query string before it is matched,
for example to strip cache-busting parameters. Only applied when `matchQuery`
is `true`.
* `query` {URLSearchParams} The parsed query parameters.
* Returns: {string} The normalized query string used for matching.
* `caseSensitive` {boolean} When `true`, header matching is case-sensitive.
**Default:** `false`.
* `shouldRecord` {Function} Decides whether a given request is recorded. Only
used in `'record'` and `'update'` modes.
* `requestOpts` {Object} The dispatch options of the request.
* Returns: {boolean} `true` to record the request.
* `shouldPlayback` {Function} Decides whether a given request is served from a
snapshot. Only used in `'playback'` and `'update'` modes.
* `requestOpts` {Object} The dispatch options of the request.
* Returns: {boolean} `true` to play the request back from a snapshot.
* `excludeUrls` {Array<string|RegExp>} URL patterns that are excluded from
recording and playback. String patterns match case-insensitively as
substrings of the URL; `RegExp` patterns are tested against the URL. Matching
requests are passed through to a real [`Agent`][] instead.
Creates a new `SnapshotAgent`. Throws an [`InvalidArgumentError`][] when `mode`
is `'playback'` or `'update'` and `snapshotPath` is not provided, and throws an
`InvalidArgumentError` when `mode` is not one of the supported values.
When `mode` is `'playback'` or `'update'` and `snapshotPath` is set, snapshots
are loaded from the file automatically; a missing file is ignored until the first
request requires it.
```mjs
import { SnapshotAgent, setGlobalDispatcher } from 'undici'
const agent = new SnapshotAgent({
mode: 'playback',
snapshotPath: './snapshots/api.json'
})
setGlobalDispatcher(agent)
```
The mode controls how requests are handled:
* `'record'` performs the real request and stores the response.
```mjs
import { SnapshotAgent, setGlobalDispatcher, fetch } from 'undici'
const agent = new SnapshotAgent({
mode: 'record',
snapshotPath: './snapshots/api.json'
})
setGlobalDispatcher(agent)
await fetch('https://api.example.com/users')
await agent.saveSnapshots()
```
* `'playback'` serves the recorded response without any network access. A
request with no matching snapshot rejects with an [`UndiciError`][] whose
message begins with `No snapshot found`.
```mjs
import { SnapshotAgent, setGlobalDispatcher, fetch } from 'undici'
const agent = new SnapshotAgent({
mode: 'playback',
snapshotPath: './snapshots/api.json'
})
setGlobalDispatcher(agent)
const response = await fetch('https://api.example.com/users')
```
* `'update'` replays an existing snapshot when one is found and otherwise records
the request like `'record'` mode.
```mjs
import { SnapshotAgent, setGlobalDispatcher, fetch } from 'undici'
const agent = new SnapshotAgent({
mode: 'update',
snapshotPath: './snapshots/api.json'
})
setGlobalDispatcher(agent)
await fetch('https://api.example.com/new-endpoint')
```
### `agent.loadSnapshots([filePath])`
<!-- YAML
added: v7.13.0
-->
* `filePath` {string} (optional) Path to read snapshots from. **Default:** the
`snapshotPath` given to the constructor.
* Returns: {Promise<void>} Resolves when the snapshots have been loaded.
Loads snapshots from disk into memory. In `'playback'` mode this also installs
the corresponding [`MockAgent`][] interceptors so that subsequent requests are
matched against the loaded snapshots.
```mjs
await agent.loadSnapshots('./snapshots/api.json')
```
### `agent.saveSnapshots([filePath])`
<!-- YAML
added: v7.13.0
-->
* `filePath` {string} (optional) Path to write snapshots to. **Default:** the
`snapshotPath` given to the constructor.
* Returns: {Promise<void>} Resolves when the snapshots have been written.
Writes all recorded snapshots to disk.
```mjs
await agent.saveSnapshots('./snapshots/api.json')
```
### `agent.getRecorder()`
<!-- YAML
added: v7.13.0
-->
* Returns: {SnapshotRecorder} The internal recorder that stores the captured
interactions.
Returns the underlying `SnapshotRecorder`. The recorder exposes lower-level
operations over the captured data, including `record()`, `findSnapshot()`,
`getSnapshots()`, `size()`, and `clear()`. The recorder is an internal type
returned for inspection; it is not exported from the package root.
```mjs
const recorder = agent.getRecorder()
console.log(`Recorded ${recorder.size()} interactions`)
```
### `agent.getMode()`
<!-- YAML
added: v7.13.0
-->
* Returns: {string} The current mode: `'record'`, `'playback'`, or `'update'`.
Returns the mode the agent was constructed with.
### `agent.clearSnapshots()`
<!-- YAML
added: v7.13.0
-->
* Returns: {undefined}
Removes all snapshots from memory.
```mjs
agent.clearSnapshots()
```
### `agent.resetCallCounts()`
<!-- YAML
added: v7.13.0
-->
* Returns: {undefined}
Resets the call count of every snapshot to zero. Useful between tests when the
same agent is reused, since matching a snapshot in `'playback'` mode increments
its call count.
```mjs
agent.resetCallCounts()
```
### `agent.deleteSnapshot(requestOpts)`
<!-- YAML
added: v7.13.0
-->
* `requestOpts` {Object} Dispatch options identifying the snapshot to remove.
* Returns: {boolean} `true` if a matching snapshot was deleted, `false` if none
was found.
Deletes a single snapshot that matches the given request options.
```mjs
const deleted = agent.deleteSnapshot({
method: 'GET',
origin: 'https://api.example.com',
path: '/users'
})
```
### `agent.getSnapshotInfo(requestOpts)`
<!-- YAML
added: v7.13.0
-->
* `requestOpts` {Object} Dispatch options identifying the snapshot to inspect.
* Returns: {Object|null} Information about the matching snapshot, or `null` when
none is found.
* `hash` {string} The hash used to key the snapshot.
* `request` {Object} The recorded request.
* `method` {string} The request method.
* `url` {string} The request URL.
* `headers` {Record<string, string>} The recorded request headers.
* `body` {string} The recorded request body, when present.
* `responseCount` {number} The number of recorded responses for the request.
* `callCount` {number} The number of times the snapshot has been matched.
* `timestamp` {string} The ISO timestamp at which the snapshot was recorded.
Returns metadata about a snapshot without returning the response payload.
```mjs
const info = agent.getSnapshotInfo({
method: 'GET',
origin: 'https://api.example.com',
path: '/users'
})
```
### `agent.replaceSnapshots(snapshotData)`
<!-- YAML
added: v7.13.0
-->
* `snapshotData` {Array} The snapshot data to load, replacing any existing
snapshots.
* `hash` {string} The hash used to key the snapshot.
* `snapshot` {Object} The snapshot entry.
* Returns: {undefined}
Replaces all in-memory snapshots with the provided data.
```mjs
const recorder = agent.getRecorder()
const snapshots = recorder.getSnapshots()
agent.replaceSnapshots(snapshots.map((snapshot, index) => ({
hash: `snapshot-${index}`,
snapshot
})))
```
### `agent.close()`
<!-- YAML
added: v7.13.0
-->
* Returns: {Promise<void>} Resolves once the agent and its resources are closed.
Closes the agent and releases its resources. In `'record'` and `'update'` modes
the recorder is flushed to disk first. In `'playback'` mode nothing is written,
because matching a snapshot mutates its call count and saving would needlessly
rewrite the snapshot file. The real [`Agent`][], when one was created, and the
underlying [`MockAgent`][] are closed as well.
```mjs
await agent.close()
```
[`Agent`]: Agent.md#class-agent
[`Dispatcher`]: Dispatcher.md#class-dispatcher
[`InvalidArgumentError`]: Errors.md#undicierrorsundiciinvalidargumenterror
[`MockAgent`]: MockAgent.md#class-mockagent
[`UndiciError`]: Errors.md#undicierrorsundicierror
[`agent.getRecorder()`]: #agentgetrecorder
[`setGlobalDispatcher()`]: Dispatcher.md#setglobaldispatcherdispatcher
node_modules/undici/docs/docs/api/Socks5ProxyAgent.md
Generated Vendored
+256
View File
@@ -0,0 +1,256 @@
# Socks5ProxyAgent
<!--introduced_in=v7.23.0-->
<!--type=module-->
<!-- source_link=lib/dispatcher/socks5-proxy-agent.js -->
> Stability: 1 - Experimental
A [`Dispatcher`][] implementation that routes requests through a [SOCKS5][]
proxy server. It tunnels both HTTP and HTTPS traffic over the proxy, supports
optional username/password authentication, and pools connections per origin so
that subsequent requests to the same host reuse the established tunnel.
DNS resolution is delegated to the proxy: target host names are sent to the
proxy as domain names rather than being resolved locally. For HTTPS targets the
TLS session is negotiated end-to-end through the tunnel, so the proxy only sees
encrypted bytes.
Import it from `'undici'`:
```mjs
import { Socks5ProxyAgent } from 'undici'
```
Constructing the agent emits a one-time `ExperimentalWarning`, reflecting the
experimental status of SOCKS5 support.
## Class: `Socks5ProxyAgent`
<!-- YAML
added: v7.23.0
-->
> Stability: 1 - Experimental
* Extends: {Dispatcher}
Routes dispatched requests through a SOCKS5 proxy. Register an instance as the
global dispatcher with [`setGlobalDispatcher()`][], or pass it per request via
the `dispatcher` option.
### `new Socks5ProxyAgent(proxyUrl[, options])`
<!-- YAML
added: v7.23.0
-->
> Stability: 1 - Experimental
* `proxyUrl` {string|URL} The SOCKS5 proxy server URL. Must use the `socks5:` or
`socks:` protocol. Credentials may be embedded in the URL userinfo (for
example `socks5://user:pass@host:1080`).
* `options` {Object} (optional) Extends {PoolOptions}; the pool options are
applied to the per-origin pools created behind the tunnel.
* `headers` {Object} Additional headers to send with the proxy connection.
**Default:** `{}`.
* `username` {string} Username for SOCKS5 authentication. Takes precedence over
a username embedded in `proxyUrl`. **Default:** the URL username, if any.
* `password` {string} Password for SOCKS5 authentication. Takes precedence over
a password embedded in `proxyUrl`. **Default:** the URL password, if any.
* `connect` {Function} Custom connector used to open the socket to the proxy.
**Default:** a connector built from `proxyTls`.
* `connectTimeout` {number} Maximum time in milliseconds for each proxy
connection, SOCKS5 negotiation, and target TLS negotiation stage. A value of
`0` disables these stage timeouts. `proxyTls.timeout` and
`requestTls.timeout` override it for their respective TLS stages.
**Default:** `5000`.
* `proxyTls` {BuildOptions} TLS options for the connection to the proxy itself
(SOCKS5 over TLS). When set, the proxy connection is established over TLS and
`servername` defaults to the proxy host name.
* `requestTls` {BuildOptions} TLS options applied to the end-to-end connection
to an HTTPS target through the tunnel, such as `ca`, `cert`, `key`,
`rejectUnauthorized`, and `servername`. `servername` defaults to the target
host name.
Throws an `InvalidArgumentError` if `proxyUrl` is missing or does not use the
`socks5:` or `socks:` protocol, or if `connectTimeout`, `proxyTls.timeout`, or
`requestTls.timeout` is not a finite, non-negative number.
```mjs
import { Socks5ProxyAgent } from 'undici'
// Without authentication.
const agent = new Socks5ProxyAgent('socks5://localhost:1080')
// With credentials in the URL.
const authAgent = new Socks5ProxyAgent('socks5://user:pass@localhost:1080')
// With credentials and pool options.
const configuredAgent = new Socks5ProxyAgent('socks5://localhost:1080', {
username: 'user',
password: 'pass',
connections: 10
})
```
Using the agent as the global dispatcher:
```mjs
import { setGlobalDispatcher, request, Socks5ProxyAgent } from 'undici'
const agent = new Socks5ProxyAgent('socks5://localhost:1080')
setGlobalDispatcher(agent)
const { statusCode, body } = await request('http://localhost:3000/foo')
console.log('response received', statusCode)
for await (const data of body) {
console.log('data', data.toString('utf8'))
}
```
Using the agent per request:
```mjs
import { request, Socks5ProxyAgent } from 'undici'
const agent = new Socks5ProxyAgent('socks5://localhost:1080')
const { statusCode, body } = await request('http://localhost:3000/foo', {
dispatcher: agent
})
console.log('response received', statusCode)
```
HTTPS targets are tunnelled and encrypted end-to-end:
```mjs
import { request, Socks5ProxyAgent } from 'undici'
const agent = new Socks5ProxyAgent('socks5://localhost:1080')
const { statusCode, body } = await request('https://api.example.com/data', {
dispatcher: agent
})
console.log('Response status:', statusCode)
console.log('Response data:', await body.json())
```
### `socks5ProxyAgent.close()`
<!-- YAML
added: v7.23.0
-->
> Stability: 1 - Experimental
* Returns: {Promise<void>} Resolves once every per-origin pool has been closed.
Gracefully closes the agent, waiting for all underlying pools and their
connections to drain and close before resolving.
```mjs
import { setGlobalDispatcher, Socks5ProxyAgent } from 'undici'
const agent = new Socks5ProxyAgent('socks5://localhost:1080')
setGlobalDispatcher(agent)
// ... make requests ...
await agent.close()
```
### `socks5ProxyAgent.destroy([err])`
<!-- YAML
added: v7.23.0
-->
> Stability: 1 - Experimental
* `err` {Error} (optional) The error to reject in-flight requests with.
* Returns: {Promise<void>} Resolves once every per-origin pool has been
destroyed.
Forcibly destroys the agent and all underlying connections immediately, without
waiting for in-flight requests to complete.
```mjs
import { Socks5ProxyAgent } from 'undici'
const agent = new Socks5ProxyAgent('socks5://localhost:1080')
await agent.destroy()
```
### `socks5ProxyAgent.dispatch(options, handlers)`
<!-- YAML
added: v7.23.0
-->
> Stability: 1 - Experimental
* `options` {DispatchOptions}
* `handlers` {DispatchHandler}
* Returns: {boolean} `false` if the dispatcher is busy and the request should be
retried later, otherwise `true`.
Routes a request through the SOCKS5 tunnel. The agent maintains a [`Pool`][] per
target origin; the first request to a given origin establishes the tunnel and
upgrades to TLS when the target is HTTPS, and later requests reuse the pool.
This is the lower-level entry point implementing
[`Dispatcher.dispatch(options, handlers)`][]. Prefer
[`socks5ProxyAgent.request()`][] for most use cases.
### `socks5ProxyAgent.request(options[, callback])`
<!-- YAML
added: v7.23.0
-->
> Stability: 1 - Experimental
* `options` {DispatchOptions}
* `callback` {Function} (optional)
* Returns: {Promise|void} A promise resolving to the response when `callback` is
omitted.
Performs a request through the SOCKS5 proxy. Inherited from
[`Dispatcher.request(options[, callback])`][]; see that method for the full set
of options and the shape of the resolved response.
```mjs
import { fetch, Socks5ProxyAgent } from 'undici'
const agent = new Socks5ProxyAgent('socks5://localhost:1080')
const response = await fetch('http://localhost:3000/api/users', {
dispatcher: agent
})
console.log('Response status:', response.status)
console.log('Response data:', await response.text())
```
## Debugging
SOCKS5 proxy activity can be traced with the `undici:socks5-proxy` debug scope:
```bash
NODE_DEBUG=undici:socks5-proxy node script.js
```
This logs the SOCKS5 handshake, authentication, and tunnel establishment steps.
[SOCKS5]: https://www.rfc-editor.org/rfc/rfc1928
[`Dispatcher.dispatch(options, handlers)`]: Dispatcher.md#dispatcherdispatchoptions-handler
[`Dispatcher.request(options[, callback])`]: Dispatcher.md#dispatcherrequestoptions-callback
[`Dispatcher`]: Dispatcher.md#class-dispatcher
[`Pool`]: Pool.md#class-pool
[`setGlobalDispatcher()`]: Dispatcher.md#setglobaldispatcherdispatcher
[`socks5ProxyAgent.request()`]: #socks5proxyagentrequestoptions-callback
node_modules/undici/docs/docs/api/Util.md
Generated Vendored
+82
View File
@@ -0,0 +1,82 @@
# Util
<!--introduced_in=v1.2.0-->
<!--type=module-->
<!-- source_link=lib/core/util.js -->
> Stability: 2 - Stable
A small set of utility helpers exposed for third-party implementations of the
[`Dispatcher`][] API. They cover the header-handling primitives undici uses
internally, so that custom dispatchers and handlers can normalize header names
and parse raw header lists exactly the way undici does.
```mjs
import { util } from 'undici'
const { parseHeaders, headerNameToString } = util
```
```cjs
const { util } = require('undici')
const { parseHeaders, headerNameToString } = util
```
## `parseHeaders(headers[, obj])`
<!-- YAML
added: v1.2.0
changes:
- version: v6.1.0
pr-url: https://github.com/nodejs/undici/pull/2501
description: Header names supplied as a `Buffer` are accepted and normalized.
-->
* `headers` {Array} A flat list of raw header entries where even indices are
header names and odd indices are the corresponding values. Each entry is a
{string}, {Buffer}, or an array of {string}/{Buffer}.
* `obj` {Record<string, string|string[]>} An object to assign the parsed values
to. When omitted, a new object is created. **Default:** `{}`.
* Returns: {Record<string, string|string[]>} The object the parsed headers were
assigned to. When `obj` is provided, the same reference is returned.
Receives a flat list of raw header name/value pairs and returns them as an
object keyed by lowercased header name. Header names are normalized with
[`headerNameToString()`][], and `Buffer` values are decoded as `latin1`. When a
header name appears more than once, its values are collected into an array.
```mjs
import { util } from 'undici'
const raw = ['Content-Type', 'text/plain', 'Set-Cookie', 'a=1', 'Set-Cookie', 'b=2']
console.log(util.parseHeaders(raw))
// { 'content-type': 'text/plain', 'set-cookie': [ 'a=1', 'b=2' ] }
```
## `headerNameToString(value)`
<!-- YAML
added: v6.1.0
-->
* `value` {string|Buffer} The header name to normalize.
* Returns: {string} The lowercased header name.
Returns the lowercased form of a header name. The `value` may be provided as a
{string} or as a {Buffer}, in which case it is decoded as `latin1`. Common
header names are resolved through an internal lookup table for performance.
```mjs
import { util } from 'undici'
console.log(util.headerNameToString('Content-Type'))
// 'content-type'
console.log(util.headerNameToString(Buffer.from('X-Custom-Header')))
// 'x-custom-header'
```
[`Dispatcher`]: Dispatcher.md#class-dispatcher
[`headerNameToString()`]: #headernametostringvalue
node_modules/undici/docs/docs/api/WebSocket.md
Generated Vendored
+536
View File
@@ -0,0 +1,536 @@
# WebSocket
<!--introduced_in=v5.15.0-->
<!--type=module-->
<!-- source_link=lib/web/websocket/websocket.js -->
> Stability: 2 - Stable
The `WebSocket` API provides a way to manage a WebSocket connection to a
server, allowing bidirectional communication. It follows the
[WHATWG WebSocket specification][] and [RFC 6455][], and is intended to be
interchangeable with the global `WebSocket` available in browsers.
```mjs
import { WebSocket } from 'undici'
const ws = new WebSocket('wss://echo.websocket.events')
ws.addEventListener('open', () => {
ws.send('Hello, world!')
})
ws.addEventListener('message', (event) => {
console.log('received:', event.data)
})
```
In addition to the standard `WebSocket` interface, this module exports the
streams-based [`WebSocketStream`][] and [`WebSocketError`][] APIs, as well as a
[`ping()`][] helper for sending ping frames.
## Class: `WebSocket`
<!-- YAML
added: v5.15.0
-->
* Extends: {EventTarget}
The `WebSocket` object represents a single WebSocket connection. Constructing a
`WebSocket` immediately begins the opening handshake; the connection cannot be
reused once it has been closed.
### `new WebSocket(url[, protocols])`
<!-- YAML
added: v5.15.0
-->
* `url` {URL|string} The URL of the server to connect to. Must use the `ws:`
or `wss:` scheme.
* `protocols` {string|string[]|WebSocketInit} A single subprotocol, a list of
subprotocols to negotiate with the server, or a `WebSocketInit` object.
**Default:** `[]`.
* `protocols` {string|string[]} Subprotocol(s) to request the server use.
**Default:** `[]`.
* `dispatcher` {Dispatcher} The dispatcher used to open the connection.
**Default:** the global dispatcher.
* `headers` {HeadersInit|null} Additional headers to send with the handshake
request. (optional)
Creates a new `WebSocket` and begins connecting to `url`. The second argument
may be a string or array of subprotocols, or a `WebSocketInit` object. The
object form is an undici extension and is not available in browsers; it allows a
custom `dispatcher` and additional `headers` to be supplied.
If a value in `protocols` is repeated or is not a valid subprotocol name, the
constructor throws a `SyntaxError` `DOMException`.
```mjs
import { WebSocket } from 'undici'
const ws = new WebSocket('wss://echo.websocket.events', ['echo', 'chat'])
```
To route the connection through a custom dispatcher, such as a
[`ProxyAgent`][], pass a `WebSocketInit` object:
```mjs
import { WebSocket, ProxyAgent } from 'undici'
const dispatcher = new ProxyAgent('http://localhost:8080')
const ws = new WebSocket('wss://echo.websocket.events', {
dispatcher,
protocols: ['echo', 'chat']
})
```
WebSocket over HTTP/2 is experimental and may change in the future. It can be
enabled by passing a dispatcher configured with `allowH2`:
```mjs
import { WebSocket, Agent } from 'undici'
const dispatcher = new Agent({ allowH2: true })
const ws = new WebSocket('wss://echo.websocket.events', {
dispatcher,
protocols: ['echo', 'chat']
})
```
### `websocket.close([code[, reason]])`
<!-- YAML
added: v5.15.0
-->
* `code` {number} The status code explaining why the connection is being
closed. **Default:** `null`.
* `reason` {string} A human-readable string explaining why the connection is
being closed. **Default:** `''`.
Starts the closing handshake. The `code` is clamped to an unsigned 16-bit
integer; when omitted, no status code is sent. The `reason` is encoded as
UTF-8 and must not exceed 123 bytes.
```mjs
ws.close(1000, 'Done')
```
### `websocket.send(data)`
<!-- YAML
added: v5.15.0
-->
* `data` {string|ArrayBuffer|TypedArray|DataView|Blob} The data to enqueue for
transmission.
Enqueues `data` to be transmitted to the server. String data is sent as a text
frame; `ArrayBuffer`, any `TypedArray`, `DataView`, and `Blob` values are sent
as binary frames. The number of bytes queued is added to
[`websocket.bufferedAmount`][].
If [`websocket.readyState`][] is `CONNECTING`, an `InvalidStateError`
`DOMException` is thrown. If the connection is closing or already closed, the
call is silently ignored.
```mjs
ws.send('a text message')
ws.send(new Uint8Array([1, 2, 3]))
```
### `websocket.readyState`
<!-- YAML
added: v5.15.0
-->
* Type: {number}
The current state of the connection. One of the numeric constants
`WebSocket.CONNECTING` (`0`), `WebSocket.OPEN` (`1`),
`WebSocket.CLOSING` (`2`), or `WebSocket.CLOSED` (`3`). This property is
read-only.
### `websocket.bufferedAmount`
<!-- YAML
added: v5.15.0
-->
* Type: {number}
The number of bytes of data that have been queued using
[`websocket.send()`][] but not yet transmitted to the network. This value
resets to `0` once all queued data is sent. This property is read-only.
### `websocket.url`
<!-- YAML
added: v5.15.0
-->
* Type: {string}
The absolute URL of the WebSocket as resolved during construction. This
property is read-only.
### `websocket.extensions`
<!-- YAML
added: v5.15.0
-->
* Type: {string}
The extensions negotiated by the server, taken from the
`Sec-WebSocket-Extensions` response header. Empty until the connection is
established. This property is read-only.
### `websocket.protocol`
<!-- YAML
added: v5.15.0
-->
* Type: {string}
The subprotocol selected by the server, taken from the
`Sec-WebSocket-Protocol` response header. Empty until the connection is
established and only set when a subprotocol was negotiated. This property is
read-only.
### `websocket.binaryType`
<!-- YAML
added: v5.15.0
-->
* Type: {string} **Default:** `'blob'`.
Controls the type used to represent binary data delivered by the
[`'message'`][] event. Must be either `'blob'` (binary frames are exposed as a
`Blob`) or `'arraybuffer'` (binary frames are exposed as an `ArrayBuffer`).
Assigning any other value resets it to `'blob'`.
### `websocket.onopen`
<!-- YAML
added: v5.15.0
-->
* Type: {Function|null} **Default:** `null`.
An event handler for the [`'open'`][] event. Setting this property replaces any
previously registered `onopen` handler.
### `websocket.onerror`
<!-- YAML
added: v5.15.0
-->
* Type: {Function|null} **Default:** `null`.
An event handler for the [`'error'`][] event. Setting this property replaces any
previously registered `onerror` handler.
### `websocket.onclose`
<!-- YAML
added: v5.15.0
-->
* Type: {Function|null} **Default:** `null`.
An event handler for the [`'close'`][] event. Setting this property replaces any
previously registered `onclose` handler.
### `websocket.onmessage`
<!-- YAML
added: v5.15.0
-->
* Type: {Function|null} **Default:** `null`.
An event handler for the [`'message'`][] event. Setting this property replaces
any previously registered `onmessage` handler.
### Event: `'open'`
<!-- YAML
added: v5.21.0
-->
Emitted when the WebSocket connection is established. After this event,
[`websocket.readyState`][] is `OPEN` and data may be sent with
[`websocket.send()`][]. The listener receives an `Event`.
### Event: `'message'`
<!-- YAML
added: v7.0.0
-->
Emitted when a message is received from the server. The listener receives a
`MessageEvent` whose `data` property is a `string` for text frames, and either a
`Blob` or an `ArrayBuffer` for binary frames depending on
[`websocket.binaryType`][]. The event's `origin` is the origin of
[`websocket.url`][].
### Event: `'error'`
<!-- YAML
added: v7.0.0
-->
Emitted when the connection is terminated abnormally, for example when no close
frame was received before the underlying transport was lost. The listener
receives an `ErrorEvent`.
### Event: `'close'`
<!-- YAML
added: v7.0.0
-->
Emitted when the connection is closed. The listener receives a `CloseEvent`
whose `code` and `reason` describe why the connection closed, and whose
`wasClean` property is `true` only when the closing handshake completed in both
directions.
## `ping(websocket[, payload])`
<!-- YAML
added: v7.12.0
-->
* `websocket` {WebSocket} The WebSocket to send the ping frame on.
* `payload` {Buffer} Optional payload to include in the ping frame. Must not
exceed 125 bytes. **Default:** `undefined`.
Sends a ping control frame to the server. A conforming server replies with a
pong frame containing the same payload, which can be used to keep the connection
alive or to verify that it is still active.
The frame is only sent when the connection is open; if it is connecting,
closing, or closed, the call is a no-op. A `TypeError` is thrown if `payload`
is not a `Buffer` or is larger than 125 bytes.
```mjs
import { WebSocket, ping } from 'undici'
const ws = new WebSocket('wss://echo.websocket.events')
ws.addEventListener('open', () => {
ping(ws)
ping(ws, Buffer.from('hello'))
})
```
## Class: `WebSocketStream`
<!-- YAML
added: v7.0.0
-->
> Stability: 1 - Experimental
`WebSocketStream` is a streams-based alternative to the event-based
[`WebSocket`][] interface, exposing a connection as a pair of `ReadableStream`
and `WritableStream` objects. See [MDN][MDN WebSocketStream] for background.
Constructing a `WebSocketStream` for the first time emits an
`ExperimentalWarning` with the code `UNDICI-WSS`.
### `new WebSocketStream(url[, options])`
<!-- YAML
added: v7.0.0
-->
> Stability: 1 - Experimental
* `url` {URL|string} The URL of the server to connect to.
* `options` {WebSocketStreamOptions}
* `protocols` {string|string[]} Subprotocol(s) to request the server use.
**Default:** `[]`.
* `signal` {AbortSignal|null} An `AbortSignal` that aborts the opening
handshake and rejects [`webSocketStream.opened`][] and
[`webSocketStream.closed`][] when triggered. **Default:** `null`.
Creates a new `WebSocketStream` and begins connecting to `url`. As with
[`new WebSocket()`][], a repeated or invalid subprotocol causes a `SyntaxError`
`DOMException` to be thrown.
```mjs
import { WebSocketStream } from 'undici'
const stream = new WebSocketStream('wss://echo.websocket.events')
const { readable, writable } = await stream.opened
const writer = writable.getWriter()
await writer.write('Hello, world!')
writer.releaseLock()
const reader = readable.getReader()
const { value } = await reader.read()
console.log('received:', value)
```
### `webSocketStream.url`
<!-- YAML
added: v5.15.0
-->
> Stability: 1 - Experimental
* Type: {string}
The serialized URL of the WebSocket. This property is read-only.
### `webSocketStream.opened`
<!-- YAML
added: v5.15.0
-->
> Stability: 1 - Experimental
* Type: {Promise} Fulfills once the connection is established.
A promise that resolves with an object describing the open connection, or
rejects if the connection could not be established. The fulfillment value has
the following shape:
* `extensions` {string} The negotiated extensions.
* `protocol` {string} The negotiated subprotocol.
* `readable` {ReadableStream} A stream of incoming messages. Text frames are
delivered as strings and binary frames as `Uint8Array` chunks.
* `writable` {WritableStream} A stream for sending messages. Writing a string
sends a text frame; writing a `BufferSource` sends a binary frame.
### `webSocketStream.closed`
<!-- YAML
added: v5.15.0
-->
> Stability: 1 - Experimental
* Type: {Promise} Fulfills once the connection is closed cleanly.
A promise that resolves with a `WebSocketCloseInfo` object when the connection
closes cleanly, or rejects with a [`WebSocketError`][] when it closes
abnormally. The fulfillment value has the following shape:
* `closeCode` {number} The status code the connection was closed with.
* `reason` {string} The reason the connection was closed with.
### `webSocketStream.close([closeInfo])`
<!-- YAML
added: v5.15.0
-->
> Stability: 1 - Experimental
* `closeInfo` {Object}
* `closeCode` {number} The status code to close with.
* `reason` {string} The reason to close with. **Default:** `''`.
Starts the closing handshake. When `closeInfo` is omitted, the connection is
closed without a status code.
## Class: `WebSocketError`
<!-- YAML
added: v7.0.0
-->
> Stability: 1 - Experimental
* Extends: {DOMException}
An error type used by [`WebSocketStream`][] to report close information. It is
used to reject [`webSocketStream.closed`][] when the connection closes
abnormally, and may be passed to a stream's abort or cancel operations to close
the connection with a specific code and reason.
### `new WebSocketError([message[, init]])`
<!-- YAML
added: v7.0.0
-->
> Stability: 1 - Experimental
* `message` {string} A human-readable description of the error.
**Default:** `''`.
* `init` {Object}
* `closeCode` {number} The status code to associate with the error.
* `reason` {string} The reason to associate with the error.
**Default:** `''`.
Creates a new `WebSocketError`. If `reason` is non-empty but no `closeCode` is
given, `closeCode` defaults to `1000` ("Normal Closure"). The `closeCode` and
`reason` are validated, so an out-of-range code or an over-long reason throws.
### `webSocketError.closeCode`
<!-- YAML
added: v5.15.0
-->
> Stability: 1 - Experimental
* Type: {number|null}
The status code associated with the error, or `null` if none was set. This
property is read-only.
### `webSocketError.reason`
<!-- YAML
added: v5.15.0
-->
> Stability: 1 - Experimental
* Type: {string}
The reason associated with the error. This property is read-only.
## Read more
* [MDN: WebSocket][]
* [RFC 6455][]
* [WHATWG WebSocket specification][]
[MDN WebSocketStream]: https://developer.mozilla.org/docs/Web/API/WebSocketStream
[MDN: WebSocket]: https://developer.mozilla.org/docs/Web/API/WebSocket
[RFC 6455]: https://www.rfc-editor.org/rfc/rfc6455
[WHATWG WebSocket specification]: https://websockets.spec.whatwg.org/
[`'close'`]: #event-close
[`'error'`]: #event-error
[`'message'`]: #event-message
[`'open'`]: #event-open
[`ProxyAgent`]: ProxyAgent.md#class-proxyagent
[`WebSocket`]: #class-websocket
[`WebSocketError`]: #class-websocketerror
[`WebSocketStream`]: #class-websocketstream
[`new WebSocket()`]: #new-websocketurl-protocols
[`ping()`]: #pingwebsocket-payload
[`webSocketStream.closed`]: #websocketstreamclosed
[`webSocketStream.opened`]: #websocketstreamopened
[`websocket.bufferedAmount`]: #websocketbufferedamount
[`websocket.binaryType`]: #websocketbinarytype
[`websocket.readyState`]: #websocketreadystate
[`websocket.send()`]: #websocketsenddata
[`websocket.url`]: #websocketurl
node_modules/undici/docs/docs/api/api-lifecycle.md
Generated Vendored
+159
View File
@@ -0,0 +1,159 @@
# Client Lifecycle
<!--type=misc-->
A {Client} can be understood as a state machine. As requests are dispatched,
processed, and drained, the client moves through a well-defined set of states
until it is eventually destroyed. This document describes those states and the
transitions between them.
The {Client} class is not literally implemented as a state machine, so the
actual execution may deviate slightly from what is described here. Treat this
guide as a conceptual model for reasoning about a client's behavior rather than
as a formal specification.
## State transition overview
* A {Client} begins in the **idle** state with no socket connection and no
queued requests.
* The *connect* transition moves the {Client} to the **pending** state, where
requests can be queued before they are processed.
* Calling [`client.close()`][] or [`client.destroy()`][] moves the {Client}
to the **destroyed** state. Because there are no queued requests in this
state, *close* transitions straight to **destroyed**.
* The **pending** state indicates that the underlying socket connection has been
established and that requests are queueing.
* The *process* transition moves the {Client} to the **processing** state,
where requests are processed.
* If requests are queued, *close* transitions to **processing**; otherwise it
transitions to **destroyed**.
* The *destroy* transition moves the {Client} to **destroyed**.
* The **processing** state initializes to the **processing.running** sub-state.
* If the current request body requires draining, *needDrain* moves the
{Client} into the **processing.busy** sub-state, which returns to
**processing.running** once *drainComplete* fires.
* After all queued requests complete, *keepalive* moves the {Client} back to
the **pending** state. If no requests are queued before the socket times
out, the {Client} transitions to **idle**.
* If *close* is fired while the {Client} still has queued requests, the
{Client} transitions to **processing.closing**, where it completes all
outstanding requests before firing *done*.
* The *done* transition moves the {Client} gracefully to **destroyed**.
* At any time, *destroy* moves the {Client} from **processing** to
**destroyed**, aborting any queued requests.
* The **destroyed** state is final; the {Client} is no longer functional.
A state diagram representing a {Client} instance:
```mermaid
stateDiagram-v2
[*] --> idle
idle --> pending : connect
idle --> destroyed : destroy/close
pending --> idle : timeout
pending --> destroyed : destroy
state close_fork <<fork>>
pending --> close_fork : close
close_fork --> processing
close_fork --> destroyed
pending --> processing : process
processing --> pending : keepalive
processing --> destroyed : done
processing --> destroyed : destroy
destroyed --> [*]
state processing {
[*] --> running
running --> closing : close
running --> busy : needDrain
busy --> running : drainComplete
running --> [*] : keepalive
closing --> [*] : done
}
```
## State details
### idle
**idle** is the initial state of a {Client} instance. Although an `origin` is
required to construct a {Client}, the underlying socket connection is not
established until a request is queued through [`client.dispatch()`][]. Calling
`client.dispatch()` directly, or through one of its higher-level wrappers
([`client.connect()`][], [`client.pipeline()`][], [`client.request()`][],
[`client.stream()`][], or [`client.upgrade()`][]), moves the {Client} from
**idle** to **pending**, and then usually directly on to **processing**.
Calling [`client.close()`][] or [`client.destroy()`][] in this state moves the
{Client} straight to **destroyed**, since there are no queued requests.
### pending
**pending** signifies a connected but non-processing {Client}. On entering this
state, the {Client} establishes a socket connection and emits the
[`'connect'`][] event, signalling that a connection to the `origin` supplied at
construction time has been established. The internal queue starts empty, and
requests can begin queueing.
Calling [`client.close()`][] with queued requests moves the {Client} to the
**processing** state; without queued requests it moves to **destroyed**.
Calling [`client.destroy()`][] moves the {Client} directly to **destroyed**,
regardless of any queued requests.
### processing
**processing** is itself a sub-state machine that initializes to the
**processing.running** sub-state. [`client.dispatch()`][], [`client.close()`][],
and [`client.destroy()`][] can all be called while the {Client} is in this
state. `client.dispatch()` queues additional requests while existing ones
continue to be processed, `client.close()` moves the {Client} to the
**processing.closing** sub-state, and `client.destroy()` moves it to
**destroyed**.
#### running
In **processing.running**, queued requests are processed in FIFO order. If a
request body requires draining, *needDrain* moves the {Client} to the
**processing.busy** sub-state. The *close* transition moves the {Client} to the
**processing.closing** sub-state. When all queued requests have completed and
neither [`client.close()`][] nor [`client.destroy()`][] has been called, the
*keepalive* transition moves the {Client} back to the **pending** state. There
the {Client} waits for the socket connection to time out; once it does, the
{Client} returns to the **idle** state.
#### busy
This sub-state is entered only when a request body is a {stream.Readable} that
requires draining. The {Client} cannot process additional requests while in
this state and waits until the current request body has been fully drained
before returning to **processing.running**.
#### closing
This sub-state is entered only when a {Client} has queued requests and
[`client.close()`][] is called. The {Client} continues to process requests as
usual, except that no additional requests may be queued. Once all queued
requests have been processed, *done* fires and the {Client} moves gracefully to
**destroyed** without an error.
### destroyed
**destroyed** is the final state of a {Client} instance. Once in this state, the
{Client} is no longer functional, and calling any further {Client} method
rejects or fails with a {ClientDestroyedError}.
[`'connect'`]: Client.md#event-connect
[`client.close()`]: Client.md#clientclosecallback
[`client.connect()`]: Client.md#clientconnectoptions-callback
[`client.destroy()`]: Client.md#clientdestroyerror-callback
[`client.dispatch()`]: Client.md#clientdispatchoptions-handlers
[`client.pipeline()`]: Client.md#clientpipelineoptions-handler
[`client.request()`]: Client.md#clientrequestoptions-callback
[`client.stream()`]: Client.md#clientstreamoptions-factory-callback
[`client.upgrade()`]: Client.md#clientupgradeoptions-callback
node_modules/undici/docs/docs/best-practices/client-certificate.md
Generated Vendored
+66
View File
@@ -0,0 +1,66 @@
# Client certificate
<!--type=misc-->
Client certificate authentication can be configured with the `Client`, the required options are passed along through the `connect` option.
The client certificates must be signed by a trusted CA. The Node.js default is to trust the well-known CAs curated by Mozilla.
Setting the server option `requestCert: true` tells the server to request the client certificate.
The server option `rejectUnauthorized: false` allows us to handle any invalid certificate errors in client code. The `authorized` property on the socket of the incoming request will show if the client certificate was valid. The `authorizationError` property will give the reason if the certificate was not valid.
### Client Certificate Authentication
```js
const { readFileSync } = require('node:fs')
const { join } = require('node:path')
const { createServer } = require('node:https')
const { Client } = require('undici')
const serverOptions = {
ca: [
readFileSync(join(__dirname, 'client-ca-crt.pem'), 'utf8')
],
key: readFileSync(join(__dirname, 'server-key.pem'), 'utf8'),
cert: readFileSync(join(__dirname, 'server-crt.pem'), 'utf8'),
requestCert: true,
rejectUnauthorized: false
}
const server = createServer(serverOptions, (req, res) => {
// true if client cert is valid
if(req.client.authorized === true) {
console.log('valid')
} else {
console.error(req.client.authorizationError)
}
res.end()
})
server.listen(0, function () {
const tls = {
ca: [
readFileSync(join(__dirname, 'server-ca-crt.pem'), 'utf8')
],
key: readFileSync(join(__dirname, 'client-key.pem'), 'utf8'),
cert: readFileSync(join(__dirname, 'client-crt.pem'), 'utf8'),
rejectUnauthorized: false,
servername: 'agent1'
}
const client = new Client(`https://localhost:${server.address().port}`, {
connect: tls
})
client.request({
path: '/',
method: 'GET'
}, (err, { body }) => {
body.on('data', (buf) => {})
body.on('end', () => {
client.close()
server.close()
})
})
})
```
node_modules/undici/docs/docs/best-practices/crawling.md
Generated Vendored
+60
View File
@@ -0,0 +1,60 @@
# Crawling
<!--type=misc-->
[RFC 9309](https://datatracker.ietf.org/doc/html/rfc9309) defines crawlers as automated clients.
Some web servers may reject requests that omit the `User-Agent` header or that use common defaults such as `'curl/7.79.1'`.
In **undici**, the default user agent is `'undici'`. Since undici is integrated into Node.js core as the implementation of `fetch()`, requests made via `fetch()` use `'node'` as the default user agent.
It is recommended to specify a **custom `User-Agent` header** when implementing crawlers. Providing a descriptive user agent allows servers to correctly identify the client and reduces the likelihood of requests being denied.
A user agent string should include sufficient detail to identify the crawler and provide contact information. For example:
```text
AcmeCo Crawler - acme.co - contact@acme.co
```
When adding contact details, avoid using personal identifiers such as your own name or a private email address—especially in a professional or employment context. Instead, use a role-based or organizational contact (e.g., crawler-team@company.com) to protect individual privacy while still enabling communication.
If a crawler behaves unexpectedly—for example, due to misconfiguration or implementation errors—server administrators can use the information in the user agent to contact the operator and coordinate an appropriate resolution.
The `User-Agent` header can be set on individual requests or applied globally by configuring a custom dispatcher.
**Example: setting a `User-Agent` per request**
```js
import { fetch } from 'undici'
const headers = {
'User-Agent': 'AcmeCo Crawler - acme.co - contact@acme.co'
}
const res = await fetch('https://example.com', { headers })
```
## Best Practices for Crawlers
When developing a crawler, the following practices are recommended in addition to setting a descriptive `User-Agent` header:
* **Respect `robots.txt`**
Follow the directives defined in the target site’s `robots.txt` file, including disallowed paths and optional crawl-delay settings (see [W3C guidelines](https://www.w3.org/wiki/Write_Web_Crawler)).
* **Rate limiting**
Regulate request frequency to avoid imposing excessive load on servers. Introduce delays between requests or limit the number of concurrent requests. The W3C suggests at least one second between requests.
* **Error handling**
Implement retry logic with exponential backoff for transient failures, and stop requests when persistent errors occur (e.g., HTTP 403 or 429).
* **Monitoring and logging**
Track request volume, response codes, and error rates to detect misbehavior and address issues proactively.
* **Contact information**
Always include valid and current contact details in the `User-Agent` string so that administrators can reach the crawler operator if necessary.
## References and Further Reading
* [RFC 9309: The Robots Exclusion Protocol](https://datatracker.ietf.org/doc/html/rfc9309)
* [W3C Wiki: Write Web Crawler](https://www.w3.org/wiki/Write_Web_Crawler)
* [Ethical Web Crawling (WWW 2010 Conference Paper)](https://archives.iw3c2.org/www2010/proceedings/www/p1101.pdf)
node_modules/undici/docs/docs/best-practices/migrating-from-v7-to-v8.md
Generated Vendored
+233
View File
@@ -0,0 +1,233 @@
# Migrating from Undici 7 to 8
<!--type=misc-->
This guide covers the changes you are most likely to hit when upgrading an
application or library from Undici v7 to v8.
## Before you upgrade
- Make sure your runtime is Node.js `>= 22.19.0`.
- If you have custom dispatchers, interceptors, or handlers, review the
handler API changes before updating.
- If you rely on HTTP/1.1-only behavior, plan to set `allowH2: false`
explicitly.
## 1. Update your Node.js version
Undici v8 requires Node.js `>= 22.19.0`.
If you are still on Node.js 20 or an older Node.js 22 release, upgrade Node.js
first:
```bash
node -v
```
If that command prints a version lower than `v22.19.0`, upgrade Node.js before
installing Undici v8.
## 2. Migrate custom dispatcher handlers to the v2 API
Undici v8 uses the newer dispatcher handler API consistently.
If you implemented custom dispatchers, interceptors, or wrappers around
`dispatch()`, update legacy callbacks such as `onConnect`, `onHeaders`, and
`onComplete` to the newer callback names.
### Old handler callbacks vs. v8 callbacks
| Undici 7 style | Undici 8 style |
|---|---|
| `onConnect(abort, context)` | `onRequestStart(controller, context)` |
| `onHeaders(statusCode, rawHeaders, resume, statusText)` | `onResponseStart(controller, statusCode, headers, statusText)` |
| `onData(chunk)` | `onResponseData(controller, chunk)` |
| `onComplete(trailers)` | `onResponseEnd(controller, trailers)` |
| `onError(err)` | `onResponseError(controller, err)` |
| `onUpgrade(statusCode, rawHeaders, socket)` | `onRequestUpgrade(controller, statusCode, headers, socket)` |
### Example
Before:
```js
client.dispatch(options, {
onConnect (abort) {
this.abort = abort
},
onHeaders (statusCode, headers, resume) {
this.resume = resume
return true
},
onData (chunk) {
chunks.push(chunk)
return true
},
onComplete (trailers) {
console.log(trailers)
},
onError (err) {
console.error(err)
}
})
```
After:
```js
client.dispatch(options, {
onRequestStart (controller) {
this.controller = controller
},
onResponseStart (controller, statusCode, headers, statusText) {
console.log(statusCode, statusText, headers)
},
onResponseData (controller, chunk) {
chunks.push(chunk)
},
onResponseEnd (controller, trailers) {
console.log(trailers)
},
onResponseError (controller, err) {
console.error(err)
}
})
```
### Pause, resume, and abort now go through the controller
In Undici v7, legacy handlers could return `false` or keep references to
`abort()` and `resume()` callbacks. In Undici v8, use the controller instead:
```js
onRequestStart (controller) {
this.controller = controller
}
onResponseData (controller, chunk) {
controller.pause()
setImmediate(() => controller.resume())
}
onResponseError (controller, err) {
controller.abort(err)
}
```
### Raw headers and trailers moved to the controller
If you need the raw header arrays, read them from the controller:
- `controller.rawHeaders`
- `controller.rawTrailers`
## 3. Update `onBodySent()` handlers
If you implemented `onBodySent()`, note that its signature changed.
Before, handlers received counters:
```js
onBodySent (chunkSize, totalBytesSent) {}
```
In Undici v8, handlers receive the actual chunk:
```js
onBodySent (chunk) {}
```
If you need a notification that the whole body has been sent, use
`onRequestSent()`:
```js
onRequestSent () {
console.log('request body fully sent')
}
```
## 4. If you need HTTP/1.1 only, disable HTTP/2 explicitly
Undici v8 enables HTTP/2 by default when a TLS server negotiates it via ALPN.
If your application depends on HTTP/1.1-specific behavior, set `allowH2: false`
explicitly.
Before:
```js
const client = new Client('https://example.com')
```
After, to keep HTTP/1.1 only:
```js
const client = new Client('https://example.com', {
allowH2: false
})
```
The same applies when you configure an `Agent`:
```js
const agent = new Agent({
allowH2: false
})
```
## 5. Use real `Blob` and `File` instances
Undici v8 no longer accepts fake Blob-like values that only imitate `Blob` or
`File` via properties such as `Symbol.toStringTag`.
If you were passing custom objects that looked like `Blob`s, replace them with
actual `Blob` or `File` instances:
```js
const body = new Blob(['hello'])
```
## 6. Avoid depending on the internal global dispatcher symbol
`setGlobalDispatcher()` and `getGlobalDispatcher()` remain the public APIs and
should continue to be used.
Internally, Undici v8 stores its dispatcher under
`Symbol.for('undici.globalDispatcher.2')` and mirrors a v1-compatible wrapper
for legacy consumers such as Node.js built-in `fetch`.
If your code was reading or writing `Symbol.for('undici.globalDispatcher.1')`
directly, migrate to the public APIs instead:
```js
import { setGlobalDispatcher, getGlobalDispatcher, Agent } from 'undici'
setGlobalDispatcher(new Agent())
const dispatcher = getGlobalDispatcher()
```
If you must expose a dispatcher to legacy v1 handler consumers, wrap it with
`Dispatcher1Wrapper`:
```js
import { Agent, Dispatcher1Wrapper } from 'undici'
const legacyCompatibleDispatcher = new Dispatcher1Wrapper(new Agent())
```
## 7. Verify the upgrade
After moving to Undici v8, it is worth checking these paths in your test suite:
- requests that use a custom `dispatcher`
- `setGlobalDispatcher()` behavior
- any custom interceptor or retry handler
- uploads that use `Blob`, `File`, or `FormData`
- integrations that depend on HTTP/1.1-only behavior
## Related documentation
- [Dispatcher](../api/Dispatcher.md)
- [Client](../api/Client.md)
- [Global Installation](../api/GlobalInstallation.md)
- [Undici Module vs. Node.js Built-in Fetch](./undici-vs-builtin-fetch.md)
node_modules/undici/docs/docs/best-practices/mocking-request.md
Generated Vendored
+192
View File
@@ -0,0 +1,192 @@
# Mocking Request
<!--type=misc-->
Undici has its own mocking [utility](../api/MockAgent.md). It allow us to intercept undici HTTP requests and return mocked values instead. It can be useful for testing purposes.
Example:
```js
// bank.mjs
import { request } from 'undici'
export async function bankTransfer(recipient, amount) {
const { body } = await request('http://localhost:3000/bank-transfer',
{
method: 'POST',
headers: {
'X-TOKEN-SECRET': 'SuperSecretToken',
},
body: JSON.stringify({
recipient,
amount
})
}
)
return await body.json()
}
```
And this is what the test file looks like:
```js
// index.test.mjs
import { strict as assert } from 'node:assert'
import { MockAgent, setGlobalDispatcher, } from 'undici'
import { bankTransfer } from './bank.mjs'
const mockAgent = new MockAgent();
setGlobalDispatcher(mockAgent);
// Provide the base url to the request
const mockPool = mockAgent.get('http://localhost:3000');
// intercept the request
mockPool.intercept({
path: '/bank-transfer',
method: 'POST',
headers: {
'X-TOKEN-SECRET': 'SuperSecretToken',
},
body: JSON.stringify({
recipient: '1234567890',
amount: '100'
})
}).reply(200, {
message: 'transaction processed'
})
const success = await bankTransfer('1234567890', '100')
assert.deepEqual(success, { message: 'transaction processed' })
// if you dont want to check whether the body or the headers contain the same value
// just remove it from interceptor
mockPool.intercept({
path: '/bank-transfer',
method: 'POST',
}).reply(400, {
message: 'bank account not found'
})
const badRequest = await bankTransfer('1234567890', '100')
assert.deepEqual(badRequest, { message: 'bank account not found' })
```
Explore other MockAgent functionality [here](../api/MockAgent.md)
## Access agent call history
Using a MockAgent also allows you to make assertions on the configuration used to make your request in your application.
Here is an example :
```js
// index.test.mjs
import { strict as assert } from 'node:assert'
import { MockAgent, setGlobalDispatcher, fetch } from 'undici'
import { app } from './app.mjs'
// given an application server running on http://localhost:3000
await app.start()
// enable call history at instantiation
const mockAgent = new MockAgent({ enableCallHistory: true })
// or after instantiation
mockAgent.enableCallHistory()
setGlobalDispatcher(mockAgent)
// this call is made (not intercepted)
await fetch(`http://localhost:3000/endpoint?query='hello'`, {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ data: '' })
})
// access to the call history of the MockAgent (which register every call made intercepted or not)
assert.ok(mockAgent.getCallHistory()?.calls().length === 1)
assert.strictEqual(mockAgent.getCallHistory()?.firstCall()?.fullUrl, `http://localhost:3000/endpoint?query='hello'`)
assert.strictEqual(mockAgent.getCallHistory()?.firstCall()?.body, JSON.stringify({ data: '' }))
assert.deepStrictEqual(mockAgent.getCallHistory()?.firstCall()?.searchParams, { query: 'hello' })
assert.strictEqual(mockAgent.getCallHistory()?.firstCall()?.port, '3000')
assert.strictEqual(mockAgent.getCallHistory()?.firstCall()?.host, 'localhost:3000')
assert.strictEqual(mockAgent.getCallHistory()?.firstCall()?.method, 'POST')
assert.strictEqual(mockAgent.getCallHistory()?.firstCall()?.path, '/endpoint')
assert.deepStrictEqual(mockAgent.getCallHistory()?.firstCall()?.headers, { 'content-type': 'application/json' })
// clear all call history logs
mockAgent.clearCallHistory()
assert.ok(mockAgent.getCallHistory()?.calls().length === 0)
```
Calling `mockAgent.close()` will automatically clear and delete every call history for you.
Explore other MockAgent functionality [here](../api/MockAgent.md)
Explore other MockCallHistory functionality [here](../api/MockCallHistory.md)
Explore other MockCallHistoryLog functionality [here](../api/MockCallHistoryLog.md)
## Debug Mock Value
When the interceptor and the request options are not the same, undici will automatically make a real HTTP request. To prevent real requests from being made, use `mockAgent.disableNetConnect()`:
```js
const mockAgent = new MockAgent();
setGlobalDispatcher(mockAgent);
mockAgent.disableNetConnect()
// Provide the base url to the request
const mockPool = mockAgent.get('http://localhost:3000');
mockPool.intercept({
path: '/bank-transfer',
method: 'POST',
}).reply(200, {
message: 'transaction processed'
})
const badRequest = await bankTransfer('1234567890', '100')
// Will throw an error
// MockNotMatchedError: Mock dispatch not matched for path '/bank-transfer':
// subsequent request to origin http://localhost:3000 was not allowed (net.connect disabled)
```
## Reply with data based on request
If the mocked response needs to be dynamically derived from the request parameters, you can provide a function instead of an object to `reply`:
```js
mockPool.intercept({
path: '/bank-transfer',
method: 'POST',
headers: {
'X-TOKEN-SECRET': 'SuperSecretToken',
},
body: JSON.stringify({
recipient: '1234567890',
amount: '100'
})
}).reply(200, (opts) => {
// do something with opts
return { message: 'transaction processed' }
})
```
in this case opts will be
```js
{
method: 'POST',
headers: { 'X-TOKEN-SECRET': 'SuperSecretToken' },
body: '{"recipient":"1234567890","amount":"100"}',
origin: 'http://localhost:3000',
path: '/bank-transfer'
}
```
node_modules/undici/docs/docs/best-practices/proxy.md
Generated Vendored
+129
View File
@@ -0,0 +1,129 @@
# Connecting through a proxy
<!--type=misc-->
Connecting through a proxy is possible by:
- Using {ProxyAgent}.
- Configuring `Client` or `Pool` constructor.
The proxy url should be passed to the `Client` or `Pool` constructor, while the upstream server url
should be added to every request call in the `path`.
For instance, if you need to send a request to the `/hello` route of your upstream server,
the `path` should be `path: 'http://upstream.server:port/hello?foo=bar'`.
If you proxy requires basic authentication, you can send it via the `proxy-authorization` header.
### Connect without authentication
```js
import { Client } from 'undici'
import { createServer } from 'http'
import { createProxy } from 'proxy'
const server = await buildServer()
const proxyServer = await buildProxy()
const serverUrl = `http://localhost:${server.address().port}`
const proxyUrl = `http://localhost:${proxyServer.address().port}`
server.on('request', (req, res) => {
console.log(req.url) // '/hello?foo=bar'
res.setHeader('content-type', 'application/json')
res.end(JSON.stringify({ hello: 'world' }))
})
const client = new Client(proxyUrl)
const response = await client.request({
method: 'GET',
path: serverUrl + '/hello?foo=bar'
})
response.body.setEncoding('utf8')
let data = ''
for await (const chunk of response.body) {
data += chunk
}
console.log(response.statusCode) // 200
console.log(JSON.parse(data)) // { hello: 'world' }
server.close()
proxyServer.close()
client.close()
function buildServer () {
return new Promise((resolve, reject) => {
const server = createServer()
server.listen(0, () => resolve(server))
})
}
function buildProxy () {
return new Promise((resolve, reject) => {
const server = createProxy(createServer())
server.listen(0, () => resolve(server))
})
}
```
### Connect with authentication
```js
import { Client } from 'undici'
import { createServer } from 'http'
import { createProxy } from 'proxy'
const server = await buildServer()
const proxyServer = await buildProxy()
const serverUrl = `http://localhost:${server.address().port}`
const proxyUrl = `http://localhost:${proxyServer.address().port}`
proxyServer.authenticate = function (req) {
return req.headers['proxy-authorization'] === `Basic ${Buffer.from('user:pass').toString('base64')}`
}
server.on('request', (req, res) => {
console.log(req.url) // '/hello?foo=bar'
res.setHeader('content-type', 'application/json')
res.end(JSON.stringify({ hello: 'world' }))
})
const client = new Client(proxyUrl)
const response = await client.request({
method: 'GET',
path: serverUrl + '/hello?foo=bar',
headers: {
'proxy-authorization': `Basic ${Buffer.from('user:pass').toString('base64')}`
}
})
response.body.setEncoding('utf8')
let data = ''
for await (const chunk of response.body) {
data += chunk
}
console.log(response.statusCode) // 200
console.log(JSON.parse(data)) // { hello: 'world' }
server.close()
proxyServer.close()
client.close()
function buildServer () {
return new Promise((resolve, reject) => {
const server = createServer()
server.listen(0, () => resolve(server))
})
}
function buildProxy () {
return new Promise((resolve, reject) => {
const server = createProxy(createServer())
server.listen(0, () => resolve(server))
})
}
```
node_modules/undici/docs/docs/best-practices/undici-vs-builtin-fetch.md
Generated Vendored
+226
View File
@@ -0,0 +1,226 @@
# Undici Module vs. Node.js Built-in Fetch
<!--type=misc-->
Node.js has shipped a built-in `fetch()` implementation powered by undici since
Node.js v18. This guide explains the relationship between the `undici` npm
package and the built-in `fetch`, and when you should install one versus relying
on the other.
## Background
The `fetch()`, `Request`, `Response`, `Headers`, and `FormData` globals in
Node.js v18+ are provided by a version of undici that is bundled into Node.js
itself. You can check which version is bundled with:
```js
console.log(process.versions.undici); // e.g., "7.5.0"
```
When you install undici from npm, you get the full library with all of its
additional APIs, and potentially a newer release than what your Node.js version
bundles.
## Keep `fetch` and `FormData` from the same implementation
When you send a `FormData` body, keep `fetch` and `FormData` together from the
same implementation.
Use one of these patterns:
### Built-in globals
```js
const body = new FormData()
body.set('name', 'some')
body.set('someOtherProperty', '8000')
await fetch('https://example.com', {
method: 'POST',
body
})
```
### `undici` module imports
```js
import { fetch, FormData } from 'undici'
const body = new FormData()
body.set('name', 'some')
body.set('someOtherProperty', '8000')
await fetch('https://example.com', {
method: 'POST',
body
})
```
### `undici.install()` globals
If you want the installed `undici` package to provide the globals, call
[`install()`](../api/GlobalInstallation.md):
```js
import { install } from 'undici'
install()
const body = new FormData()
body.set('name', 'some')
body.set('someOtherProperty', '8000')
await fetch('https://example.com', {
method: 'POST',
body
})
```
`install()` replaces the global `fetch`, `Headers`, `Response`, `Request`, and
`FormData` implementations with undici's versions, and also installs undici's
`WebSocket`, `CloseEvent`, `ErrorEvent`, `MessageEvent`, and `EventSource`
globals.
Avoid mixing implementations in the same request, for example:
```js
import { fetch } from 'undici'
const body = new FormData()
await fetch('https://example.com', {
method: 'POST',
body
})
```
```js
import { FormData } from 'undici'
const body = new FormData()
await fetch('https://example.com', {
method: 'POST',
body
})
```
Those combinations may behave differently across Node.js and undici versions.
Using matching pairs keeps multipart handling predictable.
## When you do NOT need to install undici
If all of the following are true, you can rely on the built-in globals and skip
adding undici to your dependencies:
- You only need the standard Fetch API (`fetch`, `Request`, `Response`,
`Headers`, `FormData`).
- You are running Node.js v18 or later.
- You do not depend on features or bug fixes introduced in a version of undici
newer than the one bundled with your Node.js release.
- You want zero additional runtime dependencies.
- You want cross-platform interoperability with browsers and other runtimes
(Deno, Bun, Cloudflare Workers, etc.) using the same Fetch API surface.
This is common in applications that make straightforward HTTP requests or in
libraries that target multiple JavaScript runtimes.
## When you SHOULD install undici
Install undici from npm when you need capabilities beyond the standard Fetch API:
### Advanced HTTP APIs
undici exposes `request`, `stream`, `pipeline`, and `connect` methods that
provide lower-level control and significantly better performance than `fetch`:
```js
import { request } from 'undici';
const { statusCode, headers, body } = await request('https://example.com');
const data = await body.json();
```
### Connection pooling and dispatchers
`Client`, `Pool`, `BalancedPool`, `Agent`, and their configuration options
let you manage connection lifecycle, keep-alive behavior, pipelining depth,
and concurrency limits:
```js
import { Pool } from 'undici';
const pool = new Pool('https://example.com', { connections: 10 });
const { body } = await pool.request({ path: '/', method: 'GET' });
```
### Proxy support
`ProxyAgent` and `EnvHttpProxyAgent` handle HTTP(S) proxying. Note that
Node.js v22.21.0+ and v24.0.0+ support environment-variable-based proxy
configuration for the built-in `fetch` via the `--use-env-proxy` flag (or
`NODE_USE_ENV_PROXY=1`). However, undici's `ProxyAgent` still provides
programmatic control through the dispatcher API:
```js
import { ProxyAgent, fetch } from 'undici';
const proxyAgent = new ProxyAgent('https://my-proxy.example.com:8080');
const response = await fetch('https://example.com', { dispatcher: proxyAgent });
```
### Testing and mocking
`MockAgent`, `MockClient`, and `MockPool` let you intercept and mock HTTP
requests without patching globals or depending on external libraries:
```js
import { MockAgent, setGlobalDispatcher, fetch } from 'undici';
const mockAgent = new MockAgent();
setGlobalDispatcher(mockAgent);
const pool = mockAgent.get('https://example.com');
pool.intercept({ path: '/api' }).reply(200, { message: 'mocked' });
```
### Interceptors and middleware
Custom dispatchers and interceptors (retry, redirect, cache, DNS) give you
fine-grained control over how requests are processed.
### Newer version than what Node.js bundles
The npm package often includes features, performance improvements, and bug fixes
that have not yet landed in a Node.js release. If you need a specific fix or
feature, you can install a newer version directly.
## Version compatibility
| Node.js version | Bundled undici version | Notes |
|---|---|---|
| v18.x | ~5.x | `fetch` is experimental (behind `--experimental-fetch` in early v18) |
| v20.x | ~6.x | `fetch` is stable |
| v22.x | ~6.x / ~7.x | `fetch` is stable |
| v24.x | ~7.x | `fetch` is stable; env-proxy support via `--use-env-proxy` |
You can always check the exact bundled version at runtime with
`process.versions.undici`.
Installing undici from npm does not replace the built-in globals. If you want
your installed version to replace the global `fetch` and related classes, use
[`install()`](../api/GlobalInstallation.md). Otherwise, import `fetch`
directly from `'undici'`:
```js
import { fetch } from 'undici' // uses your installed version, not the built-in
```
## Further reading
- [API Reference: Fetch](../api/Fetch.md)
- [API Reference: Client](../api/Client.md)
- [API Reference: Pool](../api/Pool.md)
- [API Reference: ProxyAgent](../api/ProxyAgent.md)
- [API Reference: MockAgent](../api/MockAgent.md)
- [API Reference: Global Installation](../api/GlobalInstallation.md)
node_modules/undici/docs/docs/best-practices/writing-tests.md
Generated Vendored
+65
View File
@@ -0,0 +1,65 @@
# Writing tests
<!--type=misc-->
Undici is tuned for a production use case and its default will keep
a socket open for a few seconds after an HTTP request is completed to
remove the overhead of opening up a new socket. These settings that makes
Undici shine in production are not a good fit for using Undici in automated
tests, as it will result in longer execution times.
The following are good defaults that will keep the socket open for only 10ms:
```js
import { request, setGlobalDispatcher, Agent } from 'undici'
const agent = new Agent({
keepAliveTimeout: 10, // milliseconds
keepAliveMaxTimeout: 10 // milliseconds
})
setGlobalDispatcher(agent)
```
## Guarding against unexpected disconnects
Undici's `Client` automatically reconnects after a socket error. This means
a test can silently disconnect, reconnect, and still pass. Unfortunately,
this could mask bugs like unexpected parser errors or protocol violations.
To catch these silent reconnections, add a disconnect guard after creating
a `Client`:
```js
const { Client } = require('undici')
const { test, after } = require('node:test')
const { tspl } = require('@matteo.collina/tspl')
test('example with disconnect guard', async (t) => {
t = tspl(t, { plan: 1 })
const client = new Client('http://localhost:3000')
after(() => client.close())
client.on('disconnect', () => {
if (!client.closed && !client.destroyed) {
t.fail('unexpected disconnect')
}
})
// ... test logic ...
})
```
`client.close()` and `client.destroy()` both emit `'disconnect'` events, but
those are expected. The guard only fails when a disconnect happens during the
active test (i.e., `!client.closed && !client.destroyed` is true).
Skip the guard for tests where a disconnect is expected behavior, such as:
- Signal aborts (`signal.emit('abort')`, `ac.abort()`)
- Server-side destruction (`res.destroy()`, `req.socket.destroy()`)
- Client-side body destruction mid-stream (`data.body.destroy()`)
- Timeout errors (`HeadersTimeoutError`, `BodyTimeoutError`)
- Successful upgrades (the socket is detached from the `Client`)
- Retry/reconnect tests where the disconnect triggers the retry
- HTTP parser errors from malformed responses (`HTTPParserError`)
node_modules/undici/docs/docs/getting-started.md
Generated Vendored
+281
View File
@@ -0,0 +1,281 @@
# Getting Started
<!--type=misc-->
## 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:
```mjs
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:
```mjs
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:
```mjs
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](/#garbage-collection)
> for details.
For more on `fetch`, see [API Reference: Fetch](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), which should only be enabled for
trusted remote servers:
```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](api/Agent.md)
- [API Reference: Pool](api/Pool.md)
- [API Reference: Client](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](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](best-practices/proxy.md) and
[API Reference: ProxyAgent](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](best-practices/mocking-request.md)
and [API Reference: MockAgent](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](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](api/GlobalInstallation.md).
## Further reading
- [Undici vs. Built-in Fetch](best-practices/undici-vs-builtin-fetch.md) —
when to install undici vs using Node.js built-in fetch
- [API Reference](api/Dispatcher.md) — full dispatcher API documentation
- [Examples](/examples/) — runnable code examples
node_modules/undici/docs/docs/index.md
Generated Vendored
+793
View File
@@ -0,0 +1,793 @@
# undici
<!--type=misc-->
[![Node CI](https://github.com/nodejs/undici/actions/workflows/ci.yml/badge.svg)](https://github.com/nodejs/undici/actions/workflows/nodejs.yml) [![neostandard javascript style](https://img.shields.io/badge/neo-standard-7fffff?style=flat\&labelColor=ff80ff)](https://github.com/neostandard/neostandard) [![npm version](https://badge.fury.io/js/undici.svg)](https://badge.fury.io/js/undici) [![codecov](https://codecov.io/gh/nodejs/undici/branch/main/graph/badge.svg?token=yZL6LtXkOA)](https://codecov.io/gh/nodejs/undici)
An HTTP/1.1 client, written from scratch for Node.js.
> Undici means eleven in Italian. 1.1 -> 11 -> Eleven -> Undici.
It is also a Stranger Things reference.
## How to get involved
Have a question about using Undici? Open a [Q&A Discussion](https://github.com/nodejs/undici/discussions/new) or join our official OpenJS [Slack](https://openjs-foundation.slack.com/archives/C01QF9Q31QD) channel.
Looking to contribute? Start by reading the [contributing guide](./CONTRIBUTING.md)
## Install
```bash
npm i undici
```
## Benchmarks
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
```text
┌────────────────────────┬─────────┬────────────────────┬────────────┬─────────────────────────┐
│ Tests │ Samples │ Result │ Tolerance │ Difference with slowest │
├────────────────────────┼─────────┼────────────────────┼────────────┼─────────────────────────┤
│ '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).
```text
┌────────────────────────┬─────────┬───────────────────┬────────────┬─────────────────────────┐
│ 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).
```text
┌────────────────────────┬─────────┬───────────────────┬────────────┬─────────────────────────┐
│ 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
Node.js includes a built-in `fetch()` implementation powered by undici starting from Node.js v18. However, there are important differences between using the built-in fetch and installing undici as a separate module.
### Built-in Fetch (Node.js v18+)
Node.js's built-in fetch is powered by a bundled version of undici:
```js
// Available globally in Node.js v18+
const response = await fetch('https://api.example.com/data');
const data = await response.json();
// Check the bundled undici version
console.log(process.versions.undici); // e.g., "5.28.4"
```
**Pros:**
- No additional dependencies required
- Works across different JavaScript runtimes
- Automatic compression handling (gzip, deflate, br)
- Built-in caching support (in development)
**Cons:**
- Limited to the undici version bundled with your Node.js version
- Less control over connection pooling and advanced features
- Error handling follows Web API standards (errors wrapped in `TypeError`)
- Performance overhead due to Web Streams implementation
### Undici Module
Installing undici as a separate module gives you access to the latest features and APIs:
```bash
npm install undici
```
```js
import { request, fetch, Agent, setGlobalDispatcher } from 'undici';
// Use undici.request for maximum performance
const { statusCode, headers, body } = await request('https://api.example.com/data');
const data = await body.json();
// Or use undici.fetch with custom configuration
const agent = new Agent({ keepAliveTimeout: 10000 });
setGlobalDispatcher(agent);
const response = await fetch('https://api.example.com/data');
```
**Pros:**
- Latest undici features and bug fixes
- Access to advanced APIs (`request`, `stream`, `pipeline`)
- Fine-grained control over connection pooling
- Better error handling with clearer error messages
- Superior performance, especially with `undici.request`
- HTTP/1.1 pipelining support
- Custom interceptors and middleware
- Advanced features like `ProxyAgent`, `Socks5Agent`, `MockAgent`
**Cons:**
- Additional dependency to manage
- Larger bundle size
### When to Use Each
#### Use Built-in Fetch When:
- You want zero dependencies
- Building isomorphic code that runs in browsers and Node.js
- Publishing to npm and want to maximize compatibility with JS runtimes
- Simple HTTP requests without advanced configuration
- You're publishing to npm and you want to maximize compatiblity
- You don't depend on features from a specific version of undici
#### Use Undici Module When:
- You need the latest undici features and performance improvements
- You require advanced connection pooling configuration
- You need APIs not available in the built-in fetch (`ProxyAgent`, `Socks5Agent`, `MockAgent`, etc.)
- Performance is critical (use `undici.request` for maximum speed)
- You want better error handling and debugging capabilities
- You need HTTP/1.1 pipelining or advanced interceptors
- You prefer decoupled protocol and API interfaces
### Performance Comparison
Based on benchmarks, here's the typical performance hierarchy:
1. **`undici.request()`** - Fastest, most efficient
2. **`undici.fetch()`** - Good performance, standard compliance
3. **Node.js `http`/`https`** - Baseline performance
### Migration Guide
If you're currently using built-in fetch and want to migrate to undici:
```js
// Before: Built-in fetch
const response = await fetch('https://api.example.com/data');
// After: Undici fetch (drop-in replacement)
import { fetch } from 'undici';
const response = await fetch('https://api.example.com/data');
// Or: Undici request (better performance)
import { request } from 'undici';
const { statusCode, body } = await request('https://api.example.com/data');
const data = await body.json();
```
### Keep `fetch` and `FormData` together
When you send a `FormData` body, keep `fetch` and `FormData` from the same
implementation.
Use one of these patterns:
```js
// Built-in globals
const body = new FormData()
body.set('name', 'some')
await fetch('https://example.com', {
method: 'POST',
body
})
```
```js
// undici module imports
import { fetch, FormData } from 'undici'
const body = new FormData()
body.set('name', 'some')
await fetch('https://example.com', {
method: 'POST',
body
})
```
If you want the installed `undici` package to provide the globals, call
`install()` first:
```js
import { install } from 'undici'
install()
const body = new FormData()
body.set('name', 'some')
await fetch('https://example.com', {
method: 'POST',
body
})
```
`install()` replaces the global `fetch`, `Headers`, `Response`, `Request`, and
`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()`.
### Version Compatibility
You can check which version of undici is bundled with your Node.js version:
```js
console.log(process.versions.undici);
```
Installing undici as a module allows you to use a newer version than what's bundled with Node.js, giving you access to the latest features and performance improvements.
## Quick Start
### Basic Request
```js
import { request } from 'undici'
const {
statusCode,
headers,
trailers,
body
} = await request('http://localhost:3000/foo')
console.log('response received', statusCode)
console.log('headers', headers)
for await (const data of body) { console.log('data', data) }
console.log('trailers', trailers)
```
### Using Cache Interceptor
Undici provides a powerful HTTP caching interceptor that follows HTTP caching best practices. Here's how to use it:
```js
import { fetch, Agent, interceptors, cacheStores } from 'undici';
// Create a client with cache interceptor
const client = new Agent().compose(interceptors.cache({
// Optional: Configure cache store (defaults to MemoryCacheStore)
store: new cacheStores.MemoryCacheStore({
maxSize: 100 * 1024 * 1024, // 100MB
maxCount: 1000,
maxEntrySize: 5 * 1024 * 1024 // 5MB
}),
// Optional: Specify which HTTP methods to cache (default: ['GET', 'HEAD'])
methods: ['GET', 'HEAD']
}));
// Set the global dispatcher to use our caching client
setGlobalDispatcher(client);
// Now all fetch requests will use the cache
async function getData() {
const response = await fetch('https://api.example.com/data');
// The server should set appropriate Cache-Control headers in the response
// which the cache will respect based on the cache policy
return response.json();
}
// First request - fetches from origin
const data1 = await getData();
// Second request - served from cache if within max-age
const data2 = await getData();
```
#### Key Features:
- **Automatic Caching**: Respects `Cache-Control` and `Expires` headers
- **Validation**: Supports `ETag` and `Last-Modified` validation
- **Storage Options**: In-memory or persistent SQLite storage
- **Flexible**: Configure cache size, TTL, and more
## Global Installation
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 undici's global web APIs
install()
// Now you can use fetch classes globally without importing
const response = await fetch('https://api.example.com/data')
const data = await response.json()
// All classes are available globally:
const headers = new Headers([['content-type', 'application/json']])
const request = new Request('https://example.com')
const formData = new FormData()
const ws = new WebSocket('wss://example.com')
const eventSource = new EventSource('https://example.com/events')
```
The `install()` function adds the following classes to `globalThis`:
- `fetch` - The fetch function
- `Headers` - HTTP headers management
- `Response` - HTTP response representation
- `Request` - HTTP request representation
- `FormData` - Form data handling
- `WebSocket` - WebSocket client
- `CloseEvent`, `ErrorEvent`, `MessageEvent` - WebSocket events
- `EventSource` - Server-sent events client
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, 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
- Ensuring consistent fetch behavior across different Node.js versions
- Making undici's implementations available globally for libraries that expect them
## Body Mixins
The `body` mixins are the most common way to format the request/response body. Mixins include:
- [`.arrayBuffer()`](https://fetch.spec.whatwg.org/#dom-body-arraybuffer)
- [`.blob()`](https://fetch.spec.whatwg.org/#dom-body-blob)
- [`.bytes()`](https://fetch.spec.whatwg.org/#dom-body-bytes)
- [`.json()`](https://fetch.spec.whatwg.org/#dom-body-json)
- [`.text()`](https://fetch.spec.whatwg.org/#dom-body-text)
> [!NOTE]
> The body returned from `undici.request` does not implement `.formData()`.
> [!WARNING]
> The body mixins `.arrayBuffer()`, `.blob()`, `.bytes()`, `.json()`, `.text()`,
> and `.formData()` buffer the entire body in memory before returning. Where
> applicable, they also decode or parse the payload and retain that
> representation in memory. Calling these methods therefore means trusting that
> the response body is small enough to fit in the available memory. Do not use
> them for responses from untrusted or user-controlled sources. Instead, consume
> the response body as a stream and enforce an application-specific size limit:
> use `response.body` for fetch responses or the `body` returned by
> `undici.request()`. For streaming decoded text, use `body.textStream()` on a
> fetch `Request` or `Response`.
Example usage:
```js
import { request } from 'undici'
const {
statusCode,
headers,
trailers,
body
} = await request('http://localhost:3000/foo')
console.log('response received', statusCode)
console.log('headers', headers)
console.log('data', await body.json())
console.log('trailers', trailers)
```
_Note: Once a mixin has been called then the body cannot be reused, thus calling additional mixins on `.body`, e.g. `.body.json(); .body.text()` will result in an error `TypeError: unusable` being thrown and returned through the `Promise` rejection._
Should you need to access the `body` in plain-text after using a mixin, the best practice is to use the `.text()` mixin first and then manually parse the text to the desired format.
For more information about their behavior, please reference the body mixin from the [Fetch Standard](https://fetch.spec.whatwg.org/#body-mixin).
## Common API Methods
This section documents our most commonly used API methods. Additional APIs are documented in their own files within the [docs](./docs/) folder and are accessible via the navigation list on the left side of the docs site.
For the top-level APIs below, the `url` argument supplies the request origin and
path. Do not pass `origin` or `path` in the second `options` argument. The linked
`Dispatcher` option types include those fields because dispatcher methods are
lower-level APIs that do not receive a separate `url` argument.
### `undici.request([url, options])`
* `url` {string|URL|UrlObject}
* `options` {RequestOptions} See [`RequestOptions`](./docs/docs/api/Dispatcher.md#parameter-requestoptions).
* `dispatcher` {Dispatcher} **Default:** [getGlobalDispatcher](#undicigetglobaldispatcher).
* `method` {string} **Default:** `PUT` if `options.body`, otherwise `GET`.
* Returns: {Promise} A promise with the result of the `Dispatcher.request` method.
Calls `options.dispatcher.request(options)`.
See [Dispatcher.request](./docs/docs/api/Dispatcher.md#dispatcherrequestoptions-callback) for more details, and [request examples](./docs/examples/README.md) for examples.
### `undici.stream([url, options, ]factory)`
* `url` {string|URL|UrlObject}
* `options` {StreamOptions} See [`StreamOptions`](./docs/docs/api/Dispatcher.md#parameter-streamoptions).
* `dispatcher` {Dispatcher} **Default:** [getGlobalDispatcher](#undicigetglobaldispatcher).
* `method` {string} **Default:** `PUT` if `options.body`, otherwise `GET`.
* `factory` {Function} `Dispatcher.stream.factory`.
* Returns: {Promise} A promise with the result of the `Dispatcher.stream` method.
Calls `options.dispatcher.stream(options, factory)`.
See [Dispatcher.stream](./docs/docs/api/Dispatcher.md#dispatcherstreamoptions-factory-callback) for more details.
### `undici.pipeline([url, options, ]handler)`
* `url` {string|URL|UrlObject}
* `options` {PipelineOptions} See [`PipelineOptions`](./docs/docs/api/Dispatcher.md#parameter-pipelineoptions).
* `dispatcher` {Dispatcher} **Default:** [getGlobalDispatcher](#undicigetglobaldispatcher).
* `method` {string} **Default:** `PUT` if `options.body`, otherwise `GET`.
* `handler` {Function} `Dispatcher.pipeline.handler`.
* Returns: {Duplex} A `stream.Duplex`.
Calls `options.dispatch.pipeline(options, handler)`.
See [Dispatcher.pipeline](./docs/docs/api/Dispatcher.md#dispatcherpipelineoptions-handler) for more details.
### `undici.connect([url, options])`
Starts two-way communications with the requested resource using [HTTP CONNECT](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/CONNECT).
* `url` {string|URL|UrlObject}
* `options` {ConnectOptions} See [`ConnectOptions`](./docs/docs/api/Dispatcher.md#parameter-connectoptions).
* `dispatcher` {Dispatcher} **Default:** [getGlobalDispatcher](#undicigetglobaldispatcher).
* `callback` {Function} (optional) — `(err, data) => void`.
* Returns: {Promise} A promise with the result of the `Dispatcher.connect` method.
Calls `options.dispatch.connect(options)`.
See [Dispatcher.connect](./docs/docs/api/Dispatcher.md#dispatcherconnectoptions-callback) for more details.
### `undici.fetch(input[, init])`
Implements [fetch](https://fetch.spec.whatwg.org/#fetch-method).
* https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch
* https://fetch.spec.whatwg.org/#fetch-method
Basic usage example:
```js
import { fetch } from 'undici'
const res = await fetch('https://example.com')
const json = await res.json()
console.log(json)
```
You can pass an optional dispatcher to `fetch` as:
```js
import { fetch, Agent } from 'undici'
const res = await fetch('https://example.com', {
// Mocks are also supported
dispatcher: new Agent({
keepAliveTimeout: 10,
keepAliveMaxTimeout: 10
})
})
const json = await res.json()
console.log(json)
```
#### `request.body`
A body can be of the following types:
- ArrayBuffer
- ArrayBufferView
- AsyncIterables
- Blob
- Iterables
- String
- URLSearchParams
- FormData
In this implementation of fetch, ```request.body``` now accepts ```Async Iterables```. It is not present in the [Fetch Standard](https://fetch.spec.whatwg.org).
```js
import { fetch } from 'undici'
const data = {
async *[Symbol.asyncIterator]() {
yield 'hello'
yield 'world'
},
}
await fetch('https://example.com', { body: data, method: 'POST', duplex: 'half' })
```
[FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData) besides text data and buffers can also utilize streams via [Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob) objects:
```js
import { openAsBlob } from 'node:fs'
const file = await openAsBlob('./big.csv')
const body = new FormData()
body.set('file', file, 'big.csv')
await fetch('http://example.com', { method: 'POST', body })
```
#### `request.duplex`
- `'half'`
In this implementation of fetch, `request.duplex` must be set if `request.body` is `ReadableStream` or `Async Iterables`, however, even though the value must be set to `'half'`, it is actually a _full_ duplex. For more detail refer to the [Fetch Standard](https://fetch.spec.whatwg.org/#dom-requestinit-duplex).
#### `response.body`
Nodejs has two kinds of streams: [web streams](https://nodejs.org/api/webstreams.html), which follow the API of the WHATWG web standard found in browsers, and an older Node-specific [streams API](https://nodejs.org/api/stream.html). `response.body` returns a readable web stream. If you would prefer to work with a Node stream you can convert a web stream using `.fromWeb()`.
```js
import { fetch } from 'undici'
import { Readable } from 'node:stream'
const response = await fetch('https://example.com')
const readableWebStream = response.body
const readableNodeStream = Readable.fromWeb(readableWebStream)
```
## Specification Compliance
This section documents parts of the [HTTP/1.1](https://www.rfc-editor.org/rfc/rfc9110.html) and [Fetch Standard](https://fetch.spec.whatwg.org) that Undici does
not support or does not fully implement.
#### CORS
Unlike browsers, Undici does not implement CORS (Cross-Origin Resource Sharing) checks by default. This means:
- No preflight requests are automatically sent for cross-origin requests
- No validation of `Access-Control-Allow-Origin` headers is performed
- Requests to any origin are allowed regardless of the source
This behavior is intentional for server-side environments where CORS restrictions are typically unnecessary. If your application requires CORS-like protections, you will need to implement these checks manually.
#### Garbage Collection
* https://fetch.spec.whatwg.org/#garbage-collection
The [Fetch Standard](https://fetch.spec.whatwg.org) allows users to skip consuming the response body by relying on
[garbage collection](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Memory_Management#garbage_collection) to release connection resources.
Garbage collection in Node is less aggressive and deterministic
(due to the lack of clear idle periods that browsers have through the rendering refresh rate)
which means that leaving the release of connection resources to the garbage collector can lead
to excessive connection usage, reduced performance (due to less connection re-use), and even
stalls or deadlocks when running out of connections.
Therefore, __it is important to always either consume or cancel the response body anyway__.
```js
// Do
const { body, headers } = await fetch(url);
for await (const chunk of body) {
// force consumption of body
}
// Do not
const { headers } = await fetch(url);
```
However, if you want to get only headers, it might be better to use `HEAD` request method. Usage of this method will obviate the need for consumption or cancelling of the response body. See [MDN - HTTP - HTTP request methods - HEAD](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/HEAD) for more details.
```js
const headers = await fetch(url, { method: 'HEAD' })
.then(res => res.headers)
```
Note that consuming the response body is _mandatory_ for `request`:
```js
// Do
const { body, headers } = await request(url);
await body.dump(); // force consumption of body
// Do not
const { headers } = await request(url);
```
#### Forbidden and Safelisted Header Names
* https://fetch.spec.whatwg.org/#cors-safelisted-response-header-name
* https://fetch.spec.whatwg.org/#forbidden-header-name
* https://fetch.spec.whatwg.org/#forbidden-response-header-name
* https://github.com/wintercg/fetch/issues/6
The [Fetch Standard](https://fetch.spec.whatwg.org) requires implementations to exclude certain headers from requests and responses. In browser environments, some headers are forbidden so the user agent remains in full control over them. In Undici, these constraints are removed to give more control to the user.
#### Content-Encoding
* https://www.rfc-editor.org/rfc/rfc9110#field.content-encoding
Undici limits the number of `Content-Encoding` layers in a response to **5** to prevent resource exhaustion attacks. If a server responds with more than 5 content-encodings (e.g., `Content-Encoding: gzip, gzip, gzip, gzip, gzip, gzip`), the fetch will be rejected with an error. This limit matches the approach taken by [curl](https://curl.se/docs/CVE-2022-32206.html) and [urllib3](https://github.com/advisories/GHSA-gm62-xv2j-4rw9).
#### `undici.upgrade([url, options])`
Upgrade to a different protocol. See [MDN - HTTP - Protocol upgrade mechanism](https://developer.mozilla.org/en-US/docs/Web/HTTP/Protocol_upgrade_mechanism) for more details.
* `url` {string|URL|UrlObject}
* `options` {UpgradeOptions} See [`UpgradeOptions`](./docs/docs/api/Dispatcher.md#parameter-upgradeoptions).
* `dispatcher` {Dispatcher} **Default:** [getGlobalDispatcher](#undicigetglobaldispatcher).
* `callback` {Function} (optional) — `(error, data) => void`.
* Returns: {Promise} A promise with the result of the `Dispatcher.upgrade` method.
Calls `options.dispatcher.upgrade(options)`.
See [Dispatcher.upgrade](./docs/docs/api/Dispatcher.md#dispatcherupgradeoptions-callback) for more details.
### `undici.setGlobalDispatcher(dispatcher)`
* `dispatcher` {Dispatcher}
Sets the global dispatcher used by Common API Methods. Global dispatcher is shared among compatible undici modules,
including undici that is bundled internally with node.js.
Undici stores this dispatcher under `Symbol.for('undici.globalDispatcher.2')`.
`setGlobalDispatcher()` also mirrors the configured dispatcher to
`Symbol.for('undici.globalDispatcher.1')` using `Dispatcher1Wrapper`, so Node.js built-in `fetch`
can keep using the legacy handler contract while Undici uses the new handler API.
### `undici.getGlobalDispatcher()`
Gets the global dispatcher used by Common API Methods.
* Returns: {Dispatcher}
### `undici.setGlobalOrigin(origin)`
* `origin` {string|URL|undefined}
Sets the global origin used in `fetch`.
If `undefined` is passed, the global origin will be reset. This will cause `Response.redirect`, `new Request()`, and `fetch` to throw an error when a relative path is passed.
```js
setGlobalOrigin('http://localhost:3000')
const response = await fetch('/api/ping')
console.log(response.url) // http://localhost:3000/api/ping
```
### `undici.getGlobalOrigin()`
Gets the global origin used in `fetch`.
* Returns: {URL}
### `UrlObject`
* `port` {string|number} (optional)
* `path` {string} (optional)
* `pathname` {string} (optional)
* `hostname` {string} (optional)
* `origin` {string} (optional)
* `protocol` {string} (optional)
* `search` {string} (optional)
#### Expect
Undici does not support the `Expect` request header field. The request
body is always immediately sent and the `100 Continue` response will be
ignored.
Refs: https://tools.ietf.org/html/rfc7231#section-5.1.1
#### Pipelining
Undici will only use pipelining if configured with a `pipelining` factor
greater than `1`. Only enable pipelining when the remote server is trusted.
Also it is important to pass `blocking: false` to the request options to
properly pipeline requests.
Undici always assumes that connections are persistent and will immediately
pipeline requests, without checking whether the connection is persistent.
Hence, automatic fallback to HTTP/1.0 or HTTP/1.1 without pipelining is
not supported.
Undici will immediately pipeline when retrying requests after a failed
connection. However, Undici will not retry the first remaining requests in
the prior pipeline and instead error the corresponding callback/promise/stream.
Undici will abort all running requests in the pipeline when any of them are
aborted.
* Refs: https://tools.ietf.org/html/rfc2616#section-8.1.2.2
* Refs: https://tools.ietf.org/html/rfc7230#section-6.3.2
#### Manual Redirect
Since it is not possible to manually follow an HTTP redirect on the server-side,
Undici returns the actual response instead of an `opaqueredirect` filtered one
when invoked with a `manual` redirect. This aligns `fetch()` with the other
implementations in Deno and Cloudflare Workers.
Refs: https://fetch.spec.whatwg.org/#atomic-http-redirect-handling
### Workarounds
#### Network address family autoselection.
If you experience problem when connecting to a remote server that is resolved by your DNS servers to a IPv6 (AAAA record)
first, there are chances that your local router or ISP might have problem connecting to IPv6 networks. In that case
undici will throw an error with code `UND_ERR_CONNECT_TIMEOUT`.
If the target server resolves to both a IPv6 and IPv4 (A records) address and you are using a compatible Node version
(18.3.0 and above), you can fix the problem by providing the `autoSelectFamily` option (support by both `undici.request`
and `undici.Agent`) which will enable the family autoselection algorithm when establishing the connection.
## Collaborators
* [__Daniele Belardi__](https://github.com/dnlup), <https://www.npmjs.com/~dnlup>
* [__Ethan Arrowood__](https://github.com/ethan-arrowood), <https://www.npmjs.com/~ethan_arrowood>
* [__Matteo Collina__](https://github.com/mcollina), <https://www.npmjs.com/~matteo.collina>
* [__Matthew Aitken__](https://github.com/KhafraDev), <https://www.npmjs.com/~khaf>
* [__Robert Nagy__](https://github.com/ronag), <https://www.npmjs.com/~ronag>
* [__Szymon Marczak__](https://github.com/szmarczak), <https://www.npmjs.com/~szmarczak>
## Past Collaborators
* [__Tomas Della Vedova__](https://github.com/delvedor), <https://www.npmjs.com/~delvedor>
### Releasers
* [__Ethan Arrowood__](https://github.com/ethan-arrowood), <https://www.npmjs.com/~ethan_arrowood>
* [__Matteo Collina__](https://github.com/mcollina), <https://www.npmjs.com/~matteo.collina>
* [__Robert Nagy__](https://github.com/ronag), <https://www.npmjs.com/~ronag>
* [__Matthew Aitken__](https://github.com/KhafraDev), <https://www.npmjs.com/~khaf>
## Long Term Support
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) | 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
MIT
node_modules/undici/docs/docs/site.json
Generated Vendored
+125
View File
@@ -0,0 +1,125 @@
{
"sidebar": [
{
"groupName": "Documentation",
"items": [
{ "link": "/", "label": "Home" },
{ "link": "/getting-started", "label": "Getting Started" }
]
},
{
"groupName": "API",
"items": [
{
"label": "Core",
"items": [
{ "link": "/api/Dispatcher", "label": "Dispatcher" },
{ "link": "/api/Client", "label": "Client" },
{ "link": "/api/H2CClient", "label": "H2CClient" },
{ "link": "/api/Pool", "label": "Pool" },
{ "link": "/api/BalancedPool", "label": "BalancedPool" },
{ "link": "/api/RoundRobinPool", "label": "RoundRobinPool" },
{ "link": "/api/Agent", "label": "Agent" },
{ "link": "/api/PoolStats", "label": "PoolStats" },
{ "link": "/api/Connector", "label": "Connector" }
]
},
{
"label": "Proxy & Agents",
"items": [
{ "link": "/api/ProxyAgent", "label": "ProxyAgent" },
{
"link": "/api/EnvHttpProxyAgent",
"label": "EnvHttpProxyAgent"
},
{ "link": "/api/Socks5ProxyAgent", "label": "Socks5ProxyAgent" },
{ "link": "/api/RetryAgent", "label": "RetryAgent" }
]
},
{
"label": "Web Standards",
"items": [
{ "link": "/api/Fetch", "label": "Fetch" },
{ "link": "/api/EventSource", "label": "EventSource" },
{ "link": "/api/WebSocket", "label": "WebSocket" },
{ "link": "/api/Cookies", "label": "Cookies" },
{ "link": "/api/CacheStorage", "label": "CacheStorage" },
{ "link": "/api/ContentType", "label": "MIME Type Parsing" }
]
},
{
"label": "Mocking",
"items": [
{ "link": "/api/MockClient", "label": "MockClient" },
{ "link": "/api/MockPool", "label": "MockPool" },
{ "link": "/api/MockAgent", "label": "MockAgent" },
{ "link": "/api/SnapshotAgent", "label": "SnapshotAgent" },
{ "link": "/api/MockCallHistory", "label": "MockCallHistory" },
{
"link": "/api/MockCallHistoryLog",
"label": "MockCallHistoryLog"
},
{ "link": "/api/MockErrors", "label": "MockErrors" }
]
},
{
"label": "Interceptors",
"items": [
{ "link": "/api/Interceptors", "label": "Interceptors" }
]
},
{
"label": "Handlers",
"items": [
{ "link": "/api/RedirectHandler", "label": "RedirectHandler" },
{ "link": "/api/RetryHandler", "label": "RetryHandler" }
]
},
{
"label": "Diagnostics & Utilities",
"items": [
{ "link": "/api/Errors", "label": "Errors" },
{
"link": "/api/DiagnosticsChannel",
"label": "Diagnostics Channel Support"
},
{ "link": "/api/Debug", "label": "Debug" },
{ "link": "/api/Util", "label": "Util" },
{
"link": "/api/GlobalInstallation",
"label": "Global Installation"
},
{ "link": "/api/api-lifecycle", "label": "API Lifecycle" }
]
}
]
},
{
"groupName": "Best Practices",
"items": [
{
"link": "/best-practices/undici-vs-builtin-fetch",
"label": "Undici vs. Built-in Fetch"
},
{
"link": "/best-practices/migrating-from-v7-to-v8",
"label": "Migrating from Undici 7 to 8"
},
{ "link": "/best-practices/proxy", "label": "Proxy" },
{
"link": "/best-practices/client-certificate",
"label": "Client Certificate"
},
{
"link": "/best-practices/writing-tests",
"label": "Writing Tests"
},
{
"link": "/best-practices/mocking-request",
"label": "Mocking Request"
},
{ "link": "/best-practices/crawling", "label": "Crawling" }
]
}
]
}
node_modules/undici/docs/docs/type-map.json
Generated Vendored
+79
View File
@@ -0,0 +1,79 @@
{
"AbortError": "/api/Errors.md#class-aborterror",
"Agent": "/api/Agent.md#class-agent",
"AgentDispatchOptions": "/api/Agent.md#agentdispatchoptions-handler",
"AgentOptions": "/api/Agent.md#new-agentoptions",
"BalancedPool": "/api/BalancedPool.md#class-balancedpool",
"BalancedPoolOptions": "/api/BalancedPool.md#parameter-balancedpooloptions",
"BodyMixin": "/api/Fetch.md#new-formdata",
"Buffer": "https://nodejs.org/api/buffer.html#class-buffer",
"BuildOptions": "/api/Connector.md#buildconnectoroptions",
"CacheKey": "/api/CacheStore.md#cachekey",
"CacheStore": "/api/CacheStore.md#new-memorycachestoreoptions",
"CacheValue": "/api/CacheStore.md#cachevalue",
"ClientDestroyedError": "/api/Errors.md#class-clientdestroyederror",
"ClientOptions": "/api/Client.md#new-clienturl-options",
"ClientStats": "/api/ClientStats.md#class-clientstats",
"ConnectOptions": "/api/Dispatcher.md#class-dispatcher",
"Cookie": "/api/Cookies.md#cookie",
"DispatchController": "/api/Dispatcher.md#class-dispatcher",
"DispatchHandler": "/api/Dispatcher.md#class-dispatcher",
"DispatchOptions": "/api/Dispatcher.md#class-dispatcher",
"Dispatcher": "/api/Dispatcher.md#class-dispatcher",
"Duplex": "https://nodejs.org/api/stream.html#class-streamduplex",
"EnvHttpProxyAgent": "/api/EnvHttpProxyAgent.md#class-envhttpproxyagent",
"EnvHttpProxyAgentOptions": "/api/EnvHttpProxyAgent.md#new-envhttpproxyagentoptions",
"EventEmitter": "https://nodejs.org/api/events.html#class-eventemitter",
"GetResult": "/api/CacheStore.md#getresult",
"H2CClientOptions": "/api/H2CClient.md#new-h2cclienturl-options",
"HeadersInit": "https://developer.mozilla.org/docs/Web/API/Headers/Headers",
"InvalidArgumentError": "/api/Errors.md#class-invalidargumenterror",
"Iterable": "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Iteration_protocols",
"MaxOriginsReachedError": "/api/Errors.md#class-maxoriginsreachederror",
"MockAgent": "/api/MockAgent.md#class-mockagent",
"MockAgentOptions": "/api/MockAgent.md#parameter-mockagentoptions",
"MockCallHistory": "/api/MockCallHistory.md#class-mockcallhistory",
"MockCallHistoryLog": "/api/MockCallHistoryLog.md#class-mockcallhistorylog",
"MockClient": "/api/MockClient.md#class-mockclient",
"MockClientOptions": "/api/MockClient.md#parameter-mockclientoptions",
"MockInterceptor": "/api/MockPool.md#return-mockinterceptor",
"MockInterceptor.Options": "/api/MockPool.md#parameter-mockpoolinterceptoptions",
"MockPool": "/api/MockPool.md#class-mockpool",
"MockPoolInterceptOptions": "/api/MockPool.md#parameter-mockpoolinterceptoptions",
"MockPoolOptions": "/api/MockPool.md#parameter-mockpooloptions",
"MockResponseOptions": "/api/MockPool.md#parameter-mockresponseoptions",
"MockScope": "/api/MockPool.md#return-mockscope",
"PendingInterceptor": "/api/MockAgent.md#new-mockagentoptions",
"PipelineOptions": "/api/Dispatcher.md#class-dispatcher",
"Pool": "/api/Pool.md#class-pool",
"PoolOptions": "/api/Pool.md#new-poolurl-options",
"PoolStats": "/api/PoolStats.md#class-poolstats",
"ProxyAgent": "/api/ProxyAgent.md#class-proxyagent",
"ProxyAgentOptions": "/api/ProxyAgent.md#new-proxyagentoptions",
"Readable": "https://nodejs.org/api/stream.html#class-streamreadable",
"Record": "https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type",
"RequestInit": "/api/Fetch.md#new-formdata",
"RequestOptions": "/api/Dispatcher.md#class-dispatcher",
"ResponseInit": "/api/Fetch.md#new-formdata",
"RetryContext": "/api/RetryHandler.md#retrycontext",
"RetryHandler": "/api/RetryHandler.md#class-retryhandler",
"RetryHandlers": "/api/RetryHandler.md#parameter-retryhandlers",
"RetryOptions": "/api/RetryHandler.md#retryoptions",
"RetryState": "/api/RetryHandler.md#retrystate",
"RoundRobinPoolOptions": "/api/RoundRobinPool.md#parameter-roundrobinpooloptions",
"SnapshotRecorder": "/api/SnapshotAgent.md#new-snapshotagentoptions",
"Socket": "https://nodejs.org/api/net.html#class-netsocket",
"SocketInfo": "/api/Errors.md#new-requestretryerrormessage-code-options",
"StreamOptions": "/api/Dispatcher.md#class-dispatcher",
"TLSSocket": "https://nodejs.org/api/tls.html#class-tlstlssocket",
"UndiciError": "/api/Errors.md#class-undicierror",
"UndiciHeaders": "/api/Dispatcher.md#class-dispatcher",
"UpgradeOptions": "/api/Dispatcher.md#class-dispatcher",
"UrlObject": "/index.md#urlobject",
"WebSocketInit": "/api/WebSocket.md#new-websocketurl-protocols",
"WebSocketStreamOptions": "/api/WebSocket.md#new-websocketurl-protocols",
"Writable": "https://nodejs.org/api/stream.html#class-streamwritable",
"buildConnector.BuildOptions": "/api/Connector.md#buildconnectoroptions",
"net.Socket": "https://nodejs.org/api/net.html#class-netsocket",
"stream.Readable": "https://nodejs.org/api/stream.html#class-streamreadable"
}