Class: RetryHandler

Extends: undici.DispatcherHandlers

A handler class that implements the retry logic for a request.

new RetryHandler(dispatchOptions, retryHandlers, [retryOptions])

Arguments:

• options Dispatch.DispatchOptions & RetryOptions (required) - It is an intersection of Dispatcher.DispatchOptions and RetryOptions.
• retryHandlers RetryHandlers (required) - Object containing the dispatch to be used on every retry, and handler for handling the dispatch lifecycle.

Returns: retryHandler

Parameter: Dispatch.DispatchOptions & RetryOptions

Extends: Dispatch.DispatchOptions.

RetryOptions

• 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.
• maxRetries number (optional) - Maximum number of retries. Default: 5
• maxTimeout number (optional) - Maximum number of milliseconds to wait before retrying. Default: 30000 (30 seconds)
• minTimeout number (optional) - Minimum number of milliseconds to wait before retrying. Default: 500 (half a second)
• timeoutFactor number (optional) - Factor to multiply the timeout by for each retry attempt. Default: 2
• retryAfter boolean (optional) - It enables automatic retry after the Retry-After header is received. Default: true
• methods string[] (optional) - Array of HTTP methods to retry. Default: ['GET', 'PUT', 'HEAD', 'OPTIONS', 'DELETE']
• statusCodes number[] (optional) - Array of HTTP status codes to retry. Default: [429, 500, 502, 503, 504]
• errorCodes string[] (optional) - Array of Error codes to retry. Default: ['ECONNRESET', 'ECONNREFUSED', 'ENOTFOUND', 'ENETDOWN','ENETUNREACH', 'EHOSTDOWN', 'UND_ERR_SOCKET']

RetryContext

• state: RetryState - Current retry state. It can be mutated.
• opts: Dispatch.DispatchOptions & RetryOptions - Options passed to the retry handler.

RetryState

It represents the retry state for a given request.

• counter: number - Current retry attempt.

Parameter RetryHandlers

• dispatch (options: Dispatch.DispatchOptions, handlers: Dispatch.DispatchHandlers) => Promise<Dispatch.DispatchResponse> (required) - Dispatch function to be called after every retry.
• handler Extends Dispatch.DispatchHandlers (required) - Handler function to be called after the request is successful or the retries are exhausted.

Note: The RetryHandler does not retry over stateful bodies (e.g. streams, AsyncIterable) as those, once consumed, are left in a state that cannot be reutilized. For these situations the RetryHandler will identify the body as stateful and will not retry the request rejecting with the error UND_ERR_REQ_RETRY.

Examples:

const client = new Client(`http://localhost:${server.address().port}`);
const chunks = [];
const handler = new RetryHandler(
  {
    ...dispatchOptions,
    retryOptions: {
      // custom retry function
      retry: function (err, state, callback) {
        counter++;

        if (err.code && err.code === "UND_ERR_DESTROYED") {
          callback(err);
          return;
        }

        if (err.statusCode === 206) {
          callback(err);
          return;
        }

        setTimeout(() => callback(null), 1000);
      },
    },
  },
  {
    dispatch: (...args) => {
      return client.dispatch(...args);
    },
    handler: {
      onConnect() {},
      onBodySent() {},
      onHeaders(status, _rawHeaders, resume, _statusMessage) {
        // do something with headers
      },
      onData(chunk) {
        chunks.push(chunk);
        return true;
      },
      onComplete() {},
      onError() {
        // handle error properly
      },
    },
  }
);

Example - Basic RetryHandler with defaults

const client = new Client(`http://localhost:${server.address().port}`);
const handler = new RetryHandler(dispatchOptions, {
  dispatch: client.dispatch.bind(client),
  handler: {
    onConnect() {},
    onBodySent() {},
    onHeaders(status, _rawHeaders, resume, _statusMessage) {},
    onData(chunk) {},
    onComplete() {},
    onError(err) {},
  },
});