undici 8.4.1 → 8.6.0

package/docs/docs/api/BalancedPool.md

@@ -1,99 +1,297 @@
-# Class: BalancedPool
+# BalancedPool
 
-Extends: `undici.Dispatcher`
+<!--introduced_in=v4.8.0-->
+<!--type=module-->
+<!-- source_link=lib/dispatcher/balanced-pool.js -->
 
-A pool of [Pool](/docs/docs/api/Pool.md) instances connected to multiple upstreams.
+> Stability: 2 - Stable
 
-Requests are not guaranteed to be dispatched in order of invocation.
+A `BalancedPool` distributes requests across a set of {Pool} instances, each
+connected to a different upstream. It uses a weighted round-robin algorithm:
+every upstream starts with the same weight, and the weight is adjusted up on
+successful connections and down on connection errors, so that healthy upstreams
+receive a larger share of traffic.
 
-## `new BalancedPool(upstreams [, options])`
+Requests are not guaranteed to be dispatched in the order they are issued.
 
-Arguments:
+```mjs
+import { BalancedPool } from 'undici'
 
-* **upstreams** `URL | string | string[]` - It should only include the **protocol, hostname, and port**.
-* **options** `BalancedPoolOptions` (optional)
+const pool = new BalancedPool([
+  'http://localhost:3000',
+  'http://localhost:3001',
+  'http://localhost:3002',
+])
 
-### Parameter: `BalancedPoolOptions`
+const { statusCode, body } = await pool.request({
+  path: '/',
+  method: 'GET',
+})
+console.log('response received', statusCode)
+for await (const chunk of body) {
+  console.log('data', chunk.toString())
+}
+```
 
