tor-browser

manager.js (30665B)

---

/* This Smurce 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";

loader.lazyRequireGetter(
 this,
 ["getCommandAndArgs"],
 "resource://devtools/server/actors/webconsole/commands/parser.js",
 true
);

loader.lazyGetter(this, "l10n", () => {
 return new Localization(
   [
     "devtools/shared/webconsole-commands.ftl",
     "devtools/server/actors/webconsole/commands/experimental-commands.ftl",
   ],
   true
 );
});

const lazy = {};
ChromeUtils.defineESModuleGetters(
 lazy,
 {
   JSTracer: "resource://devtools/server/tracer/tracer.sys.mjs",
 },
 { global: "contextual" }
);

const USAGE_STRING_MAPPING = {
 block: "webconsole-commands-usage-block",
 trace: "webconsole-commands-usage-trace3",
 unblock: "webconsole-commands-usage-unblock",
};

/**
* WebConsole commands manager.
*
* Defines a set of functions / variables ("commands") that are available from
* the Web Console but not from the web page.
*
*/
const WebConsoleCommandsManager = {
 // Flag used by eager evaluation in order to allow the execution of commands
 // which are side effect free and disallow all the others.
 SIDE_EFFECT_FREE: Symbol("SIDE_EFFECT_FREE"),

 // Map of command name to command function or property descriptor (see register method)
 _registeredCommands: new Map(),
 // Map of command name to optional array of accepted argument names
 _validArguments: new Map(),
 // Set of command names that are side effect free
 _sideEffectFreeCommands: new Set(),

 /**
  * Register a new command.
  *
  * @param {object} options
  * @param {string} options.name
  *        The command name (exemple: "$", "screenshot",...))
  * @param {boolean} isSideEffectFree
  *        Tells if the command is free of any side effect to know
  *        if it can run in eager console evaluation.
  * @param {function|object} options.command
  *        The command to register.
  *        It can be:
  *          - a function for the command like "$()" or ":screenshot"
  *            which triggers some code.
  *          - a property descriptor for getters like "$0",
  *            which only returns a value.
  * @param {Array<string>} options.validArguments
  *        Optional list of valid arguments.
  *        If passed, we will assert that passed arguments are all valid on execution.
  *
  *  The command function or the command getter are passed a:
  *   - "owner" object as their first parameter (see the example below).
  *     See _createOwnerObject for definition.
  *   - "args" object with all parameters when this is ran as a ":my-command" command.
  *     See getCommandAndArgs for definition.
  *
  * Note that if you want to support `--help` argument, you need to provide a usage string in:
  * devtools/shared/locales/en-US/webconsole-commands.properties
  *
  * @example
  *
  *   WebConsoleCommandsManager.register("$", function (owner, selector)
  *   {
  *     return owner.window.document.querySelector(selector);
  *   },
  *   ["my-argument"]);
  *
  *   WebConsoleCommandsManager.register("$0", {
  *     get: function(owner) {
  *       return owner.makeDebuggeeValue(owner.selectedNode);
  *     }
  *   });
  */
 register({ name, isSideEffectFree, command, validArguments }) {
   if (
     typeof command != "function" &&
     !(typeof command == "object" && typeof command.get == "function")
   ) {
     throw new Error(
       "Invalid web console command. It can only be a function, or an object with a function as 'get' attribute"
     );
   }
   if (typeof isSideEffectFree !== "boolean") {
     throw new Error(
       "Invalid web console command. 'isSideEffectFree' attribute should be set and be a boolean"
     );
   }
   this._registeredCommands.set(name, command);
   if (validArguments) {
     this._validArguments.set(name, validArguments);
   }
   if (isSideEffectFree) {
     this._sideEffectFreeCommands.add(name);
   }
 },

 /**
  * Return the name of all registered commands.
  *
  * @return {Array} List of all command names.
  */
 getAllCommandNames() {
   return [...this._registeredCommands.keys()];
 },

 /**
  * There is two types of "commands" here.
  *
  * - Functions or variables exposed in the scope of the evaluated string from the WebConsole input.
  *   Example: $(), $0, copy(), clear(),...
  * - "True commands", which can also be ran from the WebConsole input with ":" prefix.
  *   Example: this list of commands.
  *   Note that some "true commands" are not exposed as function (see getColonOnlyCommandNames).
  *
  * The following list distinguish these "true commands" from the first category.
  * It especially avoid any JavaScript evaluation when the frontend tries to execute
  * a string starting with ':' character.
  */
 getAllColonCommandNames() {
   return ["block", "help", "history", "screenshot", "unblock", "trace"];
 },

 /**
  * Some commands are not exposed in the scope of the evaluated string,
  * and can only be used via `:command-name`.
  */
 getColonOnlyCommandNames() {
   return ["screenshot", "trace"];
 },

 /**
  * Map of all command objects keyed by command name.
  * Commands object are the objects passed to register() method.
  *
  * @return {Map<string -> command>}
  */
 getAllCommands() {
   return this._registeredCommands;
 },

 /**
  * Is the command name possibly overriding a symbol which
  * already exists in the paused frame or the global into which
  * we are about to execute into?
  */
 _isCommandNameAlreadyInScope(name, frame, dbgGlobal) {
   if (frame && frame.environment) {
     return !!frame.environment.find(name);
   }

   // Fallback on global scope when Debugger.Frame doesn't come along an
   // Environment, or is not a frame.

   try {
     // This can throw in Browser Toolbox tests
     const globalEnv = dbgGlobal.asEnvironment();
     if (globalEnv) {
       return !!dbgGlobal.asEnvironment().find(name);
     }
   } catch {}

   return !!dbgGlobal.getOwnPropertyDescriptor(name);
 },

 _createOwnerObject(
   consoleActor,
   debuggerGlobal,
   evalInput,
   selectedNodeActorID
 ) {
   const owner = {
     window: consoleActor.evalGlobal,
     makeDebuggeeValue: debuggerGlobal.makeDebuggeeValue.bind(debuggerGlobal),
     createValueGrip: consoleActor.createValueGrip.bind(consoleActor),
     preprocessDebuggerObject:
       consoleActor.preprocessDebuggerObject.bind(consoleActor),
     helperResult: null,
     consoleActor,
     evalInput,
   };
   if (selectedNodeActorID) {
     const actor = consoleActor.conn.getActor(selectedNodeActorID);
     if (actor) {
       owner.selectedNode = actor.rawNode;
     }
   }
   return owner;
 },

 _getCommandsForCurrentEnvironment() {
   // Not supporting extra commands in workers yet.  This should be possible to
   // add one by one as long as they don't require jsm/mjs, Cu, etc.
   return isWorker ? new Map() : this.getAllCommands();
 },

 /**
  * Create an object with the API we expose to the Web Console during
  * JavaScript evaluation.
  * This object inherits properties and methods from the Web Console actor.
  *
  * @param object consoleActor
  *        The related web console actor evaluating some code.
  * @param object debuggerGlobal
  *        A Debugger.Object that wraps a content global. This is used for the
  *        Web Console Commands.
  * @param object frame (optional)
  *        The frame where the string was evaluated.
  * @param string evalInput
  *        String to evaluate.
  * @param string selectedNodeActorID
  *        The Node actor ID of the currently selected DOM Element, if any is selected.
  * @param bool preferConsoleCommandsOverLocalSymbols
  *        If true, define all bindings even if there's conflicting existing
  *        symbols.  This is for the case evaluating non-user code in frame
  *        environment.
  *
  * @return object
  *         Object with two properties:
  *         - 'bindings', the object with all commands set as attribute on this object.
  *         - 'getHelperResult', a live getter returning the additional data the last command
  *           which executed want to convey to the frontend.
  *           (The return value of commands isn't returned to the client but it only
  *            returned to the code ran from console evaluation)
  */
 getWebConsoleCommands(
   consoleActor,
   debuggerGlobal,
   frame,
   evalInput,
   selectedNodeActorID,
   preferConsoleCommandsOverLocalSymbols
 ) {
   const bindings = Object.create(null);

   const owner = this._createOwnerObject(
     consoleActor,
     debuggerGlobal,
     evalInput,
     selectedNodeActorID
   );

   const evalGlobal = consoleActor.evalGlobal;
   function maybeExport(obj, name) {
     if (typeof obj[name] != "function") {
       return;
     }

     // By default, chrome-implemented functions that are exposed to content
     // refuse to accept arguments that are cross-origin for the caller. This
     // is generally the safe thing, but causes problems for certain console
     // helpers like cd(), where we users sometimes want to pass a cross-origin
     // window. To circumvent this restriction, we use exportFunction along
     // with a special option designed for this purpose. See bug 1051224.
     obj[name] = Cu.exportFunction(obj[name], evalGlobal, {
       allowCrossOriginArguments: true,
     });
   }

   const commands = this._getCommandsForCurrentEnvironment();

   const colonOnlyCommandNames = this.getColonOnlyCommandNames();
   for (const [name, command] of commands) {
     // When we run user code in frame, we want to avoid overriding existing
     // symbols with commands.
     //
     // When we run user code in global scope, all bindings are automatically
     // shadowed, except for "help" function which is checked by getEvalInput.
     //
     // When preferConsoleCommandsOverLocalSymbols is true, ignore symbols in
     // the current scope and always use commands ones.
     if (
       !preferConsoleCommandsOverLocalSymbols &&
       (frame || name === "help") &&
       this._isCommandNameAlreadyInScope(name, frame, debuggerGlobal)
     ) {
       continue;
     }
     // Also ignore commands which can only be run with the `:` prefix.
     if (colonOnlyCommandNames.includes(name)) {
       continue;
     }

     const descriptor = {
       // We force the enumerability and the configurability (so the
       // WebConsoleActor can reconfigure the property).
       enumerable: true,
       configurable: true,
     };

     if (typeof command === "function") {
       // Function commands
       descriptor.value = command.bind(undefined, owner);
       maybeExport(descriptor, "value");

       // Unfortunately evalWithBindings will access all bindings values,
       // which would trigger a debuggee native call because bindings's property
       // is using Cu.exportFunction.
       // Put a magic symbol attribute on them in order to carefully accept
       // all bindings as being side effect safe by default.
       if (this._sideEffectFreeCommands.has(name)) {
         descriptor.value.isSideEffectFree = this.SIDE_EFFECT_FREE;
       }

       // Make sure the helpers can be used during eval.
       descriptor.value = debuggerGlobal.makeDebuggeeValue(descriptor.value);
     } else if (typeof command?.get === "function") {
       // Getter commands
       descriptor.get = command.get.bind(undefined, owner);
       maybeExport(descriptor, "get");

       // See comment in previous block.
       if (this._sideEffectFreeCommands.has(name)) {
         descriptor.get.isSideEffectFree = this.SIDE_EFFECT_FREE;
       }
     }
     Object.defineProperty(bindings, name, descriptor);
   }

   return {
     // Use a method as commands will update owner.helperResult later
     getHelperResult() {
       return owner.helperResult;
     },
     bindings,
   };
 },

 /**
  * Create a function for given ':command'-style command.
  *
  * @param object consoleActor
  *        The related web console actor evaluating some code.
  * @param object debuggerGlobal
  *        A Debugger.Object that wraps a content global. This is used for the
  *        Web Console Commands.
  * @param string selectedNodeActorID
  *        The Node actor ID of the currently selected DOM Element, if any is selected.
  * @param string evalInput
  *        String to evaluate.
  *
  * @return object
  *         Object with two properties:
  *         - 'commandFunc', a function corresponds to the 'commandName'
  *         - 'getHelperResult', a live getter returning the data the command
  *           which executed want to convey to the frontend.
  */
 executeCommand(consoleActor, debuggerGlobal, selectedNodeActorID, evalInput) {
   const { command, args } = getCommandAndArgs(evalInput);
   const commands = this._getCommandsForCurrentEnvironment();
   if (!commands.has(command)) {
     throw new Error(`Unsupported command '${command}'`);
   }

   if (args.help || args.usage) {
     const l10nKey = USAGE_STRING_MAPPING[command];
     if (l10nKey) {
       const message = l10n.formatValueSync(l10nKey);
       if (message && message !== l10nKey) {
         return {
           result: null,
           helperResult: {
             type: "usage",
             message,
           },
         };
       }
     }
   }

   const validArguments = this._validArguments.get(command);
   if (validArguments) {
     for (const key of Object.keys(args)) {
       if (!validArguments.includes(key)) {
         throw new Error(
           `:${command} command doesn't support '${key}' argument.`
         );
       }
     }
   }

   const owner = this._createOwnerObject(
     consoleActor,
     debuggerGlobal,
     evalInput,
     selectedNodeActorID
   );

   const commandFunction = commands.get(command);

   // This is where we run the command passed to register method
   const result = commandFunction(owner, args);

   return {
     result,

     // commandFunction may mutate owner.helperResult which is used
     // to convey additional data to the frontend.
     helperResult: owner.helperResult,
   };
 },
};

