tor-browser

ext-devtools.js (16256B)

---

/* -*- Mode: indent-tabs-mode: nil; js-indent-level: 2 -*- */
/* vim: set sts=2 sw=2 et 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";

/**
* This module provides helpers used by the other specialized `ext-devtools-*.js` modules
* and the implementation of the `devtools_page`.
*/

ChromeUtils.defineESModuleGetters(this, {
 DevToolsShim: "chrome://devtools-startup/content/DevToolsShim.sys.mjs",
});

var { ExtensionParent } = ChromeUtils.importESModule(
 "resource://gre/modules/ExtensionParent.sys.mjs"
);

var { HiddenExtensionPage, watchExtensionProxyContextLoad } = ExtensionParent;

// Get the devtools preference given the extension id.
function getDevToolsPrefBranchName(extensionId) {
 return `devtools.webextensions.${extensionId}`;
}

/**
* Retrieve the tabId for the given devtools toolbox.
*
* @param {Toolbox} toolbox
*   A devtools toolbox instance.
*
* @returns {number}
*   The corresponding WebExtensions tabId.
*/
global.getTargetTabIdForToolbox = toolbox => {
 let { descriptorFront } = toolbox.commands;

 if (!descriptorFront.isLocalTab) {
   throw new Error(
     "Unexpected target type: only local tabs are currently supported."
   );
 }

 let parentWindow = descriptorFront.localTab.linkedBrowser.ownerGlobal;
 let tab = parentWindow.gBrowser.getTabForBrowser(
   descriptorFront.localTab.linkedBrowser
 );

 return tabTracker.getId(tab);
};

// Get the WebExtensionInspectedWindowActor eval options (needed to provide the $0 and inspect
// binding provided to the evaluated js code).
global.getToolboxEvalOptions = async function (context) {
 const options = {};
 const toolbox = context.devToolsToolbox;
 const selectedNode = toolbox.selection;

 if (selectedNode && selectedNode.nodeFront) {
   // If there is a selected node in the inspector, we hand over
   // its actor id to the eval request in order to provide the "$0" binding.
   options.toolboxSelectedNodeActorID = selectedNode.nodeFront.actorID;
 }

 // Provide the console actor ID to implement the "inspect" binding.
 const consoleFront = await toolbox.target.getFront("console");
 options.toolboxConsoleActorID = consoleFront.actor;

 return options;
};

/**
* The DevToolsPage represents the "devtools_page" related to a particular
* Toolbox and WebExtension.
*
* The devtools_page contexts are invisible WebExtensions contexts, similar to the
* background page, associated to a single developer toolbox (e.g. If an add-on
* registers a devtools_page and the user opens 3 developer toolbox in 3 webpages,
* 3 devtools_page contexts will be created for that add-on).
*
* @param {Extension}              extension
*   The extension that owns the devtools_page.
* @param {object}                 options
* @param {Toolbox}                options.toolbox
*   The developer toolbox instance related to this devtools_page.
* @param {string}                 options.url
*   The path to the devtools page html page relative to the extension base URL.
* @param {DevToolsPageDefinition} options.devToolsPageDefinition
*   The instance of the devToolsPageDefinition class related to this DevToolsPage.
*/
class DevToolsPage extends HiddenExtensionPage {
 constructor(extension, options) {
   super(extension, "devtools_page");

   this.url = extension.baseURI.resolve(options.url);
   this.toolbox = options.toolbox;
   this.devToolsPageDefinition = options.devToolsPageDefinition;

   this.unwatchExtensionProxyContextLoad = null;

   this.waitForTopLevelContext = new Promise(resolve => {
     this.resolveTopLevelContext = resolve;
   });
 }

