From b4b96c9ae0d6fa5a12febaee956e9949ca0b16d2 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 29 Oct 2026 08:49:59 -0700 Subject: [PATCH 1/8] chore(quest): claim quest/m1/c/api-gaps.md Quest-Claim: 5f0e027391ea1986 From 69360a4279bc0a1d41122ea0194612cfd5ec9a62 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 29 Oct 2026 09:02:21 -0700 Subject: [PATCH 2/8] feat(c)!: expose audio enablement and normalize epoch errors Co-Authored-By: GPT-6.1 --- doc/lib/c/index.md | 2 +- quest/m1/c/README.md | 1 - quest/m1/c/api-gaps.md | 32 ---- rs/moq-c/README.md | 1 + rs/moq-c/c-tests/audio-decode-output.c | 7 + rs/moq-c/src/api.rs | 30 +++- rs/moq-c/src/consume.rs | 17 +- rs/moq-c/src/test.rs | 216 ++++++++++++++++++++++++- 8 files changed, 255 insertions(+), 51 deletions(-) delete mode 100644 quest/m1/c/api-gaps.md diff --git a/doc/lib/c/index.md b/doc/lib/c/index.md index a491cde3189..c056e53fdfb 100644 --- a/doc/lib/c/index.md +++ b/doc/lib/c/index.md @@ -108,7 +108,7 @@ inside. The header is the reference: each function carries a doc comment. - **Decoded reads.** `moq_decode_audio` and `moq_decode_video` deliver read ids in order: a frame, a gap where media was lost, or an end where the publisher stopped its encoder. Check `kind` on what `moq_decode_audio_read` or `moq_decode_video_read` writes. Free each id with `moq_decode_audio_read_free` or `moq_decode_video_read_free` promptly: a held video frame holds a decoder buffer, and the decoder stalls. - **Stats.** `moq_session_stats()` fills `moq_connection_stats` with `rtt_us`, `estimated_send_rate_bps`, and the byte and packet counters (`bytes_sent`, `bytes_received`, `bytes_lost`, `packets_sent`, `packets_received`, `packets_lost`). Each has a `_valid` flag, false when the transport does not report it, which is not the same as zero. `moq_session_snapshot()` adds the negotiated `protocol`. A failed dial or dropped connection reaches the session's `on_state` with its `failure` code, and `moq_error()` gives the reason during that callback. Hold the handle returned by `moq_session_recv_bandwidth()` to request receive estimates. `moq_bandwidth_consumer_peek()` reads the estimate and `moq_bandwidth_consumer_changed()` waits for a change. `moq_bandwidth_consumer_close()` releases demand; the last consumer stops PROBE. Stats snapshots do not request it. - **Demand.** A watcher from `moq_publish_track_demand()` (or the media, video, and audio variants) calls back `MOQ_DEMAND_USED` or `MOQ_DEMAND_UNUSED`, again whenever the wanted group moves. `moq_publish_demand_wanted()` reads that group: start a new one once it passes your largest. Set `refresh` in `moq_track_info` to have a joining subscriber ask for a new group once the newest has grown past `refresh` times its first frame. -- **Disabled renditions.** A rendition with `enabled: false` has no frames coming until its publisher re-enables it. Select an enabled rendition from the latest catalog before opening a decoder. Keep one already playing while every rendition of its kind is disabled: the convenience decoders accept a disabled configuration, and a re-enable, such as an unmute, then plays without a resubscribe. Among the video renditions you can decode, prefer the highest `preference`; `0` is the default and `-1` marks a compatibility transcode. +- **Disabled renditions.** A rendition with `enabled: false` has no frames coming until its publisher re-enables it. Query the latest catalog with `moq_consume_audio_enabled` or `moq_consume_video_enabled` before selecting a rendition and opening a decoder. Keep one already playing while every rendition of its kind is disabled: the convenience decoders accept a disabled configuration, and a re-enable, such as an unmute, then plays without a resubscribe. Among the video renditions you can decode, prefer the highest `preference`; `0` is the default and `-1` marks a compatibility transcode. ## Reference diff --git a/quest/m1/c/README.md b/quest/m1/c/README.md index bd8de26d5df..af4cbf2d370 100644 --- a/quest/m1/c/README.md +++ b/quest/m1/c/README.md @@ -31,4 +31,3 @@ Public API: moq-c gains each m1 binding feature. Wire: none. - [moq-c decode start](/quest/m1/c/decode-start.md) - a moq-c decoder can read a finished track from its start - [JSON windows](/quest/m1/c/json-window.md) - moq-c publishes and reads moq-json windows, as moq-ffi does -- [API gaps](/quest/m1/c/api-gaps.md) - one malformed-epoch error code, an audio enabled query, and a relay hops test diff --git a/quest/m1/c/api-gaps.md b/quest/m1/c/api-gaps.md deleted file mode 100644 index e545717de76..00000000000 --- a/quest/m1/c/api-gaps.md +++ /dev/null @@ -1,32 +0,0 @@ -# [S] moq-c closes its small API gaps - -## Goal - -moq-c reports a malformed epoch the same way everywhere, lets a C consumer see -that audio is disabled as it can for video, and has a test of the hops on a -route received through a relay. - -## Plan - -Found 2026-10-28 by [moq-dev/moq#7151](https://github.com/moq-dev/moq/pull/7151) -and [moq-dev/moq#7156](https://github.com/moq-dev/moq/pull/7156). - -Decided 2026-10-28 (maintainer): one PR for all three. moq-c already breaks -at this cut (0.6 to 0.7), so the error-code change rides that break. - -- `moq_broadcast_request_prepare` reports a malformed epoch as - `MOQ_ERROR_INVALID_CODE`, while `moq_publication_announce`, which takes an - epoch in `moq_announce_route` since - [moq-dev/moq#7151](https://github.com/moq-dev/moq/pull/7151), reports a - malformed one as `MOQ_ERROR_INVALID_CONFIG`. Use - `MOQ_ERROR_INVALID_CONFIG` for both, with an Impact migration note. -- Add an audio counterpart to `moq_consume_video_enabled`, so a C app can tell - that a held audio rendition is disabled. -- Add a moq-c test that announces through a relay session and checks the - received route's `hops`. - -Update `moq.h`, `rs/moq-c/README.md` and `doc/lib/c` as needed. - -Public API: moq-c gains an audio enabled query and changes one error code. -Wire: none. - diff --git a/rs/moq-c/README.md b/rs/moq-c/README.md index 3eabf2ec079..56a67a3fb09 100644 --- a/rs/moq-c/README.md +++ b/rs/moq-c/README.md @@ -124,6 +124,7 @@ int32_t moq_consume_catalog_free(uint32_t catalog); int32_t moq_consume_video_config(uint32_t catalog, uint32_t index, moq_video_config *dst); int32_t moq_consume_video_enabled(uint32_t catalog, uint32_t index, bool *dst); int32_t moq_consume_audio_config(uint32_t catalog, uint32_t index, moq_audio_config *dst); +int32_t moq_consume_audio_enabled(uint32_t catalog, uint32_t index, bool *dst); // Consuming: Video int32_t moq_consume_video(uint32_t catalog, uint32_t index, uint64_t max_delay_us, moq_status_callback on_frame, void *user_data); diff --git a/rs/moq-c/c-tests/audio-decode-output.c b/rs/moq-c/c-tests/audio-decode-output.c index 4799a02940e..608aea7f787 100644 --- a/rs/moq-c/c-tests/audio-decode-output.c +++ b/rs/moq-c/c-tests/audio-decode-output.c @@ -128,6 +128,13 @@ int main(void) { wait_until(&c, &c.catalog); pthread_mutex_unlock(&c.mutex); + bool enabled = false; + CHECK(moq_consume_audio_enabled((uint32_t)c.catalog, 0, &enabled) == 0); + CHECK(enabled); + CHECK(moq_consume_audio_enabled((uint32_t)c.catalog, 1, &enabled) == MOQ_ERROR_NO_INDEX); + CHECK(enabled); // An error preserves the destination. + CHECK(moq_consume_audio_enabled((uint32_t)c.catalog, 0, NULL) == MOQ_ERROR_INVALID_POINTER); + // Each decode reads the finished track from the start. Its budget is the track's whole // retention, since the budget ages groups by wall clock and a stalled host would skip them. const uint32_t formats[] = {MOQ_AUDIO_SAMPLE_FORMAT_F32, MOQ_AUDIO_SAMPLE_FORMAT_F32_PLANAR, MOQ_AUDIO_SAMPLE_FORMAT_S16}; diff --git a/rs/moq-c/src/api.rs b/rs/moq-c/src/api.rs index cf5e9a123f2..c2203e1739c 100644 --- a/rs/moq-c/src/api.rs +++ b/rs/moq-c/src/api.rs @@ -1912,6 +1912,7 @@ pub unsafe extern "C" fn moq_broadcast_request_path(request: u32, dst: *mut moq_ /// Consumes the request handle, writes the new broadcast handle to `broadcast` /// (which cannot announce itself; only [moq_broadcast_prepared_publish] does), /// and returns a positive prepared-answer handle or a negative error. +/// A malformed epoch returns `MOQ_ERROR_INVALID_CONFIG` without consuming the request. /// /// # Safety /// - `epoch` must point at `epoch_len` readable bytes containing a UUIDv7 epoch. @@ -1925,9 +1926,10 @@ pub unsafe extern "C" fn moq_broadcast_request_prepare( ) -> i32 { ffi::enter(move || { let request = ffi::parse_id(request)?; - let epoch = unsafe { ffi::parse_str(epoch, epoch_len)? } + let epoch = unsafe { ffi::parse_str(epoch, epoch_len)? }; + let epoch = epoch .parse() - .map_err(|_| Error::InvalidCode)?; + .map_err(|_| Error::InvalidConfig(format!("epoch {epoch:?} is not canonical UUIDv7 text")))?; let broadcast_out = unsafe { broadcast.as_mut() }.ok_or(Error::InvalidPointer)?; let mut state = State::lock(); let (pending, driver) = state.origin.broadcast_request_take(request)?; @@ -3555,6 +3557,30 @@ pub unsafe extern "C" fn moq_consume_audio_config(catalog: u32, index: u32, dst: }) } +/// Query whether the publisher is serving an audio rendition. +/// +/// False means no frames are coming until it re-enables. Pick an enabled rendition, but keep one +/// already playing while every audio rendition is disabled, so a re-enable plays without a +/// resubscribe. A catalog that omits the optional field reads as true. +/// +/// Returns zero on success, or a negative code on failure. +/// +/// # Safety +/// - The caller must ensure that `dst` points to properly aligned, writable storage for a `bool`. +#[unsafe(no_mangle)] +pub unsafe extern "C" fn moq_consume_audio_enabled(catalog: u32, index: u32, dst: *mut bool) -> i32 { + ffi::enter(move || { + let catalog = ffi::parse_id(catalog)?; + if dst.is_null() { + return Err(Error::InvalidPointer); + } + + let enabled = State::lock().consume.audio_enabled(catalog, index as usize)?; + unsafe { dst.write(enabled) }; + Ok(()) + }) +} + /// Number of untyped application catalog sections in a catalog snapshot. /// /// These are the top-level catalog keys beyond `video`/`audio`, carried through diff --git a/rs/moq-c/src/consume.rs b/rs/moq-c/src/consume.rs index 8ac5ce54f7b..8b4123ba1f9 100644 --- a/rs/moq-c/src/consume.rs +++ b/rs/moq-c/src/consume.rs @@ -337,16 +337,15 @@ impl Consume { Ok(()) } - /// Return whether a video rendition may be selected. + /// Return whether the publisher is serving a video rendition. pub fn video_enabled(&self, catalog: Id, index: usize) -> Result { - let consume = self.catalog.get(catalog).ok_or(Error::CatalogNotFound)?; - let (_, config) = consume - .catalog - .video - .renditions - .iter() - .nth(index) - .ok_or(Error::NoIndex)?; + let (_, _, config) = self.select::(catalog, index)?; + Ok(config.enabled) + } + + /// Return whether the publisher is serving an audio rendition. + pub fn audio_enabled(&self, catalog: Id, index: usize) -> Result { + let (_, _, config) = self.select::(catalog, index)?; Ok(config.enabled) } diff --git a/rs/moq-c/src/test.rs b/rs/moq-c/src/test.rs index ec7ea65798d..3d1eb672b62 100644 --- a/rs/moq-c/src/test.rs +++ b/rs/moq-c/src/test.rs @@ -938,6 +938,118 @@ fn publish_catalog_config_null_pointer() { assert_eq!(moq_publish_close(broadcast), 0); } +/// Enablement belongs to each catalog snapshot; holding a disabled rendition keeps its subscription usable. +#[test] +fn audio_enabled_snapshots_preserve_a_held_consumer() { + let origin = id(moq_origin_create()); + let path = b"audio-enabled"; + let broadcast = publish_broadcast(origin, path); + let media = id(publish_audio( + broadcast, + moq_audio_format::MOQ_AUDIO_FORMAT_OPUS, + &opus_head(), + None, + )); + let consume = request_broadcast(origin, path); + let catalogs = Callback::new(); + let catalog_task = id(unsafe { moq_consume_catalog(consume, Some(channel_callback), catalogs.ptr) }); + let initial = id(catalogs.recv()); + let mut enabled = std::mem::MaybeUninit::::uninit(); + assert_eq!( + unsafe { moq_consume_audio_enabled(initial, 0, enabled.as_mut_ptr()) }, + 0 + ); + assert!(unsafe { enabled.assume_init() }, "omitted enabled defaults to true"); + + let set_enabled = |enabled| { + let mut state = State::lock(); + let catalog = state.publish.target(Id::try_from(broadcast).unwrap()).unwrap().catalog; + catalog + .modify() + .unwrap() + .audio + .renditions + .values_mut() + .next() + .unwrap() + .enabled = enabled; + }; + set_enabled(false); + let disabled = id(catalogs.recv()); + assert_eq!( + unsafe { moq_consume_audio_enabled(disabled, 0, enabled.as_mut_ptr()) }, + 0 + ); + assert!(!unsafe { enabled.assume_init() }); + assert_eq!( + unsafe { moq_consume_audio_enabled(initial, 0, enabled.as_mut_ptr()) }, + 0 + ); + assert!(unsafe { enabled.assume_init() }, "an older snapshot remains unchanged"); + + let mut preserved = true; + assert_eq!( + unsafe { moq_consume_audio_enabled(disabled, 1, &mut preserved) }, + MOQ_ERROR_NO_INDEX + ); + assert!(preserved); + assert_eq!( + unsafe { moq_consume_audio_enabled(disabled, 0, std::ptr::null_mut()) }, + MOQ_ERROR_INVALID_POINTER + ); + + // A held rendition may be opened from a disabled snapshot, then re-enabled without resubscribing. + let frames = Callback::new(); + let track = id(unsafe { moq_consume_audio(disabled, 0, 10_000_000, Some(channel_callback), frames.ptr) }); + set_enabled(true); + let resumed = id(catalogs.recv()); + assert_eq!( + unsafe { moq_consume_audio_enabled(resumed, 0, enabled.as_mut_ptr()) }, + 0 + ); + assert!(unsafe { enabled.assume_init() }); + assert_eq!( + unsafe { moq_consume_audio_enabled(disabled, 0, enabled.as_mut_ptr()) }, + 0 + ); + assert!(!unsafe { enabled.assume_init() }); + let payload = b"resumed-audio"; + assert_eq!( + unsafe { moq_publish_media_frame(media, payload.as_ptr(), payload.len(), 0) }, + 0 + ); + let read = id(frames.recv()); + let mut frame: moq_frame = unsafe { std::mem::zeroed() }; + assert_eq!(unsafe { encoded_frame(read, &mut frame) }, 0); + assert_eq!( + unsafe { std::slice::from_raw_parts(frame.payload, frame.payload_size) }, + payload + ); + assert_eq!(moq_consume_read_free(read), 0); + + assert_eq!(moq_consume_audio_cancel(track), 0); + assert_eq!(frames.recv_terminal(), 0); + for catalog in [initial, disabled, resumed] { + assert_eq!(moq_consume_catalog_free(catalog), 0); + } + assert_eq!( + unsafe { moq_consume_audio_enabled(i32::MAX as u32, 0, &mut preserved) }, + MOQ_ERROR_CATALOG_NOT_FOUND + ); + assert!(preserved); + assert_eq!( + unsafe { moq_consume_audio_enabled(0, 0, &mut preserved) }, + MOQ_ERROR_INVALID_ID + ); + assert!(preserved); + assert_eq!(moq_consume_catalog_cancel(catalog_task), 0); + assert_eq!(catalogs.recv_catalog_terminal(), 0); + assert_eq!(moq_consume_close(consume), 0); + assert_eq!(moq_publish_media_finish(media), 0); + assert_eq!(moq_publish_close(broadcast), 0); + assert_eq!(moq_origin_close(origin), 0); +} + #[test] fn publish_catalog_roundtrip() { let origin = id(moq_origin_create()); @@ -2907,11 +3019,15 @@ fn announce_route_carries_cost_and_epoch_without_hops() { assert_eq!(moq_origin_announced_free(announced), 0); // Anything but canonical UUIDv7 text is refused. - let upper = mint_epoch().to_uppercase(); - for bad in ["6ba7b810-9dad-41d1-80b4-00c04fd430c8", upper.as_str(), "not-an-epoch"] { + for bad in [ + "6ba7b810-9dad-41d1-80b4-00c04fd430c8", + "00000000-0000-7000-8000-00000000000A", + "not-an-epoch", + ] { let route = announce_route(0, bad); - assert!( - unsafe { moq_publication_announce(publication, &route) } < 0, + assert_eq!( + unsafe { moq_publication_announce(publication, &route) }, + MOQ_ERROR_INVALID_CONFIG, "{bad:?} is not an epoch" ); } @@ -2997,8 +3113,22 @@ fn dynamic_serves_a_request_under_a_prefix() { let got = unsafe { std::str::from_utf8(std::slice::from_raw_parts(info.data.cast::(), info.len)).unwrap() }; assert_eq!(got, "live/cam"); - let epoch = moq_net::Epoch::mint().to_string(); - let mut served = 0; + // Invalid input leaves the request and destination intact, so it can still be answered. + let mut served = u32::MAX; + for bad in [ + "", + "not-an-epoch", + "6ba7b810-9dad-41d1-80b4-00c04fd430c8", + "00000000-0000-7000-8000-00000000000A", + ] { + assert_eq!( + unsafe { moq_broadcast_request_prepare(request, bad.as_ptr().cast(), bad.len(), &mut served) }, + MOQ_ERROR_INVALID_CONFIG, + "{bad:?} is not an epoch" + ); + assert_eq!(served, u32::MAX); + } + let epoch = mint_epoch(); let prepared = id(unsafe { moq_broadcast_request_prepare(request, epoch.as_ptr().cast(), epoch.len(), &mut served) }); let publication = id(moq_broadcast_prepared_publish(prepared)); @@ -6309,6 +6439,80 @@ fn dial_pinned(url: &str, fingerprint: &str, consume: u32, user_data: *mut c_voi }) } +/// Received routes expose each traversed origin in order, rather than an empty local path. +#[test] +fn announce_route_hops_cross_a_relay_session() { + let source = id(moq_origin_create()); + let relay = id(moq_origin_create()); + let sink = id(moq_origin_create()); + let hops = { + let state = State::lock(); + [source, relay].map(|origin| state.origin.get(Id::try_from(origin).unwrap()).unwrap().hop().id()) + }; + let server_cb = Callback::new(); + let (server, addr, fingerprint) = listen(&server_cb); + let url = format!("https://{addr}/"); + + let upstream_client_cb = States::new(); + let upstream_client = dial_pinned(&url, &fingerprint, relay, upstream_client_cb.ptr); + let upstream_cb = States::new(); + let upstream = id(unsafe { + moq_session_request_accept(id(server_cb.recv()), source, 0, Some(state_callback), upstream_cb.ptr) + }); + let downstream_client_cb = States::new(); + let downstream_client = dial_pinned(&url, &fingerprint, sink, downstream_client_cb.ptr); + let downstream_cb = States::new(); + let downstream = id(unsafe { + moq_session_request_accept(id(server_cb.recv()), relay, 0, Some(state_callback), downstream_cb.ptr) + }); + for cb in [&upstream_client_cb, &upstream_cb, &downstream_client_cb, &downstream_cb] { + assert_eq!(cb.recv().phase, moq_connection_phase::MOQ_CONNECTION_PHASE_CONNECTED); + } + + let announced_cb = Callback::new(); + let task = id(unsafe { moq_origin_announced(sink, std::ptr::null(), Some(channel_callback), announced_cb.ptr) }); + let (publication, broadcast) = create_broadcast(source, b"relayed"); + let route = moq_announce_route { + cost: 7, + epoch: std::ptr::null(), + epoch_len: 0, + }; + assert_eq!(unsafe { moq_publication_announce(publication, &route) }, 0); + let (announced, info) = announced_cb.recv_route(); + assert_eq!(info.kind, moq_announce_kind::MOQ_ANNOUNCE_KIND_START); + assert_eq!( + borrowed_string(info.prefix, info.prefix_len).as_deref(), + Some("relayed") + ); + assert_eq!(info.route.hops_len, hops.len()); + assert_eq!( + unsafe { std::slice::from_raw_parts(info.route.hops, info.route.hops_len) }, + hops + ); + assert_eq!(info.route.cost, 9, "each session adds its default cost of one"); + assert_eq!(route_epoch(&info.route), None); + assert_eq!(moq_origin_announced_free(announced), 0); + + assert_eq!(moq_origin_announced_cancel(task), 0); + assert_eq!(announced_cb.recv_announce_terminal(), 0); + for (session, cb) in [ + (downstream, &downstream_cb), + (downstream_client, &downstream_client_cb), + (upstream, &upstream_cb), + (upstream_client, &upstream_client_cb), + ] { + assert_eq!(moq_session_close(session), 0); + cb.recv_terminal(); + } + assert_eq!(moq_server_close(server), 0); + assert_eq!(server_cb.recv_terminal(), 0); + assert_eq!(moq_publication_free(publication), 0); + assert_eq!(moq_publish_close(broadcast), 0); + for origin in [source, relay, sink] { + assert_eq!(moq_origin_close(origin), 0); + } +} + #[test] fn server_accepts_a_session() { let served = id(moq_origin_create()); From 38969e5fdc365a102cc0fbd7bbddc0a436a94915 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 29 Oct 2026 09:17:33 -0700 Subject: [PATCH 3/8] chore(quest): preserve C API validation blockers Co-Authored-By: GPT-6.1 Sol --- quest/m1/c/README.md | 1 + quest/m1/c/api-gaps.md | 44 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 45 insertions(+) create mode 100644 quest/m1/c/api-gaps.md diff --git a/quest/m1/c/README.md b/quest/m1/c/README.md index af4cbf2d370..bd8de26d5df 100644 --- a/quest/m1/c/README.md +++ b/quest/m1/c/README.md @@ -31,3 +31,4 @@ Public API: moq-c gains each m1 binding feature. Wire: none. - [moq-c decode start](/quest/m1/c/decode-start.md) - a moq-c decoder can read a finished track from its start - [JSON windows](/quest/m1/c/json-window.md) - moq-c publishes and reads moq-json windows, as moq-ffi does +- [API gaps](/quest/m1/c/api-gaps.md) - one malformed-epoch error code, an audio enabled query, and a relay hops test diff --git a/quest/m1/c/api-gaps.md b/quest/m1/c/api-gaps.md new file mode 100644 index 00000000000..253d5ea1aaa --- /dev/null +++ b/quest/m1/c/api-gaps.md @@ -0,0 +1,44 @@ +# [S] moq-c closes its small API gaps + +## Goal + +moq-c reports a malformed epoch the same way everywhere, lets a C consumer see +that audio is disabled as it can for video, and has a test of the hops on a +route received through a relay. + +## Plan + +Found 2026-10-28 by [moq-dev/moq#7151](https://github.com/moq-dev/moq/pull/7151) +and [moq-dev/moq#7156](https://github.com/moq-dev/moq/pull/7156). + +Decided 2026-10-28 (maintainer): one PR for all three. moq-c already breaks +at this cut (0.6 to 0.7), so the error-code change rides that break. +Use `MOQ_ERROR_INVALID_CONFIG` for malformed epochs in both +`moq_broadcast_request_prepare` and `moq_publication_announce`, add the audio +enabled query, and test received relay hops. + +Implementation is checkpointed in [moq-dev/moq#7246](https://github.com/moq-dev/moq/pull/7246): +`moq_consume_audio_enabled` mirrors the video query, epoch validation uses the +settled error code, and tests cover snapshot enablement, a consumer opened +from a disabled snapshot resuming, and ordered hops over two C sessions. +The README and C guide are updated; a C audio fixture calls the new query. +The PR Impact records the error-code migration and new query. + +Remaining work is validation before marking ready and deleting this quest: +run the moq-c tests, compile and run the C fixtures against the generated +`moq.h` and `libmoq.a`, and pass the local CI gate. Resolve any relevant +failures and review findings. + +Reproduced 2026-10-29: a malformed request epoch returned -15 instead of -40, +and compiling the C fixture against the original header failed because the +audio query was undeclared. Formatting, quest validation, and the gate's +other static checks passed. `just ci` failed before Rust validation because +mbx could not launch Cargo (`Argument list too long`); the CI tooling test +failed through the same wrapper. Merely prepending pinned Cargo still hit +mbx because `BASH_ENV` reinjected it in child shells. Omitting that hook +verified the pinned Cargo path, but its validation run remained waiting at +`quest gate` for host capacity and was stopped with exit 143 before tests +started. No successful run of the new tests or C fixture is claimed. + +Public API: moq-c gains an audio enabled query and changes one error code. +Wire: none. From 8dd92528cc8e8c758e4e1dbddbedf0b2dcc4369d Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 31 Oct 2026 12:27:54 -0700 Subject: [PATCH 4/8] test(c): relay hops through a server-accepted relay; finish the quest A client session asks its peer only about what a local reader watches, and a session forwarding the relay's origin downstream is not one, so the relay ingest is now a server-accepted session, as on a relay server. Deletes quest/m1/c/api-gaps.md now that validation passes. Co-Authored-By: Claude Opus 5.5 --- quest/m1/c/README.md | 1 - quest/m1/c/api-gaps.md | 44 ------------------------------------------ rs/moq-c/src/test.rs | 20 ++++++++++++------- 3 files changed, 13 insertions(+), 52 deletions(-) delete mode 100644 quest/m1/c/api-gaps.md diff --git a/quest/m1/c/README.md b/quest/m1/c/README.md index 8c65a7e221e..5242966ccda 100644 --- a/quest/m1/c/README.md +++ b/quest/m1/c/README.md @@ -29,5 +29,4 @@ Public API: moq-c gains each m1 binding feature. Wire: none. ## Required -- [API gaps](/quest/m1/c/api-gaps.md) - one malformed-epoch error code, an audio enabled query, and a relay hops test - [Every consumer cancels while pending](/quest/m1/c/consumer-cancel.md) - catalog, raw, datagram, and media consumers end cleanly on cancel before their subscription is accepted diff --git a/quest/m1/c/api-gaps.md b/quest/m1/c/api-gaps.md deleted file mode 100644 index 253d5ea1aaa..00000000000 --- a/quest/m1/c/api-gaps.md +++ /dev/null @@ -1,44 +0,0 @@ -# [S] moq-c closes its small API gaps - -## Goal - -moq-c reports a malformed epoch the same way everywhere, lets a C consumer see -that audio is disabled as it can for video, and has a test of the hops on a -route received through a relay. - -## Plan - -Found 2026-10-28 by [moq-dev/moq#7151](https://github.com/moq-dev/moq/pull/7151) -and [moq-dev/moq#7156](https://github.com/moq-dev/moq/pull/7156). - -Decided 2026-10-28 (maintainer): one PR for all three. moq-c already breaks -at this cut (0.6 to 0.7), so the error-code change rides that break. -Use `MOQ_ERROR_INVALID_CONFIG` for malformed epochs in both -`moq_broadcast_request_prepare` and `moq_publication_announce`, add the audio -enabled query, and test received relay hops. - -Implementation is checkpointed in [moq-dev/moq#7246](https://github.com/moq-dev/moq/pull/7246): -`moq_consume_audio_enabled` mirrors the video query, epoch validation uses the -settled error code, and tests cover snapshot enablement, a consumer opened -from a disabled snapshot resuming, and ordered hops over two C sessions. -The README and C guide are updated; a C audio fixture calls the new query. -The PR Impact records the error-code migration and new query. - -Remaining work is validation before marking ready and deleting this quest: -run the moq-c tests, compile and run the C fixtures against the generated -`moq.h` and `libmoq.a`, and pass the local CI gate. Resolve any relevant -failures and review findings. - -Reproduced 2026-10-29: a malformed request epoch returned -15 instead of -40, -and compiling the C fixture against the original header failed because the -audio query was undeclared. Formatting, quest validation, and the gate's -other static checks passed. `just ci` failed before Rust validation because -mbx could not launch Cargo (`Argument list too long`); the CI tooling test -failed through the same wrapper. Merely prepending pinned Cargo still hit -mbx because `BASH_ENV` reinjected it in child shells. Omitting that hook -verified the pinned Cargo path, but its validation run remained waiting at -`quest gate` for host capacity and was stopped with exit 143 before tests -started. No successful run of the new tests or C fixture is claimed. - -Public API: moq-c gains an audio enabled query and changes one error code. -Wire: none. diff --git a/rs/moq-c/src/test.rs b/rs/moq-c/src/test.rs index de26d7452da..44e1e2b49c6 100644 --- a/rs/moq-c/src/test.rs +++ b/rs/moq-c/src/test.rs @@ -6783,8 +6783,9 @@ fn listen(cb: &Callback) -> (u32, String, String) { (server, addr, fingerprint) } -/// Dial `url`, pinning `fingerprint`, with `consume` receiving the peer's broadcasts. -fn dial_pinned(url: &str, fingerprint: &str, consume: u32, user_data: *mut c_void) -> u32 { +/// Dial `url`, pinning `fingerprint`, announcing `publish` to the peer and with `consume` +/// receiving the peer's broadcasts. +fn dial_pinned(url: &str, fingerprint: &str, publish: u32, consume: u32, user_data: *mut c_void) -> u32 { let fingerprints = [moq_str(fingerprint)]; let mut config = client_config(); config.tls_fingerprints = fingerprints.as_ptr(); @@ -6796,7 +6797,7 @@ fn dial_pinned(url: &str, fingerprint: &str, consume: u32, user_data: *mut c_voi url.as_ptr() as *const c_char, url.len(), &config, - 0, + publish, consume, Some(state_callback), user_data, @@ -6805,6 +6806,10 @@ fn dial_pinned(url: &str, fingerprint: &str, consume: u32, user_data: *mut c_voi } /// Received routes expose each traversed origin in order, rather than an empty local path. +/// +/// The relay accepts both sessions, as a relay server does: a server asks its peer about +/// everything, while a client session asks only about what a local reader watches, which +/// a session forwarding the relay's origin downstream is not. #[test] fn announce_route_hops_cross_a_relay_session() { let source = id(moq_origin_create()); @@ -6819,13 +6824,13 @@ fn announce_route_hops_cross_a_relay_session() { let url = format!("https://{addr}/"); let upstream_client_cb = States::new(); - let upstream_client = dial_pinned(&url, &fingerprint, relay, upstream_client_cb.ptr); + let upstream_client = dial_pinned(&url, &fingerprint, source, 0, upstream_client_cb.ptr); let upstream_cb = States::new(); let upstream = id(unsafe { - moq_session_request_accept(id(server_cb.recv()), source, 0, Some(state_callback), upstream_cb.ptr) + moq_session_request_accept(id(server_cb.recv()), 0, relay, Some(state_callback), upstream_cb.ptr) }); let downstream_client_cb = States::new(); - let downstream_client = dial_pinned(&url, &fingerprint, sink, downstream_client_cb.ptr); + let downstream_client = dial_pinned(&url, &fingerprint, 0, sink, downstream_client_cb.ptr); let downstream_cb = States::new(); let downstream = id(unsafe { moq_session_request_accept(id(server_cb.recv()), relay, 0, Some(state_callback), downstream_cb.ptr) @@ -6891,6 +6896,7 @@ fn server_accepts_a_session() { let client = dial_pinned( &format!("https://{addr}/room?jwt=abc"), &fingerprint, + 0, received, client_cb.ptr, ); @@ -7002,7 +7008,7 @@ fn server_rejects_a_session() { let (server, addr, fingerprint) = listen(&server_cb); let client_cb = States::new(); - let client = dial_pinned(&format!("https://{addr}/"), &fingerprint, 0, client_cb.ptr); + let client = dial_pinned(&format!("https://{addr}/"), &fingerprint, 0, 0, client_cb.ptr); let request = id(server_cb.recv()); let mut path = moq_str("x"); From d641d6b4bcd30a9f9f7600ec4e9e90c8aca06512 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 31 Oct 2026 12:31:44 -0700 Subject: [PATCH 5/8] fix(c)!: malformed epochs fail request and follow with INVALID_CONFIG moq_origin_request and moq_origin_follow still refused malformed epoch text as MOQ_ERROR_INVALID_CODE. Every epoch-taking API now parses through one helper that refuses it as MOQ_ERROR_INVALID_CONFIG. Co-Authored-By: Claude Opus 5.5 --- rs/moq-c/src/api.rs | 25 ++++++++++++++----------- rs/moq-c/src/test.rs | 7 ++++++- 2 files changed, 20 insertions(+), 12 deletions(-) diff --git a/rs/moq-c/src/api.rs b/rs/moq-c/src/api.rs index 4143b8106b6..861d59c7fc4 100644 --- a/rs/moq-c/src/api.rs +++ b/rs/moq-c/src/api.rs @@ -911,10 +911,7 @@ unsafe fn parse_announce_route(route: *const moq_announce_route) -> Result i32 { ffi::enter(move || { let request = ffi::parse_id(request)?; - let epoch = unsafe { ffi::parse_str(epoch, epoch_len)? }; - let epoch = epoch - .parse() - .map_err(|_| Error::InvalidConfig(format!("epoch {epoch:?} is not canonical UUIDv7 text")))?; + let epoch = epoch_from_str(unsafe { ffi::parse_str(epoch, epoch_len)? })?; let broadcast_out = unsafe { broadcast.as_mut() }.ok_or(Error::InvalidPointer)?; let mut state = State::lock(); let (pending, driver) = state.origin.broadcast_request_take(request)?; @@ -2271,7 +2265,7 @@ pub extern "C" fn moq_origin_announced_cancel(announced: u32) -> i32 { /// announced, like a remote one. /// /// `epoch` is the UUIDv7 text of the only publisher instance to follow, or NULL (or empty) to -/// follow every instance. A pinned follow never delivers another instance taking over, and +/// follow every instance. Malformed epoch text returns `MOQ_ERROR_INVALID_CONFIG`. A pinned follow never delivers another instance taking over, and /// delivers its own instance again if it returns after an end. /// /// `on_broadcast` is invoked with a positive broadcast handle once announced, and again with a @@ -2334,6 +2328,7 @@ pub extern "C" fn moq_origin_follow_cancel(task: u32) -> i32 { /// /// `epoch` is the UUIDv7 text of the only publisher instance to accept, or NULL (or empty) for /// any instance. A request pinned to an instance that does not serve the path is unroutable. +/// Malformed epoch text returns `MOQ_ERROR_INVALID_CONFIG`. /// /// `on_broadcast` is invoked with a positive broadcast handle once served, then exactly once more /// with a terminal code: `0` (finished, including after [moq_origin_request_cancel]) or a negative @@ -2386,10 +2381,18 @@ pub extern "C" fn moq_origin_request_cancel(task: u32) -> i32 { /// - `epoch` may be NULL, or must point at `epoch_len` readable bytes. unsafe fn parse_epoch(epoch: *const c_char, epoch_len: usize) -> Result, Error> { unsafe { ffi::parse_str_optional(epoch, epoch_len)? } - .map(|epoch| epoch.parse().map_err(|_| Error::InvalidCode)) + .map(epoch_from_str) .transpose() } +/// Parse canonical UUIDv7 epoch text, refusing anything else as `MOQ_ERROR_INVALID_CONFIG` +/// at every API that takes an epoch. +fn epoch_from_str(epoch: &str) -> Result { + epoch + .parse() + .map_err(|_| Error::InvalidConfig(format!("epoch {epoch:?} is not canonical UUIDv7 text"))) +} + /// Close an origin and clean up its resources. /// /// The origin keeps running while a broadcast published on it or a @@ -2409,7 +2412,7 @@ pub extern "C" fn moq_origin_close(origin: u32) -> i32 { /// Announcing again re-prices the route in place, or restarts it under a new epoch. A /// NULL `route` uses the default (cost 0, no epoch). Until announced, the broadcast is /// invisible and unroutable for local consumers and peers alike. Fails once the -/// broadcast closed, or when `epoch` is not UUIDv7 text. +/// broadcast closed, or with `MOQ_ERROR_INVALID_CONFIG` when `epoch` is not UUIDv7 text. /// /// Returns a zero on success, or a negative code on failure. /// diff --git a/rs/moq-c/src/test.rs b/rs/moq-c/src/test.rs index 44e1e2b49c6..50ee9a8d978 100644 --- a/rs/moq-c/src/test.rs +++ b/rs/moq-c/src/test.rs @@ -4553,7 +4553,12 @@ fn an_epoch_pins_request_and_follow() { &cb, )); assert!(cb.recv() < 0, "another instance resolved"); - assert!(resolve_pinned(moq_origin_follow, origin, "not-an-epoch", &Callback::new()) < 0); + for resolve in [moq_origin_request, moq_origin_follow] { + assert_eq!( + resolve_pinned(resolve, origin, "not-an-epoch", &Callback::new()), + MOQ_ERROR_INVALID_CONFIG + ); + } // Another instance takes over before the follow starts. An unpinned request resolves it and // holds the answer, so a follower resolving it joins that answer within its first pass. From de59b274496f44d0e48231fa345b02254c2663fa Mon Sep 17 00:00:00 2001 From: quest fixer Date: Sun, 1 Nov 2026 00:33:03 -0700 Subject: [PATCH 6/8] docs: remove link to completed C API gaps quest --- quest/m1/api-audit/route/handle.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/quest/m1/api-audit/route/handle.md b/quest/m1/api-audit/route/handle.md index 8f3fc272d48..6dae42ce085 100644 --- a/quest/m1/api-audit/route/handle.md +++ b/quest/m1/api-audit/route/handle.md @@ -90,7 +90,7 @@ JS and the bindings identical. `moq_broadcast_prepared_*`, `moq_publication_*` and `moq_mint_epoch`. - The py, kt, swift, dart and go wrappers. - [moq-c's API gaps](/quest/m1/c/api-gaps.md) error-code fix applies to + moq-c's API gaps error-code fix applies to whichever functions remain. - **Callers.** Migrate every caller: about 25 crates use `create_broadcast` or `publish`, about 19 set an epoch, plus `@moq/publish`, moq-boy, carla From 196bbc587eff81ef0634999aafeb3d2909e5f0b7 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 1 Nov 2026 15:38:27 -0800 Subject: [PATCH 7/8] test(c): pass the audio disabled test's delay as a moq_delay Main's #7311 made moq_consume_audio take a moq_delay pointer; the merged test still passed a bare microsecond count and failed to compile. Co-Authored-By: Claude Opus 5.5 --- rs/moq-c/src/test.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rs/moq-c/src/test.rs b/rs/moq-c/src/test.rs index 137f998330c..cedde4d7dc2 100644 --- a/rs/moq-c/src/test.rs +++ b/rs/moq-c/src/test.rs @@ -1015,7 +1015,7 @@ fn audio_enabled_snapshots_preserve_a_held_consumer() { // A held rendition may be opened from a disabled snapshot, then re-enabled without resubscribing. let frames = Callback::new(); - let track = id(unsafe { moq_consume_audio(disabled, 0, 10_000_000, Some(channel_callback), frames.ptr) }); + let track = id(unsafe { moq_consume_audio(disabled, 0, &TEN_SECONDS, Some(channel_callback), frames.ptr) }); set_enabled(true); let resumed = id(catalogs.recv()); assert_eq!( From 8b72ab30bc31384a4212a02b1e24cfe5eb18bc1a Mon Sep 17 00:00:00 2001 From: quest fixer Date: Sun, 1 Nov 2026 19:14:20 -0800 Subject: [PATCH 8/8] test(c): update fixtures for timestamp and epoch APIs --- rs/moq-c/c-tests/timestamps.c | 2 +- rs/moq-c/src/test.rs | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/rs/moq-c/c-tests/timestamps.c b/rs/moq-c/c-tests/timestamps.c index 9cc7185e86b..e25f5ff598f 100644 --- a/rs/moq-c/c-tests/timestamps.c +++ b/rs/moq-c/c-tests/timestamps.c @@ -102,7 +102,7 @@ int main(void) { } CHECK(moq_publish_track_frame((uint32_t)track, payload, sizeof(payload), NULL) == MOQ_ERROR_MOQ); - CHECK(moq_origin_request((uint32_t)origin, path, strlen(path), on_broadcast, &c) > 0); + CHECK(moq_origin_request((uint32_t)origin, path, strlen(path), NULL, 0, on_broadcast, &c) > 0); WAIT_FOR(&c, c.broadcast); int32_t frames = moq_consume_track((uint32_t)c.broadcast, "ticks", 5, NULL, on_frame, &c); CHECK(frames > 0); diff --git a/rs/moq-c/src/test.rs b/rs/moq-c/src/test.rs index 988264e3d7c..64127f96dde 100644 --- a/rs/moq-c/src/test.rs +++ b/rs/moq-c/src/test.rs @@ -1043,7 +1043,7 @@ fn audio_enabled_snapshots_preserve_a_held_consumer() { assert!(!unsafe { enabled.assume_init() }); let payload = b"resumed-audio"; assert_eq!( - unsafe { moq_publish_media_frame(media, payload.as_ptr(), payload.len(), 0) }, + unsafe { moq_publish_media_frame(media, payload.as_ptr(), payload.len(), micros(0)) }, 0 ); let read = id(frames.recv());