feat: dump interceptor

docs/docs/api/Dispatcher.md

@@ -952,6 +952,44 @@ 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`.
+- `abortOnDumped` - States whether or not abort the request after the response's body being dumped. Default: `true`.
+- `waitForTrailers` - Hints the dispatcher to wait for trailers if the response's body has been dumped. Default: `false`.
+
+> The `Dispatcher#options` also gets extended with the options `dumpMaxSize`, `abortOnDumped`, and `waitForTrailers` which can be used to configure the interceptor 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,
+    abortOnDumped: true,
+    waitForTrailers: false,
+  })
+);
+
+// or 
+client.dispatch(
+  {
+    path: "/",
+    method: "GET",
+    dumpMaxSize: 1024,
+    abortOnDumped: true,
+    waitForTrailers: false,
+  },
+  handler
+);
+```
+
 ## Instance Events
 
 ### Event: `'connect'`

index.js

@@ -40,7 +40,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,129 @@
+'use strict'
+
+const util = require('../core/util')
+const { InvalidArgumentError, RequestAbortedError } = require('../core/errors')
+const DecoratorHandler = require('../handler/decorator-handler')
+
+class DumpHandler extends DecoratorHandler {
+  #maxSize = 1024 * 1024
+  #abort = null
+  #dumpOnAbort = true
+  #dumped = false
+  #aborted = false
+  #size = 0
+  #reason = null
+  #handler = null
+
+  constructor (
+    { maxSize, dumpOnAbort },
+    handler
+  ) {
+    super(handler)
+
+    if (maxSize != null && (!Number.isFinite(maxSize) || maxSize < 1)) {
+      throw new InvalidArgumentError('maxSize must be a number greater than 0')
+    }
+
+    if (dumpOnAbort != null && typeof dumpOnAbort !== 'boolean') {
+      throw new InvalidArgumentError('dumpOnAbort must be a boolean')
+    }
+
+    this.#maxSize = maxSize ?? this.#maxSize
+    this.#dumpOnAbort = dumpOnAbort ?? this.#dumpOnAbort
+    this.#handler = handler
+  }
+
+  onConnect (abort) {
+    if (this.#aborted) {
+      abort(this.#reason)
+      return
+    }
+
+    this.#abort = abort
+
+    this.#handler.onConnect(
+      this.#dumpOnAbort === true ? this.#customAbort.bind(this) : this.#abort
+    )
+  }
+
+  #customAbort (reason) {
+    this.#aborted = true
+    this.#reason = reason
+  }
+
+  // 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 != null && contentLength > this.#maxSize) {
+      throw new RequestAbortedError(
+        `Response size (${contentLength}) larger than maxSize (${
+          this.#maxSize
+        })`
+      )
+    }
+
+    return this.#handler.onHeaders(
+      statusCode,
+      rawHeaders,
+      resume,
+      statusMessage
+    )
+  }
+
+  onError (err) {
+    if (
+      !(err instanceof RequestAbortedError) &&
+      (!this.#dumped || this.#aborted)
+    ) {
+      this.#handler.onError(err)
+      return
+    }
+
+    if (this.#dumped) {
+      this.#handler.onComplete([])
+    }
+  }
+
+  onData (chunk) {
+    this.#size = this.#size + chunk.length
+
+    if (this.#size >= this.#maxSize) {
+      this.#dumped = true
+      this.#handler.onData('')
+      this.#handler.onComplete([])
+    }
+
+    return true
+  }
+
+  onComplete (trailers) {
+    if (!this.#dumped) {
+      this.#handler.onComplete(trailers)
+    }
+  }
+}
+
+function createDumpInterceptor (
+  { maxSize: defaultMaxSize, dumpOnAbort: defaultDumpOnAbort } = {
+    maxSize: 1024 * 1024,
+    dumpOnAbort: true
+  }
+) {
+  return dispatch => {
+    return function Intercept (opts, handler) {
+      const { dumpMaxSize = defaultMaxSize, dumpOnAbort = defaultDumpOnAbort } =
+        opts
+
+      const dumpHandler = new DumpHandler(
+        { maxSize: dumpMaxSize, dumpOnAbort },
+        handler
+      )
+
+      return dispatch(opts, dumpHandler)
+    }
+  }
+}
+
+module.exports = createDumpInterceptor