undici 7.12.0 → 7.13.0

package/lib/mock/snapshot-recorder.js

@@ -0,0 +1,517 @@
+'use strict'
+
+const { writeFile, readFile, mkdir } = require('node:fs/promises')
+const { dirname, resolve } = require('node:path')
+const { InvalidArgumentError, UndiciError } = require('../core/errors')
+
+/**
+ * Formats a request for consistent snapshot storage
+ * Caches normalized headers to avoid repeated processing
+ */
+function formatRequestKey (opts, cachedSets, matchOptions = {}) {
+  const url = new URL(opts.path, opts.origin)
+
+  // Cache normalized headers if not already done
+  const normalized = opts._normalizedHeaders || normalizeHeaders(opts.headers)
+  if (!opts._normalizedHeaders) {
+    opts._normalizedHeaders = normalized
+  }
+
+  return {
+    method: opts.method || 'GET',
+    url: matchOptions.matchQuery !== false ? url.toString() : `${url.origin}${url.pathname}`,
+    headers: filterHeadersForMatching(normalized, cachedSets, matchOptions),
+    body: matchOptions.matchBody !== false && opts.body ? String(opts.body) : undefined
+  }
+}
+
+/**
+ * Filters headers based on matching configuration
+ */
+function filterHeadersForMatching (headers, cachedSets, matchOptions = {}) {
+  if (!headers || typeof headers !== 'object') return {}
+
+  const {
+    matchHeaders = null,
+    caseSensitive = false
+  } = matchOptions
+
+  const filtered = {}
+  const { ignoreSet, excludeSet, matchSet } = cachedSets
+
+  for (const [key, value] of Object.entries(headers)) {
+    const headerKey = caseSensitive ? key : key.toLowerCase()
+
+    // Skip if in exclude list (for security)
+    if (excludeSet.has(headerKey)) continue
+
+    // Skip if in ignore list (for matching)
+    if (ignoreSet.has(headerKey)) continue
+
+    // If matchHeaders is specified, only include those headers
+    if (matchHeaders && Array.isArray(matchHeaders)) {
+      if (!matchSet.has(headerKey)) continue
+    }
+
+    filtered[headerKey] = value
+  }
+
+  return filtered
+}
+
+/**
+ * Filters headers for storage (only excludes sensitive headers)
+ */
+function filterHeadersForStorage (headers, matchOptions = {}) {
+  if (!headers || typeof headers !== 'object') return {}
+
+  const {
+    excludeHeaders = [],
+    caseSensitive = false
+  } = matchOptions
+
+  const filtered = {}
+  const excludeSet = new Set(excludeHeaders.map(h => caseSensitive ? h : h.toLowerCase()))
+
+  for (const [key, value] of Object.entries(headers)) {
+    const headerKey = caseSensitive ? key : key.toLowerCase()
+
+    // Skip if in exclude list (for security)
+    if (excludeSet.has(headerKey)) continue
+
+    filtered[headerKey] = value
+  }
+
+  return filtered
+}
+
+/**
+ * Creates cached header sets for performance
+ */
+function createHeaderSetsCache (matchOptions = {}) {
+  const { ignoreHeaders = [], excludeHeaders = [], matchHeaders = null, caseSensitive = false } = matchOptions
+
+  return {
+    ignoreSet: new Set(ignoreHeaders.map(h => caseSensitive ? h : h.toLowerCase())),
+    excludeSet: new Set(excludeHeaders.map(h => caseSensitive ? h : h.toLowerCase())),
+    matchSet: matchHeaders && Array.isArray(matchHeaders)
+      ? new Set(matchHeaders.map(h => caseSensitive ? h : h.toLowerCase()))
+      : null
+  }
+}
+
+/**
+ * Normalizes headers for consistent comparison
+ */
+function normalizeHeaders (headers) {
+  if (!headers) return {}
+
+  const normalized = {}
+
+  // Handle array format (undici internal format: [name, value, name, value, ...])
+  if (Array.isArray(headers)) {
+    for (let i = 0; i < headers.length; i += 2) {
+      const key = headers[i]
+      const value = headers[i + 1]
+      if (key && value !== undefined) {
+        // Convert Buffers to strings if needed
+        const keyStr = Buffer.isBuffer(key) ? key.toString() : String(key)
+        const valueStr = Buffer.isBuffer(value) ? value.toString() : String(value)
+        normalized[keyStr.toLowerCase()] = valueStr
+      }
+    }
+    return normalized
+  }
+
+  // Handle object format
+  if (headers && typeof headers === 'object') {
+    for (const [key, value] of Object.entries(headers)) {
+      if (key && typeof key === 'string') {
+        normalized[key.toLowerCase()] = Array.isArray(value) ? value.join(', ') : String(value)
+      }
+    }
+  }
+
+  return normalized
+}
+
+/**
+ * Creates a hash key for request matching
+ */
+function createRequestHash (request) {
+  const parts = [
+    request.method,
+    request.url,
+    JSON.stringify(request.headers, Object.keys(request.headers).sort()),
+    request.body || ''
+  ]
+  return Buffer.from(parts.join('|')).toString('base64url')
+}
+
+/**
+ * Checks if a URL matches any of the exclude patterns
+ */
+function isUrlExcluded (url, excludePatterns = []) {
+  if (!excludePatterns.length) return false
+
+  for (const pattern of excludePatterns) {
+    if (typeof pattern === 'string') {
+      // Simple string match (case-insensitive)
+      if (url.toLowerCase().includes(pattern.toLowerCase())) {
+        return true
+      }
+    } else if (pattern instanceof RegExp) {
+      // Regex pattern match
+      if (pattern.test(url)) {
+        return true
+      }
+    }
+  }
+
+  return false
+}
+
+class SnapshotRecorder {
+  constructor (options = {}) {
+    this.snapshots = new Map()
+    this.snapshotPath = options.snapshotPath
+    this.mode = options.mode || 'record'
+    this.loaded = false
+    this.maxSnapshots = options.maxSnapshots || Infinity
+    this.autoFlush = options.autoFlush || false
+    this.flushInterval = options.flushInterval || 30000 // 30 seconds default
+    this._flushTimer = null
+    this._flushTimeout = null
+
+    // Matching configuration
+    this.matchOptions = {
+      matchHeaders: options.matchHeaders || null, // null means match all headers
+      ignoreHeaders: options.ignoreHeaders || [],
+      excludeHeaders: options.excludeHeaders || [],
+      matchBody: options.matchBody !== false, // default: true
+      matchQuery: options.matchQuery !== false, // default: true
+      caseSensitive: options.caseSensitive || false
+    }
+
+    // Cache processed header sets to avoid recreating them on every request
+    this._headerSetsCache = createHeaderSetsCache(this.matchOptions)
+
+    // Request filtering callbacks
+    this.shouldRecord = options.shouldRecord || null // function(requestOpts) -> boolean
+    this.shouldPlayback = options.shouldPlayback || null // function(requestOpts) -> boolean
+
+    // URL pattern filtering
+    this.excludeUrls = options.excludeUrls || [] // Array of regex patterns or strings
+
+    // Start auto-flush timer if enabled
+    if (this.autoFlush && this.snapshotPath) {
+      this._startAutoFlush()
+    }
+  }
+
+  /**
+   * Records a request-response interaction
+   */
+  async record (requestOpts, response) {
+    // Check if recording should be filtered out
+    if (this.shouldRecord && typeof this.shouldRecord === 'function') {
+      if (!this.shouldRecord(requestOpts)) {
+        return // Skip recording
+      }
+    }
+
+    // Check URL exclusion patterns
+    const url = new URL(requestOpts.path, requestOpts.origin).toString()
+    if (isUrlExcluded(url, this.excludeUrls)) {
+      return // Skip recording
+    }
+
+    const request = formatRequestKey(requestOpts, this._headerSetsCache, this.matchOptions)
+    const hash = createRequestHash(request)
+
+    // Extract response data - always store body as base64
+    const normalizedHeaders = normalizeHeaders(response.headers)
+    const responseData = {
+      statusCode: response.statusCode,
+      headers: filterHeadersForStorage(normalizedHeaders, this.matchOptions),
+      body: Buffer.isBuffer(response.body)
+        ? response.body.toString('base64')
+        : Buffer.from(String(response.body || '')).toString('base64'),
+      trailers: response.trailers
+    }
+
+    // Remove oldest snapshot if we exceed maxSnapshots limit
+    if (this.snapshots.size >= this.maxSnapshots && !this.snapshots.has(hash)) {
+      const oldestKey = this.snapshots.keys().next().value
+      this.snapshots.delete(oldestKey)
+    }
+
+    // Support sequential responses - if snapshot exists, add to responses array
+    const existingSnapshot = this.snapshots.get(hash)
+    if (existingSnapshot && existingSnapshot.responses) {
+      existingSnapshot.responses.push(responseData)
+      existingSnapshot.timestamp = new Date().toISOString()
+    } else {
+      this.snapshots.set(hash, {
+        request,
+        responses: [responseData], // Always store as array for consistency
+        callCount: 0,
+        timestamp: new Date().toISOString()
+      })
+    }
+
+    // Auto-flush if enabled
+    if (this.autoFlush && this.snapshotPath) {
+      this._scheduleFlush()
+    }
+  }
+
+  /**
+   * Finds a matching snapshot for the given request
+   * Returns the appropriate response based on call count for sequential responses
+   */
+  findSnapshot (requestOpts) {
+    // Check if playback should be filtered out
+    if (this.shouldPlayback && typeof this.shouldPlayback === 'function') {
+      if (!this.shouldPlayback(requestOpts)) {
+        return undefined // Skip playback
+      }
+    }
+
+    // Check URL exclusion patterns
+    const url = new URL(requestOpts.path, requestOpts.origin).toString()
+    if (isUrlExcluded(url, this.excludeUrls)) {
+      return undefined // Skip playback
+    }
+
+    const request = formatRequestKey(requestOpts, this._headerSetsCache, this.matchOptions)
+    const hash = createRequestHash(request)
+    const snapshot = this.snapshots.get(hash)
+
+    if (!snapshot) return undefined
+
+    // Handle sequential responses
+    if (snapshot.responses && Array.isArray(snapshot.responses)) {
+      const currentCallCount = snapshot.callCount || 0
+      const responseIndex = Math.min(currentCallCount, snapshot.responses.length - 1)
+      snapshot.callCount = currentCallCount + 1
+
+      return {
+        ...snapshot,
+        response: snapshot.responses[responseIndex]
+      }
+    }
+
+    // Legacy format compatibility - convert single response to array format
+    if (snapshot.response && !snapshot.responses) {
+      snapshot.responses = [snapshot.response]
+      snapshot.callCount = 1
+      delete snapshot.response
+
+      return {
+        ...snapshot,
+        response: snapshot.responses[0]
+      }
+    }
+
+    return snapshot
+  }
+
+  /**
+   * Loads snapshots from file
+   */
+  async loadSnapshots (filePath) {
+    const path = filePath || this.snapshotPath
+    if (!path) {
+      throw new InvalidArgumentError('Snapshot path is required')
+    }
+
+    try {
+      const data = await readFile(resolve(path), 'utf8')
+      const parsed = JSON.parse(data)
+
+      // Convert array format back to Map
+      if (Array.isArray(parsed)) {
+        this.snapshots.clear()
+        for (const { hash, snapshot } of parsed) {
+          this.snapshots.set(hash, snapshot)
+        }
+      } else {
+        // Legacy object format
+        this.snapshots = new Map(Object.entries(parsed))
+      }
+
+      this.loaded = true
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        // File doesn't exist yet - that's ok for recording mode
+        this.snapshots.clear()
+        this.loaded = true
+      } else {
+        throw new UndiciError(`Failed to load snapshots from ${path}`, { cause: error })
+      }
+    }
+  }
+
+  /**
+   * Saves snapshots to file
+   */
+  async saveSnapshots (filePath) {
+    const path = filePath || this.snapshotPath
+    if (!path) {
+      throw new InvalidArgumentError('Snapshot path is required')
+    }
+
+    const resolvedPath = resolve(path)
+
+    // Ensure directory exists
+    await mkdir(dirname(resolvedPath), { recursive: true })
+
+    // Convert Map to serializable format
+    const data = Array.from(this.snapshots.entries()).map(([hash, snapshot]) => ({
+      hash,
+      snapshot
+    }))
+
+    await writeFile(resolvedPath, JSON.stringify(data, null, 2), 'utf8', { flush: true })
+  }
+
+  /**
+   * Clears all recorded snapshots
+   */
+  clear () {
+    this.snapshots.clear()
+  }
+
+  /**
+   * Gets all recorded snapshots
+   */
+  getSnapshots () {
+    return Array.from(this.snapshots.values())
+  }
+
+  /**
+   * Gets snapshot count
+   */
+  size () {
+    return this.snapshots.size
+  }
+
+  /**
+   * Resets call counts for all snapshots (useful for test cleanup)
+   */
+  resetCallCounts () {
+    for (const snapshot of this.snapshots.values()) {
+      snapshot.callCount = 0
+    }
+  }
+
+  /**
+   * Deletes a specific snapshot by request options
+   */
+  deleteSnapshot (requestOpts) {
+    const request = formatRequestKey(requestOpts, this._headerSetsCache, this.matchOptions)
+    const hash = createRequestHash(request)
+    return this.snapshots.delete(hash)
+  }
+
+  /**
+   * Gets information about a specific snapshot
+   */
+  getSnapshotInfo (requestOpts) {
+    const request = formatRequestKey(requestOpts, this._headerSetsCache, this.matchOptions)
+    const hash = createRequestHash(request)
+    const snapshot = this.snapshots.get(hash)
+
+    if (!snapshot) return null
+
+    return {
+      hash,
+      request: snapshot.request,
+      responseCount: snapshot.responses ? snapshot.responses.length : (snapshot.response ? 1 : 0),
+      callCount: snapshot.callCount || 0,
+      timestamp: snapshot.timestamp
+    }
+  }
+
+  /**
+   * Replaces all snapshots with new data (full replacement)
+   */
+  replaceSnapshots (snapshotData) {
+    this.snapshots.clear()
+
+    if (Array.isArray(snapshotData)) {
+      for (const { hash, snapshot } of snapshotData) {
+        this.snapshots.set(hash, snapshot)
+      }
+    } else if (snapshotData && typeof snapshotData === 'object') {
+      // Legacy object format
+      this.snapshots = new Map(Object.entries(snapshotData))
+    }
+  }
+
+  /**
+   * Starts the auto-flush timer
+   */
+  _startAutoFlush () {
+    if (!this._flushTimer) {
+      this._flushTimer = setInterval(() => {
+        this.saveSnapshots().catch(() => {
+          // Ignore flush errors - they shouldn't interrupt normal operation
+        })
+      }, this.flushInterval)
+    }
+  }
+
+  /**
+   * Stops the auto-flush timer
+   */
+  _stopAutoFlush () {
+    if (this._flushTimer) {
+      clearInterval(this._flushTimer)
+      this._flushTimer = null
+    }
+  }
+
+  /**
+   * Schedules a flush (debounced to avoid excessive writes)
+   */
+  _scheduleFlush () {
+    // Simple debouncing - clear existing timeout and set new one
+    if (this._flushTimeout) {
+      clearTimeout(this._flushTimeout)
+    }
+    this._flushTimeout = setTimeout(() => {
+      this.saveSnapshots().catch(() => {
+        // Ignore flush errors
+      })
+      this._flushTimeout = null
+    }, 1000) // 1 second debounce
+  }
+
+  /**
+   * Cleanup method to stop timers
+   */
+  destroy () {
+    this._stopAutoFlush()
+    if (this._flushTimeout) {
+      clearTimeout(this._flushTimeout)
+      this._flushTimeout = null
+    }
+  }
+
+  /**
+   * Async close method that saves all recordings and performs cleanup
+   */
+  async close () {
+    // Save any pending recordings if we have a snapshot path
+    if (this.snapshotPath && this.snapshots.size > 0) {
+      await this.saveSnapshots()
+    }
+
+    // Perform cleanup
+    this.destroy()
+  }
+}
+
+module.exports = { SnapshotRecorder, formatRequestKey, createRequestHash, filterHeadersForMatching, filterHeadersForStorage, isUrlExcluded, createHeaderSetsCache }

