File Explorer

1'use strict'2 3const Agent = require('../dispatcher/agent')4const MockAgent = require('./mock-agent')5const { SnapshotRecorder } = require('./snapshot-recorder')6const WrapHandler = require('../handler/wrap-handler')7const { InvalidArgumentError, UndiciError } = require('../core/errors')8const { validateSnapshotMode } = require('./snapshot-utils')9 10const kSnapshotRecorder = Symbol('kSnapshotRecorder')11const kSnapshotMode = Symbol('kSnapshotMode')12const kSnapshotPath = Symbol('kSnapshotPath')13const kSnapshotLoaded = Symbol('kSnapshotLoaded')14const kRealAgent = Symbol('kRealAgent')15 16// Static flag to ensure warning is only emitted once per process17let warningEmitted = false18 19class SnapshotAgent extends MockAgent {20  constructor (opts = {}) {21    // Emit experimental warning only once22    if (!warningEmitted) {23      process.emitWarning(24        'SnapshotAgent is experimental and subject to change',25        'ExperimentalWarning'26      )27      warningEmitted = true28    }29 30    const {31      mode = 'record',32      snapshotPath = null,33      ...mockAgentOpts34    } = opts35 36    super(mockAgentOpts)37 38    validateSnapshotMode(mode)39 40    // Validate snapshotPath is provided when required41    if ((mode === 'playback' || mode === 'update') && !snapshotPath) {42      throw new InvalidArgumentError(`snapshotPath is required when mode is '${mode}'`)43    }44 45    this[kSnapshotMode] = mode46    this[kSnapshotPath] = snapshotPath47 48    this[kSnapshotRecorder] = new SnapshotRecorder({49      snapshotPath: this[kSnapshotPath],50      mode: this[kSnapshotMode],51      maxSnapshots: opts.maxSnapshots,52      autoFlush: opts.autoFlush,53      flushInterval: opts.flushInterval,54      matchHeaders: opts.matchHeaders,55      ignoreHeaders: opts.ignoreHeaders,56      excludeHeaders: opts.excludeHeaders,57      matchBody: opts.matchBody,58      matchQuery: opts.matchQuery,59      caseSensitive: opts.caseSensitive,60      shouldRecord: opts.shouldRecord,61      shouldPlayback: opts.shouldPlayback,62      excludeUrls: opts.excludeUrls63    })64    this[kSnapshotLoaded] = false65 66    // For recording/update mode, we need a real agent to make actual requests67    // For playback mode, we need a real agent if there are excluded URLs68    if (this[kSnapshotMode] === 'record' || this[kSnapshotMode] === 'update' ||69        (this[kSnapshotMode] === 'playback' && opts.excludeUrls && opts.excludeUrls.length > 0)) {70      this[kRealAgent] = new Agent(opts)71    }72 73    // Auto-load snapshots in playback/update mode74    if ((this[kSnapshotMode] === 'playback' || this[kSnapshotMode] === 'update') && this[kSnapshotPath]) {75      this.loadSnapshots().catch(() => {76        // Ignore load errors - file might not exist yet77      })78    }79  }80 81  dispatch (opts, handler) {82    handler = WrapHandler.wrap(handler)83    const mode = this[kSnapshotMode]84 85    // Check if URL should be excluded (pass through without mocking/recording)86    if (this[kSnapshotRecorder].isUrlExcluded(opts)) {87      // Real agent is guaranteed by constructor when excludeUrls is configured88      return this[kRealAgent].dispatch(opts, handler)89    }90 91    if (mode === 'playback' || mode === 'update') {92      // Ensure snapshots are loaded93      if (!this[kSnapshotLoaded]) {94        // Need to load asynchronously, delegate to async version95        return this.#asyncDispatch(opts, handler)96      }97 98      // Try to find existing snapshot (synchronous)99      const snapshot = this[kSnapshotRecorder].findSnapshot(opts)100 101      if (snapshot) {102        // Use recorded response (synchronous)103        return this.#replaySnapshot(snapshot, handler)104      } else if (mode === 'update') {105        // Make real request and record it (async required)106        return this.#recordAndReplay(opts, handler)107      } else {108        // Playback mode but no snapshot found109        const error = new UndiciError(`No snapshot found for ${opts.method || 'GET'} ${opts.path}`)110        if (handler.onError) {111          handler.onError(error)112          return113        }114        throw error115      }116    } else if (mode === 'record') {117      // Record mode - make real request and save response (async required)118      return this.#recordAndReplay(opts, handler)119    }120  }121 122  /**123   * Async version of dispatch for when we need to load snapshots first124   */125  async #asyncDispatch (opts, handler) {126    await this.loadSnapshots()127    return this.dispatch(opts, handler)128  }129 130  /**131   * Records a real request and replays the response132   */133  #recordAndReplay (opts, handler) {134    const responseData = {135      statusCode: null,136      headers: {},137      trailers: {},138      body: []139    }140 141    const self = this // Capture 'this' context for use within nested handler callbacks142 143    const recordingHandler = {144      onRequestStart (controller, context) {145        return handler.onRequestStart(controller, { ...context, history: this.history })146      },147 148      onRequestUpgrade (controller, statusCode, headers, socket) {149        return handler.onRequestUpgrade(controller, statusCode, headers, socket)150      },151 152      onResponseStart (controller, statusCode, headers, statusMessage) {153        responseData.statusCode = statusCode154        responseData.headers = headers155        return handler.onResponseStart(controller, statusCode, headers, statusMessage)156      },157 158      onResponseData (controller, chunk) {159        responseData.body.push(chunk)160        return handler.onResponseData(controller, chunk)161      },162 163      onResponseEnd (controller, trailers) {164        responseData.trailers = trailers165 166        // Record the interaction using captured 'self' context (fire and forget)167        const responseBody = Buffer.concat(responseData.body)168        self[kSnapshotRecorder].record(opts, {169          statusCode: responseData.statusCode,170          headers: responseData.headers,171          body: responseBody,172          trailers: responseData.trailers173        })174          .then(() => handler.onResponseEnd(controller, trailers))175          .catch((error) => handler.onResponseError(controller, error))176      }177    }178 179    // Use composed agent if available (includes interceptors), otherwise use real agent180    const agent = this[kRealAgent]181    return agent.dispatch(opts, recordingHandler)182  }183 184  /**185   * Replays a recorded response186   *187   * @param {Object} snapshot - The recorded snapshot to replay.188   * @param {Object} handler - The handler to call with the response data.189   * @returns {void}190   */191  #replaySnapshot (snapshot, handler) {192    try {193      const { response } = snapshot194 195      const controller = {196        pause () { },197        resume () { },198        abort (reason) {199          this.aborted = true200          this.reason = reason201        },202 203        aborted: false,204        paused: false205      }206 207      handler.onRequestStart(controller)208 209      handler.onResponseStart(controller, response.statusCode, response.headers)210 211      // Body is always stored as base64 string212      const body = Buffer.from(response.body, 'base64')213      handler.onResponseData(controller, body)214 215      handler.onResponseEnd(controller, response.trailers)216    } catch (error) {217      handler.onError?.(error)218    }219  }220 221  /**222   * Loads snapshots from file223   *224   * @param {string} [filePath] - Optional file path to load snapshots from.225   * @returns {Promise<void>} - Resolves when snapshots are loaded.226   */227  async loadSnapshots (filePath) {228    await this[kSnapshotRecorder].loadSnapshots(filePath || this[kSnapshotPath])229    this[kSnapshotLoaded] = true230 231    // In playback mode, set up MockAgent interceptors for all snapshots232    if (this[kSnapshotMode] === 'playback') {233      this.#setupMockInterceptors()234    }235  }236 237  /**238   * Saves snapshots to file239   *240   * @param {string} [filePath] - Optional file path to save snapshots to.241   * @returns {Promise<void>} - Resolves when snapshots are saved.242   */243  async saveSnapshots (filePath) {244    return this[kSnapshotRecorder].saveSnapshots(filePath || this[kSnapshotPath])245  }246 247  /**248   * Sets up MockAgent interceptors based on recorded snapshots.249   *250   * This method creates MockAgent interceptors for each recorded snapshot,251   * allowing the SnapshotAgent to fall back to MockAgent's standard intercept252   * mechanism in playback mode. Each interceptor is configured to persist253   * (remain active for multiple requests) and responds with the recorded254   * response data.255   *256   * Called automatically when loading snapshots in playback mode.257   *258   * @returns {void}259   */260  #setupMockInterceptors () {261    for (const snapshot of this[kSnapshotRecorder].getSnapshots()) {262      const { request, responses, response } = snapshot263      const url = new URL(request.url)264 265      const mockPool = this.get(url.origin)266 267      // Handle both new format (responses array) and legacy format (response object)268      const responseData = responses ? responses[0] : response269      if (!responseData) continue270 271      mockPool.intercept({272        path: url.pathname + url.search,273        method: request.method,274        headers: request.headers,275        body: request.body276      }).reply(responseData.statusCode, responseData.body, {277        headers: responseData.headers,278        trailers: responseData.trailers279      }).persist()280    }281  }282 283  /**284   * Gets the snapshot recorder285   * @return {SnapshotRecorder} - The snapshot recorder instance286   */287  getRecorder () {288    return this[kSnapshotRecorder]289  }290 291  /**292   * Gets the current mode293   * @return {import('./snapshot-utils').SnapshotMode} - The current snapshot mode294   */295  getMode () {296    return this[kSnapshotMode]297  }298 299  /**300   * Clears all snapshots301   * @returns {void}302   */303  clearSnapshots () {304    this[kSnapshotRecorder].clear()305  }306 307  /**308   * Resets call counts for all snapshots (useful for test cleanup)309   * @returns {void}310   */311  resetCallCounts () {312    this[kSnapshotRecorder].resetCallCounts()313  }314 315  /**316   * Deletes a specific snapshot by request options317   * @param {import('./snapshot-recorder').SnapshotRequestOptions} requestOpts - Request options to identify the snapshot318   * @return {Promise<boolean>} - Returns true if the snapshot was deleted, false if not found319   */320  deleteSnapshot (requestOpts) {321    return this[kSnapshotRecorder].deleteSnapshot(requestOpts)322  }323 324  /**325   * Gets information about a specific snapshot326   * @returns {import('./snapshot-recorder').SnapshotInfo|null} - Snapshot information or null if not found327   */328  getSnapshotInfo (requestOpts) {329    return this[kSnapshotRecorder].getSnapshotInfo(requestOpts)330  }331 332  /**333   * Replaces all snapshots with new data (full replacement)334   * @param {Array<{hash: string; snapshot: import('./snapshot-recorder').SnapshotEntryshotEntry}>|Record<string, import('./snapshot-recorder').SnapshotEntry>} snapshotData - New snapshot data to replace existing snapshots335   * @returns {void}336   */337  replaceSnapshots (snapshotData) {338    this[kSnapshotRecorder].replaceSnapshots(snapshotData)339  }340 341  /**342   * Closes the agent, saving snapshots and cleaning up resources.343   *344   * @returns {Promise<void>}345   */346  async close () {347    await this[kSnapshotRecorder].close()348    await this[kRealAgent]?.close()349    await super.close()350  }351}352 353module.exports = SnapshotAgent354