diff --git a/quest/m1/README.md b/quest/m1/README.md index a58dc8767ed..d30396f7e14 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -18,7 +18,6 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. ## Quests - [BBR classic ECN](/quest/m1/bbr-classic-ecn.md) - Startup and bandwidth probing respond to CE marks before the bottleneck drops packets -- [libmoq hidden opt-in](/quest/m1/libmoq-hidden.md) - `moq_origin_announced` takes a `hidden` flag so C callers can list `.`-named broadcasts - [lite-07 count settle](/quest/m1/lite-count-settle.md) - moq-lite-07 subscribers stop waiting for a subscription's tail once SUBSCRIBE_END's stream count is reached - [Dropped sources](/quest/m1/dropped-sources.md) - track consumers see the producer's real error on every end path, never `Dropped` - [JS group guard](/quest/m1/js-group-guard.md) - a `@moq/net` publisher abandons a group past its max age without an unhandled rejection @@ -51,6 +50,7 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [Tests under load](/quest/m1/test-flakes.md) - three tests that time out or run out of file descriptors under `just check` are fixed at the cause - [Decoded frame ownership](/quest/m1/decoded-frames.md) - retain moq-video Frames across bindings, with native views or CPU conversion as needed - [C++ through moq-ffi](/quest/m1/cpp/README.md) - generated C++ over moq-ffi with futures and expected-style errors, shipped as a tarball, vcpkg, and Conan, and adopted by the OBS plugin +- [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 - [moq-c](/quest/m1/moq-c.md) - libmoq ships as `moq-c`, beside `moq-cpp`, with its C header and library unchanged - [OBS native codecs](/quest/m1/obs-moq-video/README.md) - remove FFmpeg decoding dependencies, deliver GPU frames, and use native audio/video encoders - [Opus concealment](/quest/m1/opus-conceal.md) - a lost Opus packet conceals the last packet's length, not 120 ms @@ -139,12 +139,9 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [Go mirror delivery](/quest/m1/go-mirror-delivery.md) - the Go binding's staticlibs stop growing git history by ~210 MiB per release - [Relay iroh opt-in](/quest/m1/relay-iroh-opt-in.md) - moq-relay drops iroh from its defaults and shipped builds, while moq-cli keeps it for P2P - [Dart on iOS](/quest/m1/dart-ios.md) - prove the shipped iOS native asset actually loads on a device, which no CI can -- [libmoq shutdown](/quest/m1/libmoq-shutdown.md) - OBS exits cleanly with the plugin loaded: a C ABI `moq_shutdown` stops the libmoq thread before the module is unloaded - [Kotlin JVM exit](/quest/m1/kt-jvm-exit.md) - a Kotlin/JVM program exits cleanly whatever the moq-ffi runtime thread is doing, like Python does since #3766 - [Dart publish](/quest/m1/dart-publish.md) - the packages are built and dry-run clean but exist nowhere consumers can install from - [Dart codec parity](/quest/m1/dart-codecs.md) - Dart is the one binding that cannot originate media -- [libmoq CMake library](/quest/m1/libmoq-cmake-lib.md) - the in-tree CMake build links the `libmoq.a` cargo reports, not a hardcoded `target/` path -- [libmoq fetch](/quest/m1/libmoq-fetch.md) - libmoq gains an additive cached-group fetch entry point - [moq-mux on wasm32](/quest/m1/mux-wasm-target.md) - the crate's two wasm blockers are fixed and the target stays in the clippy lane - [#2850](/quest/m1/2850-js-net-give-reader-a-synchronous-decode-so-the-publisher.md) - js/net: decode messages synchronously from buffered bytes and delete the publisher read-ahead queue - [Install moq](/quest/m1/moq-installer.md) - one command installs or upgrades the released CLI on macOS and Linux diff --git a/quest/m1/c/README.md b/quest/m1/c/README.md new file mode 100644 index 00000000000..16dc144787b --- /dev/null +++ b/quest/m1/c/README.md @@ -0,0 +1,56 @@ +# Generated C bindings + +## Goal + +C programs use moq through a C API generated from moq-ffi, shipped as the +`moq-c` package with CMake target `moq::c`, so the hand-written libmoq ABI is +deleted and C tracks every moq-ffi change the way Go, Swift, Kotlin, Python, +Dart, and C++ already do. The C API shape follows moq-ffi and breaks C users +once. The C++ package and the OBS plugin are out of scope; they already sit on +moq-ffi through [C++ through moq-ffi](/quest/m1/cpp/README.md). + +## Plan + +Decided: + +- The generator is a C backend in the `kixelated/uniffi-bindgen-cpp` fork, + beside the C++ one, so both share its parsing, async, and error plumbing and + one pinned tool covers both. No mature upstream C generator exists; uniffi + itself only emits the low-level scaffolding header. +- Async calls take a completion callback and user data and return a task; + freeing the task cancels the call. Callbacks run on moq's dispatcher thread + by default, or on the host's own loop through `moq_set_dispatcher` and + `moq_work_run`, the C form of `moq::set_executor`. Streams are repeated calls. + This removes the trampolines and lock-order rules libmoq's single callback + thread forced on hosts like OBS. +- Errors, records, and names mirror the C++ package: calls return `moq_error *` + (NULL on success) with `moq_error_message()`, results come through + out-params, records are owned structs with `moq__free`, and names are + the uniffi names in snake case. +- The generated package takes over the `moq-c` name and `moq::c` target that + #4288 gives the hand-written crate, so C users migrate once. Its first release + is 0.8.0, a minor bump over the hand-written 0.7.x. +- Docs change inline: the consumer quest rewrites `doc/lib/c`, and retirement + adds an upgrade note. No separate guide. + +The line owns the end-to-end check: every `doc/lib/c` sample and the C interop +client build and run against the released 0.8.0 archive, not only in-tree. + +The hand-written crate's open feature quests are parked in m3 until this line +retires it: [fetch](/quest/m3/libmoq-fetch.md), +[hidden](/quest/m3/libmoq-hidden.md), +[CMake library](/quest/m3/libmoq-cmake-lib.md), and +[shutdown](/quest/m3/libmoq-shutdown.md). + +## Quests + +- [C backend](/quest/m1/c/backend.md) - the fork emits an ergonomic C header and implementation from moq-ffi, with its own tests +- [moq-c package](/quest/m1/c/package.md) - the generated header ships as `moq-c` 0.8.0 with `moq::c`, pkg-config, and a release workflow +- [C consumers](/quest/m1/c/consumers.md) - the C interop client and `doc/lib/c` samples move onto the generated API +- [Retire libmoq](/quest/m1/c/retire.md) - the hand-written crate is deleted after its final release points at the generated package + +## Related + +- [C++ through moq-ffi](/quest/m1/cpp/README.md) - the generator fork and package recipe this line extends +- [libmoq becomes moq-c](/quest/m1/moq-c.md) - the rename whose name this line inherits +- [FFI shape](/quest/m1/ffi-shape/README.md) - reshapes moq-ffi, which the generated C then follows for free diff --git a/quest/m1/c/backend.md b/quest/m1/c/backend.md new file mode 100644 index 00000000000..404f5e0f420 --- /dev/null +++ b/quest/m1/c/backend.md @@ -0,0 +1,25 @@ +# [L] C backend in the bindings generator + +## Goal + +`uniffi-bindgen-cpp` (the `kixelated` fork) gains a C backend that turns +moq-ffi's uniffi metadata into an ergonomic C header and implementation, in the +shape the [line](/quest/m1/c/README.md) decided: completion callbacks with a +cancelling task handle, a pluggable dispatcher, `moq_error *` returns with +out-params, owned record structs with free functions, and snake-case uniffi +names. + +## Plan + +- Build on the fork's C++ backend: it already walks the metadata, serializes + records and errors through `RustBuffer`, and drives `rust_future_poll` on a + dispatcher. The C backend emits the same calls behind a C surface, so the + generated implementation may itself be C++ compiled into the package, as long + as the public header is plain C (C99 or C11; say which). +- Cover every construct moq-ffi uses today: objects (handles), records, enums, + the one error type, async methods, and byte buffers. moq-ffi has no callback + interfaces; refuse them loudly rather than emit something half-working. +- The fork's test suite gains C fixtures for each construct, including + cancelling a pending task and running callbacks through a custom dispatcher. +- Offer the backend to the LiveKit or NordSecurity upstream once its shape + settles, or record why not. diff --git a/quest/m1/c/consumers.md b/quest/m1/c/consumers.md new file mode 100644 index 00000000000..79ec9006599 --- /dev/null +++ b/quest/m1/c/consumers.md @@ -0,0 +1,18 @@ +# [S] C consumers on the generated API + +## Goal + +The C interop client (`test/interop/clients/c`) and the `doc/lib/c` samples use +the generated `moq-c` API and pass `just test interop --all` and the doc-sample +build. Nothing in the repository calls the hand-written ABI any more. + +## Plan + +- Port the interop client first; it is the smallest real consumer and proves + the callback and dispatcher shape end to end. +- Rewrite `doc/lib/c` around the generated API, including a sample that runs + callbacks on the host's own loop through `moq_set_dispatcher`. + +## Required + +- [moq-c package](/quest/m1/c/package.md) - the package these consumers link diff --git a/quest/m1/c/package.md b/quest/m1/c/package.md new file mode 100644 index 00000000000..686ecc5ea88 --- /dev/null +++ b/quest/m1/c/package.md @@ -0,0 +1,28 @@ +# [M] moq-c package from the generated C + +## Goal + +The generated C ships as the `moq-c` package, version 0.8.0: a release archive +with the header, the moq-ffi staticlib, a CMake config exporting `moq::c`, and +`moq-c.pc`, built the same way `cpp/moq` builds the C++ package. It replaces the +hand-written crate's artifacts under the same names. + +## Plan + +- Mirror `cpp/moq`: CMake runs `cargo build -p moq-ffi`, then the generator's C + backend, and installs the result; a probe test compiles and links from the + installed package through both `find_package(moq-c)` and pkg-config. +- The installed CMake config honors `CMAKE_INSTALL_LIBDIR`, so a `lib64` + distro gets a working `find_package`; the hand-written crate's config + hardcodes `/lib`. +- `doc/index.md` says the C library ships static and shared; say what the + package actually ships. +- A release workflow and nightly/CI jobs follow the C++ package's, pinned to the + fork tag that carries the C backend. +- Every Cross-Package Sync row that names libmoq for moq-ffi changes points at + the generated package instead; update `AGENTS.md` in this quest. + +## Required + +- [libmoq becomes moq-c](/quest/m1/moq-c.md) - the rename that frees the `moq-c` name and `moq::c` target this package takes over +- [C backend](/quest/m1/c/backend.md) - the generator output this packages diff --git a/quest/m1/c/retire.md b/quest/m1/c/retire.md new file mode 100644 index 00000000000..cb3aa49e205 --- /dev/null +++ b/quest/m1/c/retire.md @@ -0,0 +1,17 @@ +# [S] Retire the hand-written libmoq + +## Goal + +The hand-written C crate is gone: its last release points users at the +generated `moq-c` 0.8.0, and the source, workflows, and docs that only served +it are deleted. `doc/setup/upgrade.md` tells C users how to move. + +## Plan + +- Fold in any retirement step #4288 already planned for the renamed crate. +- Decide the parked m3 libmoq quests: delete each whose outcome the generated + API already provides, and say so in the PR. + +## Required + +- [C consumers](/quest/m1/c/consumers.md) - nothing in the repository still calls the hand-written ABI diff --git a/quest/m1/cpp/README.md b/quest/m1/cpp/README.md index 3faa892c8f5..a48bae41947 100644 --- a/quest/m1/cpp/README.md +++ b/quest/m1/cpp/README.md @@ -9,8 +9,8 @@ cancellable futures, with no `user_data` plumbing, no handle integers, and no thread of their own to babysit. The OBS plugin is the in-tree consumer that proves the shape; external SDK users are the audience. -Non-goals: libmoq stays as the plain-C ABI, keeps its own release, and keeps -following the Cross-Package Sync table like every other wrapper; no +Non-goals: the plain-C ABI, which moves to C generated from moq-ffi in +[Generated C bindings](/quest/m1/c/README.md); no second hand-written C++ surface (ergonomics are fixed in moq-ffi where every binding benefits); no wire or public Rust API change. diff --git a/quest/m1/kt-jvm-exit.md b/quest/m1/kt-jvm-exit.md index b1ccffb892f..62f5681d8f3 100644 --- a/quest/m1/kt-jvm-exit.md +++ b/quest/m1/kt-jvm-exit.md @@ -37,4 +37,4 @@ Public API: none; the hook is internal to the binding. Wire: none. ## Related -- [libmoq shutdown](/quest/m1/libmoq-shutdown.md) - the same hazard class for the C ABI and the OBS plugin +- [libmoq shutdown](/quest/m3/libmoq-shutdown.md) - the same hazard class for the C ABI and the OBS plugin diff --git a/quest/m3/README.md b/quest/m3/README.md index d4403e5befe..232e225d3b2 100644 --- a/quest/m3/README.md +++ b/quest/m3/README.md @@ -20,3 +20,7 @@ condition clears, move the quest to the milestone its work belongs in. - [#2893](/quest/m3/2893-video-validate-pipewire-dma-buf-capture-on-kde-hardware.md) - video: validate PipeWire DMA-BUF capture on KDE hardware - [Embedded video](/quest/m3/video-embedded.md) - EGL import in the renderer, so moq-video presents on a Pi - [Vision worker](/quest/m3/processor-vision.md) - a documented customer-run vision worker proves the processor contract +- [libmoq hidden opt-in](/quest/m3/libmoq-hidden.md) - `moq_origin_announced` takes a `hidden` flag so C callers can list `.`-named broadcasts +- [libmoq shutdown](/quest/m3/libmoq-shutdown.md) - OBS exits cleanly with the plugin loaded: a C ABI `moq_shutdown` stops the libmoq thread before the module is unloaded +- [libmoq CMake library](/quest/m3/libmoq-cmake-lib.md) - the in-tree CMake build links the `libmoq.a` cargo reports, not a hardcoded `target/` path +- [libmoq fetch](/quest/m3/libmoq-fetch.md) - libmoq gains an additive cached-group fetch entry point diff --git a/quest/m1/libmoq-cmake-lib.md b/quest/m3/libmoq-cmake-lib.md similarity index 80% rename from quest/m1/libmoq-cmake-lib.md rename to quest/m3/libmoq-cmake-lib.md index ba5caa31036..9a9887f2fed 100644 --- a/quest/m1/libmoq-cmake-lib.md +++ b/quest/m3/libmoq-cmake-lib.md @@ -8,6 +8,8 @@ Today `BUILD_RUST_LIB` assumes `target//libmoq.a`, so any other layout links a stale library or fails to find one. ## Plan +Parked in m3 behind [Generated C bindings](/quest/m1/c/README.md): the hand-written libmoq is being replaced by C generated from moq-ffi, which carries this for free. Do it only if the hand-written crate outlives that line. + - `cmake/cargo-build.cmake` already parses cargo's JSON messages to find `moq.h` in its hashed `OUT_DIR`. Read the libmoq `compiler-artifact` @@ -24,4 +26,4 @@ layout links a stale library or fails to find one. ## Related -- [libmoq shutdown](/quest/m1/libmoq-shutdown.md) - the other libmoq packaging fix OBS needs +- [libmoq shutdown](/quest/m3/libmoq-shutdown.md) - the other libmoq packaging fix OBS needs diff --git a/quest/m1/libmoq-fetch.md b/quest/m3/libmoq-fetch.md similarity index 78% rename from quest/m1/libmoq-fetch.md rename to quest/m3/libmoq-fetch.md index 15710672158..a6c84306966 100644 --- a/quest/m1/libmoq-fetch.md +++ b/quest/m3/libmoq-fetch.md @@ -6,6 +6,8 @@ A C embedder can fetch one cached group by sequence through the existing frame, handle, and terminal-status conventions. The new entry point is additive. ## Plan +Parked in m3 behind [Generated C bindings](/quest/m1/c/README.md): the hand-written libmoq is being replaced by C generated from moq-ffi, which carries this for free. Do it only if the hand-written crate outlives that line. + Mirror `MoqTrackConsumer::fetch_group` from `rs/moq-ffi/src/consumer.rs` in `rs/libmoq`, supporting raw and container-decoded delivery as the FFI does. diff --git a/quest/m1/libmoq-hidden.md b/quest/m3/libmoq-hidden.md similarity index 70% rename from quest/m1/libmoq-hidden.md rename to quest/m3/libmoq-hidden.md index 5c90440ca64..4095d694f65 100644 --- a/quest/m1/libmoq-hidden.md +++ b/quest/m3/libmoq-hidden.md @@ -8,6 +8,8 @@ prefix) the way every other binding can: `moq_origin_announced` takes a caller can only list them by naming the dot segment in `prefix`. ## Plan +Parked in m3 behind [Generated C bindings](/quest/m1/c/README.md): the hand-written libmoq is being replaced by C generated from moq-ffi, which carries this for free. Do it only if the hand-written crate outlives that line. + - Adding a parameter breaks the C ABI, so this lands on `dev`. - Update `rs/libmoq/src/{api,origin}.rs`, the libmoq tests, `cpp/obs` if it diff --git a/quest/m1/libmoq-shutdown.md b/quest/m3/libmoq-shutdown.md similarity index 92% rename from quest/m1/libmoq-shutdown.md rename to quest/m3/libmoq-shutdown.md index a9d65aaf763..8b4cc4870e4 100644 --- a/quest/m1/libmoq-shutdown.md +++ b/quest/m3/libmoq-shutdown.md @@ -10,6 +10,8 @@ libmoq statically, so the thread's code is unmapped under it. Any host that unloads the library has the same exposure. ## Plan +Parked in m3 behind [Generated C bindings](/quest/m1/c/README.md): the hand-written libmoq is being replaced by C generated from moq-ffi, which carries this for free. Do it only if the hand-written crate outlives that line. + Starts on `main`; libmoq's runtime (`rs/libmoq/src/ffi.rs`) is the same on both branches and the change is additive.