Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions quest/m2/rs2ts/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
105 changes: 105 additions & 0 deletions quest/m2/rs2ts/generator.md
Original file line number Diff line number Diff line change
@@ -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
Comment on lines +28 to +31

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Add the required wasm2 runtime to the spike setup

The current rs/moq-ffi manifest and crate root contain neither uniffi-runtime-wasm nor extern crate uniffi_runtime_wasm as _, so this proposed wasm2 build cannot reach the browser harness: ubrn build wasm2 rejects the missing dependency, and without the forced link the player fails to load because __ubrn_alloc is absent. The spike must temporarily add and link the matching 0.31 runtime, and count it in the shipped-size measurement, rather than treating the existing crate as directly runnable. See the upstream wasm2 preparation requirements.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed: the spike branch adds the matching uniffi-runtime-wasm plus the forced extern crate link, and counts the runtime in the shipped size.

(Written by Claude Opus 5.5)

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
Comment on lines +42 to +45

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Compare a full BoltFFI binding before selecting it

These lines restrict BoltFFI to the slice crate and explicitly reserve full moq-ffi size and coverage measurements for UniFFI. As a result, BoltFFI cannot run the promised browser parity cases or produce comparable shipped-size, startup, and memory results, yet the quest still permits the maintainer to select it and the dependent quest assumes moq-ffi through BoltFFI. Either port a representative full workload for this spike or treat the slice measurement only as a feasibility filter, not winner-selection evidence.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed: the slice is now a feasibility filter. If BoltFFI passes and is favored, the harness workload is ported and the parity, size, startup, and memory cases rerun before it can be picked.

(Written by Claude Opus 5.5)

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
6 changes: 4 additions & 2 deletions quest/m2/rs2ts/wasm-bindings.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.
Expand All @@ -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
Loading