monitor-transfer-dsh 0.0.0-stage → 0.1.2

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

@@ -0,0 +1,278 @@
+# Pool
+
+<!--introduced_in=v1.0.0-->
+
+<!--type=module-->
+
+<!-- source_link=lib/dispatcher/pool.js -->
+
+> Stability: 2 - Stable
+
+A pool of [`Client`][] instances connected to the same upstream origin. A `Pool`
+spreads requests across several connections to the same host, which allows more
+than one request to be in flight at a time without enabling pipelining on a
+single connection.
+
+`Pool` extends [`Dispatcher`][]. Each [`Client`][] in the pool is created lazily
+through a configurable `factory` and shares the same options. Requests are not
+guaranteed to be dispatched in the order in which they are invoked.
+
+```mjs
+import { Pool } from 'undici'
+
+const pool = new Pool('http://localhost:3000', { connections: 10 })
+const { statusCode, body } = await pool.request({ path: '/', method: 'GET' })
+console.log(statusCode, await body.text())
+await pool.close()
+```
+
+## Class: `Pool`
+
+<!-- YAML
+added: v1.0.0
+changes:
+  - version: v4.10.4
+    pr-url: https://github.com/nodejs/undici/pull/1114
+    description: Reworked as part of the balanced pool implementation.
+-->
+
+* Extends: {Dispatcher}
+
+### `new Pool(url[, options])`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* `url` {URL|string} The upstream origin. It should only include the protocol,
+  hostname, and port.
+* `options` {PoolOptions} (optional) Extends {ClientOptions}, so every
+  [`Client`][] option is also accepted and forwarded to each pooled client.
+  * `factory` {Function} Creates the [`Client`][] (or other [`Dispatcher`][])
+    instances used by the pool.
+    **Default:** `(origin, opts) => new Client(origin, opts)`.
+    * `origin` {URL} The parsed upstream origin.
+    * `opts` {Object} The resolved client options.
+    * Returns: {Dispatcher}
+  * `connections` {number|null} The maximum number of [`Client`][] instances the
+    pool may create. When set to `null` the pool creates an unlimited number of
+    clients. **Default:** `null`.
+  * `clientTtl` {number|null} The amount of time, in milliseconds, before an idle
+    [`Client`][] is removed from the pool and closed. When set to `null` clients
+    are never removed based on age. **Default:** `null`.
+
+Creates a new `Pool` against `url`. If `connections` is provided it must be a
+finite, non-negative number, otherwise an [`InvalidArgumentError`][] is thrown.
+The `factory` must be a function, and `connect` (inherited from {ClientOptions})
+must be a function or an object when provided.
+
+The connection-related {ClientOptions} (`connect`, `connectTimeout`, `tls`,
+`maxCachedSessions`, `socketPath`, `autoSelectFamily`,
+`autoSelectFamilyAttemptTimeout`, `allowH2`, and `useH2c`) are used to build the
+connector shared by every pooled client.
+
+> [!NOTE]
+> `Pool` inherits all {ClientOptions}, including `allowH2` and
+> `maxConcurrentStreams`. For an h2-capable HTTPS origin, the pool waits for
+> the first TLS connection to finish ALPN negotiation before opening more
+> clients. If the server selects h2, concurrent requests share that session up
+> to `maxConcurrentStreams`. If it selects HTTP/1.1, the pool resumes normal
+> connection fan-out up to `connections`.
+
+```mjs
+import { Pool } from 'undici'
+
+const pool = new Pool('http://localhost:3000', {
+  connections: 128,
+  pipelining: 1
+})
+```
+
+### `pool.closed`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* Type: {boolean}
+
+`true` after [`pool.close()`][] has been called.
+
+### `pool.destroyed`
+
+<!-- YAML
+added: v1.0.0
+changes:
+  - version: v2.0.0
+    pr-url: https://github.com/nodejs/undici/pull/384
+    description: Reflects the state set by `pool.close()`.
+  - version: v4.10.4
+    pr-url: https://github.com/nodejs/undici/pull/1114
+    description: Reworked as part of the balanced pool implementation.
+-->
+
+* Type: {boolean}
+
+`true` after [`pool.destroy()`][] has been called, or after [`pool.close()`][]
+has been called and the pool shutdown has completed.
+
+### `pool.stats`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* Type: {PoolStats}
+
+Aggregate statistics for the pool. See [`PoolStats`][].
+
+### `pool.close([callback])`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+Implements [`dispatcher.close([callback])`][]. Gracefully closes the pool and
+all of its clients, waiting for in-flight requests to complete. Resolves once
+every pooled client has closed.
+
+### `pool.destroy([error[, callback]])`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+Implements [`dispatcher.destroy([error[, callback]])`][]. Forcefully destroys
+the pool and all of its clients, aborting any in-flight requests with `error`.
+
+### `pool.connect(options[, callback])`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+See [`dispatcher.connect(options[, callback])`][]. Performs an HTTP `CONNECT`
+request through one of the pooled clients.
+
+### `pool.dispatch(options, handler)`
+
+<!-- YAML
+added: v1.3.0
+changes:
+  - version: v4.10.4
+    pr-url: https://github.com/nodejs/undici/pull/1114
+    description: Reworked as part of the balanced pool implementation.
+-->
+
+Implements [`dispatcher.dispatch(options, handler)`][]. Selects an available
+client - creating a new one through `factory` when none is free and the
+`connections` limit has not been reached - and dispatches the request to it.
+
+### `pool.pipeline(options, handler)`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+See [`dispatcher.pipeline(options, handler)`][]. Sends a request and returns a
+{Duplex} stream that pipes the request body to the response body through
+`handler`.
+
+### `pool.request(options[, callback])`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+See [`dispatcher.request(options[, callback])`][]. Performs a request through one
+of the pooled clients.
+
+```mjs
+import { Pool } from 'undici'
+
+const pool = new Pool('http://localhost:3000', { connections: 10 })
+const { statusCode, headers, body } = await pool.request({
+  path: '/',
+  method: 'GET'
+})
+console.log(statusCode, headers)
+console.log(await body.text())
+await pool.close()
+```
+
+### `pool.stream(options, factory[, callback])`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+See [`dispatcher.stream(options, factory[, callback])`][]. Performs a request and
+writes the response body into the {Writable} stream returned by `factory`.
+
+### `pool.upgrade(options[, callback])`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+See [`dispatcher.upgrade(options[, callback])`][]. Upgrades a connection
+(for example to a WebSocket) through one of the pooled clients.
+
+### Event: `'connect'`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* `origin` {URL}
+* `targets` {Array} The pool followed by the client that connected,
+  `[pool, ...targets]`.
+
+Emitted by a pooled client when a socket has connected. See
+[`Dispatcher` Event: `'connect'`][]. When `clientTtl` is set, the connecting
+client's time-to-live timer starts on this event.
+
+### Event: `'disconnect'`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* `origin` {URL}
+* `targets` {Array} The pool followed by the client that disconnected,
+  `[pool, ...targets]`.
+* `error` {Error}
+
+Emitted by a pooled client when a socket has disconnected. See
+[`Dispatcher` Event: `'disconnect'`][].
+
+### Event: `'drain'`
+
+<!-- YAML
+added: v1.0.0
+-->
+
+* `origin` {URL}
+* `targets` {Array} The pool followed by the client that drained,
+  `[pool, ...targets]`.
+
+Emitted when a pooled client is no longer busy and can accept more requests. See
+[`Dispatcher` Event: `'drain'`][].
+
+[`Client`]: Client.md#class-client
+[`Dispatcher` Event: `'connect'`]: Dispatcher.md#event-connect
+[`Dispatcher` Event: `'disconnect'`]: Dispatcher.md#event-disconnect
+[`Dispatcher` Event: `'drain'`]: Dispatcher.md#event-drain
+[`Dispatcher`]: Dispatcher.md#class-dispatcher
+[`InvalidArgumentError`]: Errors.md#class-invalidargumenterror
+[`PoolStats`]: PoolStats.md
+[`dispatcher.close([callback])`]: Dispatcher.md#dispatcherclosecallback
+[`dispatcher.connect(options[, callback])`]: Dispatcher.md#dispatcherconnectoptions-callback
+[`dispatcher.destroy([error[, callback]])`]: Dispatcher.md#dispatcherdestroyerror-callback
+[`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
+[`pool.close()`]: #poolclosecallback
+[`pool.destroy()`]: #pooldestroyerror-callback

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

@@ -0,0 +1,141 @@
+# PoolStats
+
+<!--introduced_in=v4.15.0-->
+<!--type=module-->
+<!-- source_link=lib/util/stats.js -->
+
+> Stability: 2 - Stable
+
+`PoolStats` exposes a read-only snapshot of the aggregate connection and request
+counters for a [`Pool`][] or [`BalancedPool`][]. An instance is created lazily
+each time the `pool.stats` getter is accessed, so the values reflect the state of
+the pool at the moment of access.
+
+`PoolStats` is not constructed directly in normal use; obtain an instance from
+the `stats` property of a pool:
+
+```mjs
+import { Pool } from 'undici'
+
+const pool = new Pool('http://localhost:3000')
+const { stats } = pool
+
+console.log(stats.connected, stats.running, stats.size)
+```
+
+## Class: `PoolStats`
+
+<!-- YAML
+added: v4.15.0
+changes:
+  - version: v7.9.0
+    pr-url: https://github.com/nodejs/undici/pull/4157
+    description: Pool and client stats are exposed through `Agent`.
+-->
+
+Each property is a plain number computed from the pool's internal state when the
+instance is created. The instance is a snapshot; read `pool.stats` again to
+observe later changes.
+
+### `new PoolStats(pool)`
+
+<!-- YAML
+added: v4.15.0
+changes:
+  - version: v7.9.0
+    pr-url: https://github.com/nodejs/undici/pull/4157
+    description: Pool and client stats are exposed through `Agent`.
+-->
+
+* `pool` {Pool|BalancedPool} The pool to read counters from.
+
+Creates a new `PoolStats` instance from the current state of `pool`. Prefer the
+`pool.stats` getter, which returns a fresh `PoolStats` on each access.
+
+### `poolStats.connected`
+
+<!-- YAML
+added: v4.15.0
+changes:
+  - version: v7.9.0
+    pr-url: https://github.com/nodejs/undici/pull/4157
+    description: Pool and client stats are exposed through `Agent`.
+-->
+
+* Type: {number}
+
+Number of open socket connections in this pool.
+
+### `poolStats.free`
+
+<!-- YAML
+added: v4.15.0
+changes:
+  - version: v7.9.0
+    pr-url: https://github.com/nodejs/undici/pull/4157
+    description: Pool and client stats are exposed through `Agent`.
+-->
+
+* Type: {number}
+
+Number of open socket connections in this pool that do not have an active
+request.
+
+### `poolStats.pending`
+
+<!-- YAML
+added: v4.15.0
+changes:
+  - version: v7.9.0
+    pr-url: https://github.com/nodejs/undici/pull/4157
+    description: Pool and client stats are exposed through `Agent`.
+-->
+
+* Type: {number}
+
+Number of pending requests across all clients in this pool.
+
+### `poolStats.queued`
+
+<!-- YAML
+added: v4.15.0
+changes:
+  - version: v7.9.0
+    pr-url: https://github.com/nodejs/undici/pull/4157
+    description: Pool and client stats are exposed through `Agent`.
+-->
+
+* Type: {number}
+
+Number of queued requests across all clients in this pool.
+
+### `poolStats.running`
+
+<!-- YAML
+added: v4.15.0
+changes:
+  - version: v7.9.0
+    pr-url: https://github.com/nodejs/undici/pull/4157
+    description: Pool and client stats are exposed through `Agent`.
+-->
+
+* Type: {number}
+
+Number of currently active requests across all clients in this pool.
+
+### `poolStats.size`
+
+<!-- YAML
+added: v4.15.0
+changes:
+  - version: v7.9.0
+    pr-url: https://github.com/nodejs/undici/pull/4157
+    description: Pool and client stats are exposed through `Agent`.
+-->
+
+* Type: {number}
+
+Number of active, pending, or queued requests across all clients in this pool.
+
+[`BalancedPool`]: BalancedPool.md#class-balancedpool
+[`Pool`]: Pool.md#class-pool

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

@@ -0,0 +1,248 @@
+# ProxyAgent
+
+<!--introduced_in=v4.8.2-->
+<!--type=module-->
+<!-- source_link=lib/dispatcher/proxy-agent.js -->
+
+> Stability: 2 - Stable
+
+A `ProxyAgent` routes every request through an HTTP, HTTPS, or SOCKS5 proxy
+server. It implements the [`Agent`][] API, so it can be used wherever a
+dispatcher is accepted, for example with [`request`][] or [`fetch`][], or
+installed globally with [`setGlobalDispatcher`][].
+
+For secure (`https:`) endpoints the proxy connection is established through an
+HTTP `CONNECT` tunnel. SOCKS5 proxies (`socks5:` or `socks:` URIs) are handled
+by delegating to a [`Socks5ProxyAgent`][].
+
+```mjs
+import { ProxyAgent, setGlobalDispatcher } from 'undici'
+
+const proxyAgent = new ProxyAgent('http://localhost:8000')
+setGlobalDispatcher(proxyAgent)
+```
+
+## Class: `ProxyAgent`
+
+<!-- YAML
+added: v4.8.2
+-->
+
+* Extends: {Dispatcher}
+
+`ProxyAgent` keeps an internal [`Agent`][] that creates per-origin dispatchers
+on demand. The proxy connection is set up lazily when the first request to an
+origin is dispatched, then reused for subsequent requests to the same origin.
+
+### `new ProxyAgent(options)`
+
+<!-- YAML
+added: v4.8.2
+-->
+
+* `options` {ProxyAgentOptions|string|URL} The proxy URI, or an options object.
+  Required. When a `string` or {URL} is passed it is used as the proxy `uri`.
+  The options object extends {AgentOptions} (omitting `connect`).
+  * `uri` {string} The URI of the proxy server. Required when `options` is an
+    object. Parsed into a {URL} according to the
+    [WHATWG URL Specification][].
+  * `token` {string} A pre-formatted `proxy-authorization` header value sent to
+    the proxy on every request, for example `` `Bearer ${apiKey}` ``.
+  * `auth` {string} A base64-encoded `username:password` credential sent as a
+    `Basic` `proxy-authorization` header. Cannot be combined with `token`.
+  * `headers` {Object} Additional headers sent to the proxy server on the
+    `CONNECT` request (or on every request for an untunneled HTTP proxy).
+    **Default:** `{}`.
+  * `requestTls` {BuildOptions} TLS options for the connection to the request
+    endpoint, passed to the connector builder.
+  * `proxyTls` {BuildOptions} TLS options for the connection to the proxy
+    server, passed to the connector builder.
+  * `clientFactory` {Function} Builds the {Dispatcher} used to talk to the proxy
+    server itself. **Default:** `(origin, opts) => new Pool(origin, opts)`.
+    * `origin` {URL} The proxy origin.
+    * `opts` {Object} The resolved options for the dispatcher.
+    * Returns: {Dispatcher}
+  * `proxyTunnel` {boolean} Forces tunneling through the proxy. By default,
+    Undici detects tunneling based on the request protocol. If the target
+    endpoint uses HTTPS, Undici establishes a `CONNECT` tunnel through the proxy
+    (after the TLS handshake to the proxy itself when the proxy URL is HTTPS).
+    If the target endpoint uses plain HTTP, Undici forwards the request to the
+    proxy using an HTTP/1.1 absolute-form request target (over TLS when the
+    proxy URL is HTTPS), as required by
+    [RFC 9112 §3.2.2](https://www.rfc-editor.org/rfc/rfc9112.html#name-absolute-form).
+    This non-tunneled forwarding path does not negotiate HTTP/2 with the proxy.
+    Set `proxyTunnel` to `true` to force tunneling for plain HTTP requests as
+    well. Currently, there is no way to facilitate HTTP/1.1 IP tunneling as
+    described in
+    [RFC 9484](https://www.rfc-editor.org/rfc/rfc9484.html#name-http-11-request).
+
+Throws an {InvalidArgumentError} when no proxy URI is provided, when
+`clientFactory` is not a function, or when both `auth` and `token` are supplied.
+
+The `proxy-authorization` header is derived, in order of precedence, from
+`token`, then `auth`, then the `username` and `password` embedded in the proxy
+`uri`. Credentials in the URI are URL-decoded before being base64-encoded.
+
+> [!NOTE]
+> Unless {AgentOptions} `connections` is set to `0`, the non-standard
+> `proxy-connection: keep-alive` header is added to the tunnel `CONNECT`
+> request. This includes the default case where `connections` is unset.
+
+The `auth` option is deprecated; use `token` instead.
+
+```mjs
+import { ProxyAgent } from 'undici'
+
+// A string or URL is treated as the proxy uri.
+const a = new ProxyAgent('http://localhost:8000')
+const b = new ProxyAgent(new URL('http://localhost:8000'))
+
+// An options object requires a `uri`.
+const c = new ProxyAgent({ uri: 'http://localhost:8000' })
+
+// With proxy TLS settings.
+const d = new ProxyAgent({
+  uri: 'https://secure.proxy.server',
+  proxyTls: {
+    signal: AbortSignal.timeout(1000),
+  },
+})
+```
+
+#### Example - proxy request with the global dispatcher
+
+```mjs
+import { setGlobalDispatcher, request, ProxyAgent } from 'undici'
+
+const proxyAgent = new ProxyAgent('http://localhost:8000')
+setGlobalDispatcher(proxyAgent)
+
+const { statusCode, body } = await request('http://localhost:3000/foo')
+
+console.log('response received', statusCode)
+console.log('data', await body.text())
+```
+
+#### Example - proxy request with a local dispatcher
+
+```mjs
+import { ProxyAgent, request } from 'undici'
+
+const proxyAgent = new ProxyAgent('http://localhost:8000')
+
+const { statusCode, body } = await request('http://localhost:3000/foo', {
+  dispatcher: proxyAgent,
+})
+
+console.log('response received', statusCode)
+console.log('data', await body.text())
+```
+
+#### Example - proxy request with authentication
+
+```mjs
+import { setGlobalDispatcher, request, ProxyAgent } from 'undici'
+
+const proxyAgent = new ProxyAgent({
+  uri: 'http://localhost:8000',
+  token: `Basic ${Buffer.from('username:password').toString('base64')}`,
+})
+setGlobalDispatcher(proxyAgent)
+
+const { statusCode } = await request('http://localhost:3000/foo')
+
+console.log('response received', statusCode)
+```
+
+### `proxyAgent.dispatch(options, handler)`
+
+<!-- YAML
+added: v4.8.2
+-->
+
+* `options` {AgentDispatchOptions} Extends {DispatchOptions}.
+  * `origin` {string|URL} The origin to dispatch the request against. Required.
+* `handler` {DispatchHandler}
+* Returns: {boolean} `false` if the dispatcher is busy and the caller should
+  wait for the [`'drain'`][] event before dispatching again.
+
+Dispatches the request through the proxy. Throws an {InvalidArgumentError} if
+the request headers contain a `proxy-authorization` header, which must instead
+be supplied through the constructor's `token` or `auth` option. A `host` header
+is derived from `options.origin` when one is not already present. Implements
+[`Dispatcher.dispatch()`][].
+
+### `proxyAgent.close()`
+
+<!-- YAML
+added: v4.8.2
+changes:
+  - version: v7.10.0
+    pr-url: https://github.com/nodejs/undici/pull/4180
+    description: Untunneled HTTP-to-HTTP proxy connections match `curl` behavior.
+-->
+
+* Returns: {Promise<void>}
+
+Closes the proxy agent and waits for its internal agent and proxy client (when
+present) to close before resolving. Implements [`Dispatcher.close()`][].
+
+```mjs
+import { ProxyAgent, setGlobalDispatcher } from 'undici'
+
+const proxyAgent = new ProxyAgent('http://localhost:8000')
+setGlobalDispatcher(proxyAgent)
+
+await proxyAgent.close()
+```
+
+### `proxyAgent.request(options[, callback])`
+
+<!-- YAML
+added: v5.0.0
+-->
+
+See [`Dispatcher.request()`][]. The request is routed through the proxy.
+
+#### Example - proxy request with `fetch`
+
+```mjs
+import { ProxyAgent, fetch } from 'undici'
+
+const proxyAgent = new ProxyAgent('http://localhost:8000')
+
+const response = await fetch('http://localhost:3000/foo', {
+  dispatcher: proxyAgent,
+  method: 'GET',
+})
+
+console.log('response status', response.status)
+console.log('response data', await response.text())
+```
+
+#### Example - HTTPS tunneling
+
+```mjs
+import { ProxyAgent, fetch } from 'undici'
+
+const proxyAgent = new ProxyAgent('https://secure.proxy.server')
+
+const response = await fetch('https://secure.endpoint.com/api/data', {
+  dispatcher: proxyAgent,
+  method: 'GET',
+})
+
+console.log('response status', response.status)
+console.log('response data', await response.json())
+```
+
+[WHATWG URL Specification]: https://url.spec.whatwg.org
+[`'drain'`]: Dispatcher.md#event-drain
+[`Agent`]: Agent.md#class-agent
+[`Dispatcher.close()`]: Dispatcher.md#dispatcherclosecallback-promise
+[`Dispatcher.dispatch()`]: Dispatcher.md#dispatcherdispatchoptions-handler
+[`Dispatcher.request()`]: Dispatcher.md#dispatcherrequestoptions-callback
+[`Socks5ProxyAgent`]: Socks5ProxyAgent.md#class-socks5proxyagent
+[`fetch`]: Fetch.md
+[`request`]: Dispatcher.md#dispatcherrequestoptions-callback
+[`setGlobalDispatcher`]: Dispatcher.md#setglobaldispatcherdispatcher