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: 3 additions & 1 deletion quest/m1/ffi-shape/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +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.
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
Expand Down
1 change: 1 addition & 0 deletions quest/m2/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
87 changes: 87 additions & 0 deletions quest/m2/ffi-crate-split.md
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.
Comment on lines +48 to +54

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.

[P2] Require shortened generated names in the spike acceptance test

Separate modules and working external types do not establish the promised media.ContainerGroupConsumer API. Rust type renaming is explicitly out of scope, while the current source and generated bindings preserve MoqMediaContainerGroupConsumer. 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.


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
Loading