@noodleseed/one 0.22.0 → 0.23.0

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

@@ -1,101 +1,276 @@
-# Class: RedirectHandler
+# 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 once
+    `maxRedirections` is reached instead of returning the last redirect response.
+    **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)
 
-A class that handles redirection logic for HTTP requests.
+dispatch({ method: 'GET', path: '/', origin: 'http://example.com' }, {
+  onRequestStart () {},
+  onResponseStart (controller, statusCode) {
+    console.log(statusCode)
+  },
+  onResponseData () {},
+  onResponseEnd () {},
+})
+```
 
-## `new RedirectHandler(dispatch, maxRedirections, opts, handler)`
+### `redirectHandler.onRequestStart(controller, context)`
 
-Arguments:
+<!-- YAML
+added: v7.0.0
+-->
 
-- **dispatch** `function` - The dispatch function to be called after every retry.
-- **maxRedirections** `number` - Maximum number of redirections allowed.
-- **opts** `object` - Options for handling redirection. Supports `throwOnMaxRedirect`, `stripHeadersOnRedirect`, and `stripHeadersOnCrossOriginRedirect`.
-- **handler** `object` - An object containing handlers for different stages of the request lifecycle.
+* `controller` {DispatchController} The controller for the in-flight request.
+* `context` {Object} The dispatch context.
 
-Returns: `RedirectHandler`
+Forwards the request-start event to the wrapped `handler`, augmenting `context`
+with the current redirect `history`.
 
-### Parameters
+### `redirectHandler.onRequestUpgrade(controller, statusCode, headers, socket)`
 
-- **dispatch** `(options: Dispatch.DispatchOptions, handlers: Dispatch.DispatchHandler) => Promise<Dispatch.DispatchResponse>` (required) - Dispatch function to be called after every redirection.
-- **maxRedirections** `number` (required) - Maximum number of redirections allowed.
-- **opts** `object` (required) - Options for handling redirection.
-  - **throwOnMaxRedirect** `boolean` - Throw when the maximum number of redirections is reached.
-  - **stripHeadersOnRedirect** `string[]` - Header names to remove from all redirected requests.
-  - **stripHeadersOnCrossOriginRedirect** `string[]` - Header names to remove from cross-origin redirected requests.
-- **handler** `object` (required) - Handlers for different stages of the request lifecycle.
+<!-- YAML
+added: v7.0.0
+-->
 
-### Properties
+* `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.
 
-- **location** `string` - The current redirection location.
-- **abort** `function` - The abort function.
-- **opts** `object` - The options for handling redirection.
-- **maxRedirections** `number` - Maximum number of redirections allowed.
-- **handler** `object` - Handlers for different stages of the request lifecycle.
-- **history** `Array` - An array representing the history of URLs during redirection.
+Forwards a connection upgrade to the wrapped `handler`.
 
-### Methods
+### `redirectHandler.onResponseStart(controller, statusCode, headers, statusMessage)`
 
-#### `onRequestStart(controller, context)`
+<!-- YAML
+added: v7.0.0
+-->
 
-Called when the request starts.
+* `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.
 
-Parameters:
+Inspects the response headers to decide whether to follow a redirect. When the
+status code is redirectable, 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`.
 
-- **controller** `DispatchController` - The request controller.
-- **context** `object` - The dispatch context.
+Throws when `throwOnMaxRedirect` is `true` and the number of recorded redirects
+has reached `maxRedirections`, 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).
 
-#### `onRequestUpgrade(controller, statusCode, headers, socket)`
+### `redirectHandler.onResponseData(controller, chunk)`
 
-Called when an upgrade is requested.
+<!-- YAML
+added: v7.0.0
+-->
 
-Parameters:
+* `controller` {DispatchController} The controller for the in-flight request.
+* `chunk` {Buffer} A chunk of the response body.
 
-- **controller** `DispatchController` - The request controller.
-- **statusCode** `number` - The HTTP status code.
-- **headers** `object` - The headers received in the response.
-- **socket** `object` - The socket object.
+Forwards body data to the wrapped `handler`. While a redirect is pending
+(`location` is set), the `3xx` response body is ignored.
 
