@yanglaofish/fishtools 0.5.2 → 0.6.0

package/node_modules/undici/docs/docs/api/RetryAgent.md

@@ -1,136 +1,45 @@
-# RetryAgent
+# Class: RetryAgent
 
-<!--introduced_in=v6.7.0-->
-<!--type=module-->
-<!-- source_link=lib/dispatcher/retry-agent.js -->
+Extends: `undici.Dispatcher`
 
-> Stability: 2 - Stable
+A `undici.Dispatcher` that allows to automatically retry a request.
+Wraps a `undici.RetryHandler`.
 
-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.
+## `new RetryAgent(dispatcher, [options])`
 
-```mjs
-import { RetryAgent } from 'undici'
-```
-
-## Class: `RetryAgent`
+Arguments:
 
-<!-- YAML
-added: v6.7.0
--->
+* **dispatcher** `undici.Dispatcher` (required) - the dispatcher to wrap
+* **options** `RetryHandlerOptions` (optional) - the options
 
-* Extends: {Dispatcher}
+Returns: `ProxyAgent`
 
-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.
+### Parameter: `RetryHandlerOptions`
 
-### `new RetryAgent(dispatcher[, options])`
+- **retry** `(err: Error, context: RetryContext, callback: (err?: Error | null) => void) => void` (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']`
 
-<!-- YAML
-added: v6.7.0
--->
+**`RetryContext`**
 
-* `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']`.
+- `state`: `RetryState` - Current retry state. It can be mutated.
+- `opts`: `Dispatch.DispatchOptions & RetryOptions` - Options passed to the retry handler.
 
-Creates a new `RetryAgent` that wraps `dispatcher`. The `options` are stored and
-used to construct a [`RetryHandler`][] for each dispatched request.
+Example:
 
-```mjs
+```js
 import { Agent, RetryAgent } from 'undici'
 
-const agent = new RetryAgent(new Agent(), {
-  maxRetries: 3,
-  minTimeout: 1000,
-  timeoutFactor: 2,
-})
+const agent = new RetryAgent(new Agent())
 
-const res = await agent.request({
-  method: 'GET',
-  origin: 'http://example.com',
-  path: '/',
-})
-
-console.log(res.statusCode)
+const res = await agent.request('http://example.com')
+console.log(res.statuCode)
 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

package/node_modules/undici/docs/docs/api/RetryHandler.md

@@ -1,200 +1,117 @@
-# RetryHandler
+# Class: RetryHandler
 
-<!--introduced_in=v5.28.0-->
-<!--type=module-->
-<!-- source_link=lib/handler/retry-handler.js -->
+Extends: `undici.DispatcherHandlers`
 
-> Stability: 2 - Stable
+A handler class that implements the retry logic for a request.
 
-A [`Dispatcher`][] handler that automatically retries a request when it fails
-with a recoverable network error or an eligible HTTP status code. It wraps an
-inner handler and re-dispatches the request, applying an exponential backoff and
-honouring the `Retry-After` response header. When a response is partially
-consumed before the failure, the handler resumes the download with a `Range`
-request guarded by the original `ETag`.
+## `new RetryHandler(dispatchOptions, retryHandlers, [retryOptions])`
 
-The handler is most often used indirectly through [`RetryAgent`][], but it can
-also be supplied directly to [`dispatcher.dispatch()`][] for fine-grained
-control over the retry behaviour.
+Arguments:
 
-```mjs
-import { RetryHandler } from 'undici'
-```
+- **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.
 
-## Class: `RetryHandler`
+Returns: `retryHandler`
 
-<!-- YAML
-added: v5.28.0
--->
+### Parameter: `Dispatch.DispatchOptions & RetryOptions`
 
-* Extends: {DispatchHandler}
+Extends: [`Dispatch.DispatchOptions`](Dispatcher.md#parameter-dispatchoptions).
 
-Implements the [`DispatchHandler`][] interface. An instance is consumed by a
-single dispatch call and forwards the dispatch lifecycle to the inner `handler`,
-re-issuing the request through the supplied `dispatch` function whenever a retry
-is warranted.
+#### `RetryOptions`
 
-> **Note:** The `RetryHandler` does not retry over stateful bodies (for example
-> streams or `AsyncIterable`), because once consumed they cannot be replayed. In
-> these situations the body is identified as stateful and the request is rejected
-> with the `UND_ERR_REQ_RETRY` error instead of being retried.
+- **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']`
 
-### `new RetryHandler(options, retryHandlers)`
+**`RetryContext`**
 
-<!-- YAML
-added: v5.28.0
-changes:
-  - version: v7.0.0
-    pr-url: https://github.com/nodejs/undici/pull/3883
-    description: Reimplemented on top of the new dispatch lifecycle hooks.
--->
+- `state`: `RetryState` - Current retry state. It can be mutated.
+- `opts`: `Dispatch.DispatchOptions & RetryOptions` - Options passed to the retry handler.
 
-* `options` {DispatchOptions} The dispatch options for the request, extended with
-  an optional `retryOptions` field. Type is
-  `DispatchOptions & { retryOptions?: RetryOptions }`.
-  * `retryOptions` {RetryOptions} (optional) Configuration controlling when and
-    how the request is retried. See [`RetryOptions`](#retryoptions).
-* `retryHandlers` {RetryHandlers} The handlers used to drive the retry loop. See
-  [`RetryHandlers`](#parameter-retryhandlers).
-* Returns: {RetryHandler}
+**`RetryState`**
 
-#### `RetryOptions`
+It represents the retry state for a given request.
+
+- `counter`: `number` - Current retry attempt.
+
+### Parameter `RetryHandlers`
 
-* `throwOnError` {boolean} When `true`, an error is thrown on the last retry
-  attempt and propagated to the inner handler; when `false`, the failing response
-  is passed through instead, which is useful when the error body is needed or a
-  custom error handler is in place. **Default:** `true`.
-* `retry` {Function} Callback invoked on every retry iteration to decide whether
-  another attempt should be made. It receives the error, the retry context, and a
-  callback. Call the callback with an `Error` to stop retrying, or with `null` to
-  schedule another attempt. **Default:** the built-in retry strategy described
-  below.
-  * `err` {Error} The error that triggered the retry.
-  * `context` {RetryContext} The current retry context. See
-    [`RetryContext`](#retrycontext).
-  * `callback` {Function} Signals the outcome of this iteration.
-    * `result` {Error|null} (optional) An `Error` to abort retrying, or `null` to
-      retry.
-* `maxRetries` {number} Maximum number of retries allowed. **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} Multiplier applied to the timeout between successive
-  retries to produce an exponential backoff. **Default:** `2`.
-* `retryAfter` {boolean} When `true`, the delay before the next retry is inferred
-  from the `Retry-After` response header when present. **Default:** `true`.
-* `methods` {string[]} HTTP methods that are eligible for retrying. **Default:**
-  `['GET', 'HEAD', 'OPTIONS', 'PUT', 'DELETE', 'TRACE']`.
-* `statusCodes` {number[]} HTTP status codes that trigger a retry. **Default:**
-  `[500, 502, 503, 504, 429]`.
-* `errorCodes` {string[]} Network error codes that trigger a retry. **Default:**
-  `['ECONNRESET', 'ECONNREFUSED', 'ENOTFOUND', 'ENETDOWN', 'ENETUNREACH', 'EHOSTDOWN', 'EHOSTUNREACH', 'EPIPE', 'UND_ERR_SOCKET']`.
-
-The default `retry` strategy computes the delay before the next attempt as
-`minTimeout * timeoutFactor ** (counter - 1)`, capped at `maxTimeout`. When a
-`Retry-After` header is present it takes precedence (interpreted as seconds, or as
-an HTTP date), still capped at `maxTimeout`. The default strategy stops retrying
-once `counter` exceeds `maxRetries`, when the error code is not in `errorCodes`,
-when the method is not in `methods`, or when the response status code is not in
-`statusCodes`.
-
-#### `RetryContext`
-
-* `state` {RetryState} The current retry state. See [`RetryState`](#retrystate).
-* `opts` {DispatchOptions} The dispatch options passed to the handler, including
-  the resolved `retryOptions`. Type is
-  `DispatchOptions & { retryOptions?: RetryOptions }`.
-
-The context object passed as the second argument to the `retry` callback.
-
-#### `RetryState`
-
-* `counter` {number} The current retry attempt, starting at `1` for the first
-  retry.
-
-Represents the retry state for a given request.
-
-#### Parameter: `RetryHandlers`
-
-* `dispatch` {Function} The dispatch function called to (re-)issue the request on
-  every attempt. Type is `(options, handler) => boolean`.
-* `handler` {DispatchHandler} The inner handler invoked once the request succeeds
-  or the retries are exhausted.
-
-### Examples
-
-```mjs
-import { Client, RetryHandler } from 'undici'
-
-const client = new Client(`http://localhost:${server.address().port}`)
-const chunks = []
+- **dispatch** `(options: Dispatch.DispatchOptions, handlers: Dispatch.DispatchHandlers) => Promise<Dispatch.DispatchResponse>` (required) - Dispatch function to be called after every retry.
+- **handler** Extends [`Dispatch.DispatchHandlers`](Dispatcher.md#dispatcherdispatchoptions-handler) (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 an 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:
+
+```js
+const client = new Client(`http://localhost:${server.address().port}`);
+const chunks = [];
 const handler = new RetryHandler(
   {
     ...dispatchOptions,
     retryOptions: {
-      // Custom retry decision function.
-      retry (err, { state, opts }, callback) {
-        if (err.code === 'UND_ERR_DESTROYED') {
-          callback(err)
-          return
+      // 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
+          callback(err);
+          return;
         }
 
-        setTimeout(() => callback(null), 1000)
-      }
-    }
+        setTimeout(() => callback(null), 1000);
+      },
+    },
   },
   {
-    dispatch (...args) {
-      return client.dispatch(...args)
+    dispatch: (...args) => {
+      return client.dispatch(...args);
     },
     handler: {
-      onRequestStart () {},
-      onResponseStart (controller, status, headers) {
-        // Do something with the response headers.
+      onConnect() {},
+      onBodySent() {},
+      onHeaders(status, _rawHeaders, resume, _statusMessage) {
+        // do something with headers
       },
-      onResponseData (controller, chunk) {
-        chunks.push(chunk)
+      onData(chunk) {
+        chunks.push(chunk);
+        return true;
       },
-      onResponseEnd () {},
-      onResponseError (controller, err) {
-        // Handle the error.
-      }
-    }
+      onComplete() {},
+      onError() {
+        // handle error properly
+      },
+    },
   }
-)
-
-client.dispatch(dispatchOptions, handler)
+);
 ```
 
-A minimal handler that relies entirely on the default retry options:
-
-```mjs
-import { Client, RetryHandler } from 'undici'
-
-const client = new Client(`http://localhost:${server.address().port}`)
+#### Example - Basic RetryHandler with defaults
 
+```js
+const client = new Client(`http://localhost:${server.address().port}`);
 const handler = new RetryHandler(dispatchOptions, {
   dispatch: client.dispatch.bind(client),
   handler: {
-    onRequestStart () {},
-    onResponseStart (controller, status, headers) {},
-    onResponseData (controller, chunk) {},
-    onResponseEnd () {},
-    onResponseError (controller, err) {}
-  }
-})
-
-client.dispatch(dispatchOptions, handler)
+    onConnect() {},
+    onBodySent() {},
+    onHeaders(status, _rawHeaders, resume, _statusMessage) {},
+    onData(chunk) {},
+    onComplete() {},
+    onError(err) {},
+  },
+});
 ```
-
-[`Dispatcher`]: Dispatcher.md#class-dispatcher
-[`DispatchHandler`]: Dispatcher.md#parameter-dispatchhandler
-[`RetryAgent`]: RetryAgent.md#class-retryagent
-[`dispatcher.dispatch()`]: Dispatcher.md#dispatcherdispatchoptions-handler

package/node_modules/undici/docs/docs/api/Util.md

@@ -1,82 +1,25 @@
 # Util
 
-<!--introduced_in=v1.2.0-->
-<!--type=module-->
-<!-- source_link=lib/core/util.js -->
+Utility API for third-party implementations of the dispatcher API.
 
-> Stability: 2 - Stable
+## `parseHeaders(headers, [obj])`
 
-A small set of utility helpers exposed for third-party implementations of the
-[`Dispatcher`][] API. They cover the header-handling primitives undici uses
-internally, so that custom dispatchers and handlers can normalize header names
-and parse raw header lists exactly the way undici does.
+Receives a header object and returns the parsed value.
 
-```mjs
-import { util } from 'undici'
+Arguments:
 
-const { parseHeaders, headerNameToString } = util
-```
+- **headers** `(Buffer | string | (Buffer | string)[])[]` (required) - Header object.
 
-```cjs
-const { util } = require('undici')
+- **obj** `Record<string, string | string[]>` (optional) - Object to specify a proxy object. The parsed value is assigned to this object. But, if **headers** is an object, it is not used.
 
-const { parseHeaders, headerNameToString } = util
-```
-
-## `parseHeaders(headers[, obj])`
-
-<!-- YAML
-added: v1.2.0
-changes:
-  - version: v6.1.0
-    pr-url: https://github.com/nodejs/undici/pull/2501
-    description: Header names supplied as a `Buffer` are accepted and normalized.
--->
-
-* `headers` {Array} A flat list of raw header entries where even indices are
-  header names and odd indices are the corresponding values. Each entry is a
-  {string}, {Buffer}, or an array of {string}/{Buffer}.
-* `obj` {Record<string, string|string[]>} An object to assign the parsed values
-  to. When omitted, a new object is created. **Default:** `{}`.
-* Returns: {Record<string, string|string[]>} The object the parsed headers were
-  assigned to. When `obj` is provided, the same reference is returned.
-
-Receives a flat list of raw header name/value pairs and returns them as an
-object keyed by lowercased header name. Header names are normalized with
-[`headerNameToString()`][], and `Buffer` values are decoded as `latin1`. When a
-header name appears more than once, its values are collected into an array.
-
-```mjs
-import { util } from 'undici'
-
-const raw = ['Content-Type', 'text/plain', 'Set-Cookie', 'a=1', 'Set-Cookie', 'b=2']
-
-console.log(util.parseHeaders(raw))
-// { 'content-type': 'text/plain', 'set-cookie': [ 'a=1', 'b=2' ] }
-```
+Returns: `Record<string, string | string[]>` If **obj** is specified, it is equivalent to **obj**.
 
 ## `headerNameToString(value)`
 
-<!-- YAML
-added: v6.1.0
--->
-
-* `value` {string|Buffer} The header name to normalize.
-* Returns: {string} The lowercased header name.
-
-Returns the lowercased form of a header name. The `value` may be provided as a
-{string} or as a {Buffer}, in which case it is decoded as `latin1`. Common
-header names are resolved through an internal lookup table for performance.
-
-```mjs
-import { util } from 'undici'
+Retrieves a header name and returns its lowercase value.
 
-console.log(util.headerNameToString('Content-Type'))
-// 'content-type'
+Arguments:
 
-console.log(util.headerNameToString(Buffer.from('X-Custom-Header')))
-// 'x-custom-header'
-```
+- **value** `string | Buffer` (required) - Header name.
 
-[`Dispatcher`]: Dispatcher.md#class-dispatcher
-[`headerNameToString()`]: #headernametostringvalue
+Returns: `string`