feat: expose raw devtools protocol connection (#1770)

feat: expose raw devtools protocol connection

This patch introduces `target.createCDPSession` method that
allows directly communicating with the target over the
Chrome DevTools Protocol.

Fixes #31.

lib/Connection.js

@@ -13,6 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+const {helper} = require('./helper');
 const debugProtocol = require('debug')('puppeteer:protocol');
 const debugSession = require('debug')('puppeteer:session');
 
@@ -49,7 +50,7 @@ class Connection extends EventEmitter {
     this._ws = ws;
     this._ws.on('message', this._onMessage.bind(this));
     this._ws.on('close', this._onClose.bind(this));
-    /** @type {!Map<string, !Session>}*/
+    /** @type {!Map<string, !CDPSession>}*/
     this._sessions = new Map();
   }
 
@@ -135,17 +136,17 @@ class Connection extends EventEmitter {
 
   /**
    * @param {string} targetId
-   * @return {!Promise<!Session>}
+   * @return {!Promise<!CDPSession>}
    */
   async createSession(targetId) {
     const {sessionId} = await this.send('Target.attachToTarget', {targetId});
-    const session = new Session(this, targetId, sessionId);
+    const session = new CDPSession(this, targetId, sessionId);
     this._sessions.set(sessionId, session);
     return session;
   }
 }
 
-class Session extends EventEmitter {
+class CDPSession extends EventEmitter {
   /**
    * @param {!Connection} connection
    * @param {string} targetId
@@ -161,13 +162,6 @@ class Session extends EventEmitter {
     this._sessionId = sessionId;
   }
 
-  /**
-   * @return {string}
-   */
-  targetId() {
-    return this._targetId;
-  }
-
   /**
    * @param {string} method
    * @param {!Object=} params
@@ -211,9 +205,8 @@ class Session extends EventEmitter {
     }
   }
 
-  async dispose() {
-    console.assert(!!this._connection, 'Protocol error: Connection closed. Most likely the page has been closed.');
-    await this._connection.send('Target.closeTarget', {targetId: this._targetId});
+  async detach() {
+    await this._connection.send('Target.detachFromTarget',  {sessionId: this._sessionId});
   }
 
   _onClosed() {
@@ -223,6 +216,7 @@ class Session extends EventEmitter {
     this._connection = null;
   }
 }
+helper.tracePublicAPI(CDPSession);
 
 /**
  * @param {!Error} error
@@ -234,4 +228,4 @@ function rewriteError(error, message) {
   return error;
 }
 
-module.exports = {Connection, Session};
+module.exports = {Connection, CDPSession};