Repository navigation
quest: hard-fork UniFFI, plus payload, async, and BoltFFI spikes #5498
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
5 commits
Select commit
Hold shift + click to select a range
bed659e
quest: hard-fork UniFFI, payload bytes, poll-native async, and BoltFF…
kixelated 8bdd29d
quest: the BoltFFI spike runs in parallel and picks the fork's base
kixelated 9d042c7
quest(boltffi): the slice crate also serves the browser comparison
kixelated c83c59d
quest: address review on payload copies, cancel semantics, and BoltFF…
kixelated 63fd576
quest(boltffi): default features only change the native size
kixelated File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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<u8>` 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 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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<u8>`. 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<u8>` | ||
| through the generic `Vec<T>` 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<u8>`); 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 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
[P3] Describe the existing hot path accurately
moq-ffi already uses kio::wait in the chosen track-consumer hot path (rs/moq-ffi/src/consumer.rs:369–387), and Task::run already polls in place rather than spawning that call (ffi.rs:319–348). Describing the baseline as not using kio/detached work obscures what Shape A actually removes. Update this paragraph to distinguish run from detached and frame the comparison around the remaining synchronization, cancellation and shutdown costs, preserving the existing read-lane semantics.