From 52c646237c4ebaedf58a5e4c1dd958a3d7cbd3b0 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 4 Oct 2026 20:43:30 -0700 Subject: [PATCH 1/8] quest: claim transcode-group-start Co-Authored-By: Claude Opus 5.5 From c5bfd1a363807bf0fd98e54960400a8c5db5dfde Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 4 Oct 2026 20:53:01 -0700 Subject: [PATCH 2/8] fix(transcode): refuse a fetch that starts mid-group The rung's fetch handler transcoded the whole source group into a group accepted at the requested frame index, so a mid-group FETCH got frame 0 labeled as frame M. A tail from this encoder cannot continue a head another instance produced anyway, so refuse it with NotFound. Pin two instances fed one source publishing the same catalog and groups, and record in the quest why the subscription half needs moq-net. Co-Authored-By: Claude Opus 5.5 --- quest/m1/transcode-group-start.md | 27 +++++++ rs/moq-transcode/src/lib.rs | 124 ++++++++++++++++++++++++++++++ rs/moq-transcode/src/rung.rs | 18 ++++- 3 files changed, 168 insertions(+), 1 deletion(-) diff --git a/quest/m1/transcode-group-start.md b/quest/m1/transcode-group-start.md index 021248806db..3e58e7e2064 100644 --- a/quest/m1/transcode-group-start.md +++ b/quest/m1/transcode-group-start.md @@ -22,6 +22,33 @@ config. Public API: none. Wire: none. +### Findings + +Done: the rung's fetch handler refuses a mid-group FETCH (it used to write +the whole group at the requested index), and a test pins two instances +publishing the same catalog and groups from one source. + +Open, and not reachable from moq-transcode alone: + +- moq-net serves subscriptions and cached fetches from the track cache, so a + mid-group start is positioned into whatever group N the transcoder holds + (`position_group` in `lite/publisher.rs`, the cache path of + `fetch_group`). The handler only sees cache misses. +- The relay does not ask the new route for (N, M) anyway. `resume.rs` + subscribes the new copy from (N, 0) and continues the in-flight group from + that copy's group N at frame M, which is exactly the splice. The draft + and `resume.rs` assume every route's frames are identical; two encoders' + are only group-aligned. +- Rung names are minted per process (`video/120p.2` after a resize, see + `catalog::Names`), so an instance that started after a resize names the + same picture differently, and reuses a name another instance finished. +- With `encode::Kind::Auto` the probed catalog entry (profile, level) depends + on which backend the host has. + +Which way to close the splice is a maintainer decision: a track property that +limits route moves to group boundaries, relays moving routes only at group +boundaries, or giving each worker its own path. + ## Related - [Wildcard](/quest/m0/wildcard/README.md) - a double claim's two workers at one path are settled by interchangeable output diff --git a/rs/moq-transcode/src/lib.rs b/rs/moq-transcode/src/lib.rs index 2fbbd371cba..7dd650ba8c4 100644 --- a/rs/moq-transcode/src/lib.rs +++ b/rs/moq-transcode/src/lib.rs @@ -1271,6 +1271,130 @@ mod tests { transcoder.abort(); } + /// A fetch that starts partway through a group is refused rather than served. + /// Another instance at the same path encodes that group into different bytes, + /// so the tail this one would produce cannot continue the head a reader holds. + /// It is the relay's cue to give up on the group and move on to the next. + #[tokio::test] + async fn a_mid_group_fetch_is_refused() { + let source = source_catalog(320, 240); + // Serve any source group on demand, so a fetch that is not refused has + // something to transcode and resolves. + let source_fetches = source._track.dynamic(); + let server = tokio::spawn(async move { + while let Ok(request) = source_fetches.requested_group().await { + let mut group = request.accept(None).unwrap(); + write_keyframe(&mut group); + group.finish().unwrap(); + } + }); + + let config = Config { + ladder: Ladder::new([Rung::new(120, moq_net::bandwidth::Rate::from_bps(100_000))]).unwrap(), + encoder: moq_video::encode::Kind::Software, + decoder: moq_video::decode::Kind::Software, + source: None, + ..Default::default() + }; + let output = moq_net::broadcast::Info::default().produce(); + let consumer = output.consume(); + let transcoder = tokio::spawn(run(source.broadcast.consume(), output, config)); + + let catalog = loop { + match consumer.track(hang::Catalog::DEFAULT_NAME) { + Ok(track) => break track, + Err(moq_net::Error::NotFound) => tokio::task::yield_now().await, + Err(err) => panic!("catalog track: {err}"), + } + }; + let mut catalogs = moq_mux::catalog::hang::Consumer::<()>::new(catalog.subscribe(None).await.unwrap()); + await_catalog(&mut catalogs, |snapshot| { + snapshot.video.renditions.contains_key("video/120p") + }) + .await; + + // The source publishes no live groups, so group 7 is a cache miss that + // reaches the rung's fetch handler. + let rung = consumer.track("video/120p").unwrap(); + rung.query().await.unwrap(); + + let partial = rung + .fetch_group(7, moq_net::group::Fetch::default().with_frame_start(2)) + .await; + match partial { + Err(moq_net::Error::NotFound) => {} + Err(err) => panic!("expected a NotFound refusal, got {err}"), + Ok(_) => panic!("served a fetch that starts mid-group"), + } + + // The whole group still serves. + let mut whole = rung.fetch_group(7, None).await.unwrap(); + while whole.read_frame().await.unwrap().is_some() {} + assert!(whole.finished().await.unwrap() > 0, "the whole group had no frames"); + + server.abort(); + transcoder.abort(); + } + + /// Two transcoders fed the same source are one broadcast: the same catalog, + /// and groups that mirror the source's sequences and timestamps. That is what + /// lets a relay move a subscription between them at a group boundary. + #[tokio::test] + async fn two_instances_publish_the_same_broadcast() { + let source = source_broadcast(2, 5); + let config = Config { + ladder: Ladder::new([Rung::new(120, moq_net::bandwidth::Rate::from_bps(100_000))]).unwrap(), + encoder: moq_video::encode::Kind::Software, + decoder: moq_video::decode::Kind::Software, + source: None, + ..Default::default() + }; + + let mut instances = Vec::new(); + for _ in 0..2 { + let output = moq_net::broadcast::Info::default().produce(); + let consumer = output.consume(); + let transcoder = tokio::spawn(run(source.broadcast.consume(), output, config.clone())); + + let track = loop { + match consumer.track(hang::Catalog::DEFAULT_NAME) { + Ok(track) => break track, + Err(moq_net::Error::NotFound) => tokio::task::yield_now().await, + Err(err) => panic!("catalog track: {err}"), + } + }; + let mut catalogs = moq_mux::catalog::hang::Consumer::<()>::new(track.subscribe(None).await.unwrap()); + let catalog = await_catalog(&mut catalogs, |snapshot| { + snapshot.video.renditions.contains_key("video/120p") + }) + .await; + + let rung = consumer.track("video/120p").unwrap(); + let mut groups = Vec::new(); + for sequence in 0..2 { + let mut fetched = rung.fetch_group(sequence, None).await.unwrap(); + let mut timestamps = Vec::new(); + while let Some(payload) = fetched.read_frame().await.unwrap() { + let frame = hang::container::Frame::decode(payload.payload).unwrap(); + timestamps.push(frame.timestamp.as_micros()); + } + groups.push((fetched.sequence, timestamps)); + } + + instances.push((catalog, groups)); + transcoder.abort(); + } + + let (first, second) = (&instances[0], &instances[1]); + assert_eq!(first.0, second.0, "the two instances published different catalogs"); + assert_eq!(first.1, second.1, "the two instances published different groups"); + // Mirrored from the source, not numbered by either instance. + let expected: Vec<_> = (0..2u64) + .map(|sequence| (sequence, (0..5).map(|i| (sequence * 5 + i) as u128 * 33_333).collect())) + .collect(); + assert_eq!(first.1, expected); + } + /// A source whose codec description changes rebuilds the shared decode, so /// every rung retires with it. The picture may not have moved at all, so shape /// alone would hand the replacements the names that just ended. They have to be diff --git a/rs/moq-transcode/src/rung.rs b/rs/moq-transcode/src/rung.rs index 469ec27fa33..e7e995b3c47 100644 --- a/rs/moq-transcode/src/rung.rs +++ b/rs/moq-transcode/src/rung.rs @@ -7,7 +7,9 @@ //! source track (mirroring the aggregate subscription) and transcodes group //! for group until the track goes `unused` again. //! - A fetch of a specific group (`requested_group`) fetches that same group -//! from the source and transcodes just that group with a fresh encoder. +//! from the source and transcodes just that group with a fresh encoder. A +//! fetch that starts mid-group is refused: the frames are only valid after +//! the head this encoder produced. //! //! Output groups mirror the source group sequence numbers 1:1, so a fetch for //! output group N maps to source group N and a player switching renditions @@ -481,6 +483,20 @@ fn spawn_fetch( /// "the handler vanished" and hides the actual decode/encode/source failure from /// the waiting consumer. async fn fetch(rung: Rung, request: moq_net::group::Request) -> Result<(), Error> { + // Another instance encodes the same source group into different bytes, so a + // tail from this encoder cannot continue a head someone else produced. A + // partial group is not ours to serve; refuse it so the reader moves on to the + // next group boundary instead of decoding a splice. + if request.frame_start() != 0 { + tracing::debug!( + sequence = request.sequence(), + frame = request.frame_start(), + "refusing a fetch that starts mid-group" + ); + request.reject(moq_net::Error::NotFound); + return Ok(()); + } + let options = moq_net::group::Fetch::default().with_priority(request.priority()); let mut source = match rung.source.fetch_group(request.sequence(), options).await { Ok(source) => source, From d2833e736025410facd342d4ea83b90e2b3824ab Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 4 Oct 2026 21:38:10 -0700 Subject: [PATCH 3/8] feat(net): let a track serve only whole groups A transcoder cannot resume a group deterministically, so it must never serve one partway through. moq-net answers subscriptions and cached fetches before the transcoder sees them, so add track::Info::whole_groups, a local serving policy (not in TRACK_INFO): a subscription starting mid-group skips to the next group on lite and IETF, and a mid-group fetch is refused with NotFound, cached, uncached, or queued before accept. moq-transcode accepts rung tracks with it, replacing the handler check, and the quest records the maintainer's decision. Co-Authored-By: Claude Opus 5.5 --- quest/m1/transcode-group-start.md | 56 ++++++++---------- rs/moq-net/src/ietf/publisher.rs | 53 +++++++++++++++++ rs/moq-net/src/lite/publisher.rs | 93 +++++++++++++++++++++++++++++- rs/moq-net/src/model/group.rs | 6 ++ rs/moq-net/src/model/track.rs | 94 ++++++++++++++++++++++++++++++- rs/moq-transcode/src/lib.rs | 6 +- rs/moq-transcode/src/rung.rs | 30 ++++------ 7 files changed, 281 insertions(+), 57 deletions(-) diff --git a/quest/m1/transcode-group-start.md b/quest/m1/transcode-group-start.md index 3e58e7e2064..d0136537a65 100644 --- a/quest/m1/transcode-group-start.md +++ b/quest/m1/transcode-group-start.md @@ -12,42 +12,30 @@ config. ## Plan +- Decided 2026-10-04 by the maintainer: the fix is transcode-only and relay + resume stays as it is. A transcoder cannot resume a group + deterministically, so it never serves a partial group: a subscription + starting at (N, M>0) skips group N for that subscriber and starts at + (N+1, 0), and a mid-group FETCH is refused. +- moq-net answers subscriptions and cached fetches from the track cache + before the transcoder sees them, so the refusal needs a moq-net hook. A + `track::Info::whole_groups` flag is the hook: a local serving policy, not + carried in TRACK_INFO, so no wire change and relays are unaffected. Where + it lives (`Info` field, a `Producer` setter, or a per-group flag) is still + open on the PR. - The lite draft already lets a publisher skip a group it cannot serve from the requested frame and resolve to a later one, so no wire change. -- Output groups already mirror the source's sequences (`rung.rs`). Keep that, - and check that nothing per-process (start time, random ids, encoder - defaults) leaks into the catalog. -- Tests: a subscription and a FETCH that start mid-group, and two instances - fed the same source that publish the same catalog and group sequences. - -Public API: none. Wire: none. - -### Findings - -Done: the rung's fetch handler refuses a mid-group FETCH (it used to write -the whole group at the requested index), and a test pins two instances -publishing the same catalog and groups from one source. - -Open, and not reachable from moq-transcode alone: - -- moq-net serves subscriptions and cached fetches from the track cache, so a - mid-group start is positioned into whatever group N the transcoder holds - (`position_group` in `lite/publisher.rs`, the cache path of - `fetch_group`). The handler only sees cache misses. -- The relay does not ask the new route for (N, M) anyway. `resume.rs` - subscribes the new copy from (N, 0) and continues the in-flight group from - that copy's group N at frame M, which is exactly the splice. The draft - and `resume.rs` assume every route's frames are identical; two encoders' - are only group-aligned. -- Rung names are minted per process (`video/120p.2` after a resize, see - `catalog::Names`), so an instance that started after a resize names the - same picture differently, and reuses a name another instance finished. -- With `encode::Kind::Auto` the probed catalog entry (profile, level) depends - on which backend the host has. - -Which way to close the splice is a maintainer decision: a track property that -limits route moves to group boundaries, relays moving routes only at group -boundaries, or giving each worker its own path. +- Output groups already mirror the source's sequences (`rung.rs`), pinned by + a test of two instances fed one source. +- The maintainer wants deterministic transcodes, aligned with moq.pro's + [wildcard transcode plan](https://github.com/moq-dev/moq.pro/blob/main/quest/m2/wildcard/transcode.md). + Two per-process leaks into the catalog are queued as follow-up quests, not + done here: rung names minted per process (`video/120p.2` after a resize, + `catalog::Names`), and the probed catalog entry depending on the host's + backend under `encode::Kind::Auto` (pin the encoder kind). + +Public API: `moq_net::track::Info::whole_groups` and `with_whole_groups`. +Wire: none. ## Related diff --git a/rs/moq-net/src/ietf/publisher.rs b/rs/moq-net/src/ietf/publisher.rs index 856fca169b6..ab0388dad31 100644 --- a/rs/moq-net/src/ietf/publisher.rs +++ b/rs/moq-net/src/ietf/publisher.rs @@ -2522,6 +2522,12 @@ impl TrackServe { if slice.until.is_some_and(|until| until <= slice.skip) { continue; } + // A whole-groups track never serves a tail: the subscription starts at + // the next group instead. + if slice.skip > 0 && group.whole_groups() { + tracing::debug!(subscribe = %self.request_id, sequence, "skipping a partial start group"); + continue; + } let msg = ietf::GroupHeader { track_alias: self.request_id.0, @@ -3248,6 +3254,53 @@ mod subscribe_cursor_test { // `GroupServe` sets the priority once per stream it opens, so this counts groups served. assert_eq!(log.priorities().len(), 1, "only group 3 should have been served"); } + + /// A subscription asking a whole-groups track for the tail of a group skips that group + /// and starts at the next one, even though the group holds the requested object. + #[tokio::test] + async fn a_whole_groups_track_starts_a_partial_subscription_at_the_next_group() { + let log = Log::default(); + let session = SinkSession::new(log.clone()); + + let info = track::Info::default().with_whole_groups(true); + let track = track::Producer::new(std::sync::Arc::new(crate::broadcast::Info::default()), "video", info); + let start = track::Position { group: 5, frame: 2 }; + let subscriber = track.subscribe(track::Subscription::default().with_start(start)); + + let mut serve = TrackServe::new( + session, + subscriber, + RequestId(1), + Version::Draft14, + ServeRange { + start: Some(Location { group: 5, object: 2 }), + end: None, + }, + Some(Timescale::default()), + ); + let mut serving = std::pin::pin!(kio::wait(move |waiter| serve.poll(waiter))); + + // Group 5 holds the requested object, and is the newest when the serve looks at it. + let mut group = track.create_group(group::Info { sequence: 5 }).unwrap(); + for _ in 0..4 { + group + .write_frame(crate::Timestamp::from_millis(0).unwrap(), b"frame".as_slice()) + .unwrap(); + } + group.finish().unwrap(); + assert!(futures::poll!(serving.as_mut()).is_pending()); + assert!(log.priorities().is_empty(), "served the partial group"); + + let mut group = track.create_group(group::Info { sequence: 6 }).unwrap(); + group + .write_frame(crate::Timestamp::from_millis(0).unwrap(), b"frame".as_slice()) + .unwrap(); + group.finish().unwrap(); + track.finish().unwrap(); + serving.await.unwrap(); + + assert_eq!(log.priorities().len(), 1, "only group 6 should have been served"); + } } #[cfg(test)] diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index d13acaae455..ff0ba7845d4 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -2124,12 +2124,17 @@ async fn recv_next(track: &mut track::Subscriber, datagrams: bool, emit_boundary /// Frame bounds qualify the start and end group only; everything in between is served /// whole. `false` means the group's head is missing and the subscriber never asked for a /// partial group, so it must be skipped: a group is the unit of decodability, and only -/// the subscriber knows whether a partial one is any use to it. +/// the subscriber knows whether a partial one is any use to it. A track that serves only +/// whole groups ([`track::Info::whole_groups`]) skips a start group asked for partway +/// through too, so the subscription resolves to the next one. fn position_group(group: &mut group::Consumer, start: Option<(u64, u64)>, end: Option<(u64, u64)>) -> bool { let expected = match start { Some((sequence, frame)) if sequence == group.sequence => frame, _ => 0, }; + if expected > 0 && group.whole_groups() { + return false; + } // `start_at` clamps up to the first frame the group still holds, so landing higher // than asked means the frames below it are gone. @@ -2955,6 +2960,32 @@ mod serve_group_test { assert_eq!(consumer.index(), 0); } + /// A whole-groups track holds the whole start group, yet still skips it for a + /// subscriber asking for its tail, and serves the next group whole. + #[test] + fn position_group_skips_a_partial_start_on_a_whole_groups_track() { + let info = track::Info::default().with_whole_groups(true); + let track = track::Producer::new(Arc::new(broadcast::Info::default()), "video", info); + let mut group = track.create_group(group::Info { sequence: 3 }).unwrap(); + for _ in 0..4 { + group.write_frame(Timestamp::ZERO, b"x".to_vec()).unwrap(); + } + + let mut consumer = group.consume(); + assert!(!position_group(&mut consumer, Some((3, 2)), None)); + + // From its head it serves as usual. + let mut consumer = group.consume(); + assert!(position_group(&mut consumer, Some((3, 0)), None)); + assert_eq!(consumer.index(), 0); + + // The next group is whole, so it serves. + let other = track.create_group(group::Info { sequence: 4 }).unwrap(); + let mut consumer = other.consume(); + assert!(position_group(&mut consumer, Some((3, 2)), None)); + assert_eq!(consumer.index(), 0); + } + /// The end bound caps the end group and leaves the others whole. #[test] fn position_group_caps_the_end_group() { @@ -3537,6 +3568,66 @@ mod serve_group_test { assert!(relay.started_at(6), "named the skipped group"); } + /// A subscription asking a whole-groups track for the tail of a group starts at the + /// next group instead: SUBSCRIBE_START names it, and it is the only stream opened. + #[tokio::test] + async fn a_whole_groups_track_starts_a_partial_subscription_at_the_next_group() { + use crate::coding::Decode; + + let info = track::Info::default().with_whole_groups(true); + let mut track = track::Producer::new(Arc::new(broadcast::Info::default()), "test", info); + let start = track::Position { group: 5, frame: 2 }; + let subscriber = track.subscribe(track::Subscription::default().with_start(start)); + + let log = Log::default(); + let mut writer = Writer::new(SinkSend::new(log.clone()), Version::Lite07); + let track_priority = kio::Producer::new(0u8); + let ctx = Subscription { + session: SinkSession::new(Log::default()), + id: 0, + track_name: "test".into(), + priority: PriorityQueue::default(), + track_priority: track_priority.consume(), + track_priority_seen: 0, + version: Version::Lite07, + timescale: Some(crate::Timescale::default()), + opens: Default::default(), + }; + let bounds = Bounds { + start_group: Some(5), + start_frame: 2, + end_group: None, + end_frame: None, + }; + let mut run = TrackRun::new(ctx, subscriber, bounds, track_priority); + let mut run = std::pin::pin!(kio::wait(move |waiter| run.poll(&mut writer, waiter))); + + // Group 5 holds the requested frame, and is the newest when the run looks at it. + let mut group = track.create_group(group::Info { sequence: 5 }).unwrap(); + for millis in 0..4 { + group + .write_frame(Timestamp::from_millis(millis).unwrap(), b"x".as_slice()) + .unwrap(); + } + group.finish().unwrap(); + assert!(futures::poll!(run.as_mut()).is_pending()); + + write_group(&mut track, 6, 6); + track.finish().unwrap(); + run.await.unwrap(); + + let writes = log.writes.lock().unwrap(); + let mut slice = writes.as_slice(); + match lite::SubscribeResponse::decode(&mut slice, Version::Lite07) { + Ok(lite::SubscribeResponse::Start(start)) => assert_eq!(start.group, 6, "named the partial group"), + other => panic!("expected SUBSCRIBE_START, got {other:?}"), + } + match lite::SubscribeResponse::decode(&mut slice, Version::Lite07) { + Ok(lite::SubscribeResponse::End(end)) => assert_eq!(end.streams, 1, "served the partial group"), + other => panic!("expected SUBSCRIBE_END, got {other:?}"), + } + } + /// A track that ends without a group still ends the subscription, with no stream owed. #[tokio::test] async fn lite07_end_counts_zero_streams() { diff --git a/rs/moq-net/src/model/group.rs b/rs/moq-net/src/model/group.rs index 4fefbf4e32e..967d8165e6f 100644 --- a/rs/moq-net/src/model/group.rs +++ b/rs/moq-net/src/model/group.rs @@ -1362,6 +1362,12 @@ impl Consumer { self.track.timescale } + /// Whether the parent track serves only whole groups; see + /// [`track::Info::whole_groups`]. + pub(crate) fn whole_groups(&self) -> bool { + self.track.whole_groups + } + /// The index of the next frame this consumer will return. /// /// Starts at 0, or at the group's first available frame once [`Self::set_frames`] has diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index b79d95c1791..a3aea26af45 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -120,6 +120,14 @@ pub struct Info { /// subscriptions of equal subscriber priority. Reported in TRACK_INFO (Lite05+). /// Higher is more urgent. Defaults to 127, the midpoint. pub priority: u8, + /// Serve only whole groups: a subscription or fetch that starts partway through a + /// group skips that group (or is refused) rather than receiving its tail. + /// + /// For a publisher whose frames are only valid after the head it produced itself, + /// such as an encoder: another instance at the same path produces different bytes, + /// so its tail cannot continue a head someone else delivered. A local serving + /// policy, not carried in TRACK_INFO. Defaults to `false`. + pub whole_groups: bool, } impl Default for Info { @@ -128,6 +136,7 @@ impl Default for Info { timescale: Timescale::default(), max_age: None, priority: DEFAULT_PRIORITY, + whole_groups: false, } } } @@ -153,6 +162,12 @@ impl Info { self.priority = priority; self } + + /// Set whether only whole groups are served, returning `self` for chaining. + pub fn with_whole_groups(mut self, whole_groups: bool) -> Self { + self.whole_groups = whole_groups; + self + } } #[derive(Default)] @@ -359,6 +374,11 @@ impl TrackState { self.install(info); } + /// Whether the publisher serves only whole groups; see [`Info::whole_groups`]. + fn whole_groups(&self) -> bool { + self.info.as_ref().is_some_and(|info| info.whole_groups) + } + fn poll_info(&self) -> Poll> { if let Some(info) = &self.info { Poll::Ready(Ok(info.clone())) @@ -651,6 +671,11 @@ impl TrackState { /// end-of-stream. The handler side (a rejection, or no [`Dynamic`] at all) lives /// in [`FetchState`]; [`Fetching`] polls both. fn poll_fetch_cached(&self, sequence: u64, frame_start: u64) -> Poll> { + // A tail of a whole-groups track is never served, cached or not. + if frame_start > 0 && self.whole_groups() { + return Poll::Ready(Err(Error::NotFound)); + } + // A group aborted between the lookup and the consume (an abandoned fetch cut // short) is a miss, not a hit that fails on its first read. if let Some(group) = self.covering_group(sequence, frame_start) @@ -1848,7 +1873,7 @@ fn poll_requested_group( waiter: &kio::Waiter, ) -> Poll> { // Prefer serving a queued fetch, even if the track has since aborted. - if let Poll::Ready(mut guard) = fetch.poll(waiter, |fetch| { + while let Poll::Ready(mut guard) = fetch.poll(waiter, |fetch| { if fetch.has_queued() { Poll::Ready(()) } else { @@ -1864,7 +1889,7 @@ fn poll_requested_group( let frame_start = pending.frame_start; let result = pending.result.clone(); drop(guard); - return Poll::Ready(Ok(group::Request { + let request = group::Request { state: state.clone(), fetch: fetch.clone(), sequence, @@ -1872,7 +1897,13 @@ fn poll_requested_group( frame_start, result, done: false, - })); + }; + // Queued before the track was accepted, so `fetch_group` could not refuse it. + if frame_start > 0 && state.read().whole_groups() { + request.reject(Error::NotFound); + continue; + } + return Poll::Ready(Ok(request)); } // No fetch queued: surface a track abort so the handler loop can exit. @@ -7877,6 +7908,63 @@ mod test { ); } + /// A whole-groups track refuses a fetch for a tail even when it holds the whole + /// group, and never hands one to its handler. + #[tokio::test] + async fn a_whole_groups_track_refuses_a_partial_fetch() { + let producer = track_producer("test", Info::default().with_whole_groups(true)); + let dynamic = producer.dynamic(); + let consumer = producer.consume(); + + let mut group = producer.create_group(group::Info { sequence: 0 }).unwrap(); + for payload in [b"a", b"b", b"c"] { + group + .write_frame(Timestamp::ZERO, bytes::Bytes::from_static(payload)) + .unwrap(); + } + group.finish().unwrap(); + + // Cached: refused rather than positioned into the group. + let cached = consumer.fetch_group(0, group::Fetch::default().with_frame_start(1)); + assert!(matches!(cached.now_or_never(), Some(Err(Error::NotFound)))); + // The whole group still resolves from the cache. + let whole = consumer.fetch_group(0, None).now_or_never().expect("cached").unwrap(); + assert_eq!(whole.index(), 0); + + // Uncached: refused without queueing for the handler. + let missing = consumer.fetch_group(1, group::Fetch::default().with_frame_start(1)); + assert!(matches!(missing.now_or_never(), Some(Err(Error::NotFound)))); + assert!( + dynamic.requested_group().now_or_never().is_none(), + "queued a partial fetch" + ); + } + + /// A partial fetch queued before the track was accepted, when nothing could refuse it + /// yet, is refused once the accepted info says whole groups, and the handler never sees + /// it. + #[tokio::test] + async fn a_whole_groups_track_refuses_a_partial_fetch_queued_before_accept() { + let request = Request::new(Arc::new(broadcast::Info::default()), "test"); + let consumer = request.consume(); + let partial = consumer.fetch_group(3, group::Fetch::default().with_frame_start(2)); + let whole = consumer.fetch_group(4, None); + + let dynamic = request.dynamic(); + let _producer = request.accept(Info::default().with_whole_groups(true)); + + let served = dynamic.requested_group().await.unwrap(); + assert_eq!( + (served.sequence(), served.frame_start()), + (4, 0), + "handed out the partial fetch" + ); + assert!(matches!(partial.await, Err(Error::NotFound))); + + served.reject(Error::Cancel); + assert!(whole.await.is_err()); + } + /// Joining a queued fetch widens its range, and a caller that arrives once the range /// is already on the wire fails cleanly rather than being handed the narrower group. #[tokio::test] diff --git a/rs/moq-transcode/src/lib.rs b/rs/moq-transcode/src/lib.rs index 7dd650ba8c4..a43fb2a1fc4 100644 --- a/rs/moq-transcode/src/lib.rs +++ b/rs/moq-transcode/src/lib.rs @@ -1316,7 +1316,11 @@ mod tests { // The source publishes no live groups, so group 7 is a cache miss that // reaches the rung's fetch handler. let rung = consumer.track("video/120p").unwrap(); - rung.query().await.unwrap(); + // Which also makes a subscription starting mid-group begin at the next group. + assert!( + rung.query().await.unwrap().whole_groups, + "the rung serves partial groups" + ); let partial = rung .fetch_group(7, moq_net::group::Fetch::default().with_frame_start(2)) diff --git a/rs/moq-transcode/src/rung.rs b/rs/moq-transcode/src/rung.rs index e7e995b3c47..00901a93068 100644 --- a/rs/moq-transcode/src/rung.rs +++ b/rs/moq-transcode/src/rung.rs @@ -7,9 +7,12 @@ //! source track (mirroring the aggregate subscription) and transcodes group //! for group until the track goes `unused` again. //! - A fetch of a specific group (`requested_group`) fetches that same group -//! from the source and transcodes just that group with a fresh encoder. A -//! fetch that starts mid-group is refused: the frames are only valid after -//! the head this encoder produced. +//! from the source and transcodes just that group with a fresh encoder. +//! +//! A rung track serves whole groups only (`track::Info::whole_groups`): its +//! frames are only valid after the head this encoder produced, so a +//! subscription starting mid-group begins at the next group and a mid-group +//! fetch is refused. //! //! Output groups mirror the source group sequence numbers 1:1, so a fetch for //! output group N maps to source group N and a player switching renditions @@ -132,7 +135,10 @@ pub(crate) async fn serve(rung: Rung, request: moq_net::track::Request) -> Resul // Grab the group-request handle before accepting: a Request is dynamic from // birth, so a fetch racing the acceptance queues instead of failing. let dynamic = request.dynamic(); - let info = hang::container::track_info(hang::catalog::PRIORITY.video); + // Another instance encodes the same source group into different bytes, so a tail + // from this encoder cannot continue a head someone else delivered. A subscription + // asking for one starts at the next group instead, and such a fetch is refused. + let info = hang::container::track_info(hang::catalog::PRIORITY.video).with_whole_groups(true); let mut producer = request.accept(info); let (finished, mut finishing) = tokio::sync::watch::channel(false); @@ -483,20 +489,8 @@ fn spawn_fetch( /// "the handler vanished" and hides the actual decode/encode/source failure from /// the waiting consumer. async fn fetch(rung: Rung, request: moq_net::group::Request) -> Result<(), Error> { - // Another instance encodes the same source group into different bytes, so a - // tail from this encoder cannot continue a head someone else produced. A - // partial group is not ours to serve; refuse it so the reader moves on to the - // next group boundary instead of decoding a splice. - if request.frame_start() != 0 { - tracing::debug!( - sequence = request.sequence(), - frame = request.frame_start(), - "refusing a fetch that starts mid-group" - ); - request.reject(moq_net::Error::NotFound); - return Ok(()); - } - + // Always the whole group: the track serves whole groups only (see `serve`), so + // moq-net refuses a mid-group fetch before it gets here. let options = moq_net::group::Fetch::default().with_priority(request.priority()); let mut source = match rung.source.fetch_group(request.sequence(), options).await { Ok(source) => source, From d6307150ede679f55ed9fdf2fcad5bbbc5987b25 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 5 Oct 2026 12:00:01 -0700 Subject: [PATCH 4/8] Revert "feat(net): let a track serve only whole groups" This reverts commit d2833e736025410facd342d4ea83b90e2b3824ab. --- quest/m1/transcode-group-start.md | 56 ++++++++++-------- rs/moq-net/src/ietf/publisher.rs | 53 ----------------- rs/moq-net/src/lite/publisher.rs | 93 +----------------------------- rs/moq-net/src/model/group.rs | 6 -- rs/moq-net/src/model/track.rs | 94 +------------------------------ rs/moq-transcode/src/lib.rs | 6 +- rs/moq-transcode/src/rung.rs | 30 ++++++---- 7 files changed, 57 insertions(+), 281 deletions(-) diff --git a/quest/m1/transcode-group-start.md b/quest/m1/transcode-group-start.md index d0136537a65..3e58e7e2064 100644 --- a/quest/m1/transcode-group-start.md +++ b/quest/m1/transcode-group-start.md @@ -12,30 +12,42 @@ config. ## Plan -- Decided 2026-10-04 by the maintainer: the fix is transcode-only and relay - resume stays as it is. A transcoder cannot resume a group - deterministically, so it never serves a partial group: a subscription - starting at (N, M>0) skips group N for that subscriber and starts at - (N+1, 0), and a mid-group FETCH is refused. -- moq-net answers subscriptions and cached fetches from the track cache - before the transcoder sees them, so the refusal needs a moq-net hook. A - `track::Info::whole_groups` flag is the hook: a local serving policy, not - carried in TRACK_INFO, so no wire change and relays are unaffected. Where - it lives (`Info` field, a `Producer` setter, or a per-group flag) is still - open on the PR. - The lite draft already lets a publisher skip a group it cannot serve from the requested frame and resolve to a later one, so no wire change. -- Output groups already mirror the source's sequences (`rung.rs`), pinned by - a test of two instances fed one source. -- The maintainer wants deterministic transcodes, aligned with moq.pro's - [wildcard transcode plan](https://github.com/moq-dev/moq.pro/blob/main/quest/m2/wildcard/transcode.md). - Two per-process leaks into the catalog are queued as follow-up quests, not - done here: rung names minted per process (`video/120p.2` after a resize, - `catalog::Names`), and the probed catalog entry depending on the host's - backend under `encode::Kind::Auto` (pin the encoder kind). - -Public API: `moq_net::track::Info::whole_groups` and `with_whole_groups`. -Wire: none. +- Output groups already mirror the source's sequences (`rung.rs`). Keep that, + and check that nothing per-process (start time, random ids, encoder + defaults) leaks into the catalog. +- Tests: a subscription and a FETCH that start mid-group, and two instances + fed the same source that publish the same catalog and group sequences. + +Public API: none. Wire: none. + +### Findings + +Done: the rung's fetch handler refuses a mid-group FETCH (it used to write +the whole group at the requested index), and a test pins two instances +publishing the same catalog and groups from one source. + +Open, and not reachable from moq-transcode alone: + +- moq-net serves subscriptions and cached fetches from the track cache, so a + mid-group start is positioned into whatever group N the transcoder holds + (`position_group` in `lite/publisher.rs`, the cache path of + `fetch_group`). The handler only sees cache misses. +- The relay does not ask the new route for (N, M) anyway. `resume.rs` + subscribes the new copy from (N, 0) and continues the in-flight group from + that copy's group N at frame M, which is exactly the splice. The draft + and `resume.rs` assume every route's frames are identical; two encoders' + are only group-aligned. +- Rung names are minted per process (`video/120p.2` after a resize, see + `catalog::Names`), so an instance that started after a resize names the + same picture differently, and reuses a name another instance finished. +- With `encode::Kind::Auto` the probed catalog entry (profile, level) depends + on which backend the host has. + +Which way to close the splice is a maintainer decision: a track property that +limits route moves to group boundaries, relays moving routes only at group +boundaries, or giving each worker its own path. ## Related diff --git a/rs/moq-net/src/ietf/publisher.rs b/rs/moq-net/src/ietf/publisher.rs index ab0388dad31..856fca169b6 100644 --- a/rs/moq-net/src/ietf/publisher.rs +++ b/rs/moq-net/src/ietf/publisher.rs @@ -2522,12 +2522,6 @@ impl TrackServe { if slice.until.is_some_and(|until| until <= slice.skip) { continue; } - // A whole-groups track never serves a tail: the subscription starts at - // the next group instead. - if slice.skip > 0 && group.whole_groups() { - tracing::debug!(subscribe = %self.request_id, sequence, "skipping a partial start group"); - continue; - } let msg = ietf::GroupHeader { track_alias: self.request_id.0, @@ -3254,53 +3248,6 @@ mod subscribe_cursor_test { // `GroupServe` sets the priority once per stream it opens, so this counts groups served. assert_eq!(log.priorities().len(), 1, "only group 3 should have been served"); } - - /// A subscription asking a whole-groups track for the tail of a group skips that group - /// and starts at the next one, even though the group holds the requested object. - #[tokio::test] - async fn a_whole_groups_track_starts_a_partial_subscription_at_the_next_group() { - let log = Log::default(); - let session = SinkSession::new(log.clone()); - - let info = track::Info::default().with_whole_groups(true); - let track = track::Producer::new(std::sync::Arc::new(crate::broadcast::Info::default()), "video", info); - let start = track::Position { group: 5, frame: 2 }; - let subscriber = track.subscribe(track::Subscription::default().with_start(start)); - - let mut serve = TrackServe::new( - session, - subscriber, - RequestId(1), - Version::Draft14, - ServeRange { - start: Some(Location { group: 5, object: 2 }), - end: None, - }, - Some(Timescale::default()), - ); - let mut serving = std::pin::pin!(kio::wait(move |waiter| serve.poll(waiter))); - - // Group 5 holds the requested object, and is the newest when the serve looks at it. - let mut group = track.create_group(group::Info { sequence: 5 }).unwrap(); - for _ in 0..4 { - group - .write_frame(crate::Timestamp::from_millis(0).unwrap(), b"frame".as_slice()) - .unwrap(); - } - group.finish().unwrap(); - assert!(futures::poll!(serving.as_mut()).is_pending()); - assert!(log.priorities().is_empty(), "served the partial group"); - - let mut group = track.create_group(group::Info { sequence: 6 }).unwrap(); - group - .write_frame(crate::Timestamp::from_millis(0).unwrap(), b"frame".as_slice()) - .unwrap(); - group.finish().unwrap(); - track.finish().unwrap(); - serving.await.unwrap(); - - assert_eq!(log.priorities().len(), 1, "only group 6 should have been served"); - } } #[cfg(test)] diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index ff0ba7845d4..d13acaae455 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -2124,17 +2124,12 @@ async fn recv_next(track: &mut track::Subscriber, datagrams: bool, emit_boundary /// Frame bounds qualify the start and end group only; everything in between is served /// whole. `false` means the group's head is missing and the subscriber never asked for a /// partial group, so it must be skipped: a group is the unit of decodability, and only -/// the subscriber knows whether a partial one is any use to it. A track that serves only -/// whole groups ([`track::Info::whole_groups`]) skips a start group asked for partway -/// through too, so the subscription resolves to the next one. +/// the subscriber knows whether a partial one is any use to it. fn position_group(group: &mut group::Consumer, start: Option<(u64, u64)>, end: Option<(u64, u64)>) -> bool { let expected = match start { Some((sequence, frame)) if sequence == group.sequence => frame, _ => 0, }; - if expected > 0 && group.whole_groups() { - return false; - } // `start_at` clamps up to the first frame the group still holds, so landing higher // than asked means the frames below it are gone. @@ -2960,32 +2955,6 @@ mod serve_group_test { assert_eq!(consumer.index(), 0); } - /// A whole-groups track holds the whole start group, yet still skips it for a - /// subscriber asking for its tail, and serves the next group whole. - #[test] - fn position_group_skips_a_partial_start_on_a_whole_groups_track() { - let info = track::Info::default().with_whole_groups(true); - let track = track::Producer::new(Arc::new(broadcast::Info::default()), "video", info); - let mut group = track.create_group(group::Info { sequence: 3 }).unwrap(); - for _ in 0..4 { - group.write_frame(Timestamp::ZERO, b"x".to_vec()).unwrap(); - } - - let mut consumer = group.consume(); - assert!(!position_group(&mut consumer, Some((3, 2)), None)); - - // From its head it serves as usual. - let mut consumer = group.consume(); - assert!(position_group(&mut consumer, Some((3, 0)), None)); - assert_eq!(consumer.index(), 0); - - // The next group is whole, so it serves. - let other = track.create_group(group::Info { sequence: 4 }).unwrap(); - let mut consumer = other.consume(); - assert!(position_group(&mut consumer, Some((3, 2)), None)); - assert_eq!(consumer.index(), 0); - } - /// The end bound caps the end group and leaves the others whole. #[test] fn position_group_caps_the_end_group() { @@ -3568,66 +3537,6 @@ mod serve_group_test { assert!(relay.started_at(6), "named the skipped group"); } - /// A subscription asking a whole-groups track for the tail of a group starts at the - /// next group instead: SUBSCRIBE_START names it, and it is the only stream opened. - #[tokio::test] - async fn a_whole_groups_track_starts_a_partial_subscription_at_the_next_group() { - use crate::coding::Decode; - - let info = track::Info::default().with_whole_groups(true); - let mut track = track::Producer::new(Arc::new(broadcast::Info::default()), "test", info); - let start = track::Position { group: 5, frame: 2 }; - let subscriber = track.subscribe(track::Subscription::default().with_start(start)); - - let log = Log::default(); - let mut writer = Writer::new(SinkSend::new(log.clone()), Version::Lite07); - let track_priority = kio::Producer::new(0u8); - let ctx = Subscription { - session: SinkSession::new(Log::default()), - id: 0, - track_name: "test".into(), - priority: PriorityQueue::default(), - track_priority: track_priority.consume(), - track_priority_seen: 0, - version: Version::Lite07, - timescale: Some(crate::Timescale::default()), - opens: Default::default(), - }; - let bounds = Bounds { - start_group: Some(5), - start_frame: 2, - end_group: None, - end_frame: None, - }; - let mut run = TrackRun::new(ctx, subscriber, bounds, track_priority); - let mut run = std::pin::pin!(kio::wait(move |waiter| run.poll(&mut writer, waiter))); - - // Group 5 holds the requested frame, and is the newest when the run looks at it. - let mut group = track.create_group(group::Info { sequence: 5 }).unwrap(); - for millis in 0..4 { - group - .write_frame(Timestamp::from_millis(millis).unwrap(), b"x".as_slice()) - .unwrap(); - } - group.finish().unwrap(); - assert!(futures::poll!(run.as_mut()).is_pending()); - - write_group(&mut track, 6, 6); - track.finish().unwrap(); - run.await.unwrap(); - - let writes = log.writes.lock().unwrap(); - let mut slice = writes.as_slice(); - match lite::SubscribeResponse::decode(&mut slice, Version::Lite07) { - Ok(lite::SubscribeResponse::Start(start)) => assert_eq!(start.group, 6, "named the partial group"), - other => panic!("expected SUBSCRIBE_START, got {other:?}"), - } - match lite::SubscribeResponse::decode(&mut slice, Version::Lite07) { - Ok(lite::SubscribeResponse::End(end)) => assert_eq!(end.streams, 1, "served the partial group"), - other => panic!("expected SUBSCRIBE_END, got {other:?}"), - } - } - /// A track that ends without a group still ends the subscription, with no stream owed. #[tokio::test] async fn lite07_end_counts_zero_streams() { diff --git a/rs/moq-net/src/model/group.rs b/rs/moq-net/src/model/group.rs index 967d8165e6f..4fefbf4e32e 100644 --- a/rs/moq-net/src/model/group.rs +++ b/rs/moq-net/src/model/group.rs @@ -1362,12 +1362,6 @@ impl Consumer { self.track.timescale } - /// Whether the parent track serves only whole groups; see - /// [`track::Info::whole_groups`]. - pub(crate) fn whole_groups(&self) -> bool { - self.track.whole_groups - } - /// The index of the next frame this consumer will return. /// /// Starts at 0, or at the group's first available frame once [`Self::set_frames`] has diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index a3aea26af45..b79d95c1791 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -120,14 +120,6 @@ pub struct Info { /// subscriptions of equal subscriber priority. Reported in TRACK_INFO (Lite05+). /// Higher is more urgent. Defaults to 127, the midpoint. pub priority: u8, - /// Serve only whole groups: a subscription or fetch that starts partway through a - /// group skips that group (or is refused) rather than receiving its tail. - /// - /// For a publisher whose frames are only valid after the head it produced itself, - /// such as an encoder: another instance at the same path produces different bytes, - /// so its tail cannot continue a head someone else delivered. A local serving - /// policy, not carried in TRACK_INFO. Defaults to `false`. - pub whole_groups: bool, } impl Default for Info { @@ -136,7 +128,6 @@ impl Default for Info { timescale: Timescale::default(), max_age: None, priority: DEFAULT_PRIORITY, - whole_groups: false, } } } @@ -162,12 +153,6 @@ impl Info { self.priority = priority; self } - - /// Set whether only whole groups are served, returning `self` for chaining. - pub fn with_whole_groups(mut self, whole_groups: bool) -> Self { - self.whole_groups = whole_groups; - self - } } #[derive(Default)] @@ -374,11 +359,6 @@ impl TrackState { self.install(info); } - /// Whether the publisher serves only whole groups; see [`Info::whole_groups`]. - fn whole_groups(&self) -> bool { - self.info.as_ref().is_some_and(|info| info.whole_groups) - } - fn poll_info(&self) -> Poll> { if let Some(info) = &self.info { Poll::Ready(Ok(info.clone())) @@ -671,11 +651,6 @@ impl TrackState { /// end-of-stream. The handler side (a rejection, or no [`Dynamic`] at all) lives /// in [`FetchState`]; [`Fetching`] polls both. fn poll_fetch_cached(&self, sequence: u64, frame_start: u64) -> Poll> { - // A tail of a whole-groups track is never served, cached or not. - if frame_start > 0 && self.whole_groups() { - return Poll::Ready(Err(Error::NotFound)); - } - // A group aborted between the lookup and the consume (an abandoned fetch cut // short) is a miss, not a hit that fails on its first read. if let Some(group) = self.covering_group(sequence, frame_start) @@ -1873,7 +1848,7 @@ fn poll_requested_group( waiter: &kio::Waiter, ) -> Poll> { // Prefer serving a queued fetch, even if the track has since aborted. - while let Poll::Ready(mut guard) = fetch.poll(waiter, |fetch| { + if let Poll::Ready(mut guard) = fetch.poll(waiter, |fetch| { if fetch.has_queued() { Poll::Ready(()) } else { @@ -1889,7 +1864,7 @@ fn poll_requested_group( let frame_start = pending.frame_start; let result = pending.result.clone(); drop(guard); - let request = group::Request { + return Poll::Ready(Ok(group::Request { state: state.clone(), fetch: fetch.clone(), sequence, @@ -1897,13 +1872,7 @@ fn poll_requested_group( frame_start, result, done: false, - }; - // Queued before the track was accepted, so `fetch_group` could not refuse it. - if frame_start > 0 && state.read().whole_groups() { - request.reject(Error::NotFound); - continue; - } - return Poll::Ready(Ok(request)); + })); } // No fetch queued: surface a track abort so the handler loop can exit. @@ -7908,63 +7877,6 @@ mod test { ); } - /// A whole-groups track refuses a fetch for a tail even when it holds the whole - /// group, and never hands one to its handler. - #[tokio::test] - async fn a_whole_groups_track_refuses_a_partial_fetch() { - let producer = track_producer("test", Info::default().with_whole_groups(true)); - let dynamic = producer.dynamic(); - let consumer = producer.consume(); - - let mut group = producer.create_group(group::Info { sequence: 0 }).unwrap(); - for payload in [b"a", b"b", b"c"] { - group - .write_frame(Timestamp::ZERO, bytes::Bytes::from_static(payload)) - .unwrap(); - } - group.finish().unwrap(); - - // Cached: refused rather than positioned into the group. - let cached = consumer.fetch_group(0, group::Fetch::default().with_frame_start(1)); - assert!(matches!(cached.now_or_never(), Some(Err(Error::NotFound)))); - // The whole group still resolves from the cache. - let whole = consumer.fetch_group(0, None).now_or_never().expect("cached").unwrap(); - assert_eq!(whole.index(), 0); - - // Uncached: refused without queueing for the handler. - let missing = consumer.fetch_group(1, group::Fetch::default().with_frame_start(1)); - assert!(matches!(missing.now_or_never(), Some(Err(Error::NotFound)))); - assert!( - dynamic.requested_group().now_or_never().is_none(), - "queued a partial fetch" - ); - } - - /// A partial fetch queued before the track was accepted, when nothing could refuse it - /// yet, is refused once the accepted info says whole groups, and the handler never sees - /// it. - #[tokio::test] - async fn a_whole_groups_track_refuses_a_partial_fetch_queued_before_accept() { - let request = Request::new(Arc::new(broadcast::Info::default()), "test"); - let consumer = request.consume(); - let partial = consumer.fetch_group(3, group::Fetch::default().with_frame_start(2)); - let whole = consumer.fetch_group(4, None); - - let dynamic = request.dynamic(); - let _producer = request.accept(Info::default().with_whole_groups(true)); - - let served = dynamic.requested_group().await.unwrap(); - assert_eq!( - (served.sequence(), served.frame_start()), - (4, 0), - "handed out the partial fetch" - ); - assert!(matches!(partial.await, Err(Error::NotFound))); - - served.reject(Error::Cancel); - assert!(whole.await.is_err()); - } - /// Joining a queued fetch widens its range, and a caller that arrives once the range /// is already on the wire fails cleanly rather than being handed the narrower group. #[tokio::test] diff --git a/rs/moq-transcode/src/lib.rs b/rs/moq-transcode/src/lib.rs index a43fb2a1fc4..7dd650ba8c4 100644 --- a/rs/moq-transcode/src/lib.rs +++ b/rs/moq-transcode/src/lib.rs @@ -1316,11 +1316,7 @@ mod tests { // The source publishes no live groups, so group 7 is a cache miss that // reaches the rung's fetch handler. let rung = consumer.track("video/120p").unwrap(); - // Which also makes a subscription starting mid-group begin at the next group. - assert!( - rung.query().await.unwrap().whole_groups, - "the rung serves partial groups" - ); + rung.query().await.unwrap(); let partial = rung .fetch_group(7, moq_net::group::Fetch::default().with_frame_start(2)) diff --git a/rs/moq-transcode/src/rung.rs b/rs/moq-transcode/src/rung.rs index 00901a93068..e7e995b3c47 100644 --- a/rs/moq-transcode/src/rung.rs +++ b/rs/moq-transcode/src/rung.rs @@ -7,12 +7,9 @@ //! source track (mirroring the aggregate subscription) and transcodes group //! for group until the track goes `unused` again. //! - A fetch of a specific group (`requested_group`) fetches that same group -//! from the source and transcodes just that group with a fresh encoder. -//! -//! A rung track serves whole groups only (`track::Info::whole_groups`): its -//! frames are only valid after the head this encoder produced, so a -//! subscription starting mid-group begins at the next group and a mid-group -//! fetch is refused. +//! from the source and transcodes just that group with a fresh encoder. A +//! fetch that starts mid-group is refused: the frames are only valid after +//! the head this encoder produced. //! //! Output groups mirror the source group sequence numbers 1:1, so a fetch for //! output group N maps to source group N and a player switching renditions @@ -135,10 +132,7 @@ pub(crate) async fn serve(rung: Rung, request: moq_net::track::Request) -> Resul // Grab the group-request handle before accepting: a Request is dynamic from // birth, so a fetch racing the acceptance queues instead of failing. let dynamic = request.dynamic(); - // Another instance encodes the same source group into different bytes, so a tail - // from this encoder cannot continue a head someone else delivered. A subscription - // asking for one starts at the next group instead, and such a fetch is refused. - let info = hang::container::track_info(hang::catalog::PRIORITY.video).with_whole_groups(true); + let info = hang::container::track_info(hang::catalog::PRIORITY.video); let mut producer = request.accept(info); let (finished, mut finishing) = tokio::sync::watch::channel(false); @@ -489,8 +483,20 @@ fn spawn_fetch( /// "the handler vanished" and hides the actual decode/encode/source failure from /// the waiting consumer. async fn fetch(rung: Rung, request: moq_net::group::Request) -> Result<(), Error> { - // Always the whole group: the track serves whole groups only (see `serve`), so - // moq-net refuses a mid-group fetch before it gets here. + // Another instance encodes the same source group into different bytes, so a + // tail from this encoder cannot continue a head someone else produced. A + // partial group is not ours to serve; refuse it so the reader moves on to the + // next group boundary instead of decoding a splice. + if request.frame_start() != 0 { + tracing::debug!( + sequence = request.sequence(), + frame = request.frame_start(), + "refusing a fetch that starts mid-group" + ); + request.reject(moq_net::Error::NotFound); + return Ok(()); + } + let options = moq_net::group::Fetch::default().with_priority(request.priority()); let mut source = match rung.source.fetch_group(request.sequence(), options).await { Ok(source) => source, From 26ba7e33e220065755897f749cb95d3989c3ebda Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 5 Oct 2026 12:02:18 -0700 Subject: [PATCH 5/8] quest: each transcode worker publishes under its own epoch Two workers at one derived name are spliced by the relay's own mid-group resume, which no serving policy on the transcoder can refuse. Give each worker its own epoch instead, revising the wildcard line's derived-output layout, and justify the mid-group fetch refusal on its own terms. Co-Authored-By: Claude Opus 5.5 --- quest/m0/broadcast-epoch/README.md | 9 +-- quest/m0/wildcard/README.md | 41 +++++++------ quest/m1/README.md | 2 +- quest/m1/transcode-group-start.md | 99 ++++++++++++++++-------------- rs/moq-transcode/src/lib.rs | 11 ++-- rs/moq-transcode/src/rung.rs | 12 ++-- 6 files changed, 92 insertions(+), 82 deletions(-) diff --git a/quest/m0/broadcast-epoch/README.md b/quest/m0/broadcast-epoch/README.md index 9aba1577073..c8cbf73fd71 100644 --- a/quest/m0/broadcast-epoch/README.md +++ b/quest/m0/broadcast-epoch/README.md @@ -58,10 +58,11 @@ Decided: - [Retracted demand release](/quest/m1/unannounce-demand-release.md) also gates the release (decided 2026-10-05): a regression from #4741 on main that `release` lacks. -- Derived output mirrors the epoch it came from - (`.pro/transcode//foo.hang/@e`, per the - [wildcard](/quest/m0/wildcard/README.md) line's derived-output layout), so - the service's prefix claim still covers it. +- Derived output mirrors the source's bare name under an epoch each worker + mints (`.pro/transcode//foo.hang/@`, per the + [wildcard](/quest/m0/wildcard/README.md) line's derived-output layout, decided + 2026-10-05), so two workers are two broadcasts and the service's prefix claim + still covers both. This README owns: diff --git a/quest/m0/wildcard/README.md b/quest/m0/wildcard/README.md index b0b410588d6..2a496035a13 100644 --- a/quest/m0/wildcard/README.md +++ b/quest/m0/wildcard/README.md @@ -78,8 +78,9 @@ specificity, and rebasing tokens and filters reuse. Content identity is the path: it names one broadcast whoever serves it, and any covering route resumes a subscription from the first frame the subscriber lacks (#4741). The `@` segment (#4706) is what makes a restart a new -path. So this questline settles collisions with interchangeable output at one -path, not with a route identity or a generation field. +path. So this questline settles collisions by giving each claim worker its own +epoch, so different content never shares a path, rather than with a route +identity or a generation field. ### Decisions @@ -159,19 +160,17 @@ path, not with a route identity or a generation field. the client's ordinary resubscribe resolves again. Scanning unserved paths costs one round trip per path. No negative cache; rate limiting stays with the advertiser and the per-project auth gate. -- **A double claim is settled by interchangeable output, not by route - identity or a lease.** Two relays can hash one path to different workers - before either concrete announcement propagates, and both land at the SAME - literal path. A path is one broadcast whoever serves it, so claim workers - mirror the source's epoch and group numbers, publish a deterministic - catalog, and start at group boundaries - ([Transcoders start at group boundaries](/quest/m1/transcode-group-start.md)). - Two workers at one path are then one broadcast, and a relay moving between - them does so at a group boundary (decided 2026-10-03: #4741 drops - first-hop identity, so routing can no longer tell two workers apart). - Wildcard routing invents neither a lease nor a generation. That quest is - Required here (decided 2026-10-04), so this line cannot ship with workers - that can be spliced mid-group. +- **A double claim is settled by per-worker names, not by route identity or + a lease.** Two relays can hash one derived name to different workers before + either concrete announcement propagates. Two encoders' bytes differ, and a + path is one broadcast whoever serves it (#4741 resumes mid-group from any + covering route), so each worker publishes under an epoch it mints + ([Per-worker epochs](/quest/m1/transcode-group-start.md)). The two workers + are then two broadcasts, a viewer follows the newest like any epoch + takeover, and a relay never splices them. Wildcard routing invents neither + a lease nor a generation. That quest is Required here (decided 2026-10-04, + revised 2026-10-05 from interchangeable output at one path, which a relay's + own mid-group resume defeats). - **A serving front follows the best route.** A join or re-price re-selects every front below the prefix, and a front moves when another route now wins: cheaper, or the rendezvous winner among equal costs (decided @@ -192,10 +191,12 @@ path, not with a route identity or a generation field. ### Where derived output lives A prefix claim needs the variable part of a path trailing, so a fleet-wide -service claims its own prefix and mirrors the source path beneath it +service claims its own prefix and mirrors the source's bare name beneath it (`.pro/transcode//foo.hang`, moq.pro's convention) rather than publishing -beneath the source. The source's catalog reaches the contribution through a -cross-broadcast reference. +beneath the source. Each worker publishes under its own epoch, +`.pro/transcode//foo.hang/@`, not the source's (decided +2026-10-05; see [Per-worker epochs](/quest/m1/transcode-group-start.md)). The +source's catalog reaches the contribution through a cross-broadcast reference. The leading `.` is deliberate. Existing customers on moq-lite-06 or older must never see `.pro/` broadcasts, which could confuse their business logic. Those @@ -217,13 +218,13 @@ distinguish recording generations reads the catalog's archive entry ## Required -- [Transcoders start at group boundaries](/quest/m1/transcode-group-start.md) - two claim workers at one path are one broadcast, so a relay never splices them mid-group +- [Per-worker epochs](/quest/m1/transcode-group-start.md) - each transcode worker publishes under its own epoch, so a relay never splices two workers' output ## Related - [archive](/quest/m1/archive/README.md) - an archive claims the root, and its catalog names the generations a claim cannot - [Broadcast epochs](/quest/m0/broadcast-epoch/README.md) - derived output - mirrors the source path, `@` segment included + mirrors the source's bare name under a worker-minted epoch - [Announcement shapes](/quest/m2/announce-shapes.md) - moq-lite-only exact, suffix, and prefix+suffix claims that survive relay hops diff --git a/quest/m1/README.md b/quest/m1/README.md index 062676d01e7..38419e82baf 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -26,7 +26,7 @@ QUIC studies there on that rule. - [Bounded stats aggregate](/quest/m1/stats-aggregate-bound.md) - the stats aggregator folds departed nodes into a retired total after a grace window, so its memory stops growing with node churn - [Stats epochs](/quest/m1/stats-epoch.md) - each stats producer publishes under `.../node//@`, so a restarted node never reuses a name - [Cluster routing](/quest/m1/cluster-routing/README.md) - any node routes toward a broadcast's origin over CDN and P2P links alike, with per-origin routes and path-less announces -- [Transcoders start at group boundaries](/quest/m1/transcode-group-start.md) - moq-transcode serves from a group boundary and mirrors its source's sequences, so two instances are interchangeable +- [Per-worker epochs](/quest/m1/transcode-group-start.md) - each transcode worker publishes under its own epoch, so two workers' different bytes never share a name - [One route cost](/quest/m1/route-cost.md) - Warm and Cold collapse to one static route cost - [Delete removed cluster flags](/quest/m1/cluster-shims.md) - `mesh` and `linger` leave `cluster::Config` and their flags become unknown - [Track tail interop](/quest/m1/track-tail-interop.md) - a Rust publisher ending a track with a group in flight is read to its end by the JS subscriber, and the reverse, in `just test interop` diff --git a/quest/m1/transcode-group-start.md b/quest/m1/transcode-group-start.md index 3e58e7e2064..58caf4cea3d 100644 --- a/quest/m1/transcode-group-start.md +++ b/quest/m1/transcode-group-start.md @@ -1,54 +1,63 @@ -# [S] Transcoders start at group boundaries +# [S] Per-worker transcode epochs ## Goal -Two moq-transcode instances serving one derived path are interchangeable at -group boundaries, so a relay moving a subscription between them never splices -two encoders' output mid-group. moq-transcode (`rs/moq-transcode`, and -`moq transcode` in moq-cli) resolves a subscription that starts at (N, M>0) -to (N+1, 0), and refuses a FETCH that starts mid-group. Output groups mirror -the source's sequence numbers, and the catalog derives only from the input and -config. +Two moq-transcode workers never share a broadcast name. Each worker +(`rs/moq-transcode`, and `moq transcode` in moq-cli) publishes its output under +an epoch it mints, so two encoders' different bytes are two broadcasts. A +viewer of the derived name follows the newest worker's epoch, like any other +epoch takeover, and a relay never splices one worker's group into another's. + +Non-goals: byte-identical output across workers, and a deterministic catalog +(stable rung names, a pinned encoder kind). Neither is needed once each worker +is its own broadcast. ## Plan -- The lite draft already lets a publisher skip a group it cannot serve from - the requested frame and resolve to a later one, so no wire change. -- Output groups already mirror the source's sequences (`rung.rs`). Keep that, - and check that nothing per-process (start time, random ids, encoder - defaults) leaks into the catalog. -- Tests: a subscription and a FETCH that start mid-group, and two instances - fed the same source that publish the same catalog and group sequences. - -Public API: none. Wire: none. - -### Findings - -Done: the rung's fetch handler refuses a mid-group FETCH (it used to write -the whole group at the requested index), and a test pins two instances -publishing the same catalog and groups from one source. - -Open, and not reachable from moq-transcode alone: - -- moq-net serves subscriptions and cached fetches from the track cache, so a - mid-group start is positioned into whatever group N the transcoder holds - (`position_group` in `lite/publisher.rs`, the cache path of - `fetch_group`). The handler only sees cache misses. -- The relay does not ask the new route for (N, M) anyway. `resume.rs` - subscribes the new copy from (N, 0) and continues the in-flight group from - that copy's group N at frame M, which is exactly the splice. The draft - and `resume.rs` assume every route's frames are identical; two encoders' - are only group-aligned. -- Rung names are minted per process (`video/120p.2` after a resize, see - `catalog::Names`), so an instance that started after a resize names the - same picture differently, and reuses a name another instance finished. -- With `encode::Kind::Auto` the probed catalog entry (profile, level) depends - on which backend the host has. - -Which way to close the splice is a maintainer decision: a track property that -limits route moves to group boundaries, relays moving routes only at group -boundaries, or giving each worker its own path. +Decided 2026-10-05 by the maintainer: + +- The splice is closed by per-worker names. Two workers that double-claim one + derived path under the [wildcard](/quest/m0/wildcard/README.md) line encode + the same source group into different bytes. If they shared a name, a + #4741 route move would make the relay continue group N at frame M from the + other worker's copy (`Recover::poll_serving` in + `rs/moq-net/src/model/resume.rs` subscribes the new copy from frame 0 and + splices with `start_at(M)` itself), which no moq-transcode policy can + refuse. A name reused for different content is a bug (AGENTS.md), so each + worker gets its own. +- Rejected: a moq-net `track::Info::whole_groups` serving policy (it never + fires on the relay's own splice), resuming only at group boundaries, and + byte-deterministic workers. +- Layout: the derived name mirrors the source's bare name, and the worker + appends an epoch it mints: `.pro/transcode//foo.hang/@`. The + source's own epoch does not nest beneath it, because + [Origin](/quest/m0/broadcast-epoch/origin.md) treats a path whose final + segment is an epoch as pinned, so `foo.hang/@e/@w` could not be followed. + The worker's catalog references the exact source epoch it transcodes, so + one derived broadcast is self-consistent, and a source restart is + transcoded under a newer worker epoch. The default CLI output + (`/transcode.hang`) gains the same trailing epoch. +- A caller may pass an explicit epoch; otherwise the worker mints one. The + epoch segment adds a level to the catalog's relative source reference + (`Config::source`). + +Done in [#4812](https://github.com/moq-dev/moq/pull/4812): the rung's fetch +handler refuses a mid-group FETCH instead of writing the whole group at the +requested index, and a test pins two instances fed one source publishing the +same catalog and group sequences. + +Left: mint and append the worker epoch in moq-transcode or the CLI, fix the +catalog's source reference, and test that two workers land on distinct paths +and a viewer of the derived name follows the newer one. Update +`doc/bin/cli.md` and `doc/bin/obs.md`, which give the output path. + +Public API: possibly an epoch on the transcode output config. Wire: none. + +## Required + +- [Origin](/quest/m0/broadcast-epoch/origin.md) - viewers of a bare name follow its newest live epoch, which is how a derived-name viewer finds the current worker ## Related -- [Wildcard](/quest/m0/wildcard/README.md) - a double claim's two workers at one path are settled by interchangeable output +- [Wildcard](/quest/m0/wildcard/README.md) - a double claim's two workers are two broadcasts, so a relay never splices them +- [Broadcast epochs](/quest/m0/broadcast-epoch/README.md) - the epoch rules the worker's own epoch follows diff --git a/rs/moq-transcode/src/lib.rs b/rs/moq-transcode/src/lib.rs index 7dd650ba8c4..e714e9d3167 100644 --- a/rs/moq-transcode/src/lib.rs +++ b/rs/moq-transcode/src/lib.rs @@ -1272,9 +1272,8 @@ mod tests { } /// A fetch that starts partway through a group is refused rather than served. - /// Another instance at the same path encodes that group into different bytes, - /// so the tail this one would produce cannot continue the head a reader holds. - /// It is the relay's cue to give up on the group and move on to the next. + /// A fresh encode of that group need not match the bytes of the head a reader + /// holds, so its tail cannot continue it. The reader moves on to the next group. #[tokio::test] async fn a_mid_group_fetch_is_refused() { let source = source_catalog(320, 240); @@ -1336,9 +1335,9 @@ mod tests { transcoder.abort(); } - /// Two transcoders fed the same source are one broadcast: the same catalog, - /// and groups that mirror the source's sequences and timestamps. That is what - /// lets a relay move a subscription between them at a group boundary. + /// Two transcoders fed the same source publish the same catalog, and groups + /// that mirror the source's sequences and timestamps rather than anything + /// numbered per instance. #[tokio::test] async fn two_instances_publish_the_same_broadcast() { let source = source_broadcast(2, 5); diff --git a/rs/moq-transcode/src/rung.rs b/rs/moq-transcode/src/rung.rs index e7e995b3c47..e3aaec5cd41 100644 --- a/rs/moq-transcode/src/rung.rs +++ b/rs/moq-transcode/src/rung.rs @@ -8,8 +8,8 @@ //! for group until the track goes `unused` again. //! - A fetch of a specific group (`requested_group`) fetches that same group //! from the source and transcodes just that group with a fresh encoder. A -//! fetch that starts mid-group is refused: the frames are only valid after -//! the head this encoder produced. +//! fetch that starts mid-group is refused: a fresh encode's frames are only +//! valid after the head that same encode produced. //! //! Output groups mirror the source group sequence numbers 1:1, so a fetch for //! output group N maps to source group N and a player switching renditions @@ -483,10 +483,10 @@ fn spawn_fetch( /// "the handler vanished" and hides the actual decode/encode/source failure from /// the waiting consumer. async fn fetch(rung: Rung, request: moq_net::group::Request) -> Result<(), Error> { - // Another instance encodes the same source group into different bytes, so a - // tail from this encoder cannot continue a head someone else produced. A - // partial group is not ours to serve; refuse it so the reader moves on to the - // next group boundary instead of decoding a splice. + // A fresh encode of this group need not match the bytes the reader's head + // came from (the live encoder, or an earlier fetch), so its tail cannot + // continue that head. Refuse it so the reader moves on to the next group + // boundary instead of decoding a splice. if request.frame_start() != 0 { tracing::debug!( sequence = request.sequence(), From a7a831130a46807adb7dfbbbc25270b01c158a1f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 5 Oct 2026 12:26:14 -0700 Subject: [PATCH 6/8] quest: record per-worker epoch follow-ups for transcode and processors A worker finishes its output when its source epoch ends or is replaced, and every demand capability, external processors included, mints an epoch per worker. Describe the derived-output layout generically; moq.pro mounts it. Co-Authored-By: Claude Opus 5.5 --- quest/m0/broadcast-epoch/README.md | 2 +- quest/m0/wildcard/README.md | 23 ++++++++++++++--------- quest/m1/transcode-group-start.md | 18 ++++++++++++------ quest/m2/processor/README.md | 11 +++++++---- 4 files changed, 34 insertions(+), 20 deletions(-) diff --git a/quest/m0/broadcast-epoch/README.md b/quest/m0/broadcast-epoch/README.md index c8cbf73fd71..f6a055d7cb8 100644 --- a/quest/m0/broadcast-epoch/README.md +++ b/quest/m0/broadcast-epoch/README.md @@ -59,7 +59,7 @@ Decided: gates the release (decided 2026-10-05): a regression from #4741 on main that `release` lacks. - Derived output mirrors the source's bare name under an epoch each worker - mints (`.pro/transcode//foo.hang/@`, per the + mints (`/foo.hang/@`, per the [wildcard](/quest/m0/wildcard/README.md) line's derived-output layout, decided 2026-10-05), so two workers are two broadcasts and the service's prefix claim still covers both. diff --git a/quest/m0/wildcard/README.md b/quest/m0/wildcard/README.md index 2a496035a13..fccb1cb2313 100644 --- a/quest/m0/wildcard/README.md +++ b/quest/m0/wildcard/README.md @@ -191,22 +191,27 @@ identity or a generation field. ### Where derived output lives A prefix claim needs the variable part of a path trailing, so a fleet-wide -service claims its own prefix and mirrors the source's bare name beneath it -(`.pro/transcode//foo.hang`, moq.pro's convention) rather than publishing -beneath the source. Each worker publishes under its own epoch, -`.pro/transcode//foo.hang/@`, not the source's (decided -2026-10-05; see [Per-worker epochs](/quest/m1/transcode-group-start.md)). The -source's catalog reaches the contribution through a cross-broadcast reference. +service claims its own hidden prefix and mirrors the source's bare name beneath +it (`/foo.hang`, where `` starts with a `.` segment) rather +than publishing beneath the source. Each worker publishes under an epoch it +mints, `/foo.hang/@`, not the source's, and its catalog points +at the exact source epoch it transcodes (decided 2026-10-05; see +[Per-worker epochs](/quest/m1/transcode-group-start.md)). Every demand +capability follows the same rule, external processors included: each output +path carries an epoch minted for that one worker. The source's catalog reaches +the contribution through a cross-broadcast reference. moq.pro runs its +transcode fleet at `.transcode//foo.hang` and mounts it, so a customer +sees `/.pro/transcode/foo.hang`. The leading `.` is deliberate. Existing customers on moq-lite-06 or older must -never see `.pro/` broadcasts, which could confuse their business logic. Those -versions cannot opt into hidden routes, so the relay never announces them +never see hidden service broadcasts, which could confuse their business logic. +Those versions cannot opt into hidden routes, so the relay never announces them there. Hidden routes are a moq-lite-07 feature, so the player's covering check (Demand, done on the line branch) opts into them and sees a claim only when lite-07 is negotiated. Finalizing lite-07 is a rollout condition, not a blocker for this line (decided in the 2026-09-30 audit), since the check works whenever lite-07 is negotiated. A customer who wants transcodes upgrades, or -subscribes to the explicit `.pro//...` path, which works on any +subscribes to the explicit hidden service path, which works on any version. Grants and metering are the deployment's; moq.pro's are in its [wildcard questline](https://github.com/moq-dev/moq.pro/blob/main/quest/m2/wildcard/README.md). diff --git a/quest/m1/transcode-group-start.md b/quest/m1/transcode-group-start.md index 58caf4cea3d..732cc51f0c9 100644 --- a/quest/m1/transcode-group-start.md +++ b/quest/m1/transcode-group-start.md @@ -28,15 +28,19 @@ Decided 2026-10-05 by the maintainer: - Rejected: a moq-net `track::Info::whole_groups` serving policy (it never fires on the relay's own splice), resuming only at group boundaries, and byte-deterministic workers. -- Layout: the derived name mirrors the source's bare name, and the worker - appends an epoch it mints: `.pro/transcode//foo.hang/@`. The +- Layout: the derived name mirrors the source's bare name under the + service's hidden prefix, and the worker appends an epoch it mints: + `/foo.hang/@` (accepted 2026-10-05). The source's own epoch does not nest beneath it, because [Origin](/quest/m0/broadcast-epoch/origin.md) treats a path whose final segment is an epoch as pinned, so `foo.hang/@e/@w` could not be followed. The worker's catalog references the exact source epoch it transcodes, so - one derived broadcast is self-consistent, and a source restart is - transcoded under a newer worker epoch. The default CLI output + one derived broadcast is self-consistent. The default CLI output (`/transcode.hang`) gains the same trailing epoch. +- A worker finishes its output when its source epoch ends or is replaced by a + newer one (decided 2026-10-05), so a viewer of the bare derived name never + stays on a stale worker after a source restart. The restarted source is + transcoded under a newer worker epoch. - A caller may pass an explicit epoch; otherwise the worker mints one. The epoch segment adds a level to the catalog's relative source reference (`Config::source`). @@ -47,8 +51,10 @@ requested index, and a test pins two instances fed one source publishing the same catalog and group sequences. Left: mint and append the worker epoch in moq-transcode or the CLI, fix the -catalog's source reference, and test that two workers land on distinct paths -and a viewer of the derived name follows the newer one. Update +catalog's source reference, and finish the output when the source epoch ends +or is replaced. Test that two workers land on distinct paths and a viewer of +the derived name follows the newer one, and that a source restart finishes the +old worker's output so the viewer moves to the new one. Update `doc/bin/cli.md` and `doc/bin/obs.md`, which give the output path. Public API: possibly an epoch on the transcode output config. Wire: none. diff --git a/quest/m2/processor/README.md b/quest/m2/processor/README.md index 401ddba58f4..7f8d8c1642e 100644 --- a/quest/m2/processor/README.md +++ b/quest/m2/processor/README.md @@ -4,8 +4,9 @@ A customer runs a worker in its own environment, connects outbound to a MoQ deployment, reads only eligible source media, and publishes an on-demand -contribution under the processor's own prefix, mirroring the source path -(for example `.pro//`, the +contribution under the processor's own prefix, mirroring the source's bare +name under an epoch minted for that one worker (for example +`//@`, the [wildcard](/quest/m0/wildcard/README.md) line's derived-output layout). The platform supplies registration, scoped credentials, routing, demand, status, and usage @@ -23,8 +24,10 @@ Decided: derived output follows [Wildcard](/quest/m0/wildcard/README.md)'s service-prefix layout, not `/.pro`. Suffix routing is dropped everywhere, and a prefix claim needs the variable part of the path trailing, so the processor claims its prefix and mirrors the source path -beneath it. The source's catalog reaches the output through a -cross-broadcast reference ([media contract](/quest/m2/processor/media-contract.md)). +beneath it. Each worker appends an epoch it mints (decided 2026-10-05, as for +[transcode workers](/quest/m1/transcode-group-start.md)), so two workers' +different output never shares a name. The source's catalog reaches the output +through a cross-broadcast reference ([media contract](/quest/m2/processor/media-contract.md)). Deferred to m2 in the 2026-09-30 audit: no processor customer is committed, and its end-to-end proof (processor-vision) was deleted. From b91c6901f3d9e5a40cebd0d989ec53174733122d Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 5 Oct 2026 15:13:23 -0700 Subject: [PATCH 7/8] fix(transcode): trim to the mid-group fetch refusal Revert the per-worker epoch re-plan of the transcode, wildcard, broadcast-epoch, and processor quests so it is decided with #4817, and drop the catalog-equality assertion from the two-instance test. Co-Authored-By: Claude Opus 5.5 --- quest/m0/broadcast-epoch/README.md | 9 ++- quest/m0/wildcard/README.md | 54 +++++++-------- quest/m0/wildcard/transcode-group-start.md | 77 +++++----------------- quest/m3/processor/README.md | 11 ++-- rs/moq-transcode/src/lib.rs | 27 ++++---- 5 files changed, 61 insertions(+), 117 deletions(-) diff --git a/quest/m0/broadcast-epoch/README.md b/quest/m0/broadcast-epoch/README.md index 505715a00b2..141a6f8ff53 100644 --- a/quest/m0/broadcast-epoch/README.md +++ b/quest/m0/broadcast-epoch/README.md @@ -63,11 +63,10 @@ Decided: release) moved under it, and the OBS half of GStreamer and OBS moved to m1 as [OBS publishes under epochs](/quest/m1/obs-epoch.md), so the release gate no longer waits on m1 work. -- Derived output mirrors the source's bare name under an epoch each worker - mints (`/foo.hang/@`, per the - [wildcard](/quest/m0/wildcard/README.md) line's derived-output layout, decided - 2026-10-05), so two workers are two broadcasts and the service's prefix claim - still covers both. +- Derived output mirrors the epoch it came from + (`.pro/transcode//foo.hang/@e`, per the + [wildcard](/quest/m0/wildcard/README.md) line's derived-output layout), so + the service's prefix claim still covers it. This README owns: diff --git a/quest/m0/wildcard/README.md b/quest/m0/wildcard/README.md index 3a779be52f8..b53579c9d35 100644 --- a/quest/m0/wildcard/README.md +++ b/quest/m0/wildcard/README.md @@ -78,9 +78,8 @@ specificity, and rebasing tokens and filters reuse. Content identity is the path: it names one broadcast whoever serves it, and any covering route resumes a subscription from the first frame the subscriber lacks (#4741). The `@` segment (#4706) is what makes a restart a new -path. So this questline settles collisions by giving each claim worker its own -epoch, so different content never shares a path, rather than with a route -identity or a generation field. +path. So this questline settles collisions with interchangeable output at one +path, not with a route identity or a generation field. ### Decisions @@ -160,17 +159,19 @@ identity or a generation field. the client's ordinary resubscribe resolves again. Scanning unserved paths costs one round trip per path. No negative cache; rate limiting stays with the advertiser and the per-project auth gate. -- **A double claim is settled by per-worker names, not by route identity or - a lease.** Two relays can hash one derived name to different workers before - either concrete announcement propagates. Two encoders' bytes differ, and a - path is one broadcast whoever serves it (#4741 resumes mid-group from any - covering route), so each worker publishes under an epoch it mints - ([Per-worker epochs](/quest/m0/wildcard/transcode-group-start.md)). The two workers - are then two broadcasts, a viewer follows the newest like any epoch - takeover, and a relay never splices them. Wildcard routing invents neither - a lease nor a generation. That quest is Required here (decided 2026-10-04, - revised 2026-10-05 from interchangeable output at one path, which a relay's - own mid-group resume defeats). +- **A double claim is settled by interchangeable output, not by route + identity or a lease.** Two relays can hash one path to different workers + before either concrete announcement propagates, and both land at the SAME + literal path. A path is one broadcast whoever serves it, so claim workers + mirror the source's epoch and group numbers, publish a deterministic + catalog, and start at group boundaries + ([Transcoders start at group boundaries](/quest/m0/wildcard/transcode-group-start.md)). + Two workers at one path are then one broadcast, and a relay moving between + them does so at a group boundary (decided 2026-10-03: #4741 drops + first-hop identity, so routing can no longer tell two workers apart). + Wildcard routing invents neither a lease nor a generation. That quest is + Required here (decided 2026-10-04), so this line cannot ship with workers + that can be spliced mid-group. - **A serving front follows the best route.** A join or re-price re-selects every front below the prefix, and a front moves when another route now wins: cheaper, or the rendezvous winner among equal costs (decided @@ -191,27 +192,20 @@ identity or a generation field. ### Where derived output lives A prefix claim needs the variable part of a path trailing, so a fleet-wide -service claims its own hidden prefix and mirrors the source's bare name beneath -it (`/foo.hang`, where `` starts with a `.` segment) rather -than publishing beneath the source. Each worker publishes under an epoch it -mints, `/foo.hang/@`, not the source's, and its catalog points -at the exact source epoch it transcodes (decided 2026-10-05; see -[Per-worker epochs](/quest/m0/wildcard/transcode-group-start.md)). Every demand -capability follows the same rule, external processors included: each output -path carries an epoch minted for that one worker. The source's catalog reaches -the contribution through a cross-broadcast reference. moq.pro runs its -transcode fleet at `.transcode//foo.hang` and mounts it, so a customer -sees `/.pro/transcode/foo.hang`. +service claims its own prefix and mirrors the source path beneath it +(`.pro/transcode//foo.hang`, moq.pro's convention) rather than publishing +beneath the source. The source's catalog reaches the contribution through a +cross-broadcast reference. The leading `.` is deliberate. Existing customers on moq-lite-06 or older must -never see hidden service broadcasts, which could confuse their business logic. -Those versions cannot opt into hidden routes, so the relay never announces them +never see `.pro/` broadcasts, which could confuse their business logic. Those +versions cannot opt into hidden routes, so the relay never announces them there. Hidden routes are a moq-lite-07 feature, so the player's covering check (Demand, done on the line branch) opts into them and sees a claim only when lite-07 is negotiated. Finalizing lite-07 is a rollout condition, not a blocker for this line (decided in the 2026-09-30 audit), since the check works whenever lite-07 is negotiated. A customer who wants transcodes upgrades, or -subscribes to the explicit hidden service path, which works on any +subscribes to the explicit `.pro//...` path, which works on any version. Grants and metering are the deployment's; moq.pro's are in its [wildcard questline](https://github.com/moq-dev/moq.pro/blob/main/quest/m2/wildcard/README.md). @@ -223,7 +217,7 @@ distinguish recording generations reads the catalog's archive entry ## Required -- [Per-worker epochs](/quest/m0/wildcard/transcode-group-start.md) - each transcode worker publishes under its own epoch, so a relay never splices two workers' output +- [Transcoders start at group boundaries](/quest/m0/wildcard/transcode-group-start.md) - two claim workers at one path are one broadcast, so a relay never splices them mid-group - [A standing refusal ends the front](/quest/m0/wildcard/refusal-final.md) - a refusal from the winning route ends the request instead of re-selecting a sibling or a shorter prefix ## Related @@ -231,6 +225,6 @@ distinguish recording generations reads the catalog's archive entry - [archive](/quest/m1/archive/README.md) - an archive claims the root, and its catalog names the generations a claim cannot - [Broadcast epochs](/quest/m0/broadcast-epoch/README.md) - derived output - mirrors the source's bare name under a worker-minted epoch + mirrors the source path, `@` segment included - [Announcement shapes](/quest/m2/announce-shapes.md) - moq-lite-only exact, suffix, and prefix+suffix claims that survive relay hops diff --git a/quest/m0/wildcard/transcode-group-start.md b/quest/m0/wildcard/transcode-group-start.md index 732cc51f0c9..0502ad10abb 100644 --- a/quest/m0/wildcard/transcode-group-start.md +++ b/quest/m0/wildcard/transcode-group-start.md @@ -1,69 +1,28 @@ -# [S] Per-worker transcode epochs +# [S] Transcoders start at group boundaries ## Goal -Two moq-transcode workers never share a broadcast name. Each worker -(`rs/moq-transcode`, and `moq transcode` in moq-cli) publishes its output under -an epoch it mints, so two encoders' different bytes are two broadcasts. A -viewer of the derived name follows the newest worker's epoch, like any other -epoch takeover, and a relay never splices one worker's group into another's. - -Non-goals: byte-identical output across workers, and a deterministic catalog -(stable rung names, a pinned encoder kind). Neither is needed once each worker -is its own broadcast. +Two moq-transcode instances serving one derived path are interchangeable at +group boundaries, so a relay moving a subscription between them never splices +two encoders' output mid-group. moq-transcode (`rs/moq-transcode`, and +`moq transcode` in moq-cli) resolves a subscription that starts at (N, M>0) +to (N+1, 0), and refuses a FETCH that starts mid-group. Output groups mirror +the source's sequence numbers, and the catalog derives only from the input and +config. ## Plan -Decided 2026-10-05 by the maintainer: - -- The splice is closed by per-worker names. Two workers that double-claim one - derived path under the [wildcard](/quest/m0/wildcard/README.md) line encode - the same source group into different bytes. If they shared a name, a - #4741 route move would make the relay continue group N at frame M from the - other worker's copy (`Recover::poll_serving` in - `rs/moq-net/src/model/resume.rs` subscribes the new copy from frame 0 and - splices with `start_at(M)` itself), which no moq-transcode policy can - refuse. A name reused for different content is a bug (AGENTS.md), so each - worker gets its own. -- Rejected: a moq-net `track::Info::whole_groups` serving policy (it never - fires on the relay's own splice), resuming only at group boundaries, and - byte-deterministic workers. -- Layout: the derived name mirrors the source's bare name under the - service's hidden prefix, and the worker appends an epoch it mints: - `/foo.hang/@` (accepted 2026-10-05). The - source's own epoch does not nest beneath it, because - [Origin](/quest/m0/broadcast-epoch/origin.md) treats a path whose final - segment is an epoch as pinned, so `foo.hang/@e/@w` could not be followed. - The worker's catalog references the exact source epoch it transcodes, so - one derived broadcast is self-consistent. The default CLI output - (`/transcode.hang`) gains the same trailing epoch. -- A worker finishes its output when its source epoch ends or is replaced by a - newer one (decided 2026-10-05), so a viewer of the bare derived name never - stays on a stale worker after a source restart. The restarted source is - transcoded under a newer worker epoch. -- A caller may pass an explicit epoch; otherwise the worker mints one. The - epoch segment adds a level to the catalog's relative source reference - (`Config::source`). - -Done in [#4812](https://github.com/moq-dev/moq/pull/4812): the rung's fetch -handler refuses a mid-group FETCH instead of writing the whole group at the -requested index, and a test pins two instances fed one source publishing the -same catalog and group sequences. - -Left: mint and append the worker epoch in moq-transcode or the CLI, fix the -catalog's source reference, and finish the output when the source epoch ends -or is replaced. Test that two workers land on distinct paths and a viewer of -the derived name follows the newer one, and that a source restart finishes the -old worker's output so the viewer moves to the new one. Update -`doc/bin/cli.md` and `doc/bin/obs.md`, which give the output path. - -Public API: possibly an epoch on the transcode output config. Wire: none. - -## Required +- The lite draft already lets a publisher skip a group it cannot serve from + the requested frame and resolve to a later one, so no wire change. +- Output groups already mirror the source's sequences (`rung.rs`). Keep that, + and check that nothing per-process (start time, random ids, encoder + defaults) leaks into the catalog. +- Tests: a subscription and a FETCH that start mid-group, and two instances + fed the same source that publish the same catalog and group sequences. +- Done in [#4812](https://github.com/moq-dev/moq/pull/4812): the rung refuses a mid-group FETCH; the rest waits on [#4817](https://github.com/moq-dev/moq/pull/4817)'s bare-path rule. -- [Origin](/quest/m0/broadcast-epoch/origin.md) - viewers of a bare name follow its newest live epoch, which is how a derived-name viewer finds the current worker +Public API: none. Wire: none. ## Related -- [Wildcard](/quest/m0/wildcard/README.md) - a double claim's two workers are two broadcasts, so a relay never splices them -- [Broadcast epochs](/quest/m0/broadcast-epoch/README.md) - the epoch rules the worker's own epoch follows +- [Wildcard](/quest/m0/wildcard/README.md) - a double claim's two workers at one path are settled by interchangeable output diff --git a/quest/m3/processor/README.md b/quest/m3/processor/README.md index 7841faf2f0a..1a127f53ce2 100644 --- a/quest/m3/processor/README.md +++ b/quest/m3/processor/README.md @@ -4,9 +4,8 @@ A customer runs a worker in its own environment, connects outbound to a MoQ deployment, reads only eligible source media, and publishes an on-demand -contribution under the processor's own prefix, mirroring the source's bare -name under an epoch minted for that one worker (for example -`//@`, the +contribution under the processor's own prefix, mirroring the source path +(for example `.pro//`, the [wildcard](/quest/m0/wildcard/README.md) line's derived-output layout). The platform supplies registration, scoped credentials, routing, demand, status, and usage @@ -25,10 +24,8 @@ service-prefix layout, not `/.pro`. Processor output does not use suffix routing ([announcement shapes](/quest/m2/announce-shapes.md) may add it to moq-lite separately), and a prefix claim needs the variable part of the path trailing, so the processor claims its prefix and mirrors the source path -beneath it. Each worker appends an epoch it mints (decided 2026-10-05, as for -[transcode workers](/quest/m0/wildcard/transcode-group-start.md)), so two workers' -different output never shares a name. The source's catalog reaches the output -through a cross-broadcast reference ([media contract](/quest/m3/processor/media-contract.md)). +beneath it. The source's catalog reaches the output through a +cross-broadcast reference ([media contract](/quest/m3/processor/media-contract.md)). Deferred in the 2026-09-30 audit and moved to m3 in the 2026-10-05 audit: no processor customer is committed, and its end-to-end proof (processor-vision) was deleted. diff --git a/rs/moq-transcode/src/lib.rs b/rs/moq-transcode/src/lib.rs index e714e9d3167..6d7d1ce8e5a 100644 --- a/rs/moq-transcode/src/lib.rs +++ b/rs/moq-transcode/src/lib.rs @@ -1335,11 +1335,11 @@ mod tests { transcoder.abort(); } - /// Two transcoders fed the same source publish the same catalog, and groups - /// that mirror the source's sequences and timestamps rather than anything - /// numbered per instance. + /// Two transcoders fed the same source publish groups that mirror the + /// source's sequences and timestamps rather than anything numbered per + /// instance. #[tokio::test] - async fn two_instances_publish_the_same_broadcast() { + async fn two_instances_mirror_source_groups() { let source = source_broadcast(2, 5); let config = Config { ladder: Ladder::new([Rung::new(120, moq_net::bandwidth::Rate::from_bps(100_000))]).unwrap(), @@ -1349,7 +1349,11 @@ mod tests { ..Default::default() }; - let mut instances = Vec::new(); + // Mirrored from the source, not numbered by either instance. + let expected: Vec<_> = (0..2u64) + .map(|sequence| (sequence, (0..5).map(|i| (sequence * 5 + i) as u128 * 33_333).collect::>())) + .collect(); + for _ in 0..2 { let output = moq_net::broadcast::Info::default().produce(); let consumer = output.consume(); @@ -1363,7 +1367,7 @@ mod tests { } }; let mut catalogs = moq_mux::catalog::hang::Consumer::<()>::new(track.subscribe(None).await.unwrap()); - let catalog = await_catalog(&mut catalogs, |snapshot| { + await_catalog(&mut catalogs, |snapshot| { snapshot.video.renditions.contains_key("video/120p") }) .await; @@ -1380,18 +1384,9 @@ mod tests { groups.push((fetched.sequence, timestamps)); } - instances.push((catalog, groups)); + assert_eq!(groups, expected); transcoder.abort(); } - - let (first, second) = (&instances[0], &instances[1]); - assert_eq!(first.0, second.0, "the two instances published different catalogs"); - assert_eq!(first.1, second.1, "the two instances published different groups"); - // Mirrored from the source, not numbered by either instance. - let expected: Vec<_> = (0..2u64) - .map(|sequence| (sequence, (0..5).map(|i| (sequence * 5 + i) as u128 * 33_333).collect())) - .collect(); - assert_eq!(first.1, expected); } /// A source whose codec description changes rebuilds the shared decode, so From af2601dba3fce9ddf76311ef7248111d4b25338f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 5 Oct 2026 15:40:51 -0700 Subject: [PATCH 8/8] fix(transcode): rustfmt the two-instance test; note the dropped catalog check Co-Authored-By: Claude Opus 5.5 --- quest/m0/wildcard/transcode-group-start.md | 6 +++++- rs/moq-transcode/src/lib.rs | 7 ++++++- 2 files changed, 11 insertions(+), 2 deletions(-) diff --git a/quest/m0/wildcard/transcode-group-start.md b/quest/m0/wildcard/transcode-group-start.md index 0502ad10abb..1496afdb675 100644 --- a/quest/m0/wildcard/transcode-group-start.md +++ b/quest/m0/wildcard/transcode-group-start.md @@ -19,7 +19,11 @@ config. defaults) leaks into the catalog. - Tests: a subscription and a FETCH that start mid-group, and two instances fed the same source that publish the same catalog and group sequences. -- Done in [#4812](https://github.com/moq-dev/moq/pull/4812): the rung refuses a mid-group FETCH; the rest waits on [#4817](https://github.com/moq-dev/moq/pull/4817)'s bare-path rule. +- Done in [#4812](https://github.com/moq-dev/moq/pull/4812): the rung refuses a + mid-group FETCH, and two instances mirror the source's group sequences and + timestamps. The two-instance catalog check is dropped until + [#4817](https://github.com/moq-dev/moq/pull/4817) decides whether the catalog + must be deterministic; the rest waits on its bare-path rule. Public API: none. Wire: none. diff --git a/rs/moq-transcode/src/lib.rs b/rs/moq-transcode/src/lib.rs index 6d7d1ce8e5a..9587f07b599 100644 --- a/rs/moq-transcode/src/lib.rs +++ b/rs/moq-transcode/src/lib.rs @@ -1351,7 +1351,12 @@ mod tests { // Mirrored from the source, not numbered by either instance. let expected: Vec<_> = (0..2u64) - .map(|sequence| (sequence, (0..5).map(|i| (sequence * 5 + i) as u128 * 33_333).collect::>())) + .map(|sequence| { + ( + sequence, + (0..5).map(|i| (sequence * 5 + i) as u128 * 33_333).collect::>(), + ) + }) .collect(); for _ in 0..2 {