node/lib/internal/debugger/inspect_probe.js

'use strict';

const {
  ArrayFrom,
  ArrayIsArray,
  ArrayPrototypeJoin,
  ArrayPrototypeMap,
  ArrayPrototypePush,
  ArrayPrototypeSlice,
  ArrayPrototypeSome,
  FunctionPrototypeBind,
  JSONStringify,
  NumberIsNaN,
  NumberParseInt,
  ObjectEntries,
  PromiseWithResolvers,
  RegExpPrototypeExec,
  RegExpPrototypeSymbolSplit,
  SafeMap,
  SafeSet,
  StringPrototypeIncludes,
  StringPrototypeSlice,
  StringPrototypeStartsWith,
  StringPrototypeTrim,
  Symbol,
} = primordials;

const { clearTimeout, setTimeout } = require('timers');
const { SideEffectFreeRegExpPrototypeSymbolReplace } = require('internal/util');
const debug = require('internal/util/debuglog').debuglog('inspect_probe');

const InspectClient = require('internal/debugger/inspect_client');
const {
  ensureTrailingNewline,
  launchChildProcess,
  waitForDebugger,
} = require('internal/debugger/inspect_helpers');

const { ERR_DEBUGGER_STARTUP_ERROR } = require('internal/errors').codes;
const {
  exitCodes: {
    kGenericUserError,
    kNoFailure,
  },
} = internalBinding('errors');

const kProbeDefaultTimeout = 30000;
const kProbeVersion = 2;
const kProbeDisconnectSentinel = 'Waiting for the debugger to disconnect...';
const kProbeAttachedSentinel = 'Debugger attached.';
const kProbeListeningPrefix = 'Debugger listening on ws://';
const kProbeEndingPrefix = 'Debugger ending on ws://';
const kProbeHelpLine =
  'For help, see: https://nodejs.org/learn/getting-started/debugging';
// Thrown by `callCdp` after `recordInspectorFailure` has handled the failure,
// so callers can short-circuit without recording duplicate events.
const kInspectorFailedSentinel = Symbol('probe.inspectorFailed');
const kStartupTeardownAdvice =
  'The target startup may have torn down the inspector. If startup does ' +
  'not touch the inspector, this is likely a Node.js bug. Please file an issue.';
const kReviewProbeExprAdvice = 'If the failure repeats, review the probe expression.';
const kDigitsRegex = /^\d+$/;
const kInspectPortRegex = /^--inspect-port=(\d+)$/;

/**
 * The probe request specified by --probe, serialized into the public report.
 * @typedef {object} ProbeTarget
 * @property {string} suffix The raw suffix supplied by the user.
 * @property {number} line 1-based line number.
 * @property {number} [column] 1-based column number.
 */

/**
 * Location where the probe was evaluated, serialized into the public report.
 * @typedef {object} Location
 * @property {string} [url] V8-reported script URL, if known.
 * @property {number} line 1-based line number.
 * @property {number} column 1-based column number.
 */

/**
 * Per-breakpoint state keyed by V8 `breakpointId` from `Debugger.setBreakpointByUrl`.
 * @typedef {object} BreakpointDefinition
 * @property {number[]} probeIndices Indices into probes that bound to this breakpoint.
 */

/**
 * Per-probe state corresponds to each --probe --expr pair.
 * @typedef {object} Probe
 * @property {string} expr Expression to evaluate on hit.
 * @property {ProbeTarget} target User's original --probe request shape.
 * @property {string} [condition] Condition from --cond. V8 only breaks when it is truthy.
 *   Scoped to the location, so probes sharing a location all carry the same value.
 * @property {number} maxHit Per-probe hit limit from --max-hit. Infinity when unlimited.
 * @property {number} hits Count of hits observed.
 */

function probeReachedLimit(probe) {
  return probe.hits >= probe.maxHit;
}

function parseUnsignedInteger(value, name, allowZero = false) {
  if (typeof value !== 'string' || RegExpPrototypeExec(kDigitsRegex, value) === null) {
    throw new ERR_DEBUGGER_STARTUP_ERROR(`Invalid ${name}: ${value}`);
  }
  const parsed = NumberParseInt(value, 10);
  if (NumberIsNaN(parsed) || (!allowZero && parsed < 1)) {
    throw new ERR_DEBUGGER_STARTUP_ERROR(`Invalid ${name}: ${value}`);
  }
  return parsed;
}

/**
 * @param {string} text Raw `--probe` argument.
 * @returns {ProbeTarget}
 */
function parseProbeTarget(text) {
  // Accepts file:line or file:line:column formats.
  // Non-greedy (.+?) allows Windows drive-letter paths like C:\foo.js:10.
  const match = RegExpPrototypeExec(/^(.+?):(\d+)(?::(\d+))?$/, text);
  if (match === null) {
    throw new ERR_DEBUGGER_STARTUP_ERROR(`Invalid probe location: ${text}`);
  }

  const suffix = match[1];
  const line = parseUnsignedInteger(match[2], 'probe location');
  // Column is left as undefined if the user does not supply one.
  const column = match[3] !== undefined ? parseUnsignedInteger(match[3], 'probe location') : undefined;
  return { suffix, line, column };
}

