path: root/devtools/shared/commands/target/target-command.js

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

const EventEmitter = require("resource://devtools/shared/event-emitter.js");

const BROWSERTOOLBOX_SCOPE_PREF = "devtools.browsertoolbox.scope";
// Possible values of the previous pref:
const BROWSERTOOLBOX_SCOPE_EVERYTHING = "everything";
const BROWSERTOOLBOX_SCOPE_PARENTPROCESS = "parent-process";

// eslint-disable-next-line mozilla/reject-some-requires
const createStore = require("resource://devtools/client/shared/redux/create-store.js");
const reducer = require("resource://devtools/shared/commands/target/reducers/targets.js");

loader.lazyRequireGetter(
  this,
  ["refreshTargets", "registerTarget", "unregisterTarget"],
  "resource://devtools/shared/commands/target/actions/targets.js",
  true
);

class TargetCommand extends EventEmitter {
  #selectedTargetFront;
  /**
   * This class helps managing, iterating over and listening for Targets.
   *
   * It exposes:
   *  - the top level target, typically the main process target for the browser toolbox
   *    or the browsing context target for a regular web toolbox
   *  - target of remoted iframe, in case Fission is enabled and some <iframe>
   *    are running in a distinct process
   *  - target switching. If the top level target changes for a new one,
   *    all the targets are going to be declared as destroyed and the new ones
   *    will be notified to the user of this API.
   *
   * @fires target-tread-wrong-order-on-resume : An event that is emitted when resuming
   *        the thread throws with the "wrongOrder" error.
   *
   * @param {DescriptorFront} descriptorFront
   *        The context to inspector identified by this descriptor.
   * @param {WatcherFront} watcherFront
   *        If available, a reference to the related Watcher Front.
   * @param {Object} commands
   *        The commands object with all interfaces defined from devtools/shared/commands/
   */
  constructor({ descriptorFront, watcherFront, commands }) {
    super();

    this.commands = commands;
    this.descriptorFront = descriptorFront;
    this.watcherFront = watcherFront;
    this.rootFront = descriptorFront.client.mainRoot;

    this.store = createStore(reducer);
    // Name of the store used when calling createProvider.
    this.storeId = "target-store";

    this._updateBrowserToolboxScope =
      this._updateBrowserToolboxScope.bind(this);

    Services.prefs.addObserver(
      BROWSERTOOLBOX_SCOPE_PREF,
      this._updateBrowserToolboxScope
    );
    // Until Watcher actor notify about new top level target when navigating to another process
    // we have to manually switch to a new target from the client side
    this.onLocalTabRemotenessChange =
      this.onLocalTabRemotenessChange.bind(this);
    if (this.descriptorFront.isTabDescriptor) {
      this.descriptorFront.on(
        "remoteness-change",
        this.onLocalTabRemotenessChange
      );
    }

    if (this.isServerTargetSwitchingEnabled()) {
      // XXX: Will only be used for local tab server side target switching if
      // the first target is generated from the server.
      this._onFirstTarget = new Promise(r => (this._resolveOnFirstTarget = r));
    }

    // Reports if we have at least one listener for the given target type
    this._listenersStarted = new Set();

    // List of all the target fronts
    this._targets = new Set();
    // {Map<Function, Set<targetFront>>} A Map keyed by `onAvailable` function passed to
    // `watchTargets`, whose initial value is a Set of the existing target fronts at the
    // time watchTargets is called.
    this._pendingWatchTargetInitialization = new Map();

    // Listeners for target creation, destruction and selection
    this._createListeners = new EventEmitter();
    this._destroyListeners = new EventEmitter();
    this._selectListeners = new EventEmitter();

    this._onTargetAvailable = this._onTargetAvailable.bind(this);
    this._onTargetDestroyed = this._onTargetDestroyed.bind(this);
    this._onTargetSelected = this._onTargetSelected.bind(this);
    // Bug 1675763: Watcher actor is not available in all situations yet.
    if (this.watcherFront) {
      this.watcherFront.on("target-available", this._onTargetAvailable);
      this.watcherFront.on("target-destroyed", this._onTargetDestroyed);
    }

    this.legacyImplementation = {};

    // Public flag to allow listening for workers even if the fission pref is off
    // This allows listening for workers in the content toolbox outside of fission contexts
    // For now, this is only toggled by tests.
    this.listenForWorkers =
      this.rootFront.traits.workerConsoleApiMessagesDispatchedToMainThread ===
      false;
    this.listenForServiceWorkers = false;

    // Tells us if we received the first top level target.
    // If target switching is done on:
    // * client side, this is done from startListening => _createFirstTarget
    //                and pull from the Descriptor front.
    // * server side, this is also done from startListening,
    //                but we wait for the watcher actor to notify us about it
    //                via target-available-form avent.
    this._gotFirstTopLevelTarget = false;
    this._onResourceAvailable = this._onResourceAvailable.bind(this);
  }

  get selectedTargetFront() {
    return this.#selectedTargetFront || this.targetFront;
  }

