undici 7.0.0-alpha.1 → 7.0.0-alpha.3

package/README.md

@@ -132,7 +132,7 @@ Returns a promise with the result of the `Dispatcher.request` method.
 
 Calls `options.dispatcher.request(options)`.
 
-See [Dispatcher.request](./docs/docs/api/Dispatcher.md#dispatcherrequestoptions-callback) for more details, and [request examples](./examples/README.md) for examples.
+See [Dispatcher.request](./docs/docs/api/Dispatcher.md#dispatcherrequestoptions-callback) for more details, and [request examples](./docs/examples/README.md) for examples.
 
 ### `undici.stream([url, options, ]factory): Promise`
 
@@ -230,7 +230,7 @@ A body can be of the following types:
 - URLSearchParams
 - FormData
 
-In this implementation of fetch, ```request.body``` now accepts ```Async Iterables```. It is not present in the [Fetch Standard.](https://fetch.spec.whatwg.org)
+In this implementation of fetch, ```request.body``` now accepts ```Async Iterables```. It is not present in the [Fetch Standard](https://fetch.spec.whatwg.org).
 
 ```js
 import { fetch } from 'undici'
@@ -261,7 +261,7 @@ await fetch('http://example.com', { method: 'POST', body })
 
 - `'half'`
 
-In this implementation of fetch, `request.duplex` must be set if `request.body` is `ReadableStream` or `Async Iterables`, however, even though the value must be set to `'half'`, it is actually a _full_ duplex. For more detail refer to the [Fetch Standard.](https://fetch.spec.whatwg.org/#dom-requestinit-duplex).
+In this implementation of fetch, `request.duplex` must be set if `request.body` is `ReadableStream` or `Async Iterables`, however, even though the value must be set to `'half'`, it is actually a _full_ duplex. For more detail refer to the [Fetch Standard](https://fetch.spec.whatwg.org/#dom-requestinit-duplex).
 
 #### `response.body`
 

package/docs/docs/api/CacheStore.md

@@ -0,0 +1,116 @@
+# Cache Store
+
+A Cache Store is responsible for storing and retrieving cached responses.
+It is also responsible for deciding which specific response to use based off of
+a response's `Vary` header (if present).
+
+## Pre-built Cache Stores
+
+### `MemoryCacheStore`
+
+The `MemoryCacheStore` stores the responses in-memory.
+
+**Options**
+
+- `maxEntries` - The maximum amount of responses to store. Default `Infinity`.
+- `maxEntrySize` - The maximum size in bytes that a response's body can be. If a response's body is greater than or equal to this, the response will not be cached.
+
+## Defining a Custom Cache Store
+
+The store must implement the following functions:
+
+### Getter: `isFull`
+
+This tells the cache interceptor if the store is full or not. If this is true,
+the cache interceptor will not attempt to cache the response.
+
+### Function: `createReadStream`
+
+Parameters:
+
+* **req** `Dispatcher.RequestOptions` - Incoming request
+
+Returns: `CacheStoreReadable | Promise<CacheStoreReadable | undefined> | undefined` - If the request is cached, a readable for the body is returned. Otherwise, `undefined` is returned.
+
+### Function: `createWriteStream`
+
+Parameters:
+
+* **req** `Dispatcher.RequestOptions` - Incoming request
+* **value** `CacheStoreValue` - Response to store
+
+Returns: `CacheStoreWriteable | undefined` - If the store is full, return `undefined`. Otherwise, return a writable so that the cache interceptor can stream the body and trailers to the store.
+
+## `CacheStoreValue`
+
+This is an interface containing the majority of a response's data (minus the body).
+
+### Property `statusCode`
+
+`number` - The response's HTTP status code.
+
+### Property `statusMessage`
+
+`string` - The response's HTTP status message.
+
+### Property `rawHeaders`
+
+`(Buffer | Buffer[])[]` - The response's headers.
+
+### Property `rawTrailers`
+
+`string[] | undefined` - The response's trailers.
+
+### Property `vary`
+
+`Record<string, string> | undefined` - The headers defined by the response's `Vary` header
+and their respective values for later comparison
+
+For example, for a response like
+```
+Vary: content-encoding, accepts
+content-encoding: utf8
+accepts: application/json
+```
+
+This would be
+```js
+{
+  'content-encoding': 'utf8',
+  accepts: 'application/json'
+}
+```
+
+### Property `cachedAt`
+
+`number` - Time in millis that this value was cached.
+
+### Property `staleAt`
+
+`number` - Time in millis that this value is considered stale.
+
+### Property `deleteAt`
+
+`number` - Time in millis that this value is to be deleted from the cache. This
+is either the same sa staleAt or the `max-stale` caching directive.
+
+The store must not return a response after the time defined in this property.
+
+## `CacheStoreReadable`
+
+This extends Node's [`Readable`](https://nodejs.org/api/stream.html#class-streamreadable)
+and defines extra properties relevant to the cache interceptor.
+
+### Getter: `value`
+
+The response's [`CacheStoreValue`](#cachestorevalue)
+
+## `CacheStoreWriteable`
+
+This extends Node's [`Writable`](https://nodejs.org/api/stream.html#class-streamwritable)
+and defines extra properties relevant to the cache interceptor.
+
+### Setter: `rawTrailers`
+
+If the response has trailers, the cache interceptor will pass them to the cache
+interceptor through this method.

package/docs/docs/api/Client.md

@@ -19,7 +19,7 @@ Returns: `Client`
 
 > ⚠️ Warning: The `H2` support is experimental.
 
-* **bodyTimeout** `number | null` (optional) - Default: `300e3` - The timeout after which a request will time out, in milliseconds. Monitors time between receiving body data. Use `0` to disable it entirely. Defaults to 300 seconds. Please note the `timeout` will be reset if you keep writing data to the scoket everytime.
+* **bodyTimeout** `number | null` (optional) - Default: `300e3` - The timeout after which a request will time out, in milliseconds. Monitors time between receiving body data. Use `0` to disable it entirely. Defaults to 300 seconds. Please note the `timeout` will be reset if you keep writing data to the socket everytime.
 * **headersTimeout** `number | null` (optional) - Default: `300e3` - The amount of time, in milliseconds, the parser will wait to receive the complete HTTP headers while not sending the request. Defaults to 300 seconds.
 * **keepAliveMaxTimeout** `number | null` (optional) - Default: `600e3` - The maximum allowed `keepAliveTimeout`, in milliseconds, when overridden by *keep-alive* hints from the server. Defaults to 10 minutes.
 * **keepAliveTimeout** `number | null` (optional) - Default: `4e3` - The timeout, in milliseconds, after which a socket without active requests will time out. Monitors time between activity on a connected socket. This value may be overridden by *keep-alive* hints from the server. See [MDN: HTTP - Headers - Keep-Alive directives](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Keep-Alive#directives) for more details. Defaults to 4 seconds.

package/docs/docs/api/Debug.md

@@ -2,7 +2,7 @@
 
 Undici (and subsenquently `fetch` and `websocket`) exposes a debug statement that can be enabled by setting `NODE_DEBUG` within the environment.
 
-The flags availabile are:
+The flags available are:
 
 ## `undici`
 

package/docs/docs/api/Dispatcher.md

@@ -478,7 +478,7 @@ The `RequestOptions.method` property should not be value `'CONNECT'`.
 #### Parameter: `ResponseData`
 
 * **statusCode** `number`
-* **headers** `Record<string, string | string[]>` - Note that all header keys are lower-cased, e. g. `content-type`.
+* **headers** `Record<string, string | string[]>` - Note that all header keys are lower-cased, e.g. `content-type`.
 * **body** `stream.Readable` which also implements [the body mixin from the Fetch Standard](https://fetch.spec.whatwg.org/#body-mixin).
 * **trailers** `Record<string, string>` - This object starts out
   as empty and will be mutated to contain trailers after `body` has emitted `'end'`.
@@ -974,7 +974,7 @@ const client = new Client("http://example.com").compose(
   })
 );
 
-// or 
+// or
 client.dispatch(
   {
     path: "/",
@@ -985,6 +985,57 @@ client.dispatch(
 );
 ```
 
+##### `dns`
+
+The `dns` interceptor enables you to cache DNS lookups for a given duration, per origin.
+
+>It is well suited for scenarios where you want to cache DNS lookups to avoid the overhead of resolving the same domain multiple times
+
+**Options**
+- `maxTTL` - The maximum time-to-live (in milliseconds) of the DNS cache. It should be a positive integer. Default: `10000`.
+  - Set `0` to disable TTL.
+- `maxItems` - The maximum number of items to cache. It should be a positive integer. Default: `Infinity`.
+- `dualStack` - Whether to resolve both IPv4 and IPv6 addresses. Default: `true`.
+  - It will also attempt a happy-eyeballs-like approach to connect to the available addresses in case of a connection failure.
+- `affinity` - Whether to use IPv4 or IPv6 addresses. Default: `4`.
+  - It can be either `'4` or `6`.
+  - It will only take effect if `dualStack` is `false`.
+- `lookup: (hostname: string, options: LookupOptions, callback: (err: NodeJS.ErrnoException | null, addresses: DNSInterceptorRecord[]) => void) => void` - Custom lookup function. Default: `dns.lookup`.
+  - For more info see [dns.lookup](https://nodejs.org/api/dns.html#dns_dns_lookup_hostname_options_callback). 
+- `pick: (origin: URL, records: DNSInterceptorRecords, affinity: 4 | 6) => DNSInterceptorRecord` - Custom pick function. Default: `RoundRobin`.
+  - The function should return a single record from the records array.
+  - By default a simplified version of Round Robin is used.
+  - The `records` property can be mutated to store the state of the balancing algorithm.
+
+> The `Dispatcher#options` also gets extended with the options `dns.affinity`, `dns.dualStack`, `dns.lookup` and `dns.pick` which can be used to configure the interceptor at a request-per-request basis.
+
+
+**DNSInterceptorRecord**
+It represents a DNS record.
+- `family` - (`number`) The IP family of the address. It can be either `4` or `6`.
+- `address` - (`string`) The IP address.
+
+**DNSInterceptorOriginRecords**
+It represents a map of DNS IP addresses records for a single origin.
+- `4.ips` - (`DNSInterceptorRecord[] | null`) The IPv4 addresses.
+- `6.ips` - (`DNSInterceptorRecord[] | null`) The IPv6 addresses.
+
+**Example - Basic DNS Interceptor**
+
+```js
+const { Client, interceptors } = require("undici");
+const { dns } = interceptors;
+
+const client = new Agent().compose([
+  dns({ ...opts })
+])
+
+const response = await client.request({
+  origin: `http://localhost:3030`,
+  ...requestOpts
+})
+```
+
 ##### `Response Error Interceptor`
 
 **Introduction**
@@ -1182,6 +1233,16 @@ test('should not error if request status code is not in the specified error code
 
 The Response Error Interceptor provides a robust mechanism for handling HTTP response errors by capturing detailed error information and propagating it through a structured `ResponseError` class. This enhancement improves error handling and debugging capabilities in applications using the interceptor.
 
+##### `Cache Interceptor`
+
+The `cache` interceptor implements client-side response caching as described in
+[RFC9111](https://www.rfc-editor.org/rfc/rfc9111.html).
+
+**Options**
+
+- `store` - The [`CacheStore`](./CacheStore.md) to store and retrieve responses from. Default is [`MemoryCacheStore`](./CacheStore.md#memorycachestore).
+- `methods` - The [**safe** HTTP methods](https://www.rfc-editor.org/rfc/rfc9110#section-9.2.1) to cache the response of.
+
 ## Instance Events
 
 ### Event: `'connect'`

package/docs/docs/api/MockAgent.md

@@ -18,6 +18,8 @@ Extends: [`AgentOptions`](Agent.md#parameter-agentoptions)
 
 * **agent** `Agent` (optional) - Default: `new Agent([options])` - a custom agent encapsulated by the MockAgent.
 
+* **ignoreTrailingSlash** `boolean` (optional) - Default: `false` - set the default value for `ignoreTrailingSlash` for interceptors.
+
 ### Example - Basic MockAgent instantiation
 
 This will instantiate the MockAgent. It will not do anything until registered as the agent to use with requests and mock interceptions are added.

package/docs/docs/api/MockPool.md

@@ -58,6 +58,7 @@ Returns: `MockInterceptor` corresponding to the input options.
 * **body** `string | RegExp | (body: string) => boolean` - (optional) - a matcher for the HTTP request body.
 * **headers** `Record<string, string | RegExp | (body: string) => boolean`> - (optional) - a matcher for the HTTP request headers. To be intercepted, a request must match all defined headers. Extra headers not defined here may (or may not) be included in the request and do not affect the interception in any way.
 * **query** `Record<string, any> | null` - (optional) - a matcher for the HTTP request query string params. Only applies when a `string` was provided for `MockPoolInterceptOptions.path`.
+* **ignoreTrailingSlash** `boolean` - (optional) - set to `true` if the matcher should also match by ignoring potential trailing slashes in `MockPoolInterceptOptions.path`.
 
 ### Return: `MockInterceptor`
 
@@ -81,7 +82,7 @@ By default, `reply` and `replyWithError` define the behaviour for the first matc
 
 ### Return: `MockScope`
 
-A `MockScope` is associated with a single `MockInterceptor`. With this, we can configure the default behaviour of a intercepted reply.
+A `MockScope` is associated with a single `MockInterceptor`. With this, we can configure the default behaviour of an intercepted reply.
 
 * **delay** `(waitInMs: number) => MockScope` - delay the associated reply by a set amount in ms.
 * **persist** `() => MockScope` - any matching request will always reply with the defined response indefinitely.

package/docs/docs/api/RetryAgent.md

@@ -40,6 +40,6 @@ import { Agent, RetryAgent } from 'undici'
 const agent = new RetryAgent(new Agent())
 
 const res = await agent.request('http://example.com')
-console.log(res.statuCode)
+console.log(res.statusCode)
 console.log(await res.body.text())
 ```

package/docs/docs/api/RetryHandler.md

@@ -46,7 +46,7 @@ It represents the retry state for a given request.
 - **dispatch** `(options: Dispatch.DispatchOptions, handlers: Dispatch.DispatchHandlers) => Promise<Dispatch.DispatchResponse>` (required) - Dispatch function to be called after every retry.
 - **handler** Extends [`Dispatch.DispatchHandlers`](Dispatcher.md#dispatcherdispatchoptions-handler) (required) - Handler function to be called after the request is successful or the retries are exhausted.
 
->__Note__: The `RetryHandler` does not retry over stateful bodies (e.g. streams, AsyncIterable) as those, once consumed, are left in an state that cannot be reutilized. For these situations the `RetryHandler` will identify
+>__Note__: The `RetryHandler` does not retry over stateful bodies (e.g. streams, AsyncIterable) as those, once consumed, are left in a state that cannot be reutilized. For these situations the `RetryHandler` will identify
 >the body as stateful and will not retry the request rejecting with the error `UND_ERR_REQ_RETRY`.
 
 Examples:

package/docs/docs/api/WebSocket.md

@@ -1,7 +1,5 @@
 # Class: WebSocket
 
-> ⚠️ Warning: the WebSocket API is experimental.
-
 Extends: [`EventTarget`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget)
 
 The WebSocket object provides a way to manage a WebSocket connection to a server, allowing bidirectional communication. The API follows the [WebSocket spec](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) and [RFC 6455](https://datatracker.ietf.org/doc/html/rfc6455).
@@ -10,7 +8,7 @@ The WebSocket object provides a way to manage a WebSocket connection to a server
 
 Arguments:
 
-* **url** `URL | string` - The url's protocol *must* be `ws` or `wss`.
+* **url** `URL | string`
 * **protocol** `string | string[] | WebSocketInit` (optional) - Subprotocol(s) to request the server use, or a [`Dispatcher`](./Dispatcher.md).
 
 ### Example:
@@ -36,6 +34,50 @@ import { WebSocket } from 'undici'
 const ws = new WebSocket('wss://echo.websocket.events', ['echo', 'chat'])
 ```
 
+# Class: WebSocketStream
+
+> ⚠️ Warning: the WebSocketStream API has not been finalized and is likely to change.
+
+See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/WebSocketStream) for more information.
+
+## `new WebSocketStream(url[, protocol])`
+
+Arguments:
+
+* **url** `URL | string`
+* **options** `WebSocketStreamOptions` (optional)
+
+### WebSocketStream Example
+
+```js
+const stream = new WebSocketStream('https://echo.websocket.org/')
+const { readable, writable } = await stream.opened
+
+async function read () {
+  /** @type {ReadableStreamReader} */
+  const reader = readable.getReader()
+
+  while (true) {
+    const { done, value } = await reader.read()
+    if (done) break
+
+    // do something with value
+  }
+}
+
+async function write () {
+  /** @type {WritableStreamDefaultWriter} */
+  const writer = writable.getWriter()
+  writer.write('Hello, world!')
+  writer.releaseLock()
+}
+
+read()
+
+setInterval(() => write(), 5000)
+
+```
+
 ## Read More
 
 - [MDN - WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket)

package/index.js

@@ -39,7 +39,13 @@ module.exports.RedirectHandler = RedirectHandler
 module.exports.interceptors = {
   redirect: require('./lib/interceptor/redirect'),
   retry: require('./lib/interceptor/retry'),
-  dump: require('./lib/interceptor/dump')
+  dump: require('./lib/interceptor/dump'),
+  dns: require('./lib/interceptor/dns'),
+  cache: require('./lib/interceptor/cache')
+}
+
+module.exports.cacheStores = {
+  MemoryCacheStore: require('./lib/cache/memory-cache-store')
 }
 
 module.exports.buildConnector = buildConnector
@@ -124,7 +130,7 @@ module.exports.setGlobalOrigin = setGlobalOrigin
 module.exports.getGlobalOrigin = getGlobalOrigin
 
 const { CacheStorage } = require('./lib/web/cache/cachestorage')
-const { kConstruct } = require('./lib/web/cache/symbols')
+const { kConstruct } = require('./lib/core/symbols')
 
 // Cache & CacheStorage are tightly coupled with fetch. Even if it may run
 // in an older version of Node, it doesn't have any use without fetch.
@@ -148,6 +154,9 @@ module.exports.CloseEvent = CloseEvent
 module.exports.ErrorEvent = ErrorEvent
 module.exports.MessageEvent = MessageEvent
 
+module.exports.WebSocketStream = require('./lib/web/websocket/stream/websocketstream').WebSocketStream
+module.exports.WebSocketError = require('./lib/web/websocket/stream/websocketerror').WebSocketError
+
 module.exports.request = makeDispatcher(api.request)
 module.exports.stream = makeDispatcher(api.stream)
 module.exports.pipeline = makeDispatcher(api.pipeline)

package/lib/api/abort-signal.js

@@ -1,3 +1,5 @@
+'use strict'
+
 const { addAbortListener } = require('../core/util')
 const { RequestAbortedError } = require('../core/errors')
 

package/lib/api/api-pipeline.js

@@ -15,6 +15,8 @@ const {
 const util = require('../core/util')
 const { addSignal, removeSignal } = require('./abort-signal')
 
+function noop () {}
+
 const kResume = Symbol('resume')
 
 class PipelineRequest extends Readable {
@@ -92,7 +94,7 @@ class PipelineHandler extends AsyncResource {
     this.context = null
     this.onInfo = onInfo || null
 
-    this.req = new PipelineRequest().on('error', util.nop)
+    this.req = new PipelineRequest().on('error', noop)
 
     this.ret = new Duplex({
       readableObjectMode: opts.objectMode,
@@ -183,7 +185,7 @@ class PipelineHandler extends AsyncResource {
         context
       })
     } catch (err) {
-      this.res.on('error', util.nop)
+      this.res.on('error', noop)
       throw err
     }
 

package/lib/api/api-request.js

@@ -6,6 +6,8 @@ const { Readable } = require('./readable')
 const { InvalidArgumentError, RequestAbortedError } = require('../core/errors')
 const util = require('../core/util')
 
+function noop () {}
+
 class RequestHandler extends AsyncResource {
   constructor (opts, callback) {
     if (!opts || typeof opts !== 'object') {
@@ -38,7 +40,7 @@ class RequestHandler extends AsyncResource {
       super('UNDICI_REQUEST')
     } catch (err) {
       if (util.isStream(body)) {
-        util.destroy(body.on('error', util.nop), err)
+        util.destroy(body.on('error', noop), err)
       }
       throw err
     }
@@ -63,7 +65,7 @@ class RequestHandler extends AsyncResource {
       this.removeAbortListener = util.addAbortListener(signal, () => {
         this.reason = signal.reason ?? new RequestAbortedError()
         if (this.res) {
-          util.destroy(this.res, this.reason)
+          util.destroy(this.res.on('error', noop), this.reason)
         } else if (this.abort) {
           this.abort(this.reason)
         }
@@ -159,7 +161,7 @@ class RequestHandler extends AsyncResource {
       this.body = null
 
       if (util.isStream(body)) {
-        body.on('error', util.nop)
+        body.on('error', noop)
         util.destroy(body, err)
       }
     }

package/lib/api/api-stream.js

@@ -7,6 +7,8 @@ const { InvalidArgumentError, InvalidReturnValueError } = require('../core/error
 const util = require('../core/util')
 const { addSignal, removeSignal } = require('./abort-signal')
 
+function noop () {}
+
 class StreamHandler extends AsyncResource {
   constructor (opts, factory, callback) {
     if (!opts || typeof opts !== 'object') {
@@ -39,7 +41,7 @@ class StreamHandler extends AsyncResource {
       super('UNDICI_STREAM')
     } catch (err) {
       if (util.isStream(body)) {
-        util.destroy(body.on('error', util.nop), err)
+        util.destroy(body.on('error', noop), err)
       }
       throw err
     }

package/lib/api/api-upgrade.js

@@ -50,9 +50,9 @@ class UpgradeHandler extends AsyncResource {
   }
 
   onUpgrade (statusCode, rawHeaders, socket) {
-    const { callback, opaque, context } = this
+    assert(statusCode === 101)
 
-    assert.strictEqual(statusCode, 101)
+    const { callback, opaque, context } = this
 
     removeSignal(this)