monitor-transfer-dsh 0.0.0-stage → 0.1.2

package/skill/tools/node_modules/undici/docs/docs/api/RedirectHandler.md

@@ -0,0 +1,279 @@
+# RedirectHandler
+
+<!--introduced_in=v4.0.0-->
+<!--type=module-->
+<!-- source_link=lib/handler/redirect-handler.js -->
+
+> Stability: 2 - Stable
+
+A dispatch handler that follows HTTP redirects on behalf of another handler. It
+wraps a downstream `handler` and a `dispatch` function: when a redirectable
+response is received it transparently re-dispatches the request to the new
+location, forwarding the lifecycle callbacks to the wrapped `handler` only once a
+final (non-redirect) response is reached.
+
+Redirects are followed for the `300`, `301`, `302`, `303`, `307`, and `308`
+status codes, up to `maxRedirections` hops. Following the relevant HTTP
+specifications, the method is downgraded to `GET` for `301`/`302` `POST`
+responses and for `303` responses with any method other than `HEAD`, request
+bodies that have already been consumed are not replayed, and headers that refer
+to the original URL (such as `host`) are stripped on each hop, with additional
+credential headers removed on cross-origin redirects.
+
+```mjs
+import { RedirectHandler } from 'undici'
+```
+
+```cjs
+const { RedirectHandler } = require('undici')
+```
+
+Most users do not construct `RedirectHandler` directly. The `maxRedirections`
+option on [`Dispatcher`][] methods and the higher-level clients use it
+internally.
+
+## Class: `RedirectHandler`
+
+<!-- YAML
+added: v4.0.0
+-->
+
+* Extends: {DispatchHandler}
+
+Implements the [`DispatchHandler`][] interface, delegating every callback to the
+wrapped `handler` while intercepting redirect responses.
+
+### `new RedirectHandler(dispatch, maxRedirections, opts, handler)`
+
+<!-- YAML
+added: v4.0.0
+-->
+
+* `dispatch` {Function} The dispatch function used to issue the original request
+  and every subsequent redirect. Called as `dispatch(options, handler)`.
+* `maxRedirections` {number|null} The maximum number of redirects to follow. Must
+  be a non-negative integer or `null`. When `null` or `0`, no redirects are
+  followed and redirect responses are passed through to the wrapped `handler`.
+* `opts` {DispatchOptions} The dispatch options for the request. In addition to
+  the standard dispatch options, the following redirect-specific fields are
+  recognized:
+  * `throwOnMaxRedirect` {boolean} When `true`, an error is thrown when a
+    redirect would be followed but `maxRedirections` has been reached, instead of
+    returning that redirect response. A non-redirect response after exactly
+    `maxRedirections` redirects is returned normally. **Default:** `false`.
+  * `stripHeadersOnRedirect` {string[]} Header names to remove from the request on
+    every redirect hop. **Default:** `null`.
+  * `stripHeadersOnCrossOriginRedirect` {string[]} Additional header names to
+    remove from the request when a redirect points to a different origin.
+    **Default:** `null`.
+* `handler` {DispatchHandler} The downstream handler that receives the lifecycle
+  callbacks for the final response.
+
+Throws an [`InvalidArgumentError`][] when `maxRedirections` is not a non-negative
+integer, when `throwOnMaxRedirect` is not a boolean, or when either
+`stripHeadersOnRedirect` or `stripHeadersOnCrossOriginRedirect` is not an array of
+header-name strings.
+
+```mjs
+import { Client, RedirectHandler } from 'undici'
+
+const client = new Client('http://example.com')
+const dispatch = client.dispatch.bind(client)
+
+const handler = new RedirectHandler(dispatch, 5, {
+  method: 'GET',
+  path: '/',
+  origin: 'http://example.com',
+}, {
+  onRequestStart () {},
+  onResponseStart (controller, statusCode, headers) {
+    console.log(statusCode)
+  },
+  onResponseData (controller, chunk) {},
+  onResponseEnd () {},
+})
+
+dispatch({ method: 'GET', path: '/', origin: 'http://example.com' }, handler)
+```
+
+### Static method: `RedirectHandler.buildDispatch(dispatcher, maxRedirections)`
+
+<!-- YAML
+added: v7.0.0
+-->
+
+* `dispatcher` {Dispatcher} The dispatcher whose `dispatch` method is wrapped.
+* `maxRedirections` {number|null} The maximum number of redirects to follow. Must
+  be a non-negative integer or `null`.
+* Returns: {Function} A `dispatch(options, handler)` function that wraps each call
+  in a `RedirectHandler` before delegating to `dispatcher`.
+
+Builds a redirect-aware dispatch function from an existing dispatcher. The
+returned function has the same shape as `dispatcher.dispatch` but follows
+redirects automatically. Throws an [`InvalidArgumentError`][] when
+`maxRedirections` is not a non-negative integer.
+
+```mjs
+import { Client, RedirectHandler } from 'undici'
+
+const client = new Client('http://example.com')
+const dispatch = RedirectHandler.buildDispatch(client, 5)
+
+dispatch({ method: 'GET', path: '/', origin: 'http://example.com' }, {
+  onRequestStart () {},
+  onResponseStart (controller, statusCode) {
+    console.log(statusCode)
+  },
+  onResponseData () {},
+  onResponseEnd () {},
+})
+```
+
+### `redirectHandler.onRequestStart(controller, context)`
+
+<!-- YAML
+added: v7.0.0
+-->
+
+* `controller` {DispatchController} The controller for the in-flight request.
+* `context` {Object} The dispatch context.
+
+Forwards the request-start event to the wrapped `handler`, augmenting `context`
+with the current redirect `history`.
+
+### `redirectHandler.onRequestUpgrade(controller, statusCode, headers, socket)`
+
+<!-- YAML
+added: v7.0.0
+-->
+
+* `controller` {DispatchController} The controller for the in-flight request.
+* `statusCode` {number} The HTTP status code of the upgrade response.
+* `headers` {Object} The response headers.
+* `socket` {Duplex} The upgraded socket.
+
+Forwards a connection upgrade to the wrapped `handler`.
+
+### `redirectHandler.onResponseStart(controller, statusCode, headers, statusMessage)`
+
+<!-- YAML
+added: v7.0.0
+-->
+
+* `controller` {DispatchController} The controller for the in-flight request.
+* `statusCode` {number} The HTTP status code of the response.
+* `headers` {Object} The response headers.
+* `statusMessage` {string} The HTTP status message.
+
+Inspects the response headers to decide whether to follow a redirect. When the
+status code is redirectable, the response has a `Location` header, the
+`maxRedirections` limit has not been reached, and the request body has not been
+consumed, the `location` property is set, the method and headers are adjusted
+for the next hop, and the response is not forwarded. Otherwise the event is
+forwarded to the wrapped `handler`.
+
+Throws when `throwOnMaxRedirect` is `true` and a redirect that would otherwise be
+followed arrives after `maxRedirections` redirects have already been followed,
+and throws an [`InvalidArgumentError`][] if a
+redirect loop is detected (for example when a [`Client`][] or [`Pool`][] is used
+for a cross-origin redirect; use an [`Agent`][] instead).
+
+### `redirectHandler.onResponseData(controller, chunk)`
+
+<!-- YAML
+added: v7.0.0
+-->
+
+* `controller` {DispatchController} The controller for the in-flight request.
+* `chunk` {Buffer} A chunk of the response body.
+
+Forwards body data to the wrapped `handler`. While a redirect is pending
+(`location` is set), the `3xx` response body is ignored.
+
+### `redirectHandler.onResponseEnd(controller, trailers)`
+
+<!-- YAML
+added: v7.0.0
+-->
+
+* `controller` {DispatchController} The controller for the in-flight request.
+* `trailers` {Object} The response trailers.
+
+Completes the response. When a redirect is pending, the request is re-dispatched
+to the new `location`; otherwise the end event is forwarded to the wrapped
+`handler`.
+
+### `redirectHandler.onResponseError(controller, error)`
+
+<!-- YAML
+added: v7.0.0
+-->
+
+* `controller` {DispatchController} The controller for the in-flight request.
+* `error` {Error} The error that occurred.
+
+Forwards the error to the wrapped `handler`.
+
+### `redirectHandler.location`
+
+<!-- YAML
+added: v4.0.0
+-->
+
+* Type: {string|null}
+
+The `Location` header value of the redirect currently being followed, or `null`
+when no redirect is pending and the response is being passed through to the
+wrapped `handler`.
+
+### `redirectHandler.opts`
+
+<!-- YAML
+added: v7.12.0
+-->
+
+* Type: {DispatchOptions}
+
+A copy of the dispatch options for the next request. It excludes the redirect
+control fields (`maxRedirections`, `stripHeadersOnRedirect`, and
+`stripHeadersOnCrossOriginRedirect`) and is mutated on each hop to reflect the
+updated method, path, origin, and headers.
+
+### `redirectHandler.maxRedirections`
+
+<!-- YAML
+added: v4.0.0
+-->
+
+* Type: {number|null}
+
+The maximum number of redirects this handler will follow.
+
+### `redirectHandler.handler`
+
+<!-- YAML
+added: v4.0.0
+-->
+
+* Type: {DispatchHandler}
+
+The wrapped downstream handler that receives the lifecycle callbacks for the final
+response.
+
+### `redirectHandler.history`
+
+<!-- YAML
+added: v4.0.0
+-->
+
+* Type: {URL[]}
+
+The ordered list of URLs visited while following redirects. It is used to enforce
+`maxRedirections` and to detect redirect loops.
+
+[`Agent`]: Agent.md#class-agent
+[`Client`]: Client.md#class-client
+[`Dispatcher`]: Dispatcher.md#class-dispatcher
+[`DispatchHandler`]: Dispatcher.md#parameter-dispatchhandler
+[`InvalidArgumentError`]: Errors.md#class-invalidargumenterror
+[`Pool`]: Pool.md#class-pool

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