exports.WebConsoleCommandsManager = WebConsoleCommandsManager;

/*
* Built-in commands.
*
* A list of helper functions used by Firebug can be found here:
*   http://getfirebug.com/wiki/index.php/Command_Line_API
*/

/**
* Find the first node matching a CSS selector.
*
* @param string selector
*        A string that is passed to window.document.querySelector
* @param [optional] Node element
*        An optional Node to replace window.document
* @return Node or null
*         The result of calling document.querySelectorAll(selector).
*/
WebConsoleCommandsManager.register({
 name: "$",
 isSideEffectFree: true,
 command(owner, selector, element) {
   try {
     if (
       element &&
       element.querySelector &&
       (element.nodeType == Node.ELEMENT_NODE ||
         element.nodeType == Node.DOCUMENT_NODE ||
         element.nodeType == Node.DOCUMENT_FRAGMENT_NODE)
     ) {
       return element.querySelector(selector);
     }
     return owner.window.document.querySelector(selector);
   } catch (err) {
     // Throw an error like `err` but that belongs to `owner.window`.
     throw new owner.window.DOMException(err.message, err.name);
   }
 },
});

/**
* Find the nodes matching a CSS selector.
*
* @param string selector
*        A string that is passed to window.document.querySelectorAll.
* @param [optional] Node element
*        An optional root Node, defaults to window.document
* @return array of Node
*         The result of calling document.querySelector(selector) in an array.
*/
WebConsoleCommandsManager.register({
 name: "$$",
 isSideEffectFree: true,
 command(owner, selector, element) {
   let scope = owner.window.document;
   try {
     if (
       element &&
       element.querySelectorAll &&
       (element.nodeType == Node.ELEMENT_NODE ||
         element.nodeType == Node.DOCUMENT_NODE ||
         element.nodeType == Node.DOCUMENT_FRAGMENT_NODE)
     ) {
       scope = element;
     }
     const nodes = scope.querySelectorAll(selector);
     const result = new owner.window.Array();
     // Calling owner.window.Array.from() doesn't work without accessing the
     // wrappedJSObject, so just loop through the results instead.
     for (let i = 0; i < nodes.length; i++) {
       result.push(nodes[i]);
     }
     return result;
   } catch (err) {
     // Throw an error like `err` but that belongs to `owner.window`.
     throw new owner.window.DOMException(err.message, err.name);
   }
 },
});

