undici 7.11.0 → 7.12.0

package/README.md

@@ -114,8 +114,10 @@ const response = await fetch('https://api.example.com/data');
 #### Use Built-in Fetch When:
 - You want zero dependencies
 - Building isomorphic code that runs in browsers and Node.js
+- Publishing to npm and want to maximize compatibility with JS runtimes
 - Simple HTTP requests without advanced configuration
-- You're okay with the undici version bundled in your Node.js version
+- You're publishing to npm and you want to maximize compatiblity
+- You don't depend on features from a specific version of undici
 
 #### Use Undici Module When:
 - You need the latest undici features and performance improvements
@@ -209,7 +211,7 @@ The `install()` function adds the following classes to `globalThis`:
 - `fetch` - The fetch function
 - `Headers` - HTTP headers management
 - `Response` - HTTP response representation
-- `Request` - HTTP request representation  
+- `Request` - HTTP request representation
 - `FormData` - Form data handling
 - `WebSocket` - WebSocket client
 - `CloseEvent`, `ErrorEvent`, `MessageEvent` - WebSocket events

package/docs/docs/api/DiagnosticsChannel.md

@@ -169,10 +169,11 @@ This message is published after the client has successfully connected to a serve
 ```js
 import diagnosticsChannel from 'diagnostics_channel'
 
-diagnosticsChannel.channel('undici:websocket:open').subscribe(({ address, protocol, extensions }) => {
+diagnosticsChannel.channel('undici:websocket:open').subscribe(({ address, protocol, extensions, websocket }) => {
   console.log(address) // address, family, and port
   console.log(protocol) // negotiated subprotocols
   console.log(extensions) // negotiated extensions
+  console.log(websocket) // the WebSocket instance
 })
 ```
 
@@ -184,7 +185,7 @@ This message is published after the connection has closed.
 import diagnosticsChannel from 'diagnostics_channel'
 
 diagnosticsChannel.channel('undici:websocket:close').subscribe(({ websocket, code, reason }) => {
-  console.log(websocket) // the WebSocket object
+  console.log(websocket) // the WebSocket instance
   console.log(code) // the closing status code
   console.log(reason) // the closing reason
 })
@@ -209,9 +210,10 @@ This message is published after the client receives a ping frame, if the connect
 ```js
 import diagnosticsChannel from 'diagnostics_channel'
 
-diagnosticsChannel.channel('undici:websocket:ping').subscribe(({ payload }) => {
+diagnosticsChannel.channel('undici:websocket:ping').subscribe(({ payload, websocket }) => {
   // a Buffer or undefined, containing the optional application data of the frame
   console.log(payload)
+  console.log(websocket) // the WebSocket instance
 })
 ```
 
@@ -222,8 +224,9 @@ This message is published after the client receives a pong frame.
 ```js
 import diagnosticsChannel from 'diagnostics_channel'
 
-diagnosticsChannel.channel('undici:websocket:pong').subscribe(({ payload }) => {
+diagnosticsChannel.channel('undici:websocket:pong').subscribe(({ payload, websocket }) => {
   // a Buffer or undefined, containing the optional application data of the frame
   console.log(payload)
+  console.log(websocket) // the WebSocket instance
 })
 ```

package/docs/docs/api/Dispatcher.md

