From cb5c5b3b46c8face7896921ec1c5f9455d36dd1e Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 21 Oct 2026 20:50:45 -0700 Subject: [PATCH 1/3] quest: claim m1/reference-epoch-bindings From edc028a8c4e93f35f5b82e9eb3d724ca8a378b92 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 21 Oct 2026 21:11:55 -0700 Subject: [PATCH 2/3] feat(ffi)!: bindings carry and honor catalog reference epochs MoqVideo and MoqAudio expose the rendition's optional `epoch`, and MoqBroadcastConsumer::resolve takes it beside `reference`, mirroring moq_mux::Source::resolve and @moq/watch. The rendition-based consumers and libmoq's rendition resolution pass it through, so a broadcast proven to serve another publisher instance fails the rendition instead of playing. Co-Authored-By: Claude Opus 5.5 --- dart/moq/MIGRATE.md | 6 ++ dart/moq_ffi/MIGRATE.md | 6 ++ dart/moq_ffi/lib/src/moq.dart | 46 ++++++++++++-- dart/moq_ffi/test/leak_test.dart | 2 +- go/ffi/MIGRATE.md | 7 ++ go/wrapper/MIGRATE.md | 6 ++ go/wrapper/subscribe.go | 12 ++-- py/moq-rs/MIGRATE.md | 6 ++ py/moq-rs/moq/subscribe.py | 17 +++-- quest/m1/README.md | 1 - quest/m1/reference-epoch-bindings.md | 30 --------- rs/moq-c/MIGRATE.md | 4 ++ rs/moq-c/src/consume.rs | 26 +++++--- rs/moq-c/src/test.rs | 86 ++++++++++++++++++------- rs/moq-ffi/MIGRATE.md | 6 ++ rs/moq-ffi/src/audio.rs | 4 +- rs/moq-ffi/src/consumer.rs | 51 +++++++++------ rs/moq-ffi/src/media.rs | 40 ++++++++---- rs/moq-ffi/src/test.rs | 95 ++++++++++++++++++++++++++-- rs/moq-ffi/src/video.rs | 4 +- swift/MIGRATE.md | 6 ++ swift/Sources/Moq/Broadcast.swift | 14 ++-- 22 files changed, 346 insertions(+), 129 deletions(-) delete mode 100644 quest/m1/reference-epoch-bindings.md 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/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 b3b330fc544..e0d4812048f 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -83,7 +83,6 @@ lite-07 stream type here. - [Announcement takeover](/quest/m1/announce-takeover.md) - a new independent route explicitly continues instances served through its predecessor, with shared Rust/JS semantics and lite-07 wire - [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` - [Generated C bindings](/quest/m1/c/README.md) - C generated from moq-ffi ships as `moq-c` 0.8.0 and replaces the hand-written libmoq - [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 diff --git a/quest/m1/reference-epoch-bindings.md b/quest/m1/reference-epoch-bindings.md deleted file mode 100644 index 3e426407772..00000000000 --- a/quest/m1/reference-epoch-bindings.md +++ /dev/null @@ -1,30 +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 -libmoq, and run `just test interop --all`. - -## 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-c/MIGRATE.md b/rs/moq-c/MIGRATE.md index 45a2f272283..ccb227fd001 100644 --- a/rs/moq-c/MIGRATE.md +++ b/rs/moq-c/MIGRATE.md @@ -4,6 +4,10 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Catalog references honor their epoch + +`moq_consume_video` and `moq_consume_audio` now fail a rendition whose catalog reference names an epoch its broadcast is proven not to serve, with `MOQ_ERROR_MUX`, instead of playing another publisher instance. + ### Finished tracks stay until the broadcast ends (#6157) `moq_publish_track_finish`, `moq_publish_media_finish`, `moq_publish_container_finish`, and the encoder finishes now release the handle while the broadcast keeps the finished track listed, with its catalog rendition and demand, until `moq_publish_close` or the new `moq_publish_finish_close`. diff --git a/rs/moq-c/src/consume.rs b/rs/moq-c/src/consume.rs index 8e46e7f44c5..fa264d25403 100644 --- a/rs/moq-c/src/consume.rs +++ b/rs/moq-c/src/consume.rs @@ -107,28 +107,33 @@ struct ConsumeBroadcast { origin: Option, } -/// The broadcast serving a rendition, honoring its catalog `broadcast` reference. +/// The broadcast serving a rendition, honoring its catalog `broadcast` reference and `epoch`. /// /// An absent or empty reference names the catalog's own broadcast, which the caller already /// holds; anything else resolves against that broadcast's path through the origin, which -/// deduplicates the subscription the catalog itself already holds. Awaited inside the track -/// task, never under the state lock, so `origin` is cloned out rather than borrowed. +/// deduplicates the subscription the catalog itself already holds. Either way a broadcast proven +/// to serve another instance than `epoch` fails the rendition. Awaited inside the track task, +/// never under the state lock, so `origin` is cloned out rather than borrowed. async fn resolve( broadcast: moq_net::broadcast::Consumer, origin: Option, reference: Option, + epoch: Option, ) -> Result { - let Some(reference) = reference.filter(|reference| !reference.is_empty()) else { - return Ok(broadcast); + let Some(origin) = origin 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(broadcast), + Some(reference) => Err(Error::UnresolvableBroadcast(reference.as_str().to_string())), + }; }; - let origin = origin.ok_or_else(|| Error::UnresolvableBroadcast(reference.as_str().to_string()))?; let source = moq_mux::Source::new(origin.inner, broadcast); - // The C ABI does not expose a reference's epoch yet, so it reads like an older reader: the - // first instance resolved, without the epoch's guarantee. + let reference = reference.as_ref().map(|reference| reference.borrow()); origin .driver - .watch(async { Ok(source.resolve(Some(&reference.borrow()), None).await?) }) + .watch(async { Ok(source.resolve(reference.as_ref(), epoch.as_ref()).await?) }) .await } @@ -487,6 +492,7 @@ impl Consume { // The rendition may live in a sibling broadcast, so resolve its reference rather than // assuming the catalog's own broadcast serves the track. let reference = config.broadcast().cloned(); + let epoch = config.epoch().cloned(); let broadcast = consume.broadcast.clone(); let origin = consume.origin.clone(); let driver = origin.as_ref().map(|origin| origin.driver.clone()).unwrap_or_default(); @@ -498,7 +504,7 @@ impl Consume { |close| async move { driver .watch(async move { - let broadcast = resolve(broadcast, origin, reference).await?; + let broadcast = resolve(broadcast, origin, reference, epoch).await?; let track = broadcast .track(&name)? .subscribe( diff --git a/rs/moq-c/src/test.rs b/rs/moq-c/src/test.rs index 4f75c26de93..b7edd60a3f8 100644 --- a/rs/moq-c/src/test.rs +++ b/rs/moq-c/src/test.rs @@ -3506,10 +3506,44 @@ fn consume_announced_local() { /// catalog's own broadcast: `NotFound`, or a same-named local track with mismatched metadata. #[test] fn consume_audio_follows_a_sibling_broadcast_reference() { + consume_sibling_audio(None, None).expect("the sibling broadcast's frame should arrive"); +} + +/// A reference's epoch names the sibling instance it expects: one proven to serve another fails +/// the rendition, while an epochless reference, or a route that cannot prove its instance, reads +/// whichever instance resolves. +#[test] +fn consume_audio_honors_the_reference_epoch() { + let served = moq_net::Epoch::mint(); + let other = moq_net::Epoch::mint(); + consume_sibling_audio(Some(served.clone()), Some(served.clone())).expect("a matching epoch resolves"); + consume_sibling_audio(Some(served.clone()), None).expect("an epochless reference resolves"); + consume_sibling_audio(None, Some(other.clone())).expect("an epochless route is best effort"); + assert_eq!( + consume_sibling_audio(Some(served), Some(other)), + Err(crate::error::MOQ_ERROR_MUX), + "a sibling serving another instance fails the rendition" + ); +} + +/// Consume an `a/pub` catalog rendition referencing `./source` under `epoch`, where `a/source` +/// serves the track under `served`: whether the sibling's frame arrived, or the code that failed it. +fn consume_sibling_audio(served: Option, epoch: Option) -> Result<(), i32> { let origin = id(moq_origin_create()); - // Only the sibling serves the track; the catalog broadcast just describes it. - let source = publish_broadcast(origin, b"a/source"); + // Only the sibling serves the track; the catalog broadcast just describes it. The C route has no + // epoch, so announce one here. + let path = b"a/source"; + let source = id(unsafe { moq_origin_create_broadcast(origin, path.as_ptr().cast(), path.len()) }); + let route = moq_net::origin::Route::default(); + let route = match served { + Some(served) => route.with_epoch(served), + None => route, + }; + State::lock() + .publish + .announce(Id::try_from(source).unwrap(), route) + .unwrap(); let init = opus_head(); let media = id(publish_audio( source, @@ -3553,14 +3587,10 @@ fn consume_audio_follows_a_sibling_broadcast_reference() { { let mut state = State::lock(); let catalog = state.publish.target(Id::try_from(broadcast).unwrap()).unwrap().catalog; - catalog - .modify() - .unwrap() - .audio - .renditions - .get_mut(&name) - .unwrap() - .broadcast = Some(moq_net::path::Relative::new("./source").into_owned()); + let mut catalog = catalog.modify().unwrap(); + let rendition = catalog.audio.renditions.get_mut(&name).unwrap(); + rendition.broadcast = Some(moq_net::path::Relative::new("./source").into_owned()); + rendition.epoch = epoch; } let consume = request_broadcast(origin, b"a/pub"); @@ -3579,22 +3609,29 @@ fn consume_audio_follows_a_sibling_broadcast_reference() { 0 ); - let frame_id = id(frame_cb.recv()); - let mut frame = moq_frame { - payload: std::ptr::null(), - payload_size: 0, - timestamp_us: 0, - timestamp_present: false, - keyframe: false, + let code = frame_cb.recv(); + let result = if code < 0 { + Err(code) + } else { + let frame_id = id(code); + let mut frame = moq_frame { + payload: std::ptr::null(), + payload_size: 0, + timestamp_us: 0, + timestamp_present: false, + keyframe: false, + }; + assert_eq!(unsafe { moq_consume_frame(frame_id, &mut frame) }, 0); + let received = unsafe { std::slice::from_raw_parts(frame.payload, frame.payload_size) }; + assert_eq!(received, payload, "the sibling broadcast's frame should arrive"); + assert_eq!(frame.timestamp_us, timestamp_us); + + assert_eq!(moq_consume_frame_free(frame_id), 0); + assert_eq!(moq_consume_audio_cancel(track), 0); + assert_eq!(frame_cb.recv_terminal(), 0, "audio close delivers terminal 0"); + Ok(()) }; - assert_eq!(unsafe { moq_consume_frame(frame_id, &mut frame) }, 0); - let received = unsafe { std::slice::from_raw_parts(frame.payload, frame.payload_size) }; - assert_eq!(received, payload, "the sibling broadcast's frame should arrive"); - assert_eq!(frame.timestamp_us, timestamp_us); - assert_eq!(moq_consume_frame_free(frame_id), 0); - assert_eq!(moq_consume_audio_cancel(track), 0); - assert_eq!(frame_cb.recv_terminal(), 0, "audio close delivers terminal 0"); assert_eq!(moq_consume_catalog_free(catalog_id), 0); assert_eq!(moq_consume_catalog_cancel(catalog_task), 0); assert_eq!(catalog_cb.recv_terminal(), 0, "catalog close delivers terminal 0"); @@ -3603,6 +3640,7 @@ fn consume_audio_follows_a_sibling_broadcast_reference() { assert_eq!(moq_publish_close(broadcast), 0); assert_eq!(moq_publish_close(source), 0); assert_eq!(moq_origin_close(origin), 0); + result } #[test] 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 87240e05c68..d0be90677b0 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, @@ -2688,7 +2690,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(); @@ -2765,13 +2767,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"), @@ -2791,7 +2793,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(); @@ -2804,7 +2806,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(); @@ -2814,6 +2816,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 7d58a57d27e..0b2ccb1d750 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)) } } From c77f56f634e29f10d82667e5a2b265d3486a6981 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 21 Oct 2026 22:48:46 -0700 Subject: [PATCH 3/3] docs: migration notes for the generated Kotlin, Python, Swift, and C++ packages Co-Authored-By: Claude Opus 5.5 --- cpp/moq/MIGRATE.md | 6 ++++++ kt/moq-ffi/MIGRATE.md | 7 +++++++ kt/moq/MIGRATE.md | 6 ++++++ py/moq-ffi/MIGRATE.md | 7 +++++++ swift/ffi/MIGRATE.md | 7 +++++++ 5 files changed, 33 insertions(+) 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/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/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.