-Extends: [`PoolOptions`](/docs/docs/api/Pool.md#parameter-pooloptions)
+## Class: `BalancedPool`
 
-* **factory** `(origin: URL, opts: Object) => Dispatcher` - Default: `(origin, opts) => new Pool(origin, opts)`
+<!-- YAML
+added: v4.8.0
+changes:
+  - version: v4.10.4
+    pr-url: https://github.com/nodejs/undici/pull/1114
+    description: Introduced the `BalancedPool` class.
+-->
 
-The `PoolOptions` are passed to each of the `Pool` instances being created.
-## Instance Properties
+* Extends: {Dispatcher}
 
-### `BalancedPool.upstreams`
+A pool of {Pool} instances connected to multiple upstreams.
 
-Returns an array of upstreams that were previously added.
+### `new BalancedPool(upstreams[, options])`
 
-### `BalancedPool.closed`
+<!-- YAML
+added: v4.8.0
+changes:
+  - version: v4.15.0
+    pr-url: https://github.com/nodejs/undici/pull/1237
+    description: Added the `factory` option.
+-->
 
-Implements [Client.closed](/docs/docs/api/Client.md#clientclosed)
+* `upstreams` {URL|string|URL[]|string[]} One or more upstream origins. Each
+  value should only include the **protocol, hostname, and port**. **Default:**
+  `[]`.
+* `options` {BalancedPoolOptions} (optional)
 
-### `BalancedPool.destroyed`
+The options passed to the constructor are forwarded to every {Pool} instance
+that is created for an upstream.
 
-Implements [Client.destroyed](/docs/docs/api/Client.md#clientdestroyed)
+#### Parameter: `BalancedPoolOptions`
 
-### `BalancedPool.stats`
+Extends: {PoolOptions}
 
-Returns [`PoolStats`](/docs/docs/api/PoolStats.md) instance for this pool.
+In addition to all {PoolOptions}, the following options are supported:
 
-## Instance Methods
+* `factory` {Function} A function used to create the {Pool} instance for each
+  upstream. **Default:** `(origin, opts) => new Pool(origin, opts)`.
+  * `origin` {URL|string} The upstream origin.
+  * `opts` {Object} The options object derived from the constructor options.
+  * Returns: {Dispatcher}
+* `maxWeightPerServer` {number} The maximum weight any single upstream can
+  reach. Successful connections increase an upstream's weight up to this value.
+  **Default:** `100`.
+* `errorPenalty` {number} The amount by which an upstream's weight is decreased
+  on a connection error and increased on a successful connection. **Default:**
+  `15`.
 
-### `BalancedPool.addUpstream(upstream)`
+### `balancedPool.addUpstream(upstream)`
 
-Add an upstream.
+<!-- YAML
+added: v4.8.0
+-->
 
-Arguments:
+* `upstream` {URL|string} The upstream origin to add. It should only include the
+  **protocol, hostname, and port**.
+* Returns: {BalancedPool} The `BalancedPool` instance, for chaining.
 
-* **upstream** `string` - It should only include the **protocol, hostname, and port**.
+Adds an upstream. If an open, non-destroyed upstream with the same origin is
+already present, the call is a no-op.
 
-### `BalancedPool.removeUpstream(upstream)`
+### `balancedPool.removeUpstream(upstream)`
 
-Removes an upstream that was previously added.
+<!-- YAML
+added: v4.8.0
+-->
 
-### `BalancedPool.close([callback])`
+* `upstream` {URL|string} The upstream origin to remove. It should only include
+  the **protocol, hostname, and port**.
+* Returns: {BalancedPool} The `BalancedPool` instance, for chaining.
 
-Implements [`Dispatcher.close([callback])`](/docs/docs/api/Dispatcher.md#dispatcherclosecallback-promise).
+Removes an upstream that was previously added. If no matching upstream is found,
+the call is a no-op.
 
-### `BalancedPool.destroy([error, callback])`
+### `balancedPool.getUpstream(upstream)`
 
-Implements [`Dispatcher.destroy([error, callback])`](/docs/docs/api/Dispatcher.md#dispatcherdestroyerror-callback-promise).
+<!-- YAML
+added: v7.17.0
+-->
 
-### `BalancedPool.connect(options[, callback])`
+* `upstream` {URL|string} The upstream origin to look up. It should only include
+  the **protocol, hostname, and port**.
+* Returns: {Pool|undefined} The {Pool} instance managing the given upstream, or
+  `undefined` if it is not present.
 
-See [`Dispatcher.connect(options[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherconnectoptions-callback).
+Returns the {Pool} instance for the given upstream origin, if it is open and not
+destroyed.
 
-### `BalancedPool.dispatch(options, handlers)`
+### `balancedPool.upstreams`
 
-Implements [`Dispatcher.dispatch(options, handlers)`](/docs/docs/api/Dispatcher.md#dispatcherdispatchoptions-handler).
+<!-- YAML
+added: v4.8.0
+-->
 
-### `BalancedPool.pipeline(options, handler)`
+* Type: {string[]} The origins of the upstreams that are currently open and not
+  destroyed.
 
-See [`Dispatcher.pipeline(options, handler)`](/docs/docs/api/Dispatcher.md#dispatcherpipelineoptions-handler).
+### `balancedPool.closed`
 
-### `BalancedPool.request(options[, callback])`
+<!-- YAML
+added: v4.8.0
+changes:
+  - version: v4.10.4
+    pr-url: https://github.com/nodejs/undici/pull/1114
+    description: Introduced the `BalancedPool` class.
+-->
 
-See [`Dispatcher.request(options [, callback])`](/docs/docs/api/Dispatcher.md#dispatcherrequestoptions-callback).
+* Type: {boolean} `true` after `balancedPool.close()` has been called.
 
-### `BalancedPool.stream(options, factory[, callback])`
+Implements [`client.closed`][].
 
-See [`Dispatcher.stream(options, factory[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherstreamoptions-factory-callback).
+### `balancedPool.destroyed`
 
-### `BalancedPool.upgrade(options[, callback])`
+<!-- YAML
+added: v4.8.0
+changes:
+  - version: v4.10.4
+    pr-url: https://github.com/nodejs/undici/pull/1114
+    description: Introduced the `BalancedPool` class.
+-->
 
-See [`Dispatcher.upgrade(options[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherupgradeoptions-callback).
+* Type: {boolean} `true` after `balancedPool.destroy()` has been called, or after
+  `balancedPool.close()` has been called and the shutdown has completed.
 
-## Instance Events
+Implements [`client.destroyed`][].
+
+### `balancedPool.stats`
+
+<!-- YAML
+added: v4.8.0
+-->
+
+* Type: {PoolStats}
+
+Returns a {PoolStats} instance aggregating the statistics of the underlying
+pools.
+
+### `balancedPool.close([callback])`
+
+<!-- YAML
+added: v4.8.0
+-->
+
+Implements [`Dispatcher.close([callback])`][].
+
+### `balancedPool.destroy([error[, callback]])`
+
+<!-- YAML
+added: v4.8.0
+-->
+
+Implements [`Dispatcher.destroy([error, callback])`][].
+
+### `balancedPool.connect(options[, callback])`
+
+<!-- YAML
+added: v4.8.0
+-->
+
+See [`Dispatcher.connect(options[, callback])`][].
+
+### `balancedPool.dispatch(options, handlers)`
+
+<!-- YAML
+added: v4.8.0
+changes:
+  - version: v4.10.4
+    pr-url: https://github.com/nodejs/undici/pull/1114
+    description: Introduced the `BalancedPool` class.
+-->
+
+Implements [`Dispatcher.dispatch(options, handler)`][].
+
+### `balancedPool.pipeline(options, handler)`
+
+<!-- YAML
+added: v4.8.0
+-->
+
+See [`Dispatcher.pipeline(options, handler)`][].
+
+### `balancedPool.request(options[, callback])`
+
+<!-- YAML
+added: v4.8.0
+-->
+
+See [`Dispatcher.request(options[, callback])`][].
+
+### `balancedPool.stream(options, factory[, callback])`
+
+<!-- YAML
+added: v4.8.0
+-->
+
+See [`Dispatcher.stream(options, factory[, callback])`][].
+
+### `balancedPool.upgrade(options[, callback])`
+
+<!-- YAML
+added: v4.8.0
+-->
+
+See [`Dispatcher.upgrade(options[, callback])`][].
 
 ### Event: `'connect'`
 
-See [Dispatcher Event: `'connect'`](/docs/docs/api/Dispatcher.md#event-connect).
+<!-- YAML
+added: v4.8.0
+changes:
+  - version: v4.10.4
+    pr-url: https://github.com/nodejs/undici/pull/1114
+    description: Introduced the `BalancedPool` class.
+  - version: v5.8.0
+    pr-url: https://github.com/nodejs/undici/pull/1069
+    description: Adopted weighted round-robin selection across upstreams.
+-->
+
+See [Dispatcher Event: `'connect'`][].
 
 ### Event: `'disconnect'`
 
-See [Dispatcher Event: `'disconnect'`](/docs/docs/api/Dispatcher.md#event-disconnect).
+<!-- YAML
+added: v4.8.0
+changes:
+  - version: v4.10.4
+    pr-url: https://github.com/nodejs/undici/pull/1114
+    description: Introduced the `BalancedPool` class.
+  - version: v5.8.0
+    pr-url: https://github.com/nodejs/undici/pull/1069
+    description: Adopted weighted round-robin selection across upstreams.
+-->
+
+See [Dispatcher Event: `'disconnect'`][].
 
 ### Event: `'drain'`
 
-See [Dispatcher Event: `'drain'`](/docs/docs/api/Dispatcher.md#event-drain).
+<!-- YAML
+added: v4.8.0
+changes:
+  - version: v4.10.4
+    pr-url: https://github.com/nodejs/undici/pull/1114
+    description: Introduced the `BalancedPool` class.
+-->
+
+See [Dispatcher Event: `'drain'`][].
+
+[Dispatcher Event: `'connect'`]: Dispatcher.md#event-connect
+[Dispatcher Event: `'disconnect'`]: Dispatcher.md#event-disconnect
+[Dispatcher Event: `'drain'`]: Dispatcher.md#event-drain
+[`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
+[`client.closed`]: Client.md#clientclosed
+[`client.destroyed`]: Client.md#clientdestroyed

package/docs/docs/api/CacheStorage.md

@@ -1,30 +1,188 @@
 # CacheStorage
 
-Undici exposes a W3C spec-compliant implementation of [CacheStorage](https://developer.mozilla.org/en-US/docs/Web/API/CacheStorage) and [Cache](https://developer.mozilla.org/en-US/docs/Web/API/Cache).
+<!--introduced_in=v5.22.1-->
+<!--type=module-->
+<!-- source_link=lib/web/cache/cachestorage.js -->
 
-## Opening a Cache
+> Stability: 2 - Stable
 
-Undici exports a top-level CacheStorage instance. You can open a new Cache, or duplicate a Cache with an existing name, by using `CacheStorage.prototype.open`. If you open a Cache with the same name as an already-existing Cache, its list of cached Responses will be shared between both instances.
+undici provides a spec-compliant implementation of the [W3C Service Worker
+`CacheStorage`][] and [`Cache`][] interfaces. A `CacheStorage` is a named
+collection of [`Cache`][] objects, each of which stores `Request`/`Response`
+pairs.
+
+The class itself is not exported; instead, undici exposes a single shared
+`CacheStorage` instance named `caches`. Import it from `'undici'`:
+
+```mjs
+import { caches } from 'undici'
+
+const cache = await caches.open('v1')
+```
+
+```cjs
+const { caches } = require('undici')
+
+caches.open('v1').then((cache) => {
+  // ...
+})
+```
+
+## `caches`
+
+<!-- YAML
+added: v5.22.1
+-->
+
+* Type: {CacheStorage}
+
+The shared [`CacheStorage`](#class-cachestorage) instance exported by undici.
+All caches opened through `caches` live for the lifetime of the process.
+
+```mjs
+import { caches } from 'undici'
+
+await caches.open('v1')
+console.log(await caches.keys()) // ['v1']
+```
+
+## Class: `CacheStorage`
+
+<!-- YAML
+added: v5.22.1
+-->
+
+Represents the storage for [`Cache`][] objects. Each `CacheStorage` keeps a
+mapping of cache names to their backing list of cached responses.
+
+The constructor is not public: attempting to instantiate `CacheStorage`
+directly throws a `TypeError`. Use the exported [`caches`](#caches) instance
+instead.
+
+### `caches.match(request[, options])`
+
+<!-- YAML
+added: v5.22.1
+-->
+
+* `request` {Request|string} The request to match against. A string is treated
+  as a URL.
+* `options` {Object} (optional)
+  * `ignoreSearch` {boolean} When `true`, ignores the query string of the URL
+    when matching. **Default:** `false`.
+  * `ignoreMethod` {boolean} When `true`, prevents matching operations from
+    validating the `Request` `http` method. **Default:** `false`.
+  * `ignoreVary` {boolean} When `true`, ignores the `Vary` header when matching.
+    **Default:** `false`.
+  * `cacheName` {string} When set, restricts the search to the cache with this
+    name. **Default:** `undefined`.
+* Returns: {Promise} Fulfills with the first matching {Response}, or
+  `undefined` if no response matched.
+
+Searches the caches for a response matching `request`. When `options.cacheName`
+is provided, only that cache is searched; otherwise every cache is searched in
+insertion order and the first match is returned.
+
+```mjs
+import { caches } from 'undici'
+
+const response = await caches.match('https://example.com/data', {
+  cacheName: 'v1'
+})
+```
+
+### `caches.has(cacheName)`
+
+<!-- YAML
+added: v5.22.1
+-->
+
+* `cacheName` {string} The name of the cache to look up.
+* Returns: {Promise} Fulfills with `true` if a cache named `cacheName` exists,
+  otherwise `false`.
+
+Checks whether a cache with the given name exists in the storage.
+
+```mjs
+import { caches } from 'undici'
+
+await caches.open('v1')
+console.log(await caches.has('v1')) // true
+console.log(await caches.has('v2')) // false
+```
+
+### `caches.open(cacheName)`
+
+<!-- YAML
+added: v5.22.1
+-->
+
+* `cacheName` {string} The name of the cache to open.
+* Returns: {Promise} Fulfills with the {Cache} named `cacheName`.
+
+Opens the cache named `cacheName`, creating it if it does not already exist.
+
+Each call returns a new [`Cache`][] object, but caches opened with the same name
+share their underlying list of cached responses. As a result, a response stored
+through one instance is visible through another instance with the same name.
 
 ```mjs
 import { caches } from 'undici'
+import assert from 'node:assert'
 
-const cache_1 = await caches.open('v1')
-const cache_2 = await caches.open('v1')
+const cache1 = await caches.open('v1')
+const cache2 = await caches.open('v1')
 
-// Although .open() creates a new instance,
-assert(cache_1 !== cache_2)
-// The same Response is matched in both.
-assert.deepStrictEqual(await cache_1.match('/req'), await cache_2.match('/req'))
+// open() returns distinct objects,
+assert(cache1 !== cache2)
+// but they share the same cached responses.
+assert.deepStrictEqual(await cache1.match('/req'), await cache2.match('/req'))
 ```
 
-## Deleting a Cache
+### `caches.delete(cacheName)`
 
-If a Cache is deleted, the cached Responses/Requests can still be used.
+<!-- YAML
+added: v5.22.1
+-->
+
+* `cacheName` {string} The name of the cache to delete.
+* Returns: {Promise} Fulfills with `true` if the cache existed and was deleted,
+  otherwise `false`.
+
+Removes the cache named `cacheName` from the storage. Any [`Cache`][] objects
+already obtained for that name, along with the `Request`/`Response` pairs they
+returned, remain usable after deletion.
 
 ```mjs
-const response = await cache_1.match('/req')
+import { caches } from 'undici'
+
+const cache = await caches.open('v1')
+const response = await cache.match('/req')
+
 await caches.delete('v1')
 
-await response.text() // the Response's body
+// The already-retrieved response is still usable.
+await response.text()
 ```
+
+### `caches.keys()`
+
+<!-- YAML
+added: v5.22.1
+-->
+
+* Returns: {Promise} Fulfills with a {string[]} of cache names in insertion
+  order.
+
+Returns the names of all caches currently held by the storage.
+
+```mjs
+import { caches } from 'undici'
+
+await caches.open('v1')
+await caches.open('v2')
+console.log(await caches.keys()) // ['v1', 'v2']
+```
+
+[W3C Service Worker `CacheStorage`]: https://w3c.github.io/ServiceWorker/#cachestorage-interface
+[`Cache`]: https://w3c.github.io/ServiceWorker/#cache-interface