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

package/lib/handler/cache-handler.js

@@ -0,0 +1,359 @@
+'use strict'
+
+const util = require('../core/util')
+const DecoratorHandler = require('../handler/decorator-handler')
+const {
+  parseCacheControlHeader,
+  parseVaryHeader
+} = require('../util/cache')
+
+/**
+ * Writes a response to a CacheStore and then passes it on to the next handler
+ */
+class CacheHandler extends DecoratorHandler {
+  /**
+   * @type {import('../../types/cache-interceptor.d.ts').default.CacheStore}
+   */
+  #store
+
+  /**
+   * @type {import('../../types/dispatcher.d.ts').default.RequestOptions}
+   */
+  #requestOptions
+
+  /**
+   * @type {import('../../types/dispatcher.d.ts').default.DispatchHandlers}
+   */
+  #handler
+
+  /**
+   * @type {import('../../types/cache-interceptor.d.ts').default.CacheStoreWriteable | undefined}
+   */
+  #writeStream
+
+  /**
+   * @param {import('../../types/cache-interceptor.d.ts').default.CacheOptions} opts
+   * @param {import('../../types/dispatcher.d.ts').default.RequestOptions} requestOptions
+   * @param {import('../../types/dispatcher.d.ts').default.DispatchHandlers} handler
+   */
+  constructor (opts, requestOptions, handler) {
+    const { store } = opts
+
+    super(handler)
+
+    this.#store = store
+    this.#requestOptions = requestOptions
+    this.#handler = handler
+  }
+
+  /**
+   * @see {DispatchHandlers.onHeaders}
+   *
+   * @param {number} statusCode
+   * @param {Buffer[]} rawHeaders
+   * @param {() => void} resume
+   * @param {string} statusMessage
+   * @returns {boolean}
+   */
+  onHeaders (
+    statusCode,
+    rawHeaders,
+    resume,
+    statusMessage
+  ) {
+    const downstreamOnHeaders = () => this.#handler.onHeaders(
+      statusCode,
+      rawHeaders,
+      resume,
+      statusMessage
+    )
+
+    if (
+      !util.safeHTTPMethods.includes(this.#requestOptions.method) &&
+      statusCode >= 200 &&
+      statusCode <= 399
+    ) {
+      // https://www.rfc-editor.org/rfc/rfc9111.html#name-invalidating-stored-respons
+      // Try/catch for if it's synchronous
+      try {
+        const result = this.#store.deleteByOrigin(this.#requestOptions.origin)
+        if (
+          result &&
+          typeof result.catch === 'function' &&
+          typeof this.#handler.onError === 'function'
+        ) {
+          // Fail silently
+          result.catch(_ => {})
+        }
+      } catch (err) {
+        // Fail silently
+      }
+
+      return downstreamOnHeaders()
+    }
+
+    const headers = util.parseHeaders(rawHeaders)
+
+    const cacheControlHeader = headers['cache-control']
+    const contentLengthHeader = headers['content-length']
+
+    if (!cacheControlHeader || !contentLengthHeader || this.#store.isFull) {
+      // Don't have the headers we need, can't cache
+      return downstreamOnHeaders()
+    }
+
+    const contentLength = Number(contentLengthHeader)
+    if (!Number.isInteger(contentLength)) {
+      return downstreamOnHeaders()
+    }
+
+    const cacheControlDirectives = parseCacheControlHeader(cacheControlHeader)
+    if (!canCacheResponse(statusCode, headers, cacheControlDirectives)) {
+      return downstreamOnHeaders()
+    }
+
+    const now = Date.now()
+    const staleAt = determineStaleAt(now, headers, cacheControlDirectives)
+    if (staleAt) {
+      const varyDirectives = headers.vary
+        ? parseVaryHeader(headers.vary, this.#requestOptions.headers)
+        : undefined
+      const deleteAt = determineDeleteAt(now, cacheControlDirectives, staleAt)
+
+      const strippedHeaders = stripNecessaryHeaders(
+        rawHeaders,
+        headers,
+        cacheControlDirectives
+      )
+
+      this.#writeStream = this.#store.createWriteStream(this.#requestOptions, {
+        statusCode,
+        statusMessage,
+        rawHeaders: strippedHeaders,
+        vary: varyDirectives,
+        cachedAt: now,
+        staleAt,
+        deleteAt
+      })
+
+      if (this.#writeStream) {
+        this.#writeStream.on('drain', resume)
+        this.#writeStream.on('error', () => {
+          this.#writeStream = undefined
+          resume()
+        })
+      }
+    }
+
+    if (typeof this.#handler.onHeaders === 'function') {
+      return downstreamOnHeaders()
+    }
+    return false
+  }
+
+  /**
+   * @see {DispatchHandlers.onData}
+   *
+   * @param {Buffer} chunk
+   * @returns {boolean}
+   */
+  onData (chunk) {
+    let paused = false
+
+    if (this.#writeStream) {
+      paused ||= this.#writeStream.write(chunk) === false
+    }
+
+    if (typeof this.#handler.onData === 'function') {
+      paused ||= this.#handler.onData(chunk) === false
+    }
+
+    return !paused
+  }
+
+  /**
+   * @see {DispatchHandlers.onComplete}
+   *
+   * @param {string[] | null} rawTrailers
+   */
+  onComplete (rawTrailers) {
+    if (this.#writeStream) {
+      if (rawTrailers) {
+        this.#writeStream.rawTrailers = rawTrailers
+      }
+
+      this.#writeStream.end()
+    }
+
+    if (typeof this.#handler.onComplete === 'function') {
+      return this.#handler.onComplete(rawTrailers)
+    }
+  }
+
+  /**
+   * @see {DispatchHandlers.onError}
+   *
+   * @param {Error} err
+   */
+  onError (err) {
+    if (this.#writeStream) {
+      this.#writeStream.destroy(err)
+      this.#writeStream = undefined
+    }
+
+    if (typeof this.#handler.onError === 'function') {
+      this.#handler.onError(err)
+    }
+  }
+}
+
+/**
+ * @see https://www.rfc-editor.org/rfc/rfc9111.html#name-storing-responses-to-authen
+ *
+ * @param {number} statusCode
+ * @param {Record<string, string>} headers
+ * @param {import('../util/cache.js').CacheControlDirectives} cacheControlDirectives
+ */
+function canCacheResponse (statusCode, headers, cacheControlDirectives) {
+  if (
+    statusCode !== 200 &&
+    statusCode !== 307
+  ) {
+    return false
+  }
+
+  if (
+    !cacheControlDirectives.public ||
+    cacheControlDirectives.private === true ||
+    cacheControlDirectives['no-cache'] === true ||
+    cacheControlDirectives['no-store']
+  ) {
+    return false
+  }
+
+  // https://www.rfc-editor.org/rfc/rfc9111.html#section-4.1-5
+  if (headers.vary === '*') {
+    return false
+  }
+
+  // https://www.rfc-editor.org/rfc/rfc9111.html#name-storing-responses-to-authen
+  if (headers['authorization']) {
+    if (
+      Array.isArray(cacheControlDirectives['no-cache']) &&
+      cacheControlDirectives['no-cache'].includes('authorization')
+    ) {
+      return false
+    }
+
+    if (
+      Array.isArray(cacheControlDirectives['private']) &&
+      cacheControlDirectives['private'].includes('authorization')
+    ) {
+      return false
+    }
+  }
+
+  return true
+}
+
+/**
+ * @param {number} now
+ * @param {Record<string, string | string[]>} headers
+ * @param {import('../util/cache.js').CacheControlDirectives} cacheControlDirectives
+ *
+ * @returns {number | undefined} time that the value is stale at or undefined if it shouldn't be cached
+ */
+function determineStaleAt (now, headers, cacheControlDirectives) {
+  // Prioritize s-maxage since we're a shared cache
+  //  s-maxage > max-age > Expire
+  //  https://www.rfc-editor.org/rfc/rfc9111.html#section-5.2.2.10-3
+  const sMaxAge = cacheControlDirectives['s-maxage']
+  if (sMaxAge) {
+    return now + (sMaxAge * 1000)
+  }
+
+  if (cacheControlDirectives.immutable) {
+    // https://www.rfc-editor.org/rfc/rfc8246.html#section-2.2
+    return now + 31536000
+  }
+
+  const maxAge = cacheControlDirectives['max-age']
+  if (maxAge) {
+    return now + (maxAge * 1000)
+  }
+
+  if (headers.expire) {
+    // https://www.rfc-editor.org/rfc/rfc9111.html#section-5.3
+    return now + (Date.now() - new Date(headers.expire).getTime())
+  }
+
+  return undefined
+}
+
+/**
+ * @param {number} now
+ * @param {import('../util/cache.js').CacheControlDirectives} cacheControlDirectives
+ * @param {number} staleAt
+ */
+function determineDeleteAt (now, cacheControlDirectives, staleAt) {
+  if (cacheControlDirectives['stale-while-revalidate']) {
+    return now + (cacheControlDirectives['stale-while-revalidate'] * 1000)
+  }
+
+  return staleAt
+}
+
+/**
+ * Strips headers required to be removed in cached responses
+ * @param {Buffer[]} rawHeaders
+ * @param {Record<string, string | string[]>} parsedHeaders
+ * @param {import('../util/cache.js').CacheControlDirectives} cacheControlDirectives
+ * @returns {(Buffer|Buffer[])[]}
+ */
+function stripNecessaryHeaders (rawHeaders, parsedHeaders, cacheControlDirectives) {
+  const headersToRemove = ['connection']
+
+  if (Array.isArray(cacheControlDirectives['no-cache'])) {
+    headersToRemove.push(...cacheControlDirectives['no-cache'])
+  }
+
+  if (Array.isArray(cacheControlDirectives['private'])) {
+    headersToRemove.push(...cacheControlDirectives['private'])
+  }
+
+  /**
+   * These are the headers that are okay to cache. If this is assigned, we need
+   *  to remake the buffer representation of the headers
+   * @type {Record<string, string | string[]> | undefined}
+   */
+  let strippedHeaders
+
+  const headerNames = Object.keys(parsedHeaders)
+  for (let i = 0; i < headerNames.length; i++) {
+    const header = headerNames[i]
+
+    if (headersToRemove.indexOf(header) !== -1) {
+      // We have a at least one header we want to remove
+      if (!strippedHeaders) {
+        // This is the first header we want to remove, let's create the object
+        //  and backfill the previous headers into it
+        strippedHeaders = {}
+
+        for (let j = 0; j < i; j++) {
+          strippedHeaders[headerNames[j]] = parsedHeaders[headerNames[j]]
+        }
+      }
+
+      continue
+    }
+
+    // This header is fine. Let's add it to strippedHeaders if it exists.
+    if (strippedHeaders) {
+      strippedHeaders[header] = parsedHeaders[header]
+    }
+  }
+
+  return strippedHeaders ? util.encodeHeaders(strippedHeaders) : rawHeaders
+}
+
+module.exports = CacheHandler

