Devtools Targets:
DevTools Toolbox can debug many contexts, which can be:
- Documents
- Workers (regular web workers, shared workers and service workers) (As of today, shared workers and service workers are only supported in the browser toolbox)
- Processes (only for the browser toolbox)
- Extensions (only from the browser toolbox, or per-extension dedicated toolbox)
Each instance of these contexts are called "target" in DevToools. They are debugged through a dedicated actor class on the backend:
- Documents are reachable via BrowsingContextTargetActor
- Workers, via WorkerTargetActor
- Processes, via ContentProcessTargetActor
- Extensions, via WebExtensionTargetActor They are all implemented in this folder: https://searchfox.org/mozilla-central/source/devtools/server/actors/targets
On the frontend side, we have equivalent objects, whose name is having Front instead of Actor suffix: https://searchfox.org/mozilla-central/source/devtools/client/fronts/targets/
A given DevTools toolbox will manipulate many target instances. There is a special one, the first, top level target one, which relates to the main context you are debugging. For regular web toolbox, where you debug a tab, this will be a BrowsingContextTargetActor, which is attached to the top level document of your tab. Then, in addition to this target, the toolbox may interact with many others:
- WorkerTargetActor, if the page is having any workers
- other BrowsingContextTargetActor instances, if the page is having any remote iframe, running in a distinct process Similarly, the browser toolbox will interact with even more target instances. Process and extension targets.
As of today, there is two important edgecase to know about BrowsingContextTargetActor lifecycle:
- The lifecycle of this target can be drasticaly different:
- For the first top level target, it will follow the lifecycle of the document's docshell. This mean that the target will debug any reload or navigation happening in the same process. The target will debug any following document loaded in this docshell. It means that this one target will debug many top level documents.
- Still about the top level target... For now, if you navigate the top level document to another process, you will get a brand new BrowsingContextTargetActor, still following the lifecycle of a docshell. But once bug 1644397 lands, navigation to another process will start spawning a BrowsingContextTargetActor with a different lifecycle. These targets will now follow the WindowGlobal lifecycle. It means that the target actor will only debug one document load. Any reload, or navigation, even in the same process, will force the creation of a new dedicated target.
- Now, about target of remote frames, they all follow the WindowGlobal lifecycle. So that each target actor will only inspect one document load. And reload as well as navigation, even in the same process, will use a new dedicated target actor instance.
- "Out of process" and "In process" iframes are handled differently
- "Out of process" are the iframes that are running in a distinct process than their parent document. For these iframes, a new dedicated BrowsingContextTargetActor will be spawn.
- "In process" are the iframes running in the same process as their parent document. For these iframes, no dedicated target actor is spawn. Instead, the BrowsingContextTargetActor of their parent document is allowing to debug them. Server and client codebase get to know about these additional document via window-ready and window-destroyed events.
Hopefully, we can someday simplify all that, and unify all theses cases so that the BrowsingContextTargetActor becomes the WindowGlobalTargetActor and:
- all iframes, no matter if they are remote or not, have a dedicated WindowGlobalTargetActor actor.
- all document, first or subsequent, top level or iframes are all following the WindowGlobal lifecycle. So that all reload and navigation, no matter if we navigate to another process or not, induce the same behavior: we get a new target actor.