diff --git a/quest/m1/README.md b/quest/m1/README.md index 425179dc8e8..2670ceef171 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -124,6 +124,10 @@ above them. - [Generated C++ shape](/quest/m1/cpp-generated-shape.md) - `moq::Client` is the generated type itself and `moq::expected` is one type at every C++ standard - [OBS publishes under epochs](/quest/m1/obs-epoch.md) - each OBS Start Streaming is a fresh epoch, through the generated C++ - [Generated C bindings](/quest/m1/c/README.md) - C generated from moq-ffi ships as `moq-c` 0.8.0 and replaces the hand-written libmoq +- [BoltFFI or UniFFI](/quest/m1/boltffi.md) - BoltFFI vs UniFFI on a moq-ffi slice in Python, Kotlin, and Swift decides which one the moq-dev fork starts from +- [Hard-fork the binding generator](/quest/m1/uniffi-fork.md) - one moq-dev repo holds the chosen generator's core and every language backend, released under one tag and one pin +- [Payload bytes](/quest/m1/ffi-bytes.md) - payloads cross the FFI in one bulk copy, proven by a nightly benchmark in every wrapper +- [Poll-native async spike](/quest/m1/ffi-poll.md) - measure kio poll-native exports and foreign poll against `ffi::Task`, then pick the shape - [A failed rendition fails alone](/quest/m1/rendition-failure.md) - when one `@moq/publish` rendition's encoder fails, only that rendition ends, loudly, while the others and the broadcast keep running under the same epoch - [Rendition preference](/quest/m1/rendition-preference.md) - automatic selection by ``, `Video::ranked`, and WHEP keeps the highest `preference` that decodes, so a compatibility transcode is only picked when nothing preferred decodes - [Rust PROBE on demand](/quest/m1/probe-on-demand-rs.md) - a Rust client opens PROBE only while a `recv_bandwidth()` consumer is held, and `Stats` drops `estimated_recv_rate` diff --git a/quest/m1/boltffi.md b/quest/m1/boltffi.md new file mode 100644 index 00000000000..2ec1e546d9c --- /dev/null +++ b/quest/m1/boltffi.md @@ -0,0 +1,63 @@ +# [M] Spike: BoltFFI or UniFFI as the fork's base + +## Goal + +A reproducible report compares BoltFFI with UniFFI on the same slice of +moq-ffi, in Python, Kotlin, and Swift, for call overhead, payload throughput, +async cost, and output size. It also estimates what each base costs to +carry. The maintainer picks which one [the hard fork](/quest/m1/uniffi-fork.md) +starts from. This quest does not adopt or fork either one. + +## Plan + +Decided with the maintainer on 2026-10-13: + +- **Why now**: moq is hard-forking its binding generator. It is not clear + whether UniFFI or BoltFFI is the better starting point, so this spike runs + in parallel with other work and nothing waits on its harness. +- **Candidates**: [BoltFFI](https://github.com/boltffi/boltffi) against + UniFFI 0.32. BoltFFI has UniFFI's proc-macro style and the same + poll-plus-continuation async model. It ships Swift, Kotlin, Java, C#, + Python, and wasm/TS (its own loader; since v0.31 it also runs + wasm-bindgen for crates that use web-sys). Its README claims 1000x faster + no-op calls than UniFFI, but those are vendor-run benchmarks. Diplomat was + rejected: no async, no Swift or Go, no data enums, and its JS breaks on + crates using wasm-bindgen. +- **BoltFFI's known gaps**: no Go or C++, Dart is unfinished, C is + sync-only, and async constructors and static async methods are dropped + (boltffi/boltffi#95). `MoqClient::connect` takes `&self` and works, but + async constructors such as the media catalog consumer's `subscribe` hit + it. One maintainer wrote about 80% + of the code. Same-name types in one target probably collide (RFC #700). + Put each gap in the report with what closing it in a fork would cost. +- **UniFFI's known costs**: three generator forks broken by every minor + release, `Vec` copied one byte at a time, and bare-name type keys + (mozilla/uniffi-rs#3026). +- **Slice**: connect, publish and subscribe one track, `write_frame` and + `read_frame`, and one async read loop. Bind them with both generators side + by side via `cfg_attr` in a spike crate, not in moq-ffi. The spike crate + carries its own benchmarks, so it does not wait on the + [payload harness](/quest/m1/ffi-bytes.md). It also builds for wasm32: + the browser comparison in #5478 reuses this slice for per-call numbers, + so tell that quest if the crate's location or shape changes. +- **Measure**: no-op and record call overhead, payload throughput across + frame sizes from 100 B to 1 MB, and the cost of each async await. + Re-measure UniFFI rather than trusting BoltFFI's numbers for it. +- **Size table**: native library, generated bindings, and wasm plus JS glue + (gzip), for both generators. Measure the native library with moq-ffi's + default features on and off; the toggle changes nothing on wasm32, where + `audio` and `video` are already compiled out. Put moq-wasm in the table for reference. +- **Carry cost**: for each base, estimate the work to reach moq's eight + targets (Python, Go, Swift, Kotlin, Dart, C++, C, browser TS), porting + the existing Go, Dart, and C++/C generators where needed. Also estimate + how each base's internals suit the planned fork work: bulk byte copies, + zero-copy returns, namespaced types, and poll-native async. +- **Browser half**: BoltFFI also joins the browser generator choice in + [#5478](https://github.com/moq-dev/moq/pull/5478) as a third candidate on + the baseline harness. Neither blocks the other. + +Public API: none. Wire: none. + +## Related + +- [Rust-backed @moq/net](/quest/m2/rs2ts/README.md) - the browser binding choice BoltFFI also competes in diff --git a/quest/m1/ffi-bytes.md b/quest/m1/ffi-bytes.md new file mode 100644 index 00000000000..cc73fa66f22 --- /dev/null +++ b/quest/m1/ffi-bytes.md @@ -0,0 +1,52 @@ +# [L] Binding payloads cross the FFI without per-byte copies + +## Goal + +A binding moves a frame payload across the FFI with no per-byte loop: every +copy on the path is a bulk copy, and the report counts them per direction. +Proven by a payload benchmark in every wrapper (Python, Go, +Kotlin, Swift, Dart, and C++) that runs nightly. The benchmark is the shared +harness later binding performance quests reuse. + +## Plan + +Decided with the maintainer on 2026-10-13: + +- **Benchmark first.** Each wrapper gets a benchmark of payload throughput + and per-call cost: `write_frame` and `read_frame` on an in-process + publisher and subscriber (no network), frame sizes swept from 100 B to + 1 MB, plus a no-op call and a record round trip. Add a Rust microbenchmark + of UniFFI's lift and lower for `Vec`. Wire them all into nightly CI. + Every wrapper, because each lowers bytes differently and a generator + regression only shows in its own language. The + [poll spike](/quest/m1/ffi-poll.md) and the + [size profile](/quest/m2/ffi-size-profile.md) reuse this harness. +- **Bulk copy in the fork's core.** UniFFI lifts and lowers `Vec` + through the generic `Vec` path, one byte at a time with a bounds check + each (`uniffi_core` `ffi_converter_impls.rs`), in both directions. That + path covers arguments, record fields (`MoqFrame.payload`, video and audio + frames), and returns (`read_frame`, `recv_datagram`). Make it one + `memcpy` in [moq-dev/uniffi](/quest/m1/uniffi-fork.md). The serialized + format is unchanged, so no generator or binding API changes. Two copies + remain for records and returns (the wrapper's container to `RustBuffer`, + then `RustBuffer` to `Vec`); removing the second needs the ownership + change in [zero-copy returns](/quest/m2/ffi-bytes-return.md). + #2946 already removed the per-byte copy on the Python side. +- **`&[u8]` arguments only if the numbers say so.** UniFFI 0.32 makes + `&[u8]` arguments zero-copy, but only for sync calls that take bytes + directly: flate `update`/`append` and the three `write(payload)` methods. + It cannot be used in records, async calls, or callback interfaces. Adopting + it means fixing the Go and C++/C generators (both lower to `RustBuffer` + where the declaration expects `ForeignBytes`, so they would not compile) + and Dart (copies and never frees). Kotlin's parameter type would become + `ByteBuffer`. Do it only if the benchmark shows the remaining copy + matters after the bulk copy; otherwise record the numbers and skip it. +- Zero-copy returns are [their own quest](/quest/m2/ffi-bytes-return.md), + gated on these numbers. + +Public API: none unless `&[u8]` lands, which changes Kotlin's parameter +type. Wire: none. + +## Required + +- [Hard fork](/quest/m1/uniffi-fork.md) - the repository the core patch lands in diff --git a/quest/m1/ffi-poll.md b/quest/m1/ffi-poll.md new file mode 100644 index 00000000000..5974039f5de --- /dev/null +++ b/quest/m1/ffi-poll.md @@ -0,0 +1,52 @@ +# [M] Spike: poll-native async in moq-ffi + +## Goal + +A report measures two kio-based async shapes against today's `ffi::Task` +on one hot path, and the maintainer picks which one moq-ffi migrates to. +This quest does not migrate moq-ffi; the migration is a follow-up quest. + +## Plan + +Decided with the maintainer on 2026-10-13: + +- **Why**: moq-net is poll-based through kio, but moq-ffi does not use kio. + `rs/moq-ffi/src/ffi.rs` wraps every handle in a tokio `Mutex`, a `watch` + cancel flag, and `select!`. It spawns detached work with an + `AbortOnDrop`, and needs a poll counter so shutdown can wait out + in-flight calls. There are about 43 `run`/`detached` call sites, and its + cancel bugs (#2932, the swallowed-event fix) came from that machinery. +- **Shape A, poll-native exports**: an async export is a `kio::wait` over the + underlying `poll_*`, and UniFFI's `RustFuture` polls it directly. No + per-handle mutex and no spawned task. UniFFI's cancel only stops polling + and keeps the future until `rust_future_free` + (mozilla/uniffi-rs#2771), and `ffi::Task::run` depends on that today. So + Shape A includes the core change that drops the future on cancel, + prototyped on a UniFFI branch if [the fork](/quest/m1/uniffi-fork.md) + does not exist yet, and measures with and without it. Measure what + remains of `Task` (cancel, shutdown). +- **Shape B, foreign poll**: export a sync `poll_x(waker)` whose waker is a + foreign callback interface, and let each wrapper build its own future + around it (asyncio, a Go channel, a coroutine). This works with UniFFI as + it is. A generator-level poll protocol in the fork is a candidate too if + the numbers justify it. +- **Hot path**: track `next` and group `read_frame`, prototyped in both + shapes beside the existing `Task` version. +- **Measure** in Python and Go, on the [payload harness](/quest/m1/ffi-bytes.md): + per-call latency, wakeups per frame, throughput, and CPU. Sweep subscriber + count so a cost that grows with the fan-out shows up. Test + cancellation semantics too: a cancelled read must not swallow the next + event, and shutdown mid-call must not crash at exit. +- No invented thresholds; the maintainer weighs the report. The migration + quest records the chosen shape. + +Public API: none. Wire: none. + +## Required + +- [Payload bytes](/quest/m1/ffi-bytes.md) - the per-wrapper benchmark harness + +## Related + +- [Runtime trait](/quest/m2/runtime-trait.md) - replaces web-async; moq-ffi's tokio runtime may move behind it +- [Kotlin JVM exit](/quest/m2/kt-jvm-exit.md) - a shutdown race the async shape affects diff --git a/quest/m1/ffi-shape/README.md b/quest/m1/ffi-shape/README.md index 8972efbda6a..b361218d617 100644 --- a/quest/m1/ffi-shape/README.md +++ b/quest/m1/ffi-shape/README.md @@ -63,9 +63,10 @@ Settled shape: silently; every other generator refuses. Distinct Rust names renamed back per language work only in Python and Go: Kotlin, Swift, Dart, and C++ shadow or misplace the external type, and generated C refuses - external types. Revisit only once + external types. Revisit once + [namespaced external types](/quest/m2/uniffi-namespaces.md) fixes [mozilla/uniffi-rs#3026](https://github.com/mozilla/uniffi-rs/issues/3026) - namespaces external types. + in the moq-dev/uniffi fork. - `demand()` is the one way to watch subscribers; producers drop their `name`/`is_used`/`used`/`unused` duplicates. - moq-ffi and its generated consumers, including `cpp/obs` (above). The diff --git a/quest/m1/uniffi-fork.md b/quest/m1/uniffi-fork.md new file mode 100644 index 00000000000..95369cccb57 --- /dev/null +++ b/quest/m1/uniffi-fork.md @@ -0,0 +1,75 @@ +# [L] Hard-fork the binding generator + +## Goal + +One moq-dev repository holds UniFFI's core and every generator moq uses +(Kotlin, Swift, Python, Go, Dart, C++, and C), builds them from one lockfile, +and releases them under one tag. moq-ffi depends on the fork's crates from +crates.io under moq names, and moq names that release in one pin file. The +three `kixelated/uniffi-*` generator forks are archived. Generated bindings +are unchanged by the move itself. + +## Plan + +Decided with the maintainer on 2026-10-13, after a review of how moq uses +UniFFI: + +- **Base**: [the BoltFFI spike](/quest/m1/boltffi.md) decides whether the + fork starts from UniFFI or BoltFFI. The plan below assumes UniFFI. If + BoltFFI is chosen, re-plan this quest against it (the repo name, the + crate names, porting the Go, Dart, and C++/C generators to BoltFFI) along + with the quests that name UniFFI internals: + [Payload bytes](/quest/m1/ffi-bytes.md), + [Poll-native async](/quest/m1/ffi-poll.md), + [Zero-copy byte returns](/quest/m2/ffi-bytes-return.md), and + [Namespaced external types](/quest/m2/uniffi-namespaces.md). + +- **Why**: every UniFFI minor release breaks external generators (0.31 + changed `module_path`, 0.32 changed the metadata encoding without bumping + the contract version, and `main` removes the old library-mode API). No + external generator has released for 0.32, so moq already carries three + forks, each pinned in about five places. The core also blocks work moq + needs: byte copies, zero-copy returns, and namespaced external types + (mozilla/uniffi-rs#3026). +- **Hard fork, fresh repo**: `moq-dev/uniffi` is a new repository, not a + GitHub fork and not submodules. Import uniffi-rs at the 0.32.2 release and + the three generators at their pinned tags + (`kixelated/uniffi-bindgen-go`, `kixelated/uniffi-dart`, + `kixelated/uniffi-bindgen-cpp` with its C backend) into one Cargo + workspace with a committed lockfile. Record each import's upstream source + and revision, and keep each component's license (uniffi-rs is MPL-2.0). +- **Free to diverge**: the fork may change metadata, checksums, and the FFI + contract when a moq quest needs it. Upstream changes are cherry-picked when + useful, not tracked. Offering a patch upstream is optional and needs + maintainer approval each time. +- **Publishing**: the fork publishes renamed crates to crates.io (for example + `moq-uniffi`, `moq-uniffi-core`, `moq-uniffi-macros`, + `moq-uniffi-bindgen`), and moq-ffi depends on them directly with no + `[patch]`. crates.io moq-ffi must build without git dependencies, and a + diverged contract must never mix silently with upstream UniFFI. Give the + contract its own namespace, so a mismatch fails loudly at load time. +- **Generated code stays identical at the move**: Kotlin package names, + library symbol prefixes, and every wrapper's API do not change in this + quest. Diff the regenerated bindings for every language against `main`'s, + and run each wrapper's check plus `just test interop --all`. +- **One pin**: replace the per-generator pins with one file that + `flake.nix`, the release workflows, `rs/moq-ffi/build.sh`, and `sh/` + read. Delete the "five places" comments in `flake.nix` and the + `nix/uniffi-dart-*` lockfile and patch. `rs/uniffi-bindgen` builds the + Kotlin/Swift/Python CLI from the fork. +- **The fork's CI** builds every generator and runs its fixture suite, + including the unlocked `cargo install` resolve that bit the 0.32 port. +- Update the quests that name a `kixelated/uniffi-*` fork + ([Generated C++ shape](/quest/m1/cpp-generated-shape.md), + [Generated C bindings](/quest/m1/c/README.md)) to point at moq-dev/uniffi. + +Public API: none at the move; moq-ffi's dependency names change. Wire: none. + +## Required + +- [BoltFFI or UniFFI](/quest/m1/boltffi.md) - picks the base this fork starts from + +## Related + +- [Payload bytes](/quest/m1/ffi-bytes.md) - the first patch the fork carries +- [Namespaced external types](/quest/m2/uniffi-namespaces.md) - fixes mozilla/uniffi-rs#3026 in the fork diff --git a/quest/m2/README.md b/quest/m2/README.md index 6cbe21faea2..7d020da29c7 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -64,6 +64,8 @@ ranked just below deterministic TS legs, which it requires. - [fMP4 WebVTT ctim and vtta](/quest/m2/wvtt-ctim-vtta.md) - `wvtt` samples with `ctim` cue times or `vtta` comments import instead of failing - [TS passthrough export](/quest/m2/ts-passthrough-export.md) - `export ts --passthrough` writes the `m2ts` track back byte-identical (less late drops) on a fixed delay - [Bindings size profile](/quest/m2/ffi-size-profile.md) - a benchmark decides whether the moq-ffi builds ship at opt-level "s", which halves the dylib +- [Zero-copy byte returns](/quest/m2/ffi-bytes-return.md) - returned payloads reach the host without a copy, if the payload numbers justify it +- [Namespaced external types](/quest/m2/uniffi-namespaces.md) - the UniFFI fork lets two crates export the same type name, reopening the per-layer crate split - [Go mirror delivery](/quest/m2/go-mirror-delivery.md) - the Go binding's staticlibs stop growing git history by ~210 MiB per release - [Dart on iOS](/quest/m2/dart-ios.md) - prove the shipped iOS native asset actually loads on a device, which no CI can - [Dart codec parity](/quest/m2/dart-codecs.md) - Dart is the one binding that cannot originate media diff --git a/quest/m2/ffi-bytes-return.md b/quest/m2/ffi-bytes-return.md new file mode 100644 index 00000000000..87a68780a4e --- /dev/null +++ b/quest/m2/ffi-bytes-return.md @@ -0,0 +1,28 @@ +# [M] Zero-copy byte returns + +## Goal + +A frame payload returned to a binding (`read_frame`, `recv_datagram`, decoded +media) reaches the host without a copy, through a Rust-owned buffer the host +releases, in every generator of [moq-dev/uniffi](/quest/m1/uniffi-fork.md). +Proven on the [payload benchmark](/quest/m1/ffi-bytes.md). + +## Plan + +Decided with the maintainer on 2026-10-13: build it in the fork rather than +wait for upstream (mozilla/uniffi-rs#2847). Gated on the payload numbers: +start only if, after the bulk copy, the remaining return copy is a +measurable share of the read path. Otherwise delete this quest and record +why. + +- The buffer's lifetime must be explicit in each language: a host that + keeps a payload view after release reads freed memory. Prefer a + host-owned type that frees on its finalizer or close, matching each + wrapper's handle idiom. +- Every generator gets the change, including Go, Dart, C++, and C. + +Public API: returned payload types may change per language. Wire: none. + +## Required + +- [Payload bytes](/quest/m1/ffi-bytes.md) - the numbers that justify it, and the harness diff --git a/quest/m2/ffi-size-profile.md b/quest/m2/ffi-size-profile.md index c1d981a50ee..b933b222d09 100644 --- a/quest/m2/ffi-size-profile.md +++ b/quest/m2/ffi-size-profile.md @@ -19,8 +19,13 @@ Guidance: opt-level 3 with per-package overrides, and compare against building everything at "s". - Measure what the bindings actually do: publish and subscribe throughput - through moq-ffi, plus audio and video encode and decode. Wire the benchmark - into CI, at least nightly. + through moq-ffi on the [payload harness](/quest/m1/ffi-bytes.md), plus + audio and video encode and decode. Wire the benchmark into CI, at least + nightly. - If it's adopted, use a named profile (for example `[profile.ffi]`, inheriting release) that every binding build path selects, so the relay and self-builders keep opt-level 3. + +## Required + +- [Payload bytes](/quest/m1/ffi-bytes.md) - the per-wrapper benchmark harness this measures with diff --git a/quest/m2/uniffi-namespaces.md b/quest/m2/uniffi-namespaces.md new file mode 100644 index 00000000000..e9eae1182c6 --- /dev/null +++ b/quest/m2/uniffi-namespaces.md @@ -0,0 +1,33 @@ +# [L] Namespaced external types in the UniFFI fork + +## Goal + +Two crates linked into one library can each export a type with the same +name, and a type in one can take the other's: `media.GroupConsumer(group: +GroupConsumer)` generates and runs in Kotlin, Swift, Python, Go, Dart, C++, +and C from [moq-dev/uniffi](/quest/m1/uniffi-fork.md). + +## Plan + +Decided with the maintainer on 2026-10-13: fix +[mozilla/uniffi-rs#3026](https://github.com/mozilla/uniffi-rs/issues/3026) +in the fork instead of waiting for upstream. + +- `TypeUniverse` keys types by `(module_path, name)` instead of bare name, + and each generator qualifies cross-crate references through the other + crate's module. The #5460 and #5473 probes found Python and Go already + reference external types that way. Kotlin and Dart shadow them, Swift + needs per-crate modules plus an import, C++ sorts by bare name, and + generated C refuses external types. +- Reuse the two-crate spike harness from #5460 as the regression: both + layers export `GroupConsumer` and `Frame`, and every generator compiles + and runs the consumer. +- Re-running the per-layer crate split decision is a follow-up once this + lands. [FFI shape](/quest/m1/ffi-shape/README.md) points here as its + revisit condition. + +Public API: none in moq until the crate split is re-decided. Wire: none. + +## Required + +- [Hard fork](/quest/m1/uniffi-fork.md) - the repository the fix lands in