diff --git a/quest/m2/rs2ts/README.md b/quest/m2/rs2ts/README.md index e00ae63ab13..207d2321437 100644 --- a/quest/m2/rs2ts/README.md +++ b/quest/m2/rs2ts/README.md @@ -59,6 +59,7 @@ any necessary breaks. Wire: no changes intended. ## Required - [Browser backend baseline](/quest/m2/rs2ts/spike.md) - reproducible browser fixtures and measurements before choosing or adopting a backend +- [Binding generator](/quest/m2/rs2ts/generator.md) - the maintainer picks UniFFI- or BoltFFI-generated moq-ffi, or hand-written moq-wasm, from measurements - [Complete WASM bindings](/quest/m2/rs2ts/wasm-bindings.md) - Rust publishing and consumption cover the browser protocol and model surface - [Adopt WASM in @moq/net](/quest/m2/rs2ts/wasm-adopt.md) - the TypeScript interface uses Rust, with measured tradeoffs accepted before replacement diff --git a/quest/m2/rs2ts/generator.md b/quest/m2/rs2ts/generator.md new file mode 100644 index 00000000000..fc206fbc63a --- /dev/null +++ b/quest/m2/rs2ts/generator.md @@ -0,0 +1,105 @@ +# [M] Choose the browser binding generator + +## Goal + +A reproducible report compares three Rust browser bindings on the baseline +harness: TypeScript that UniFFI generates from `rs/moq-ffi`, TypeScript +that BoltFFI generates from it, and the hand-written wasm-bindgen +`rs/moq-wasm`. The maintainer picks which one `@moq/net` wraps, and the +report records that decision. This quest does not adopt any binding, +delete `moq-wasm`, or evaluate JS-only output. + +## Plan + +Decided with the maintainer on 2026-10-13: + +- Spike before [Complete WASM bindings](/quest/m2/rs2ts/wasm-bindings.md) + grows `moq-wasm`. Every native language already binds through `moq-ffi`. + [#2907](https://github.com/moq-dev/moq/issues/2907) argued the browser + should too, rather than keep a second hand-written surface. +- Bind `moq-ffi` as it is, not a browser-only UniFFI crate: + [#5460](https://github.com/moq-dev/moq/pull/5460) rejected per-layer crate + splits. The generated TS tree-shakes, but the `.wasm` does not. The linker + keeps every UniFFI export, so only cargo features reduce size. Toggling + `default-features` changes nothing on wasm32 (`audio` and `video` are + already native-only), so report each module's share of the `.wasm` + instead. If size decides the result, propose a net-only feature rather + than a new crate. +- Use [uniffi-bindgen-react-native](https://github.com/jhugman/uniffi-bindgen-react-native) + (ubrn), whose `wasm2` flavour is a plain wasm32 cargo build driven by a + generic JS player. Upstream UniFFI will not ship a JS generator and points + to ubrn. ubrn pins UniFFI 0.31, while `moq-ffi` is on 0.32. The spike + branch therefore pins `moq-ffi` to 0.31 for measurement only and does not + land that pin. `wasm2` also needs the matching `uniffi-runtime-wasm` + dependency and an `extern crate uniffi_runtime_wasm as _` to force its + link (the player looks for `__ubrn_alloc`). Add both on the spike branch + and count the runtime in the shipped size. If UniFFI wins, add a waiting quest for ubrn 0.32 support + ([#468](https://github.com/jhugman/uniffi-bindgen-react-native/pull/468)), + required by adoption but not by this report. +- [BoltFFI](https://github.com/boltffi/boltffi) is the third candidate + (decided in [#5498](https://github.com/moq-dev/moq/pull/5498), whose + BoltFFI spike covers the native half). Neither quest blocks the other. + BoltFFI has its own macros, so it cannot bind `moq-ffi` as-is. Reuse + that spike's slice crate, which binds both generators via `cfg_attr`, + and measure UniFFI on the same slice so the per-call numbers compare + like for like. Full `moq-ffi` through UniFFI still provides the size and + coverage numbers. The slice is a feasibility filter for BoltFFI, not + selection evidence: if BoltFFI passes and is favored, port the harness + workload to it and rerun the parity, size, startup, and memory cases + before the maintainer picks it. BoltFFI ships its own wasm loader and + `.d.ts` files for web, node, and bundlers. Async uses poll plus a + continuation, like UniFFI. Crates using `web-sys` trapped at runtime + until [boltffi#943](https://github.com/boltffi/boltffi/pull/943) + (2026-09-28, released in v0.31.0). Async constructors and static async + methods are dropped + ([boltffi#95](https://github.com/boltffi/boltffi/issues/95), open). + `MoqClient::connect` takes `&self` and works, but async constructors + such as the media catalog consumer's `subscribe` hit it. TypeScript streams are experimental + ([boltffi#40](https://github.com/boltffi/boltffi/issues/40)). Roughly + one maintainer. + +What already exists: `moq-ffi` compiles for wasm32 +([#2911](https://github.com/moq-dev/moq/pull/2911)) with +`wasm-unstable-single-threaded`, including the media layer. Native codecs, +the server, and the TLS knobs are gated out. The #2907 spike generated TS +(with a different generator) that passes `tsc --strict`. It maps u64 to +bigint and lets a handle be freed while one of its calls is pending. +None of it has run in a browser. + +Measure on the [baseline harness](/quest/m2/rs2ts/spike.md): + +- Shipped size (compressed `.wasm` plus JS player and glue), cold start, + first frame, per-frame CPU, and memory. +- Per-async-call cost, since UniFFI resolves one JS Promise per + `rust_future_poll` wakeup. Compare it with wasm-bindgen's async glue. + Sweep publisher and subscriber counts. +- Parity on the harness cases: exact u64 above 2^53, cancellation through + `AbortSignal`, close/error propagation, and freeing a handle mid-call. +- `ffi::Task::run` awaits in place on every target: a cancelled foreign + call stops polling, and its future drops at `rust_future_free`. Test that + aborting or freeing a pending call releases its state without stealing + the next call's event. +- Things the binding cannot do. `JsValue` cannot cross the boundary, so + Rust constructs the WebTransport, as `moq-ffi` already does. Cover the + supported fallback transport as well. +- Deployment: ubrn's player compiles dispatchers with `new Function` and + falls back to an interpreter under a strict CSP. Measure both modes. Note + open ubrn wasm issues such as TS that fails to type-check + ([#472](https://github.com/jhugman/uniffi-bindgen-react-native/issues/472)). +- The JS-only path: whether the player can drive wasm2js output, as an + input to the [WASM-to-JS evaluation](/quest/m2/rs2ts-wasm2js.md). + +There are no invented thresholds; the maintainer weighs the report. Update +the wasm-bindings quest for the chosen binding. If a generated binding +wins, that quest completes `moq-ffi`'s browser parity and generates the TS in CI, and +`moq-wasm`'s deletion moves to [adoption](/quest/m2/rs2ts/wasm-adopt.md). + +Public API: none. Wire: none. + +## Required + +- [Browser backend baseline](/quest/m2/rs2ts/spike.md) - the harness and handwritten baseline every candidate runs on + +## Related + +- [Binding namespaces](/quest/m1/ffi-shape/README.md) - the `moq-ffi` shape a generated browser binding inherits diff --git a/quest/m2/rs2ts/wasm-bindings.md b/quest/m2/rs2ts/wasm-bindings.md index d765ae70151..f0b3c583bb5 100644 --- a/quest/m2/rs2ts/wasm-bindings.md +++ b/quest/m2/rs2ts/wasm-bindings.md @@ -4,7 +4,7 @@ The Rust browser bindings support publishing and consumption for lite and moq-transport, including the model behavior required by `@moq/net` consumers. -The existing consume-only experiment becomes a tested replacement candidate; +The chosen binding becomes a tested replacement candidate; this quest does not switch the public package's default implementation. ## Plan @@ -16,7 +16,8 @@ close/error behavior, cancellation, and backpressure. Validate supported versions and transports with the browser fixtures and `just test interop --all`. Wire new tests into CI, at least nightly. -Start with the existing bindings. Measure boundary calls, Promise allocation, +Complete the binding the [generator quest](/quest/m2/rs2ts/generator.md) +chose: `moq-ffi` through UniFFI or BoltFFI, or the consume-only `moq-wasm`. Measure boundary calls, Promise allocation, payload copies, and retained memory. Compare a batched poll/event-drain boundary if these dominate, including latency and backpressure effects; do not require a sans-IO rewrite or impose batching latency to win throughput. @@ -34,4 +35,5 @@ Public API: extends the unpublished browser bindings; any changes needed to ## Required +- [Binding generator](/quest/m2/rs2ts/generator.md) - which binding this completes - [Browser backend baseline](/quest/m2/rs2ts/spike.md) - the measurements and parity harness this extends