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

@@ -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,170 @@
+'use strict'
+
+const util = require('../core/util')
+const { InvalidArgumentError, RequestAbortedError } = require('../core/errors')
+
+class DumpHandler {
+  #maxSize = 1024 * 1024
+  #abort = null
+  #abortOnDumped = true
+  #waitForTrailers = false
+  #hasTrailers = false
+  #dumped = false
+  #aborted = false
+  #completed = false
+  #size = 0
+  #reason = null
+  #handler = null
+
+  constructor ({ maxSize, abortOnDumped, waitForTrailers }, handler) {
+    if (maxSize != null && (!Number.isFinite(maxSize) || maxSize < 1)) {
+      throw new InvalidArgumentError('maxSize must be a number greater than 0')
+    }
+
+    if (abortOnDumped != null && typeof abortOnDumped !== 'boolean') {
+      throw new InvalidArgumentError('abortOnDumped must be a boolean')
+    }
+
+    if (waitForTrailers != null && typeof waitForTrailers !== 'boolean') {
+      throw new InvalidArgumentError('waitForTrailers must be a boolean')
+    }
+
+    this.#maxSize = maxSize ?? this.#maxSize
+    this.#abortOnDumped = abortOnDumped ?? this.#abortOnDumped
+    this.#waitForTrailers = waitForTrailers ?? this.#waitForTrailers
+    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 != null && contentLength > this.#maxSize) {
+      this.#reason = new RequestAbortedError(
+        `Response size (${contentLength}) larger than maxSize (${
+          this.#maxSize
+        })`
+      )
+
+      this.#abort(this.#reason)
+      return
+    }
+
+    if (this.#waitForTrailers) {
+      this.#hasTrailers = headers.trailer != null
+    }
+
+    this.#handler.onHeaders(statusCode, rawHeaders, resume, statusMessage)
+  }
+
+  onError (err) {
+    if (
+      !(err instanceof RequestAbortedError) &&
+      (!this.#dumped || this.#aborted)
+    ) {
+      this.#handler.onError(err)
+      return
+    }
+
+    if (!this.#completed) {
+      this.#handler.onComplete([])
+    }
+  }
+
+  onData (chunk) {
+    this.#size = this.#size + chunk.length
+
+    if (this.#size >= this.#maxSize) {
+      this.#dumped = true
+
+      if (this.#abortOnDumped && (!this.#waitForTrailers || !this.#hasTrailers)) {
+        console.log('dumped')
+        this.#reason = new RequestAbortedError(
+          `Response dumped (${this.#size}) for max size (${this.#maxSize})`
+        )
+
+        this.#abort(this.#reason)
+        return false
+      }
+    }
+
+    return true
+  }
+
+  onComplete (trailers) {
+    this.#completed = true
+    this.#handler.onComplete(trailers)
+
+    if (this.#dumped && this.#abortOnDumped) {
+      this.#reason = new RequestAbortedError(
+        `Response dumped (${this.#size}) for max size (${this.#maxSize})`
+      )
+
+      this.#abort(this.#reason)
+    }
+  }
+}
+
+function createDumpInterceptor (
+  {
+    maxSize: defaultMaxSize,
+    abortOnDumped: defaultAbortOnDumped,
+    waitForTrailers: defaultWaitForTrailers
+  } = {
+    maxSize: 1024 * 1024,
+    abortOnDumped: true,
+    waitForTrailers: false
+  }
+) {
+  return dispatch => {
+    return function Intercept (opts, handler) {
+      const {
+        dumpMaxSize = defaultMaxSize,
+        abortOnDumped = defaultAbortOnDumped,
+        waitForTrailers = defaultWaitForTrailers
+      } = opts
+
+      const dumpHandler = new DumpHandler(
+        { maxSize: dumpMaxSize, abortOnDumped, waitForTrailers },
+        handler
+      )
+
+      return dispatch(opts, dumpHandler)
+    }
+  }
+}
+
+module.exports = createDumpInterceptor