@emiliosp/pi-maestro 0.17.0 → 0.18.0

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

@@ -1,239 +0,0 @@
-# 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/node_modules/undici/docs/docs/api/SnapshotAgent.md

@@ -1,361 +0,0 @@
-# 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