New Principle: Use [Exposed=*] to make only purely computational APIs available

[ptomato]

Problem statement

In webidl#526 a new Exposed annotation, [Exposed=*], was introduced. It denotes a fundamental set of interfaces that are intended to be exposed in Window, all Workers, all Worklets, ShadowRealm, as well as any future global scopes.

We've heard concerns (e.g., tc39/proposal-shadowrealm#401) that it's not clear when an interface should belong to this fundamental set and when it shouldn't. We'd like to issue guidance for this in a design principle.

I'm interested in feedback on the proposed guidance below, and am willing to write up the conclusions in a PR if it is generally positive.

Proposed guidance

[Exposed=*] should be applied only to purely computational interfaces. That is, they do not perform I/O and do not affect the state of the user agent or the user's device.

Anything annotated with [SecureContext] should not be exposed everywhere; not all global scopes are secure contexts.

Anything relying on an event loop should not be exposed everywhere; not all global scopes have an event loop.

The [Exposed=*] annotation should also be applied conservatively. If an interface is not that useful without other interfaces that are not exposed everywhere, default to not exposing that interface as well.

Further reading

Directly related, but predates [Exposed=*]: #35

Discussion resulting in the addition of [Exposed=*]: webidl#468

Other relevant reading: #325, #360, #448, tc39/ecma262#1120, WebAudio/web-audio-api#2499, tc39/proposal-shadowrealm#398

[zcorpan]

cc @smaug---- @mgaudet

[annevk]

This sounds reasonable. I'm not sure if it needs to be a principle or could just be advice in the Web IDL standard. It might also be helpful to have some examples so people can evaluate whether they understand the rules correctly.

[ptomato]

As it so happens, I do have some examples to propose.

The TextEncoder interface converts a string to UTF-8 encoded bytes. This is a purely computational interface, generally useful as a JS language facility, so it should be exposed everywhere.

localStorage is not purely computational because it affects the state of the user agent, so it should not be exposed everywhere.

The timeout method of the AbortSignal interface relies on an event loop and should not be exposed everywhere.

The Blob interface is purely computational, but Blob objects are primarily used for, or obtained as a result of, I/O. By the principle of exposing conservatively, Blob should not be exposed everywhere.

[mgaudet]

I support having guidance for this. I think this is a good piece of guidance.

I think Blob, as described, sits right on the line.

[ptomato]

Given the positive feedback so far, I've gone ahead and drafted a text for this in #510.

[annevk]

(Given the File API discussion in WebApps at TPAC Blob should be out for now as some people think it should maybe count towards a website's quota at some point. That would definitely not make it fit for all realms I think.)

[bakkot]

In the spirit of clarifying edge cases, what about

• OffScreenCanvas
• ImageBitmap
• WebGPU
• WebCodecs
  ?

I'm guessing no, but I'm not sure I could articulate exactly what makes OffScreenCanvas or WebCodecs not pure computation (at least the subset of the APIs which doesn't do any network/on-screen rendering stuff).