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.