Clarify "types of agent clusters"

[domenic]

Today @domfarolino reached out to ask some questions about the agent clusters portion of the spec, and I realized there is an important concept that's left implicit. I had to explain it with no direct spec support.

Basically, there are three types of agent clusters:

• Window-rooted ones
  • The first agent created is a similar-origin window agent
  • It can also gain dedicated worker and worklet agents
• Shared worker-rooted ones
  • The first agent created is a shared worker agent
  • It can also gain dedicated worker agents
• Service worker-rooted ones
  • These will only ever have a single agent, the service worker agent

This division is currently implicit. You can piece it together by looking at all the call sites of "obtain a similar-origin window agent" and "obtain a worker/worklet agent", to figure out how they're trying to group agents together. But it's not clear. For example @domfarolino was wondering whether it was possible to create an agent cluster without a similar-origin window agent in it, and then later add a similar-origin window agent to that cluster. (It is not.)

It would probably help readers to add an explanation like my bulleted list above to the spec. I'm unsure whether it should just be a non-normative summary, or whether we should try to make it a bit more formal and normative, like the different types of agents are. For example, if we had the latter approach, then obtain a similar-origin window agent step 7 could assert that group's agent cluster map[key] was a window-rooted agent cluster, and thus @domfarolino's question would be quickly answerable.

[domfarolino]

For example, if we had the latter approach, then obtain a similar-origin window agent step 7 could assert that group's agent cluster map[key] was a window-rooted agent, and thus @domfarolino's question would be quickly answerable.

I think you mean window-rooted agent cluster, right?

[domenic]

Yes, indeed, sorry! Will edit.

[domenic]

Another thing that making this more formal/normative could help with is clarifying what "owns" agent clusters. Right now we have an implicit structure which is something like:

• User agent owns a set of shared worker-rooted agent clusters
• User agent owns a set of service worker-rooted agent clusters
• User agent owns a browsing context group set. (Which contains browsing context groups, which contain agent cluster maps, which map keys to window-rooted agent clusters.) This part is explicit in the spec today.

Right now for workers, the agent clusters are just created (in "obtain a worker/worklet agent") and float in the ether, not attached to anything explicitly. They sometimes get called back into service via the not-very-formal sentence "Set agentCluster to the agent cluster which contains ownerAgent." We could add an explicit holder for them, like browsing context group set.

[annevk]

I like these ideas. One weird owner scenario is with opaque origin dedicated workers (data URL or sandboxing): #5254.

[domfarolino]

I think one thing that would be great to come out of this issue is indeed an explicit owner for agent clusters. Specifically one thing that I want an answer to is: should all agent clusters be owned by a "browsing context group"? Right now, top-level worker agents (and their brand new/fresh clusters) completely float in the ether, as previously mentioned, where non-top-level ones kinda get "added" to an existing agent cluster that I think always[^1] exists in a browsing context group's agent cluster map.

I was asked to review https://wicg.github.io/isolated-web-apps/isolated-contexts, which expects all environment settings objects to belong to a browsing context group, which brought me back to this issue.

Today, it seems that the top-level worker agents are not owned by a BCG. But if these top-level worker agents are scriptable from agents that do belong to exactly one BCG, then I think said BCG should explicitly own those top-level worker agents. Is that the case / do people agree?

[^1]: Is it possible for a top-level worker agent to create a non-top-level worker agent? And therefore the new non-top-level worker agent would be "added" to the free-floating top-level worker agent cluster that created it?

[domenic]

should all agent clusters be owned by a "browsing context group"?

I don't think so. In particular I don't see how service workers or shared workers could be associated to any specific BCG, as they interface with windows in multiple different BCGs.

But if these top-level worker agents are scriptable from agents that do belong to exactly one BCG, then I think said BCG should explicitly own those top-level worker agents.

It's possible that coincidentally, the agents that have access to a top-level worker are all in one BCG. But that can easily change. (E.g. if another agent does new SharedWorker(theURL), or if another agent starts sending resources through the service worker.) It doesn't make sense for me to have a setup where the first BCG "owns" the top-level agents.

---

In general, the setup in the spec right now is that the user agent owns agent clusters. And it also owns BCGs. And then there's an association between some BCGs and some agent clusters, via a BCG's agent cluster map. But the agent cluster map is specifically a weak map, because it doesn't express ownership and doesn't keep the agents alive. The agent management is done at the UA level.

[annevk]

I always assumed that the user agent holds shared/service worker agent clusters and BCGs. And BCGs hold window agent clusters alive. I don't think that the user agent has a need to separately hold window agent clusters. (As you wrote in https://github.com/whatwg/html/issues/6127#issuecomment-722638881 as well.)