Easily support non-standard WebIDL

[alexcrichton]

This is intended to be a tracking issue to pull together a number of requests from a few different locations.

The basic problem is that browsers will ship features before fully stabilized. Often these features are behind flags or some other gating mechanism, but once the gates are all unlocked some pages are able to use these features, and Rust/wasm often want to use the features as well!

Currently we are not adding these unstable WebIDL definitions to web-sys because they are almost guaranteed to change. This means that we'd have to ship breaking changes which we would prefer not to do. We do, however, want to make it easier to consume these WebIDL files!

Split across a number of PRs, there's two possible solutions I think we have right now for supporting this:

1. First we can use --cfg flags to support everything in web-sys itself. The general idea is that web-sys would grow all the unstable WebIDL files, but you'd have to compile with RUSTFLAGS=--cfg=web_sys_unstable to actually get anything to show up. This sort of "explicit opt in" would be required by everyone building a crate.

• The pro of this approach is that it centralizes all the WebIDL into this repository, taking the maintenance burden away from users
• The cons of this approach is that it's difficult to build for users and it puts more maintenance burden ehre.

2. An alternative to putting these WebIDL annotations in web-sys itself would be to encourage users to publish their own crates synthesized from WebIDL. The general idea here is that this repository would publish a stable crate (or tool) which can be used to synthesize a crate from WebIDL. That way users could publish their own webxr-sys (for example) and it would not be maintained in this repository. Once the specification stabilizes we'd move the WebIDL into web-sys itself.

• The pro of this approach is that it doesn't have much maintenance burden on us in this repository. It also allows anyone to build their own crate with raw WebIDL in the same manner web-sys is built. This approach is also pretty easy for users to consume, they'd basically just depend on a crate.
• The cons of this approach are pretty bad though. This involves a relatively significant amount of infrastructure which doesn't exists, so would be difficult to start out. For example these new crates probably want to depend on web-sys for basic types to start, which web-sys itself doesn't do at all (cross-crate dependencies). Additionally it puts the maintenance burden on users.

I'm still somewhat tempted to go with (1) myself, but we've had enough proposals running around here for awhile that I wanted to get this all written down myself!

[kettle11]

Thanks for thinking this through!

Some thoughts:

I like the first approach as it centralizes effort and maintenance, as you said. It avoids a situation where there are multiple crates for a WebIDL and it's unclear which ones are up to date and maintained.

However, the first approach also prevents people from unblocking themselves independent of this repository. It may lead to people temporarily forking this repository, as I've done now for WebXR. Which isn't terrible, it just feels like a messy short term solution.

As you mentioned the first approach adds maintenance burden here. If a WebIDL is changing frequently this repository may find itself with way more issues surrounding unstable API changes. With separate crates focused on a WebIDL some of that volume would be partitioned.

A perfect world solution would be to allow for an unstable flag in this repository and separate crates if users so desire, but that's extra work.

All that said, from my perspecitve, as a user of web-sys, both approaches work for me. But I'd like to hear what others have to say as well.

[Pauan]

Here's a third approach: have the unstable APIs be maintained in a separate crate, but provide a re-export for them in web-sys.

So the burden of updating the IDL falls onto outside contributors, but it's still conveniently accessible from web-sys, giving it a more "blessed" feel.

Of course the re-export would only exist when the flag is set.

[dakom]

This third approach sounds reasonable - but wouldn't it also require a bit of churn in web-sys to keep the versions updated?

Why not have that other crate be part of the wasm-bindgen ecosystem (as opposed to scattered third parties), but separate to web_sys itself? e.g. web_sys_experimental- and then the re-export could be in that other direction (web_sys_experimental would depend on and re-export web_sys)

[alexcrichton]

If we're going to maintain this in wasm-bindgen itself I would personally probably lean towards keeping it all in the same crate (web-sys) and implementing the --cfg solution required to enable the features.

[Pauan]

@dakom No, it doesn't, because semver will automatically upgrade to the latest version, so a version bump is only needed on major version changes.

And major version changes don't make much sense, because the API is unstable and experimental, so the crate should be permanently at version 0.1.x