undici 7.15.0 → 7.17.0

package/lib/handler/deduplication-handler.js

@@ -0,0 +1,216 @@
+'use strict'
+
+/**
+ * @typedef {import('../../types/dispatcher.d.ts').default.DispatchHandler} DispatchHandler
+ */
+
+/**
+ * Handler that buffers response data and notifies multiple waiting handlers.
+ * Used for request deduplication.
+ *
+ * @implements {DispatchHandler}
+ */
+class DeduplicationHandler {
+  /**
+   * @type {DispatchHandler}
+   */
+  #primaryHandler
+
+  /**
+   * @type {DispatchHandler[]}
+   */
+  #waitingHandlers = []
+
+  /**
+   * @type {Buffer[]}
+   */
+  #chunks = []
+
+  /**
+   * @type {number}
+   */
+  #statusCode = 0
+
+  /**
+   * @type {Record<string, string | string[]>}
+   */
+  #headers = {}
+
+  /**
+   * @type {string}
+   */
+  #statusMessage = ''
+
+  /**
+   * @type {boolean}
+   */
+  #aborted = false
+
+  /**
+   * @type {import('../../types/dispatcher.d.ts').default.DispatchController | null}
+   */
+  #controller = null
+
+  /**
+   * @type {(() => void) | null}
+   */
+  #onComplete = null
+
+  /**
+   * @param {DispatchHandler} primaryHandler The primary handler
+   * @param {() => void} onComplete Callback when request completes
+   */
+  constructor (primaryHandler, onComplete) {
+    this.#primaryHandler = primaryHandler
+    this.#onComplete = onComplete
+  }
+
+  /**
+   * Add a waiting handler that will receive the buffered response
+   * @param {DispatchHandler} handler
+   */
+  addWaitingHandler (handler) {
+    this.#waitingHandlers.push(handler)
+  }
+
+  /**
+   * @param {() => void} abort
+   * @param {any} context
+   */
+  onRequestStart (controller, context) {
+    this.#controller = controller
+    this.#primaryHandler.onRequestStart?.(controller, context)
+  }
+
+  /**
+   * @param {import('../../types/dispatcher.d.ts').default.DispatchController} controller
+   * @param {number} statusCode
+   * @param {import('../../types/header.d.ts').IncomingHttpHeaders} headers
+   * @param {Socket} socket
+   */
+  onRequestUpgrade (controller, statusCode, headers, socket) {
+    this.#primaryHandler.onRequestUpgrade?.(controller, statusCode, headers, socket)
+  }
+
+  /**
+   * @param {import('../../types/dispatcher.d.ts').default.DispatchController} controller
+   * @param {number} statusCode
+   * @param {Record<string, string | string[]>} headers
+   * @param {string} statusMessage
+   */
+  onResponseStart (controller, statusCode, headers, statusMessage) {
+    this.#statusCode = statusCode
+    this.#headers = headers
+    this.#statusMessage = statusMessage
+    this.#primaryHandler.onResponseStart?.(controller, statusCode, headers, statusMessage)
+  }
+
+  /**
+   * @param {import('../../types/dispatcher.d.ts').default.DispatchController} controller
+   * @param {Buffer} chunk
+   */
+  onResponseData (controller, chunk) {
+    // Buffer the chunk for waiting handlers
+    this.#chunks.push(Buffer.from(chunk))
+    this.#primaryHandler.onResponseData?.(controller, chunk)
+  }
+
+  /**
+   * @param {import('../../types/dispatcher.d.ts').default.DispatchController} controller
+   * @param {object} trailers
+   */
+  onResponseEnd (controller, trailers) {
+    this.#primaryHandler.onResponseEnd?.(controller, trailers)
+    this.#notifyWaitingHandlers()
+    this.#onComplete?.()
+  }
+
+  /**
+   * @param {import('../../types/dispatcher.d.ts').default.DispatchController} controller
+   * @param {Error} err
+   */
+  onResponseError (controller, err) {
+    this.#aborted = true
+    this.#primaryHandler.onResponseError?.(controller, err)
+    this.#notifyWaitingHandlersError(err)
+    this.#onComplete?.()
+  }
+
+  /**
+   * Notify all waiting handlers with the buffered response
+   */
+  #notifyWaitingHandlers () {
+    const body = Buffer.concat(this.#chunks)
+
+    for (const handler of this.#waitingHandlers) {
+      // Create a simple controller for each waiting handler
+      const waitingController = {
+        resume () {},
+        pause () {},
+        get paused () { return false },
+        get aborted () { return false },
+        get reason () { return null },
+        abort () {}
+      }
+
+      try {
+        handler.onRequestStart?.(waitingController, null)
+
+        if (waitingController.aborted) {
+          continue
+        }
+
+        handler.onResponseStart?.(
+          waitingController,
+          this.#statusCode,
+          this.#headers,
+          this.#statusMessage
+        )
+
+        if (waitingController.aborted) {
+          continue
+        }
+
+        if (body.length > 0) {
+          handler.onResponseData?.(waitingController, body)
+        }
+
+        handler.onResponseEnd?.(waitingController, {})
+      } catch {
+        // Ignore errors from waiting handlers
+      }
+    }
+
+    this.#waitingHandlers = []
+    this.#chunks = []
+  }
+
+  /**
+   * Notify all waiting handlers of an error
+   * @param {Error} err
+   */
+  #notifyWaitingHandlersError (err) {
+    for (const handler of this.#waitingHandlers) {
+      const waitingController = {
+        resume () {},
+        pause () {},
+        get paused () { return false },
+        get aborted () { return true },
+        get reason () { return err },
+        abort () {}
+      }
+
+      try {
+        handler.onRequestStart?.(waitingController, null)
+        handler.onResponseError?.(waitingController, err)
+      } catch {
+        // Ignore errors from waiting handlers
+      }
+    }
+
+    this.#waitingHandlers = []
+    this.#chunks = []
+  }
+}
+
+module.exports = DeduplicationHandler

