undici 7.0.0-alpha.2 → 7.0.0-alpha.3

package/README.md

@@ -132,7 +132,7 @@ Returns a promise with the result of the `Dispatcher.request` method.
 
 Calls `options.dispatcher.request(options)`.
 
-See [Dispatcher.request](./docs/docs/api/Dispatcher.md#dispatcherrequestoptions-callback) for more details, and [request examples](./examples/README.md) for examples.
+See [Dispatcher.request](./docs/docs/api/Dispatcher.md#dispatcherrequestoptions-callback) for more details, and [request examples](./docs/examples/README.md) for examples.
 
 ### `undici.stream([url, options, ]factory): Promise`
 

package/docs/docs/api/CacheStore.md

@@ -0,0 +1,116 @@
+# Cache Store
+
+A Cache Store is responsible for storing and retrieving cached responses.
+It is also responsible for deciding which specific response to use based off of
+a response's `Vary` header (if present).
+
+## Pre-built Cache Stores
+
+### `MemoryCacheStore`
+
+The `MemoryCacheStore` stores the responses in-memory.
+
+**Options**
+
+- `maxEntries` - The maximum amount of responses to store. Default `Infinity`.
+- `maxEntrySize` - The maximum size in bytes that a response's body can be. If a response's body is greater than or equal to this, the response will not be cached.
+
+## Defining a Custom Cache Store
+
+The store must implement the following functions:
+
+### Getter: `isFull`
+
+This tells the cache interceptor if the store is full or not. If this is true,
+the cache interceptor will not attempt to cache the response.
+
+### Function: `createReadStream`
+
+Parameters:
+
+* **req** `Dispatcher.RequestOptions` - Incoming request
+
+Returns: `CacheStoreReadable | Promise<CacheStoreReadable | undefined> | undefined` - If the request is cached, a readable for the body is returned. Otherwise, `undefined` is returned.
+
+### Function: `createWriteStream`
+
+Parameters:
+
+* **req** `Dispatcher.RequestOptions` - Incoming request
+* **value** `CacheStoreValue` - Response to store
+
+Returns: `CacheStoreWriteable | undefined` - If the store is full, return `undefined`. Otherwise, return a writable so that the cache interceptor can stream the body and trailers to the store.
+
+## `CacheStoreValue`
+
+This is an interface containing the majority of a response's data (minus the body).
+
+### Property `statusCode`
+
+`number` - The response's HTTP status code.
+
+### Property `statusMessage`
+
+`string` - The response's HTTP status message.
+
+### Property `rawHeaders`
+
+`(Buffer | Buffer[])[]` - The response's headers.
+
+### Property `rawTrailers`
+
+`string[] | undefined` - The response's trailers.
+
+### Property `vary`
+
+`Record<string, string> | undefined` - The headers defined by the response's `Vary` header
+and their respective values for later comparison
+
+For example, for a response like
+```
+Vary: content-encoding, accepts
+content-encoding: utf8
+accepts: application/json
+```
+
+This would be
+```js
+{
+  'content-encoding': 'utf8',
+  accepts: 'application/json'
+}
+```
+
+### Property `cachedAt`
+
+`number` - Time in millis that this value was cached.
+
+### Property `staleAt`
+
+`number` - Time in millis that this value is considered stale.
+
+### Property `deleteAt`
+
+`number` - Time in millis that this value is to be deleted from the cache. This
+is either the same sa staleAt or the `max-stale` caching directive.
+
+The store must not return a response after the time defined in this property.
+
+## `CacheStoreReadable`
+
+This extends Node's [`Readable`](https://nodejs.org/api/stream.html#class-streamreadable)
+and defines extra properties relevant to the cache interceptor.
+
+### Getter: `value`
+
+The response's [`CacheStoreValue`](#cachestorevalue)
+
+## `CacheStoreWriteable`
+
+This extends Node's [`Writable`](https://nodejs.org/api/stream.html#class-streamwritable)
+and defines extra properties relevant to the cache interceptor.
+
+### Setter: `rawTrailers`
+
+If the response has trailers, the cache interceptor will pass them to the cache
+interceptor through this method.

package/docs/docs/api/Dispatcher.md

@@ -1233,6 +1233,16 @@ test('should not error if request status code is not in the specified error code
 
 The Response Error Interceptor provides a robust mechanism for handling HTTP response errors by capturing detailed error information and propagating it through a structured `ResponseError` class. This enhancement improves error handling and debugging capabilities in applications using the interceptor.
 
+##### `Cache Interceptor`
+
+The `cache` interceptor implements client-side response caching as described in
+[RFC9111](https://www.rfc-editor.org/rfc/rfc9111.html).
+
+**Options**
+
+- `store` - The [`CacheStore`](./CacheStore.md) to store and retrieve responses from. Default is [`MemoryCacheStore`](./CacheStore.md#memorycachestore).
+- `methods` - The [**safe** HTTP methods](https://www.rfc-editor.org/rfc/rfc9110#section-9.2.1) to cache the response of.
+
 ## Instance Events
 
 ### Event: `'connect'`

package/index.js

@@ -40,7 +40,12 @@ module.exports.interceptors = {
   redirect: require('./lib/interceptor/redirect'),
   retry: require('./lib/interceptor/retry'),
   dump: require('./lib/interceptor/dump'),
-  dns: require('./lib/interceptor/dns')
+  dns: require('./lib/interceptor/dns'),
+  cache: require('./lib/interceptor/cache')
+}
+
+module.exports.cacheStores = {
+  MemoryCacheStore: require('./lib/cache/memory-cache-store')
 }
 
 module.exports.buildConnector = buildConnector

package/lib/api/api-request.js

@@ -65,7 +65,7 @@ class RequestHandler extends AsyncResource {
       this.removeAbortListener = util.addAbortListener(signal, () => {
         this.reason = signal.reason ?? new RequestAbortedError()
         if (this.res) {
-          util.destroy(this.res, this.reason)
+          util.destroy(this.res.on('error', noop), this.reason)
         } else if (this.abort) {
           this.abort(this.reason)
         }

package/lib/api/readable.js

@@ -164,7 +164,7 @@ class BodyReadable extends Readable {
    * @see https://fetch.spec.whatwg.org/#dom-body-text
    * @returns {Promise<string>}
    */
-  async text () {
+  text () {
     return consume(this, 'text')
   }
 
@@ -174,7 +174,7 @@ class BodyReadable extends Readable {
    * @see https://fetch.spec.whatwg.org/#dom-body-json
    * @returns {Promise<unknown>}
    */
-  async json () {
+  json () {
     return consume(this, 'json')
   }
 
@@ -184,7 +184,7 @@ class BodyReadable extends Readable {
    * @see https://fetch.spec.whatwg.org/#dom-body-blob
    * @returns {Promise<Blob>}
    */
-  async blob () {
+  blob () {
     return consume(this, 'blob')
   }
 
@@ -194,7 +194,7 @@ class BodyReadable extends Readable {
    * @see https://fetch.spec.whatwg.org/#dom-body-bytes
    * @returns {Promise<Uint8Array>}
    */
-  async bytes () {
+  bytes () {
     return consume(this, 'bytes')
   }
 
@@ -204,7 +204,7 @@ class BodyReadable extends Readable {
    * @see https://fetch.spec.whatwg.org/#dom-body-arraybuffer
    * @returns {Promise<ArrayBuffer>}
    */
-  async arrayBuffer () {
+  arrayBuffer () {
     return consume(this, 'arrayBuffer')
   }
 
@@ -355,7 +355,7 @@ function isUnusable (bodyReadable) {
  * @param {string} type
  * @returns {Promise<any>}
  */
-async function consume (stream, type) {
+function consume (stream, type) {
   assert(!stream[kConsume])
 
   return new Promise((resolve, reject) => {

package/lib/cache/memory-cache-store.js

@@ -0,0 +1,417 @@
+'use strict'
+
+const { Writable, Readable } = require('node:stream')
+
+/**
+ * @typedef {import('../../types/cache-interceptor.d.ts').default.CacheStore} CacheStore
+ * @implements {CacheStore}
+ *
+ * @typedef {{
+ *  readers: number
+ *  readLock: boolean
+ *  writeLock: boolean
+ *  opts: import('../../types/cache-interceptor.d.ts').default.CacheStoreValue
+ *  body: Buffer[]
+ * }} MemoryStoreValue
+ */
+class MemoryCacheStore {
+  #maxEntries = Infinity
+
+  #maxEntrySize = Infinity
+
+  /**
+   * @type {((err) => void) | undefined}
+   */
+  #errorCallback = undefined
+
+  #entryCount = 0
+
+  /**
+   * @type {Map<string, Map<string, MemoryStoreValue>>}
+   */
+  #data = new Map()
+
+  /**
+   * @param {import('../../types/cache-interceptor.d.ts').default.MemoryCacheStoreOpts | undefined} [opts]
+   */
+  constructor (opts) {
+    if (opts) {
+      if (typeof opts !== 'object') {
+        throw new TypeError('MemoryCacheStore options must be an object')
+      }
+
+      if (opts.maxEntries !== undefined) {
+        if (
+          typeof opts.maxEntries !== 'number' ||
+          !Number.isInteger(opts.maxEntries) ||
+          opts.maxEntries < 0
+        ) {
+          throw new TypeError('MemoryCacheStore options.maxEntries must be a non-negative integer')
+        }
+        this.#maxEntries = opts.maxEntries
+      }
+
+      if (opts.maxEntrySize !== undefined) {
+        if (
+          typeof opts.maxEntrySize !== 'number' ||
+          !Number.isInteger(opts.maxEntrySize) ||
+          opts.maxEntrySize < 0
+        ) {
+          throw new TypeError('MemoryCacheStore options.maxEntrySize must be a non-negative integer')
+        }
+        this.#maxEntrySize = opts.maxEntrySize
+      }
+
+      if (opts.errorCallback !== undefined) {
+        if (typeof opts.errorCallback !== 'function') {
+          throw new TypeError('MemoryCacheStore options.errorCallback must be a function')
+        }
+        this.#errorCallback = opts.errorCallback
+      }
+    }
+  }
+
+  get isFull () {
+    return this.#entryCount >= this.#maxEntries
+  }
+
+  /**
+   * @param {import('../../types/dispatcher.d.ts').default.RequestOptions} req
+   * @returns {import('../../types/cache-interceptor.d.ts').default.CacheStoreReadable | undefined}
+   */
+  createReadStream (req) {
+    if (typeof req !== 'object') {
+      throw new TypeError(`expected req to be object, got ${typeof req}`)
+    }
+
+    const values = this.#getValuesForRequest(req, false)
+    if (!values) {
+      return undefined
+    }
+
+    const value = this.#findValue(req, values)
+
+    if (!value || value.readLock) {
+      return undefined
+    }
+
+    return new MemoryStoreReadableStream(value)
+  }
+
+  /**
+   * @param {import('../../types/dispatcher.d.ts').default.RequestOptions} req
+   * @param {import('../../types/cache-interceptor.d.ts').default.CacheStoreValue} opts
+   * @returns {import('../../types/cache-interceptor.d.ts').default.CacheStoreWriteable | undefined}
+   */
+  createWriteStream (req, opts) {
+    if (typeof req !== 'object') {
+      throw new TypeError(`expected req to be object, got ${typeof req}`)
+    }
+    if (typeof opts !== 'object') {
+      throw new TypeError(`expected value to be object, got ${typeof opts}`)
+    }
+
+    if (this.isFull) {
+      return undefined
+    }
+
+    const values = this.#getValuesForRequest(req, true)
+
+    let value = this.#findValue(req, values)
+    if (!value) {
+      // The value doesn't already exist, meaning we haven't cached this
+      //  response before. Let's assign it a value and insert it into our data
+      //  property.
+
+      if (this.isFull) {
+        // Or not, we don't have space to add another response
+        return undefined
+      }
+
+      this.#entryCount++
+
+      value = {
+        readers: 0,
+        readLock: false,
+        writeLock: false,
+        opts,
+        body: []
+      }
+
+      // We want to sort our responses in decending order by their deleteAt
+      //  timestamps so that deleting expired responses is faster
+      if (
+        values.length === 0 ||
+        opts.deleteAt < values[values.length - 1].deleteAt
+      ) {
+        // Our value is either the only response for this path or our deleteAt
+        //  time is sooner than all the other responses
+        values.push(value)
+      } else if (opts.deleteAt >= values[0].deleteAt) {
+        // Our deleteAt is later than everyone elses
+        values.unshift(value)
+      } else {
+        // We're neither in the front or the end, let's just binary search to
+        //  find our stop we need to be in
+        let startIndex = 0
+        let endIndex = values.length
+        while (true) {
+          if (startIndex === endIndex) {
+            values.splice(startIndex, 0, value)
+            break
+          }
+
+          const middleIndex = Math.floor((startIndex + endIndex) / 2)
+          const middleValue = values[middleIndex]
+          if (opts.deleteAt === middleIndex) {
+            values.splice(middleIndex, 0, value)
+            break
+          } else if (opts.deleteAt > middleValue.opts.deleteAt) {
+            endIndex = middleIndex
+            continue
+          } else {
+            startIndex = middleIndex
+            continue
+          }
+        }
+      }
+    } else {
+      // Check if there's already another request writing to the value or
+      //  a request reading from it
+      if (value.writeLock || value.readLock) {
+        return undefined
+      }
+
+      // Empty it so we can overwrite it
+      value.body = []
+    }
+
+    const writable = new MemoryStoreWritableStream(
+      value,
+      this.#maxEntrySize
+    )
+
+    // Remove the value if there was some error
+    writable.on('error', (err) => {
+      values.filter(current => value !== current)
+      if (this.#errorCallback) {
+        this.#errorCallback(err)
+      }
+    })
+
+    writable.on('bodyOversized', () => {
+      values.filter(current => value !== current)
+    })
+
+    return writable
+  }
+
+  /**
+   * @param {string} origin
+   */
+  deleteByOrigin (origin) {
+    this.#data.delete(origin)
+  }
+
+  /**
+   * Gets all of the requests of the same origin, path, and method. Does not
+   *  take the `vary` property into account.
+   * @param {import('../../types/dispatcher.d.ts').default.RequestOptions} req
+   * @param {boolean} [makeIfDoesntExist=false]
+   */
+  #getValuesForRequest (req, makeIfDoesntExist) {
+    // https://www.rfc-editor.org/rfc/rfc9111.html#section-2-3
+    let cachedPaths = this.#data.get(req.origin)
+    if (!cachedPaths) {
+      if (!makeIfDoesntExist) {
+        return undefined
+      }
+
+      cachedPaths = new Map()
+      this.#data.set(req.origin, cachedPaths)
+    }
+
+    let values = cachedPaths.get(`${req.path}:${req.method}`)
+    if (!values && makeIfDoesntExist) {
+      values = []
+      cachedPaths.set(`${req.path}:${req.method}`, values)
+    }
+
+    return values
+  }
+
+  /**
+   * Given a list of values of a certain request, this decides the best value
+   *  to respond with.
+   * @param {import('../../types/dispatcher.d.ts').default.RequestOptions} req
+   * @param {MemoryStoreValue[]} values
+   * @returns {MemoryStoreValue | undefined}
+   */
+  #findValue (req, values) {
+    /**
+     * @type {MemoryStoreValue}
+     */
+    let value
+    const now = Date.now()
+    for (let i = values.length - 1; i >= 0; i--) {
+      const current = values[i]
+      const currentCacheValue = current.opts
+      if (now >= currentCacheValue.deleteAt) {
+        // We've reached expired values, let's delete them
+        this.#entryCount -= values.length - i
+        values.length = i
+        break
+      }
+
+      let matches = true
+
+      if (currentCacheValue.vary) {
+        if (!req.headers) {
+          matches = false
+          break
+        }
+
+        for (const key in currentCacheValue.vary) {
+          if (currentCacheValue.vary[key] !== req.headers[key]) {
+            matches = false
+            break
+          }
+        }
+      }
+
+      if (matches) {
+        value = current
+        break
+      }
+    }
+
+    return value
+  }
+}
+
+class MemoryStoreReadableStream extends Readable {
+  /**
+   * @type {MemoryStoreValue}
+   */
+  #value
+  /**
+   * @type {Buffer[]}
+   */
+  #chunksToSend = []
+
+  /**
+   * @param {MemoryStoreValue} value
+   */
+  constructor (value) {
+    super()
+
+    if (value.readLock) {
+      throw new Error('can\'t read a locked value')
+    }
+
+    this.#value = value
+    this.#chunksToSend = value?.body ? [...value.body, null] : [null]
+
+    this.#value.readers++
+    this.#value.writeLock = true
+
+    this.on('close', () => {
+      this.#value.readers--
+
+      if (this.#value.readers === 0) {
+        this.#value.writeLock = false
+      }
+    })
+  }
+
+  get value () {
+    return this.#value.opts
+  }
+
+  /**
+   * @param {number} size
+   */
+  _read (size) {
+    if (this.#chunksToSend.length === 0) {
+      throw new Error('no chunks left to read, stream should have closed')
+    }
+
+    if (size > this.#chunksToSend.length) {
+      size = this.#chunksToSend.length
+    }
+
+    for (let i = 0; i < size; i++) {
+      this.push(this.#chunksToSend.shift())
+    }
+  }
+}
+
+class MemoryStoreWritableStream extends Writable {
+  /**
+   * @type {MemoryStoreValue}
+   */
+  #value
+  #currentSize = 0
+  #maxEntrySize = 0
+  /**
+   * @type {Buffer[]|null}
+   */
+  #body = []
+
+  /**
+   * @param {MemoryStoreValue} value
+   * @param {number} maxEntrySize
+   */
+  constructor (value, maxEntrySize) {
+    super()
+    this.#value = value
+    this.#value.readLock = true
+    this.#maxEntrySize = maxEntrySize ?? Infinity
+  }
+
+  get rawTrailers () {
+    return this.#value.opts.rawTrailers
+  }
+
+  /**
+   * @param {string[] | undefined} trailers
+   */
+  set rawTrailers (trailers) {
+    this.#value.opts.rawTrailers = trailers
+  }
+
+  /**
+   * @param {Buffer} chunk
+   * @param {string} encoding
+   * @param {BufferEncoding} encoding
+   */
+  _write (chunk, encoding, callback) {
+    if (typeof chunk === 'string') {
+      chunk = Buffer.from(chunk, encoding)
+    }
+
+    this.#currentSize += chunk.byteLength
+    if (this.#currentSize < this.#maxEntrySize) {
+      this.#body.push(chunk)
+    } else {
+      this.#body = null // release memory as early as possible
+      this.emit('bodyOversized')
+    }
+
+    callback()
+  }
+
+  /**
+   * @param {() => void} callback
+   */
+  _final (callback) {
+    if (this.#currentSize < this.#maxEntrySize) {
+      this.#value.readLock = false
+      this.#value.body = this.#body
+    }
+
+    callback()
+  }
+}
+
+module.exports = MemoryCacheStore

package/lib/core/constants.js

@@ -107,6 +107,28 @@ const headerNameLowerCasedRecord = {}
 // Note: object prototypes should not be able to be referenced. e.g. `Object#hasOwnProperty`.
 Object.setPrototypeOf(headerNameLowerCasedRecord, null)
 
+/**
+ * @type {Record<Lowercase<typeof wellknownHeaderNames[number]>, Buffer>}
+ */
+const wellknownHeaderNameBuffers = {}
+
+// Note: object prototypes should not be able to be referenced. e.g. `Object#hasOwnProperty`.
+Object.setPrototypeOf(wellknownHeaderNameBuffers, null)
+
+/**
+ * @param {string} header Lowercased header
+ * @returns {Buffer}
+ */
+function getHeaderNameAsBuffer (header) {
+  let buffer = wellknownHeaderNameBuffers[header]
+
+  if (buffer === undefined) {
+    buffer = Buffer.from(header)
+  }
+
+  return buffer
+}
+
 for (let i = 0; i < wellknownHeaderNames.length; ++i) {
   const key = wellknownHeaderNames[i]
   const lowerCasedKey = key.toLowerCase()
@@ -116,5 +138,6 @@ for (let i = 0; i < wellknownHeaderNames.length; ++i) {
 
 module.exports = {
   wellknownHeaderNames,
-  headerNameLowerCasedRecord
+  headerNameLowerCasedRecord,
+  getHeaderNameAsBuffer
 }