/**
* Find the nodes matching a CSS selector, including those inside shadow DOM
*
* @param string selector
*        A string that is passed to all `querySelectorAll` calls performed by this command.
* @param [optional] Node element
*        An optional root Node, defaults to window.document
* @return array of Node
*         An array containing the nodes returned by calling `querySelectorAll(selector)`
*         on `element` and on all shadow hosts under element (recursively).
*/
WebConsoleCommandsManager.register({
 name: "$$$",
 isSideEffectFree: true,
 command(owner, selector, element) {
   let scope = owner.window.document;
   try {
     if (
       element?.querySelectorAll &&
       (element.nodeType == Node.ELEMENT_NODE ||
         element.nodeType == Node.DOCUMENT_NODE ||
         element.nodeType == Node.DOCUMENT_FRAGMENT_NODE)
     ) {
       scope = element;
     }

     const result = new owner.window.Array();

     const collectElements = root => {
       const nodes = root.querySelectorAll(selector);
       // Calling owner.window.Array.from() doesn't work without accessing the
       // wrappedJSObject, so just loop through the results instead.
       for (let i = 0, len = nodes.length; i < len; i++) {
         // If we have a native anonymous element, it's seen as a cross-origin object
         // and can't be added to result. We could waive `result` to avoid this exception,
         // but those nodes would show up as `Restricted` (See Bug 2006913), so it's not
         // really useful. If we'd have a proper rendering for those, ideally we'd use
         // the Inspector Walker filter to see if a node should be skipped or not
         // and we could add the node here.
         if (nodes[i].isNativeAnonymous) {
           continue;
         }

         result.push(nodes[i]);
       }

       // If the scope is a host, run the query inside its shadow DOM
       if (root.openOrClosedShadowRoot) {
         collectElements(root.openOrClosedShadowRoot);
       }

       // Finally, run the query for all hosts in scope
       const all = root.querySelectorAll("*");
       for (let i = 0, len = all.length; i < len; i++) {
         const el = all[i];
         if (el.openOrClosedShadowRoot) {
           collectElements(el.openOrClosedShadowRoot);
         }
       }
     };

     collectElements(scope);

     return result;
   } catch (err) {
     // Throw an error like `err` but that belongs to `owner.window`.
     throw new owner.window.DOMException(err.message, err.name);
   }
 },
});

