137 lines
4.9 KiB
Plaintext
137 lines
4.9 KiB
Plaintext
# 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
|