package/lib/handler/retry-handler.js

@@ -92,8 +92,6 @@ class RetryHandler {
 
     function shouldRetry (passedErr) {
       if (passedErr) {
-        this.headersSent = true
-
         this.headersSent = true
         this.handler.onResponseStart?.(controller, statusCode, headers, statusMessage)
         controller.resume()

package/lib/interceptor/cache.js

@@ -9,6 +9,8 @@ const CacheRevalidationHandler = require('../handler/cache-revalidation-handler'
 const { assertCacheStore, assertCacheMethods, makeCacheKey, normalizeHeaders, parseCacheControlHeader } = require('../util/cache.js')
 const { AbortError } = require('../core/errors.js')
 
+const nop = () => {}
+
 /**
  * @typedef {(options: import('../../types/dispatcher.d.ts').default.DispatchOptions, handler: import('../../types/dispatcher.d.ts').default.DispatchHandler) => void} DispatchFn
  */
@@ -16,19 +18,34 @@ const { AbortError } = require('../core/errors.js')
 /**
  * @param {import('../../types/cache-interceptor.d.ts').default.GetResult} result
  * @param {import('../../types/cache-interceptor.d.ts').default.CacheControlDirectives | undefined} cacheControlDirectives
+ * @param {import('../../types/dispatcher.d.ts').default.RequestOptions} opts
  * @returns {boolean}
  */
-function needsRevalidation (result, cacheControlDirectives) {
+function needsRevalidation (result, cacheControlDirectives, { headers = {} }) {
+  // Always revalidate requests with the no-cache request directive.
   if (cacheControlDirectives?.['no-cache']) {
-    // Always revalidate requests with the no-cache request directive
     return true
   }
 
+  // Always revalidate requests with unqualified no-cache response directive.
   if (result.cacheControlDirectives?.['no-cache'] && !Array.isArray(result.cacheControlDirectives['no-cache'])) {
-    // Always revalidate requests with unqualified no-cache response directive
     return true
   }
 
+  // Always revalidate requests with conditional headers.
+  if (headers['if-modified-since'] || headers['if-none-match']) {
+    return true
+  }
+
+  return false
+}
+
+/**
+ * @param {import('../../types/cache-interceptor.d.ts').default.GetResult} result
+ * @param {import('../../types/cache-interceptor.d.ts').default.CacheControlDirectives | undefined} cacheControlDirectives
+ * @returns {boolean}
+ */
+function isStale (result, cacheControlDirectives) {
   const now = Date.now()
   if (now > result.staleAt) {
     // Response is stale
@@ -56,6 +73,22 @@ function needsRevalidation (result, cacheControlDirectives) {
   return false
 }
 
+/**
+ * Check if we're within the stale-while-revalidate window for a stale response
+ * @param {import('../../types/cache-interceptor.d.ts').default.GetResult} result
+ * @returns {boolean}
+ */
+function withinStaleWhileRevalidateWindow (result) {
+  const staleWhileRevalidate = result.cacheControlDirectives?.['stale-while-revalidate']
+  if (!staleWhileRevalidate) {
+    return false
+  }
+
+  const now = Date.now()
+  const staleWhileRevalidateExpiry = result.staleAt + (staleWhileRevalidate * 1000)
+  return now <= staleWhileRevalidateExpiry
+}
+
 /**
  * @param {DispatchFn} dispatch
  * @param {import('../../types/cache-interceptor.d.ts').default.CacheHandlerOptions} globalOpts
@@ -86,7 +119,7 @@ function handleUncachedResponse (
       }
 
       if (typeof handler.onHeaders === 'function') {
-        handler.onHeaders(504, [], () => {}, 'Gateway Timeout')
+        handler.onHeaders(504, [], nop, 'Gateway Timeout')
         if (aborted) {
           return
         }
@@ -223,14 +256,62 @@ function handleResult (
     return dispatch(opts, handler)
   }
 
+  const stale = isStale(result, reqCacheControl)
+  const revalidate = needsRevalidation(result, reqCacheControl, opts)
+
   // Check if the response is stale
-  if (needsRevalidation(result, reqCacheControl)) {
+  if (stale || revalidate) {
     if (util.isStream(opts.body) && util.bodyLength(opts.body) !== 0) {
       // If body is a stream we can't revalidate...
       // TODO (fix): This could be less strict...
       return dispatch(opts, new CacheHandler(globalOpts, cacheKey, handler))
     }
 
+    // RFC 5861: If we're within stale-while-revalidate window, serve stale immediately
+    // and revalidate in background, unless immediate revalidation is necessary
+    if (!revalidate && withinStaleWhileRevalidateWindow(result)) {
+      // Serve stale response immediately
+      sendCachedValue(handler, opts, result, age, null, true)
+
+      // Start background revalidation (fire-and-forget)
+      queueMicrotask(() => {
+        let headers = {
+          ...opts.headers,
+          'if-modified-since': new Date(result.cachedAt).toUTCString()
+        }
+
+        if (result.etag) {
+          headers['if-none-match'] = result.etag
+        }
+
+        if (result.vary) {
+          headers = {
+            ...headers,
+            ...result.vary
+          }
+        }
+
+        // Background revalidation - update cache if we get new data
+        dispatch(
+          {
+            ...opts,
+            headers
+          },
+          new CacheHandler(globalOpts, cacheKey, {
+            // Silent handler that just updates the cache
+            onRequestStart () {},
+            onRequestUpgrade () {},
+            onResponseStart () {},
+            onResponseData () {},
+            onResponseEnd () {},
+            onResponseError () {}
+          })
+        )
+      })
+
+      return true
+    }
+
     let withinStaleIfErrorThreshold = false
     const staleIfErrorExpiry = result.cacheControlDirectives['stale-if-error'] ?? reqCacheControl?.['stale-if-error']
     if (staleIfErrorExpiry) {
@@ -262,9 +343,10 @@ function handleResult (
       new CacheRevalidationHandler(
         (success, context) => {
           if (success) {
-            sendCachedValue(handler, opts, result, age, context, true)
+            // TODO: successful revalidation should be considered fresh (not give stale warning).
+            sendCachedValue(handler, opts, result, age, context, stale)
           } else if (util.isStream(result.body)) {
-            result.body.on('error', () => {}).destroy()
+            result.body.on('error', nop).destroy()
           }
         },
         new CacheHandler(globalOpts, cacheKey, handler),
@@ -275,7 +357,7 @@ function handleResult (
 
   // Dump request body.
   if (util.isStream(opts.body)) {
-    opts.body.on('error', () => {}).destroy()
+    opts.body.on('error', nop).destroy()
   }
 
   sendCachedValue(handler, opts, result, age, null, false)
@@ -344,18 +426,17 @@ module.exports = (opts = {}) => {
       const result = store.get(cacheKey)
 
       if (result && typeof result.then === 'function') {
-        result.then(result => {
-          handleResult(dispatch,
+        return result
+          .then(result => handleResult(dispatch,
             globalOpts,
             cacheKey,
             handler,
             opts,
             reqCacheControl,
             result
-          )
-        })
+          ))
       } else {
-        handleResult(
+        return handleResult(
           dispatch,
           globalOpts,
           cacheKey,
@@ -365,8 +446,6 @@ module.exports = (opts = {}) => {
           result
         )
       }
-
-      return true
     }
   }
 }

package/lib/interceptor/decompress.js

@@ -3,6 +3,7 @@
 const { createInflate, createGunzip, createBrotliDecompress, createZstdDecompress } = require('node:zlib')
 const { pipeline } = require('node:stream')
 const DecoratorHandler = require('../handler/decorator-handler')
+const { runtimeFeatures } = require('../util/runtime-features')
 
 /** @typedef {import('node:stream').Transform} Transform */
 /** @typedef {import('node:stream').Transform} Controller */
@@ -16,7 +17,7 @@ const supportedEncodings = {
   deflate: createInflate,
   compress: createInflate,
   'x-compress': createInflate,
-  ...(createZstdDecompress ? { zstd: createZstdDecompress } : {})
+  ...(runtimeFeatures.has('zstd') ? { zstd: createZstdDecompress } : {})
 }
 
 const defaultSkipStatusCodes = /** @type {const} */ ([204, 304])

package/lib/interceptor/deduplicate.js

@@ -0,0 +1,109 @@
+'use strict'
+
+const diagnosticsChannel = require('node:diagnostics_channel')
+const util = require('../core/util')
+const DeduplicationHandler = require('../handler/deduplication-handler')
+const { normalizeHeaders, makeCacheKey, makeDeduplicationKey } = require('../util/cache.js')
+
+const pendingRequestsChannel = diagnosticsChannel.channel('undici:request:pending-requests')
+
+/**
+ * @param {import('../../types/interceptors.d.ts').default.DeduplicateInterceptorOpts} [opts]
+ * @returns {import('../../types/dispatcher.d.ts').default.DispatcherComposeInterceptor}
+ */
+module.exports = (opts = {}) => {
+  const {
+    methods = ['GET'],
+    skipHeaderNames = [],
+    excludeHeaderNames = []
+  } = opts
+
+  if (typeof opts !== 'object' || opts === null) {
+    throw new TypeError(`expected type of opts to be an Object, got ${opts === null ? 'null' : typeof opts}`)
+  }
+
+  if (!Array.isArray(methods)) {
+    throw new TypeError(`expected opts.methods to be an array, got ${typeof methods}`)
+  }
+
+  for (const method of methods) {
+    if (!util.safeHTTPMethods.includes(method)) {
+      throw new TypeError(`expected opts.methods to only contain safe HTTP methods, got ${method}`)
+    }
+  }
+
+  if (!Array.isArray(skipHeaderNames)) {
+    throw new TypeError(`expected opts.skipHeaderNames to be an array, got ${typeof skipHeaderNames}`)
+  }
+
+  if (!Array.isArray(excludeHeaderNames)) {
+    throw new TypeError(`expected opts.excludeHeaderNames to be an array, got ${typeof excludeHeaderNames}`)
+  }
+
+  // Convert to lowercase Set for case-insensitive header matching
+  const skipHeaderNamesSet = new Set(skipHeaderNames.map(name => name.toLowerCase()))
+
+  // Convert to lowercase Set for case-insensitive header exclusion from deduplication key
+  const excludeHeaderNamesSet = new Set(excludeHeaderNames.map(name => name.toLowerCase()))
+
+  const safeMethodsToNotDeduplicate = util.safeHTTPMethods.filter(method => methods.includes(method) === false)
+
+  /**
+   * Map of pending requests for deduplication
+   * @type {Map<string, DeduplicationHandler>}
+   */
+  const pendingRequests = new Map()
+
+  return dispatch => {
+    return (opts, handler) => {
+      if (!opts.origin || safeMethodsToNotDeduplicate.includes(opts.method)) {
+        return dispatch(opts, handler)
+      }
+
+      opts = {
+        ...opts,
+        headers: normalizeHeaders(opts)
+      }
+
+      // Skip deduplication if request contains any of the specified headers
+      if (skipHeaderNamesSet.size > 0) {
+        for (const headerName of Object.keys(opts.headers)) {
+          if (skipHeaderNamesSet.has(headerName.toLowerCase())) {
+            return dispatch(opts, handler)
+          }
+        }
+      }
+
+      const cacheKey = makeCacheKey(opts)
+      const dedupeKey = makeDeduplicationKey(cacheKey, excludeHeaderNamesSet)
+
+      // Check if there's already a pending request for this key
+      const pendingHandler = pendingRequests.get(dedupeKey)
+      if (pendingHandler) {
+        // Add this handler to the waiting list
+        pendingHandler.addWaitingHandler(handler)
+        return true
+      }
+
+      // Create a new deduplication handler
+      const deduplicationHandler = new DeduplicationHandler(
+        handler,
+        () => {
+          // Clean up when request completes
+          pendingRequests.delete(dedupeKey)
+          if (pendingRequestsChannel.hasSubscribers) {
+            pendingRequestsChannel.publish({ size: pendingRequests.size, key: dedupeKey, type: 'removed' })
+          }
+        }
+      )
+
+      // Register the pending request
+      pendingRequests.set(dedupeKey, deduplicationHandler)
+      if (pendingRequestsChannel.hasSubscribers) {
+        pendingRequestsChannel.publish({ size: pendingRequests.size, key: dedupeKey, type: 'added' })
+      }
+
+      return dispatch(opts, deduplicationHandler)
+    }
+  }
+}

package/lib/interceptor/dns.js

@@ -5,14 +5,44 @@ const DecoratorHandler = require('../handler/decorator-handler')
 const { InvalidArgumentError, InformationalError } = require('../core/errors')
 const maxInt = Math.pow(2, 31) - 1
 
+class DNSStorage {
+  #maxItems = 0
+  #records = new Map()
+
+  constructor (opts) {
+    this.#maxItems = opts.maxItems
+  }
+
+  get size () {
+    return this.#records.size
+  }
+
+  get (hostname) {
+    return this.#records.get(hostname) ?? null
+  }
+
+  set (hostname, records) {
+    this.#records.set(hostname, records)
+  }
+
+  delete (hostname) {
+    this.#records.delete(hostname)
+  }
+
+  // Delegate to storage decide can we do more lookups or not
+  full () {
+    return this.size >= this.#maxItems
+  }
+}
+
 class DNSInstance {
   #maxTTL = 0
   #maxItems = 0
-  #records = new Map()
   dualStack = true
   affinity = null
   lookup = null
   pick = null
+  storage = null
 
   constructor (opts) {
     this.#maxTTL = opts.maxTTL
@@ -21,17 +51,14 @@ class DNSInstance {
     this.affinity = opts.affinity
     this.lookup = opts.lookup ?? this.#defaultLookup
     this.pick = opts.pick ?? this.#defaultPick
-  }
-
-  get full () {
-    return this.#records.size === this.#maxItems
+    this.storage = opts.storage ?? new DNSStorage(opts)
   }
 
   runLookup (origin, opts, cb) {
-    const ips = this.#records.get(origin.hostname)
+    const ips = this.storage.get(origin.hostname)
 
     // If full, we just return the origin
-    if (ips == null && this.full) {
+    if (ips == null && this.storage.full()) {
       cb(null, origin)
       return
     }
@@ -55,7 +82,7 @@ class DNSInstance {
         }
 
         this.setRecords(origin, addresses)
-        const records = this.#records.get(origin.hostname)
+        const records = this.storage.get(origin.hostname)
 
         const ip = this.pick(
           origin,
@@ -89,7 +116,7 @@ class DNSInstance {
 
       // If no IPs we lookup - deleting old records
       if (ip == null) {
-        this.#records.delete(origin.hostname)
+        this.storage.delete(origin.hostname)
         this.runLookup(origin, opts, cb)
         return
       }
@@ -193,7 +220,7 @@ class DNSInstance {
   }
 
   pickFamily (origin, ipFamily) {
-    const records = this.#records.get(origin.hostname)?.records
+    const records = this.storage.get(origin.hostname)?.records
     if (!records) {
       return null
     }
@@ -227,11 +254,13 @@ class DNSInstance {
   setRecords (origin, addresses) {
     const timestamp = Date.now()
     const records = { records: { 4: null, 6: null } }
+    let minTTL = this.#maxTTL
     for (const record of addresses) {
       record.timestamp = timestamp
       if (typeof record.ttl === 'number') {
         // The record TTL is expected to be in ms
         record.ttl = Math.min(record.ttl, this.#maxTTL)
+        minTTL = Math.min(minTTL, record.ttl)
       } else {
         record.ttl = this.#maxTTL
       }
@@ -242,11 +271,12 @@ class DNSInstance {
       records.records[record.family] = familyRecords
     }
 
-    this.#records.set(origin.hostname, records)
+    // We provide a default TTL if external storage will be used without TTL per record-level support
+    this.storage.set(origin.hostname, records, { ttl: minTTL })
   }
 
   deleteRecords (origin) {
-    this.#records.delete(origin.hostname)
+    this.storage.delete(origin.hostname)
   }
 
   getHandler (meta, opts) {
@@ -372,6 +402,17 @@ module.exports = interceptorOpts => {
     throw new InvalidArgumentError('Invalid pick. Must be a function')
   }
 
+  if (
+    interceptorOpts?.storage != null &&
+    (typeof interceptorOpts?.storage?.get !== 'function' ||
+      typeof interceptorOpts?.storage?.set !== 'function' ||
+      typeof interceptorOpts?.storage?.full !== 'function' ||
+      typeof interceptorOpts?.storage?.delete !== 'function'
+    )
+  ) {
+    throw new InvalidArgumentError('Invalid storage. Must be a object with methods: { get, set, full, delete }')
+  }
+
   const dualStack = interceptorOpts?.dualStack ?? true
   let affinity
   if (dualStack) {
@@ -386,7 +427,8 @@ module.exports = interceptorOpts => {
     pick: interceptorOpts?.pick ?? null,
     dualStack,
     affinity,
-    maxItems: interceptorOpts?.maxItems ?? Infinity
+    maxItems: interceptorOpts?.maxItems ?? Infinity,
+    storage: interceptorOpts?.storage
   }
 
   const instance = new DNSInstance(opts)