-#### `onResponseError(controller, error)`
+### `redirectHandler.onResponseEnd(controller, trailers)`
 
-Called when an error occurs.
+<!-- YAML
+added: v7.0.0
+-->
 
-Parameters:
+* `controller` {DispatchController} The controller for the in-flight request.
+* `trailers` {Object} The response trailers.
 
-- **controller** `DispatchController` - The request controller.
-- **error** `Error` - The error that occurred.
+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`.
 
-#### `onResponseStart(controller, statusCode, headers, statusText)`
+### `redirectHandler.onResponseError(controller, error)`
 
-Called when headers are received.
+<!-- YAML
+added: v7.0.0
+-->
 
-Parameters:
+* `controller` {DispatchController} The controller for the in-flight request.
+* `error` {Error} The error that occurred.
 
-- **controller** `DispatchController` - The request controller.
-- **statusCode** `number` - The HTTP status code.
-- **headers** `object` - The headers received in the response.
-- **statusText** `string` - The status text.
+Forwards the error to the wrapped `handler`.
 
-#### `onResponseData(controller, chunk)`
+### `redirectHandler.location`
 
-Called when data is received.
+<!-- YAML
+added: v4.0.0
+-->
 
-Parameters:
+* Type: {string|null}
 
-- **controller** `DispatchController` - The request controller.
-- **chunk** `Buffer` - The data chunk received.
+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`.
 
-#### `onResponseEnd(controller, trailers)`
+### `redirectHandler.opts`
 
-Called when the request is complete.
+<!-- YAML
+added: v7.12.0
+-->
 
-Parameters:
+* Type: {DispatchOptions}
 
-- **controller** `DispatchController` - The request controller.
-- **trailers** `object` - The trailers received.
+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.
 
-#### `onBodySent(chunk)`
+### `redirectHandler.maxRedirections`
 
-Called when the request body is sent.
+<!-- YAML
+added: v4.0.0
+-->
 
-Parameters:
+* Type: {number|null}
 
-- **chunk** `Buffer` - The chunk of the request body sent.
+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/node_modules/undici/docs/docs/api/RetryAgent.md

@@ -1,49 +1,136 @@
-# Class: RetryAgent
+# RetryAgent
 
-Extends: `undici.Dispatcher`
+<!--introduced_in=v6.7.0-->
+<!--type=module-->
+<!-- source_link=lib/dispatcher/retry-agent.js -->
 
-A `undici.Dispatcher` that allows to automatically retry a request.
-Wraps a `undici.RetryHandler`.
+> Stability: 2 - Stable
 
-## `new RetryAgent(dispatcher, [options])`
+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.
 
-Arguments:
+```mjs
+import { RetryAgent } from 'undici'
+```
+
+## Class: `RetryAgent`
 
-* **dispatcher** `undici.Dispatcher` (required) - the dispatcher to wrap
-* **options** `RetryHandlerOptions` (optional) - the options
+<!-- YAML
+added: v6.7.0
+-->
 
-Returns: `RetryAgent`
+* Extends: {Dispatcher}
 
-### Parameter: `RetryHandlerOptions`
+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.
 
-- **throwOnError** `boolean` (optional) - Disable to prevent throwing error on last retry attept, useful if you need the body on errors from server or if you have custom error handler. Default: `true`
-- **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', 'HEAD', 'OPTIONS', 'PUT', 'DELETE', 'TRACE']`
-- **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', 'EHOSTUNREACH', 'EPIPE', 'UND_ERR_SOCKET']`
+### `new RetryAgent(dispatcher[, options])`
 
-**`RetryContext`**
+<!-- YAML
+added: v6.7.0
+-->
 
-- `state`: `RetryState` - Current retry state. It can be mutated.
-- `opts`: `Dispatch.DispatchOptions & RetryOptions` - Options passed to the retry handler.
+* `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']`.
 
-Example:
+Creates a new `RetryAgent` that wraps `dispatcher`. The `options` are stored and
+used to construct a [`RetryHandler`][] for each dispatched request.
 
-```js
+```mjs
 import { Agent, RetryAgent } from 'undici'
 
-const agent = new RetryAgent(new Agent())
+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