File Explorer

1# Class: RetryHandler2 3Extends: `undici.DispatcherHandlers`4 5A handler class that implements the retry logic for a request.6 7## `new RetryHandler(dispatchOptions, retryHandlers, [retryOptions])`8 9Arguments:10 11- **options** `Dispatch.DispatchOptions & RetryOptions` (required) - It is an intersection of `Dispatcher.DispatchOptions` and `RetryOptions`.12- **retryHandlers** `RetryHandlers` (required) - Object containing the `dispatch` to be used on every retry, and `handler` for handling the `dispatch` lifecycle.13 14Returns: `retryHandler`15 16### Parameter: `Dispatch.DispatchOptions & RetryOptions`17 18Extends: [`Dispatch.DispatchOptions`](Dispatcher.md#parameter-dispatchoptions).19 20#### `RetryOptions`21 22- **retry** `(err: Error, context: RetryContext, callback: (err?: Error | null) => void) => number | null` (optional) - Function to be called after every retry. It should pass error if no more retries should be performed.23- **maxRetries** `number` (optional) - Maximum number of retries. Default: `5`24- **maxTimeout** `number` (optional) - Maximum number of milliseconds to wait before retrying. Default: `30000` (30 seconds)25- **minTimeout** `number` (optional) - Minimum number of milliseconds to wait before retrying. Default: `500` (half a second)26- **timeoutFactor** `number` (optional) - Factor to multiply the timeout by for each retry attempt. Default: `2`27- **retryAfter** `boolean` (optional) - It enables automatic retry after the `Retry-After` header is received. Default: `true`28-29- **methods** `string[]` (optional) - Array of HTTP methods to retry. Default: `['GET', 'PUT', 'HEAD', 'OPTIONS', 'DELETE']`30- **statusCodes** `number[]` (optional) - Array of HTTP status codes to retry. Default: `[429, 500, 502, 503, 504]`31- **errorCodes** `string[]` (optional) - Array of Error codes to retry. Default: `['ECONNRESET', 'ECONNREFUSED', 'ENOTFOUND', 'ENETDOWN','ENETUNREACH', 'EHOSTDOWN', 'UND_ERR_SOCKET']`32 33**`RetryContext`**34 35- `state`: `RetryState` - Current retry state. It can be mutated.36- `opts`: `Dispatch.DispatchOptions & RetryOptions` - Options passed to the retry handler.37 38**`RetryState`**39 40It represents the retry state for a given request.41 42- `counter`: `number` - Current retry attempt.43 44### Parameter `RetryHandlers`45 46- **dispatch** `(options: Dispatch.DispatchOptions, handlers: Dispatch.DispatchHandlers) => Promise<Dispatch.DispatchResponse>` (required) - Dispatch function to be called after every retry.47- **handler** Extends [`Dispatch.DispatchHandlers`](Dispatcher.md#dispatcherdispatchoptions-handler) (required) - Handler function to be called after the request is successful or the retries are exhausted.48 49>__Note__: The `RetryHandler` does not retry over stateful bodies (e.g. streams, AsyncIterable) as those, once consumed, are left in an state that cannot be reutilized. For these situations the `RetryHandler` will identify50>the body as stateful and will not retry the request rejecting with the error `UND_ERR_REQ_RETRY`.51 52Examples:53 54```js55const client = new Client(`http://localhost:${server.address().port}`);56const chunks = [];57const handler = new RetryHandler(58  {59    ...dispatchOptions,60    retryOptions: {61      // custom retry function62      retry: function (err, state, callback) {63        counter++;64 65        if (err.code && err.code === "UND_ERR_DESTROYED") {66          callback(err);67          return;68        }69 70        if (err.statusCode === 206) {71          callback(err);72          return;73        }74 75        setTimeout(() => callback(null), 1000);76      },77    },78  },79  {80    dispatch: (...args) => {81      return client.dispatch(...args);82    },83    handler: {84      onConnect() {},85      onBodySent() {},86      onHeaders(status, _rawHeaders, resume, _statusMessage) {87        // do something with headers88      },89      onData(chunk) {90        chunks.push(chunk);91        return true;92      },93      onComplete() {},94      onError() {95        // handle error properly96      },97    },98  }99);100```101 102#### Example - Basic RetryHandler with defaults103 104```js105const client = new Client(`http://localhost:${server.address().port}`);106const handler = new RetryHandler(dispatchOptions, {107  dispatch: client.dispatch.bind(client),108  handler: {109    onConnect() {},110    onBodySent() {},111    onHeaders(status, _rawHeaders, resume, _statusMessage) {},112    onData(chunk) {},113    onComplete() {},114    onError(err) {},115  },116});117```118