  /**
   * Called fired when BROWSERTOOLBOX_SCOPE_PREF pref changes.
   * This will enable/disable the full multiprocess debugging.
   * When enabled we will watch for content process targets and debug all the processes.
   * When disabled we will only watch for FRAME and WORKER and restrict ourself to parent process resources.
   */
  _updateBrowserToolboxScope() {
    const browserToolboxScope = Services.prefs.getCharPref(
      BROWSERTOOLBOX_SCOPE_PREF
    );
    if (browserToolboxScope == BROWSERTOOLBOX_SCOPE_EVERYTHING) {
      // Force listening to new additional target types
      this.startListening();
    } else if (browserToolboxScope == BROWSERTOOLBOX_SCOPE_PARENTPROCESS) {
      const disabledTargetTypes = [
        TargetCommand.TYPES.FRAME,
        TargetCommand.TYPES.PROCESS,
      ];
      // Force unwatching for additional targets types
      // (we keep listening to workers)
      // The related targets will be destroyed by the server
      // and reported as destroyed to the frontend.
      for (const type of disabledTargetTypes) {
        this.stopListeningForType(type, {
          isTargetSwitching: false,
          isModeSwitching: true,
        });
      }
    }
  }

  // Called whenever a new Target front is available.
  // Either because a target was already available as we started calling startListening
  // or if it has just been created
  async _onTargetAvailable(targetFront) {
    // We put the `commands` on the targetFront so it can be retrieved from any front easily.
    // Without this, protocol.js fronts won't have any easy access to it.
    // Ideally, Fronts would all be migrated to commands and we would no longer need this hack.
    targetFront.commands = this.commands;

    // If the new target is a top level target, we are target switching.
    // Target-switching is only triggered for "local-tab" browsing-context
    // targets which should always have the topLevelTarget flag initialized
    // on the server.
    const isTargetSwitching = targetFront.isTopLevel;
    const isFirstTarget =
      targetFront.isTopLevel && !this._gotFirstTopLevelTarget;

    if (this._targets.has(targetFront)) {
      // The top level target front can be reported via listProcesses in the
      // case of the BrowserToolbox. For any other target, log an error if it is
      // already registered.
      if (targetFront != this.targetFront) {
        console.error(
          "Target is already registered in the TargetCommand",
          targetFront.actorID
        );
      }
      return;
    }

    if (this.isDestroyed() || targetFront.isDestroyedOrBeingDestroyed()) {
      return;
    }

    // Handle top level target switching
    // Note that, for now, `_onTargetAvailable` isn't called for the *initial* top level target.
    // i.e. the one that is passed to TargetCommand constructor.
    if (targetFront.isTopLevel) {
      // First report that all existing targets are destroyed
      if (!isFirstTarget) {
        this._destroyExistingTargetsOnTargetSwitching();
      }

      // Update the reference to the memoized top level target
      this.targetFront = targetFront;
      this.descriptorFront.setTarget(targetFront);
      this.#selectedTargetFront = null;

      if (isFirstTarget && this.isServerTargetSwitchingEnabled()) {
        this._gotFirstTopLevelTarget = true;
        this._resolveOnFirstTarget();
      }
    }

    // Map the descriptor typeName to a target type.
    const targetType = this.getTargetType(targetFront);
    targetFront.setTargetType(targetType);

    this._targets.add(targetFront);
    try {
      await targetFront.attachAndInitThread(this);
    } catch (e) {
      console.error("Error when attaching target:", e);
      this._targets.delete(targetFront);
      return;
    }

    for (const targetFrontsSet of this._pendingWatchTargetInitialization.values()) {
      targetFrontsSet.delete(targetFront);
    }

    if (this.isDestroyed() || targetFront.isDestroyedOrBeingDestroyed()) {
      return;
    }

    this.store.dispatch(registerTarget(targetFront));

    // Then, once the target is attached, notify the target front creation listeners
    await this._createListeners.emitAsync(targetType, {
      targetFront,
      isTargetSwitching,
    });

    // Re-register the listeners as the top level target changed
    // and some targets are fetched from it
    if (targetFront.isTopLevel && !isFirstTarget) {
      await this.startListening({ isTargetSwitching: true });
    }

    // These two events are used by tests using the production codepath (i.e. disabling flags.testing)
    // To be consumed by tests triggering frame navigations, spawning workers...
    this.emit("processed-available-target", targetFront);

    if (isTargetSwitching) {
      this.emit("switched-target", targetFront);
    }
  }

