From bed659e6d8281975088d7f88ca9ff960f1288672 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 13 Oct 2026 20:41:54 -0700 Subject: [PATCH 1/5] quest: hard-fork UniFFI, payload bytes, poll-native async, and BoltFFI spikes Co-Authored-By: Claude Opus 5.5 --- quest/m1/README.md | 3 ++ quest/m1/ffi-bytes.md | 49 ++++++++++++++++++++++++++++ quest/m1/ffi-poll.md | 48 +++++++++++++++++++++++++++ quest/m1/ffi-shape/README.md | 5 +-- quest/m1/uniffi-fork.md | 61 +++++++++++++++++++++++++++++++++++ quest/m2/README.md | 3 ++ quest/m2/boltffi.md | 49 ++++++++++++++++++++++++++++ quest/m2/ffi-bytes-return.md | 28 ++++++++++++++++ quest/m2/ffi-size-profile.md | 9 ++++-- quest/m2/uniffi-namespaces.md | 33 +++++++++++++++++++ 10 files changed, 284 insertions(+), 4 deletions(-) create mode 100644 quest/m1/ffi-bytes.md create mode 100644 quest/m1/ffi-poll.md create mode 100644 quest/m1/uniffi-fork.md create mode 100644 quest/m2/boltffi.md create mode 100644 quest/m2/ffi-bytes-return.md create mode 100644 quest/m2/uniffi-namespaces.md diff --git a/quest/m1/README.md b/quest/m1/README.md index 425179dc8e8..0c564bdcefa 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -124,6 +124,9 @@ 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 +- [Hard-fork UniFFI](/quest/m1/uniffi-fork.md) - one moq-dev/uniffi repo holds UniFFI's core and every generator, 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/ffi-bytes.md b/quest/m1/ffi-bytes.md new file mode 100644 index 00000000000..31553e60f14 --- /dev/null +++ b/quest/m1/ffi-bytes.md @@ -0,0 +1,49 @@ +# [L] Binding payloads cross the FFI in one copy + +## Goal + +A binding moves a frame payload across the FFI with at most one bulk copy in +each 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), the + [BoltFFI spike](/quest/m2/boltffi.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. + #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 UniFFI](/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..2e8347564e3 --- /dev/null +++ b/quest/m1/ffi-poll.md @@ -0,0 +1,48 @@ +# [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. Cancelling the foreign future drops + the waiter. 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. Since moq owns [the fork](/quest/m1/uniffi-fork.md), a + generator-level poll protocol, or a `RustFuture` that drops the future on + cancel instead of at free, 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..b926056ea5d --- /dev/null +++ b/quest/m1/uniffi-fork.md @@ -0,0 +1,61 @@ +# [L] Hard-fork UniFFI as moq-dev/uniffi + +## 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: + +- **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. + +## 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..db4f9737b07 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -64,6 +64,9 @@ 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 +- [BoltFFI spike](/quest/m2/boltffi.md) - BoltFFI vs UniFFI on a moq-ffi slice in Python, Kotlin, and Swift: call cost, payloads, async, and output size +- [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/boltffi.md b/quest/m2/boltffi.md new file mode 100644 index 00000000000..bf5f3e79c4c --- /dev/null +++ b/quest/m2/boltffi.md @@ -0,0 +1,49 @@ +# [M] Spike: BoltFFI beside UniFFI + +## 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. The maintainer then decides whether to keep +UniFFI, replace it, or run both. This quest does not adopt BoltFFI. + +## Plan + +Decided with the maintainer on 2026-10-13: + +- **Candidates**: [BoltFFI](https://github.com/boltffi/boltffi) only. It 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. +- **Known gaps to report, not fix**: no Go or C++, Dart is unfinished, C is + sync-only, and async constructors and static async methods are dropped + (boltffi/boltffi#95, which `connect` hits). One maintainer wrote about 80% + of the code. Same-name types in one target probably collide (RFC #700). +- **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. +- **Measure** on the [payload harness](/quest/m1/ffi-bytes.md): no-op and + record call overhead, payload throughput across frame sizes, 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), each with moq-ffi's default features on and off, for both + generators. Put moq-wasm in the table for reference. +- **Browser half**: BoltFFI joins the browser generator choice in + [#5478](https://github.com/moq-dev/moq/pull/5478) as a third candidate on + the baseline harness. This quest owns the native half and the combined + size table. Neither blocks the other. + +Public API: none. Wire: none. + +## Required + +- [Payload bytes](/quest/m1/ffi-bytes.md) - the per-wrapper benchmark harness + +## Related + +- [Rust-backed @moq/net](/quest/m2/rs2ts/README.md) - the browser binding choice BoltFFI also competes in +- [Hard-fork UniFFI](/quest/m1/uniffi-fork.md) - the alternative to switching generators 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..412f017df3d --- /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 UniFFI](/quest/m1/uniffi-fork.md) - the repository the fix lands in From 8bdd29d891d8c03536834bd28ac40e8502fb5a17 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 13 Oct 2026 20:43:21 -0700 Subject: [PATCH 2/5] quest: the BoltFFI spike runs in parallel and picks the fork's base Co-Authored-By: Claude Opus 5.5 --- quest/m1/README.md | 3 +- quest/m1/boltffi.md | 58 +++++++++++++++++++++++++++++++++++ quest/m1/ffi-bytes.md | 5 ++- quest/m1/uniffi-fork.md | 16 +++++++++- quest/m2/README.md | 1 - quest/m2/boltffi.md | 49 ----------------------------- quest/m2/uniffi-namespaces.md | 2 +- 7 files changed, 78 insertions(+), 56 deletions(-) create mode 100644 quest/m1/boltffi.md delete mode 100644 quest/m2/boltffi.md diff --git a/quest/m1/README.md b/quest/m1/README.md index 0c564bdcefa..2670ceef171 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -124,7 +124,8 @@ 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 -- [Hard-fork UniFFI](/quest/m1/uniffi-fork.md) - one moq-dev/uniffi repo holds UniFFI's core and every generator, released under one tag and one pin +- [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 diff --git a/quest/m1/boltffi.md b/quest/m1/boltffi.md new file mode 100644 index 00000000000..8e173feac34 --- /dev/null +++ b/quest/m1/boltffi.md @@ -0,0 +1,58 @@ +# [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, which `connect` hits). 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). +- **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), each with moq-ffi's default features on and off, for both + generators. 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 index 31553e60f14..78a69162450 100644 --- a/quest/m1/ffi-bytes.md +++ b/quest/m1/ffi-bytes.md @@ -18,8 +18,7 @@ Decided with the maintainer on 2026-10-13: 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), the - [BoltFFI spike](/quest/m2/boltffi.md), and 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 @@ -46,4 +45,4 @@ type. Wire: none. ## Required -- [Hard-fork UniFFI](/quest/m1/uniffi-fork.md) - the repository the core patch lands in +- [Hard fork](/quest/m1/uniffi-fork.md) - the repository the core patch lands in diff --git a/quest/m1/uniffi-fork.md b/quest/m1/uniffi-fork.md index b926056ea5d..95369cccb57 100644 --- a/quest/m1/uniffi-fork.md +++ b/quest/m1/uniffi-fork.md @@ -1,4 +1,4 @@ -# [L] Hard-fork UniFFI as moq-dev/uniffi +# [L] Hard-fork the binding generator ## Goal @@ -14,6 +14,16 @@ are unchanged by the move itself. 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 @@ -55,6 +65,10 @@ 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 diff --git a/quest/m2/README.md b/quest/m2/README.md index db4f9737b07..7d020da29c7 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -64,7 +64,6 @@ 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 -- [BoltFFI spike](/quest/m2/boltffi.md) - BoltFFI vs UniFFI on a moq-ffi slice in Python, Kotlin, and Swift: call cost, payloads, async, and output size - [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 diff --git a/quest/m2/boltffi.md b/quest/m2/boltffi.md deleted file mode 100644 index bf5f3e79c4c..00000000000 --- a/quest/m2/boltffi.md +++ /dev/null @@ -1,49 +0,0 @@ -# [M] Spike: BoltFFI beside UniFFI - -## 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. The maintainer then decides whether to keep -UniFFI, replace it, or run both. This quest does not adopt BoltFFI. - -## Plan - -Decided with the maintainer on 2026-10-13: - -- **Candidates**: [BoltFFI](https://github.com/boltffi/boltffi) only. It 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. -- **Known gaps to report, not fix**: no Go or C++, Dart is unfinished, C is - sync-only, and async constructors and static async methods are dropped - (boltffi/boltffi#95, which `connect` hits). One maintainer wrote about 80% - of the code. Same-name types in one target probably collide (RFC #700). -- **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. -- **Measure** on the [payload harness](/quest/m1/ffi-bytes.md): no-op and - record call overhead, payload throughput across frame sizes, 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), each with moq-ffi's default features on and off, for both - generators. Put moq-wasm in the table for reference. -- **Browser half**: BoltFFI joins the browser generator choice in - [#5478](https://github.com/moq-dev/moq/pull/5478) as a third candidate on - the baseline harness. This quest owns the native half and the combined - size table. Neither blocks the other. - -Public API: none. Wire: none. - -## Required - -- [Payload bytes](/quest/m1/ffi-bytes.md) - the per-wrapper benchmark harness - -## Related - -- [Rust-backed @moq/net](/quest/m2/rs2ts/README.md) - the browser binding choice BoltFFI also competes in -- [Hard-fork UniFFI](/quest/m1/uniffi-fork.md) - the alternative to switching generators diff --git a/quest/m2/uniffi-namespaces.md b/quest/m2/uniffi-namespaces.md index 412f017df3d..e9eae1182c6 100644 --- a/quest/m2/uniffi-namespaces.md +++ b/quest/m2/uniffi-namespaces.md @@ -30,4 +30,4 @@ Public API: none in moq until the crate split is re-decided. Wire: none. ## Required -- [Hard-fork UniFFI](/quest/m1/uniffi-fork.md) - the repository the fix lands in +- [Hard fork](/quest/m1/uniffi-fork.md) - the repository the fix lands in From 9d042c75fc6e56f12504632d4613aaf548c9e521 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 13 Oct 2026 20:45:15 -0700 Subject: [PATCH 3/5] quest(boltffi): the slice crate also serves the browser comparison Co-Authored-By: Claude Opus 5.5 --- quest/m1/boltffi.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/quest/m1/boltffi.md b/quest/m1/boltffi.md index 8e173feac34..a0088292752 100644 --- a/quest/m1/boltffi.md +++ b/quest/m1/boltffi.md @@ -35,7 +35,9 @@ Decided with the maintainer on 2026-10-13: `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). + [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. From c83c59dd8974b631a62ab19a35662ad3a381ce7d Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 13 Oct 2026 20:49:12 -0700 Subject: [PATCH 4/5] quest: address review on payload copies, cancel semantics, and BoltFFI statics Co-Authored-By: Claude Opus 5.5 --- quest/m1/boltffi.md | 4 +++- quest/m1/ffi-bytes.md | 12 ++++++++---- quest/m1/ffi-poll.md | 14 +++++++++----- 3 files changed, 20 insertions(+), 10 deletions(-) diff --git a/quest/m1/boltffi.md b/quest/m1/boltffi.md index a0088292752..68330248f19 100644 --- a/quest/m1/boltffi.md +++ b/quest/m1/boltffi.md @@ -25,7 +25,9 @@ Decided with the maintainer on 2026-10-13: 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, which `connect` hits). One maintainer wrote about 80% + (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 diff --git a/quest/m1/ffi-bytes.md b/quest/m1/ffi-bytes.md index 78a69162450..cc73fa66f22 100644 --- a/quest/m1/ffi-bytes.md +++ b/quest/m1/ffi-bytes.md @@ -1,9 +1,10 @@ -# [L] Binding payloads cross the FFI in one copy +# [L] Binding payloads cross the FFI without per-byte copies ## Goal -A binding moves a frame payload across the FFI with at most one bulk copy in -each direction, proven by a payload benchmark in every wrapper (Python, Go, +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. @@ -26,7 +27,10 @@ Decided with the maintainer on 2026-10-13: 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. + 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 diff --git a/quest/m1/ffi-poll.md b/quest/m1/ffi-poll.md index 2e8347564e3..5974039f5de 100644 --- a/quest/m1/ffi-poll.md +++ b/quest/m1/ffi-poll.md @@ -18,14 +18,18 @@ Decided with the maintainer on 2026-10-13: 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. Cancelling the foreign future drops - the waiter. Measure what remains of `Task` (cancel, shutdown). + 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. Since moq owns [the fork](/quest/m1/uniffi-fork.md), a - generator-level poll protocol, or a `RustFuture` that drops the future on - cancel instead of at free, is a candidate too if the numbers justify it. + 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): From 63fd57632a19e9e5f9c9a973879a75f272e42c19 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 13 Oct 2026 20:50:14 -0700 Subject: [PATCH 5/5] quest(boltffi): default features only change the native size Co-Authored-By: Claude Opus 5.5 --- quest/m1/boltffi.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/quest/m1/boltffi.md b/quest/m1/boltffi.md index 68330248f19..2ec1e546d9c 100644 --- a/quest/m1/boltffi.md +++ b/quest/m1/boltffi.md @@ -44,8 +44,9 @@ Decided with the maintainer on 2026-10-13: 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), each with moq-ffi's default features on and off, for both - generators. Put moq-wasm in the table for reference. + (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