undici 8.5.0 → 8.7.0

package/README.md

@@ -717,8 +717,9 @@ 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`. Also it is important to pass `blocking: false` to the
-request options to properly pipeline requests.
+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.

package/docs/docs/api/Agent.md

@@ -1,87 +1,291 @@
 # Agent
 
-Extends: `undici.Dispatcher`
+<!--introduced_in=v3.2.0-->
+<!--type=module-->
+<!-- source_link=lib/dispatcher/agent.js -->
+
+> Stability: 2 - Stable
+
+An `Agent` dispatches requests against multiple different origins, creating and
+reusing a per-origin [`Pool`][] (or [`Client`][]) on demand. It is the default
+dispatcher used by [`request`][], [`stream`][], and [`fetch`][] when no explicit
+dispatcher is supplied.
+
+Requests are not guaranteed to be dispatched in their order of invocation.
+
+```mjs
+import { Agent, setGlobalDispatcher } from 'undici'
+
+const agent = new Agent({ connections: 10 })
+setGlobalDispatcher(agent)
+```
+
+## Class: `Agent`
+
+<!-- YAML
+added: v3.2.0
+-->
+
+* Extends: {Dispatcher}
+
+`Agent` keeps an internal map of origins to dispatchers. The first request to a
+given origin lazily creates a dispatcher through the configured `factory`, and
+subsequent requests to the same origin reuse it. Idle dispatchers are closed
+automatically once they have no open connections and are no longer busy.
+
+### `new Agent([options])`
+
+<!-- YAML
+added: v3.2.0
+changes:
+  - version: v7.16.0
+    pr-url: https://github.com/nodejs/undici/pull/4365
+    description: Added the `maxOrigins` option to cap the number of origins.
+-->
+
+* `options` {AgentOptions} (optional) Extends {PoolOptions}.
+  * `factory` {Function} Builds the dispatcher used for a given origin. When the
+    resolved options contain `connections: 1`, the default factory creates a
+    {Client}; otherwise it creates a {Pool}. **Default:** `(origin, opts) => new Pool(origin, opts)`.
+    * `origin` {URL|string} The origin to create a dispatcher for.
+    * `opts` {Object} The resolved options for the new dispatcher.
+    * Returns: {Dispatcher}
+  * `maxOrigins` {number} Limits the total number of distinct origins that may
+    receive requests at the same time. A {MaxOriginsReachedError} is thrown when
+    a request targets a new origin once the limit is reached. When set to
+    `Infinity`, no limit is enforced. Must be a number greater than `0`.
+    **Default:** `Infinity`.
+
+`Agent` inherits all {PoolOptions} (and therefore all {ClientOptions}). The
+per-origin {Pool} it creates uses the default unlimited `connections`, so
+concurrent requests to the same origin are spread across separate {Client}
+instances on separate sockets.
 
-Agent allows dispatching requests against multiple different origins.
+> [!NOTE]
+> Because each concurrent request to an origin may use a different {Client},
+> HTTP/2 multiplexing on a shared session does not apply unless `connections` is
+> set to a small value (for example `connections: 1`). See {PoolOptions} and
+> {ClientOptions} for the full set of inherited options such as `allowH2`
+> (default `true`) and `maxConcurrentStreams` (default `100`).
 
-Requests are not guaranteed to be dispatched in order of invocation.
+### `agent.closed`
 
-## `new undici.Agent([options])`
+<!-- YAML
+added: v3.2.0
+-->
 
-Arguments:
+* Type: {boolean}
 
-* **options** `AgentOptions` (optional)
+`true` after [`agent.close()`][] has been called.
 
-Returns: `Agent`
+### `agent.destroyed`
 
-### Parameter: `AgentOptions`
+<!-- YAML
+added: v3.2.0
+-->
 
-Extends: [`PoolOptions`](/docs/docs/api/Pool.md#parameter-pooloptions)
+* Type: {boolean}
 
-* **factory** `(origin: URL, opts: Object) => Dispatcher` - Default: `(origin, opts) => new Pool(origin, opts)`
-* **maxOrigins** `number` (optional) - Default: `Infinity` - Limits the total number of origins that can receive requests at a time, throwing an `MaxOriginsReachedError` error when attempting to dispatch when the max is reached. If `Infinity`, no limit is enforced.
+`true` after [`agent.destroy()`][] has been called, or after [`agent.close()`][]
+has been called and the shutdown has completed.
 
-> [!NOTE]
-> Like `Pool`, `Agent` inherits all [`ClientOptions`](/docs/docs/api/Client.md#parameter-clientoptions). `allowH2` defaults to `true` and `maxConcurrentStreams` to `100`. The per-origin `Pool` it creates uses the default unlimited `connections`, so concurrent requests to the same origin land on separate `Client` instances and separate TCP/TLS sockets — HTTP/2 multiplexing on a shared session does not apply unless `connections` is set to a small value. See [`PoolOptions`](/docs/docs/api/Pool.md#parameter-pooloptions).
+### `agent.stats`
+
+<!-- YAML
+added: v7.9.0
+-->
+
+* Type: {Record<string, ClientStats|PoolStats>}
+
+Aggregate statistics for the agent, keyed by origin. Each value is the
+[`ClientStats`][] or [`PoolStats`][] object reported by the dispatcher currently
+serving that origin. Origins whose dispatcher does not expose `stats` are
+omitted.
+
+```mjs
+import { Agent } from 'undici'
+
+const agent = new Agent()
+await agent.request({ origin: 'http://localhost:3000', path: '/', method: 'GET' })
+console.log(agent.stats)
+// { 'http://localhost:3000': PoolStats { ... } }
+```
+
+### `agent.dispatch(options, handler)`
+
+<!-- YAML
+added: v3.2.0
+-->
+
+* `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.
+
+Routes the request to the dispatcher for `options.origin`, creating one through
+the `factory` if needed. Throws an {InvalidArgumentError} when `options.origin`
+is not a non-empty string or {URL}, and a {MaxOriginsReachedError} when a new
+origin would exceed `maxOrigins`. Implements [`Dispatcher.dispatch()`][].
+
+### `agent.close([callback])`
+
+<!-- YAML
+added: v3.2.0
+-->
+
+* `callback` {Function} (optional) Invoked once every per-origin dispatcher has
+  closed. When omitted, a {Promise} is returned.
+* Returns: {Promise|void}
+
+Gracefully closes the agent and every dispatcher it owns, waiting for in-flight
+requests to complete. Implements [`Dispatcher.close()`][].
+
+### `agent.destroy([error[, callback]])`
+
+<!-- YAML
+added: v3.2.0
+-->
+
+* `error` {Error} (optional) The error to abort pending requests with.
+* `callback` {Function} (optional) Invoked once every per-origin dispatcher has
+  been destroyed. When omitted, a {Promise} is returned.
+* Returns: {Promise|void}
+
+Forcefully destroys the agent and every dispatcher it owns, aborting all pending
+requests. Implements [`Dispatcher.destroy()`][].
+
+### `agent.connect(options[, callback])`
+
+<!-- YAML
+added: v3.2.0
+-->
+
+See [`Dispatcher.connect()`][]. The request is routed to the dispatcher for
+`options.origin`.
+
+### `agent.pipeline(options, handler)`
 
