1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
|
# How actors are organized
To start with, actors are living within devtools/server/actors folder.
They are organized in a hierarchy for easier lifecycle and memory management:
once a parent is removed from the pool, its children are removed as well.
(See actor-registration.md for more information about how to implement one)
The overall hierarchy of actors looks like this:
```
RootActor: First one, automatically instantiated when we start connecting.
| Mostly meant to instantiate new actors.
|
|-- Global-scoped actors:
| Actors exposing features related to the main process, that are not
| specific to any particular target (document, tab, add-on, or worker).
| These actors are registered with `global: true` in
| devtools/server/actors/utils/actor-registry.js
| Examples include:
| PreferenceActor (for Firefox prefs)
|
\-- Descriptor Actor's -or- Watcher Actor
|
\ -- Target actors:
Actors that represent the main "thing" being targeted by a given toolbox,
such as a tab, frame, worker, add-on, etc. and track its lifetime.
Generally, there is a target actor for each thing you can point a
toolbox at.
Examples include:
WindowGlobalTargetActor (for a WindowGlobal, such as a tab or a remote iframe)
ProcessTargetActor
WorkerTargetActor (for various kind of workers)
|
\-- Target-scoped actors:
Actors exposing one particular feature set. They are children of a
given target actor and the data they return is filtered to reflect
the target.
These actors are registered with `target: true` in
devtools/server/actors/utils/actor-registry.js
Examples include:
WebConsoleActor
InspectorActor
These actors may extend this hierarchy by having their own children,
like LongStringActor, WalkerActor, etc.
```
## RootActor
The root actor is special. It is automatically created when a client connects.
It has a special `actorID` which is unique and is "root".
All other actors have an `actorID` which is computed dynamically,
so that you need to ask an existing actor to create an Actor
and returns its `actorID`. That's the main role of RootActor.
```
RootActor (root.js)
|
|-- TabDescriptorActor (descriptors/tab.js)
| Targets frames (such as a tab) living in the parent or child process.
| Returned by "listTabs" or "getTab" requests.
|
|-- WorkerTargetActor (worker.js)
| Targets a worker (applies to various kinds like web worker, service
| worker, etc.).
| Returned by "listWorkers" request to the root actor to get all workers.
| Returned by "listWorkers" request to a WindowGlobalTargetActor to get
| workers for a specific document/WindowGlobal.
| Returned by "listWorkers" request to a ContentProcessTargetActor to get
| workers for the chrome of the child process.
|
|-- ParentProcessTargetActor (parent-process.js)
| Targets all resources in the parent process of Firefox (chrome documents,
| JSMs, JS XPCOM, etc.).
| Extends the abstract class WindowGlobalTargetActor.
| Extended by WebExtensionTargetActor.
| Returned by "getProcess" request without any argument.
|
|-- ContentProcessTargetActor (content-process.js)
| Targets all resources in a content process of Firefox (chrome sandboxes,
| frame scripts, documents, etc.)
| Returned by "getProcess" request with a id argument, matching the
| targeted process.
|
\-- WebExtensionActor (addon/webextension.js)
Represents a WebExtension add-on in the parent process. This gives some
metadata about the add-on and watches for uninstall events. This uses a
proxy to access the actual WebExtension in the WebExtension process via
the message manager.
Returned by "listAddons" request.
|
\-- WebExtensionTargetActor (targets/webextension.js)
Targets a WebExtension add-on. This runs in the WebExtension process.
The client issues an additional "connect" request to
WebExtensionActor to get this actor, which is different from the
approach used for frame target actors.
Extends ParentProcessTargetActor.
Returned by "connect" request to WebExtensionActor.
```
All these descriptor actors expose a `getTarget()` method which
returns the target actor for the descriptor's debuggable context
(tab, worker, process or add-on).
But note that this is now considered as a deprecated codepath.
Ideally, all targets should be retrieved via the new WatcherActor.
For now, the WatcherActor only support tabs and entire browser debugging.
Workers and add-ons still have to go through descriptor's getTarget.
## Target Actors
Those are the actors exposed by the watcher actor, or, via descriptor's getTarget methods.
They are meant to track the lifetime of a given target: document, process, add-on, or worker.
It also allows to fetch the target-scoped actors connected to this target,
which are actors like console, inspector, thread (for debugger), style inspector, etc.
Some target actors inherit from WindowGlobalTargetActor (defined in
window-global.js) which is meant for "window globals" which present
documents to the user. It automatically tracks the lifetime of the targeted
window global, but it also tracks its iframes and allows switching the
target to one of its iframes.
For historical reasons, target actors also handle creating the ThreadActor, used
to manage breakpoints in the debugger. Actors inheriting from
WindowGlobalTargetActor expose `attach`/`detach` requests, that allows to
start/stop the ThreadActor.
Target-scoped actors are accessed via the target actor's RDP form which contains
the `actorID` for each target-scoped actor.
The target-scoped actors expect to find the following properties on the target
actor:
- threadActor:
ThreadActor instance for the given target,
only defined once `attach` request is called, or on construction.
- isRootActor: (historical name)
Always false, except on ParentProcessTargetActor.
Despite the attribute name, it is being used to accept all resources
(like chrome one) instead of limiting only to content resources.
- makeDebugger:
Helper function used to create Debugger object for the target.
(See actors/utils/make-debugger.js for more info)
In addition to this, the actors inheriting from WindowGlobalTargetActor,
expose many other attributes and events:
- window:
Reference to the window global object currently targeted.
It can change over time if we switch target to an iframe, so it
shouldn't be stored in a variable, but always retrieved from the actor.
- windows:
List of all document globals including the main window object and all
iframes.
- docShell:
Primary docShell reference for the targeted document.
- docShells:
List of all docShells for the targeted document and all its iframes.
- chromeEventHandler:
The chrome event handler for the current target. Allows to listen to events
that can be missing/cancelled on this document itself.
See WindowGlobalTargetActor documentation for more details.
## Target-scoped actors
Each of these actors focuses on providing one particular feature set. They are
children of a given target actor.
The data they return is filtered to reflect the target. For example, the
InspectorActor that you fetch from a WindowGlobalTargetActor gives you information
about the markup and styles for only that frame.
These actors may extend this hierarchy by having their own children, like
LongStringActor, WalkerActor, etc.
To improve performance, target-scoped actors are created lazily. The target
actor lists the actor ID for each one, but the actor modules aren't actually
loaded and instantiated at that point. Once the first request for a given
target-scoped actor is received by the server, that specific actor is
instantiated just in time to service the request.
|