/**
* Returns the result of the last console input evaluation
*
* @return object|undefined
* Returns last console evaluation or undefined
*/
WebConsoleCommandsManager.register({
 name: "$_",
 isSideEffectFree: true,
 command: {
   get(owner) {
     return owner.consoleActor.getLastConsoleInputEvaluation();
   },
 },
});

/**
* Runs an xPath query and returns all matched nodes.
*
* @param string xPath
*        xPath search query to execute.
* @param [optional] Node context
*        Context to run the xPath query on. Uses window.document if not set.
* @param [optional] string|number resultType
         Specify the result type. Default value XPathResult.ANY_TYPE
* @return array of Node
*/
WebConsoleCommandsManager.register({
 name: "$x",
 isSideEffectFree: true,
 command(
   owner,
   xPath,
   context,
   resultType = owner.window.XPathResult.ANY_TYPE
 ) {
   const nodes = new owner.window.Array();
   // Not waiving Xrays, since we want the original Document.evaluate function,
   // instead of anything that's been redefined.
   const doc = owner.window.document;
   context = context || doc;
   switch (resultType) {
     case "number":
       resultType = owner.window.XPathResult.NUMBER_TYPE;
       break;

     case "string":
       resultType = owner.window.XPathResult.STRING_TYPE;
       break;

     case "bool":
       resultType = owner.window.XPathResult.BOOLEAN_TYPE;
       break;

     case "node":
       resultType = owner.window.XPathResult.FIRST_ORDERED_NODE_TYPE;
       break;

     case "nodes":
       resultType = owner.window.XPathResult.UNORDERED_NODE_ITERATOR_TYPE;
       break;
   }
   const results = doc.evaluate(xPath, context, null, resultType, null);
   if (results.resultType === owner.window.XPathResult.NUMBER_TYPE) {
     return results.numberValue;
   }
   if (results.resultType === owner.window.XPathResult.STRING_TYPE) {
     return results.stringValue;
   }
   if (results.resultType === owner.window.XPathResult.BOOLEAN_TYPE) {
     return results.booleanValue;
   }
   if (
     results.resultType === owner.window.XPathResult.ANY_UNORDERED_NODE_TYPE ||
     results.resultType === owner.window.XPathResult.FIRST_ORDERED_NODE_TYPE
   ) {
     return results.singleNodeValue;
   }
   if (
     results.resultType ===
       owner.window.XPathResult.UNORDERED_NODE_SNAPSHOT_TYPE ||
     results.resultType === owner.window.XPathResult.ORDERED_NODE_SNAPSHOT_TYPE
   ) {
     for (let i = 0; i < results.snapshotLength; i++) {
       nodes.push(results.snapshotItem(i));
     }
     return nodes;
   }

   let node;
   while ((node = results.iterateNext())) {
     nodes.push(node);
   }

   return nodes;
 },
});