function formatTargetText(target) {
  const { suffix, line, column } = target;
  return column === undefined ? `${suffix}:${line}` : `${suffix}:${line}:${column}`;
}

// Identity of a probe location. Probes sharing a key share one V8 breakpoint,
// so this must stay in sync between condition validation and breakpoint setup.
function locationKey(target) {
  return `${target.suffix}\n${target.line}\n${target.column ?? ''}`;
}

function formatPendingProbeLocations(probes, pending) {
  const seen = new SafeSet();
  for (const probeIndex of pending) {
    seen.add(formatTargetText(probes[probeIndex].target));
  }
  return ArrayPrototypeJoin(ArrayFrom(seen), ', ');
}

// Trim inspector-side noise lines from stderr for reporting child errors.
function trimProbeChildStderr(stderr) {
  const lines = RegExpPrototypeSymbolSplit(/\r\n|\r|\n/g, stderr);
  const kept = [];
  for (let i = 0; i < lines.length; i++) {
    const line = lines[i];
    if (line === '' && i === lines.length - 1) { continue; }
    if (line === kProbeDisconnectSentinel) { continue; }
    if (line === kProbeAttachedSentinel) { continue; }
    if (line === kProbeHelpLine) { continue; }
    if (StringPrototypeStartsWith(line, kProbeListeningPrefix)) { continue; }
    if (StringPrototypeStartsWith(line, kProbeEndingPrefix)) { continue; }
    ArrayPrototypePush(kept, line);
  }
  return ArrayPrototypeJoin(kept, '\n');
}

function formatPreviewPropertyValue(property) {
  if (property.type === 'string') {
    return JSONStringify(property.value ?? '');
  }
  return property.value ?? property.type;
}

function trimRemoteObject(result) {
  if (result === undefined || result === null || typeof result !== 'object') {
    return result;
  }

  if (ArrayIsArray(result)) {
    return ArrayPrototypeMap(result, trimRemoteObject);
  }

  const trimmed = { __proto__: null };
  for (const { 0: key, 1: value } of ObjectEntries(result)) {
    if (key === 'objectId' || key === 'className') {
      continue;
    }
    trimmed[key] = trimRemoteObject(value);
  }
  return trimmed;
}

function stripProbePreviews(value) {
  if (value === undefined || value === null || typeof value !== 'object') {
    return value;
  }

  if (ArrayIsArray(value)) {
    return ArrayPrototypeMap(value, stripProbePreviews);
  }

  const stripped = { __proto__: null };
  for (const { 0: key, 1: entry } of ObjectEntries(value)) {
    if (key === 'preview') {
      continue;
    }
    stripped[key] = stripProbePreviews(entry);
  }
  return stripped;
}

// Format CDP RemoteObject values into more readable formats.
function formatRemoteObject(result) {
  if (result === undefined) { return 'undefined'; }

  switch (result.type) {
    case 'undefined':
      return 'undefined';
    case 'string':
      return JSONStringify(result.value);
    case 'number':
      if (result.unserializableValue !== undefined) {
        return result.unserializableValue;
      }
      return `${result.value}`;
    case 'boolean':
      return `${result.value}`;
    case 'symbol':
      return result.description || 'Symbol()';
    case 'bigint':
      return result.unserializableValue ?? result.description ?? '0n';
    case 'function':
      return result.description || 'function()';
    case 'object':
      if (result.subtype === 'null') {
        return 'null';
      }
      if (result.subtype === 'error') {
        return result.description || 'Error';
      }
      if (result.preview !== undefined) {
        const properties = ArrayPrototypeJoin(ArrayPrototypeMap(
          result.preview.properties,
          result.preview.subtype === 'array' ?
            (property) => formatPreviewPropertyValue(property) :
            (property) => `${property.name}: ${formatPreviewPropertyValue(property)}`,
        ), ', ');
        const suffix = result.preview.overflow ? ', ...' : '';
        if (result.preview.subtype === 'array') {
          return `[${properties}${suffix}]`;
        }
        return `{${properties}${suffix}}`;
      }
      return result.description || result.className || 'Object';
    default:
      return `${result.value ?? result.description ?? ''}`;
  }
}

function formatHitLocation(location) {
  return `${location.url}:${location.line}:${location.column}`;
}

