debugger: wait for target startup

lib/internal/debugger/inspect_helpers.js

@@ -1,11 +1,20 @@
 'use strict';
 
 const {
+  ArrayPrototypePop,
+  ArrayPrototypePush,
   ArrayPrototypePushApply,
+  MapPrototypeGet,
   Number,
   Promise,
+  PromiseWithResolvers,
   RegExpPrototypeExec,
+  RegExpPrototypeSymbolReplace,
+  SafePromiseRace,
   StringPrototypeEndsWith,
+  StringPrototypeIndexOf,
+  StringPrototypeSlice,
+  StringPrototypeStartsWith,
 } = primordials;
 
 const { spawn } = require('child_process');
@@ -18,12 +27,24 @@ const {
   AbortController,
 } = require('internal/abort_controller');
 
-const { ERR_DEBUGGER_STARTUP_ERROR } = require('internal/errors').codes;
+const {
+  ERR_DEBUGGER_ERROR,
+  ERR_DEBUGGER_STARTUP_ERROR,
+} = require('internal/errors').codes;
 const {
   exitCodes: {
     kInvalidCommandLineArgument,
   },
 } = internalBinding('errors');
+const {
+  types: {
+    kBoolean,
+    kNoOp,
+    kV8Option,
+  },
+} = internalBinding('options');
+
+const { getCLIOptionsInfo } = require('internal/options');
 
 const debugRegex = /Debugger listening on ws:\/\/\[?(.+?)\]?:(\d+)\//;
 
@@ -61,6 +82,176 @@ function ensureTrailingNewline(text) {
   return StringPrototypeEndsWith(text, '\n') ? text : `${text}\n`;
 }
 
