monitor-transfer-dsh 0.0.0-stage → 0.1.2

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

@@ -0,0 +1,239 @@
+# RoundRobinPool
+
+<!--introduced_in=v7.17.0-->
+<!--type=module-->
+<!-- source_link=lib/dispatcher/round-robin-pool.js -->
+
+> Stability: 2 - Stable
+
+A pool of [`Client`][] instances connected to the same upstream target that
+selects clients in a round-robin fashion.
+
+Unlike [`Pool`][], which always reuses the first available client,
+`RoundRobinPool` cycles through its clients so that requests are distributed
+evenly across every open connection. This is useful when the upstream target is
+fronted by a load balancer that distributes TCP connections across multiple
+backend servers (for example, a Kubernetes Service): each connection is pinned
+to a backend by the load balancer, and `RoundRobinPool` spreads requests across
+those connections so every backend receives a comparable share of traffic.
+
+Requests are not guaranteed to be dispatched in the order they were invoked.
+
+```mjs
+import { RoundRobinPool } from 'undici'
+
+const pool = new RoundRobinPool('http://localhost:3000', { connections: 10 })
+```
+
+`RoundRobinPool` distributes HTTP requests evenly across TCP connections, not
+across backend servers directly. Even backend distribution therefore depends on
+the load balancer assigning different connections to different backends (for
+example, round-robin, random, or least-connections without client affinity). If
+the load balancer pins all connections from one source to the same backend (for
+example, source-IP affinity or sticky sessions), consider [`BalancedPool`][]
+with the individual backend addresses instead.
+
+## Class: `RoundRobinPool`
+
+<!-- YAML
+added: v7.17.0
+-->
+
+* Extends: {Dispatcher}
+
+### `new RoundRobinPool(url[, options])`
+
+<!-- YAML
+added: v7.17.0
+-->
+
+* `url` {URL|string} The upstream target. It should only include the
+  **protocol, hostname, and port**.
+* `options` {RoundRobinPoolOptions} (optional)
+
+#### Parameter: `RoundRobinPoolOptions`
+
+Extends: {ClientOptions}
+
+* `factory` {Function} A function used to create the underlying {Client}
+  instances. **Default:** `(origin, opts) => new Client(origin, opts)`.
+  * `origin` {URL}
+  * `opts` {Object}
+  * Returns: {Dispatcher}
+* `connections` {number|null} (optional) The maximum number of {Client}
+  instances to create. When set to `null`, the `RoundRobinPool` instance creates
+  an unlimited number of {Client} instances. **Default:** `null`.
+* `clientTtl` {number|null} (optional) The amount of time, in milliseconds,
+  before a {Client} instance is removed from the `RoundRobinPool` and closed.
+  When set to `null`, {Client} instances are not removed or closed based on age.
+  **Default:** `null`.
+
+`RoundRobinPool` inherits all [`Client`][] options. A [`Client`][] instance is
+created lazily on the first dispatch and additional instances are created on
+demand, up to `connections`, when every existing client is busy.
+
+### `roundRobinPool.closed`
+
+<!-- YAML
+added: v7.17.0
+-->
+
+* Type: {boolean}
+
+`true` after `roundRobinPool.close()` has been called.
+
+### `roundRobinPool.destroyed`
+
+<!-- YAML
+added: v7.17.0
+-->
+
+* Type: {boolean}
+
+`true` after `roundRobinPool.destroy()` has been called, or after
+`roundRobinPool.close()` has been called and the pool shutdown has completed.
+
+### `roundRobinPool.stats`
+
+<!-- YAML
+added: v7.17.0
+-->
+
+* Type: {PoolStats}
+
+Aggregate connection statistics for the pool. See [`PoolStats`][].
+
+### `roundRobinPool.close([callback])`
+
+<!-- YAML
+added: v7.17.0
+-->
+
+Closes the pool and gracefully waits for enqueued requests to complete before
+resolving. Implements [`dispatcher.close([callback])`][].
+
+### `roundRobinPool.destroy([error[, callback]])`
+
+<!-- YAML
+added: v7.17.0
+-->
+
+Destroys the pool abruptly. All pending and running requests are aborted with
+the given `error`. Implements [`dispatcher.destroy([error[, callback]])`][].
+
+### `roundRobinPool.connect(options[, callback])`
+
+<!-- YAML
+added: v7.17.0
+-->
+
+Starts two-way communications with the requested resource using
+[HTTP CONNECT][]. See [`dispatcher.connect(options[, callback])`][].
+
+### `roundRobinPool.dispatch(options, handler)`
+
+<!-- YAML
+added: v7.17.0
+-->
+
+Dispatches a request through the next client selected in round-robin order.
+Implements [`dispatcher.dispatch(options, handler)`][].
+
+### `roundRobinPool.pipeline(options, handler)`
+
+<!-- YAML
+added: v7.17.0
+-->
+
+For easy use with [`stream.pipeline`][]. See
+[`dispatcher.pipeline(options, handler)`][].
+
+### `roundRobinPool.request(options[, callback])`
+
+<!-- YAML
+added: v7.17.0
+-->
+
+Performs an HTTP request. See [`dispatcher.request(options[, callback])`][].
+
+### `roundRobinPool.stream(options, factory[, callback])`
+
+<!-- YAML
+added: v7.17.0
+-->
+
+A faster version of [`roundRobinPool.request()`][]. See
+[`dispatcher.stream(options, factory[, callback])`][].
+
+### `roundRobinPool.upgrade(options[, callback])`
+
+<!-- YAML
+added: v7.17.0
+-->
+
+Upgrades a connection to a different protocol. See
+[`dispatcher.upgrade(options[, callback])`][].
+
+### Event: `'connect'`
+
+<!-- YAML
+added: v7.17.0
+-->
+
+See [Dispatcher Event: `'connect'`][].
+
+### Event: `'disconnect'`
+
+<!-- YAML
+added: v7.17.0
+-->
+
+See [Dispatcher Event: `'disconnect'`][].
+
+### Event: `'drain'`
+
+<!-- YAML
+added: v7.17.0
+-->
+
+See [Dispatcher Event: `'drain'`][].
+
+## Example
+
+```mjs
+import { RoundRobinPool } from 'undici'
+
+const pool = new RoundRobinPool('http://localhost:3000', {
+  connections: 10
+})
+
+// Requests are distributed evenly across all 10 connections.
+for (let i = 0; i < 100; i++) {
+  const { body } = await pool.request({
+    path: '/api/data',
+    method: 'GET'
+  })
+  console.log(await body.json())
+}
+
+await pool.close()
+```
+
+[HTTP CONNECT]: https://developer.mozilla.org/docs/Web/HTTP/Methods/CONNECT
+[`BalancedPool`]: BalancedPool.md#class-balancedpool
+[`Client`]: Client.md#class-client
+[`Pool`]: Pool.md#class-pool
+[`PoolStats`]: PoolStats.md#class-poolstats
+[`dispatcher.close([callback])`]: Dispatcher.md#dispatcherclosecallback-promise
+[`dispatcher.connect(options[, callback])`]: Dispatcher.md#dispatcherconnectoptions-callback
+[`dispatcher.destroy([error[, callback]])`]: Dispatcher.md#dispatcherdestroyerror-callback-promise
+[`dispatcher.dispatch(options, handler)`]: Dispatcher.md#dispatcherdispatchoptions-handler
+[`dispatcher.pipeline(options, handler)`]: Dispatcher.md#dispatcherpipelineoptions-handler
+[`dispatcher.request(options[, callback])`]: Dispatcher.md#dispatcherrequestoptions-callback
+[`dispatcher.stream(options, factory[, callback])`]: Dispatcher.md#dispatcherstreamoptions-factory-callback
+[`dispatcher.upgrade(options[, callback])`]: Dispatcher.md#dispatcherupgradeoptions-callback
+[`roundRobinPool.request()`]: #roundrobinpoolrequestoptions-callback
+[`stream.pipeline`]: https://nodejs.org/api/stream.html#streampipelinesource-transforms-destination-callback
+[Dispatcher Event: `'connect'`]: Dispatcher.md#event-connect
+[Dispatcher Event: `'disconnect'`]: Dispatcher.md#event-disconnect
+[Dispatcher Event: `'drain'`]: Dispatcher.md#event-drain

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