  _destroyExistingTargetsOnTargetSwitching() {
    const destroyedTargets = [];
    for (const target of this._targets) {
      // We only consider the top level target to be switched
      const isDestroyedTargetSwitching = target == this.targetFront;
      const isServiceWorker = target.targetType === this.TYPES.SERVICE_WORKER;
      const isPopup = target.targetForm.isPopup;

      // Never destroy the popup targets when the top level target is destroyed
      // as the popup follow a different lifecycle.
      // Also avoid destroying service worker targets for similar reason.
      if (!isPopup && !isServiceWorker) {
        this._onTargetDestroyed(target, {
          isTargetSwitching: isDestroyedTargetSwitching,
          // Do not destroy service worker front as we may want to keep using it.
          shouldDestroyTargetFront: !isServiceWorker,
        });
        destroyedTargets.push(target);
      }
    }

    // Stop listening to legacy listeners as we now have to listen
    // on the new target.
    this.stopListening({ isTargetSwitching: true });

    // Remove destroyed target from the cached target list. We don't simply clear the
    // Map as SW targets might not have been destroyed.
    for (const target of destroyedTargets) {
      this._targets.delete(target);
    }
  }

  /**
   * Function fired everytime a target is destroyed.
   *
   * This is called either:
   * - via target-destroyed event fired by the WatcherFront,
   *   event which is a simple translation of the target-destroyed-form emitted by the WatcherActor.
   *   Watcher Actor emits this is various condition when the debugged target is meant to be destroyed:
   *   - the related target context is destroyed (tab closed, worker shut down, content process destroyed, ...),
   *   - when the DevToolsServerConnection used on the server side to communicate to the client is closed.

   * - by TargetCommand._onTargetAvailable, when a top level target switching happens and all previously
   *   registered target fronts should be destroyed.

   * - by the legacy Targets listeners, calling this method directly.
   *   This usecase is meant to be removed someday when all target targets are supported by the Watcher.
   *   (bug 1687459)
   *
   * @param {TargetFront} targetFront
   *        The target that just got destroyed.
   * @param {Object} options
   * @param {Boolean} [options.isTargetSwitching]
   *        To be set to true when this is about the top level target which is being replaced
   *        by a new one.
   *        The passed target should be still the one store in TargetCommand.targetFront
   *        and will be replaced via a call to onTargetAvailable with a new target front.
   * @param {Boolean} [options.isModeSwitching]
   *        To be set to true when the target was destroyed was called as the result of a
   *        change to the devtools.browsertoolbox.scope pref.
   * @param {Boolean} [options.shouldDestroyTargetFront]
   *        By default, the passed target front will be destroyed. But in some cases like
   *        legacy listeners for service workers we want to keep the front alive.
   */
  _onTargetDestroyed(
    targetFront,
    {
      isModeSwitching = false,
      isTargetSwitching = false,
      shouldDestroyTargetFront = true,
    } = {}
  ) {
    // The watcher actor may notify us about the destruction of the top level target.
    // But second argument to this method, isTargetSwitching is only passed from the frontend.
    // So automatically toggle the isTargetSwitching flag for server side destructions
    // only if that's about the existing top level target.
    if (targetFront == this.targetFront) {
      isTargetSwitching = true;
    }
    this._destroyListeners.emit(targetFront.targetType, {
      targetFront,
      isTargetSwitching,
      isModeSwitching,
    });
    this._targets.delete(targetFront);

    this.store.dispatch(unregisterTarget(targetFront));

    // If the destroyed target was the selected one, we need to do some cleanup
    if (this.#selectedTargetFront == targetFront) {
      // If we're doing a targetSwitch, simply nullify #selectedTargetFront
      if (isTargetSwitching) {
        this.#selectedTargetFront = null;
      } else {
        // Otherwise we want to select the top level target
        this.selectTarget(this.targetFront);
      }
    }

    if (shouldDestroyTargetFront) {
      // When calling targetFront.destroy(), we will first call TargetFrontMixin.destroy,
      // which will try to call `detach` RDP method.
      // Unfortunately, this request will never complete in some cases like bfcache navigations.
      // Because of that, the target front will never be completely destroy as it will prevent
      // calling super.destroy and Front.destroy.
      // Workaround that by manually calling Front class destroy method:
      targetFront.baseFrontClassDestroy();

      targetFront.destroy();

      // Delete the attribute we set from _onTargetAvailable so that we avoid leaking commands
      // if any target front is leaked.
      delete targetFront.commands;
    }
  }

  /**
   *
   * @param {TargetFront} targetFront
   */
  async _onTargetSelected(targetFront) {
    if (this.#selectedTargetFront == targetFront) {
      // Target is already selected, we can bail out.
      return;
    }

    this.#selectedTargetFront = targetFront;
    const targetType = this.getTargetType(targetFront);
    await this._selectListeners.emitAsync(targetType, {
      targetFront,
    });
  }

  _setListening(type, value) {
    if (value) {
      this._listenersStarted.add(type);
    } else {
      this._listenersStarted.delete(type);
    }
  }

  _isListening(type) {
    return this._listenersStarted.has(type);
  }

