feat: dump interceptor

docs/docs/api/Dispatcher.md

@@ -952,6 +952,38 @@ const client = new Client("http://example.com").compose(
 );
 ```
 
+##### `dump`
+
+The `dump` interceptor enables you to dump the response body from a request upon a given limit.
+
+**Options**
+- `maxSize` - The maximum size (in bytes) of the response body to dump. If the size of the request's body exceeds this value then the connection will be closed. Default: `1048576`.
+
+> The `Dispatcher#options` also gets extended with the option `dumpMaxSize` which can be used to set the default `maxSize` at a request-per-request basis.
+
+**Example - Basic Dump Interceptor**
+
+```js
+const { Client, interceptors } = require("undici");
+const { dump } = interceptors;
+
+const client = new Client("http://example.com").compose(
+  dump({
+    maxSize: 1024,
+  })
+);
+
+// or 
+client.dispatch(
+  {
+    path: "/",
+    method: "GET",
+    dumpMaxSize: 1024,
+  },
+  handler
+);
+```
+
 ## Instance Events
 
 ### Event: `'connect'`

index.js

@@ -38,7 +38,8 @@ module.exports.RedirectHandler = RedirectHandler
 module.exports.createRedirectInterceptor = createRedirectInterceptor
 module.exports.interceptors = {
   redirect: require('./lib/interceptor/redirect'),
-  retry: require('./lib/interceptor/retry')
+  retry: require('./lib/interceptor/retry'),
+  dump: require('./lib/interceptor/dump')
 }
 
 module.exports.buildConnector = buildConnector

lib/interceptor/dump.js

@@ -0,0 +1,109 @@
+'use strict'
+
+const util = require('../core/util')
+const { InvalidArgumentError, RequestAbortedError } = require('../core/errors')
+
+class DumpHandler {
+  res = null
+  maxSize = 1024 * 1024
+
+  #abort = null
+  #aborted = false
+  #size = 0
+  #contentLength = 0
+  #reason = null
+  #handler = null
+
+  constructor ({ maxSize }, handler) {
+    if (maxSize != null && (!Number.isFinite(maxSize) || maxSize < 1)) {
+      throw new InvalidArgumentError('maxSize must be a number greater than 0')
+    }
+
+    this.maxSize = maxSize ?? this.maxSize
+    this.#handler = handler
+
+    // Handle possible onConnect duplication
+    this.#handler.onConnect(reason => {
+      this.#aborted = true
+      if (this.#abort != null) {
+        this.#abort(reason)
+      } else {
+        this.#reason = reason
+      }
+    })
+  }
+
+  onConnect (...args) {
+    const [abort] = args
+    if (this.#aborted) {
+      abort(this.#reason)
+      return
+    }
+
+    this.#abort = abort
+  }
+
+  onResponseStarted () {
+    this.#handler.onResponseStarted?.()
+  }
+
+  onBodySent () {
+    this.#handler.onBodySent?.()
+  }
+
+  onUpgrade (statusCode, headers, socket) {
+    this.#handler.onUpgrade?.(statusCode, headers, socket)
+  }
+
+  // TODO: will require adjustment after new hooks are out
+  onHeaders (statusCode, rawHeaders, resume, statusMessage) {
+    const headers = util.parseHeaders(rawHeaders)
+    const contentLength = headers['content-length']
+
+    if (contentLength > this.maxSize) {
+      this.#reason = new RequestAbortedError(
+        `Response size (${contentLength}) larger than maxSize (${this.maxSize})`
+      )
+
+      this.#abort(this.#reason)
+      return
+    }
+
+    this.#contentLength = contentLength
+    this.#handler.onHeaders(statusCode, rawHeaders, resume, statusMessage)
+  }
+
+  onError (err) {
+    this.#handler.onError(err)
+  }
+
+  onData (chunk) {
+    this.#size = this.#size + chunk.length
+
+    if (this.#size < this.maxSize) {
+      return true
+    }
+
+    // TODO: shall we forward the rest of the data to the handler or better to abort?
+  }
+
+  onComplete (trailers) {
+    this.#handler.onComplete(trailers)
+  }
+}
+
+function createDumpInterceptor (
+  { maxSize: defaultMaxSize } = { maxSize: 1024 * 1024 }
+) {
+  return dispatch => {
+    return function Intercept (opts, handler) {
+      const { dumpMaxSize = defaultMaxSize } = opts
+
+      const dumpHandler = new DumpHandler({ maxSize: dumpMaxSize }, handler)
+
+      return dispatch(opts, dumpHandler)
+    }
+  }
+}
+
+module.exports = createDumpInterceptor