Moving `wasm-bindgen` from "Future Compatible with" to "Polyfill for" WebIDL Bindings

[fitzgen]

Where we are Now

Here is a simplified view of our Rust and Wasm toolchain, its artifacts and the processes that input and output these artifacts:

+--------------+
| Rust Sources |
+--------------+
       |
       |
     rustc
       |
       |
       V
+----------------------------------------+
| Initial .wasm w/ wasm-bindgen metadata |
+----------------------------------------+
       |
       |
  wasm-bindgen CLI ----------.
       |                     |
       |                     |
       V                     V
+-------------+       +------------------+
| Final .wasm |       | JS Bindings Glue |
+-------------+       +------------------+

Right now the initial .wasm contains two things that are used by the wasm-bindgen CLI, and stripped from the final .wasm binary:

• A wasm-bindgen-specific custom section. This contains a summary of all the imported and exported functions, structs, fields, and methods. It doesn't include functions' and methods' ABI types, however.

• "Descriptor" functions. These are evaluated by the CLI and communicate the types being sent and received over the ABI boundary for a given function or method. We do this because we want the ABI representation of types to be trait-based, so we can customize it for different types, and it was the best way at the time to support that.

The generated JS bindings glue is responsible for the following things:

• Translating JS values going to Wasm into their ABI representation.

• Translating values coming out of Wasm to JS from their ABI representation into JS values.

• Instantiating the Wasm module and hooking up imported functions.

Vision

We leverage WebIDL bindings and anyref to completely remove the wasm-bindgen-specific metadata and 99% of the JS bindings glue:

+--------------+
| Rust Sources |
+--------------+
       |
       |
     rustc
       |
       |
       V
+---------------------------------------------------+
| Final .wasm w/ WebIDL Bindings Section and anyref |
+---------------------------------------------------+
       |
       |
  wasm-bindgen CLI
       |
       |
       V
+-----------------------+
| JS Instantiation Glue |
+-----------------------+

rustc has first-class support for anyref and emitting the WebIDL bindings custom section.

The JS bindings glue is no longer responsible for translating between ABI representations and JS values:

• The ABI representation of most JS values is simply anyref. In JS hosts, an anyref is a JS value, or at least the conversion is so transparent that they are effectively the same from our perspective.

• Strings typically use WebIDL bindings' UTF-8 string shepherding facilities (unless they are trying to handle unpaired surrogates, in which case they can work with JS string values as anyrefs).

The only thing that the generated JS is responsible for now is WebAssembly instantiation with all of the right WebIDL function imports, and polyfilling Wasm's ESM integration.

For Browsers that Don't Support WebIDL Bindings Yet

To support browsers that don't support WebIDL bindings yet in this future world, the wasm-bindgen CLI will also be able to act as a polyfill, removing the WebIDL bindings section from the .wasm binary, and instead emitting equivalent JS bindings glue (essentially what it emits today).

+--------------+
| Rust Sources |
+--------------+
       |
       |
     rustc
       |
       |
       V
+---------------------------------------------+
| .wasm w/ WebIDL Bindings Section and anyref |
+---------------------------------------------+
       |
       |
  wasm-bindgen CLI --------------------------------------.
       |                                                 |
       |                                                 |
       V                                                 V
+----------------------------------------+       +------------------+
| .wasm w/out WebIDL Bindings nor anyref |       | JS Bindings Glue |
+----------------------------------------+       +------------------+

An Intermediate Goal

Polyfill generating the WebIDL bindings section in the wasm-bindgen CLI:

+--------------+
| Rust Sources |
+--------------+
       |
       |
     rustc
       |
       |
       V
+------------------------------------------------------+
| Initial .wasm w/ wasm-bindgen metadata and no anyref |
+------------------------------------------------------+
       |
       |
  wasm-bindgen CLI
       |
       |
       V
+---------------------------------------------+
| .wasm w/ WebIDL Bindings Section and anyref |
+---------------------------------------------+

Then, to run on environments that don't support WebIDL bindings yet, we use the polyfill described in the previous section to emit a final .wasm and JS bindings glue that is equivalent to what we use today:

+--------------+
| Rust Sources |
+--------------+
       |
       |
     rustc
       |
       |
       V
+------------------------------------------------------+
| Initial .wasm w/ wasm-bindgen metadata and no anyref |
+------------------------------------------------------+
       |
       |
  wasm-bindgen CLI
       |
       |
       V
+---------------------------------------------+
| .wasm w/ WebIDL Bindings Section and anyref |
+---------------------------------------------+
       |
       |
  wasm-bindgen CLI --------------------------------------.
       |                                                 |
       |                                                 |
       V                                                 V
+----------------------------------------+       +------------------+
| .wasm w/out WebIDL Bindings, nor       |       | JS Bindings Glue |
| wasm-bindgen metadata, nor anyref      |       +------------------+
+----------------------------------------+

In practice, we won't need to literally invoke the wasm-bindgen CLI twice and serialize the .wasm to disk just to read it back again, but having the phases split and explicitly represented like this will be helpful for moving us forward, I suspect.

Things we can do now

• Fix the current experimental anyref implementation and upgrade it to non-experimental. It seems to have bugs where it isn't working in Firefox/SpiderMonkey anymore. Node.js >= 12.x also has support for anyref behind a flag, so we should start running our test suite with anyref on Node.js in CI, instead of just checking that it builds.

• Build a crate to consume and emit the text and binary representations of the WebIDL bindings custom section. We can use this in walrus and wasm-bindgen and wherever else we find a need.

