From 8b113ea4a5345f91383ef9440551d922e9a8258d Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 2 Nov 2026 23:21:34 -0800 Subject: [PATCH 1/9] chore(quest): claim quest/m1/json-required-timestamp.md Quest-Claim: 7350a1f8b5646919 From a5787b795a9f4d79237a272661d18e3dc1ad4e8f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 2 Nov 2026 23:34:17 -0800 Subject: [PATCH 2/9] feat!: JSON writes take a broadcast-clock timestamp Co-Authored-By: Claude Opus 5.5 --- rs/moq-c/c-tests/timestamps.c | 2 + rs/moq-c/src/api.rs | 38 +++-- rs/moq-c/src/publish.rs | 30 ++-- rs/moq-c/src/test.rs | 89 ++++++++++-- rs/moq-ffi/src/json.rs | 29 ++-- rs/moq-ffi/src/test.rs | 133 +++++++++-------- rs/moq-mux/src/catalog/tracks.rs | 6 +- rs/moq-mux/src/container/fmp4/import_test.rs | 6 +- rs/moq-mux/src/json.rs | 141 ++++++++++--------- rs/moq-transcode/src/catalog.rs | 2 +- 10 files changed, 287 insertions(+), 189 deletions(-) diff --git a/rs/moq-c/c-tests/timestamps.c b/rs/moq-c/c-tests/timestamps.c index e25f5ff598f..88954ac9292 100644 --- a/rs/moq-c/c-tests/timestamps.c +++ b/rs/moq-c/c-tests/timestamps.c @@ -101,6 +101,8 @@ int main(void) { MOQ_ERROR_TIMESTAMP_OVERFLOW); } CHECK(moq_publish_track_frame((uint32_t)track, payload, sizeof(payload), NULL) == MOQ_ERROR_MOQ); + // A JSON write is never stamped for you. + CHECK(moq_publish_json_stream_append((uint32_t)json, doc, strlen(doc), NULL) == MOQ_ERROR_INVALID_POINTER); CHECK(moq_origin_request((uint32_t)origin, path, strlen(path), NULL, 0, on_broadcast, &c) > 0); WAIT_FOR(&c, c.broadcast); diff --git a/rs/moq-c/src/api.rs b/rs/moq-c/src/api.rs index 763b64a9d99..10192345e6b 100644 --- a/rs/moq-c/src/api.rs +++ b/rs/moq-c/src/api.rs @@ -2481,6 +2481,26 @@ pub extern "C" fn moq_publish_close(broadcast: u32) -> i32 { }) } +/// Read the broadcast clock's current time into `dst`. +/// +/// Every track in a broadcast shares this clock's epoch, so stamp media frames and JSON writes +/// from it. Reading it fixes the clock: a container importer whose first frame arrives later +/// shifts onto it rather than moving it. +/// +/// Returns a zero on success, or a negative code on failure. +/// +/// # Safety +/// - `dst` must be a valid pointer to a [moq_timestamp]. +#[unsafe(no_mangle)] +pub unsafe extern "C" fn moq_publish_catalog_now(broadcast: u32, dst: *mut moq_timestamp) -> i32 { + ffi::enter(move || { + let broadcast = ffi::parse_id(broadcast)?; + let dst = unsafe { dst.as_mut() }.ok_or(Error::InvalidPointer)?; + *dst = State::lock().publish.catalog_now(broadcast)?.into(); + Ok(()) + }) +} + /// Finish a broadcast's catalog, which ends its content. /// /// Finish every track first. The broadcast stays announced and keeps serving its finished @@ -3566,9 +3586,10 @@ pub unsafe extern "C" fn moq_publish_json_snapshot( /// Publish a new value to a JSON snapshot track. `value` is a UTF-8 JSON document. A no-op if /// unchanged from the previous update. /// -/// `timestamp` is when the value was captured, converted to the track's millisecond timescale; -/// NULL stamps the broadcast clock's current time. A timestamp too large for milliseconds fails -/// with `MOQ_ERROR_MOQ` and publishes nothing. +/// `timestamp` is when the value was captured on the broadcast clock (see +/// [moq_publish_catalog_now]), converted to the track's millisecond timescale. NULL fails with +/// `MOQ_ERROR_INVALID_POINTER`, and a timestamp too large for milliseconds with `MOQ_ERROR_MOQ`; +/// either publishes nothing. /// /// Returns a zero on success, or a negative code on failure. /// @@ -3586,7 +3607,7 @@ pub unsafe extern "C" fn moq_publish_json_snapshot_update( let json = ffi::parse_id(json)?; let value = unsafe { ffi::parse_slice(value.cast::(), value_len)? }; let value = serde_json::from_slice(value)?; - let timestamp = unsafe { ffi::parse_timestamp(timestamp)? }; + let timestamp = unsafe { ffi::parse_timestamp(timestamp)? }.ok_or(Error::InvalidPointer)?; State::lock().publish.json_snapshot_update(json, value, timestamp) }) } @@ -3626,9 +3647,10 @@ pub unsafe extern "C" fn moq_publish_json_stream(broadcast: u32, name: *const c_ /// Append one record to a JSON stream track. `value` is a UTF-8 JSON document. /// -/// `timestamp` is when the value was captured, converted to the track's millisecond timescale; -/// NULL stamps the broadcast clock's current time. A timestamp too large for milliseconds fails -/// with `MOQ_ERROR_MOQ` and publishes nothing. +/// `timestamp` is when the value was captured on the broadcast clock (see +/// [moq_publish_catalog_now]), converted to the track's millisecond timescale. NULL fails with +/// `MOQ_ERROR_INVALID_POINTER`, and a timestamp too large for milliseconds with `MOQ_ERROR_MOQ`; +/// either appends nothing. /// /// Returns a zero on success, or a negative code on failure. /// @@ -3646,7 +3668,7 @@ pub unsafe extern "C" fn moq_publish_json_stream_append( let stream = ffi::parse_id(stream)?; let value = unsafe { ffi::parse_slice(value.cast::(), value_len)? }; let value = serde_json::from_slice(value)?; - let timestamp = unsafe { ffi::parse_timestamp(timestamp)? }; + let timestamp = unsafe { ffi::parse_timestamp(timestamp)? }.ok_or(Error::InvalidPointer)?; State::lock().publish.json_stream_append(stream, value, timestamp) }) } diff --git a/rs/moq-c/src/publish.rs b/rs/moq-c/src/publish.rs index 31b8f557b56..8efda89fa5b 100644 --- a/rs/moq-c/src/publish.rs +++ b/rs/moq-c/src/publish.rs @@ -252,8 +252,8 @@ impl std::ops::DerefMut for Kept { } } -// C data methods stamp a write the caller left unstamped on one fixed broadcast clock, -// without retaining another catalog handle after a failed stream retires its listing. +// C window methods stamp a write the caller left unstamped on one fixed broadcast clock, +// without retaining another catalog handle. struct Data { producer: T, clock: moq_mux::Clock, @@ -496,6 +496,13 @@ impl Publish { result } + /// Read the broadcast clock, the epoch every track in the broadcast is stamped in. + /// + /// Reading it fixes the clock, as [`moq_mux::catalog::Producer::clock`] does. + pub fn catalog_now(&mut self, broadcast: Id) -> Result { + Ok(self.catalog(broadcast)?.clock().now()) + } + /// End the broadcast's content by finishing its catalog, with its entries still listed, so /// a late subscriber finds the finished tracks until [`State::publish_close`]. pub fn catalog_finish(&mut self, broadcast: Id) -> Result<(), Error> { @@ -1288,16 +1295,16 @@ impl Publish { Ok(id) } - /// Publish a new value to a JSON snapshot track. A no-op if unchanged. + /// Publish a new value to a JSON snapshot track at `timestamp` on the broadcast clock. A no-op + /// if unchanged. pub fn json_snapshot_update( &mut self, json: Id, value: serde_json::Value, - timestamp: Option, + timestamp: moq_net::Timestamp, ) -> Result<(), Error> { let json = &mut self.json_snapshot.get_mut(json).ok_or(Error::TrackNotFound)?.data; - let at = timestamp.unwrap_or_else(|| json.clock.now()); - json.producer.update(moq_net::Timed::from(&value).at(at))?; + json.producer.update(&value, timestamp)?; Ok(()) } @@ -1322,16 +1329,15 @@ impl Publish { children.insert(&mut self.json_stream, producer, Child::JsonStream) } - /// Append one record to a JSON stream track. + /// Append one record to a JSON stream track at `timestamp` on the broadcast clock. pub fn json_stream_append( &mut self, stream: Id, value: serde_json::Value, - timestamp: Option, + timestamp: moq_net::Timestamp, ) -> Result<(), Error> { let producer = self.json_stream.get_mut(stream).ok_or(Error::TrackNotFound)?; - let at = timestamp.unwrap_or_else(|| producer.clock.now()); - producer.producer.append(moq_net::Timed::from(&value).at(at))?; + producer.producer.append(&value, timestamp)?; Ok(()) } @@ -1582,11 +1588,11 @@ mod children_tests { } let json = serde_json::Value::Null; assert!(matches!( - state.publish.json_snapshot_update(json_snapshot, json.clone(), None), + state.publish.json_snapshot_update(json_snapshot, json.clone(), moq_net::Timestamp::ZERO), Err(Error::TrackNotFound) )); assert!(matches!( - state.publish.json_stream_append(json_stream, json, None), + state.publish.json_stream_append(json_stream, json, moq_net::Timestamp::ZERO), Err(Error::TrackNotFound) )); } diff --git a/rs/moq-c/src/test.rs b/rs/moq-c/src/test.rs index 13ea2cf8c3c..008f4840e18 100644 --- a/rs/moq-c/src/test.rs +++ b/rs/moq-c/src/test.rs @@ -20,6 +20,13 @@ fn read_timestamp(timestamp: *const moq_timestamp) -> Option { unsafe { timestamp.as_ref() }.copied() } +/// The broadcast clock's current time, which every write on the broadcast is stamped from. +fn catalog_now(broadcast: u32) -> moq_timestamp { + let mut now = moq_timestamp::default(); + assert_eq!(unsafe { moq_publish_catalog_now(broadcast, &mut now) }, 0); + now +} + /// A ten-second max delay, the media consumers' usual budget here. const TEN_SECONDS: moq_delay = moq_delay { min_us: 0, @@ -2592,15 +2599,23 @@ fn json_snapshot_publish_consume() { let mut last = 0; for expected in [r#"{"a":1}"#, r#"{"a":2}"#] { + // Nothing stamps a write for the caller, so a NULL timestamp publishes nothing. assert_eq!( unsafe { moq_publish_json_snapshot_update( producer, - expected.as_ptr() as *const c_char, - expected.len(), + r#"{"a":0}"#.as_ptr() as *const c_char, + 7, std::ptr::null(), ) }, + MOQ_ERROR_INVALID_POINTER + ); + let now = catalog_now(broadcast); + assert_eq!( + unsafe { + moq_publish_json_snapshot_update(producer, expected.as_ptr() as *const c_char, expected.len(), &now) + }, 0 ); let value_id = id(value_cb.recv()); @@ -2610,7 +2625,6 @@ fn json_snapshot_publish_consume() { timestamp: std::ptr::null(), }; assert_eq!(unsafe { moq_consume_json_value(value_id, &mut value) }, 0); - // The producer stamps each value with the broadcast clock. let at = read_timestamp(value.timestamp).expect("a stamped value is timed"); assert!(at.value >= last); last = at.value; @@ -2660,15 +2674,16 @@ fn json_stream_publish_consume() { let mut last = 0; for expected in [r#"{"n":0}"#, r#"{"n":1}"#, r#"{"n":2}"#] { + // Nothing stamps a write for the caller, so a NULL timestamp appends nothing. assert_eq!( unsafe { - moq_publish_json_stream_append( - producer, - expected.as_ptr() as *const c_char, - expected.len(), - std::ptr::null(), - ) + moq_publish_json_stream_append(producer, r#"{"n":-1}"#.as_ptr() as *const c_char, 8, std::ptr::null()) }, + MOQ_ERROR_INVALID_POINTER + ); + let now = catalog_now(broadcast); + assert_eq!( + unsafe { moq_publish_json_stream_append(producer, expected.as_ptr() as *const c_char, expected.len(), &now) }, 0 ); let value_id = id(value_cb.recv()); @@ -2678,7 +2693,6 @@ fn json_stream_publish_consume() { timestamp: std::ptr::null(), }; assert_eq!(unsafe { moq_consume_json_value(value_id, &mut value) }, 0); - // The producer stamps each value with the broadcast clock. let at = read_timestamp(value.timestamp).expect("a stamped value is timed"); assert!(at.value >= last); last = at.value; @@ -2690,7 +2704,7 @@ fn json_stream_publish_consume() { assert_eq!(moq_consume_json_value_free(value_id), 0); } - // A caller's timestamp replaces the clock's, floored to the track's millisecond scale. + // A timestamp at another scale is floored to the track's milliseconds. let expected = r#"{"n":3}"#; let at = moq_timestamp { value: (last + 1_000) * 90 + 45, @@ -7524,6 +7538,59 @@ fn json_tracks_are_advertised_in_the_catalog() { assert_eq!(moq_origin_close(origin), 0); } +/// Media and data stamped from the broadcast clock share one epoch, so a JSON track gives the +/// media no `delay`: a media frame trails no data write. +#[test] +fn a_shared_epoch_gives_media_no_delay() { + let origin = id(moq_origin_create()); + let broadcast = publish_broadcast(origin, b"shared-epoch"); + let before: Vec = published_catalog(broadcast).audio.renditions.keys().cloned().collect(); + let media = id(publish_audio( + broadcast, + moq_audio_format::MOQ_AUDIO_FORMAT_OPUS, + &opus_head(), + None, + )); + let name = (published_catalog(broadcast).audio.renditions.keys()) + .find(|name| !before.contains(name)) + .expect("rendition listed") + .clone(); + let status = b"status"; + let json = id(unsafe { + moq_publish_json_snapshot( + broadcast, + status.as_ptr() as *const c_char, + status.len(), + &moq_json_snapshot_config { deltas: true }, + ) + }); + + let now = catalog_now(broadcast); + let value = br#"{"live":true}"#; + assert_eq!( + unsafe { moq_publish_json_snapshot_update(json, value.as_ptr() as *const c_char, value.len(), &now) }, + 0 + ); + let start = moq_net::Timestamp::try_from(now).unwrap().as_micros() as u64; + write_opus(media, start, 50, 100); + + let delay = audio_rendition(broadcast, &name).delay; + assert!(delay.unwrap_or_default().is_zero(), "{delay:?}"); + + assert_eq!( + unsafe { moq_publish_catalog_now(broadcast, std::ptr::null_mut()) }, + MOQ_ERROR_INVALID_POINTER + ); + assert_eq!(moq_publish_json_snapshot_finish(json), 0); + assert_eq!(moq_publish_media_finish(media), 0); + assert_eq!(moq_publish_close(broadcast), 0); + assert!( + unsafe { moq_publish_catalog_now(broadcast, &mut moq_timestamp::default()) } < 0, + "a closed broadcast has no clock" + ); + assert_eq!(moq_origin_close(origin), 0); +} + #[test] fn data_track_names_cannot_collide() { let origin = id(moq_origin_create()); diff --git a/rs/moq-ffi/src/json.rs b/rs/moq-ffi/src/json.rs index ade243ec600..3fa6b02383e 100644 --- a/rs/moq-ffi/src/json.rs +++ b/rs/moq-ffi/src/json.rs @@ -149,7 +149,7 @@ impl MoqJsonSnapshotProducer { /// The catalog carries `json.tracks.` (`mode: snapshot`) for as long as the producer /// lives; finishing or dropping it retires the entry. Takes /// over `track`, whose handle is closed afterward. Errors if the catalog already carries an - /// entry under the track's name. + /// entry under the track's name, or if `track` has no timescale, since every update is timed. #[uniffi::constructor] pub fn new( broadcast: &MoqBroadcastProducer, @@ -173,17 +173,15 @@ impl MoqJsonSnapshotProducer { /// Publish a new value, encoded as a snapshot or delta automatically. `value` is a JSON /// document. A no-op if unchanged from the previous update. - /// `timestamp` is on the broadcast clock; null publishes untimed. - #[uniffi::method(default(timestamp = None))] - pub fn update(&self, value: String, timestamp: Option) -> Result<(), MoqError> { + /// `timestamp` is on the broadcast clock, which + /// [`MoqMediaCatalogProducer::now`](crate::media::MoqMediaCatalogProducer::now) reads. + pub fn update(&self, value: String, timestamp: MoqTimestamp) -> Result<(), MoqError> { let _guard = crate::ffi::enter(); let value: Value = serde_json::from_str(&value)?; + let timestamp = timestamp.try_into()?; let mut guard = self.inner.lock().unwrap(); let producer = guard.as_mut().ok_or(MoqError::Closed)?; - producer.update(moq_net::Timed { - value: &value, - at: timestamp.map(TryInto::try_into).transpose()?, - })?; + producer.update(&value, timestamp)?; Ok(()) } @@ -311,7 +309,8 @@ impl MoqJsonStreamProducer { /// /// The catalog carries `json.tracks.` (`mode: stream`) for as long as the producer /// lives. Takes over `track`, whose handle is closed afterward. Errors if the catalog already - /// carries an entry under the track's name. + /// carries an entry under the track's name, or if `track` has no timescale, since every append + /// is timed. #[uniffi::constructor] pub fn new(broadcast: &MoqBroadcastProducer, track: &MoqTrackProducer) -> Result, MoqError> { let _guard = crate::ffi::enter(); @@ -325,17 +324,15 @@ impl MoqJsonStreamProducer { } /// Append one record to the log. `value` is a JSON document. - /// `timestamp` is on the broadcast clock; null publishes untimed. - #[uniffi::method(default(timestamp = None))] - pub fn append(&self, value: String, timestamp: Option) -> Result<(), MoqError> { + /// `timestamp` is on the broadcast clock, which + /// [`MoqMediaCatalogProducer::now`](crate::media::MoqMediaCatalogProducer::now) reads. + pub fn append(&self, value: String, timestamp: MoqTimestamp) -> Result<(), MoqError> { let _guard = crate::ffi::enter(); let value: Value = serde_json::from_str(&value)?; + let timestamp = timestamp.try_into()?; let mut guard = self.inner.lock().unwrap(); let producer = guard.as_mut().ok_or(MoqError::Closed)?; - producer.append(moq_net::Timed { - value: &value, - at: timestamp.map(TryInto::try_into).transpose()?, - })?; + producer.append(&value, timestamp)?; Ok(()) } diff --git a/rs/moq-ffi/src/test.rs b/rs/moq-ffi/src/test.rs index c055599ad6b..d675a20daeb 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -1334,56 +1334,52 @@ async fn subscribe(broadcast: &MoqBroadcastProducer, name: &str) -> Arc { - let producer = - MoqJsonSnapshotProducer::new(&broadcast, &track, MoqJsonSnapshotConfig { deltas: false }) - .unwrap(); - producer - .update(String::from_utf8(payload.to_vec()).unwrap(), timestamp) - .unwrap(); - producer.finish().unwrap(); - } - "json stream" => { - let producer = MoqJsonStreamProducer::new(&broadcast, &track).unwrap(); - producer - .append(String::from_utf8(payload.to_vec()).unwrap(), timestamp) + let timestamp = MoqTimestamp { + value: 123_457, + scale: 90_000, + }; + for kind in ["json snapshot", "json stream"] { + let broadcast = MoqBroadcastProducer::new().unwrap(); + let track = broadcast + .publish_track( + "data".into(), + Some(MoqTrackInfo { + priority: 0, + max_age: None, + refresh: None, + timescale: Some(timestamp.scale), + compress: false, + }), + ) + .unwrap(); + let consumer = subscribe(&broadcast, "data").await; + let payload = b"{\"n\":1}"; + match kind { + "json snapshot" => { + let producer = + MoqJsonSnapshotProducer::new(&broadcast, &track, MoqJsonSnapshotConfig { deltas: false }) .unwrap(); - producer.finish().unwrap(); - } - _ => unreachable!(), + producer + .update(String::from_utf8(payload.to_vec()).unwrap(), timestamp) + .unwrap(); + producer.finish().unwrap(); } - let frame = consumer.read_frame().await.unwrap().unwrap(); - assert_eq!(frame.payload, payload, "{kind}"); - assert_eq!(frame.timestamp, timestamp, "{kind}"); - assert_eq!(consumer.info().timescale, timestamp.map(|timestamp| timestamp.scale)); - broadcast.close().unwrap(); + "json stream" => { + let producer = MoqJsonStreamProducer::new(&broadcast, &track).unwrap(); + producer + .append(String::from_utf8(payload.to_vec()).unwrap(), timestamp) + .unwrap(); + producer.finish().unwrap(); + } + _ => unreachable!(), } + let frame = consumer.read_frame().await.unwrap().unwrap(); + assert_eq!(frame.payload, payload, "{kind}"); + assert_eq!(frame.timestamp, Some(timestamp), "{kind}"); + assert_eq!(consumer.info().timescale, Some(timestamp.scale)); + broadcast.close().unwrap(); } } @@ -1469,7 +1465,7 @@ async fn json_snapshot_roundtrip() { let consumer = MoqJsonSnapshotConsumer::new(&*subscribe(&broadcast, "meta").await).unwrap(); for n in 1..=4 { - producer.update(format!(r#"{{"a":{n}}}"#), Some(us(n * 1000))).unwrap(); + producer.update(format!(r#"{{"a":{n}}}"#), us(n * 1000)).unwrap(); } let value = kio::clock::timeout(TIMEOUT, consumer.next()) @@ -1508,7 +1504,7 @@ async fn json_snapshot_roundtrip() { producer.finish().unwrap(); assert!(matches!( - producer.update(r#"{"a":5}"#.into(), Some(us(5000))), + producer.update(r#"{"a":5}"#.into(), us(5000)), Err(MoqError::Closed) )); let end = kio::clock::timeout(TIMEOUT, consumer.next()) @@ -1530,7 +1526,7 @@ async fn json_snapshot_refreshes_for_a_joiner() { priority: 127, max_age: None, refresh: Some(1), - timescale: None, + timescale: Some(1_000_000), compress: false, }), ) @@ -1538,7 +1534,7 @@ async fn json_snapshot_refreshes_for_a_joiner() { let config = MoqJsonSnapshotConfig { deltas: true }; let producer = MoqJsonSnapshotProducer::new(&broadcast, &track, config.clone()).unwrap(); for n in 0..4 { - producer.update(format!(r#"{{"n":{n}}}"#), None).unwrap(); + producer.update(format!(r#"{{"n":{n}}}"#), us(n * 1000)).unwrap(); } // The join crosses the ratio, so the producer restates the value without another update. The @@ -1574,9 +1570,9 @@ async fn json_snapshot_refreshes_for_a_joiner() { async fn json_demand() { let broadcast = MoqBroadcastProducer::new().unwrap(); let snapshot_config = MoqJsonSnapshotConfig { deltas: true }; - let track = broadcast.publish_track("status".into(), None).unwrap(); + let track = broadcast.publish_track("status".into(), Some(timed_info())).unwrap(); let snapshot = MoqJsonSnapshotProducer::new(&broadcast, &track, snapshot_config.clone()).unwrap(); - let track = broadcast.publish_track("events".into(), None).unwrap(); + let track = broadcast.publish_track("events".into(), Some(timed_info())).unwrap(); let stream = MoqJsonStreamProducer::new(&broadcast, &track).unwrap(); let snapshot_demand = snapshot.demand().unwrap(); let stream_demand = stream.demand().unwrap(); @@ -1877,12 +1873,12 @@ async fn demand_handle_outlives_finish() { #[tokio::test] async fn json_stream_roundtrip() { let broadcast = MoqBroadcastProducer::new().unwrap(); - let track = broadcast.publish_track("events".into(), None).unwrap(); + let track = broadcast.publish_track("events".into(), Some(timed_info())).unwrap(); let producer = MoqJsonStreamProducer::new(&broadcast, &track).unwrap(); let consumer = MoqJsonStreamConsumer::new(&*subscribe(&broadcast, "events").await).unwrap(); for n in 0..3 { - producer.append(format!(r#"{{"n":{n}}}"#), None).unwrap(); + producer.append(format!(r#"{{"n":{n}}}"#), us(n * 1000)).unwrap(); let value = kio::clock::timeout(TIMEOUT, consumer.next()) .await .expect("timed out waiting for json stream record") @@ -1892,7 +1888,7 @@ async fn json_stream_roundtrip() { serde_json::from_str::(&value.value).unwrap(), serde_json::json!({ "n": n }) ); - assert_eq!(value.timestamp, None, "an untimed track yields no timestamp"); + assert_eq!(value.timestamp.map(micros), Some(n * 1000)); } producer.finish().unwrap(); } @@ -1912,7 +1908,7 @@ async fn json_on_requested_track() { .await .expect("timed out waiting for requested track") .unwrap(); - let producer = MoqJsonStreamProducer::new(&broadcast, &request.accept(None).unwrap()).unwrap(); + let producer = MoqJsonStreamProducer::new(&broadcast, &request.accept(Some(timed_info())).unwrap()).unwrap(); let track = kio::clock::timeout(TIMEOUT, subscribe) .await .expect("timed out waiting for the subscribe") @@ -1920,7 +1916,7 @@ async fn json_on_requested_track() { .unwrap(); let consumer = MoqJsonStreamConsumer::new(&track).unwrap(); - producer.append(r#"{"n":1}"#.into(), None).unwrap(); + producer.append(r#"{"n":1}"#.into(), us(1000)).unwrap(); let value = kio::clock::timeout(TIMEOUT, consumer.next()) .await .expect("timed out waiting for json stream record") @@ -4765,7 +4761,7 @@ async fn data_children( [Arc; 3], ) { let consumer = broadcast.consume().unwrap(); - let track = |name: &str| broadcast.publish_track(name.into(), None).unwrap(); + let track = |name: &str| broadcast.publish_track(name.into(), Some(timed_info())).unwrap(); let writers = ( MoqJsonSnapshotProducer::new( broadcast, @@ -4799,9 +4795,9 @@ async fn closing_a_broadcast_ends_its_open_data_tracks() { broadcast.close().unwrap(); assert_left(readers).await; - assert!(matches!(json_snapshot.update("1".into(), None), Err(MoqError::Closed))); - assert!(matches!(json_stream.append("1".into(), None), Err(MoqError::Closed))); - assert!(matches!(json_window.push("1".into(), None), Err(MoqError::Closed))); + assert!(matches!(json_snapshot.update("1".into(), us(0)), Err(MoqError::Closed))); + assert!(matches!(json_stream.append("1".into(), us(0)), Err(MoqError::Closed))); + assert!(matches!(json_window.push("1".into(), Some(us(0))), Err(MoqError::Closed))); } /// A data writer released without a finish ends its track as a publisher leaving. @@ -4819,7 +4815,7 @@ async fn dropping_an_unfinished_data_writer_ends_it() { #[tokio::test(start_paused = true)] async fn a_track_is_adopted_by_one_writer() { let broadcast = MoqBroadcastProducer::new().unwrap(); - let track = broadcast.publish_track("json".into(), None).unwrap(); + let track = broadcast.publish_track("json".into(), Some(timed_info())).unwrap(); let config = || MoqJsonSnapshotConfig { deltas: false }; let failed = track.adopt::(|_| { assert!(matches!( @@ -8170,12 +8166,15 @@ async fn json_tracks_are_advertised_in_the_catalog() { let broadcast = MoqBroadcastProducer::new().unwrap(); let snapshot = MoqJsonSnapshotProducer::new( &broadcast, - &broadcast.publish_track("status".into(), None).unwrap(), + &broadcast.publish_track("status".into(), Some(timed_info())).unwrap(), MoqJsonSnapshotConfig { deltas: true }, ) .unwrap(); - let stream = - MoqJsonStreamProducer::new(&broadcast, &broadcast.publish_track("events".into(), None).unwrap()).unwrap(); + let stream = MoqJsonStreamProducer::new( + &broadcast, + &broadcast.publish_track("events".into(), Some(timed_info())).unwrap(), + ) + .unwrap(); let catalog = published_catalog(&broadcast); let entry = catalog.json.tracks.get("status").expect("snapshot track advertised"); @@ -8203,12 +8202,12 @@ async fn data_track_names_cannot_collide() { let broadcast = MoqBroadcastProducer::new().unwrap(); let first = MoqJsonSnapshotProducer::new( &broadcast, - &broadcast.publish_track("state".into(), None).unwrap(), + &broadcast.publish_track("state".into(), Some(timed_info())).unwrap(), MoqJsonSnapshotConfig { deltas: false }, ) .unwrap(); let other = MoqBroadcastProducer::new().unwrap(); - let track = other.publish_track("state".into(), None).unwrap(); + let track = other.publish_track("state".into(), Some(timed_info())).unwrap(); assert!( MoqJsonStreamProducer::new(&broadcast, &track).is_err(), "a duplicate data track name should fail" diff --git a/rs/moq-mux/src/catalog/tracks.rs b/rs/moq-mux/src/catalog/tracks.rs index f45658282d7..0d0c86868f5 100644 --- a/rs/moq-mux/src/catalog/tracks.rs +++ b/rs/moq-mux/src/catalog/tracks.rs @@ -71,12 +71,14 @@ use super::hang::{Catalog, CatalogExt}; /// # broadcast: &mut moq_net::broadcast::Producer, /// # catalog: &moq_mux::catalog::Producer, /// # ) -> moq_mux::Result<()> { -/// let info = moq_net::track::Info::default().with_compress(true); +/// let info = moq_net::track::Info::default() +/// .with_timescale(moq_net::Timescale::MILLI) +/// .with_compress(true); /// let track = broadcast.create_track("telemetry", info)?; /// // The producer fixes the mode, so the one passed here is only a placeholder. /// let entry = Mavlink { config: JsonConfig::new(Mode::Stream), sysid: 1 }; /// let mut telemetry = catalog.json_stream::(track, entry)?; -/// telemetry.append(&serde_json::json!({ "heartbeat": 1 }))?; +/// telemetry.append(&serde_json::json!({ "heartbeat": 1 }), catalog.clock().now())?; /// # Ok(()) /// # } /// ``` diff --git a/rs/moq-mux/src/container/fmp4/import_test.rs b/rs/moq-mux/src/container/fmp4/import_test.rs index f2e0a1362e3..79e8dc06d6b 100644 --- a/rs/moq-mux/src/container/fmp4/import_test.rs +++ b/rs/moq-mux/src/container/fmp4/import_test.rs @@ -2747,7 +2747,7 @@ async fn join_after(earlier: Earlier, start_us: u64) { .json_stream::(track, crate::json::Config::default()) .unwrap(); stream - .append(moq_net::Timed::from(&serde_json::json!("before")).at(catalog.clock().now())) + .append(&serde_json::json!("before"), catalog.clock().now()) .unwrap(); Some(stream) } @@ -2763,9 +2763,7 @@ async fn join_after(earlier: Earlier, start_us: u64) { fmp4.decode(&live_session(start_us, 20)).unwrap(); let after = clock.now().as_micros(); if let Some(stream) = data.as_mut() { - stream - .append(moq_net::Timed::from(&serde_json::json!("after")).at(catalog.clock().now())) - .unwrap(); + stream.append(&serde_json::json!("after"), catalog.clock().now()).unwrap(); } fmp4.finish().unwrap(); diff --git a/rs/moq-mux/src/json.rs b/rs/moq-mux/src/json.rs index caee3b03c60..4e3d69f0158 100644 --- a/rs/moq-mux/src/json.rs +++ b/rs/moq-mux/src/json.rs @@ -20,11 +20,13 @@ //! # broadcast: &mut moq_net::broadcast::Producer, //! # catalog: &moq_mux::catalog::Producer, //! # ) -> moq_mux::Result<()> { -//! // JSON is small and repetitive, so compress it on the wire. -//! let info = moq_net::track::Info::default().with_compress(true); +//! // A timed track, since every write is stamped. JSON is small and repetitive, so compress it. +//! let info = moq_net::track::Info::default() +//! .with_timescale(moq_net::Timescale::MILLI) +//! .with_compress(true); //! let track = broadcast.create_track("chat", info)?; //! let mut chat = catalog.json_stream::(track, moq_mux::json::Config::default())?; -//! chat.append(&Message { text: "hello".to_string() })?; +//! chat.append(&Message { text: "hello".to_string() }, catalog.clock().now())?; //! # Ok(()) //! # } //! ``` @@ -32,12 +34,12 @@ //! The catalog entry is written when the producer is created and removed when it drops, so a track //! is never advertised without a publisher behind it. //! -//! A bare value stays untimed; only a timed track accepts an explicit capture time. -//! -//! A value timed on the broadcast [`Clock`](crate::Clock) is written at that timestamp as given, -//! and the entry advertises how late values reach the transport as its `jitter` and `delay`, the -//! way a media rendition does. A capture [`Instant`](kio::clock::Instant) converts with -//! [`Clock::capture`](crate::Clock::capture) on the catalog's clock: +//! Every write takes a timestamp on the broadcast [`Clock`](crate::Clock), the epoch every track +//! in the broadcast shares, so the track must have a timescale. A value is written at that +//! timestamp as given, and the entry advertises how late values reach the transport as its +//! `jitter` and `delay`, the way a media rendition does. A capture +//! [`Instant`](kio::clock::Instant) converts with [`Clock::capture`](crate::Clock::capture) on the +//! catalog's clock: //! //! ```no_run //! # fn example( @@ -47,7 +49,7 @@ //! # received: kio::clock::Instant, //! # ) -> moq_mux::Result<()> { //! let at = catalog.clock().capture(received)?; -//! gps.append(moq_net::Timed::from(&fix).at(at))?; +//! gps.append(&fix, at)?; //! # Ok(()) //! # } //! ``` @@ -146,8 +148,12 @@ impl IntoRendition for Config { /// Fix `config`'s mode. /// /// Errors on a `broadcast` reference, which would point consumers away from the track this -/// publishes. -fn prepare(config: &mut impl AsMut, mode: Mode) -> crate::Result<()> { +/// publishes, and with [`moq_net::Error::TimestampMismatch`] on a track without a timescale, which +/// would refuse every timestamped write. +fn prepare(track: &moq_net::track::Producer, config: &mut impl AsMut, mode: Mode) -> crate::Result<()> { + if track.info().timescale.is_none() { + return Err(moq_net::Error::TimestampMismatch.into()); + } let json = config.as_mut(); if json.broadcast.is_some() { return Err(crate::Error::ForeignBroadcast); @@ -172,7 +178,7 @@ impl Snapshot { mut config: C, options: Options, ) -> crate::Result { - prepare(&mut config, Mode::Snapshot)?; + prepare(&track, &mut config, Mode::Snapshot)?; let json = moq_json::snapshot::Config::default().with_deltas(options.deltas); let inner = moq_json::snapshot::Producer::new(track, json); let listing = Listing::new(rendition, config)?; @@ -207,19 +213,13 @@ impl Snapshot { self.inner.poll_refresh(waiter).map_err(Into::into) } - /// Publish a new value, superseding the previous one. + /// Publish a new value at `timestamp` on the broadcast clock, superseding the previous one. /// - /// A value timed on the broadcast clock is written at that timestamp and measures the entry's - /// `jitter` and `delay`; one ahead of now measures as zero delay. An unchanged - /// value writes nothing and measures nothing. - pub fn update<'a>(&mut self, value: impl Into>) -> crate::Result<()> - where - T: 'a, - { - let value = value.into(); - let captured = value.at; - match self.inner.update(value)? { - Some(size) => self.listing.record(size, captured), + /// The value is written at that timestamp and measures the entry's `jitter` and `delay`; one + /// ahead of now measures as zero delay. An unchanged value writes nothing and measures nothing. + pub fn update(&mut self, value: &T, timestamp: moq_net::Timestamp) -> crate::Result<()> { + match self.inner.update(Timed::from(value).at(timestamp))? { + Some(size) => self.listing.record(size, Some(timestamp)), None => Ok(()), } } @@ -260,7 +260,7 @@ impl Stream { rendition: crate::catalog::Rendition, mut config: C, ) -> crate::Result { - prepare(&mut config, Mode::Stream)?; + prepare(&track, &mut config, Mode::Stream)?; let inner = moq_json::stream::Producer::new(track, moq_json::stream::Config::default()); let listing = Listing::new(rendition, config)?; Ok(Self { @@ -288,20 +288,16 @@ impl Stream { self.inner.demand() } - /// Append one record to the log. + /// Append one record to the log at `timestamp` on the broadcast clock. /// /// A record that cannot be written ends the track (see [`moq_json::stream::Producer::append`]) /// and retires the catalog entry with it. A record refused with /// [`moq_net::Error::FrameTooLarge`], [`moq_net::Error::GroupTooLarge`], or - /// [`moq_net::Error::TimestampMismatch`] leaves both intact, since nothing was written. A catalog error publishing the measured bitrate is returned after the record was written, so the track + /// [`moq_net::Error::TimestampMismatch`] leaves both intact, since nothing was written. A catalog + /// error publishing the measured bitrate is returned after the record was written, so the track /// stays open and a retry would duplicate it. - pub fn append<'a>(&mut self, value: impl Into>) -> crate::Result<()> - where - T: 'a, - { - let value = value.into(); - let captured = value.at; - let size = match self.inner.append(value) { + pub fn append(&mut self, value: &T, timestamp: moq_net::Timestamp) -> crate::Result<()> { + let size = match self.inner.append(Timed::from(value).at(timestamp)) { Ok(size) => size, // Refused before anything was written, so the log and its entry carry on. Err( @@ -322,7 +318,7 @@ impl Stream { }; match &mut self.listing { - Some(listing) => listing.record(size, captured), + Some(listing) => listing.record(size, Some(timestamp)), None => Ok(()), } } @@ -464,12 +460,6 @@ mod test { /// Create the moq-net track a data producer publishes on, as a caller does for a media track. fn track(broadcast: &mut moq_net::broadcast::Producer, name: &str) -> moq_net::track::Producer { - broadcast - .create_track(name, moq_net::track::Info::default().with_compress(true)) - .unwrap() - } - - fn timed_track(broadcast: &mut moq_net::broadcast::Producer, name: &str) -> moq_net::track::Producer { broadcast.create_track(name, timed().with_compress(true)).unwrap() } @@ -509,7 +499,7 @@ mod test { let track = chat.consume(); let expected: Vec = (0..3).map(|n| json!({ "n": n })).collect(); for value in &expected { - chat.append(value).unwrap(); + chat.append(value, catalog.clock().now()).unwrap(); } // `finish` retires the entry, so read both off the live track first. let entry = entry(&catalog, "chat"); @@ -529,8 +519,8 @@ mod test { .unwrap(); let track = status.consume(); - status.update(&json!({ "live": false })).unwrap(); - status.update(&json!({ "live": true })).unwrap(); + status.update(&json!({ "live": false }), catalog.clock().now()).unwrap(); + status.update(&json!({ "live": true }), catalog.clock().now()).unwrap(); let entry = entry(&catalog, "status"); status.finish().unwrap(); @@ -547,13 +537,13 @@ mod test { let (mut broadcast, catalog) = catalog(); let mut status = catalog .json_snapshot::( - timed_track(&mut broadcast, "status"), + track(&mut broadcast, "status"), Config::default(), Options::default(), ) .unwrap(); let mut chat = catalog - .json_stream::(timed_track(&mut broadcast, "chat"), Config::default()) + .json_stream::(track(&mut broadcast, "chat"), Config::default()) .unwrap(); let mut subscribers = [status.consume(), chat.consume()]; @@ -566,11 +556,8 @@ mod test { .unwrap(); assert_eq!(catalog.snapshot().clock, published, "the clock never moves"); assert!(before <= first, "the importer lands at now: {before:?} {first:?}"); - status - .update(Timed::from(&json!({ "live": true })).at(catalog.clock().now())) - .unwrap(); - chat.append(Timed::from(&json!({ "n": 1 })).at(catalog.clock().now())) - .unwrap(); + status.update(&json!({ "live": true }), catalog.clock().now()).unwrap(); + chat.append(&json!({ "n": 1 }), catalog.clock().now()).unwrap(); let after = catalog.clock().now(); let waiter = kio::Waiter::noop(); @@ -610,14 +597,13 @@ mod test { let mut full_track = full.consume(); let mut delta_track = delta.consume(); for value in [json!({ "n": 1 }), json!({ "n": 2 })] { - full.update(&value).unwrap(); - delta.update(&value).unwrap(); + full.update(&value, catalog.clock().now()).unwrap(); + delta.update(&value, catalog.clock().now()).unwrap(); } full.finish().unwrap(); delta.finish().unwrap(); - // The default subscription budget keeps only the latest group, aging untimed groups by - // wall clock. Without deltas the second value rolled a new group, so that group holds one + // The default subscription budget keeps only the latest group. Without deltas the second value rolled a new group, so that group holds one // frame. With deltas the second value joins the same group. assert_eq!(ready_groups(&mut full_track), vec![1]); assert_eq!(ready_groups(&mut delta_track), vec![2]); @@ -734,29 +720,28 @@ mod test { fn an_unchanged_snapshot_measures_nothing() { let (mut broadcast, catalog) = catalog(); let mut gps = catalog - .json_stream::(timed_track(&mut broadcast, "gps"), Config::default()) + .json_stream::(track(&mut broadcast, "gps"), Config::default()) .unwrap(); let mut status = catalog .json_snapshot::( - timed_track(&mut broadcast, "status"), + track(&mut broadcast, "status"), Config::default(), Options::default(), ) .unwrap(); let now = catalog.clock().now(); let value = serde_json::json!({ "armed": true }); - status.update(Timed::from(&value).at(now)).unwrap(); - gps.append(Timed::from(&serde_json::json!({ "lat": 0 })).at(now)) - .unwrap(); + status.update(&value, now).unwrap(); + gps.append(&serde_json::json!({ "lat": 0 }), now).unwrap(); let stale = now .checked_sub(moq_net::Timestamp::from_micros(1_000_000).unwrap()) .unwrap(); - status.update(Timed::from(&value).at(stale)).unwrap(); + status.update(&value, stale).unwrap(); assert_eq!(entry(&catalog, "status").delay, None); // The same stale capture on a changed value is written behind gps. let changed = serde_json::json!({ "armed": false }); - status.update(Timed::from(&changed).at(stale)).unwrap(); + status.update(&changed, stale).unwrap(); let delay = entry(&catalog, "status").delay.expect("a capture behind gps is delay"); assert!(delay >= std::time::Duration::from_secs(1), "{delay:?}"); } @@ -802,7 +787,7 @@ mod test { let mut chat = catalog .json_stream::(track(&mut broadcast, "chat"), Config::default()) .unwrap(); - chat.append(&json!({ "text": "hello" })).unwrap(); + chat.append(&json!({ "text": "hello" }), catalog.clock().now()).unwrap(); let snapshot = catalog.snapshot(); let entry = crate::catalog::Entry::new("chat", snapshot.json.tracks.get("chat").expect("missing entry")); @@ -843,11 +828,11 @@ mod test { .unwrap(); let mut track = chat.consume(); - assert!(chat.append(&Record(true)).is_err()); + assert!(chat.append(&Record(true), catalog.clock().now()).is_err()); assert!(!catalog.snapshot().json.tracks.contains_key("chat")); assert!( - chat.append(&Record(false)).is_err(), + chat.append(&Record(false), catalog.clock().now()).is_err(), "a record after the failure would land on a track the retired entry no longer advertises" ); @@ -867,12 +852,12 @@ mod test { let oversized = Value::String("x".repeat(moq_net::group::MAX_CACHE_BYTES as usize)); assert!(matches!( - chat.append(&oversized), + chat.append(&oversized, catalog.clock().now()), Err(crate::Error::Json(moq_json::Error::Net(moq_net::Error::FrameTooLarge))) )); assert!(catalog.snapshot().json.tracks.contains_key("chat")); - chat.append(&json!({ "n": 1 })).unwrap(); + chat.append(&json!({ "n": 1 }), catalog.clock().now()).unwrap(); let entry = entry(&catalog, "chat"); chat.finish().unwrap(); assert_eq!( @@ -881,6 +866,26 @@ mod test { ); } + /// Every write is stamped, so a track without a timescale, which refuses a timestamp, is refused + /// up front instead of on every write, and nothing is advertised for it. + #[test] + fn an_untimed_track_is_refused() { + let (mut broadcast, catalog) = catalog(); + let untimed = |broadcast: &mut moq_net::broadcast::Producer, name: &str| { + broadcast.create_track(name, moq_net::track::Info::default()).unwrap() + }; + + assert!(matches!( + catalog.json_stream::(untimed(&mut broadcast, "chat"), Config::default()), + Err(crate::Error::Moq(moq_net::Error::TimestampMismatch)) + )); + assert!(matches!( + catalog.json_snapshot::(untimed(&mut broadcast, "status"), Config::default(), Options::default()), + Err(crate::Error::Moq(moq_net::Error::TimestampMismatch)) + )); + assert!(catalog.snapshot().json.tracks.is_empty()); + } + /// A consumer that can't tell a log from a latest-value document would silently drop records, /// so an unreadable entry is an error rather than a guess. #[test] diff --git a/rs/moq-transcode/src/catalog.rs b/rs/moq-transcode/src/catalog.rs index 5ed28433e10..d48def1e7c5 100644 --- a/rs/moq-transcode/src/catalog.rs +++ b/rs/moq-transcode/src/catalog.rs @@ -1037,7 +1037,7 @@ mod tests { .unwrap(); let mut subscriber = status.consume(); tokio::time::advance(Duration::from_secs(3)).await; - status.update(moq_net::Timed::from(&1).at(adopted.now())).unwrap(); + status.update(&1, adopted.now()).unwrap(); let waiter = kio::Waiter::noop(); let std::task::Poll::Ready(Ok(Some(mut group))) = subscriber.poll_recv_group(&waiter) else { From 069da2737246b952e124dca565ee4c90eb08d72e Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 2 Nov 2026 23:39:11 -0800 Subject: [PATCH 3/9] feat!: JSON writes take a broadcast-clock timestamp in every binding Co-Authored-By: Claude Opus 5.5 --- c/moq/MIGRATE.md | 4 ++++ cpp/moq/MIGRATE.md | 4 ++++ dart/moq/MIGRATE.md | 4 ++++ dart/moq/lib/json.dart | 12 +++++++--- dart/moq_ffi/lib/src/moq.dart | 22 +++++++++---------- doc/lib/c/index.md | 2 +- doc/lib/dart/index.md | 1 + doc/lib/go/index.md | 2 +- doc/lib/kt/index.md | 1 + doc/lib/py/index.md | 6 ++--- doc/lib/swift/index.md | 1 + go/wrapper/MIGRATE.md | 4 ++++ go/wrapper/json/json.go | 19 ++++++++++------ go/wrapper/json/json_test.go | 14 +++++++----- kt/moq/MIGRATE.md | 4 ++++ .../kotlin/dev/moq/json/Tracks.kt | 20 ++++++++++------- .../kotlin/dev/moq/SmokeTest.kt | 18 +++++++-------- py/moq-rs/MIGRATE.md | 4 ++++ py/moq-rs/moq/json.py | 19 +++++++++++----- py/moq-rs/tests/test_data_timestamps.py | 10 ++++----- py/moq-rs/tests/test_local.py | 17 +++++++------- rs/moq-c/MIGRATE.md | 5 +++++ rs/moq-ffi/MIGRATE.md | 5 +++++ rs/moq-mux/MIGRATE.md | 6 +++++ swift/MIGRATE.md | 4 ++++ swift/Sources/Moq/Json.swift | 18 +++++++++------ swift/Tests/MoqTests/SmokeTests.swift | 12 +++++----- 27 files changed, 157 insertions(+), 81 deletions(-) diff --git a/c/moq/MIGRATE.md b/c/moq/MIGRATE.md index e2a9d73e5cd..2db71895f7a 100644 --- a/c/moq/MIGRATE.md +++ b/c/moq/MIGRATE.md @@ -6,6 +6,10 @@ How to update your code for each breaking change, newest first. The hand-written crate never published as moq-c: a libmoq 0.6 user applies these entries before moving to the generated API. +### JSON writes refuse a NULL timestamp ([#7691](https://github.com/moq-dev/moq/pull/7691)) + +`moq_publish_json_snapshot_update` and `moq_publish_json_stream_append` fail with `MOQ_ERROR_INVALID_POINTER` on a NULL `timestamp` instead of stamping the broadcast clock. Stamp media and JSON from `moq_publish_catalog_now()`; in the generated API, JSON `update` and `append` take a required `moq_timestamp` from the media catalog producer's `now`, and refuse a track without a timescale. + ### Announcement captures are required ([#7484](https://github.com/moq-dev/moq/pull/7484)) `moq_announce_event.has_captures` is removed, changing the C ABI. Read `captures_len` directly: zero means the filter has no wildcards. Rebuild consumers against the regenerated header and matching native library. diff --git a/cpp/moq/MIGRATE.md b/cpp/moq/MIGRATE.md index d561d680531..8384eab0686 100644 --- a/cpp/moq/MIGRATE.md +++ b/cpp/moq/MIGRATE.md @@ -2,6 +2,10 @@ ## Unreleased +### JSON writes take a broadcast-clock timestamp ([#7691](https://github.com/moq-dev/moq/pull/7691)) + +`moq::JsonSnapshotProducer::update` and `moq::JsonStreamProducer::append` take a required `moq::Timestamp` instead of an optional one. Stamp it from `moq::MediaCatalogProducer::now()`, the broadcast clock every track shares. Their constructors refuse a track created without a `timescale`. Regenerate bindings and rebuild with the matching native library. + ### Announcement captures are required ([#7484](https://github.com/moq-dev/moq/pull/7484)) `moq::Announce.captures` is `std::vector` instead of an optional vector. Remove optional checks and dereferences; an empty vector means the filter has no wildcards. Regenerate bindings and rebuild with the matching native library. diff --git a/dart/moq/MIGRATE.md b/dart/moq/MIGRATE.md index 38f4d5f1f5b..490873f368f 100644 --- a/dart/moq/MIGRATE.md +++ b/dart/moq/MIGRATE.md @@ -4,6 +4,10 @@ How to update your code for each breaking change, newest first. ## Unreleased +### JSON writes take a broadcast-clock timestamp ([#7691](https://github.com/moq-dev/moq/pull/7691)) + +`json.SnapshotProducer.update` and `json.StreamProducer.append` take a `required MoqTimestamp timestamp` on the broadcast clock instead of an optional one. Read it with `MoqMediaCatalogProducer(broadcast: broadcast).now()`. Their track needs a timescale, such as `MoqTrackInfo(timescale: 1000)`; one without is refused. + ### Announcement captures are required ([#7484](https://github.com/moq-dev/moq/pull/7484)) `Announce.captures` is `List` instead of `List?`. Remove null checks and pass `captures: []` when constructing an announcement for a filter without wildcards. Regenerate bindings and rebuild with the matching native library. diff --git a/dart/moq/lib/json.dart b/dart/moq/lib/json.dart index 33c6efe5e47..afc35f1d5d0 100644 --- a/dart/moq/lib/json.dart +++ b/dart/moq/lib/json.dart @@ -5,8 +5,10 @@ /// which has no window mode), and a consumer takes over a `TrackConsumer` that /// has not read a group yet. Values cross as JSON strings. Compression is the /// track's: publish JSON with `MoqTrackInfo(compress: true)`, and a consumer -/// reads it with no option of its own. Import it with a prefix, since -/// `dart:convert` has a `json` too: +/// reads it with no option of its own. Every snapshot update and stream append +/// takes a timestamp on the broadcast clock, the epoch every track in the +/// broadcast shares, so their track needs a timescale; one without is refused. +/// Import it with a prefix, since `dart:convert` has a `json` too: /// /// ```dart /// import 'package:moq/json.dart' as moq_json; @@ -15,10 +17,14 @@ /// broadcast: broadcast, /// track: broadcast.publishTrack( /// name: 'status', -/// info: MoqTrackInfo(compress: true), +/// info: MoqTrackInfo(timescale: 1000, compress: true), /// ), /// config: moq_json.SnapshotConfig(), /// ); +/// status.update( +/// value: '{"state":"live"}', +/// timestamp: MoqMediaCatalogProducer(broadcast: broadcast).now(), +/// ); /// ``` library; diff --git a/dart/moq_ffi/lib/src/moq.dart b/dart/moq_ffi/lib/src/moq.dart index 469ee931747..bea4cc3e46b 100644 --- a/dart/moq_ffi/lib/src/moq.dart +++ b/dart/moq_ffi/lib/src/moq.dart @@ -10685,7 +10685,7 @@ class FfiConverterMoqJsonSnapshotConsumer { abstract class MoqJsonSnapshotProducerInterface { MoqTrackDemand demand(); void finish(); - void update({required String value, MoqTimestamp? timestamp = null}); + void update({required String value, required MoqTimestamp timestamp}); } final _MoqJsonSnapshotProducerFinalizer = Finalizer>((ptr) { @@ -10762,12 +10762,12 @@ class MoqJsonSnapshotProducer implements MoqJsonSnapshotProducerInterface { }, moqExceptionErrorHandler); } - void update({required String value, MoqTimestamp? timestamp = null}) { + void update({required String value, required MoqTimestamp timestamp}) { return rustCall((status) { uniffi_moq_ffi_fn_method_moqjsonsnapshotproducer_update( uniffiClonePointer(), FfiConverterString.lower(value), - FfiConverterOptionalMoqTimestamp.lower(timestamp), + FfiConverterMoqTimestamp.lower(timestamp), status, ); }, moqExceptionErrorHandler); @@ -10905,7 +10905,7 @@ class FfiConverterMoqJsonStreamConsumer { } abstract class MoqJsonStreamProducerInterface { - void append({required String value, MoqTimestamp? timestamp = null}); + void append({required String value, required MoqTimestamp timestamp}); MoqTrackDemand demand(); void finish(); } @@ -10962,12 +10962,12 @@ class MoqJsonStreamProducer implements MoqJsonStreamProducerInterface { } } - void append({required String value, MoqTimestamp? timestamp = null}) { + void append({required String value, required MoqTimestamp timestamp}) { return rustCall((status) { uniffi_moq_ffi_fn_method_moqjsonstreamproducer_append( uniffiClonePointer(), FfiConverterString.lower(value), - FfiConverterOptionalMoqTimestamp.lower(timestamp), + FfiConverterMoqTimestamp.lower(timestamp), status, ); }, moqExceptionErrorHandler); @@ -21951,8 +21951,7 @@ void _checkApiChecksums() { 42593) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqjsonsnapshotproducer_update() != - 41112) { + if (uniffi_moq_ffi_checksum_method_moqjsonsnapshotproducer_update() != 7688) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqjsonstreamconsumer_cancel() != 29308) { @@ -21961,7 +21960,7 @@ void _checkApiChecksums() { if (uniffi_moq_ffi_checksum_method_moqjsonstreamconsumer_next() != 21257) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqjsonstreamproducer_append() != 57310) { + if (uniffi_moq_ffi_checksum_method_moqjsonstreamproducer_append() != 60414) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqjsonstreamproducer_demand() != 52854) { @@ -22441,14 +22440,13 @@ void _checkApiChecksums() { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_constructor_moqjsonsnapshotproducer_new() != - 14914) { + 37949) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_constructor_moqjsonstreamconsumer_new() != 3025) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_constructor_moqjsonstreamproducer_new() != - 20445) { + if (uniffi_moq_ffi_checksum_constructor_moqjsonstreamproducer_new() != 2022) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_constructor_moqjsonwindowconsumer_new() != diff --git a/doc/lib/c/index.md b/doc/lib/c/index.md index a9b5d6533cc..c14b6a10766 100644 --- a/doc/lib/c/index.md +++ b/doc/lib/c/index.md @@ -107,7 +107,7 @@ inside. The header is the reference: each function carries a doc comment. - **Discovery.** Announcement captures are always a list of wildcard matches, empty when the filter has no wildcards. - **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()` 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, NULL on an untimed track and valid as long as the payload. Tracks moq-c creates are timed, so their raw writes need one. JSON writes, including window pushes and pops, take one too, converted to their track's milliseconds; NULL stamps the broadcast clock's current time. A zero scale or an out-of-range value fails with `MOQ_ERROR_TIMESTAMP_OVERFLOW`. +- **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, NULL on an untimed track and valid as long as the payload. Tracks moq-c creates are timed, so their raw writes need one. 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 `moq_publish_json_snapshot_update` or `moq_publish_json_stream_append` fails with `MOQ_ERROR_INVALID_POINTER`, while a window push or pop stamps the broadcast clock's current time. A zero scale or an out-of-range value fails with `MOQ_ERROR_TIMESTAMP_OVERFLOW`. - **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. diff --git a/doc/lib/dart/index.md b/doc/lib/dart/index.md index 106c767cb72..2e2fc431118 100644 --- a/doc/lib/dart/index.md +++ b/doc/lib/dart/index.md @@ -19,6 +19,7 @@ and a `Named` or `Requested` target. `CatalogProducer(broadcast: ...)` owns cata and sections; it holds the broadcast weakly and fails after the broadcast closes. Publish JSON tracks with `MoqTrackInfo(compress: true)`; a `package:moq/json.dart` consumer reads one with no option of its own. A missing data timestamp stays untimed; the library never substitutes zero or now. +`SnapshotProducer.update` and `StreamProducer.append` require a timestamp on the broadcast clock (`CatalogProducer.now()`), the epoch every track in the broadcast shares, so their track needs a timescale. `package:moq/json.dart` consumers return `Value` (`value`, `timestamp`) from `next()`; a snapshot consumer yields each state in order, and `latest()` skips to the newest. Media times are exact `Timestamp` records, `value` units at `scale` units per second, so a 90 kHz tick survives a diff --git a/doc/lib/go/index.md b/doc/lib/go/index.md index 5ad9e4eb92e..afc53126f85 100644 --- a/doc/lib/go/index.md +++ b/doc/lib/go/index.md @@ -22,7 +22,7 @@ catalog writes fail with `ErrClosed` after the broadcast closes. Media timestamp A missing data timestamp stays untimed; the library never substitutes zero or now. Raw tracks with a `nil` timescale are untimed on both publish and receive. `TrackInfo.Compress` sends each group DEFLATE-compressed to opt-in `moq-lite-07-wip` peers; other peers, and every reader here, get the original frames. Set it on JSON tracks. -The JSON producers' `Update` / `Append` take a final `*moq.Timestamp` argument (`nil` for untimed). +The JSON snapshot and stream producers' `Update` / `Append` take a final `moq.Timestamp` on the broadcast clock, the epoch every track in the broadcast shares, so their track needs a timescale. JSON consumers return a `*Timed` holding the value and that timestamp; `SnapshotConsumer.Latest` skips to the newest state where `Next` yields each one. A read timestamp is at the track's timescale. Whole-frame media writes require caller time; container imports keep their own timeline handling. diff --git a/doc/lib/kt/index.md b/doc/lib/kt/index.md index d7c33fb9fe5..d6f931c5cf9 100644 --- a/doc/lib/kt/index.md +++ b/doc/lib/kt/index.md @@ -18,6 +18,7 @@ x86\_64) and desktop JVM (Linux x86\_64/aarch64, macOS arm64, Windows x64). `CatalogProducer(broadcast)` holds its broadcast weakly and fails with `Closed` after it closes. Publish JSON tracks with `TrackInfo(compress = true)`; a `dev.moq.json` consumer reads one with no option of its own. A missing data timestamp stays untimed; the library never substitutes zero or now. +`SnapshotProducer.update` and `StreamProducer.append` require a timestamp on the broadcast clock (`CatalogProducer.now()`), the epoch every track in the broadcast shares, so their track needs a timescale. `dev.moq.json` consumers' `values()` emits `Value` (`value`, `timestamp`) and `valuesAs()` emits `Timed`; a snapshot consumer yields each state in order, and `latest()` skips to the newest. A `Timestamp(value, scale)` is exact and reads back at the track's timescale, so a 90 kHz tick republishes unchanged. diff --git a/doc/lib/py/index.md b/doc/lib/py/index.md index 3f1a8d5ae3f..8d1f2487fea 100644 --- a/doc/lib/py/index.md +++ b/doc/lib/py/index.md @@ -29,7 +29,7 @@ JSON consumers yield `moq.json.Timed(value, timestamp)`; a snapshot consumer yie and `await consumer.latest()` skips to the newest. A window consumer's value is a `WindowPush`, `WindowPop`, or `WindowSkip`. Raw tracks with a `None` timescale are untimed on both publish and receive. `TrackInfo(compress=True)` sends each group DEFLATE-compressed to opt-in `moq-lite-07-wip` peers; other peers, and every reader here, get the original frames. Set it on JSON tracks. -The JSON producers' `update` / `append` accept `timestamp=moq.Timestamp(...)` (`None` for untimed). +The JSON snapshot and stream producers' `update` / `append` require a `timestamp` on the broadcast clock, the epoch every track in the broadcast shares, so their track needs a timescale. Whole-frame media writes require caller time; container imports keep their own timeline handling. Timed raw/data tracks require caller-supplied timestamps. Use `CatalogProducer.now()` to stamp a locally created event on the broadcast clock; reading it fixes that clock for later media producers. @@ -95,9 +95,9 @@ async def main(): # Raw bytes and JSON events = broadcast.publish_track("events") events.write_frame(b'{"cmd": "ready"}') - status_track = broadcast.publish_track("status", moq.TrackInfo(compress=True)) + status_track = broadcast.publish_track("status", moq.TrackInfo(timescale=1_000, compress=True)) status = moq.json.SnapshotProducer(broadcast, status_track) - status.update({"state": "live", "viewers": 42}) + status.update({"state": "live", "viewers": 42}, catalog_producer.now()) publication.announce() # each broadcast mints a fresh instance audio.finish() diff --git a/doc/lib/swift/index.md b/doc/lib/swift/index.md index ec0ae5b804a..6dd79412e01 100644 --- a/doc/lib/swift/index.md +++ b/doc/lib/swift/index.md @@ -22,6 +22,7 @@ Media timestamps are exact `Timestamp` records, `value` units at `scale` units p and `try timestamp.duration` rounds down to a whole attosecond. Publish JSON tracks with `TrackInfo(compress: true)`; a `Json` consumer reads one with no option of its own. A missing data timestamp stays untimed; the library never substitutes zero or now. +`Json.SnapshotProducer.update` and `Json.StreamProducer.append` require a timestamp on the broadcast clock (`Media.CatalogProducer.now()`), the epoch every track in the broadcast shares, so their track needs a timescale. `Json` consumers yield `Json.Timed` (`value`, `timestamp`); a snapshot consumer yields each state in order, and `latest()` skips to the newest. Raw tracks with a `nil` timescale are untimed on both publish and receive. diff --git a/go/wrapper/MIGRATE.md b/go/wrapper/MIGRATE.md index 8f0b8385259..1a7588f46ec 100644 --- a/go/wrapper/MIGRATE.md +++ b/go/wrapper/MIGRATE.md @@ -4,6 +4,10 @@ How to update your code for each breaking change, newest first. ## Unreleased +### JSON writes take a broadcast-clock timestamp ([#7691](https://github.com/moq-dev/moq/pull/7691)) + +`json.SnapshotProducer.Update` and `json.StreamProducer.Append` take a `moq.Timestamp` instead of a `*moq.Timestamp`, so there is no untimed write. Stamp it from `media.CatalogProducer.Now()`, the broadcast clock every track shares. Their track needs a `TrackInfo.Timescale`; one without is refused. + ### `media.VideoInit` is a struct `media.VideoInit` is its own struct rather than an alias of the generated record, so its new `Lower` field takes a `*media.TrackProducer`. A composite literal with `Format`, `Data`, `Label`, and `Hint` compiles unchanged; build one that way where you converted a generated `MoqVideoInit`. diff --git a/go/wrapper/json/json.go b/go/wrapper/json/json.go index 138f045919e..809be5b44b8 100644 --- a/go/wrapper/json/json.go +++ b/go/wrapper/json/json.go @@ -6,7 +6,10 @@ // over a [moq.TrackConsumer] that has not read a group yet. The track can come // from a request as well as by name. Compression is the track's: publish JSON // with [moq.TrackInfo] Compress set, and a consumer reads it with no option of -// its own. Import it under an alias next to encoding/json: +// its own. Every snapshot update and stream append takes a timestamp on the +// broadcast clock, the epoch every track in the broadcast shares (read it with +// media.CatalogProducer.Now), so their track needs a [moq.TrackInfo] Timescale; +// one without is refused. Import it under an alias next to encoding/json: // // import moqjson "moq.dev/moq/json" package json @@ -54,7 +57,8 @@ type SnapshotProducer struct { // NewSnapshotProducer publishes track as a lossy latest-value JSON track, advertised in // broadcast's catalog until it finishes. It takes over track, whose handle is closed -// afterward, and fails if the catalog already carries the track's name. +// afterward, and fails if the catalog already carries the track's name or track has no +// timescale. func NewSnapshotProducer(broadcast *moq.BroadcastProducer, track *moq.TrackProducer, options SnapshotOptions) (*SnapshotProducer, error) { inner, err := ffi.NewMoqJsonSnapshotProducer( bridge.BroadcastProducer(broadcast), @@ -67,9 +71,9 @@ func NewSnapshotProducer(broadcast *moq.BroadcastProducer, track *moq.TrackProdu return &SnapshotProducer{inner: inner}, nil } -// Update publishes value at timestamp on the broadcast clock; nil is untimed. +// Update publishes value at timestamp on the broadcast clock. // It is a no-op when unchanged. -func (p *SnapshotProducer) Update(value any, timestamp *moq.Timestamp) error { +func (p *SnapshotProducer) Update(value any, timestamp moq.Timestamp) error { encoded, err := stdjson.Marshal(value) if err != nil { return err @@ -98,7 +102,8 @@ type StreamProducer struct { // NewStreamProducer publishes track as a lossless append-log JSON track, advertised in // broadcast's catalog until it finishes. It takes over track, whose handle is closed -// afterward, and fails if the catalog already carries the track's name. +// afterward, and fails if the catalog already carries the track's name or track has no +// timescale. func NewStreamProducer(broadcast *moq.BroadcastProducer, track *moq.TrackProducer) (*StreamProducer, error) { inner, err := ffi.NewMoqJsonStreamProducer(bridge.BroadcastProducer(broadcast), bridge.TrackProducer(track)) if err != nil { @@ -107,8 +112,8 @@ func NewStreamProducer(broadcast *moq.BroadcastProducer, track *moq.TrackProduce return &StreamProducer{inner: inner}, nil } -// Append adds one JSON record at timestamp on the broadcast clock; nil is untimed. -func (p *StreamProducer) Append(value any, timestamp *moq.Timestamp) error { +// Append adds one JSON record at timestamp on the broadcast clock. +func (p *StreamProducer) Append(value any, timestamp moq.Timestamp) error { encoded, err := stdjson.Marshal(value) if err != nil { return err diff --git a/go/wrapper/json/json_test.go b/go/wrapper/json/json_test.go index 1cee5ca3a71..2acbbaed1fe 100644 --- a/go/wrapper/json/json_test.go +++ b/go/wrapper/json/json_test.go @@ -30,10 +30,11 @@ func newBroadcast(t *testing.T) (*moq.BroadcastProducer, *moq.BroadcastConsumer) return broadcast, consumer } -// publishTrack creates a raw track for a JSON producer to take over. +// publishTrack creates a millisecond track for a JSON producer to take over. func publishTrack(t *testing.T, broadcast *moq.BroadcastProducer, name string) *moq.TrackProducer { t.Helper() - track, err := broadcast.PublishTrack(name, nil) + scale := uint64(1_000) + track, err := broadcast.PublishTrack(name, &moq.TrackInfo{Timescale: &scale}) if err != nil { t.Fatal(err) } @@ -71,7 +72,7 @@ func TestTracks(t *testing.T) { defer snapshotConsumer.Cancel() for viewers := 1; viewers <= 4; viewers++ { at := moq.Timestamp{Value: uint64(viewers) * 1000, Scale: scale} - if err := snapshot.Update(map[string]any{"viewers": viewers}, &at); err != nil { + if err := snapshot.Update(map[string]any{"viewers": viewers}, at); err != nil { t.Fatal(err) } } @@ -109,15 +110,16 @@ func TestTracks(t *testing.T) { t.Fatal(err) } defer streamConsumer.Cancel() - if err := stream.Append(map[string]any{"n": 1}, nil); err != nil { + at := moq.Timestamp{Value: 5, Scale: 1_000} + if err := stream.Append(map[string]any{"n": 1}, at); err != nil { t.Fatal(err) } record, err := streamConsumer.Next(ctx) if err != nil { t.Fatal(err) } - if string(record.Value) != `{"n":1}` || record.Timestamp != nil { - t.Fatalf("record = %s at %v, want untimed", record.Value, record.Timestamp) + if string(record.Value) != `{"n":1}` || record.Timestamp == nil || *record.Timestamp != at { + t.Fatalf("record = %s at %v, want %v", record.Value, record.Timestamp, at) } if err := snapshot.Finish(); err != nil { diff --git a/kt/moq/MIGRATE.md b/kt/moq/MIGRATE.md index ecb3c831ba8..61bef30f2b2 100644 --- a/kt/moq/MIGRATE.md +++ b/kt/moq/MIGRATE.md @@ -4,6 +4,10 @@ How to update your code for each breaking change, newest first. ## Unreleased +### JSON writes take a broadcast-clock timestamp ([#7691](https://github.com/moq-dev/moq/pull/7691)) + +`json.SnapshotProducer.update(value, timestamp)` and `json.StreamProducer.append(value, timestamp)` require a `Timestamp` on the broadcast clock instead of defaulting to null, for both the typed and the `String` overloads. Read it with `media.CatalogProducer(broadcast).now()`. Their track needs a timescale, such as `TrackInfo(timescale = 1_000uL)`; one without is refused. + ### Announcement captures are required ([#7484](https://github.com/moq-dev/moq/pull/7484)) `Announce.captures` is `List` instead of `List?`. Remove null checks and pass `captures = emptyList()` when constructing an announcement for a filter without wildcards. Rebuild with the matching generated bindings and native library. diff --git a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/json/Tracks.kt b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/json/Tracks.kt index 36ef697f80d..2a61e840d93 100644 --- a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/json/Tracks.kt +++ b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/json/Tracks.kt @@ -4,10 +4,14 @@ package dev.moq.json // producer takes over a `dev.moq.TrackProducer` (the snapshot and stream // producers also advertise it in the broadcast's catalog, which has no window // mode), and a consumer takes over a `dev.moq.TrackConsumer` that has not read -// a group yet. Compression is the track's, set through `TrackInfo(compress = true)`: +// a group yet. Compression is the track's, set through `TrackInfo(compress = true)`. +// Every snapshot update and stream append takes a timestamp on the broadcast +// clock, the epoch every track in the broadcast shares, so their track needs a +// timescale; one without is refused: // -// val track = broadcast.publishTrack("status", TrackInfo(compress = true)) +// val track = broadcast.publishTrack("status", TrackInfo(timescale = 1_000uL, compress = true)) // val status = SnapshotProducer(broadcast, track, SnapshotConfig()) +// status.update(Status(state = "live"), CatalogProducer(broadcast).now()) // val reader = SnapshotConsumer(consumer.subscribeTrack("status", null)) import dev.moq.MoqJson @@ -69,18 +73,18 @@ inline fun Value.decode(): Timed = Timed(MoqJson.decodeFromString(serializer(), value), timestamp) /** - * Publish [value] as a JSON snapshot, superseding the last. A no-op when unchanged. + * Publish [value] as a JSON snapshot at [timestamp] on the broadcast clock, superseding the last. A + * no-op when unchanged. * * The `@Serializable` type is encoded with [MoqJson]. Pass an already-encoded `String` to serialize - * with another library: the member overload takes it unchanged. [timestamp] is on the broadcast - * clock; null is untimed. + * with another library: the member overload takes it unchanged. */ -inline fun SnapshotProducer.update(value: T, timestamp: Timestamp? = null) { +inline fun SnapshotProducer.update(value: T, timestamp: Timestamp) { update(MoqJson.encodeToString(serializer(), value), timestamp) } -/** Append [value] at [timestamp] on the broadcast clock; null is untimed. */ -inline fun StreamProducer.append(value: T, timestamp: Timestamp? = null) { +/** Append [value] at [timestamp] on the broadcast clock. */ +inline fun StreamProducer.append(value: T, timestamp: Timestamp) { append(MoqJson.encodeToString(serializer(), value), timestamp) } diff --git a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt index cad86be4475..bdf5f62868c 100644 --- a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt +++ b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt @@ -574,8 +574,8 @@ class SmokeTest { fun `json producer demand follows subscribers`() = runTest { BroadcastProducer().use { broadcast -> val config = SnapshotConfig(deltas = false) - SnapshotProducer(broadcast, broadcast.publishTrack("status", null), config).use { - producer -> + val track = broadcast.publishTrack("status", TrackInfo(timescale = 1_000uL)) + SnapshotProducer(broadcast, track, config).use { producer -> val demand: TrackDemand = producer.demand() assertEquals("status", demand.name()) assertEquals(null, demand.wanted()) @@ -593,10 +593,10 @@ class SmokeTest { BroadcastProducer().use { broadcast -> val config = SnapshotConfig(deltas = false) // A demand watcher does not own the writer; keep it alive through collection. - SnapshotProducer(broadcast, broadcast.publishTrack("status", null), config).use { - producer -> + val track = broadcast.publishTrack("status", TrackInfo(timescale = 1_000uL)) + SnapshotProducer(broadcast, track, config).use { producer -> val demand: TrackDemand = producer.demand() - producer.update(Status(state = "live")) + producer.update(Status(state = "live"), Timestamp(1uL, 1_000uL)) val consumer = SnapshotConsumer(broadcast.consume().subscribeTrack("status", null)) while (demand.wantedChanged() == null) {} @@ -616,13 +616,13 @@ class SmokeTest { fun `raw json string passes through unencoded`() = runTest { BroadcastProducer().use { broadcast -> val config = SnapshotConfig(deltas = false) - SnapshotProducer(broadcast, broadcast.publishTrack("status", null), config).use { - producer -> - producer.update("""{"state":"raw"}""") + val track = broadcast.publishTrack("status", TrackInfo(timescale = 1_000uL)) + SnapshotProducer(broadcast, track, config).use { producer -> + producer.update("""{"state":"raw"}""", Timestamp(1uL, 1_000uL)) val consumer = SnapshotConsumer(broadcast.consume().subscribeTrack("status", null)) assertEquals( - Timed(Status(state = "raw"), null), + Timed(Status(state = "raw"), Timestamp(1uL, 1_000uL)), consumer.valuesAs().first(), ) } diff --git a/py/moq-rs/MIGRATE.md b/py/moq-rs/MIGRATE.md index af31a32d54a..d05f0bf3ac6 100644 --- a/py/moq-rs/MIGRATE.md +++ b/py/moq-rs/MIGRATE.md @@ -4,6 +4,10 @@ How to update your code for each breaking change, newest first. ## Unreleased +### JSON writes take a broadcast-clock timestamp ([#7691](https://github.com/moq-dev/moq/pull/7691)) + +`json.SnapshotProducer.update(value, timestamp)` and `json.StreamProducer.append(value, timestamp)` require a `Timestamp` on the broadcast clock instead of an optional `timestamp=` keyword. Read it with `media.CatalogProducer(broadcast).now()`. Their track needs a timescale, such as `TrackInfo(timescale=1_000)`; one without is refused. + ### Announcement captures are required ([#7484](https://github.com/moq-dev/moq/pull/7484)) `Announce.captures` is `list[str]` instead of `list[str] | None`. Remove `None` checks and pass `captures=[]` when constructing an announcement for a filter without wildcards. Rebuild with the matching generated bindings and native library. diff --git a/py/moq-rs/moq/json.py b/py/moq-rs/moq/json.py index e8a029e3dff..546988a2d5c 100644 --- a/py/moq-rs/moq/json.py +++ b/py/moq-rs/moq/json.py @@ -8,6 +8,10 @@ Compression is the track's: publish it with ``TrackInfo(compress=True)``, which JSON benefits from, and a consumer reads it with no option of its own. + +Every snapshot update and stream append takes a timestamp on the broadcast clock, the epoch every +track in the broadcast shares: read it with :meth:`moq.media.CatalogProducer.now`. Their track +needs a timescale (``TrackInfo(timescale=1000)``); one without is refused. """ from __future__ import annotations @@ -91,9 +95,12 @@ def demand(self) -> TrackDemand: """A watch-only handle to whether this track has subscribers.""" return TrackDemand(self._inner.demand()) - def update(self, value: Any, *, timestamp: Timestamp | None = None) -> None: - """Publish a new value. A no-op if unchanged from the previous update.""" - self._inner.update(json.dumps(value), _opt_ts(timestamp)) + def update(self, value: Any, timestamp: Timestamp) -> None: + """Publish a new value at ``timestamp`` on the broadcast clock. + + A no-op if unchanged from the previous update. + """ + self._inner.update(json.dumps(value), timestamp._ffi()) def finish(self) -> None: """Finish the track, closing any open group.""" @@ -114,9 +121,9 @@ def demand(self) -> TrackDemand: """A watch-only handle to whether this track has subscribers.""" return TrackDemand(self._inner.demand()) - def append(self, value: Any, *, timestamp: Timestamp | None = None) -> None: - """Append one record to the log.""" - self._inner.append(json.dumps(value), _opt_ts(timestamp)) + def append(self, value: Any, timestamp: Timestamp) -> None: + """Append one record to the log at ``timestamp`` on the broadcast clock.""" + self._inner.append(json.dumps(value), timestamp._ffi()) def finish(self) -> None: """Finish the track, closing the group.""" diff --git a/py/moq-rs/tests/test_data_timestamps.py b/py/moq-rs/tests/test_data_timestamps.py index 4cfe802a8a8..2995a0c518b 100644 --- a/py/moq-rs/tests/test_data_timestamps.py +++ b/py/moq-rs/tests/test_data_timestamps.py @@ -47,19 +47,19 @@ def test_timedelta_conversions(): @pytest.mark.parametrize("mode", ["snapshot", "stream"]) -@pytest.mark.parametrize("timestamp", TIMESTAMPS) -async def test_json_timestamp_round_trip(mode: str, timestamp: moq.Timestamp | None): +@pytest.mark.parametrize("timestamp", [timestamp for timestamp in TIMESTAMPS if timestamp is not None]) +async def test_json_timestamp_round_trip(mode: str, timestamp: moq.Timestamp): broadcast = moq.BroadcastProducer() - track = broadcast.publish_track("value", moq.TrackInfo(timescale=None if timestamp is None else timestamp.scale)) + track = broadcast.publish_track("value", moq.TrackInfo(timescale=timestamp.scale)) consumer = track.consume() value = {"n": 1} if mode == "snapshot": snapshot = moq.json.SnapshotProducer(broadcast, track) - snapshot.update(value, timestamp=timestamp) + snapshot.update(value, timestamp) snapshot.finish() else: stream = moq.json.StreamProducer(broadcast, track) - stream.append(value, timestamp=timestamp) + stream.append(value, timestamp) stream.finish() frame = await asyncio.wait_for(consumer.read_frame(), timeout=5.0) assert frame is not None diff --git a/py/moq-rs/tests/test_local.py b/py/moq-rs/tests/test_local.py index 7803aca57ba..da70ae6b1f2 100644 --- a/py/moq-rs/tests/test_local.py +++ b/py/moq-rs/tests/test_local.py @@ -538,7 +538,7 @@ async def test_json_snapshot_roundtrip(): consumer = moq.json.SnapshotConsumer(await broadcast.consume().subscribe_track("status")) for viewers in range(1, 5): - producer.update({"viewers": viewers}, timestamp=moq.Timestamp(viewers, 1_000)) + producer.update({"viewers": viewers}, moq.Timestamp(viewers, 1_000)) # Iteration yields every state in order; latest() skips the buffered third. value = await asyncio.wait_for(anext(consumer), timeout=5.0) @@ -554,13 +554,13 @@ async def test_json_snapshot_roundtrip(): async def test_json_stream_roundtrip(): broadcast = moq.BroadcastProducer() - producer = moq.json.StreamProducer(broadcast, broadcast.publish_track("events")) + producer = moq.json.StreamProducer(broadcast, broadcast.publish_track("events", moq.TrackInfo(timescale=1_000))) consumer = moq.json.StreamConsumer(await broadcast.consume().subscribe_track("events")) for n in range(3): - producer.append({"n": n}) + producer.append({"n": n}, moq.Timestamp(n, 1_000)) record = await asyncio.wait_for(anext(consumer), timeout=5.0) - assert record == moq.json.Timed({"n": n}, None) + assert record == moq.json.Timed({"n": n}, moq.Timestamp(n, 1_000)) producer.finish() @@ -652,8 +652,9 @@ async def test_json_window_skips_records_outside_the_checkpoint(): async def test_json_producers_report_demand(): broadcast = moq.BroadcastProducer() - snapshot = moq.json.SnapshotProducer(broadcast, broadcast.publish_track("status", moq.TrackInfo(compress=True))) - stream = moq.json.StreamProducer(broadcast, broadcast.publish_track("events")) + timed = moq.TrackInfo(timescale=1_000, compress=True) + snapshot = moq.json.SnapshotProducer(broadcast, broadcast.publish_track("status", timed)) + stream = moq.json.StreamProducer(broadcast, broadcast.publish_track("events", timed)) snapshot_demand = snapshot.demand() stream_demand = stream.demand() assert snapshot_demand.name == "status" @@ -1757,12 +1758,12 @@ async def assert_cancelled(awaitable) -> None: pass await assert_cancelled(track_dynamic.requested_fill()) - snapshot = moq.json.SnapshotProducer(broadcast, broadcast.publish_track("state")) + snapshot = moq.json.SnapshotProducer(broadcast, broadcast.publish_track("state", moq.TrackInfo(timescale=1_000))) async with moq.json.SnapshotConsumer(await broadcast.consume().subscribe_track("state")) as snapshot_consumer: pass await assert_cancelled(anext(snapshot_consumer)) - stream = moq.json.StreamProducer(broadcast, broadcast.publish_track("log")) + stream = moq.json.StreamProducer(broadcast, broadcast.publish_track("log", moq.TrackInfo(timescale=1_000))) async with moq.json.StreamConsumer(await broadcast.consume().subscribe_track("log")) as stream_consumer: pass await assert_cancelled(anext(stream_consumer)) diff --git a/rs/moq-c/MIGRATE.md b/rs/moq-c/MIGRATE.md index 8a782e11d76..595ef244e55 100644 --- a/rs/moq-c/MIGRATE.md +++ b/rs/moq-c/MIGRATE.md @@ -4,6 +4,11 @@ How to update your code for each breaking change, newest first. ## Unreleased +### JSON writes refuse a NULL timestamp ([#7691](https://github.com/moq-dev/moq/pull/7691)) + +`moq_publish_json_snapshot_update` and `moq_publish_json_stream_append` fail with `MOQ_ERROR_INVALID_POINTER` and publish nothing on a NULL `timestamp`, instead of stamping the broadcast clock's current time. +Read the broadcast clock with the new `moq_publish_catalog_now(broadcast, &now)` and stamp both media frames and JSON writes from it, so every track shares its epoch; media on a timeline of its own advertises the gap to the JSON tracks as catalog `delay`. The JSON window calls still stamp a NULL timestamp. + ### JSON window edits take an optional timestamp `moq_publish_json_window_push` and `moq_publish_json_window_pop` take a final diff --git a/rs/moq-ffi/MIGRATE.md b/rs/moq-ffi/MIGRATE.md index 7f6f48e6d25..4af85698db9 100644 --- a/rs/moq-ffi/MIGRATE.md +++ b/rs/moq-ffi/MIGRATE.md @@ -5,6 +5,11 @@ These are the UniFFI names; each language wrapper has its own `MIGRATE.md` in it ## Unreleased +### JSON writes take a broadcast-clock timestamp ([#7691](https://github.com/moq-dev/moq/pull/7691)) + +`MoqJsonSnapshotProducer::update` and `MoqJsonStreamProducer::append` take a required `MoqTimestamp` instead of an optional one that defaulted to null. Stamp it on the broadcast clock, read with `MoqMediaCatalogProducer::now`, so the data shares the media's epoch. +Their constructors refuse a track created without a `timescale`: set one in `MoqTrackInfo`. `MoqJsonWindowProducer` is unchanged. + ### Announcement captures are required ([#7484](https://github.com/moq-dev/moq/pull/7484)) `MoqAnnounce.captures` is `Vec` instead of `Option>`. Remove optional checks and pass an empty list when constructing an announcement for a filter without wildcards. Regenerate bindings and rebuild the matching native library together. diff --git a/rs/moq-mux/MIGRATE.md b/rs/moq-mux/MIGRATE.md index d1522c7f1f0..7696cd5df8d 100644 --- a/rs/moq-mux/MIGRATE.md +++ b/rs/moq-mux/MIGRATE.md @@ -4,6 +4,12 @@ How to update your code for each breaking change, newest first. ## Unreleased +### JSON writes take a broadcast-clock timestamp ([#7691](https://github.com/moq-dev/moq/pull/7691)) + +`json::Snapshot::update` and `json::Stream::append` take `(&value, timestamp)`, a required `moq_net::Timestamp` on the broadcast clock, instead of `impl Into>`. Every track in a broadcast shares that clock's epoch, so nothing stamps a write for you. +Replace `update(&value)` and `update(Timed::from(&value).at(at))` with `update(&value, at)`, taking `at` from `catalog.clock().now()` or `catalog.clock().capture(instant)?`. +`catalog::Producer::json_snapshot` and `json_stream` refuse a track without a timescale with `Error::Moq(moq_net::Error::TimestampMismatch)`: create it with `moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI)`. + ### fMP4 decode errors are terminal After `container::fmp4::Import::decode` fails, later decodes, cuts, seeks and discontinuities return that error without reading input or changing tracks, including through `import::Container`. diff --git a/swift/MIGRATE.md b/swift/MIGRATE.md index 3ff5db0b9d9..9326362e649 100644 --- a/swift/MIGRATE.md +++ b/swift/MIGRATE.md @@ -4,6 +4,10 @@ How to update your code for each breaking change, newest first. ## Unreleased +### JSON writes take a broadcast-clock timestamp ([#7691](https://github.com/moq-dev/moq/pull/7691)) + +`Json.SnapshotProducer.update(_:timestamp:)` and `Json.StreamProducer.append(_:timestamp:)` require a `Timestamp` on the broadcast clock instead of defaulting to `nil`. Read it with `Media.CatalogProducer(broadcast:).now()`. Their track needs a timescale, such as `TrackInfo(timescale: 1000)`; one without is refused. + ### Announcement captures are required ([#7484](https://github.com/moq-dev/moq/pull/7484)) `Announce.captures` is `[String]` instead of `[String]?`. Remove optional checks and pass `captures: []` when constructing an announcement for a filter without wildcards. Rebuild with the matching MoqFFI package and native library. diff --git a/swift/Sources/Moq/Json.swift b/swift/Sources/Moq/Json.swift index c4717bb1c89..96b18e821ce 100644 --- a/swift/Sources/Moq/Json.swift +++ b/swift/Sources/Moq/Json.swift @@ -12,6 +12,10 @@ import MoqFFI /// /// Compression is the track's: publish JSON with `TrackInfo(compress: true)`, and a consumer reads /// it with no option of its own. +/// +/// Every snapshot update and stream append takes a timestamp on the broadcast clock, the epoch every +/// track in the broadcast shares: read it with `Media.CatalogProducer.now()`. Their track needs a +/// timescale (`TrackInfo(timescale: 1000)`); one without is refused. public enum Json {} extension Json { @@ -42,7 +46,7 @@ extension Json { /// Publish `track` as a JSON snapshot track, advertised in `broadcast`'s catalog until it /// finishes. Takes over `track`, whose handle is closed afterward; throws if the catalog - /// already carries the track's name. + /// already carries the track's name or `track` has no timescale. /// /// `deltas` encodes updates as merge-patch deltas; with it off every update is a full /// snapshot in its own group. With deltas on, give the track a `refresh` ratio so a joiner @@ -59,9 +63,9 @@ extension Json { ) } - /// Publish a new value, encoded as a snapshot or merge-patch delta automatically. A no-op - /// if unchanged from the previous update. - public func update(_ value: Value, timestamp: Timestamp? = nil) throws { + /// Publish a new value at `timestamp` on the broadcast clock, encoded as a snapshot or + /// merge-patch delta automatically. A no-op if unchanged from the previous update. + public func update(_ value: Value, timestamp: Timestamp) throws { try ffi.update(value: encodeJson(value), timestamp: timestamp) } @@ -123,13 +127,13 @@ extension Json { /// Publish `track` as a JSON stream track, advertised in `broadcast`'s catalog until it /// finishes. Takes over `track`, whose handle is closed afterward; throws if the catalog - /// already carries the track's name. + /// already carries the track's name or `track` has no timescale. public init(broadcast: BroadcastProducer, track: TrackProducer) throws { ffi = try MoqJsonStreamProducer(broadcast: broadcast.ffi, track: track.ffi) } - /// Append one record to the log. - public func append(_ value: Value, timestamp: Timestamp? = nil) throws { + /// Append one record to the log at `timestamp` on the broadcast clock. + public func append(_ value: Value, timestamp: Timestamp) throws { try ffi.append(value: encodeJson(value), timestamp: timestamp) } diff --git a/swift/Tests/MoqTests/SmokeTests.swift b/swift/Tests/MoqTests/SmokeTests.swift index bc090bcebb9..3a4496a3e72 100644 --- a/swift/Tests/MoqTests/SmokeTests.swift +++ b/swift/Tests/MoqTests/SmokeTests.swift @@ -444,14 +444,15 @@ final class SmokeTests: XCTestCase { let broadcast = try BroadcastProducer() let producer = try Json.StreamProducer( - broadcast: broadcast, track: try broadcast.publishTrack(name: "events")) + broadcast: broadcast, + track: try broadcast.publishTrack(name: "events", info: TrackInfo(timescale: 1_000_000))) let consumer = try Json.StreamConsumer( track: try await broadcast.consume().subscribeTrack(name: "events")) for n in 0..<3 { - try producer.append(Event(n: n)) + try producer.append(Event(n: n), timestamp: micros(UInt64(n) * 1000)) let record = try await consumer.next() - XCTAssertEqual(record, Json.Timed(value: Event(n: n), timestamp: nil)) + XCTAssertEqual(record, Json.Timed(value: Event(n: n), timestamp: micros(UInt64(n) * 1000))) } consumer.cancel() @@ -498,10 +499,11 @@ final class SmokeTests: XCTestCase { func testJsonProducersReportDemand() async throws { let broadcast = try BroadcastProducer() + let timed = TrackInfo(timescale: 1_000_000) let snapshot = try Json.SnapshotProducer<[String: Int]>( - broadcast: broadcast, track: try broadcast.publishTrack(name: "status")) + broadcast: broadcast, track: try broadcast.publishTrack(name: "status", info: timed)) let stream = try Json.StreamProducer<[String: Int]>( - broadcast: broadcast, track: try broadcast.publishTrack(name: "events")) + broadcast: broadcast, track: try broadcast.publishTrack(name: "events", info: timed)) let snapshotDemand = try snapshot.demand() let streamDemand = try stream.demand() XCTAssertEqual(snapshotDemand.name, "status") From 1f2f2edec3458a0f33fa93d6f526f6a2d1347ec0 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 2 Nov 2026 23:43:04 -0800 Subject: [PATCH 4/9] chore: format, document the timed JSON track, and finish the quest Co-Authored-By: Claude Opus 5.5 --- quest/m1/README.md | 1 - quest/m1/json-required-timestamp.md | 49 -------------------- rs/moq-c/src/publish.rs | 8 +++- rs/moq-c/src/test.rs | 11 ++--- rs/moq-ffi/src/test.rs | 8 ++-- rs/moq-mux/src/catalog/producer.rs | 11 +++-- rs/moq-mux/src/container/fmp4/import_test.rs | 4 +- rs/moq-mux/src/json.rs | 12 +---- 8 files changed, 27 insertions(+), 77 deletions(-) delete mode 100644 quest/m1/json-required-timestamp.md diff --git a/quest/m1/README.md b/quest/m1/README.md index ef568f55338..dbcdde97596 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -142,7 +142,6 @@ per-frame CPU growth since #5926. - [Cluster routing](/quest/m1/cluster-routing/README.md) - prove shared routing contracts, implement per-origin routes, and connect outbound local clusters - [Routing guide](/quest/m1/routing-guide.md) - concepts and practical outbound federation setup - [moq-c at parity](/quest/m1/c/README.md) - the hand-written `moq-c` ships at the cut with every m1 binding feature moq-ffi gains -- [JSON writes take a broadcast-clock timestamp](/quest/m1/json-required-timestamp.md) - every binding's JSON write requires one, moq-c's NULL fails, and C gains `moq_publish_catalog_now()`, so C media stops advertising an 8 s delay - [Catalog delay is the least a track trails](/quest/m1/catalog-delay-min.md) - the estimator keeps the minimum trail, so B-frame reorder never becomes `delay` - [Byte-stream renditions form a ladder](/quest/m1/stream-ladder.md) - moq-ffi stream producers link as `lower` and disable unfundable rungs like frame producers - [A job's exact route continues its claim's readers](/quest/m1/announce-takeover.md) - a job's route inherits its claim's instance, replacing the ANNOUNCE_TAKEOVER predecessor design diff --git a/quest/m1/json-required-timestamp.md b/quest/m1/json-required-timestamp.md deleted file mode 100644 index 5dc8e02f4dc..00000000000 --- a/quest/m1/json-required-timestamp.md +++ /dev/null @@ -1,49 +0,0 @@ -# [S] JSON writes take a broadcast-clock timestamp in every binding - -## Goal - -Every JSON snapshot update and stream append takes a required timestamp on -the broadcast clock: `moq_mux::json`'s `Snapshot` and `Stream`, moq-ffi's -JSON producers, and moq-c's `moq_publish_json_snapshot_update` and -`moq_publish_json_stream_append`, where a NULL timestamp fails instead of -being stamped with `now()`. moq-c gains `moq_publish_catalog_now()`, so a C -publisher stamps its media and its data in the broadcast clock's epoch. A C -publisher's JSON tracks no longer give its media an 8 s catalog `delay`. - -## Plan - -Reported in [moq-dev/moq#7573](https://github.com/moq-dev/moq/issues/7573) -and verified on `main`. moq-c stamps a NULL-timestamp JSON write with the -catalog clock's `now()` (`json_snapshot_update` and `json_stream_append` in -`rs/moq-c/src/publish.rs`). That write takes a seat in the catalog's write -`Order` against C media on the publisher's own timeline, so every media -track advertises the gap between the two timelines, about 8 s, as `delay`. -Rust and moq-ffi publish a null timestamp untimed instead, and moq-ffi -already exposes `MoqMediaCatalogProducer::now()`. - -Decided 2026-11-03 (maintainer, `/quest-import`): - -- Fix: require a timestamp, and expose `now()` to C, "because every track in - a broadcast needs to use the same epoch". Options were: NULL writes - unordered; ✅ require a timestamp (with C `now()`); won't fix. -- Scope: ✅ every binding in one quest; moq-c only; moq-c now and the others - later. -- This is the JSON part of - [time-addressing's required timestamps](/quest/m1/time-addressing/model.md), - which removes untimed writes everywhere. It lands first because #7573 is a - live bug. - -`moq_publish_catalog_now(broadcast, moq_timestamp *dst)` mirrors moq-ffi's -`now()`. `doc/lib/c` tells a C publisher to stamp media and timed data from -it. A NULL timestamp returns the invalid-argument error and publishes -nothing. Test that a C broadcast with JSON tracks advertises no `delay` on -its media, and that NULL fails, and update the moq-ffi and Rust JSON tests to -pass a timestamp. - -Public API: breaking in moq-c (NULL refused, `moq_publish_catalog_now` -added), moq-ffi (JSON `timestamp` required), and `moq_mux::json` (a write -takes a timestamp). Wire: none. - -## Closes - -- [#7573](https://github.com/moq-dev/moq/issues/7573) - moq-c JSON writes without a timestamp give every media track ~8 s of delay diff --git a/rs/moq-c/src/publish.rs b/rs/moq-c/src/publish.rs index 8efda89fa5b..c49b82b6c37 100644 --- a/rs/moq-c/src/publish.rs +++ b/rs/moq-c/src/publish.rs @@ -1588,11 +1588,15 @@ mod children_tests { } let json = serde_json::Value::Null; assert!(matches!( - state.publish.json_snapshot_update(json_snapshot, json.clone(), moq_net::Timestamp::ZERO), + state + .publish + .json_snapshot_update(json_snapshot, json.clone(), moq_net::Timestamp::ZERO), Err(Error::TrackNotFound) )); assert!(matches!( - state.publish.json_stream_append(json_stream, json, moq_net::Timestamp::ZERO), + state + .publish + .json_stream_append(json_stream, json, moq_net::Timestamp::ZERO), Err(Error::TrackNotFound) )); } diff --git a/rs/moq-c/src/test.rs b/rs/moq-c/src/test.rs index 008f4840e18..80dfcc91cb4 100644 --- a/rs/moq-c/src/test.rs +++ b/rs/moq-c/src/test.rs @@ -2602,12 +2602,7 @@ fn json_snapshot_publish_consume() { // Nothing stamps a write for the caller, so a NULL timestamp publishes nothing. assert_eq!( unsafe { - moq_publish_json_snapshot_update( - producer, - r#"{"a":0}"#.as_ptr() as *const c_char, - 7, - std::ptr::null(), - ) + moq_publish_json_snapshot_update(producer, r#"{"a":0}"#.as_ptr() as *const c_char, 7, std::ptr::null()) }, MOQ_ERROR_INVALID_POINTER ); @@ -2683,7 +2678,9 @@ fn json_stream_publish_consume() { ); let now = catalog_now(broadcast); assert_eq!( - unsafe { moq_publish_json_stream_append(producer, expected.as_ptr() as *const c_char, expected.len(), &now) }, + unsafe { + moq_publish_json_stream_append(producer, expected.as_ptr() as *const c_char, expected.len(), &now) + }, 0 ); let value_id = id(value_cb.recv()); diff --git a/rs/moq-ffi/src/test.rs b/rs/moq-ffi/src/test.rs index d675a20daeb..fad04175d7d 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -1359,8 +1359,7 @@ async fn data_writes_preserve_the_callers_timestamp() { match kind { "json snapshot" => { let producer = - MoqJsonSnapshotProducer::new(&broadcast, &track, MoqJsonSnapshotConfig { deltas: false }) - .unwrap(); + MoqJsonSnapshotProducer::new(&broadcast, &track, MoqJsonSnapshotConfig { deltas: false }).unwrap(); producer .update(String::from_utf8(payload.to_vec()).unwrap(), timestamp) .unwrap(); @@ -4797,7 +4796,10 @@ async fn closing_a_broadcast_ends_its_open_data_tracks() { assert!(matches!(json_snapshot.update("1".into(), us(0)), Err(MoqError::Closed))); assert!(matches!(json_stream.append("1".into(), us(0)), Err(MoqError::Closed))); - assert!(matches!(json_window.push("1".into(), Some(us(0))), Err(MoqError::Closed))); + assert!(matches!( + json_window.push("1".into(), Some(us(0))), + Err(MoqError::Closed) + )); } /// A data writer released without a finish ends its track as a publisher leaving. diff --git a/rs/moq-mux/src/catalog/producer.rs b/rs/moq-mux/src/catalog/producer.rs index d2b96b98a93..a8d335e3522 100644 --- a/rs/moq-mux/src/catalog/producer.rs +++ b/rs/moq-mux/src/catalog/producer.rs @@ -1080,8 +1080,10 @@ impl Producer { /// /// The caller creates the track on the broadcast, as it does for a media track; this writes its /// catalog entry and removes the entry when the returned handle drops. The catalog key is - /// [`track.name()`](moq_net::track::Producer::name) verbatim. Create `track` with - /// [`compress`](moq_net::track::Info::compress) set: JSON is small and repetitive. + /// [`track.name()`](moq_net::track::Producer::name) verbatim. Create `track` with a + /// [`timescale`](moq_net::track::Info::timescale), since every write is stamped on the + /// broadcast clock, and with [`compress`](moq_net::track::Info::compress) set: JSON is small and + /// repetitive. /// /// `config` is a [`json::Config`](crate::json::Config) for the `json` section, or an /// application's own entry embedding a [`JsonConfig`](hang::catalog::JsonConfig) (see @@ -1093,8 +1095,9 @@ impl Producer { /// [`Snapshot::refresh`](crate::json::Snapshot::refresh), so joiners get a fresh group. /// /// Errors if the entry's section already carries that name, for example an entry seeded - /// through [`Config::with_catalog`] or one pointing at a sibling broadcast, or if the entry - /// references another broadcast. + /// through [`Config::with_catalog`] or one pointing at a sibling broadcast, if the entry + /// references another broadcast, or with [`moq_net::Error::TimestampMismatch`] if `track` has no + /// timescale. pub fn json_snapshot( &self, track: moq_net::track::Producer, diff --git a/rs/moq-mux/src/container/fmp4/import_test.rs b/rs/moq-mux/src/container/fmp4/import_test.rs index 79e8dc06d6b..53c2bc9540f 100644 --- a/rs/moq-mux/src/container/fmp4/import_test.rs +++ b/rs/moq-mux/src/container/fmp4/import_test.rs @@ -2763,7 +2763,9 @@ async fn join_after(earlier: Earlier, start_us: u64) { fmp4.decode(&live_session(start_us, 20)).unwrap(); let after = clock.now().as_micros(); if let Some(stream) = data.as_mut() { - stream.append(&serde_json::json!("after"), catalog.clock().now()).unwrap(); + stream + .append(&serde_json::json!("after"), catalog.clock().now()) + .unwrap(); } fmp4.finish().unwrap(); diff --git a/rs/moq-mux/src/json.rs b/rs/moq-mux/src/json.rs index 4e3d69f0158..a83d23ef245 100644 --- a/rs/moq-mux/src/json.rs +++ b/rs/moq-mux/src/json.rs @@ -536,11 +536,7 @@ mod test { fn an_importer_joins_the_data_tracks_clock() { let (mut broadcast, catalog) = catalog(); let mut status = catalog - .json_snapshot::( - track(&mut broadcast, "status"), - Config::default(), - Options::default(), - ) + .json_snapshot::(track(&mut broadcast, "status"), Config::default(), Options::default()) .unwrap(); let mut chat = catalog .json_stream::(track(&mut broadcast, "chat"), Config::default()) @@ -723,11 +719,7 @@ mod test { .json_stream::(track(&mut broadcast, "gps"), Config::default()) .unwrap(); let mut status = catalog - .json_snapshot::( - track(&mut broadcast, "status"), - Config::default(), - Options::default(), - ) + .json_snapshot::(track(&mut broadcast, "status"), Config::default(), Options::default()) .unwrap(); let now = catalog.clock().now(); let value = serde_json::json!({ "armed": true }); From 792ddd907d8fbb7ab8b00f01aa782e5b025aefa7 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 2 Nov 2026 23:54:47 -0800 Subject: [PATCH 5/9] fix: Go callers, doc samples, and READMEs pass a JSON timestamp Co-Authored-By: Claude Opus 5.5 --- go/wrapper/README.md | 19 +++++++++++++------ go/wrapper/data_timestamps_test.go | 12 ++++++++---- py/moq-rs/README.md | 5 +++-- rs/moq-mux/src/json.rs | 4 ++-- swift/README.md | 4 +++- 5 files changed, 29 insertions(+), 15 deletions(-) diff --git a/go/wrapper/README.md b/go/wrapper/README.md index dc8f4550fba..94f16bc6776 100644 --- a/go/wrapper/README.md +++ b/go/wrapper/README.md @@ -114,20 +114,27 @@ carry every record in order. `NewWindowProducer` / `NewWindowConsumer` carry a s of records a reader can join at any point; the catalog has no window mode, so the producer takes only the track. Producers accept any `encoding/json` value; consumers return `json.RawMessage` so callers choose their own decoded type. -`Update` / `Append` / `Push` / `Pop` take a final `*moq.Timestamp` on the broadcast clock; nil publishes untimed. +`Update` / `Append` take a final `moq.Timestamp` on the broadcast clock, so their track needs a timescale; `Push` / `Pop` take a `*moq.Timestamp`, where nil publishes untimed. Raw tracks with a nil timescale are untimed; timed tracks require matching timestamps. -`media.CatalogProducer.Now()` samples and fixes the catalog clock for explicit local-event stamps. +`media.CatalogProducer.Now()` samples and fixes the broadcast clock, the epoch every track in the broadcast shares; stamp media and JSON from it. Opaque bytes go on a plain `TrackProducer`. ```go -import moqjson "moq.dev/moq/json" +import ( + moqjson "moq.dev/moq/json" + moqmedia "moq.dev/moq/media" +) publication, _ := client.CreateBroadcast("room") broadcast := publication.Broadcast() -// JSON is small and repetitive, so compress the track on the wire. -track, _ := broadcast.PublishTrack("status", &moq.TrackInfo{Compress: true}) +// Every JSON write is stamped, so the track is timed. JSON is small and repetitive, so +// compress it on the wire. +scale := uint64(1_000) +track, _ := broadcast.PublishTrack("status", &moq.TrackInfo{Timescale: &scale, Compress: true}) status, _ := moqjson.NewSnapshotProducer(broadcast, track, moqjson.SnapshotOptions{}) -_ = status.Update(map[string]any{"viewers": 42}, nil) +catalog, _ := moqmedia.NewCatalogProducer(broadcast) +now, _ := catalog.Now() +_ = status.Update(map[string]any{"viewers": 42}, now) _ = publication.Announce(moq.AnnounceRoute{}) ``` diff --git a/go/wrapper/data_timestamps_test.go b/go/wrapper/data_timestamps_test.go index ea45972d2d5..13ec9bba9c0 100644 --- a/go/wrapper/data_timestamps_test.go +++ b/go/wrapper/data_timestamps_test.go @@ -18,8 +18,9 @@ func ninetyKHz() *moq.TrackInfo { return &moq.TrackInfo{Timescale: &scale} } -// Every producer carries an exact timestamp, a present zero, or none at all, and -// the raw reader gets back exactly what was written. +// Every producer carries an exact timestamp or a present zero, a raw frame none at +// all too, and the raw reader gets back exactly what was written. JSON writes +// always take one, so they have no untimed case. func TestDataTimestamps(t *testing.T) { timestamps := []struct { name string @@ -31,6 +32,9 @@ func TestDataTimestamps(t *testing.T) { } for _, mode := range []string{"frame", "json snapshot", "json stream"} { for _, timestamp := range timestamps { + if timestamp.at == nil && mode != "frame" { + continue + } t.Run(mode+"/"+timestamp.name, func(t *testing.T) { ctx, cancel := context.WithTimeout(context.Background(), testTimeout) defer cancel() @@ -93,7 +97,7 @@ func publishData(mode string, broadcast *moq.BroadcastProducer, track *moq.Track if err != nil { return err } - if err := producer.Update(map[string]int{"n": 1}, timestamp); err != nil { + if err := producer.Update(map[string]int{"n": 1}, *timestamp); err != nil { return err } return producer.Finish() @@ -102,7 +106,7 @@ func publishData(mode string, broadcast *moq.BroadcastProducer, track *moq.Track if err != nil { return err } - if err := producer.Append(map[string]int{"n": 1}, timestamp); err != nil { + if err := producer.Append(map[string]int{"n": 1}, *timestamp); err != nil { return err } return producer.Finish() diff --git a/py/moq-rs/README.md b/py/moq-rs/README.md index a14ba3aabf9..ba63576471f 100644 --- a/py/moq-rs/README.md +++ b/py/moq-rs/README.md @@ -222,8 +222,9 @@ subscriber waits. `.cut()` / `.seek(sequence)` draw group boundaries; `.finish() ### Data -`moq.json.SnapshotProducer.update(value, timestamp=None)`, -`moq.json.StreamProducer.append(value, timestamp=None)`, and +`moq.json.SnapshotProducer.update(value, timestamp)` and +`moq.json.StreamProducer.append(value, timestamp)` require a capture time on the broadcast clock, +read with `media.CatalogProducer.now()`, so their track needs a `timescale`. `moq.json.WindowProducer.push(value, timestamp=None)` / `.pop(count, timestamp=None)` preserve optional capture time. A window keeps a sliding run of records a reader can join at any point, and `.cut()` ends its open group so the next edit opens one restating the window; the catalog has diff --git a/rs/moq-mux/src/json.rs b/rs/moq-mux/src/json.rs index a83d23ef245..fcaeac86ee5 100644 --- a/rs/moq-mux/src/json.rs +++ b/rs/moq-mux/src/json.rs @@ -22,8 +22,8 @@ //! # ) -> moq_mux::Result<()> { //! // A timed track, since every write is stamped. JSON is small and repetitive, so compress it. //! let info = moq_net::track::Info::default() -//! .with_timescale(moq_net::Timescale::MILLI) -//! .with_compress(true); +//! .with_timescale(moq_net::Timescale::MILLI) +//! .with_compress(true); //! let track = broadcast.create_track("chat", info)?; //! let mut chat = catalog.json_stream::(track, moq_mux::json::Config::default())?; //! chat.append(&Message { text: "hello".to_string() }, catalog.clock().now())?; diff --git a/swift/README.md b/swift/README.md index 84e51c90725..ef047889ea2 100644 --- a/swift/README.md +++ b/swift/README.md @@ -93,7 +93,9 @@ JSON tracks live under the `Json` namespace, mirroring the `moq-json` crate, and (lossless append-log, every record preserved in order), or `Json.WindowProducer`/`Json.WindowConsumer` (a sliding window of records a reader can join at any point, not advertised in the catalog). Values encode/decode at the boundary with `JSONEncoder`/`JSONDecoder`; the consumer is an `AsyncSequence` of the decoded type. Publish the -track with `TrackInfo(compress: true)`; consumers read it the same either way. +track with `TrackInfo(compress: true)`; consumers read it the same either way. Snapshot updates and +stream appends take a timestamp on the broadcast clock (`Media.CatalogProducer.now()`), so their +track needs a timescale. ## Local development From 4fc9445959a365f55c635f2dcf53cbfa802e9764 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 09:28:32 -0800 Subject: [PATCH 6/9] feat!: JSON window edits take a broadcast-clock timestamp too Co-Authored-By: Claude Opus 5.5 --- c/moq/MIGRATE.md | 2 +- cpp/moq/MIGRATE.md | 2 +- dart/moq/MIGRATE.md | 2 +- dart/moq/lib/json.dart | 7 ++- dart/moq_ffi/lib/src/moq.dart | 18 +++--- doc/lib/c/index.md | 2 +- doc/lib/dart/index.md | 2 +- doc/lib/go/index.md | 2 +- doc/lib/kt/index.md | 2 +- doc/lib/py/index.md | 2 +- doc/lib/swift/index.md | 2 +- go/wrapper/MIGRATE.md | 2 +- go/wrapper/README.md | 2 +- go/wrapper/json/json.go | 20 +++--- go/wrapper/json/json_test.go | 6 +- kt/moq/MIGRATE.md | 2 +- .../kotlin/dev/moq/json/Tracks.kt | 10 +-- py/moq-rs/MIGRATE.md | 2 +- py/moq-rs/README.md | 10 +-- py/moq-rs/moq/json.py | 21 ++++--- py/moq-rs/tests/test_local.py | 23 +++---- rs/moq-c/MIGRATE.md | 10 +-- rs/moq-c/src/api.rs | 16 ++--- rs/moq-c/src/publish.rs | 25 +++----- rs/moq-c/src/test.rs | 46 ++++++++++---- rs/moq-ffi/src/json.rs | 26 ++++---- rs/moq-ffi/src/test.rs | 63 ++++++++++++------- swift/MIGRATE.md | 2 +- swift/README.md | 4 +- swift/Sources/Moq/Json.swift | 18 +++--- 30 files changed, 194 insertions(+), 157 deletions(-) diff --git a/c/moq/MIGRATE.md b/c/moq/MIGRATE.md index 2db71895f7a..c455130e885 100644 --- a/c/moq/MIGRATE.md +++ b/c/moq/MIGRATE.md @@ -8,7 +8,7 @@ The hand-written crate never published as moq-c: a libmoq 0.6 user applies these ### JSON writes refuse a NULL timestamp ([#7691](https://github.com/moq-dev/moq/pull/7691)) -`moq_publish_json_snapshot_update` and `moq_publish_json_stream_append` fail with `MOQ_ERROR_INVALID_POINTER` on a NULL `timestamp` instead of stamping the broadcast clock. Stamp media and JSON from `moq_publish_catalog_now()`; in the generated API, JSON `update` and `append` take a required `moq_timestamp` from the media catalog producer's `now`, and refuse a track without a timescale. +`moq_publish_json_snapshot_update`, `moq_publish_json_stream_append`, `moq_publish_json_window_push`, and `moq_publish_json_window_pop` fail with `MOQ_ERROR_INVALID_POINTER` on a NULL `timestamp` instead of stamping the broadcast clock. Stamp media and JSON from `moq_publish_catalog_now()`; in the generated API, JSON `update`, `append`, `push`, and `pop` take a required `moq_timestamp` from the media catalog producer's `now`, and the JSON producers refuse a track without a timescale. ### Announcement captures are required ([#7484](https://github.com/moq-dev/moq/pull/7484)) diff --git a/cpp/moq/MIGRATE.md b/cpp/moq/MIGRATE.md index 8384eab0686..cbcf392adef 100644 --- a/cpp/moq/MIGRATE.md +++ b/cpp/moq/MIGRATE.md @@ -4,7 +4,7 @@ ### JSON writes take a broadcast-clock timestamp ([#7691](https://github.com/moq-dev/moq/pull/7691)) -`moq::JsonSnapshotProducer::update` and `moq::JsonStreamProducer::append` take a required `moq::Timestamp` instead of an optional one. Stamp it from `moq::MediaCatalogProducer::now()`, the broadcast clock every track shares. Their constructors refuse a track created without a `timescale`. Regenerate bindings and rebuild with the matching native library. +`moq::JsonSnapshotProducer::update`, `moq::JsonStreamProducer::append`, and `moq::JsonWindowProducer::push` and `pop` take a required `moq::Timestamp` instead of an optional one. Stamp it from `moq::MediaCatalogProducer::now()`, the broadcast clock every track shares. Their constructors refuse a track created without a `timescale`. Regenerate bindings and rebuild with the matching native library. ### Announcement captures are required ([#7484](https://github.com/moq-dev/moq/pull/7484)) diff --git a/dart/moq/MIGRATE.md b/dart/moq/MIGRATE.md index e2dd3aaa85f..4361724c2fd 100644 --- a/dart/moq/MIGRATE.md +++ b/dart/moq/MIGRATE.md @@ -6,7 +6,7 @@ How to update your code for each breaking change, newest first. ### JSON writes take a broadcast-clock timestamp ([#7691](https://github.com/moq-dev/moq/pull/7691)) -`json.SnapshotProducer.update` and `json.StreamProducer.append` take a `required MoqTimestamp timestamp` on the broadcast clock instead of an optional one. Read it with `MoqMediaCatalogProducer(broadcast: broadcast).now()`. Their track needs a timescale, such as `MoqTrackInfo(timescale: 1000)`; one without is refused. +`json.SnapshotProducer.update`, `json.StreamProducer.append`, and `json.WindowProducer.push` / `pop` take a `required MoqTimestamp timestamp` on the broadcast clock instead of an optional one. Read it with `MoqMediaCatalogProducer(broadcast: broadcast).now()`. Their track needs a timescale, such as `MoqTrackInfo(timescale: 1000)`; one without is refused. ### `Transport.iroh` is removed ([#7345](https://github.com/moq-dev/moq/pull/7345)) diff --git a/dart/moq/lib/json.dart b/dart/moq/lib/json.dart index afc35f1d5d0..2ede41f88b8 100644 --- a/dart/moq/lib/json.dart +++ b/dart/moq/lib/json.dart @@ -5,9 +5,10 @@ /// which has no window mode), and a consumer takes over a `TrackConsumer` that /// has not read a group yet. Values cross as JSON strings. Compression is the /// track's: publish JSON with `MoqTrackInfo(compress: true)`, and a consumer -/// reads it with no option of its own. Every snapshot update and stream append -/// takes a timestamp on the broadcast clock, the epoch every track in the -/// broadcast shares, so their track needs a timescale; one without is refused. +/// reads it with no option of its own. Every write (a snapshot update, a stream +/// append, a window push or pop) takes a timestamp on the broadcast clock, the +/// epoch every track in the broadcast shares, so the track needs a timescale; +/// one without is refused. /// Import it with a prefix, since `dart:convert` has a `json` too: /// /// ```dart diff --git a/dart/moq_ffi/lib/src/moq.dart b/dart/moq_ffi/lib/src/moq.dart index df6f7070990..3aff45330aa 100644 --- a/dart/moq_ffi/lib/src/moq.dart +++ b/dart/moq_ffi/lib/src/moq.dart @@ -11126,8 +11126,8 @@ abstract class MoqJsonWindowProducerInterface { void cut(); MoqTrackDemand demand(); void finish(); - void pop({required int count, MoqTimestamp? timestamp = null}); - void push({required String value, MoqTimestamp? timestamp = null}); + void pop({required int count, required MoqTimestamp timestamp}); + void push({required String value, required MoqTimestamp timestamp}); } final _MoqJsonWindowProducerFinalizer = Finalizer>((ptr) { @@ -11211,23 +11211,23 @@ class MoqJsonWindowProducer implements MoqJsonWindowProducerInterface { }, moqExceptionErrorHandler); } - void pop({required int count, MoqTimestamp? timestamp = null}) { + void pop({required int count, required MoqTimestamp timestamp}) { return rustCall((status) { uniffi_moq_ffi_fn_method_moqjsonwindowproducer_pop( uniffiClonePointer(), FfiConverterUInt64.lower(count), - FfiConverterOptionalMoqTimestamp.lower(timestamp), + FfiConverterMoqTimestamp.lower(timestamp), status, ); }, moqExceptionErrorHandler); } - void push({required String value, MoqTimestamp? timestamp = null}) { + void push({required String value, required MoqTimestamp timestamp}) { return rustCall((status) { uniffi_moq_ffi_fn_method_moqjsonwindowproducer_push( uniffiClonePointer(), FfiConverterString.lower(value), - FfiConverterOptionalMoqTimestamp.lower(timestamp), + FfiConverterMoqTimestamp.lower(timestamp), status, ); }, moqExceptionErrorHandler); @@ -21982,10 +21982,10 @@ void _checkApiChecksums() { if (uniffi_moq_ffi_checksum_method_moqjsonwindowproducer_finish() != 49018) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqjsonwindowproducer_pop() != 58245) { + if (uniffi_moq_ffi_checksum_method_moqjsonwindowproducer_pop() != 24069) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqjsonwindowproducer_push() != 47237) { + if (uniffi_moq_ffi_checksum_method_moqjsonwindowproducer_push() != 56727) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqmediacatalogconsumer_cancel() != @@ -22452,7 +22452,7 @@ void _checkApiChecksums() { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_constructor_moqjsonwindowproducer_new() != - 43418) { + 34390) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_constructor_moqmediacatalogconsumer_subscribe() != diff --git a/doc/lib/c/index.md b/doc/lib/c/index.md index 9e16f9a21df..0484a9ecab9 100644 --- a/doc/lib/c/index.md +++ b/doc/lib/c/index.md @@ -110,7 +110,7 @@ inside. The header is the reference: each function carries a doc comment. - **Discovery.** Announcement captures are always a list of wildcard matches, empty when the filter has no wildcards. - **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()` 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, NULL on an untimed track and valid as long as the payload. Tracks moq-c creates are timed, so their raw writes need one. 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 `moq_publish_json_snapshot_update` or `moq_publish_json_stream_append` fails with `MOQ_ERROR_INVALID_POINTER`, while a window push or pop stamps the broadcast clock's current time. A zero scale or an out-of-range value fails with `MOQ_ERROR_TIMESTAMP_OVERFLOW`. +- **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, NULL on an untimed track and valid as long as the payload. Tracks moq-c creates are timed, so their raw writes need one. 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 JSON write (snapshot update, stream append, window push or pop) fails with `MOQ_ERROR_INVALID_POINTER` and publishes nothing. A zero scale or an out-of-range value fails with `MOQ_ERROR_TIMESTAMP_OVERFLOW`. - **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. diff --git a/doc/lib/dart/index.md b/doc/lib/dart/index.md index 2e2fc431118..8a48cf6f43e 100644 --- a/doc/lib/dart/index.md +++ b/doc/lib/dart/index.md @@ -19,7 +19,7 @@ and a `Named` or `Requested` target. `CatalogProducer(broadcast: ...)` owns cata and sections; it holds the broadcast weakly and fails after the broadcast closes. Publish JSON tracks with `MoqTrackInfo(compress: true)`; a `package:moq/json.dart` consumer reads one with no option of its own. A missing data timestamp stays untimed; the library never substitutes zero or now. -`SnapshotProducer.update` and `StreamProducer.append` require a timestamp on the broadcast clock (`CatalogProducer.now()`), the epoch every track in the broadcast shares, so their track needs a timescale. +`SnapshotProducer.update`, `StreamProducer.append`, and `WindowProducer.push` and `pop` require a timestamp on the broadcast clock (`CatalogProducer.now()`), the epoch every track in the broadcast shares, so their track needs a timescale. `package:moq/json.dart` consumers return `Value` (`value`, `timestamp`) from `next()`; a snapshot consumer yields each state in order, and `latest()` skips to the newest. Media times are exact `Timestamp` records, `value` units at `scale` units per second, so a 90 kHz tick survives a diff --git a/doc/lib/go/index.md b/doc/lib/go/index.md index afc53126f85..4e7b3efc8c5 100644 --- a/doc/lib/go/index.md +++ b/doc/lib/go/index.md @@ -22,7 +22,7 @@ catalog writes fail with `ErrClosed` after the broadcast closes. Media timestamp A missing data timestamp stays untimed; the library never substitutes zero or now. Raw tracks with a `nil` timescale are untimed on both publish and receive. `TrackInfo.Compress` sends each group DEFLATE-compressed to opt-in `moq-lite-07-wip` peers; other peers, and every reader here, get the original frames. Set it on JSON tracks. -The JSON snapshot and stream producers' `Update` / `Append` take a final `moq.Timestamp` on the broadcast clock, the epoch every track in the broadcast shares, so their track needs a timescale. +The JSON producers' `Update`, `Append`, `Push`, and `Pop` take a final `moq.Timestamp` on the broadcast clock, the epoch every track in the broadcast shares, so their track needs a timescale. JSON consumers return a `*Timed` holding the value and that timestamp; `SnapshotConsumer.Latest` skips to the newest state where `Next` yields each one. A read timestamp is at the track's timescale. Whole-frame media writes require caller time; container imports keep their own timeline handling. diff --git a/doc/lib/kt/index.md b/doc/lib/kt/index.md index d6f931c5cf9..77610bc41d1 100644 --- a/doc/lib/kt/index.md +++ b/doc/lib/kt/index.md @@ -18,7 +18,7 @@ x86\_64) and desktop JVM (Linux x86\_64/aarch64, macOS arm64, Windows x64). `CatalogProducer(broadcast)` holds its broadcast weakly and fails with `Closed` after it closes. Publish JSON tracks with `TrackInfo(compress = true)`; a `dev.moq.json` consumer reads one with no option of its own. A missing data timestamp stays untimed; the library never substitutes zero or now. -`SnapshotProducer.update` and `StreamProducer.append` require a timestamp on the broadcast clock (`CatalogProducer.now()`), the epoch every track in the broadcast shares, so their track needs a timescale. +`SnapshotProducer.update`, `StreamProducer.append`, and `WindowProducer.push` and `pop` require a timestamp on the broadcast clock (`CatalogProducer.now()`), the epoch every track in the broadcast shares, so their track needs a timescale. `dev.moq.json` consumers' `values()` emits `Value` (`value`, `timestamp`) and `valuesAs()` emits `Timed`; a snapshot consumer yields each state in order, and `latest()` skips to the newest. A `Timestamp(value, scale)` is exact and reads back at the track's timescale, so a 90 kHz tick republishes unchanged. diff --git a/doc/lib/py/index.md b/doc/lib/py/index.md index 8d1f2487fea..687868afede 100644 --- a/doc/lib/py/index.md +++ b/doc/lib/py/index.md @@ -29,7 +29,7 @@ JSON consumers yield `moq.json.Timed(value, timestamp)`; a snapshot consumer yie and `await consumer.latest()` skips to the newest. A window consumer's value is a `WindowPush`, `WindowPop`, or `WindowSkip`. Raw tracks with a `None` timescale are untimed on both publish and receive. `TrackInfo(compress=True)` sends each group DEFLATE-compressed to opt-in `moq-lite-07-wip` peers; other peers, and every reader here, get the original frames. Set it on JSON tracks. -The JSON snapshot and stream producers' `update` / `append` require a `timestamp` on the broadcast clock, the epoch every track in the broadcast shares, so their track needs a timescale. +The JSON producers' `update`, `append`, `push`, and `pop` require a `timestamp` on the broadcast clock, the epoch every track in the broadcast shares, so their track needs a timescale. Whole-frame media writes require caller time; container imports keep their own timeline handling. Timed raw/data tracks require caller-supplied timestamps. Use `CatalogProducer.now()` to stamp a locally created event on the broadcast clock; reading it fixes that clock for later media producers. diff --git a/doc/lib/swift/index.md b/doc/lib/swift/index.md index 6dd79412e01..bc0bad88440 100644 --- a/doc/lib/swift/index.md +++ b/doc/lib/swift/index.md @@ -22,7 +22,7 @@ Media timestamps are exact `Timestamp` records, `value` units at `scale` units p and `try timestamp.duration` rounds down to a whole attosecond. Publish JSON tracks with `TrackInfo(compress: true)`; a `Json` consumer reads one with no option of its own. A missing data timestamp stays untimed; the library never substitutes zero or now. -`Json.SnapshotProducer.update` and `Json.StreamProducer.append` require a timestamp on the broadcast clock (`Media.CatalogProducer.now()`), the epoch every track in the broadcast shares, so their track needs a timescale. +`Json.SnapshotProducer.update`, `Json.StreamProducer.append`, and `Json.WindowProducer.push` and `pop` require a timestamp on the broadcast clock (`Media.CatalogProducer.now()`), the epoch every track in the broadcast shares, so their track needs a timescale. `Json` consumers yield `Json.Timed` (`value`, `timestamp`); a snapshot consumer yields each state in order, and `latest()` skips to the newest. Raw tracks with a `nil` timescale are untimed on both publish and receive. diff --git a/go/wrapper/MIGRATE.md b/go/wrapper/MIGRATE.md index 1a7588f46ec..518cedd65d6 100644 --- a/go/wrapper/MIGRATE.md +++ b/go/wrapper/MIGRATE.md @@ -6,7 +6,7 @@ How to update your code for each breaking change, newest first. ### JSON writes take a broadcast-clock timestamp ([#7691](https://github.com/moq-dev/moq/pull/7691)) -`json.SnapshotProducer.Update` and `json.StreamProducer.Append` take a `moq.Timestamp` instead of a `*moq.Timestamp`, so there is no untimed write. Stamp it from `media.CatalogProducer.Now()`, the broadcast clock every track shares. Their track needs a `TrackInfo.Timescale`; one without is refused. +`json.SnapshotProducer.Update`, `json.StreamProducer.Append`, and `json.WindowProducer.Push` / `Pop` take a `moq.Timestamp` instead of a `*moq.Timestamp`, so there is no untimed write. Stamp it from `media.CatalogProducer.Now()`, the broadcast clock every track shares. Their track needs a `TrackInfo.Timescale`; one without is refused. ### `media.VideoInit` is a struct diff --git a/go/wrapper/README.md b/go/wrapper/README.md index 94f16bc6776..4ef501f19bc 100644 --- a/go/wrapper/README.md +++ b/go/wrapper/README.md @@ -114,7 +114,7 @@ carry every record in order. `NewWindowProducer` / `NewWindowConsumer` carry a s of records a reader can join at any point; the catalog has no window mode, so the producer takes only the track. Producers accept any `encoding/json` value; consumers return `json.RawMessage` so callers choose their own decoded type. -`Update` / `Append` take a final `moq.Timestamp` on the broadcast clock, so their track needs a timescale; `Push` / `Pop` take a `*moq.Timestamp`, where nil publishes untimed. +`Update` / `Append` / `Push` / `Pop` take a final `moq.Timestamp` on the broadcast clock, so their track needs a timescale. Raw tracks with a nil timescale are untimed; timed tracks require matching timestamps. `media.CatalogProducer.Now()` samples and fixes the broadcast clock, the epoch every track in the broadcast shares; stamp media and JSON from it. Opaque bytes go on a plain `TrackProducer`. diff --git a/go/wrapper/json/json.go b/go/wrapper/json/json.go index 809be5b44b8..085db76b305 100644 --- a/go/wrapper/json/json.go +++ b/go/wrapper/json/json.go @@ -6,10 +6,10 @@ // over a [moq.TrackConsumer] that has not read a group yet. The track can come // from a request as well as by name. Compression is the track's: publish JSON // with [moq.TrackInfo] Compress set, and a consumer reads it with no option of -// its own. Every snapshot update and stream append takes a timestamp on the -// broadcast clock, the epoch every track in the broadcast shares (read it with -// media.CatalogProducer.Now), so their track needs a [moq.TrackInfo] Timescale; -// one without is refused. Import it under an alias next to encoding/json: +// its own. Every write (a snapshot update, a stream append, a window push or +// pop) takes a timestamp on the broadcast clock, the epoch every track in the +// broadcast shares (read it with media.CatalogProducer.Now), so the track needs +// a [moq.TrackInfo] Timescale; one without is refused. Import it under an alias next to encoding/json: // // import moqjson "moq.dev/moq/json" package json @@ -230,8 +230,8 @@ type WindowProducer struct { // NewWindowProducer publishes track as a JSON window track. The window rolls to // new groups that restate the records it retains, so a reader can join at any // point; give the track a refresh ratio so a joiner past it gets a fresh group. -// It takes over track, whose handle is closed afterward. It is not advertised in -// the catalog, which has no window mode. +// It takes over track, whose handle is closed afterward, and fails if track has +// no timescale. It is not advertised in the catalog, which has no window mode. func NewWindowProducer(track *moq.TrackProducer, options WindowOptions) (*WindowProducer, error) { inner, err := ffi.NewMoqJsonWindowProducer( bridge.TrackProducer(track), @@ -243,8 +243,8 @@ func NewWindowProducer(track *moq.TrackProducer, options WindowOptions) (*Window return &WindowProducer{inner: inner}, nil } -// Push appends one JSON record at timestamp on the broadcast clock; nil is untimed. -func (p *WindowProducer) Push(value any, timestamp *moq.Timestamp) error { +// Push appends one JSON record at timestamp on the broadcast clock. +func (p *WindowProducer) Push(value any, timestamp moq.Timestamp) error { encoded, err := stdjson.Marshal(value) if err != nil { return err @@ -253,8 +253,8 @@ func (p *WindowProducer) Push(value any, timestamp *moq.Timestamp) error { } // Pop drops count records from the front of the window, clamped to what it holds, -// at timestamp on the broadcast clock; nil is untimed. -func (p *WindowProducer) Pop(count uint64, timestamp *moq.Timestamp) error { +// at timestamp on the broadcast clock. +func (p *WindowProducer) Pop(count uint64, timestamp moq.Timestamp) error { return p.inner.Pop(count, timestamp) } diff --git a/go/wrapper/json/json_test.go b/go/wrapper/json/json_test.go index 2acbbaed1fe..df60fb57ee6 100644 --- a/go/wrapper/json/json_test.go +++ b/go/wrapper/json/json_test.go @@ -155,11 +155,11 @@ func TestWindow(t *testing.T) { return &moq.Timestamp{Value: uint64(n) * 1000, Scale: scale} } for n := range 3 { - if err := window.Push(map[string]any{"n": n}, ms(n)); err != nil { + if err := window.Push(map[string]any{"n": n}, *ms(n)); err != nil { t.Fatal(err) } } - if err := window.Pop(2, ms(3)); err != nil { + if err := window.Pop(2, *ms(3)); err != nil { t.Fatal(err) } @@ -183,7 +183,7 @@ func TestWindow(t *testing.T) { if err := window.Cut(); err != nil { t.Fatal(err) } - if err := window.Push(map[string]any{"n": 3}, ms(4)); err != nil { + if err := window.Push(map[string]any{"n": 3}, *ms(4)); err != nil { t.Fatal(err) } if err := window.Finish(); err != nil { diff --git a/kt/moq/MIGRATE.md b/kt/moq/MIGRATE.md index 61bef30f2b2..06b361caa96 100644 --- a/kt/moq/MIGRATE.md +++ b/kt/moq/MIGRATE.md @@ -6,7 +6,7 @@ How to update your code for each breaking change, newest first. ### JSON writes take a broadcast-clock timestamp ([#7691](https://github.com/moq-dev/moq/pull/7691)) -`json.SnapshotProducer.update(value, timestamp)` and `json.StreamProducer.append(value, timestamp)` require a `Timestamp` on the broadcast clock instead of defaulting to null, for both the typed and the `String` overloads. Read it with `media.CatalogProducer(broadcast).now()`. Their track needs a timescale, such as `TrackInfo(timescale = 1_000uL)`; one without is refused. +`json.SnapshotProducer.update(value, timestamp)`, `json.StreamProducer.append(value, timestamp)`, and `json.WindowProducer.push(value, timestamp)` / `pop(count, timestamp)` require a `Timestamp` on the broadcast clock instead of defaulting to null, for both the typed and the `String` overloads. Read it with `media.CatalogProducer(broadcast).now()`. Their track needs a timescale, such as `TrackInfo(timescale = 1_000uL)`; one without is refused. ### Announcement captures are required ([#7484](https://github.com/moq-dev/moq/pull/7484)) diff --git a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/json/Tracks.kt b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/json/Tracks.kt index 2a61e840d93..4c1f1b37b26 100644 --- a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/json/Tracks.kt +++ b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/json/Tracks.kt @@ -5,9 +5,9 @@ package dev.moq.json // producers also advertise it in the broadcast's catalog, which has no window // mode), and a consumer takes over a `dev.moq.TrackConsumer` that has not read // a group yet. Compression is the track's, set through `TrackInfo(compress = true)`. -// Every snapshot update and stream append takes a timestamp on the broadcast -// clock, the epoch every track in the broadcast shares, so their track needs a -// timescale; one without is refused: +// Every write (a snapshot update, a stream append, a window push or pop) takes a +// timestamp on the broadcast clock, the epoch every track in the broadcast +// shares, so the track needs a timescale; one without is refused: // // val track = broadcast.publishTrack("status", TrackInfo(timescale = 1_000uL, compress = true)) // val status = SnapshotProducer(broadcast, track, SnapshotConfig()) @@ -88,8 +88,8 @@ inline fun StreamProducer.append(value: T, timestamp: Timestamp) { append(MoqJson.encodeToString(serializer(), value), timestamp) } -/** Push [value] onto the window at [timestamp] on the broadcast clock; null is untimed. */ -inline fun WindowProducer.push(value: T, timestamp: Timestamp? = null) { +/** Push [value] onto the window at [timestamp] on the broadcast clock. */ +inline fun WindowProducer.push(value: T, timestamp: Timestamp) { push(MoqJson.encodeToString(serializer(), value), timestamp) } diff --git a/py/moq-rs/MIGRATE.md b/py/moq-rs/MIGRATE.md index d05f0bf3ac6..3cc2233b2ee 100644 --- a/py/moq-rs/MIGRATE.md +++ b/py/moq-rs/MIGRATE.md @@ -6,7 +6,7 @@ How to update your code for each breaking change, newest first. ### JSON writes take a broadcast-clock timestamp ([#7691](https://github.com/moq-dev/moq/pull/7691)) -`json.SnapshotProducer.update(value, timestamp)` and `json.StreamProducer.append(value, timestamp)` require a `Timestamp` on the broadcast clock instead of an optional `timestamp=` keyword. Read it with `media.CatalogProducer(broadcast).now()`. Their track needs a timescale, such as `TrackInfo(timescale=1_000)`; one without is refused. +`json.SnapshotProducer.update(value, timestamp)`, `json.StreamProducer.append(value, timestamp)`, and `json.WindowProducer.push(value, timestamp)` / `pop(count, timestamp)` require a `Timestamp` on the broadcast clock instead of an optional `timestamp=` keyword. Read it with `media.CatalogProducer(broadcast).now()`. Their track needs a timescale, such as `TrackInfo(timescale=1_000)`; one without is refused. ### Announcement captures are required ([#7484](https://github.com/moq-dev/moq/pull/7484)) diff --git a/py/moq-rs/README.md b/py/moq-rs/README.md index ba63576471f..5a25b1a1d38 100644 --- a/py/moq-rs/README.md +++ b/py/moq-rs/README.md @@ -222,11 +222,11 @@ subscriber waits. `.cut()` / `.seek(sequence)` draw group boundaries; `.finish() ### Data -`moq.json.SnapshotProducer.update(value, timestamp)` and -`moq.json.StreamProducer.append(value, timestamp)` require a capture time on the broadcast clock, -read with `media.CatalogProducer.now()`, so their track needs a `timescale`. -`moq.json.WindowProducer.push(value, timestamp=None)` / `.pop(count, timestamp=None)` preserve -optional capture time. A window keeps a sliding run of records a reader can join at any point, +`moq.json.SnapshotProducer.update(value, timestamp)`, +`moq.json.StreamProducer.append(value, timestamp)`, and +`moq.json.WindowProducer.push(value, timestamp)` / `.pop(count, timestamp)` require a capture time +on the broadcast clock, read with `media.CatalogProducer.now()`, so their track needs a `timescale`. +A window keeps a sliding run of records a reader can join at any point, and `.cut()` ends its open group so the next edit opens one restating the window; the catalog has no window mode, so `WindowProducer` takes only the track. Omitting time leaves data untimed; choose the track's `timescale` to match. Publish JSON tracks with diff --git a/py/moq-rs/moq/json.py b/py/moq-rs/moq/json.py index 546988a2d5c..4c229a7e26a 100644 --- a/py/moq-rs/moq/json.py +++ b/py/moq-rs/moq/json.py @@ -9,9 +9,10 @@ Compression is the track's: publish it with ``TrackInfo(compress=True)``, which JSON benefits from, and a consumer reads it with no option of its own. -Every snapshot update and stream append takes a timestamp on the broadcast clock, the epoch every -track in the broadcast shares: read it with :meth:`moq.media.CatalogProducer.now`. Their track -needs a timescale (``TrackInfo(timescale=1000)``); one without is refused. +Every write (a snapshot update, a stream append, a window push or pop) takes a timestamp on the +broadcast clock, the epoch every track in the broadcast shares: read it with +:meth:`moq.media.CatalogProducer.now`. The track needs a timescale (``TrackInfo(timescale=1000)``); +one without is refused. """ from __future__ import annotations @@ -35,7 +36,7 @@ ) from . import publish, subscribe -from ._records import Timestamp, _opt_from_ts, _opt_ts +from ._records import Timestamp, _opt_from_ts from ._stream import _Stream from .publish import BroadcastProducer, TrackDemand @@ -198,13 +199,13 @@ def demand(self) -> TrackDemand: """A watch-only handle to whether this track has subscribers.""" return TrackDemand(self._inner.demand()) - def push(self, value: Any, *, timestamp: Timestamp | None = None) -> None: - """Append one record to the back of the window.""" - self._inner.push(json.dumps(value), _opt_ts(timestamp)) + def push(self, value: Any, timestamp: Timestamp) -> None: + """Append one record to the back of the window at ``timestamp`` on the broadcast clock.""" + self._inner.push(json.dumps(value), timestamp._ffi()) - def pop(self, count: int, *, timestamp: Timestamp | None = None) -> None: - """Drop ``count`` records from the front of the window, clamped to what it holds.""" - self._inner.pop(count, _opt_ts(timestamp)) + def pop(self, count: int, timestamp: Timestamp) -> None: + """Drop ``count`` records from the front of the window at ``timestamp``, clamped to what it holds.""" + self._inner.pop(count, timestamp._ffi()) def cut(self) -> None: """Close the open group, so the next edit opens one restating the retained window. diff --git a/py/moq-rs/tests/test_local.py b/py/moq-rs/tests/test_local.py index da70ae6b1f2..780df0bd867 100644 --- a/py/moq-rs/tests/test_local.py +++ b/py/moq-rs/tests/test_local.py @@ -574,8 +574,8 @@ async def test_json_window_roundtrip(): await asyncio.wait_for(until_wanted(demand), timeout=5.0) for n in range(3): - producer.push({"n": n}, timestamp=moq.Timestamp(n, 1_000)) - producer.pop(2, timestamp=moq.Timestamp(3, 1_000)) + producer.push({"n": n}, moq.Timestamp(n, 1_000)) + producer.pop(2, moq.Timestamp(3, 1_000)) for n in range(3): event = await asyncio.wait_for(anext(consumer), timeout=5.0) @@ -585,19 +585,19 @@ async def test_json_window_roundtrip(): producer.finish() with pytest.raises(moq.Error.Closed): - producer.push({"n": 3}, timestamp=moq.Timestamp(4, 1_000)) + producer.push({"n": 3}, moq.Timestamp(4, 1_000)) assert [event async for event in consumer] == [] async def test_json_window_cut_restates_the_window(): broadcast = moq.BroadcastProducer() - producer = moq.json.WindowProducer(broadcast.publish_track("log")) + producer = moq.json.WindowProducer(broadcast.publish_track("log", moq.TrackInfo(timescale=1_000))) raw = await broadcast.consume().subscribe_track("log") consumer = moq.json.WindowConsumer(await broadcast.consume().subscribe_track("log")) for n in range(3): - producer.push({"n": n}) - producer.pop(1) + producer.push({"n": n}, moq.Timestamp(n, 1_000)) + producer.pop(1, moq.Timestamp(3, 1_000)) events = [(await asyncio.wait_for(anext(consumer), timeout=5.0)).value for _ in range(4)] assert events == [ moq.json.WindowPush(0, {"n": 0}), @@ -607,7 +607,7 @@ async def test_json_window_cut_restates_the_window(): ] producer.cut() - producer.push({"n": 3}) + producer.push({"n": 3}, moq.Timestamp(4, 1_000)) while True: group = await asyncio.wait_for(raw.recv_group(), timeout=5.0) assert group is not None @@ -625,9 +625,10 @@ async def test_json_window_cut_restates_the_window(): async def test_json_window_skips_records_outside_the_checkpoint(): broadcast = moq.BroadcastProducer() - producer = moq.json.WindowProducer(broadcast.publish_track("log", moq.TrackInfo(refresh=1)), checkpoint_records=2) + track = broadcast.publish_track("log", moq.TrackInfo(refresh=1, timescale=1_000)) + producer = moq.json.WindowProducer(track, checkpoint_records=2) for n in range(5): - producer.push({"n": n}) + producer.push({"n": n}, moq.Timestamp(n, 1_000)) # The join crosses the refresh ratio, so the producer restates the bounded checkpoint. joiner = await broadcast.consume().subscribe_track("log") @@ -647,7 +648,7 @@ async def test_json_window_skips_records_outside_the_checkpoint(): producer.finish() with pytest.raises(moq.Error.JsonTrack): - moq.json.WindowProducer(broadcast.publish_track("bad"), checkpoint_records=0) + moq.json.WindowProducer(broadcast.publish_track("bad", moq.TrackInfo(timescale=1_000)), checkpoint_records=0) async def test_json_producers_report_demand(): @@ -1768,7 +1769,7 @@ async def assert_cancelled(awaitable) -> None: pass await assert_cancelled(anext(stream_consumer)) - window = moq.json.WindowProducer(broadcast.publish_track("window")) + window = moq.json.WindowProducer(broadcast.publish_track("window", moq.TrackInfo(timescale=1_000))) async with moq.json.WindowConsumer(await broadcast.consume().subscribe_track("window")) as window_consumer: pass await assert_cancelled(anext(window_consumer)) diff --git a/rs/moq-c/MIGRATE.md b/rs/moq-c/MIGRATE.md index 595ef244e55..029f6adf511 100644 --- a/rs/moq-c/MIGRATE.md +++ b/rs/moq-c/MIGRATE.md @@ -6,14 +6,14 @@ How to update your code for each breaking change, newest first. ### JSON writes refuse a NULL timestamp ([#7691](https://github.com/moq-dev/moq/pull/7691)) -`moq_publish_json_snapshot_update` and `moq_publish_json_stream_append` fail with `MOQ_ERROR_INVALID_POINTER` and publish nothing on a NULL `timestamp`, instead of stamping the broadcast clock's current time. -Read the broadcast clock with the new `moq_publish_catalog_now(broadcast, &now)` and stamp both media frames and JSON writes from it, so every track shares its epoch; media on a timeline of its own advertises the gap to the JSON tracks as catalog `delay`. The JSON window calls still stamp a NULL timestamp. +`moq_publish_json_snapshot_update`, `moq_publish_json_stream_append`, `moq_publish_json_window_push`, and `moq_publish_json_window_pop` fail with `MOQ_ERROR_INVALID_POINTER` and publish nothing on a NULL `timestamp`, instead of stamping the broadcast clock's current time. +Read the broadcast clock with the new `moq_publish_catalog_now(broadcast, &now)` and stamp both media frames and JSON writes from it, so every track shares its epoch; media on a timeline of its own advertises the gap to the JSON tracks as catalog `delay`. -### JSON window edits take an optional timestamp +### JSON window edits take a timestamp `moq_publish_json_window_push` and `moq_publish_json_window_pop` take a final -`const moq_timestamp *timestamp`. Pass `NULL` to keep stamping the broadcast -clock, or a pointer to the edit's capture time, converted to track milliseconds. +`const moq_timestamp *timestamp`: a pointer to the edit's capture time on the +broadcast clock, converted to track milliseconds. NULL fails, as above. Recompile callers against the regenerated `moq.h`. ### Announcement captures are required ([#7484](https://github.com/moq-dev/moq/pull/7484)) diff --git a/rs/moq-c/src/api.rs b/rs/moq-c/src/api.rs index d7e93b88f84..93e1881ec38 100644 --- a/rs/moq-c/src/api.rs +++ b/rs/moq-c/src/api.rs @@ -3723,9 +3723,9 @@ pub unsafe extern "C" fn moq_publish_json_window( /// Append one record to the back of a JSON window. `value` is a UTF-8 JSON document. /// -/// `timestamp` is when the edit occurred, converted to the track's millisecond timescale; -/// NULL stamps the broadcast clock's current time. A timestamp too large for milliseconds fails -/// with `MOQ_ERROR_MOQ` and publishes nothing. +/// `timestamp` is when the edit occurred on the broadcast clock (see [moq_publish_catalog_now]), +/// converted to the track's millisecond timescale. NULL fails with `MOQ_ERROR_INVALID_POINTER`, +/// and a timestamp too large for milliseconds with `MOQ_ERROR_MOQ`; either publishes nothing. /// /// Returns a zero on success, or a negative code on failure. /// @@ -3743,16 +3743,16 @@ pub unsafe extern "C" fn moq_publish_json_window_push( let window = ffi::parse_id(window)?; let value = unsafe { ffi::parse_slice(value.cast::(), value_len)? }; let value = serde_json::from_slice(value)?; - let timestamp = unsafe { ffi::parse_timestamp(timestamp)? }; + let timestamp = unsafe { ffi::parse_timestamp(timestamp)? }.ok_or(Error::InvalidPointer)?; State::lock().publish.json_window_push(window, value, timestamp) }) } /// Drop `count` records from the front of a JSON window, clamped to what it holds. /// -/// `timestamp` is when the edit occurred, converted to the track's millisecond timescale; -/// NULL stamps the broadcast clock's current time. A timestamp too large for milliseconds fails -/// with `MOQ_ERROR_MOQ` and publishes nothing. +/// `timestamp` is when the edit occurred on the broadcast clock (see [moq_publish_catalog_now]), +/// converted to the track's millisecond timescale. NULL fails with `MOQ_ERROR_INVALID_POINTER`, +/// and a timestamp too large for milliseconds with `MOQ_ERROR_MOQ`; either publishes nothing. /// /// Returns a zero on success, or a negative code on failure. /// @@ -3762,7 +3762,7 @@ pub unsafe extern "C" fn moq_publish_json_window_push( pub unsafe extern "C" fn moq_publish_json_window_pop(window: u32, count: u64, timestamp: *const moq_timestamp) -> i32 { ffi::enter(move || { let window = ffi::parse_id(window)?; - let timestamp = unsafe { ffi::parse_timestamp(timestamp)? }; + let timestamp = unsafe { ffi::parse_timestamp(timestamp)? }.ok_or(Error::InvalidPointer)?; State::lock().publish.json_window_pop(window, count, timestamp) }) } diff --git a/rs/moq-c/src/publish.rs b/rs/moq-c/src/publish.rs index c49b82b6c37..407c88fbcf3 100644 --- a/rs/moq-c/src/publish.rs +++ b/rs/moq-c/src/publish.rs @@ -252,11 +252,9 @@ impl std::ops::DerefMut for Kept { } } -// C window methods stamp a write the caller left unstamped on one fixed broadcast clock, -// without retaining another catalog handle. +/// A data producer, kept beside its broadcast's children. struct Data { producer: T, - clock: moq_mux::Clock, children: Children, } @@ -1219,7 +1217,6 @@ impl Publish { let producer = publish(&broadcast.catalog, track)?; Ok(Data { producer, - clock: broadcast.catalog.clock(), children: broadcast.children.clone(), }) } @@ -1374,29 +1371,23 @@ impl Publish { ) } - /// Append one record to the back of a JSON window. + /// Append one record to the back of a JSON window at `timestamp` on the broadcast clock. pub fn json_window_push( &mut self, window: Id, value: serde_json::Value, - timestamp: Option, + timestamp: moq_net::Timestamp, ) -> Result<(), Error> { let window = &mut self.json_window.get_mut(window).ok_or(Error::TrackNotFound)?.data; - let at = timestamp.unwrap_or_else(|| window.clock.now()); - window.producer.push(moq_net::Timed::from(&value).at(at))?; + window.producer.push(moq_net::Timed::from(&value).at(timestamp))?; Ok(()) } - /// Drop `count` records from the front of a JSON window, clamped to what it holds. - pub fn json_window_pop( - &mut self, - window: Id, - count: u64, - timestamp: Option, - ) -> Result<(), Error> { + /// Drop `count` records from the front of a JSON window, clamped to what it holds, at + /// `timestamp` on the broadcast clock. + pub fn json_window_pop(&mut self, window: Id, count: u64, timestamp: moq_net::Timestamp) -> Result<(), Error> { let window = &mut self.json_window.get_mut(window).ok_or(Error::TrackNotFound)?.data; - let at = timestamp.unwrap_or_else(|| window.clock.now()); - window.producer.pop(moq_net::Timed::from(count).at(at))?; + window.producer.pop(moq_net::Timed::from(count).at(timestamp))?; Ok(()) } diff --git a/rs/moq-c/src/test.rs b/rs/moq-c/src/test.rs index d55fae287a3..7fa12f37919 100644 --- a/rs/moq-c/src/test.rs +++ b/rs/moq-c/src/test.rs @@ -2768,10 +2768,12 @@ fn recv_window(cb: &Callback) -> WindowEvent { (event.kind, event.start..event.end, json, timestamp) } +/// Push record `n` at `n` milliseconds. fn window_push(handle: u32, n: u64) { let value = format!(r#"{{"n":{n}}}"#); + let at = micros(n * 1_000); assert_eq!( - unsafe { moq_publish_json_window_push(handle, value.as_ptr() as *const c_char, value.len(), std::ptr::null()) }, + unsafe { moq_publish_json_window_push(handle, value.as_ptr() as *const c_char, value.len(), &at) }, 0 ); } @@ -2788,8 +2790,8 @@ fn window_consume(consume: u32, name: &[u8], cb: &Callback) -> u32 { }) } -/// A live reader sees each push and pop in order, stamped by the broadcast clock, and closing the -/// broadcast ends a window still open. +/// A live reader sees each push and pop in order at its timestamp, a NULL timestamp is refused, and +/// closing the broadcast ends a window still open. #[test] fn json_window_publish_consume() { use moq_json_window_kind::*; @@ -2811,32 +2813,50 @@ fn json_window_publish_consume() { let event_cb = Callback::new(); let consumer = window_consume(consume, name, &event_cb); + // Nothing stamps an edit for the caller, so a NULL timestamp publishes nothing. + let value = br#"{"n":-1}"#; + assert_eq!( + unsafe { moq_publish_json_window_push(producer, value.as_ptr().cast(), value.len(), std::ptr::null()) }, + MOQ_ERROR_INVALID_POINTER + ); + assert_eq!( + unsafe { moq_publish_json_window_pop(producer, 1, std::ptr::null()) }, + MOQ_ERROR_INVALID_POINTER + ); for n in 0..3 { window_push(producer, n); } - assert_eq!(unsafe { moq_publish_json_window_pop(producer, 2, std::ptr::null()) }, 0); + assert_eq!(unsafe { moq_publish_json_window_pop(producer, 2, µs(3_000)) }, 0); - let mut last = moq_net::Timestamp::ZERO; for n in 0..3 { let (kind, range, json, timestamp) = recv_window(&event_cb); assert_eq!( - (kind, range, json), - (MOQ_JSON_WINDOW_KIND_PUSH, n..n + 1, Some(serde_json::json!({ "n": n }))) + (kind, range, json, timestamp), + ( + MOQ_JSON_WINDOW_KIND_PUSH, + n..n + 1, + Some(serde_json::json!({ "n": n })), + Some(moq_net::Timestamp::from_millis(n).unwrap()) + ) ); - let timestamp = timestamp.expect("the producer stamps each edit with the broadcast clock"); - assert!(timestamp >= last); - last = timestamp; } let (kind, range, json, timestamp) = recv_window(&event_cb); - assert_eq!((kind, range, json), (MOQ_JSON_WINDOW_KIND_POP, 0..2, None)); - assert!(timestamp.expect("the pop is stamped too") >= last); + assert_eq!( + (kind, range, json, timestamp), + ( + MOQ_JSON_WINDOW_KIND_POP, + 0..2, + None, + Some(moq_net::Timestamp::from_millis(3).unwrap()) + ) + ); // Closing the broadcast ends the open window and releases its handle. assert_eq!(moq_publish_close(broadcast), 0); assert!(event_cb.recv_terminal() < 0, "an aborted window is not a clean end"); assert!(moq_consume_json_cancel(consumer) < 0, "the task removed itself"); assert!( - unsafe { moq_publish_json_window_pop(producer, 1, std::ptr::null()) } < 0, + unsafe { moq_publish_json_window_pop(producer, 1, µs(4_000)) } < 0, "the handle was released" ); assert!(moq_publish_json_window_finish(producer) < 0, "the handle was released"); diff --git a/rs/moq-ffi/src/json.rs b/rs/moq-ffi/src/json.rs index 3fa6b02383e..0d4f0ddfe5f 100644 --- a/rs/moq-ffi/src/json.rs +++ b/rs/moq-ffi/src/json.rs @@ -471,12 +471,16 @@ impl MoqJsonWindowProducer { /// /// Not advertised in the broadcast's catalog, which has no window mode; a reader names the /// track itself. Takes over `track`, whose handle is closed afterward. Errors if - /// [`MoqJsonWindowConfig::checkpoint_records`] is zero. + /// [`MoqJsonWindowConfig::checkpoint_records`] is zero, or if `track` has no timescale, since + /// every edit is timed. #[uniffi::constructor] pub fn new(track: &MoqTrackProducer, config: MoqJsonWindowConfig) -> Result, MoqError> { let _guard = crate::ffi::enter(); let config = config.try_into()?; let this = track.adopt(|track| { + if track.info().timescale.is_none() { + return Err(moq_net::Error::TimestampMismatch.into()); + } Ok(Self { demand: track.demand(), inner: Arc::new(std::sync::Mutex::new(Some(moq_json::window::Producer::new( @@ -490,20 +494,20 @@ impl MoqJsonWindowProducer { } /// Append one record to the back of the window. `value` is a JSON document. - /// `timestamp` is on the broadcast clock; null publishes untimed. - #[uniffi::method(default(timestamp = None))] - pub fn push(&self, value: String, timestamp: Option) -> Result<(), MoqError> { + /// `timestamp` is on the broadcast clock, which + /// [`MoqMediaCatalogProducer::now`](crate::media::MoqMediaCatalogProducer::now) reads. + pub fn push(&self, value: String, timestamp: MoqTimestamp) -> Result<(), MoqError> { let value: Value = serde_json::from_str(&value)?; - let at = timestamp.map(TryInto::try_into).transpose()?; - self.edit(|producer| producer.push(moq_net::Timed { value: &value, at })) + let at = timestamp.try_into()?; + self.edit(|producer| producer.push(moq_net::Timed::from(&value).at(at))) } /// Drop `count` records from the front of the window, clamped to what it holds. - /// `timestamp` is on the broadcast clock; null publishes untimed. - #[uniffi::method(default(timestamp = None))] - pub fn pop(&self, count: u64, timestamp: Option) -> Result<(), MoqError> { - let at = timestamp.map(TryInto::try_into).transpose()?; - self.edit(|producer| producer.pop(moq_net::Timed { value: count, at })) + /// `timestamp` is on the broadcast clock, which + /// [`MoqMediaCatalogProducer::now`](crate::media::MoqMediaCatalogProducer::now) reads. + pub fn pop(&self, count: u64, timestamp: MoqTimestamp) -> Result<(), MoqError> { + let at = timestamp.try_into()?; + self.edit(|producer| producer.pop(moq_net::Timed::from(count).at(at))) } /// Close the open group, so the next push or pop opens a new one whose header restates the diff --git a/rs/moq-ffi/src/test.rs b/rs/moq-ffi/src/test.rs index fad04175d7d..a41286284da 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -1642,9 +1642,9 @@ async fn json_window_roundtrip() { let consumer = MoqJsonWindowConsumer::new(&*subscribe(&broadcast, "log").await).unwrap(); for n in 0..3 { - producer.push(format!(r#"{{"n":{n}}}"#), Some(us(n * 1000))).unwrap(); + producer.push(format!(r#"{{"n":{n}}}"#), us(n * 1000)).unwrap(); } - producer.pop(2, Some(us(3000))).unwrap(); + producer.pop(2, us(3000)).unwrap(); for n in 0..3 { let event = next_window(&consumer).await.expect("expected a push"); @@ -1666,10 +1666,10 @@ async fn json_window_roundtrip() { producer.finish().unwrap(); assert!(matches!( - producer.push(r#"{"n":3}"#.into(), Some(us(4000))), + producer.push(r#"{"n":3}"#.into(), us(4000)), Err(MoqError::Closed) )); - assert!(matches!(producer.pop(1, Some(us(4000))), Err(MoqError::Closed))); + assert!(matches!(producer.pop(1, us(4000)), Err(MoqError::Closed))); assert_eq!(next_window(&consumer).await, None); } @@ -1681,31 +1681,34 @@ async fn json_window_cut_restates_the_window() { let config = MoqJsonWindowConfig { checkpoint_records: None, }; - let track = broadcast.publish_track("log".into(), None).unwrap(); + let track = broadcast.publish_track("log".into(), Some(timed_info())).unwrap(); let producer = MoqJsonWindowProducer::new(&track, config.clone()).unwrap(); let raw = subscribe(&broadcast, "log").await; let consumer = MoqJsonWindowConsumer::new(&*subscribe(&broadcast, "log").await).unwrap(); for n in 0..3 { - producer.push(format!(r#"{{"n":{n}}}"#), None).unwrap(); + producer.push(format!(r#"{{"n":{n}}}"#), us(n * 1000)).unwrap(); } - producer.pop(1, None).unwrap(); + producer.pop(1, us(3000)).unwrap(); let events = [ - window_push(0, 0), - window_push(1, 1), - window_push(2, 2), - MoqJsonWindowEvent::Pop { start: 0, end: 1 }, + (window_push(0, 0), 0), + (window_push(1, 1), 1000), + (window_push(2, 2), 2000), + (MoqJsonWindowEvent::Pop { start: 0, end: 1 }, 3000), ]; - for event in events { + for (event, at) in events { assert_eq!( next_window(&consumer).await, - Some(MoqJsonWindowTimed { event, timestamp: None }) + Some(MoqJsonWindowTimed { + event, + timestamp: Some(us(at)), + }) ); } producer.cut().unwrap(); producer.cut().unwrap(); - producer.push(r#"{"n":3}"#.into(), None).unwrap(); + producer.push(r#"{"n":3}"#.into(), us(4000)).unwrap(); let group = kio::clock::timeout(TIMEOUT, async { loop { @@ -1729,7 +1732,7 @@ async fn json_window_cut_restates_the_window() { next_window(&consumer).await, Some(MoqJsonWindowTimed { event: window_push(3, 3), - timestamp: None, + timestamp: Some(us(4000)), }) ); @@ -1749,7 +1752,7 @@ async fn json_window_refreshes_a_bounded_checkpoint_for_a_joiner() { priority: 127, max_age: None, refresh: Some(1), - timescale: None, + timescale: Some(1_000_000), compress: false, }), ) @@ -1759,7 +1762,7 @@ async fn json_window_refreshes_a_bounded_checkpoint_for_a_joiner() { }; let producer = MoqJsonWindowProducer::new(&track, config.clone()).unwrap(); for n in 0..5 { - producer.push(format!(r#"{{"n":{n}}}"#), None).unwrap(); + producer.push(format!(r#"{{"n":{n}}}"#), us(n * 1000)).unwrap(); } // The join crosses the ratio, so the producer restates the window without another edit. @@ -1777,10 +1780,7 @@ async fn json_window_refreshes_a_bounded_checkpoint_for_a_joiner() { window_push(4, 4), ]; for event in events { - assert_eq!( - next_window(&consumer).await, - Some(MoqJsonWindowTimed { event, timestamp: None }) - ); + assert_eq!(next_window(&consumer).await.map(|timed| timed.event), Some(event)); } producer.finish().unwrap(); @@ -1800,6 +1800,23 @@ fn json_window_refuses_zero_checkpoint_records() { assert!(track.demand().is_ok(), "a refused config leaves the track open"); } +/// Every edit is timed, so a track without a timescale is refused up front and handed back. +#[test] +fn json_window_refuses_an_untimed_track() { + let broadcast = MoqBroadcastProducer::new().unwrap(); + let track = broadcast.publish_track("log".into(), None).unwrap(); + let config = MoqJsonWindowConfig { + checkpoint_records: None, + }; + let refused = MoqJsonWindowProducer::new(&track, config); + assert!( + matches!(&refused, Err(MoqError::Protocol { details }) if details.kind == MoqProtocolKind::TimestampMismatch), + "{:?}", + refused.err() + ); + assert!(track.demand().is_ok(), "a refused track stays open"); +} + /// The window producer reports subscriber demand, and drops it once finished. #[tokio::test] async fn json_window_demand() { @@ -1807,7 +1824,7 @@ async fn json_window_demand() { let config = MoqJsonWindowConfig { checkpoint_records: None, }; - let track = broadcast.publish_track("log".into(), None).unwrap(); + let track = broadcast.publish_track("log".into(), Some(timed_info())).unwrap(); let producer = MoqJsonWindowProducer::new(&track, config.clone()).unwrap(); let demand = producer.demand().unwrap(); assert_eq!(demand.name(), "log"); @@ -4797,7 +4814,7 @@ async fn closing_a_broadcast_ends_its_open_data_tracks() { assert!(matches!(json_snapshot.update("1".into(), us(0)), Err(MoqError::Closed))); assert!(matches!(json_stream.append("1".into(), us(0)), Err(MoqError::Closed))); assert!(matches!( - json_window.push("1".into(), Some(us(0))), + json_window.push("1".into(), us(0)), Err(MoqError::Closed) )); } diff --git a/swift/MIGRATE.md b/swift/MIGRATE.md index 9326362e649..6ad8043c52b 100644 --- a/swift/MIGRATE.md +++ b/swift/MIGRATE.md @@ -6,7 +6,7 @@ How to update your code for each breaking change, newest first. ### JSON writes take a broadcast-clock timestamp ([#7691](https://github.com/moq-dev/moq/pull/7691)) -`Json.SnapshotProducer.update(_:timestamp:)` and `Json.StreamProducer.append(_:timestamp:)` require a `Timestamp` on the broadcast clock instead of defaulting to `nil`. Read it with `Media.CatalogProducer(broadcast:).now()`. Their track needs a timescale, such as `TrackInfo(timescale: 1000)`; one without is refused. +`Json.SnapshotProducer.update(_:timestamp:)`, `Json.StreamProducer.append(_:timestamp:)`, and `Json.WindowProducer.push(_:timestamp:)` / `pop(_:timestamp:)` require a `Timestamp` on the broadcast clock instead of defaulting to `nil`. Read it with `Media.CatalogProducer(broadcast:).now()`. Their track needs a timescale, such as `TrackInfo(timescale: 1000)`; one without is refused. ### Announcement captures are required ([#7484](https://github.com/moq-dev/moq/pull/7484)) diff --git a/swift/README.md b/swift/README.md index ef047889ea2..ed144aef582 100644 --- a/swift/README.md +++ b/swift/README.md @@ -93,8 +93,8 @@ JSON tracks live under the `Json` namespace, mirroring the `moq-json` crate, and (lossless append-log, every record preserved in order), or `Json.WindowProducer`/`Json.WindowConsumer` (a sliding window of records a reader can join at any point, not advertised in the catalog). Values encode/decode at the boundary with `JSONEncoder`/`JSONDecoder`; the consumer is an `AsyncSequence` of the decoded type. Publish the -track with `TrackInfo(compress: true)`; consumers read it the same either way. Snapshot updates and -stream appends take a timestamp on the broadcast clock (`Media.CatalogProducer.now()`), so their +track with `TrackInfo(compress: true)`; consumers read it the same either way. Every JSON write +(snapshot update, stream append, window push or pop) takes a timestamp on the broadcast clock (`Media.CatalogProducer.now()`), so the track needs a timescale. ## Local development diff --git a/swift/Sources/Moq/Json.swift b/swift/Sources/Moq/Json.swift index 96b18e821ce..61655193e30 100644 --- a/swift/Sources/Moq/Json.swift +++ b/swift/Sources/Moq/Json.swift @@ -13,9 +13,10 @@ import MoqFFI /// Compression is the track's: publish JSON with `TrackInfo(compress: true)`, and a consumer reads /// it with no option of its own. /// -/// Every snapshot update and stream append takes a timestamp on the broadcast clock, the epoch every -/// track in the broadcast shares: read it with `Media.CatalogProducer.now()`. Their track needs a -/// timescale (`TrackInfo(timescale: 1000)`); one without is refused. +/// Every write (a snapshot update, a stream append, a window push or pop) takes a timestamp on the +/// broadcast clock, the epoch every track in the broadcast shares: read it with +/// `Media.CatalogProducer.now()`. The track needs a timescale (`TrackInfo(timescale: 1000)`); one +/// without is refused. public enum Json {} extension Json { @@ -190,7 +191,7 @@ extension Json { let ffi: MoqJsonWindowProducer /// Publish `track` as a JSON window track. Takes over `track`, whose handle is closed - /// afterward. + /// afterward; throws if `track` has no timescale. /// /// `checkpointRecords` bounds the records retained and restated for a window that is never /// popped: a reader that keeps up still sees every record, while a later joiner is told the @@ -203,13 +204,14 @@ extension Json { ) } - /// Append one record to the back of the window. - public func push(_ value: Value, timestamp: Timestamp? = nil) throws { + /// Append one record to the back of the window at `timestamp` on the broadcast clock. + public func push(_ value: Value, timestamp: Timestamp) throws { try ffi.push(value: encodeJson(value), timestamp: timestamp) } - /// Drop `count` records from the front of the window, clamped to what it holds. - public func pop(_ count: UInt64, timestamp: Timestamp? = nil) throws { + /// Drop `count` records from the front of the window at `timestamp` on the broadcast + /// clock, clamped to what it holds. + public func pop(_ count: UInt64, timestamp: Timestamp) throws { try ffi.pop(count: count, timestamp: timestamp) } From 48e86b2f2e4395c5c09721f6543e11dd4148988a Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 09:37:56 -0800 Subject: [PATCH 7/9] chore: format Co-Authored-By: Claude Opus 5.5 --- rs/moq-ffi/src/test.rs | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/rs/moq-ffi/src/test.rs b/rs/moq-ffi/src/test.rs index a41286284da..840f6c334e8 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -4813,10 +4813,7 @@ async fn closing_a_broadcast_ends_its_open_data_tracks() { assert!(matches!(json_snapshot.update("1".into(), us(0)), Err(MoqError::Closed))); assert!(matches!(json_stream.append("1".into(), us(0)), Err(MoqError::Closed))); - assert!(matches!( - json_window.push("1".into(), us(0)), - Err(MoqError::Closed) - )); + assert!(matches!(json_window.push("1".into(), us(0)), Err(MoqError::Closed))); } /// A data writer released without a finish ends its track as a publisher leaving. From b8a774d6cf76b6cdaf234ba904e1bba70e27f8ae Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 11:32:09 -0800 Subject: [PATCH 8/9] docs: a raw frame may be untimed, a JSON write never Co-Authored-By: Claude Opus 5.5 --- doc/lib/dart/index.md | 2 +- doc/lib/go/index.md | 2 +- doc/lib/kt/index.md | 2 +- doc/lib/py/index.md | 2 +- doc/lib/swift/index.md | 2 +- py/moq-rs/README.md | 3 ++- 6 files changed, 7 insertions(+), 6 deletions(-) diff --git a/doc/lib/dart/index.md b/doc/lib/dart/index.md index 8a48cf6f43e..bd8395a36c0 100644 --- a/doc/lib/dart/index.md +++ b/doc/lib/dart/index.md @@ -18,7 +18,7 @@ container consumers. `TrackProducer.audio` / `.video` take a broadcast, an init and a `Named` or `Requested` target. `CatalogProducer(broadcast: ...)` owns catalog properties and sections; it holds the broadcast weakly and fails after the broadcast closes. Publish JSON tracks with `MoqTrackInfo(compress: true)`; a `package:moq/json.dart` consumer reads one with no option of its own. -A missing data timestamp stays untimed; the library never substitutes zero or now. +A raw frame without a timestamp stays untimed, which only an untimed track accepts; JSON writes always take one. The library never substitutes zero or now. `SnapshotProducer.update`, `StreamProducer.append`, and `WindowProducer.push` and `pop` require a timestamp on the broadcast clock (`CatalogProducer.now()`), the epoch every track in the broadcast shares, so their track needs a timescale. `package:moq/json.dart` consumers return `Value` (`value`, `timestamp`) from `next()`; a snapshot consumer yields each state in order, and `latest()` skips to the newest. diff --git a/doc/lib/go/index.md b/doc/lib/go/index.md index 4e7b3efc8c5..2780b9f04a7 100644 --- a/doc/lib/go/index.md +++ b/doc/lib/go/index.md @@ -19,7 +19,7 @@ and a `Named` or `Requested` target. `NewCatalogProducer` holds its broadcast we catalog writes fail with `ErrClosed` after the broadcast closes. Media timestamps are exact `moq.Timestamp` records (`Value` at `Scale` units per second), so a 90 kHz tick survives a read and republish; `TimestampFromDuration` converts exactly; `TimestampToDuration` rounds down to a whole nanosecond. -A missing data timestamp stays untimed; the library never substitutes zero or now. +A raw frame without a timestamp stays untimed, which only an untimed track accepts; JSON writes always take one. The library never substitutes zero or now. Raw tracks with a `nil` timescale are untimed on both publish and receive. `TrackInfo.Compress` sends each group DEFLATE-compressed to opt-in `moq-lite-07-wip` peers; other peers, and every reader here, get the original frames. Set it on JSON tracks. The JSON producers' `Update`, `Append`, `Push`, and `Pop` take a final `moq.Timestamp` on the broadcast clock, the epoch every track in the broadcast shares, so their track needs a timescale. diff --git a/doc/lib/kt/index.md b/doc/lib/kt/index.md index 77610bc41d1..354ae6bbf7b 100644 --- a/doc/lib/kt/index.md +++ b/doc/lib/kt/index.md @@ -17,7 +17,7 @@ x86\_64) and desktop JVM (Linux x86\_64/aarch64, macOS arm64, Windows x64). / `.video` take a broadcast, a `Named` or `Requested` target, and an init record. `CatalogProducer(broadcast)` holds its broadcast weakly and fails with `Closed` after it closes. Publish JSON tracks with `TrackInfo(compress = true)`; a `dev.moq.json` consumer reads one with no option of its own. -A missing data timestamp stays untimed; the library never substitutes zero or now. +A raw frame without a timestamp stays untimed, which only an untimed track accepts; JSON writes always take one. The library never substitutes zero or now. `SnapshotProducer.update`, `StreamProducer.append`, and `WindowProducer.push` and `pop` require a timestamp on the broadcast clock (`CatalogProducer.now()`), the epoch every track in the broadcast shares, so their track needs a timescale. `dev.moq.json` consumers' `values()` emits `Value` (`value`, `timestamp`) and `valuesAs()` emits `Timed`; a snapshot consumer yields each state in order, and `latest()` skips to the newest. diff --git a/doc/lib/py/index.md b/doc/lib/py/index.md index 687868afede..0c588359c19 100644 --- a/doc/lib/py/index.md +++ b/doc/lib/py/index.md @@ -24,7 +24,7 @@ so a raw byte stream needs no other importer. `ContainerFormat.FMP4` splits each fragment into one frame per sample. Media timestamps are exact `moq.Timestamp(value, scale)` records, so a 90 kHz tick survives a read and republish. `Timestamp.from_timedelta` is exact; `.to_timedelta()` rounds down to a whole microsecond. -A missing data timestamp stays untimed; the library never substitutes zero or now. +A raw frame without a timestamp stays untimed, which only an untimed track accepts; JSON writes always take one. The library never substitutes zero or now. JSON consumers yield `moq.json.Timed(value, timestamp)`; a snapshot consumer yields each state in order, and `await consumer.latest()` skips to the newest. A window consumer's value is a `WindowPush`, `WindowPop`, or `WindowSkip`. Raw tracks with a `None` timescale are untimed on both publish and receive. diff --git a/doc/lib/swift/index.md b/doc/lib/swift/index.md index bc0bad88440..b35be01909d 100644 --- a/doc/lib/swift/index.md +++ b/doc/lib/swift/index.md @@ -21,7 +21,7 @@ Media timestamps are exact `Timestamp` records, `value` units at `scale` units p (a write at another scale rounds down to it). On macOS 13+ and iOS, `try Timestamp(duration)` converts a `Duration` exactly, and `try timestamp.duration` rounds down to a whole attosecond. Publish JSON tracks with `TrackInfo(compress: true)`; a `Json` consumer reads one with no option of its own. -A missing data timestamp stays untimed; the library never substitutes zero or now. +A raw frame without a timestamp stays untimed, which only an untimed track accepts; JSON writes always take one. The library never substitutes zero or now. `Json.SnapshotProducer.update`, `Json.StreamProducer.append`, and `Json.WindowProducer.push` and `pop` require a timestamp on the broadcast clock (`Media.CatalogProducer.now()`), the epoch every track in the broadcast shares, so their track needs a timescale. `Json` consumers yield `Json.Timed` (`value`, `timestamp`); a snapshot consumer yields each state in order, and `latest()` skips to the newest. diff --git a/py/moq-rs/README.md b/py/moq-rs/README.md index 5a25b1a1d38..bb76df31efc 100644 --- a/py/moq-rs/README.md +++ b/py/moq-rs/README.md @@ -229,7 +229,8 @@ on the broadcast clock, read with `media.CatalogProducer.now()`, so their track A window keeps a sliding run of records a reader can join at any point, and `.cut()` ends its open group so the next edit opens one restating the window; the catalog has no window mode, so `WindowProducer` takes only the track. -Omitting time leaves data untimed; choose the track's `timescale` to match. Publish JSON tracks with +A raw frame may omit its timestamp on an untimed track, but every JSON write takes one on the +broadcast clock. Publish JSON tracks with `TrackInfo(compress=True)`: the track compresses each group on the wire, and consumers read it the same either way. Opaque bytes go on a plain `TrackProducer`. From 8a02fdf503fef53a58b3238bf49953b2217cd452 Mon Sep 17 00:00:00 2001 From: "pullfrog[bot]" <226033991+pullfrog[bot]@users.noreply.github.com> Date: Tue, 3 Nov 2026 20:46:18 +0000 Subject: [PATCH 9/9] fix(carla): stamp status snapshots from the broadcast clock --- demo/carla/sim/moq_carla_sim/publish.py | 11 +++++++---- demo/carla/sim/tests/conftest.py | 15 ++++++++++++++- demo/carla/sim/tests/test_publish.py | 3 ++- 3 files changed, 23 insertions(+), 6 deletions(-) diff --git a/demo/carla/sim/moq_carla_sim/publish.py b/demo/carla/sim/moq_carla_sim/publish.py index 2b2088dfedf..bdc496325f7 100644 --- a/demo/carla/sim/moq_carla_sim/publish.py +++ b/demo/carla/sim/moq_carla_sim/publish.py @@ -177,14 +177,17 @@ def status_payload(status: Status) -> dict[str, Any]: class StatusPublisher: - """The `status` track: JSON snapshots on a compressed track. + """The `status` track: JSON snapshots on a compressed, timed track. Snapshot rather than stream, because a late joiner wants the truck's current - state, not the history of every command it ever accepted. + state, not the history of every command it ever accepted. Every update is + stamped from the broadcast clock, the same epoch the media tracks use, so + the catalog never reads the JSON track's timeline as a delay. """ def __init__(self, broadcast: moq.BroadcastProducer) -> None: - track = broadcast.publish_track("status", moq.TrackInfo(compress=True)) + track = broadcast.publish_track("status", moq.TrackInfo(timescale=1_000, compress=True)) + self._catalog = moq.media.CatalogProducer(broadcast) self._producer = moq.json.SnapshotProducer(broadcast, track) # Weak: watching demand neither keeps the track open nor locks it. self._demand = self._producer.demand() @@ -199,7 +202,7 @@ def publish(self, payload: dict[str, Any]) -> None: truck that cannot answer is not one anybody should be steering: let it reach the session, exactly as the video pump does with its own track. """ - self._producer.update(payload) + self._producer.update(payload, self._catalog.now()) async def used(self) -> None: while await self._demand.wanted_changed() is None: diff --git a/demo/carla/sim/tests/conftest.py b/demo/carla/sim/tests/conftest.py index bd3eef5702c..64c01c0c189 100644 --- a/demo/carla/sim/tests/conftest.py +++ b/demo/carla/sim/tests/conftest.py @@ -43,7 +43,7 @@ def __init__(self, broadcast: object, track: SimpleNamespace) -> None: def demand(self) -> object: return self.track.demand() - def update(self, value: object) -> None: + def update(self, value: object, timestamp: object) -> None: self.values.append(value) @@ -73,6 +73,19 @@ async def __aiter__(self): moq.json = moq_json moq_media = ModuleType("moq.media") + + +class CatalogProducer: + """A broadcast clock fixed at zero, like the runtime's shared epoch.""" + + def __init__(self, broadcast: object) -> None: + pass + + def now(self) -> SimpleNamespace: + return SimpleNamespace(value=0, scale=1_000) + + +moq_media.CatalogProducer = CatalogProducer moq_media.VideoFormat = SimpleNamespace(AVC3="avc3") moq_media.VideoInit = lambda **kwargs: SimpleNamespace(**kwargs) moq_media.VideoHint = lambda **kwargs: SimpleNamespace(**kwargs) diff --git a/demo/carla/sim/tests/test_publish.py b/demo/carla/sim/tests/test_publish.py index 6cd1881faf3..2ed3994dedd 100644 --- a/demo/carla/sim/tests/test_publish.py +++ b/demo/carla/sim/tests/test_publish.py @@ -165,10 +165,11 @@ def test_status_omits_only_the_collision_a_truck_has_not_had() -> None: def test_a_closed_status_track_fails_the_session() -> None: """Status republishes on a timer, so a swallowed failure would spin forever.""" - def closed(_payload: object) -> None: + def closed(_payload: object, _timestamp: object) -> None: raise moq.Error("track closed") publisher = publish.StatusPublisher.__new__(publish.StatusPublisher) + publisher._catalog = SimpleNamespace(now=lambda: SimpleNamespace(value=0, scale=1_000)) publisher._producer = SimpleNamespace(update=closed) with pytest.raises(moq.Error):