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

headless/lib/browser/devtools_api/devtools_connection.js

+// 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.module('chromium.DevTools.Connection');
+
+/**
+ * Handles sending and receiving DevTools JSON protocol messages over the
+ * provided low level message transport.
+ */
+class Connection {

[dpapad, 2017/06/08 17:12:03]

FYI, yesterday I discovered an issue when using ES6 clasess and --chrome_pass
flag, details at
https://bugs.chromium.org/p/chromium/issues/detail?id=671426#c20. Use at your
own risk (until the linked bug is addressed).

[alex clarke (OOO till 29th), 2017/06/09 08:37:16]

Noted, thanks.

+  /**
+   * @param {!Object} transport The API providing transport for devtools
+   *     commands.
+   */
+  constructor(transport) {
+    /** @private {!Object} */
+    this.transport_ = transport;
+
+    /** @private {number} */
+    this.commandId_ = 1;
+
+    /**
+     * An object containing pending DevTools protocol commands keyed by id.
+     *
+     * @private {!Map<number, !Connection.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, !Connection.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 {!Connection.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.
+   */
+  addEventListener(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.
+   * @return {boolean} Whether the event listener was actually removed.
+   */
+  removeEventListener(id) {
+    if (!this.eventListenerIdToEventName_.has(id)) return false;
+    let eventName = this.eventListenerIdToEventName_.get(id);
+    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=} params An object containing the command parameters if
+   *     any.
+   * @return {!Promise<!Object>} A promise for the results object.
+   */
+  sendDevToolsMessage(method, 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 quotes to prevent closure compiler name mangling.
+    this.transport_.send(
+        JSON.stringify({'method': method, 'id': id, 'params': params}));
+    return new Promise((resolve, reject) => {
+      this.pendingCommands_.set(id, resolve);
+    });
+  }
+
+
+  /**
+   * @param {string} jsonMessage An object containing a DevTools protocol
+   *     message.
+   * @private
+   */
+  onMessage_(jsonMessage) {
+    const message = JSON.parse(jsonMessage);
+    if (message.hasOwnProperty('id')) {
+      if (!this.pendingCommands_.has(message.id))
+        throw new Error('Unrecognized id:' + jsonMessage);
+      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:' + jsonMessage);
+      }
+      const method = message['method'];
+      const params = message['params'];
+      if (this.eventListeners_.has(method)) {
+        this.eventListeners_.get(method).forEach(function(listener) {
+          listener(params);
+        });
+      }
+    }
+  }
+}
+
+/**
+ * @typedef {function(Object): undefined|function(string): undefined}
+ */
+Connection.CallbackFunction;
+
+exports = Connection;