  /**
   * Check if the watcher is currently supported.
   *
   * When no typeOrTrait is provided, we will only check that the watcher is
   * available.
   *
   * When a typeOrTrait is provided, we will check for an explicit trait on the
   * watcherFront that indicates either that:
   *   - a target type is supported
   *   - or that a custom trait is true
   *
   * @param {String} [targetTypeOrTrait]
   *        Optional target type or trait.
   * @return {Boolean} true if the watcher is available and supports the
   *          optional targetTypeOrTrait
   */
  hasTargetWatcherSupport(targetTypeOrTrait) {
    if (targetTypeOrTrait) {
      // Target types are also exposed as traits, where resource types are
      // exposed under traits.resources (cf hasResourceWatcherSupport
      // implementation).
      return !!this.watcherFront?.traits[targetTypeOrTrait];
    }

    return !!this.watcherFront;
  }

  /**
   * Start listening for targets from the server
   *
   * Interact with the actors in order to start listening for new types of targets.
   * This will fire the _onTargetAvailable function for all already-existing targets,
   * as well as the next one to be created. It will also call _onTargetDestroyed
   * everytime a target is reported as destroyed by the actors.
   * By the time this function resolves, all the already-existing targets will be
   * reported to _onTargetAvailable.
   *
   * @param Object options
   * @param Boolean options.isTargetSwitching
   *        Set to true when this is called while a target switching happens. In such case,
   *        we won't register listener set on the Watcher Actor, but still register listeners
   *        set via Legacy Listeners.
   */
  async startListening({ isTargetSwitching = false } = {}) {
    // The first time we call this method, we pull the current top level target from the descriptor
    if (
      !this.isServerTargetSwitchingEnabled() &&
      !this._gotFirstTopLevelTarget
    ) {
      await this._createFirstTarget();
    }

    // If no pref are set to true, nor is listenForWorkers set to true,
    // we won't listen for any additional target. Only the top level target
    // will be managed. We may still do target-switching.
    const types = this._computeTargetTypes();

    for (const type of types) {
      if (this._isListening(type)) {
        continue;
      }
      this._setListening(type, true);

      // Only a few top level targets support the watcher actor at the moment (see WatcherActor
      // traits in the _form method). Bug 1675763 tracks watcher actor support for all targets.
      if (this.hasTargetWatcherSupport(type)) {
        // When we switch to a new top level target, we don't have to stop and restart
        // Watcher listener as it is independant from the top level target.
        // This isn't the case for some Legacy Listeners, which fetch targets from the top level target
        if (!isTargetSwitching) {
          await this.watcherFront.watchTargets(type);
        }
      } else if (LegacyTargetWatchers[type]) {
        // Instantiate the legacy listener only once for each TargetCommand, and reuse it if we stop and restart listening
        if (!this.legacyImplementation[type]) {
          this.legacyImplementation[type] = new LegacyTargetWatchers[type](
            this,
            this._onTargetAvailable,
            this._onTargetDestroyed,
            this.commands
          );
        }
        await this.legacyImplementation[type].listen();
      } else {
        throw new Error(`Unsupported target type '${type}'`);
      }
    }

    if (!this._watchingDocumentEvent && !this.isDestroyed()) {
      // We want to watch DOCUMENT_EVENT in order to update the url and title of target fronts,
      // as the initial value that is set in them might be erroneous (if the target was
      // created so early that the document url is still pointing to about:blank and the
      // html hasn't be parsed yet, so we can't know the <title> content).

      this._watchingDocumentEvent = true;
      await this.commands.resourceCommand.watchResources(
        [this.commands.resourceCommand.TYPES.DOCUMENT_EVENT],
        {
          onAvailable: this._onResourceAvailable,
        }
      );
    }

    if (this.isServerTargetSwitchingEnabled()) {
      await this._onFirstTarget;
    }
  }

  async _createFirstTarget() {
    // Note that this is a public attribute, used outside of this class
    // and helps knowing what is the current top level target we debug.
    this.targetFront = await this.descriptorFront.getTarget();
    this.targetFront.setTargetType(this.getTargetType(this.targetFront));
    this.targetFront.setIsTopLevel(true);
    this._gotFirstTopLevelTarget = true;

    // See _onTargetAvailable. As this target isn't going through that method
    // we have to replicate doing that here.
    this.targetFront.commands = this.commands;

    // Add the top-level target to the list of targets.
    this._targets.add(this.targetFront);
    this.store.dispatch(registerTarget(this.targetFront));
  }

  _computeTargetTypes() {
    let types = [];

    // We also check for watcher support as some xpcshell tests uses legacy APIs and don't support frames.
    if (
      this.descriptorFront.isTabDescriptor &&
      this.hasTargetWatcherSupport(TargetCommand.TYPES.FRAME)
    ) {
      types = [TargetCommand.TYPES.FRAME];
    } else if (this.descriptorFront.isBrowserProcessDescriptor) {
      const browserToolboxScope = Services.prefs.getCharPref(
        BROWSERTOOLBOX_SCOPE_PREF
      );
      if (browserToolboxScope == BROWSERTOOLBOX_SCOPE_EVERYTHING) {
        types = TargetCommand.ALL_TYPES;
      }
    }
    if (this.listenForWorkers && !types.includes(TargetCommand.TYPES.WORKER)) {
      types.push(TargetCommand.TYPES.WORKER);
    }
    if (
      this.listenForWorkers &&
      !types.includes(TargetCommand.TYPES.SHARED_WORKER)
    ) {
      types.push(TargetCommand.TYPES.SHARED_WORKER);
    }
    if (
      this.listenForServiceWorkers &&
      !types.includes(TargetCommand.TYPES.SERVICE_WORKER)
    ) {
      types.push(TargetCommand.TYPES.SERVICE_WORKER);
    }

    return types;
  }