// Built human-readable text output for probe reports.
function buildProbeTextReport(report) {
  const lines = [];

  for (const result of report.results) {
    if (result.event === 'hit') {
      const probe = report.probes[result.probe];
      // If Debugger.scriptParsed was missed and the URL is unknown, fall back to the user's
      // probe target text for readability. This is unlikely unless there's a bug in V8.
      const locText = (result.location.url !== undefined) ?
        formatHitLocation(result.location) : formatTargetText(probe.target);
      ArrayPrototypePush(lines, `Hit ${result.hit} at ${locText}`);
      if (result.error !== undefined) {
        ArrayPrototypePush(lines, `  [error] ${probe.expr} = ${result.error.message}`);
      } else {
        ArrayPrototypePush(lines,
                           `  ${probe.expr} = ` +
                           `${formatRemoteObject(result.result)}`);
      }
      continue;
    }

    if (result.event === 'completed') {
      ArrayPrototypePush(lines, 'Completed');
      continue;
    }

    if (result.event === 'miss') {
      ArrayPrototypePush(lines,
                         `Missed probes: ` +
                         `${formatPendingProbeLocations(report.probes, result.pending)}`);
      continue;
    }

    if (result.event === 'timeout') {
      ArrayPrototypePush(lines, result.error.message);
      continue;
    }

    if (result.event === 'error') {
      ArrayPrototypePush(lines, result.error.message);
      if (result.error.stderr !== undefined) {
        ArrayPrototypePush(lines, '  [stderr]');
        const stderrLines = RegExpPrototypeSymbolSplit(
          /\r\n|\r|\n/g,
          result.error.stderr,
        );
        for (let i = 0; i < stderrLines.length; i++) {
          if (stderrLines[i] === '' && i === stderrLines.length - 1) {
            continue;
          }
          ArrayPrototypePush(lines, `  ${stderrLines[i]}`);
        }
      }
    }
  }

  return ensureTrailingNewline(ArrayPrototypeJoin(lines, '\n'));
}

function parseProbeTokens(tokens, args) {
  let port = 0;
  let preview = false;
  let timeout = kProbeDefaultTimeout;
  let json = false;
  let sawSeparator = false;
  let childStartIndex = args.length;
  let pendingTarget;
  let expectedExprIndex = -1;
  const probes = [];

  for (const token of tokens) {
    if (token.kind === 'option-terminator') {
      sawSeparator = true;
      childStartIndex = token.index + 1;
      break;
    }

    if (pendingTarget !== undefined) {
      if (token.kind === 'option' &&
          token.name === 'expr' &&
          token.index === expectedExprIndex &&
          token.value !== undefined) {
        ArrayPrototypePush(probes, {
          expr: token.value,
          target: pendingTarget,
        });
        pendingTarget = undefined;
        continue;
      }

      throw new ERR_DEBUGGER_STARTUP_ERROR(
        'Each --probe must be followed immediately by --expr <expr>');
    }

    if (token.kind === 'positional') {
      childStartIndex = token.index;
      break;
    }

    switch (token.name) {
      case 'json':
        json = true;
        break;
      case 'timeout':
        if (token.value === undefined) {
          throw new ERR_DEBUGGER_STARTUP_ERROR(`Missing value for ${token.rawName}`);
        }
        timeout = parseUnsignedInteger(token.value, 'timeout', true);
        break;
      case 'port':
        if (token.value === undefined) {
          throw new ERR_DEBUGGER_STARTUP_ERROR(`Missing value for ${token.rawName}`);
        }
        port = parseUnsignedInteger(token.value, 'inspector port', true);
        break;
      case 'preview':
        preview = true;
        break;
      case 'probe':
        pendingTarget = parseProbeTarget(token.value);
        expectedExprIndex = token.index + (token.inlineValue ? 1 : 2);
        break;
      case 'expr':
        throw new ERR_DEBUGGER_STARTUP_ERROR('Unexpected --expr before --probe');
      case 'max-hit': {
        if (probes.length === 0) {
          throw new ERR_DEBUGGER_STARTUP_ERROR('Unexpected --max-hit before --probe');
        }
        if (token.value === undefined) {
          throw new ERR_DEBUGGER_STARTUP_ERROR(`Missing value for ${token.rawName}`);
        }
        const probe = probes[probes.length - 1];
        if (probe.maxHit !== undefined) {
          throw new ERR_DEBUGGER_STARTUP_ERROR('Duplicate --max-hit for a single --probe');
        }
        probe.maxHit = parseUnsignedInteger(token.value, 'max-hit');
        break;
      }
      case 'cond': {
        if (probes.length === 0) {
          throw new ERR_DEBUGGER_STARTUP_ERROR('Unexpected --cond before --probe');
        }
        // A blank condition does not act as a real predicate in V8 (an empty
        // string always breaks), so reject it rather than silently mislead.
        if (token.value === undefined || StringPrototypeTrim(token.value) === '') {
          throw new ERR_DEBUGGER_STARTUP_ERROR(`Missing value for ${token.rawName}`);
        }
        const probe = probes[probes.length - 1];
        if (probe.condition !== undefined) {
          throw new ERR_DEBUGGER_STARTUP_ERROR('A --probe can have at most one --cond');
        }
        probe.condition = token.value;
        break;
      }
      default:
        if (probes.length > 0) {
          throw new ERR_DEBUGGER_STARTUP_ERROR(
            'Use -- before child Node.js flags in probe mode');
        }
        throw new ERR_DEBUGGER_STARTUP_ERROR(`Unknown probe option: ${token.rawName}`);
    }
  }

  if (pendingTarget !== undefined) {
    throw new ERR_DEBUGGER_STARTUP_ERROR(
      'Each --probe must be followed immediately by --expr <expr>');
  }

  if (probes.length === 0) {
    throw new ERR_DEBUGGER_STARTUP_ERROR(
      'Probe mode requires at least one --probe <loc> --expr <expr> group');
  }

  // V8 allows only one breakpoint per location, so probes sharing a location
  // cannot carry different conditions.
  const conditionByLocation = new SafeMap();
  for (const { target, condition } of probes) {
    const key = locationKey(target);
    // All probes at the same location must share one condition. We split the
    // existence check since if one probe does not have a condition (= undefined),
    // then all probes at the location must also omit it.
    if (conditionByLocation.has(key)) {
      if (conditionByLocation.get(key) !== condition) {
        throw new ERR_DEBUGGER_STARTUP_ERROR(
          `Probes at ${formatTargetText(target)} must use the same --cond (or none)`);
      }
    } else {
      conditionByLocation.set(key, condition);
    }
  }

  const childArgv = ArrayPrototypeSlice(args, childStartIndex);
  if (childArgv.length === 0) {
    throw new ERR_DEBUGGER_STARTUP_ERROR('Probe mode requires a child script');
  }

  if (!sawSeparator && StringPrototypeStartsWith(childArgv[0], '-')) {
    throw new ERR_DEBUGGER_STARTUP_ERROR('Use -- before child Node.js flags in probe mode');
  }

  let skipPortPreflight = port === 0;
  for (const arg of childArgv) {
    const inspectPortMatch = RegExpPrototypeExec(kInspectPortRegex, arg);
    if (inspectPortMatch === null) {
      continue;
    }
    if (inspectPortMatch[1] === '0') {
      skipPortPreflight = true;
      continue;
    }
    throw new ERR_DEBUGGER_STARTUP_ERROR(
      'Only child --inspect-port=0 is supported in probe mode');
  }

  return {
    host: '127.0.0.1',
    port,
    preview,
    timeout,
    json,
    probes,
    childArgv,
    skipPortPreflight,
  };
}