-## Instance Properties
+<!-- YAML
+added: v3.2.0
+-->
 
-### `Agent.closed`
+See [`Dispatcher.pipeline()`][]. The request is routed to the dispatcher for
+`options.origin`.
 
-Implements [Client.closed](/docs/docs/api/Client.md#clientclosed)
+### `agent.request(options[, callback])`
 
-### `Agent.destroyed`
+<!-- YAML
+added: v3.2.0
+-->
 
-Implements [Client.destroyed](/docs/docs/api/Client.md#clientdestroyed)
+See [`Dispatcher.request()`][]. The request is routed to the dispatcher for
+`options.origin`.
 
-## Instance Methods
+```mjs
+import { Agent } from 'undici'
 
-### `Agent.close([callback])`
+const agent = new Agent()
+const { statusCode, body } = await agent.request({
+  origin: 'http://localhost:3000',
+  path: '/',
+  method: 'GET',
+})
 
-Implements [`Dispatcher.close([callback])`](/docs/docs/api/Dispatcher.md#dispatcherclosecallback-promise).
+console.log('response received', statusCode)
+console.log('data', await body.text())
+```
 
-### `Agent.destroy([error, callback])`
+### `agent.stream(options, factory[, callback])`
 
-Implements [`Dispatcher.destroy([error, callback])`](/docs/docs/api/Dispatcher.md#dispatcherdestroyerror-callback-promise).
+<!-- YAML
+added: v3.2.0
+-->
 
-### `Agent.dispatch(options, handler: AgentDispatchOptions)`
+See [`Dispatcher.stream()`][]. The request is routed to the dispatcher for
+`options.origin`.
 
-Implements [`Dispatcher.dispatch(options, handler)`](/docs/docs/api/Dispatcher.md#dispatcherdispatchoptions-handler).
+### `agent.upgrade(options[, callback])`
 
-#### Parameter: `AgentDispatchOptions`
+<!-- YAML
+added: v3.2.0
+-->
 
-Extends: [`DispatchOptions`](/docs/docs/api/Dispatcher.md#parameter-dispatchoptions)
+See [`Dispatcher.upgrade()`][]. The request is routed to the dispatcher for
+`options.origin`.
 
-* **origin** `string | URL`
+### Event: `'connect'`
 
-Implements [`Dispatcher.destroy([error, callback])`](/docs/docs/api/Dispatcher.md#dispatcherdestroyerror-callback-promise).
+<!-- YAML
+added: v6.6.0
+-->
 
-### `Agent.connect(options[, callback])`
+* `origin` {URL}
+* `targets` {Array<Dispatcher>} The dispatchers involved, starting with this
+  `Agent` followed by the per-origin dispatcher chain.
 
-See [`Dispatcher.connect(options[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherconnectoptions-callback).
+Emitted when a socket has been created for an origin and is ready to receive
+requests. Forwarded from the underlying dispatcher's [`'connect'`][] event.
 
-### `Agent.dispatch(options, handler)`
+### Event: `'disconnect'`
 
-Implements [`Dispatcher.dispatch(options, handler)`](/docs/docs/api/Dispatcher.md#dispatcherdispatchoptions-handler).
+<!-- YAML
+added: v6.6.0
+-->
 
-### `Agent.pipeline(options, handler)`
+* `origin` {URL}
+* `targets` {Array<Dispatcher>} The dispatchers involved, starting with this
+  `Agent`.
+* `error` {Error}
 
-See [`Dispatcher.pipeline(options, handler)`](/docs/docs/api/Dispatcher.md#dispatcherpipelineoptions-handler).
+Emitted when a socket for an origin has disconnected. Forwarded from the
+underlying dispatcher's [`'disconnect'`][] event.
 
-### `Agent.request(options[, callback])`
+### Event: `'connectionError'`
 
-See [`Dispatcher.request(options [, callback])`](/docs/docs/api/Dispatcher.md#dispatcherrequestoptions-callback).
+<!-- YAML
+added: v6.6.0
+-->
 
-### `Agent.stream(options, factory[, callback])`
+* `origin` {URL}
+* `targets` {Array<Dispatcher>} The dispatchers involved, starting with this
+  `Agent`.
+* `error` {Error}
 
-See [`Dispatcher.stream(options, factory[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherstreamoptions-factory-callback).
+Emitted when a connection attempt for an origin fails. Forwarded from the
+underlying dispatcher's [`'connectionError'`][] event.
 
-### `Agent.upgrade(options[, callback])`
+### Event: `'drain'`
 
-See [`Dispatcher.upgrade(options[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherupgradeoptions-callback).
+<!-- YAML
+added: v6.6.0
+-->
 
-### `Agent.stats()`
+* `origin` {URL}
+* `targets` {Array<Dispatcher>} The dispatchers involved, starting with this
+  `Agent`.
 
-Returns an object of stats by origin in the format of `Record<string, TClientStats | TPoolStats>`
+Emitted when an origin's dispatcher is no longer busy and can accept more
+requests. Forwarded from the underlying dispatcher's [`'drain'`][] event.
 
-See [`PoolStats`](/docs/docs/api/PoolStats.md) and [`ClientStats`](/docs/docs/api/ClientStats.md).
+[`'connect'`]: Dispatcher.md#event-connect
+[`'connectionError'`]: Dispatcher.md#event-connectionerror
+[`'disconnect'`]: Dispatcher.md#event-disconnect
+[`'drain'`]: Dispatcher.md#event-drain
+[`Client`]: Client.md#class-client
+[`ClientStats`]: ClientStats.md
+[`Dispatcher.close()`]: Dispatcher.md#dispatcherclosecallback-promise
+[`Dispatcher.connect()`]: Dispatcher.md#dispatcherconnectoptions-callback
+[`Dispatcher.destroy()`]: Dispatcher.md#dispatcherdestroyerror-callback-promise
+[`Dispatcher.dispatch()`]: Dispatcher.md#dispatcherdispatchoptions-handler
+[`Dispatcher.pipeline()`]: Dispatcher.md#dispatcherpipelineoptions-handler
+[`Dispatcher.request()`]: Dispatcher.md#dispatcherrequestoptions-callback
+[`Dispatcher.stream()`]: Dispatcher.md#dispatcherstreamoptions-factory-callback
+[`Dispatcher.upgrade()`]: Dispatcher.md#dispatcherupgradeoptions-callback
+[`Pool`]: Pool.md#class-pool
+[`PoolStats`]: PoolStats.md
+[`agent.close()`]: #agentclosecallback
+[`agent.destroy()`]: #agentdestroyerror-callback
+[`fetch`]: Fetch.md
+[`request`]: Dispatcher.md#dispatcherrequestoptions-callback
+[`stream`]: Dispatcher.md#dispatcherstreamoptions-factory-callback