Zwischen Commit
This commit is contained in:
erik committed
1 parent
4fc5acfebb
commit
18d04e2c4a
1 file changed
+291
+291
@@ -0,0 +1,291 @@
|
||||
# Agent
|
||||
|
||||
<!--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}). Each
|
||||
origin gets a separate {Pool}, with `connections` acting as the maximum number
|
||||
of clients that pool may create.
|
||||
|
||||
> [!NOTE]
|
||||
> For an h2-capable HTTPS origin, the per-origin pool waits for the first TLS
|
||||
> connection to finish ALPN negotiation. If the server selects h2, concurrent
|
||||
> requests share that session up to `maxConcurrentStreams`. If it selects
|
||||
> HTTP/1.1, normal connection fan-out resumes up to `connections`. See
|
||||
> {PoolOptions} and {ClientOptions} for inherited options such as `allowH2`
|
||||
> (default `true`) and `maxConcurrentStreams` (default `100`).
|
||||
|
||||
### `agent.closed`
|
||||
|
||||
<!-- YAML
|
||||
added: v3.2.0
|
||||
-->
|
||||
|
||||
* Type: {boolean}
|
||||
|
||||
`true` after [`agent.close()`][] has been called.
|
||||
|
||||
### `agent.destroyed`
|
||||
|
||||
<!-- YAML
|
||||
added: v3.2.0
|
||||
-->
|
||||
|
||||
* Type: {boolean}
|
||||
|
||||
`true` after [`agent.destroy()`][] has been called, or after [`agent.close()`][]
|
||||
has been called and the shutdown has completed.
|
||||
|
||||
### `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)`
|
||||
|
||||
<!-- YAML
|
||||
added: v3.2.0
|
||||
-->
|
||||
|
||||
See [`Dispatcher.pipeline()`][]. The request is routed to the dispatcher for
|
||||
`options.origin`.
|
||||
|
||||
### `agent.request(options[, callback])`
|
||||
|
||||
<!-- YAML
|
||||
added: v3.2.0
|
||||
-->
|
||||
|
||||
See [`Dispatcher.request()`][]. The request is routed to the dispatcher for
|
||||
`options.origin`.
|
||||
|
||||
```mjs
|
||||
import { Agent } from 'undici'
|
||||
|
||||
const agent = new Agent()
|
||||
const { statusCode, body } = await agent.request({
|
||||
origin: 'http://localhost:3000',
|
||||
path: '/',
|
||||
method: 'GET',
|
||||
})
|
||||
|
||||
console.log('response received', statusCode)
|
||||
console.log('data', await body.text())
|
||||
```
|
||||
|
||||
### `agent.stream(options, factory[, callback])`
|
||||
|
||||
<!-- YAML
|
||||
added: v3.2.0
|
||||
-->
|
||||
|
||||
See [`Dispatcher.stream()`][]. The request is routed to the dispatcher for
|
||||
`options.origin`.
|
||||
|
||||
### `agent.upgrade(options[, callback])`
|
||||
|
||||
<!-- YAML
|
||||
added: v3.2.0
|
||||
-->
|
||||
|
||||
See [`Dispatcher.upgrade()`][]. The request is routed to the dispatcher for
|
||||
`options.origin`.
|
||||
|
||||
### Event: `'connect'`
|
||||
|
||||
<!-- YAML
|
||||
added: v6.6.0
|
||||
-->
|
||||
|
||||
* `origin` {URL}
|
||||
* `targets` {Array<Dispatcher>} The dispatchers involved, starting with this
|
||||
`Agent` followed by the per-origin dispatcher chain.
|
||||
|
||||
Emitted when a socket has been created for an origin and is ready to receive
|
||||
requests. Forwarded from the underlying dispatcher's [`'connect'`][] event.
|
||||
|
||||
### Event: `'disconnect'`
|
||||
|
||||
<!-- YAML
|
||||
added: v6.6.0
|
||||
-->
|
||||
|
||||
* `origin` {URL}
|
||||
* `targets` {Array<Dispatcher>} The dispatchers involved, starting with this
|
||||
`Agent`.
|
||||
* `error` {Error}
|
||||
|
||||
Emitted when a socket for an origin has disconnected. Forwarded from the
|
||||
underlying dispatcher's [`'disconnect'`][] event.
|
||||
|
||||
### Event: `'connectionError'`
|
||||
|
||||
<!-- YAML
|
||||
added: v6.6.0
|
||||
-->
|
||||
|
||||
* `origin` {URL}
|
||||
* `targets` {Array<Dispatcher>} The dispatchers involved, starting with this
|
||||
`Agent`.
|
||||
* `error` {Error}
|
||||
|
||||
Emitted when a connection attempt for an origin fails. Forwarded from the
|
||||
underlying dispatcher's [`'connectionError'`][] event.
|
||||
|
||||
### Event: `'drain'`
|
||||
|
||||
<!-- YAML
|
||||
added: v6.6.0
|
||||
-->
|
||||
|
||||
* `origin` {URL}
|
||||
* `targets` {Array<Dispatcher>} The dispatchers involved, starting with this
|
||||
`Agent`.
|
||||
|
||||
Emitted when an origin's dispatcher is no longer busy and can accept more
|
||||
requests. Forwarded from the underlying dispatcher's [`'drain'`][] event.
|
||||
|
||||
[`'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
|
||||
Reference in new issue
Block a user