undici 6.8.0 → 6.10.0

package/docs/docs/api/Client.md

@@ -29,7 +29,8 @@ Returns: `Client`
 * **pipelining** `number | null` (optional) - Default: `1` - The amount of concurrent requests to be sent over the single TCP/TLS connection according to [RFC7230](https://tools.ietf.org/html/rfc7230#section-6.3.2). Carefully consider your workload and environment before enabling concurrent requests as pipelining may reduce performance if used incorrectly. Pipelining is sensitive to network stack settings as well as head of line blocking caused by e.g. long running requests. Set to `0` to disable keep-alive connections.
 * **connect** `ConnectOptions | Function | null` (optional) - Default: `null`.
 * **strictContentLength** `Boolean` (optional) - Default: `true` - Whether to treat request content length mismatches as errors. If true, an error is thrown when the request content-length header doesn't match the length of the request body.
-* **interceptors** `{ Client: DispatchInterceptor[] }` - Default: `[RedirectInterceptor]` - A list of interceptors that are applied to the dispatch method. Additional logic can be applied (such as, but not limited to: 302 status code handling, authentication, cookies, compression and caching). Note that the behavior of interceptors is Experimental and might change at any given time.
+  <!-- TODO: Remove once we drop its support -->
+* **interceptors** `{ Client: DispatchInterceptor[] }` - Default: `[RedirectInterceptor]` - A list of interceptors that are applied to the dispatch method. Additional logic can be applied (such as, but not limited to: 302 status code handling, authentication, cookies, compression and caching). Note that the behavior of interceptors is Experimental and might change at any given time. **Note: this is deprecated in favor of [Dispatcher#compose](./Dispatcher.md#dispatcher). Support will be droped in next major.**
 * **autoSelectFamily**: `boolean` (optional) - Default: depends on local Node version, on Node 18.13.0 and above is `false`. Enables a family autodetection algorithm that loosely implements section 5 of [RFC 8305](https://tools.ietf.org/html/rfc8305#section-5). See [here](https://nodejs.org/api/net.html#socketconnectoptions-connectlistener) for more details. This option is ignored if not supported by the current Node version.
 * **autoSelectFamilyAttemptTimeout**: `number` - Default: depends on local Node version, on Node 18.13.0 and above is `250`. The amount of time in milliseconds to wait for a connection attempt to finish before trying the next address when using the `autoSelectFamily` option. See [here](https://nodejs.org/api/net.html#socketconnectoptions-connectlistener) for more details.
 * **allowH2**: `boolean` - Default: `false`. Enables support for H2 if the server has assigned bigger priority to it through ALPN negotiation.

package/docs/docs/api/Dispatcher.md

@@ -817,6 +817,141 @@ try {
 }
 ```
 
+### `Dispatcher.compose(interceptors[, interceptor])`
+
+Compose a new dispatcher from the current dispatcher and the given interceptors.
+
+> _Notes_:
+> - The order of the interceptors matters. The first interceptor will be the first to be called.
+> - It is important to note that the `interceptor` function should return a function that follows the `Dispatcher.dispatch` signature.
+> - Any fork of the chain of `interceptors` can lead to unexpected results.
+
+Arguments:
+
+* **interceptors** `Interceptor[interceptor[]]`: It is an array of `Interceptor` functions passed as only argument, or several interceptors passed as separate arguments.
+
+Returns: `Dispatcher`.
+
+#### Parameter: `Interceptor`
+
+A function that takes a `dispatch` method and returns a `dispatch`-like function.
+
+#### Example 1 - Basic Compose
+
+```js
+const { Client, RedirectHandler } = require('undici')
+
+const redirectInterceptor = dispatch => {
+    return (opts, handler) => {
+      const { maxRedirections } = opts
+
+      if (!maxRedirections) {
+        return dispatch(opts, handler)
+      }
+
+      const redirectHandler = new RedirectHandler(
+        dispatch,
+        maxRedirections,
+        opts,
+        handler
+      )
+      opts = { ...opts, maxRedirections: 0 } // Stop sub dispatcher from also redirecting.
+      return dispatch(opts, redirectHandler)
+    }
+}
+
+const client = new Client('http://localhost:3000')
+  .compose(redirectInterceptor)
+
+await client.request({ path: '/', method: 'GET' })
+```
+
+#### Example 2 - Chained Compose
+
+```js
+const { Client, RedirectHandler, RetryHandler } = require('undici')
+
+const redirectInterceptor = dispatch => {
+    return (opts, handler) => {
+      const { maxRedirections } = opts
+
+      if (!maxRedirections) {
+        return dispatch(opts, handler)
+      }
+
+      const redirectHandler = new RedirectHandler(
+        dispatch,
+        maxRedirections,
+        opts,
+        handler
+      )
+      opts = { ...opts, maxRedirections: 0 }
+      return dispatch(opts, redirectHandler)
+    }
+}
+
+const retryInterceptor = dispatch => {
+  return function retryInterceptor (opts, handler) {
+    return dispatch(
+      opts,
+      new RetryHandler(opts, {
+        handler,
+        dispatch
+      })
+    )
+  }
+}
+
+const client = new Client('http://localhost:3000')
+  .compose(redirectInterceptor)
+  .compose(retryInterceptor)
+
+await client.request({ path: '/', method: 'GET' })
+```
+
+#### Pre-built interceptors
+
+##### `redirect`
+
+The `redirect` interceptor allows you to customize the way your dispatcher handles redirects.
+
+It accepts the same arguments as the [`RedirectHandler` constructor](./RedirectHandler.md).
+
+**Example - Basic Redirect Interceptor**
+
+```js
+const { Client, interceptors } = require("undici");
+const { redirect } = interceptors;
+
+const client = new Client("http://example.com").compose(
+  redirect({ maxRedirections: 3, throwOnMaxRedirects: true })
+);
+client.request({ path: "/" })
+```
+
+##### `retry`
+
+The `retry` interceptor allows you to customize the way your dispatcher handles retries.
+
+It accepts the same arguments as the [`RetryHandler` constructor](./RetryHandler.md).
+
+**Example - Basic Redirect Interceptor**
+
+```js
+const { Client, interceptors } = require("undici");
+const { retry } = interceptors;
+
+const client = new Client("http://example.com").compose(
+  retry({
+    maxRetries: 3,
+    minTimeout: 1000,
+    maxTimeout: 10000,
+    timeoutFactor: 2,
+    retryAfter: true,
+  })
+);
+```
+
 ## Instance Events
 
 ### Event: `'connect'`

package/docs/docs/api/RetryHandler.md

@@ -35,6 +35,12 @@ Extends: [`Dispatch.DispatchOptions`](Dispatcher.md#parameter-dispatchoptions).
 - `state`: `RetryState` - Current retry state. It can be mutated.
 - `opts`: `Dispatch.DispatchOptions & RetryOptions` - Options passed to the retry handler.
 
+**`RetryState`**
+
+It represents the retry state for a given request.
+
+- `counter`: `number` - Current retry attempt.
+
 ### Parameter `RetryHandlers`
 
 - **dispatch** `(options: Dispatch.DispatchOptions, handlers: Dispatch.DispatchHandlers) => Promise<Dispatch.DispatchResponse>` (required) - Dispatch function to be called after every retry.

package/index.js

@@ -36,6 +36,10 @@ module.exports.RetryHandler = RetryHandler
 module.exports.DecoratorHandler = DecoratorHandler
 module.exports.RedirectHandler = RedirectHandler
 module.exports.createRedirectInterceptor = createRedirectInterceptor
+module.exports.interceptors = {
+  redirect: require('./lib/interceptor/redirect'),
+  retry: require('./lib/interceptor/retry')
+}
 
 module.exports.buildConnector = buildConnector
 module.exports.errors = errors

package/lib/dispatcher/client.js

@@ -59,6 +59,7 @@ const {
 } = require('../core/symbols.js')
 const connectH1 = require('./client-h1.js')
 const connectH2 = require('./client-h2.js')
+let deprecatedInterceptorWarned = false
 
 const kClosedResolve = Symbol('kClosedResolve')
 
@@ -207,9 +208,18 @@ class Client extends DispatcherBase {
       })
     }
 
-    this[kInterceptors] = interceptors?.Client && Array.isArray(interceptors.Client)
-      ? interceptors.Client
-      : [createRedirectInterceptor({ maxRedirections })]
+    if (interceptors?.Client && Array.isArray(interceptors.Client)) {
+      this[kInterceptors] = interceptors.Client
+      if (!deprecatedInterceptorWarned) {
+        deprecatedInterceptorWarned = true
+        process.emitWarning('Client.Options#interceptor is deprecated. Use Dispatcher#compose instead.', {
+          code: 'UNDICI-CLIENT-INTERCEPTOR-DEPRECATED'
+        })
+      }
+    } else {
+      this[kInterceptors] = [createRedirectInterceptor({ maxRedirections })]
+    }
+
     this[kUrl] = util.parseOrigin(url)
     this[kConnector] = connect
     this[kPipelining] = pipelining != null ? pipelining : 1

package/lib/dispatcher/dispatcher.js

@@ -1,5 +1,4 @@
 'use strict'
-
 const EventEmitter = require('node:events')
 
 class Dispatcher extends EventEmitter {
@@ -14,6 +13,53 @@ class Dispatcher extends EventEmitter {
   destroy () {
     throw new Error('not implemented')
   }
+
+  compose (...args) {
+    // So we handle [interceptor1, interceptor2] or interceptor1, interceptor2, ...
+    const interceptors = Array.isArray(args[0]) ? args[0] : args
+    let dispatch = this.dispatch.bind(this)
+
+    for (const interceptor of interceptors) {
+      if (interceptor == null) {
+        continue
+      }
+
+      if (typeof interceptor !== 'function') {
+        throw new TypeError(`invalid interceptor, expected function received ${typeof interceptor}`)
+      }
+
+      dispatch = interceptor(dispatch)
+
+      if (dispatch == null || typeof dispatch !== 'function' || dispatch.length !== 2) {
+        throw new TypeError('invalid interceptor')
+      }
+    }
+
+    return new ComposedDispatcher(this, dispatch)
+  }
+}
+
+class ComposedDispatcher extends Dispatcher {
+  #dispatcher = null
+  #dispatch = null
+
+  constructor (dispatcher, dispatch) {
+    super()
+    this.#dispatcher = dispatcher
+    this.#dispatch = dispatch
+  }
+
+  dispatch (...args) {
+    this.#dispatch(...args)
+  }
+
+  close (...args) {
+    return this.#dispatcher.close(...args)
+  }
+
+  destroy (...args) {
+    return this.#dispatcher.destroy(...args)
+  }
 }
 
 module.exports = Dispatcher

package/lib/handler/retry-handler.js

@@ -1,3 +1,4 @@
+'use strict'
 const assert = require('node:assert')
 
 const { kRetryHandlerDefaultRetry } = require('../core/symbols')
@@ -37,7 +38,7 @@ class RetryHandler {
       retry: retryFn ?? RetryHandler[kRetryHandlerDefaultRetry],
       retryAfter: retryAfter ?? true,
       maxTimeout: maxTimeout ?? 30 * 1000, // 30s,
-      timeout: minTimeout ?? 500, // .5s
+      minTimeout: minTimeout ?? 500, // .5s
       timeoutFactor: timeoutFactor ?? 2,
       maxRetries: maxRetries ?? 5,
       // What errors we should retry
@@ -59,6 +60,7 @@ class RetryHandler {
     }
 
     this.retryCount = 0
+    this.retryCountCheckpoint = 0
     this.start = 0
     this.end = null
     this.etag = null
@@ -104,17 +106,14 @@ class RetryHandler {
     const { method, retryOptions } = opts
     const {
       maxRetries,
-      timeout,
+      minTimeout,
       maxTimeout,
       timeoutFactor,
       statusCodes,
       errorCodes,
       methods
     } = retryOptions
-    let { counter, currentTimeout } = state
-
-    currentTimeout =
-      currentTimeout != null && currentTimeout > 0 ? currentTimeout : timeout
+    const { counter } = state
 
     // Any code that is not a Undici's originated and allowed to retry
     if (
@@ -159,9 +158,7 @@ class RetryHandler {
     const retryTimeout =
       retryAfterHeader > 0
         ? Math.min(retryAfterHeader, maxTimeout)
-        : Math.min(currentTimeout * timeoutFactor ** counter, maxTimeout)
-
-    state.currentTimeout = retryTimeout
+        : Math.min(minTimeout * timeoutFactor ** (counter - 1), maxTimeout)
 
     setTimeout(() => cb(null), retryTimeout)
   }
@@ -309,10 +306,19 @@ class RetryHandler {
       return this.handler.onError(err)
     }
 
+    // We reconcile in case of a mix between network errors
+    // and server error response
+    if (this.retryCount - this.retryCountCheckpoint > 0) {
+      // We count the difference between the last checkpoint and the current retry count
+      this.retryCount = this.retryCountCheckpoint + (this.retryCount - this.retryCountCheckpoint)
+    } else {
+      this.retryCount += 1
+    }
+
     this.retryOpts.retry(
       err,
       {
-        state: { counter: this.retryCount++, currentTimeout: this.retryAfter },
+        state: { counter: this.retryCount },
         opts: { retryOptions: this.retryOpts, ...this.opts }
       },
       onRetry.bind(this)
@@ -334,6 +340,7 @@ class RetryHandler {
       }
 
       try {
+        this.retryCountCheckpoint = this.retryCount
         this.dispatch(this.opts, this)
       } catch (err) {
         this.handler.onError(err)

package/lib/interceptor/redirect.js

@@ -0,0 +1,24 @@
+'use strict'
+const RedirectHandler = require('../handler/redirect-handler')
+
+module.exports = opts => {
+  const globalMaxRedirections = opts?.maxRedirections
+  return dispatch => {
+    return function redirectInterceptor (opts, handler) {
+      const { maxRedirections = globalMaxRedirections, ...baseOpts } = opts
+
+      if (!maxRedirections) {
+        return dispatch(opts, handler)
+      }
+
+      const redirectHandler = new RedirectHandler(
+        dispatch,
+        maxRedirections,
+        opts,
+        handler
+      )
+
+      return dispatch(baseOpts, redirectHandler)
+    }
+  }
+}

package/lib/interceptor/retry.js

@@ -0,0 +1,19 @@
+'use strict'
+const RetryHandler = require('../handler/retry-handler')
+
+module.exports = globalOpts => {
+  return dispatch => {
+    return function retryInterceptor (opts, handler) {
+      return dispatch(
+        opts,
+        new RetryHandler(
+          { ...opts, retryOptions: { ...globalOpts, ...opts.retryOptions } },
+          {
+            handler,
+            dispatch
+          }
+        )
+      )
+    }
+  }
+}

package/lib/web/fetch/formdata-parser.js

@@ -444,15 +444,13 @@ function parseMultipartFormDataName (input, position) {
  * @param {{ position: number }} position
  */
 function collectASequenceOfBytes (condition, input, position) {
-  const result = []
+  let start = position.position
 
-  while (position.position < input.length && condition(input[position.position])) {
-    result.push(input[position.position])
-
-    position.position++
+  while (start < input.length && condition(input[start])) {
+    ++start
   }
 
-  return Buffer.from(result, result.length)
+  return input.subarray(position.position, (position.position = start))
 }
 
 /**

package/lib/web/fetch/formdata.js

@@ -6,6 +6,7 @@ const { kEnumerableProperty } = require('../../core/util')
 const { File: UndiciFile, FileLike, isFileLike } = require('./file')
 const { webidl } = require('./webidl')
 const { File: NativeFile } = require('node:buffer')
+const nodeUtil = require('node:util')
 
 /** @type {globalThis['File']} */
 const File = NativeFile ?? UndiciFile
@@ -154,6 +155,30 @@ class FormData {
       this[kState].push(entry)
     }
   }
+
+  [nodeUtil.inspect.custom] (depth, options) {
+    const state = this[kState].reduce((a, b) => {
+      if (a[b.name]) {
+        if (Array.isArray(a[b.name])) {
+          a[b.name].push(b.value)
+        } else {
+          a[b.name] = [a[b.name], b.value]
+        }
+      } else {
+        a[b.name] = b.value
+      }
+
+      return a
+    }, { __proto__: null })
+
+    options.depth ??= depth
+    options.colors ??= true
+
+    const output = nodeUtil.formatWithOptions(options, state)
+
+    // remove [Object null prototype]
+    return `FormData ${output.slice(output.indexOf(']') + 2)}`
+  }
 }
 
 iteratorMixin('FormData', FormData, kState, 'name', 'value')

package/lib/web/fetch/headers.js

@@ -572,16 +572,10 @@ class Headers {
     return (this[kHeadersList][kHeadersSortedMap] = headers)
   }
 
-  [Symbol.for('nodejs.util.inspect.custom')] () {
-    webidl.brandCheck(this, Headers)
-
-    return this[kHeadersList]
-  }
-
   [util.inspect.custom] (depth, options) {
-    const inspected = util.inspect(this[kHeadersList].entries)
+    options.depth ??= depth
 
-    return `Headers ${inspected}`
+    return `Headers ${util.formatWithOptions(options, this[kHeadersList].entries)}`
   }
 }
 

package/lib/web/fetch/request.js

@@ -6,6 +6,7 @@ const { extractBody, mixinBody, cloneBody } = require('./body')
 const { Headers, fill: fillHeaders, HeadersList } = require('./headers')
 const { FinalizationRegistry } = require('./dispatcher-weakref')()
 const util = require('../../core/util')
+const nodeUtil = require('node:util')
 const {
   isValidHTTPToken,
   sameOrigin,
@@ -771,6 +772,34 @@ class Request {
     // 4. Return clonedRequestObject.
     return fromInnerRequest(clonedRequest, ac.signal, this[kHeaders][kGuard], this[kRealm])
   }
+
+  [nodeUtil.inspect.custom] (depth, options) {
+    if (options.depth === null) {
+      options.depth = 2
+    }
+
+    options.colors ??= true
+
+    const properties = {
+      method: this.method,
+      url: this.url,
+      headers: this.headers,
+      destination: this.destination,
+      referrer: this.referrer,
+      referrerPolicy: this.referrerPolicy,
+      mode: this.mode,
+      credentials: this.credentials,
+      cache: this.cache,
+      redirect: this.redirect,
+      integrity: this.integrity,
+      keepalive: this.keepalive,
+      isReloadNavigation: this.isReloadNavigation,
+      isHistoryNavigation: this.isHistoryNavigation,
+      signal: this.signal
+    }
+
+    return `Request ${nodeUtil.formatWithOptions(options, properties)}`
+  }
 }
 
 mixinBody(Request)

package/lib/web/fetch/response.js

@@ -3,6 +3,7 @@
 const { Headers, HeadersList, fill } = require('./headers')
 const { extractBody, cloneBody, mixinBody } = require('./body')
 const util = require('../../core/util')
+const nodeUtil = require('node:util')
 const { kEnumerableProperty } = util
 const {
   isValidReasonPhrase,
@@ -252,6 +253,28 @@ class Response {
     // clonedResponse, this’s headers’s guard, and this’s relevant Realm.
     return fromInnerResponse(clonedResponse, this[kHeaders][kGuard], this[kRealm])
   }
+
+  [nodeUtil.inspect.custom] (depth, options) {
+    if (options.depth === null) {
+      options.depth = 2
+    }
+
+    options.colors ??= true
+
+    const properties = {
+      status: this.status,
+      statusText: this.statusText,
+      headers: this.headers,
+      body: this.body,
+      bodyUsed: this.bodyUsed,
+      ok: this.ok,
+      redirected: this.redirected,
+      type: this.type,
+      url: this.url
+    }
+
+    return `Response ${nodeUtil.formatWithOptions(options, properties)}`
+  }
 }
 
 mixinBody(Response)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "undici",
-  "version": "6.8.0",
+  "version": "6.10.0",
   "description": "An HTTP/1.1 client, written from scratch for Node.js",
   "homepage": "https://undici.nodejs.org",
   "bugs": {

package/types/dispatcher.d.ts

@@ -18,6 +18,9 @@ declare class Dispatcher extends EventEmitter {
   /** Starts two-way communications with the requested resource. */
   connect(options: Dispatcher.ConnectOptions): Promise<Dispatcher.ConnectData>;
   connect(options: Dispatcher.ConnectOptions, callback: (err: Error | null, data: Dispatcher.ConnectData) => void): void;
+  /** Compose a chain of dispatchers */
+  compose(dispatchers: Dispatcher['dispatch'][]): Dispatcher.ComposedDispatcher;
+  compose(...dispatchers: Dispatcher['dispatch'][]): Dispatcher.ComposedDispatcher;
   /** Performs an HTTP request. */
   request(options: Dispatcher.RequestOptions): Promise<Dispatcher.ResponseData>;
   request(options: Dispatcher.RequestOptions, callback: (err: Error | null, data: Dispatcher.ResponseData) => void): void;
@@ -93,6 +96,8 @@ declare class Dispatcher extends EventEmitter {
 }
 
 declare namespace Dispatcher {
+  export interface ComposedDispatcher extends Dispatcher {}
+  export type DispatcherInterceptor = (dispatch: Dispatcher['dispatch']) => Dispatcher['dispatch'];
   export interface DispatchOptions {
     origin?: string | URL;
     path: string;

package/types/fetch.d.ts

@@ -122,7 +122,7 @@ export interface RequestInit {
   method?: string
   keepalive?: boolean
   headers?: HeadersInit
-  body?: BodyInit
+  body?: BodyInit | null
   redirect?: RequestRedirect
   integrity?: string
   signal?: AbortSignal | null

package/types/retry-handler.d.ts

@@ -12,7 +12,7 @@ declare class RetryHandler implements Dispatcher.DispatchHandlers {
 }
 
 declare namespace RetryHandler {
-  export type RetryState = { counter: number; currentTimeout: number };
+  export type RetryState = { counter: number; };
 
   export type RetryContext = {
     state: RetryState;