• Stop emitting descriptor functions and interpreting them in the wasm-bindgen CLI. We do this by switching from descriptor functions to building up a static from associated consts. Essentially a static array of the exact same thing stuff that we pass to a series of calls to __wbindgen_describe now.

• After that, we should align the format of our custom section with the format of WebIDL bindings. We will emit a copy of this custom section for each #[wasm_bindgen] use, so it won't be 100% compatible with the WebIDL bindings section. Instead it will be like a pre-linked "object section", that we will link into a single section in the CLI.

Unresolved Questions

• What is the bare minimum we need to get rustc (and presumably LLVM and lld) to support anyref enough to use them and WebIDL bindings together without wasm-bindgen post-processing the .wasm binary?

  • I'm assuming we want to just immediately spill anyrefs to a shadow stack or heap immediately, work with them as indices, and avoid the question of actually representing anyrefs at the Rust language level directly. At least for the foreseeable future.

  • So rustc and LLVM need some knowledge about the anyref table that we use for the shadow stack and heap, and what function to call to allocate into them? Presumably that function is returning an index for the anyref to move into, so that these functions can be authored in Rust, and don't have to touch an anyref directly.

  • Alternatively, it might be simpler to only have an anyref table that is used as a shadow stack at the LLVM level, and then separately at the Rust level also expose intrinsics for copying anyrefs from that shadow stack to a separate anyref table that we use as a heap? This might be a smaller set of moving parts that we have to get everyone to agree upon...

• Presumably the user-facing building block for emitting WebIDL bindings is some sort of attribute on an extern declaration. Not clear to me exactly what this attribute looks like, but I think it should be pretty easy to design in comparison to the last point.

• I think all the borrowed-vs-owned anyref stuff can be handled in the Rust source that the proc-macro generates when we are managing the anyref table from Rust instead of in the JS glue. I don't think this stuff leaks into anything the WebIDL bindings needs to know about (other than WebIDL imports returning strings, which it has facilities for). But I'm not 100% sure on this point.

[fitzgen]

+cc @alexcrichton @lukewagner @tschneidereit

@sunfishcode, maybe you have some thoughts on the LLVM side of things in the "unresolved questions" bit?

[fitzgen]

Build a crate to consume and emit the text and binary representations of the WebIDL bindings custom section. We can use this in walrus and wasm-bindgen and wherever else we find a need.

Starting on this here: https://github.com/rustwasm/wasm-webidl-bindings

[jgravelle-google]

In the presence of anyref (and multivalue) it should be possible to read the custom section in JS at runtime. This has the benefit of reducing code size to a constant factor, and should be forward-compatible with the proposal itself, meaning when browsers ship the feature, any modules with the section will start to Just Work with the speed improvements that native support implies.

[fitzgen]

Status update:

• Have finished implementing parsing the straw proposal text and have AST types for representing the webidl-bindings section and all of its operators and all that.
• Have PR open for adding better APIs for working with custom sections in walrus: Custom sections API walrus#76
• Next step is to take the AST types and implement encoding them into a straw proposal binary format and hook this into those new walrus custom section APIs

There are also a few "help wanted" issues open in https://github.com/rustwasm/wasm-webidl-bindings if anyone is interested :)

[alexcrichton]

I haven't explicitly commented on this yet, but the plan sounds great! I'm definitely looking forward to architecting wasm-bindgen this way :)

Fix the current experimental anyref implementation and upgrade it to non-experimental. It seems to have bugs where it isn't working in Firefox/SpiderMonkey anymore.

One bug was fixed in rustwasm/walrus#74, there's another around initialization of the anyref table for browsers and when that runs, I'll try to update that soon.

Node.js >= 12.x also has support for anyref behind a flag, so we should start running our test suite with anyref on Node.js in CI, instead of just checking that it builds.

Trying this out, unfortunately table.grow isn't supported in the version of v8 used by Node.js right now. Looking at v8's master branch it looks like table.grow is indeed supported. I suspect we need to wait for a PR such as nodejs/node#27375 to land in Node and get published, aka Node.js needs to update the v8 dependency which I'm sure is not a trivial task!

[fitzgen]

Trying this out, unfortunately table.grow isn't supported in the version of v8 used by Node.js right now. Looking at v8's master branch it looks like table.grow is indeed supported. I suspect we need to wait for a PR such as nodejs/node#27375 to land in Node and get published, aka Node.js needs to update the v8 dependency which I'm sure is not a trivial task!

Interesting -- do you know if chrome canary supports it? Maybe we can have a smoke test for now in the form of a headless browser test running on chrome canary.

[alexcrichton]

Hm it may, although I can't quite figure it out. I'm not sure how to enable the support for anyref in v8 when using Chrome, and in doing it a way that I think should work doesn't work, so I can't get it to work in chrome canary yet.

(this works in headless firefox nightly though I think modulo our own bugs)

[alexcrichton]

I've started initial refactoring in #1566, although it's not using the wasm-webidl-bindings crate yet. I hope to transition to that in short order though after that PR is in better shape!

[alexcrichton]

Ok the next stage of refactoring (wow it's bigger than the first) is #1594. With that PR we're literally using WebIDL bindings as the internal abstraction in wasm-bindgen and it should be much easier to keep up with standards changes. It also informs us exactly where JS shims are generated and what is needed to avoid JS shims!

There's still more work needed to actually emit a WebIDL bindings section, but it should be much easier than this last refactoring.