From 2bef592251b565b079a7ad23ab86734b1f50a31b Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 14 Oct 2026 14:45:35 -0700 Subject: [PATCH 1/7] chore: claim publish timestamp quest Co-Authored-By: GPT-6 From 3a89a547dfc47dbbe4653181d582df0d72259058 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 14 Oct 2026 20:44:35 -0700 Subject: [PATCH 2/7] Preserve caller-supplied producer timestamps Co-Authored-By: GPT-6 --- cpp/moq/test/probe.cpp | 4 +- dart/moq/lib/flate.dart | 13 + dart/moq/test/moq_test.dart | 53 +++- dart/moq_ffi/lib/src/moq.dart | 90 +++++-- dart/moq_ffi/test/leak_test.dart | 5 +- dart/moq_ffi/test/smoke_test.dart | 5 +- doc/lib/dart/index.md | 8 +- doc/lib/go/index.md | 7 + doc/lib/kt/index.md | 6 + doc/lib/py/index.md | 9 +- doc/lib/rs/moq-flate.md | 11 +- doc/lib/rs/moq-json.md | 11 +- doc/lib/swift/index.md | 6 + doc/setup/upgrade.md | 16 +- go/wrapper/README.md | 6 +- go/wrapper/data_timestamps_test.go | 118 +++++++++ go/wrapper/flate/flate.go | 66 +++++ go/wrapper/internal/bridge/handles.go | 12 + go/wrapper/json/json.go | 22 +- go/wrapper/json/json_test.go | 4 +- go/wrapper/media/media.go | 6 + go/wrapper/media/media_test.go | 6 + go/wrapper/moq_test.go | 18 +- go/wrapper/reconnect_test.go | 2 +- go/wrapper/records.go | 8 +- go/wrapper/runtime_bench_test.go | 2 +- go/wrapper/subscribe.go | 10 +- .../kotlin/dev/moq/flate/Tracks.kt | 8 + .../kotlin/dev/moq/json/Tracks.kt | 12 +- .../kotlin/dev/moq/SmokeTest.kt | 46 +++- py/moq-ffi/tests/exit_inside_callback.py | 2 +- py/moq-rs/README.md | 28 +- py/moq-rs/docs/index.md | 13 + py/moq-rs/examples/clock.py | 2 +- py/moq-rs/examples/serve_clock.py | 2 +- py/moq-rs/moq/__init__.py | 3 +- py/moq-rs/moq/_records.py | 8 +- py/moq-rs/moq/flate.py | 60 +++++ py/moq-rs/moq/json.py | 10 +- py/moq-rs/moq/media.py | 6 +- py/moq-rs/moq/publish.py | 6 +- py/moq-rs/moq/subscribe.py | 8 +- py/moq-rs/tests/test_data_timestamps.py | 84 ++++++ py/moq-rs/tests/test_local.py | 44 ++-- quest/m1/README.md | 1 - quest/m1/data-consumer-timestamps.md | 7 +- quest/m1/publish-timestamp.md | 70 ----- quest/m2/flate.md | 11 +- rs/moq-boy/src/status.rs | 5 +- rs/moq-c/src/publish.rs | 47 +++- rs/moq-ffi/src/flate.rs | 18 +- rs/moq-ffi/src/json.rs | 18 +- rs/moq-ffi/src/media.rs | 30 ++- rs/moq-ffi/src/producer.rs | 37 +-- rs/moq-ffi/src/test.rs | 248 ++++++++++++++++-- rs/moq-flate/src/snapshot/mod.rs | 36 ++- rs/moq-flate/src/snapshot/producer.rs | 2 +- rs/moq-flate/src/stream/mod.rs | 42 ++- rs/moq-flate/src/stream/producer.rs | 2 +- rs/moq-hls/src/export/archive_tests.rs | 8 +- rs/moq-hls/src/export/mod.rs | 4 +- rs/moq-json/examples/telemetry.rs | 12 +- rs/moq-json/src/snapshot/mod.rs | 130 +++++++-- rs/moq-json/src/snapshot/producer.rs | 27 +- rs/moq-json/src/stream/mod.rs | 36 ++- rs/moq-json/src/stream/producer.rs | 4 +- rs/moq-json/src/window/mod.rs | 62 ++++- rs/moq-json/src/window/producer.rs | 42 +-- rs/moq-mux/src/binary.rs | 70 ++--- rs/moq-mux/src/catalog/data.rs | 19 +- rs/moq-mux/src/catalog/producer.rs | 6 +- rs/moq-mux/src/container/fmp4/import_test.rs | 8 +- rs/moq-mux/src/json.rs | 37 +-- rs/moq-mux/src/timeline.rs | 8 +- rs/moq-net/src/model/timed.rs | 26 +- rs/moq-room/src/chat.rs | 6 +- rs/moq-stats/benches/aggregate.rs | 4 +- rs/moq-stats/src/aggregate.rs | 13 +- rs/moq-transcode/src/catalog.rs | 2 +- swift/Sources/Moq/Flate.swift | 43 +++ swift/Sources/Moq/Json.swift | 8 +- swift/Sources/Moq/Media.swift | 5 +- swift/Sources/Moq/Track.swift | 14 +- swift/Tests/MoqTests/SmokeTests.swift | 48 +++- 84 files changed, 1609 insertions(+), 473 deletions(-) create mode 100644 dart/moq/lib/flate.dart create mode 100644 go/wrapper/data_timestamps_test.go create mode 100644 go/wrapper/flate/flate.go create mode 100644 kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/flate/Tracks.kt create mode 100644 py/moq-rs/moq/flate.py create mode 100644 py/moq-rs/tests/test_data_timestamps.py delete mode 100644 quest/m1/publish-timestamp.md create mode 100644 swift/Sources/Moq/Flate.swift diff --git a/cpp/moq/test/probe.cpp b/cpp/moq/test/probe.cpp index f67593c8b45..5993ae536bd 100644 --- a/cpp/moq/test/probe.cpp +++ b/cpp/moq/test/probe.cpp @@ -119,7 +119,9 @@ int main() { // Publisher: a server whose origin serves one broadcast with one track. auto origin = moq::OriginProducer::init({}); auto broadcast = ok(origin->create_broadcast("probe"), "create_broadcast"); - auto track = ok(broadcast->publish_track("data", std::nullopt), "publish_track"); + moq::TrackInfo info; + info.timescale = 1000000; + auto track = ok(broadcast->publish_track("data", info), "publish_track"); ok(broadcast->announce({}), "announce"); moq::ServerConfig server_config; diff --git a/dart/moq/lib/flate.dart b/dart/moq/lib/flate.dart new file mode 100644 index 00000000000..f5afdf327de --- /dev/null +++ b/dart/moq/lib/flate.dart @@ -0,0 +1,13 @@ +/// Opaque snapshot and stream tracks, mirroring the moq-flate crate. +library; + +import 'package:moq_ffi/moq_ffi.dart'; + +/// Publishes the latest opaque payload on a track it takes over. +typedef SnapshotProducer = MoqFlateSnapshotProducer; + +/// Publishes an ordered opaque payload log on a track it takes over. +typedef StreamProducer = MoqFlateStreamProducer; + +/// Configures compression and the opaque payload media type. +typedef Config = MoqFlateConfig; diff --git a/dart/moq/test/moq_test.dart b/dart/moq/test/moq_test.dart index b419019357a..2999057501c 100644 --- a/dart/moq/test/moq_test.dart +++ b/dart/moq/test/moq_test.dart @@ -2,6 +2,7 @@ import 'dart:convert'; import 'dart:typed_data'; import 'package:moq/media.dart' as moq_media; +import 'package:moq/flate.dart' as moq_flate; import 'package:moq/json.dart' as moq_json; import 'package:moq/moq.dart'; import 'package:test/test.dart'; @@ -25,11 +26,58 @@ void main() { final broadcast = BroadcastProducer(); final catalog = moq_media.CatalogProducer(broadcast: broadcast); catalog.setSection(name: 'app', json: '{"value":42}'); + catalog.now(); broadcast.close(); expect( () => catalog.removeSection(name: 'app'), throwsA(isA()), ); + expect(() => catalog.now(), throwsA(isA())); + }); + + for (final timestamp in [null, 123456]) { + for (final mode in ['snapshot', 'stream']) { + test('flate $mode preserves timestamp $timestamp', () async { + final broadcast = BroadcastProducer(); + final info = timestamp == null ? null : TrackInfo(timescale: 1000000); + final track = broadcast.publishTrack(name: 'data', info: info); + final consumer = track.consume(subscription: null); + final payload = utf8.encode('payload'); + if (mode == 'snapshot') { + final producer = moq_flate.SnapshotProducer( + broadcast: broadcast, + track: track, + config: moq_flate.Config(), + ); + producer.update(payload: payload, timestampUs: timestamp); + producer.finish(); + } else { + final producer = moq_flate.StreamProducer( + broadcast: broadcast, + track: track, + config: moq_flate.Config(), + ); + producer.append(payload: payload, timestampUs: timestamp); + producer.finish(); + } + final frame = await consumer.readFrame().timeout(timeout); + expect(frame?.payload, payload); + expect(frame?.timestampUs, timestamp); + broadcast.close(); + }); + } + } + + test('raw writes without timestamps stay untimed', () async { + final broadcast = BroadcastProducer(); + final track = broadcast.publishTrack(name: 'untimed', info: null); + final consumer = track.consume(subscription: null); + track.writeFrame(frame: Frame(payload: utf8.encode('payload'))); + final frame = await consumer.readFrame().timeout(timeout); + expect(frame?.timestampUs, isNull); + expect(consumer.info().timescale, isNull); + track.finish(); + broadcast.close(); }); test('connects, announces, subscribes, and delivers a frame', () async { @@ -62,7 +110,10 @@ void main() { (event) => event is AnnounceEventStart, ); final broadcast = relay.createBroadcast(path: 'live'); - final track = broadcast.publishTrack(name: 'events', info: null); + final track = broadcast.publishTrack( + name: 'events', + info: TrackInfo(timescale: 1000000), + ); broadcast.announce(route: MoqRoute()); final announced = (await announcement.timeout(timeout) as AnnounceEventStart).announce; diff --git a/dart/moq_ffi/lib/src/moq.dart b/dart/moq_ffi/lib/src/moq.dart index 8f47ff6f1b1..0cbc832bdb4 100644 --- a/dart/moq_ffi/lib/src/moq.dart +++ b/dart/moq_ffi/lib/src/moq.dart @@ -5754,7 +5754,7 @@ class FfiConverterMoqTrackDemand { abstract class MoqFlateSnapshotProducerInterface { void finish(); - void update({required Uint8List payload}); + void update({required Uint8List payload, int? timestampUs = null}); } final _MoqFlateSnapshotProducerFinalizer = Finalizer>((ptr) { @@ -5809,11 +5809,12 @@ class MoqFlateSnapshotProducer implements MoqFlateSnapshotProducerInterface { }, moqExceptionErrorHandler); } - void update({required Uint8List payload}) { + void update({required Uint8List payload, int? timestampUs = null}) { return rustCall((status) { uniffi_moq_ffi_fn_method_moqflatesnapshotproducer_update( uniffiClonePointer(), FfiConverterUint8List.lower(payload), + FfiConverterOptionalUInt64.lower(timestampUs), status, ); }, moqExceptionErrorHandler); @@ -5847,7 +5848,7 @@ class FfiConverterMoqFlateSnapshotProducer { } abstract class MoqFlateStreamProducerInterface { - void append({required Uint8List payload}); + void append({required Uint8List payload, int? timestampUs = null}); void finish(); } @@ -5893,11 +5894,12 @@ class MoqFlateStreamProducer implements MoqFlateStreamProducerInterface { ); } - void append({required Uint8List payload}) { + void append({required Uint8List payload, int? timestampUs = null}) { return rustCall((status) { uniffi_moq_ffi_fn_method_moqflatestreamproducer_append( uniffiClonePointer(), FfiConverterUint8List.lower(payload), + FfiConverterOptionalUInt64.lower(timestampUs), status, ); }, moqExceptionErrorHandler); @@ -6036,7 +6038,7 @@ class FfiConverterMoqJsonSnapshotConsumer { abstract class MoqJsonSnapshotProducerInterface { MoqTrackDemand demand(); void finish(); - void update({required String value}); + void update({required String value, int? timestampUs = null}); } final _MoqJsonSnapshotProducerFinalizer = Finalizer>((ptr) { @@ -6101,11 +6103,12 @@ class MoqJsonSnapshotProducer implements MoqJsonSnapshotProducerInterface { }, moqExceptionErrorHandler); } - void update({required String value}) { + void update({required String value, int? timestampUs = null}) { return rustCall((status) { uniffi_moq_ffi_fn_method_moqjsonsnapshotproducer_update( uniffiClonePointer(), FfiConverterString.lower(value), + FfiConverterOptionalUInt64.lower(timestampUs), status, ); }, moqExceptionErrorHandler); @@ -6233,7 +6236,7 @@ class FfiConverterMoqJsonStreamConsumer { } abstract class MoqJsonStreamProducerInterface { - void append({required String value}); + void append({required String value, int? timestampUs = null}); MoqTrackDemand demand(); void finish(); } @@ -6280,11 +6283,12 @@ class MoqJsonStreamProducer implements MoqJsonStreamProducerInterface { ); } - void append({required String value}) { + void append({required String value, int? timestampUs = null}) { return rustCall((status) { uniffi_moq_ffi_fn_method_moqjsonstreamproducer_append( uniffiClonePointer(), FfiConverterString.lower(value), + FfiConverterOptionalUInt64.lower(timestampUs), status, ); }, moqExceptionErrorHandler); @@ -6435,6 +6439,7 @@ class FfiConverterMoqMediaCatalogConsumer { } abstract class MoqMediaCatalogProducerInterface { + int now(); void removeSection({required String name}); void setSection({required String name, required String json}); void setVideoProperties({required MoqVideoProperties properties}); @@ -6477,6 +6482,17 @@ class MoqMediaCatalogProducer implements MoqMediaCatalogProducerInterface { ); } + int now() { + return rustCallWithLifter( + (status) => uniffi_moq_ffi_fn_method_moqmediacatalogproducer_now( + uniffiClonePointer(), + status, + ), + FfiConverterUInt64.lift, + moqExceptionErrorHandler, + ); + } + void removeSection({required String name}) { return rustCall((status) { uniffi_moq_ffi_fn_method_moqmediacatalogproducer_remove_section( @@ -10777,12 +10793,13 @@ external void uniffi_moq_ffi_fn_method_moqflatesnapshotproducer_finish( Pointer uniffiStatus, ); -@Native, RustBuffer, Pointer)>( - assetId: _uniffiAssetId, -) +@Native< + Void Function(Pointer, RustBuffer, RustBuffer, Pointer) +>(assetId: _uniffiAssetId) external void uniffi_moq_ffi_fn_method_moqflatesnapshotproducer_update( Pointer ptr, RustBuffer payload, + RustBuffer timestamp_us, Pointer uniffiStatus, ); @@ -10817,12 +10834,13 @@ external Pointer uniffi_moq_ffi_fn_constructor_moqflatestreamproducer_new( Pointer uniffiStatus, ); -@Native, RustBuffer, Pointer)>( - assetId: _uniffiAssetId, -) +@Native< + Void Function(Pointer, RustBuffer, RustBuffer, Pointer) +>(assetId: _uniffiAssetId) external void uniffi_moq_ffi_fn_method_moqflatestreamproducer_append( Pointer ptr, RustBuffer payload, + RustBuffer timestamp_us, Pointer uniffiStatus, ); @@ -10921,12 +10939,13 @@ external void uniffi_moq_ffi_fn_method_moqjsonsnapshotproducer_finish( Pointer uniffiStatus, ); -@Native, RustBuffer, Pointer)>( - assetId: _uniffiAssetId, -) +@Native< + Void Function(Pointer, RustBuffer, RustBuffer, Pointer) +>(assetId: _uniffiAssetId) external void uniffi_moq_ffi_fn_method_moqjsonsnapshotproducer_update( Pointer ptr, RustBuffer value, + RustBuffer timestamp_us, Pointer uniffiStatus, ); @@ -10999,12 +11018,13 @@ external Pointer uniffi_moq_ffi_fn_constructor_moqjsonstreamproducer_new( Pointer uniffiStatus, ); -@Native, RustBuffer, Pointer)>( - assetId: _uniffiAssetId, -) +@Native< + Void Function(Pointer, RustBuffer, RustBuffer, Pointer) +>(assetId: _uniffiAssetId) external void uniffi_moq_ffi_fn_method_moqjsonstreamproducer_append( Pointer ptr, RustBuffer value, + RustBuffer timestamp_us, Pointer uniffiStatus, ); @@ -11084,6 +11104,14 @@ uniffi_moq_ffi_fn_constructor_moqmediacatalogproducer_new( Pointer uniffiStatus, ); +@Native, Pointer)>( + assetId: _uniffiAssetId, +) +external int uniffi_moq_ffi_fn_method_moqmediacatalogproducer_now( + Pointer ptr, + Pointer uniffiStatus, +); + @Native, RustBuffer, Pointer)>( assetId: _uniffiAssetId, ) @@ -12850,6 +12878,9 @@ external int uniffi_moq_ffi_checksum_method_moqmediacatalogconsumer_cancel(); @Native(assetId: _uniffiAssetId) external int uniffi_moq_ffi_checksum_method_moqmediacatalogconsumer_next(); +@Native(assetId: _uniffiAssetId) +external int uniffi_moq_ffi_checksum_method_moqmediacatalogproducer_now(); + @Native(assetId: _uniffiAssetId) external int uniffi_moq_ffi_checksum_method_moqmediacatalogproducer_remove_section(); @@ -13323,10 +13354,10 @@ void _checkApiChecksums() { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqflatesnapshotproducer_update() != - 28820) { + 29136) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqflatestreamproducer_append() != 38961) { + if (uniffi_moq_ffi_checksum_method_moqflatestreamproducer_append() != 45773) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqflatestreamproducer_finish() != 6982) { @@ -13348,7 +13379,7 @@ void _checkApiChecksums() { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqjsonsnapshotproducer_update() != - 18037) { + 17590) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqjsonstreamconsumer_cancel() != 29308) { @@ -13357,7 +13388,7 @@ void _checkApiChecksums() { if (uniffi_moq_ffi_checksum_method_moqjsonstreamconsumer_next() != 7523) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqjsonstreamproducer_append() != 12571) { + if (uniffi_moq_ffi_checksum_method_moqjsonstreamproducer_append() != 36078) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqjsonstreamproducer_demand() != 52854) { @@ -13373,6 +13404,9 @@ void _checkApiChecksums() { if (uniffi_moq_ffi_checksum_method_moqmediacatalogconsumer_next() != 43296) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } + if (uniffi_moq_ffi_checksum_method_moqmediacatalogproducer_now() != 14140) { + throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); + } if (uniffi_moq_ffi_checksum_method_moqmediacatalogproducer_remove_section() != 36089) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); @@ -13443,7 +13477,7 @@ void _checkApiChecksums() { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqmediatrackproducer_write_frame() != - 53915) { + 7616) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqmediatrackstreamproducer_demand() != @@ -13550,7 +13584,7 @@ void _checkApiChecksums() { if (uniffi_moq_ffi_checksum_method_moqgroupproducer_sequence() != 21067) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqgroupproducer_write_frame() != 51857) { + if (uniffi_moq_ffi_checksum_method_moqgroupproducer_write_frame() != 42053) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqgrouprequest_abort() != 26970) { @@ -13579,7 +13613,7 @@ void _checkApiChecksums() { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqtrackproducer_append_datagram() != - 31895) { + 8934) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqtrackproducer_append_group() != 45225) { @@ -13603,7 +13637,7 @@ void _checkApiChecksums() { if (uniffi_moq_ffi_checksum_method_moqtrackproducer_finish_at() != 24581) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqtrackproducer_write_frame() != 1418) { + if (uniffi_moq_ffi_checksum_method_moqtrackproducer_write_frame() != 32196) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqtrackrequest_abort() != 62713) { diff --git a/dart/moq_ffi/test/leak_test.dart b/dart/moq_ffi/test/leak_test.dart index d54207a473a..edfbdc8dc7d 100644 --- a/dart/moq_ffi/test/leak_test.dart +++ b/dart/moq_ffi/test/leak_test.dart @@ -63,7 +63,10 @@ void main() { // the bindings leak, not frames a live track still holds. Future roundTrip() async { final broadcast = MoqBroadcastProducer(); - final track = broadcast.publishTrack(name: 'frames', info: null); + final track = broadcast.publishTrack( + name: 'frames', + info: MoqTrackInfo(timescale: 1000000), + ); final consumer = track.consume(subscription: null); final producer = track.appendGroup(); producer.writeFrame(frame: MoqFrame(payload: payload, timestampUs: 0)); diff --git a/dart/moq_ffi/test/smoke_test.dart b/dart/moq_ffi/test/smoke_test.dart index a7d937ec692..4da645ca739 100644 --- a/dart/moq_ffi/test/smoke_test.dart +++ b/dart/moq_ffi/test/smoke_test.dart @@ -35,7 +35,10 @@ void main() { test('raw track round trips a frame', () async { final broadcast = MoqBroadcastProducer(); - final track = broadcast.publishTrack(name: 'events', info: null); + final track = broadcast.publishTrack( + name: 'events', + info: MoqTrackInfo(timescale: 1000000), + ); final consumer = track.consume(subscription: null); final nextGroup = consumer.nextGroup(); diff --git a/doc/lib/dart/index.md b/doc/lib/dart/index.md index 5f89d426a38..6d9f8a59e89 100644 --- a/doc/lib/dart/index.md +++ b/doc/lib/dart/index.md @@ -17,6 +17,12 @@ Import `package:moq/media.dart` with a prefix for catalogs, encoded-media import container consumers. `TrackProducer.audio` / `.video` take a broadcast, an init record, and a `Named` or `Requested` target. `CatalogProducer(broadcast: ...)` owns catalog properties and sections; it holds the broadcast weakly and fails after the broadcast closes. +`package:moq/flate.dart` exposes opaque `SnapshotProducer` / `StreamProducer` with an optional `timestampUs`. +A missing data timestamp stays untimed; the library never substitutes zero or now. +Raw tracks with a `null` timescale are untimed on both publish and receive. +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. `media.CatalogConsumer.subscribe`, `media.TrackConsumer.subscribe`, and `media.GroupConsumer.fetch` construct the read side from a broadcast. For arrival-order reads, decode each group from `TrackConsumer.recvGroup()` with `media.GroupConsumer(group: ..., container: ...)`; frames @@ -58,7 +64,7 @@ print(await catalog.next()); final mine = moq.createBroadcast('live/camera'); final track = mine.publishTrack(name: 'video', info: null); final group = track.appendGroup(); -group.writeFrame(frame: Frame(payload: bytes, timestampUs: 0)); +group.writeFrame(frame: Frame(payload: bytes, timestampUs: null)); group.finish(); mine.announce(route: MoqRoute(epoch: mintEpoch())); // a fresh epoch per run track.finish(); diff --git a/doc/lib/go/index.md b/doc/lib/go/index.md index d9c791352c7..30ee4e429f8 100644 --- a/doc/lib/go/index.md +++ b/doc/lib/go/index.md @@ -17,6 +17,13 @@ linux/amd64, linux/arm64, darwin/arm64 (macOS 12.3+), windows/amd64. Construct `NewAudioTrackProducer` / `NewVideoTrackProducer` from a broadcast, an init record, and a `Named` or `Requested` target. `NewCatalogProducer` holds its broadcast weakly; catalog writes fail with `ErrClosed` after the broadcast closes. Media timestamps use `time.Duration`. +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. +`moq.dev/moq/flate` publishes opaque snapshot and stream payloads; its `Update` / `Append` +and the JSON producers take a final `*time.Duration` timestamp argument (`nil` for untimed). +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. For arrival-order reads, decode each group from `moq.TrackConsumer.RecvGroup` with `media.NewGroupConsumer`; frames carry container media time as they land. `media.FetchGroup` fetches and decodes one past group. diff --git a/doc/lib/kt/index.md b/doc/lib/kt/index.md index 869edb26b26..b97dc806e3a 100644 --- a/doc/lib/kt/index.md +++ b/doc/lib/kt/index.md @@ -16,6 +16,12 @@ x86\_64) and desktop JVM (Linux x86\_64/aarch64, macOS arm64, Windows x64). `dev.moq.media` owns catalogs, encoded imports, and container consumers. `TrackProducer.audio` / `.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. +`dev.moq.flate.SnapshotProducer` / `StreamProducer` publish opaque bytes with an optional `timestampUs`. +A missing data timestamp stays untimed; the library never substitutes zero or now. +Raw tracks with a `null` timescale are untimed on both publish and receive. +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. Construct readers with `CatalogConsumer.subscribe`, `TrackConsumer.subscribe`, or `GroupConsumer.fetch`. For arrival-order reads, decode each group from `dev.moq.TrackConsumer.recvGroup()` with `dev.moq.media.GroupConsumer(group, container)`; frames diff --git a/doc/lib/py/index.md b/doc/lib/py/index.md index 6de3ead7f29..9e93327eb8a 100644 --- a/doc/lib/py/index.md +++ b/doc/lib/py/index.md @@ -18,6 +18,13 @@ Use `Named(name)` or `Requested(request)` as the target for `TrackProducer.audio `CatalogProducer(broadcast)` holds the broadcast weakly and owns catalog properties and sections; its writes fail with `Error.Closed` after the broadcast closes or is released. `MediaFrame.timestamp`, media writes, and `flush` use `datetime.timedelta`. +A missing data timestamp stays untimed; the library never substitutes zero or now. +Raw tracks with a `None` timescale are untimed on both publish and receive. +`moq.flate.SnapshotProducer` / `StreamProducer` publish opaque payloads; their `update` / `append` +and the JSON producers accept `timestamp=timedelta(...)` (`None` for untimed). +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. For arrival-order reads, decode each group from `TrackConsumer.recv_group()` with `media.GroupConsumer(group, container)`; frames carry container media time as they land. @@ -58,7 +65,7 @@ async def main(): # Already-encoded frames: the catalog is filled from the bitstream audio = moq.media.TrackProducer.audio(broadcast, moq.media.AudioInit(format=moq.media.AudioFormat.OPUS, data=opus_init_bytes)) - audio.write_frame(payload) + audio.write_frame(payload, moq.media.CatalogProducer(broadcast).now()) audio.cut() # audio has no keyframes, so this is what gives it groups # Or raw pixels, encoded inside the binding (VideoToolbox, Media Foundation, NVENC, openh264) diff --git a/doc/lib/rs/moq-flate.md b/doc/lib/rs/moq-flate.md index 524a6bb725d..f0b2853f6a0 100644 --- a/doc/lib/rs/moq-flate.md +++ b/doc/lib/rs/moq-flate.md @@ -26,9 +26,14 @@ let mut producer = moq_flate::snapshot::Producer::new(track, config); producer.update(payload)?; ``` -A payload is stamped when written, unless it carries its capture time: -`moq_net::Timed::from(bytes).at(captured)`. Writes return the encoded frame -size. +A bare payload stays untimed. To publish at a capture time, pass +`moq_net::Timed::from(bytes).at(captured)`. The timestamp must match the track: +an untimed track has no timescale, and a timed track requires a timestamp on +every write. A publisher that wants to stamp now samples its own clock. +Writes return the encoded frame size. + +When upgrading, replace `Timed` with `Timed

` and pass capture times +explicitly instead of relying on a write-time default. A stream rides one group, so the whole log shares moq-net's group budget: 32 MiB of payload and 8192 payloads. An `append` that might not fit returns diff --git a/doc/lib/rs/moq-json.md b/doc/lib/rs/moq-json.md index 38d60fbd7ba..fb0dafc3334 100644 --- a/doc/lib/rs/moq-json.md +++ b/doc/lib/rs/moq-json.md @@ -17,8 +17,15 @@ generic catalog reader will not pick it up. - **stream**: lossless append-log in a single group. A reader that falls behind fails the read rather than resuming mid-log. - **window**: a bounded run of records a reader can join at any point. A new group restates what it keeps explicitly, so a reader that was keeping up is not handed a record twice. -Both sides choose the same compression. A value is stamped when written, -unless it carries its capture time. +Both sides choose the same compression. A bare value stays untimed; publish +`moq_net::Timed::from(&value).at(captured)` to retain a capture timestamp. +The timestamp must match the track: an untimed track has no timescale, and a +timed track requires a timestamp on every write. Editing guards take the +same optional capture time when opened, including when they publish on drop. + +When upgrading, replace `Timed` with `Timed

` and pass timestamps +explicitly. A publisher that wants to stamp an event now samples its own +clock; the producer never supplies one. A stream rides one group, so the whole log shares moq-net's group budget: 32 MiB of payload and 8192 records. An append that might not fit is refused diff --git a/doc/lib/swift/index.md b/doc/lib/swift/index.md index 104178eb9a3..51c5c017921 100644 --- a/doc/lib/swift/index.md +++ b/doc/lib/swift/index.md @@ -17,6 +17,12 @@ slices for iOS 16+, the iOS Simulator, and macOS 12.3+. `.named(name:)` or `.requested(request)` target. `Media.CatalogProducer(broadcast:)` updates catalog properties and sections without keeping the broadcast open. Its writes fail after closing or releasing the broadcast. +`Flate.SnapshotProducer` / `StreamProducer` publish opaque bytes with an optional `timestampUs`. +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. +Whole-frame media writes require caller time; container imports keep their own timeline handling. +Timed raw/data tracks require caller-supplied timestamps. Use `Media.CatalogProducer.now()` to stamp a locally +created event on the broadcast clock; reading it fixes that clock for later media producers. For arrival-order reads, decode each group from `TrackConsumer.recvGroup()` with `Media.GroupConsumer(group:container:)`; frames carry container media time as they land. diff --git a/doc/setup/upgrade.md b/doc/setup/upgrade.md index 2156a52e141..81081ce06a2 100644 --- a/doc/setup/upgrade.md +++ b/doc/setup/upgrade.md @@ -242,10 +242,18 @@ These land with the next breaking release, not the 2026-09-23 train. `web.https.cert`, `key`, and `root` need `web.https.listen`. `moq` without a listener refuses `--listen-*` and `--auth-*` flags. Each used to be ignored; drop it, or add the listener it configures. -- **moq-mux data producers take a broadcast-clock `Timestamp`.** `json` and - `binary` `Snapshot::update` and `Stream::append` take `Timed<_, Timestamp>` - instead of `Timed<_, Instant>`, and publish it as given. Convert a capture - `Instant` with `.at(catalog.clock().capture(instant)?)`. A timestamp ahead +- **Data publishes preserve optional timestamps.** `moq_net::Timed

` drops + its clock type parameter. JSON and flate snapshot/stream producers and JSON + window `push` / `pop` publish `at: None` untimed, so their track must also be + untimed. Pass a timestamp explicitly on timed tracks. Snapshot `modify(at)` + and `mutate(at, f)` carry the caller's optional time through the edit guard. + moq-mux data timestamps use the broadcast clock; convert a capture `Instant` + with `.at(catalog.clock().capture(instant)?)`. FFI data operations take an + optional timestamp in microseconds, and raw track info's null timescale now + means untimed on publish as well as receive. Python/Swift raw writes no + longer default to zero. Whole-frame media writes now require caller time; + container imports keep their existing timeline handling. `media.CatalogProducer.now()` samples and fixes the + broadcast clock for explicit local-event stamps. A supplied timestamp ahead of now is published rather than refused. - **moq-mux importers publish the catalog at their first frame.** The fMP4, MKV, and MPEG-TS importers used to publish it at their init segment (`moov`, diff --git a/go/wrapper/README.md b/go/wrapper/README.md index 575da3c7180..b4d9c81ec09 100644 --- a/go/wrapper/README.md +++ b/go/wrapper/README.md @@ -97,6 +97,10 @@ in the broadcast's catalog, and `NewSnapshotConsumer` / `NewStreamConsumer` take `TrackConsumer` that has not read a group yet. Snapshots carry lossy latest state; streams carry every record in order. Producers accept any `encoding/json` value; consumers return `json.RawMessage` so callers choose their own decoded type. +`Update` / `Append` take a final `*time.Duration` on the broadcast clock; 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. +`moq.dev/moq/flate` provides the matching snapshot and stream producers for opaque bytes. ```go import moqjson "moq.dev/moq/json" @@ -104,7 +108,7 @@ import moqjson "moq.dev/moq/json" broadcast, _ := client.CreateBroadcast("room") track, _ := broadcast.PublishTrack("status", nil) status, _ := moqjson.NewSnapshotProducer(broadcast, track, moqjson.SnapshotOptions{Compression: true}) -_ = status.Update(map[string]any{"viewers": 42}) +_ = status.Update(map[string]any{"viewers": 42}, nil) ``` Producers take `SnapshotOptions` or `StreamOptions`; both consumers take diff --git a/go/wrapper/data_timestamps_test.go b/go/wrapper/data_timestamps_test.go new file mode 100644 index 00000000000..63255dbde2c --- /dev/null +++ b/go/wrapper/data_timestamps_test.go @@ -0,0 +1,118 @@ +package moq_test + +import ( + "context" + "encoding/json" + "testing" + "time" + + "moq.dev/moq" + "moq.dev/moq/flate" + moqjson "moq.dev/moq/json" +) + +func TestDataTimestamps(t *testing.T) { + for _, mode := range []string{"json snapshot", "json stream", "flate snapshot", "flate stream"} { + for _, timed := range []bool{false, true} { + name := mode + "/untimed" + if timed { + name = mode + "/timed" + } + t.Run(name, func(t *testing.T) { + ctx, cancel := context.WithTimeout(context.Background(), testTimeout) + defer cancel() + broadcast, err := moq.NewBroadcastProducer() + if err != nil { + t.Fatal(err) + } + defer broadcast.Close() + var timestamp *time.Duration + var info *moq.TrackInfo + if timed { + at := 123456 * time.Microsecond + timestamp = &at + info = timedInfo() + } + track, err := broadcast.PublishTrack("data", info) + if err != nil { + t.Fatal(err) + } + consumer, err := track.Consume(nil) + if err != nil { + t.Fatal(err) + } + defer consumer.Cancel() + payload := []byte("opaque payload") + switch mode { + case "json snapshot": + producer, err := moqjson.NewSnapshotProducer(broadcast, track, moqjson.SnapshotOptions{}) + if err != nil { + t.Fatal(err) + } + err = producer.Update(map[string]int{"n": 1}, timestamp) + if err != nil { + t.Fatal(err) + } + if err := producer.Finish(); err != nil { + t.Fatal(err) + } + case "json stream": + producer, err := moqjson.NewStreamProducer(broadcast, track, moqjson.StreamOptions{}) + if err != nil { + t.Fatal(err) + } + err = producer.Append(map[string]int{"n": 1}, timestamp) + if err != nil { + t.Fatal(err) + } + if err := producer.Finish(); err != nil { + t.Fatal(err) + } + case "flate snapshot": + producer, err := flate.NewSnapshotProducer(broadcast, track, flate.Options{}) + if err != nil { + t.Fatal(err) + } + if err := producer.Update(payload, timestamp); err != nil { + t.Fatal(err) + } + if err := producer.Finish(); err != nil { + t.Fatal(err) + } + case "flate stream": + producer, err := flate.NewStreamProducer(broadcast, track, flate.Options{}) + if err != nil { + t.Fatal(err) + } + if err := producer.Append(payload, timestamp); err != nil { + t.Fatal(err) + } + if err := producer.Finish(); err != nil { + t.Fatal(err) + } + } + frame, err := consumer.ReadFrame(ctx) + if err != nil { + t.Fatal(err) + } + if frame == nil { + t.Fatal("missing frame") + } + if (frame.Timestamp == nil) != (timestamp == nil) || timestamp != nil && *frame.Timestamp != *timestamp { + t.Fatalf("timestamp = %v, want %v", frame.Timestamp, timestamp) + } + if mode == "json snapshot" || mode == "json stream" { + var value map[string]int + if err := json.Unmarshal(frame.Payload, &value); err != nil { + t.Fatal(err) + } + if value["n"] != 1 { + t.Fatalf("payload = %s", frame.Payload) + } + } else if string(frame.Payload) != string(payload) { + t.Fatalf("payload = %q", frame.Payload) + } + }) + } + } +} diff --git a/go/wrapper/flate/flate.go b/go/wrapper/flate/flate.go new file mode 100644 index 00000000000..ef830b4e6f5 --- /dev/null +++ b/go/wrapper/flate/flate.go @@ -0,0 +1,66 @@ +// Package flate publishes opaque snapshot and stream tracks. +package flate + +import ( + "time" + + "moq.dev/moq" + ffi "moq.dev/moq-ffi/moq" + "moq.dev/moq/internal/bridge" +) + +// Options configures an opaque data track. +type Options struct { + // Compression enables group-scoped DEFLATE. + Compression bool + // Mime describes the payload media type, or nil leaves it unstated. + Mime *string +} + +// SnapshotProducer publishes the latest opaque payload. +type SnapshotProducer struct{ inner *ffi.MoqFlateSnapshotProducer } + +// NewSnapshotProducer takes over track and advertises it in broadcast's catalog. +func NewSnapshotProducer(broadcast *moq.BroadcastProducer, track *moq.TrackProducer, options Options) (*SnapshotProducer, error) { + inner, err := ffi.NewMoqFlateSnapshotProducer(bridge.BroadcastProducer(broadcast), bridge.TrackProducer(track), ffi.MoqFlateConfig{Compression: options.Compression, Mime: options.Mime}) + if err != nil { + return nil, err + } + return &SnapshotProducer{inner: inner}, nil +} + +// Update publishes payload at timestamp on the broadcast clock; nil is untimed. +func (p *SnapshotProducer) Update(payload []byte, timestamp *time.Duration) error { + at, err := bridge.OptionalDuration(timestamp, "timestamp") + if err != nil { + return err + } + return p.inner.Update(payload, at) +} + +// Finish closes the track and retires its catalog entry. +func (p *SnapshotProducer) Finish() error { return p.inner.Finish() } + +// StreamProducer publishes an ordered log of opaque payloads. +type StreamProducer struct{ inner *ffi.MoqFlateStreamProducer } + +// NewStreamProducer takes over track and advertises it in broadcast's catalog. +func NewStreamProducer(broadcast *moq.BroadcastProducer, track *moq.TrackProducer, options Options) (*StreamProducer, error) { + inner, err := ffi.NewMoqFlateStreamProducer(bridge.BroadcastProducer(broadcast), bridge.TrackProducer(track), ffi.MoqFlateConfig{Compression: options.Compression, Mime: options.Mime}) + if err != nil { + return nil, err + } + return &StreamProducer{inner: inner}, nil +} + +// Append adds payload at timestamp on the broadcast clock; nil is untimed. +func (p *StreamProducer) Append(payload []byte, timestamp *time.Duration) error { + at, err := bridge.OptionalDuration(timestamp, "timestamp") + if err != nil { + return err + } + return p.inner.Append(payload, at) +} + +// Finish closes the track and retires its catalog entry. +func (p *StreamProducer) Finish() error { return p.inner.Finish() } diff --git a/go/wrapper/internal/bridge/handles.go b/go/wrapper/internal/bridge/handles.go index b5de8b5eee1..20eb62d4c6e 100644 --- a/go/wrapper/internal/bridge/handles.go +++ b/go/wrapper/internal/bridge/handles.go @@ -37,3 +37,15 @@ var Subscription func(any) (*ffi.MoqSubscription, error) // Duration converts a duration into nonnegative microseconds. var Duration func(time.Duration, string) (uint64, error) + +// OptionalDuration converts a caller's time to microseconds, preserving absence. +func OptionalDuration(value *time.Duration, name string) (*uint64, error) { + if value == nil { + return nil, nil + } + us, err := Duration(*value, name) + if err != nil { + return nil, err + } + return &us, nil +} diff --git a/go/wrapper/json/json.go b/go/wrapper/json/json.go index ff217590cab..71833c6b86e 100644 --- a/go/wrapper/json/json.go +++ b/go/wrapper/json/json.go @@ -13,6 +13,7 @@ import ( "context" stdjson "encoding/json" "iter" + "time" "moq.dev/moq" ffi "moq.dev/moq-ffi/moq" @@ -76,13 +77,18 @@ func NewSnapshotProducer(broadcast *moq.BroadcastProducer, track *moq.TrackProdu return &SnapshotProducer{inner: inner}, nil } -// Update publishes value as a JSON snapshot or delta. It is a no-op when unchanged. -func (p *SnapshotProducer) Update(value any) error { +// Update publishes value at timestamp on the broadcast clock; nil is untimed. +// It is a no-op when unchanged. +func (p *SnapshotProducer) Update(value any, timestamp *time.Duration) error { encoded, err := stdjson.Marshal(value) if err != nil { return err } - return p.inner.Update(string(encoded)) + at, err := bridge.OptionalDuration(timestamp, "timestamp") + if err != nil { + return err + } + return p.inner.Update(string(encoded), at) } // Demand returns a watch-only handle to whether the track has subscribers. @@ -119,13 +125,17 @@ func NewStreamProducer(broadcast *moq.BroadcastProducer, track *moq.TrackProduce return &StreamProducer{inner: inner}, nil } -// Append adds one JSON record to the log. -func (p *StreamProducer) Append(value any) error { +// Append adds one JSON record at timestamp on the broadcast clock; nil is untimed. +func (p *StreamProducer) Append(value any, timestamp *time.Duration) error { encoded, err := stdjson.Marshal(value) if err != nil { return err } - return p.inner.Append(string(encoded)) + at, err := bridge.OptionalDuration(timestamp, "timestamp") + if err != nil { + return err + } + return p.inner.Append(string(encoded), at) } // Demand returns a watch-only handle to whether the track has subscribers. diff --git a/go/wrapper/json/json_test.go b/go/wrapper/json/json_test.go index f5105f420f3..f5b62f6c9ce 100644 --- a/go/wrapper/json/json_test.go +++ b/go/wrapper/json/json_test.go @@ -63,7 +63,7 @@ func TestTracks(t *testing.T) { t.Fatal(err) } defer snapshotConsumer.Cancel() - if err := snapshot.Update(map[string]any{"viewers": 42}); err != nil { + if err := snapshot.Update(map[string]any{"viewers": 42}, nil); err != nil { t.Fatal(err) } value, err := snapshotConsumer.Next(ctx) @@ -87,7 +87,7 @@ func TestTracks(t *testing.T) { t.Fatal(err) } defer streamConsumer.Cancel() - if err := stream.Append(map[string]any{"n": 1}); err != nil { + if err := stream.Append(map[string]any{"n": 1}, nil); err != nil { t.Fatal(err) } record, err := streamConsumer.Next(ctx) diff --git a/go/wrapper/media/media.go b/go/wrapper/media/media.go index 12eb5cc3405..c380b701635 100644 --- a/go/wrapper/media/media.go +++ b/go/wrapper/media/media.go @@ -102,6 +102,12 @@ func NewCatalogProducer(broadcast *moq.BroadcastProducer) (*CatalogProducer, err return &CatalogProducer{inner: inner}, nil } +// Now reads the broadcast clock, fixing it for subsequent media producers. +func (c *CatalogProducer) Now() (time.Duration, error) { + us, err := c.inner.Now() + return time.Duration(us) * time.Microsecond, err +} + // SetVideoProperties replaces the video properties shared by all renditions. func (c *CatalogProducer) SetVideoProperties(properties VideoProperties) error { return c.inner.SetVideoProperties(properties) diff --git a/go/wrapper/media/media_test.go b/go/wrapper/media/media_test.go index 41944f24ad5..5b051a99afa 100644 --- a/go/wrapper/media/media_test.go +++ b/go/wrapper/media/media_test.go @@ -20,9 +20,15 @@ func TestCatalogClosesWithBroadcast(t *testing.T) { if err := catalog.SetSection("app", map[string]int{"value": 42}); err != nil { t.Fatal(err) } + if _, err := catalog.Now(); err != nil { + t.Fatal(err) + } if err := broadcast.Close(); err != nil { t.Fatal(err) } + if _, err := catalog.Now(); !errors.Is(err, moq.ErrClosed) { + t.Fatalf("now after close: %v", err) + } if err := catalog.RemoveSection("app"); !errors.Is(err, moq.ErrClosed) { t.Fatalf("remove after close: %v", err) } diff --git a/go/wrapper/moq_test.go b/go/wrapper/moq_test.go index 594f511e27d..30d6a37f5d1 100644 --- a/go/wrapper/moq_test.go +++ b/go/wrapper/moq_test.go @@ -85,7 +85,7 @@ func TestDynamicBroadcastRequest(t *testing.T) { if err != nil { t.Fatal(err) } - track, err := served.PublishTrack("status", nil) + track, err := served.PublishTrack("status", timedInfo()) if err != nil { t.Fatal(err) } @@ -401,7 +401,7 @@ func TestFetchGroupAndServeDynamicMiss(t *testing.T) { if err != nil { t.Fatal(err) } - track, err := broadcast.PublishTrack("events", nil) + track, err := broadcast.PublishTrack("events", timedInfo()) if err != nil { t.Fatal(err) } @@ -601,7 +601,7 @@ func TestTrackPublishConsume(t *testing.T) { if err != nil { t.Fatal(err) } - track, err := broadcast.PublishTrack("data", nil) + track, err := broadcast.PublishTrack("data", timedInfo()) if err != nil { t.Fatal(err) } @@ -661,7 +661,7 @@ func TestReadFrameSkipsEmptyThenPopulatedGroups(t *testing.T) { if err != nil { t.Fatal(err) } - track, err := broadcast.PublishTrack("status", nil) + track, err := broadcast.PublishTrack("status", timedInfo()) if err != nil { t.Fatal(err) } @@ -771,7 +771,7 @@ func TestDynamicTrackRequest(t *testing.T) { t.Fatalf("request name = %q, want events", name) } - track, err := request.Accept(nil) + track, err := request.Accept(timedInfo()) if err != nil { t.Fatal(err) } @@ -1110,7 +1110,7 @@ func TestUsedCancelKeepsTheTrack(t *testing.T) { } defer broadcast.Close() - track, err := broadcast.PublishTrack("status", nil) + track, err := broadcast.PublishTrack("status", timedInfo()) if err != nil { t.Fatal(err) } @@ -1450,3 +1450,9 @@ func TestDynamicServesARequestUnderAPrefix(t *testing.T) { func us(v uint64) *uint64 { return &v } func ts(d time.Duration) *time.Duration { return &d } + +// timedInfo declares the microsecond timeline used by timed raw fixtures. +func timedInfo() *moq.TrackInfo { + scale := uint64(1_000_000) + return &moq.TrackInfo{Priority: 127, Timescale: &scale} +} diff --git a/go/wrapper/reconnect_test.go b/go/wrapper/reconnect_test.go index 6377d8c9d64..77ba09a0cd3 100644 --- a/go/wrapper/reconnect_test.go +++ b/go/wrapper/reconnect_test.go @@ -168,7 +168,7 @@ func TestReconnectAcrossRelayRestart(t *testing.T) { } defer broadcast.Close() - track, err := broadcast.PublishTrack("data", nil) + track, err := broadcast.PublishTrack("data", timedInfo()) if err != nil { t.Fatal(err) } diff --git a/go/wrapper/records.go b/go/wrapper/records.go index 562eed33557..27efff4da76 100644 --- a/go/wrapper/records.go +++ b/go/wrapper/records.go @@ -41,8 +41,7 @@ func optFromMicros(us *uint64) *time.Duration { } // Frame is a raw track frame: a payload and its presentation timestamp. -// Timestamp is nil on a frame read from an untimed track; a raw track published -// here is timed, so writing one needs it. +// Timestamp is nil on an untimed track, on both publish and receive. type Frame struct { Payload []byte Timestamp *time.Duration @@ -105,9 +104,8 @@ func subscriptionFFI(s *Subscription) (*ffi.MoqSubscription, error) { // TrackInfo holds publisher-side track properties: priority, how long a // non-latest group is cached (nil for no limit), and the timescale in ticks per -// second (nil uses microseconds when publishing, and means the source declared no -// timeline on a received track). A zero Priority is the least urgent, not the -// default; set 127 for the midpoint a nil TrackInfo uses. +// second (nil means untimed on both publish and receive). A zero Priority is +// the least urgent; set 127 for the midpoint a nil TrackInfo uses. type TrackInfo struct { Priority uint8 MaxAge *time.Duration diff --git a/go/wrapper/runtime_bench_test.go b/go/wrapper/runtime_bench_test.go index 26b14335940..20a733cfa80 100644 --- a/go/wrapper/runtime_bench_test.go +++ b/go/wrapper/runtime_bench_test.go @@ -45,7 +45,7 @@ func BenchmarkPublisher(b *testing.B) { b.Fatal(err) } b.Cleanup(func() { _ = broadcast.Close() }) - tracks[p], err = broadcast.PublishTrack("payload", nil) + tracks[p], err = broadcast.PublishTrack("payload", timedInfo()) if err != nil { b.Fatal(err) } diff --git a/go/wrapper/subscribe.go b/go/wrapper/subscribe.go index e4707880671..a3b959b589a 100644 --- a/go/wrapper/subscribe.go +++ b/go/wrapper/subscribe.go @@ -95,7 +95,7 @@ func (b *BroadcastConsumer) DecodeVideo( return &VideoConsumer{inner: inner}, nil } -// GroupConsumer is a stream of timestamped raw frames within a single group. +// GroupConsumer is a stream of raw frames within a single group. type GroupConsumer struct { inner *ffi.MoqGroupConsumer } @@ -105,13 +105,13 @@ func (g *GroupConsumer) Sequence() uint64 { return g.inner.Sequence() } -// ReadFrame returns the next timestamped frame, or (nil, nil) when the group ends. +// ReadFrame returns the next raw frame, or (nil, nil) when the group ends. func (g *GroupConsumer) ReadFrame(ctx context.Context) (*Frame, error) { frame, err := bridge.Call(ctx, g.inner.Cancel, g.inner.ReadFrame) return frameFromFFI(frame), err } -// All ranges over timestamped frames until the group ends or the loop breaks. +// All ranges over raw frames until the group ends or the loop breaks. func (g *GroupConsumer) All(ctx context.Context) iter.Seq2[*Frame, error] { return bridge.Seq(ctx, g.ReadFrame) } @@ -122,7 +122,7 @@ func (g *GroupConsumer) Cancel() { } // TrackConsumer is a stream of groups from a track. Each group is itself a -// stream of timestamped raw frames. +// stream of raw frames. type TrackConsumer struct { inner *ffi.MoqTrackConsumer } @@ -162,7 +162,7 @@ func (t *TrackConsumer) NextGroup(ctx context.Context) (*GroupConsumer, error) { return &GroupConsumer{inner: res}, nil } -// ReadFrame reads the first timestamped frame of the next group, or (nil, nil) +// ReadFrame reads the first raw frame of the next group, or (nil, nil) // when the track ends. Convenient for one-frame-per-group tracks. Completed // empty groups are skipped; a nil frame is track EOF, not an empty group. // Cancelling the context cancels this consumer, not just this call: see diff --git a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/flate/Tracks.kt b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/flate/Tracks.kt new file mode 100644 index 00000000000..e9d416fd6ba --- /dev/null +++ b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/flate/Tracks.kt @@ -0,0 +1,8 @@ +package dev.moq.flate + +/** Publishes the latest opaque payload on a track it takes over. */ +typealias SnapshotProducer = uniffi.moq.MoqFlateSnapshotProducer +/** Publishes an ordered opaque payload log on a track it takes over. */ +typealias StreamProducer = uniffi.moq.MoqFlateStreamProducer +/** Configures compression and the opaque payload media type. */ +typealias Config = uniffi.moq.MoqFlateConfig 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 9550f7600a3..7970a86931f 100644 --- a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/json/Tracks.kt +++ b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/json/Tracks.kt @@ -36,15 +36,15 @@ typealias StreamConfig = uniffi.moq.MoqJsonStreamConfig * * The `@Serializable` type is encoded with [MoqJson]. Pass an already-encoded * `String` to serialize with another library: the member overload takes it - * unchanged. + * unchanged. [timestampUs] is on the broadcast clock; null is untimed. */ -inline fun SnapshotProducer.update(value: T) { - update(MoqJson.encodeToString(serializer(), value)) +inline fun SnapshotProducer.update(value: T, timestampUs: ULong? = null) { + update(MoqJson.encodeToString(serializer(), value), timestampUs) } -/** Append [value] to a JSON stream track as one record, encoded with [MoqJson]. */ -inline fun StreamProducer.append(value: T) { - append(MoqJson.encodeToString(serializer(), value)) +/** Append [value] at [timestampUs] on the broadcast clock; null is untimed. */ +inline fun StreamProducer.append(value: T, timestampUs: ULong? = null) { + append(MoqJson.encodeToString(serializer(), value), timestampUs) } /** diff --git a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt index 05c85f66047..ee1d6fc7cbf 100644 --- a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt +++ b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt @@ -193,7 +193,7 @@ class SmokeTest { @Test fun `broadcast consumer fetches cached group`() = runTest { BroadcastProducer().use { broadcast -> - val track = broadcast.publishTrack("events", null) + val track = broadcast.publishTrack("events", TrackInfo(timescale = 1_000_000uL)) val group = track.appendGroup() group.writeFrame(Frame(payload = "cached".encodeToByteArray(), timestampUs = 0uL)) group.finish() @@ -212,7 +212,7 @@ class SmokeTest { @Test fun `readFrame skips empty then populated groups`() = runTest { BroadcastProducer().use { broadcast -> - val track = broadcast.publishTrack("status", null) + val track = broadcast.publishTrack("status", TrackInfo(timescale = 1_000_000uL)) val consumer = track.consume(null) track.appendGroup().finish() track.appendGroup().finish() @@ -223,13 +223,55 @@ class SmokeTest { } } + @Test + fun `flate preserves optional timestamps`() = runTest { + for (timestamp in listOf(null, 123_456uL)) { + for (mode in listOf("snapshot", "stream")) { + BroadcastProducer().use { broadcast -> + val info = if (timestamp == null) null else TrackInfo(timescale = 1_000_000uL) + val track = broadcast.publishTrack("data", info) + val consumer = track.consume(null) + val payload = "payload".encodeToByteArray() + if (mode == "snapshot") { + val producer = dev.moq.flate.SnapshotProducer(broadcast, track, dev.moq.flate.Config()) + producer.update(payload, timestamp) + producer.finish() + } else { + val producer = dev.moq.flate.StreamProducer(broadcast, track, dev.moq.flate.Config()) + producer.append(payload, timestamp) + producer.finish() + } + val frame = consumer.readFrame() + assertEquals("payload", frame?.payload?.decodeToString()) + assertEquals(timestamp, frame?.timestampUs) + } + } + } + } + + @Test + fun `raw writes without timestamps stay untimed`() = runTest { + BroadcastProducer().use { broadcast -> + val track = broadcast.publishTrack("untimed", null) + val consumer = track.consume(null) + track.writeFrame(Frame(payload = "payload".encodeToByteArray())) + val frame = consumer.readFrame() + assertEquals("payload", frame?.payload?.decodeToString()) + assertNull(frame?.timestampUs) + assertNull(consumer.info().timescale) + track.finish() + } + } + @Test fun `catalog handle closes with its broadcast`() { val broadcast = BroadcastProducer() val catalog = CatalogProducer(broadcast) catalog.setSection("app", "{\"value\":42}") + catalog.now() broadcast.close() assertFailsWith { catalog.removeSection("app") } + assertFailsWith { catalog.now() } catalog.close() } diff --git a/py/moq-ffi/tests/exit_inside_callback.py b/py/moq-ffi/tests/exit_inside_callback.py index 7821b9b12a0..a519a519641 100644 --- a/py/moq-ffi/tests/exit_inside_callback.py +++ b/py/moq-ffi/tests/exit_inside_callback.py @@ -56,7 +56,7 @@ async def main() -> None: origin = moq_ffi.MoqOriginProducer(moq_ffi.MoqOriginConfig()) broadcast = origin.create_broadcast("exit") broadcast.announce(moq_ffi.MoqRoute()) - track = broadcast.publish_track("data", None) + track = broadcast.publish_track("data", moq_ffi.MoqTrackInfo(timescale=1_000_000)) consumer = await origin.consume().request_broadcast("exit") subscriber = await consumer.subscribe_track("data", None) diff --git a/py/moq-rs/README.md b/py/moq-rs/README.md index 03051090c06..570e8f33224 100644 --- a/py/moq-rs/README.md +++ b/py/moq-rs/README.md @@ -67,7 +67,7 @@ async def main(): # Write frames # Audio has no keyframes, so `cut` is what gives it group boundaries. - audio.write_frame(payload) + audio.write_frame(payload, timestamp=timedelta(0)) audio.cut() audio.write_frame(payload, timestamp=timedelta(milliseconds=20)) audio.cut() @@ -167,12 +167,12 @@ client = moq.Client( - `await .requested_track() → TrackRequest`. Call `.accept()` on it for a `TrackProducer`, or `.abort(code)` to reject. - Async iterator yielding `TrackRequest` - **`TrackProducer` / `GroupProducer`**. Write raw payloads with no codec parsing. - - `.write_frame(payload, timestamp=timedelta(0))` writes a payload with its presentation timestamp. + - `.write_frame(payload, timestamp=None)` writes a payload with optional capture time. - `.create_group(sequence)` creates a sparse or replayed group at an explicit sequence. - `.finish()` ends at the live edge; the handle remains so `.abort(error_code)` can still run. - `.finish_at(final_sequence)` declares the first group that will never be produced while leaving lower groups writable. - `.abort(error_code)` terminates the track or group with an application error. - - `.append_datagram(payload, timestamp=timedelta(0)) -> sequence` (`TrackProducer`) sends a best-effort datagram. Payloads are capped at 1200 bytes and there is no stream fallback. + - `.append_datagram(payload, timestamp=None) -> sequence` (`TrackProducer`) sends a best-effort datagram. Payloads are capped at 1200 bytes and there is no stream fallback. ### Media @@ -187,7 +187,8 @@ client = moq.Client( `media.ContainerStreamProducer(broadcast, format)` recovers framing from a byte stream. - `media.CatalogProducer(broadcast)` owns `set_video_properties`, `set_section`, and `remove_section`. It holds the broadcast weakly; writes fail with `Error.Closed` after closing - or releasing the broadcast. + or releasing the broadcast. `.now()` returns its current media time as `timedelta` and fixes + the clock for subsequent producers. - `await media.CatalogConsumer.subscribe(broadcast)` streams catalog snapshots; `await media.catalog(broadcast)` reads one snapshot and releases its subscription. - `await media.TrackConsumer.subscribe(broadcast, name, container, *, subscription=None)` @@ -198,10 +199,17 @@ client = moq.Client( `TrackConsumer.recv_group()` for arrival-order reads, with container media time on each frame as it lands. -`media.TrackProducer.write_frame(payload, timestamp=timedelta(0))` and `.flush(timestamp)` use -`timedelta`; returned `media.MediaFrame.timestamp` does too. `demand()` owns the track name and +`media.TrackProducer.write_frame(payload, timestamp)` requires the caller's capture time as +`timedelta`; `.flush(timestamp)` and returned `media.MediaFrame.timestamp` use it too. `demand()` owns the track name and subscriber waits. `.cut()` / `.seek(sequence)` draw group boundaries; `.finish()` ends the import. +### Data + +`moq.json.SnapshotProducer.update(value, timestamp=None)` and +`moq.json.StreamProducer.append(value, timestamp=None)` preserve optional capture time. +`moq.flate.SnapshotProducer` and `moq.flate.StreamProducer` offer the same operations for bytes. +Omitting time leaves data untimed; choose the track's `timescale` to match. + ### Subscribing - **`BroadcastConsumer`**. Subscribe to tracks within a broadcast. @@ -210,12 +218,12 @@ subscriber waits. `.cut()` / `.seek(sequence)` draw group boundaries; `.finish() - `await .next_group() → GroupConsumer | None`. Sequence order; what the default iteration yields. - `await .recv_group() → GroupConsumer | None`. Arrival order, which may be out of sequence. Prefer it when latency matters more than order. - `.groups_as_arrived()`. Async iterator over `recv_group()`. - - `.read_frame() -> Frame | None` returns the first timestamped frame of the next group. Empty groups are skipped; `None` is track EOF. + - `.read_frame() -> Frame | None` returns the first frame of the next group. Empty groups are skipped; `None` is track EOF. - `await .recv_datagram() -> Datagram | None` for best-effort raw track datagrams. - `.info() → TrackInfo` - `.update(subscription)`. Change delivery priority, staleness, or group range after subscribing. -- **`GroupConsumer`**. Async iterator of timestamped `Frame`s. - - `.read_frame() -> Frame | None` returns a timestamped raw frame. +- **`GroupConsumer`**. Async iterator of raw `Frame`s. + - `.read_frame() -> Frame | None` returns a raw frame with optional capture time. Every handle whose cleanup is `cancel()` is an async context manager, so exiting `async with` releases it: the consumers (`media.CatalogConsumer`, `media.TrackConsumer`, `media.GroupConsumer`, `TrackConsumer`, `AudioConsumer`, `GroupConsumer`, `json.SnapshotConsumer`, `json.StreamConsumer`, `AnnounceConsumer`, `AnnouncedBroadcast`) and the dynamic sources (`OriginDynamic`, `BroadcastDynamic`, `TrackDynamic`). @@ -236,7 +244,7 @@ Every handle whose cleanup is `cancel()` is an async context manager, so exiting ### Types - **`media.Catalog`**. `.audio: dict[str, Audio]`, `.video: dict[str, Video]`, `.display`, `.rotation`, `.flip`. -- **`Frame`**. `.payload: bytes`, `.timestamp: timedelta | None`. The unit of every write and every raw read; `None` only on a frame read from an untimed track. +- **`Frame`**. `.payload: bytes`, `.timestamp: timedelta | None`. The unit of every write and every raw read; `None` means untimed when publishing or reading. - **`media.MediaFrame`**. `.payload: bytes`, `.timestamp: timedelta`, `.keyframe: bool`. Returned by media subscriptions. `keyframe` marks a group start or video keyframe; for audio it is true only at a group start. - **`Datagram`**. `.sequence: int`, `.timestamp: timedelta | None`, `.payload: bytes`. Delivered only on datagram-capable transports with lite-05 or newer moq-lite, or moq-transport. - **`media.Audio`**. `.codec`, `.sample_rate`, `.channel_count`, `.bitrate`, `.enabled`, `.description`. diff --git a/py/moq-rs/docs/index.md b/py/moq-rs/docs/index.md index 7837a93e066..0f3c42e2772 100644 --- a/py/moq-rs/docs/index.md +++ b/py/moq-rs/docs/index.md @@ -124,6 +124,19 @@ broadcast, and producers advertise it in the catalog. StreamConsumer ``` +## Opaque data + +```{eval-rst} +.. currentmodule:: moq.flate + +.. autosummary:: + :toctree: api + :nosignatures: + + SnapshotProducer + StreamProducer +``` + ## Origin and announcements ```{eval-rst} diff --git a/py/moq-rs/examples/clock.py b/py/moq-rs/examples/clock.py index 6d53edb906b..e09a42c0e95 100644 --- a/py/moq-rs/examples/clock.py +++ b/py/moq-rs/examples/clock.py @@ -18,7 +18,7 @@ async def publish(url: str, broadcast_name: str, track_name: str, tls_verify: bool) -> None: async with moq.Client(url, tls_verify=tls_verify) as client: broadcast = client.create_broadcast(broadcast_name) - track = broadcast.publish_track(track_name) + track = broadcast.publish_track(track_name, moq.TrackInfo(timescale=1_000_000)) broadcast.announce() print(f"publishing {broadcast_name!r} track={track_name!r} at {url}") diff --git a/py/moq-rs/examples/serve_clock.py b/py/moq-rs/examples/serve_clock.py index 3fe7c8f5213..8fff413851b 100644 --- a/py/moq-rs/examples/serve_clock.py +++ b/py/moq-rs/examples/serve_clock.py @@ -21,7 +21,7 @@ async def run(bind: str, broadcast_name: str, track_name: str, host: str) -> None: async with moq.Server(bind, tls_generate=[host]) as server: broadcast = server.create_broadcast(broadcast_name) - track = broadcast.publish_track(track_name) + track = broadcast.publish_track(track_name, moq.TrackInfo(timescale=1_000_000)) broadcast.announce() print(f"serving {broadcast_name!r} track={track_name!r} on https://{server.local_addr}") for fp in server.cert_fingerprints(): diff --git a/py/moq-rs/moq/__init__.py b/py/moq-rs/moq/__init__.py index d5a64c7c4ac..d83c275c224 100644 --- a/py/moq-rs/moq/__init__.py +++ b/py/moq-rs/moq/__init__.py @@ -5,7 +5,8 @@ from moq_ffi import MoqError as Error -# A submodule, not in __all__: a star import would shadow the stdlib `json`. +# Layer namespaces stay out of __all__; json would shadow the stdlib module. +from . import flate as flate from . import json as json from .client import Client, connect from .epoch import epoch_time, mint_epoch diff --git a/py/moq-rs/moq/_records.py b/py/moq-rs/moq/_records.py index adc2414b94b..af707a14787 100644 --- a/py/moq-rs/moq/_records.py +++ b/py/moq-rs/moq/_records.py @@ -52,12 +52,11 @@ def _opt_from_us(us: int | None) -> timedelta | None: class Frame: """A raw track frame: a payload and its presentation timestamp. - ``timestamp`` is ``None`` on a frame read from an untimed track. A raw track - published here is timed, so writing one needs it. + ``timestamp`` is ``None`` on an untimed track, on both publish and receive. """ payload: bytes - timestamp: timedelta | None = timedelta(0) + timestamp: timedelta | None = None def _ffi(self) -> MoqFrame: return MoqFrame(payload=self.payload, timestamp_us=_opt_us(self.timestamp, "timestamp")) @@ -120,8 +119,7 @@ class TrackInfo: ``priority`` defaults to 127, the middle of the range. ``max_age`` is how long the publisher caches a non-latest group, ``None`` for no limit. ``timescale`` is ticks - per second: ``None`` uses microseconds when publishing, and means the source - declared no timeline on a received track. + per second: ``None`` means the track is untimed, on both publish and receive. """ priority: int = 127 diff --git a/py/moq-rs/moq/flate.py b/py/moq-rs/moq/flate.py new file mode 100644 index 00000000000..bd06e7c1d3e --- /dev/null +++ b/py/moq-rs/moq/flate.py @@ -0,0 +1,60 @@ +"""Publish opaque payload tracks, mirroring the ``moq-flate`` crate.""" + +from __future__ import annotations + +from datetime import timedelta + +from moq_ffi import MoqFlateConfig, MoqFlateSnapshotProducer, MoqFlateStreamProducer + +from . import publish +from ._records import _opt_us + +__all__ = ["SnapshotProducer", "StreamProducer"] + + +class SnapshotProducer: + """Publish the latest opaque payload, advertised in the broadcast catalog.""" + + def __init__( + self, + broadcast: publish.BroadcastProducer, + track: publish.TrackProducer, + *, + compression: bool = False, + mime: str | None = None, + ) -> None: + self._inner = MoqFlateSnapshotProducer( + broadcast._inner, track._inner, MoqFlateConfig(compression=compression, mime=mime) + ) + + def update(self, payload: bytes, *, timestamp: timedelta | None = None) -> None: + """Replace the payload at the given broadcast time, or leave it untimed.""" + self._inner.update(payload, _opt_us(timestamp, "timestamp")) + + def finish(self) -> None: + """Finish the track and retire its catalog entry.""" + self._inner.finish() + + +class StreamProducer: + """Publish an ordered opaque payload log, advertised in the broadcast catalog.""" + + def __init__( + self, + broadcast: publish.BroadcastProducer, + track: publish.TrackProducer, + *, + compression: bool = False, + mime: str | None = None, + ) -> None: + self._inner = MoqFlateStreamProducer( + broadcast._inner, track._inner, MoqFlateConfig(compression=compression, mime=mime) + ) + + def append(self, payload: bytes, *, timestamp: timedelta | None = None) -> None: + """Append a payload at the given broadcast time, or leave it untimed.""" + self._inner.append(payload, _opt_us(timestamp, "timestamp")) + + def finish(self) -> None: + """Finish the track and retire its catalog entry.""" + self._inner.finish() diff --git a/py/moq-rs/moq/json.py b/py/moq-rs/moq/json.py index 274914e8ea7..a82414a1863 100644 --- a/py/moq-rs/moq/json.py +++ b/py/moq-rs/moq/json.py @@ -9,6 +9,7 @@ from __future__ import annotations import json +from datetime import timedelta from typing import Any from moq_ffi import ( @@ -20,6 +21,7 @@ MoqJsonStreamProducer, ) +from ._records import _opt_us from .publish import BroadcastProducer, TrackDemand, TrackProducer from .subscribe import TrackConsumer @@ -56,9 +58,9 @@ def demand(self) -> TrackDemand: """A watch-only handle to whether this track has subscribers.""" return TrackDemand(self._inner.demand()) - def update(self, value: Any) -> None: + def update(self, value: Any, *, timestamp: timedelta | None = None) -> None: """Publish a new value. A no-op if unchanged from the previous update.""" - self._inner.update(json.dumps(value)) + self._inner.update(json.dumps(value), _opt_us(timestamp, "timestamp")) def finish(self) -> None: """Finish the track, closing any open group.""" @@ -81,9 +83,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) -> None: + def append(self, value: Any, *, timestamp: timedelta | None = None) -> None: """Append one record to the log.""" - self._inner.append(json.dumps(value)) + self._inner.append(json.dumps(value), _opt_us(timestamp, "timestamp")) def finish(self) -> None: """Finish the track, closing the group.""" diff --git a/py/moq-rs/moq/media.py b/py/moq-rs/moq/media.py index 1a6038a6994..e98272b661f 100644 --- a/py/moq-rs/moq/media.py +++ b/py/moq-rs/moq/media.py @@ -100,6 +100,10 @@ class CatalogProducer: def __init__(self, broadcast: BroadcastProducer) -> None: self._inner = MoqMediaCatalogProducer(broadcast._inner) + def now(self) -> timedelta: + """Read the broadcast clock, fixing it for subsequent media producers.""" + return _from_us(self._inner.now()) + def set_video_properties(self, properties: VideoProperties) -> None: """Replace the video properties shared by every rendition.""" self._inner.set_video_properties(properties) @@ -137,7 +141,7 @@ def demand(self) -> TrackDemand: """A watch-only handle to whether this media track has subscribers.""" return TrackDemand(self._inner.demand()) - def write_frame(self, payload: bytes, timestamp: timedelta = timedelta(0)) -> None: + def write_frame(self, payload: bytes, timestamp: timedelta) -> None: """Write one encoded frame with a presentation timestamp.""" self._inner.write_frame(Frame(payload, timestamp)._ffi()) diff --git a/py/moq-rs/moq/publish.py b/py/moq-rs/moq/publish.py index 5492ddd1faa..2b5787739cc 100644 --- a/py/moq-rs/moq/publish.py +++ b/py/moq-rs/moq/publish.py @@ -55,7 +55,7 @@ def consume(self) -> GroupConsumer: return GroupConsumer(self._inner.consume()) - def write_frame(self, payload: bytes, timestamp: timedelta = timedelta(0)) -> None: + def write_frame(self, payload: bytes, timestamp: timedelta | None = None) -> None: """Write a frame with its presentation timestamp.""" self._inner.write_frame(Frame(payload, timestamp)._ffi()) @@ -126,11 +126,11 @@ def create_group(self, sequence: int) -> GroupProducer: """Create a group with an explicit sequence number.""" return GroupProducer(self._inner.create_group(sequence)) - def write_frame(self, payload: bytes, timestamp: timedelta = timedelta(0)) -> None: + def write_frame(self, payload: bytes, timestamp: timedelta | None = None) -> None: """Write a single-frame group with its presentation timestamp.""" self._inner.write_frame(Frame(payload, timestamp)._ffi()) - def append_datagram(self, payload: bytes, timestamp: timedelta = timedelta(0)) -> int: + def append_datagram(self, payload: bytes, timestamp: timedelta | None = None) -> int: """Send a best-effort datagram and return its sequence number. Payloads are capped at 1200 bytes. Datagram delivery requires a datagram-capable diff --git a/py/moq-rs/moq/subscribe.py b/py/moq-rs/moq/subscribe.py index a5000fe6f1e..417606048fd 100644 --- a/py/moq-rs/moq/subscribe.py +++ b/py/moq-rs/moq/subscribe.py @@ -34,7 +34,7 @@ def _frame(frame: MoqFrame | None) -> Frame | None: class GroupConsumer: - """Async iterator of timestamped frames within a single group.""" + """Async iterator of raw frames within a single group.""" def __init__(self, inner: MoqGroupConsumer) -> None: self._inner = inner @@ -60,7 +60,7 @@ async def __anext__(self) -> Frame: return Frame._from_ffi(frame) async def read_frame(self) -> Frame | None: - """Read the next timestamped frame. Returns `None` when the group ends.""" + """Read the next raw frame. Returns `None` when the group ends.""" return _frame(await self._inner.read_frame()) def cancel(self) -> None: @@ -74,7 +74,7 @@ class TrackConsumer: Iterating yields groups via :meth:`next_group`. Use :meth:`recv_group` (or :meth:`groups_as_arrived`) for arrival order instead. - Each group is itself an async iterator of timestamped frames. Same pattern as + Each group is itself an async iterator of raw frames. Same pattern as moq-boy's status/command tracks (one frame per group), but multi-frame groups are also supported. """ @@ -134,7 +134,7 @@ async def next_group(self) -> GroupConsumer | None: return GroupConsumer(group) async def read_frame(self) -> Frame | None: - """Read the first timestamped frame of the next group. + """Read the first raw frame of the next group. Convenience for tracks using one-frame-per-group (like moq-boy's status/command tracks). Completed empty groups are skipped. Returns diff --git a/py/moq-rs/tests/test_data_timestamps.py b/py/moq-rs/tests/test_data_timestamps.py new file mode 100644 index 00000000000..4a06a1009a0 --- /dev/null +++ b/py/moq-rs/tests/test_data_timestamps.py @@ -0,0 +1,84 @@ +"""Data publishers preserve the caller's capture time, including absence.""" + +import asyncio +import json +import struct +from datetime import timedelta + +import moq +import moq_ffi +import pytest + + +@pytest.mark.parametrize("mode", ["snapshot", "stream"]) +@pytest.mark.parametrize("timestamp", [None, timedelta(microseconds=123_456)]) +async def test_flate_timestamp_round_trip(mode: str, timestamp: timedelta | None): + broadcast = moq.BroadcastProducer() + track = broadcast.publish_track("payload", moq.TrackInfo(timescale=None if timestamp is None else 1_000_000)) + consumer = track.consume() + payload = b"opaque payload" + if mode == "snapshot": + snapshot = moq.flate.SnapshotProducer(broadcast, track, mime="application/octet-stream") + snapshot.update(payload, timestamp=timestamp) + snapshot.finish() + else: + stream = moq.flate.StreamProducer(broadcast, track, mime="application/octet-stream") + stream.append(payload, timestamp=timestamp) + stream.finish() + frame = await asyncio.wait_for(consumer.read_frame(), timeout=5.0) + assert frame is not None + assert frame.payload == payload + assert frame.timestamp == timestamp + broadcast.close() + + +@pytest.mark.parametrize("mode", ["snapshot", "stream"]) +@pytest.mark.parametrize("timestamp", [None, timedelta(microseconds=123_456)]) +async def test_json_timestamp_round_trip(mode: str, timestamp: timedelta | None): + broadcast = moq.BroadcastProducer() + track = broadcast.publish_track("value", moq.TrackInfo(timescale=None if timestamp is None else 1_000_000)) + consumer = track.consume() + value = {"n": 1} + if mode == "snapshot": + snapshot = moq.json.SnapshotProducer(broadcast, track) + snapshot.update(value, timestamp=timestamp) + snapshot.finish() + else: + stream = moq.json.StreamProducer(broadcast, track) + stream.append(value, timestamp=timestamp) + stream.finish() + frame = await asyncio.wait_for(consumer.read_frame(), timeout=5.0) + assert frame is not None + assert json.loads(frame.payload) == value + assert frame.timestamp == timestamp + broadcast.close() + + +def test_catalog_now_uses_a_weak_broadcast_handle(): + broadcast = moq.BroadcastProducer() + catalog = moq.media.CatalogProducer(broadcast) + assert catalog.now() >= timedelta(0) + broadcast.close() + with pytest.raises(moq.Error.Closed): # type: ignore[attr-defined] + catalog.now() + + +def test_whole_media_frames_require_the_callers_timestamp(): + broadcast = moq.BroadcastProducer() + head = ( + b"OpusHead" + + bytes([1, 2]) + + struct.pack("`, the type the producers -take in [Publishing never invents a timestamp](/quest/m1/publish-timestamp.md). +Decided: `next()` and `poll_next()` return `Timed`, the same type the producers take. `at` is the frame's media timestamp on the track's timescale, and `None` for an untimed frame: absence survives the wire rather than becoming arrival time (decided 2026-10-01, landed in [#4822](https://github.com/moq-dev/moq/pull/4822)). A republisher passes `at` straight to a moq-mux data producer. @@ -44,7 +43,3 @@ this contract, so this quest neither duplicates that work nor waits on m2. `@moq already return `Timed` with the same `next()` and `latest()`. Public API: breaking. Wire: none. - -## Required - -- [Publishing never invents a timestamp](/quest/m1/publish-timestamp.md) - gives `Timed.at` its untimed meaning, the type this returns diff --git a/quest/m1/publish-timestamp.md b/quest/m1/publish-timestamp.md deleted file mode 100644 index 1f7de4dae4b..00000000000 --- a/quest/m1/publish-timestamp.md +++ /dev/null @@ -1,70 +0,0 @@ -# [M] Publishing never invents a timestamp - -## Goal - -No publish API fills in a timestamp the caller didn't give. A frame's -timestamp is the publisher's statement of when the content happened; a payload -published without one goes out untimed and arrives untimed. Covers moq-net, -moq-json, moq-flate, moq-mux, moq-ffi, and every binding wrapper (Python, -Swift, Kotlin, Go, Dart). Not libmoq, which the -[Generated C bindings](/quest/m1/c/README.md) replace. - -## Plan - -Decided (2026-10-01), reversing the 2026-09-30 "timestamp required" plan: the -timestamp is optional end to end, on the wire and in every API, and absent -means untimed. A library never substitutes now, wall clock, or arrival time. -How absence travels through the model and over the wire is the untimed model -([#4822](https://github.com/moq-dev/moq/pull/4822)) and -lite-07's untimed encoding; this quest -removes every place that fills one in. - -Today `Timed.at: None` means "stamp when written": moq-json and moq-flate -fill `Timestamp::now()` (moq-net's clock, not the broadcast's), and moq-mux's -data producers fill the broadcast clock's `now()`. The FFI raw -`MoqFrame.timestamp_us` and `MoqDatagram.timestamp_us` are optional, but a -raw track published through moq-ffi is always timed, and the Python and -Swift wrappers default them to 0. - -- `moq_net::Timed` drops its unused clock parameter `T` (decided 2026-10-06: - here rather than in #4822, which is already large). That's a breaking - change and gets an upgrade note. Timedness is per track - (the untimed model, [#4822](https://github.com/moq-dev/moq/pull/4822), decided 2026-10-05), so an - untimed payload belongs on an untimed track, and one appended to a timed - track is refused. The json/flate consumers return the same type - (see [Data consumer timestamps](/quest/m1/data-consumer-timestamps.md)). -- moq-json (snapshot, stream, and window, whose `push` always stamps now) and - moq-flate producers take `Timed<_, Timestamp>` and write `None` as untimed. -- moq-mux data producers already take `Timed<_, Timestamp>` on the broadcast - clock. Here `None` stops meaning the clock's now and goes out untimed. - `catalog::data::Listing::record` already samples `delay` and `jitter` only - for timed writes. -- Publishers inside the repository (hang catalog snapshots, MSF, stats, room - chat, examples) pass their clock's now explicitly. -- moq-ffi: data producers take an optional timestamp in microseconds on the - broadcast clock, unchecked, as Rust does. moq-ffi exposes the broadcast - clock's `now()` so callers have a value to stamp with. - Decided 2026-10-08, replacing the 2026-10-07 rule that a raw track - published through moq-ffi is always timed: `MoqTrackInfo`'s null - `timescale` means untimed when publishing, as it already does on a - received track. A received info then round-trips, and an untimed raw track - needs no API of its own. A timed raw track names its timescale, and a - write that doesn't match the track's timedness is refused. The wrappers' - `= 0` defaults go with it. -- Go (`go/wrapper/moq`) and Python (`py/moq-rs`) wrap only the JSON - producers; [#4137](https://github.com/moq-dev/moq/pull/4137) added - `publish_binary_snapshot` / `publish_binary_stream` (now the - `MoqFlateSnapshotProducer` / `MoqFlateStreamProducer` constructors) to - moq-ffi without them. Add hand-written flate wrappers there, in a `flate` - namespace beside each wrapper's `json` one (see `rs/moq-ffi/AGENTS.md`). The maintainer asked for this. - Each wrapper gets a test that a timestamp round-trips and an untimed payload - arrives untimed. -- Docs: "stamped when written" in `doc/lib/rs/{moq-json,moq-flate}.md` and - `rs/moq-net/src/model/timed.rs`, plus `doc/lib/{py,swift,kt,go,dart}`. - -Public API: breaking. Wire: none here; absence on the wire lands -with the untimed implementation quests. - -## Related - -- [FFI shape](/quest/m1/ffi-shape/README.md) - moves the data producers this changes into `json` and `flate` namespaces in the same merge, so this is ready once #4519 lands rather than waiting on the codec child (2026-10-06 audit) diff --git a/quest/m2/flate.md b/quest/m2/flate.md index 51b0df835a2..1ef5086742b 100644 --- a/quest/m2/flate.md +++ b/quest/m2/flate.md @@ -19,17 +19,16 @@ already owns the per-group window a caller could otherwise desynchronize. Bind those track modes, not the bare codec: a `frame()` call across the FFI boundary invites the window desync the track modes exist to prevent. -The `MoqFlate*Producer` constructors landed in #4519. Reconciled 2026-10-10: -[Publish timestamps](/quest/m1/publish-timestamp.md) owns missing producer -wrappers, including Python and Go. This quest owns the remaining consumers -and interop coverage; it does not wait for unrelated FFI-shape children. +The `MoqFlate*Producer` constructors landed in #4519, and producer wrappers +now exist in every binding with explicit optional timestamps. This quest owns +the remaining consumers and interop coverage; it does not wait for unrelated +FFI-shape children. What remains: - moq-ffi has no consume side for flate tracks. Add consumers mirroring the `json` ones so each wrapper can read what it writes. - Add consumers to each wrapper's `flate` namespace, following `json` and - the timestamp-preserving `next()` / `latest()` contract. Do not duplicate - the producer work owned by publish-timestamp. + the timestamp-preserving `next()` / `latest()` contract. - Document in `doc/lib/{py,swift,kt,go,dart}` beside the JSON entry. - Tests: a round trip in each wrapper that has tests, and one cross-language check that a wrapper-published group decodes with `@moq/flate`. Run diff --git a/rs/moq-boy/src/status.rs b/rs/moq-boy/src/status.rs index 7ae3e28d4dd..6d726b38d1e 100644 --- a/rs/moq-boy/src/status.rs +++ b/rs/moq-boy/src/status.rs @@ -52,7 +52,10 @@ impl StatusPublisher { /// Publish status, a no-op if unchanged since the last call. pub fn publish(&mut self, status: &Status) { - if let Err(err) = self.producer.update(status) { + if let Err(err) = self + .producer + .update(moq_net::Timed::from(status).at(moq_net::Timestamp::now())) + { tracing::warn!(%err, "failed to publish status"); } } diff --git a/rs/moq-c/src/publish.rs b/rs/moq-c/src/publish.rs index 17e06fe0fe7..1433db00996 100644 --- a/rs/moq-c/src/publish.rs +++ b/rs/moq-c/src/publish.rs @@ -50,6 +50,13 @@ struct Broadcast { audio: BTreeMap, } +// Legacy C data methods stamp writes on one fixed broadcast clock without retaining +// another catalog handle after a failed stream retires its listing. +struct Data { + producer: T, + clock: moq_mux::Clock, +} + #[derive(Default)] pub struct Publish { /// Active broadcast producers for publishing. @@ -72,16 +79,16 @@ pub struct Publish { /// JSON snapshot producers (lossy latest-value tracks), each advertised in its broadcast's /// catalog for as long as it lives. - json_snapshot: NonZeroSlab>, + json_snapshot: NonZeroSlab>>, /// JSON stream producers (lossless append-log tracks), advertised the same way. - json_stream: NonZeroSlab>, + json_stream: NonZeroSlab>>, /// Binary snapshot producers (lossy latest-value tracks of opaque bytes), advertised the same way. - binary_snapshot: NonZeroSlab>, + binary_snapshot: NonZeroSlab>>, /// Binary stream producers (lossless append-log tracks of opaque bytes), advertised the same way. - binary_stream: NonZeroSlab>, + binary_stream: NonZeroSlab>>, /// Demand watchers. Close signals shutdown; the task delivers a final callback, then removes itself. demand: NonZeroSlab>, @@ -768,13 +775,17 @@ impl Publish { broadcast: Id, name: &str, publish: impl FnOnce(&moq_mux::catalog::Producer, moq_net::track::Producer) -> moq_mux::Result, - ) -> Result { + ) -> Result, Error> { let broadcast = self.broadcasts.get_mut(broadcast).ok_or(Error::BroadcastNotFound)?; let track = broadcast.producer.create_track( name, moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI), )?; - Ok(publish(&broadcast.catalog, track)?) + let producer = publish(&broadcast.catalog, track)?; + Ok(Data { + producer, + clock: broadcast.catalog.clock(), + }) } /// Create a JSON snapshot track (lossy latest-value) on a broadcast, advertised in its catalog. @@ -790,14 +801,16 @@ impl Publish { /// Publish a new value to a JSON snapshot track. A no-op if unchanged. pub fn json_snapshot_update(&mut self, json: Id, value: serde_json::Value) -> Result<(), Error> { let producer = self.json_snapshot.get_mut(json).ok_or(Error::TrackNotFound)?; - producer.update(&value)?; + producer + .producer + .update(moq_net::Timed::from(&value).at(producer.clock.now()))?; Ok(()) } /// Finish a JSON snapshot track and retire its catalog entry. No more values can be published. pub fn json_snapshot_finish(&mut self, json: Id) -> Result<(), Error> { let producer = self.json_snapshot.remove(json).ok_or(Error::TrackNotFound)?; - producer.finish()?; + producer.producer.finish()?; Ok(()) } @@ -813,14 +826,16 @@ impl Publish { /// Append one record to a JSON stream track. pub fn json_stream_append(&mut self, stream: Id, value: serde_json::Value) -> Result<(), Error> { let producer = self.json_stream.get_mut(stream).ok_or(Error::TrackNotFound)?; - producer.append(&value)?; + producer + .producer + .append(moq_net::Timed::from(&value).at(producer.clock.now()))?; Ok(()) } /// Finish a JSON stream track and retire its catalog entry. No more records can be appended. pub fn json_stream_finish(&mut self, stream: Id) -> Result<(), Error> { let producer = self.json_stream.remove(stream).ok_or(Error::TrackNotFound)?; - producer.finish()?; + producer.producer.finish()?; Ok(()) } @@ -834,14 +849,16 @@ impl Publish { /// Publish a new payload to a binary snapshot track, superseding the last. pub fn binary_snapshot_update(&mut self, binary: Id, payload: &[u8]) -> Result<(), Error> { let producer = self.binary_snapshot.get_mut(binary).ok_or(Error::TrackNotFound)?; - producer.update(bytes::Bytes::copy_from_slice(payload))?; + producer + .producer + .update(moq_net::Timed::from(bytes::Bytes::copy_from_slice(payload)).at(producer.clock.now()))?; Ok(()) } /// Finish a binary snapshot track and retire its catalog entry. pub fn binary_snapshot_finish(&mut self, binary: Id) -> Result<(), Error> { let producer = self.binary_snapshot.remove(binary).ok_or(Error::TrackNotFound)?; - producer.finish()?; + producer.producer.finish()?; Ok(()) } @@ -855,14 +872,16 @@ impl Publish { /// Append one payload to a binary stream track. pub fn binary_stream_append(&mut self, stream: Id, payload: &[u8]) -> Result<(), Error> { let producer = self.binary_stream.get_mut(stream).ok_or(Error::TrackNotFound)?; - producer.append(bytes::Bytes::copy_from_slice(payload))?; + producer + .producer + .append(moq_net::Timed::from(bytes::Bytes::copy_from_slice(payload)).at(producer.clock.now()))?; Ok(()) } /// Finish a binary stream track and retire its catalog entry. pub fn binary_stream_finish(&mut self, stream: Id) -> Result<(), Error> { let producer = self.binary_stream.remove(stream).ok_or(Error::TrackNotFound)?; - producer.finish()?; + producer.producer.finish()?; Ok(()) } diff --git a/rs/moq-ffi/src/flate.rs b/rs/moq-ffi/src/flate.rs index d2df56cbac6..e389c0c729c 100644 --- a/rs/moq-ffi/src/flate.rs +++ b/rs/moq-ffi/src/flate.rs @@ -67,10 +67,15 @@ impl MoqFlateSnapshotProducer { } /// Publish a new payload, superseding the last. - pub fn update(&self, payload: Vec) -> Result<(), MoqError> { + /// `timestamp_us` is on the broadcast clock; null publishes untimed. + #[uniffi::method(default(timestamp_us = None))] + pub fn update(&self, payload: Vec, timestamp_us: Option) -> Result<(), MoqError> { let _guard = crate::ffi::enter(); let mut guard = self.inner.lock().unwrap(); - guard.as_mut().ok_or(MoqError::Closed)?.update(payload)?; + guard.as_mut().ok_or(MoqError::Closed)?.update(moq_net::Timed { + value: payload.into(), + at: timestamp_us.map(moq_net::Timestamp::from_micros).transpose()?, + })?; Ok(()) } @@ -114,10 +119,15 @@ impl MoqFlateStreamProducer { } /// Append one payload to the log. - pub fn append(&self, payload: Vec) -> Result<(), MoqError> { + /// `timestamp_us` is on the broadcast clock; null publishes untimed. + #[uniffi::method(default(timestamp_us = None))] + pub fn append(&self, payload: Vec, timestamp_us: Option) -> Result<(), MoqError> { let _guard = crate::ffi::enter(); let mut guard = self.inner.lock().unwrap(); - guard.as_mut().ok_or(MoqError::Closed)?.append(payload)?; + guard.as_mut().ok_or(MoqError::Closed)?.append(moq_net::Timed { + value: payload.into(), + at: timestamp_us.map(moq_net::Timestamp::from_micros).transpose()?, + })?; Ok(()) } diff --git a/rs/moq-ffi/src/json.rs b/rs/moq-ffi/src/json.rs index 5a8ec3f30e8..12577040dab 100644 --- a/rs/moq-ffi/src/json.rs +++ b/rs/moq-ffi/src/json.rs @@ -137,12 +137,17 @@ 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. - pub fn update(&self, value: String) -> Result<(), MoqError> { + /// `timestamp_us` is on the broadcast clock; null publishes untimed. + #[uniffi::method(default(timestamp_us = None))] + pub fn update(&self, value: String, timestamp_us: Option) -> Result<(), MoqError> { let _guard = crate::ffi::enter(); let value: Value = serde_json::from_str(&value)?; let mut guard = self.inner.lock().unwrap(); let producer = guard.as_mut().ok_or(MoqError::Closed)?; - producer.update(&value)?; + producer.update(moq_net::Timed { + value: &value, + at: timestamp_us.map(moq_net::Timestamp::from_micros).transpose()?, + })?; Ok(()) } @@ -244,12 +249,17 @@ impl MoqJsonStreamProducer { } /// Append one record to the log. `value` is a JSON document. - pub fn append(&self, value: String) -> Result<(), MoqError> { + /// `timestamp_us` is on the broadcast clock; null publishes untimed. + #[uniffi::method(default(timestamp_us = None))] + pub fn append(&self, value: String, timestamp_us: Option) -> Result<(), MoqError> { let _guard = crate::ffi::enter(); let value: Value = serde_json::from_str(&value)?; let mut guard = self.inner.lock().unwrap(); let producer = guard.as_mut().ok_or(MoqError::Closed)?; - producer.append(&value)?; + producer.append(moq_net::Timed { + value: &value, + at: timestamp_us.map(moq_net::Timestamp::from_micros).transpose()?, + })?; Ok(()) } diff --git a/rs/moq-ffi/src/media.rs b/rs/moq-ffi/src/media.rs index b9457a21707..e769bb6bcdd 100644 --- a/rs/moq-ffi/src/media.rs +++ b/rs/moq-ffi/src/media.rs @@ -148,8 +148,7 @@ pub struct MoqAudio { pub struct MoqFrame { /// The frame payload. pub payload: Vec, - /// Presentation timestamp in microseconds, or null on a frame read from an untimed - /// track. A raw track published here is timed, so writing one needs it. + /// Presentation timestamp in microseconds, or null on an untimed track, on both publish and receive. #[uniffi(default = None)] pub timestamp_us: Option, } @@ -174,8 +173,7 @@ pub struct MoqDatagram { /// Per-track sequence number, shared with groups. #[uniffi(default = 0)] pub sequence: u64, - /// Presentation timestamp in microseconds, or null on a datagram read from an untimed - /// track. A raw track published here is timed, so appending one needs it. + /// Presentation timestamp in microseconds, or null on an untimed track, on both publish and receive. #[uniffi(default = None)] pub timestamp_us: Option, /// Datagram payload, capped at 1200 bytes. @@ -555,6 +553,16 @@ impl MoqMediaCatalogProducer { })) } + /// Read the broadcast clock in microseconds, fixing it for subsequent media producers. + pub fn now(&self) -> Result { + let _guard = crate::ffi::enter(); + self.broadcast.upgrade().ok_or(MoqError::Closed)?.with_state(|state| { + u64::try_from(state.catalog.clock().now().as_micros()).map_err(|_| MoqError::Codec { + reason: "broadcast clock exceeds microsecond timestamp range".into(), + }) + }) + } + /// Replace shared video properties, clearing fields that are absent. /// /// Rotation is clockwise and normalized to the nearest quarter turn. @@ -817,19 +825,19 @@ impl MoqMediaTrackProducer { /// Write `frame` to this track. /// /// The importer derives keyframe status from the bitstream, so a [`MoqFrame`] carries only the - /// payload and its timestamp. + /// payload and its caller-supplied timestamp. A missing timestamp is refused. pub fn write_frame(&self, frame: MoqFrame) -> Result<(), MoqError> { let _guard = crate::ffi::enter(); let mut guard = self.inner.lock().unwrap(); let media = guard.as_mut().ok_or(MoqError::Closed)?; - let timestamp = frame - .timestamp_us - .map(hang::container::Timestamp::from_micros) - .transpose()?; + let timestamp = + hang::container::Timestamp::from_micros(frame.timestamp_us.ok_or_else(|| MoqError::Codec { + reason: "whole media frames require a timestamp".into(), + })?)?; media .import - .decode(&frame.payload, timestamp) + .decode(&frame.payload, Some(timestamp)) .map_err(|err| MoqError::Codec { reason: format!("decode failed: {err}"), })?; @@ -1299,6 +1307,7 @@ mod catalog_tests { Err(MoqError::Closed) )); assert!(matches!(catalog.remove_section("app".into()), Err(MoqError::Closed))); + assert!(matches!(catalog.now(), Err(MoqError::Closed))); } #[test] @@ -1306,6 +1315,7 @@ mod catalog_tests { let broadcast = MoqBroadcastProducer::new().unwrap(); let catalog = MoqMediaCatalogProducer::new(broadcast.clone()).unwrap(); broadcast.close().unwrap(); + assert!(matches!(catalog.now(), Err(MoqError::Closed))); assert!(matches!( catalog.set_video_properties(MoqVideoProperties::default()), Err(MoqError::Closed) diff --git a/rs/moq-ffi/src/producer.rs b/rs/moq-ffi/src/producer.rs index bfe0be88030..19b79e08c08 100644 --- a/rs/moq-ffi/src/producer.rs +++ b/rs/moq-ffi/src/producer.rs @@ -11,7 +11,7 @@ use crate::media::MoqFrame; /// Publisher-side track properties, mirroring [`moq_net::track::Info`]. /// /// Construct with the fields you care about; the rest use raw-track defaults -/// (priority 127, no publisher age limit, microsecond timescale). +/// (priority 127, no publisher age limit, untimed). #[derive(Clone, uniffi::Record)] pub struct MoqTrackInfo { /// Priority, used only to break ties between subscriptions of equal subscriber priority. @@ -23,8 +23,7 @@ pub struct MoqTrackInfo { /// [`MoqSubscription::max_delay_us`](crate::consumer::MoqSubscription::max_delay_us). #[uniffi(default = None)] pub max_age_us: Option, - /// Per-frame timescale in ticks per second. Null uses microseconds when publishing, and - /// means the source declared no timeline on a received track. + /// Per-frame timescale in ticks per second, or null for an untimed track. #[uniffi(default = None)] pub timescale: Option, } @@ -33,9 +32,7 @@ impl TryFrom for moq_net::track::Info { type Error = MoqError; fn try_from(info: MoqTrackInfo) -> Result { - let mut out = moq_net::track::Info::default() - .with_timescale(moq_net::Timescale::MICRO) - .with_priority(info.priority); + let mut out = moq_net::track::Info::default().with_priority(info.priority); if let Some(us) = info.max_age_us { out = out.with_max_age(std::time::Duration::from_micros(us)); } @@ -52,7 +49,7 @@ impl TryFrom for moq_net::track::Info { fn raw_track_info(info: Option) -> Result { info.map(moq_net::track::Info::try_from) .transpose() - .map(|info| info.unwrap_or_else(|| moq_net::track::Info::default().with_timescale(moq_net::Timescale::MICRO))) + .map(|info| info.unwrap_or_default()) } impl TryFrom<&moq_net::track::Info> for MoqTrackInfo { @@ -530,10 +527,9 @@ impl MoqTrackProducer { /// Write `frame` as a single-frame group. /// - /// Raw tracks default to a microsecond timescale. Custom timescales may round - /// the timestamp during conversion. A frame without one is refused with - /// [`MoqProtocolKind::TimestampMismatch`](crate::error::MoqProtocolKind::TimestampMismatch): raw - /// tracks are timed. + /// Custom timescales may round the timestamp during conversion. The frame must + /// match its track's timedness, otherwise it is refused with + /// [`MoqProtocolKind::TimestampMismatch`](crate::error::MoqProtocolKind::TimestampMismatch). pub fn write_frame(&self, frame: MoqFrame) -> Result<(), MoqError> { let _guard = crate::ffi::enter(); let timestamp = frame.timestamp_us.map(moq_net::Timestamp::from_micros).transpose()?; @@ -546,8 +542,8 @@ impl MoqTrackProducer { /// Send `frame` as a best-effort datagram, returning the sequence number assigned to it. /// /// The payload must be at most 1200 bytes. Datagrams are only delivered on transports and - /// wire versions with a datagram channel; there is no stream fallback. Like a frame, a - /// datagram without a timestamp is refused. + /// wire versions with a datagram channel; there is no stream fallback. Like a frame, + /// its timestamp must match the track's timedness. pub fn append_datagram(&self, frame: MoqFrame) -> Result { let _guard = crate::ffi::enter(); let timestamp = frame.timestamp_us.map(moq_net::Timestamp::from_micros).transpose()?; @@ -616,10 +612,9 @@ impl MoqGroupProducer { /// Write `frame` into this group. /// - /// Raw tracks default to a microsecond timescale. Custom timescales may round - /// the timestamp during conversion. A frame without one is refused with - /// [`MoqProtocolKind::TimestampMismatch`](crate::error::MoqProtocolKind::TimestampMismatch): raw - /// tracks are timed. + /// Custom timescales may round the timestamp during conversion. The frame must + /// match its track's timedness, otherwise it is refused with + /// [`MoqProtocolKind::TimestampMismatch`](crate::error::MoqProtocolKind::TimestampMismatch). pub fn write_frame(&self, frame: MoqFrame) -> Result<(), MoqError> { let _guard = crate::ffi::enter(); let timestamp = frame.timestamp_us.map(moq_net::Timestamp::from_micros).transpose()?; @@ -663,6 +658,14 @@ impl MoqGroupProducer { mod metadata_tests { use super::*; + #[test] + fn untimed_info_round_trips_through_the_binding() { + let original = moq_net::track::Info::default(); + let info = MoqTrackInfo::try_from(&original).unwrap(); + assert_eq!(moq_net::track::Info::try_from(info).unwrap().timescale, None); + assert_eq!(raw_track_info(None).unwrap().timescale, None); + } + #[test] fn optional_retention_survives_binding_conversion() { for max_age_us in [None, Some(0), Some(30_000_000)] { diff --git a/rs/moq-ffi/src/test.rs b/rs/moq-ffi/src/test.rs index b771434d4dc..15cbfe0b929 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -25,6 +25,15 @@ fn timed() -> moq_net::track::Info { moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI) } +/// An explicitly timed raw track, whose frame API accepts microsecond timestamps. +fn timed_info() -> MoqTrackInfo { + MoqTrackInfo { + priority: 127, + max_age_us: None, + timescale: Some(1_000_000), + } +} + const TIMEOUT: Duration = Duration::from_secs(10); /// Wait until the FFI runtime has polled work spawned ahead of this call. @@ -751,7 +760,7 @@ async fn raw_track_info_reports_publisher_properties() { #[tokio::test] async fn raw_track_update_does_not_wait_for_pending_read() { let broadcast = MoqBroadcastProducer::new().unwrap(); - let track = broadcast.publish_track("status".into(), None).unwrap(); + let track = broadcast.publish_track("status".into(), Some(timed_info())).unwrap(); let consumer = track.consume(None).unwrap(); let read = { @@ -794,6 +803,146 @@ async fn subscribe(broadcast: &MoqBroadcastProducer, name: &str) -> Arc { + let producer = MoqJsonSnapshotProducer::new( + &broadcast, + &track, + MoqJsonSnapshotConfig { + delta_ratio: 0, + compression: false, + }, + ) + .unwrap(); + producer + .update(String::from_utf8(payload.to_vec()).unwrap(), timestamp_us) + .unwrap(); + producer.finish().unwrap(); + } + "json stream" => { + let producer = + MoqJsonStreamProducer::new(&broadcast, &track, MoqJsonStreamConfig { compression: false }) + .unwrap(); + producer + .append(String::from_utf8(payload.to_vec()).unwrap(), timestamp_us) + .unwrap(); + producer.finish().unwrap(); + } + "flate snapshot" => { + let producer = MoqFlateSnapshotProducer::new( + &broadcast, + &track, + MoqFlateConfig { + compression: false, + mime: None, + }, + ) + .unwrap(); + producer.update(payload.to_vec(), timestamp_us).unwrap(); + producer.finish().unwrap(); + } + "flate stream" => { + let producer = MoqFlateStreamProducer::new( + &broadcast, + &track, + MoqFlateConfig { + compression: false, + mime: None, + }, + ) + .unwrap(); + producer.append(payload.to_vec(), timestamp_us).unwrap(); + producer.finish().unwrap(); + } + _ => unreachable!(), + } + let frame = consumer.read_frame().await.unwrap().unwrap(); + assert_eq!(frame.payload, payload, "{kind}"); + assert_eq!(frame.timestamp_us, timestamp_us, "{kind}"); + assert_eq!(consumer.info().unwrap().timescale, timestamp_us.map(|_| 1_000_000)); + broadcast.close().unwrap(); + } + } +} + +#[tokio::test(start_paused = true)] +async fn whole_media_frames_require_the_callers_timestamp() { + let broadcast = MoqBroadcastProducer::new().unwrap(); + let media = MoqMediaTrackProducer::audio( + &broadcast, + MoqMediaTarget::Named { name: None }, + audio_init(MoqAudioFormat::Opus, opus_head()), + ) + .unwrap(); + assert!(matches!( + media.write_frame(MoqFrame { + payload: b"opus frame".to_vec(), + timestamp_us: None + }), + Err(MoqError::Codec { .. }) + )); + media + .write_frame(MoqFrame { + payload: b"opus frame".to_vec(), + timestamp_us: Some(0), + }) + .unwrap(); + media.finish().unwrap(); + broadcast.close().unwrap(); +} + +#[tokio::test(start_paused = true)] +async fn catalog_now_fixes_the_clock_for_later_media() { + let broadcast = MoqBroadcastProducer::new().unwrap(); + let catalog = MoqMediaCatalogProducer::new(broadcast.clone()).unwrap(); + let clock = broadcast + .with_state(|state| Ok(state.catalog.snapshot().clock)) + .unwrap(); + // Withhold publication so only the explicit clock read can fix it before the first frame. + let reserved = broadcast.with_state(|state| Ok(state.catalog.reserve())).unwrap(); + let media = MoqMediaTrackProducer::audio( + &broadcast, + MoqMediaTarget::Named { name: None }, + audio_init(MoqAudioFormat::Opus, opus_head()), + ) + .unwrap(); + let now = catalog.now().unwrap(); + assert!(now > 0); + media + .write_frame(MoqFrame { + payload: b"opus frame".to_vec(), + timestamp_us: Some(1_000_000), + }) + .unwrap(); + assert_eq!( + broadcast + .with_state(|state| Ok(state.catalog.snapshot().clock)) + .unwrap(), + clock + ); + drop(reserved); + media.finish().unwrap(); + broadcast.close().unwrap(); + assert!(matches!(catalog.now(), Err(MoqError::Closed))); +} + #[tokio::test] async fn json_snapshot_roundtrip() { let broadcast = MoqBroadcastProducer::new().unwrap(); @@ -809,7 +958,7 @@ async fn json_snapshot_roundtrip() { ); let consumer = MoqJsonSnapshotConsumer::new(&*subscribe(&broadcast, "meta").await, config).unwrap(); - producer.update(r#"{"a":1}"#.into()).unwrap(); + producer.update(r#"{"a":1}"#.into(), None).unwrap(); let value = tokio::time::timeout(TIMEOUT, consumer.next()) .await .expect("timed out waiting for json snapshot") @@ -821,7 +970,7 @@ async fn json_snapshot_roundtrip() { ); // A second update supersedes the first; a late reader collapses to the latest. - producer.update(r#"{"a":2}"#.into()).unwrap(); + producer.update(r#"{"a":2}"#.into(), None).unwrap(); let value = tokio::time::timeout(TIMEOUT, consumer.next()) .await .expect("timed out waiting for json snapshot delta") @@ -833,7 +982,10 @@ async fn json_snapshot_roundtrip() { ); producer.finish().unwrap(); - assert!(matches!(producer.update(r#"{"a":3}"#.into()), Err(MoqError::Closed))); + assert!(matches!( + producer.update(r#"{"a":3}"#.into(), None), + Err(MoqError::Closed) + )); } /// JSON producers report subscriber demand through a handle, like the media and raw track producers. @@ -935,7 +1087,7 @@ async fn json_stream_roundtrip() { let consumer = MoqJsonStreamConsumer::new(&*subscribe(&broadcast, "events").await, config).unwrap(); for n in 0..3 { - producer.append(format!(r#"{{"n":{n}}}"#)).unwrap(); + producer.append(format!(r#"{{"n":{n}}}"#), None).unwrap(); let value = tokio::time::timeout(TIMEOUT, consumer.next()) .await .expect("timed out waiting for json stream record") @@ -973,7 +1125,7 @@ async fn json_on_requested_track() { .unwrap(); let consumer = MoqJsonStreamConsumer::new(&track, config).unwrap(); - producer.append(r#"{"n":1}"#.into()).unwrap(); + producer.append(r#"{"n":1}"#.into(), None).unwrap(); let value = tokio::time::timeout(TIMEOUT, consumer.next()) .await .expect("timed out waiting for json stream record") @@ -1074,7 +1226,7 @@ async fn dynamic_track_request() { assert_eq!(request.name().unwrap(), "events"); // Accept the request as a raw track (which unblocks the subscribe), then write. - let track = request.accept(None).unwrap(); + let track = request.accept(Some(timed_info())).unwrap(); let payload = b"hello dynamic track".to_vec(); track .write_frame(MoqFrame { @@ -1100,12 +1252,50 @@ async fn dynamic_track_request() { track.finish().unwrap(); } -/// A raw track is timed, so a write or datagram without a timestamp is refused rather than -/// stamped. +#[tokio::test(start_paused = true)] +async fn raw_untimed_frames_and_datagrams_roundtrip() { + let broadcast = MoqBroadcastProducer::new().unwrap(); + let track = broadcast.publish_track("untimed".into(), None).unwrap(); + let consumer = track.consume(None).unwrap(); + assert_eq!(consumer.info().unwrap().timescale, None); + track + .write_frame(MoqFrame { + payload: b"frame".to_vec(), + timestamp_us: None, + }) + .unwrap(); + let frame = consumer.read_frame().await.unwrap().unwrap(); + assert_eq!(frame.payload, b"frame"); + assert_eq!(frame.timestamp_us, None); + let group = track.append_group().unwrap(); + let reader = group.consume().unwrap(); + group + .write_frame(MoqFrame { + payload: b"group".to_vec(), + timestamp_us: None, + }) + .unwrap(); + group.finish().unwrap(); + let frame = reader.read_frame().await.unwrap().unwrap(); + assert_eq!(frame.payload, b"group"); + assert_eq!(frame.timestamp_us, None); + track + .append_datagram(MoqFrame { + payload: b"datagram".to_vec(), + timestamp_us: None, + }) + .unwrap(); + let datagram = consumer.recv_datagram().await.unwrap().unwrap(); + assert_eq!(datagram.payload, b"datagram"); + assert_eq!(datagram.timestamp_us, None); + track.finish().unwrap(); +} + +/// An explicitly timed raw track refuses frames and datagrams without a timestamp. #[test] fn raw_writes_need_a_timestamp() { let broadcast = MoqBroadcastProducer::new().unwrap(); - let track = broadcast.publish_track("status".into(), None).unwrap(); + let track = broadcast.publish_track("status".into(), Some(timed_info())).unwrap(); let untimed = || MoqFrame { payload: b"ready".to_vec(), timestamp_us: None, @@ -1130,7 +1320,7 @@ fn raw_writes_need_a_timestamp() { #[tokio::test] async fn raw_frame_timestamps() { let broadcast = MoqBroadcastProducer::new().unwrap(); - let track = broadcast.publish_track("status".into(), None).unwrap(); + let track = broadcast.publish_track("status".into(), Some(timed_info())).unwrap(); let consumer = track.consume(None).unwrap(); let payload = b"ready".to_vec(); @@ -1190,7 +1380,7 @@ fn raw_track_supports_sparse_groups_and_known_end() { #[tokio::test] async fn abort_after_finish_keeps_the_track_handle() { let broadcast = MoqBroadcastProducer::new().unwrap(); - let track = broadcast.publish_track("aborted".into(), None).unwrap(); + let track = broadcast.publish_track("aborted".into(), Some(timed_info())).unwrap(); let consumer = track.consume(None).unwrap(); track @@ -1207,7 +1397,7 @@ async fn abort_after_finish_keeps_the_track_handle() { #[tokio::test] async fn abort_after_finish_reaches_group_consumer() { let broadcast = MoqBroadcastProducer::new().unwrap(); - let track = broadcast.publish_track("aborted".into(), None).unwrap(); + let track = broadcast.publish_track("aborted".into(), Some(timed_info())).unwrap(); let group = track.append_group().unwrap(); let consumer = group.consume().unwrap(); @@ -1265,7 +1455,7 @@ async fn dynamic_track_request_can_abort() { #[tokio::test] async fn fetches_cached_group_without_subscribing() { 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 group = track.append_group().unwrap(); group .write_frame(MoqFrame { @@ -1595,7 +1785,7 @@ async fn media_group_fails_loudly_on_bad_containers() { #[tokio::test] async fn dynamic_track_serves_fetch_miss_and_priority() { 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 dynamic = track.dynamic().unwrap(); let consumer = broadcast.consume().unwrap(); @@ -1742,7 +1932,7 @@ async fn requested_track_dynamic_survives_accept() { .expect("timed out waiting for track request") .unwrap(); let track_dynamic = request.dynamic().unwrap(); - let _track = request.accept(None).unwrap(); + let _track = request.accept(Some(timed_info())).unwrap(); let group_request = tokio::time::timeout(TIMEOUT, track_dynamic.requested_group()) .await @@ -3064,7 +3254,7 @@ async fn dynamic_broadcast_request() { assert_eq!(request.path().unwrap(), "dynamic/broadcast"); let served = MoqBroadcastProducer::new().unwrap(); - let track = served.publish_track("status".into(), None).unwrap(); + let track = served.publish_track("status".into(), Some(timed_info())).unwrap(); request.accept(&served).unwrap(); assert!(matches!(request.path(), Err(MoqError::Closed))); @@ -3194,7 +3384,7 @@ async fn cancel_retracts_the_route_synchronously() { #[tokio::test] async fn raw_track_next_group_is_repeatable() { let broadcast = MoqBroadcastProducer::new().unwrap(); - let track = broadcast.publish_track("commands".into(), None).unwrap(); + let track = broadcast.publish_track("commands".into(), Some(timed_info())).unwrap(); let consumer = broadcast .consume() .unwrap() @@ -3233,7 +3423,7 @@ async fn raw_track_next_group_is_repeatable() { #[tokio::test] async fn raw_track_group_order_commits_on_first_read() { let broadcast = MoqBroadcastProducer::new().unwrap(); - let track = broadcast.publish_track("commands".into(), None).unwrap(); + let track = broadcast.publish_track("commands".into(), Some(timed_info())).unwrap(); let consumer = broadcast .consume() .unwrap() @@ -3294,7 +3484,7 @@ fn raw_track() -> ( Arc, ) { 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 consumer = track.consume(None).unwrap(); (broadcast, track, consumer) } @@ -3570,7 +3760,7 @@ async fn raw_track_handle_cancel_aborts_both_pending_lanes() { #[tokio::test] async fn raw_read_frame_skips_empty_group_on_open_track() { let broadcast = MoqBroadcastProducer::new().unwrap(); - let track = broadcast.publish_track("status".into(), None).unwrap(); + let track = broadcast.publish_track("status".into(), Some(timed_info())).unwrap(); let consumer = track.consume(None).unwrap(); let empty = track.append_group().unwrap(); @@ -3612,7 +3802,7 @@ async fn raw_read_frame_skips_empty_group_on_open_track() { #[tokio::test] async fn raw_read_frame_skips_empty_then_populated_groups() { let broadcast = MoqBroadcastProducer::new().unwrap(); - let track = broadcast.publish_track("status".into(), None).unwrap(); + let track = broadcast.publish_track("status".into(), Some(timed_info())).unwrap(); let consumer = track.consume(None).unwrap(); track.append_group().unwrap().finish().unwrap(); @@ -3665,7 +3855,7 @@ async fn raw_read_frame_cancelled_before_free_leaves_the_frame() { #[tokio::test] async fn raw_read_frame_keeps_group_across_cancelled_call() { let broadcast = MoqBroadcastProducer::new().unwrap(); - let track = broadcast.publish_track("status".into(), None).unwrap(); + let track = broadcast.publish_track("status".into(), Some(timed_info())).unwrap(); let consumer = track.consume(None).unwrap(); let group = track.append_group().unwrap(); @@ -3703,7 +3893,7 @@ async fn raw_read_frame_keeps_group_across_cancelled_call() { #[tokio::test] async fn raw_read_frame_drops_aborted_pending_group() { let broadcast = MoqBroadcastProducer::new().unwrap(); - let track = broadcast.publish_track("status".into(), None).unwrap(); + let track = broadcast.publish_track("status".into(), Some(timed_info())).unwrap(); let consumer = track.consume(None).unwrap(); let first = track.append_group().unwrap(); @@ -3751,7 +3941,7 @@ async fn raw_read_frame_drops_aborted_pending_group() { #[tokio::test] async fn raw_read_frame_and_next_group_share_the_cursor() { let broadcast = MoqBroadcastProducer::new().unwrap(); - let track = broadcast.publish_track("status".into(), None).unwrap(); + let track = broadcast.publish_track("status".into(), Some(timed_info())).unwrap(); let consumer = track.consume(None).unwrap(); let first = track.append_group().unwrap(); @@ -5430,8 +5620,8 @@ async fn flate_tracks_are_advertised_in_the_catalog() { }, ) .unwrap(); - thumb.update(vec![0xff, 0xd8, 0xff]).unwrap(); - log.append(vec![1, 2, 3]).unwrap(); + thumb.update(vec![0xff, 0xd8, 0xff], None).unwrap(); + log.append(vec![1, 2, 3], None).unwrap(); let catalog = published_catalog(&broadcast); let entry = catalog @@ -5446,7 +5636,7 @@ async fn flate_tracks_are_advertised_in_the_catalog() { assert_eq!(entry.mime, None); thumb.finish().unwrap(); - assert!(matches!(thumb.update(vec![0]), Err(MoqError::Closed))); + assert!(matches!(thumb.update(vec![0], None), Err(MoqError::Closed))); log.finish().unwrap(); assert!(published_catalog(&broadcast).binary.tracks.is_empty()); } @@ -5547,7 +5737,7 @@ async fn shutdown_delivers_the_finished_track() { (&accepted, &client) }; let broadcast = create_announced(&publisher.publish(), "tail"); - let track = broadcast.publish_track("data".into(), None).unwrap(); + let track = broadcast.publish_track("data".into(), Some(timed_info())).unwrap(); let remote = await_announced(&subscriber.consume(), "tail").await; let reader = tokio::time::timeout(TIMEOUT, remote.subscribe_track("data".into(), None)) .await diff --git a/rs/moq-flate/src/snapshot/mod.rs b/rs/moq-flate/src/snapshot/mod.rs index fc0c36d08e0..c2e0c2fe7d5 100644 --- a/rs/moq-flate/src/snapshot/mod.rs +++ b/rs/moq-flate/src/snapshot/mod.rs @@ -42,6 +42,34 @@ mod test { use super::*; + #[test] + fn a_timed_track_refuses_a_bare_publish() { + let (mut producer, _) = producer_on(false, timed()); + assert!(matches!( + producer.update(&b"payload"[..]), + Err(crate::Error::Net(moq_net::Error::TimestampMismatch)) + )); + } + + #[test] + fn a_bare_publish_stays_untimed() { + let track = moq_net::broadcast::Info::new() + .produce() + .create_track("untimed", moq_net::track::Info::default()) + .unwrap(); + let mut groups = track.subscribe(None); + let mut producer = Producer::new(track, Config::default()); + producer.update(&b"payload"[..]).unwrap(); + let waiter = kio::Waiter::noop(); + let Poll::Ready(Ok(Some(mut group))) = groups.poll_recv_group(&waiter) else { + panic!("expected an untimed group"); + }; + let Poll::Ready(Ok(Some(frame))) = group.poll_read_frame(&waiter) else { + panic!("expected an untimed frame"); + }; + assert_eq!(frame.timestamp, None); + } + /// A millisecond track: the frames written here carry timestamps. fn timed() -> moq_net::track::Info { moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI) @@ -58,9 +86,13 @@ mod test { } fn producer(compression: bool) -> (Producer, moq_net::track::Subscriber) { + producer_on(compression, moq_net::track::Info::default()) + } + + fn producer_on(compression: bool, info: moq_net::track::Info) -> (Producer, moq_net::track::Subscriber) { let track = moq_net::broadcast::Info::new() .produce() - .create_track("test", timed()) + .create_track("test", info) .unwrap(); let consumer = track.subscribe(None); (Producer::new(track, cfg(compression)), consumer) @@ -120,7 +152,7 @@ mod test { /// on the wire rather than the payload handed in. #[test] fn a_stamped_update_writes_its_capture_time() { - let (mut producer, track) = producer(true); + let (mut producer, track) = producer_on(true, timed()); let mut groups = producer.consume(); let captured = moq_net::Timestamp::from_millis(1_234).unwrap(); let payload = Bytes::from(vec![7u8; 4096]); diff --git a/rs/moq-flate/src/snapshot/producer.rs b/rs/moq-flate/src/snapshot/producer.rs index 95ecf60ffb5..d6309d483e4 100644 --- a/rs/moq-flate/src/snapshot/producer.rs +++ b/rs/moq-flate/src/snapshot/producer.rs @@ -67,7 +67,7 @@ struct Inner { impl Inner { fn update(&mut self, payload: Timed) -> Result { - let timestamp = payload.at.unwrap_or_else(moq_net::Timestamp::now); + let timestamp = payload.at; let payload = payload.value; // One frame per group, so the window spans a single value and starts cold every time. diff --git a/rs/moq-flate/src/stream/mod.rs b/rs/moq-flate/src/stream/mod.rs index fc29cdfbe4b..ea4f408498f 100644 --- a/rs/moq-flate/src/stream/mod.rs +++ b/rs/moq-flate/src/stream/mod.rs @@ -59,6 +59,34 @@ mod test { use super::*; + #[test] + fn a_timed_track_refuses_a_bare_publish() { + let (mut producer, _) = producer_on(false, timed()); + assert!(matches!( + producer.append(&b"payload"[..]), + Err(crate::Error::Net(moq_net::Error::TimestampMismatch)) + )); + } + + #[test] + fn a_bare_publish_stays_untimed() { + let track = moq_net::broadcast::Info::new() + .produce() + .create_track("untimed", moq_net::track::Info::default()) + .unwrap(); + let mut groups = track.subscribe(None); + let mut producer = Producer::new(track, Config::default()); + producer.append(&b"payload"[..]).unwrap(); + let waiter = kio::Waiter::noop(); + let Poll::Ready(Ok(Some(mut group))) = groups.poll_recv_group(&waiter) else { + panic!("expected an untimed group"); + }; + let Poll::Ready(Ok(Some(frame))) = group.poll_read_frame(&waiter) else { + panic!("expected an untimed frame"); + }; + assert_eq!(frame.timestamp, None); + } + /// A millisecond track: the frames written here carry timestamps. fn timed() -> moq_net::track::Info { moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI) @@ -75,9 +103,13 @@ mod test { } fn producer(compression: bool) -> (Producer, moq_net::track::Subscriber) { + producer_on(compression, moq_net::track::Info::default()) + } + + fn producer_on(compression: bool, info: moq_net::track::Info) -> (Producer, moq_net::track::Subscriber) { let track = moq_net::broadcast::Info::new() .produce() - .create_track("test", timed()) + .create_track("test", info) .unwrap(); let consumer = track.subscribe(None); (Producer::new(track, cfg(compression)), consumer) @@ -112,16 +144,18 @@ mod test { assert_eq!(drain(track, false), expected); } - /// Each record keeps its own capture time, and a bare payload is stamped when written. + /// Each record keeps its caller-supplied capture time. #[test] fn a_stamped_append_writes_its_capture_time() { - let (mut producer, _track) = producer(true); + let (mut producer, _track) = producer_on(true, timed()); let mut groups = producer.consume(); let captured = moq_net::Timestamp::from_millis(1_234).unwrap(); let first = producer .append(moq_net::Timed::from(vec![1u8; 4096]).at(captured)) .unwrap(); - producer.append(vec![2u8; 16]).unwrap(); + producer + .append(moq_net::Timed::from(vec![2u8; 16]).at(moq_net::Timestamp::from_millis(2_345).unwrap())) + .unwrap(); let waiter = kio::Waiter::noop(); let Poll::Ready(Ok(Some(mut group))) = groups.poll_recv_group(&waiter) else { diff --git a/rs/moq-flate/src/stream/producer.rs b/rs/moq-flate/src/stream/producer.rs index 487675028e8..093f8c298bc 100644 --- a/rs/moq-flate/src/stream/producer.rs +++ b/rs/moq-flate/src/stream/producer.rs @@ -94,7 +94,7 @@ const _: () = assert!(moq_net::group::MAX_CACHE_BYTES <= crate::DEFAULT_MAX_FRAM impl Inner { fn append(&mut self, payload: Timed) -> Result { - let timestamp = payload.at.unwrap_or_else(moq_net::Timestamp::now); + let timestamp = payload.at; let payload = payload.value; // A closed track refuses every append, so say so before the budget: `GroupTooLarge` promises diff --git a/rs/moq-hls/src/export/archive_tests.rs b/rs/moq-hls/src/export/archive_tests.rs index 4a0bcc9a8e6..a72e8cb6e3f 100644 --- a/rs/moq-hls/src/export/archive_tests.rs +++ b/rs/moq-hls/src/export/archive_tests.rs @@ -304,7 +304,9 @@ impl Replay { let mut json = moq_json::snapshot::Config::default(); json.delta_ratio = 0; let mut catalog = moq_json::snapshot::Producer::new(track, json); - catalog.update(&self::catalog(archive)).unwrap(); + catalog + .update(moq_net::Timed::from(&self::catalog(archive)).at(moq_net::Timestamp::now())) + .unwrap(); let serving = reader::Config::new(recording.timelines()).with_cache(cache); let reader = moq_archive::Reader::open(recording.store.clone(), &broadcast, serving) @@ -658,7 +660,9 @@ async fn history_after_expiry(finished: bool) { .create_track(hang::Catalog::DEFAULT_NAME, hang::Catalog::default_track_info()) .unwrap(); let mut catalog = moq_json::snapshot::Producer::new(track, moq_json::snapshot::Config::default()); - catalog.update(&self::catalog(durable())).unwrap(); + catalog + .update(moq_net::Timed::from(&self::catalog(durable())).at(moq_net::Timestamp::now())) + .unwrap(); let reader = moq_archive::Reader::open( recording.store.clone(), &broadcast, diff --git a/rs/moq-hls/src/export/mod.rs b/rs/moq-hls/src/export/mod.rs index 42730ae4adb..f98b0af513d 100644 --- a/rs/moq-hls/src/export/mod.rs +++ b/rs/moq-hls/src/export/mod.rs @@ -1674,7 +1674,9 @@ mod tests { .unwrap(), json, ); - catalog.update(&snapshot).unwrap(); + catalog + .update(moq_net::Timed::from(&snapshot).at(moq_net::Timestamp::now())) + .unwrap(); let track = broadcast.create_track("video0", timed()).unwrap(); let mut media = moq_mux::container::Producer::new( diff --git a/rs/moq-json/examples/telemetry.rs b/rs/moq-json/examples/telemetry.rs index b6356b11929..7fdceb8db1c 100644 --- a/rs/moq-json/examples/telemetry.rs +++ b/rs/moq-json/examples/telemetry.rs @@ -88,7 +88,9 @@ fn wire_bytes(config: snapshot::Config, ticks: u64) -> usize { let mut producer = Producer::::new(track, config); for tick in 0..ticks { - producer.update(&telemetry(tick)).unwrap(); + producer + .update(moq_net::Timed::from(&telemetry(tick)).at(moq_net::Timestamp::now())) + .unwrap(); } producer.finish().unwrap(); @@ -124,7 +126,9 @@ fn verify(producer_config: snapshot::Config, ticks: u64) { for tick in 0..ticks { let expected = telemetry(tick); - producer.update(&expected).unwrap(); + producer + .update(moq_net::Timed::from(&expected).at(moq_net::Timestamp::now())) + .unwrap(); // The producer emits exactly one frame per update, so the live consumer yields exactly one // reconstructed value: it must match the input byte-for-byte after decompression + patching. match consumer.poll_next(&waiter) { @@ -158,7 +162,9 @@ fn verify_late_joiner(producer_config: snapshot::Config, ticks: u64) -> usize { let consumer = track.subscribe(None); let mut producer = Producer::::new(track, producer_config.clone()); for tick in 0..ticks { - producer.update(&telemetry(tick)).unwrap(); + producer + .update(moq_net::Timed::from(&telemetry(tick)).at(moq_net::Timestamp::now())) + .unwrap(); } producer.finish().unwrap(); diff --git a/rs/moq-json/src/snapshot/mod.rs b/rs/moq-json/src/snapshot/mod.rs index 862b466e9d0..4cd6453b3ca 100644 --- a/rs/moq-json/src/snapshot/mod.rs +++ b/rs/moq-json/src/snapshot/mod.rs @@ -57,6 +57,78 @@ mod test { use super::*; use crate::Compression; + #[test] + fn editing_keeps_the_callers_timestamp_on_commit_and_drop() { + let (mut producer, _) = producer_on(cfg(100), timed()); + let mut groups = producer.consume(); + let first = moq_net::Timestamp::from_millis(100).unwrap(); + let second = moq_net::Timestamp::from_millis(200).unwrap(); + producer.modify(Some(first)).unwrap()["n"] = json!(1); + let mut edit = producer.modify(Some(second)).unwrap(); + edit["n"] = json!(2); + edit.commit().unwrap(); + let waiter = kio::Waiter::noop(); + let Poll::Ready(Ok(Some(mut group))) = groups.poll_recv_group(&waiter) else { + panic!("expected the edited snapshot"); + }; + for at in [first, second] { + let Poll::Ready(Ok(Some(frame))) = group.poll_read_frame(&waiter) else { + panic!("expected the edited value"); + }; + assert_eq!(frame.timestamp, Some(at)); + } + } + + #[test] + fn a_missing_edit_timestamp_is_refused_on_a_timed_track() { + let (mut producer, _) = producer_on(cfg(0), timed()); + let mut edit = producer.modify(None).unwrap(); + edit["n"] = json!(1); + assert!(matches!( + edit.commit(), + Err(crate::Error::Net(moq_net::Error::TimestampMismatch)) + )); + let at = moq_net::Timestamp::from_millis(100).unwrap(); + producer.mutate(Some(at), |value| value["n"] = json!(2)).unwrap(); + let waiter = kio::Waiter::noop(); + let mut groups = producer.consume(); + let Poll::Ready(Ok(Some(mut group))) = groups.poll_recv_group(&waiter) else { + panic!("expected the subsequent explicit publish"); + }; + let Poll::Ready(Ok(Some(frame))) = group.poll_read_frame(&waiter) else { + panic!("expected a timed frame"); + }; + assert_eq!(frame.timestamp, Some(at)); + } + + #[test] + fn a_timed_track_refuses_a_bare_publish() { + let (mut producer, _) = producer_on(Config::default(), timed()); + assert!(matches!( + producer.update(&json!({ "n": 1 })), + Err(crate::Error::Net(moq_net::Error::TimestampMismatch)) + )); + } + + #[test] + fn a_bare_publish_stays_untimed() { + let track = moq_net::broadcast::Info::new() + .produce() + .create_track("untimed", moq_net::track::Info::default()) + .unwrap(); + let mut groups = track.subscribe(None); + let mut producer = Producer::new(track, Config::default()); + producer.update(&json!({ "n": 1 })).unwrap(); + let waiter = kio::Waiter::noop(); + let Poll::Ready(Ok(Some(mut group))) = groups.poll_recv_group(&waiter) else { + panic!("expected an untimed group"); + }; + let Poll::Ready(Ok(Some(frame))) = group.poll_read_frame(&waiter) else { + panic!("expected an untimed frame"); + }; + assert_eq!(frame.timestamp, None); + } + /// A millisecond track: the frames written here carry timestamps. fn timed() -> moq_net::track::Info { moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI) @@ -87,9 +159,13 @@ mod test { } fn producer(config: Config) -> (Producer, moq_net::track::Subscriber) { + producer_on(config, moq_net::track::Info::default()) + } + + fn producer_on(config: Config, info: moq_net::track::Info) -> (Producer, moq_net::track::Subscriber) { let track = moq_net::broadcast::Info::new() .produce() - .create_track("test", timed()) + .create_track("test", info) .unwrap(); let consumer = track.subscribe(None); (Producer::new(track, config), consumer) @@ -329,7 +405,7 @@ mod test { /// size is the encoded frame. #[test] fn a_stamped_update_writes_its_capture_time() { - let (mut producer, _track) = producer(cfg(100)); + let (mut producer, _track) = producer_on(cfg(100), timed()); let mut groups = producer.consume(); let first = moq_net::Timestamp::from_millis(1_000).unwrap(); let second = moq_net::Timestamp::from_millis(2_000).unwrap(); @@ -455,13 +531,13 @@ mod test { let track = moq_net::broadcast::Info::new() .produce() - .create_track("test", timed()) + .create_track("test", moq_net::track::Info::default()) .unwrap(); let consumer = track.subscribe(None); let mut producer = Producer::::new(track, Config::default()); producer.update(&Doc { count: 1 }).unwrap(); - assert!(matches!(producer.modify(), Err(crate::Error::Json(_)))); + assert!(matches!(producer.modify(None), Err(crate::Error::Json(_)))); // The refused edit published nothing after the original value. producer.finish().unwrap(); @@ -481,19 +557,19 @@ mod test { let track = moq_net::broadcast::Info::new() .produce() - .create_track("test", timed()) + .create_track("test", moq_net::track::Info::default()) .unwrap(); let consumer = track.subscribe(None); let mut producer = Producer::::new(track, Config::default()); // First owner sets its field. - producer.modify().unwrap().video = Some("v1".to_string()); + producer.modify(None).unwrap().video = Some("v1".to_string()); // Second owner starts from the latest value and adds its own field without clobbering. - producer.modify().unwrap().scte35 = Some(42); + producer.modify(None).unwrap().scte35 = Some(42); // Locking without mutating publishes nothing (the guard stays clean). - let _ = producer.modify().unwrap(); + let _ = producer.modify(None).unwrap(); producer.finish().unwrap(); @@ -525,19 +601,19 @@ mod test { let track = moq_net::broadcast::Info::new() .produce() - .create_track("test", timed()) + .create_track("test", moq_net::track::Info::default()) .unwrap(); let consumer = track.subscribe(None); let mut producer = Producer::::new(track, cfg(0)); - producer.mutate(|doc| doc.video = Some("v1".to_string())).unwrap(); + producer.mutate(None, |doc| doc.video = Some("v1".to_string())).unwrap(); // The second owner starts from the latest value and adds its own field without clobbering. - producer.mutate(|doc| doc.scte35 = Some(42)).unwrap(); + producer.mutate(None, |doc| doc.scte35 = Some(42)).unwrap(); // A closure that changes nothing publishes nothing: deltas are off, so each publish would // otherwise open a group of its own. - producer.mutate(|_| {}).unwrap(); + producer.mutate(None, |_| {}).unwrap(); assert_eq!(consumer.latest(), Some(1)); producer.finish().unwrap(); @@ -564,7 +640,7 @@ mod test { producer.update(&json!({ "keep": true })).unwrap(); assert!(matches!( - producer.mutate(|value| { + producer.mutate(None, |value| { *value = json!({ "big": "x".repeat(moq_net::group::MAX_CACHE_BYTES as usize + 1) }); }), Err(crate::Error::Net(moq_net::Error::FrameTooLarge)) @@ -575,8 +651,8 @@ mod test { fn a_dropped_edit_publishes_a_snapshot_then_a_delta() { let (mut producer, track) = producer(cfg(100)); - *producer.modify().unwrap() = json!({ "a": 1, "b": 1 }); - *producer.modify().unwrap() = json!({ "a": 1, "b": 2 }); + *producer.modify(None).unwrap() = json!({ "a": 1, "b": 1 }); + *producer.modify(None).unwrap() = json!({ "a": 1, "b": 2 }); producer.finish().unwrap(); // The ratio keeps both edits in one group: a snapshot plus a merge-patch delta. @@ -591,7 +667,7 @@ mod test { producer.finish().unwrap(); assert!(matches!( - producer.modify(), + producer.modify(None), Err(crate::Error::Net(moq_net::Error::Closed)) )); assert_eq!(drain(track), vec![json!({ "a": 1 })]); @@ -603,12 +679,12 @@ mod test { producer.update(&json!({ "keep": true })).unwrap(); let mut subscriber = track.ordered(); - *producer.modify().unwrap() = json!({ "big": "x".repeat(moq_net::group::MAX_CACHE_BYTES as usize + 1) }); + *producer.modify(None).unwrap() = json!({ "big": "x".repeat(moq_net::group::MAX_CACHE_BYTES as usize + 1) }); // The publisher learns the cause at its next edit. The consumer drains the snapshot // that finished, then learns it from the aborted track. assert!(matches!( - producer.modify(), + producer.modify(None), Err(crate::Error::Net(moq_net::Error::FrameTooLarge)) )); assert!(matches!( @@ -626,7 +702,7 @@ mod test { let (mut producer, track) = producer(cfg(0)); producer.update(&json!({ "keep": true })).unwrap(); - let mut guard = producer.modify().unwrap(); + let mut guard = producer.modify(None).unwrap(); *guard = json!({ "big": "x".repeat(moq_net::group::MAX_CACHE_BYTES as usize + 1) }); assert!(matches!( guard.commit(), @@ -634,7 +710,7 @@ mod test { )); // The caller got the error, so the track stays usable for a smaller value. - *producer.modify().unwrap() = json!({ "keep": false }); + *producer.modify(None).unwrap() = json!({ "keep": false }); producer.finish().unwrap(); assert_eq!(drain(track).last().unwrap(), &json!({ "keep": false })); } @@ -645,14 +721,14 @@ mod test { producer.update(&json!({ "a": 1 })).unwrap(); let panicked = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| { - let mut guard = producer.modify().unwrap(); + let mut guard = producer.modify(None).unwrap(); *guard = json!({ "a": 2 }); panic!("torn edit"); })); assert!(panicked.is_err()); // A discarded edit is not a publish failure, so the track is still open for the next one. - *producer.modify().unwrap() = json!({ "a": 3 }); + *producer.modify(None).unwrap() = json!({ "a": 3 }); producer.finish().unwrap(); assert_eq!(track.latest(), Some(1), "the torn edit took a group"); assert_eq!(drain(track).last().unwrap(), &json!({ "a": 3 })); @@ -673,16 +749,16 @@ mod test { // Every frame is rejected, so each publish fails and the encoder resynchronizes. let mut producer = Producer::::new(rejecting_track(), Config::default()); - let mut guard = producer.modify().unwrap(); + let mut guard = producer.modify(None).unwrap(); guard.video = Some("v1".to_string()); assert!(guard.commit().is_err()); - let mut guard = producer.modify().unwrap(); + let mut guard = producer.modify(None).unwrap(); guard.scte35 = Some(42); assert!(guard.commit().is_err()); // The editing baseline still carries the composed value. - let guard = producer.modify().unwrap(); + let guard = producer.modify(None).unwrap(); assert_eq!( guard.video, Some("v1".to_string()), @@ -747,12 +823,12 @@ mod test { let track = moq_net::broadcast::Info::new() .produce() - .create_track("test", timed()) + .create_track("test", moq_net::track::Info::default()) .unwrap(); let consumer = track.subscribe(None); let mut producer = Producer::::new(track, cfg(0)); - let mut guard = producer.modify().unwrap(); + let mut guard = producer.modify(None).unwrap(); guard.a = 1; guard.commit().unwrap(); diff --git a/rs/moq-json/src/snapshot/producer.rs b/rs/moq-json/src/snapshot/producer.rs index 48daef54c83..a7aae40c292 100644 --- a/rs/moq-json/src/snapshot/producer.rs +++ b/rs/moq-json/src/snapshot/producer.rs @@ -87,7 +87,7 @@ impl Producer { take(&self.inner).update(value.into()) } - /// Edit the current value in place and publish the result. + /// Edit the current value in place and publish at `at`, or leave it untimed. /// /// The closure receives the current value: everything published through this producer so far, /// composed, or `T::default()` if nothing has been. Edit it in place; on return the result is @@ -95,7 +95,7 @@ impl Producer { /// /// ```no_run /// # fn example(producer: &mut moq_json::snapshot::Producer) -> moq_json::Result<()> { - /// producer.mutate(|catalog| { + /// producer.mutate(None, |catalog| { /// catalog["scte35"] = serde_json::json!({ "id": 1 }); /// }) /// # } @@ -105,16 +105,16 @@ impl Producer { /// from the latest value, so their sections compose instead of clobbering one another. This is /// [`modify`](Self::modify) opened and committed for you; take the guard to hold the lock across /// several edits, and [`update`](Self::update) to replace the whole value. - pub fn mutate(&mut self, f: impl FnOnce(&mut T)) -> Result<()> + pub fn mutate(&mut self, at: Option, f: impl FnOnce(&mut T)) -> Result<()> where T: Default + DeserializeOwned, { - let mut guard = self.modify()?; + let mut guard = self.modify(at)?; f(&mut guard); guard.commit() } - /// Lock the current value for in-place editing, publishing on drop. + /// Edit the current value, publishing on drop at `at`, or untimed when absent. /// /// The returned [`Guard`] derefs to the current value: everything published through this producer /// so far, composed, or `T::default()` if nothing has been. Editing it through [`DerefMut`] marks @@ -139,7 +139,7 @@ impl Producer { /// consumers see it instead of a stale value, and the next `modify` returns it here. Call /// [`Guard::commit`] to get the error back immediately instead. A panic while the guard is held /// discards the in-flight edit rather than publishing a torn value. - pub fn modify(&mut self) -> Result> + pub fn modify(&mut self, at: Option) -> Result> where T: Default + DeserializeOwned, { @@ -158,6 +158,7 @@ impl Producer { inner, value, dirty: false, + at, }) } @@ -203,6 +204,7 @@ pub struct Guard<'a, T: Serialize> { inner: MutexGuard<'a, Inner>, value: T, dirty: bool, + at: Option, } impl Guard<'_, T> { @@ -223,7 +225,10 @@ impl Guard<'_, T> { self.dirty = false; // We already hold the lock, so publish through the held guard rather than re-locking. - self.inner.update(Timed::from(&self.value))?; + self.inner.update(Timed { + value: &self.value, + at: self.at, + })?; Ok(()) } } @@ -331,7 +336,7 @@ impl Inner { // A failed write drops `frame` uncommitted, which resets the encoder so the next update // resynchronizes with a fresh snapshot. Most failures kill the track outright, but a rejected // frame (too large) doesn't, and a delta against a snapshot no consumer ever saw is unreadable. - let timestamp = payload.at.unwrap_or_else(moq_net::Timestamp::now); + let timestamp = payload.at; track.write(timestamp, &frame)?; let size = frame.payload.len(); frame.commit(); @@ -370,7 +375,7 @@ impl Track { } /// Write one encoded frame at `timestamp`, rolling a group when it's a snapshot. - fn write(&mut self, timestamp: moq_net::Timestamp, encoded: &Encoded) -> Result<()> { + fn write(&mut self, timestamp: Option, encoded: &Encoded) -> Result<()> { // Check before touching a group. `write_snapshot` closes the previous group and publishes a // new one before the frame is written, so discovering the limit inside `write_frame` would // leave an empty newest group behind: a snapshot consumer jumps to the newest, so the previous @@ -386,7 +391,7 @@ impl Track { } /// Close the open group and write a snapshot as the first frame of a new one. - fn write_snapshot(&mut self, timestamp: moq_net::Timestamp, payload: bytes::Bytes) -> Result<()> { + fn write_snapshot(&mut self, timestamp: Option, payload: bytes::Bytes) -> Result<()> { // The previous group is complete; no more frames will be appended to it. if let Some(group) = self.group.take() { group.finish()?; @@ -412,7 +417,7 @@ impl Track { } /// Append a delta to the group the last snapshot opened. - fn write_delta(&mut self, timestamp: moq_net::Timestamp, payload: bytes::Bytes) -> Result<()> { + fn write_delta(&mut self, timestamp: Option, payload: bytes::Bytes) -> Result<()> { self.group .as_mut() .expect("the encoder only emits a delta after a snapshot opened a group") diff --git a/rs/moq-json/src/stream/mod.rs b/rs/moq-json/src/stream/mod.rs index 874fdc49e2f..4b98502c081 100644 --- a/rs/moq-json/src/stream/mod.rs +++ b/rs/moq-json/src/stream/mod.rs @@ -58,15 +58,47 @@ mod test { use super::*; use crate::Compression; + #[test] + fn a_timed_track_refuses_a_bare_publish() { + let (mut producer, _) = producer_on(Config::default(), timed()); + assert!(matches!( + producer.append(&json!({ "n": 1 })), + Err(crate::Error::Net(moq_net::Error::TimestampMismatch)) + )); + } + + #[test] + fn a_bare_publish_stays_untimed() { + let track = moq_net::broadcast::Info::new() + .produce() + .create_track("untimed", moq_net::track::Info::default()) + .unwrap(); + let mut groups = track.subscribe(None); + let mut producer = Producer::new(track, Config::default()); + producer.append(&json!({ "n": 1 })).unwrap(); + let waiter = kio::Waiter::noop(); + let Poll::Ready(Ok(Some(mut group))) = groups.poll_recv_group(&waiter) else { + panic!("expected an untimed group"); + }; + let Poll::Ready(Ok(Some(frame))) = group.poll_read_frame(&waiter) else { + panic!("expected an untimed frame"); + }; + assert_eq!(frame.timestamp, None); + } + /// A millisecond track: the frames written here carry timestamps. fn timed() -> moq_net::track::Info { moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI) } fn producer(config: Config) -> (Producer, moq_net::track::Subscriber) { + producer_on(config, moq_net::track::Info::default()) + } + + fn producer_on(config: Config, info: moq_net::track::Info) -> (Producer, moq_net::track::Subscriber) { let track = moq_net::broadcast::Info::new() .produce() - .create_track("test", timed()) + .create_track("test", info) .unwrap(); let consumer = track.subscribe(None); (Producer::new(track, config), consumer) @@ -133,7 +165,7 @@ mod test { /// Each record keeps its own capture time, and the returned size is the encoded frame. #[test] fn a_stamped_append_writes_its_capture_time() { - let (mut producer, _track) = producer(compressed()); + let (mut producer, _track) = producer_on(compressed(), timed()); let mut groups = producer.consume(); let captured = moq_net::Timestamp::from_millis(1_234).unwrap(); let record = json!({ "n": 1 }); diff --git a/rs/moq-json/src/stream/producer.rs b/rs/moq-json/src/stream/producer.rs index aea5e2012bf..341d994c850 100644 --- a/rs/moq-json/src/stream/producer.rs +++ b/rs/moq-json/src/stream/producer.rs @@ -126,7 +126,7 @@ impl Inner { let opened = track.open(); let published = opened.is_ok(); let result = match opened { - Ok(()) => track.write(payload.at.unwrap_or_else(moq_net::Timestamp::now), record.payload()), + Ok(()) => track.write(payload.at, record.payload()), Err(err) => Err(err), }; @@ -182,7 +182,7 @@ impl Track { /// Append one encoded record to the log's group at `timestamp`. fn write( &mut self, - timestamp: moq_net::Timestamp, + timestamp: Option, payload: &bytes::Bytes, ) -> std::result::Result<(), moq_net::Error> { let group = self.group.as_mut().expect("a group is open"); diff --git a/rs/moq-json/src/window/mod.rs b/rs/moq-json/src/window/mod.rs index f3bf0567dfa..04618e6eb2f 100644 --- a/rs/moq-json/src/window/mod.rs +++ b/rs/moq-json/src/window/mod.rs @@ -66,15 +66,71 @@ mod test { use super::*; + #[test] + fn pushes_and_pops_keep_the_callers_timestamps() { + let (mut producer, mut groups) = producer_on(ProducerConfig::default(), timed()); + let first = moq_net::Timestamp::from_millis(100).unwrap(); + let second = moq_net::Timestamp::from_millis(200).unwrap(); + producer + .push(moq_net::Timed::from(&json!({ "n": 1 })).at(first)) + .unwrap(); + producer.pop(moq_net::Timed::from(1u64).at(second)).unwrap(); + let waiter = kio::Waiter::noop(); + let Poll::Ready(Ok(Some(mut group))) = groups.poll_recv_group(&waiter) else { + panic!("expected the window group"); + }; + for at in [first, second] { + let Poll::Ready(Ok(Some(frame))) = group.poll_read_frame(&waiter) else { + panic!("expected the timestamped window edit"); + }; + assert_eq!(frame.timestamp, Some(at)); + } + } + + #[test] + fn a_timed_track_refuses_a_bare_publish() { + let (mut producer, _) = producer_on(ProducerConfig::default(), timed()); + assert!(matches!( + producer.push(&json!({ "n": 1 })), + Err(crate::Error::Net(moq_net::Error::TimestampMismatch)) + )); + } + + #[test] + fn a_bare_publish_stays_untimed() { + let track = moq_net::broadcast::Info::new() + .produce() + .create_track("untimed", moq_net::track::Info::default()) + .unwrap(); + let mut groups = track.subscribe(None); + let mut producer = Producer::new(track, ProducerConfig::default()); + producer.push(&json!({ "n": 1 })).unwrap(); + let waiter = kio::Waiter::noop(); + let Poll::Ready(Ok(Some(mut group))) = groups.poll_recv_group(&waiter) else { + panic!("expected an untimed group"); + }; + let Poll::Ready(Ok(Some(frame))) = group.poll_read_frame(&waiter) else { + panic!("expected an untimed frame"); + }; + assert_eq!(frame.timestamp, None); + } + /// A millisecond track: the frames written here carry timestamps. fn timed() -> moq_net::track::Info { moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI) } fn producer(config: ProducerConfig) -> (Producer, moq_net::track::Subscriber) { + producer_on(config, moq_net::track::Info::default()) + } + + fn producer_on( + config: ProducerConfig, + info: moq_net::track::Info, + ) -> (Producer, moq_net::track::Subscriber) { let track = moq_net::broadcast::Info::new() .produce() - .create_track("test", timed()) + .create_track("test", info) .unwrap(); let consumer = track.subscribe(None); (Producer::new(track, config), consumer) @@ -366,7 +422,7 @@ mod test { fn a_fresh_consumer_adopts_the_offset_without_skipping_history() { let track = moq_net::broadcast::Info::new() .produce() - .create_track("test", timed()) + .create_track("test", moq_net::track::Info::default()) .unwrap(); let mut producer = Producer::::new(track, ProducerConfig::default().with_op_ratio(0)); @@ -661,7 +717,7 @@ mod test { fn cut_finishes_the_group_and_the_next_edit_restates() { let track = moq_net::broadcast::Info::new() .produce() - .create_track("test", timed()) + .create_track("test", moq_net::track::Info::default()) .unwrap(); let replay = moq_net::track::Subscription::default().with_max_delay(std::time::Duration::from_secs(30)); let mut groups = track.subscribe(replay); diff --git a/rs/moq-json/src/window/producer.rs b/rs/moq-json/src/window/producer.rs index 50d604bf9c0..e3808869c2f 100644 --- a/rs/moq-json/src/window/producer.rs +++ b/rs/moq-json/src/window/producer.rs @@ -3,6 +3,7 @@ use std::marker::PhantomData; use std::sync::{Arc, Mutex}; +use moq_net::Timed; use serde::Serialize; use serde_json::Value; @@ -66,12 +67,12 @@ impl Producer { self.inner.lock().unwrap().encoder.range() } - /// Drop `count` records from the front of the window. + /// Drop records from the front at `count`'s timestamp, or untimed when absent. /// /// A no-op when the window is already empty, and clamped to what it holds, so a caller can trim /// unconditionally. - pub fn pop(&mut self, count: u64) -> Result<()> { - self.inner.lock().unwrap().pop(count) + pub fn pop(&mut self, count: impl Into>) -> Result<()> { + self.inner.lock().unwrap().pop(count.into()) } /// Finish the open group, leaving the next edit to open a replacement with a header. @@ -101,9 +102,12 @@ impl Producer { Ok(Self::with_encoder(track, Encoder::resume(config, checkpoint)?)) } - /// Append one record to the back of the window. - pub fn push(&mut self, value: &T) -> Result<()> { - self.inner.lock().unwrap().push(value) + /// Append a record at its timestamp, or untimed when absent. + pub fn push<'a>(&mut self, value: impl Into>) -> Result<()> + where + T: 'a, + { + self.inner.lock().unwrap().push(value.into()) } } @@ -119,17 +123,17 @@ struct Inner { } impl Inner { - fn pop(&mut self, count: u64) -> Result<()> { + fn pop(&mut self, count: Timed) -> Result<()> { self.ensure_open()?; let Inner { track, encoder, .. } = self; - let Some(frame) = encoder.pop(count)? else { + let Some(frame) = encoder.pop(count.value)? else { return Ok(()); }; // A failed write drops the frame uncommitted. The pop is discarded, and the next edit opens a // new group because the attempted frame advanced the group-local compression state. - track.write(&frame)?; + track.write(count.at, &frame)?; frame.commit(); Ok(()) @@ -163,12 +167,12 @@ impl Inner { } impl Inner { - fn push(&mut self, value: &T) -> Result<()> { + fn push(&mut self, value: Timed<&T>) -> Result<()> { self.ensure_open()?; let Inner { track, encoder, .. } = self; - let frame = encoder.push(value)?; - track.write(&frame)?; + let frame = encoder.push(value.value)?; + track.write(value.at, &frame)?; frame.commit(); Ok(()) @@ -185,22 +189,22 @@ struct Track { impl Track { /// Write one encoded frame, rolling a group when it is a header. - fn write(&mut self, encoded: &Encoded) -> Result<()> { + fn write(&mut self, timestamp: Option, encoded: &Encoded) -> Result<()> { match encoded.keyframe { - true => self.write_header(encoded.payload.clone()), - false => self.write_op(encoded.payload.clone()), + true => self.write_header(timestamp, encoded.payload.clone()), + false => self.write_op(timestamp, encoded.payload.clone()), } } /// Close the open group and write the header as the first frame of a new one. - fn write_header(&mut self, payload: bytes::Bytes) -> Result<()> { + fn write_header(&mut self, timestamp: Option, payload: bytes::Bytes) -> Result<()> { // The previous group is complete; no more frames will be appended to it. if let Some(group) = self.group.take() { group.finish()?; } let mut group = self.inner.append_group()?; - if let Err(err) = group.write_frame(moq_net::Timestamp::now(), payload) { + if let Err(err) = group.write_frame(timestamp, payload) { // `append_group` already published this group, and a rejected frame (too large) doesn't // close the track. Dropping the handle does NOT close the group, so leaving it would strand // any subscriber that advanced into it with nothing to read and no end. @@ -213,11 +217,11 @@ impl Track { } /// Append an op to the group the last header opened. - fn write_op(&mut self, payload: bytes::Bytes) -> Result<()> { + fn write_op(&mut self, timestamp: Option, payload: bytes::Bytes) -> Result<()> { self.group .as_mut() .expect("the encoder only emits an op after a header opened a group") - .write_frame(moq_net::Timestamp::now(), payload)?; + .write_frame(timestamp, payload)?; Ok(()) } diff --git a/rs/moq-mux/src/binary.rs b/rs/moq-mux/src/binary.rs index 1894ab50d4c..b6562b80e89 100644 --- a/rs/moq-mux/src/binary.rs +++ b/rs/moq-mux/src/binary.rs @@ -19,7 +19,7 @@ //! # catalog: &moq_mux::catalog::Producer, //! # jpeg: bytes::Bytes, //! # ) -> moq_mux::Result<()> { -//! let info = moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI); +//! let info = moq_net::track::Info::default(); //! let track = broadcast.create_track("thumbnail", info)?; //! let config = moq_mux::binary::Config::default().with_mime("image/jpeg"); //! let mut thumbnail = catalog.binary_snapshot(track, config)?; @@ -31,6 +31,8 @@ //! 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 payload stays untimed; only a timed track accepts an explicit capture time. +//! //! A payload timed on the broadcast [`Clock`](crate::Clock) is written at that timestamp as given, //! and the entry advertises how late payloads reach the transport as its `jitter` and `delay`, the //! way a media rendition does. A capture [`Instant`](std::time::Instant) converts with @@ -183,7 +185,8 @@ impl Snapshot { /// A payload 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. pub fn update(&mut self, payload: impl Into>) -> crate::Result<()> { - let (payload, captured) = self.listing.stamp(payload.into()); + let payload = payload.into(); + let captured = payload.at; let size = self.inner.update(payload)?; self.listing.record(size, captured) } @@ -255,11 +258,8 @@ impl Stream { /// A catalog error publishing the measured bitrate is returned after the payload was written, so /// the track stays open and a retry would duplicate it. pub fn append(&mut self, payload: impl Into>) -> crate::Result<()> { - let (payload, captured) = match &mut self.listing { - Some(listing) => listing.stamp(payload.into()), - // A failed write already ended the log, which refuses this payload whatever its time. - None => (Timed::from(payload.into().value), None), - }; + let payload = payload.into(); + let captured = payload.at; let size = match self.inner.append(payload) { Ok(size) => size, // Refused before anything was written, so the log and its entry carry on. @@ -405,6 +405,10 @@ 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()).unwrap() + } + + fn timed_track(broadcast: &mut moq_net::broadcast::Producer, name: &str) -> moq_net::track::Producer { broadcast.create_track(name, timed()).unwrap() } @@ -419,12 +423,12 @@ mod test { } /// Drain the timestamp of every frame a subscriber currently has, without blocking. - fn stamps(subscriber: &mut moq_net::track::Subscriber) -> Vec { + fn stamps(subscriber: &mut moq_net::track::Subscriber) -> Vec> { let waiter = kio::Waiter::noop(); let mut stamps = Vec::new(); while let Poll::Ready(Ok(Some(mut group))) = subscriber.poll_recv_group(&waiter) { while let Poll::Ready(Ok(Some(frame))) = group.poll_read_frame(&waiter) { - stamps.push(frame.timestamp.unwrap().as_millis()); + stamps.push(frame.timestamp.map(|at| at.as_millis())); } } stamps @@ -448,13 +452,13 @@ mod test { fn a_late_capture_is_delay() { let (mut broadcast, catalog) = catalog(); let mut fast = catalog - .binary_stream(track(&mut broadcast, "fast"), Config::default()) + .binary_stream(timed_track(&mut broadcast, "fast"), Config::default()) .unwrap(); let mut slow = catalog - .binary_stream(track(&mut broadcast, "slow"), Config::default()) + .binary_stream(timed_track(&mut broadcast, "slow"), Config::default()) .unwrap(); let mut bare = catalog - .binary_stream(track(&mut broadcast, "bare"), Config::default()) + .binary_stream(timed_track(&mut broadcast, "bare"), Config::default()) .unwrap(); let anchor = std::time::Instant::now(); @@ -488,7 +492,7 @@ mod test { fn a_capture_measures_through_the_clock() { let (mut broadcast, catalog) = catalog(); let mut telemetry = catalog - .binary_stream(track(&mut broadcast, "telemetry"), Config::default()) + .binary_stream(timed_track(&mut broadcast, "telemetry"), Config::default()) .unwrap(); let captured = std::time::Instant::now(); @@ -513,7 +517,7 @@ mod test { catalog.timebase().anchor(first).unwrap(); let mut klv = catalog - .binary_stream(track(&mut broadcast, "klv"), Config::default()) + .binary_stream(timed_track(&mut broadcast, "klv"), Config::default()) .unwrap(); let mut subscriber = klv.consume(); let sample = moq_net::Timestamp::from_millis(3_600_040).unwrap(); @@ -521,7 +525,7 @@ mod test { let ahead = moq_net::Timestamp::from_millis(3_700_000).unwrap(); klv.append(Timed::from(&b"ahead"[..]).at(ahead)).unwrap(); - assert_eq!(stamps(&mut subscriber), [3_600_040, 3_700_000]); + assert_eq!(stamps(&mut subscriber), [Some(3_600_040), Some(3_700_000)]); } /// A timestamp ahead of now counts as on time: its track advertises no delay, and another track @@ -531,10 +535,10 @@ mod test { fn an_ahead_timestamp_counts_as_on_time() { let (mut broadcast, catalog) = catalog(); let mut slow = catalog - .binary_stream(track(&mut broadcast, "slow"), Config::default()) + .binary_stream(timed_track(&mut broadcast, "slow"), Config::default()) .unwrap(); let mut ahead = catalog - .binary_stream(track(&mut broadcast, "ahead"), Config::default()) + .binary_stream(timed_track(&mut broadcast, "ahead"), Config::default()) .unwrap(); let anchor = std::time::Instant::now(); @@ -564,26 +568,18 @@ mod test { /// An untimed payload is stamped on the broadcast clock too, so mixing it with captured payloads /// keeps the track on one timeline. #[test] - fn an_untimed_payload_shares_the_broadcast_clock() { + fn an_untimed_payload_stays_untimed() { let (mut broadcast, catalog) = catalog(); let mut telemetry = catalog .binary_stream(track(&mut broadcast, "telemetry"), Config::default()) .unwrap(); let mut subscriber = telemetry.consume(); - - let before = catalog.clock().now(); telemetry.append(&b"untimed"[..]).unwrap(); - telemetry - .append(Timed::from(&b"timed"[..]).at(catalog.clock().now())) - .unwrap(); - let after = catalog.clock().now(); - - let stamps = stamps(&mut subscriber); - assert_eq!(stamps.len(), 2); + assert_eq!(stamps(&mut subscriber), vec![None]); assert!( - // The track stores milliseconds. - before.as_millis() <= stamps[0] && stamps[0] <= stamps[1] && stamps[1] <= after.as_millis(), - "{before:?} {stamps:?} {after:?}" + telemetry + .append(Timed::from(&b"timed"[..]).at(catalog.clock().now())) + .is_err() ); } @@ -594,10 +590,12 @@ mod test { fn an_importer_joins_the_data_tracks_clock() { let (mut broadcast, catalog) = catalog(); let mut stream = catalog - .binary_stream(track(&mut broadcast, "telemetry"), Config::default()) + .binary_stream(timed_track(&mut broadcast, "telemetry"), Config::default()) .unwrap(); let mut subscriber = stream.consume(); - stream.append(&b"before"[..]).unwrap(); + stream + .append(Timed::from(&b"before"[..]).at(catalog.clock().now())) + .unwrap(); let published = catalog.snapshot().clock; let before = catalog.clock().now(); @@ -605,12 +603,14 @@ mod test { .timebase() .shift(moq_net::Timestamp::from_micros(3_600_000_000).unwrap()) .unwrap(); - stream.append(&b"after"[..]).unwrap(); + stream + .append(Timed::from(&b"after"[..]).at(catalog.clock().now())) + .unwrap(); let after = catalog.clock().now(); assert_eq!(catalog.snapshot().clock, published, "the clock never moves"); assert!(before <= first && first <= after, "{before:?} {first:?} {after:?}"); - let stamps = stamps(&mut subscriber); + let stamps: Vec<_> = stamps(&mut subscriber).into_iter().map(Option::unwrap).collect(); assert_eq!(stamps.len(), 2); assert!(stamps[0] <= stamps[1] && stamps[1] <= after.as_millis(), "{stamps:?}"); let jitter = entry(&catalog, "telemetry").jitter; @@ -649,7 +649,7 @@ mod test { assert_eq!(catalog.snapshot().clock, None); let stamps = stamps(&mut subscriber); assert_eq!(stamps.len(), 2); - assert!(stamps[0] < 3_600_000 && 3_600_000 <= stamps[1], "{stamps:?}"); + assert_eq!(stamps, vec![None, None], "data writes never fill the moved clock"); assert_eq!( entry(&catalog, "telemetry").bitrate, None, diff --git a/rs/moq-mux/src/catalog/data.rs b/rs/moq-mux/src/catalog/data.rs index 88f91aeccac..4a2af87a1c8 100644 --- a/rs/moq-mux/src/catalog/data.rs +++ b/rs/moq-mux/src/catalog/data.rs @@ -80,24 +80,17 @@ impl Listing { self.rendition.name() } - /// Stamp an untimed payload with the catalog's current clock reading, keeping a timed one as - /// given. Also returns the given time, if there was one. - pub(crate) fn stamp

(&mut self, timed: moq_net::Timed

) -> (moq_net::Timed

, Option) { + /// Measure a frame of `bytes` encoded bytes, just written, captured at `captured` on the + /// broadcast clock if known. + pub(crate) fn record(&mut self, bytes: usize, captured: Option) -> crate::Result<()> { let clock = self.rendition.clock(); - // A re-anchor moves this track's timeline, which measured across would read as jitter. The - // whole clock is compared: on a host with an unset wall clock, every clock has no mapping. + // A re-anchor moves this track's timeline, which measured across would read as jitter. + // Compare the whole clock, since an unset host wall clock has no mapping to compare. if clock != self.clock { self.estimator.discontinuity(); } self.clock = clock; - let given = timed.at; - (timed.at(given.unwrap_or_else(|| clock.now())), given) - } - - /// Measure a frame of `bytes` encoded bytes, just written, captured at `captured` on the - /// broadcast clock if known. - pub(crate) fn record(&mut self, bytes: usize, captured: Option) -> crate::Result<()> { - let now = self.clock.now(); + let now = clock.now(); let flush = captured.map(|captured| (captured, std::time::Instant::now())); self.record_at(now, bytes, flush) } diff --git a/rs/moq-mux/src/catalog/producer.rs b/rs/moq-mux/src/catalog/producer.rs index ccb7cebdec5..82ef35415fe 100644 --- a/rs/moq-mux/src/catalog/producer.rs +++ b/rs/moq-mux/src/catalog/producer.rs @@ -176,9 +176,11 @@ impl Outputs { // Every consumer refuses a catalog that fails this, so refuse it before it reaches one. catalog.check_renditions()?; // One snapshot per group while deltas are disabled; the `.z` track carries the identical catalog. - self.hang.update(catalog)?; + self.hang + .update(moq_net::Timed::from(catalog).at(moq_net::Timestamp::now()))?; self.catalog_timeline.lock().unwrap().record(&self.hang_track); - self.hangz.update(catalog)?; + self.hangz + .update(moq_net::Timed::from(catalog).at(moq_net::Timestamp::now()))?; // The MSF catalog is derived from our own types, so a serialize failure means an extension broke // the shape; report it like any other JSON failure rather than panicking. `abort` below is diff --git a/rs/moq-mux/src/container/fmp4/import_test.rs b/rs/moq-mux/src/container/fmp4/import_test.rs index 871eb35b322..209aceedb40 100644 --- a/rs/moq-mux/src/container/fmp4/import_test.rs +++ b/rs/moq-mux/src/container/fmp4/import_test.rs @@ -1404,7 +1404,9 @@ async fn join_after(earlier: Earlier, start_us: u64) { ) .unwrap(); let mut stream = catalog.binary_stream(track, crate::binary::Config::default()).unwrap(); - stream.append(&b"before"[..]).unwrap(); + stream + .append(moq_net::Timed::from(&b"before"[..]).at(catalog.clock().now())) + .unwrap(); Some(stream) } Earlier::Capture => None, @@ -1419,7 +1421,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(&b"after"[..]).unwrap(); + stream + .append(moq_net::Timed::from(&b"after"[..]).at(catalog.clock().now())) + .unwrap(); } fmp4.finish().unwrap(); diff --git a/rs/moq-mux/src/json.rs b/rs/moq-mux/src/json.rs index 1010c1360e3..cf4a2d224b7 100644 --- a/rs/moq-mux/src/json.rs +++ b/rs/moq-mux/src/json.rs @@ -20,7 +20,7 @@ //! # broadcast: &mut moq_net::broadcast::Producer, //! # catalog: &moq_mux::catalog::Producer, //! # ) -> moq_mux::Result<()> { -//! let info = moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI); +//! let info = moq_net::track::Info::default(); //! let track = broadcast.create_track("chat", info)?; //! let config = moq_mux::json::Config::default().with_compression(true); //! let mut chat = catalog.json_stream::(track, config)?; @@ -32,6 +32,8 @@ //! 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`](std::time::Instant) converts with @@ -229,7 +231,8 @@ impl Snapshot { where T: 'a, { - let (value, captured) = self.listing.stamp(value.into()); + let value = value.into(); + let captured = value.at; match self.inner.update(value)? { Some(size) => self.listing.record(size, captured), None => Ok(()), @@ -311,11 +314,8 @@ impl Stream { where T: 'a, { - let (value, captured) = match &mut self.listing { - Some(listing) => listing.stamp(value.into()), - // A failed write already ended the log, which refuses this record whatever its time. - None => (Timed::from(value.into().value), None), - }; + let value = value.into(); + let captured = value.at; let size = match self.inner.append(value) { Ok(size) => size, // Refused before anything was written, so the log and its entry carry on. @@ -463,6 +463,10 @@ 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()).unwrap() + } + + fn timed_track(broadcast: &mut moq_net::broadcast::Producer, name: &str) -> moq_net::track::Producer { broadcast.create_track(name, timed()).unwrap() } @@ -530,15 +534,15 @@ mod test { } /// A track registered before an importer's first frame fixes the clock, so an importer starting - /// an hour in shifts onto it: the track keeps stamping on the clock it started with. + /// an hour in shifts onto it: the publisher keeps stamping on the clock it started with. #[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()) + .json_snapshot::(timed_track(&mut broadcast, "status"), Config::default()) .unwrap(); let mut chat = catalog - .json_stream::(track(&mut broadcast, "chat"), Config::default()) + .json_stream::(timed_track(&mut broadcast, "chat"), Config::default()) .unwrap(); let mut subscribers = [status.consume(), chat.consume()]; @@ -551,7 +555,9 @@ 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(&json!({ "live": true })).unwrap(); + status + .update(Timed::from(&json!({ "live": true })).at(catalog.clock().now())) + .unwrap(); chat.append(Timed::from(&json!({ "n": 1 })).at(catalog.clock().now())) .unwrap(); let after = catalog.clock().now(); @@ -594,10 +600,9 @@ mod test { full.finish().unwrap(); delta.finish().unwrap(); - // The default subscription budget keeps only the latest group. Ratio 0 rolled a new - // group for the second value, so that group holds one frame. A positive ratio appends - // the second value to the same group. - assert_eq!(ready_groups(&mut full_track), vec![1]); + // Untimed groups have no age budget to skip them: ratio 0 gives each value its + // own group, while the positive ratio appends a delta to the first group. + assert_eq!(ready_groups(&mut full_track), vec![1, 1]); assert_eq!(ready_groups(&mut delta_track), vec![2]); } @@ -720,7 +725,7 @@ mod test { fn an_unchanged_snapshot_measures_nothing() { let (mut broadcast, catalog) = catalog(); let mut status = catalog - .json_snapshot::(track(&mut broadcast, "status"), Config::default()) + .json_snapshot::(timed_track(&mut broadcast, "status"), Config::default()) .unwrap(); let now = catalog.clock().now(); let value = serde_json::json!({ "armed": true }); diff --git a/rs/moq-mux/src/timeline.rs b/rs/moq-mux/src/timeline.rs index 85bcf2aa9cc..c7fc1bc6844 100644 --- a/rs/moq-mux/src/timeline.rs +++ b/rs/moq-mux/src/timeline.rs @@ -403,12 +403,16 @@ impl Producer { actual: record.sequence, }); } - self.sink.push(record).map_err(json) + self.sink + .push(moq_net::Timed::from(record).at(moq_net::Timestamp::now())) + .map_err(json) } /// Remove up to `count` oldest records from the window. pub fn pop(&mut self, count: u64) -> crate::Result<()> { - self.sink.pop(count).map_err(json) + self.sink + .pop(moq_net::Timed::from(count).at(moq_net::Timestamp::now())) + .map_err(json) } /// Close the track's open group, so every push and pop so far sits in a complete group. diff --git a/rs/moq-net/src/model/timed.rs b/rs/moq-net/src/model/timed.rs index 4cb354f7d9f..71bdc7f7b69 100644 --- a/rs/moq-net/src/model/timed.rs +++ b/rs/moq-net/src/model/timed.rs @@ -4,27 +4,25 @@ use crate::Timestamp; /// A value to publish, and optionally when it was captured. /// -/// `T` is the clock the time is on: a raw [`Timestamp`] by default, or whatever a higher layer -/// maps onto one. Converts from a bare payload (bytes, or a `&V` to serialize), so a producer -/// taking one still accepts the plain value, stamped when written. +/// Converts from a bare payload (bytes, or a `&V` to serialize), which stays untimed. #[derive(Debug, Clone, Copy)] -pub struct Timed { +pub struct Timed

{ /// The value to publish. pub value: P, - /// When the value was captured. `None` stamps it when written. - pub at: Option, + /// When the value was captured. `None` leaves it untimed. + pub at: Option, } -impl Timed { +impl

Timed

{ /// Set when the value was captured. - pub fn at(mut self, at: T) -> Self { + pub fn at(mut self, at: Timestamp) -> Self { self.at = Some(at); self } } -impl, T> From for Timed { +impl> From for Timed { fn from(value: B) -> Self { Self { value: value.into(), @@ -33,12 +31,18 @@ impl, T> From for Timed { } } -impl<'a, V, T> From<&'a V> for Timed<&'a V, T> { +impl<'a, V> From<&'a V> for Timed<&'a V> { fn from(value: &'a V) -> Self { Self { value, at: None } } } +impl From for Timed { + fn from(value: u64) -> Self { + Self { value, at: None } + } +} + #[cfg(test)] mod tests { use super::*; @@ -53,7 +57,7 @@ mod tests { assert_eq!(stamped.at, Some(Timestamp::from_millis(5).unwrap())); let value = 7u32; - let timed: Timed<&u32, std::time::Instant> = (&value).into(); + let timed: Timed<&u32> = (&value).into(); assert_eq!(*timed.value, 7); } } diff --git a/rs/moq-room/src/chat.rs b/rs/moq-room/src/chat.rs index fd1dafe3696..c5fc4c3108c 100644 --- a/rs/moq-room/src/chat.rs +++ b/rs/moq-room/src/chat.rs @@ -92,7 +92,8 @@ impl Publisher { return Ok(()); } self.prune()?; - self.producer.push(&text.to_owned())?; + self.producer + .push(moq_net::Timed::from(&text.to_owned()).at(moq_net::Timestamp::now()))?; self.expires.push_back(Instant::now() + HISTORY); Ok(()) } @@ -103,7 +104,8 @@ impl Publisher { if count == 0 { return Ok(()); } - self.producer.pop(count as u64)?; + self.producer + .pop(moq_net::Timed::from(count as u64).at(moq_net::Timestamp::now()))?; self.expires.drain(..count); Ok(()) } diff --git a/rs/moq-stats/benches/aggregate.rs b/rs/moq-stats/benches/aggregate.rs index 9d9b1610972..82978dde963 100644 --- a/rs/moq-stats/benches/aggregate.rs +++ b/rs/moq-stats/benches/aggregate.rs @@ -69,7 +69,9 @@ impl Node { for traffic in self.frame.values_mut() { traffic.bytes += bytes; } - self.traffic.update(&self.frame).unwrap(); + self.traffic + .update(moq_net::Timed::from(&self.frame).at(moq_net::Timestamp::now())) + .unwrap(); } } diff --git a/rs/moq-stats/src/aggregate.rs b/rs/moq-stats/src/aggregate.rs index 4b20f555c29..69015632cdc 100644 --- a/rs/moq-stats/src/aggregate.rs +++ b/rs/moq-stats/src/aggregate.rs @@ -1024,7 +1024,9 @@ mod tests { fn publish(&mut self, path: &str, bytes: u64) { let entry = self.frame.entry(path.to_string()).or_default(); entry.bytes += bytes; - self.traffic.update(&self.frame).expect("publish"); + self.traffic + .update(moq_net::Timed::from(&self.frame).at(moq_net::Timestamp::now())) + .expect("publish"); } /// Fail the node's reader: append a frame the snapshot decoder can't @@ -1598,7 +1600,10 @@ mod tests { published.subscriptions_ended = 1; published.bytes = 100; node_a.frame.insert("acme/room".to_string(), published); - node_a.traffic.update(&node_a.frame).expect("publish"); + node_a + .traffic + .update(moq_net::Timed::from(&node_a.frame).at(moq_net::Timestamp::now())) + .expect("publish"); let agg = Consumer::new(origin.consume(), Config::new().with_depth(1)); let mut traffic = agg.traffic(&Tier::default(), Role::Publisher); @@ -1770,7 +1775,9 @@ mod tests { let mut totals = Totals::default(); totals.publisher.bytes = bytes; self.totals - .update(&TotalsFrame::from([(String::new(), totals)])) + .update( + moq_net::Timed::from(&TotalsFrame::from([(String::new(), totals)])).at(moq_net::Timestamp::now()), + ) .expect("publish"); } } diff --git a/rs/moq-transcode/src/catalog.rs b/rs/moq-transcode/src/catalog.rs index bc6104b0d3d..c8af31b0021 100644 --- a/rs/moq-transcode/src/catalog.rs +++ b/rs/moq-transcode/src/catalog.rs @@ -986,7 +986,7 @@ mod tests { .unwrap(); let mut subscriber = status.consume(); tokio::time::advance(Duration::from_secs(3)).await; - status.update(&1).unwrap(); + status.update(moq_net::Timed::from(&1).at(adopted.now())).unwrap(); let waiter = kio::Waiter::noop(); let std::task::Poll::Ready(Ok(Some(mut group))) = subscriber.poll_recv_group(&waiter) else { diff --git a/swift/Sources/Moq/Flate.swift b/swift/Sources/Moq/Flate.swift new file mode 100644 index 00000000000..3ed5ba6a974 --- /dev/null +++ b/swift/Sources/Moq/Flate.swift @@ -0,0 +1,43 @@ +import Foundation +import MoqFFI + +/// Opaque snapshot and stream tracks, mirroring the moq-flate crate. +public enum Flate {} + +extension Flate { + /// Publishes the latest opaque payload on a track it takes over. + public final class SnapshotProducer: Sendable { + let ffi: MoqFlateSnapshotProducer + + /// Take over the track and advertise its compression and media type in the catalog. + public init(broadcast: BroadcastProducer, track: TrackProducer, compression: Bool = false, mime: String? = nil) throws { + ffi = try MoqFlateSnapshotProducer(broadcast: broadcast.ffi, track: track.ffi, config: MoqFlateConfig(compression: compression, mime: mime)) + } + + /// Replace the payload at the given broadcast time, or leave it untimed when nil. + public func update(_ payload: Data, timestampUs: UInt64? = nil) throws { + try ffi.update(payload: payload, timestampUs: timestampUs) + } + + /// Close the track and retire its catalog entry. + public func finish() throws { try ffi.finish() } + } + + /// Publishes an ordered opaque payload log on a track it takes over. + public final class StreamProducer: Sendable { + let ffi: MoqFlateStreamProducer + + /// Take over the track and advertise its compression and media type in the catalog. + public init(broadcast: BroadcastProducer, track: TrackProducer, compression: Bool = false, mime: String? = nil) throws { + ffi = try MoqFlateStreamProducer(broadcast: broadcast.ffi, track: track.ffi, config: MoqFlateConfig(compression: compression, mime: mime)) + } + + /// Append a payload at the given broadcast time, or leave it untimed when nil. + public func append(_ payload: Data, timestampUs: UInt64? = nil) throws { + try ffi.append(payload: payload, timestampUs: timestampUs) + } + + /// Close the track and retire its catalog entry. + public func finish() throws { try ffi.finish() } + } +} diff --git a/swift/Sources/Moq/Json.swift b/swift/Sources/Moq/Json.swift index 222fa7c677e..e1f36f3acf0 100644 --- a/swift/Sources/Moq/Json.swift +++ b/swift/Sources/Moq/Json.swift @@ -40,8 +40,8 @@ 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) throws { - try ffi.update(value: encodeJson(value)) + public func update(_ value: Value, timestampUs: UInt64? = nil) throws { + try ffi.update(value: encodeJson(value), timestampUs: timestampUs) } /// A watch-only handle to whether the track has subscribers. @@ -109,8 +109,8 @@ extension Json { } /// Append one record to the log. - public func append(_ value: Value) throws { - try ffi.append(value: encodeJson(value)) + public func append(_ value: Value, timestampUs: UInt64? = nil) throws { + try ffi.append(value: encodeJson(value), timestampUs: timestampUs) } /// A watch-only handle to whether the track has subscribers. diff --git a/swift/Sources/Moq/Media.swift b/swift/Sources/Moq/Media.swift index 50fe1dcd506..f2bcb18fd7e 100644 --- a/swift/Sources/Moq/Media.swift +++ b/swift/Sources/Moq/Media.swift @@ -60,6 +60,9 @@ public enum Media { let ffi: MoqMediaCatalogProducer /// Construct a weak catalog handle for this broadcast. public init(broadcast: BroadcastProducer) throws { ffi = try MoqMediaCatalogProducer(broadcast: broadcast.ffi) } + + /// Read the broadcast clock in microseconds, fixing it for subsequent media producers. + public func now() throws -> UInt64 { try ffi.now() } /// Replace the video properties shared by every rendition. public func setVideoProperties(_ properties: VideoProperties) throws { try ffi.setVideoProperties(properties: properties) } /// Set an application catalog section from its serialized JSON value. @@ -209,7 +212,7 @@ public enum Media { /// /// The importer derives keyframe status from the bitstream, so only the payload and its /// timestamp cross the boundary. - public func writeFrame(_ payload: Data, timestampUs: UInt64 = 0) throws { + public func writeFrame(_ payload: Data, timestampUs: UInt64) throws { try ffi.writeFrame(frame: Frame(payload: payload, timestampUs: timestampUs)) } diff --git a/swift/Sources/Moq/Track.swift b/swift/Sources/Moq/Track.swift index 3462c2001bc..f5883967f14 100644 --- a/swift/Sources/Moq/Track.swift +++ b/swift/Sources/Moq/Track.swift @@ -26,7 +26,7 @@ public final class TrackConsumer: AsyncSequence, Sendable { (try await ffi.recvGroup()).map(GroupConsumer.init) } - /// Read the first timestamped frame of the next group. Convenience for + /// Read the first raw frame of the next group. Convenience for /// one-frame-per-group tracks (status/command style). Completed empty groups /// are skipped. `nil` only once the track ends. Cancelling one call keeps /// the current group so a later `readFrame` or `nextGroup` still sees it. @@ -78,9 +78,9 @@ public final class TrackConsumer: AsyncSequence, Sendable { } } -/// Read side of a single group. Iterating yields timestamped raw frames. +/// Read side of a single group. Iterating yields raw frames. public final class GroupConsumer: AsyncSequence, Sendable { - /// The timestamped frame emitted by this sequence. + /// The raw frame emitted by this sequence. public typealias Element = Frame let ffi: MoqGroupConsumer @@ -94,7 +94,7 @@ public final class GroupConsumer: AsyncSequence, Sendable { ffi.sequence() } - /// The next timestamped frame, or `nil` once the group ends. + /// The next raw frame, or `nil` once the group ends. public func readFrame() async throws -> Frame? { try await ffi.readFrame() } @@ -180,7 +180,7 @@ public final class TrackProducer: Sendable { } /// Write a single-frame group with a timestamp in microseconds. - public func writeFrame(_ payload: Data, timestampUs: UInt64 = 0) throws { + public func writeFrame(_ payload: Data, timestampUs: UInt64? = nil) throws { try ffi.writeFrame(frame: Frame(payload: payload, timestampUs: timestampUs)) } @@ -188,7 +188,7 @@ public final class TrackProducer: Sendable { /// /// `timestampUs` is the presentation timestamp in microseconds. Payloads are /// capped at 1200 bytes. There is no stream fallback. - public func appendDatagram(_ payload: Data, timestampUs: UInt64 = 0) throws -> UInt64 { + public func appendDatagram(_ payload: Data, timestampUs: UInt64? = nil) throws -> UInt64 { try ffi.appendDatagram(frame: Frame(payload: payload, timestampUs: timestampUs)) } @@ -228,7 +228,7 @@ public final class GroupProducer: Sendable { } /// Write a frame with a timestamp in microseconds. - public func writeFrame(_ payload: Data, timestampUs: UInt64 = 0) throws { + public func writeFrame(_ payload: Data, timestampUs: UInt64? = nil) throws { try ffi.writeFrame(frame: Frame(payload: payload, timestampUs: timestampUs)) } diff --git a/swift/Tests/MoqTests/SmokeTests.swift b/swift/Tests/MoqTests/SmokeTests.swift index f8c80f98263..710dedeaaee 100644 --- a/swift/Tests/MoqTests/SmokeTests.swift +++ b/swift/Tests/MoqTests/SmokeTests.swift @@ -213,13 +213,15 @@ final class SmokeTests: XCTestCase { let broadcast = try BroadcastProducer() let catalog = try Media.CatalogProducer(broadcast: broadcast) try catalog.setSection(name: "app", json: "{\"value\":42}") + _ = try catalog.now() try broadcast.close() XCTAssertThrowsError(try catalog.removeSection(name: "app")) + XCTAssertThrowsError(try catalog.now()) } func testBroadcastConsumerFetchesCachedGroup() async throws { let broadcast = try BroadcastProducer() - let track = try broadcast.publishTrack(name: "events") + let track = try broadcast.publishTrack(name: "events", info: TrackInfo(timescale: 1_000_000)) let group = try track.appendGroup() try group.writeFrame(Data("cached".utf8), timestampUs: 0) try group.finish() @@ -313,9 +315,49 @@ final class SmokeTests: XCTestCase { try broadcast.close() } + func testFlateTimestampsRoundTrip() async throws { + for timestamp in [nil, UInt64(123_456)] { + for mode in ["snapshot", "stream"] { + let broadcast = try BroadcastProducer() + let info: TrackInfo? = timestamp.map { _ in TrackInfo(timescale: 1_000_000) } + let track = try broadcast.publishTrack(name: "data", info: info) + let consumer = try track.consume() + let payload = Data("payload".utf8) + if mode == "snapshot" { + let producer = try Flate.SnapshotProducer(broadcast: broadcast, track: track) + try producer.update(payload, timestampUs: timestamp) + try producer.finish() + } else { + let producer = try Flate.StreamProducer(broadcast: broadcast, track: track) + try producer.append(payload, timestampUs: timestamp) + try producer.finish() + } + let received = try await consumer.readFrame() + let frame = try XCTUnwrap(received) + XCTAssertEqual(frame.payload, payload) + XCTAssertEqual(frame.timestampUs, timestamp) + try broadcast.close() + } + } + } + + func testRawTrackWithoutTimestampStaysUntimed() async throws { + let broadcast = try BroadcastProducer() + let track = try broadcast.publishTrack(name: "untimed") + let consumer = try track.consume() + try track.writeFrame(Data("payload".utf8)) + let received = try await consumer.readFrame() + let frame = try XCTUnwrap(received) + XCTAssertEqual(frame.payload, Data("payload".utf8)) + XCTAssertNil(frame.timestampUs) + XCTAssertNil(try consumer.info().timescale) + try track.finish() + try broadcast.close() + } + func testRawTrackTimestamps() async throws { let broadcast = try BroadcastProducer() - let track = try broadcast.publishTrack(name: "events") + let track = try broadcast.publishTrack(name: "events", info: TrackInfo(timescale: 1_000_000)) let consumer = try track.consume() let payload = Data("ready".utf8) @@ -341,7 +383,7 @@ final class SmokeTests: XCTestCase { func testReadFrameSkipsEmptyThenPopulatedGroups() async throws { let broadcast = try BroadcastProducer() - let track = try broadcast.publishTrack(name: "status") + let track = try broadcast.publishTrack(name: "status", info: TrackInfo(timescale: 1_000_000)) let consumer = try track.consume() try track.appendGroup().finish() From 7264abc1046a9f1a8abac6f18a7be6908a948592 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 15 Oct 2026 08:30:25 -0700 Subject: [PATCH 3/7] test(moq-mux): superseded untimed groups now age by wall clock Co-Authored-By: Claude Opus 5.5 --- rs/moq-mux/src/json.rs | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/rs/moq-mux/src/json.rs b/rs/moq-mux/src/json.rs index cf4a2d224b7..a236f4e8920 100644 --- a/rs/moq-mux/src/json.rs +++ b/rs/moq-mux/src/json.rs @@ -600,9 +600,10 @@ mod test { full.finish().unwrap(); delta.finish().unwrap(); - // Untimed groups have no age budget to skip them: ratio 0 gives each value its - // own group, while the positive ratio appends a delta to the first group. - assert_eq!(ready_groups(&mut full_track), vec![1, 1]); + // The default subscription budget keeps only the latest group, aging untimed groups by + // wall clock. Ratio 0 rolled a new group for the second value, so that group holds one + // frame. A positive ratio appends the second value to the same group. + assert_eq!(ready_groups(&mut full_track), vec![1]); assert_eq!(ready_groups(&mut delta_track), vec![2]); } From 78a9c79dc4fff86ad84e4171bdc52260fc7a474f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 15 Oct 2026 09:17:09 -0700 Subject: [PATCH 4/7] test(ffi): publish the unfinished shutdown track as timed Co-Authored-By: Claude Opus 5.5 --- rs/moq-ffi/src/test.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rs/moq-ffi/src/test.rs b/rs/moq-ffi/src/test.rs index 15cbfe0b929..633ec70bba1 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -5790,7 +5790,7 @@ async fn shutdown_times_out_on_an_unfinished_track() { (&accepted, &client) }; let broadcast = create_announced(&publisher.publish(), "live"); - let track = broadcast.publish_track("data".into(), None).unwrap(); + let track = broadcast.publish_track("data".into(), Some(timed_info())).unwrap(); let remote = await_announced(&subscriber.consume(), "live").await; let reader = tokio::time::timeout(TIMEOUT, remote.subscribe_track("data".into(), None)) .await From 86995210caf685c751ed8a5fc777d1f899ced127 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 15 Oct 2026 09:58:18 -0700 Subject: [PATCH 5/7] test(moq-mux): stamp the TS follower's timed catalog Co-Authored-By: Claude Opus 5.5 --- rs/moq-mux/src/container/ts/export_test.rs | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/rs/moq-mux/src/container/ts/export_test.rs b/rs/moq-mux/src/container/ts/export_test.rs index 0952f3709cb..ebae31dce9c 100644 --- a/rs/moq-mux/src/container/ts/export_test.rs +++ b/rs/moq-mux/src/container/ts/export_test.rs @@ -229,7 +229,9 @@ async fn a_follower_keeps_hangz_after_catalog_eof() { let mut config = moq_json::snapshot::Config::default(); config.compression = moq_json::Compression::Deflate; let mut catalog = moq_json::snapshot::Producer::::new(track.clone(), config); - catalog.update(&Catalog::default()).unwrap(); + catalog + .update(moq_net::Timed::from(&Catalog::default()).at(moq_net::Timestamp::now())) + .unwrap(); broadcast .announce(moq_net::origin::Route::default().with_epoch(epoch.clone())) .unwrap(); From 2664b425779efa37576b3552edceec0d61ab170e Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 15 Oct 2026 12:02:08 -0700 Subject: [PATCH 6/7] fix(data): refuse a mismatched timestamp before publishing a group Co-Authored-By: Claude Opus 5.5 --- rs/moq-flate/src/snapshot/mod.rs | 11 +++++-- rs/moq-flate/src/snapshot/producer.rs | 4 +++ rs/moq-flate/src/stream/mod.rs | 39 ++++++++++++++++++++----- rs/moq-flate/src/stream/producer.rs | 6 ++++ rs/moq-json/src/snapshot/mod.rs | 36 +++++++++++++++++------ rs/moq-json/src/snapshot/producer.rs | 4 +++ rs/moq-json/src/stream/mod.rs | 42 +++++++++++++++++++++++---- rs/moq-json/src/stream/producer.rs | 6 ++++ rs/moq-json/src/window/mod.rs | 22 ++++++++++++-- rs/moq-json/src/window/producer.rs | 6 ++++ rs/moq-mux/src/binary.rs | 4 ++- rs/moq-mux/src/json.rs | 4 ++- rs/moq-net/src/model/track.rs | 5 ++++ 13 files changed, 159 insertions(+), 30 deletions(-) diff --git a/rs/moq-flate/src/snapshot/mod.rs b/rs/moq-flate/src/snapshot/mod.rs index c2e0c2fe7d5..49e0e2571fa 100644 --- a/rs/moq-flate/src/snapshot/mod.rs +++ b/rs/moq-flate/src/snapshot/mod.rs @@ -42,13 +42,20 @@ mod test { use super::*; + /// Refused before a replacement group is published, so the last value stays readable. #[test] fn a_timed_track_refuses_a_bare_publish() { - let (mut producer, _) = producer_on(false, timed()); + let (mut producer, track) = producer_on(false, timed()); + let at = moq_net::Timestamp::from_millis(100).unwrap(); + producer + .update(moq_net::Timed::::from(&b"keep"[..]).at(at)) + .unwrap(); assert!(matches!( - producer.update(&b"payload"[..]), + producer.update(&b"bare"[..]), Err(crate::Error::Net(moq_net::Error::TimestampMismatch)) )); + producer.finish().unwrap(); + assert_eq!(drain(consume(track, false)), vec![Bytes::from_static(b"keep")]); } #[test] diff --git a/rs/moq-flate/src/snapshot/producer.rs b/rs/moq-flate/src/snapshot/producer.rs index d6309d483e4..bd59e71727c 100644 --- a/rs/moq-flate/src/snapshot/producer.rs +++ b/rs/moq-flate/src/snapshot/producer.rs @@ -90,6 +90,10 @@ impl Inner { if payload.len() as u64 > moq_net::group::MAX_CACHE_BYTES { return Err(moq_net::Error::FrameTooLarge.into()); } + // The same goes for a timestamp that doesn't match the track. + if timestamp.is_some() != self.track.info().timescale.is_some() { + return Err(moq_net::Error::TimestampMismatch.into()); + } let size = payload.len(); let mut group = self.track.append_group()?; diff --git a/rs/moq-flate/src/stream/mod.rs b/rs/moq-flate/src/stream/mod.rs index ea4f408498f..1664ddbb8fb 100644 --- a/rs/moq-flate/src/stream/mod.rs +++ b/rs/moq-flate/src/stream/mod.rs @@ -59,13 +59,30 @@ mod test { use super::*; + /// Refused before the log's group opens, so the log carries on rather than ending. #[test] fn a_timed_track_refuses_a_bare_publish() { - let (mut producer, _) = producer_on(false, timed()); + let (mut producer, track) = producer_on(false, timed()); assert!(matches!( - producer.append(&b"payload"[..]), + producer.append(&b"zero"[..]), Err(crate::Error::Net(moq_net::Error::TimestampMismatch)) )); + let at = moq_net::Timestamp::from_millis(100).unwrap(); + producer + .append(moq_net::Timed::::from(&b"one"[..]).at(at)) + .unwrap(); + assert!(matches!( + producer.append(&b"two"[..]), + Err(crate::Error::Net(moq_net::Error::TimestampMismatch)) + )); + producer + .append(moq_net::Timed::::from(&b"three"[..]).at(at)) + .unwrap(); + producer.finish().unwrap(); + assert_eq!( + drain(track, false), + vec![Bytes::from_static(b"one"), Bytes::from_static(b"three")] + ); } #[test] @@ -248,6 +265,12 @@ mod test { .unwrap() } + /// `payload` at a time [`rejecting_track`] can't hold: it matches the timed track, so the + /// append gets as far as the group before the conversion fails. + fn late(payload: &'static [u8]) -> moq_net::Timed { + moq_net::Timed::from(Bytes::from_static(payload)).at(moq_net::Timestamp::from_millis(10_000).unwrap()) + } + /// A failed write must reach the consumer, not just the caller. A clean close drains a reader to /// `None`, which is exactly what a completed log looks like, so a truncated log would be /// indistinguishable from a whole one. @@ -257,7 +280,7 @@ mod test { let mut subscriber = track.subscribe(None); let mut producer = Producer::new(track, Config::default()); - assert!(producer.append(&b"rejected"[..]).is_err()); + assert!(producer.append(late(b"rejected")).is_err()); // Aborting the group alone is not enough: the group is dropped from the cache and the reader // still sees a clean end, which is exactly what a completed log looks like. @@ -354,8 +377,8 @@ mod test { }; assert!(matches!(group.poll_read_frame(&waiter), Poll::Ready(Ok(Some(_))))); - // Stamped now, which overflows the timescale, so the write fails and ends the log. - let Err(crate::Error::Net(written)) = producer.append(&b"rejected"[..]) else { + // Too late for the timescale, so the write fails and ends the log. + let Err(crate::Error::Net(written)) = producer.append(late(b"rejected")) else { panic!("the write should fail"); }; @@ -382,9 +405,9 @@ mod test { let track = rejecting_track(); let mut producer = Producer::new(track, Config::default()); - assert!(producer.append(&b"rejected"[..]).is_err()); + assert!(producer.append(late(b"rejected")).is_err()); assert!( - producer.append(&b"again"[..]).is_err(), + producer.append(late(b"again")).is_err(), "a second append must fail on the closed track rather than open another group" ); } @@ -396,7 +419,7 @@ mod test { let track = rejecting_track(); let mut producer = Producer::new(track, Config::default()); - let Err(written) = producer.append(&b"rejected"[..]) else { + let Err(written) = producer.append(late(b"rejected")) else { panic!("the write should fail"); }; diff --git a/rs/moq-flate/src/stream/producer.rs b/rs/moq-flate/src/stream/producer.rs index 093f8c298bc..2af3ca88b81 100644 --- a/rs/moq-flate/src/stream/producer.rs +++ b/rs/moq-flate/src/stream/producer.rs @@ -103,6 +103,12 @@ impl Inner { return Err(err.into()); } + // A timestamp that doesn't match the track is refused before anything changes: found by + // `write_frame`, it would be a hole that ends the whole log. + if timestamp.is_some() != self.track.info().timescale.is_some() { + return Err(moq_net::Error::TimestampMismatch.into()); + } + // Check before compressing: encoding advances the window, so a payload refused afterwards // would leave the encoder ahead of every reader. The worst case is checked rather than the // actual size for the same reason. Also checked before the group is opened, so a refused diff --git a/rs/moq-json/src/snapshot/mod.rs b/rs/moq-json/src/snapshot/mod.rs index 4cd6453b3ca..364772b0477 100644 --- a/rs/moq-json/src/snapshot/mod.rs +++ b/rs/moq-json/src/snapshot/mod.rs @@ -101,13 +101,22 @@ mod test { assert_eq!(frame.timestamp, Some(at)); } + /// Refused before a replacement group is published, so the last value stays readable. #[test] fn a_timed_track_refuses_a_bare_publish() { - let (mut producer, _) = producer_on(Config::default(), timed()); - assert!(matches!( - producer.update(&json!({ "n": 1 })), - Err(crate::Error::Net(moq_net::Error::TimestampMismatch)) - )); + for delta_ratio in [0, 100] { + let (mut producer, track) = producer_on(cfg(delta_ratio), timed()); + let at = moq_net::Timestamp::from_millis(100).unwrap(); + producer + .update(moq_net::Timed::from(&json!({ "n": 1 })).at(at)) + .unwrap(); + assert!(matches!( + producer.update(&json!({ "n": 2 })), + Err(crate::Error::Net(moq_net::Error::TimestampMismatch)) + )); + producer.finish().unwrap(); + assert_eq!(drain(track), vec![json!({ "n": 1 })], "delta_ratio={delta_ratio}"); + } } #[test] @@ -749,16 +758,16 @@ mod test { // Every frame is rejected, so each publish fails and the encoder resynchronizes. let mut producer = Producer::::new(rejecting_track(), Config::default()); - let mut guard = producer.modify(None).unwrap(); + let mut guard = producer.modify(Some(late())).unwrap(); guard.video = Some("v1".to_string()); assert!(guard.commit().is_err()); - let mut guard = producer.modify(None).unwrap(); + let mut guard = producer.modify(Some(late())).unwrap(); guard.scte35 = Some(42); assert!(guard.commit().is_err()); // The editing baseline still carries the composed value. - let guard = producer.modify(None).unwrap(); + let guard = producer.modify(Some(late())).unwrap(); assert_eq!( guard.video, Some("v1".to_string()), @@ -793,6 +802,12 @@ mod test { .unwrap() } + /// A time [`rejecting_track`] can't hold: it matches the timed track, so the publish gets as + /// far as the group before the conversion fails. + fn late() -> moq_net::Timestamp { + moq_net::Timestamp::from_millis(10_000).unwrap() + } + /// `append_group` publishes the group before the frame is written, and a rejected frame does not /// close the track. Dropping the handle does not close the group either, so without an explicit /// close a subscriber that advanced into it waits there forever. @@ -802,7 +817,10 @@ mod test { let mut subscriber = track.subscribe(None).ordered(); let mut producer = Producer::::new(track, cfg(0)); - assert!(matches!(producer.update(&json!({ "a": 1 })), Err(crate::Error::Net(_)))); + assert!(matches!( + producer.update(moq_net::Timed::from(&json!({ "a": 1 })).at(late())), + Err(crate::Error::Net(_)) + )); let waiter = kio::Waiter::noop(); let Poll::Ready(Ok(Some(mut group))) = subscriber.poll_next_group(&waiter) else { diff --git a/rs/moq-json/src/snapshot/producer.rs b/rs/moq-json/src/snapshot/producer.rs index a7aae40c292..79b899dd507 100644 --- a/rs/moq-json/src/snapshot/producer.rs +++ b/rs/moq-json/src/snapshot/producer.rs @@ -383,6 +383,10 @@ impl Track { if encoded.payload.len() as u64 > moq_net::group::MAX_CACHE_BYTES { return Err(moq_net::Error::FrameTooLarge.into()); } + // The same goes for a timestamp that doesn't match the track. + if timestamp.is_some() != self.inner.info().timescale.is_some() { + return Err(moq_net::Error::TimestampMismatch.into()); + } match encoded.keyframe { true => self.write_snapshot(timestamp, encoded.payload.clone()), diff --git a/rs/moq-json/src/stream/mod.rs b/rs/moq-json/src/stream/mod.rs index 4b98502c081..a4f49ecba00 100644 --- a/rs/moq-json/src/stream/mod.rs +++ b/rs/moq-json/src/stream/mod.rs @@ -58,13 +58,27 @@ mod test { use super::*; use crate::Compression; + /// Refused before the log's group opens, so the log carries on rather than ending. #[test] fn a_timed_track_refuses_a_bare_publish() { - let (mut producer, _) = producer_on(Config::default(), timed()); + let (mut producer, track) = producer_on(Config::default(), timed()); assert!(matches!( - producer.append(&json!({ "n": 1 })), + producer.append(&json!({ "n": 0 })), Err(crate::Error::Net(moq_net::Error::TimestampMismatch)) )); + let at = moq_net::Timestamp::from_millis(100).unwrap(); + producer + .append(moq_net::Timed::from(&json!({ "n": 1 })).at(at)) + .unwrap(); + assert!(matches!( + producer.append(&json!({ "n": 2 })), + Err(crate::Error::Net(moq_net::Error::TimestampMismatch)) + )); + producer + .append(moq_net::Timed::from(&json!({ "n": 3 })).at(at)) + .unwrap(); + producer.finish().unwrap(); + assert_eq!(drain(consume(track, false)), vec![json!({ "n": 1 }), json!({ "n": 3 })]); } #[test] @@ -266,7 +280,11 @@ mod test { let mut bad = std::collections::BTreeMap::new(); bad.insert((1, 2), 3); - assert!(producer.append(&bad).is_err()); + assert!( + producer + .append(moq_net::Timed::from(&bad).at(moq_net::Timestamp::from_millis(0).unwrap())) + .is_err() + ); assert_eq!(subscriber.latest(), None, "a rejected record opened a group"); @@ -291,6 +309,12 @@ mod test { .unwrap() } + /// `value` at a time [`rejecting_track`] can't hold: it matches the timed track, so the + /// append gets as far as the group before the conversion fails. + fn late(value: &Value) -> moq_net::Timed<&Value> { + moq_net::Timed::from(value).at(moq_net::Timestamp::from_millis(10_000).unwrap()) + } + /// A failed write must reach the consumer, not just the caller. A clean close drains a reader to /// `None`, which is exactly what a completed log looks like, so a truncated log would be /// indistinguishable from a whole one. @@ -300,7 +324,10 @@ mod test { let mut subscriber = track.subscribe(None); let mut producer = Producer::::new(track, Config::default()); - assert!(matches!(producer.append(&json!({ "n": 1 })), Err(crate::Error::Net(_)))); + assert!(matches!( + producer.append(late(&json!({ "n": 1 }))), + Err(crate::Error::Net(_)) + )); let waiter = kio::Waiter::noop(); assert!( @@ -317,12 +344,15 @@ mod test { let track = rejecting_track(); let mut producer = Producer::::new(track, compressed()); - assert!(matches!(producer.append(&json!({ "n": 1 })), Err(crate::Error::Net(_)))); + assert!(matches!( + producer.append(late(&json!({ "n": 1 }))), + Err(crate::Error::Net(_)) + )); // The retry reports the abort rather than the `Error::Desync` the dropped record left on the // encoder, which says nothing about why the log stopped. assert!( - matches!(producer.append(&json!({ "n": 2 })), Err(crate::Error::Net(_))), + matches!(producer.append(late(&json!({ "n": 2 }))), Err(crate::Error::Net(_))), "a second append must fail on the ended track rather than open another group" ); diff --git a/rs/moq-json/src/stream/producer.rs b/rs/moq-json/src/stream/producer.rs index 341d994c850..6b182e0aacc 100644 --- a/rs/moq-json/src/stream/producer.rs +++ b/rs/moq-json/src/stream/producer.rs @@ -107,6 +107,12 @@ impl Inner { // Split the borrow so `record` can hold the encoder while `track` is written through. let Inner { track, encoder } = self; + // A timestamp that doesn't match the track is refused before anything changes: found by + // `write`, it would be a hole that ends the whole log. + if payload.at.is_some() != track.inner.info().timescale.is_some() { + return Err(moq_net::Error::TimestampMismatch.into()); + } + // Encode first, so a value that can't be serialized doesn't publish an empty group that // subscribers would advance into and wait on. Opening the group afterwards is safe because // `record` guards the window: any failure below drops it uncommitted. diff --git a/rs/moq-json/src/window/mod.rs b/rs/moq-json/src/window/mod.rs index 04618e6eb2f..bf2799dc2f5 100644 --- a/rs/moq-json/src/window/mod.rs +++ b/rs/moq-json/src/window/mod.rs @@ -87,13 +87,27 @@ mod test { } } + /// Refused before the header's group is published, so the window carries on cleanly. #[test] fn a_timed_track_refuses_a_bare_publish() { - let (mut producer, _) = producer_on(ProducerConfig::default(), timed()); + let (mut producer, track) = producer_on(ProducerConfig::default(), timed()); assert!(matches!( - producer.push(&json!({ "n": 1 })), + producer.push(&json!({ "n": 0 })), Err(crate::Error::Net(moq_net::Error::TimestampMismatch)) )); + assert_eq!(track.latest(), None, "a refused header published a group"); + let at = moq_net::Timestamp::from_millis(100).unwrap(); + producer.push(moq_net::Timed::from(&rec(1)).at(at)).unwrap(); + producer.push(moq_net::Timed::from(&rec(2)).at(at)).unwrap(); + producer.finish().unwrap(); + let pushed: Vec<_> = drain(&mut consumer(track, false)) + .into_iter() + .filter_map(|event| match event { + Event::Push { value, .. } => Some(value), + _ => None, + }) + .collect(); + assert_eq!(pushed, vec![rec(1), rec(2)]); } #[test] @@ -596,7 +610,9 @@ mod test { let mut subscriber = track.subscribe(None).ordered(); let mut producer = Producer::::new(track, ProducerConfig::default()); - assert!(producer.push(&rec(1)).is_err()); + // Too late for the timescale, so the header group is published before the write fails. + let late = moq_net::Timestamp::from_millis(10_000).unwrap(); + assert!(producer.push(moq_net::Timed::from(&rec(1)).at(late)).is_err()); assert_eq!(producer.range(), 0..0); assert!(producer.window().is_empty()); diff --git a/rs/moq-json/src/window/producer.rs b/rs/moq-json/src/window/producer.rs index e3808869c2f..babb9356a24 100644 --- a/rs/moq-json/src/window/producer.rs +++ b/rs/moq-json/src/window/producer.rs @@ -190,6 +190,12 @@ struct Track { impl Track { /// Write one encoded frame, rolling a group when it is a header. fn write(&mut self, timestamp: Option, encoded: &Encoded) -> Result<()> { + // Check before touching a group: a header publishes a new group before its frame is + // written, so a mismatch found by `write_frame` would leave an empty newest group behind. + if timestamp.is_some() != self.inner.info().timescale.is_some() { + return Err(moq_net::Error::TimestampMismatch.into()); + } + match encoded.keyframe { true => self.write_header(timestamp, encoded.payload.clone()), false => self.write_op(timestamp, encoded.payload.clone()), diff --git a/rs/moq-mux/src/binary.rs b/rs/moq-mux/src/binary.rs index b6562b80e89..3be259e1760 100644 --- a/rs/moq-mux/src/binary.rs +++ b/rs/moq-mux/src/binary.rs @@ -263,7 +263,9 @@ impl Stream { let size = match self.inner.append(payload) { Ok(size) => size, // Refused before anything was written, so the log and its entry carry on. - Err(err @ moq_flate::Error::Net(moq_net::Error::GroupTooLarge)) => return Err(err.into()), + Err(err @ moq_flate::Error::Net(moq_net::Error::GroupTooLarge | moq_net::Error::TimestampMismatch)) => { + return Err(err.into()); + } Err(err) => { // The inner producer has already closed the track. Dropping the listing retires the // catalog entry too: waiting for the handle to drop would keep advertising a track diff --git a/rs/moq-mux/src/json.rs b/rs/moq-mux/src/json.rs index a236f4e8920..7deb0a283da 100644 --- a/rs/moq-mux/src/json.rs +++ b/rs/moq-mux/src/json.rs @@ -319,7 +319,9 @@ impl Stream { let size = match self.inner.append(value) { Ok(size) => size, // Refused before anything was written, so the log and its entry carry on. - Err(err @ moq_json::Error::Net(moq_net::Error::GroupTooLarge)) => return Err(err.into()), + Err(err @ moq_json::Error::Net(moq_net::Error::GroupTooLarge | moq_net::Error::TimestampMismatch)) => { + return Err(err.into()); + } Err(err) => { // The inner producer has already ended the track. Dropping the listing retires the // catalog entry: waiting for the handle to drop would keep advertising a track that diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index 2ae78e53c84..522c42b2375 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -1870,6 +1870,11 @@ impl Producer { &self.broadcast } + /// The properties this track was created with. + pub fn info(&self) -> &Info { + &self.info + } + /// Create a new group with the given sequence number. pub fn create_group(&self, group: group::Info) -> Result { self.insert(group, false) From 2c512d96befc169e5fe2b0894b5ac1cef5b2dc03 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 15 Oct 2026 13:22:11 -0700 Subject: [PATCH 7/7] docs(data): document timestamp mismatch as a nonterminal refusal The stream appends refuse a mismatched timestamp before writing, like an oversized record, so say so. The custom rendition example published a bare payload on a timed track, which the preflight now refuses; make its track untimed. Co-Authored-By: Claude Opus 5.5 --- rs/moq-flate/src/stream/producer.rs | 4 +++- rs/moq-json/src/stream/producer.rs | 4 +++- rs/moq-mux/src/binary.rs | 3 ++- rs/moq-mux/src/catalog/tracks.rs | 2 +- rs/moq-mux/src/json.rs | 4 ++-- 5 files changed, 11 insertions(+), 6 deletions(-) diff --git a/rs/moq-flate/src/stream/producer.rs b/rs/moq-flate/src/stream/producer.rs index 2af3ca88b81..5f0db989b6d 100644 --- a/rs/moq-flate/src/stream/producer.rs +++ b/rs/moq-flate/src/stream/producer.rs @@ -54,7 +54,9 @@ impl Producer { /// A payload that might not fit in what is left of the group's budget is refused with /// [`moq_net::Error::GroupTooLarge`] before anything is written, leaving the log intact. The /// budget covers the whole log, so once it is spent every append is refused; a publisher with - /// more to say opens a new track. + /// more to say opens a new track. A timestamp whose presence doesn't match the track's timescale + /// is refused with [`moq_net::Error::TimestampMismatch`] the same way, so a corrected append + /// carries on. /// /// Any other payload that cannot be written ends the track: a log missing a record is not the /// lossless log this mode promises, so the failure is surfaced rather than papered over with a diff --git a/rs/moq-json/src/stream/producer.rs b/rs/moq-json/src/stream/producer.rs index 6b182e0aacc..6b7551aa026 100644 --- a/rs/moq-json/src/stream/producer.rs +++ b/rs/moq-json/src/stream/producer.rs @@ -70,7 +70,9 @@ impl Producer { /// A record that might not fit in what is left of the group's budget is refused with /// [`moq_net::Error::GroupTooLarge`] before anything is written, leaving the log intact. The /// budget covers the whole log, so once it is spent every append is refused; a publisher with - /// more to say opens a new track. + /// more to say opens a new track. A timestamp whose presence doesn't match the track's timescale + /// is refused with [`moq_net::Error::TimestampMismatch`] the same way, so a corrected append + /// carries on. /// /// Any other failure ends the track. A log missing a record is not the lossless log a stream /// promises, and that holds whether the group rejected the record or it never encoded at all, so diff --git a/rs/moq-mux/src/binary.rs b/rs/moq-mux/src/binary.rs index 3be259e1760..33e95470dab 100644 --- a/rs/moq-mux/src/binary.rs +++ b/rs/moq-mux/src/binary.rs @@ -254,7 +254,8 @@ impl Stream { /// /// A payload that cannot be written ends the track (see /// [`moq_flate::stream::Producer::append`]) and retires the catalog entry with it. A payload - /// refused with [`moq_net::Error::GroupTooLarge`] leaves both intact, since nothing was written. + /// refused with [`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 payload was written, so /// the track stays open and a retry would duplicate it. pub fn append(&mut self, payload: impl Into>) -> crate::Result<()> { diff --git a/rs/moq-mux/src/catalog/tracks.rs b/rs/moq-mux/src/catalog/tracks.rs index 8273e906665..51ea9165b52 100644 --- a/rs/moq-mux/src/catalog/tracks.rs +++ b/rs/moq-mux/src/catalog/tracks.rs @@ -71,7 +71,7 @@ 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_timescale(moq_net::Timescale::MILLI); +/// let info = moq_net::track::Info::default(); /// 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: BinaryConfig::new(Mode::Stream), sysid: 1 }; diff --git a/rs/moq-mux/src/json.rs b/rs/moq-mux/src/json.rs index 7deb0a283da..2e65a85154b 100644 --- a/rs/moq-mux/src/json.rs +++ b/rs/moq-mux/src/json.rs @@ -307,8 +307,8 @@ impl Stream { /// /// 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::GroupTooLarge`] 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::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 /// stays open and a retry would duplicate it. pub fn append<'a>(&mut self, value: impl Into>) -> crate::Result<()> where