{ "type": "module", "source": "doc/api/api-retryagent.md", "modules": [ { "textRaw": "RetryAgent", "name": "retryagent", "introduced_in": "v6.7.0", "type": "module", "stability": 2, "stabilityText": "Stable", "desc": "

A Dispatcher that automatically retries failed requests by wrapping\nanother dispatcher with the retry logic of RetryHandler. Requests that fail\nwith a retryable status code or transport error are re-dispatched according to\nthe configured retry policy.

\n
import { RetryAgent } from 'undici'\n
", "classes": [ { "textRaw": "Class: `RetryAgent`", "name": "RetryAgent", "type": "class", "meta": { "added": [ "v6.7.0" ], "changes": [] }, "desc": "\n

Wraps an existing dispatcher and applies retry behaviour to every request it\ndispatches. Lifecycle methods such as retryAgent.close() and\nretryAgent.destroy() are forwarded to the wrapped dispatcher.

", "signatures": [ { "textRaw": "`new RetryAgent(dispatcher[, options])`", "name": "RetryAgent", "type": "ctor", "meta": { "added": [ "v6.7.0" ], "changes": [] }, "params": [ { "textRaw": "`dispatcher` {Dispatcher} The dispatcher to wrap and add retry behaviour to.", "name": "dispatcher", "type": "Dispatcher", "desc": "The dispatcher to wrap and add retry behaviour to." }, { "textRaw": "`options` {RetryOptions} (optional)", "name": "options", "type": "RetryOptions", "desc": "(optional)", "options": [ { "textRaw": "`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`.", "name": "throwOnError", "type": "boolean", "default": "`true`", "desc": "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." }, { "textRaw": "`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.", "name": "retry", "type": "Function", "desc": "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.", "options": [ { "textRaw": "`err` {Error} The error that caused the retry attempt.", "name": "err", "type": "Error", "desc": "The error that caused the retry attempt." }, { "textRaw": "`context` {RetryContext} The current retry context.", "name": "context", "type": "RetryContext", "desc": "The current retry context.", "options": [ { "textRaw": "`state` {RetryState} The mutable retry state.", "name": "state", "type": "RetryState", "desc": "The mutable retry state.", "options": [ { "textRaw": "`counter` {number} The number of retries performed so far.", "name": "counter", "type": "number", "desc": "The number of retries performed so far." } ] }, { "textRaw": "`opts` {Object} The options passed to the retry handler, combining the dispatch options with `retryOptions`.", "name": "opts", "type": "Object", "desc": "The options passed to the retry handler, combining the dispatch options with `retryOptions`." } ] }, { "textRaw": "`callback` {Function} Called to continue. Pass an `Error` to stop retrying, or `null`/`undefined` to perform the next retry.", "name": "callback", "type": "Function", "desc": "Called to continue. Pass an `Error` to stop retrying, or `null`/`undefined` to perform the next retry." } ] }, { "textRaw": "`maxRetries` {number} Maximum number of retries to allow. **Default:** `5`.", "name": "maxRetries", "type": "number", "default": "`5`", "desc": "Maximum number of retries to allow." }, { "textRaw": "`maxTimeout` {number} Maximum number of milliseconds to wait between retries. **Default:** `30000` (30 seconds).", "name": "maxTimeout", "type": "number", "default": "`30000` (30 seconds)", "desc": "Maximum number of milliseconds to wait between retries." }, { "textRaw": "`minTimeout` {number} Initial number of milliseconds to wait before the first retry. **Default:** `500` (half a second).", "name": "minTimeout", "type": "number", "default": "`500` (half a second)", "desc": "Initial number of milliseconds to wait before the first retry." }, { "textRaw": "`timeoutFactor` {number} Factor by which the timeout is multiplied between retries. **Default:** `2`.", "name": "timeoutFactor", "type": "number", "default": "`2`", "desc": "Factor by which the timeout is multiplied between retries." }, { "textRaw": "`retryAfter` {boolean} When `true`, the delay between retries is inferred from the `Retry-After` response header when present. **Default:** `true`.", "name": "retryAfter", "type": "boolean", "default": "`true`", "desc": "When `true`, the delay between retries is inferred from the `Retry-After` response header when present." }, { "textRaw": "`methods` {string}[] HTTP methods that are eligible for retry. **Default:** `['GET', 'HEAD', 'OPTIONS', 'PUT', 'DELETE', 'TRACE']`.", "name": "methods", "type": "string", "default": "`['GET', 'HEAD', 'OPTIONS', 'PUT', 'DELETE', 'TRACE']`", "desc": "[] HTTP methods that are eligible for retry." }, { "textRaw": "`statusCodes` {number}[] HTTP status codes that trigger a retry. **Default:** `[500, 502, 503, 504, 429]`.", "name": "statusCodes", "type": "number", "default": "`[500, 502, 503, 504, 429]`", "desc": "[] HTTP status codes that trigger a retry." }, { "textRaw": "`errorCodes` {string}[] Transport error codes that trigger a retry. **Default:** `['ECONNRESET', 'ECONNREFUSED', 'ENOTFOUND', 'ENETDOWN', 'ENETUNREACH', 'EHOSTDOWN', 'EHOSTUNREACH', 'EPIPE', 'UND_ERR_SOCKET']`.", "name": "errorCodes", "type": "string", "default": "`['ECONNRESET', 'ECONNREFUSED', 'ENOTFOUND', 'ENETDOWN', 'ENETUNREACH', 'EHOSTDOWN', 'EHOSTUNREACH', 'EPIPE', 'UND_ERR_SOCKET']`", "desc": "[] Transport error codes that trigger a retry." } ], "optional": true } ], "desc": "

Creates a new RetryAgent that wraps dispatcher. The options are stored and\nused to construct a RetryHandler for each dispatched request.

\n
import { Agent, RetryAgent } from 'undici'\n\nconst agent = new RetryAgent(new Agent(), {\n  maxRetries: 3,\n  minTimeout: 1000,\n  timeoutFactor: 2,\n})\n\nconst res = await agent.request({\n  method: 'GET',\n  origin: 'http://example.com',\n  path: '/',\n})\n\nconsole.log(res.statusCode)\nconsole.log(await res.body.text())\n
" } ], "methods": [ { "textRaw": "`retryAgent.dispatch(options, handler)`", "name": "dispatch", "type": "method", "meta": { "added": [ "v6.7.0" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`options` {DispatchOptions} The dispatch options, identical to `dispatcher.dispatch()`.", "name": "options", "type": "DispatchOptions", "desc": "The dispatch options, identical to `dispatcher.dispatch()`." }, { "textRaw": "`handler` {DispatchHandler} The dispatch handler.", "name": "handler", "type": "DispatchHandler", "desc": "The dispatch handler." } ], "return": { "textRaw": "Returns: {boolean}", "name": "return", "type": "boolean" } } ], "desc": "

Dispatches options through the wrapped dispatcher, installing a\nRetryHandler that applies the configured retry policy before delegating to\nhandler. Returns false if the dispatcher is busy and the caller should wait\nbefore dispatching again, otherwise true.

" }, { "textRaw": "`retryAgent.close()`", "name": "close", "type": "method", "meta": { "added": [ "v6.7.0" ], "changes": [] }, "signatures": [ { "params": [], "return": { "textRaw": "Returns: {Promise} Resolves when the wrapped dispatcher has closed.", "name": "return", "type": "Promise", "desc": "Resolves when the wrapped dispatcher has closed." } } ], "desc": "

Gracefully closes the wrapped dispatcher, waiting for in-flight requests to\ncomplete. Equivalent to calling dispatcher.close() on the wrapped\ndispatcher.

" }, { "textRaw": "`retryAgent.destroy()`", "name": "destroy", "type": "method", "meta": { "added": [ "v6.7.0" ], "changes": [] }, "signatures": [ { "params": [], "return": { "textRaw": "Returns: {Promise} Resolves when the wrapped dispatcher has been destroyed.", "name": "return", "type": "Promise", "desc": "Resolves when the wrapped dispatcher has been destroyed." } } ], "desc": "

Forcefully destroys the wrapped dispatcher, aborting all pending requests.\nEquivalent to calling dispatcher.destroy() on the wrapped dispatcher.

" } ] } ] } ] }