class ProbeInspectorSession {
  constructor(options) {
    this.options = options;
    this.client = new InspectClient();
    this.child = null;
    this.cleanupStarted = false;
    this.childStderr = '';
    this.disconnectRequested = false;
    this.finished = false;
    // True once the inspector WebSocket connects. Event handlers ignore
    // pre-connect exits/closes so launch/connect failures report through run().
    this.connected = false;
    // True once breakpoints are bound and the target is released from --inspect-brk
    // via `Runtime.runIfWaitingForDebugger`.
    // Distinguishes "exited before user code ran" from "exited during the live session".
    this.started = false;
    // A sliding buffer of at most kProbeDisconnectSentinel.length to detect disconnect.
    this.disconnectSentinelBuffer = '';
    /** @type {Map<string, BreakpointDefinition>} keyed by V8 breakpointId. */
    this.breakpointDefinitions = new SafeMap();
    /** @type {Map<string, string>} scriptId -> URL. */
    this.scriptIdToUrl = new SafeMap();
    this.results = [];
    this.timeout = null;
    // The currently-awaited CDP request, or null when no request is in flight.
    /** @type {{ method: string, probe: { index: number, location: Location } | null } | null} */
    this.inFlight = null;
    // Most recently completed probe, used for `error.probe` when a non-evaluate CDP call rejects.
    this.lastProbeIndex = null;
    const { promise, resolve } = PromiseWithResolvers();
    this.completionPromise = promise;
    this.resolveCompletion = resolve;
    /** @type {Probe[]} */
    this.probes = ArrayPrototypeMap(options.probes,
                                    ({ expr, target, maxHit, condition }) =>
                                      ({ expr, target, condition, maxHit: maxHit ?? Infinity, hits: 0 }));
    this.onChildOutput = FunctionPrototypeBind(this.onChildOutput, this);
    this.onChildExit = FunctionPrototypeBind(this.onChildExit, this);
    this.onClientClose = FunctionPrototypeBind(this.onClientClose, this);
    this.onPaused = FunctionPrototypeBind(this.onPaused, this);
    this.onScriptParsed = FunctionPrototypeBind(this.onScriptParsed, this);
  }

  // Marking the probing process to exit with 0, recorded hits are trustworthy.
  finishWithTrustedResult(terminal) {
    this.finish(kNoFailure, terminal);
  }

  // Marking the probing process to exit with 1, recorded hits are best-effort.
  finishWithUnreliableResult(terminal) {
    this.finish(kGenericUserError, terminal);
  }

  finish(exitCode, terminal) {
    if (this.finished) { return; }
    debug('finish: exitCode=%d, terminal=%s', exitCode, terminal?.event);
    this.finished = true;
    if (this.timeout !== null) {
      clearTimeout(this.timeout);
      this.timeout = null;
    }
    this.resolveCompletion({ exitCode, terminal });
  }

