inspector: add inspector.waitForDebugger()

This method blocks current node process until a client sends
Runtime.runifWaitingForDebugger.
It can be useful when we need to report inspector.url() before
waiting for connection:
```
inspector.open(0, undefined, false);
fs.writeFileSync(someFileName, inspector.url());
inspector.waitForDebugger();
```
PR-URL: #28453
Reviewed-By: Eugene Ostroukhov <eostroukhov@google.com>
Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Rich Trott <rtrott@gmail.com>

Author: alexkozy

doc/api/errors.md

@@ -1186,6 +1186,11 @@ after the session had already closed.
 
 An error occurred while issuing a command via the `inspector` module.
 
+<aid="ERR_INSPECTOR_NOT_ACTIVE"></a>
+### ERR_INSPECTOR_NOT_ACTIVE
+
+The `inspector` is not active when `inspector.waitForDebugger()` is called.
+
 <aid="ERR_INSPECTOR_NOT_AVAILABLE"></a>
 ### ERR_INSPECTOR_NOT_AVAILABLE
 

doc/api/inspector.md

@@ -52,6 +52,16 @@ parameter usage.
 
 Return the URL of the active inspector, or `undefined` if there is none.
 
+## inspector.waitForDebugger()
+<!-- YAML
+added: REPLACEME
+-->
+
+Blocks until a client (existing or connected later) has sent
+`Runtime.runIfWaitingForDebugger` command.
+
+An exception will be thrown if there is no active inspector.
+
 ## Class: inspector.Session
 
 The `inspector.Session` is used for dispatching messages to the V8 inspector

lib/inspector.js

@@ -8,6 +8,7 @@ const {
 ERR_INSPECTOR_COMMAND,
 ERR_INSPECTOR_NOT_AVAILABLE,
 ERR_INSPECTOR_NOT_CONNECTED,
+ERR_INSPECTOR_NOT_ACTIVE,
 ERR_INVALID_ARG_TYPE,
 ERR_INVALID_CALLBACK
 }=require('internal/errors').codes;
@@ -19,7 +20,12 @@ if (!hasInspector)
 constEventEmitter=require('events');
 const{ validateString }=require('internal/validators');
 constutil=require('util');
-const{ Connection, open, url }=internalBinding('inspector');
+const{
+ Connection,
+ open,
+ url,
+ waitForDebugger
+}=internalBinding('inspector');
 
 constconnectionSymbol=Symbol('connectionProperty');
 constmessageCallbacksSymbol=Symbol('messageCallbacks');
@@ -105,10 +111,22 @@ class Session extends EventEmitter {
 }
 }
 
