-
Notifications
You must be signed in to change notification settings - Fork 513
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
refactor: Client.clients & Agent is a Client.
Refs: #616
- Loading branch information
Showing
18 changed files
with
1,366 additions
and
1,023 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,119 +1,95 @@ | ||
# Agent | ||
|
||
## `new undici.Agent(opts)` | ||
Extends: `undici.Dispatcher` | ||
|
||
Arguments: | ||
Agent allow dispatching requests against multiple different origins. | ||
|
||
* **factory** - Default: `(origin, opts) => new Pool(origin, opts)` | ||
* // TODO: document rest opts? | ||
Requests are not guaranteed to be dispatched in order of invocation. | ||
|
||
Returns: `Agent` | ||
## `new undici.Agent([options])` | ||
|
||
Returns a new Agent instance used for dispatching requests. | ||
Arguments: | ||
|
||
### `Agent.get(origin)` | ||
* **options** `AgentOptions` (optional) | ||
|
||
* origin `string` - A origin to be retrieved from the Agent. | ||
Returns: `Agent` | ||
|
||
This method retrieves Client instances from the Agent. If the client does not exist it is automatically added by calling | ||
the `factory` method passed through the `Agent` constructor. | ||
### Parameter: `AgentOptions` | ||
|
||
### `Agent.dispatch(options, handlers)` | ||
Extends: [`ClientOptions`](docs/api/Pool.md#parameter-pooloptions) | ||
|
||
Dispatches a request. | ||
* **factory** `(origin: URL, opts: Object) => Dispatcher` - Default: `(origin, opts) => new Pool(origin, opts)` | ||
* **maxRedirections** `Integer` - Default: `0`. | ||
|
||
This API is expected to evolve through semver-major versions and is less stable than the preceding higher level APIs. It is primarily intended for library developers who implement higher level APIs on top of this. | ||
## Instance Properties | ||
|
||
Arguments: | ||
### `Agent.closed` | ||
|
||
* **options** `DispatchOptions` | ||
* **handlers** `DispatchHandlers` | ||
Implements [Client.closed](docs/api/Client.md#clientclosed) | ||
|
||
Returns: `void` | ||
### `Agent.connected` | ||
|
||
#### Parameter: `DispatchOptions` | ||
Implements [Client.connected](docs/api/Client.md#clientconnected) | ||
|
||
* **origin** `string | URL` | ||
* **path** `string` | ||
* **method** `string` | ||
* **body** `string | Buffer | Uint8Array | stream.Readable | null` (optional) - Default: `null` | ||
* **headers** `UndiciHeaders` (optional) - Default: `null` | ||
* **idempotent** `boolean` (optional) - Default: `true` if `method` is `'HEAD'` or `'GET'` - Whether the requests can be safely retried or not. If `false` the request won't be sent until all preceeding requests in the pipeline has completed. | ||
* **upgrade** `string | null` (optional) - Default: `method === 'CONNECT' || null` - Upgrade the request. Should be used to specify the kind of upgrade i.e. `'Websocket'`. | ||
### `Agent.destroyed` | ||
|
||
#### Parameter: `DispatchHandlers` | ||
Implements [Client.destroyed](docs/api/Client.md#clientdestroyed) | ||
|
||
* **onConnect** `(abort: () => void) => void` - Invoked before request is dispatched on socket. May be invoked multiple times when a request is retried when the request at the head of the pipeline fails. | ||
* **onError** `(error: Error) => void` - Invoked when an error has occurred. | ||
* **onUpgrade** `(statusCode: number, headers: string[] | null, socket: Duplex) => void` (optional) - Invoked when request is upgraded. Required if `DispatchOptions.upgrade` is defined or `DispatchOptions.method === 'CONNECT'`. | ||
* **onHeaders** `(statusCode: number, headers: string[] | null, resume: () => void) => boolean` - Invoked when statusCode and headers have been received. May be invoked multiple times due to 1xx informational headers. Not required for `upgrade` requests. | ||
* **onData** `(chunk: Buffer) => boolean` - Invoked when response payload data is received. Not required for `upgrade` requests. | ||
* **onComplete** `(trailers: string[] | null) => void` - Invoked when response payload and trailers have been received and the request has completed. Not required for `upgrade` requests. | ||
### `Agent.pending` | ||
|
||
## `agent.close(): Promise` | ||
Implements [Client.pending](docs/api/Client.md#clientpending) | ||
|
||
Returns a `Promise.all` operation closing all of the pool instances in the Agent instance. This calls `pool.close` under the hood. | ||
### `Agent.running` | ||
|
||
## `agent.destroy(): Promise` | ||
Implements [Client.running](docs/api/Client.md#clientrunning) | ||
|
||
Returns a `Promise.all` operation destroying all of the pool instances in the Agent instance. This calls `pool.destroy` under the hood. | ||
### `Agent.size` | ||
|
||
## `undici.setGlobalAgent(agent)` | ||
Implements [Client.size](docs/api/Client.md#clientsize) | ||
|
||
* agent `Agent` | ||
## Instance Methods | ||
|
||
Sets the global agent used by `request`, `pipeline`, and `stream` methods. | ||
The default global agent creates `undici.Pool`s with no max number of | ||
connections. | ||
### `Agent.close([callback])` | ||
|
||
The agent must only **implement** the `Agent` API; not necessary extend from it. | ||
Implements [`Dispatcher.close([callback])`](docs/api/Dispatcher.md#clientclose-callback-). | ||
|
||
## `undici.getGlobalAgent(agent)` | ||
### `Agent.destroy([error, callback])` | ||
|
||
TODO: document | ||
Implements [`Dispatcher.destroy([error, callback])`](docs/api/Dispatcher.md#dispatcher-callback-). | ||
|
||
## `undici.request(url[, opts]): Promise` | ||
### `Agent.dispatch(options, handlers: AgentDispatchOptions)` | ||
|
||
* url `string | URL | object` | ||
* opts `{ agent: Agent } & client.request.opts` | ||
* // TODO: document maxRedirections? | ||
Implements [`Dispatcher.dispatch(options, handlers)`](docs/api/Dispatcher.md#clientdispatchoptions-handlers). | ||
|
||
`url` may contain path. `opts` may not contain path. `opts.method` is `GET` by default. | ||
Calls `pool.request(opts)` on the pool returned from either the globalAgent (see [setGlobalAgent](#undicisetglobalagentagent)) or the agent passed to the `opts` argument. | ||
#### Parameter: `AgentDispatchOptions` | ||
|
||
Returns a promise with the result of the `request` method. | ||
Extends: [`DispatchOptions``](docs/api/Dispatcher.md#parameter-dispatchoptions) | ||
|
||
## `undici.stream(url, opts, factory): Promise` | ||
* **origin** `string | URL` | ||
* **maxRedirections** `Integer`. | ||
|
||
* url `string | URL | object` | ||
* opts `{ agent: Agent } & client.stream.opts` | ||
* factory `client.stream.factory` | ||
* // TODO: document maxRedirections? | ||
Implements [`Dispatcher.destroy([error, callback])`](docs/api/Dispatcher.md#dispatcher-callback-). | ||
|
||
`url` may contain path. `opts` may not contain path. | ||
See [client.stream](docs/api/Client.md#clientstreamoptions-factory--callback) for details on the `opts` and `factory` arguments. | ||
Calls `pool.stream(opts, factory)` on the pool returned from either the globalAgent (see [setGlobalAgent](#undicisetglobalagentagent)) or the agent passed to the `opts` argument. | ||
Result is returned in the factory function. See [client.stream](docs/api/Client.md#clientstreamoptions-factory--callback) for more details. | ||
### `Agent.connect(options[, callback])` | ||
|
||
## `undici.pipeline(url, opts, handler): Duplex` | ||
See [`Dispatcher.connect(options[, callback])`](docs/api/Dispatcher.md#clientconnectoptions--callback). | ||
|
||
### `Agent.dispatch(options, handlers)` | ||
|
||
* url `string | URL | object` | ||
* opts `{ agent: Agent } & client.pipeline.opts` | ||
* handler `client.pipeline.handler` | ||
* // TODO: document maxRedirections? | ||
Implements [`Dispatcher.dispatch(options, handlers)`](docs/api/Dispatcher.md#clientdispatchoptions-handlers). | ||
|
||
`url` may contain path. `opts` may not contain path. | ||
### `Agent.pipeline(options, handler)` | ||
|
||
See [client.pipeline](docs/api/Client.md#clientpipelining) for details on the `opts` and `handler` arguments. | ||
See [`Dispatcher.pipeline(options, handler)`](docs/api/Dispatcher.md#clientpipelineoptions-handler). | ||
|
||
Calls `pool.pipeline(opts, factory)` on the pool returned from either the globalAgent (see [setGlobalAgent](#undicisetglobalagentagent)) or the agent passed to the `opts` argument. | ||
### `Agent.request(options[, callback])` | ||
|
||
See [client.pipeline](docs/api/Client.md#clientpipelining) for more details. | ||
See [`Dispatcher.request(options [, callback])`](docs/api/Dispatcher.md#clientrequestoptions--callback). | ||
|
||
### `undici.connect(options[, callback])` | ||
### `Agent.stream(options, factory[, callback])` | ||
|
||
TODO: document | ||
See [`Dispatcher.stream(options, factory[, callback])`](docs/api/Dispatcher.md#clientstreamoptions-factory--callback). | ||
|
||
### `undici.upgrade(options[, callback])` | ||
### `Agent.upgrade(options[, callback])` | ||
|
||
TODO: document | ||
See [`Dispatcher.upgrade(options[, callback])`](docs/api/Dispatcher.md#clientupgradeoptions-callback). |
Oops, something went wrong.