package/lib/handler/cache-revalidation-handler.js

@@ -0,0 +1,119 @@
+'use strict'
+
+const DecoratorHandler = require('../handler/decorator-handler')
+
+/**
+ * This takes care of revalidation requests we send to the origin. If we get
+ *  a response indicating that what we have is cached (via a HTTP 304), we can
+ *  continue using the cached value. Otherwise, we'll receive the new response
+ *  here, which we then just pass on to the next handler (most likely a
+ *  CacheHandler). Note that this assumes the proper headers were already
+ *  included in the request to tell the origin that we want to revalidate the
+ *  response (i.e. if-modified-since).
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc9111.html#name-validation
+ *
+ * @typedef {import('../../types/dispatcher.d.ts').default.DispatchHandlers} DispatchHandlers
+ * @implements {DispatchHandlers}
+ */
+class CacheRevalidationHandler extends DecoratorHandler {
+  #successful = false
+  /**
+   * @type {(() => void)}
+   */
+  #successCallback
+  /**
+   * @type {(import('../../types/dispatcher.d.ts').default.DispatchHandlers)}
+   */
+  #handler
+
+  /**
+   * @param {() => void} successCallback Function to call if the cached value is valid
+   * @param {import('../../types/dispatcher.d.ts').default.DispatchHandlers} handler
+   */
+  constructor (successCallback, handler) {
+    if (typeof successCallback !== 'function') {
+      throw new TypeError('successCallback must be a function')
+    }
+
+    super(handler)
+
+    this.#successCallback = successCallback
+    this.#handler = handler
+  }
+
+  /**
+   * @see {DispatchHandlers.onHeaders}
+   *
+   * @param {number} statusCode
+   * @param {Buffer[]} rawHeaders
+   * @param {() => void} resume
+   * @param {string} statusMessage
+   * @returns {boolean}
+   */
+  onHeaders (
+    statusCode,
+    rawHeaders,
+    resume,
+    statusMessage
+  ) {
+    // https://www.rfc-editor.org/rfc/rfc9111.html#name-handling-a-validation-respo
+    if (statusCode === 304) {
+      this.#successful = true
+      this.#successCallback()
+      return true
+    }
+
+    if (typeof this.#handler.onHeaders === 'function') {
+      return this.#handler.onHeaders(
+        statusCode,
+        rawHeaders,
+        resume,
+        statusMessage
+      )
+    }
+    return false
+  }
+
+  /**
+   * @see {DispatchHandlers.onData}
+   *
+   * @param {Buffer} chunk
+   * @returns {boolean}
+   */
+  onData (chunk) {
+    if (this.#successful) {
+      return true
+    }
+
+    if (typeof this.#handler.onData === 'function') {
+      return this.#handler.onData(chunk)
+    }
+
+    return false
+  }
+
+  /**
+   * @see {DispatchHandlers.onComplete}
+   *
+   * @param {string[] | null} rawTrailers
+   */
+  onComplete (rawTrailers) {
+    if (!this.#successful && typeof this.#handler.onComplete === 'function') {
+      this.#handler.onComplete(rawTrailers)
+    }
+  }
+
+  /**
+   * @see {DispatchHandlers.onError}
+   *
+   * @param {Error} err
+   */
+  onError (err) {
+    if (typeof this.#handler.onError === 'function') {
+      this.#handler.onError(err)
+    }
+  }
+}
+
+module.exports = CacheRevalidationHandler

