devtools/server/devtools-server.js

   1 /* This Source Code Form is subject to the terms of the Mozilla Public
   2  * License, v. 2.0. If a copy of the MPL was not distributed with this
   3  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   4
   5 "use strict";
   6
   7 var {
   8   ActorRegistry,
   9 } = require("resource://devtools/server/actors/utils/actor-registry.js");
  10 var DevToolsUtils = require("resource://devtools/shared/DevToolsUtils.js");
  11 var { dumpn } = DevToolsUtils;
  12
  13 loader.lazyRequireGetter(
  14   this,
  15   "DevToolsServerConnection",
  16   "resource://devtools/server/devtools-server-connection.js",
  17   true
  18 );
  19 loader.lazyRequireGetter(
  20   this,
  21   "Authentication",
  22   "resource://devtools/shared/security/auth.js"
  23 );
  24 loader.lazyRequireGetter(
  25   this,
  26   "LocalDebuggerTransport",
  27   "resource://devtools/shared/transport/local-transport.js",
  28   true
  29 );
  30 loader.lazyRequireGetter(
  31   this,
  32   "ChildDebuggerTransport",
  33   "resource://devtools/shared/transport/child-transport.js",
  34   true
  35 );
  36 loader.lazyRequireGetter(
  37   this,
  38   "JsWindowActorTransport",
  39   "resource://devtools/shared/transport/js-window-actor-transport.js",
  40   true
  41 );
  42 loader.lazyRequireGetter(
  43   this,
  44   "WorkerThreadWorkerDebuggerTransport",
  45   "resource://devtools/shared/transport/worker-transport.js",
  46   true
  47 );
  48
  49 const CONTENT_PROCESS_SERVER_STARTUP_SCRIPT =
  50   "resource://devtools/server/startup/content-process.js";
  51
  52 loader.lazyRequireGetter(
  53   this,
  54   "EventEmitter",
  55   "resource://devtools/shared/event-emitter.js"
  56 );
  57
  58 /**
  59  * DevToolsServer is a singleton that has several responsibilities. It will
  60  * register the DevTools server actors that are relevant to the context.
  61  * It can also create other DevToolsServer, that will live in the same
  62  * environment as the debugged target (content page, worker...).
  63  *
  64  * For instance a regular Toolbox will be linked to DevToolsClient connected to
  65  * a DevToolsServer running in the same process as the Toolbox (main process).
  66  * But another DevToolsServer will be created in the same process as the page
  67  * targeted by the Toolbox.
  68  *
  69  * Despite being a singleton, the DevToolsServer still has a lifecycle and a
  70  * state. When a consumer needs to spawn a DevToolsServer, the init() method
  71  * should be called. Then you should either call registerAllActors or
  72  * registerActors to setup the server.
  73  * When the server is no longer needed, destroy() should be called.
  74  *
  75  */
  76 var DevToolsServer = {
  77   _listeners: [],
  78   _initialized: false,
  79   // Map of global actor names to actor constructors.
  80   globalActorFactories: {},
  81   // Map of target-scoped actor names to actor constructors.
  82   targetScopedActorFactories: {},
  83
  84   LONG_STRING_LENGTH: 10000,
  85   LONG_STRING_INITIAL_LENGTH: 1000,
  86   LONG_STRING_READ_LENGTH: 65 * 1024,
  87
  88   /**
  89    * The windowtype of the chrome window to use for actors that use the global
  90    * window (i.e the global style editor). Set this to your main window type,
  91    * for example "navigator:browser".
  92    */
  93   chromeWindowType: "navigator:browser",
  94
  95   /**
  96    * Allow debugging chrome of (parent or child) processes.
  97    */
  98   allowChromeProcess: false,
  99
 100   /**
 101    * Flag used to check if the server can be destroyed when all connections have been
 102    * removed. Firefox on Android runs a single shared DevToolsServer, and should not be
 103    * closed even if no client is connected.
 104    */
 105   keepAlive: false,
 106
 107   /**
 108    * We run a special server in child process whose main actor is an instance
 109    * of WindowGlobalTargetActor, but that isn't a root actor. Instead there is no root
 110    * actor registered on DevToolsServer.
 111    */
 112   get rootlessServer() {
 113     return !this.createRootActor;
 114   },
 115
 116   /**
 117    * Initialize the devtools server.
 118    */
 119   init() {
 120     if (this.initialized) {
 121       return;
 122     }
 123
 124     this._connections = {};
 125     ActorRegistry.init(this._connections);
 126     this._nextConnID = 0;
 127
 128     this._initialized = true;
 129     this._onSocketListenerAccepted = this._onSocketListenerAccepted.bind(this);
 130
 131     if (!isWorker) {
 132       // Mochitests watch this observable in order to register the custom actor
 133       // highlighter-test-actor.js.
 134       // Services.obs is not available in workers.
 135       const subject = { wrappedJSObject: ActorRegistry };
 136       Services.obs.notifyObservers(subject, "devtools-server-initialized");
 137     }
 138   },
 139
 140   get protocol() {
 141     return require("resource://devtools/shared/protocol.js");
 142   },
 143
 144   get initialized() {
 145     return this._initialized;
 146   },
 147
 148   hasConnection() {
 149     return this._connections && !!Object.keys(this._connections).length;
 150   },
 151
 152   hasConnectionForPrefix(prefix) {
 153     return this._connections && !!this._connections[prefix + "/"];
 154   },
 155   /**
 156    * Performs cleanup tasks before shutting down the devtools server. Such tasks
 157    * include clearing any actor constructors added at runtime. This method
 158    * should be called whenever a devtools server is no longer useful, to avoid
 159    * memory leaks. After this method returns, the devtools server must be
 160    * initialized again before use.
 161    */
 162   destroy() {
 163     if (!this._initialized) {
 164       return;
 165     }
 166     this._initialized = false;
 167
 168     for (const connection of Object.values(this._connections)) {
 169       connection.close();
 170     }
 171
 172     ActorRegistry.destroy();
 173     this.closeAllSocketListeners();
 174
 175     // Unregister all listeners
 176     this.off("connectionchange");
 177
 178     dumpn("DevTools server is shut down.");
 179   },
 180
 181   /**
 182    * Raises an exception if the server has not been properly initialized.
 183    */
 184   _checkInit() {
 185     if (!this._initialized) {
 186       throw new Error("DevToolsServer has not been initialized.");
 187     }
 188
 189     if (!this.rootlessServer && !this.createRootActor) {
 190       throw new Error(
 191         "Use DevToolsServer.setRootActor() to add a root actor " +
 192           "implementation."
 193       );
 194     }
 195   },
 196
 197   /**
 198    * Register different type of actors. Only register the one that are not already
 199    * registered.
 200    *
 201    * @param root boolean
 202    *        Registers the root actor from webbrowser module, which is used to
 203    *        connect to and fetch any other actor.
 204    * @param browser boolean
 205    *        Registers all the parent process actors useful for debugging the
 206    *        runtime itself, like preferences and addons actors.
 207    * @param target boolean
 208    *        Registers all the target-scoped actors like console, script, etc.
 209    *        for debugging a target context.
 210    */
 211   registerActors({ root, browser, target }) {
 212     if (browser) {
 213       ActorRegistry.addBrowserActors();
 214     }
 215
 216     if (root) {
 217       const {
 218         createRootActor,
 219       } = require("resource://devtools/server/actors/webbrowser.js");
 220       this.setRootActor(createRootActor);
 221     }
 222
 223     if (target) {
 224       ActorRegistry.addTargetScopedActors();
 225     }
 226   },
 227
 228   /**
 229    * Register all possible actors for this DevToolsServer.
 230    */
 231   registerAllActors() {
 232     this.registerActors({ root: true, browser: true, target: true });
 233   },
 234
 235   get listeningSockets() {
 236     return this._listeners.length;
 237   },
 238
 239   /**
 240    * Add a SocketListener instance to the server's set of active
 241    * SocketListeners.  This is called by a SocketListener after it is opened.
 242    */
 243   addSocketListener(listener) {
 244     if (!Services.prefs.getBoolPref("devtools.debugger.remote-enabled")) {
 245       throw new Error("Can't add a SocketListener, remote debugging disabled");
 246     }
 247     this._checkInit();
 248
 249     listener.on("accepted", this._onSocketListenerAccepted);
 250     this._listeners.push(listener);
 251   },
 252
 253   /**
 254    * Remove a SocketListener instance from the server's set of active
 255    * SocketListeners.  This is called by a SocketListener after it is closed.
 256    */
 257   removeSocketListener(listener) {
 258     // Remove connections that were accepted in the listener.
 259     for (const connID of Object.getOwnPropertyNames(this._connections)) {
 260       const connection = this._connections[connID];
 261       if (connection.isAcceptedBy(listener)) {
 262         connection.close();
 263       }
 264     }
 265
 266     this._listeners = this._listeners.filter(l => l !== listener);
 267     listener.off("accepted", this._onSocketListenerAccepted);
 268   },
 269
 270   /**
 271    * Closes and forgets all previously opened listeners.
 272    *
 273    * @return boolean
 274    *         Whether any listeners were actually closed.
 275    */
 276   closeAllSocketListeners() {
 277     if (!this.listeningSockets) {
 278       return false;
 279     }
 280
 281     for (const listener of this._listeners) {
 282       listener.close();
 283     }
 284
 285     return true;
 286   },
 287
 288   _onSocketListenerAccepted(transport, listener) {
 289     this._onConnection(transport, null, false, listener);
 290   },
 291
 292   /**
 293    * Creates a new connection to the local debugger speaking over a fake
 294    * transport. This connection results in straightforward calls to the onPacket
 295    * handlers of each side.
 296    *
 297    * @param prefix string [optional]
 298    *    If given, all actors in this connection will have names starting
 299    *    with |prefix + '/'|.
 300    * @returns a client-side DebuggerTransport for communicating with
 301    *    the newly-created connection.
 302    */
 303   connectPipe(prefix) {
 304     this._checkInit();
 305
 306     const serverTransport = new LocalDebuggerTransport();
 307     const clientTransport = new LocalDebuggerTransport(serverTransport);
 308     serverTransport.other = clientTransport;
 309     const connection = this._onConnection(serverTransport, prefix);
 310
 311     // I'm putting this here because I trust you.
 312     //
 313     // There are times, when using a local connection, when you're going
 314     // to be tempted to just get direct access to the server.  Resist that
 315     // temptation!  If you succumb to that temptation, you will make the
 316     // fine developers that work on Fennec and Firefox OS sad.  They're
 317     // professionals, they'll try to act like they understand, but deep
 318     // down you'll know that you hurt them.
 319     //
 320     // This reference allows you to give in to that temptation.  There are
 321     // times this makes sense: tests, for example, and while porting a
 322     // previously local-only codebase to the remote protocol.
 323     //
 324     // But every time you use this, you will feel the shame of having
 325     // used a property that starts with a '_'.
 326     clientTransport._serverConnection = connection;
 327
 328     return clientTransport;
 329   },
 330
 331   /**
 332    * In a content child process, create a new connection that exchanges
 333    * nsIMessageSender messages with our parent process.
 334    *
 335    * @param prefix
 336    *    The prefix we should use in our nsIMessageSender message names and
 337    *    actor names. This connection will use messages named
 338    *    "debug:<prefix>:packet", and all its actors will have names
 339    *    beginning with "<prefix>/".
 340    */
 341   connectToParent(prefix, scopeOrManager) {
 342     this._checkInit();
 343
 344     const transport = isWorker
 345       ? new WorkerThreadWorkerDebuggerTransport(scopeOrManager, prefix)
 346       : new ChildDebuggerTransport(scopeOrManager, prefix);
 347
 348     return this._onConnection(transport, prefix, true);
 349   },
 350
 351   connectToParentWindowActor(jsWindowChildActor, forwardingPrefix) {
 352     this._checkInit();
 353     const transport = new JsWindowActorTransport(
 354       jsWindowChildActor,
 355       forwardingPrefix
 356     );
 357
 358     return this._onConnection(transport, forwardingPrefix, true);
 359   },
 360
 361   /**
 362    * Check if the server is running in the child process.
 363    */
 364   get isInChildProcess() {
 365     return (
 366       Services.appinfo.processType != Ci.nsIXULRuntime.PROCESS_TYPE_DEFAULT
 367     );
 368   },
 369
 370   /**
 371    * Create a new debugger connection for the given transport. Called after
 372    * connectPipe(), from connectToParent, or from an incoming socket
 373    * connection handler.
 374    *
 375    * If present, |forwardingPrefix| is a forwarding prefix that a parent
 376    * server is using to recognizes messages intended for this server. Ensure
 377    * that all our actors have names beginning with |forwardingPrefix + '/'|.
 378    * In particular, the root actor's name will be |forwardingPrefix + '/root'|.
 379    */
 380   _onConnection(
 381     transport,
 382     forwardingPrefix,
 383     noRootActor = false,
 384     socketListener = null
 385   ) {
 386     let connID;
 387     if (forwardingPrefix) {
 388       connID = forwardingPrefix + "/";
 389     } else {
 390       // Multiple servers can be started at the same time, and when that's the
 391       // case, they are loaded in separate devtools loaders.
 392       // So, use the current loader ID to prefix the connection ID and make it
 393       // unique.
 394       connID = "server" + loader.id + ".conn" + this._nextConnID++ + ".";
 395     }
 396
 397     // Notify the platform code that DevTools is running in the current process
 398     // when we are wiring the very first connection
 399     if (!this.hasConnection()) {
 400       ChromeUtils.notifyDevToolsOpened();
 401     }
 402
 403     const conn = new DevToolsServerConnection(
 404       connID,
 405       transport,
 406       socketListener
 407     );
 408     this._connections[connID] = conn;
 409
 410     // Create a root actor for the connection and send the hello packet.
 411     if (!noRootActor) {
 412       conn.rootActor = this.createRootActor(conn);
 413       if (forwardingPrefix) {
 414         conn.rootActor.actorID = forwardingPrefix + "/root";
 415       } else {
 416         conn.rootActor.actorID = "root";
 417       }
 418       conn.addActor(conn.rootActor);
 419       transport.send(conn.rootActor.sayHello());
 420     }
 421     transport.ready();
 422
 423     this.emit("connectionchange", "opened", conn);
 424     return conn;
 425   },
 426
 427   /**
 428    * Remove the connection from the debugging server.
 429    */
 430   _connectionClosed(connection) {
 431     delete this._connections[connection.prefix];
 432     this.emit("connectionchange", "closed", connection);
 433
 434     const hasConnection = this.hasConnection();
 435
 436     // Notify the platform code that we stopped running DevTools code in the current process
 437     if (!hasConnection) {
 438       ChromeUtils.notifyDevToolsClosed();
 439     }
 440
 441     // If keepAlive isn't explicitely set to true, destroy the server once its
 442     // last connection closes. Multiple JSWindowActor may use the same DevToolsServer
 443     // and in this case, let the server destroy itself once the last connection closes.
 444     // Otherwise we set keepAlive to true when starting a listening server, receiving
 445     // client connections. Typically when running server on phones, or on desktop
 446     // via `--start-debugger-server`.
 447     if (hasConnection || this.keepAlive) {
 448       return;
 449     }
 450
 451     this.destroy();
 452   },
 453
 454   // DevToolsServer extension API.
 455
 456   setRootActor(actorFactory) {
 457     this.createRootActor = actorFactory;
 458   },
 459
 460   /**
 461    * Called when DevTools are unloaded to remove the contend process server startup script
 462    * for the list of scripts loaded for each new content process. Will also remove message
 463    * listeners from already loaded scripts.
 464    */
 465   removeContentServerScript() {
 466     Services.ppmm.removeDelayedProcessScript(
 467       CONTENT_PROCESS_SERVER_STARTUP_SCRIPT
 468     );
 469     try {
 470       Services.ppmm.broadcastAsyncMessage("debug:close-content-server");
 471     } catch (e) {
 472       // Nothing to do
 473     }
 474   },
 475
 476   /**
 477    * Searches all active connections for an actor matching an ID.
 478    *
 479    * ⚠ TO BE USED ONLY FROM SERVER CODE OR TESTING ONLY! ⚠`
 480    *
 481    * This is helpful for some tests which depend on reaching into the server to check some
 482    * properties of an actor, and it is also used by the actors related to the
 483    * DevTools WebExtensions API to be able to interact with the actors created for the
 484    * panels natively provided by the DevTools Toolbox.
 485    */
 486   searchAllConnectionsForActor(actorID) {
 487     // NOTE: the actor IDs are generated with the following format:
 488     //
 489     //   `server${loaderID}.conn${ConnectionID}${ActorPrefix}${ActorID}`
 490     //
 491     // as an optimization we can come up with a regexp to query only
 492     // the right connection via its id.
 493     for (const connID of Object.getOwnPropertyNames(this._connections)) {
 494       const actor = this._connections[connID].getActor(actorID);
 495       if (actor) {
 496         return actor;
 497       }
 498     }
 499     return null;
 500   },
 501 };
 502
 503 // Expose these to save callers the trouble of importing DebuggerSocket
 504 DevToolsUtils.defineLazyGetter(DevToolsServer, "Authenticators", () => {
 505   return Authentication.Authenticators;
 506 });
 507 DevToolsUtils.defineLazyGetter(DevToolsServer, "AuthenticationResult", () => {
 508   return Authentication.AuthenticationResult;
 509 });
 510
 511 EventEmitter.decorate(DevToolsServer);
 512
 513 exports.DevToolsServer = DevToolsServer;