package/lib/web/fetch/body.js

@@ -10,7 +10,6 @@ const {
 } = require('./util')
 const { FormData, setFormDataState } = require('./formdata')
 const { webidl } = require('../webidl')
-const { Blob } = require('node:buffer')
 const assert = require('node:assert')
 const { isErrored, isDisturbed } = require('node:stream')
 const { isArrayBuffer } = require('node:util/types')

package/lib/web/fetch/formdata-parser.js

@@ -6,9 +6,6 @@ const { HTTP_TOKEN_CODEPOINTS, isomorphicDecode } = require('./data-url')
 const { makeEntry } = require('./formdata')
 const { webidl } = require('../webidl')
 const assert = require('node:assert')
-const { File: NodeFile } = require('node:buffer')
-
-const File = globalThis.File ?? NodeFile
 
 const formDataNameBuffer = Buffer.from('form-data; name="')
 const filenameBuffer = Buffer.from('filename')

package/lib/web/fetch/formdata.js

@@ -3,12 +3,8 @@
 const { iteratorMixin } = require('./util')
 const { kEnumerableProperty } = require('../../core/util')
 const { webidl } = require('../webidl')
-const { File: NativeFile } = require('node:buffer')
 const nodeUtil = require('node:util')
 
-/** @type {globalThis['File']} */
-const File = globalThis.File ?? NativeFile
-
 // https://xhr.spec.whatwg.org/#formdata
 class FormData {
   #state = []

package/lib/web/webidl/index.js

@@ -509,7 +509,7 @@ webidl.is.USVString = function (value) {
 webidl.is.ReadableStream = webidl.util.MakeTypeAssertion(ReadableStream)
 webidl.is.Blob = webidl.util.MakeTypeAssertion(Blob)
 webidl.is.URLSearchParams = webidl.util.MakeTypeAssertion(URLSearchParams)
-webidl.is.File = webidl.util.MakeTypeAssertion(globalThis.File ?? require('node:buffer').File)
+webidl.is.File = webidl.util.MakeTypeAssertion(File)
 webidl.is.URL = webidl.util.MakeTypeAssertion(URL)
 webidl.is.AbortSignal = webidl.util.MakeTypeAssertion(AbortSignal)
 webidl.is.MessagePort = webidl.util.MakeTypeAssertion(MessagePort)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "undici",
-  "version": "7.12.0",
+  "version": "7.13.0",
   "description": "An HTTP/1.1 client, written from scratch for Node.js",
   "homepage": "https://undici.nodejs.org",
   "bugs": {

package/types/agent.d.ts

@@ -22,14 +22,10 @@ declare namespace Agent {
   export interface Options extends Pool.Options {
     /** Default: `(origin, opts) => new Pool(origin, opts)`. */
     factory?(origin: string | URL, opts: Object): Dispatcher;
-    /** Integer. Default: `0` */
-    maxRedirections?: number;
 
     interceptors?: { Agent?: readonly Dispatcher.DispatchInterceptor[] } & Pool.Options['interceptors']
   }
 
   export interface DispatchOptions extends Dispatcher.DispatchOptions {
-    /** Integer. */
-    maxRedirections?: number;
   }
 }

package/types/client.d.ts

@@ -71,8 +71,6 @@ export declare namespace Client {
     /** TODO */
     maxCachedSessions?: number;
     /** TODO */
-    maxRedirections?: number;
-    /** TODO */
     connect?: Partial<buildConnector.BuildOptions> | buildConnector.connector;
     /** TODO */
     maxRequestsPerClient?: number;

package/types/dispatcher.d.ts

@@ -135,8 +135,6 @@ declare namespace Dispatcher {
     signal?: AbortSignal | EventEmitter | null;
     /** This argument parameter is passed through to `ConnectData` */
     opaque?: TOpaque;
-    /** Default: 0 */
-    maxRedirections?: number;
     /** Default: false */
     redirectionLimitReached?: boolean;
     /** Default: `null` */
@@ -147,8 +145,6 @@ declare namespace Dispatcher {
     opaque?: TOpaque;
     /** Default: `null` */
     signal?: AbortSignal | EventEmitter | null;
-    /** Default: 0 */
-    maxRedirections?: number;
     /** Default: false */
     redirectionLimitReached?: boolean;
     /** Default: `null` */
@@ -172,8 +168,6 @@ declare namespace Dispatcher {
     protocol?: string;
     /** Default: `null` */
     signal?: AbortSignal | EventEmitter | null;
-    /** Default: 0 */
-    maxRedirections?: number;
     /** Default: false */
     redirectionLimitReached?: boolean;
     /** Default: `null` */

package/types/h2c-client.d.ts

@@ -51,8 +51,6 @@ export declare namespace H2CClient {
     /** TODO */
     maxCachedSessions?: number;
     /** TODO */
-    maxRedirections?: number;
-    /** TODO */
     connect?: Omit<Partial<buildConnector.BuildOptions>, 'allowH2'> | buildConnector.connector;
     /** TODO */
     maxRequestsPerClient?: number;

package/types/index.d.ts

@@ -13,6 +13,7 @@ import Agent from './agent'
 import MockClient from './mock-client'
 import MockPool from './mock-pool'
 import MockAgent from './mock-agent'
+import { SnapshotAgent } from './snapshot-agent'
 import { MockCallHistory, MockCallHistoryLog } from './mock-call-history'
 import mockErrors from './mock-errors'
 import ProxyAgent from './proxy-agent'
@@ -33,7 +34,7 @@ export * from './content-type'
 export * from './cache'
 export { Interceptable } from './mock-interceptor'
 
-export { Dispatcher, BalancedPool, Pool, Client, buildConnector, errors, Agent, request, stream, pipeline, connect, upgrade, setGlobalDispatcher, getGlobalDispatcher, setGlobalOrigin, getGlobalOrigin, interceptors, MockClient, MockPool, MockAgent, MockCallHistory, MockCallHistoryLog, mockErrors, ProxyAgent, EnvHttpProxyAgent, RedirectHandler, DecoratorHandler, RetryHandler, RetryAgent, H2CClient }
+export { Dispatcher, BalancedPool, Pool, Client, buildConnector, errors, Agent, request, stream, pipeline, connect, upgrade, setGlobalDispatcher, getGlobalDispatcher, setGlobalOrigin, getGlobalOrigin, interceptors, MockClient, MockPool, MockAgent, SnapshotAgent, MockCallHistory, MockCallHistoryLog, mockErrors, ProxyAgent, EnvHttpProxyAgent, RedirectHandler, DecoratorHandler, RetryHandler, RetryAgent, H2CClient }
 export default Undici
 
 declare namespace Undici {
@@ -58,6 +59,7 @@ declare namespace Undici {
   const MockClient: typeof import('./mock-client').default
   const MockPool: typeof import('./mock-pool').default
   const MockAgent: typeof import('./mock-agent').default
+  const SnapshotAgent: typeof import('./snapshot-agent').SnapshotAgent
   const MockCallHistory: typeof import('./mock-call-history').MockCallHistory
   const MockCallHistoryLog: typeof import('./mock-call-history').MockCallHistoryLog
   const mockErrors: typeof import('./mock-errors').default

package/types/mock-interceptor.d.ts

@@ -69,7 +69,6 @@ declare namespace MockInterceptor {
     headers?: Headers | Record<string, string>;
     origin?: string;
     body?: BodyInit | Dispatcher.DispatchOptions['body'] | null;
-    maxRedirections?: number;
   }
 
   export type MockResponseDataHandler<TData extends object = object> = (