  /**
   * Stop listening for targets from the server
   *
   * @param Object options
   * @param Boolean options.isTargetSwitching
   *        Set to true when this is called while a target switching happens. In such case,
   *        we won't unregister listener set on the Watcher Actor, but still unregister
   *        listeners set via Legacy Listeners.
   */
  stopListening({ isTargetSwitching = false } = {}) {
    // As DOCUMENT_EVENT isn't using legacy listener,
    // there is no need to stop and restart it in case of target switching.
    if (this._watchingDocumentEvent && !isTargetSwitching) {
      this.commands.resourceCommand.unwatchResources(
        [this.commands.resourceCommand.TYPES.DOCUMENT_EVENT],
        {
          onAvailable: this._onResourceAvailable,
        }
      );
      this._watchingDocumentEvent = false;
    }

    for (const type of TargetCommand.ALL_TYPES) {
      this.stopListeningForType(type, { isTargetSwitching });
    }
  }

  /**
   * Stop listening for targets of a given type from the server
   *
   * @param String type
   *        target type we want to stop listening for
   * @param Object options
   * @param Boolean options.isTargetSwitching
   *        Set to true when this is called while a target switching happens. In such case,
   *        we won't unregister listener set on the Watcher Actor, but still unregister
   *        listeners set via Legacy Listeners.
   * @param Boolean options.isModeSwitching
   *        Set to true when this is called as the result of a change to the
   *        devtools.browsertoolbox.scope pref.
   */
  stopListeningForType(type, { isTargetSwitching, isModeSwitching }) {
    if (!this._isListening(type)) {
      return;
    }
    this._setListening(type, false);

    // Only a few top level targets support the watcher actor at the moment (see WatcherActor
    // traits in the _form method). Bug 1675763 tracks watcher actor support for all targets.
    if (this.hasTargetWatcherSupport(type)) {
      // When we switch to a new top level target, we don't have to stop and restart
      // Watcher listener as it is independant from the top level target.
      // This isn't the case for some Legacy Listeners, which fetch targets from the top level target
      // Also, TargetCommand.destroy may be called after the client is closed.
      // So avoid calling the RDP method in that situation.
      if (!isTargetSwitching && !this.watcherFront.isDestroyed()) {
        this.watcherFront.unwatchTargets(type, { isModeSwitching });
      }
    } else if (this.legacyImplementation[type]) {
      this.legacyImplementation[type].unlisten({
        isTargetSwitching,
        isModeSwitching,
      });
    } else {
      throw new Error(`Unsupported target type '${type}'`);
    }
  }

  getTargetType(target) {
    const { typeName } = target;
    if (typeName == "windowGlobalTarget") {
      return TargetCommand.TYPES.FRAME;
    }

    if (
      typeName == "contentProcessTarget" ||
      typeName == "parentProcessTarget"
    ) {
      return TargetCommand.TYPES.PROCESS;
    }

    if (typeName == "workerDescriptor" || typeName == "workerTarget") {
      if (target.isSharedWorker) {
        return TargetCommand.TYPES.SHARED_WORKER;
      }

      if (target.isServiceWorker) {
        return TargetCommand.TYPES.SERVICE_WORKER;
      }

      return TargetCommand.TYPES.WORKER;
    }

    throw new Error("Unsupported target typeName: " + typeName);
  }

  _matchTargetType(type, target) {
    return type === target.targetType;
  }

  _onResourceAvailable(resources) {
    for (const resource of resources) {
      if (
        resource.resourceType ===
        this.commands.resourceCommand.TYPES.DOCUMENT_EVENT
      ) {
        const { targetFront } = resource;
        if (resource.title !== undefined && targetFront?.setTitle) {
          targetFront.setTitle(resource.title);
        }
        if (resource.url !== undefined && targetFront?.setUrl) {
          targetFront.setUrl(resource.url);
        }
        if (
          !resource.isFrameSwitching &&
          // `url` is set on the targetFront when we receive dom-loading, and `title` when
          // `dom-interactive` is received. Here we're only updating the window title in
          // the "newer" event.
          resource.name === "dom-interactive"
        ) {
          // We just updated the targetFront title and url, force a refresh
          // so that the EvaluationContext selector update them.
          this.store.dispatch(refreshTargets());
        }
      }
    }
  }

