Add some closureised JS bindings for DevTools for use by headless embedder

headless/lib/browser/devtools_api/devtools_connection.js

Index: headless/lib/browser/devtools_api/devtools_connection.js
diff --git a/headless/lib/browser/devtools_api/devtools_connection.js b/headless/lib/browser/devtools_api/devtools_connection.js
new file mode 100644
index 0000000000000000000000000000000000000000..ee1e19de2ed5c7f207e3f726223f068759e2c16c
--- /dev/null
+++ b/headless/lib/browser/devtools_api/devtools_connection.js
@@ -0,0 +1,155 @@
+// Copyright 2017 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+/**
+ * @fileoverview Contains a class which marshals DevTools protocol messages over
+ * a provided low level message transport. This transport might be a headless
+ * TabSocket, or a WebSocket or a mock for testing.
+ */
+
+'use strict';
+
+goog.provide('chromium.DevTools.Connection');
+
+/**
+ * @typedef {function(Object): undefined|function(string): undefined}
+ *
+ */
+chromium.DevTools.CallbackFunction;
+
+/**
+ * @class Handles sending and receiving DevTools JSON protocol messages over the
+ *   provided low level message transport.
+ * @param {!Object} transport The API providing transport for devtools commands.
+ * @constructor
+ */
+chromium.DevTools.Connection = function(transport) {
+  /** @private {!Object} */
+  this.transport_ = transport;
+
+  /** @private {number} */
+  this.commandId_ = 1;
+
+  /**
+   * An object containing pending DevTools protocol commands keyed by id.
+   *
+   * @private {!Map<number, !chromium.DevTools.CallbackFunction>}
+   */
+  this.pendingCommands_ = new Map();
+
+  /** @private {number} */
+  this.nextListenerId_ = 1;
+
+  /**
+   * An object containing DevTools protocol events we are listening for keyed by
+   * name.
+   *
+   * @private {!Map<string, !Map<number, !chromium.DevTools.CallbackFunction>>}
+   */
+  this.eventListeners_ = new Map();
+
+  /**
+   * Used for removing event listeners by id.
+   *
+   * @private {!Map<number, string>}
+   */
+  this.eventListenerIdToEventName_ = new Map();
+
+  this.transport_.onmessage = this.onMessage_.bind(this);
+};
+
+
+/**
+ * Listens for DevTools protocol events of the specified name and issues the
+ * callback upon reception.
+ *
+ * @param {string} eventName Name of the DevTools protocol event to listen for.
+ * @param {!chromium.DevTools.CallbackFunction} listener The callback issued
+ *   when we receive a DevTools protocol event corresponding to the given name.
+ * @return {number} The id of this event listener.
+ */
+chromium.DevTools.Connection.prototype.addEventListener = function(
+    eventName, listener) {
+  if (!this.eventListeners_.has(eventName)) {
+    this.eventListeners_.set(eventName, new Map());
+  }
+  let id = this.nextListenerId_++;
+  this.eventListeners_.get(eventName).set(id, listener);
+  this.eventListenerIdToEventName_.set(id, eventName);
+  return id;
+};
+
+
+/**
+ * Removes an event listener previously added by <code>addEventListener</code>.
+ *
+ * @param {number} id The id of the event listener to remove.
+ * @returbn {boolean} Returns true if the event listener was actually removed.

[dpapad, 2017/06/07 17:49:23]

s/returnbn/return
s/Returns true if/Whether

[alex clarke (OOO till 29th), 2017/06/08 10:33:15]

Done.

+ */
+chromium.DevTools.Connection.prototype.removeEventListener = function(id) {
+  if (!this.eventListenerIdToEventName_.has(id)) return false;
+  let eventName = this.eventListenerIdToEventName_.get(id);

[dpapad, 2017/06/07 17:49:23]

Nit (optional): You are using ES6 (aka ES2015) 'let' here, but the rest of this
file is using old style prototype to define the Connection class. Have you
considered using a proper ES6 class definition instead?

FYI, we have an ES6 guide for Chromium JS code at
https://chromium.googlesource.com/chromium/src/+/master/docs/es6_chromium.md#...,
and I am planning to propose moving more features in the "Allowed list" very
soon (probably today).

[alex clarke (OOO till 29th), 2017/06/08 10:33:15]

It sounds like you're OK with ES6 stuff :)  ES6style  code does look much more
readable so lets go with that.

+  this.eventListenerIdToEventName_.delete(id);
+  // This shouldn't happen, but lets check anyway.
+  if (!this.eventListeners_.has(eventName)) return false;
+  return this.eventListeners_.get(eventName).delete(id);
+};
+
+
+/**
+ * Issues a DevTools protocol command and returns a promise for the results.
+ *
+ * @param {string} method The name of the DevTools protocol command method.
+ * @param {!Object=} opt_params An object containing the command parameters if
+ *    any.
+ * @return {!Promise<!Object>} A promise for the results object.
+ */
+chromium.DevTools.Connection.prototype.sendDevToolsMessage = function(
+    method, opt_params) {

[dpapad, 2017/06/07 17:49:22]

If you were to use ES6 for declaring optional parameters, you could do the
following

chromium.DevTools.Connection.prototype.sendDevToolsMessage = function(method,
params = {}) {
  let id = this.commandId_;
  ...
}

See
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/D....

[alex clarke (OOO till 29th), 2017/06/08 10:33:15]

Done.

+  if (opt_params === undefined) {
+    opt_params = {};
+  }
+  let id = this.commandId_;
+  // We increment by two because these bindings are intended to be used in
+  // conjunction with HeadlessDevToolsClient::RawProtocolListener and using odd
+  // numbers for js generated IDs lets the implementation of OnProtocolMessage
+  // easily distinguish between C++ and JS generated commands and route the
+  // response accordingly.
+  this.commandId_ += 2;
+  // Note the names are in quites to prevent closure compiler name mangling.

[dpapad, 2017/06/07 17:49:22]

s/quites/quotes

[alex clarke (OOO till 29th), 2017/06/08 10:33:15]

Done.

+  this.transport_.send(
+      JSON.stringify({'method': method, 'id': id, 'params': opt_params}));
+  return new Promise((resolve, reject) => {
+    this.pendingCommands_.set(id, resolve);

[dpapad, 2017/06/07 17:49:22]

I am assuming that the returned promise can never fail? FWIW, we use a small
helper class for similar situations elsewhere in the code, called
PromiseResolver
(https://cs.chromium.org/chromium/src/ui/webui/resources/js/promise_resolver.js),
which allows both resolving/rejecting a promise at a later time.

[alex clarke (OOO till 29th), 2017/06/08 10:33:15]

Interesting.  I guess right now that's not super easy to reuse here without
adding more js_library definitions.

+  });
+};
+
+
+/**
+ * @param {string} jsonMessage An object containing a DevTools protocol message.
+ * @private
+ */
+chromium.DevTools.Connection.prototype.onMessage_ = function(jsonMessage) {
+  const message = JSON.parse(jsonMessage);
+  if (message.hasOwnProperty('id')) {
+    if (!this.pendingCommands_.has(message.id))
+      throw new Error('Unrecognized id:' + json_message);
+    if (message.hasOwnProperty('error'))
+      throw new Error('DevTools protocol error: ' + message.error);
+    this.pendingCommands_.get(message.id)(message.result);
+    this.pendingCommands_.delete(message.id);
+  } else {
+    if (!message.hasOwnProperty('method') ||
+        !message.hasOwnProperty('params')) {
+      throw new Error('Bad message:' + json_message);
+    }
+    const method = message['method'];
+    const params = message['params'];
+    if (this.eventListeners_.has(method)) {
+      this.eventListeners_.get(method).forEach(function(listener) {
+        listener(params);
+      });
+    }
+  }
+};