@@ -1103,8 +1103,8 @@ The `cache` interceptor implements client-side response caching as described in
 
 - `store` - The [`CacheStore`](/docs/docs/api/CacheStore.md) to store and retrieve responses from. Default is [`MemoryCacheStore`](/docs/docs/api/CacheStore.md#memorycachestore).
 - `methods` - The [**safe** HTTP methods](https://www.rfc-editor.org/rfc/rfc9110#section-9.2.1) to cache the response of.
-- `cacheByDefault` - The default expiration time to cache responses by if they don't have an explicit expiration. If this isn't present, responses without explicit expiration will not be cached. Default `undefined`.
-- `type` - The type of cache for Undici to act as. Can be `shared` or `private`. Default `shared`.
+- `cacheByDefault` - The default expiration time to cache responses by if they don't have an explicit expiration and cannot have an heuristic expiry computed. If this isn't present, responses neither with an explicit expiration nor heuristically cacheable will not be cached. Default `undefined`.
+- `type` - The [type of cache](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Caching#types_of_caches) for Undici to act as. Can be `shared` or `private`. Default `shared`. `private` implies privately cacheable responses will be cached and potentially shared with other users of your application.
 
 ## Instance Events
 

package/docs/docs/api/WebSocket.md

@@ -78,6 +78,33 @@ setInterval(() => write(), 5000)
 
 ```
 
+## ping(websocket, payload)
+Arguments:
+
+* **websocket** `WebSocket` - The WebSocket instance to send the ping frame on
+* **payload** `Buffer|undefined` (optional) - Optional payload data to include with the ping frame. Must not exceed 125 bytes.
+
+Sends a ping frame to the WebSocket server. The server must respond with a pong frame containing the same payload data. This can be used for keepalive purposes or to verify that the connection is still active.
+
+### Example:
+
+```js
+import { WebSocket, ping } from 'undici'
+
+const ws = new WebSocket('wss://echo.websocket.events')
+
+ws.addEventListener('open', () => {
+  // Send ping with no payload
+  ping(ws)
+
+  // Send ping with payload
+  const payload = Buffer.from('hello')
+  ping(ws, payload)
+})
+```
+
+**Note**: A ping frame cannot have a payload larger than 125 bytes. The ping will only be sent if the WebSocket connection is in the OPEN state.
+
 ## Read More
 
 - [MDN - WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket)

package/index.js

@@ -157,10 +157,12 @@ module.exports.parseMIMEType = parseMIMEType
 module.exports.serializeAMimeType = serializeAMimeType
 
 const { CloseEvent, ErrorEvent, MessageEvent } = require('./lib/web/websocket/events')
-module.exports.WebSocket = require('./lib/web/websocket/websocket').WebSocket
+const { WebSocket, ping } = require('./lib/web/websocket/websocket')
+module.exports.WebSocket = WebSocket
 module.exports.CloseEvent = CloseEvent
 module.exports.ErrorEvent = ErrorEvent
 module.exports.MessageEvent = MessageEvent
+module.exports.ping = ping
 
 module.exports.WebSocketStream = require('./lib/web/websocket/stream/websocketstream').WebSocketStream
 module.exports.WebSocketError = require('./lib/web/websocket/stream/websocketerror').WebSocketError

package/lib/api/readable.js

@@ -89,9 +89,7 @@ class BodyReadable extends Readable {
     // promise (i.e micro tick) for installing an 'error' listener will
     // never get a chance and will always encounter an unhandled exception.
     if (!this[kUsed]) {
-      setImmediate(() => {
-        callback(err)
-      })
+      setImmediate(callback, err)
     } else {
       callback(err)
     }

package/lib/core/request.js

@@ -42,7 +42,8 @@ class Request {
     reset,
     expectContinue,
     servername,
-    throwOnError
+    throwOnError,
+    maxRedirections
   }, handler) {
     if (typeof path !== 'string') {
       throw new InvalidArgumentError('path must be a string')
@@ -86,6 +87,10 @@ class Request {
       throw new InvalidArgumentError('invalid throwOnError')
     }
 
+    if (maxRedirections != null && maxRedirections !== 0) {
+      throw new InvalidArgumentError('maxRedirections is not supported, use the redirect interceptor')
+    }
+
     this.headersTimeout = headersTimeout
 
     this.bodyTimeout = bodyTimeout

package/lib/core/tree.js

@@ -86,7 +86,7 @@ class TstNode {
 
   /**
    * @param {Uint8Array} key
-   * @return {TstNode | null}
+   * @returns {TstNode | null}
    */
   search (key) {
     const keylength = key.length

package/lib/dispatcher/client-h1.js

@@ -60,12 +60,12 @@ const removeAllListeners = util.removeAllListeners
 
 let extractBody
 
-async function lazyllhttp () {
+function lazyllhttp () {
   const llhttpWasmData = process.env.JEST_WORKER_ID ? require('../llhttp/llhttp-wasm.js') : undefined
 
   let mod
   try {
-    mod = await WebAssembly.compile(require('../llhttp/llhttp_simd-wasm.js'))
+    mod = new WebAssembly.Module(require('../llhttp/llhttp_simd-wasm.js'))
   } catch (e) {
     /* istanbul ignore next */
 
@@ -73,10 +73,10 @@ async function lazyllhttp () {
     // being enabled, but the occurring of this other error
     // * https://github.com/emscripten-core/emscripten/issues/11495
     // got me to remove that check to avoid breaking Node 12.
-    mod = await WebAssembly.compile(llhttpWasmData || require('../llhttp/llhttp-wasm.js'))
+    mod = new WebAssembly.Module(llhttpWasmData || require('../llhttp/llhttp-wasm.js'))
   }
 
-  return await WebAssembly.instantiate(mod, {
+  return new WebAssembly.Instance(mod, {
     env: {
       /**
        * @param {number} p
@@ -165,11 +165,6 @@ async function lazyllhttp () {
 }
 
 let llhttpInstance = null
-/**
- * @type {Promise<WebAssembly.Instance>|null}
- */
-let llhttpPromise = lazyllhttp()
-llhttpPromise.catch()
 
 /**
  * @type {Parser|null}
@@ -732,7 +727,7 @@ class Parser {
       // We must wait a full event loop cycle to reuse this socket to make sure
       // that non-spec compliant servers are not closing the connection even if they
       // said they won't.
-      setImmediate(() => client[kResume]())
+      setImmediate(client[kResume])
     } else {
       client[kResume]()
     }
@@ -769,11 +764,7 @@ async function connectH1 (client, socket) {
   client[kSocket] = socket
 
   if (!llhttpInstance) {
-    const noop = () => {}
-    socket.on('error', noop)
-    llhttpInstance = await llhttpPromise
-    llhttpPromise = null
-    socket.off('error', noop)
+    llhttpInstance = lazyllhttp()
   }
 
   if (socket.errored) {
@@ -1297,9 +1288,9 @@ function writeStream (abort, body, client, request, socket, contentLength, heade
     .on('error', onFinished)
 
   if (body.errorEmitted ?? body.errored) {
-    setImmediate(() => onFinished(body.errored))
+    setImmediate(onFinished, body.errored)
   } else if (body.endEmitted ?? body.readableEnded) {
-    setImmediate(() => onFinished(null))
+    setImmediate(onFinished, null)
   }
 
   if (body.closeEmitted ?? body.closed) {

package/lib/handler/cache-handler.js

@@ -241,7 +241,10 @@ class CacheHandler {
  * @param {import('../../types/cache-interceptor.d.ts').default.CacheControlDirectives} cacheControlDirectives
  */
 function canCacheResponse (cacheType, statusCode, resHeaders, cacheControlDirectives) {
-  if (statusCode !== 200 && statusCode !== 307) {
+  // Allow caching for status codes 200 and 307 (original behavior)
+  // Also allow caching for other status codes that are heuristically cacheable
+  // when they have explicit cache directives
+  if (statusCode !== 200 && statusCode !== 307 && !HEURISTICALLY_CACHEABLE_STATUS_CODES.includes(statusCode)) {
     return false
   }
 

package/lib/handler/redirect-handler.js

@@ -42,7 +42,8 @@ class RedirectHandler {
 
     this.dispatch = dispatch
     this.location = null
-    this.opts = { ...opts, maxRedirections: 0 } // opts must be a copy
+    const { maxRedirections: _, ...cleanOpts } = opts
+    this.opts = cleanOpts // opts must be a copy, exclude maxRedirections
     this.maxRedirections = maxRedirections
     this.handler = handler
     this.history = []
@@ -138,7 +139,6 @@ class RedirectHandler {
     this.opts.headers = cleanRequestHeaders(this.opts.headers, statusCode === 303, this.opts.origin !== origin)
     this.opts.path = path
     this.opts.origin = origin
-    this.opts.maxRedirections = 0
     this.opts.query = null
   }
 

package/lib/interceptor/cache.js

@@ -301,11 +301,11 @@ module.exports = (opts = {}) => {
   assertCacheMethods(methods, 'opts.methods')
 
   if (typeof cacheByDefault !== 'undefined' && typeof cacheByDefault !== 'number') {
-    throw new TypeError(`exepcted opts.cacheByDefault to be number or undefined, got ${typeof cacheByDefault}`)
+    throw new TypeError(`expected opts.cacheByDefault to be number or undefined, got ${typeof cacheByDefault}`)
   }
 
   if (typeof type !== 'undefined' && type !== 'shared' && type !== 'private') {
-    throw new TypeError(`exepcted opts.type to be shared, private, or undefined, got ${typeof type}`)
+    throw new TypeError(`expected opts.type to be shared, private, or undefined, got ${typeof type}`)
   }
 
   const globalOpts = {

package/lib/interceptor/redirect.js

@@ -11,7 +11,7 @@ function createRedirectInterceptor ({ maxRedirections: defaultMaxRedirections }
         return dispatch(opts, handler)
       }
 
-      const dispatchOpts = { ...rest, maxRedirections: 0 } // Stop sub dispatcher from also redirecting.
+      const dispatchOpts = { ...rest } // Stop sub dispatcher from also redirecting.
       const redirectHandler = new RedirectHandler(dispatch, maxRedirections, dispatchOpts, handler)
       return dispatch(dispatchOpts, redirectHandler)
     }

package/lib/util/cache.js

@@ -32,7 +32,7 @@ function makeCacheKey (opts) {
 
 /**
  * @param {Record<string, string[] | string>}
- * @return {Record<string, string[] | string>}
+ * @returns {Record<string, string[] | string>}
  */
 function normaliseHeaders (opts) {
   let headers

package/lib/util/promise.js

@@ -0,0 +1,28 @@
+'use strict'
+
+/**
+ * @template {*} T
+ * @typedef {Object} DeferredPromise
+ * @property {Promise<T>} promise
+ * @property {(value?: T) => void} resolve
+ * @property {(reason?: any) => void} reject
+ */
+
+/**
+ * @template {*} T
+ * @returns {DeferredPromise<T>} An object containing a promise and its resolve/reject methods.
+ */
+function createDeferredPromise () {
+  let res
+  let rej
+  const promise = new Promise((resolve, reject) => {
+    res = resolve
+    rej = reject
+  })
+
+  return { promise, resolve: res, reject: rej }
+}
+
+module.exports = {
+  createDeferredPromise
+}

package/lib/web/cache/cache.js

@@ -1,5 +1,7 @@
 'use strict'
 
+const assert = require('node:assert')
+
 const { kConstruct } = require('../../core/symbols')
 const { urlEquals, getFieldValues } = require('./util')
 const { kEnumerableProperty, isDisturbed } = require('../../core/util')
@@ -7,8 +9,8 @@ const { webidl } = require('../webidl')
 const { cloneResponse, fromInnerResponse, getResponseState } = require('../fetch/response')
 const { Request, fromInnerRequest, getRequestState } = require('../fetch/request')
 const { fetching } = require('../fetch/index')
-const { urlIsHttpHttpsScheme, createDeferredPromise, readAllBytes } = require('../fetch/util')
-const assert = require('node:assert')
+const { urlIsHttpHttpsScheme, readAllBytes } = require('../fetch/util')
+const { createDeferredPromise } = require('../../util/promise')
 
 /**
  * @see https://w3c.github.io/ServiceWorker/#dfn-cache-batch-operation
@@ -46,7 +48,7 @@ class Cache {
     const prefix = 'Cache.match'
     webidl.argumentLengthCheck(arguments, 1, prefix)
 
-    request = webidl.converters.RequestInfo(request, prefix, 'request')
+    request = webidl.converters.RequestInfo(request)
     options = webidl.converters.CacheQueryOptions(options, prefix, 'options')
 
     const p = this.#internalMatchAll(request, options, 1)
@@ -62,7 +64,7 @@ class Cache {
     webidl.brandCheck(this, Cache)
 
     const prefix = 'Cache.matchAll'
-    if (request !== undefined) request = webidl.converters.RequestInfo(request, prefix, 'request')
+    if (request !== undefined) request = webidl.converters.RequestInfo(request)
     options = webidl.converters.CacheQueryOptions(options, prefix, 'options')
 
     return this.#internalMatchAll(request, options)
@@ -74,7 +76,7 @@ class Cache {
     const prefix = 'Cache.add'
     webidl.argumentLengthCheck(arguments, 1, prefix)
 
-    request = webidl.converters.RequestInfo(request, prefix, 'request')
+    request = webidl.converters.RequestInfo(request)
 
     // 1.
     const requests = [request]
@@ -262,7 +264,7 @@ class Cache {
     const prefix = 'Cache.put'
     webidl.argumentLengthCheck(arguments, 2, prefix)
 
-    request = webidl.converters.RequestInfo(request, prefix, 'request')
+    request = webidl.converters.RequestInfo(request)
     response = webidl.converters.Response(response, prefix, 'response')
 
     // 1.
@@ -393,7 +395,7 @@ class Cache {
     const prefix = 'Cache.delete'
     webidl.argumentLengthCheck(arguments, 1, prefix)
 
-    request = webidl.converters.RequestInfo(request, prefix, 'request')
+    request = webidl.converters.RequestInfo(request)
     options = webidl.converters.CacheQueryOptions(options, prefix, 'options')
 
     /**
@@ -458,7 +460,7 @@ class Cache {
 
     const prefix = 'Cache.keys'
 
-    if (request !== undefined) request = webidl.converters.RequestInfo(request, prefix, 'request')
+    if (request !== undefined) request = webidl.converters.RequestInfo(request)
     options = webidl.converters.CacheQueryOptions(options, prefix, 'options')
 
     // 1.

package/lib/web/fetch/body.js

@@ -4,7 +4,6 @@ const util = require('../../core/util')
 const {
   ReadableStreamFrom,
   readableStreamClose,
-  createDeferredPromise,
   fullyReadBody,
   extractMimeType,
   utf8DecodeBytes
@@ -17,6 +16,8 @@ const { isErrored, isDisturbed } = require('node:stream')
 const { isArrayBuffer } = require('node:util/types')
 const { serializeAMimeType } = require('./data-url')
 const { multipartFormDataParser } = require('./formdata-parser')
+const { createDeferredPromise } = require('../../util/promise')
+
 let random
 
 try {
@@ -29,19 +30,22 @@ try {
 const textEncoder = new TextEncoder()
 function noop () {}
 
-const hasFinalizationRegistry = globalThis.FinalizationRegistry
-let streamRegistry
-
-if (hasFinalizationRegistry) {
-  streamRegistry = new FinalizationRegistry((weakRef) => {
-    const stream = weakRef.deref()
-    if (stream && !stream.locked && !isDisturbed(stream) && !isErrored(stream)) {
-      stream.cancel('Response object has been garbage collected').catch(noop)
-    }
-  })
-}
+const streamRegistry = new FinalizationRegistry((weakRef) => {
+  const stream = weakRef.deref()
+  if (stream && !stream.locked && !isDisturbed(stream) && !isErrored(stream)) {
+    stream.cancel('Response object has been garbage collected').catch(noop)
+  }
+})
 
-// https://fetch.spec.whatwg.org/#concept-bodyinit-extract
+/**
+ * Extract a body with type from a byte sequence or BodyInit object
+ *
+ * @param {import('../../../types').BodyInit} object - The BodyInit object to extract from
+ * @param {boolean} [keepalive=false] - If true, indicates that the body
+ * @returns {[{stream: ReadableStream, source: any, length: number | null}, string | null]} - Returns a tuple containing the body and its type
+ *
+ * @see https://fetch.spec.whatwg.org/#concept-bodyinit-extract
+ */
 function extractBody (object, keepalive = false) {
   // 1. Let stream be null.
   let stream = null
@@ -267,7 +271,22 @@ function extractBody (object, keepalive = false) {
   return [body, type]
 }
 
-// https://fetch.spec.whatwg.org/#bodyinit-safely-extract
+/**
+ * @typedef {object} ExtractBodyResult
+ * @property {ReadableStream<Uint8Array<ArrayBuffer>>} stream - The ReadableStream containing the body data
+ * @property {any} source - The original source of the body data
+ * @property {number | null} length - The length of the body data, or null
+ */
+
+/**
+ * Safely extract a body with type from a byte sequence or BodyInit object.
+ *
+ * @param {import('../../../types').BodyInit} object - The BodyInit object to extract from
+ * @param {boolean} [keepalive=false] - If true, indicates that the body
+ * @returns {[ExtractBodyResult, string | null]} - Returns a tuple containing the body and its type
+ *
+ * @see https://fetch.spec.whatwg.org/#bodyinit-safely-extract
+ */
 function safelyExtractBody (object, keepalive = false) {
   // To safely extract a body and a `Content-Type` value from
   // a byte sequence or BodyInit object object, run these steps:
@@ -275,9 +294,7 @@ function safelyExtractBody (object, keepalive = false) {
   // 1. If object is a ReadableStream object, then:
   if (webidl.is.ReadableStream(object)) {
     // Assert: object is neither disturbed nor locked.
-    // istanbul ignore next
     assert(!util.isDisturbed(object), 'The body has already been consumed.')
-    // istanbul ignore next
     assert(!object.locked, 'The stream is locked.')
   }
 
@@ -285,17 +302,13 @@ function safelyExtractBody (object, keepalive = false) {
   return extractBody(object, keepalive)
 }
 
-function cloneBody (instance, body) {
+function cloneBody (body) {
   // To clone a body body, run these steps:
 
   // https://fetch.spec.whatwg.org/#concept-body-clone
 
   // 1. Let « out1, out2 » be the result of teeing body’s stream.
-  const [out1, out2] = body.stream.tee()
-
-  if (hasFinalizationRegistry) {
-    streamRegistry.register(instance, new WeakRef(out1))
-  }
+  const { 0: out1, 1: out2 } = body.stream.tee()
 
   // 2. Set body’s stream to out1.
   body.stream = out1
@@ -527,6 +540,5 @@ module.exports = {
   cloneBody,
   mixinBody,
   streamRegistry,
-  hasFinalizationRegistry,
   bodyUnusable
 }