  /**
   * Listen for the creation and/or destruction of target fronts matching one of the provided types.
   *
   * @param {Object} options
   * @param {Array<String>} options.types
   *        The type of target to listen for. Constant of TargetCommand.TYPES.
   * @param {Function} options.onAvailable
   *        Mandatory callback fired when a target has been just created or was already available.
   *        The function is called with a single object argument containing the following properties:
   *        - {TargetFront} targetFront: The target Front
   *        - {Boolean} isTargetSwitching: Is this target relates to a navigation and
   *                    this replaced a previously available target, this flag will be true
   * @param {Function} options.onDestroyed
   *        Optional callback fired in case of target front destruction.
   *        The function is called with the same arguments than onAvailable.
   * @param {Function} options.onSelected
   *        Optional callback fired when a given target is selected from the iframe picker
   *        The function is called with a single object argument containing the following properties:
   *        - {TargetFront} targetFront: The target Front
   */
  async watchTargets(options = {}) {
    const availableOptions = [
      "types",
      "onAvailable",
      "onDestroyed",
      "onSelected",
    ];
    const unsupportedKeys = Object.keys(options).filter(
      key => !availableOptions.includes(key)
    );
    if (unsupportedKeys.length) {
      throw new Error(
        `TargetCommand.watchTargets does not expect the following options: ${unsupportedKeys.join(
          ", "
        )}`
      );
    }

    const { types, onAvailable, onDestroyed, onSelected } = options;
    if (typeof onAvailable != "function") {
      throw new Error(
        "TargetCommand.watchTargets expects a function for the onAvailable option"
      );
    }

    for (const type of types) {
      if (!this._isValidTargetType(type)) {
        throw new Error(
          `TargetCommand.watchTargets invoked with an unknown type: "${type}"`
        );
      }
    }

    // Notify about already existing target of these types
    const targetFronts = [...this._targets].filter(targetFront =>
      types.includes(targetFront.targetType)
    );
    this._pendingWatchTargetInitialization.set(
      onAvailable,
      new Set(targetFronts)
    );
    const promises = targetFronts.map(async targetFront => {
      // Attach the targets that aren't attached yet (e.g. the initial top-level target),
      // and wait for the other ones to be fully attached.
      try {
        await targetFront.attachAndInitThread(this);
      } catch (e) {
        console.error("Error when attaching target:", e);
        return;
      }

      // It can happen that onAvailable was already called with this targetFront at
      // this time (via _onTargetAvailable). If that's the case, we don't want to call
      // onAvailable a second time.
      if (
        this._pendingWatchTargetInitialization &&
        this._pendingWatchTargetInitialization.has(onAvailable) &&
        !this._pendingWatchTargetInitialization
          .get(onAvailable)
          .has(targetFront)
      ) {
        return;
      }

      try {
        // Ensure waiting for eventual async create listeners
        // which may setup things regarding the existing targets
        // and listen callsite may care about the full initialization
        await onAvailable({
          targetFront,
          isTargetSwitching: false,
        });
      } catch (e) {
        // Prevent throwing when onAvailable handler throws on one target
        // so that it can try to register the other targets
        console.error(
          "Exception when calling onAvailable handler",
          e.message,
          e
        );
      }
    });

    for (const type of types) {
      this._createListeners.on(type, onAvailable);
      if (onDestroyed) {
        this._destroyListeners.on(type, onDestroyed);
      }
      if (onSelected) {
        this._selectListeners.on(type, onSelected);
      }
    }

    await Promise.all(promises);
    this._pendingWatchTargetInitialization.delete(onAvailable);
  }

  /**
   * Stop listening for the creation and/or destruction of a given type of target fronts.
   * See `watchTargets()` for documentation of the arguments.
   */
  unwatchTargets(options = {}) {
    const availableOptions = [
      "types",
      "onAvailable",
      "onDestroyed",
      "onSelected",
    ];
    const unsupportedKeys = Object.keys(options).filter(
      key => !availableOptions.includes(key)
    );
    if (unsupportedKeys.length) {
      throw new Error(
        `TargetCommand.unwatchTargets does not expect the following options: ${unsupportedKeys.join(
          ", "
        )}`
      );
    }

    const { types, onAvailable, onDestroyed, onSelected } = options;
    if (typeof onAvailable != "function") {
      throw new Error(
        "TargetCommand.unwatchTargets expects a function for the onAvailable option"
      );
    }

    for (const type of types) {
      if (!this._isValidTargetType(type)) {
        throw new Error(
          `TargetCommand.unwatchTargets invoked with an unknown type: "${type}"`
        );
      }

      this._createListeners.off(type, onAvailable);
      if (onDestroyed) {
        this._destroyListeners.off(type, onDestroyed);
      }
      if (onSelected) {
        this._selectListeners.off(type, onSelected);
      }
    }
    this._pendingWatchTargetInitialization.delete(onAvailable);
  }

  /**
   * Retrieve all the current target fronts of a given type.
   *
   * @param {Array<String>} types
   *        The types of target to retrieve. Array of TargetCommand.TYPES
   * @return {Array<TargetFront>} Array of target fronts matching any of the
   *         provided types.
   */
  getAllTargets(types) {
    if (!types?.length) {
      throw new Error("getAllTargets expects a non-empty array of types");
    }

    const targets = [...this._targets].filter(target =>
      types.some(type => this._matchTargetType(type, target))
    );

    return targets;
  }