  getProbeTargetExitEvent(exitCode, signal) {
    const pending = this.getPendingProbeIndices();
    const how = signal !== null ? `with signal ${signal}` : `with code ${exitCode}`;
    const status = pending.length === 0 ?
      'target completion' : `probes: ${formatPendingProbeLocations(this.probes, pending)}`;
    const error = {
      __proto__: null,
      code: 'probe_target_exit',
      message: `Target exited ${how} before ${status}`,
    };
    if (exitCode !== null) { error.exitCode = exitCode; }
    if (signal !== null) { error.signal = signal; }
    error.stderr = trimProbeChildStderr(this.childStderr);
    return { event: 'error', pending, error };
  }

  onChildOutput(text, which) {
    if (which !== 'stderr') { return; }
    debug('child stderr: %j', text);

    this.childStderr += text;

    const combined = this.disconnectSentinelBuffer + text;
    // Detect the disconnect sentinel.
    if (this.connected &&
        StringPrototypeIncludes(combined, kProbeDisconnectSentinel)) {
      debug('disconnect sentinel detected, resetting client');
      this.disconnectRequested = true;
      this.client.reset();
    }

    if (combined.length > kProbeDisconnectSentinel.length) {  // Slide the buffer.
      this.disconnectSentinelBuffer = StringPrototypeSlice(combined,
                                                           combined.length - kProbeDisconnectSentinel.length);
    } else {
      this.disconnectSentinelBuffer = combined;
    }
  }

  onChildExit(code, signal) {
    debug('child exit: code=%s signal=%s connected=%s started=%s finished=%s inFlight=%j',
          code, signal, this.connected, this.started, this.finished, this.inFlight);
    // Pre-connect exits are deliberately silent: the target never reached
    // a state where probes could be set, so any report would be empty.
    if (!this.connected) { return; }
    if (this.finished) { return; }
    if (this.inFlight !== null && this.inFlight.probe !== null) {
      this.recordInspectorFailure({
        reason: 'Target process exited during probe evaluation',
        advice: kReviewProbeExprAdvice,
      });
      return;
    }
    if (this.started && code === 0 && signal === null) {
      const pending = this.getPendingProbeIndices();
      this.finishWithTrustedResult(pending.length === 0 ? { event: 'completed' } : { event: 'miss', pending });
      return;
    }
    this.finishWithTrustedResult(this.getProbeTargetExitEvent(code, signal));
  }

  onClientClose() {
    debug('client close: disconnectRequested=%s finished=%s inFlight=%j',
          this.disconnectRequested, this.finished, this.inFlight);
    if (!this.connected) { return; }
    if (this.disconnectRequested) { return; }
    if (this.finished) { return; }

    if (this.child.exitCode !== null || this.child.signalCode !== null) {
      this.onChildExit(this.child.exitCode, this.child.signalCode);
      return;
    }
    if (!this.started) {
      this.recordInspectorFailure({
        reason: 'Inspector connection lost before probes started',
        advice: kStartupTeardownAdvice,
      });
      return;
    }
    if (this.inFlight !== null) {
      if (this.inFlight.probe !== null || this.lastProbeIndex !== null) {
        this.recordInspectorFailure({
          reason: 'Inspector connection lost during probe activity',
          advice: 'A probe expression may have caused the disconnection. ' +
            'If the failure repeats, review the probe expressions.',
        });
      } else {
        this.recordInspectorFailure({
          reason: 'Inspector connection lost during inspector activity',
          advice: 'This is likely a Node.js bug. Please file an issue.',
        });
      }
      return;
    }
    this.recordInspectorFailure({
      reason: 'Inspector connection lost',
      advice: 'The target was likely terminated externally. If the failure ' +
        'persists, check the target\'s process environment.',
    });
  }

  onPaused(params) {
    debug('paused: finished=%d, reason=%s hitBreakpoints=%j', this.finished, params.reason, params.hitBreakpoints);
    this.handlePaused(params).catch((error) => {
      if (error === kInspectorFailedSentinel) { return; }
      this.recordInspectorFailure({
        reason: 'Probe mode encountered an unexpected internal failure',
        advice: 'This is likely a Node.js bug. Please file an issue.',
        internalError: error,
      });
    });
  }