/**
* Returns the currently selected object in the highlighter.
*
* @return Object representing the current selection in the
*         Inspector, or null if no selection exists.
*/
WebConsoleCommandsManager.register({
 name: "$0",
 isSideEffectFree: true,
 command: {
   get(owner) {
     return owner.makeDebuggeeValue(owner.selectedNode);
   },
 },
});

/**
* Clears the output of the WebConsole.
*/
WebConsoleCommandsManager.register({
 name: "clear",
 isSideEffectFree: false,
 command(owner) {
   owner.helperResult = {
     type: "clearOutput",
   };
 },
});

/**
* Clears the input history of the WebConsole.
*/
WebConsoleCommandsManager.register({
 name: "clearHistory",
 isSideEffectFree: false,
 command(owner) {
   owner.helperResult = {
     type: "clearHistory",
   };
 },
});

/**
* Returns the result of Object.keys(object).
*
* @param object object
*        Object to return the property names from.
* @return array of strings
*/
WebConsoleCommandsManager.register({
 name: "keys",
 isSideEffectFree: true,
 command(owner, object) {
   // Need to waive Xrays so we can iterate functions and accessor properties
   return Cu.cloneInto(Object.keys(Cu.waiveXrays(object)), owner.window);
 },
});

/**
* Returns the values of all properties on object.
*
* @param object object
*        Object to display the values from.
* @return array of string
*/
WebConsoleCommandsManager.register({
 name: "values",
 isSideEffectFree: true,
 command(owner, object) {
   const values = [];
   // Need to waive Xrays so we can iterate functions and accessor properties
   const waived = Cu.waiveXrays(object);
   const names = Object.getOwnPropertyNames(waived);

   for (const name of names) {
     values.push(waived[name]);
   }

   return Cu.cloneInto(values, owner.window);
 },
});