  /**
   * Retrieve all the target fronts in the selected target tree (including the selected
   * target itself).
   *
   * @param {Array<String>} types
   *        The types of target to retrieve. Array of TargetCommand.TYPES
   * @return {Promise<Array<TargetFront>>} Promise that resolves to an array of target fronts.
   */
  async getAllTargetsInSelectedTargetTree(types) {
    const allTargets = this.getAllTargets(types);
    if (this.isTopLevelTargetSelected()) {
      return allTargets;
    }

    const targets = [this.selectedTargetFront];
    for (const target of allTargets) {
      const isInSelectedTree = await target.isTargetAnAncestor(
        this.selectedTargetFront
      );

      if (isInSelectedTree) {
        targets.push(target);
      }
    }
    return targets;
  }

  /**
   * For all the target fronts of given types, retrieve all the target-scoped fronts of the given types.
   *
   * @param {Array<String>} targetTypes
   *        The types of target to iterate over. Constant of TargetCommand.TYPES.
   * @param {String} frontType
   *        The type of target-scoped front to retrieve. It can be "inspector", "console", "thread",...
   * @param {Object} options
   * @param {Boolean} options.onlyInSelectedTargetTree
   *        Set to true to only get the fronts for targets who are in the "targets tree"
   *        of the selected target.
   */
  async getAllFronts(
    targetTypes,
    frontType,
    { onlyInSelectedTargetTree = false } = {}
  ) {
    if (!Array.isArray(targetTypes) || !targetTypes?.length) {
      throw new Error("getAllFronts expects a non-empty array of target types");
    }
    const promises = [];
    const targets = !onlyInSelectedTargetTree
      ? this.getAllTargets(targetTypes)
      : await this.getAllTargetsInSelectedTargetTree(targetTypes);
    for (const target of targets) {
      // For still-attaching worker targets, the thread or console front may not yet be available,
      // whereas TargetMixin.getFront will throw if the actorID isn't available in targetForm.
      // Also ignore destroyed targets. For some reason the previous methods fetching targets
      // can sometime return destroyed targets.
      if (
        (frontType == "thread" && !target.targetForm.threadActor) ||
        (frontType == "console" && !target.targetForm.consoleActor) ||
        target.isDestroyed()
      ) {
        continue;
      }

      promises.push(target.getFront(frontType));
    }
    return Promise.all(promises);
  }

  /**
   * This function is triggered by an event sent by the TabDescriptor when
   * the tab navigates to a distinct process.
   *
   * @param TargetFront targetFront
   *        The WindowGlobalTargetFront instance that navigated to another process
   */
  async onLocalTabRemotenessChange(targetFront) {
    if (this.isServerTargetSwitchingEnabled()) {
      // For server-side target switching, everything will be handled by the
      // _onTargetAvailable callback.
      return;
    }

    // TabDescriptor may emit the event with a null targetFront, interpret that as if the previous target
    // has already been destroyed
    if (targetFront) {
      // Wait for the target to be destroyed so that LocalTabCommandsFactory clears its memoized target for this tab
      await targetFront.once("target-destroyed");
    }

    // Fetch the new target from the descriptor.
    const newTarget = await this.descriptorFront.getTarget();

    // If a navigation happens while we try to get the target for the page that triggered
    // the remoteness change, `getTarget` will return null. In such case, we'll get the
    // "next" target through onTargetAvailable so it's safe to bail here.
    if (!newTarget) {
      console.warn(
        `Couldn't get the target for descriptor ${this.descriptorFront.actorID}`
      );
      return;
    }

    this.switchToTarget(newTarget);
  }

  /**
   * Reload the current top level target.
   * This only works for targets inheriting from WindowGlobalTarget.
   *
   * @param {Boolean} bypassCache
   *        If true, the reload will be forced to bypass any cache.
   */
  async reloadTopLevelTarget(bypassCache = false) {
    if (!this.descriptorFront.traits.supportsReloadDescriptor) {
      throw new Error("The top level target doesn't support being reloaded");
    }

    // Wait for the next DOCUMENT_EVENT's dom-complete event
    // Wait for waitForNextResource completion before reloading, otherwise we might miss the dom-complete event.
    // This can happen if `ResourceCommand.watchResources` made by `waitForNextResource` is still pending
    // while the reload already started and finished loading the document early.
    const { onResource: onReloaded } =
      await this.commands.resourceCommand.waitForNextResource(
        this.commands.resourceCommand.TYPES.DOCUMENT_EVENT,
        {
          ignoreExistingResources: true,
          predicate(resource) {
            return resource.name == "dom-complete";
          },
        }
      );

    await this.descriptorFront.reloadDescriptor({ bypassCache });

    await onReloaded;
  }