+// Mirror OptionsParser::Parse() far enough to find the child script. Options
+// before it must not undo the inspector setup added by launchChildProcess().
+function validateChildArgs(childArgs) {
+  const { options, aliases } = getCLIOptionsInfo();
+  const syntheticArgs = [];
+  let breakFirstLine = true;
+  let childArgIndex = 0;
+  let inspectorEnabled = true;
+
+  function peekArg() {
+    return syntheticArgs.length > 0 ?
+      syntheticArgs[syntheticArgs.length - 1] :
+      childArgs[childArgIndex];
+  }
+
+  function shiftArg() {
+    return syntheticArgs.length > 0 ?
+      ArrayPrototypePop(syntheticArgs) :
+      childArgs[childArgIndex++];
+  }
+
+  while (true) {
+    const nextArg = peekArg();
+    if (nextArg === undefined || nextArg.length <= 1 || nextArg[0] !== '-') {
+      break;
+    }
+
+    const isSynthetic = syntheticArgs.length > 0;
+    const arg = shiftArg();
+    if (arg === '--') { break; }
+    if (!isSynthetic &&
+        (arg === '--experimental-config-file' ||
+         arg === '--experimental-default-config-file')) {
+      // ConfigReader rewrites these to an inline default path before parsing.
+      continue;
+    }
+    if (!isSynthetic &&
+        StringPrototypeStartsWith(
+          arg, '--experimental-default-config-file=')) {
+      // ConfigReader rejects this form before parsing the remaining options.
+      return;
+    }
+
+    const equalsIndex = arg[1] === '-' ? StringPrototypeIndexOf(arg, '=') : -1;
+    let name = equalsIndex === -1 ? arg : StringPrototypeSlice(arg, 0, equalsIndex);
+    if (name.length > 2) {
+      name = `${StringPrototypeSlice(name, 0, 2)}${
+        RegExpPrototypeSymbolReplace(/_/g, StringPrototypeSlice(name, 2), '-')}`;
+    }
+
+    let isNegation = false;
+    if (StringPrototypeStartsWith(name, '--no-')) {
+      name = `--${StringPrototypeSlice(name, 5)}`;
+      isNegation = true;
+    }
+
+    while (true) {
+      let expansion = MapPrototypeGet(aliases, name);
+      if (expansion === undefined && equalsIndex !== -1) {
+        expansion = MapPrototypeGet(aliases, `${name}=`);
+      }
+      const aliasArg = peekArg();
+      if (expansion === undefined &&
+          aliasArg !== undefined &&
+          aliasArg.length > 0 &&
+          aliasArg[0] !== '-') {
+        expansion = MapPrototypeGet(aliases, `${name} <arg>`);
+      }
+      if (expansion === undefined) { break; }
+
+      const previousName = name;
+      // process.allowedNodeEnvironmentFlags may remove a self-recursive
+      // first entry from the cached alias metadata. Preserve the native
+      // parser's synthetic option terminator in that case.
+      if (expansion[0] === '--') {
+        for (let i = expansion.length - 1; i >= 0; i--) {
+          ArrayPrototypePush(syntheticArgs, expansion[i]);
+        }
+        break;
+      }
+      name = expansion[0];
+      for (let i = expansion.length - 1; i > 0; i--) {
+        ArrayPrototypePush(syntheticArgs, expansion[i]);
+      }
+      if (name === previousName) { break; }
+    }
+
+    const info = MapPrototypeGet(options, name);
+    if (info === undefined) { continue; }
+    if (isNegation && info.type !== kBoolean && info.type !== kV8Option) {
+      return;
+    }
+    if (info.type === kBoolean || info.type === kNoOp || info.type === kV8Option) {
+      if (name === '--inspect') {
+        inspectorEnabled = !isNegation;
+      } else if (name === '--inspect-brk') {
+        breakFirstLine = !isNegation;
+        if (!isNegation) { inspectorEnabled = true; }
+      } else if (!isNegation &&
+                 (name === '--inspect-wait' ||
+                  name === '--inspect-brk-node')) {
+        inspectorEnabled = true;
+      }
+      continue;
+    }
+
+    if (equalsIndex !== -1) {
+      if (equalsIndex === arg.length - 1) { return; }
+      continue;
+    }
+
+    const value = peekArg();
+    if (value === undefined || (value.length > 0 && value[0] === '-')) {
+      return;
+    }
+    shiftArg();
+  }
+
+  if (!inspectorEnabled) {
+    throw new ERR_DEBUGGER_STARTUP_ERROR(
+      '--no-inspect is incompatible with node inspect before the child script');
+  }
+  if (!breakFirstLine) {
+    throw new ERR_DEBUGGER_STARTUP_ERROR(
+      '--no-inspect-brk is incompatible with node inspect before the child script');
+  }
+}
+
+async function waitForDebugger(
+  client,
+  callMethod = (method) => client.callMethod(method),
+) {
+  const {
+    promise: waitingPromise,
+    resolve: resolveWaiting,
+  } = PromiseWithResolvers();
+  const {
+    promise: closedPromise,
+    reject: rejectClosed,
+  } = PromiseWithResolvers();
+  const onWaiting = () => resolveWaiting();
+  const onClose = () => {
+    rejectClosed(new ERR_DEBUGGER_ERROR(
+      'Debugger session ended while waiting for target startup'));
+  };
+
+  // The inspector can accept a connection before the target reaches its
+  // startup wait. Enabling NodeRuntime makes that state observable whether
+  // the target was already waiting or starts waiting later.
+  client.once('NodeRuntime.waitingForDebugger', onWaiting);
+  client.once('close', onClose);
+  try {
+    await SafePromiseRace([
+      callMethod('NodeRuntime.enable'),
+      closedPromise,
+    ]);
+    await SafePromiseRace([
+      waitingPromise,
+      closedPromise,
+    ]);
+    await SafePromiseRace([
+      callMethod('NodeRuntime.disable'),
+      closedPromise,
+    ]);
+  } finally {
+    client.removeListener('NodeRuntime.waitingForDebugger', onWaiting);
+    client.removeListener('close', onClose);
+  }
+}
+
 function writeInspectUsageAndExit(invokedAs, message, exitCode) {
   const code = exitCode ?? (message ? kInvalidCommandLineArgument : 0);
   const out = code === 0 ? process.stdout : process.stderr;
@@ -141,6 +332,8 @@ probe output schema.
 
 async function launchChildProcess(childArgs, inspectHost, inspectPort,
                                   childOutput, options = { __proto__: null }) {
+  validateChildArgs(childArgs);
+
   if (!options.skipPortPreflight) {
     await portIsFree(inspectHost, inspectPort);
   }
@@ -189,5 +382,6 @@ async function launchChildProcess(childArgs, inspectHost, inspectPort,
 module.exports = {
   ensureTrailingNewline,
   launchChildProcess,
+  waitForDebugger,
   writeInspectUsageAndExit,
 };

lib/internal/debugger/inspect_probe.js

@@ -33,6 +33,7 @@ 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;
@@ -1044,6 +1045,17 @@ class ProbeInspectorSession {
       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();

lib/internal/debugger/inspect_repl.js

@@ -60,6 +60,7 @@ const { fileURLToPath } = require('internal/url');
 const { customInspectSymbol, SideEffectFreeRegExpPrototypeSymbolReplace } = require('internal/util');
 const { inspect: utilInspect } = require('internal/util/inspect');
 const { isObjectLiteral } = require('internal/repl/utils');
+const { waitForDebugger } = require('internal/debugger/inspect_helpers');
 const debuglog = require('internal/util/debuglog').debuglog('inspect');
 
 const SHORTCUTS = {
@@ -1204,9 +1205,13 @@ function createRepl(inspector) {
   }
 
   async function initAfterStart() {
+    const waitForDebuggerOnStart = !!inspector.options?.script;
     waitForInitialBreakRender =
-      !!inspector.options?.script &&
+      waitForDebuggerOnStart &&
       process.env.NODE_INSPECT_RESUME_ON_START !== '1';
+    if (waitForDebuggerOnStart) {
+      await waitForDebugger(inspector.client);
+    }
     await Runtime.enable();
     await Profiler.enable();
     await Profiler.setSamplingInterval({ interval: 100 });