diff options
Diffstat (limited to '')
| -rw-r--r-- | devtools/shared/commands/resource/resource-command.js | 1367 |
1 files changed, 1367 insertions, 0 deletions
diff --git a/devtools/shared/commands/resource/resource-command.js b/devtools/shared/commands/resource/resource-command.js new file mode 100644 index 0000000000..c45dc6a584 --- /dev/null +++ b/devtools/shared/commands/resource/resource-command.js @@ -0,0 +1,1367 @@ +/* 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 { throttle } = require("resource://devtools/shared/throttle.js"); + +let gLastResourceId = 0; + +function cacheKey(resourceType, resourceId) { + return `${resourceType}:${resourceId}`; +} + +class ResourceCommand { + /** + * This class helps retrieving existing and listening to resources. + * A resource is something that: + * - the target you are debugging exposes + * - can be created as early as the process/worker/page starts loading + * - can already exist, or will be created later on + * - doesn't require any user data to be fetched, only a type/category + * + * @param object commands + * The commands object with all interfaces defined from devtools/shared/commands/ + */ + constructor({ commands }) { + this.targetCommand = commands.targetCommand; + + // Public attribute set by tests to disable throttling + this.throttlingDisabled = false; + + this._onTargetAvailable = this._onTargetAvailable.bind(this); + this._onTargetDestroyed = this._onTargetDestroyed.bind(this); + + this._onResourceAvailable = this._onResourceAvailable.bind(this); + this._onResourceDestroyed = this._onResourceDestroyed.bind(this); + + // Array of all the currently registered watchers, which contains object with attributes: + // - {String} resources: list of all resource watched by this one watcher + // - {Function} onAvailable: watcher's function to call when a new resource is available + // - {Function} onUpdated: watcher's function to call when a resource has been updated + // - {Function} onDestroyed: watcher's function to call when a resource is destroyed + this._watchers = []; + + // Set of watchers currently going through watchResources, only used to handle + // early calls to unwatchResources. Using a Set instead of an array for easier + // delete operations. + this._pendingWatchers = new Set(); + + // Caches for all resources by the order that the resource was taken. + this._cache = new Map(); + this._listenedResources = new Set(); + + // WeakMap used to avoid starting a legacy listener twice for the same + // target + resource-type pair. Legacy listener creation can be subject to + // race conditions. + // Maps a target front to an array of resource types. + this._existingLegacyListeners = new WeakMap(); + this._processingExistingResources = new Set(); + + // List of targetFront event listener unregistration functions keyed by target front. + // These are called when unwatching resources, so if a consumer starts watching resources again, + // we don't have listeners registered twice. + this._offTargetFrontListeners = new Map(); + + this._notifyWatchers = this._notifyWatchers.bind(this); + this._throttledNotifyWatchers = throttle(this._notifyWatchers, 100); + } + + get watcherFront() { + return this.targetCommand.watcherFront; + } + + addResourceToCache(resource) { + const { resourceId, resourceType } = resource; + this._cache.set(cacheKey(resourceType, resourceId), resource); + } + + /** + * Clear all the resources related to specifed resource types. + * Should also trigger clearing of the caches that exists on the related + * serverside resource watchers. + * + * @param {Array:string} resourceTypes + * A list of all the resource types whose + * resources shouled be cleared. + */ + async clearResources(resourceTypes) { + if (!Array.isArray(resourceTypes)) { + throw new Error("clearResources expects a list of resources types"); + } + // Clear the cached resources of the type. + for (const [key, resource] of this._cache) { + if (resourceTypes.includes(resource.resourceType)) { + // NOTE: To anyone paranoid like me, yes it is okay to delete from a Map while iterating it. + this._cache.delete(key); + } + } + + const resourcesToClear = resourceTypes.filter(resourceType => + this.hasResourceCommandSupport(resourceType) + ); + if (resourcesToClear.length) { + this.watcherFront.clearResources(resourcesToClear); + } + } + /** + * Return all specified resources cached in this watcher. + * + * @param {String} resourceType + * @return {Array} resources cached in this watcher + */ + getAllResources(resourceType) { + const result = []; + for (const resource of this._cache.values()) { + if (resource.resourceType === resourceType) { + result.push(resource); + } + } + return result; + } + + /** + * Return the specified resource cached in this watcher. + * + * @param {String} resourceType + * @param {String} resourceId + * @return {Object} resource cached in this watcher + */ + getResourceById(resourceType, resourceId) { + return this._cache.get(cacheKey(resourceType, resourceId)); + } + + /** + * Request to start retrieving all already existing instances of given + * type of resources and also start watching for the one to be created after. + * + * @param {Array:string} resources + * List of all resources which should be fetched and observed. + * @param {Object} options + * - {Function} onAvailable: This attribute is mandatory. + * Function which will be called with an array of resources + * each time resource(s) are created. + * A second dictionary argument with `areExistingResources` boolean + * attribute helps knowing if that's live resources, or some coming + * from ResourceCommand cache. + * - {Function} onUpdated: This attribute is optional. + * Function which will be called with an array of updates resources + * each time resource(s) are updated. + * These resources were previously notified via onAvailable. + * - {Function} onDestroyed: This attribute is optional. + * Function which will be called with an array of deleted resources + * each time resource(s) are destroyed. + * - {boolean} ignoreExistingResources: + * This attribute is optional. Default value is false. + * If set to true, onAvailable won't be called with + * existing resources. + */ + async watchResources(resources, options) { + const { + onAvailable, + onUpdated, + onDestroyed, + ignoreExistingResources = false, + } = options; + + if (typeof onAvailable !== "function") { + throw new Error( + "ResourceCommand.watchResources expects an onAvailable function as argument" + ); + } + + for (const type of resources) { + if (!this._isValidResourceType(type)) { + throw new Error( + `ResourceCommand.watchResources invoked with an unknown type: "${type}"` + ); + } + } + + // Pending watchers are used in unwatchResources to remove watchers which + // are not fully registered yet. Store `onAvailable` which is the unique key + // for a watcher, as well as the resources array, so that unwatchResources + // can update the array if we stop watching a specific resource. + const pendingWatcher = { + resources, + onAvailable, + }; + this._pendingWatchers.add(pendingWatcher); + + // Bug 1675763: Watcher actor is not available in all situations yet. + if (!this._listenerRegistered && this.watcherFront) { + this._listenerRegistered = true; + // Resources watched from the parent process will be emitted on the Watcher Actor. + // So that we also have to listen for this event on it, in addition to all targets. + this.watcherFront.on( + "resource-available-form", + this._onResourceAvailable.bind(this, { + watcherFront: this.watcherFront, + }) + ); + this.watcherFront.on( + "resource-updated-form", + this._onResourceUpdated.bind(this, { watcherFront: this.watcherFront }) + ); + this.watcherFront.on( + "resource-destroyed-form", + this._onResourceDestroyed.bind(this, { + watcherFront: this.watcherFront, + }) + ); + } + + const promises = []; + for (const resource of resources) { + promises.push(this._startListening(resource)); + } + await Promise.all(promises); + + // The resource cache is immediately filled when receiving the sources, but they are + // emitted with a delay due to throttling. Since the cache can contain resources that + // will soon be emitted, we have to flush it before adding the new listeners. + // Otherwise _forwardExistingResources might emit resources that will also be emitted by + // the next `_notifyWatchers` call done when calling `_startListening`, which will pull the + // "already existing" resources. + this._notifyWatchers(); + + // Update the _pendingWatchers set before adding the watcher to _watchers. + this._pendingWatchers.delete(pendingWatcher); + + // If unwatchResources was called in the meantime, use pendingWatcher's + // resources to get the updated list of watched resources. + const watchedResources = pendingWatcher.resources; + + // If no resource needs to be watched anymore, do not add an empty watcher + // to _watchers, and do not notify about cached resources. + if (!watchedResources.length) { + return; + } + + // Register the watcher just after calling _startListening in order to avoid it being called + // for already existing resources, which will optionally be notified via _forwardExistingResources + this._watchers.push({ + resources: watchedResources, + onAvailable, + onUpdated, + onDestroyed, + pendingEvents: [], + }); + + if (!ignoreExistingResources) { + await this._forwardExistingResources(watchedResources, onAvailable); + } + } + + /** + * Stop watching for given type of resources. + * See `watchResources` for the arguments as both methods receive the same. + * Note that `onUpdated` and `onDestroyed` attributes of `options` aren't used here. + * Only `onAvailable` attribute is looked up and we unregister all the other registered callbacks + * when a matching available callback is found. + */ + unwatchResources(resources, options) { + const { onAvailable } = options; + + if (typeof onAvailable !== "function") { + throw new Error( + "ResourceCommand.unwatchResources expects an onAvailable function as argument" + ); + } + + for (const type of resources) { + if (!this._isValidResourceType(type)) { + throw new Error( + `ResourceCommand.unwatchResources invoked with an unknown type: "${type}"` + ); + } + } + + // Unregister the callbacks from the watchers registries. + // Check _watchers for the fully initialized watchers, as well as + // `_pendingWatchers` for new watchers still being created by `watchResources` + const allWatchers = [...this._watchers, ...this._pendingWatchers]; + for (const watcherEntry of allWatchers) { + // onAvailable is the only mandatory argument which ends up being used to match + // the right watcher entry. + if (watcherEntry.onAvailable == onAvailable) { + // Remove all resources that we stop watching. We may still watch for some others. + watcherEntry.resources = watcherEntry.resources.filter(resourceType => { + return !resources.includes(resourceType); + }); + } + } + this._watchers = this._watchers.filter(entry => { + // Remove entries entirely if it isn't watching for any resource type + return !!entry.resources.length; + }); + + // Stop listening to all resources for which we removed the last watcher + for (const resource of resources) { + const isResourceWatched = allWatchers.some(watcherEntry => + watcherEntry.resources.includes(resource) + ); + + // Also check in _listenedResources as we may call unwatchResources + // for resources that we haven't started watching for. + if (!isResourceWatched && this._listenedResources.has(resource)) { + this._stopListening(resource); + } + } + + // Stop watching for targets if we removed the last listener. + if (this._listenedResources.size == 0) { + this._unwatchAllTargets(); + } + } + + /** + * Wait for a single resource of the provided resourceType. + * + * @param {String} resourceType + * One of ResourceCommand.TYPES, type of the expected resource. + * @param {Object} additional options + * - {Boolean} ignoreExistingResources: ignore existing resources or not. + * - {Function} predicate: if provided, will wait until a resource makes + * predicate(resource) return true. + * @return {Promise<Object>} + * Return a promise which resolves once we fully settle the resource listener. + * You should await for its resolution before doing the action which may fire + * your resource. + * This promise will expose an object with `onResource` attribute, + * itself being a promise, which will resolve once a matching resource is received. + */ + async waitForNextResource( + resourceType, + { ignoreExistingResources = false, predicate } = {} + ) { + // If no predicate was provided, convert to boolean to avoid resolving for + // empty `resources` arrays. + predicate = predicate || (resource => !!resource); + + let resolve; + const promise = new Promise(r => (resolve = r)); + const onAvailable = async resources => { + const matchingResource = resources.find(resource => predicate(resource)); + if (matchingResource) { + this.unwatchResources([resourceType], { onAvailable }); + resolve(matchingResource); + } + }; + + await this.watchResources([resourceType], { + ignoreExistingResources, + onAvailable, + }); + return { onResource: promise }; + } + + /** + * Check if there are any watchers for the specified resource. + * + * @param {String} resourceType + * One of ResourceCommand.TYPES + * @return {Boolean} + * If the resources type is beibg watched. + */ + isResourceWatched(resourceType) { + return this._listenedResources.has(resourceType); + } + + /** + * Start watching for all already existing and future targets. + * + * We are using ALL_TYPES, but this won't force listening to all types. + * It will only listen for types which are defined by `TargetCommand.startListening`. + */ + async _watchAllTargets() { + if (!this._watchTargetsPromise) { + // If this is the very first listener registered, of all kind of resource types: + // * we want to start observing targets via TargetCommand + // * _onTargetAvailable will be called for each already existing targets and the next one to come + this._watchTargetsPromise = this.targetCommand.watchTargets({ + types: this.targetCommand.ALL_TYPES, + onAvailable: this._onTargetAvailable, + onDestroyed: this._onTargetDestroyed, + }); + } + return this._watchTargetsPromise; + } + + _unwatchAllTargets() { + if (!this._watchTargetsPromise) { + return; + } + + for (const offList of this._offTargetFrontListeners.values()) { + offList.forEach(off => off()); + } + this._offTargetFrontListeners.clear(); + + this._watchTargetsPromise = null; + this.targetCommand.unwatchTargets({ + types: this.targetCommand.ALL_TYPES, + onAvailable: this._onTargetAvailable, + onDestroyed: this._onTargetDestroyed, + }); + } + + /** + * For a given resource type, start the legacy listeners for all already existing targets. + * Do that only if we have to. If this resourceType requires legacy listeners. + */ + async _startLegacyListenersForExistingTargets(resourceType) { + // If we were already listening to targets, we want to start the legacy listeners + // for all already existing targets. + // + // Only try instantiating the legacy listener, if this resource type: + // - has legacy listener implementation + // (new resource types may not be supported by old runtime and just not be received without breaking anything) + // - isn't supported by the server, or, the target type requires the a legacy listener implementation. + const shouldRunLegacyListeners = + resourceType in LegacyListeners && + (!this.hasResourceCommandSupport(resourceType) || + this._shouldRunLegacyListenerEvenWithWatcherSupport(resourceType)); + if (shouldRunLegacyListeners) { + const promises = []; + const targets = this.targetCommand.getAllTargets( + this.targetCommand.ALL_TYPES + ); + for (const targetFront of targets) { + // We disable warning in case we already registered the legacy listener for this target + // as this code may race with the call from onTargetAvailable if we end up having multiple + // calls to _startListening in parallel. + promises.push( + this._watchResourcesForTarget({ + targetFront, + resourceType, + disableWarning: true, + }) + ); + } + await Promise.all(promises); + } + } + + /** + * Method called by the TargetCommand for each already existing or target which has just been created. + * + * @param {Object} arg + * @param {Front} arg.targetFront + * The Front of the target that is available. + * This Front inherits from TargetMixin and is typically + * composed of a WindowGlobalTargetFront or ContentProcessTargetFront. + * @param {Boolean} arg.isTargetSwitching + * true when the new target was created because of a target switching. + */ + async _onTargetAvailable({ targetFront, isTargetSwitching }) { + const resources = []; + if (isTargetSwitching) { + // WatcherActor currently only watches additional frame targets and + // explicitely ignores top level one that may be created when navigating + // to a new process. + // In order to keep working resources that are being watched via the + // Watcher actor, we have to unregister and re-register the resource + // types. This will force calling `Resources.watchResources` on the new top + // level target. + for (const resourceType of Object.values(ResourceCommand.TYPES)) { + // ...which has at least one listener... + if (!this._listenedResources.has(resourceType)) { + continue; + } + + if (this._shouldRestartListenerOnTargetSwitching(resourceType)) { + this._stopListening(resourceType, { + bypassListenerCount: true, + }); + resources.push(resourceType); + } + } + } + + if (targetFront.isDestroyed()) { + return; + } + + // If we are target switching, we already stop & start listening to all the + // currently monitored resources. + if (!isTargetSwitching) { + // For each resource type... + for (const resourceType of Object.values(ResourceCommand.TYPES)) { + // ...which has at least one listener... + if (!this._listenedResources.has(resourceType)) { + continue; + } + // ...request existing resource and new one to come from this one target + // *but* only do that for backward compat, where we don't have the watcher API + // (See bug 1626647) + await this._watchResourcesForTarget({ targetFront, resourceType }); + } + } + + // Compared to the TargetCommand and Watcher.watchTargets, + // We do call Watcher.watchResources, but the events are fired on the target. + // That's because the Watcher runs in the parent process/main thread, while resources + // are available from the target's process/thread. + const offResourceAvailable = targetFront.on( + "resource-available-form", + this._onResourceAvailable.bind(this, { targetFront }) + ); + const offResourceUpdated = targetFront.on( + "resource-updated-form", + this._onResourceUpdated.bind(this, { targetFront }) + ); + const offResourceDestroyed = targetFront.on( + "resource-destroyed-form", + this._onResourceDestroyed.bind(this, { targetFront }) + ); + + const offList = this._offTargetFrontListeners.get(targetFront) || []; + offList.push( + offResourceAvailable, + offResourceUpdated, + offResourceDestroyed + ); + + if (isTargetSwitching) { + await Promise.all( + resources.map(resourceType => + this._startListening(resourceType, { + bypassListenerCount: true, + }) + ) + ); + } + + // DOCUMENT_EVENT's will-navigate should replace target actor's will-navigate event, + // but only for targets provided by the watcher actor. + // Emit a fake DOCUMENT_EVENT's "will-navigate" out of target actor's will-navigate + // until watcher actor is supported by all descriptors (bug 1675763). + if (!this.targetCommand.hasTargetWatcherSupport()) { + const offWillNavigate = targetFront.on( + "will-navigate", + ({ url, isFrameSwitching }) => { + targetFront.emit("resource-available-form", [ + { + resourceType: this.TYPES.DOCUMENT_EVENT, + name: "will-navigate", + time: Date.now(), // will-navigate was not passing any timestamp + isFrameSwitching, + newURI: url, + }, + ]); + } + ); + offList.push(offWillNavigate); + } + + this._offTargetFrontListeners.set(targetFront, offList); + } + + _shouldRestartListenerOnTargetSwitching(resourceType) { + // Note that we aren't using isServerTargetSwitchingEnabled, nor checking the + // server side target switching preference as we may have server side targets + // even when this is false/disabled. + // This will happen for bfcache navigations, even with server side targets disabled. + // `followWindowGlobalLifeCycle` will be false for the first top level target + // and only become true when doing a bfcache navigation. + // (only server side targets follow the WindowGlobal lifecycle) + // When server side targets are enabled, this will always be true. + const isServerSideTarget = + this.targetCommand.targetFront.targetForm.followWindowGlobalLifeCycle; + if (isServerSideTarget) { + // For top-level targets created from the server, only restart legacy + // listeners. + return !this.hasResourceCommandSupport(resourceType); + } + + // For top-level targets created from the client we should always restart + // listeners. + return true; + } + + /** + * Method called by the TargetCommand when a target has just been destroyed + * @param {Object} arg + * @param {Front} arg.targetFront + * The Front of the target that was destroyed + * @param {Boolean} arg.isModeSwitching + * true when this is called as the result of a change to the devtools.browsertoolbox.scope pref. + */ + _onTargetDestroyed({ targetFront, isModeSwitching }) { + // Clear the map of legacy listeners for this target. + this._existingLegacyListeners.set(targetFront, []); + this._offTargetFrontListeners.delete(targetFront); + + // Purge the cache from any resource related to the destroyed target. + // Top level BrowsingContext target will be purge via DOCUMENT_EVENT will-navigate events. + // If we were to clean resources from target-destroyed, we will clear resources + // happening between will-navigate and target-destroyed. Typically the navigation request + // At the moment, isModeSwitching can only be true when targetFront.isTopLevel isn't true, + // so we don't need to add a specific check for isModeSwitching. + if (!targetFront.isTopLevel || !targetFront.isBrowsingContext) { + for (const [key, resource] of this._cache) { + if (resource.targetFront === targetFront) { + // NOTE: To anyone paranoid like me, yes it is okay to delete from a Map while iterating it. + this._cache.delete(key); + } + } + } + + // Purge "available" pendingEvents for resources from the destroyed target when switching + // mode as we want to ignore those. + if (isModeSwitching) { + for (const watcherEntry of this._watchers) { + for (const pendingEvent of watcherEntry.pendingEvents) { + if (pendingEvent.callbackType == "available") { + pendingEvent.updates = pendingEvent.updates.filter( + update => update.targetFront !== targetFront + ); + } + } + } + } + } + + /** + * Method called either by: + * - the backward compatibility code (LegacyListeners) + * - target actors RDP events + * whenever an already existing resource is being listed or when a new one + * has been created. + * + * @param {Object} source + * A dictionary object with only one of these two attributes: + * - targetFront: a Target Front, if the resource is watched from the target process or thread + * - watcherFront: a Watcher Front, if the resource is watched from the parent process + * @param {Array<json/Front>} resources + * Depending on the resource Type, it can be an Array composed of either JSON objects or Fronts, + * which describes the resource. + */ + async _onResourceAvailable({ targetFront, watcherFront }, resources) { + let includesDocumentEventWillNavigate = false; + let includesDocumentEventDomLoading = false; + for (let resource of resources) { + const { resourceType } = resource; + + if (watcherFront) { + targetFront = await this._getTargetForWatcherResource(resource); + // When we receive resources from the Watcher actor, + // there is no guarantee that the target front is fully initialized. + // The Target Front is initialized by the TargetCommand, by calling TargetFront.attachAndInitThread. + // We have to wait for its completion as resources watchers are expecting it to be completed. + // + // But when navigating, we may receive resources packets for a destroyed target. + // Or, in the context of the browser toolbox, they may not relate to any target. + if (targetFront) { + await targetFront.initialized; + } + } + + // isAlreadyExistingResource indicates that the resources already existed before + // the resource command started watching for this type of resource. + resource.isAlreadyExistingResource = + this._processingExistingResources.has(resourceType); + + // Put the targetFront on the resource for easy retrieval. + // (Resources from the legacy listeners may already have the attribute set) + if (!resource.targetFront) { + resource.targetFront = targetFront; + } + + if (ResourceTransformers[resourceType]) { + resource = ResourceTransformers[resourceType]({ + resource, + targetCommand: this.targetCommand, + targetFront, + watcherFront: this.watcherFront, + }); + } + + if (!resource.resourceId) { + resource.resourceId = `auto:${++gLastResourceId}`; + } + + // Only consider top level document, and ignore remote iframes top document + const isWillNavigate = + resourceType == ResourceCommand.TYPES.DOCUMENT_EVENT && + resource.name == "will-navigate"; + if (isWillNavigate && resource.targetFront.isTopLevel) { + includesDocumentEventWillNavigate = true; + this._onWillNavigate(resource.targetFront); + } + + if ( + resourceType == ResourceCommand.TYPES.DOCUMENT_EVENT && + resource.name == "dom-loading" && + resource.targetFront.isTopLevel + ) { + includesDocumentEventDomLoading = true; + } + + this._queueResourceEvent("available", resourceType, resource); + + // Avoid storing will-navigate resource and consider it as a transcient resource. + // We do that to prevent leaking this resource (and its target) on navigation. + // We do clear the cache in _onWillNavigate, that we call a few lines before this. + if (!isWillNavigate) { + this.addResourceToCache(resource); + } + } + + // If we receive the DOCUMENT_EVENT for: + // - will-navigate + // - dom-loading + we're using the service worker legacy listener + // then flush immediately the resources to notify about the navigation sooner than later. + // (this is especially useful for tests, even if they should probably avoid depending on this...) + if ( + includesDocumentEventWillNavigate || + (includesDocumentEventDomLoading && + !this.targetCommand.hasTargetWatcherSupport("service_worker")) || + this.throttlingDisabled + ) { + this._notifyWatchers(); + } else { + this._throttledNotifyWatchers(); + } + } + + /** + * Method called either by: + * - the backward compatibility code (LegacyListeners) + * - target actors RDP events + * Called everytime a resource is updated in the remote target. + * + * @param {Object} source + * Please see _onResourceAvailable for this parameter. + * @param {Array<Object>} updates + * Depending on the listener. + * + * Among the element in the array, the following attributes are given special handling. + * - resourceType {String}: + * The type of resource to be updated. + * - resourceId {String}: + * The id of resource to be updated. + * - resourceUpdates {Object}: + * If resourceUpdates is in the element, a cached resource specified by resourceType + * and resourceId is updated by Object.assign(cachedResource, resourceUpdates). + * - nestedResourceUpdates {Object}: + * If `nestedResourceUpdates` is passed, update one nested attribute with a new value + * This allows updating one attribute of an object stored in a resource's attribute, + * as well as adding new elements to arrays. + * `path` is an array mentioning all nested attribute to walk through. + * `value` is the new nested attribute value to set. + * + * And also, the element is passed to the listener as it is as “update” object. + * So if we don't want to update a cached resource but have information want to + * pass on to the listener, can pass it on using attributes other than the ones + * listed above. + * For example, if the element consists of like + * "{ resourceType:… resourceId:…, testValue: “test”, }”, + * the listener can receive the value as follows. + * + * onResourceUpdate({ update }) { + * console.log(update.testValue); // “test” should be displayed + * } + */ + async _onResourceUpdated({ targetFront, watcherFront }, updates) { + for (const update of updates) { + const { + resourceType, + resourceId, + resourceUpdates, + nestedResourceUpdates, + } = update; + + if (!resourceId) { + console.warn(`Expected resource ${resourceType} to have a resourceId`); + } + + // See _onResourceAvailable() + // We also need to wait for the related targetFront to be initialized + // otherwise we would notify about the udpate *before* the available + // and the resource won't be in _cache. + if (watcherFront) { + targetFront = await this._getTargetForWatcherResource(update); + // When we receive the navigation request, the target front has already been + // destroyed, but this is fine. The cached resource has the reference to + // the (destroyed) target front and it is fully initialized. + if (targetFront) { + await targetFront.initialized; + } + } + + const existingResource = this._cache.get( + cacheKey(resourceType, resourceId) + ); + if (!existingResource) { + continue; + } + + if (resourceUpdates) { + Object.assign(existingResource, resourceUpdates); + } + + if (nestedResourceUpdates) { + for (const { path, value } of nestedResourceUpdates) { + let target = existingResource; + + for (let i = 0; i < path.length - 1; i++) { + target = target[path[i]]; + } + + target[path[path.length - 1]] = value; + } + } + this._queueResourceEvent("updated", resourceType, { + resource: existingResource, + update, + }); + } + this._throttledNotifyWatchers(); + } + + /** + * Called everytime a resource is destroyed in the remote target. + * See _onResourceAvailable for the argument description. + */ + async _onResourceDestroyed({ targetFront, watcherFront }, resources) { + for (const resource of resources) { + const { resourceType, resourceId } = resource; + this._cache.delete(cacheKey(resourceType, resourceId)); + if (!resource.targetFront) { + resource.targetFront = targetFront; + } + this._queueResourceEvent("destroyed", resourceType, resource); + } + this._throttledNotifyWatchers(); + } + + _queueResourceEvent(callbackType, resourceType, update) { + for (const { resources, pendingEvents } of this._watchers) { + // This watcher doesn't listen to this type of resource + if (!resources.includes(resourceType)) { + continue; + } + // If we receive a new event of the same type, accumulate the new update in the last event + if (pendingEvents.length) { + const lastEvent = pendingEvents[pendingEvents.length - 1]; + if (lastEvent.callbackType == callbackType) { + lastEvent.updates.push(update); + continue; + } + } + // Otherwise, pile up a new event, which will force calling watcher + // callback a new time + pendingEvents.push({ + callbackType, + updates: [update], + }); + } + } + + /** + * Flush the pending event and notify all the currently registered watchers + * about all the available, updated and destroyed events that have been accumulated in + * `_watchers`'s `pendingEvents` arrays. + */ + _notifyWatchers() { + for (const watcherEntry of this._watchers) { + const { onAvailable, onUpdated, onDestroyed, pendingEvents } = + watcherEntry; + // Immediately clear the buffer in order to avoid possible races, where an event listener + // would end up somehow adding a new throttled resource + watcherEntry.pendingEvents = []; + + for (const { callbackType, updates } of pendingEvents) { + try { + if (callbackType == "available") { + onAvailable(updates, { areExistingResources: false }); + } else if (callbackType == "updated" && onUpdated) { + onUpdated(updates); + } else if (callbackType == "destroyed" && onDestroyed) { + onDestroyed(updates); + } + } catch (e) { + console.error( + "Exception while calling a ResourceCommand", + callbackType, + "callback", + ":", + e + ); + } + } + } + } + + // Compute the target front if the resource comes from the Watcher Actor. + // (`targetFront` will be null as the watcher is in the parent process + // and targets are in distinct processes) + _getTargetForWatcherResource(resource) { + const { browsingContextID, innerWindowId, resourceType } = resource; + + // Some privileged resources aren't related to any BrowsingContext + // and so aren't bound to any Target Front. + // Server watchers should pass an explicit "-1" value in order to prevent + // silently ignoring an undefined browsingContextID attribute. + if (browsingContextID == -1) { + return null; + } + + if (innerWindowId && this.targetCommand.isServerTargetSwitchingEnabled()) { + return this.watcherFront.getWindowGlobalTargetByInnerWindowId( + innerWindowId + ); + } else if (browsingContextID) { + return this.watcherFront.getWindowGlobalTarget(browsingContextID); + } + console.error( + `Resource of ${resourceType} is missing a browsingContextID or innerWindowId attribute` + ); + return null; + } + + _onWillNavigate(targetFront) { + // Special case for toolboxes debugging a document, + // purge the cache entirely when we start navigating to a new document. + // Other toolboxes and additional target for remote iframes or content process + // will be purge from onTargetDestroyed. + + // NOTE: we could `clear` the cache here, but technically if anything is + // currently iterating over resources provided by getAllResources, that + // would interfere with their iteration. We just assign a new Map here to + // leave those iterators as is. + this._cache = new Map(); + } + + /** + * Tells if the server supports listening to the given resource type + * via the watcher actor's watchResources method. + * + * @return {Boolean} True, if the server supports this type. + */ + hasResourceCommandSupport(resourceType) { + return this.watcherFront?.traits?.resources?.[resourceType]; + } + + /** + * Tells if the server supports listening to the given resource type + * via the watcher actor's watchResources method, and that, for a specific + * target. + * + * @return {Boolean} True, if the server supports this type. + */ + _hasResourceCommandSupportForTarget(resourceType, targetFront) { + // First check if the watcher supports this target type. + // If it doesn't, no resource type can be listened via the Watcher actor for this target. + if (!this.targetCommand.hasTargetWatcherSupport(targetFront.targetType)) { + return false; + } + + return this.hasResourceCommandSupport(resourceType); + } + + _isValidResourceType(type) { + return this.ALL_TYPES.includes(type); + } + + /** + * Start listening for a given type of resource. + * For backward compatibility code, we register the legacy listeners on + * each individual target + * + * @param {String} resourceType + * One string of ResourceCommand.TYPES, which designates the types of resources + * to be listened. + * @param {Object} + * - {Boolean} bypassListenerCount + * Pass true to avoid checking/updating the listenersCount map. + * Exclusively used when target switching, to stop & start listening + * to all resources. + */ + async _startListening(resourceType, { bypassListenerCount = false } = {}) { + if (!bypassListenerCount) { + if (this._listenedResources.has(resourceType)) { + return; + } + this._listenedResources.add(resourceType); + } + + this._processingExistingResources.add(resourceType); + + // Ensuring enabling listening to targets. + // This will be a no-op expect for the very first call to `_startListening`, + // where it is going to call `onTargetAvailable` for all already existing targets, + // as well as for those who will be created later. + // + // Do this *before* calling WatcherActor.watchResources in order to register "resource-available" + // listeners on targets before these events start being emitted. + await this._watchAllTargets(resourceType); + + // When we are calling _startListening for the first time, _watchAllTargets + // will register legacylistener when it will call onTargetAvailable for all existing targets. + // But for any next calls to _startListening, _watchAllTargets will be a no-op, + // and nothing will start legacy listener for each already registered targets. + await this._startLegacyListenersForExistingTargets(resourceType); + + // If the server supports the Watcher API and the Watcher supports + // this resource type, use this API + if (this.hasResourceCommandSupport(resourceType)) { + await this.watcherFront.watchResources([resourceType]); + } + this._processingExistingResources.delete(resourceType); + } + + /** + * Return true if the resource should be watched via legacy listener, + * even when watcher supports this resource type. + * + * Bug 1678385: In order to support watching for JS Source resource + * for service workers and parent process workers, which aren't supported yet + * by the watcher actor, we do not bail out here and allow to execute + * the legacy listener for these targets. + * Once bug 1608848 is fixed, we can remove this and never trigger + * the legacy listeners codepath for these resource types. + * + * If this isn't fixed soon, we may add other resources we want to see + * being fetched from these targets. + */ + _shouldRunLegacyListenerEvenWithWatcherSupport(resourceType) { + return WORKER_RESOURCE_TYPES.includes(resourceType); + } + + async _forwardExistingResources(resourceTypes, onAvailable) { + const existingResources = []; + for (const resource of this._cache.values()) { + if (resourceTypes.includes(resource.resourceType)) { + existingResources.push(resource); + } + } + if (existingResources.length) { + await onAvailable(existingResources, { areExistingResources: true }); + } + } + + /** + * Call backward compatibility code from `LegacyListeners` in order to listen for a given + * type of resource from a given target. + */ + async _watchResourcesForTarget({ + targetFront, + resourceType, + disableWarning = false, + }) { + if (this._hasResourceCommandSupportForTarget(resourceType, targetFront)) { + // This resource / target pair should already be handled by the watcher, + // no need to start legacy listeners. + return; + } + + // All workers target types are still not supported by the watcher + // so that we have to spawn legacy listener for all their resources. + // But some resources are irrelevant to workers, like network events. + // And we removed the related legacy listener as they are no longer used. + if ( + targetFront.targetType.endsWith("worker") && + !WORKER_RESOURCE_TYPES.includes(resourceType) + ) { + return; + } + + if (targetFront.isDestroyed()) { + return; + } + + const onAvailable = this._onResourceAvailable.bind(this, { targetFront }); + const onUpdated = this._onResourceUpdated.bind(this, { targetFront }); + const onDestroyed = this._onResourceDestroyed.bind(this, { targetFront }); + + if (!(resourceType in LegacyListeners)) { + throw new Error(`Missing legacy listener for ${resourceType}`); + } + + const legacyListeners = + this._existingLegacyListeners.get(targetFront) || []; + if (legacyListeners.includes(resourceType)) { + if (!disableWarning) { + console.warn( + `Already started legacy listener for ${resourceType} on ${targetFront.actorID}` + ); + } + return; + } + this._existingLegacyListeners.set( + targetFront, + legacyListeners.concat(resourceType) + ); + + try { + await LegacyListeners[resourceType]({ + targetCommand: this.targetCommand, + targetFront, + onAvailable, + onDestroyed, + onUpdated, + }); + } catch (e) { + // Swallow the error to avoid breaking calls to watchResources which will + // loop on all existing targets to create legacy listeners. + // If a legacy listener fails to handle a target for some reason, we + // should still try to process other targets as much as possible. + // See Bug 1687645. + console.error( + `Failed to start [${resourceType}] legacy listener for target ${targetFront.actorID}`, + e + ); + } + } + + /** + * Reverse of _startListening. Stop listening for a given type of resource. + * For backward compatibility, we unregister from each individual target. + * + * See _startListening for parameters description. + */ + _stopListening(resourceType, { bypassListenerCount = false } = {}) { + if (!bypassListenerCount) { + if (!this._listenedResources.has(resourceType)) { + throw new Error( + `Stopped listening for resource '${resourceType}' that isn't being listened to` + ); + } + this._listenedResources.delete(resourceType); + } + + // Clear the cached resources of the type. + for (const [key, resource] of this._cache) { + if (resource.resourceType == resourceType) { + // NOTE: To anyone paranoid like me, yes it is okay to delete from a Map while iterating it. + this._cache.delete(key); + } + } + + // If the server supports the Watcher API and the Watcher supports + // this resource type, use this API + if (this.hasResourceCommandSupport(resourceType)) { + if (!this.watcherFront.isDestroyed()) { + this.watcherFront.unwatchResources([resourceType]); + } + + const shouldRunLegacyListeners = + this._shouldRunLegacyListenerEvenWithWatcherSupport(resourceType); + if (!shouldRunLegacyListeners) { + return; + } + } + // Otherwise, fallback on backward compat mode and use LegacyListeners. + + // If this was the last listener, we should stop watching these events from the actors + // and the actors should stop watching things from the platform + const targets = this.targetCommand.getAllTargets( + this.targetCommand.ALL_TYPES + ); + for (const target of targets) { + this._unwatchResourcesForTarget(target, resourceType); + } + } + + /** + * Backward compatibility code, reverse of _watchResourcesForTarget. + */ + _unwatchResourcesForTarget(targetFront, resourceType) { + if (this._hasResourceCommandSupportForTarget(resourceType, targetFront)) { + // This resource / target pair should already be handled by the watcher, + // no need to stop legacy listeners. + } + // Is there really a point in: + // - unregistering `onAvailable` RDP event callbacks from target-scoped actors? + // - calling `stopListeners()` as we are most likely closing the toolbox and destroying everything? + // + // It is important to keep this method synchronous and do as less as possible + // in the case of toolbox destroy. + // + // We are aware of one case where that might be useful. + // When a panel is disabled via the options panel, after it has been opened. + // Would that justify doing this? Is there another usecase? + + // XXX: This is most likely only needed to avoid growing the Map infinitely. + // Unless in the "disabled panel" use case mentioned in the comment above, + // we should not see the same target actorID again. + const listeners = this._existingLegacyListeners.get(targetFront); + if (listeners && listeners.includes(resourceType)) { + const remainingListeners = listeners.filter(l => l !== resourceType); + this._existingLegacyListeners.set(targetFront, remainingListeners); + } + } +} + +ResourceCommand.TYPES = ResourceCommand.prototype.TYPES = { + CONSOLE_MESSAGE: "console-message", + CSS_CHANGE: "css-change", + CSS_MESSAGE: "css-message", + CSS_REGISTERED_PROPERTIES: "css-registered-properties", + ERROR_MESSAGE: "error-message", + PLATFORM_MESSAGE: "platform-message", + DOCUMENT_EVENT: "document-event", + ROOT_NODE: "root-node", + STYLESHEET: "stylesheet", + NETWORK_EVENT: "network-event", + WEBSOCKET: "websocket", + COOKIE: "cookies", + LOCAL_STORAGE: "local-storage", + SESSION_STORAGE: "session-storage", + CACHE_STORAGE: "Cache", + EXTENSION_STORAGE: "extension-storage", + INDEXED_DB: "indexed-db", + NETWORK_EVENT_STACKTRACE: "network-event-stacktrace", + REFLOW: "reflow", + SOURCE: "source", + THREAD_STATE: "thread-state", + JSTRACER_TRACE: "jstracer-trace", + JSTRACER_STATE: "jstracer-state", + SERVER_SENT_EVENT: "server-sent-event", + LAST_PRIVATE_CONTEXT_EXIT: "last-private-context-exit", +}; +ResourceCommand.ALL_TYPES = ResourceCommand.prototype.ALL_TYPES = Object.values( + ResourceCommand.TYPES +); +module.exports = ResourceCommand; + +// This is the list of resource types supported by workers. +// We need such list to know when forcing to run the legacy listeners +// and when to avoid try to spawn some unsupported ones for workers. +const WORKER_RESOURCE_TYPES = [ + ResourceCommand.TYPES.CONSOLE_MESSAGE, + ResourceCommand.TYPES.ERROR_MESSAGE, + ResourceCommand.TYPES.SOURCE, + ResourceCommand.TYPES.THREAD_STATE, +]; + +// Backward compat code for each type of resource. +// Each section added here should eventually be removed once the equivalent server +// code is implement in Firefox, in its release channel. +const LegacyListeners = { + async [ResourceCommand.TYPES.DOCUMENT_EVENT]({ + targetCommand, + targetFront, + onAvailable, + }) { + // DocumentEventsListener of webconsole handles only top level document. + if (!targetFront.isTopLevel) { + return; + } + + const webConsoleFront = await targetFront.getFront("console"); + webConsoleFront.on("documentEvent", event => { + event.resourceType = ResourceCommand.TYPES.DOCUMENT_EVENT; + onAvailable([event]); + }); + await webConsoleFront.startListeners(["DocumentEvents"]); + }, +}; +loader.lazyRequireGetter( + LegacyListeners, + ResourceCommand.TYPES.CONSOLE_MESSAGE, + "resource://devtools/shared/commands/resource/legacy-listeners/console-messages.js" +); +loader.lazyRequireGetter( + LegacyListeners, + ResourceCommand.TYPES.CSS_CHANGE, + "resource://devtools/shared/commands/resource/legacy-listeners/css-changes.js" +); +loader.lazyRequireGetter( + LegacyListeners, + ResourceCommand.TYPES.CSS_MESSAGE, + "resource://devtools/shared/commands/resource/legacy-listeners/css-messages.js" +); +loader.lazyRequireGetter( + LegacyListeners, + ResourceCommand.TYPES.ERROR_MESSAGE, + "resource://devtools/shared/commands/resource/legacy-listeners/error-messages.js" +); +loader.lazyRequireGetter( + LegacyListeners, + ResourceCommand.TYPES.PLATFORM_MESSAGE, + "resource://devtools/shared/commands/resource/legacy-listeners/platform-messages.js" +); +loader.lazyRequireGetter( + LegacyListeners, + ResourceCommand.TYPES.ROOT_NODE, + "resource://devtools/shared/commands/resource/legacy-listeners/root-node.js" +); + +loader.lazyRequireGetter( + LegacyListeners, + ResourceCommand.TYPES.SOURCE, + "resource://devtools/shared/commands/resource/legacy-listeners/source.js" +); +loader.lazyRequireGetter( + LegacyListeners, + ResourceCommand.TYPES.THREAD_STATE, + "resource://devtools/shared/commands/resource/legacy-listeners/thread-states.js" +); + +loader.lazyRequireGetter( + LegacyListeners, + ResourceCommand.TYPES.REFLOW, + "resource://devtools/shared/commands/resource/legacy-listeners/reflow.js" +); + +// Optional transformers for each type of resource. +// Each module added here should be a function that will receive the resource, the target, … +// and perform some transformation on the resource before it will be emitted. +// This is a good place to handle backward compatibility and manual resource marshalling. +const ResourceTransformers = {}; + +loader.lazyRequireGetter( + ResourceTransformers, + ResourceCommand.TYPES.CONSOLE_MESSAGE, + "resource://devtools/shared/commands/resource/transformers/console-messages.js" +); +loader.lazyRequireGetter( + ResourceTransformers, + ResourceCommand.TYPES.ERROR_MESSAGE, + "resource://devtools/shared/commands/resource/transformers/error-messages.js" +); +loader.lazyRequireGetter( + ResourceTransformers, + ResourceCommand.TYPES.CACHE_STORAGE, + "resource://devtools/shared/commands/resource/transformers/storage-cache.js" +); +loader.lazyRequireGetter( + ResourceTransformers, + ResourceCommand.TYPES.COOKIE, + "resource://devtools/shared/commands/resource/transformers/storage-cookie.js" +); +loader.lazyRequireGetter( + ResourceTransformers, + ResourceCommand.TYPES.EXTENSION_STORAGE, + "resource://devtools/shared/commands/resource/transformers/storage-extension.js" +); +loader.lazyRequireGetter( + ResourceTransformers, + ResourceCommand.TYPES.INDEXED_DB, + "resource://devtools/shared/commands/resource/transformers/storage-indexed-db.js" +); +loader.lazyRequireGetter( + ResourceTransformers, + ResourceCommand.TYPES.LOCAL_STORAGE, + "resource://devtools/shared/commands/resource/transformers/storage-local-storage.js" +); +loader.lazyRequireGetter( + ResourceTransformers, + ResourceCommand.TYPES.SESSION_STORAGE, + "resource://devtools/shared/commands/resource/transformers/storage-session-storage.js" +); +loader.lazyRequireGetter( + ResourceTransformers, + ResourceCommand.TYPES.NETWORK_EVENT, + "resource://devtools/shared/commands/resource/transformers/network-events.js" +); +loader.lazyRequireGetter( + ResourceTransformers, + ResourceCommand.TYPES.THREAD_STATE, + "resource://devtools/shared/commands/resource/transformers/thread-states.js" +); |