The Tor Browser: comparison toolkit/devtools/server/transport.js

comparison: toolkit/devtools/server/transport.js

toolkit/devtools/server/transport.js

changeset 0: 6474c204b198

equal deleted inserted replaced

--1:000000000000
+:4a1eaac91eeb
+/* -*- Mode: javascript; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
+/* vim: set ft=javascript ts=2 et sw=2 tw=80: */
+/* This Source Code Form is subject to the terms of the Mozilla Public
+* License, v. 2.0. If a copy of the MPL was not distributed with this
+* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+// TODO: Get rid of this code once the marionette server loads transport.js as
+// an SDK module (see bug 1000814)
+(function (factory) { // Module boilerplate
+if (this.module && module.id.indexOf("transport") >= 0) { // require
+factory(require, exports);
+} else { // loadSubScript
+if (this.require) {
+factory(require, this);
+} else {
+const Cu = Components.utils;
+const { devtools } = Cu.import("resource://gre/modules/devtools/Loader.jsm", {});
+factory(devtools.require, this);
+}
+}
+}).call(this, function (require, exports) {
+"use strict";
+const { Cc, Ci, Cr, Cu } = require("chrome");
+const Services = require("Services");
+const DevToolsUtils = require("devtools/toolkit/DevToolsUtils");
+const { dumpn } = DevToolsUtils;
+Cu.import("resource://gre/modules/NetUtil.jsm");
+/**
+* An adapter that handles data transfers between the debugger client and
+* server. It can work with both nsIPipe and nsIServerSocket transports so
+* long as the properly created input and output streams are specified.
+* (However, for intra-process connections, LocalDebuggerTransport, below,
+* is more efficient than using an nsIPipe pair with DebuggerTransport.)
+*
+* @param aInput nsIInputStream
+*        The input stream.
+* @param aOutput nsIAsyncOutputStream
+*        The output stream.
+*
+* Given a DebuggerTransport instance dt:
+* 1) Set dt.hooks to a packet handler object (described below).
+* 2) Call dt.ready() to begin watching for input packets.
+* 3) Call dt.send() to send packets as you please, and handle incoming
+*    packets passed to hook.onPacket.
+* 4) Call dt.close() to close the connection, and disengage from the event
+*    loop.
+*
+* A packet handler is an object with two methods:
+*
+* - onPacket(packet) - called when we have received a complete packet.
+*   |Packet| is the parsed form of the packet --- a JavaScript value, not
+*   a JSON-syntax string.
+*
+* - onClosed(status) - called when the connection is closed. |Status| is
+*   an nsresult, of the sort passed to nsIRequestObserver.
+*
+* Data is transferred as a JSON packet serialized into a string, with the
+* string length prepended to the packet, followed by a colon
+* ([length]:[packet]). The contents of the JSON packet are specified in
+* the Remote Debugging Protocol specification.
+*/
+function DebuggerTransport(aInput, aOutput)
+{
+this._input = aInput;
+this._output = aOutput;
+this._converter = Cc["@mozilla.org/intl/scriptableunicodeconverter"]
+.createInstance(Ci.nsIScriptableUnicodeConverter);
+this._converter.charset = "UTF-8";
+this._outgoing = "";
+this._incoming = "";
+this.hooks = null;
+}
+DebuggerTransport.prototype = {
+/**
+* Transmit a packet.
+*
+* This method returns immediately, without waiting for the entire
+* packet to be transmitted, registering event handlers as needed to
+* transmit the entire packet. Packets are transmitted in the order
+* they are passed to this method.
+*/
+send: function DT_send(aPacket) {
+let data = JSON.stringify(aPacket);
+data = this._converter.ConvertFromUnicode(data);
+data = data.length + ':' + data;
+this._outgoing += data;
+this._flushOutgoing();
+},
+/**
+* Close the transport.
+*/
+close: function DT_close() {
+this._input.close();
+this._output.close();
+},
+/**
+* Flush the outgoing stream.
+*/
+_flushOutgoing: function DT_flushOutgoing() {
+if (this._outgoing.length > 0) {
+var threadManager = Cc["@mozilla.org/thread-manager;1"].getService();
+this._output.asyncWait(this, 0, 0, threadManager.currentThread);
+}
+},
+onOutputStreamReady:
+DevToolsUtils.makeInfallible(function DT_onOutputStreamReady(aStream) {
+let written = 0;
+try {
+written = aStream.write(this._outgoing, this._outgoing.length);
+} catch(e if e.result == Cr.NS_BASE_STREAM_CLOSED) {
+dumpn("Connection closed.");
+this.close();
+return;
+}
+this._outgoing = this._outgoing.slice(written);
+this._flushOutgoing();
+}, "DebuggerTransport.prototype.onOutputStreamReady"),
+/**
+* Initialize the input stream for reading. Once this method has been
+* called, we watch for packets on the input stream, and pass them to
+* this.hook.onPacket.
+*/
+ready: function DT_ready() {
+let pump = Cc["@mozilla.org/network/input-stream-pump;1"]
+.createInstance(Ci.nsIInputStreamPump);
+pump.init(this._input, -1, -1, 0, 0, false);
+pump.asyncRead(this, null);
+},
+// nsIStreamListener
+onStartRequest:
+DevToolsUtils.makeInfallible(function DT_onStartRequest(aRequest, aContext) {},
+"DebuggerTransport.prototype.onStartRequest"),
+onStopRequest:
+DevToolsUtils.makeInfallible(function DT_onStopRequest(aRequest, aContext, aStatus) {
+this.close();
+if (this.hooks) {
+this.hooks.onClosed(aStatus);
+this.hooks = null;
+}
+}, "DebuggerTransport.prototype.onStopRequest"),
+onDataAvailable:
+DevToolsUtils.makeInfallible(function DT_onDataAvailable(aRequest, aContext,
+aStream, aOffset, aCount) {
+this._incoming += NetUtil.readInputStreamToString(aStream,
+aStream.available());
+while (this._processIncoming()) {};
+}, "DebuggerTransport.prototype.onDataAvailable"),
+/**
+* Process incoming packets. Returns true if a packet has been received, either
+* if it was properly parsed or not. Returns false if the incoming stream does
+* not contain a full packet yet. After a proper packet is parsed, the dispatch
+* handler DebuggerTransport.hooks.onPacket is called with the packet as a
+* parameter.
+*/
+_processIncoming: function DT__processIncoming() {
+// Well this is ugly.
+let sep = this._incoming.indexOf(':');
+if (sep < 0) {
+// Incoming packet length is too big anyway - drop the connection.
+if (this._incoming.length > 20) {
+this.close();
+}
+return false;
+}
+let count = this._incoming.substring(0, sep);
+// Check for a positive number with no garbage afterwards.
+if (!/^[0-9]+$/.exec(count)) {
+this.close();
+return false;
+}
+count = +count;
+if (this._incoming.length - (sep + 1) < count) {
+// Don't have a complete request yet.
+return false;
+}
+// We have a complete request, pluck it out of the data and parse it.
+this._incoming = this._incoming.substring(sep + 1);
+let packet = this._incoming.substring(0, count);
+this._incoming = this._incoming.substring(count);
+try {
+packet = this._converter.ConvertToUnicode(packet);
+var parsed = JSON.parse(packet);
+} catch(e) {
+let msg = "Error parsing incoming packet: " + packet + " (" + e + " - " + e.stack + ")";
+if (Cu.reportError) {
+Cu.reportError(msg);
+}
+dump(msg + "\n");
+return true;
+}
+if (dumpn.wantLogging) {
+dumpn("Got: " + JSON.stringify(parsed, null, 2));
+}
+let self = this;
+Services.tm.currentThread.dispatch(DevToolsUtils.makeInfallible(function() {
+// Ensure the hooks are still around by the time this runs (they will go
+// away when the transport is closed).
+if (self.hooks) {
+self.hooks.onPacket(parsed);
+}
+}, "DebuggerTransport instance's this.hooks.onPacket"), 0);
+return true;
+}
+}
+exports.DebuggerTransport = DebuggerTransport;
+/**
+* An adapter that handles data transfers between the debugger client and
+* server when they both run in the same process. It presents the same API as
+* DebuggerTransport, but instead of transmitting serialized messages across a
+* connection it merely calls the packet dispatcher of the other side.
+*
+* @param aOther LocalDebuggerTransport
+*        The other endpoint for this debugger connection.
+*
+* @see DebuggerTransport
+*/
+function LocalDebuggerTransport(aOther)
+{
+this.other = aOther;
+this.hooks = null;
+/*
+* A packet number, shared between this and this.other. This isn't used
+* by the protocol at all, but it makes the packet traces a lot easier to
+* follow.
+*/
+this._serial = this.other ? this.other._serial : { count: 0 };
+}
+LocalDebuggerTransport.prototype = {
+/**
+* Transmit a message by directly calling the onPacket handler of the other
+* endpoint.
+*/
+send: function LDT_send(aPacket) {
+let serial = this._serial.count++;
+if (dumpn.wantLogging) {
+/* Check 'from' first, as 'echo' packets have both. */
+if (aPacket.from) {
+dumpn("Packet " + serial + " sent from " + uneval(aPacket.from));
+} else if (aPacket.to) {
+dumpn("Packet " + serial + " sent to " + uneval(aPacket.to));
+}
+}
+this._deepFreeze(aPacket);
+let other = this.other;
+if (other) {
+Services.tm.currentThread.dispatch(DevToolsUtils.makeInfallible(function() {
+// Avoid the cost of JSON.stringify() when logging is disabled.
+if (dumpn.wantLogging) {
+dumpn("Received packet " + serial + ": " + JSON.stringify(aPacket, null, 2));
+}
+if (other.hooks) {
+other.hooks.onPacket(aPacket);
+}
+}, "LocalDebuggerTransport instance's this.other.hooks.onPacket"), 0);
+}
+},
+/**
+* Close the transport.
+*/
+close: function LDT_close() {
+if (this.other) {
+// Remove the reference to the other endpoint before calling close(), to
+// avoid infinite recursion.
+let other = this.other;
+this.other = null;
+other.close();
+}
+if (this.hooks) {
+try {
+this.hooks.onClosed();
+} catch(ex) {
+Cu.reportError(ex);
+}
+this.hooks = null;
+}
+},
+/**
+* An empty method for emulating the DebuggerTransport API.
+*/
+ready: function LDT_ready() {},
+/**
+* Helper function that makes an object fully immutable.
+*/
+_deepFreeze: function LDT_deepFreeze(aObject) {
+Object.freeze(aObject);
+for (let prop in aObject) {
+// Freeze the properties that are objects, not on the prototype, and not
+// already frozen. Note that this might leave an unfrozen reference
+// somewhere in the object if there is an already frozen object containing
+// an unfrozen object.
+if (aObject.hasOwnProperty(prop) && typeof aObject === "object" &&
+!Object.isFrozen(aObject)) {
+this._deepFreeze(o[prop]);
+}
+}
+}
+};
+exports.LocalDebuggerTransport = LocalDebuggerTransport;
+/**
+* A transport for the debugging protocol that uses nsIMessageSenders to
+* exchange packets with servers running in child processes.
+*
+* In the parent process, |aSender| should be the nsIMessageSender for the
+* child process. In a child process, |aSender| should be the child process
+* message manager, which sends packets to the parent.
+*
+* aPrefix is a string included in the message names, to distinguish
+* multiple servers running in the same child process.
+*
+* This transport exchanges messages named 'debug:<prefix>:packet', where
+* <prefix> is |aPrefix|, whose data is the protocol packet.
+*/
+function ChildDebuggerTransport(aSender, aPrefix) {
+this._sender = aSender.QueryInterface(Ci.nsIMessageSender);
+this._messageName = "debug:" + aPrefix + ":packet";
+}
+/*
+* To avoid confusion, we use 'message' to mean something that
+* nsIMessageSender conveys, and 'packet' to mean a remote debugging
+* protocol packet.
+*/
+ChildDebuggerTransport.prototype = {
+constructor: ChildDebuggerTransport,
+hooks: null,
+ready: function () {
+this._sender.addMessageListener(this._messageName, this);
+},
+close: function () {
+this._sender.removeMessageListener(this._messageName, this);
+this.hooks.onClosed();
+},
+receiveMessage: function ({data}) {
+this.hooks.onPacket(data);
+},
+send: function (packet) {
+this._sender.sendAsyncMessage(this._messageName, packet);
+}
+};
+exports.ChildDebuggerTransport = ChildDebuggerTransport;
+});