 async build() {
   await this.createBrowserElement();

   // Listening to new proxy contexts.
   this.unwatchExtensionProxyContextLoad = watchExtensionProxyContextLoad(
     this,
     context => {
       // Keep track of the toolbox and target associated to the context, which is
       // needed by the API methods implementation.
       context.devToolsToolbox = this.toolbox;

       if (!this.topLevelContext) {
         this.topLevelContext = context;

         // Ensure this devtools page is destroyed, when the top level context proxy is
         // closed.
         this.topLevelContext.callOnClose(this);

         this.resolveTopLevelContext(context);
       }
     }
   );

   extensions.emit("extension-browser-inserted", this.browser, {
     devtoolsToolboxInfo: {
       inspectedWindowTabId: getTargetTabIdForToolbox(this.toolbox),
       themeName: DevToolsShim.getTheme(),
     },
   });

   this.browser.fixupAndLoadURIString(this.url, {
     triggeringPrincipal: this.extension.principal,
   });

   await this.waitForTopLevelContext;
 }

 close() {
   if (this.closed) {
     throw new Error("Unable to shutdown a closed DevToolsPage instance");
   }

   this.closed = true;

   // Unregister the devtools page instance from the devtools page definition.
   this.devToolsPageDefinition.forgetForToolbox(this.toolbox);

   // Unregister it from the resources to cleanup when the context has been closed.
   if (this.topLevelContext) {
     this.topLevelContext.forgetOnClose(this);
   }

   // Stop watching for any new proxy contexts from the devtools page.
   if (this.unwatchExtensionProxyContextLoad) {
     this.unwatchExtensionProxyContextLoad();
     this.unwatchExtensionProxyContextLoad = null;
   }

   super.shutdown();
 }
}

/**
* The DevToolsPageDefinitions class represents the "devtools_page" manifest property
* of a WebExtension.
*
* A DevToolsPageDefinition instance is created automatically when a WebExtension
* which contains the "devtools_page" manifest property has been loaded, and it is
* automatically destroyed when the related WebExtension has been unloaded,
* and so there will be at most one DevtoolsPageDefinition per add-on.
*
* Every time a developer tools toolbox is opened, the DevToolsPageDefinition creates
* and keep track of a DevToolsPage instance (which represents the actual devtools_page
* instance related to that particular toolbox).
*
* @param {Extension} extension
*   The extension that owns the devtools_page.
* @param {string}    url
*   The path to the devtools page html page relative to the extension base URL.
*/
class DevToolsPageDefinition {
 constructor(extension, url) {
   this.url = url;
   this.extension = extension;

   // Map[Toolbox -> DevToolsPage]
   this.devtoolsPageForToolbox = new Map();
 }

 onThemeChanged(themeName) {
   Services.ppmm.broadcastAsyncMessage("Extension:DevToolsThemeChanged", {
     themeName,
   });
 }

 buildForToolbox(toolbox) {
   if (
     !this.extension.canAccessWindow(
       toolbox.commands.descriptorFront.localTab.ownerGlobal
     )
   ) {
     // We should never create a devtools page for a toolbox related to a private browsing window
     // if the extension is not allowed to access it.
     return;
   }

   if (this.devtoolsPageForToolbox.has(toolbox)) {
     return Promise.reject(
       new Error("DevtoolsPage has been already created for this toolbox")
     );
   }

   const devtoolsPage = new DevToolsPage(this.extension, {
     toolbox,
     url: this.url,
     devToolsPageDefinition: this,
   });

   // If this is the first DevToolsPage, subscribe to the theme-changed event
   if (this.devtoolsPageForToolbox.size === 0) {
     DevToolsShim.on("theme-changed", this.onThemeChanged);
   }
   this.devtoolsPageForToolbox.set(toolbox, devtoolsPage);

   return devtoolsPage.build();
 }

 shutdownForToolbox(toolbox) {
   if (this.devtoolsPageForToolbox.has(toolbox)) {
     const devtoolsPage = this.devtoolsPageForToolbox.get(toolbox);
     devtoolsPage.close();

     // `devtoolsPage.close()` should remove the instance from the map,
     // raise an exception if it is still there.
     if (this.devtoolsPageForToolbox.has(toolbox)) {
       throw new Error(
         `Leaked DevToolsPage instance for target "${toolbox.commands.descriptorFront.url}", extension "${this.extension.policy.debugName}"`
       );
     }

     // If this was the last DevToolsPage, unsubscribe from the theme-changed event
     if (this.devtoolsPageForToolbox.size === 0) {
       DevToolsShim.off("theme-changed", this.onThemeChanged);
     }
     this.extension.emit("devtools-page-shutdown", toolbox);
   }
 }

