From c17b5478b76fadc90432da2e81f24b660fce870d Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 13 Oct 2026 17:26:08 -0700 Subject: [PATCH 1/3] quest(m2): spike UniFFI-generated browser bindings before growing moq-wasm Co-Authored-By: Claude Opus 5.5 --- quest/m2/rs2ts/README.md | 1 + quest/m2/rs2ts/generator.md | 77 +++++++++++++++++++++++++++++++++ quest/m2/rs2ts/wasm-bindings.md | 6 ++- 3 files changed, 82 insertions(+), 2 deletions(-) create mode 100644 quest/m2/rs2ts/generator.md diff --git a/quest/m2/rs2ts/README.md b/quest/m2/rs2ts/README.md index e00ae63ab13..0e6aafa8f1f 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-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..4549c5aba1a --- /dev/null +++ b/quest/m2/rs2ts/generator.md @@ -0,0 +1,77 @@ +# [M] Choose the browser binding generator + +## Goal + +A reproducible report compares two Rust browser bindings on the baseline +harness. One is TypeScript generated by UniFFI from `rs/moq-ffi`. The +other is 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 either 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. Measure + `default-features` on and off. 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. 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. + +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. +- On wasm, `ffi::Task` cancels when the caller drops it, whereas native + detaches. Check that `@moq/net` semantics hold under that difference. +- 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 UniFFI 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 both candidates run 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..88e634abc41 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 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 From 925f3691a00368003ac1ef08725a98c592c962b9 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 13 Oct 2026 20:44:51 -0700 Subject: [PATCH 2/3] quest(m2): add BoltFFI as a third browser binding candidate Co-Authored-By: Claude Opus 5.5 --- quest/m2/rs2ts/README.md | 2 +- quest/m2/rs2ts/generator.md | 35 ++++++++++++++++++++++++--------- quest/m2/rs2ts/wasm-bindings.md | 2 +- 3 files changed, 28 insertions(+), 11 deletions(-) diff --git a/quest/m2/rs2ts/README.md b/quest/m2/rs2ts/README.md index 0e6aafa8f1f..207d2321437 100644 --- a/quest/m2/rs2ts/README.md +++ b/quest/m2/rs2ts/README.md @@ -59,7 +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-generated moq-ffi or hand-written moq-wasm from measurements +- [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 index 4549c5aba1a..3a6c69468eb 100644 --- a/quest/m2/rs2ts/generator.md +++ b/quest/m2/rs2ts/generator.md @@ -2,12 +2,12 @@ ## Goal -A reproducible report compares two Rust browser bindings on the baseline -harness. One is TypeScript generated by UniFFI from `rs/moq-ffi`. The -other is 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 either binding, delete `moq-wasm`, or evaluate JS-only -output. +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 @@ -31,6 +31,23 @@ Decided with the maintainer on 2026-10-13: land that pin. 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. 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), + which `connect` hits. 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 @@ -62,15 +79,15 @@ Measure on the [baseline harness](/quest/m2/rs2ts/spike.md): 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 UniFFI wins, that quest -completes `moq-ffi`'s browser parity and generates the TS in CI, and +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 both candidates run on +- [Browser backend baseline](/quest/m2/rs2ts/spike.md) - the harness and handwritten baseline every candidate runs on ## Related diff --git a/quest/m2/rs2ts/wasm-bindings.md b/quest/m2/rs2ts/wasm-bindings.md index 88e634abc41..f0b3c583bb5 100644 --- a/quest/m2/rs2ts/wasm-bindings.md +++ b/quest/m2/rs2ts/wasm-bindings.md @@ -17,7 +17,7 @@ versions and transports with the browser fixtures and `just test interop --all`. Wire new tests into CI, at least nightly. Complete the binding the [generator quest](/quest/m2/rs2ts/generator.md) -chose: `moq-ffi` through UniFFI, or the consume-only `moq-wasm`. Measure boundary calls, Promise allocation, +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. From fb197819afcb8155ce11b856dee1965f764e36c7 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 13 Oct 2026 20:49:57 -0700 Subject: [PATCH 3/3] quest(rs2ts): address review on wasm2 runtime, feature sizing, BoltFFI evidence, and cancel Co-Authored-By: Claude Opus 5.5 --- quest/m2/rs2ts/generator.md | 29 ++++++++++++++++++++--------- 1 file changed, 20 insertions(+), 9 deletions(-) diff --git a/quest/m2/rs2ts/generator.md b/quest/m2/rs2ts/generator.md index 3a6c69468eb..fc206fbc63a 100644 --- a/quest/m2/rs2ts/generator.md +++ b/quest/m2/rs2ts/generator.md @@ -20,15 +20,20 @@ Decided with the maintainer on 2026-10-13: - 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. Measure - `default-features` on and off. If size decides the result, propose a - net-only feature rather than a new crate. + 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. If UniFFI wins, add a waiting quest for ubrn 0.32 support + 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 @@ -38,14 +43,18 @@ Decided with the maintainer on 2026-10-13: 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. BoltFFI ships its own wasm loader 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), - which `connect` hits. TypeScript streams are experimental + ([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. @@ -66,8 +75,10 @@ Measure on the [baseline harness](/quest/m2/rs2ts/spike.md): 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. -- On wasm, `ffi::Task` cancels when the caller drops it, whereas native - detaches. Check that `@moq/net` semantics hold under that difference. +- `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.