  async handlePaused(params) {
    if (this.finished) { return; }
    // Ignore pauses that arrive before breakpoint setup is complete. Once
    // startup is marked complete, `Runtime.runIfWaitingForDebugger` may surface
    // the initial --inspect-brk pause, which the normal resume path handles.
    if (!this.started) { return; }

    const hitBreakpoints = params.hitBreakpoints;
    if (hitBreakpoints === undefined || hitBreakpoints.length === 0) {
      await this.resume();
      return;
    }

    const topFrame = params.callFrames?.[0];
    const callFrameId = topFrame?.callFrameId;
    if (callFrameId === undefined) {
      await this.resume();
      return;
    }

    const { scriptId, lineNumber, columnNumber } = topFrame.location;
    // `Debugger.scriptParsed` should always precede a pause for the same script.
    // It should only be undefined if there's a bug (even in that case, just omit it).
    const location = {
      url: this.scriptIdToUrl.get(scriptId),
      // CDP locations are 0-based, locations in public report are 1-based.
      line: lineNumber + 1,
      column: columnNumber + 1,
    };
    for (const breakpointId of hitBreakpoints) {
      // The breakpoint ID is stable even for scripts parsed after the initial resolution
      // so we can count on it here.
      const definition = this.breakpointDefinitions.get(breakpointId);
      if (definition === undefined) { continue; }

      // Evaluate the expressions in the order they appear on the command line.
      for (const probeIndex of definition.probeIndices) {
        await this.evaluateProbe(callFrameId, probeIndex, location);
        if (this.finished) { break; }
      }
    }

    // Finish proactively as soon as any probe reaches its hit limit. All probes
    // hit in this pause are recorded first, then the session ends.
    // TODO(joyeecheung): When we implement attach mode, this teardown must
    // resume-and-detach rather than kill, since the target is not ours.
    if (!this.finished && ArrayPrototypeSome(this.probes, probeReachedLimit)) {
      this.finishWithTrustedResult({ event: 'completed' });
      return;
    }

    await this.resume();
  }

  async evaluateProbe(callFrameId, probeIndex, location) {
    if (this.finished) { return; }
    const probe = this.probes[probeIndex];
    const evaluation = await this.callCdp(
      'Debugger.evaluateOnCallFrame',
      { callFrameId, expression: probe.expr, generatePreview: true },
      { __proto__: null, index: probeIndex, location },
    );
    this.lastProbeIndex = probeIndex;

    probe.hits++;
    const result = { probe: probeIndex, event: 'hit', hit: probe.hits, location };
    if (evaluation.exceptionDetails !== undefined) {
      result.error = {
        __proto__: null,
        message: evaluation.result?.description ?? 'Probe expression failed',
        details: { __proto__: null, exception: trimRemoteObject(evaluation.exceptionDetails) },
      };
    } else {
      result.result = trimRemoteObject(evaluation.result);
    }
    ArrayPrototypePush(this.results, result);
  }

  async resume() {
    if (this.finished) { return; }
    await this.callCdp('Debugger.resume');
  }

  async callCdp(method, params, probe = null) {
    if (this.finished) { throw kInspectorFailedSentinel; }
    const request = { __proto__: null, method, probe };
    this.inFlight = request;
    debug('CDP -> %s%s', method, probe !== null ? `, probe=${probe.index}` : '');
    try {
      const result = await this.client.callMethod(method, params);
      // A timeout or process exit can finish the report while the CDP request
      // is still outstanding. Ignore the late reply in that case.
      if (this.finished) {
        debug('CDP <- %s discarded (already finished)', method);
        throw kInspectorFailedSentinel;
      }
      debug('CDP <- %s (success)', method);
      return result;
    } catch (err) {
      if (err !== kInspectorFailedSentinel) {  // Already handled.
        debug('CDP <- %s error: %s', method, err?.code);
      }
      if (this.disconnectRequested) {
        // Only the in-flight evaluation gets attribution. Other rejections
        // under disconnect are downstream noise.
        if (probe !== null) {
          this.recordInspectorFailure({
            reason: 'Target process exited during probe evaluation',
            advice: kReviewProbeExprAdvice,
          });
        }
        throw kInspectorFailedSentinel;
      }
      // Another event handler already recorded the terminal event.
      if (this.finished) { throw kInspectorFailedSentinel; }
      if (!this.started) {
        this.recordInspectorFailure({
          reason: 'Probe mode failed before user code ran',
          advice: kStartupTeardownAdvice,
          cdpError: err,
        });
      } else if (method === 'Debugger.evaluateOnCallFrame') {
        this.recordInspectorFailure({
          reason: 'The inspector could not evaluate a probe expression',
          advice: `The rejection details are recorded on the probe hit. ${kReviewProbeExprAdvice}`,
          cdpError: err,
        });
      } else if (this.lastProbeIndex !== null) {
        this.recordInspectorFailure({
          reason: 'Probe session failed after a probe evaluation',
          advice: 'If the failure repeats, review the most-recently-evaluated probe expression.',
          cdpError: err,
        });
      } else {
        this.recordInspectorFailure({
          reason: 'Probe session failed during inspector activity',
          advice: 'This is likely a Node.js bug. Please file an issue.',
          cdpError: err,
        });
      }
      throw kInspectorFailedSentinel;
    } finally {
      if (this.inFlight === request) {
        this.inFlight = null;
      }
    }
  }