/**
* Opens a help window in MDN.
*/
WebConsoleCommandsManager.register({
 name: "help",
 isSideEffectFree: false,
 command(owner) {
   owner.helperResult = { type: "help" };
 },
});

/**
* Inspects the passed object. This is done by opening the PropertyPanel.
*
* @param object object
*        Object to inspect.
*/
WebConsoleCommandsManager.register({
 name: "inspect",
 isSideEffectFree: false,
 command(owner, object, forceExpandInConsole = false) {
   const dbgObj = owner.preprocessDebuggerObject(
     owner.makeDebuggeeValue(object)
   );

   const grip = owner.createValueGrip(dbgObj);
   owner.helperResult = {
     type: "inspectObject",
     input: owner.evalInput,
     object: grip,
     forceExpandInConsole,
   };
 },
});

/**
* Copy the String representation of a value to the clipboard.
*
* @param any value
*        A value you want to copy as a string.
* @return void
*/
WebConsoleCommandsManager.register({
 name: "copy",
 isSideEffectFree: false,
 command(owner, value) {
   let payload;
   try {
     if (Element.isInstance(value)) {
       payload = value.outerHTML;
     } else if (typeof value == "string") {
       payload = value;
     } else {
       // Need to waive Xrays so we can iterate accessor properties.
       // If Cu is not defined, we are running on a worker thread, where xrays don't exist.
       if (value && Cu) {
         value = Cu.waiveXrays(value);
       }
       payload = JSON.stringify(value, null, "  ");
     }
   } catch (ex) {
     owner.helperResult = {
       type: "error",
       message: "webconsole.error.commands.copyError",
       messageArgs: [ex.toString()],
     };
     return;
   }
   owner.helperResult = {
     type: "copyValueToClipboard",
     value: payload,
   };
 },
});

/**
* Take a screenshot of a page.
*
* @param object args
*               The arguments to be passed to the screenshot
* @return void
*/
WebConsoleCommandsManager.register({
 name: "screenshot",
 isSideEffectFree: false,
 command(owner, args = {}) {
   owner.helperResult = {
     type: "screenshotOutput",
     args,
   };
 },
});