  /**
   * Called when the top level target is replaced by a new one.
   * Typically when we navigate to another domain which requires to be loaded in a distinct process.
   *
   * @param {TargetFront} newTarget
   *        The new top level target to debug.
   */
  async switchToTarget(newTarget) {
    // Notify about this new target to creation listeners
    // _onTargetAvailable will also destroy all previous target before notifying about this new one.
    await this._onTargetAvailable(newTarget);
  }

  /**
   * Called when the user selects a frame in the iframe picker.
   *
   * @param {WindowGlobalTargetFront} targetFront
   *        The target front we want the toolbox to focus on.
   */
  selectTarget(targetFront) {
    return this._onTargetSelected(targetFront);
  }

  /**
   * Returns true if the top-level frame is the selected one
   *
   * @returns {Boolean}
   */
  isTopLevelTargetSelected() {
    return this.selectedTargetFront === this.targetFront;
  }

  /**
   * Returns true if a non top-level frame is the selected one in the iframe picker.
   *
   * @returns {Boolean}
   */
  isNonTopLevelTargetSelected() {
    return this.selectedTargetFront !== this.targetFront;
  }

  isTargetRegistered(targetFront) {
    return this._targets.has(targetFront);
  }

  getParentTarget(targetFront) {
    // Note that there are edgecases:
    // * Until bug 1741927 is fixed and we remove non-EFT codepath entirely,
    //   we may receive a `parentInnerWindowId` that doesn't relate to any target.
    //   This happens when the parent document of the targetFront is a document loaded in the
    //   same process as its parent document. In such scenario, and only when EFT is disabled,
    //   we won't instantiate a target for the parent document of the targetFront.
    // * `parentInnerWindowId` could be null in some case like for tabs in the MBT
    //   we should report the top level target as parent. That's what `getParentWindowGlobalTarget` does.
    //   Once we can stop using getParentWindowGlobalTarget for the other edgecase we will be able to
    //   replace it with such fallback: `return this.targetFront;`.
    //   browser_target_command_frames.js will help you get things right.
    const { parentInnerWindowId } = targetFront.targetForm;
    if (parentInnerWindowId) {
      const targets = this.getAllTargets([TargetCommand.TYPES.FRAME]);
      const parent = targets.find(
        target => target.innerWindowId == parentInnerWindowId
      );
      // Until EFT is the only codepath supported (bug 1741927), we will fallback to `getParentWindowGlobalTarget`
      // as we may not have a target if the parent is an iframe running in the same process as its parent.
      if (parent) {
        return parent;
      }
    }

    // Note that all callsites which care about FRAME additional target
    // should all have a toolbox using the watcher actor.
    // It should be: MBT, regular tab toolbox and web extension.
    // The others which still don't support watcher don't spawn FRAME targets:
    // browser content toolbox and service workers.

    return this.watcherFront.getParentWindowGlobalTarget(
      targetFront.browsingContextID
    );
  }

  isDestroyed() {
    return this._isDestroyed;
  }

  isServerTargetSwitchingEnabled() {
    if (this.descriptorFront.isServerTargetSwitchingEnabled) {
      return this.descriptorFront.isServerTargetSwitchingEnabled();
    }
    return false;
  }

  _isValidTargetType(type) {
    return this.ALL_TYPES.includes(type);
  }

  destroy() {
    this.stopListening();
    this._createListeners.off();
    this._destroyListeners.off();
    this._selectListeners.off();

    this.#selectedTargetFront = null;
    this._isDestroyed = true;

    Services.prefs.removeObserver(
      BROWSERTOOLBOX_SCOPE_PREF,
      this._updateBrowserToolboxScope
    );
  }
}

/**
 * All types of target:
 */
TargetCommand.TYPES = TargetCommand.prototype.TYPES = {
  PROCESS: "process",
  FRAME: "frame",
  WORKER: "worker",
  SHARED_WORKER: "shared_worker",
  SERVICE_WORKER: "service_worker",
};
TargetCommand.ALL_TYPES = TargetCommand.prototype.ALL_TYPES = Object.values(
  TargetCommand.TYPES
);

const LegacyTargetWatchers = {};
loader.lazyRequireGetter(
  LegacyTargetWatchers,
  TargetCommand.TYPES.PROCESS,
  "resource://devtools/shared/commands/target/legacy-target-watchers/legacy-processes-watcher.js"
);
loader.lazyRequireGetter(
  LegacyTargetWatchers,
  TargetCommand.TYPES.WORKER,
  "resource://devtools/shared/commands/target/legacy-target-watchers/legacy-workers-watcher.js"
);
loader.lazyRequireGetter(
  LegacyTargetWatchers,
  TargetCommand.TYPES.SHARED_WORKER,
  "resource://devtools/shared/commands/target/legacy-target-watchers/legacy-sharedworkers-watcher.js"
);
loader.lazyRequireGetter(
  LegacyTargetWatchers,
  TargetCommand.TYPES.SERVICE_WORKER,
  "resource://devtools/shared/commands/target/legacy-target-watchers/legacy-serviceworkers-watcher.js"
);

module.exports = TargetCommand;