@@ -0,0 +1,361 @@
+# SnapshotAgent
+
+<!--introduced_in=v7.13.0-->
+<!--type=module-->
+<!-- source_link=lib/mock/snapshot-agent.js -->
+
+> Stability: 1 - Experimental
+
+`SnapshotAgent` records real HTTP responses and replays them on later requests,
+allowing tests to run against deterministic, captured data instead of a live
+network. It extends [`MockAgent`][], so it can be installed with
+[`setGlobalDispatcher()`][] or passed explicitly through the `dispatcher`
+option, and it works with every undici API (`fetch`, `request`, `stream`,
+`pipeline`, and so on).
+
+A `SnapshotAgent` operates in one of three modes. In `'record'` mode it performs
+real requests and writes the responses to a snapshot file. In `'playback'` mode
+it serves responses from the snapshot file without touching the network. In
+`'update'` mode it replays existing snapshots and records any request that has no
+matching snapshot.
+
+```mjs
+import { SnapshotAgent, setGlobalDispatcher, fetch } from 'undici'
+
+const agent = new SnapshotAgent({
+  mode: 'record',
+  snapshotPath: './snapshots/api.json'
+})
+setGlobalDispatcher(agent)
+
+const response = await fetch('https://api.example.com/users')
+const users = await response.json()
+
+await agent.close()
+```
+
+Constructing a `SnapshotAgent` emits an `ExperimentalWarning` once per process.
+
+## Class: `SnapshotAgent`
+
+<!-- YAML
+added: v7.13.0
+-->
+
+* Extends: {MockAgent}
+
+The captured interactions are managed by an internal `SnapshotRecorder`, which
+is accessible through [`agent.getRecorder()`][]. Because `SnapshotAgent` extends
+[`MockAgent`][], all `MockAgent` and [`Dispatcher`][] methods and events are also
+available.
+
+### `new SnapshotAgent([options])`
+
+<!-- YAML
+added: v7.13.0
+-->
+
+* `options` {Object} (optional) Accepts all [`MockAgent`][] options plus the
+  following snapshot-specific options.
+  * `mode` {string} The snapshot mode. One of `'record'`, `'playback'`, or
+    `'update'`. **Default:** `'record'`.
+  * `snapshotPath` {string} Path to the snapshot file used for loading and
+    saving. Required when `mode` is `'playback'` or `'update'`. **Default:**
+    `null`.
+  * `maxSnapshots` {number} Maximum number of snapshots to keep in memory.
+    **Default:** `Infinity`.
+  * `autoFlush` {boolean} When `true`, snapshots are written to `snapshotPath`
+    automatically as they are recorded. **Default:** `false`.
+  * `flushInterval` {number} Interval, in milliseconds, between automatic flushes
+    when `autoFlush` is enabled. **Default:** `30000`.
+  * `matchHeaders` {string[]} Names of the only headers to include when matching
+    a request against a snapshot. When omitted, all headers are matched.
+  * `ignoreHeaders` {string[]} Header names to ignore when matching a request.
+  * `excludeHeaders` {string[]} Header names to strip from snapshots entirely,
+    so that sensitive values are never written to disk.
+  * `matchBody` {boolean} When `true`, the request body is included in request
+    matching. **Default:** `true`.
+  * `normalizeBody` {Function} Normalizes the request body before it is matched
+    or stored, for example to strip volatile fields such as timestamps. Only
+    applied when `matchBody` is `true`.
+    * `body` {string|Buffer|null|undefined} The raw request body.
+    * Returns: {string} The normalized body used for matching.
+  * `matchQuery` {boolean} When `true`, query parameters are included in request
+    matching. **Default:** `true`.
+  * `normalizeQuery` {Function} Normalizes the query string before it is matched,
+    for example to strip cache-busting parameters. Only applied when `matchQuery`
+    is `true`.
+    * `query` {URLSearchParams} The parsed query parameters.
+    * Returns: {string} The normalized query string used for matching.
+  * `caseSensitive` {boolean} When `true`, header matching is case-sensitive.
+    **Default:** `false`.
+  * `shouldRecord` {Function} Decides whether a given request is recorded. Only
+    used in `'record'` and `'update'` modes.
+    * `requestOpts` {Object} The dispatch options of the request.
+    * Returns: {boolean} `true` to record the request.
+  * `shouldPlayback` {Function} Decides whether a given request is served from a
+    snapshot. Only used in `'playback'` and `'update'` modes.
+    * `requestOpts` {Object} The dispatch options of the request.
+    * Returns: {boolean} `true` to play the request back from a snapshot.
+  * `excludeUrls` {Array<string|RegExp>} URL patterns that are excluded from
+    recording and playback. String patterns match case-insensitively as
+    substrings of the URL; `RegExp` patterns are tested against the URL. Matching
+    requests are passed through to a real [`Agent`][] instead.
+
+Creates a new `SnapshotAgent`. Throws an [`InvalidArgumentError`][] when `mode`
+is `'playback'` or `'update'` and `snapshotPath` is not provided, and throws an
+`InvalidArgumentError` when `mode` is not one of the supported values.
+
+When `mode` is `'playback'` or `'update'` and `snapshotPath` is set, snapshots
+are loaded from the file automatically; a missing file is ignored until the first
+request requires it.
+
+```mjs
+import { SnapshotAgent, setGlobalDispatcher } from 'undici'
+
+const agent = new SnapshotAgent({
+  mode: 'playback',
+  snapshotPath: './snapshots/api.json'
+})
+setGlobalDispatcher(agent)
+```
+
+The mode controls how requests are handled:
+
+* `'record'` performs the real request and stores the response.
+
+  ```mjs
+  import { SnapshotAgent, setGlobalDispatcher, fetch } from 'undici'
+
+  const agent = new SnapshotAgent({
+    mode: 'record',
+    snapshotPath: './snapshots/api.json'
+  })
+  setGlobalDispatcher(agent)
+
+  await fetch('https://api.example.com/users')
+  await agent.saveSnapshots()
+  ```
+
+* `'playback'` serves the recorded response without any network access. A
+  request with no matching snapshot rejects with an [`UndiciError`][] whose
+  message begins with `No snapshot found`.
+
+  ```mjs
+  import { SnapshotAgent, setGlobalDispatcher, fetch } from 'undici'
+
+  const agent = new SnapshotAgent({
+    mode: 'playback',
+    snapshotPath: './snapshots/api.json'
+  })
+  setGlobalDispatcher(agent)
+
+  const response = await fetch('https://api.example.com/users')
+  ```
+
+* `'update'` replays an existing snapshot when one is found and otherwise records
+  the request like `'record'` mode.
+
+  ```mjs
+  import { SnapshotAgent, setGlobalDispatcher, fetch } from 'undici'
+
+  const agent = new SnapshotAgent({
+    mode: 'update',
+    snapshotPath: './snapshots/api.json'
+  })
+  setGlobalDispatcher(agent)
+
+  await fetch('https://api.example.com/new-endpoint')
+  ```
+
+### `agent.loadSnapshots([filePath])`
+
+<!-- YAML
+added: v7.13.0
+-->
+
+* `filePath` {string} (optional) Path to read snapshots from. **Default:** the
+  `snapshotPath` given to the constructor.
+* Returns: {Promise<void>} Resolves when the snapshots have been loaded.
+
+Loads snapshots from disk into memory. In `'playback'` mode this also installs
+the corresponding [`MockAgent`][] interceptors so that subsequent requests are
+matched against the loaded snapshots.
+
+```mjs
+await agent.loadSnapshots('./snapshots/api.json')
+```
+
+### `agent.saveSnapshots([filePath])`
+
+<!-- YAML
+added: v7.13.0
+-->
+
+* `filePath` {string} (optional) Path to write snapshots to. **Default:** the
+  `snapshotPath` given to the constructor.
+* Returns: {Promise<void>} Resolves when the snapshots have been written.
+
+Writes all recorded snapshots to disk.
+
+```mjs
+await agent.saveSnapshots('./snapshots/api.json')
+```
+
+### `agent.getRecorder()`
+
+<!-- YAML
+added: v7.13.0
+-->
+
+* Returns: {SnapshotRecorder} The internal recorder that stores the captured
+  interactions.
+
+Returns the underlying `SnapshotRecorder`. The recorder exposes lower-level
+operations over the captured data, including `record()`, `findSnapshot()`,
+`getSnapshots()`, `size()`, and `clear()`. The recorder is an internal type
+returned for inspection; it is not exported from the package root.
+
+```mjs
+const recorder = agent.getRecorder()
+console.log(`Recorded ${recorder.size()} interactions`)
+```
+
+### `agent.getMode()`
+
+<!-- YAML
+added: v7.13.0
+-->
+
+* Returns: {string} The current mode: `'record'`, `'playback'`, or `'update'`.
+
+Returns the mode the agent was constructed with.
+
+### `agent.clearSnapshots()`
+
+<!-- YAML
+added: v7.13.0
+-->
+
+* Returns: {undefined}
+
+Removes all snapshots from memory.
+
+```mjs
+agent.clearSnapshots()
+```
+
+### `agent.resetCallCounts()`
+
+<!-- YAML
+added: v7.13.0
+-->
+
+* Returns: {undefined}
+
+Resets the call count of every snapshot to zero. Useful between tests when the
+same agent is reused, since matching a snapshot in `'playback'` mode increments
+its call count.
+
+```mjs
+agent.resetCallCounts()
+```
+
+### `agent.deleteSnapshot(requestOpts)`
+
+<!-- YAML
+added: v7.13.0
+-->
+
+* `requestOpts` {Object} Dispatch options identifying the snapshot to remove.
+* Returns: {boolean} `true` if a matching snapshot was deleted, `false` if none
+  was found.
+
+Deletes a single snapshot that matches the given request options.
+
+```mjs
+const deleted = agent.deleteSnapshot({
+  method: 'GET',
+  origin: 'https://api.example.com',
+  path: '/users'
+})
+```
+
+### `agent.getSnapshotInfo(requestOpts)`
+
+<!-- YAML
+added: v7.13.0
+-->
+
+* `requestOpts` {Object} Dispatch options identifying the snapshot to inspect.
+* Returns: {Object|null} Information about the matching snapshot, or `null` when
+  none is found.
+  * `hash` {string} The hash used to key the snapshot.
+  * `request` {Object} The recorded request.
+    * `method` {string} The request method.
+    * `url` {string} The request URL.
+    * `headers` {Record<string, string>} The recorded request headers.
+    * `body` {string} The recorded request body, when present.
+  * `responseCount` {number} The number of recorded responses for the request.
+  * `callCount` {number} The number of times the snapshot has been matched.
+  * `timestamp` {string} The ISO timestamp at which the snapshot was recorded.
+
+Returns metadata about a snapshot without returning the response payload.
+
+```mjs
+const info = agent.getSnapshotInfo({
+  method: 'GET',
+  origin: 'https://api.example.com',
+  path: '/users'
+})
+```
+
+### `agent.replaceSnapshots(snapshotData)`
+
+<!-- YAML
+added: v7.13.0
+-->
+
+* `snapshotData` {Array} The snapshot data to load, replacing any existing
+  snapshots.
+  * `hash` {string} The hash used to key the snapshot.
+  * `snapshot` {Object} The snapshot entry.
+* Returns: {undefined}
+
+Replaces all in-memory snapshots with the provided data.
+
+```mjs
+const recorder = agent.getRecorder()
+const snapshots = recorder.getSnapshots()
+
+agent.replaceSnapshots(snapshots.map((snapshot, index) => ({
+  hash: `snapshot-${index}`,
+  snapshot
+})))
+```
+
+### `agent.close()`
+
+<!-- YAML
+added: v7.13.0
+-->
+
+* Returns: {Promise<void>} Resolves once the agent and its resources are closed.
+
+Closes the agent and releases its resources. In `'record'` and `'update'` modes
+the recorder is flushed to disk first. In `'playback'` mode nothing is written,
+because matching a snapshot mutates its call count and saving would needlessly
+rewrite the snapshot file. The real [`Agent`][], when one was created, and the
+underlying [`MockAgent`][] are closed as well.
+
+```mjs
+await agent.close()
+```
+
+[`Agent`]: Agent.md#class-agent
+[`Dispatcher`]: Dispatcher.md#class-dispatcher
+[`InvalidArgumentError`]: Errors.md#undicierrorsundiciinvalidargumenterror
+[`MockAgent`]: MockAgent.md#class-mockagent
+[`UndiciError`]: Errors.md#undicierrorsundicierror
+[`agent.getRecorder()`]: #agentgetrecorder
+[`setGlobalDispatcher()`]: Dispatcher.md#setglobaldispatcherdispatcher