summaryrefslogtreecommitdiffstats
path: root/remote/shared/messagehandler/MessageHandler.sys.mjs
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 19:33:14 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 19:33:14 +0000
commit36d22d82aa202bb199967e9512281e9a53db42c9 (patch)
tree105e8c98ddea1c1e4784a60a5a6410fa416be2de /remote/shared/messagehandler/MessageHandler.sys.mjs
parentInitial commit. (diff)
downloadfirefox-esr-36d22d82aa202bb199967e9512281e9a53db42c9.tar.xz
firefox-esr-36d22d82aa202bb199967e9512281e9a53db42c9.zip
Adding upstream version 115.7.0esr.upstream/115.7.0esrupstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'remote/shared/messagehandler/MessageHandler.sys.mjs')
-rw-r--r--remote/shared/messagehandler/MessageHandler.sys.mjs357
1 files changed, 357 insertions, 0 deletions
diff --git a/remote/shared/messagehandler/MessageHandler.sys.mjs b/remote/shared/messagehandler/MessageHandler.sys.mjs
new file mode 100644
index 0000000000..ed15ed29b8
--- /dev/null
+++ b/remote/shared/messagehandler/MessageHandler.sys.mjs
@@ -0,0 +1,357 @@
+/* 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/. */
+
+import { XPCOMUtils } from "resource://gre/modules/XPCOMUtils.sys.mjs";
+
+import { EventEmitter } from "resource://gre/modules/EventEmitter.sys.mjs";
+
+const lazy = {};
+
+ChromeUtils.defineESModuleGetters(lazy, {
+ error: "chrome://remote/content/shared/messagehandler/Errors.sys.mjs",
+ EventsDispatcher:
+ "chrome://remote/content/shared/messagehandler/EventsDispatcher.sys.mjs",
+ Log: "chrome://remote/content/shared/Log.sys.mjs",
+ ModuleCache:
+ "chrome://remote/content/shared/messagehandler/ModuleCache.sys.mjs",
+});
+
+XPCOMUtils.defineLazyGetter(lazy, "logger", () => lazy.Log.get());
+
+/**
+ * A ContextDescriptor object provides information to decide if a broadcast or
+ * a session data item should be applied to a specific MessageHandler context.
+ *
+ * @typedef {object} ContextDescriptor
+ * @property {ContextDescriptorType} type
+ * The type of context
+ * @property {string=} id
+ * Unique id of a given context for the provided type.
+ * For ContextDescriptorType.All, id can be ommitted.
+ * For ContextDescriptorType.TopBrowsingContext, the id should be the
+ * browserId corresponding to a top-level browsing context.
+ */
+
+/**
+ * Enum of ContextDescriptor types.
+ *
+ * @enum {string}
+ */
+export const ContextDescriptorType = {
+ All: "All",
+ TopBrowsingContext: "TopBrowsingContext",
+};
+
+/**
+ * A ContextInfo identifies a given context that can be linked to a MessageHandler
+ * instance. It should be used to identify events coming from this context.
+ *
+ * It can either be provided by the MessageHandler itself, when the event is
+ * emitted from the context it relates to.
+ *
+ * Or it can be assembled manually, for instance when emitting an event which
+ * relates to a window global from the root layer (eg browsingContext.contextCreated).
+ *
+ * @typedef {object} ContextInfo
+ * @property {string} contextId
+ * Unique id of the MessageHandler corresponding to this context.
+ * @property {string} type
+ * One of MessageHandler.type.
+ */
+
+/**
+ * MessageHandler instances are dedicated to handle both Commands and Events
+ * to enable automation and introspection for remote control protocols.
+ *
+ * MessageHandler instances are designed to form a network, where each instance
+ * should allow to inspect a specific context (eg. a BrowsingContext, a Worker,
+ * etc). Those instances might live in different processes and threads but
+ * should be linked together by the usage of a single sessionId, shared by all
+ * the instances of a single MessageHandler network.
+ *
+ * MessageHandler instances will be dynamically spawned depending on which
+ * Command or which Event needs to be processed and should therefore not be
+ * explicitly created by consumers, nor used directly.
+ *
+ * The only exception is the ROOT MessageHandler. This MessageHandler will be
+ * the entry point to send commands to the rest of the network. It will also
+ * emit all the relevant events captured by the network.
+ *
+ * However, even to create this ROOT MessageHandler, consumers should use the
+ * RootMessageHandlerRegistry. This singleton will ensure that MessageHandler
+ * instances are properly registered and can be retrieved based on a given
+ * session id as well as some other context information.
+ */
+export class MessageHandler extends EventEmitter {
+ #context;
+ #contextId;
+ #eventsDispatcher;
+ #moduleCache;
+ #registry;
+ #sessionId;
+
+ /**
+ * Create a new MessageHandler instance.
+ *
+ * @param {string} sessionId
+ * ID of the session the handler is used for.
+ * @param {object} context
+ * The context linked to this MessageHandler instance.
+ * @param {MessageHandlerRegistry} registry
+ * The MessageHandlerRegistry which owns this MessageHandler instance.
+ */
+ constructor(sessionId, context, registry) {
+ super();
+
+ this.#moduleCache = new lazy.ModuleCache(this);
+
+ this.#sessionId = sessionId;
+ this.#context = context;
+ this.#contextId = this.constructor.getIdFromContext(context);
+ this.#eventsDispatcher = new lazy.EventsDispatcher(this);
+ this.#registry = registry;
+ }
+
+ get context() {
+ return this.#context;
+ }
+
+ get contextId() {
+ return this.#contextId;
+ }
+
+ get eventsDispatcher() {
+ return this.#eventsDispatcher;
+ }
+
+ get moduleCache() {
+ return this.#moduleCache;
+ }
+
+ get name() {
+ return [this.sessionId, this.constructor.type, this.contextId].join("-");
+ }
+
+ get registry() {
+ return this.#registry;
+ }
+
+ get sessionId() {
+ return this.#sessionId;
+ }
+
+ destroy() {
+ lazy.logger.trace(
+ `MessageHandler ${this.constructor.type} for session ${this.sessionId} is being destroyed`
+ );
+ this.#eventsDispatcher.destroy();
+ this.#moduleCache.destroy();
+
+ // At least the MessageHandlerRegistry will be expecting this event in order
+ // to remove the instance from the registry when destroyed.
+ this.emit("message-handler-destroyed", this);
+ }
+
+ /**
+ * Emit a message handler event.
+ *
+ * Such events should bubble up to the root of a MessageHandler network.
+ *
+ * @param {string} name
+ * Name of the event. Protocol level events should be of the
+ * form [module name].[event name].
+ * @param {object} data
+ * The event's data.
+ * @param {ContextInfo=} contextInfo
+ * The event's context info, used to identify the origin of the event.
+ * If not provided, the context info of the current MessageHandler will be
+ * used.
+ */
+ emitEvent(name, data, contextInfo) {
+ // If no contextInfo field is provided on the event, extract it from the
+ // MessageHandler instance.
+ contextInfo = contextInfo || this.#getContextInfo();
+
+ // Events are emitted both under their own name for consumers listening to
+ // a specific and as `message-handler-event` for consumers which need to
+ // catch all events.
+ this.emit(name, data, contextInfo);
+ this.emit("message-handler-event", {
+ name,
+ contextInfo,
+ data,
+ sessionId: this.sessionId,
+ });
+ }
+
+ /**
+ * @typedef {object} CommandDestination
+ * @property {string} type
+ * One of MessageHandler.type.
+ * @property {string=} id
+ * Unique context identifier. The format depends on the type.
+ * For WINDOW_GLOBAL destinations, this is a browsing context id.
+ * Optional, should only be provided if `contextDescriptor` is missing.
+ * @property {ContextDescriptor=} contextDescriptor
+ * Descriptor used to match several contexts, which will all receive the
+ * command.
+ * Optional, should only be provided if `id` is missing.
+ */
+
+ /**
+ * @typedef {object} Command
+ * @property {string} commandName
+ * The name of the command to execute.
+ * @property {string} moduleName
+ * The name of the module.
+ * @property {object} params
+ * Optional command parameters.
+ * @property {CommandDestination} destination
+ * The destination describing a debuggable context.
+ * @property {boolean=} retryOnAbort
+ * Optional. When true, commands will be retried upon AbortError, which
+ * can occur when the underlying JSWindowActor pair is destroyed.
+ * Defaults to `false`.
+ */
+
+ /**
+ * Retrieve all module classes matching the moduleName and destination.
+ * See `getAllModuleClasses` (ModuleCache.jsm) for more details.
+ *
+ * @param {string} moduleName
+ * The name of the module.
+ * @param {Destination} destination
+ * The destination.
+ * @returns {Array.<class<Module>|null>}
+ * An array of Module classes.
+ */
+ getAllModuleClasses(moduleName, destination) {
+ return this.#moduleCache.getAllModuleClasses(moduleName, destination);
+ }
+
+ /**
+ * Handle a command, either in one of the modules owned by this MessageHandler
+ * or in a another MessageHandler after forwarding the command.
+ *
+ * @param {Command} command
+ * The command that should be either handled in this layer or forwarded to
+ * the next layer leading to the destination.
+ * @returns {Promise} A Promise that will resolve with the return value of the
+ * command once it has been executed.
+ */
+ handleCommand(command) {
+ const { moduleName, commandName, params, destination } = command;
+ lazy.logger.trace(
+ `Received command ${moduleName}.${commandName} for destination ${destination.type}`
+ );
+
+ if (!this.supportsCommand(moduleName, commandName, destination)) {
+ throw new lazy.error.UnsupportedCommandError(
+ `${moduleName}.${commandName} not supported for destination ${destination?.type}`
+ );
+ }
+
+ const module = this.#moduleCache.getModuleInstance(moduleName, destination);
+ if (module && module.supportsMethod(commandName)) {
+ return module[commandName](params, destination);
+ }
+
+ return this.forwardCommand(command);
+ }
+
+ toString() {
+ return `[object ${this.constructor.name} ${this.name}]`;
+ }
+
+ /**
+ * Apply the initial session data items provided to this MessageHandler on
+ * startup. Implementation is specific to each MessageHandler class.
+ *
+ * By default the implementation is a no-op.
+ *
+ * @param {Array<SessionDataItem>} sessionDataItems
+ * Initial session data items for this MessageHandler.
+ */
+ async applyInitialSessionDataItems(sessionDataItems) {}
+
+ /**
+ * Returns the module path corresponding to this MessageHandler class.
+ *
+ * Needs to be implemented in the sub class.
+ */
+ static get modulePath() {
+ throw new Error("Not implemented");
+ }
+
+ /**
+ * Returns the type corresponding to this MessageHandler class.
+ *
+ * Needs to be implemented in the sub class.
+ */
+ static get type() {
+ throw new Error("Not implemented");
+ }
+
+ /**
+ * Returns the id corresponding to a context compatible with this
+ * MessageHandler class.
+ *
+ * Needs to be implemented in the sub class.
+ */
+ static getIdFromContext(context) {
+ throw new Error("Not implemented");
+ }
+
+ /**
+ * Forward a command to other MessageHandlers.
+ *
+ * Needs to be implemented in the sub class.
+ */
+ forwardCommand(command) {
+ throw new Error("Not implemented");
+ }
+
+ /**
+ * Check if contextDescriptor matches the context linked
+ * to this MessageHandler instance.
+ *
+ * Needs to be implemented in the sub class.
+ */
+ matchesContext(contextDescriptor) {
+ throw new Error("Not implemented");
+ }
+
+ /**
+ * Check if the given command is supported in the module
+ * for the destination
+ *
+ * @param {string} moduleName
+ * The name of the module.
+ * @param {string} commandName
+ * The name of the command.
+ * @param {Destination} destination
+ * The destination.
+ * @returns {boolean}
+ * True if the command is supported.
+ */
+ supportsCommand(moduleName, commandName, destination) {
+ return this.getAllModuleClasses(moduleName, destination).some(cls =>
+ cls.supportsMethod(commandName)
+ );
+ }
+
+ /**
+ * Return the context information for this MessageHandler instance, which
+ * can be used to identify the origin of an event.
+ *
+ * @returns {ContextInfo}
+ * The context information for this MessageHandler.
+ */
+ #getContextInfo() {
+ return {
+ contextId: this.contextId,
+ type: this.constructor.type,
+ };
+ }
+}