From 31ca9f418c1e85256b9073e14762136d517efcdb Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 02:02:39 -0800 Subject: [PATCH 1/4] chore(quest): claim quest/m2/c-catalog-timing.md Quest-Claim: f5ba41cb07952adc From a3ea100777c39b68e855e081e8b61c99ccfdebb4 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 02:50:12 -0800 Subject: [PATCH 2/4] feat(moq-c)!: catalog snapshots carry their timestamp and the reader's playout delay moq_consume_catalog takes delay_us and reads through hang::catalog::Consumer, so a C player behind the live edge receives in order every update it may still need. moq_consume_catalog_timestamp reports the media timestamp each snapshot takes effect at. Co-Authored-By: Claude Opus 5.5 --- doc/lib/c/index.md | 1 + nix/Cargo.nix | 1 + quest/m0/test-flakes-3/js-announce-reset.md | 23 +++++ quest/m2/c-catalog-timing.md | 29 ------ rs/moq-c/Cargo.toml | 2 +- rs/moq-c/README.md | 3 +- rs/moq-c/c-tests/audio-decode-output.c | 2 +- rs/moq-c/c-tests/decode-output.c | 2 +- rs/moq-c/src/api.rs | 33 +++++- rs/moq-c/src/consume.rs | 22 +++- rs/moq-c/src/test.rs | 109 +++++++++++++++----- test/interop/clients/c/subscribe.c | 2 +- 12 files changed, 165 insertions(+), 64 deletions(-) create mode 100644 quest/m0/test-flakes-3/js-announce-reset.md delete mode 100644 quest/m2/c-catalog-timing.md diff --git a/doc/lib/c/index.md b/doc/lib/c/index.md index 90185eb6d29..81ea107bbb4 100644 --- a/doc/lib/c/index.md +++ b/doc/lib/c/index.md @@ -129,6 +129,7 @@ inside. The header is the reference: each function carries a doc comment. - **Ending cleanly.** When the input ends, finish every track, then call `moq_publish_catalog_finish()` to finish the catalog, which ends the content. The broadcast stays announced and keeps serving the finished tracks, so a subscriber still catching up can drain them, until `moq_publish_close()` or `moq_route_free()` takes it offline. How long to keep it up is yours to decide. A track still open at the close ends with `UNROUTABLE` (an internal error over moq-transport, which has no such code), and its handle is released. Readers follow a publisher's runs by announcement, not by that error: see [identity and recovery](/concept/identity). - **Timeline breaks.** On a seek or pause, call `moq_publish_media_discontinuity`, then keep timestamps moving forward and resume video on a keyframe. - **Timestamps.** A `moq_timestamp` is exact: `value` units at `scale` units per second, so a 90 kHz tick survives a read and republish. Frames, datagrams, and JSON values point `timestamp` at theirs, valid as long as the payload. An untimed track has no scale, so there `has_scale` is false and `value` is the frame's group key (a datagram's sequence); every write takes one, with `moq_publish_group_start` naming a group's key. Stream tracks moq-c creates are timed, so their raw writes need one. Datagram tracks are separate and default to untimed; set their timescale when creating them to require timestamps. Stamp media frames and JSON writes from `moq_publish_catalog_now()`, the broadcast clock every track in the broadcast shares; media on a timeline of its own advertises the gap to the JSON tracks as catalog `delay`. JSON writes are converted to their track's milliseconds. A NULL timestamp on any write fails with `MOQ_ERROR_INVALID_POINTER`. A zero scale with `has_scale` set, or an out-of-range value, fails with `MOQ_ERROR_TIMESTAMP_OVERFLOW`. +- **Catalog timing.** Each catalog snapshot from `moq_consume_catalog` takes effect at the media timestamp `moq_consume_catalog_timestamp` fills. A zero `delay_us` delivers only the newest catalog; a player that holds each update until its media reaches that time passes its playout delay instead, and receives in order every update it may still need. - **JSON values.** `moq_consume_json_value` fills `moq_json_value` with the document and its frame's timestamp. A snapshot consumer's callback fires for each state in order, but a group superseded before it is read is skipped. - **JSON windows.** `moq_publish_json_window` publishes a sliding run of records: `moq_publish_json_window_push` appends at the back, `moq_publish_json_window_pop` drops from the front, and `moq_publish_json_window_cut` closes the open group at a natural boundary. The catalog has no window mode, so a reader names the track. `moq_consume_json_window_event` fills `moq_json_window_event` with a push (the record at `start`, in `json`), a pop of `[start, end)`, or a skip of `[start, end)` that this reader joined too late to receive. Set `checkpoint_records` to bound what each new group restates for a window you never pop. - **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. A decoder reads everything the track still holds unless a live player sets `start` to `MOQ_DECODE_START_LATEST`, which joins at the newest group and skips the cached backlog. A decoder setup refusal reports `MOQ_ERROR_UNSUPPORTED_CONFIG` on its terminal callback, so the caller can try another rendition; later peer or decode failures retain their own error codes. diff --git a/nix/Cargo.nix b/nix/Cargo.nix index d0caec0de4f..cdd23fbf720 100644 --- a/nix/Cargo.nix +++ b/nix/Cargo.nix @@ -18456,6 +18456,7 @@ rec { { name = "hang"; packageId = "hang"; + features = [ "async" ]; } { name = "kio"; diff --git a/quest/m0/test-flakes-3/js-announce-reset.md b/quest/m0/test-flakes-3/js-announce-reset.md new file mode 100644 index 00000000000..fe06e17feda --- /dev/null +++ b/quest/m0/test-flakes-3/js-announce-reset.md @@ -0,0 +1,23 @@ +# [S] js/net's reset Announce Stream test closes the session under load + +## Goal + +`js/net/src/lite/connection.test.ts`'s "a reset Announce Stream closes +moq-lite-07 with PROTOCOL_VIOLATION" passes every loaded `just check`. + +## Plan + +Found 2026-11-17 by `just check` on +[moq-dev/moq#8996](https://github.com/moq-dev/moq/pull/8996), whose change +touches no JS. Under the loaded check it hit bun's 5000 ms test timeout: the +session never closed. Run alone it passed 15 times in a row. + +A timeout, not a wrong code, means the reset went unnoticed. Trace how the +connection reads the Announce Stream when the mock transport delivers the +reset before or alongside the ANNOUNCE_REQUEST it follows: if a path drops the +reset (a read that resolves with the message and never polls again, or a reset +raced against the stream's open), that is a bug in `js/net`, fixed there with +a regression test. Only if the trace shows the close is merely slow is the fix +in the test, by the epic's rules. + +Public API: none. Wire: none. diff --git a/quest/m2/c-catalog-timing.md b/quest/m2/c-catalog-timing.md deleted file mode 100644 index c717fe6151a..00000000000 --- a/quest/m2/c-catalog-timing.md +++ /dev/null @@ -1,29 +0,0 @@ -# [S] moq-c reads each catalog's timestamp and takes a playout delay - -## Goal - -The C ABI reaches the same catalog timing the other SDKs have: a catalog -snapshot from `moq_consume_catalog` reports the media timestamp it takes -effect at, and the subscription takes the reader's playout delay, so a C -player behind the live edge reads in order every update it may still need. -Rust (`hang::catalog::Consumer::new(track, delay)`), JS -(`Catalog.watch(broadcast, { delay })`), and every moq-ffi binding -(`MoqMediaCatalogConsumer::subscribe(broadcast, delay)`, `MoqCatalog.timestamp`) -already do, from -[moq-dev/moq#8907](https://github.com/moq-dev/moq/pull/8907). - -## Plan - -- `rs/moq-c/src/consume.rs` reads through `moq_mux::catalog::hang::Consumer`, - which drops the stamp and reads only the newest catalog. Read through - `hang::catalog::Consumer::new(track, delay)` instead, as - `rs/moq-ffi/src/media.rs` does, and keep each snapshot's `at`. -- Add `moq_consume_catalog_timestamp(catalog, out)` filling a - `moq_timestamp`, and a delay argument, in the ABI's existing duration shape, - to `moq_consume_catalog`. -- Settled by the maintainer (2026-11-16, [moq-dev/moq#8907](https://github.com/moq-dev/moq/pull/8907#issuecomment-6930706614)): - change `moq_consume_catalog`'s signature in the next moq-c release (rejected: - leaving moq-c on arrival timing). -- Mirror the Rust test `a_holding_reader_reads_every_update_within_its_delay` - in `rs/moq-c/src/test.rs`, and update `doc/lib/c/index.md` and the C interop - client. diff --git a/rs/moq-c/Cargo.toml b/rs/moq-c/Cargo.toml index f5ffce6d531..150ed29a4ca 100644 --- a/rs/moq-c/Cargo.toml +++ b/rs/moq-c/Cargo.toml @@ -24,7 +24,7 @@ openh264 = ["moq-video/openh264"] [dependencies] anyhow = { workspace = true, features = ["backtrace"] } bytes = { workspace = true } -hang = { workspace = true } +hang = { workspace = true, features = ["async"] } kio = { workspace = true, features = ["async"] } # Codecs only: OBS and the other C consumers do their own device I/O. moq-audio = { workspace = true } diff --git a/rs/moq-c/README.md b/rs/moq-c/README.md index 28cfd98e022..23e60559599 100644 --- a/rs/moq-c/README.md +++ b/rs/moq-c/README.md @@ -168,7 +168,8 @@ int32_t moq_consume_closed(uint32_t broadcast, moq_status_callback on_closed, vo int32_t moq_consume_closed_cancel(uint32_t watcher); // Consuming: Catalog -int32_t moq_consume_catalog(uint32_t broadcast, moq_status_callback on_catalog, void *user_data); +int32_t moq_consume_catalog(uint32_t broadcast, uint64_t delay_us, moq_status_callback on_catalog, void *user_data); +int32_t moq_consume_catalog_timestamp(uint32_t catalog, moq_timestamp *dst); int32_t moq_consume_catalog_cancel(uint32_t catalog); 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); diff --git a/rs/moq-c/c-tests/audio-decode-output.c b/rs/moq-c/c-tests/audio-decode-output.c index 01244fecb35..58fefdbd827 100644 --- a/rs/moq-c/c-tests/audio-decode-output.c +++ b/rs/moq-c/c-tests/audio-decode-output.c @@ -123,7 +123,7 @@ int main(void) { pthread_mutex_lock(&c.mutex); wait_until(&c, &c.broadcast); pthread_mutex_unlock(&c.mutex); - int32_t catalogs = moq_consume_catalog((uint32_t)c.broadcast, on_catalog, &c); + int32_t catalogs = moq_consume_catalog((uint32_t)c.broadcast, 0, on_catalog, &c); CHECK(catalogs > 0); pthread_mutex_lock(&c.mutex); wait_until(&c, &c.catalog); diff --git a/rs/moq-c/c-tests/decode-output.c b/rs/moq-c/c-tests/decode-output.c index cf88cb29795..19ce6607c30 100644 --- a/rs/moq-c/c-tests/decode-output.c +++ b/rs/moq-c/c-tests/decode-output.c @@ -267,7 +267,7 @@ int main(void) { int32_t consume = c.broadcast; pthread_mutex_unlock(&c.mu); - int32_t catalog_sub = moq_consume_catalog((uint32_t)consume, on_catalog, &c); + int32_t catalog_sub = moq_consume_catalog((uint32_t)consume, 0, on_catalog, &c); if (catalog_sub <= 0) fail("error: moq_consume_catalog failed: %d\n", catalog_sub); pthread_mutex_lock(&c.mu); diff --git a/rs/moq-c/src/api.rs b/rs/moq-c/src/api.rs index a7f02c4d14b..a608b866391 100644 --- a/rs/moq-c/src/api.rs +++ b/rs/moq-c/src/api.rs @@ -4489,7 +4489,8 @@ pub extern "C" fn moq_publish_json_window_finish(window: u32) -> i32 { }) } -/// Create a catalog consumer for a broadcast. +/// Create a catalog consumer for a broadcast, for a reader playing `delay_us` microseconds +/// behind the live edge. /// /// `on_catalog` is invoked with a positive catalog ID for each catalog update /// (usable to query video/audio track information), then exactly once more with @@ -4498,6 +4499,12 @@ pub extern "C" fn moq_publish_json_window_finish(window: u32) -> i32 { /// touched again, so release `user_data` there. The terminal callback fires even /// after [moq_consume_catalog_cancel]. /// +/// Each update takes effect at its [moq_consume_catalog_timestamp]. A zero `delay_us` delivers +/// only the newest catalog, for a reader that applies each on arrival. A reader that holds each +/// update until its media reaches the update's timestamp passes its playout delay instead, and +/// receives in order every update it may still need: one stays deliverable until it falls +/// `delay_us` behind the live edge. +/// /// Returns a non-zero handle on success, or a negative code on failure. /// /// # Safety @@ -4505,13 +4512,35 @@ pub extern "C" fn moq_publish_json_window_finish(window: u32) -> i32 { #[unsafe(no_mangle)] pub unsafe extern "C" fn moq_consume_catalog( broadcast: u32, + delay_us: u64, on_catalog: ffi::moq_status_callback, user_data: *mut c_void, ) -> i32 { ffi::enter(move || { let broadcast = ffi::parse_id(broadcast)?; + let delay = std::time::Duration::from_micros(delay_us); let on_catalog = unsafe { ffi::OnStatus::new(user_data, on_catalog)? }; - State::lock().consume.catalog(broadcast, on_catalog) + State::lock().consume.catalog(broadcast, delay, on_catalog) + }) +} + +/// Query the media timestamp a catalog snapshot takes effect at. +/// +/// A reader holds a snapshot it receives before its media reaches this time, and applies one +/// received late, or the first it receives, at once. On a scale-less catalog track `has_scale` is +/// false and `value` is a group key with no time, so the snapshot applies on arrival. +/// +/// Returns a zero on success, or a negative code on failure. +/// +/// # Safety +/// - The caller must ensure that `dst` is a valid pointer to a [moq_timestamp] struct. +#[unsafe(no_mangle)] +pub unsafe extern "C" fn moq_consume_catalog_timestamp(catalog: u32, dst: *mut moq_timestamp) -> i32 { + ffi::enter(move || { + let catalog = ffi::parse_id(catalog)?; + let dst = unsafe { dst.as_mut() }.ok_or(Error::InvalidPointer)?; + *dst = State::lock().consume.catalog_timestamp(catalog)?; + Ok(()) }) } diff --git a/rs/moq-c/src/consume.rs b/rs/moq-c/src/consume.rs index 8960779052b..4df7971f972 100644 --- a/rs/moq-c/src/consume.rs +++ b/rs/moq-c/src/consume.rs @@ -33,6 +33,9 @@ struct ConsumeCatalog { // into `moq_catalog_section_*` instead of being dropped on parse. catalog: moq_mux::catalog::hang::Catalog, + /// The media timestamp this snapshot takes effect at. + timestamp: moq_timestamp, + /// We need to store the codec information on the heap unfortunately. audio_codec: Vec, video_codec: Vec, @@ -369,7 +372,8 @@ impl Consume { self.closed_task.close(task, Error::NotFound) } - pub fn catalog(&mut self, broadcast: Id, on_catalog: OnStatus) -> Result { + /// Read a broadcast's catalog updates for a reader playing `delay` behind the live edge. + pub fn catalog(&mut self, broadcast: Id, delay: Duration, on_catalog: OnStatus) -> Result { let ConsumeBroadcast { broadcast, origin } = self.broadcast.get(broadcast).ok_or(Error::BroadcastNotFound)?.clone(); @@ -384,7 +388,8 @@ impl Consume { driver .watch(async move { // The consumer subscribes itself at catalog priority. - let catalog = broadcast.track(hang::catalog::Catalog::DEFAULT_NAME)?.into(); + let track = broadcast.track(hang::catalog::Catalog::DEFAULT_NAME)?; + let catalog = hang::catalog::Consumer::new(track, delay); Self::run_catalog(on_catalog, broadcast.clone(), origin, catalog, close).await }) .await @@ -396,14 +401,14 @@ impl Consume { callback: OnStatus, broadcast: moq_net::broadcast::Consumer, origin: Option, - mut catalog: moq_mux::catalog::hang::Consumer, + mut catalog: hang::catalog::Consumer, mut close: oneshot::Receiver<()>, ) -> Result<(), Error> { loop { // `biased` so a pending close always wins over a ready update: a hot // stream must not be able to starve the close signal, and we must not // deliver another update once close has been requested. - let update = tokio::select! { + let moq_json::Timed { value: update, at } = tokio::select! { biased; _ = &mut close => return Ok(()), next = catalog.next() => match next? { @@ -452,6 +457,7 @@ impl Consume { broadcast: broadcast.clone(), origin: origin.clone(), catalog: update, + timestamp: at.into(), audio_codec, video_codec, audio_ref, @@ -465,6 +471,11 @@ impl Consume { } } + /// The media timestamp a catalog snapshot takes effect at. + pub fn catalog_timestamp(&self, catalog: Id) -> Result { + Ok(self.catalog.get(catalog).ok_or(Error::CatalogNotFound)?.timestamp) + } + pub fn video_config(&mut self, catalog: Id, index: usize, dst: &mut moq_video_config) -> Result<(), Error> { let consume = self.catalog.get(catalog).ok_or(Error::CatalogNotFound)?; @@ -1399,6 +1410,7 @@ mod supervision_tests { driver: driver.clone(), }), catalog, + timestamp: moq_timestamp::default(), audio_codec: Vec::new(), video_codec: Vec::new(), audio_ref: Vec::new(), @@ -1435,6 +1447,7 @@ mod rendition_tests { broadcast: broadcast.consume(), origin: None, catalog, + timestamp: moq_timestamp::default(), audio_codec: Vec::new(), video_codec: Vec::new(), audio_ref: Vec::new(), @@ -1583,6 +1596,7 @@ mod tests { broadcast: broadcast.consume(), origin: None, catalog, + timestamp: moq_timestamp::default(), audio_codec: Vec::new(), video_codec: Vec::new(), audio_ref: Vec::new(), diff --git a/rs/moq-c/src/test.rs b/rs/moq-c/src/test.rs index 45b44dcae47..edf5dceb729 100644 --- a/rs/moq-c/src/test.rs +++ b/rs/moq-c/src/test.rs @@ -741,7 +741,7 @@ fn publish_media_labels_config_without_naming_track() { let consume = request_broadcast(origin, path); let catalog_cb = Callback::new(); - let catalog_task = id(unsafe { moq_consume_catalog(consume, Some(channel_callback), catalog_cb.ptr) }); + let catalog_task = id(unsafe { moq_consume_catalog(consume, 0, Some(channel_callback), catalog_cb.ptr) }); let catalog_id1 = id(catalog_cb.recv()); let mut audio_cfg = moq_audio_config { @@ -1118,7 +1118,7 @@ fn audio_enabled_follows_each_snapshot() { )); 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 catalog_task = id(unsafe { moq_consume_catalog(consume, 0, Some(channel_callback), catalogs.ptr) }); let initial = id(catalogs.recv()); let mut enabled = std::mem::MaybeUninit::::uninit(); assert_eq!( @@ -1332,7 +1332,7 @@ fn publish_catalog_roundtrip() { // Consume the broadcast to verify the catalog round-trips. let consume = request_broadcast(origin, path); let catalog_cb = Callback::new(); - let catalog_task = id(unsafe { moq_consume_catalog(consume, Some(channel_callback), catalog_cb.ptr) }); + let catalog_task = id(unsafe { moq_consume_catalog(consume, 0, Some(channel_callback), catalog_cb.ptr) }); let catalog_id = id(catalog_cb.recv()); // The video rendition we authored comes back through the consume API. @@ -1516,7 +1516,7 @@ fn a_half_specified_coded_size_round_trips() { let consume = request_broadcast(origin, path); let catalog_cb = Callback::new(); - let catalog_task = id(unsafe { moq_consume_catalog(consume, Some(channel_callback), catalog_cb.ptr) }); + let catalog_task = id(unsafe { moq_consume_catalog(consume, 0, Some(channel_callback), catalog_cb.ptr) }); let catalog = id(catalog_cb.recv()); let mut read = moq_video_config { @@ -1555,7 +1555,7 @@ fn a_half_specified_coded_size_round_trips() { let forwarded = request_broadcast(origin, b"half-coded-size-forwarded"); let forwarded_cb = Callback::new(); - let forwarded_task = id(unsafe { moq_consume_catalog(forwarded, Some(channel_callback), forwarded_cb.ptr) }); + let forwarded_task = id(unsafe { moq_consume_catalog(forwarded, 0, Some(channel_callback), forwarded_cb.ptr) }); let forwarded_catalog = id(forwarded_cb.recv()); assert_eq!(unsafe { moq_consume_video_config(forwarded_catalog, 0, &mut read) }, 0); assert_eq!(read.preference, -1); @@ -1615,7 +1615,7 @@ fn raw_loc_video_uses_the_declared_catalog_container() { let consume = request_broadcast(origin, path); let catalog_cb = Callback::new(); - let catalog_task = id(unsafe { moq_consume_catalog(consume, Some(channel_callback), catalog_cb.ptr) }); + let catalog_task = id(unsafe { moq_consume_catalog(consume, 0, Some(channel_callback), catalog_cb.ptr) }); let catalog = id(catalog_cb.recv()); // The declaration survives the round trip, so a consumer knows to parse LOC. @@ -1730,7 +1730,7 @@ fn cmaf_catalog_container_carries_its_init_segment() { let consume = request_broadcast(origin, path); let catalog_cb = Callback::new(); - let catalog_task = id(unsafe { moq_consume_catalog(consume, Some(channel_callback), catalog_cb.ptr) }); + let catalog_task = id(unsafe { moq_consume_catalog(consume, 0, Some(channel_callback), catalog_cb.ptr) }); let catalog = id(catalog_cb.recv()); let mut audio_cfg = moq_audio_config { @@ -1913,7 +1913,7 @@ fn catalog_section_roundtrip() { // Consume to verify the sections survive the wire. let consume = request_broadcast(origin, path); let catalog_cb = Callback::new(); - let catalog_task = id(unsafe { moq_consume_catalog(consume, Some(channel_callback), catalog_cb.ptr) }); + let catalog_task = id(unsafe { moq_consume_catalog(consume, 0, Some(channel_callback), catalog_cb.ptr) }); let catalog_id = id(catalog_cb.recv()); // Both sections come back; iterate by index to find each by name. @@ -3590,7 +3590,7 @@ fn catalog_cancel_while_subscribing() { let consume = i32::from(State::lock().consume.start(broadcast.consume(), None).unwrap()) as u32; let cb = Callback::new(); - let catalog = id(unsafe { moq_consume_catalog(consume, Some(channel_callback), cb.ptr) }); + let catalog = id(unsafe { moq_consume_catalog(consume, 0, Some(channel_callback), cb.ptr) }); let _unanswered = crate::ffi::RUNTIME.block_on(requests.requested_track()).unwrap(); assert_eq!(moq_consume_catalog_cancel(catalog), 0); @@ -3598,6 +3598,67 @@ fn catalog_cancel_while_subscribing() { assert_eq!(moq_consume_close(consume), 0); } +/// Updates that arrive together reach a holding reader in order while it may still play them, +/// each with its timestamp; an arrival reader takes only the newest. +#[test] +fn a_holding_reader_reads_every_update_within_its_delay() { + // A reader `delay` behind the live edge (3s) plays from `3000 - delay`, so it needs the update + // in effect there and every later one. + for (delay_ms, expected) in [ + (0, vec![3_000]), + (999, vec![2_000, 3_000]), + (1_001, vec![1_000, 2_000, 3_000]), + ] { + // A raw broadcast, since a moq-c one stamps its own catalog from its clock. + let broadcast = moq_net::broadcast::Info::new().produce(); + let track = broadcast + .create_track( + hang::catalog::Catalog::DEFAULT_NAME, + hang::catalog::Catalog::default_track_info(), + ) + .unwrap(); + for ms in [1_000, 2_000, 3_000] { + let at = moq_net::Timestamp::from_millis(ms).unwrap(); + let mut group = track.append_group(at).unwrap(); + group.write_frame(at, format!(r#"{{"app":{ms}}}"#)).unwrap(); + group.finish().unwrap(); + } + // Kept alive, so the reader subscribing later still finds the finished track. + let _finished = track.finish().unwrap(); + let consume = i32::from(State::lock().consume.start(broadcast.consume(), None).unwrap()) as u32; + + let cb = Callback::new(); + id(unsafe { moq_consume_catalog(consume, delay_ms * 1_000, Some(channel_callback), cb.ptr) }); + let mut read = Vec::new(); + loop { + let code = cb.recv(); + if code <= 0 { + assert_eq!(code, 0, "the finished track ends cleanly"); + break; + } + let snapshot = code as u32; + let mut at = moq_timestamp::default(); + assert_eq!(unsafe { moq_consume_catalog_timestamp(snapshot, &mut at) }, 0); + assert_eq!(at.scale, 1_000); + assert!(at.has_scale); + let name = "app"; + let mut section: moq_string = unsafe { std::mem::zeroed() }; + assert_eq!( + unsafe { moq_consume_catalog_section(snapshot, name.as_ptr().cast(), name.len(), &mut section) }, + 0 + ); + assert_eq!( + borrowed_string(section.data, section.len).unwrap(), + at.value.to_string() + ); + assert_eq!(moq_consume_catalog_free(snapshot), 0); + read.push(at.value); + } + assert_eq!(read, expected, "a {delay_ms}ms delay"); + assert_eq!(moq_consume_close(consume), 0); + } +} + #[test] fn media_consumers_cancel_while_subscribing() { let origin = id(moq_origin_create()); @@ -3656,7 +3717,7 @@ fn media_consumers_cancel_while_subscribing() { let dynamic = id(unsafe { moq_publish_requests(broadcast, Some(channel_callback), request_cb.ptr) }); let consume = consume_local(broadcast); let catalog_cb = Callback::new(); - let catalog_task = id(unsafe { moq_consume_catalog(consume, Some(channel_callback), catalog_cb.ptr) }); + let catalog_task = id(unsafe { moq_consume_catalog(consume, 0, Some(channel_callback), catalog_cb.ptr) }); let catalog = id(catalog_cb.recv()); type Media = unsafe extern "C" fn(u32, u32, *const moq_delay, ffi::moq_status_callback, *mut c_void) -> i32; @@ -3846,7 +3907,7 @@ fn double_close_all_resource_types() { let consume = request_broadcast(origin, path); let catalog_cb = Callback::new(); - let catalog_task = id(unsafe { moq_consume_catalog(consume, Some(channel_callback), catalog_cb.ptr) }); + let catalog_task = id(unsafe { moq_consume_catalog(consume, 0, Some(channel_callback), catalog_cb.ptr) }); let catalog_id = id(catalog_cb.recv()); @@ -5122,7 +5183,7 @@ fn local_publish_consume() { let consume = request_broadcast(origin, path); let catalog_cb = Callback::new(); - let catalog_task = id(unsafe { moq_consume_catalog(consume, Some(channel_callback), catalog_cb.ptr) }); + let catalog_task = id(unsafe { moq_consume_catalog(consume, 0, Some(channel_callback), catalog_cb.ptr) }); let catalog_id = id(catalog_cb.recv()); @@ -5254,7 +5315,7 @@ fn follow_local() { // The delivered handle behaves like one from moq_origin_request. let catalog_cb = Callback::new(); - let catalog_task = id(unsafe { moq_consume_catalog(consume, Some(channel_callback), catalog_cb.ptr) }); + let catalog_task = id(unsafe { moq_consume_catalog(consume, 0, Some(channel_callback), catalog_cb.ptr) }); let catalog_id = id(catalog_cb.recv()); let mut audio_cfg = moq_audio_config { @@ -5366,7 +5427,7 @@ fn consume_audio_follows_a_sibling_broadcast_reference() { let consume = request_broadcast(origin, b"a/pub"); let catalog_cb = Callback::new(); - let catalog_task = id(unsafe { moq_consume_catalog(consume, Some(channel_callback), catalog_cb.ptr) }); + let catalog_task = id(unsafe { moq_consume_catalog(consume, 0, Some(channel_callback), catalog_cb.ptr) }); let catalog_id = id(catalog_cb.recv()); let frame_cb = Callback::new(); @@ -5415,7 +5476,7 @@ fn consume_audio_refuses_a_sibling_of_another_instance() { let consume = request_broadcast(origin, b"a/pub"); let catalog_cb = Callback::new(); - let catalog_task = id(unsafe { moq_consume_catalog(consume, Some(channel_callback), catalog_cb.ptr) }); + let catalog_task = id(unsafe { moq_consume_catalog(consume, 0, Some(channel_callback), catalog_cb.ptr) }); let catalog_id = id(catalog_cb.recv()); let frame_cb = Callback::new(); @@ -5459,7 +5520,7 @@ fn decoders_cancel_while_resolving_a_sibling() { let consume = request_broadcast(origin, b"r/pub"); let catalog_cb = Callback::new(); - let catalog_task = id(unsafe { moq_consume_catalog(consume, Some(channel_callback), catalog_cb.ptr) }); + let catalog_task = id(unsafe { moq_consume_catalog(consume, 0, Some(channel_callback), catalog_cb.ptr) }); let catalog_id = id(catalog_cb.recv()); let audio_output = moq_audio_decoder_output { @@ -5552,7 +5613,7 @@ fn decode_audio_follows_a_sibling_broadcast_reference() { let consume = request_broadcast(origin, b"d/pub"); let catalog_cb = Callback::new(); - let catalog_task = id(unsafe { moq_consume_catalog(consume, Some(channel_callback), catalog_cb.ptr) }); + let catalog_task = id(unsafe { moq_consume_catalog(consume, 0, Some(channel_callback), catalog_cb.ptr) }); let catalog_id = id(catalog_cb.recv()); let decoded = moq_audio_decoder_output { format: moq_audio_sample_format::MOQ_AUDIO_SAMPLE_FORMAT_F32 as u32, @@ -5912,7 +5973,7 @@ fn video_publish_consume() { let consume = request_broadcast(origin, path); let catalog_cb = Callback::new(); - let catalog_task = id(unsafe { moq_consume_catalog(consume, Some(channel_callback), catalog_cb.ptr) }); + let catalog_task = id(unsafe { moq_consume_catalog(consume, 0, Some(channel_callback), catalog_cb.ptr) }); let catalog_id = id(catalog_cb.recv()); @@ -6174,7 +6235,7 @@ fn audio_raw_decode_reads_the_encoder_end() { let consume = request_broadcast(origin, path); let catalog_cb = Callback::new(); - let catalog_task = id(unsafe { moq_consume_catalog(consume, Some(channel_callback), catalog_cb.ptr) }); + let catalog_task = id(unsafe { moq_consume_catalog(consume, 0, Some(channel_callback), catalog_cb.ptr) }); let catalog_id = id(catalog_cb.recv()); let decoded = moq_audio_decoder_output { format: moq_audio_sample_format::MOQ_AUDIO_SAMPLE_FORMAT_F32 as u32, @@ -6283,7 +6344,7 @@ fn video_raw_publish_consume() { let consume = request_broadcast(origin, path); let catalog_cb = Callback::new(); - let catalog_task = id(unsafe { moq_consume_catalog(consume, Some(channel_callback), catalog_cb.ptr) }); + let catalog_task = id(unsafe { moq_consume_catalog(consume, 0, Some(channel_callback), catalog_cb.ptr) }); let catalog_id = id(catalog_cb.recv()); let decoder = moq_video_decoder_output { @@ -6467,7 +6528,7 @@ fn decode_first_frame(output: &moq_video_decoder_output) -> (u32, u32, usize) { let consume = request_broadcast(origin, path); let catalog_cb = Callback::new(); - let catalog_task = id(unsafe { moq_consume_catalog(consume, Some(channel_callback), catalog_cb.ptr) }); + let catalog_task = id(unsafe { moq_consume_catalog(consume, 0, Some(channel_callback), catalog_cb.ptr) }); let catalog_id = id(catalog_cb.recv()); let frame_cb = Callback::new(); @@ -6937,7 +6998,7 @@ fn video_raw_decode() { let consume = request_broadcast(origin, path); let catalog_cb = Callback::new(); - let catalog_task = id(unsafe { moq_consume_catalog(consume, Some(channel_callback), catalog_cb.ptr) }); + let catalog_task = id(unsafe { moq_consume_catalog(consume, 0, Some(channel_callback), catalog_cb.ptr) }); let catalog_id = id(catalog_cb.recv()); // Subscribe + decode before publishing frames so the keyframe group is delivered. @@ -7021,7 +7082,7 @@ fn multiple_frames_ordering() { let consume = request_broadcast(origin, path); let catalog_cb = Callback::new(); - let catalog_task = id(unsafe { moq_consume_catalog(consume, Some(channel_callback), catalog_cb.ptr) }); + let catalog_task = id(unsafe { moq_consume_catalog(consume, 0, Some(channel_callback), catalog_cb.ptr) }); let catalog_id = id(catalog_cb.recv()); let frame_cb = Callback::new(); @@ -7085,7 +7146,7 @@ fn catalog_update_on_new_track() { let consume = request_broadcast(origin, path); let catalog_cb = Callback::new(); - let catalog_task = id(unsafe { moq_consume_catalog(consume, Some(channel_callback), catalog_cb.ptr) }); + let catalog_task = id(unsafe { moq_consume_catalog(consume, 0, Some(channel_callback), catalog_cb.ptr) }); let catalog_id1 = id(catalog_cb.recv()); let mut audio_cfg = moq_audio_config { diff --git a/test/interop/clients/c/subscribe.c b/test/interop/clients/c/subscribe.c index 1f155218733..21e38d5da2e 100644 --- a/test/interop/clients/c/subscribe.c +++ b/test/interop/clients/c/subscribe.c @@ -699,7 +699,7 @@ int main(int argc, char **argv) { fail("error: broadcast never announced\n"); } - c.catalog = moq_consume_catalog((uint32_t)bc, on_catalog, &c); + c.catalog = moq_consume_catalog((uint32_t)bc, 0, on_catalog, &c); if (c.catalog <= 0) { fail("error: moq_consume_catalog failed: %d\n", c.catalog); } From 1e366b111c7d01d91e06219675f2f3162944dd11 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 03:42:23 -0800 Subject: [PATCH 3/4] fix(moq-c): a lost catalog track reports MOQ_ERROR_MOQ Lift hang::Error::Moq to Error::Moq, as moq_json's transport errors already are, so a catalog reader losing its track reports the code other consumers do. Co-Authored-By: Claude Opus 5.5 --- rs/moq-c/src/error.rs | 12 +++++++++++- rs/moq-c/src/test.rs | 25 +++++++++++++++++++++++++ 2 files changed, 36 insertions(+), 1 deletion(-) diff --git a/rs/moq-c/src/error.rs b/rs/moq-c/src/error.rs index 55435dcf6fc..956e85252e3 100644 --- a/rs/moq-c/src/error.rs +++ b/rs/moq-c/src/error.rs @@ -313,7 +313,7 @@ pub enum Error { /// Error from the hang media layer. #[error("hang error: {0}")] - Hang(#[from] hang::Error), + Hang(hang::Error), /// Error from the moq-mux consumer layer. #[error("mux error: {0}")] @@ -362,6 +362,16 @@ pub enum Error { Unsupported(String), } +// A lost track reports the transport code every other consumer does, not a hang failure. +impl From for Error { + fn from(err: hang::Error) -> Self { + match err { + hang::Error::Moq(e) => Error::Moq(e), + e => Error::Hang(e), + } + } +} + impl From for Error { fn from(err: moq_json::Error) -> Self { match err { diff --git a/rs/moq-c/src/test.rs b/rs/moq-c/src/test.rs index edf5dceb729..fbfe82082f2 100644 --- a/rs/moq-c/src/test.rs +++ b/rs/moq-c/src/test.rs @@ -3582,6 +3582,31 @@ fn named_consumers_cancel_while_subscribing() { assert_eq!(moq_origin_close(origin), 0); } +/// A lost catalog track ends the reader with the transport code other consumers report, so a +/// player can wait for the source to return instead of treating the catalog as malformed. +#[test] +fn a_lost_catalog_track_is_a_transport_error() { + let broadcast = moq_net::broadcast::Info::new().produce(); + let track = broadcast + .create_track( + hang::catalog::Catalog::DEFAULT_NAME, + hang::catalog::Catalog::default_track_info(), + ) + .unwrap(); + let at = moq_net::Timestamp::from_millis(1_000).unwrap(); + let mut group = track.append_group(at).unwrap(); + group.write_frame(at, "{}").unwrap(); + group.finish().unwrap(); + let consume = i32::from(State::lock().consume.start(broadcast.consume(), None).unwrap()) as u32; + + let cb = Callback::new(); + id(unsafe { moq_consume_catalog(consume, 0, Some(channel_callback), cb.ptr) }); + assert_eq!(moq_consume_catalog_free(id(cb.recv())), 0); + track.abort(moq_net::Error::Cancel).unwrap(); + assert_eq!(cb.recv_terminal(), crate::error::MOQ_ERROR_MOQ); + assert_eq!(moq_consume_close(consume), 0); +} + #[test] fn catalog_cancel_while_subscribing() { // A bare moq-net broadcast has no catalog track, so its subscribe waits on the handler. From 7184d3c5abca9ab323df4f0cb2201e7831140211 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 03:51:40 -0800 Subject: [PATCH 4/4] fix(moq-c): write the catalog timestamp through the raw pointer The caller's storage may be uninitialized, so no reference is made to it. Co-Authored-By: Claude Opus 5.5 --- rs/moq-c/src/api.rs | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/rs/moq-c/src/api.rs b/rs/moq-c/src/api.rs index a608b866391..6b5c6ad94ed 100644 --- a/rs/moq-c/src/api.rs +++ b/rs/moq-c/src/api.rs @@ -4538,8 +4538,11 @@ pub unsafe extern "C" fn moq_consume_catalog( pub unsafe extern "C" fn moq_consume_catalog_timestamp(catalog: u32, dst: *mut moq_timestamp) -> i32 { ffi::enter(move || { let catalog = ffi::parse_id(catalog)?; - let dst = unsafe { dst.as_mut() }.ok_or(Error::InvalidPointer)?; - *dst = State::lock().consume.catalog_timestamp(catalog)?; + if dst.is_null() { + return Err(Error::InvalidPointer); + } + let timestamp = State::lock().consume.catalog_timestamp(catalog)?; + unsafe { dst.write(timestamp) }; Ok(()) }) }