feat: add new dispatch compose

docs/docs/api/Dispatcher.md

@@ -817,6 +817,131 @@ try {
 }
 ```
 
+### `Dispatcher.compose(interceptors[, interceptor])`
+
+Compose a new dispatcher from the current dispatcher and the given interceptors.
+
+> _Notes_:
+> - The order of the interceptors is important. The first interceptor will be the first to be called.
+> - It is important to note that the `interceptor` function should return a `Dispatcher` instance.
+> - Any fork of the chain of `interceptors` can lead to unexpected results, it is important that an interceptor returns a `Dispatcher` instance that forwards the request to the next interceptor in the chain.
+
+Arguments:
+
+* **interceptors** `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 `Dispatcher` instance and returns a `Dispatcher` instance.
+
+#### Example 1 - Basic Compose
+
+```js
+import { RedirectHandler, Dispatcher } from 'undici'
+
+class RedirectDispatcher extends Dispatcher {
+  #opts
+  #dispatcher
+
+  constructor (dispatcher, opts) {
+    super()
+
+    this.#dispatcher = dispatcher
+    this.#opts = opts
+  }
+
+  dispatch (opts, handler) {
+    return this.#dispatcher.dispatch(
+      opts,
+      new RedirectHandler(this.#dispatcher, opts, this.#opts, handler)
+    )
+  }
+
+  close (...args) {
+    return this.#dispatcher.close(...args)
+  }
+
+  destroy (...args) {
+    return this.#dispatcher.destroy(...args)
+  }
+}
+
+const redirectInterceptor = dispatcher => new RedirectDispatcher(dispatcher, opts)
+
+const client = new Client('http://localhost:3000')
+  .compose(redirectInterceptor)
+```
+
+#### Example 2 - Chained Compose
+
+```js
+import { RedirectHandler, Dispatcher, RetryHandler } from 'undici'
+
+class RedirectDispatcher extends Dispatcher {
+  #opts
+  #dispatcher
+
+  constructor (dispatcher, opts) {
+    super()
+
+    this.#dispatcher = dispatcher
+    this.#opts = opts
+  }
+
+  dispatch (opts, handler) {
+    return this.#dispatcher.dispatch(
+      opts,
+      new RedirectHandler(this.#dispatcher, opts, this.#opts, handler)
+    )
+  }
+
+  close (...args) {
+    return this.#dispatcher.close(...args)
+  }
+
+  destroy (...args) {
+    return this.#dispatcher.destroy(...args)
+  }
+}
+
+class RetryDispatcher extends Dispatcher {
+  #dispatcher
+  #opts
+
+  constructor (dispatcher, opts) {
+    super()
+
+    this.#dispatcher = dispatcher
+    this.#opts = opts
+  }
+
+  dispatch (opts, handler) {
+    return this.#dispatcher.dispatch(
+      opts,
+      new RetryHandler(this.#dispatcher, opts, this.#opts, handler)
+    )
+  }
+
+  close (...args) {
+    return this.#dispatcher.close(...args)
+  }
+
+  destroy (...args) {
+    return this.#dispatcher.destroy(...args)
+  }
+}
+
+
+const redirectInterceptor = dispatcher => new RedirectDispatcher(dispatcher, opts)
+const retryInterceptor = dispatcher => new RetryDispatcher(dispatcher, opts)
+
+const client = new Client('http://localhost:3000')
+  .compose(redirectInterceptor)
+  .compose(retryInterceptor)
+```
+
 ## Instance Events
 
 ### Event: `'connect'`

docs/docs/api/Interceptors.md

