GitButler Workspace Commit
This is placeholder commit and will be replaced by a merge of your virtual branches. Due to GitButler managing multiple virtual branches, you cannot switch back and forth between git branches and virtual branches easily. If you switch to another branch, GitButler will need to be reinitialized. If you commit on this branch, GitButler will throw it away. For more information about what we're doing here, check out our docs: https://docs.gitbutler.com/features/branch-management/integration-branch
This commit is contained in:
GitButler authored and Erik Dunin committed
commit
bc30f2900b
49 files changed
+2449
-5738
No files matched your search
+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