diff --git a/cpp/moq/MIGRATE.md b/cpp/moq/MIGRATE.md index ec0b7243cd4..09da0c41629 100644 --- a/cpp/moq/MIGRATE.md +++ b/cpp/moq/MIGRATE.md @@ -4,6 +4,12 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Catalog references carry their epoch + +`Video` and `Audio` gain `epoch`, the publisher instance their `broadcast` reference names, right after `broadcast`; positional initializers shift by one. +`BroadcastConsumer::resolve(reference)` becomes `resolve(reference, epoch)`; pass the rendition's `epoch` alongside its `broadcast`, or `std::nullopt` to resolve whichever instance answers. +Resolving, and the rendition-based consumers, fail with `moq::Error::kMux` for a rendition whose broadcast is proven to serve another epoch. + ### Finished tracks stay until the broadcast ends (#6157) A finished track now stays listed, with its catalog rendition and demand, until its broadcast closes or the new `BroadcastProducer::finish` lets go. diff --git a/dart/moq/MIGRATE.md b/dart/moq/MIGRATE.md index 7a1f1be6ca3..3681db49226 100644 --- a/dart/moq/MIGRATE.md +++ b/dart/moq/MIGRATE.md @@ -4,6 +4,12 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Catalog references carry their epoch + +`Video` and `Audio` renditions gain `epoch`, the publisher instance their `broadcast` reference names. +`BroadcastConsumer.resolve(reference:)` requires `epoch:` too; pass the rendition's `epoch` alongside its `broadcast`, or `null` to resolve whichever instance answers. +Resolving, and the rendition-based consumers, throw for a rendition whose broadcast is proven to serve another epoch. + ### Finished tracks stay until the broadcast ends (#6157) A finished track now stays listed, with its catalog rendition and demand, until its broadcast closes or the new `BroadcastProducer.finish()` lets go. diff --git a/dart/moq_ffi/MIGRATE.md b/dart/moq_ffi/MIGRATE.md index 3e8c381a845..e0ee6d6efd6 100644 --- a/dart/moq_ffi/MIGRATE.md +++ b/dart/moq_ffi/MIGRATE.md @@ -4,6 +4,12 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Catalog references carry their epoch + +`MoqVideo` and `MoqAudio` gain `epoch`, the publisher instance their `broadcast` reference names. +`MoqBroadcastConsumer.resolve(reference:)` requires `epoch:` too; pass the rendition's `epoch` alongside, or `null` to resolve whichever instance answers. +Resolving, and the rendition-based consumers, fail a rendition whose broadcast is proven to serve another epoch with `MuxMoqException`. + ### Finished tracks stay until the broadcast ends (#6157) A finished track, raw or media, now stays listed, with its catalog rendition and demand, until its broadcast closes or the new `MoqBroadcastProducer.finish()` lets go, instead of unlisting when its producer finishes or is released. diff --git a/dart/moq_ffi/lib/src/moq.dart b/dart/moq_ffi/lib/src/moq.dart index 1d0d4121dcd..a9584a2d808 100644 --- a/dart/moq_ffi/lib/src/moq.dart +++ b/dart/moq_ffi/lib/src/moq.dart @@ -1094,6 +1094,7 @@ class FfiConverterMoqJsonValue { class MoqAudio { final String? label; final String? broadcast; + final String? epoch; final String? track; final String codec; final Uint8List? description; @@ -1106,6 +1107,7 @@ class MoqAudio { MoqAudio({ this.label = null, this.broadcast = null, + this.epoch = null, this.track = null, required this.codec, this.description, @@ -1135,6 +1137,11 @@ class FfiConverterMoqAudio { ); final broadcast = broadcast_lifted.value; new_offset += broadcast_lifted.bytesRead; + final epoch_lifted = FfiConverterOptionalString.read( + Uint8List.view(buf.buffer, new_offset), + ); + final epoch = epoch_lifted.value; + new_offset += epoch_lifted.bytesRead; final track_lifted = FfiConverterOptionalString.read( Uint8List.view(buf.buffer, new_offset), ); @@ -1184,6 +1191,7 @@ class FfiConverterMoqAudio { MoqAudio( label: label, broadcast: broadcast, + epoch: epoch, track: track, codec: codec, description: description, @@ -1202,6 +1210,7 @@ class FfiConverterMoqAudio { final total_length = FfiConverterOptionalString.allocationSize(value.label) + FfiConverterOptionalString.allocationSize(value.broadcast) + + FfiConverterOptionalString.allocationSize(value.epoch) + FfiConverterOptionalString.allocationSize(value.track) + FfiConverterString.allocationSize(value.codec) + FfiConverterOptionalUint8List.allocationSize(value.description) + @@ -1227,6 +1236,10 @@ class FfiConverterMoqAudio { value.broadcast, Uint8List.view(buf.buffer, new_offset), ); + new_offset += FfiConverterOptionalString.write( + value.epoch, + Uint8List.view(buf.buffer, new_offset), + ); new_offset += FfiConverterOptionalString.write( value.track, Uint8List.view(buf.buffer, new_offset), @@ -1269,6 +1282,7 @@ class FfiConverterMoqAudio { static int allocationSize(MoqAudio value) { return FfiConverterOptionalString.allocationSize(value.label) + FfiConverterOptionalString.allocationSize(value.broadcast) + + FfiConverterOptionalString.allocationSize(value.epoch) + FfiConverterOptionalString.allocationSize(value.track) + FfiConverterString.allocationSize(value.codec) + FfiConverterOptionalUint8List.allocationSize(value.description) + @@ -1966,6 +1980,7 @@ class FfiConverterMoqMediaTrackConfig { class MoqVideo { final String? label; final String? broadcast; + final String? epoch; final String? track; final String codec; final Uint8List? description; @@ -1978,6 +1993,7 @@ class MoqVideo { MoqVideo({ this.label = null, this.broadcast = null, + this.epoch = null, this.track = null, required this.codec, this.description, @@ -2007,6 +2023,11 @@ class FfiConverterMoqVideo { ); final broadcast = broadcast_lifted.value; new_offset += broadcast_lifted.bytesRead; + final epoch_lifted = FfiConverterOptionalString.read( + Uint8List.view(buf.buffer, new_offset), + ); + final epoch = epoch_lifted.value; + new_offset += epoch_lifted.bytesRead; final track_lifted = FfiConverterOptionalString.read( Uint8List.view(buf.buffer, new_offset), ); @@ -2056,6 +2077,7 @@ class FfiConverterMoqVideo { MoqVideo( label: label, broadcast: broadcast, + epoch: epoch, track: track, codec: codec, description: description, @@ -2074,6 +2096,7 @@ class FfiConverterMoqVideo { final total_length = FfiConverterOptionalString.allocationSize(value.label) + FfiConverterOptionalString.allocationSize(value.broadcast) + + FfiConverterOptionalString.allocationSize(value.epoch) + FfiConverterOptionalString.allocationSize(value.track) + FfiConverterString.allocationSize(value.codec) + FfiConverterOptionalUint8List.allocationSize(value.description) + @@ -2099,6 +2122,10 @@ class FfiConverterMoqVideo { value.broadcast, Uint8List.view(buf.buffer, new_offset), ); + new_offset += FfiConverterOptionalString.write( + value.epoch, + Uint8List.view(buf.buffer, new_offset), + ); new_offset += FfiConverterOptionalString.write( value.track, Uint8List.view(buf.buffer, new_offset), @@ -2141,6 +2168,7 @@ class FfiConverterMoqVideo { static int allocationSize(MoqVideo value) { return FfiConverterOptionalString.allocationSize(value.label) + FfiConverterOptionalString.allocationSize(value.broadcast) + + FfiConverterOptionalString.allocationSize(value.epoch) + FfiConverterOptionalString.allocationSize(value.track) + FfiConverterString.allocationSize(value.codec) + FfiConverterOptionalUint8List.allocationSize(value.description) + @@ -8332,7 +8360,10 @@ abstract class MoqBroadcastConsumerInterface { required int sequence, required MoqFetchGroupOptions? options, }); - Future resolve({required String? reference}); + Future resolve({ + required String? reference, + required String? epoch, + }); Future subscribeTrack({ required String name, required MoqSubscription? subscription, @@ -8395,11 +8426,15 @@ class MoqBroadcastConsumer implements MoqBroadcastConsumerInterface { ); } - Future resolve({required String? reference}) { + Future resolve({ + required String? reference, + required String? epoch, + }) { return uniffiRustCallAsync( () => uniffi_moq_ffi_fn_method_moqbroadcastconsumer_resolve( uniffiClonePointer(), FfiConverterOptionalString.lower(reference), + FfiConverterOptionalString.lower(epoch), ), ffi_moq_ffi_rust_future_poll_u64, ffi_moq_ffi_rust_future_complete_u64, @@ -15994,12 +16029,13 @@ uniffi_moq_ffi_fn_method_moqbroadcastconsumer_fetch_group( RustBuffer options, ); -@Native Function(Pointer, RustBuffer)>( +@Native Function(Pointer, RustBuffer, RustBuffer)>( assetId: _uniffiAssetId, ) external Pointer uniffi_moq_ffi_fn_method_moqbroadcastconsumer_resolve( Pointer ptr, RustBuffer reference, + RustBuffer epoch, ); @Native Function(Pointer, RustBuffer, RustBuffer)>( @@ -19310,7 +19346,7 @@ void _checkApiChecksums() { 18633) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqbroadcastconsumer_resolve() != 62317) { + if (uniffi_moq_ffi_checksum_method_moqbroadcastconsumer_resolve() != 33982) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqbroadcastconsumer_subscribe_track() != @@ -19883,7 +19919,7 @@ void _checkApiChecksums() { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_constructor_moqmediatrackconsumer_subscribe() != - 62204) { + 55638) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_constructor_moqmediatrackproducer_audio() != diff --git a/dart/moq_ffi/test/leak_test.dart b/dart/moq_ffi/test/leak_test.dart index edfbdc8dc7d..d95fea33b23 100644 --- a/dart/moq_ffi/test/leak_test.dart +++ b/dart/moq_ffi/test/leak_test.dart @@ -39,7 +39,7 @@ void main() { final consumer = MoqBroadcastProducer().consume(); final reference = 'x' * size; Future call() => expectLater( - consumer.resolve(reference: reference), + consumer.resolve(reference: reference, epoch: null), throwsA(isA()), ); diff --git a/go/ffi/MIGRATE.md b/go/ffi/MIGRATE.md index d7abfc288f8..85200148d87 100644 --- a/go/ffi/MIGRATE.md +++ b/go/ffi/MIGRATE.md @@ -4,6 +4,13 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Catalog references carry their epoch + +`MoqVideo` and `MoqAudio` gain `Epoch *string`, the publisher instance their `Broadcast` reference names. +`MoqBroadcastConsumer.Resolve` takes the rendition's `epoch` after `reference`; pass it alongside, or `nil` to resolve whichever instance answers. +Resolving, and the rendition-based consumers, fail a rendition whose broadcast is proven to serve another epoch with `Mux`. +Regenerate the bindings for the changed records and checksums. + ### Finished tracks stay until the broadcast ends (#6157) A finished track, raw or media, now stays listed, with its catalog rendition and demand, until its broadcast closes or the new `MoqBroadcastProducer.Finish()` lets go, instead of unlisting when its producer finishes or is released. diff --git a/go/wrapper/MIGRATE.md b/go/wrapper/MIGRATE.md index b5e60cf4cc7..a272db32a02 100644 --- a/go/wrapper/MIGRATE.md +++ b/go/wrapper/MIGRATE.md @@ -4,6 +4,12 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Catalog references carry their epoch + +`ffi.MoqVideo` and `ffi.MoqAudio` gain `Epoch`, the publisher instance their `Broadcast` reference names. +`BroadcastConsumer.Resolve(ctx, reference)` becomes `Resolve(ctx, reference, epoch)`; pass the rendition's `Epoch` alongside its `Broadcast`, or `nil` to resolve whichever instance answers. +Resolving, and the rendition-based consumers, error for a rendition whose broadcast is proven to serve another epoch. + ### Finished tracks stay until the broadcast ends (#6157) A finished track now stays listed, with its catalog rendition and demand, until its broadcast closes or the new `BroadcastProducer.Finish()` lets go. diff --git a/go/wrapper/subscribe.go b/go/wrapper/subscribe.go index f9172cf133f..d077dd03280 100644 --- a/go/wrapper/subscribe.go +++ b/go/wrapper/subscribe.go @@ -48,15 +48,17 @@ func (b *BroadcastConsumer) FetchGroup( // Resolve returns the broadcast serving a catalog rendition, honoring its broadcast // reference: ffi.MoqVideo.Broadcast / ffi.MoqAudio.Broadcast. A nil or empty reference names this -// broadcast, anything else names a sibling relative to it (e.g. "./source"). Call it on a -// rendition that carries one before SubscribeTrack or FetchGroup, which take a track name rather -// than a rendition: the rendition's Track, or its ID when nil. The rendition-based +// broadcast, anything else names a sibling relative to it (e.g. "./source"). epoch is the same +// rendition's Epoch: a broadcast proven to serve another instance errors instead of resolving, +// and a route without an epoch cannot prove one, so there it is best effort. Call it on a +// rendition that carries a reference before SubscribeTrack or FetchGroup, which take a track name +// rather than a rendition: the rendition's Track, or its ID when nil. The rendition-based // media.NewTrackConsumer, media.FetchGroup, audio.Subscribe, and video.Subscribe resolve both themselves. // // Errors if this broadcast came from a local producer rather than an origin, since a // standalone broadcast has no sibling to name. -func (b *BroadcastConsumer) Resolve(ctx context.Context, reference *string) (*BroadcastConsumer, error) { - inner, err := b.inner.Resolve(ctx, reference) +func (b *BroadcastConsumer) Resolve(ctx context.Context, reference *string, epoch *string) (*BroadcastConsumer, error) { + inner, err := b.inner.Resolve(ctx, reference, epoch) if err != nil { return nil, err } diff --git a/kt/moq-ffi/MIGRATE.md b/kt/moq-ffi/MIGRATE.md index 6e9627fd6a6..f9c39e69de4 100644 --- a/kt/moq-ffi/MIGRATE.md +++ b/kt/moq-ffi/MIGRATE.md @@ -4,6 +4,13 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Catalog references carry their epoch + +`MoqVideo` and `MoqAudio` gain `epoch`, the publisher instance their `broadcast` reference names; it defaults to `null`, so only positional construction changes. +`MoqBroadcastConsumer.resolve` takes the rendition's `epoch` after `reference`; pass it alongside, or `null` to resolve whichever instance answers. +Resolving, and the rendition-based consumers, throw `MoqException.Mux` for a rendition whose broadcast is proven to serve another epoch. +Regenerate the bindings for the changed records and checksums. + ### Finished tracks stay until the broadcast ends (#6157) A finished track, raw or media, now stays listed, with its catalog rendition and demand, until its broadcast closes or the new `MoqBroadcastProducer.finish()` lets go, instead of unlisting when its producer finishes or is released. diff --git a/kt/moq/MIGRATE.md b/kt/moq/MIGRATE.md index 2ff652f9212..8f7a74724ec 100644 --- a/kt/moq/MIGRATE.md +++ b/kt/moq/MIGRATE.md @@ -4,6 +4,12 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Catalog references carry their epoch + +`Video` and `Audio` gain `epoch`, the publisher instance their `broadcast` reference names; it defaults to `null`, so only positional construction changes. +`BroadcastConsumer.resolve(reference)` becomes `resolve(reference, epoch)`; pass the rendition's `epoch` alongside its `broadcast`, or `null` to resolve whichever instance answers. +Resolving, and the rendition-based consumers, throw `MoqException.Mux` for a rendition whose broadcast is proven to serve another epoch. + ### Finished tracks stay until the broadcast ends (#6157) A finished track now stays listed, with its catalog rendition and demand, until its broadcast ends or the new `BroadcastProducer.finish()` lets go. diff --git a/py/moq-ffi/MIGRATE.md b/py/moq-ffi/MIGRATE.md index a009932892c..13fb1158a89 100644 --- a/py/moq-ffi/MIGRATE.md +++ b/py/moq-ffi/MIGRATE.md @@ -4,6 +4,13 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Catalog references carry their epoch + +`MoqVideo` and `MoqAudio` gain `epoch`, the publisher instance their `broadcast` reference names; it defaults to `None`, so only positional construction changes. +`MoqBroadcastConsumer.resolve` takes the rendition's `epoch` after `reference`; pass it alongside, or `None` to resolve whichever instance answers. +Resolving, and the rendition-based consumers, raise `MoqError.Mux` for a rendition whose broadcast is proven to serve another epoch. +Rebuild or reinstall the complete wheel so its generated Python code and native library match. + ### Finished tracks stay until the broadcast ends (#6157) A finished track, raw or media, now stays listed, with its catalog rendition and demand, until its broadcast closes or the new `MoqBroadcastProducer.finish()` lets go, instead of unlisting when its producer finishes or is released. diff --git a/py/moq-rs/MIGRATE.md b/py/moq-rs/MIGRATE.md index 4175ecd3ec6..929dfdbf511 100644 --- a/py/moq-rs/MIGRATE.md +++ b/py/moq-rs/MIGRATE.md @@ -4,6 +4,12 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Catalog references carry their epoch + +`Video` and `Audio` renditions gain `epoch`, the publisher instance their `broadcast` reference names. +`BroadcastConsumer.resolve(reference)` becomes `resolve(reference, epoch)`; pass the rendition's `epoch` alongside its `broadcast`, or `None` to resolve whichever instance answers. +Resolving, and the rendition-based consumers, raise for a rendition whose broadcast is proven to serve another epoch. + ### Finished tracks stay until the broadcast ends (#6157) A finished track now stays listed, with its catalog rendition and demand, until its broadcast closes or the new `BroadcastProducer.finish()` lets go. diff --git a/py/moq-rs/moq/subscribe.py b/py/moq-rs/moq/subscribe.py index 4648d683d6a..aaa6747d4fc 100644 --- a/py/moq-rs/moq/subscribe.py +++ b/py/moq-rs/moq/subscribe.py @@ -167,19 +167,22 @@ async def fetch_group( """ return GroupConsumer(await self._inner.fetch_group(name, sequence, options)) - async def resolve(self, reference: str | None) -> "BroadcastConsumer": + async def resolve(self, reference: str | None, epoch: str | None) -> "BroadcastConsumer": """Resolve a catalog rendition's ``broadcast`` reference to the broadcast serving its track. ``reference`` is ``catalog.video[name].broadcast`` / ``catalog.audio[name].broadcast``: ``None`` or empty names this broadcast, - anything else names a sibling relative to it (e.g. ``./source``). Call it on - a rendition that carries one before :meth:`subscribe_track` or :meth:`fetch_group`, - which take a track name rather than a rendition: the rendition's ``track``, or its - ID when unset. The rendition-based consumers in the media, audio, and video - namespaces resolve both themselves. + anything else names a sibling relative to it (e.g. ``./source``). ``epoch`` is + the same rendition's ``epoch``: a broadcast proven to serve another instance + raises instead of resolving, and a route without an epoch cannot prove one, so + there it is best effort. Call it on a rendition that carries a reference before + :meth:`subscribe_track` or :meth:`fetch_group`, which take a track name rather + than a rendition: the rendition's ``track``, or its ID when unset. The + rendition-based consumers in the media, audio, and video namespaces resolve + both themselves. Raises if this broadcast came from a local producer rather than an origin, since a standalone broadcast has no sibling to name. """ - return BroadcastConsumer(await self._inner.resolve(reference)) + return BroadcastConsumer(await self._inner.resolve(reference, epoch)) diff --git a/quest/m1/README.md b/quest/m1/README.md index 002fcd7fce8..009975f0c6e 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -92,7 +92,6 @@ lite-07 stream type here. - [Rust identity enforcement](/quest/m1/catalog-identity-rs.md) - `moq-mux` refuses a redefined rendition, and every Rust publisher mints a new rendition name for a decoder identity change and updates everything else in place - [IETF takeover](/quest/m1/ietf-takeover.md) - carry the shared takeover contract through the negotiated IETF epoch extension - [Identity and recovery guide](/quest/m1/identity-guide.md) - explain pinned catalogs, lazy jobs, takeover, restart and version compatibility -- [Reference epoch bindings](/quest/m1/reference-epoch-bindings.md) - the UniFFI bindings and C ABI expose and honor a catalog reference's optional `epoch` - [Scope track priority](/quest/m1/track-priority-scope.md) - priority orders one owner's streams, sent and received, and a shared cluster session is fair across tenants - [Session send target](/quest/m1/probe-target.md) - a session probes up to the sum of its publisher reservations through whichever sender its transport has - [An evicted group is judged stale](/quest/m1/evicted-group-stale.md) - a handed-out group the cache evicted goes stale once its successor's arrival plus the budget passes, so its stalled stream resets diff --git a/quest/m1/c/README.md b/quest/m1/c/README.md index 9715f158b77..21f89be52cf 100644 --- a/quest/m1/c/README.md +++ b/quest/m1/c/README.md @@ -54,7 +54,6 @@ Decided 2026-10-20 (maintainer): m1 quests that change the C API ([exact binding timestamps](/quest/m1/binding-timestamps.md), [scope track priority](/quest/m1/track-priority-scope.md), [binding linger](/quest/m1/linger-ffi.md), -[reference epoch bindings](/quest/m1/reference-epoch-bindings.md), [Rust identity enforcement](/quest/m1/catalog-identity-rs.md), and [dynamic subscribe ranges](/quest/m1/subscribe-ranges/dynamic.md)) Require this line and land their C half on the generated package, so C users break once. diff --git a/quest/m1/reference-epoch-bindings.md b/quest/m1/reference-epoch-bindings.md deleted file mode 100644 index 7f8df4e4402..00000000000 --- a/quest/m1/reference-epoch-bindings.md +++ /dev/null @@ -1,38 +0,0 @@ -# [M] Bindings carry catalog reference epochs - -## Goal - -The UniFFI bindings and the C ABI expose a catalog reference's optional -`epoch` and honor it when resolving, so a native app gets the same guarantee -as Rust and `@moq/watch`: a broadcast proven to serve another instance fails -the rendition instead of playing it. - -## Plan - -Today `MoqVideo` and `MoqAudio` drop the field, and `MoqBroadcastConsumer::resolve`, -`decode_video`, `decode_audio` and libmoq's rendition resolution pass `None` -to `moq_mux::Source::resolve`, so they read like a reader that predates the -field: the first instance resolved, without its guarantee. - -- Add `epoch` beside `broadcast` on the binding records, and pass it from - `decode_video` and `decode_audio`. -- Decide the `resolve` shape with the maintainer: a second optional argument, - or one reference record carrying `broadcast` and `epoch`. -- Carry it through the hand-written wrappers and docs in the Cross-Package - Sync table (`rs/moq-c`, `py`, `swift`, `kt`, `go/wrapper`, `dart`, `cpp`, - `doc/lib`). - -Test a matching, mismatched and epochless reference through `moq-ffi` and -the C package, and run `just test interop --all`. - -Decided 2026-10-20 (maintainer): the C half lands on the -[generated C package](/quest/m1/c/README.md), not the frozen hand-written -ABI, so C users break once. - -## Required - -- [Generated C bindings](/quest/m1/c/README.md) - the reference `epoch` reaches C through the generated package, not the frozen hand-written ABI - -## Related - -- [Rust readers follow references](/quest/m0/broadcast-epoch/reference-announcements.md) - the following behavior the bindings inherit from `moq_mux` diff --git a/rs/moq-ffi/MIGRATE.md b/rs/moq-ffi/MIGRATE.md index 59e13b01410..68def21695b 100644 --- a/rs/moq-ffi/MIGRATE.md +++ b/rs/moq-ffi/MIGRATE.md @@ -5,6 +5,12 @@ These are the UniFFI names; each language wrapper has its own `MIGRATE.md` in it ## Unreleased +### Catalog references carry their epoch + +`MoqVideo` and `MoqAudio` gain `epoch`, the publisher instance their `broadcast` reference names. It defaults to null in every generated binding; a Rust struct literal adds `epoch: None`. +`MoqBroadcastConsumer::resolve` takes the rendition's `epoch` after `reference`; pass it alongside, or `None` to resolve whichever instance answers. +Resolving, and the rendition-based consumers, fail a rendition whose broadcast is proven to serve another epoch with `Mux`. + ### Finished tracks stay until the broadcast ends (#6157) A finished track, raw or media, now stays listed, with its catalog rendition and demand, until its broadcast closes or the new `MoqBroadcastProducer::finish` lets go, instead of unlisting when its producer finishes or is released. diff --git a/rs/moq-ffi/src/audio.rs b/rs/moq-ffi/src/audio.rs index 0cdbc0cf35c..6cc8110e20a 100644 --- a/rs/moq-ffi/src/audio.rs +++ b/rs/moq-ffi/src/audio.rs @@ -602,8 +602,9 @@ impl MoqAudioConsumer { // Reject the codec before resolving: resolving reaches the origin, which can invoke a // dynamic handler and open an upstream subscription we would immediately drop. let reference = catalog_audio.broadcast.clone(); + let epoch = catalog_audio.epoch.clone(); let cfg = audio_config(catalog_audio)?; - let resolved = broadcast.resolve_inner(reference.as_deref()).await?; + let resolved = broadcast.resolve_inner(reference.as_deref(), epoch.as_deref()).await?; let mut config = moq_audio::decode::Options::default(); config.output.format = output.format.into(); @@ -638,6 +639,7 @@ mod tests { MoqAudio { label: None, broadcast: None, + epoch: None, track: None, codec: codec.to_string(), description: None, diff --git a/rs/moq-ffi/src/consumer.rs b/rs/moq-ffi/src/consumer.rs index 17fab728081..2a5c6c3e204 100644 --- a/rs/moq-ffi/src/consumer.rs +++ b/rs/moq-ffi/src/consumer.rs @@ -216,31 +216,35 @@ impl MoqBroadcastConsumer { &self.inner } - /// Resolve a catalog rendition's `broadcast` reference to the broadcast serving its track. + /// Resolve a catalog rendition's `broadcast` reference to the broadcast serving its track, + /// refusing one proven to serve another instance than `epoch`. pub(crate) async fn resolve_inner( &self, reference: Option<&str>, + epoch: Option<&str>, ) -> Result { self.driver .watch(async { // Normalize before testing emptiness: this is a caller-supplied string, and one made only // of slashes normalizes to the empty reference, which names this broadcast. let reference = reference.map(moq_net::path::Relative::new); - - // An absent or empty reference names the catalog's own broadcast, which we already hold. - // Short-circuiting also keeps a standalone broadcast usable: the common case needs no origin. - let Some(reference) = reference.filter(|reference| !reference.is_empty()) else { - return Ok(self.inner.clone()); + let epoch: Option = epoch.map(str::parse).transpose()?; + + let Some(origin) = self.origin.clone() else { + // A standalone broadcast came through no route, so it has no epoch to prove: the + // epoch is best effort, as on an epochless route. Only its own broadcast resolves. + return match reference.filter(|reference| !reference.is_empty()) { + None => Ok(self.inner.clone()), + Some(reference) => Err(MoqError::UnresolvableBroadcast { + reason: reference.as_str().to_string(), + }), + }; }; - let origin = self.origin.clone().ok_or_else(|| MoqError::UnresolvableBroadcast { - reason: reference.as_str().to_string(), - })?; - + // Even an empty reference goes through the source, which checks the epoch against the + // catalog's own broadcast. let source = moq_mux::Source::new(origin, self.inner.clone()); - // The bindings do not expose a reference's epoch yet, so they read like an older - // reader: the first instance resolved, without the epoch's guarantee. - Ok(source.resolve(Some(&reference), None).await?) + Ok(source.resolve(reference.as_ref(), epoch.as_ref()).await?) }) .await } @@ -253,18 +257,25 @@ impl MoqBroadcastConsumer { /// Resolve a catalog rendition's `broadcast` reference to the broadcast serving its track. /// /// `reference` is [`MoqVideo::broadcast`] / [`MoqAudio::broadcast`]: absent or empty names - /// this broadcast, anything else names a sibling relative to it (e.g. `./source`). Call it on a - /// rendition that carries one before [`Self::subscribe_track`] or [`Self::fetch_group`], which - /// take a track name rather than a rendition. The rendition-based consumers - /// (`MoqMediaTrackConsumer::subscribe`, `MoqMediaGroupConsumer::fetch`, - /// `MoqVideoConsumer::subscribe`, `MoqAudioConsumer::subscribe`) resolve it themselves. + /// this broadcast, anything else names a sibling relative to it (e.g. `./source`). `epoch` is + /// the same rendition's [`MoqVideo::epoch`] / [`MoqAudio::epoch`], the publisher instance the + /// reference names: a broadcast proven to serve another one fails with `Mux` instead of + /// resolving, while a route without an epoch cannot prove one, so there it is best effort. + /// Call it on a rendition that carries a reference before [`Self::subscribe_track`] or + /// [`Self::fetch_group`], which take a track name rather than a rendition. The rendition-based + /// consumers (`MoqMediaTrackConsumer::subscribe`, `MoqMediaGroupConsumer::fetch`, + /// `MoqVideoConsumer::subscribe`, `MoqAudioConsumer::subscribe`) resolve both themselves. /// /// Errors if this broadcast came from a local producer rather than an origin, since a /// standalone broadcast has no sibling to name, and reports a sibling that exists but is not /// announced yet as unroutable rather than waiting for it (see /// [`MoqOriginConsumer::request_broadcast`](crate::origin::MoqOriginConsumer::request_broadcast)). - pub async fn resolve(&self, reference: Option) -> Result, MoqError> { - let broadcast = self.resolve_inner(reference.as_deref()).await?; + pub async fn resolve( + &self, + reference: Option, + epoch: Option, + ) -> Result, MoqError> { + let broadcast = self.resolve_inner(reference.as_deref(), epoch.as_deref()).await?; Ok(Arc::new(match self.origin.clone() { Some(origin) => Self::routed(broadcast, origin, self.driver.clone()), None => Self { diff --git a/rs/moq-ffi/src/media.rs b/rs/moq-ffi/src/media.rs index a753e094054..863d725891e 100644 --- a/rs/moq-ffi/src/media.rs +++ b/rs/moq-ffi/src/media.rs @@ -113,6 +113,11 @@ pub struct MoqVideo { /// (e.g. `./source`). Absent or empty means the catalog's broadcast. #[uniffi(default = None)] pub broadcast: Option, + /// The publisher epoch of the instance [`broadcast`](Self::broadcast) names, when the + /// catalog knows it. Resolving refuses a broadcast proven to serve another instance; absent + /// names whichever instance resolves first. + #[uniffi(default = None)] + pub epoch: Option, /// The track's name in its broadcast, when it differs from the rendition's ID. Absent means /// the ID is the track name. #[uniffi(default = None)] @@ -146,6 +151,11 @@ pub struct MoqAudio { /// (e.g. `./source`). Absent or empty means the catalog's broadcast. #[uniffi(default = None)] pub broadcast: Option, + /// The publisher epoch of the instance [`broadcast`](Self::broadcast) names, when the + /// catalog knows it. Resolving refuses a broadcast proven to serve another instance; absent + /// names whichever instance resolves first. + #[uniffi(default = None)] + pub epoch: Option, /// The track's name in its broadcast, when it differs from the rendition's ID. Absent means /// the ID is the track name. #[uniffi(default = None)] @@ -499,6 +509,7 @@ pub(crate) fn convert_catalog(catalog: &moq_mux::catalog::hang::Catalog (Option, String, MoqContainer) { - let (id, broadcast, track, container) = match self { - Self::Video { id, config } => (id, config.broadcast, config.track, config.container), - Self::Audio { id, config } => (id, config.broadcast, config.track, config.container), + /// Split into the broadcast reference and its epoch, the track name, and the container. + fn into_parts(self) -> (Option, Option, String, MoqContainer) { + let (id, broadcast, epoch, track, container) = match self { + Self::Video { id, config } => (id, config.broadcast, config.epoch, config.track, config.container), + Self::Audio { id, config } => (id, config.broadcast, config.epoch, config.track, config.container), }; - (broadcast, track.unwrap_or(id), container) + (broadcast, epoch, track.unwrap_or(id), container) } } @@ -1374,7 +1391,8 @@ impl MoqMediaTrackConsumer { /// Subscribe to a catalog rendition and decode its container. /// /// Follows the rendition's broadcast reference and track name, so a rendition served by a - /// sibling broadcast or under another track name subscribes to the right track. + /// sibling broadcast or under another track name subscribes to the right track, and fails + /// one whose broadcast is proven to serve another instance than its epoch. #[uniffi::constructor] pub async fn subscribe( broadcast: &MoqBroadcastConsumer, @@ -1384,11 +1402,11 @@ impl MoqMediaTrackConsumer { rendition, subscription, } = config; - let (reference, name, container) = rendition.into_parts(); + let (reference, epoch, name, container) = rendition.into_parts(); // Parse the container before resolving or subscribing so we don't leave a dangling // subscription if init parsing fails. let media = media_container(container)?; - let resolved = broadcast.resolve_inner(reference.as_deref()).await?; + let resolved = broadcast.resolve_inner(reference.as_deref(), epoch.as_deref()).await?; let subscription = subscription .map(moq_net::track::Subscription::try_from) .transpose()? @@ -1435,11 +1453,11 @@ impl MoqMediaGroupConsumer { sequence, options, } = config; - let (reference, name, container) = rendition.into_parts(); + let (reference, epoch, name, container) = rendition.into_parts(); // Parse the container before fetching so invalid CMAF init data does not leave a // dynamic group request waiting for a consumer that can never read it. let media = media_container(container)?; - let resolved = broadcast.resolve_inner(reference.as_deref()).await?; + let resolved = broadcast.resolve_inner(reference.as_deref(), epoch.as_deref()).await?; let options = options.map(moq_net::group::Fetch::from); let group = broadcast .driver diff --git a/rs/moq-ffi/src/test.rs b/rs/moq-ffi/src/test.rs index 8807060dced..ee5132d4e7e 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -262,6 +262,7 @@ fn rendition(id: &str, container: MoqContainer) -> MoqRendition { config: MoqVideo { label: None, broadcast: None, + epoch: None, track: None, codec: "avc1.64001f".into(), description: None, @@ -283,6 +284,7 @@ fn sibling_audio(reference: &str) -> crate::media::MoqAudio { MoqAudio { label: None, broadcast: Some(reference.to_string()), + epoch: None, track: None, codec: "opus".to_string(), description: None, @@ -2662,7 +2664,7 @@ async fn announced_broadcasts_resolve_siblings_under_the_prefix() { await_announced(&consumer, "a/source").await; - let sibling = tokio::time::timeout(TIMEOUT, broadcast.resolve(Some("./source".into()))) + let sibling = tokio::time::timeout(TIMEOUT, broadcast.resolve(Some("./source".into()), None)) .await .expect("timed out resolving the reference") .unwrap(); @@ -2739,13 +2741,13 @@ async fn resolve_rejects_a_reference_without_an_origin() { // An absent or empty reference still names this broadcast, so it needs no origin. A reference // made only of slashes normalizes to the empty one, so it must be treated the same rather than // looking like a cross-broadcast reference. - consumer.resolve(None).await.unwrap(); - consumer.resolve(Some(String::new())).await.unwrap(); - consumer.resolve(Some("/".into())).await.unwrap(); + consumer.resolve(None, None).await.unwrap(); + consumer.resolve(Some(String::new()), None).await.unwrap(); + consumer.resolve(Some("/".into()), None).await.unwrap(); // Reported in normalized form, matching `EscapingBroadcast` and moq-c: it names what the // resolver actually tried to reach, not the caller's spelling of it. - match consumer.resolve(Some("./source".into())).await { + match consumer.resolve(Some("./source".into()), None).await { Err(MoqError::UnresolvableBroadcast { reason: reference }) => assert_eq!(reference, "source"), Err(err) => panic!("wrong error for an unresolvable reference: {err:?}"), Ok(_) => panic!("a standalone broadcast cannot resolve a sibling"), @@ -2765,7 +2767,7 @@ async fn resolve_returns_a_broadcast_that_resolves_further_references() { let broadcast = await_announced(&consumer, "a/pub").await; await_announced(&consumer, "a/source").await; - let sibling = tokio::time::timeout(TIMEOUT, broadcast.resolve(Some("./source".into()))) + let sibling = tokio::time::timeout(TIMEOUT, broadcast.resolve(Some("./source".into()), None)) .await .expect("timed out resolving the reference") .unwrap(); @@ -2778,7 +2780,7 @@ async fn resolve_returns_a_broadcast_that_resolves_further_references() { .unwrap(); // And it can follow a reference of its own, back to where we started. - let back = tokio::time::timeout(TIMEOUT, sibling.resolve(Some("./pub".into()))) + let back = tokio::time::timeout(TIMEOUT, sibling.resolve(Some("./pub".into()), None)) .await .expect("timed out resolving back") .unwrap(); @@ -2788,6 +2790,85 @@ async fn resolve_returns_a_broadcast_that_resolves_further_references() { source.close().unwrap(); } +/// A reference's epoch names the instance it expects: a broadcast proven to serve another fails +/// the rendition, while an epochless reference, or a route that cannot prove its instance, reads +/// whichever instance resolves. +#[tokio::test] +async fn resolve_honors_the_reference_epoch() { + async fn resolve( + broadcast: &MoqBroadcastConsumer, + reference: &str, + epoch: Option<&str>, + ) -> Result, MoqError> { + tokio::time::timeout( + TIMEOUT, + broadcast.resolve(Some(reference.into()), epoch.map(Into::into)), + ) + .await + .expect("timed out resolving the reference") + } + + let origin = MoqOriginProducer::new(MoqOriginConfig::default()); + let consumer = origin.consume(); + let served = moq_mint_epoch(); + let other = moq_mint_epoch(); + let route = MoqRoute { + epoch: Some(served.clone()), + ..Default::default() + }; + + let catalog = origin.create_broadcast("a/pub".into()).unwrap(); + catalog.announce(route.clone()).unwrap(); + let source = origin.create_broadcast("a/source".into()).unwrap(); + source.announce(route).unwrap(); + let _video = source.publish_track("video".into(), None).unwrap(); + let plain = create_announced(&origin, "a/plain"); + + let broadcast = await_announced(&consumer, "a/pub").await; + await_announced(&consumer, "a/source").await; + await_announced(&consumer, "a/plain").await; + + let matching = resolve(&broadcast, "./source", Some(&served)).await.unwrap(); + assert_eq!(matching.inner().info().path.as_str(), "a/source"); + resolve(&broadcast, "./source", None).await.unwrap(); + resolve(&broadcast, "./plain", Some(&other)).await.unwrap(); + + assert!(matches!( + resolve(&broadcast, "./source", Some(&other)).await, + Err(MoqError::Mux { reason }) if reason.contains("serves epoch") + )); + // Without a broadcast, the epoch names the catalog's own instance. + resolve(&broadcast, "", Some(&served)).await.unwrap(); + assert!(matches!( + resolve(&broadcast, "", Some(&other)).await, + Err(MoqError::Mux { reason }) if reason.contains("serves epoch") + )); + assert!(matches!( + resolve(&broadcast, "./source", Some("not-an-epoch")).await, + Err(MoqError::InvalidEpoch { .. }) + )); + + // The rendition-based consumers read the epoch off the rendition. + let mut mismatched = rendition("video", MoqContainer::Legacy); + let MoqRendition::Video { config, .. } = &mut mismatched else { + unreachable!() + }; + config.broadcast = Some("./source".into()); + config.epoch = Some(other); + let config = MoqMediaTrackConfig { + rendition: mismatched, + subscription: None, + }; + let subscribed = tokio::time::timeout(TIMEOUT, MoqMediaTrackConsumer::subscribe(&broadcast, config)) + .await + .expect("timed out subscribing to the rendition"); + assert!(matches!(subscribed, Err(MoqError::Mux { reason }) if reason.contains("serves epoch"))); + + catalog.close().unwrap(); + source.close().unwrap(); + plain.close().unwrap(); +} + #[tokio::test] async fn announce_and_unannounce_toggles_discovery() { let origin = MoqOriginProducer::new(MoqOriginConfig::default()); diff --git a/rs/moq-ffi/src/video.rs b/rs/moq-ffi/src/video.rs index 82d8ab4d86c..36a18a097c3 100644 --- a/rs/moq-ffi/src/video.rs +++ b/rs/moq-ffi/src/video.rs @@ -954,10 +954,11 @@ impl MoqVideoConsumer { // Reject the codec and output before resolving: resolving reaches the origin, which can // invoke a dynamic handler and open an upstream subscription we would immediately drop. let reference = catalog_video.broadcast.clone(); + let epoch = catalog_video.epoch.clone(); let cfg = video_config(catalog_video)?; let mut options = moq_video::decode::Options::default(); options.decoder.output = decoder_output(output.surface, HAS_SURFACE)?; - let resolved = broadcast.resolve_inner(reference.as_deref()).await?; + let resolved = broadcast.resolve_inner(reference.as_deref(), epoch.as_deref()).await?; options.decoder.scale_hint = output.resize.map(|size| moq_video::Size::new(size.width, size.height)); options.max_delay = output @@ -985,6 +986,7 @@ mod decode_tests { MoqVideo { label: None, broadcast: None, + epoch: None, track: None, codec: codec.to_string(), description: None, diff --git a/swift/MIGRATE.md b/swift/MIGRATE.md index 044aa7fa273..f69cfa3596d 100644 --- a/swift/MIGRATE.md +++ b/swift/MIGRATE.md @@ -4,6 +4,12 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Catalog references carry their epoch + +`Media.Video` and `Media.Audio` gain `epoch`, the publisher instance their `broadcast` reference names. +`BroadcastConsumer.resolve(_:)` becomes `resolve(_:epoch:)`; pass the rendition's `epoch` alongside its `broadcast`, or `nil` to resolve whichever instance answers. +Resolving, and the rendition-based consumers, throw for a rendition whose broadcast is proven to serve another epoch. + ### Finished tracks stay until the broadcast ends (#6157) A finished track now stays listed, with its catalog rendition and demand, until its broadcast closes or the new `BroadcastProducer.finish()` lets go. diff --git a/swift/Sources/Moq/Broadcast.swift b/swift/Sources/Moq/Broadcast.swift index 5c2d9f866c3..8c8cc5958fd 100644 --- a/swift/Sources/Moq/Broadcast.swift +++ b/swift/Sources/Moq/Broadcast.swift @@ -29,16 +29,18 @@ public final class BroadcastConsumer: Sendable { /// Resolve a catalog rendition's `broadcast` reference to the broadcast serving its track. /// /// `reference` is `Media.Video.broadcast` / `Media.Audio.broadcast`: `nil` or empty names this - /// broadcast, anything else names a sibling relative to it (e.g. `./source`). Call it on a - /// rendition that carries one before `subscribeTrack` or `fetchGroup`, which take a track name - /// rather than a rendition: the rendition's `track`, or its ID when `nil`. The - /// rendition-based `Media.TrackConsumer.subscribe`, `Media.GroupConsumer.fetch`, + /// broadcast, anything else names a sibling relative to it (e.g. `./source`). `epoch` is the + /// same rendition's `epoch`: a broadcast proven to serve another instance throws instead of + /// resolving, and a route without an epoch cannot prove one, so there it is best effort. Call + /// it on a rendition that carries a reference before `subscribeTrack` or `fetchGroup`, which + /// take a track name rather than a rendition: the rendition's `track`, or its ID when `nil`. + /// The rendition-based `Media.TrackConsumer.subscribe`, `Media.GroupConsumer.fetch`, /// `Audio.Consumer.subscribe`, and `Video.Consumer.subscribe` resolve both themselves. /// /// Throws if this broadcast came from a local producer rather than an origin, since a /// standalone broadcast has no sibling to name. - public func resolve(_ reference: String?) async throws -> BroadcastConsumer { - BroadcastConsumer(try await ffi.resolve(reference: reference)) + public func resolve(_ reference: String?, epoch: String?) async throws -> BroadcastConsumer { + BroadcastConsumer(try await ffi.resolve(reference: reference, epoch: epoch)) } } diff --git a/swift/ffi/MIGRATE.md b/swift/ffi/MIGRATE.md index 3552e06292f..f52e36a3a93 100644 --- a/swift/ffi/MIGRATE.md +++ b/swift/ffi/MIGRATE.md @@ -4,6 +4,13 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Catalog references carry their epoch + +`MoqVideo` and `MoqAudio` gain `epoch`, the publisher instance their `broadcast` reference names; the memberwise initializer defaults it to `nil`. +`MoqBroadcastConsumer.resolve(reference:)` requires `epoch:` too; pass the rendition's `epoch` alongside, or `nil` to resolve whichever instance answers. +Resolving, and the rendition-based consumers, throw `MoqError.Mux` for a rendition whose broadcast is proven to serve another epoch. +Regenerate the Swift sources and rebuild the matching XCFramework, then rebuild callers. + ### Finished tracks stay until the broadcast ends (#6157) A finished track, raw or media, now stays listed, with its catalog rendition and demand, until its broadcast closes or the new `MoqBroadcastProducer.finish()` lets go, instead of unlisting when its producer finishes or is released.