 forgetForToolbox(toolbox) {
   this.devtoolsPageForToolbox.delete(toolbox);
 }

 /**
  * Build the devtools_page instances for all the existing toolboxes
  * (if the toolbox target is supported).
  */
 build() {
   // Iterate over the existing toolboxes and create the devtools page for them
   // (if the toolbox target is supported).
   for (let toolbox of DevToolsShim.getToolboxes()) {
     if (
       // Skip toolboxes in the middle of their destroy sequence (fully
       // destroyed will not be returned by getToolboxes()).
       toolbox.isDestroying() ||
       // Skip remote / non-web toolboxes (ie. target is not a local tab).
       !toolbox.commands.descriptorFront.isLocalTab ||
       // Skip private browsing windows if the extension is not allowed to
       // access them.
       !this.extension.canAccessWindow(
         toolbox.commands.descriptorFront.localTab.ownerGlobal
       )
     ) {
       continue;
     }

     // Ensure that the WebExtension is listed in the toolbox options.
     toolbox.registerWebExtension(this.extension.uuid, {
       name: this.extension.name,
       pref: `${getDevToolsPrefBranchName(this.extension.id)}.enabled`,
     });

     this.buildForToolbox(toolbox);
   }
 }

 /**
  * Shutdown all the devtools_page instances.
  */
 shutdown() {
   for (let toolbox of this.devtoolsPageForToolbox.keys()) {
     this.shutdownForToolbox(toolbox);
   }

   if (this.devtoolsPageForToolbox.size > 0) {
     throw new Error(
       `Leaked ${this.devtoolsPageForToolbox.size} DevToolsPage instances in devtoolsPageForToolbox Map`
     );
   }
 }
}

