Repository navigation
plan: quest for one UniFFI crate per binding layer #5405
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
3 commits
Select commit
Hold shift + click to select a range
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
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,87 @@ | ||
| # [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`. | ||
|
|
||
| ✅ 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, 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: | ||
|
|
||
| - ✅ 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. 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: | ||
| - It emits one module per crate. | ||
| - `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. | ||
| 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. | ||
| 4. Record the verdict for each generator here, along with the library size | ||
| before and after the split. | ||
|
|
||
| If the spike passes, migrate: | ||
|
|
||
| - 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 | ||
| 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`. | ||
|
|
||
| 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 | ||
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.
[P2] Require shortened generated names in the spike acceptance test
Separate modules and working external types do not establish the promised
media.ContainerGroupConsumerAPI. Rust type renaming is explicitly out of scope, while the current source and generated bindings preserveMoqMediaContainerGroupConsumer. These checks can therefore pass with the unwanted prefixes still present. Specify the binding-level prefix-removal mechanism and require a compiling consumer using the short identifier in every target language before approving migration.