package/lib/interceptor/cache.js

@@ -0,0 +1,171 @@
+'use strict'
+
+const util = require('../core/util')
+const CacheHandler = require('../handler/cache-handler')
+const MemoryCacheStore = require('../cache/memory-cache-store')
+const CacheRevalidationHandler = require('../handler/cache-revalidation-handler')
+const { assertCacheStore, assertCacheMethods } = require('../util/cache.js')
+
+const AGE_HEADER = Buffer.from('age')
+
+/**
+ * @param {import('../../types/cache-interceptor.d.ts').default.CacheOptions} [opts]
+ * @returns {import('../../types/dispatcher.d.ts').default.DispatcherComposeInterceptor}
+ */
+module.exports = (opts = {}) => {
+  const {
+    store = new MemoryCacheStore(),
+    methods = ['GET']
+  } = opts
+
+  if (typeof opts !== 'object' || opts === null) {
+    throw new TypeError(`expected type of opts to be an Object, got ${opts === null ? 'null' : typeof opts}`)
+  }
+
+  assertCacheStore(store, 'opts.store')
+  assertCacheMethods(methods, 'opts.methods')
+
+  const globalOpts = {
+    store,
+    methods
+  }
+
+  const safeMethodsToNotCache = util.safeHTTPMethods.filter(method => methods.includes(method) === false)
+
+  return dispatch => {
+    return (opts, handler) => {
+      if (!opts.origin || safeMethodsToNotCache.includes(opts.method)) {
+        // Not a method we want to cache or we don't have the origin, skip
+        return dispatch(opts, handler)
+      }
+
+      const stream = store.createReadStream(opts)
+      if (!stream) {
+        // Request isn't cached
+        return dispatch(opts, new CacheHandler(globalOpts, opts, handler))
+      }
+
+      let onErrorCalled = false
+
+      /**
+       * @param {import('../../types/cache-interceptor.d.ts').default.CacheStoreReadable} stream
+       * @param {import('../../types/cache-interceptor.d.ts').default.CacheStoreValue} value
+       */
+      const respondWithCachedValue = (stream, value) => {
+        const ac = new AbortController()
+        const signal = ac.signal
+
+        signal.onabort = (_, err) => {
+          stream.destroy()
+          if (!onErrorCalled) {
+            handler.onError(err)
+            onErrorCalled = true
+          }
+        }
+
+        stream.on('error', (err) => {
+          if (!onErrorCalled) {
+            handler.onError(err)
+            onErrorCalled = true
+          }
+        })
+
+        try {
+          if (typeof handler.onConnect === 'function') {
+            handler.onConnect(ac.abort)
+            signal.throwIfAborted()
+          }
+
+          if (typeof handler.onHeaders === 'function') {
+            // Add the age header
+            // https://www.rfc-editor.org/rfc/rfc9111.html#name-age
+            const age = Math.round((Date.now() - value.cachedAt) / 1000)
+
+            value.rawHeaders.push(AGE_HEADER, Buffer.from(`${age}`))
+
+            handler.onHeaders(value.statusCode, value.rawHeaders, stream.resume, value.statusMessage)
+            signal.throwIfAborted()
+          }
+
+          if (opts.method === 'HEAD') {
+            if (typeof handler.onComplete === 'function') {
+              handler.onComplete(null)
+              stream.destroy()
+            }
+          } else {
+            if (typeof handler.onData === 'function') {
+              stream.on('data', chunk => {
+                if (!handler.onData(chunk)) {
+                  stream.pause()
+                }
+              })
+            }
+
+            if (typeof handler.onComplete === 'function') {
+              stream.on('end', () => {
+                handler.onComplete(value.rawTrailers ?? [])
+              })
+            }
+          }
+        } catch (err) {
+          stream.destroy(err)
+          if (!onErrorCalled && typeof handler.onError === 'function') {
+            handler.onError(err)
+            onErrorCalled = true
+          }
+        }
+      }
+
+      /**
+       * @param {import('../../types/cache-interceptor.d.ts').default.CacheStoreReadable | undefined} stream
+       */
+      const handleStream = (stream) => {
+        if (!stream) {
+          // Request isn't cached
+          return dispatch(opts, new CacheHandler(globalOpts, opts, handler))
+        }
+
+        const { value } = stream
+
+        // Dump body on error
+        if (util.isStream(opts.body)) {
+          opts.body?.on('error', () => {}).resume()
+        }
+
+        // Check if the response is stale
+        const now = Date.now()
+        if (now >= value.staleAt) {
+          if (now >= value.deleteAt) {
+            // Safety check in case the store gave us a response that should've been
+            //  deleted already
+            dispatch(opts, new CacheHandler(globalOpts, opts, handler))
+            return
+          }
+
+          if (!opts.headers) {
+            opts.headers = {}
+          }
+
+          opts.headers['if-modified-since'] = new Date(value.cachedAt).toUTCString()
+
+          // Need to revalidate the response
+          dispatch(
+            opts,
+            new CacheRevalidationHandler(
+              () => respondWithCachedValue(stream, value),
+              new CacheHandler(globalOpts, opts, handler)
+            )
+          )
+
+          return
+        }
+
+        respondWithCachedValue(stream, value)
+      }
+
+      Promise.resolve(stream).then(handleStream).catch(handler.onError)
+
+      return true
+    }
+  }
+}