@@ -0,0 +1,68 @@
+# Interceptors
+
+Undici provides a way to intercept requests and responses using interceptors.
+
+Interceptors are a way to modify the request or response before it is sent or received by the original dispatcher, apply custom logic to a network request, or even cancel the request, connect through a proxy for the origin, etc.
+
+Within Undici there are a set of pre-built that can be used, on top of that, you can create your own interceptors.
+
+## Pre-built interceptors
+
+### `proxy`
+
+The `proxy` interceptor allows you to connect to a proxy server before connecting to the origin server.
+
+It accepts the same arguments as the [`ProxyAgent` constructor](./ProxyAgent.md).
+
+#### Example - Basic Proxy Interceptor
+
+```js
+const { Client, interceptors } = require("undici");
+const { proxy } = interceptors;
+
+const client = new Client("http://example.com");
+
+client.compose(proxy("http://proxy.com"));
+```
+
+### `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");
+
+client.compose(redirect({ maxRedirections: 3, throwOnMaxRedirects: true }));
+```
+
+### `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");
+
+client.compose(
+  retry({
+    maxRetries: 3,
+    minTimeout: 1000,
+    maxTimeout: 10000,
+    timeoutFactor: 2,
+    retryAfter: true,
+  })
+);
+```

docs/docsify/sidebar.md

@@ -9,6 +9,7 @@
   * [Agent](/docs/api/Agent.md "Undici API - Agent")
   * [ProxyAgent](/docs/api/ProxyAgent.md "Undici API - ProxyAgent")
   * [RetryAgent](/docs/api/RetryAgent.md "Undici API - RetryAgent")
+  * [Interceptors](/docs/api/Interceptors.md "Undici API - Interceptors")
   * [Connector](/docs/api/Connector.md "Custom connector")
   * [Errors](/docs/api/Errors.md "Undici API - Errors")
   * [EventSource](/docs/api/EventSource.md "Undici API - EventSource")

index.js

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

lib/dispatcher/dispatcher.js

@@ -1,8 +1,11 @@
 'use strict'
-
 const EventEmitter = require('node:events')
 
+const kDispatcherVersion = Symbol.for('undici.dispatcher.version')
+
 class Dispatcher extends EventEmitter {
+  [kDispatcherVersion] = 1
+
   dispatch () {
     throw new Error('not implemented')
   }
@@ -14,6 +17,28 @@ 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 dispatcher = this
+    for (const interceptor of interceptors) {
+      if (interceptor == null) {
+        continue
+      }
+
+      if (typeof interceptor !== 'function') {
+        throw new Error('invalid interceptor')
+      }
+
+      dispatcher = interceptor(dispatcher) ?? dispatcher
+
+      if (dispatcher[kDispatcherVersion] !== 1) {
+        throw new Error('invalid dispatcher')
+      }
+    }
+    return dispatcher
+  }
 }
 
 module.exports = Dispatcher

lib/interceptor/proxy.js

@@ -0,0 +1,45 @@
+'use strict'
+
+const { InvalidArgumentError } = require('../core/errors')
+const ProxyAgent = require('../dispatcher/proxy-agent')
+const Dispatcher = require('../dispatcher/dispatcher')
+
+class ProxyInterceptor extends Dispatcher {
+  constructor (dispatcher, opts) {
+    if (dispatcher == null) {
+      throw new InvalidArgumentError(
+        'Dispatcher instance is mandatory for ProxyInterceptor'
+      )
+    }
+
+    if (typeof opts === 'string') {
+      opts = { uri: opts }
+    }
+
+    if (!opts || (!opts.uri && !(opts instanceof URL))) {
+      throw new InvalidArgumentError(
+        'Proxy opts.uri or instance of URL is mandatory'
+      )
+    }
+
+    if (opts.auth && opts.token) {
+      throw new InvalidArgumentError(
+        'opts.auth cannot be used in combination with opts.token'
+      )
+    }
+
+    super()
+    this.dispatcher = dispatcher
+    this.agent = new ProxyAgent(opts)
+  }
+
+  dispatch (opts, handler) {
+    return this.agent.dispatch(opts, handler)
+  }
+
+  close () {
+    return this.dispatcher.close().then(() => this.agent.close())
+  }
+}
+
+module.exports = ProxyInterceptor

lib/interceptor/redirect.js

@@ -0,0 +1,44 @@
+'use strict'
+
+const { InvalidArgumentError } = require('../core/errors')
+const Dispatcher = require('../dispatcher/dispatcher')
+const RedirectHandler = require('../handler/RedirectHandler')
+
+class RedirectDispatcher extends Dispatcher {
+  #opts
+  #dispatcher
+
+  constructor (dispatcher, opts) {
+    super()
+
+    this.#dispatcher = dispatcher
+    this.#opts = opts
+  }
+
+  dispatch (opts, handler) {
+    return this.#dispatcher.dispatch(
+      opts,
+      new RedirectHandler(this.#dispatcher, opts, this.#opts, handler)
+    )
+  }
+
+  close (...args) {
+    return this.#dispatcher.close(...args)
+  }
+
+  destroy (...args) {
+    return this.#dispatcher.destroy(...args)
+  }
+}
+
+module.exports = opts => {
+  if (opts?.maxRedirections == null || opts?.maxRedirections === 0) {
+    return null
+  }
+
+  if (!Number.isInteger(opts.maxRedirections) || opts.maxRedirections < 0) {
+    throw new InvalidArgumentError('maxRedirections must be a positive number')
+  }
+
+  return dispatcher => new RedirectDispatcher(dispatcher, opts)
+}

lib/interceptor/retry.js

@@ -0,0 +1,35 @@
+'use strict'
+
+const Dispatcher = require('../dispatcher/dispatcher')
+const RetryHandler = require('../handler/RetryHandler')
+
+class RetryDispatcher extends Dispatcher {
+  #dispatcher
+  #opts
+
+  constructor (dispatcher, opts) {
+    super()
+
+    this.#dispatcher = dispatcher
+    this.#opts = opts
+  }
+
+  dispatch (opts, handler) {
+    return this.#dispatcher.dispatch(
+      opts,
+      new RetryHandler(this.#dispatcher, opts, this.#opts, handler)
+    )
+  }
+
+  close (...args) {
+    return this.#dispatcher.close(...args)
+  }
+
+  destroy (...args) {
+    return this.#dispatcher.destroy(...args)
+  }
+}
+
+module.exports = opts => {
+  return dispatcher => new RetryDispatcher(dispatcher, opts)
+}