  // Records the first inspector-side terminal for the session, later callers are ignored.
  recordInspectorFailure({ reason, advice, cdpError, internalError }) {
    if (this.finished) { return; }
    debug('recordInspectorFailure "%s": inFlight=%j, lastProbeIndex=%s, cdpError=%j',
          reason, this.inFlight, this.lastProbeIndex, cdpError);
    const child = this.child;
    const exitedAbnormally = child !== null &&
      (child.signalCode !== null || (child.exitCode !== null && child.exitCode !== 0));
    const inFlightProbe = this.inFlight === null ? null : this.inFlight.probe;
    // This normally emits `probe_failure`, but yields to `probe_target_exit` when the child
    // has already exited abnormally and there is no in-flight probe to attribute to.
    if (exitedAbnormally && inFlightProbe === null) {
      this.finishWithTrustedResult(this.getProbeTargetExitEvent(child.exitCode, child.signalCode));
      return;
    }

    const failedCdpMethod = this.inFlight === null ? null : this.inFlight.method;
    let protocolError = null;
    // // `ERR_DEBUGGER_ERROR` is a Node-internal code, not a CDP-level protocol code
    if (cdpError !== undefined && cdpError.code !== 'ERR_DEBUGGER_ERROR') {
      protocolError = { __proto__: null, message: cdpError.message, code: cdpError.code };
    }
    const protocolErrorGoesOnHit = (protocolError !== null) && (failedCdpMethod === 'Debugger.evaluateOnCallFrame');

    let attribution = null;
    if (inFlightProbe !== null) {
      const { index, location } = inFlightProbe;
      const error = { __proto__: null };
      if (protocolErrorGoesOnHit) {
        error.message = 'Probe evaluation failed at the protocol layer';
        error.details = { __proto__: null, protocolError };
      } else {
        error.message = 'Probe evaluation did not complete';
      }
      this.probes[index].hits++;
      ArrayPrototypePush(this.results, {
        probe: index, event: 'hit', hit: this.probes[index].hits, location, error,
      });
      attribution = index;
    } else if (failedCdpMethod !== null && this.lastProbeIndex !== null) {
      attribution = this.lastProbeIndex;
    }
    // When there is no in-flight CDP call (e.g. `onClientClose` after all probes hit), ignore
    // `lastProbeIndex` since it can't be attributed to a specific probe.

    const pending = this.getPendingProbeIndices();
    const suffix = pending.length === 0 ?
      '' : ` before probes: ${formatPendingProbeLocations(this.probes, pending)}`;
    const error = {
      __proto__: null,
      code: 'probe_failure',
      message: `${reason}${suffix}. ${advice}`,
    };
    if (attribution !== null) { error.probe = attribution; }
    error.stderr = trimProbeChildStderr(this.childStderr);

    let details;
    if (failedCdpMethod !== null) {
      details = { __proto__: null, lastCdpMethod: failedCdpMethod };
      if (protocolError !== null && !protocolErrorGoesOnHit) { details.protocolError = protocolError; }
    }
    if (internalError !== undefined) {
      details ??= { __proto__: null };
      details.internalError = { __proto__: null, message: internalError?.message, stack: internalError?.stack };
    }
    if (details !== undefined) { error.details = details; }

    this.finishWithUnreliableResult({ event: 'error', pending, error });
  }

  startTimeout() {
    this.timeout = setTimeout(() => {
      debug('timeout fired: finished=%s, inFlight=%j, lastProbeIndex=%s',
            this.finished, this.inFlight, this.lastProbeIndex);
      if (this.finished) { return; }
      if (this.inFlight !== null) {
        const hasProbeAttribution =
          this.inFlight.probe !== null || this.lastProbeIndex !== null;
        this.recordInspectorFailure({
          reason: 'Probe session timed out',
          advice: hasProbeAttribution ?
            ('The probe expression may be slow, hanging, or interfering with the inspector connection. ' +
            'Try increasing `--timeout`; if the failure persists, review the probe expressions.') :
            'Try increasing `--timeout`; if the failure persists, please file an issue.',
        });
        return;
      }
      const pending = this.getPendingProbeIndices();
      const message = `Timed out after ${this.options.timeout}ms waiting for ` +
        (pending.length === 0 ? 'target completion' :
          `probes: ${formatPendingProbeLocations(this.probes, pending)}`);
      this.finishWithUnreliableResult({
        event: 'timeout',
        pending,
        error: { code: 'probe_timeout', message },
      });
    }, this.options.timeout);
    this.timeout.unref();
  }

  attachListeners() {
    this.child.on('exit', this.onChildExit);
    this.client.on('close', this.onClientClose);
    this.client.on('Debugger.paused', this.onPaused);
    this.client.on('Debugger.scriptParsed', this.onScriptParsed);
  }

  onScriptParsed(params) {
    if (params.url && !StringPrototypeStartsWith(params.url, 'node:')) {
      debug('scriptParsed: scriptId=%s url=%s, length=%d', params.scriptId, params.url, params.length);
    }
    // This map grows by the number of scripts parsed, which is limited, and is just a
    // small string -> string map. The lifetime is bounded by probe timeout etc. so cleanup is overkill.
    this.scriptIdToUrl.set(params.scriptId, params.url);
  }

