diff -r 000000000000 -r 6474c204b198 toolkit/devtools/server/main.js --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/toolkit/devtools/server/main.js Wed Dec 31 06:09:35 2014 +0100 @@ -0,0 +1,1203 @@ +/* -*- 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::packet", and all its actors will have names + * beginning with ":". + */ + 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); +});