Extensible DispatchHandler (nodejs#1338)

* Create DispatchInterceptors

* Add Unit Tests, fix DispatchHandler typescript
Add documentation

* Switch to simple null check and shortcircuit bind

* Add typescript test for Dispatcher events

* Move build intecepted dispatch to top level

* Restore lost method

* Fix TS error

* Address code review comments

* Fix linting

* Type improvements

* Fix TS tests

* Address code review comments

* Fix TS test

* Fix types

* Address comments

* Fix client construction

Co-authored-by: Igor Savin <[email protected]>

Author: arontsang

docs/api/Agent.md

@@ -20,6 +20,7 @@ Extends: [`ClientOptions`](Pool.md#parameter-pooloptions)
 
 * **factory** `(origin: URL, opts: Object) => Dispatcher` - Default: `(origin, opts) => new Pool(origin, opts)`
 * **maxRedirections** `Integer` - Default: `0`. The number of HTTP redirection to follow unless otherwise specified in `DispatchOptions`.
+* **interceptors** `{ Agent: 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).
 
 ## Instance Properties
 

docs/api/Client.md

@@ -26,6 +26,7 @@ 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).
 
 #### Parameter: `ConnectOptions`
 

docs/api/DispatchInterceptor.md

@@ -0,0 +1,60 @@
+#Interface: DispatchInterceptor
+
+Extends: `Function`
+
+A function that can be applied to the `Dispatcher.Dispatch` function before it is invoked with a dispatch request.
+
+This allows one to write logic to intercept both the outgoing request, and the incoming response.
+
+### Parameter: `Dispatcher.Dispatch`
+
+The base dispatch function you are decorating.
+
+### ReturnType: `Dispatcher.Dispatch`
+
+A dispatch function that has been altered to provide additional logic
+
+### Basic Example
+
+Here is an example of an interceptor being used to provide a JWT bearer token
+
+```js
+'use strict'
+
+const insertHeaderInterceptor = dispatch => {
+  return function InterceptedDispatch(opts, handler){
+    opts.headers.push('Authorization', 'Bearer [Some token]')
+    return dispatch(opts, handler)
+  }
+}
+
+const client = new Client('https://localhost:3000', {
+  interceptors: { Client: [insertHeaderInterceptor] }
+})
+
+```
+
+### Basic Example 2
+
+Here is a contrived example of an interceptor stripping the headers from a response.
+
+```js
+'use strict'
+
+const clearHeadersInterceptor = dispatch => {
+  const { DecoratorHandler } = require('undici')
+  class ResultInterceptor extends DecoratorHandler {
+    onHeaders (statusCode, headers, resume) {
+      return super.onHeaders(statusCode, [], resume)
+    }
+  }
+  return function InterceptedDispatch(opts, handler){
+    return dispatch(opts, new ResultInterceptor(handler))
+  }
+}
+
+const client = new Client('https://localhost:3000', {
+  interceptors: { Client: [clearHeadersInterceptor] }
+})
+
+```

docs/api/Pool.md

@@ -19,6 +19,7 @@ Extends: [`ClientOptions`](Client.md#parameter-clientoptions)
 
 * **factory** `(origin: URL, opts: Object) => Dispatcher` - Default: `(origin, opts) => new Client(origin, opts)`
 * **connections** `number | null` (optional) - Default: `null` - The number of `Client` instances to create. When set to `null`, the `Pool` instance will create an unlimited amount of `Client` instances.
+* **interceptors** `{ Pool: DispatchInterceptor[] } }` - Default: `{ Pool: [] }` - 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).
 
 ## Instance Properties
 

index.d.ts

@@ -2,6 +2,8 @@ import Dispatcher = require('./types/dispatcher')
 import { setGlobalDispatcher, getGlobalDispatcher } from './types/global-dispatcher'
 import { setGlobalOrigin, getGlobalOrigin } from './types/global-origin'
 import Pool = require('./types/pool')
+import { RedirectHandler, DecoratorHandler } from './types/handlers'
+
 import BalancedPool = require('./types/balanced-pool')
 import Client = require('./types/client')
 import buildConnector = require('./types/connector')
@@ -20,14 +22,17 @@ export * from './types/formdata'
 export * from './types/diagnostics-channel'
 export { Interceptable } from './types/mock-interceptor'
 
-export { Dispatcher, BalancedPool, Pool, Client, buildConnector, errors, Agent, request, stream, pipeline, connect, upgrade, setGlobalDispatcher, getGlobalDispatcher, setGlobalOrigin, getGlobalOrigin, MockClient, MockPool, MockAgent, mockErrors, ProxyAgent }
+export { Dispatcher, BalancedPool, Pool, Client, buildConnector, errors, Agent, request, stream, pipeline, connect, upgrade, setGlobalDispatcher, getGlobalDispatcher, setGlobalOrigin, getGlobalOrigin, MockClient, MockPool, MockAgent, mockErrors, ProxyAgent, RedirectHandler, DecoratorHandler }
 export default Undici
 
 declare function Undici(url: string, opts: Pool.Options): Pool
 
 declare namespace Undici {
   var Dispatcher: typeof import('./types/dispatcher')
   var Pool: typeof import('./types/pool');
+  var RedirectHandler: typeof import ('./types/handlers').RedirectHandler
+  var DecoratorHandler: typeof import ('./types/handlers').DecoratorHandler
+  var createRedirectInterceptor: typeof import ('./types/interceptors').createRedirectInterceptor
   var BalancedPool: typeof import('./types/balanced-pool');
   var Client: typeof import('./types/client');
   var buildConnector: typeof import('./types/connector');

index.js

@@ -16,6 +16,9 @@ const MockPool = require('./lib/mock/mock-pool')
 const mockErrors = require('./lib/mock/mock-errors')
 const ProxyAgent = require('./lib/proxy-agent')
 const { getGlobalDispatcher, setGlobalDispatcher } = require('./lib/global')
+const DecoratorHandler = require('./lib/handler/DecoratorHandler')
+const RedirectHandler = require('./lib/handler/RedirectHandler')
+const createRedirectInterceptor = require('./lib/interceptor/redirectInterceptor')
 
 const nodeVersion = process.versions.node.split('.')
 const nodeMajor = Number(nodeVersion[0])
@@ -30,6 +33,10 @@ module.exports.BalancedPool = BalancedPool
 module.exports.Agent = Agent
 module.exports.ProxyAgent = ProxyAgent
 
+module.exports.DecoratorHandler = DecoratorHandler
+module.exports.RedirectHandler = RedirectHandler
+module.exports.createRedirectInterceptor = createRedirectInterceptor
+
 module.exports.buildConnector = buildConnector
 module.exports.errors = errors
 

lib/agent.js

@@ -1,12 +1,12 @@
 'use strict'
 
 const { InvalidArgumentError } = require('./core/errors')
-const { kClients, kRunning, kClose, kDestroy, kDispatch } = require('./core/symbols')
+const { kClients, kRunning, kClose, kDestroy, kDispatch, kInterceptors } = require('./core/symbols')
 const DispatcherBase = require('./dispatcher-base')
 const Pool = require('./pool')
 const Client = require('./client')
 const util = require('./core/util')
-const RedirectHandler = require('./handler/redirect')
+const createRedirectInterceptor = require('./interceptor/redirectInterceptor')
 const { WeakRef, FinalizationRegistry } = require('./compat/dispatcher-weakref')()
 
 const kOnConnect = Symbol('onConnect')
@@ -44,7 +44,14 @@ class Agent extends DispatcherBase {
       connect = { ...connect }
     }
 
+    this[kInterceptors] = options.interceptors && options.interceptors.Agent && Array.isArray(options.interceptors.Agent)
+      ? options.interceptors.Agent
+      : [createRedirectInterceptor({ maxRedirections })]
+
     this[kOptions] = { ...util.deepClone(options), connect }
+    this[kOptions].interceptors = options.interceptors
+      ? { ...options.interceptors }
+      : undefined
     this[kMaxRedirections] = maxRedirections
     this[kFactory] = factory
     this[kClients] = new Map()
@@ -108,12 +115,6 @@ class Agent extends DispatcherBase {
       this[kFinalizer].register(dispatcher, key)
     }
 
-    const { maxRedirections = this[kMaxRedirections] } = opts
-    if (maxRedirections != null && maxRedirections !== 0) {
-      opts = { ...opts, maxRedirections: 0 } // Stop sub dispatcher from also redirecting.
-      handler = new RedirectHandler(this, maxRedirections, opts, handler)
-    }
-
     return dispatcher.dispatch(opts, handler)
   }
 

lib/balanced-pool.js

@@ -13,7 +13,7 @@ const {
   kGetDispatcher
 } = require('./pool-base')
 const Pool = require('./pool')
-const { kUrl } = require('./core/symbols')
+const { kUrl, kInterceptors } = require('./core/symbols')
 const { parseOrigin } = require('./core/util')
 const kFactory = Symbol('factory')
 
@@ -53,6 +53,9 @@ class BalancedPool extends PoolBase {
       throw new InvalidArgumentError('factory must be a function.')
     }
 
+    this[kInterceptors] = opts.interceptors && opts.interceptors.BalancedPool && Array.isArray(opts.interceptors.BalancedPool)
+      ? opts.interceptors.BalancedPool
+      : []
     this[kFactory] = factory
 
     for (const upstream of upstreams) {

lib/client.js

@@ -7,7 +7,6 @@ const net = require('net')
 const util = require('./core/util')
 const Request = require('./core/request')
 const DispatcherBase = require('./dispatcher-base')
-const RedirectHandler = require('./handler/redirect')
 const {
   RequestContentLengthMismatchError,
   ResponseContentLengthMismatchError,
@@ -60,7 +59,8 @@ const {
   kCounter,
   kClose,
   kDestroy,
-  kDispatch
+  kDispatch,
+  kInterceptors
 } = require('./core/symbols')
 
 const kClosedResolve = Symbol('kClosedResolve')
@@ -82,6 +82,7 @@ try {
 
 class Client extends DispatcherBase {
   constructor (url, {
+    interceptors,
     maxHeaderSize,
     headersTimeout,
     socketTimeout,
@@ -179,6 +180,9 @@ class Client extends DispatcherBase {
       })
     }
 
+    this[kInterceptors] = interceptors && interceptors.Client && Array.isArray(interceptors.Client)
+      ? interceptors.Client
+      : [createRedirectInterceptor({ maxRedirections })]
     this[kUrl] = util.parseOrigin(url)
     this[kConnector] = connect
     this[kSocket] = null
@@ -254,11 +258,6 @@ class Client extends DispatcherBase {
   }
 
   [kDispatch] (opts, handler) {
-    const { maxRedirections = this[kMaxRedirections] } = opts
-    if (maxRedirections) {
-      handler = new RedirectHandler(this, maxRedirections, opts, handler)
-    }
-
     const origin = opts.origin || this[kUrl].origin
 
     const request = new Request(origin, opts, handler)
@@ -319,6 +318,7 @@ class Client extends DispatcherBase {
 }
 
 const constants = require('./llhttp/constants')
+const createRedirectInterceptor = require('./interceptor/redirectInterceptor')
 const EMPTY_BUF = Buffer.alloc(0)
 
 async function lazyllhttp () {

lib/core/symbols.js

@@ -48,5 +48,6 @@ module.exports = {
   kMaxRedirections: Symbol('maxRedirections'),
   kMaxRequests: Symbol('maxRequestsPerClient'),
   kProxy: Symbol('proxy agent options'),
-  kCounter: Symbol('socket request counter')
+  kCounter: Symbol('socket request counter'),
+  kInterceptors: Symbol('dispatch interceptors')
 }