/**
* Shows a history of commands and expressions previously executed within the command line.
*
* @param object args
*               The arguments to be passed to the history
* @return void
*/
WebConsoleCommandsManager.register({
 name: "history",
 isSideEffectFree: false,
 command(owner, args = {}) {
   owner.helperResult = {
     type: "historyOutput",
     args,
   };
 },
});

/**
* Block specific resource from loading
*
* @param object args
*               an object with key "url", i.e. a filter
*
* @return void
*/
WebConsoleCommandsManager.register({
 name: "block",
 isSideEffectFree: false,
 command(owner, args = {}) {
   // Note that this command is implemented in the frontend, from actions's input.js
   // We only forward the command arguments back to the client.
   if (!args.url) {
     owner.helperResult = {
       type: "error",
       message: "webconsole.messages.commands.blockArgMissing",
     };
     return;
   }

   owner.helperResult = {
     type: "blockURL",
     args,
   };
 },
 validArguments: ["url"],
});

/**
* Unblock a blocked a resource
*
* @param object filter
*               an object with key "url", i.e. a filter
*
* @return void
*/
WebConsoleCommandsManager.register({
 name: "unblock",
 isSideEffectFree: false,
 command(owner, args = {}) {
   // Note that this command is implemented in the frontend, from actions's input.js
   // We only forward the command arguments back to the client.
   if (!args.url) {
     owner.helperResult = {
       type: "error",
       message: "webconsole.messages.commands.blockArgMissing",
     };
     return;
   }

   owner.helperResult = {
     type: "unblockURL",
     args,
   };
 },
 validArguments: ["url"],
});

/**
* Toggle JavaScript tracing
*
* @param object args
*        An object with various configuration only valid when starting the tracing.
*
* @return void
*/
WebConsoleCommandsManager.register({
 name: "trace",
 isSideEffectFree: false,
 command(owner, args) {
   // Disable :trace command on worker until this feature is enabled by default
   if (isWorker) {
     throw new Error(":trace command isn't supported in workers");
   }

   if (!owner.consoleActor.targetActor.isTracerFeatureEnabled) {
     throw new Error(
       ":trace requires 'devtools.debugger.features.javascript-tracing' preference to be true"
     );
   }
   const tracerActor =
     owner.consoleActor.targetActor.getTargetScopedActor("tracer");
   const logMethod = args.logMethod || "console";
   let traceDOMMutations = null;
   if ("dom-mutations" in args) {
     // When no value is passed, track all types of mutations
     if (args["dom-mutations"] === true) {
       traceDOMMutations = ["add", "attributes", "remove"];
     } else if (typeof args["dom-mutations"] == "string") {
       // Otherwise consider the value as coma seperated list and remove any white space.
       traceDOMMutations = args["dom-mutations"].split(",").map(e => e.trim());
       const acceptedValues = Object.values(lazy.JSTracer.DOM_MUTATIONS);
       if (!traceDOMMutations.every(e => acceptedValues.includes(e))) {
         throw new Error(
           `:trace --dom-mutations only accept a list of strings whose values can be: ${acceptedValues}`
         );
       }
     } else {
       throw new Error(
         ":trace --dom-mutations accept only no arguments, or a list mutation type strings (add,attributes,remove)"
       );
     }
   }
   // Note that toggleTracing does some sanity checks and will throw meaningful error
   // when the arguments are wrong.
   const enabled = tracerActor.toggleTracing({
     logMethod,
     prefix: args.prefix || null,
     traceFunctionReturn: !!args.returns,
     traceValues: !!args.values,
     traceOnNextInteraction: args["on-next-interaction"] || null,
     traceDOMMutations,
     maxDepth: args["max-depth"] || null,
     maxRecords: args["max-records"] || null,
   });

   owner.helperResult = {
     type: "traceOutput",
     enabled,
     logMethod,
   };
 },
 validArguments: [
   "logMethod",
   "max-depth",
   "max-records",
   "on-next-interaction",
   "dom-mutations",
   "prefix",
   "returns",
   "values",
 ],
});