Use @webref/idl to maintain IDL files

[dontcallmedom]

Motivation

Automate the maintenance of IDL files used to generate WASM bindings by using the fragments maintained at the source in the webref project.

Proposed Solution

@tidoust and I maintain a list of automatically extracted IDL fragments from browser specifications as part of the webref project: https://github.com/w3c/webref/tree/curated/ed/idl (also available as an NPM package)

This list is already used e.g. in the Web Platform Tests project to maintain the authoritative list of IDL fragments to test browser against, and in TypeScript to maintain the relevant TypeScript class declarations.

Automating its use to populate https://github.com/rustwasm/wasm-bindgen/tree/main/crates/web-sys/webidls would simplify the maintenance of these files in the project (which seems entirely manual at this stage?)

[Liamolucko]

They won't work as they are, because web-sys relies on some non-standard attributes and things which aren't there in the original WebIDL files. For instance, [Throws] is used to mark whether a function is throwing and has to return Result<T, JsValue>.

If that issue could be solved, though, this seems like a good idea to me.

[tidoust]

Ah, right, I see a number of such attributes in the IDL definitions, including [Throws], [SetterThrows], [NeedsSubjectPrincipal], [BinaryName], [Pure], [Cached], [ChromeOnly], [Pref]. Many of them I don't understand. Some of them could perhaps be interesting to track in the specs themselves (I see that the possibility to add [Throws] in Web IDL was raised in https://github.com/whatwg/webidl/issues/603) or in Webref but we're somewhat reluctant to introduce more places in Webref that require manual maintenance...

[Liamolucko]

I took a look at the webidl-parsing code and a lot of those attributes aren't actually used. They're there because the webidls were initially imported from Firefox, and so we've inherited all their internal attributes.

These are all of the attributes that are actually used:

• [ChromeOnly]: The API is only exposed to Firefox-internal code, and so APIs with this attribute are ignored. Those APIs shouldn't be in webref's copy of the webidls anyway, so we don't have to worry about it.
• [NoInterfaceObject]: Old name for [LegacyNoIntefaceObject].
• [RustDeprecated]: Internal attribute to mark APIs with a Rust #[deprecated]. This is only used in BaseAudioContext.webidl and AudioScheduledSourceNode.webidl, which are deprecated saying that they don't exist in Safari; it looks like they've since been added, though, so I think it should be fine to un-deprecate those and remove this attribute.
• [Constructor]: Replaced by first-class constructor operations.
• [NamedConstructor]: Seems to have been replaced by [LegacyFactoryFunction].
• [Unforgeable]: Old name for [LegacyUnforgeable].
• [Throws]: Marks whether a function should return a Result in Rust.

So, it looks like [Throws] is the only one that can't be removed/replaced with a newer webidl feature.

It seems somewhat feasible to auto-generate [Throws] from the spec text. I think that a function should probably return a Result if the spec explicitly includes ways that it can throw, so we can add a [Throws] attribute if that's the case. The simplest way to do that would be to just straight-up check for the word 'throw' in the function's steps (or the steps of any other operations they reference), although that could be a bit flaky.