inspector: JavaScript bindings for the inspector

PR-URL: #12263
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Sam Roberts <vieuxtech@gmail.com>
Reviewed-By: Timothy Gu <timothygu99@gmail.com>
Reviewed-By: Josh Gavant <josh.gavant@outlook.com>
Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl>

doc/api/_toc.md

@@ -24,6 +24,7 @@
 * [Globals](globals.html)
 * [HTTP](http.html)
 * [HTTPS](https.html)
+* [Inspector](inspector.html)
 * [Modules](modules.html)
 * [Net](net.html)
 * [OS](os.html)

doc/api/all.md

@@ -18,6 +18,7 @@
 @include globals
 @include http
 @include https
+@include inspector
 @include modules
 @include net
 @include os

doc/api/inspector.md

@@ -0,0 +1,114 @@
+# Inspector
+
+> Stability: 1 - Experimental
+
+The `inspector` module provides an API for interacting with the V8 inspector.
+
+It can be accessed using:
+
+```js
+const inspector = require('inspector');
+```
+
+## Class: inspector.Session
+
+The `inspector.Session` is used for dispatching messages to the V8 inspector
+back-end and receiving message responses and notifications.
+
+### Constructor: new inspector.Session()
+<!-- YAML
+added: REPLACEME
+-->
+
+Create a new instance of the `inspector.Session` class. The inspector session
+needs to be connected through [`session.connect()`][] before the messages
+can be dispatched to the inspector backend.
+
+`inspector.Session` is an [`EventEmitter`][] with the following events:
+
+### Event: 'inspectorNotification'
+<!-- YAML
+added: REPLACEME
+-->
+
+* {Object} The notification message object
+
+Emitted when any notification from the V8 Inspector is received.
+
+```js
+session.on('inspectorNotification', (message) => console.log(message.method));
+// Debugger.paused
+// Debugger.resumed
+```
+
+It is also possible to subscribe only to notifications with specific method:
+
+### Event: &lt;inspector-protocol-method&gt;
+<!-- YAML
+added: REPLACEME
+-->
+
+* {Object} The notification message object
+
+Emitted when an inspector notification is received that has its method field set
+to the `<inspector-protocol-method>` value.
+
+The following snippet installs a listener on the [`Debugger.paused`][]
+event, and prints the reason for program suspension whenever program
+execution is suspended (through breakpoints, for example):
+
+```js
+session.on('Debugger.paused', ({params}) => console.log(params.hitBreakpoints));
+// [ '/node/test/inspector/test-bindings.js:11:0' ]
+```
+
+### session.connect()
+<!-- YAML
+added: REPLACEME
+-->
+
+Connects a session to the inspector back-end. An exception will be thrown
+if there is already a connected session established either through the API or by
+a front-end connected to the Inspector WebSocket port.
+
+### session.post(method[, params][, callback])
+<!-- YAML
+added: REPLACEME
+-->
+
+* method {string}
+* params {Object}
+* callback {Function}
+
+Posts a message to the inspector back-end. `callback` will be notified when
+a response is received. `callback` is a function that accepts two optional
+arguments - error and message-specific result.
+
+```js
+session.post('Runtime.evaluate', {'expression': '2 + 2'},
+             (error, {result}) => console.log(result.value));
+// Output: { type: 'number', value: 4, description: '4' }
+```
+
+The latest version of the V8 inspector protocol is published on the
+[Chrome DevTools Protocol Viewer][].
+
+Node inspector supports all the Chrome DevTools Protocol domains declared
+by V8. Chrome DevTools Protocol domain provides an interface for interacting
+with one of the runtime agents used to inspect the application state and listen
+to the run-time events.
+
+### session.disconnect()
+<!-- YAML
+added: REPLACEME
+-->
+
+Immediately close the session. All pending message callbacks will be called
+with an error. [`session.connect()`] will need to be called to be able to send
+messages again. Reconnected session will lose all inspector state, such as
+enabled agents or configured breakpoints.
+
+[`session.connect()`]: #sessionconnect
+[`Debugger.paused`]: https://chromedevtools.github.io/devtools-protocol/v8/Debugger/#event-paused
+[`EventEmitter`]: events.html#events_class_eventemitter
+[Chrome DevTools Protocol Viewer]: https://chromedevtools.github.io/devtools-protocol/v8/

lib/inspector.js

@@ -0,0 +1,87 @@
+'use strict';
+
+const connect = process.binding('inspector').connect;
+const EventEmitter = require('events');
+const util = require('util');
+
+if (!connect)
+  throw new Error('Inspector is not available');
+
+const connectionSymbol = Symbol('connectionProperty');
+const messageCallbacksSymbol = Symbol('messageCallbacks');
+const nextIdSymbol = Symbol('nextId');
+const onMessageSymbol = Symbol('onMessage');
+
+class Session extends EventEmitter {
+  constructor() {
+    super();
+    this[connectionSymbol] = null;
+    this[nextIdSymbol] = 1;
+    this[messageCallbacksSymbol] = new Map();
+  }
+
+  connect() {
+    if (this[connectionSymbol])
+      throw new Error('Already connected');
+    this[connectionSymbol] =
+        connect((message) => this[onMessageSymbol](message));
+  }
+
+  [onMessageSymbol](message) {
+    const parsed = JSON.parse(message);
+    if (parsed.id) {
+      const callback = this[messageCallbacksSymbol].get(parsed.id);
+      this[messageCallbacksSymbol].delete(parsed.id);
+      if (callback)
+        callback(parsed.error || null, parsed.result || null);
+    } else {
+      this.emit(parsed.method, parsed);
+      this.emit('inspectorNotification', parsed);
+    }
+  }
+
+  post(method, params, callback) {
+    if (typeof method !== 'string')
+      throw new TypeError(
+          `"method" must be a string, got ${typeof method} instead`);
+    if (!callback && util.isFunction(params)) {
+      callback = params;
+      params = null;
+    }
+    if (params && typeof params !== 'object')
+      throw new TypeError(
+          `"params" must be an object, got ${typeof params} instead`);
+    if (callback && typeof callback !== 'function')
+      throw new TypeError(
+          `"callback" must be a function, got ${typeof callback} instead`);
+
+    if (!this[connectionSymbol])
+      throw new Error('Session is not connected');
+    const id = this[nextIdSymbol]++;
+    const message = {id, method};
+    if (params) {
+      message['params'] = params;
+    }
+    if (callback) {
+      this[messageCallbacksSymbol].set(id, callback);
+    }
+    this[connectionSymbol].dispatch(JSON.stringify(message));
+  }
+
+  disconnect() {
+    if (!this[connectionSymbol])
+      return;
+    this[connectionSymbol].disconnect();
+    this[connectionSymbol] = null;
+    const remainingCallbacks = this[messageCallbacksSymbol].values();
+    for (const callback of remainingCallbacks) {
+      process.nextTick(callback, new Error('Session was closed'));
+    }
+    this[messageCallbacksSymbol].clear();
+    this[nextIdSymbol] = 1;
+  }
+}
+
+module.exports = {
+  Session
+};

node.gyp

@@ -43,6 +43,7 @@
       'lib/_http_outgoing.js',
       'lib/_http_server.js',
       'lib/https.js',
+      'lib/inspector.js',
       'lib/module.js',
       'lib/net.js',
       'lib/os.js',