codekingpro/portable-devtools

1# Class: RetryHandler
2
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 identify
50>the body as stateful and will not retry the request rejecting with the error `UND_ERR_REQ_RETRY`.
51
52Examples:
53
54```js
55const client = new Client(`http://localhost:${server.address().port}`);
56const chunks = [];
57const handler = new RetryHandler(
58  {
59    ...dispatchOptions,
60    retryOptions: {
61      // custom retry function
62      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 headers
88      },
89      onData(chunk) {
90        chunks.push(chunk);
91        return true;
92      },
93      onComplete() {},
94      onError() {
95        // handle error properly
96      },
97    },
98  }
99);
100```
101
102#### Example - Basic RetryHandler with defaults
103
104```js
105const 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