  async bindBreakpoints() {
    const uniqueTargets = new SafeMap();

    for (let probeIndex = 0; probeIndex < this.probes.length; probeIndex++) {
      const { target, condition } = this.probes[probeIndex];
      // Probes at the same location share one V8 breakpoint. parseProbeTokens has
      // already ensured they carry the same condition.
      const key = locationKey(target);
      let entry = uniqueTargets.get(key);
      if (entry === undefined) {
        entry = { target, condition, probeIndices: [] };
        uniqueTargets.set(key, entry);
      }
      ArrayPrototypePush(entry.probeIndices, probeIndex);
    }

    for (const { target, condition, probeIndices } of uniqueTargets.values()) {
      // On Windows, normalize backslashes to forward slashes so the regex matches
      // V8 script URLs which always use forward slashes.
      const normalizedFile = process.platform === 'win32' ?
        SideEffectFreeRegExpPrototypeSymbolReplace(/\\/g, target.suffix, '/') :
        target.suffix;
      const escapedPath = SideEffectFreeRegExpPrototypeSymbolReplace(
        /([/\\.?*()^${}|[\]])/g,
        normalizedFile,
        '\\$1',
      );
      const params = {
        urlRegex: `^(.*[\\/\\\\])?${escapedPath}$`,
        // CDP locations are 0-based, the probe target from CLI is 1-based.
        lineNumber: target.line - 1,
      };
      if (target.column !== undefined) {
        // Only pass columnNumber to CDP when the user specifies one, otherwise let
        // the inspector bind to the first executable column.
        params.columnNumber = target.column - 1;
      }
      if (condition !== undefined) {
        params.condition = condition;
      }

      const result = await this.callCdp('Debugger.setBreakpointByUrl', params);
      debug('breakpoint set: id=%s urlRegex=%s locations=%j',
            result.breakpointId, params.urlRegex, result.locations);
      this.breakpointDefinitions.set(result.breakpointId, { probeIndices });
    }
  }

  getPendingProbeIndices() {
    const pending = [];
    for (let probeIndex = 0; probeIndex < this.probes.length; probeIndex++) {
      if (this.probes[probeIndex].hits === 0) {
        ArrayPrototypePush(pending, probeIndex);
      }
    }
    return pending;
  }

  buildReport({ exitCode, terminal }) {
    const results = ArrayPrototypeSlice(this.results);
    ArrayPrototypePush(results, terminal);
    return {
      code: exitCode,
      report: {
        v: kProbeVersion,
        probes: ArrayPrototypeMap(this.probes, ({ expr, target, maxHit, condition }) => {
          const probe = { expr, target };
          if (condition !== undefined) { probe.condition = condition; }
          // Omit an unlimited maxHit, as Infinity would serialize to null in JSON.
          if (maxHit !== Infinity) { probe.maxHit = maxHit; }
          return probe;
        }),
        results,
      },
    };
  }

  async cleanup() {
    if (this.cleanupStarted) { return; }
    this.cleanupStarted = true;

    if (this.timeout !== null) {
      clearTimeout(this.timeout);
      this.timeout = null;
    }

    this.client.reset();

    if (this.child === null) { return; }

    // TODO(joyeecheung): When we implement attach mode, this teardown must
    // resume-and-detach rather than kill, since the target is not ours.
    if (this.child.exitCode === null && this.child.signalCode === null) {
      this.child.kill();
    }
  }

  async run() {
    try {
      const { childArgv, host, port, skipPortPreflight } = this.options;
      const { 0: child, 1: actualPort, 2: actualHost } =
        await launchChildProcess(childArgv,
                                 host,
                                 port,
                                 this.onChildOutput,
                                 { skipPortPreflight });
      this.child = child;
      // On Debugger.enable, V8 emits Debugger.scriptParsed for all existing scripts.
      // Attach the listener early to make sure we don't miss any events.
      this.attachListeners();

      await this.client.connect(actualPort, actualHost);
      this.connected = true;

      try {
        try {
          await waitForDebugger(
            this.client,
            (method) => this.callCdp(method),
          );
        } catch (err) {
          // A close event may have completed the structured report while the
          // readiness helper was rejecting its disconnect race.
          if (this.finished) { throw kInspectorFailedSentinel; }
          throw err;
        }
        await this.callCdp('Runtime.enable');
        await this.callCdp('Debugger.enable');
        await this.bindBreakpoints();
        this.started = true;
        this.startTimeout();
        await this.callCdp('Runtime.runIfWaitingForDebugger');
      } catch (err) {
        if (err !== kInspectorFailedSentinel) { throw err; }
      }

      const state = await this.completionPromise;
      return this.buildReport(state);
    } finally {
      await this.cleanup();
    }
  }
}

async function runProbeMode(stdout, probeOptions) {
  try {
    const session = new ProbeInspectorSession(probeOptions);
    const { code, report } = await session.run();
    stdout.write(probeOptions.json ?
      `${JSONStringify(probeOptions.preview ? report : stripProbePreviews(report))}\n` :
      buildProbeTextReport(report));
    process.exit(code);
  } catch (error) {
    if (error.childStderr) {
      process.stderr.write(error.childStderr);
    }
    process.stderr.write(ensureTrailingNewline(error.message));
    process.exit(kGenericUserError);
  }
}

module.exports = {
  parseProbeTokens,
  ProbeInspectorSession,
  runProbeMode,
};