The Tor Browser / file revision

 /* -*- 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/. */

 "use strict";

 /**

  * Toolkit glue for the remote debugging protocol, loaded into the

  * debugging global.

  */

 let { Ci, Cc, CC, Cu, Cr } = require("chrome");

 let Debugger = require("Debugger");

 let Services = require("Services");

 let { ActorPool } = require("devtools/server/actors/common");

 let { DebuggerTransport, LocalDebuggerTransport, ChildDebuggerTransport } = require("devtools/server/transport");

 let DevToolsUtils = require("devtools/toolkit/DevToolsUtils");

 let { dumpn, dbg_assert } = DevToolsUtils;

 let Services = require("Services");

 let EventEmitter = require("devtools/toolkit/event-emitter");

 // Until all Debugger server code is converted to SDK modules,

 // imports Components.* alias from chrome module.

 var { Ci, Cc, CC, Cu, Cr } = require("chrome");

 // On B2G, `this` != Global scope, so `Ci` won't be binded on `this`

 // (i.e. this.Ci is undefined) Then later, when using loadSubScript,

 // Ci,... won't be defined for sub scripts.

 this.Ci = Ci;

 this.Cc = Cc;

 this.CC = CC;

 this.Cu = Cu;

 this.Cr = Cr;

 this.Debugger = Debugger;

 this.Services = Services;

 this.ActorPool = ActorPool;

 this.DevToolsUtils = DevToolsUtils;

 this.dumpn = dumpn;

 this.dbg_assert = dbg_assert;

 // Overload `Components` to prevent SDK loader exception on Components

 // object usage

 Object.defineProperty(this, "Components", {

   get: function () require("chrome").components

 });

 const DBG_STRINGS_URI = "chrome://global/locale/devtools/debugger.properties";

 const nsFile = CC("@mozilla.org/file/local;1", "nsIFile", "initWithPath");

 Cu.import("resource://gre/modules/reflect.jsm");

 Cu.import("resource://gre/modules/XPCOMUtils.jsm");

 Cu.import("resource://gre/modules/NetUtil.jsm");

 dumpn.wantLogging = Services.prefs.getBoolPref("devtools.debugger.log");

 Cu.import("resource://gre/modules/devtools/deprecated-sync-thenables.js");

 function loadSubScript(aURL)

 {

   try {

     let loader = Cc["@mozilla.org/moz/jssubscript-loader;1"]

       .getService(Ci.mozIJSSubScriptLoader);

     loader.loadSubScript(aURL, this);

   } catch(e) {

     let errorStr = "Error loading: " + aURL + ":\n" +

                    (e.fileName ? "at " + e.fileName + " : " + e.lineNumber + "\n" : "") +

                    e + " - " + e.stack + "\n";

     dump(errorStr);

     Cu.reportError(errorStr);

     throw e;

   }

 }

 let events = require("sdk/event/core");

 let {defer, resolve, reject, all} = require("devtools/toolkit/deprecated-sync-thenables");

 this.defer = defer;

 this.resolve = resolve;

 this.reject = reject;

 this.all = all;

 Cu.import("resource://gre/modules/devtools/SourceMap.jsm");

 XPCOMUtils.defineLazyModuleGetter(this, "console",

                                   "resource://gre/modules/devtools/Console.jsm");

 XPCOMUtils.defineLazyGetter(this, "NetworkMonitorManager", () => {

   return require("devtools/toolkit/webconsole/network-monitor").NetworkMonitorManager;

 });

 // XPCOM constructors

 const ServerSocket = CC("@mozilla.org/network/server-socket;1",

                         "nsIServerSocket",

                         "initSpecialConnection");

 const UnixDomainServerSocket = CC("@mozilla.org/network/server-socket;1",

                                   "nsIServerSocket",

                                   "initWithFilename");

 var gRegisteredModules = Object.create(null);

 /**

  * The ModuleAPI object is passed to modules loaded using the

  * DebuggerServer.registerModule() API.  Modules can use this

  * object to register actor factories.

  * Factories registered through the module API will be removed

  * when the module is unregistered or when the server is

  * destroyed.

  */

 function ModuleAPI() {

   let activeTabActors = new Set();

   let activeGlobalActors = new Set();

   return {

     // See DebuggerServer.addGlobalActor for a description.

     addGlobalActor: function(factory, name) {

       DebuggerServer.addGlobalActor(factory, name);

       activeGlobalActors.add(factory);

     },

     // See DebuggerServer.removeGlobalActor for a description.

     removeGlobalActor: function(factory) {

       DebuggerServer.removeGlobalActor(factory);

       activeGlobalActors.delete(factory);

     },

     // See DebuggerServer.addTabActor for a description.

     addTabActor: function(factory, name) {

       DebuggerServer.addTabActor(factory, name);

       activeTabActors.add(factory);

     },

     // See DebuggerServer.removeTabActor for a description.

     removeTabActor: function(factory) {

       DebuggerServer.removeTabActor(factory);

       activeTabActors.delete(factory);

     },

     // Destroy the module API object, unregistering any

     // factories registered by the module.

     destroy: function() {

       for (let factory of activeTabActors) {

         DebuggerServer.removeTabActor(factory);

       }

       activeTabActors = null;

       for (let factory of activeGlobalActors) {

         DebuggerServer.removeGlobalActor(factory);

       }

       activeGlobalActors = null;

     }

   }

 };

 /***

  * Public API

  */

 var DebuggerServer = {

   _listener: null,

   _initialized: false,

   _transportInitialized: false,

   xpcInspector: null,

   // Number of currently open TCP connections.

   _socketConnections: 0,

   // Map of global actor names to actor constructors provided by extensions.

   globalActorFactories: {},

   // Map of tab actor names to actor constructors provided by extensions.

   tabActorFactories: {},

   LONG_STRING_LENGTH: 10000,

   LONG_STRING_INITIAL_LENGTH: 1000,

   LONG_STRING_READ_LENGTH: 65 * 1024,

   /**

    * A handler function that prompts the user to accept or decline the incoming

    * connection.

    */

   _allowConnection: null,

   /**

    * The windowtype of the chrome window to use for actors that use the global

    * window (i.e the global style editor). Set this to your main window type,

    * for example "navigator:browser".

    */

   chromeWindowType: null,

   /**

    * Prompt the user to accept or decline the incoming connection. This is the

    * default implementation that products embedding the debugger server may

    * choose to override.

    *

    * @return true if the connection should be permitted, false otherwise

    */

   _defaultAllowConnection: function DS__defaultAllowConnection() {

     let title = L10N.getStr("remoteIncomingPromptTitle");

     let msg = L10N.getStr("remoteIncomingPromptMessage");

     let disableButton = L10N.getStr("remoteIncomingPromptDisable");

     let prompt = Services.prompt;

     let flags = prompt.BUTTON_POS_0 * prompt.BUTTON_TITLE_OK +

                 prompt.BUTTON_POS_1 * prompt.BUTTON_TITLE_CANCEL +

                 prompt.BUTTON_POS_2 * prompt.BUTTON_TITLE_IS_STRING +

                 prompt.BUTTON_POS_1_DEFAULT;

     let result = prompt.confirmEx(null, title, msg, flags, null, null,

                                   disableButton, null, { value: false });

     if (result == 0) {

       return true;

     }

     if (result == 2) {

       DebuggerServer.closeListener(true);

       Services.prefs.setBoolPref("devtools.debugger.remote-enabled", false);

     }

     return false;

   },

   /**

    * Initialize the debugger server.

    *

    * @param function aAllowConnectionCallback

    *        The embedder-provider callback, that decides whether an incoming

    *        remote protocol conection should be allowed or refused.

    */

   init: function DS_init(aAllowConnectionCallback) {

     if (this.initialized) {

       return;

     }

     this.xpcInspector = Cc["@mozilla.org/jsinspector;1"].getService(Ci.nsIJSInspector);

     this.initTransport(aAllowConnectionCallback);

     this.addActors("resource://gre/modules/devtools/server/actors/root.js");

     this._initialized = true;

   },

   protocol: require("devtools/server/protocol"),

   /**

    * Initialize the debugger server's transport variables.  This can be

    * in place of init() for cases where the jsdebugger isn't needed.

    *

    * @param function aAllowConnectionCallback

    *        The embedder-provider callback, that decides whether an incoming

    *        remote protocol conection should be allowed or refused.

    */

   initTransport: function DS_initTransport(aAllowConnectionCallback) {

     if (this._transportInitialized) {

       return;

     }

     this._connections = {};

     this._nextConnID = 0;

     this._transportInitialized = true;

     this._allowConnection = aAllowConnectionCallback ?

                             aAllowConnectionCallback :

                             this._defaultAllowConnection;

   },

   get initialized() this._initialized,

   /**

    * Performs cleanup tasks before shutting down the debugger server. Such tasks

    * include clearing any actor constructors added at runtime. This method

    * should be called whenever a debugger server is no longer useful, to avoid

    * memory leaks. After this method returns, the debugger server must be

    * initialized again before use.

    */

   destroy: function DS_destroy() {

     if (!this._initialized) {

       return;

     }

     for (let connID of Object.getOwnPropertyNames(this._connections)) {

       this._connections[connID].close();

     }

     for (let id of Object.getOwnPropertyNames(gRegisteredModules)) {

       let mod = gRegisteredModules[id];

       mod.module.unregister(mod.api);

     }

     gRegisteredModules = {};

     this.closeListener();

     this.globalActorFactories = {};

     this.tabActorFactories = {};

     this._allowConnection = null;

     this._transportInitialized = false;

     this._initialized = false;

     dumpn("Debugger server is shut down.");

   },

   /**

    * Load a subscript into the debugging global.

    *

    * @param aURL string A url that will be loaded as a subscript into the

    *        debugging global.  The user must load at least one script

    *        that implements a createRootActor() function to create the

    *        server's root actor.

    */

   addActors: function DS_addActors(aURL) {

     loadSubScript.call(this, aURL);

   },

   /**

    * Register a CommonJS module with the debugger server.

    * @param id string

    *    The ID of a CommonJS module.  This module must export

    *    'register' and 'unregister' functions.

    */

   registerModule: function(id) {

     if (id in gRegisteredModules) {

       throw new Error("Tried to register a module twice: " + id + "\n");

     }

     let moduleAPI = ModuleAPI();

     let mod = require(id);

     mod.register(moduleAPI);

     gRegisteredModules[id] = { module: mod, api: moduleAPI };

   },

   /**

    * Returns true if a module id has been registered.

    */

   isModuleRegistered: function(id) {

     return (id in gRegisteredModules);

   },

   /**

    * Unregister a previously-loaded CommonJS module from the debugger server.

    */

   unregisterModule: function(id) {

     let mod = gRegisteredModules[id];

     if (!mod) {

       throw new Error("Tried to unregister a module that was not previously registered.");

     }

     mod.module.unregister(mod.api);

     mod.api.destroy();

     delete gRegisteredModules[id];

   },

   /**

    * Install Firefox-specific actors.

    *

    * /!\ Be careful when adding a new actor, especially global actors.

    * Any new global actor will be exposed and returned by the root actor.

    *

    * That's the reason why tab actors aren't loaded on demand via

    * restrictPrivileges=true, to prevent exposing them on b2g parent process's

    * root actor.

    */

   addBrowserActors: function(aWindowType = "navigator:browser", restrictPrivileges = false) {

     this.chromeWindowType = aWindowType;

     this.addActors("resource://gre/modules/devtools/server/actors/webbrowser.js");

     if (!restrictPrivileges) {

       this.addTabActors();

       this.addGlobalActor(this.ChromeDebuggerActor, "chromeDebugger");

       this.registerModule("devtools/server/actors/preference");

     }

     this.addActors("resource://gre/modules/devtools/server/actors/webapps.js");

     this.registerModule("devtools/server/actors/device");

   },

   /**

    * Install tab actors in documents loaded in content childs

    */

   addChildActors: function () {

     // In case of apps being loaded in parent process, DebuggerServer is already

     // initialized and browser actors are already loaded,

     // but childtab.js hasn't been loaded yet.

     if (!DebuggerServer.tabActorFactories.hasOwnProperty("consoleActor")) {

       this.addTabActors();

     }

     // But webbrowser.js and childtab.js aren't loaded from shell.js.

     if (!("BrowserTabActor" in this)) {

       this.addActors("resource://gre/modules/devtools/server/actors/webbrowser.js");

     }

     if (!("ContentActor" in this)) {

       this.addActors("resource://gre/modules/devtools/server/actors/childtab.js");

     }

   },

   /**

    * Install tab actors.

    */

   addTabActors: function() {

     this.addActors("resource://gre/modules/devtools/server/actors/script.js");

     this.registerModule("devtools/server/actors/webconsole");

     this.registerModule("devtools/server/actors/inspector");

     this.registerModule("devtools/server/actors/call-watcher");

     this.registerModule("devtools/server/actors/canvas");

     this.registerModule("devtools/server/actors/webgl");

     this.registerModule("devtools/server/actors/webaudio");

     this.registerModule("devtools/server/actors/stylesheets");

     this.registerModule("devtools/server/actors/styleeditor");

     this.registerModule("devtools/server/actors/storage");

     this.registerModule("devtools/server/actors/gcli");

     this.registerModule("devtools/server/actors/tracer");

     this.registerModule("devtools/server/actors/memory");

     this.registerModule("devtools/server/actors/eventlooplag");

     if ("nsIProfiler" in Ci) {

       this.addActors("resource://gre/modules/devtools/server/actors/profiler.js");

     }

   },

   /**

    * Passes a set of options to the BrowserAddonActors for the given ID.

    *

    * @param aId string

    *        The ID of the add-on to pass the options to

    * @param aOptions object

    *        The options.

    * @return a promise that will be resolved when complete.

    */

   setAddonOptions: function DS_setAddonOptions(aId, aOptions) {

     if (!this._initialized) {

       return;

     }

     let promises = [];

     // Pass to all connections

     for (let connID of Object.getOwnPropertyNames(this._connections)) {

       promises.push(this._connections[connID].setAddonOptions(aId, aOptions));

     }

     return all(promises);

   },

   /**

    * Listens on the given port or socket file for remote debugger connections.

    *

    * @param aPortOrPath int, string

    *        If given an integer, the port to listen on.

    *        Otherwise, the path to the unix socket domain file to listen on.

    */

   openListener: function DS_openListener(aPortOrPath) {

     if (!Services.prefs.getBoolPref("devtools.debugger.remote-enabled")) {

       return false;

     }

     this._checkInit();

     // Return early if the server is already listening.

     if (this._listener) {

       return true;

     }

     let flags = Ci.nsIServerSocket.KeepWhenOffline;

     // A preference setting can force binding on the loopback interface.

     if (Services.prefs.getBoolPref("devtools.debugger.force-local")) {

       flags |= Ci.nsIServerSocket.LoopbackOnly;

     }

     try {

       let backlog = 4;

       let socket;

       let port = Number(aPortOrPath);

       if (port) {

         socket = new ServerSocket(port, flags, backlog);

       } else {

         let file = nsFile(aPortOrPath);

         if (file.exists())

           file.remove(false);

         socket = new UnixDomainServerSocket(file, parseInt("666", 8), backlog);

       }

       socket.asyncListen(this);

       this._listener = socket;

     } catch (e) {

       dumpn("Could not start debugging listener on '" + aPortOrPath + "': " + e);

       throw Cr.NS_ERROR_NOT_AVAILABLE;

     }

     this._socketConnections++;

     return true;

   },

   /**

    * Close a previously-opened TCP listener.

    *

    * @param aForce boolean [optional]

    *        If set to true, then the socket will be closed, regardless of the

    *        number of open connections.

    */

   closeListener: function DS_closeListener(aForce) {

     if (!this._listener || this._socketConnections == 0) {

       return false;

     }

     // Only close the listener when the last connection is closed, or if the

     // aForce flag is passed.

     if (--this._socketConnections == 0 || aForce) {

       this._listener.close();

       this._listener = null;

       this._socketConnections = 0;

     }

     return true;

   },

   /**

    * Creates a new connection to the local debugger speaking over a fake

    * transport. This connection results in straightforward calls to the onPacket

    * handlers of each side.

    *

    * @param aPrefix string [optional]

    *    If given, all actors in this connection will have names starting

    *    with |aPrefix + ':'|.

    * @returns a client-side DebuggerTransport for communicating with

    *    the newly-created connection.

    */

   connectPipe: function DS_connectPipe(aPrefix) {

     this._checkInit();

     let serverTransport = new LocalDebuggerTransport;

     let clientTransport = new LocalDebuggerTransport(serverTransport);

     serverTransport.other = clientTransport;

     let connection = this._onConnection(serverTransport, aPrefix);

     // I'm putting this here because I trust you.

     //

     // There are times, when using a local connection, when you're going

     // to be tempted to just get direct access to the server.  Resist that

     // temptation!  If you succumb to that temptation, you will make the

     // fine developers that work on Fennec and Firefox OS sad.  They're

     // professionals, they'll try to act like they understand, but deep

     // down you'll know that you hurt them.

     //

     // This reference allows you to give in to that temptation.  There are

     // times this makes sense: tests, for example, and while porting a

     // previously local-only codebase to the remote protocol.

     //

     // But every time you use this, you will feel the shame of having

     // used a property that starts with a '_'.

     clientTransport._serverConnection = connection;

     return clientTransport;

   },

   /**

    * In a content child process, create a new connection that exchanges

    * nsIMessageSender messages with our parent process.

    *

    * @param aPrefix

    *    The prefix we should use in our nsIMessageSender message names and

    *    actor names. This connection will use messages named

    *    "debug:<prefix>:packet", and all its actors will have names

    *    beginning with "<prefix>:".

    */

   connectToParent: function(aPrefix, aMessageManager) {

     this._checkInit();

     let transport = new ChildDebuggerTransport(aMessageManager, aPrefix);

     return this._onConnection(transport, aPrefix, true);

   },

   /**

    * Connect to a child process.

    *

    * @param object aConnection

    *        The debugger server connection to use.

    * @param nsIDOMElement aFrame

    *        The browser element that holds the child process.

    * @param function [aOnDisconnect]

    *        Optional function to invoke when the child is disconnected.

    * @return object

    *         A promise object that is resolved once the connection is

    *         established.

    */

   connectToChild: function(aConnection, aFrame, aOnDisconnect) {

     let deferred = defer();

     let mm = aFrame.QueryInterface(Ci.nsIFrameLoaderOwner).frameLoader

              .messageManager;

     mm.loadFrameScript("resource://gre/modules/devtools/server/child.js", false);

     let actor, childTransport;

     let prefix = aConnection.allocID("child");

     let netMonitor = null;

     let onActorCreated = DevToolsUtils.makeInfallible(function (msg) {

       mm.removeMessageListener("debug:actor", onActorCreated);

       // Pipe Debugger message from/to parent/child via the message manager

       childTransport = new ChildDebuggerTransport(mm, prefix);

       childTransport.hooks = {

         onPacket: aConnection.send.bind(aConnection),

         onClosed: function () {}

       };

       childTransport.ready();

       aConnection.setForwarding(prefix, childTransport);

       dumpn("establishing forwarding for app with prefix " + prefix);

       actor = msg.json.actor;

       netMonitor = new NetworkMonitorManager(aFrame, actor.actor);

       deferred.resolve(actor);

     }).bind(this);

     mm.addMessageListener("debug:actor", onActorCreated);

     let onMessageManagerDisconnect = DevToolsUtils.makeInfallible(function (subject, topic, data) {

       if (subject == mm) {

         Services.obs.removeObserver(onMessageManagerDisconnect, topic);

         if (childTransport) {

           // If we have a child transport, the actor has already

           // been created. We need to stop using this message manager.

           childTransport.close();

           childTransport = null;

           aConnection.cancelForwarding(prefix);

         } else {

           // Otherwise, the app has been closed before the actor

           // had a chance to be created, so we are not able to create

           // the actor.

           deferred.resolve(null);

         }

         if (actor) {

           // The ContentActor within the child process doesn't necessary

           // have to time to uninitialize itself when the app is closed/killed.

           // So ensure telling the client that the related actor is detached.

           aConnection.send({ from: actor.actor, type: "tabDetached" });

           actor = null;

         }

         if (netMonitor) {

           netMonitor.destroy();

           netMonitor = null;

         }

         if (aOnDisconnect) {

           aOnDisconnect(mm);

         }

       }

     }).bind(this);

     Services.obs.addObserver(onMessageManagerDisconnect,

                              "message-manager-disconnect", false);

     events.once(aConnection, "closed", () => {

       if (childTransport) {

         // When the client disconnects, we have to unplug the dedicated

         // ChildDebuggerTransport...

         childTransport.close();

         childTransport = null;

         aConnection.cancelForwarding(prefix);

         // ... and notify the child process to clean the tab actors.

         mm.sendAsyncMessage("debug:disconnect");

       }

       Services.obs.removeObserver(onMessageManagerDisconnect, "message-manager-disconnect");

     });

     mm.sendAsyncMessage("debug:connect", { prefix: prefix });

     return deferred.promise;

   },

   // nsIServerSocketListener implementation

   onSocketAccepted:

   DevToolsUtils.makeInfallible(function DS_onSocketAccepted(aSocket, aTransport) {

     if (Services.prefs.getBoolPref("devtools.debugger.prompt-connection") && !this._allowConnection()) {

       return;

     }

     dumpn("New debugging connection on " + aTransport.host + ":" + aTransport.port);

     let input = aTransport.openInputStream(0, 0, 0);

     let output = aTransport.openOutputStream(0, 0, 0);

     let transport = new DebuggerTransport(input, output);

     DebuggerServer._onConnection(transport);

   }, "DebuggerServer.onSocketAccepted"),

   onStopListening: function DS_onStopListening(aSocket, status) {

     dumpn("onStopListening, status: " + status);

   },

   /**

    * Raises an exception if the server has not been properly initialized.

    */

   _checkInit: function DS_checkInit() {

     if (!this._transportInitialized) {

       throw "DebuggerServer has not been initialized.";

     }

     if (!this.createRootActor) {

       throw "Use DebuggerServer.addActors() to add a root actor implementation.";

     }

   },

   /**

    * Create a new debugger connection for the given transport. Called after

    * connectPipe(), from connectToParent, or from an incoming socket

    * connection handler.

    *

    * If present, |aForwardingPrefix| is a forwarding prefix that a parent

    * server is using to recognizes messages intended for this server. Ensure

    * that all our actors have names beginning with |aForwardingPrefix + ':'|.

    * In particular, the root actor's name will be |aForwardingPrefix + ':root'|.

    */

   _onConnection: function DS_onConnection(aTransport, aForwardingPrefix, aNoRootActor = false) {

     let connID;

     if (aForwardingPrefix) {

       connID = aForwardingPrefix + ":";

     } else {

       connID = "conn" + this._nextConnID++ + '.';

     }

     let conn = new DebuggerServerConnection(connID, aTransport);

     this._connections[connID] = conn;

     // Create a root actor for the connection and send the hello packet.

     if (!aNoRootActor) {

       conn.rootActor = this.createRootActor(conn);

       if (aForwardingPrefix)

         conn.rootActor.actorID = aForwardingPrefix + ":root";

       else

         conn.rootActor.actorID = "root";

       conn.addActor(conn.rootActor);

       aTransport.send(conn.rootActor.sayHello());

     }

     aTransport.ready();

     this.emit("connectionchange", "opened", conn);

     return conn;

   },

   /**

    * Remove the connection from the debugging server.

    */

   _connectionClosed: function DS_connectionClosed(aConnection) {

     delete this._connections[aConnection.prefix];

     this.emit("connectionchange", "closed", aConnection);

   },

   // DebuggerServer extension API.

   /**

    * Registers handlers for new tab-scoped request types defined dynamically.

    * This is used for example by add-ons to augment the functionality of the tab

    * actor. Note that the name or actorPrefix of the request type is not allowed

    * to clash with existing protocol packet properties, like 'title', 'url' or

    * 'actor', since that would break the protocol.

    *

    * @param aFunction function

    *        The constructor function for this request type. This expects to be

    *        called as a constructor (i.e. with 'new'), and passed two

    *        arguments: the DebuggerServerConnection, and the BrowserTabActor

    *        with which it will be associated.

    *

    * @param aName string [optional]

    *        The name of the new request type. If this is not present, the

    *        actorPrefix property of the constructor prototype is used.

    */

   addTabActor: function DS_addTabActor(aFunction, aName) {

     let name = aName ? aName : aFunction.prototype.actorPrefix;

     if (["title", "url", "actor"].indexOf(name) != -1) {

       throw Error(name + " is not allowed");

     }

     if (DebuggerServer.tabActorFactories.hasOwnProperty(name)) {

       throw Error(name + " already exists");

     }

     DebuggerServer.tabActorFactories[name] = aFunction;

   },

   /**

    * Unregisters the handler for the specified tab-scoped request type.

    * This may be used for example by add-ons when shutting down or upgrading.

    *

    * @param aFunction function

    *        The constructor function for this request type.

    */

   removeTabActor: function DS_removeTabActor(aFunction) {

     for (let name in DebuggerServer.tabActorFactories) {

       let handler = DebuggerServer.tabActorFactories[name];

       if (handler.name == aFunction.name) {

         delete DebuggerServer.tabActorFactories[name];

       }

     }

   },

   /**

    * Registers handlers for new browser-scoped request types defined

    * dynamically. This is used for example by add-ons to augment the

    * functionality of the root actor. Note that the name or actorPrefix of the

    * request type is not allowed to clash with existing protocol packet

    * properties, like 'from', 'tabs' or 'selected', since that would break the

    * protocol.

    *

    * @param aFunction function

    *        The constructor function for this request type. This expects to be

    *        called as a constructor (i.e. with 'new'), and passed two

    *        arguments: the DebuggerServerConnection, and the BrowserRootActor

    *        with which it will be associated.

    *

    * @param aName string [optional]

    *        The name of the new request type. If this is not present, the

    *        actorPrefix property of the constructor prototype is used.

    */

   addGlobalActor: function DS_addGlobalActor(aFunction, aName) {

     let name = aName ? aName : aFunction.prototype.actorPrefix;

     if (["from", "tabs", "selected"].indexOf(name) != -1) {

       throw Error(name + " is not allowed");

     }

     if (DebuggerServer.globalActorFactories.hasOwnProperty(name)) {

       throw Error(name + " already exists");

     }

     DebuggerServer.globalActorFactories[name] = aFunction;

   },

   /**

    * Unregisters the handler for the specified browser-scoped request type.

    * This may be used for example by add-ons when shutting down or upgrading.

    *

    * @param aFunction function

    *        The constructor function for this request type.

    */

   removeGlobalActor: function DS_removeGlobalActor(aFunction) {

     for (let name in DebuggerServer.globalActorFactories) {

       let handler = DebuggerServer.globalActorFactories[name];

       if (handler.name == aFunction.name) {

         delete DebuggerServer.globalActorFactories[name];

       }

     }

   }

 };

 EventEmitter.decorate(DebuggerServer);

 if (this.exports) {

   exports.DebuggerServer = DebuggerServer;

 }

 // Needed on B2G (See header note)

 this.DebuggerServer = DebuggerServer;

 // Export ActorPool for requirers of main.js

 if (this.exports) {

   exports.ActorPool = ActorPool;

 }

 /**

  * Creates a DebuggerServerConnection.

  *

  * Represents a connection to this debugging global from a client.

  * Manages a set of actors and actor pools, allocates actor ids, and

  * handles incoming requests.

  *

  * @param aPrefix string

  *        All actor IDs created by this connection should be prefixed

  *        with aPrefix.

  * @param aTransport transport

  *        Packet transport for the debugging protocol.

  */

 function DebuggerServerConnection(aPrefix, aTransport)

 {

   this._prefix = aPrefix;

   this._transport = aTransport;

   this._transport.hooks = this;

   this._nextID = 1;

   this._actorPool = new ActorPool(this);

   this._extraPools = [];

   // Responses to a given actor must be returned the the client

   // in the same order as the requests that they're replying to, but

   // Implementations might finish serving requests in a different

   // order.  To keep things in order we generate a promise for each

   // request, chained to the promise for the request before it.

   // This map stores the latest request promise in the chain, keyed

   // by an actor ID string.

   this._actorResponses = new Map;

   /*

    * We can forward packets to other servers, if the actors on that server

    * all use a distinct prefix on their names. This is a map from prefixes

    * to transports: it maps a prefix P to a transport T if T conveys

    * packets to the server whose actors' names all begin with P + ":".

    */

   this._forwardingPrefixes = new Map;

 }

 DebuggerServerConnection.prototype = {

   _prefix: null,

   get prefix() { return this._prefix },

   _transport: null,

   get transport() { return this._transport },

   close: function() {

     this._transport.close();

   },

   send: function DSC_send(aPacket) {

     this.transport.send(aPacket);

   },

   allocID: function DSC_allocID(aPrefix) {

     return this.prefix + (aPrefix || '') + this._nextID++;

   },

   /**

    * Add a map of actor IDs to the connection.

    */

   addActorPool: function DSC_addActorPool(aActorPool) {

     this._extraPools.push(aActorPool);

   },

   /**

    * Remove a previously-added pool of actors to the connection.

    *

    * @param ActorPool aActorPool

    *        The ActorPool instance you want to remove.

    * @param boolean aNoCleanup [optional]

    *        True if you don't want to disconnect each actor from the pool, false

    *        otherwise.

    */

   removeActorPool: function DSC_removeActorPool(aActorPool, aNoCleanup) {

     let index = this._extraPools.lastIndexOf(aActorPool);

     if (index > -1) {

       let pool = this._extraPools.splice(index, 1);

       if (!aNoCleanup) {

         pool.map(function(p) { p.cleanup(); });

       }

     }

   },

   /**

    * Add an actor to the default actor pool for this connection.

    */

   addActor: function DSC_addActor(aActor) {

     this._actorPool.addActor(aActor);

   },

   /**

    * Remove an actor to the default actor pool for this connection.

    */

   removeActor: function DSC_removeActor(aActor) {

     this._actorPool.removeActor(aActor);

   },

   /**

    * Match the api expected by the protocol library.

    */

   unmanage: function(aActor) {

     return this.removeActor(aActor);

   },

   /**

    * Look up an actor implementation for an actorID.  Will search

    * all the actor pools registered with the connection.

    *

    * @param aActorID string

    *        Actor ID to look up.

    */

   getActor: function DSC_getActor(aActorID) {

     let pool = this.poolFor(aActorID);

     if (pool) {

       return pool.get(aActorID);

     }

     if (aActorID === "root") {

       return this.rootActor;

     }

     return null;

   },

   poolFor: function DSC_actorPool(aActorID) {

     if (this._actorPool && this._actorPool.has(aActorID)) {

       return this._actorPool;

     }

     for (let pool of this._extraPools) {

       if (pool.has(aActorID)) {

         return pool;

       }

     }

     return null;

   },

   _unknownError: function DSC__unknownError(aPrefix, aError) {

     let errorString = aPrefix + ": " + DevToolsUtils.safeErrorString(aError);

     Cu.reportError(errorString);

     dumpn(errorString);

     return {

       error: "unknownError",

       message: errorString

     };

   },

   /**

    * Passes a set of options to the BrowserAddonActors for the given ID.

    *

    * @param aId string

    *        The ID of the add-on to pass the options to

    * @param aOptions object

    *        The options.

    * @return a promise that will be resolved when complete.

    */

   setAddonOptions: function DSC_setAddonOptions(aId, aOptions) {

     let addonList = this.rootActor._parameters.addonList;

     if (!addonList) {

       return resolve();

     }

     return addonList.getList().then((addonActors) => {

       for (let actor of addonActors) {

         if (actor.id != aId) {

           continue;

         }

         actor.setOptions(aOptions);

         return;

       }

     });

   },

   /* Forwarding packets to other transports based on actor name prefixes. */

   /*

    * Arrange to forward packets to another server. This is how we

    * forward debugging connections to child processes.

    *

    * If we receive a packet for an actor whose name begins with |aPrefix|

    * followed by ':', then we will forward that packet to |aTransport|.

    *

    * This overrides any prior forwarding for |aPrefix|.

    *

    * @param aPrefix string

    *    The actor name prefix, not including the ':'.

    * @param aTransport object

    *    A packet transport to which we should forward packets to actors

    *    whose names begin with |(aPrefix + ':').|

    */

   setForwarding: function(aPrefix, aTransport) {

     this._forwardingPrefixes.set(aPrefix, aTransport);

   },

   /*

    * Stop forwarding messages to actors whose names begin with

    * |aPrefix+':'|. Such messages will now elicit 'noSuchActor' errors.

    */

   cancelForwarding: function(aPrefix) {

     this._forwardingPrefixes.delete(aPrefix);

   },

   // Transport hooks.

   /**

    * Called by DebuggerTransport to dispatch incoming packets as appropriate.

    *

    * @param aPacket object

    *        The incoming packet.

    */

   onPacket: function DSC_onPacket(aPacket) {

     // If the actor's name begins with a prefix we've been asked to

     // forward, do so.

     //

     // Note that the presence of a prefix alone doesn't indicate that

     // forwarding is needed: in DebuggerServerConnection instances in child

     // processes, every actor has a prefixed name.

     if (this._forwardingPrefixes.size > 0) {

       let colon = aPacket.to.indexOf(':');

       if (colon >= 0) {

         let forwardTo = this._forwardingPrefixes.get(aPacket.to.substring(0, colon));

         if (forwardTo) {

           forwardTo.send(aPacket);

           return;

         }

       }

     }

     let actor = this.getActor(aPacket.to);

     if (!actor) {

       this.transport.send({ from: aPacket.to ? aPacket.to : "root",

                             error: "noSuchActor",

                             message: "No such actor for ID: " + aPacket.to });

       return;

     }

     // Dyamically-loaded actors have to be created lazily.

     if (typeof actor == "function") {

       let instance;

       try {

         instance = new actor();

       } catch (e) {

         this.transport.send(this._unknownError(

           "Error occurred while creating actor '" + actor.name,

           e));

       }

       instance.parentID = actor.parentID;

       // We want the newly-constructed actor to completely replace the factory

       // actor. Reusing the existing actor ID will make sure ActorPool.addActor

       // does the right thing.

       instance.actorID = actor.actorID;

       actor.registeredPool.addActor(instance);

       actor = instance;

     }

     var ret = null;

     // handle "requestTypes" RDP request.

     if (aPacket.type == "requestTypes") {

       ret = { from: actor.actorID, requestTypes: Object.keys(actor.requestTypes) };

     } else if (actor.requestTypes && actor.requestTypes[aPacket.type]) {

       // Dispatch the request to the actor.

       try {

         this.currentPacket = aPacket;

         ret = actor.requestTypes[aPacket.type].bind(actor)(aPacket, this);

       } catch(e) {

         this.transport.send(this._unknownError(

           "error occurred while processing '" + aPacket.type,

           e));

       } finally {

         this.currentPacket = undefined;

       }

     } else {

       ret = { error: "unrecognizedPacketType",

               message: ('Actor "' + actor.actorID +

                         '" does not recognize the packet type "' +

                         aPacket.type + '"') };

     }

     if (!ret) {

       // This should become an error once we've converted every user

       // of this to promises in bug 794078.

       return;

     }

     let pendingResponse = this._actorResponses.get(actor.actorID) || resolve(null);

     let response = pendingResponse.then(() => {

       return ret;

     }).then(aResponse => {

       if (!aResponse.from) {

         aResponse.from = aPacket.to;

       }

       this.transport.send(aResponse);

     }).then(null, (e) => {

       let errorPacket = this._unknownError(

         "error occurred while processing '" + aPacket.type,

         e);

       errorPacket.from = aPacket.to;

       this.transport.send(errorPacket);

     });

     this._actorResponses.set(actor.actorID, response);

   },

   /**

    * Called by DebuggerTransport when the underlying stream is closed.

    *

    * @param aStatus nsresult

    *        The status code that corresponds to the reason for closing

    *        the stream.

    */

   onClosed: function DSC_onClosed(aStatus) {

     dumpn("Cleaning up connection.");

     if (!this._actorPool) {

       // Ignore this call if the connection is already closed.

       return;

     }

     events.emit(this, "closed", aStatus);

     this._actorPool.cleanup();

     this._actorPool = null;

     this._extraPools.map(function(p) { p.cleanup(); });

     this._extraPools = null;

     DebuggerServer._connectionClosed(this);

   },

   /*

    * Debugging helper for inspecting the state of the actor pools.

    */

   _dumpPools: function DSC_dumpPools() {

     dumpn("/-------------------- dumping pools:");

     if (this._actorPool) {

       dumpn("--------------------- actorPool actors: " +

             uneval(Object.keys(this._actorPool._actors)));

     }

     for each (let pool in this._extraPools)

       dumpn("--------------------- extraPool actors: " +

             uneval(Object.keys(pool._actors)));

   },

   /*

    * Debugging helper for inspecting the state of an actor pool.

    */

   _dumpPool: function DSC_dumpPools(aPool) {

     dumpn("/-------------------- dumping pool:");

     dumpn("--------------------- actorPool actors: " +

           uneval(Object.keys(aPool._actors)));

   }

 };

 /**

  * Localization convenience methods.

  */

 let L10N = {

   /**

    * L10N shortcut function.

    *

    * @param string aName

    * @return string

    */

   getStr: function L10N_getStr(aName) {

     return this.stringBundle.GetStringFromName(aName);

   }

 };

 XPCOMUtils.defineLazyGetter(L10N, "stringBundle", function() {

   return Services.strings.createBundle(DBG_STRINGS_URI);

 });