summaryrefslogtreecommitdiffstats
path: root/devtools/docs
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-05-15 03:34:50 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-05-15 03:34:50 +0000
commitdef92d1b8e9d373e2f6f27c366d578d97d8960c6 (patch)
tree2ef34b9ad8bb9a9220e05d60352558b15f513894 /devtools/docs
parentAdding debian version 125.0.3-1. (diff)
downloadfirefox-def92d1b8e9d373e2f6f27c366d578d97d8960c6.tar.xz
firefox-def92d1b8e9d373e2f6f27c366d578d97d8960c6.zip
Merging upstream version 126.0.
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'devtools/docs')
-rw-r--r--devtools/docs/contributor/backend/watcher-architecture.md233
-rw-r--r--devtools/docs/contributor/index.rst1
2 files changed, 234 insertions, 0 deletions
diff --git a/devtools/docs/contributor/backend/watcher-architecture.md b/devtools/docs/contributor/backend/watcher-architecture.md
new file mode 100644
index 0000000000..48d316e35c
--- /dev/null
+++ b/devtools/docs/contributor/backend/watcher-architecture.md
@@ -0,0 +1,233 @@
+
+# Server side overview
+
+## Connecting to backend
+
+The DevTools backend exposes a RDP server that the client can query. See Client API <client-api.md>
+
+## Picking a particular context to debug
+
+The client will typically query the Root Actor for one particular Descriptor Actor which will designate what piece of the browser to debug. See <actor-hierarchy.md>.
+
+The typical scenario is for the client to query a [TabDescriptorActor](https://searchfox.org/mozilla-central/source/devtools/server/actors/descriptors/tab.js) in order to debug one particular tab.
+
+## The Watcher Actor
+
+Then, once you set a particular context to debug, you are retrieving one [WatcherActor](https://searchfox.org/mozilla-central/source/devtools/server/actors/watcher.js) instance.
+This actor is a pillar of DevTools backend as it will coordinate the observation of everything.
+
+### Debuggable contexts / DevTools Targets
+
+First you will use `WatcherActor.watchTarget(String targetType)` method to define the child debugging contexts you are interested in.
+This method will only resolve after having been notified of all the existing debuggable contexts.
+Then a `target-available-form` RDP event is emitted on the WatcherActor for each new debuggable context being created later.
+As well as a `target-destroyed-form` when any debuggable context gets destroyed.
+
+The debugging contexts are called Targets in DevTools jargon and can be:
+
+ * "frame"
+
+ Any document instance running anywhere in the browser.
+ Each very specific document instance will be notified to the client via a dedicated [WindowGlobalTargetActor](https://searchfox.org/mozilla-central/source/devtools/server/actors/targets/window-global.js) instance.
+ This means that if you reload the page, you will have as many target actors as you reload.
+ Also, if there is \<iframe\>s, you will get one frame targets for each iframe.
+
+ * "worker", "service_worker", "shared_worker"
+
+ Any worker instance running anywhere in the browser.
+ Each worker instance will ne notified to the client via a dedicated [WorkerTargetActor](https://searchfox.org/mozilla-central/source/devtools/server/actors/targets/worker.js) instance.
+
+ * "process"
+
+ Any process running in the browser.
+ This is only used for debugging Firefox and not when debugging web pages.
+ Each process will be notified to the client via a dedicated [ProcessTargetActor](https://searchfox.org/mozilla-central/source/devtools/server/actors/targets/content-process.js).
+ You will be notified of as many process targets as there are content processes running.
+
+The target type strings are defined in [devtools/server/actors/targets/index.js](https://searchfox.org/mozilla-central/source/devtools/server/actors/targets/index.js).
+
+Target Actors are exposing many other important actors, like Inspector, WebConsole, Thread Actors. See <actor-hierarchy.md>.
+
+### Resources
+
+Once you started watching for some target types, you can use `WatcherActor.watchResources(Array<String> resourceTypes)` method to be notified about resources for each active Target/Debuggable context.
+This method will only resolve after having been notified of all the existing resources.
+Resources aren't returned by the watchResources method. Instead they are notified to the client via `resource-available-form` RDP events emitted, either on the Watcher Actor or one of the many Target Actors.
+Some resources may also support:
+ * a `resource-updated-form` RDP event, when any resource gets updated (like stylesheets or network events),
+ * a `resource-destroyed-form` RDP event, when any resource gets destroyed (like stylesheets).
+
+The resources can be:
+
+ * "console-message"
+
+ Any `console.log()`, `console.error()`, ... method call, in any of the debuggable context, will be notified to the client via such "console-message" resource.
+
+ * "source"
+
+ Any JavaScript or Wasm source in any of the debuggable context will be notified to the client via such "source" resource.
+
+ * "stylesheet"
+
+ Any StyleSheet, defined by any "frame" debuggable context will be notified to the client via such "stylesheet" resource.
+
+ * Many other things.
+
+ You can find the list of all resources in [devtools/server/resources/](https://searchfox.org/mozilla-central/source/devtools/server/actors/resources) folder.
+
+The resource type strings are defined in [devtools/server/actors/resources/index.js](https://searchfox.org/mozilla-central/source/devtools/server/actors/resources/index.js).
+
+A resource will be a JSON object with attributes specific to each resource type.
+Each resource has a dedicated `ResourceWatcher` class in [devtools/server/actors/resources/](https://searchfox.org/mozilla-central/source/devtools/server/actors/resources/) folder.
+
+Depending on the resource type, they may be observed either in:
+
+ * parent process (regardless of where targets run)
+ * main thread of the target's process
+ * worker thread (if we have a worker target)
+
+This behavior is also defined in [devtools/server/actors/resources/index.js](https://searchfox.org/mozilla-central/source/devtools/server/actors/resources/index.js) via:
+
+ * `ParentProcessResources`
+
+ The ResourceWatcher will be instantiated in the parent process.
+
+ * `FrameTargetResources`
+
+ The ResourceWatcher will be instantiated for "frame" targets, in the main thread of where the frame runs.
+
+ * `ProcessTargetResources`
+
+ The ResourceWatcher will be instantiated for "process" targets, in the main thread of it.
+
+ * `WorkerTargetResources`
+
+ The ResourceWatcher will be instantiated for "worker" targets, in the worker thread.
+
+
+Each resource should then implement the following interface:
+```
+class MyResourceWatcher {
+ /**
+ * Start watching for my resource for a given context.
+ *
+ * This class will be instantiated only once when registered in `ParentProcessResources` and running in the parent process.
+ * Also, the first argument `watcherOrTargetActor` will be a reference to the WatcherActor instance.
+ * In all the other cases, this class will be instantiated once per active Target instance.
+ * In any other case, it will be a reference to a TargetActor.
+ *
+ * Then, the onAvailable, onUpdated and onDestroyed should be called according to their names
+ * for each resource.
+ *
+ * /!\ This method should only resolve **after** having notified via onAvailable about all the existing resource instances.
+ */
+ async watch(watcherOrTargetActor, { onAvailable, onUpdated, onDestroyed }) {
+
+ // Each method except a list of updates
+
+ // onAvailable expects a list of JSON object being Resources Object being passed as-is to the client
+ // There must be a `resourceType` attribute.
+ const {
+ TYPES: { MY_RESOURCE },
+ } = require("devtools/server/actors/resources/index");
+ onAvailable([
+ {
+ resourceType: MY_RESOURCE,
+
+ resourceId: 123, // Mandatory when using onUpdated and/or onDestroyed, otherwise optional
+
+ myResourceSpecificData: 42,
+
+ some: { nested : { object : "foo" } },
+ },
+ ]);
+
+ // onUpdated expects a list of updates against many resource objects previously notified via onAvailable
+ onUpdated([
+ {
+ resourceType: MY_RESOURCE,
+ resourceId, // Same id passed to onAvailable
+
+ // This field allows to update top attributes of your resource object
+ resourceUpdates: {
+ myResourceSpecificData: 43,
+ },
+
+ // This advanced field allows to update any nested object attribute
+ nestedResourceUpdates: [
+ {
+ path: ["some", "nested", "object"],
+ value: "bar",
+ },
+ ],
+ },
+ ]);
+
+ // onDestroyed expects a list of resource to be notified as destroyed to the client
+ onDestroyed([
+ {
+ resourceType: MY_RESOURCE,
+ resourceId, // Same id passed to onAvailable
+ }
+ ]);
+ }
+
+ /**
+ * Stop observing these resources. Unregister any listener to prevent any leak.
+ */
+ destroy() {
+
+ }
+```
+
+
+## How the Watcher Actor handles processes/threads and instantiates the targets actors?
+
+The Watcher Actor is running in the parent process and needs to reach all content processes and threads
+in order to interact with all the debuggable contexts.
+In order to reach all the content processes, the Watcher Actor uses the JS Process Actor API. See <dom/docs/ipc/jsactors.rst>.
+It registers one JS Process Actor called "DevToolsProcess".
+For each `watchTargets` and `watchResources` method call, a new query will be sent through the JS Process Actor to all the processes.
+The JS Process Actor API consists of two distinct modules:
+
+ * One running in the parent process. [DevToolsProcessParent.sys.mjs](https://searchfox.org/mozilla-central/source/devtools/server/connectors/js-process-actor/DevToolsProcessParent.sys.mjs)
+
+ This module is simple. It will mostly forward the queries to the content process when the watcher actor calls some of its methods.
+ It will also receive messages from the content process, and uses the [ParentProcessWatcherRegistry](https://searchfox.org/mozilla-central/source/devtools/server/actors/watcher/ParentProcessWatcherRegistry.sys.mjs) in order to retrieve the related Watcher Actor instance and notify it about the incoming message.
+
+ * One running in the content process. [DevToolsProcessChild.sys.mjs](https://searchfox.org/mozilla-central/source/devtools/server/connectors/js-process-actor/DevToolsProcessChild.sys.mjs)
+
+ This module contains some more logic.
+ When receiving requests to watch for new targets and resources types, this will delegate these requests to many Target Watcher classes.
+ These classes are specific to each target type:
+ * [WindowGlobal](https://searchfox.org/mozilla-central/source/devtools/server/connectors/js-process-actor/target-watchers/window-global.sys.mjs),
+ * [Process](https://searchfox.org/mozilla-central/source/devtools/server/connectors/js-process-actor/target-watchers/process.sys.mjs),
+ * [Worker](https://searchfox.org/mozilla-central/source/devtools/server/connectors/js-process-actor/target-watchers/worker.sys.mjs),
+ * [ServiceWorker](https://searchfox.org/mozilla-central/source/devtools/server/connectors/js-process-actor/target-watchers/service-worker.sys.mjs),
+
+ These classes will:
+ * Instantiate a new Target Actor each time a new matching debuggable contexts gets created.
+ * Destroy the related Target Actor when the contexts gets destroyed.
+ * Dispatch SessionData updates to the target actor. (this includes the watched resources, which are a SessionData attribute)
+ * For workers, this class will also reach the distinct worker thread in order to do all these 3 first bullet points, but from the worker thread.
+
+ Similarly to the parent process codebase, the [ContentProcessWatcherRegistry](https://searchfox.org/mozilla-central/source/devtools/server/connectors/js-process-actor/ContentProcessWatcherRegistry.sys.mjs) maintains an list of objects which represents each active watcher actor. This helps store state in the content process which will be specific to each watcher.
+
+## Session Data
+
+Each Watcher Actor maintains a dedicated Session Data object.
+This is a JSON-serializable object that is meant to be shared across all processes and threads.
+This is easily accessible from any server side code. Modifications are only been done from the parent process,
+but its state is synced across processes and threads.
+
+The list of supported attributes is maintained in [SessionDataHelpers.sys.mjs](https://searchfox.org/mozilla-central/rev/7bbc54b70e348a11f9cd12071ada2cb47c8a14e3/devtools/server/actors/watcher/SessionDataHelpers.sys.mjs)'s `SUPPORTED_DATA` variable.
+Values stored in the session data object are arrays of objects.
+But these arrays are meant to behave like Sets.
+Primitive values (strings, numbers,...) can only exists once per array.
+For objects, `DATA_KEY_FUNCTION` variable in SessionDataHelper module will provide a unique key identifying each element of the arrays.
+
+The Session Data object is maintained in the parent process by [ParentProcessWatcherRegistry](https://searchfox.org/mozilla-central/source/devtools/server/actors/watcher/ParentProcessWatcherRegistry.sys.mjs). This module will store each Watcher Actor's Session Data object.
+Then, the Watcher Actor will use the JS Process Actor in order to communicate updates made to the Session Data Object to all the content processes.
+The Worker Target Watchers are also going to relay the updates to all worker threads.
+
+The Session Data objects of all the watcher actors are also going to be stored in [GlobalProcessScript.sharedData](https://searchfox.org/mozilla-central/rev/b73676a106c1655030bb876fd5e0a6825aee6044/dom/chrome-webidl/MessageManager.webidl#452). This is meant to provide the Session Data to the [DevToolsProcessChild.sys.mjs](https://searchfox.org/mozilla-central/source/devtools/server/connectors/js-process-actor/DevToolsProcessChild.sys.mjs) when a new content process starts. We need to have access to the Session Data the earliest during the startup sequence in order to setup breakpoints. We can't wait for a JS Process Actor query and need immediate access to it. On Process startup, we will read the Session Data from `sharedData` and then maintain the copy via JS Process Actor queries.
diff --git a/devtools/docs/contributor/index.rst b/devtools/docs/contributor/index.rst
index 39de863c86..4f29f27bb5 100644
--- a/devtools/docs/contributor/index.rst
+++ b/devtools/docs/contributor/index.rst
@@ -107,6 +107,7 @@ Backend
:maxdepth: 1
Remote Debugging Protocol <backend/protocol.md>
+ Backend Overview <backend/watcher-architecture.md>
Client API <backend/client-api.md>
Debugger API <backend/debugger-api.md>
Backward Compatibility <backend/backward-compatibility.md>