From b347f5f2d2603f00234def4ea6ec766adde2f094 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 12 Oct 2026 22:21:26 -0700 Subject: [PATCH 1/3] plan: quest for one UniFFI crate per binding layer A spike checks that the Go, Dart, and C++ generators (then Kotlin, Swift, Python) handle several UniFFI crates in one library before migrating, so generated names drop the Moq and layer prefixes. It reopens the 2026-10-09 ffi-shape one-crate decision, left open for the maintainer. Co-Authored-By: Claude Opus 5.5 --- quest/m1/ffi-shape/README.md | 3 +- quest/m2/README.md | 1 + quest/m2/ffi-crate-split.md | 77 ++++++++++++++++++++++++++++++++++++ 3 files changed, 80 insertions(+), 1 deletion(-) create mode 100644 quest/m2/ffi-crate-split.md diff --git a/quest/m1/ffi-shape/README.md b/quest/m1/ffi-shape/README.md index c9d7c104951..beb946f13a4 100644 --- a/quest/m1/ffi-shape/README.md +++ b/quest/m1/ffi-shape/README.md @@ -52,7 +52,8 @@ Settled shape: the wrappers supply real namespaces in each language's idiom: Python submodules, Go subpackages (`moq.dev/moq/json`, aliased on import next to `encoding/json`), Kotlin packages, Dart libraries, Swift caseless-enum - namespaces. + namespaces. [One UniFFI crate per binding layer](/quest/m2/ffi-crate-split.md) + proposes reopening this, pending the maintainer. - `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/m2/README.md b/quest/m2/README.md index a6a79c37fb6..390564b0c2a 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -37,6 +37,7 @@ and bench readiness. Refusal reasons folded the same day into - [MP4 export](/quest/m2/mp4-export.md) - `moq export mp4 --output` records crash-safe fragments, then finishes a regular MP4 with moov at the end - [fMP4 edit lists](/quest/m2/fmp4-edit-lists.md) - the fMP4 importer applies edit lists to frame timestamps - [Shared timebase in the bindings](/quest/m2/ffi-timebase.md) - binding apps publish several containers from one source on one shared offset +- [One UniFFI crate per binding layer](/quest/m2/ffi-crate-split.md) - a generator spike, then per-layer UniFFI crates in one library so generated names drop the `Moq` and layer prefixes; reopens the one-crate decision - [Linux decoded frames](/quest/m2/obs-decode-linux.md) - present supported native decoded surfaces with visible CPU fallback - [Windows decoded frames](/quest/m2/obs-decode-windows.md) - present decoded D3D11 surfaces in OBS without CPU readback - [macOS GPU input](/quest/m2/obs-macos.md) - feed the encoder from the OBS compositor without CPU readback diff --git a/quest/m2/ffi-crate-split.md b/quest/m2/ffi-crate-split.md new file mode 100644 index 00000000000..8dbb88931ee --- /dev/null +++ b/quest/m2/ffi-crate-split.md @@ -0,0 +1,77 @@ +# [L] One UniFFI crate per binding layer + +## Goal + +The generated bindings carry the layers themselves. moq-ffi becomes one +UniFFI crate per layer (`net`, `media`, `json`, `flate`, `audio`, `video`), +all linked into the one moq-ffi library, so a generated type is +`media.ContainerGroupConsumer` instead of `MoqMediaContainerGroupConsumer`. +A spike first proves that every generator handles several crates. If one +cannot, the quest ends with a written no-go per generator, and the wrappers +keep supplying the namespaces. + +Out of scope: the hand-written moq-c, the wire, and Rust type names. + +## Plan + +Raised on #5356, where the maintainer found `MoqMediaContainerGroupConsumer` +too long and asked how to namespace the modules better. The long name shows +up in moq-ffi's source, the raw generated packages (`go/ffi`, +`dart/moq_ffi`), and C++ (`moq::MediaContainerGroupConsumer`). The Python, +Go, Swift, Kotlin, and Dart wrappers already shorten it to +`media.ContainerGroupConsumer`. + +Open question for the maintainer: this reopens the 2026-10-09 decision in +[The bindings mirror Rust's layers](/quest/m1/ffi-shape/README.md) that +moq-ffi stays one crate and the wrappers supply the namespaces, since +UniFFI 0.32 gives each crate one flat namespace. The spike can run before it +is answered. The migration waits for a yes. + +Options weighed on #5356: + +- ✅ One UniFFI crate per layer, all in one library. This is the only option + that puts real namespaces below the wrappers. Mozilla's + application-services ships many UniFFI component crates in one "megazord" + library this way. +- Drop `Moq` with `#[uniffi(name = "...")]`. The layer prefix stays, + because the namespace is still flat. Bare names collide with host types + (Swift `Error`, Kotlin `Result`), and UniFFI renames behave inconsistently + in Python and for custom types. +- Keep the generated names and treat them as plumbing behind the wrappers. + +Spike, splitting `media` from `net` alone: + +1. Generate bindings from the built library, in this order: uniffi-bindgen-go, + uniffi-bindgen-dart, uniffi-bindgen-cpp, then Kotlin, Swift, and Python. + For each, check two things: + - It emits one module per crate. + - A `media` constructor that takes a `net` `GroupConsumer` resolves it as + an external type. + + The Go, Dart, and C++ generators are kixelated forks pinned in + `flake.nix`, so patch a gap in the fork before calling it a no-go. +2. Check that each platform still ships one native library: the `go/ffi` + module layout, the Swift XCFramework and its module maps, the Kotlin and + Android artifacts, the `moq_ffi` Dart package, the Python wheel, and the + C++ CMake package. +3. Record the verdict for each generator here, along with the library size + before and after the split. + +If the spike passes and the maintainer reopens the decision, migrate: + +- Split moq-ffi into one crate per ffi-shape layer. +- Point each wrapper at the generated modules, and delete any wrapper code + that only existed to rename types. +- Update `doc/lib`, the Unreleased section of `doc/setup/upgrade.md`, and the + ffi-shape Plan. +- Run `just test interop --all`. + +The migration lands after [Codecs](/quest/m1/ffi-shape/codec.md), so it does +not fight that reshape of `audio` and `video`. + +## Related + +- [The bindings mirror Rust's layers](/quest/m1/ffi-shape/README.md) - the one-crate decision this reopens +- [Unprefixed generated C++](/quest/m1/cpp-generated-shape.md) - its `Moq` prefix rename shrinks if the C++ generator gives each crate its own namespace +- [Generated C bindings](/quest/m1/c/README.md) - the C backend in the same generator fork would also see one module per crate +- [Bindings size profile](/quest/m1/ffi-size-profile.md) - measures the same library whose size the split may change From 8b64ed437667af1263645ef8df398654386cc5b7 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 13 Oct 2026 08:53:56 -0700 Subject: [PATCH 2/3] plan: record the reopened one-crate decision and fold in Codex findings The maintainer reopened the moq-ffi one-crate decision on 2026-10-13. The spike now breaks the net/media cycle first, checks external errors and records as well as objects, and the migration names the C++ and OBS consumers. Co-Authored-By: Claude Opus 5.5 --- quest/m1/ffi-shape/README.md | 5 +++-- quest/m2/ffi-crate-split.md | 31 +++++++++++++++++++------------ 2 files changed, 22 insertions(+), 14 deletions(-) diff --git a/quest/m1/ffi-shape/README.md b/quest/m1/ffi-shape/README.md index beb946f13a4..ed2363b603a 100644 --- a/quest/m1/ffi-shape/README.md +++ b/quest/m1/ffi-shape/README.md @@ -52,8 +52,9 @@ Settled shape: the wrappers supply real namespaces in each language's idiom: Python submodules, Go subpackages (`moq.dev/moq/json`, aliased on import next to `encoding/json`), Kotlin packages, Dart libraries, Swift caseless-enum - namespaces. [One UniFFI crate per binding layer](/quest/m2/ffi-crate-split.md) - proposes reopening this, pending the maintainer. + namespaces. Reopened 2026-10-13: + [One UniFFI crate per binding layer](/quest/m2/ffi-crate-split.md) spikes + a per-layer split that would move the namespaces below the wrappers. - `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/m2/ffi-crate-split.md b/quest/m2/ffi-crate-split.md index 8dbb88931ee..1f8c1ac9c84 100644 --- a/quest/m2/ffi-crate-split.md +++ b/quest/m2/ffi-crate-split.md @@ -21,11 +21,12 @@ up in moq-ffi's source, the raw generated packages (`go/ffi`, Go, Swift, Kotlin, and Dart wrappers already shorten it to `media.ContainerGroupConsumer`. -Open question for the maintainer: this reopens the 2026-10-09 decision in +✅ The maintainer reopened (2026-10-13) the 2026-10-09 decision in [The bindings mirror Rust's layers](/quest/m1/ffi-shape/README.md) that -moq-ffi stays one crate and the wrappers supply the namespaces, since -UniFFI 0.32 gives each crate one flat namespace. The spike can run before it -is answered. The migration waits for a yes. +moq-ffi stays one crate and the wrappers supply the namespaces, calling the +5-word generated name from #5356 terrible. UniFFI 0.32 gives each crate one +flat namespace, so only a split shortens it. The migration waits for the +spike to pass. Options weighed on #5356: @@ -41,27 +42,33 @@ Options weighed on #5356: Spike, splitting `media` from `net` alone: -1. Generate bindings from the built library, in this order: uniffi-bindgen-go, +1. Make the dependency one-way, `media` on `net`. Today `net`'s consumers + return `MoqFrame` and `MoqDatagram` from `media.rs`, which Cargo would + reject as a cycle; those raw records likely belong in `net`. +2. Generate bindings from the built library, in this order: uniffi-bindgen-go, uniffi-bindgen-dart, uniffi-bindgen-cpp, then Kotlin, Swift, and Python. - For each, check two things: + For each, check: - It emits one module per crate. - - A `media` constructor that takes a `net` `GroupConsumer` resolves it as - an external type. + - `net` types used from `media` resolve as external types, covering each + category the real split crosses: an object (`GroupConsumer`), the + thrown `MoqError`, and a record or enum. The Go, Dart, and C++ generators are kixelated forks pinned in `flake.nix`, so patch a gap in the fork before calling it a no-go. -2. Check that each platform still ships one native library: the `go/ffi` +3. Check that each platform still ships one native library: the `go/ffi` module layout, the Swift XCFramework and its module maps, the Kotlin and Android artifacts, the `moq_ffi` Dart package, the Python wheel, and the C++ CMake package. -3. Record the verdict for each generator here, along with the library size +4. Record the verdict for each generator here, along with the library size before and after the split. -If the spike passes and the maintainer reopens the decision, migrate: +If the spike passes, migrate: - Split moq-ffi into one crate per ffi-shape layer. - Point each wrapper at the generated modules, and delete any wrapper code - that only existed to rename types. + that only existed to rename types. This includes every `rs/moq-ffi` + consumer in AGENTS.md's Cross-Package Sync table; `cpp/moq`'s alias list + backs the flat `moq::Media*` names that `cpp/obs/src` uses. - Update `doc/lib`, the Unreleased section of `doc/setup/upgrade.md`, and the ffi-shape Plan. - Run `just test interop --all`. From 5b9ee23520b4b62c2e78d3f85e7827f0f08bce9c Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 13 Oct 2026 09:00:24 -0700 Subject: [PATCH 3/3] plan: keep every split layer on the one ffi runtime Co-Authored-By: Claude Opus 5.5 --- quest/m2/ffi-crate-split.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/quest/m2/ffi-crate-split.md b/quest/m2/ffi-crate-split.md index 1f8c1ac9c84..a24c9a4c23f 100644 --- a/quest/m2/ffi-crate-split.md +++ b/quest/m2/ffi-crate-split.md @@ -64,7 +64,10 @@ Spike, splitting `media` from `net` alone: If the spike passes, migrate: -- Split moq-ffi into one crate per ffi-shape layer. +- Split moq-ffi into one crate per ffi-shape layer. Every layer keeps the + one runtime in `ffi.rs`, so `moq_ffi_shutdown` (Python's `atexit` hook) + still stops tasks from every layer; add an exit regression with a live + non-`net` task. - Point each wrapper at the generated modules, and delete any wrapper code that only existed to rename types. This includes every `rs/moq-ffi` consumer in AGENTS.md's Cross-Package Sync table; `cpp/moq`'s alias list