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
4 changes: 4 additions & 0 deletions quest/m1/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<moq-watch>`, `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`
Expand Down
63 changes: 63 additions & 0 deletions quest/m1/boltffi.md
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
52 changes: 52 additions & 0 deletions quest/m1/ffi-bytes.md
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
52 changes: 52 additions & 0 deletions quest/m1/ffi-poll.md
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.

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.

[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.

`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
5 changes: 3 additions & 2 deletions quest/m1/ffi-shape/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
75 changes: 75 additions & 0 deletions quest/m1/uniffi-fork.md
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
2 changes: 2 additions & 0 deletions quest/m2/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
28 changes: 28 additions & 0 deletions quest/m2/ffi-bytes-return.md
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
9 changes: 7 additions & 2 deletions quest/m2/ffi-size-profile.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
33 changes: 33 additions & 0 deletions quest/m2/uniffi-namespaces.md
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
Loading