@@ -0,0 +1,136 @@
+# RetryAgent
+
+<!--introduced_in=v6.7.0-->
+<!--type=module-->
+<!-- source_link=lib/dispatcher/retry-agent.js -->
+
+> Stability: 2 - Stable
+
+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.
+
+```mjs
+import { RetryAgent } from 'undici'
+```
+
+## Class: `RetryAgent`
+
+<!-- YAML
+added: v6.7.0
+-->
+
+* Extends: {Dispatcher}
+
+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.
+
+### `new RetryAgent(dispatcher[, options])`
+
+<!-- YAML
+added: v6.7.0
+-->
+
+* `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', 'QUERY']`.
+  * `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']`.
+
+Creates a new `RetryAgent` that wraps `dispatcher`. The `options` are stored and
+used to construct a [`RetryHandler`][] for each dispatched request.
+
+```mjs
+import { Agent, RetryAgent } from 'undici'
+
+const agent = new RetryAgent(new Agent(), {
+  maxRetries: 3,
+  minTimeout: 1000,
+  timeoutFactor: 2,
+})
+
+const res = await agent.request({
+  method: 'GET',
+  origin: 'http://example.com',
+  path: '/',
+})
+
+console.log(res.statusCode)
+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/skill/tools/node_modules/undici/docs/docs/api/RetryHandler.md

@@ -0,0 +1,200 @@
+# RetryHandler
+
+<!--introduced_in=v5.28.0-->
+<!--type=module-->
+<!-- source_link=lib/handler/retry-handler.js -->
+
+> Stability: 2 - Stable
+
+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`.
+
+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.
+
+```mjs
+import { RetryHandler } from 'undici'
+```
+
+## Class: `RetryHandler`
+
+<!-- YAML
+added: v5.28.0
+-->
+
+* Extends: {DispatchHandler}
+
+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.
+
+> **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.
+
+### `new RetryHandler(options, retryHandlers)`
+
+<!-- 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.
+-->
+
+* `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}
+
+#### `RetryOptions`
+
+* `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', 'QUERY']`.
+* `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 = []
+
+const handler = new RetryHandler(
+  {
+    ...dispatchOptions,
+    retryOptions: {
+      // Custom retry decision function.
+      retry (err, { state, opts }, callback) {
+        if (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: {
+      onRequestStart () {},
+      onResponseStart (controller, status, headers) {
+        // Do something with the response headers.
+      },
+      onResponseData (controller, chunk) {
+        chunks.push(chunk)
+      },
+      onResponseEnd () {},
+      onResponseError (controller, err) {
+        // Handle the error.
+      }
+    }
+  }
+)
+
+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}`)
+
+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)
+```
+
+[`Dispatcher`]: Dispatcher.md#class-dispatcher
+[`DispatchHandler`]: Dispatcher.md#parameter-dispatchhandler
+[`RetryAgent`]: RetryAgent.md#class-retryagent
+[`dispatcher.dispatch()`]: Dispatcher.md#dispatcherdispatchoptions-handler