this.devtools = class extends ExtensionAPI {
 constructor(extension) {
   super(extension);

   this._initialized = false;

   // DevToolsPageDefinition instance (created in onManifestEntry).
   this.pageDefinition = null;

   this.onToolboxReady = this.onToolboxReady.bind(this);
   this.onToolboxDestroy = this.onToolboxDestroy.bind(this);

   /* eslint-disable mozilla/balanced-listeners */
   extension.on("add-permissions", (ignoreEvent, permissions) => {
     if (permissions.permissions.includes("devtools")) {
       Services.prefs.setBoolPref(
         `${getDevToolsPrefBranchName(extension.id)}.enabled`,
         true
       );

       this._initialize();
     }
   });

   extension.on("remove-permissions", (ignoreEvent, permissions) => {
     if (permissions.permissions.includes("devtools")) {
       Services.prefs.setBoolPref(
         `${getDevToolsPrefBranchName(extension.id)}.enabled`,
         false
       );

       this._uninitialize();
     }
   });
 }

 onManifestEntry() {
   this._initialize();
 }

 static onUninstall(extensionId) {
   // Remove the preference branch on uninstall.
   const prefBranch = Services.prefs.getBranch(
     `${getDevToolsPrefBranchName(extensionId)}.`
   );

   prefBranch.deleteBranch("");
 }

 _initialize() {
   const { extension } = this;

   if (!extension.hasPermission("devtools") || this._initialized) {
     return;
   }

   this.initDevToolsPref();

   // Create the devtools_page definition.
   this.pageDefinition = new DevToolsPageDefinition(
     extension,
     extension.manifest.devtools_page
   );

   // Build the extension devtools_page on all existing toolboxes (if the extension
   // devtools_page is not disabled by the related preference).
   if (!this.isDevToolsPageDisabled()) {
     this.pageDefinition.build();
   }

   DevToolsShim.on("toolbox-ready", this.onToolboxReady);
   DevToolsShim.on("toolbox-destroy", this.onToolboxDestroy);
   this._initialized = true;
 }

 _uninitialize() {
   // devtoolsPrefBranch is set in onManifestEntry, and nullified
   // later in onShutdown.  If it isn't set, then onManifestEntry
   // did not initialize devtools for the extension.
   if (!this._initialized) {
     return;
   }

   DevToolsShim.off("toolbox-ready", this.onToolboxReady);
   DevToolsShim.off("toolbox-destroy", this.onToolboxDestroy);

   // Shutdown the extension devtools_page from all existing toolboxes.
   this.pageDefinition.shutdown();
   this.pageDefinition = null;

   // Iterate over the existing toolboxes and unlist the devtools webextension from them.
   for (let toolbox of DevToolsShim.getToolboxes()) {
     toolbox.unregisterWebExtension(this.extension.uuid);
   }

   this.uninitDevToolsPref();
   this._initialized = false;
 }

 onShutdown() {
   this._uninitialize();
 }

 getAPI() {
   return {
     devtools: {},
   };
 }

 onToolboxReady(toolbox) {
   if (
     !toolbox.commands.descriptorFront.isLocalTab ||
     !this.extension.canAccessWindow(
       toolbox.commands.descriptorFront.localTab.ownerGlobal
     )
   ) {
     // Skip any non-local (as remote tabs are not yet supported, see Bug 1304378 for additional details
     // related to remote targets support), and private browsing windows if the extension
     // is not allowed to access them.
     return;
   }

   // Ensure that the WebExtension is listed in the toolbox options.
   toolbox.registerWebExtension(this.extension.uuid, {
     name: this.extension.name,
     pref: `${getDevToolsPrefBranchName(this.extension.id)}.enabled`,
   });

   // Do not build the devtools page if the extension has been disabled
   // (e.g. based on the devtools preference).
   if (toolbox.isWebExtensionEnabled(this.extension.uuid)) {
     this.pageDefinition.buildForToolbox(toolbox);
   }
 }

 onToolboxDestroy(toolbox) {
   if (!toolbox.commands.descriptorFront.isLocalTab) {
     // Only local tabs are currently supported (See Bug 1304378 for additional details
     // related to remote targets support).
     return;
   }

   this.pageDefinition.shutdownForToolbox(toolbox);
 }

 /**
  * Initialize the DevTools preferences branch for the extension and
  * start to observe it for changes on the "enabled" preference.
  */
 initDevToolsPref() {
   const prefBranch = Services.prefs.getBranch(
     `${getDevToolsPrefBranchName(this.extension.id)}.`
   );

   // Initialize the devtools extension preference if it doesn't exist yet.
   if (prefBranch.getPrefType("enabled") === prefBranch.PREF_INVALID) {
     prefBranch.setBoolPref("enabled", true);
   }

   this.devtoolsPrefBranch = prefBranch;
   this.devtoolsPrefBranch.addObserver("enabled", this);
 }

 /**
  * Stop from observing the DevTools preferences branch for the extension.
  */
 uninitDevToolsPref() {
   this.devtoolsPrefBranch.removeObserver("enabled", this);
   this.devtoolsPrefBranch = null;
 }

 /**
  * Test if the extension's devtools_page has been disabled using the
  * DevTools preference.
  *
  * @returns {boolean}
  *          true if the devtools_page for this extension is disabled.
  */
 isDevToolsPageDisabled() {
   return !this.devtoolsPrefBranch.getBoolPref("enabled", false);
 }

 /**
  * Observes the changed preferences on the DevTools preferences branch
  * related to the extension.
  *
  * @param {nsIPrefBranch} subject  The observed preferences branch.
  * @param {string}        topic    The notified topic.
  * @param {string}        prefName The changed preference name.
  */
 observe(subject, topic, prefName) {
   // We are currently interested only in the "enabled" preference from the
   // WebExtension devtools preferences branch.
   if (subject !== this.devtoolsPrefBranch || prefName !== "enabled") {
     return;
   }

   // Shutdown or build the devtools_page on any existing toolbox.
   if (this.isDevToolsPageDisabled()) {
     this.pageDefinition.shutdown();
   } else {
     this.pageDefinition.build();
   }
 }
};