+functioninspectorOpen(port,host,wait){
+open(port,host);
+if(wait)
+waitForDebugger();
+}
+
+functioninspectorWaitForDebugger(){
+if(!waitForDebugger())
+thrownewERR_INSPECTOR_NOT_ACTIVE();
+}
+
 module.exports={
-open: (port,host,wait)=>open(port,host,!!wait),
+open: inspectorOpen,
 close: process._debugEnd,
 url: url,
+waitForDebugger: inspectorWaitForDebugger,
 // This is dynamically added during bootstrap,
 // where the console from the VM is still available
 console: require('internal/util/inspector').consoleFromVM,

lib/internal/errors.js

@@ -882,6 +882,7 @@ E('ERR_INPUT_TYPE_NOT_ALLOWED', '--input-type can only be used with string ' +
 E('ERR_INSPECTOR_ALREADY_CONNECTED','%s is already connected',Error);
 E('ERR_INSPECTOR_CLOSED','Session was closed',Error);
 E('ERR_INSPECTOR_COMMAND','Inspector error %d: %s',Error);
+E('ERR_INSPECTOR_NOT_ACTIVE','Inspector is not active',Error);
 E('ERR_INSPECTOR_NOT_AVAILABLE','Inspector is not available',Error);
 E('ERR_INSPECTOR_NOT_CONNECTED','Session is not connected',Error);
 E('ERR_INTERNAL_ASSERTION',(message)=>{

src/inspector_js_api.cc

@@ -237,7 +237,6 @@ void IsEnabled(const FunctionCallbackInfo<Value>& args) {
 voidOpen(const FunctionCallbackInfo<Value>& args) {
  Environment* env = Environment::GetCurrent(args);
  Agent* agent = env->inspector_agent();
-bool wait_for_connect = false;
 
 if (args.Length() > 0 && args[0]->IsUint32()) {
 uint32_t port = args[0].As<Uint32>()->Value();
@@ -249,12 +248,15 @@ void Open(const FunctionCallbackInfo<Value>& args) {
  agent->host_port()->set_host(*host);
  }
 
-if (args.Length() > 2 && args[2]->IsBoolean()) {
- wait_for_connect = args[2]->BooleanValue(args.GetIsolate());
- }
  agent->StartIoThread();
-if (wait_for_connect)
+}
+
+voidWaitForDebugger(const FunctionCallbackInfo<Value>& args) {
+ Environment* env = Environment::GetCurrent(args);
+ Agent* agent = env->inspector_agent();
+if (agent->IsActive())
  agent->WaitForConnect();
+ args.GetReturnValue().Set(agent->IsActive());
 }
 
 voidUrl(const FunctionCallbackInfo<Value>& args) {
@@ -285,6 +287,7 @@ void Initialize(Local<Object> target, Local<Value> unused,
  env->SetMethod(target, "callAndPauseOnStart", CallAndPauseOnStart);
  env->SetMethod(target, "open", Open);
  env->SetMethodNoSideEffect(target, "url", Url);
+ env->SetMethod(target, "waitForDebugger", WaitForDebugger);
 
  env->SetMethod(target, "asyncTaskScheduled", AsyncTaskScheduledWrapper);
  env->SetMethod(target, "asyncTaskCanceled",

test/parallel/test-inspector-wait-for-connection.js

@@ -0,0 +1,63 @@
+// Flags: --expose-internals
+
+'use strict';
+constcommon=require('../common');
+
+common.skipIfInspectorDisabled();
+
+constassert=require('assert');
+const{ NodeInstance }=require('../common/inspector-helper.js');
+
+asyncfunctionrunTests(){
+constchild=newNodeInstance(['-e',`(${main.toString()})()`],'','');
+constsession=awaitchild.connectInspectorSession();
+awaitsession.send({method: 'Runtime.enable'});
+// Check that there is only one console message received.
+awaitsession.waitForConsoleOutput('log','before wait for debugger');
+assert.ok(!session.unprocessedNotifications()
+.some((n)=>n.method==='Runtime.consoleAPICalled'));
+// Check that inspector.url() is available between inspector.open() and
+// inspector.waitForDebugger()
+const{result: { value }}=awaitsession.send({
+method: 'Runtime.evaluate',
+params: {
+expression: 'process._ws',
+includeCommandLineAPI: true
+}
+});
+assert.ok(value.startsWith('ws://'));
+session.send({method: 'Runtime.runIfWaitingForDebugger'});
+// Check that messages after first and before second waitForDebugger are
+// received
+awaitsession.waitForConsoleOutput('log','after wait for debugger');
+awaitsession.waitForConsoleOutput('log','before second wait for debugger');
+assert.ok(!session.unprocessedNotifications()
+.some((n)=>n.method==='Runtime.consoleAPICalled'));
+constsecondSession=awaitchild.connectInspectorSession();
+// Check that inspector.waitForDebugger can be resumed from another session
+secondSession.send({method: 'Runtime.runIfWaitingForDebugger'});
+awaitsession.waitForConsoleOutput('log','after second wait for debugger');
+assert.ok(!session.unprocessedNotifications()
+.some((n)=>n.method==='Runtime.consoleAPICalled'));
+secondSession.disconnect();
+session.disconnect();
+
+functionmain(prefix){
+constinspector=require('inspector');
+inspector.open(0,undefined,false);
+process._ws=inspector.url();
+console.log('before wait for debugger');
+inspector.waitForDebugger();
+console.log('after wait for debugger');
+console.log('before second wait for debugger');
+inspector.waitForDebugger();
+console.log('after second wait for debugger');
+}
+
+// Check that inspector.waitForDebugger throws if there is no active
+// inspector
+constre=/^Error\[ERR_INSPECTOR_NOT_ACTIVE\]:Inspectorisnotactive$/;
+assert.throws(()=>require('inspector').waitForDebugger(),re);
+}
+
+runTests();