From 0e440a4e4b59ac4f108188ce7a6ab405a493b9de Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Wed, 21 Oct 2026 22:35:21 -0700 Subject: [PATCH 01/14] quest: claim m1/archive/subscribe-tracks-outbound Co-Authored-By: Claude Opus 5.5 From bf0bd8afd1c2d50dc1fea8d48409bd7f4bbbdb27 Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Wed, 21 Oct 2026 23:02:48 -0700 Subject: [PATCH 02/14] feat(ietf): list a moq-transport peer's tracks with SUBSCRIBE_TRACKS (wip) Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/ietf/adapter.rs | 2 + rs/moq-net/src/ietf/error.rs | 3 + rs/moq-net/src/ietf/publisher.rs | 6 + rs/moq-net/src/ietf/publisher/tracks.rs | 14 +- rs/moq-net/src/ietf/subscribe.rs | 18 +- rs/moq-net/src/ietf/subscribe_tracks.rs | 44 +- rs/moq-net/src/ietf/subscriber.rs | 259 +++- rs/moq-net/src/ietf/subscriber/tracks.rs | 1186 +++++++++++++++++++ rs/moq-net/tests/integration/main.rs | 1 + rs/moq-net/tests/integration/tracks_ietf.rs | 221 ++++ 10 files changed, 1703 insertions(+), 51 deletions(-) create mode 100644 rs/moq-net/src/ietf/subscriber/tracks.rs create mode 100644 rs/moq-net/tests/integration/tracks_ietf.rs diff --git a/rs/moq-net/src/ietf/adapter.rs b/rs/moq-net/src/ietf/adapter.rs index 8b4c5a78567..8b0a4e2d92f 100644 --- a/rs/moq-net/src/ietf/adapter.rs +++ b/rs/moq-net/src/ietf/adapter.rs @@ -1565,6 +1565,7 @@ mod tests { forward: Some(false), filter: Some(ietf::Filter::NextObject), authorization_token: None, + fill: None, }; let body = encode_body(&update, version); let raw = encode_raw(ietf::SubscribeUpdate::ID, &body, version); @@ -2232,6 +2233,7 @@ mod tests { forward: Some(true), filter: Some(ietf::Filter::NextObject), authorization_token: None, + fill: None, }; let update = encode_raw(ietf::SubscribeUpdate::ID, &encode_body(&update, VERSION), VERSION); // The target is in the window and the update's own ID is past it. diff --git a/rs/moq-net/src/ietf/error.rs b/rs/moq-net/src/ietf/error.rs index 23e5abb67df..de60a3a2142 100644 --- a/rs/moq-net/src/ietf/error.rs +++ b/rs/moq-net/src/ietf/error.rs @@ -194,6 +194,9 @@ pub(crate) mod request { /// A second subscription to a track the peer already subscribes to. Draft-16 and later. pub(crate) const DUPLICATE_SUBSCRIPTION: u64 = 0x19; + /// The endpoint is overloaded and cannot process the request. Draft-18 and later. + pub(crate) const EXCESSIVE_LOAD: u64 = 0x9; + /// A SUBSCRIBE_NAMESPACE or SUBSCRIBE_TRACKS prefix overlapping an established one. /// Draft-15 and later. pub(crate) const PREFIX_OVERLAP: u64 = 0x30; diff --git a/rs/moq-net/src/ietf/publisher.rs b/rs/moq-net/src/ietf/publisher.rs index 3f98a8c421d..60d868d19c3 100644 --- a/rs/moq-net/src/ietf/publisher.rs +++ b/rs/moq-net/src/ietf/publisher.rs @@ -7251,6 +7251,7 @@ mod serve_tests { forward: Some(forward), filter: None, authorization_token: None, + fill: None, } .encode_msg(&mut Encoder::new(&mut body, version.into()), version) .unwrap(); @@ -7369,6 +7370,7 @@ mod serve_tests { forward: None, filter: None, authorization_token: None, + fill: None, } .encode_msg(&mut Encoder::new(&mut body, version.into()), version) .unwrap(); @@ -7565,6 +7567,7 @@ mod serve_tests { forward: Some(true), filter: None, authorization_token: None, + fill: None, } .encode_msg(&mut Encoder::new(&mut body, version.into()), version) .unwrap(); @@ -11578,6 +11581,7 @@ mod serve_tests { forward: Some(true), filter: None, authorization_token: Some(request_token()), + fill: None, }; writer.varint(ietf::SubscribeUpdate::ID).await.unwrap(); writer.encode(&msg).await.unwrap(); @@ -11892,6 +11896,7 @@ mod serve_tests { forward: Some(true), filter: None, authorization_token: Some(request_token()), + fill: None, }; writer.varint(ietf::SubscribeUpdate::ID).await.unwrap(); writer.encode(&msg).await.unwrap(); @@ -11919,6 +11924,7 @@ mod serve_tests { forward: Some(true), filter: None, authorization_token: None, + fill: None, }; writer.varint(ietf::SubscribeUpdate::ID).await.unwrap(); writer.encode(&msg).await.unwrap(); diff --git a/rs/moq-net/src/ietf/publisher/tracks.rs b/rs/moq-net/src/ietf/publisher/tracks.rs index 888637e605e..3054fd37888 100644 --- a/rs/moq-net/src/ietf/publisher/tracks.rs +++ b/rs/moq-net/src/ietf/publisher/tracks.rs @@ -1375,6 +1375,7 @@ mod tests { authorization_token: None, new_group: None, max_age: None, + fill: None, } } @@ -1808,7 +1809,8 @@ mod tests { } async fn resume_asks_for_a_new_group(on_listing: bool) { - let version = Version::Draft22; + // Draft-22 sends no NEW_GROUP_REQUEST on SUBSCRIBE_TRACKS. + let version = Version::Draft21; let mut h = harness(version); let live = h .broadcast @@ -1993,11 +1995,12 @@ mod tests { } } - /// A paused listing's FILL_PARAMETERS (draft-20+) open no fill, even once a PUBLISH - /// resumes without its own (draft-22 section 3.4.1). + /// A paused listing's FILL_PARAMETERS (draft-20 and draft-21; draft-22 sends none on + /// SUBSCRIBE_TRACKS) open no fill, even once a PUBLISH resumes without its own + /// (draft-22 section 3.4.1). #[moq_clock::test] async fn a_listing_fill_opens_nothing() { - for version in [Version::Draft20, Version::Draft22] { + for version in [Version::Draft20, Version::Draft21] { let mut h = harness(version); let video = h.tracks.remove("video").unwrap(); let mut group = video.append_group().unwrap(); @@ -2096,9 +2099,10 @@ mod tests { /// From draft-20 each PUBLISH states the listing's subscription parameters, which the /// subscriber otherwise takes as the defaults; earlier drafts carry them on PUBLISH_OK. + /// Draft-22 sends none of them on SUBSCRIBE_TRACKS. #[moq_clock::test] async fn a_listing_states_its_parameters_on_each_publish() { - for version in DRAFTS { + for version in DRAFTS.into_iter().filter(|version| *version != Version::Draft22) { let mut h = harness(version); let request = ietf::SubscribeTracks { subscriber_priority: Some(7), diff --git a/rs/moq-net/src/ietf/subscribe.rs b/rs/moq-net/src/ietf/subscribe.rs index 3967895258c..b06a940c9cd 100644 --- a/rs/moq-net/src/ietf/subscribe.rs +++ b/rs/moq-net/src/ietf/subscribe.rs @@ -434,6 +434,9 @@ pub struct SubscribeUpdate { pub new_group: Option, /// Subscriber max age in milliseconds (MoQ Timestamp), if negotiated. pub max_age: Option, + /// FILL_PARAMETERS (0x23, draft-20+): the backfill a paused PUBLISH subscription takes as + /// it resumes (draft-20 section 3.6.2). + pub fill: Option, } impl Message for SubscribeUpdate { @@ -484,6 +487,7 @@ impl Message for SubscribeUpdate { 0x10 => self.forward, 0x20 => self.subscriber_priority, 0x21 => self.filter, + 0x23 => self.fill.filter(|_| Filter::is_draft20(version)), 0x32 => self.new_group, super::max_age::PARAMETER => self.max_age, ); @@ -519,6 +523,7 @@ impl Message for SubscribeUpdate { authorization_token, new_group: None, max_age: super::max_age::validate(max_age)?, + fill: None, }) } Version::Draft15 | Version::Draft16 => { @@ -545,6 +550,7 @@ impl Message for SubscribeUpdate { authorization_token: super::token::single(authorization_token)?, new_group, max_age: super::max_age::validate(max_age)?, + fill: None, }) } _ => { @@ -553,7 +559,7 @@ impl Message for SubscribeUpdate { if matches!(version, Version::Draft17) { let _required_request_id_delta = r.varint()?; } - // Nothing reads an update's FILL_PARAMETERS or Range Filters yet; they are + // Nothing reads an update's Range Filters yet; they are // consumed so a legal update does not fail the session. decode_params!(r, version, 0x02 => _object_delivery_timeout: Option, @@ -562,7 +568,7 @@ impl Message for SubscribeUpdate { 0x10 => forward: Option, 0x20 => subscriber_priority: Option, 0x21 => filter: Option, - 0x23 => _fill: Option where Filter::is_draft20(version), + 0x23 => fill: Option where Filter::is_draft20(version), 0x25 => _subgroup_filter: Vec where has_range_filters(version), 0x26 => _object_id_filter: Vec where has_range_filters(version), 0x27 => _priority_filter: Vec where has_range_filters(version), @@ -583,6 +589,7 @@ impl Message for SubscribeUpdate { authorization_token: super::token::single(authorization_token)?, new_group, max_age: super::max_age::validate(max_age)?, + fill, }) } } @@ -650,6 +657,7 @@ mod tests { filter: None, authorization_token: None, new_group: None, + fill: None, }; let decoded: SubscribeUpdate = decode_message(&encode_message(&update, version), version).unwrap(); assert_eq!(decoded.max_age, max_age, "{version}"); @@ -766,6 +774,7 @@ mod tests { forward: None, filter: None, authorization_token: None, + fill: None, }; let decoded: SubscribeUpdate = decode_message(&encode_message(&update, version), version).unwrap(); assert_eq!(decoded.new_group, expected, "{version}: REQUEST_UPDATE"); @@ -1144,6 +1153,7 @@ mod tests { forward: Some(true), filter: Some(Filter::NextObject), authorization_token: None, + fill: None, }; let encoded = encode_message(&msg, Version::Draft15); @@ -1168,6 +1178,7 @@ mod tests { forward: Some(true), filter: Some(Filter::NextObject), authorization_token: None, + fill: None, }; let encoded = encode_message(&msg, Version::Draft14); @@ -1281,6 +1292,7 @@ mod tests { forward: Some(true), filter: Some(Filter::NextObject), authorization_token: None, + fill: None, }; let encoded = encode_message(&msg, Version::Draft17); @@ -1530,6 +1542,7 @@ mod tests { forward: Some(true), filter: Some(Filter::NextObject), authorization_token: None, + fill: None, }; let encoded = encode_message(&msg, Version::Draft18); @@ -1557,6 +1570,7 @@ mod tests { forward: Some(true), filter: Some(Filter::NextObject), authorization_token: None, + fill: None, }; let v18_msg = SubscribeUpdate { ..v17_msg.clone() }; diff --git a/rs/moq-net/src/ietf/subscribe_tracks.rs b/rs/moq-net/src/ietf/subscribe_tracks.rs index 64c7b2a26d0..5dba72a7103 100644 --- a/rs/moq-net/src/ietf/subscribe_tracks.rs +++ b/rs/moq-net/src/ietf/subscribe_tracks.rs @@ -58,16 +58,19 @@ impl Message for SubscribeTracks<'_> { encode_namespace(w, &self.prefix)?; // Absent means 1, so only a paused listing writes it. let include_properties = (!self.properties_wanted && Filter::is_draft20(version)).then_some(false); - // Draft-18 allows only AUTHORIZATION_TOKEN and FORWARD here. + // Draft-18 allows only AUTHORIZATION_TOKEN and FORWARD here. Draft-22 section 9.18 + // lists GROUP_ORDER but no longer SUBSCRIBER_PRIORITY, LOCATION_FILTER, + // FILL_PARAMETERS, or NEW_GROUP_REQUEST, which a resuming REQUEST_UPDATE carries. let defaults = version != Version::Draft18; + let subscription = defaults && version != Version::Draft22; encode_params!(w, version, 0x03 => self.authorization_token.clone(), 0x10 => (!self.forward).then_some(false), - 0x20 => self.subscriber_priority.filter(|_| defaults), - 0x21 => self.filter.filter(|_| defaults), + 0x20 => self.subscriber_priority.filter(|_| subscription), + 0x21 => self.filter.filter(|_| subscription), 0x22 => self.group_order.filter(|_| defaults), - 0x23 => self.fill.filter(|_| Filter::is_draft20(version)), - 0x32 => self.new_group.filter(|_| defaults), + 0x23 => self.fill.filter(|_| subscription && Filter::is_draft20(version)), + 0x32 => self.new_group.filter(|_| subscription), 0x35 => include_properties, ); Ok(()) @@ -269,6 +272,37 @@ mod tests { assert!(decode::(&bytes, Version::Draft18).is_err()); } + /// Draft-22 section 9.18 no longer lists SUBSCRIBER_PRIORITY, LOCATION_FILTER, + /// FILL_PARAMETERS, or NEW_GROUP_REQUEST, so none is sent there; GROUP_ORDER still is. + /// Section 3.6.2 still allows any subscription parameter, so one received is read. + #[test] + fn draft_22_sends_only_its_listed_parameters() { + let listing = SubscribeTracks { + subscriber_priority: Some(7), + filter: Some(Filter::NextObject), + fill: Some(super::super::Fill { + filter: Some(Filter::NextObject), + range_filters: false, + }), + new_group: Some(0), + ..paused() + }; + let ordered = SubscribeTracks { + group_order: Some(GroupOrder::Ascending), + ..paused() + }; + let with_order = SubscribeTracks { + group_order: Some(GroupOrder::Ascending), + ..listing.clone() + }; + let version = Version::Draft22; + assert_eq!(encode(&listing, version), encode(&paused(), version)); + assert_eq!(encode(&with_order, version), encode(&ordered, version)); + let decoded: SubscribeTracks = decode(&encode(&listing, Version::Draft21), version).unwrap(); + assert_eq!(decoded.subscriber_priority, Some(7)); + assert_eq!(decoded.new_group, Some(0)); + } + #[test] fn subscribe_tracks_starts_at_draft_18() { let mut buf = Vec::new(); diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index 2c36057b310..dd47f20555f 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -19,6 +19,8 @@ use crate::tail::{Reading, Settle, Tail}; use kio::Lock; +mod tracks; + const TRACK_ALIAS_TIMEOUT: Duration = Duration::from_secs(1); /// How many cancelled aliases to remember. Objects keep arriving for about a round trip @@ -763,8 +765,11 @@ pub(super) struct Subscriber { auth: crate::auth::Handle, // What this session may allocate up front for objects still arriving. frames: frame::Budget, - // Namespaces the peer may have announced at once (`session::Limits::announces`). + // Namespaces the peer may have announced at once (`session::Limits::announces`), and + // tracks it lists to us. pub(super) announces: crate::session::Slots, + // What SUBSCRIBE_TRACKS lists of the peer's tracks. + listings: Lock>, } /// The prefixes to issue SUBSCRIBE_NAMESPACE for: `origin`'s permitted scope, @@ -858,6 +863,7 @@ where auth: crate::auth::Handle::new(false), frames: Default::default(), announces: Default::default(), + listings: Default::default(), validity: Default::default(), epoch: None, } @@ -1384,7 +1390,7 @@ where } tracing::debug!(message = ?msg, "received publish"); async move { - if let Err(err) = this.run_publish_stream(stream, msg).await { + if let Err(err) = this.serve_publish(stream, msg).await { tracing::debug!(%err, "publish stream error"); } } @@ -2571,6 +2577,13 @@ where ) -> Result<(), Error> { let mut subscribes = TaskSet::owned(); let mut closed_session = self.session.clone(); + // Answers the source's listings with the peer's tracks, while anyone lists it. + let lister = std::sync::Arc::new( + broadcast + .lister() + .expect("only the source answers its broadcast's listings"), + ); + let mut listening = None; loop { let next = subscribes .drive(|waiter| { @@ -2578,6 +2591,7 @@ where if closed_session.poll_closed(&mut cx).is_ready() { return Poll::Ready(None); } + self.poll_listing(&path, &lister, &mut listening, waiter); loop { if let Poll::Ready(next) = broadcast.poll_requested_track(waiter) { return Poll::Ready(Some(next)); @@ -2601,6 +2615,7 @@ where Some(Ok(request)) => request, Some(Err(err)) => { tracing::debug!(%err, "broadcast closed"); + drop(listening.take()); // No new tracks, but those in flight run to their own end. self.drain(&mut subscribes).await; break; @@ -2622,6 +2637,43 @@ where Ok(()) } + /// Answer the source's listings while anyone lists it, from a SUBSCRIBE_TRACKS covering + /// it; a failed listing ends its readers, which ask again. + fn poll_listing( + &self, + path: &Path<'_>, + lister: &std::sync::Arc, + listening: &mut Option>, + waiter: &kio::Waiter, + ) { + loop { + match listening { + None => { + if !matches!(lister.poll_used(waiter), Poll::Ready(Ok(()))) { + return; + } + if !super::subscribe_tracks::has_subscribe_tracks(self.version) { + // An empty answer would claim the peer lists nothing. + lister.abort(Error::Unsupported); + continue; + } + *listening = Some(self.listen(path.to_owned(), lister.clone())); + } + Some(_) if lister.poll_unused(waiter).is_ready() => { + *listening = None; + lister.clear(); + } + Some(current) => match current.poll_failed(waiter) { + Poll::Ready(err) => { + *listening = None; + lister.abort(err); + } + Poll::Pending => return, + }, + } + } + } + async fn run_subscribe( &mut self, broadcast_path: Path<'_>, @@ -2735,32 +2787,73 @@ where } }; + // A listed track's paused subscription is already this track's upstream copy, so + // resume it rather than open a second one. + let key: tracks::TrackKey = (broadcast_path.to_owned(), track_name.into()); + let mut adopting = self.want(&key); + // Retirement and revocation cancel only the wait for an ID. On drafts 14-16 the peer // grants MAX_REQUEST_ID credit back only for requests it receives, so an allocated ID // is always sent; the response wait below cancels it if either landed meanwhile. let mut timeout = crate::time::Deadline::after(&self.runtime, Control::REQUEST_ID_TIMEOUT); - let request_id = kio::wait(|waiter| { + let acquired = kio::wait(|waiter| { if gate.poll_denied(waiter).is_ready() { return Poll::Ready(Err(Error::Unauthorized)); } validity.check(waiter)?; - self.control.poll_credit(waiter, &mut timeout) + if let Some(handoff) = &adopting { + match Self::poll_handoff(handoff, waiter) { + Poll::Ready(Some(upstream)) => return Poll::Ready(Ok(Err(upstream))), + Poll::Ready(None) => adopting = None, + Poll::Pending => return Poll::Pending, + } + } + self.control.poll_credit(waiter, &mut timeout).map(|id| id.map(Ok)) }) .await; - let request_id = match request_id { - Ok(id) => id, + let acquired = match acquired { + Ok(acquired) => acquired, Err(err) => { + if let Some(handoff) = &adopting { + self.unwant(key, handoff); + } target.fail(err); return None; } }; - let mut stream = match Stream::open(&mut self.session.clone(), self.version).await { - Ok(s) => s, - Err(err) => { - tracing::debug!(%err, "failed to open subscribe stream"); - target.fail(err); - return None; + // The resumed subscription's alias, properties, and owed answers, when resuming one. + let mut held: Option = None; + let (request_id, mut stream, mut messages) = match acquired { + Ok(request_id) => { + let stream = match Stream::open(&mut self.session.clone(), self.version).await { + Ok(s) => s, + Err(err) => { + tracing::debug!(%err, "failed to open subscribe stream"); + target.fail(err); + return None; + } + }; + let messages = super::request_stream::Messages::new(self.session.clone(), self.control.client()); + (request_id, stream, messages) + } + Err(upstream) => { + self.adopted(&key, upstream.request_id); + let tracks::Upstream { + stream, + messages, + request_id, + alias, + properties, + owed, + } = upstream; + held = Some(tracks::Resumed { + alias, + properties, + owed, + ended: None, + }); + (request_id, stream, messages) } }; @@ -2773,6 +2866,16 @@ where }); { let mut state = self.state.lock(); + // A resumed subscription keeps the alias it is bound to and the data streams it + // counted while it forwarded before. + let (alias, tail) = match held.is_some() { + true => state + .subscribes + .remove(&request_id) + .map(|held| (held.alias, held.tail)) + .unwrap_or_default(), + false => Default::default(), + }; state.subscribes.insert( request_id, TrackState { @@ -2783,6 +2886,8 @@ where // A resumed copy is the session's to abort from here on. producer: target.producer().cloned(), epoch: self.epoch.clone(), + alias, + tail, ..TrackState::pending(track_name.to_owned(), broadcast_path.to_owned(), fill.clone(), joining) }, ); @@ -2807,34 +2912,53 @@ where let new_group = target .new_group() .filter(|_| super::subscribe::has_new_group_request(self.version)); - let written = async { - stream.writer.varint(ietf::Subscribe::ID).await?; - stream - .writer - .encode(&ietf::Subscribe { - max_age, - new_group, - request_id, - track_namespace: broadcast_path.to_owned(), - track_name: track_name.into(), - subscriber_priority: super::priority::to_wire(priority), - group_order: order.into(), - filter: join.filter, - fill: join.fill, - // A resumed copy already knows the track, from the answer that accepted it. - properties_wanted: matches!(target, Target::Request(_)), + let written = match &held { + // Resume the held subscription: its group order is the one it was made with, + // since no update can change it. + Some(held) => { + let forward = tracks::Forward { forward: true, - rendezvous: false, - range_filters: false, - authorization_token: None, - epoch: self.epoch.clone(), - }) + filter: Some(join.filter), + fill: join.fill, + priority: Some(priority), + max_age, + // Only a track declaring DYNAMIC_GROUPS takes one on an update. + new_group: new_group.filter(|_| held.properties.dynamic_groups), + }; + self.write_forward(&mut stream.writer, &forward).await + } + None => { + async { + stream.writer.varint(ietf::Subscribe::ID).await?; + stream + .writer + .encode(&ietf::Subscribe { + max_age, + new_group, + request_id, + track_namespace: broadcast_path.to_owned(), + track_name: track_name.into(), + subscriber_priority: super::priority::to_wire(priority), + group_order: order.into(), + filter: join.filter, + fill: join.fill, + // A resumed copy already knows the track, from the answer that accepted it. + properties_wanted: matches!(target, Target::Request(_)), + forward: true, + rendezvous: false, + range_filters: false, + authorization_token: None, + epoch: self.epoch.clone(), + }) + .await + } .await - } - .await; + } + }; if let Err(err) = written { tracing::debug!(%err, "failed to write subscribe"); self.remove_subscribe(request_id); + self.entry_ended(&key, request_id, Err(err.clone())); target.fail(err); return None; } @@ -2870,11 +2994,10 @@ where Gone, } - let mut messages = super::request_stream::Messages::new(self.session.clone(), self.control.client()); // A local terminal ended the wait, so the peer still holds the request to cancel. let mut unanswered = false; let setup = { - let mut response = std::pin::pin!(self.read_subscribe_response(&mut stream, &mut messages)); + let mut response = std::pin::pin!(self.read_answer(&mut stream, &mut messages, held.as_mut())); loop { let setup = kio::wait(|waiter| { let response = waiter.poll_future(response.as_mut()); @@ -2952,6 +3075,22 @@ where track = %track_name, "subscribe abandoned before it was accepted" ); + // A held subscription is still the track's entry: pause it again, owing the + // answer to the resume as well. + if let Some(held) = held + && self.state.lock().subscribes.contains_key(&request_id) + { + let upstream = tracks::Upstream { + stream, + messages, + request_id, + alias: held.alias, + properties: held.properties, + owed: held.owed + 1, + }; + self.pause(key, upstream).await; + return resumed; + } // The publisher may already be serving before it answers. A session abort // already rejected the parked request; dropping what remains is not a second one. let aborted = self.remove_subscribe(request_id).is_none(); @@ -2974,6 +3113,7 @@ where pending.reject(err.clone()); } self.remove_subscribe(request_id); + self.entry_ended(&key, request_id, Err(err.clone())); if let Some(idle) = resumed { let _ = idle.track.abort(err); } @@ -2986,6 +3126,7 @@ where pending.reject(Error::UnexpectedMessage); } self.remove_subscribe(request_id); + self.entry_ended(&key, request_id, Err(Error::UnexpectedMessage)); if let Some(idle) = resumed { let _ = idle.track.abort(Error::UnexpectedMessage); } @@ -2998,10 +3139,16 @@ where pending.reject(err.clone()); } self.remove_subscribe(request_id); + // A held subscription that the publisher ended before answering ends its + // entry as the PUBLISH_DONE says; one whose resume failed fails it, and is + // cancelled since its PUBLISH_DONE has yet to come. + let ended = held.as_mut().and_then(|held| held.ended.take()); + let cancel = unanswered || (held.is_some() && ended.is_none()); + self.entry_ended(&key, request_id, ended.unwrap_or_else(|| Err(err.clone()))); if let Some(idle) = resumed { let _ = idle.track.abort(err); } - if unanswered { + if cancel { self.cancel_subscribe(stream, request_id).await; } return None; @@ -3012,6 +3159,8 @@ where properties, largest, } = accepted; + // What a pause holds again: the properties the track was listed with. + let held_properties = properties.clone(); // A resumed copy opts out of the properties from draft-20, so it keeps the units it // learned. Before that the answer declares them again. let timescale = properties @@ -3090,7 +3239,11 @@ where } } } - if let Err(err) = self.register_alias(request_id, alias) { + self.entry_info(&key, request_id, track.info()); + // A resumed subscription stays bound to the alias it was held with. + if held.is_none() + && let Err(err) = self.register_alias(request_id, alias) + { if matches!(err, Error::Duplicate) { tracing::warn!(track_alias = %alias, "publisher reused a live track alias for another track"); self.session.close( @@ -3148,6 +3301,8 @@ where let mut fetch_done = fetching.is_none(); // Our grant stopped covering the track, which is aborted rather than kept lingering. let mut revoked = false; + // How the upstream subscription ended, which ends a listing entry it held. + let mut ended: Option> = None; let mut demand = track.demand(); // Nobody subscribing at all (only fetches asked) needs no subscription. let mut subscribed = track.subscription().is_some(); @@ -3239,6 +3394,7 @@ where let (asked, new_group, asked_age) = (update.priority, update.new_group, update.max_age); if let Err(err) = self.write_update(&mut stream.writer, request_id, update).await { tracing::debug!(%err, "failed to update the subscription"); + ended = Some(Err(err.clone())); let _ = track.clone().abort(err); break false; } @@ -3259,6 +3415,7 @@ where tracing::info!(broadcast = %self.origin.absolute(broadcast_path), track = %track_name, "subscription no longer authorized"); let _ = track.clone().abort(Error::Unauthorized); revoked = true; + ended = Some(Err(Error::Unauthorized)); break true; } End::Fetch(request) => { @@ -3275,6 +3432,7 @@ where break true; } End::Done(res) => { + ended = Some(tracks::unlisted(res.as_ref().map(|_| ()).map_err(Clone::clone))); match res { Ok(count) => { tracing::info!(broadcast = %self.origin.absolute(broadcast_path), track = %track_name, "subscribe complete"); @@ -3328,6 +3486,28 @@ where // Release an unallocated join now, or let the session finish its committed header. drop(fetching); + if let Some(end) = ended { + self.entry_ended(&key, request_id, end); + } else if idle && self.is_entry(&key, request_id) && self.state.lock().subscribes.contains_key(&request_id) { + // A listed track's subscription pauses rather than ends, held again as its entry. + track.set_idle(); + let upstream = tracks::Upstream { + stream, + messages, + request_id, + alias, + properties: held_properties, + owed: unanswered.load(Ordering::Relaxed), + }; + self.pause(key, upstream).await; + return Some(Idle { + demand: track.demand(), + track, + dynamic, + timescale, + }); + } + // Clean up let aborted = self.remove_subscribe(request_id).is_none(); @@ -3521,6 +3701,7 @@ where filter: None, authorization_token: None, new_group: update.new_group, + fill: None, }) .await } diff --git a/rs/moq-net/src/ietf/subscriber/tracks.rs b/rs/moq-net/src/ietf/subscriber/tracks.rs new file mode 100644 index 00000000000..6a35db36d86 --- /dev/null +++ b/rs/moq-net/src/ietf/subscriber/tracks.rs @@ -0,0 +1,1186 @@ +//! Lists a moq-transport peer's tracks through the TRACKS hook (draft-18+). +//! +//! A listed broadcast sends SUBSCRIBE_TRACKS with FORWARD=0, and each track it lists is +//! one paused subscription held for the session: the PUBLISH the peer answers with, +//! accepted paused, or for a track the peer skips, a SUBSCRIBE we open paused. That +//! subscription is both the listing entry, removed by its PUBLISH_DONE with TRACK_ENDED, +//! and the track's upstream copy: a reader resumes it with REQUEST_UPDATE and pauses it +//! again once the last one leaves, rather than opening a second subscription. +//! +//! One SUBSCRIBE_TRACKS covers each nesting chain of listed broadcasts, since the peer +//! refuses an overlapping prefix: a nested listing reuses the broader request and filters +//! locally, and a broader one replaces the nested requests once the peer has closed them, +//! keeping the subscriptions they made. Any end of a held subscription other than +//! TRACK_ENDED fails every listing its request serves, which then asks again, rather +//! than hide a track that may still be live. + +use std::sync::Arc; + +use super::*; +use crate::AsPath as _; +use crate::ietf::request_stream::{self, Framed, Messages}; + +/// A listed track, by its namespace and name. +pub(super) type TrackKey = (PathOwned, Arc); + +/// How a PUBLISH_DONE ending `end` leaves the listing: TRACK_ENDED removes the track, and +/// so does INTERNAL_ERROR, which is what our own answerer sends once a track is no longer +/// listed (PUBLISH_DONE registers no DOES_NOT_EXIST). Any other status fails the listing, +/// so it asks again rather than hide a track that may still be live. +pub(super) fn unlisted(end: Result<(), Error>) -> Result<(), Error> { + match end { + Err(Error::Remote(code)) if u64::from(code) == ietf::PublishDoneStatus::InternalError.code(Version::Draft18) => { + Ok(()) + } + end => end, + } +} + +/// A paused upstream subscription and the request stream that controls it. +pub(super) struct Upstream { + pub(super) stream: Stream, + pub(super) messages: Messages, + pub(super) request_id: RequestId, + pub(super) alias: u64, + /// The Track Properties the PUBLISH or SUBSCRIBE_OK declared. + pub(super) properties: ietf::Properties, + /// REQUEST_UPDATE answers still owed, read before anything else. + pub(super) owed: u64, +} + +/// Hands a paused subscription from the task watching it to a subscription resuming it. +pub(super) struct Handoff { + /// A subscription asked for it. + wanted: bool, + /// Handed over by the watcher. + upstream: Option>, + /// The entry was let go, so the watcher cancels the subscription. + gone: bool, +} + +impl Default for Handoff { + fn default() -> Self { + Self { + wanted: false, + upstream: None, + gone: false, + } + } +} + +/// One listed track and the upstream subscription that holds it. +struct Entry { + /// Its TRACK_INFO, once known: a paused SUBSCRIBE learns it from its SUBSCRIBE_OK. + info: Option, + /// The subscription holding it, once known. + request_id: Option, + /// Set while it is paused, or still opening, and a watcher owns it. `None` while a + /// subscription forwarding it owns it. + handoff: Option>>, + /// Discovery state the peer makes us hold, as for a lite listed track. + _slot: crate::session::Slot, +} + +impl Drop for Entry { + fn drop(&mut self) { + if let Some(handoff) = &self.handoff { + handoff.lock().gone = true; + } + } +} + +/// A broadcast listed through this session. +struct Listener { + path: PathOwned, + lister: Arc, + /// Set to the error that fails the listing. + failed: kio::Producer>, +} + +/// One SUBSCRIBE_TRACKS, from when it is wanted until the peer has closed it. +struct Request { + prefix: PathOwned, + /// Dropped to cancel it; `None` once cancelled, while it leaves the wire. + live: Option>, + /// Closes once it is off the wire, so an overlapping one may go out. + gone: kio::Consumer<()>, +} + +/// The session's listings of the peer's tracks. +pub(super) struct Listings { + listeners: HashMap, + requests: HashMap, + entries: HashMap>, + next: u64, +} + +impl Default for Listings { + fn default() -> Self { + Self { + listeners: HashMap::new(), + requests: HashMap::new(), + entries: HashMap::new(), + next: 0, + } + } +} + +/// A SUBSCRIBE_TRACKS for its task to send. +struct Opening { + key: u64, + prefix: PathOwned, + /// The overlapping requests that must leave the wire first. + blockers: Vec>, + live: kio::Consumer<()>, + gone: kio::Producer<()>, +} + +impl Listings { + fn key(&mut self) -> u64 { + self.next += 1; + self.next + } + + /// The standing request that covers `namespace`; at most one does. + fn covering(&self, namespace: &PathOwned) -> Option { + self.requests + .iter() + .find(|(_, request)| request.live.is_some() && namespace.has_prefix(&request.prefix)) + .map(|(key, _)| *key) + } + + fn listers<'a>(&'a self, namespace: &'a PathOwned) -> impl Iterator + 'a { + self.listeners + .values() + .filter(move |listener| &listener.path == namespace) + .map(|listener| &*listener.lister) + } + + fn listen(&mut self, path: PathOwned, lister: Arc) -> (u64, kio::Consumer>, Option) { + // What a broader listing already holds is listed at once. + for ((namespace, name), entry) in &self.entries { + if namespace == &path + && let Some(info) = &entry.info + { + let _ = lister.add(name.clone(), info.clone()); + } + } + // This hop never waits on its upstream: later tracks follow as live adds. + lister.synced(); + let failed = kio::Producer::new(None); + let consumer = failed.consume(); + let key = self.key(); + self.listeners.insert( + key, + Listener { + path: path.clone(), + lister, + failed, + }, + ); + if self.covering(&path).is_some() { + return (key, consumer, None); + } + // Nested requests give way to this broader one, which keeps what they hold. + for request in self.requests.values_mut() { + if request.prefix.has_prefix(&path) { + request.live = None; + } + } + let blockers = self + .requests + .values() + .filter(|request| request.prefix.has_prefix(&path) || path.has_prefix(&request.prefix)) + .map(|request| request.gone.clone()) + .collect(); + let live = kio::Producer::new(()); + let gone = kio::Producer::new(()); + let request = self.key(); + self.requests.insert( + request, + Request { + prefix: path.clone(), + gone: gone.consume(), + live: Some(live.clone()), + }, + ); + let opening = Opening { + key: request, + prefix: path, + blockers, + live: live.consume(), + gone, + }; + (key, consumer, Some(opening)) + } + + fn unlisten(&mut self, key: u64) { + self.listeners.remove(&key); + self.release(); + } + + /// Cancel each standing request nobody lists under, and let go of each held track no + /// standing request covers. + fn release(&mut self) { + for request in self.requests.values_mut() { + if request.live.is_some() + && !self + .listeners + .values() + .any(|listener| listener.path.has_prefix(&request.prefix)) + { + request.live = None; + } + } + let standing: Vec = self + .requests + .values() + .filter(|request| request.live.is_some()) + .map(|request| request.prefix.clone()) + .collect(); + self.entries + .retain(|(namespace, _), _| standing.iter().any(|prefix| namespace.has_prefix(prefix))); + } + + /// Fail every listing the request covering `namespace` serves with `err`, and cancel it: + /// they ask again rather than miss a track that may still be live. + fn fail(&mut self, namespace: &PathOwned, err: Error) { + let Some(key) = self.covering(namespace) else { + return; + }; + let request = self.requests.get_mut(&key).expect("covering"); + request.live = None; + let prefix = request.prefix.clone(); + tracing::debug!(%prefix, %err, "track listing failed"); + for listener in self.listeners.values() { + if listener.path.has_prefix(&prefix) + && let Ok(mut failed) = listener.failed.write() + { + *failed = Some(err.clone()); + } + } + self.release(); + } + + fn insert(&mut self, key: TrackKey, entry: Entry) { + if let Some(info) = &entry.info { + for lister in self.listers(&key.0) { + let _ = lister.add(key.1.clone(), info.clone()); + } + } + self.entries.insert(key, entry); + } + + fn remove(&mut self, key: &TrackKey) { + let Some(entry) = self.entries.remove(key) else { + return; + }; + if entry.info.is_some() { + for lister in self.listers(&key.0) { + let _ = lister.remove(&key.1); + } + } + } + + /// The entry held by the subscription with `request_id`, if this is it. + fn held_by(&mut self, key: &TrackKey, request_id: RequestId) -> Option<&mut Entry> { + self.entries + .get_mut(key) + .filter(|entry| entry.request_id == Some(request_id)) + } + + /// The entry `handoff` belongs to, if it still stands. + fn watched_by(&mut self, key: &TrackKey, handoff: &kio::Shared>) -> Option<&mut Entry> { + self.entries.get_mut(key).filter(|entry| { + entry + .handoff + .as_ref() + .is_some_and(|held| held.same_channel(handoff)) + }) + } + + /// End the entry held by the subscription with `request_id`: TRACK_ENDED unlists it, + /// and anything else fails its listings. + fn ended(&mut self, key: &TrackKey, request_id: RequestId, end: Result<(), Error>) { + if self.held_by(key, request_id).is_none() { + return; + } + match end { + Ok(()) => self.remove(key), + Err(err) => { + self.remove(key); + self.fail(&key.0, err); + } + } + } +} + +/// A broadcast's listing through this session, until dropped. +pub(super) struct Listening { + listings: kio::Lock>, + key: u64, + failed: kio::Consumer>, +} + +impl Listening { + /// Ready with the error that failed the listing. + pub(super) fn poll_failed(&self, waiter: &kio::Waiter) -> Poll { + match self.failed.poll(waiter, |failed| match &**failed { + Some(err) => Poll::Ready(err.clone()), + None => Poll::Pending, + }) { + Poll::Ready(Ok(err)) => Poll::Ready(err), + Poll::Ready(Err(_)) => Poll::Ready(Error::Cancel), + Poll::Pending => Poll::Pending, + } + } +} + +impl Drop for Listening { + fn drop(&mut self) { + self.listings.lock().unlisten(self.key); + } +} + +/// What to do with a PUBLISH. +enum Offer { + /// No listing asked for it. + Unsolicited, + /// Refused with this code and reason. + Refuse(u64, &'static str), + /// Accepted paused and held as the entry `handoff` watches. + Hold(kio::Shared>), +} + +impl Subscriber +where + S: crate::transport::poll::Boxable, +{ + /// List `path`'s tracks into `lister` until the returned guard drops, through a + /// SUBSCRIBE_TRACKS covering it. + pub(super) fn listen(&self, path: PathOwned, lister: Arc) -> Listening { + let (key, failed, opening) = self.listings.lock().listen(path, lister); + if let Some(opening) = opening { + let this = self.clone(); + self.tasks.push(this.run_subscribe_tracks(opening)); + } + Listening { + listings: self.listings.clone(), + key, + failed, + } + } + + /// Send one SUBSCRIBE_TRACKS and read its answers until it is cancelled and the peer + /// has closed it, or it fails. + async fn run_subscribe_tracks(self, opening: Opening) { + let Opening { + key, + prefix, + blockers, + live, + gone, + } = opening; + let result = self.subscribe_tracks(&prefix, blockers, &live).await; + let mut listings = self.listings.lock(); + if let Err(err) = result + && listings.requests.get(&key).is_some_and(|request| request.live.is_some()) + { + listings.fail(&prefix, err); + } + listings.requests.remove(&key); + listings.release(); + drop(listings); + // Off the wire: an overlapping request may go out. + drop(gone); + } + + async fn subscribe_tracks( + &self, + prefix: &PathOwned, + blockers: Vec>, + live: &kio::Consumer<()>, + ) -> Result<(), Error> { + // The peer refuses a prefix overlapping one it still holds, so wait for each + // overlapping request to leave the wire. + let proceed = kio::wait(|waiter| { + if live.poll_closed(waiter).is_ready() { + return Poll::Ready(false); + } + for blocker in &blockers { + if blocker.poll_closed(waiter).is_pending() { + return Poll::Pending; + } + } + Poll::Ready(true) + }) + .await; + if !proceed { + return Ok(()); + } + + let mut session = self.session.clone(); + let opened = { + let mut opening = std::pin::pin!(Stream::open(&mut session, self.version)); + kio::wait(|waiter| { + if live.poll_closed(waiter).is_ready() { + return Poll::Ready(None); + } + waiter.poll_future(opening.as_mut()).map(Some) + }) + .await + }; + let Some(stream) = opened else { + return Ok(()); + }; + let mut stream = stream?; + // No draft with SUBSCRIBE_TRACKS has MAX_REQUEST_ID, so this never waits on credit. + let request_id = kio::wait(|waiter| self.control.poll_next_request_id(waiter)).await; + stream.writer.buffer_varint(ietf::SubscribeTracks::ID)?; + stream.writer.buffer(&ietf::SubscribeTracks { + request_id, + prefix: prefix.as_path(), + forward: false, + subscriber_priority: None, + group_order: None, + filter: None, + fill: None, + properties_wanted: true, + new_group: None, + range_filters: false, + track_filter: false, + authorization_token: None, + })?; + tracing::debug!(prefix = %self.origin.absolute(prefix), id = %request_id, "subscribe_tracks started"); + + let mut messages = Messages::new(self.session.clone(), self.control.client()); + let mut established = false; + enum Event { + Closed, + Cancelled, + Message(Option), + } + loop { + let event = kio::wait(|waiter| { + let mut cx = waiter.context(); + if session.poll_closed(&mut cx).is_ready() { + return Poll::Ready(Ok(Event::Closed)); + } + if live.poll_closed(waiter).is_ready() { + return Poll::Ready(Ok(Event::Cancelled)); + } + ready!(stream.writer.poll_flush(&mut cx))?; + messages + .poll_next(&mut stream.reader, &mut cx) + .map(|next| next.map(Event::Message)) + }) + .await?; + let Framed(id, body) = match event { + Event::Closed => return Ok(()), + Event::Cancelled => break, + // The peer ended the listing, which only a cancel of ours should do. + Event::Message(None) if established => return Err(Error::Closed), + Event::Message(None) => return Err(messages.failed(Error::ProtocolViolation)), + Event::Message(Some(framed)) => framed, + }; + match id { + ietf::RequestOk::ID if !established => { + body.message::(self.version) + .map_err(|err| messages.failed(err.into()))?; + established = true; + } + ietf::RequestError::ID if !established => { + let refused = body + .message::(self.version) + .map_err(|err| messages.failed(err.into()))?; + tracing::debug!(prefix = %prefix, code = refused.error_code, reason = %refused.reason_phrase, "subscribe_tracks refused"); + return Err(request::from_code( + refused.error_code, + request::Kind::SubscribeNamespace, + self.version, + )); + } + ietf::PublishSkipped::ID if established => { + let skipped = body + .message::(self.version) + .map_err(|err| messages.failed(err.into()))?; + let namespace = prefix.join(&skipped.suffix); + self.skipped(namespace, skipped.track_name.as_ref().into()); + } + _ => return Err(messages.failed(Error::UnexpectedMessage)), + } + } + + // Cancelled: close our half (FIN on draft-18, RESET_STREAM from draft-19, where a + // FIN is not a cancel), then read until the peer closes its own. The PUBLISHes it + // made stay ours. + tracing::debug!(prefix = %self.origin.absolute(prefix), "subscribe_tracks cancelled"); + let Stream { mut writer, mut reader } = stream; + match request_stream::fin_cancels(self.version) { + true => { + let _ = writer.finish(); + } + false => writer.abort(&Error::Cancel), + } + kio::wait(|waiter| { + let mut cx = waiter.context(); + if session.poll_closed(&mut cx).is_ready() { + return Poll::Ready(()); + } + loop { + match ready!(messages.poll_next(&mut reader, &mut cx)) { + Ok(Some(_)) => continue, + Ok(None) | Err(_) => return Poll::Ready(()), + } + } + }) + .await; + Ok(()) + } + + /// A fresh subscription of ours to `name` in `namespace`, and its info once accepted. + fn subscribed(&self, namespace: &PathOwned, name: &str) -> Option<(RequestId, Option)> { + let state = self.state.lock(); + state + .subscribes + .iter() + .find(|(_, track)| track.broadcast == *namespace && track.name == name) + .map(|(id, track)| (*id, track.producer.as_ref().map(|producer| producer.info().clone()))) + } + + /// The peer skipped a listed track: list it through a subscription of ours, opening + /// one paused if we have none. + fn skipped(&self, namespace: PathOwned, name: Arc) { + let key = (namespace, name); + let mut listings = self.listings.lock(); + if listings.entries.contains_key(&key) || listings.covering(&key.0).is_none() { + return; + } + let slot = match self.announces.acquire() { + Ok(slot) => slot, + Err(err) => return listings.fail(&key.0, err), + }; + if let Some((request_id, info)) = self.subscribed(&key.0, &key.1) { + let entry = Entry { + info, + request_id: Some(request_id), + handoff: None, + _slot: slot, + }; + return listings.insert(key, entry); + } + let handoff = kio::Shared::>::default(); + let entry = Entry { + info: None, + request_id: None, + handoff: Some(handoff.clone()), + _slot: slot, + }; + listings.insert(key.clone(), entry); + drop(listings); + let this = self.clone(); + self.tasks.push(async move { + match this.open_paused(&key, &handoff).await { + Ok(Some(upstream)) => this.watch(key, upstream, handoff).await, + Ok(None) => {} + Err(err) => { + tracing::debug!(broadcast = %key.0, track = %key.1, %err, "paused subscribe failed"); + let mut listings = this.listings.lock(); + if listings.watched_by(&key, &handoff).is_some() { + listings.remove(&key); + listings.fail(&key.0, err); + } + } + } + }); + } + + /// Open a paused SUBSCRIBE for a skipped track and list it once its SUBSCRIBE_OK + /// arrives. `None` once its entry was let go. + async fn open_paused(&self, key: &TrackKey, handoff: &kio::Shared>) -> Result>, Error> { + let gone = |waiter: &kio::Waiter| { + handoff + .poll(waiter, |handoff| match handoff.gone { + true => Poll::Ready(()), + false => Poll::Pending, + }) + .is_ready() + }; + let mut session = self.session.clone(); + let opened = { + let mut opening = std::pin::pin!(Stream::open(&mut session, self.version)); + kio::wait(|waiter| { + if gone(waiter) { + return Poll::Ready(None); + } + waiter.poll_future(opening.as_mut()).map(Some) + }) + .await + }; + let Some(stream) = opened else { + return Ok(None); + }; + let mut stream = stream?; + let request_id = kio::wait(|waiter| self.control.poll_next_request_id(waiter)).await; + self.state.lock().subscribes.insert( + request_id, + TrackState { + epoch: self.epoch.clone(), + ..TrackState::pending(key.1.to_string(), key.0.clone(), kio::Producer::new(Fill::Done), None) + }, + ); + let mut messages = Messages::new(self.session.clone(), self.control.client()); + let accepted = async { + stream.writer.varint(ietf::Subscribe::ID).await?; + stream + .writer + .encode(&ietf::Subscribe { + max_age: None, + new_group: None, + request_id, + track_namespace: key.0.as_path(), + track_name: key.1.as_ref().into(), + subscriber_priority: super::super::priority::to_wire(0), + group_order: GroupOrder::Ascending, + filter: Filter::NextObject, + fill: None, + properties_wanted: true, + forward: false, + rendezvous: false, + range_filters: false, + authorization_token: None, + epoch: self.epoch.clone(), + }) + .await?; + let mut response = std::pin::pin!(self.read_subscribe_response(&mut stream, &mut messages)); + let answered = kio::wait(|waiter| { + if gone(waiter) { + return Poll::Ready(None); + } + waiter.poll_future(response.as_mut()).map(Some) + }) + .await; + match answered { + Some(Ok(Some(accepted))) => Ok(Some(accepted)), + Some(Ok(None)) => Err(Error::UnexpectedMessage), + Some(Err(err)) => Err(err), + None => Ok(None), + } + } + .await; + let accepted = match accepted { + Ok(Some(accepted)) => accepted, + Ok(None) => { + self.remove_subscribe(request_id); + self.cancel_subscribe(stream, request_id).await; + return Ok(None); + } + Err(err) => { + self.remove_subscribe(request_id); + return Err(err); + } + }; + if let Some(err) = refused(&accepted.properties, self.version) { + self.remove_subscribe(request_id); + self.cancel_subscribe(stream, request_id).await; + return Err(err); + } + if let Err(err) = self.bind_alias(request_id, accepted.alias) { + self.remove_subscribe(request_id); + self.cancel_subscribe(stream, request_id).await; + return Err(err); + } + let info = accepted_info(&accepted.properties, self.version); + let listed = { + let mut listings = self.listings.lock(); + match listings.watched_by(key, handoff) { + Some(entry) => { + entry.request_id = Some(request_id); + entry.info = Some(info.clone()); + for lister in listings.listers(&key.0) { + let _ = lister.add(key.1.clone(), info.clone()); + } + true + } + None => false, + } + }; + if !listed { + self.remove_subscribe(request_id); + self.cancel_subscribe(stream, request_id).await; + return Ok(None); + } + Ok(Some(Upstream { + stream, + messages, + request_id, + alias: accepted.alias, + properties: accepted.properties, + owed: 0, + })) + } + + /// Bind the alias a held subscription's PUBLISH or SUBSCRIBE_OK chose, closing the + /// session if it names another track. + fn bind_alias(&self, request_id: RequestId, alias: u64) -> Result<(), Error> { + let err = match self.register_alias(request_id, alias) { + Ok(()) => return Ok(()), + Err(err) => err, + }; + if matches!(err, Error::Duplicate) { + tracing::warn!(track_alias = %alias, "publisher reused a live track alias for another track"); + self.session.clone().close( + super::super::error::to_session_code(&SessionError::from(&err)), + err.to_string().as_ref(), + ); + } + Err(err) + } + + /// Serve a PUBLISH: hold one answering our SUBSCRIBE_TRACKS paused as its track's entry, + /// refuse a redundant one, and decline one no listing asked for. + pub(super) async fn serve_publish(&mut self, mut stream: Stream, msg: ietf::Publish<'_>) -> Result<(), Error> { + let key: TrackKey = (msg.track_namespace.to_owned(), msg.track_name.as_ref().into()); + let info = accepted_info(&msg.properties, self.version); + let offer = { + let mut listings = self.listings.lock(); + // Draft-18 allows one subscription per track (section 5.1); later drafts allow + // more, but the one we hold already lists the track and carries its data. + let duplicate = match self.version { + Version::Draft18 => request::DUPLICATE_SUBSCRIPTION, + _ => request::to_code(&Error::Unroutable, request::Kind::Publish, self.version), + }; + if listings.covering(&key.0).is_none() { + match listings.requests.values().any(|request| key.0.has_prefix(&request.prefix)) { + true => Offer::Refuse( + request::to_code(&Error::Unroutable, request::Kind::Publish, self.version), + "listing cancelled", + ), + false => Offer::Unsolicited, + } + } else if listings.entries.contains_key(&key) { + Offer::Refuse(duplicate, "already subscribed") + } else if let Some(err) = refused(&msg.properties, self.version) { + Offer::Refuse( + request::to_code(&err, request::Kind::Publish, self.version), + "track properties not supported", + ) + } else { + match self.announces.acquire() { + Err(err) => { + listings.fail(&key.0, err); + Offer::Refuse(request::EXCESSIVE_LOAD, "too many listed tracks") + } + Ok(slot) => match self.subscribed(&key.0, &key.1) { + // Our own SUBSCRIBE holds the track, so it is the entry. + Some((request_id, _)) => { + let entry = Entry { + info: Some(info), + request_id: Some(request_id), + handoff: None, + _slot: slot, + }; + listings.insert(key.clone(), entry); + Offer::Refuse(duplicate, "already subscribed") + } + None => { + let handoff = kio::Shared::>::default(); + let entry = Entry { + info: Some(info), + request_id: Some(msg.request_id), + handoff: Some(handoff.clone()), + _slot: slot, + }; + listings.insert(key.clone(), entry); + Offer::Hold(handoff) + } + }, + } + } + }; + let handoff = match offer { + Offer::Unsolicited => return self.run_publish_stream(stream, msg).await, + Offer::Refuse(code, reason) => { + tracing::debug!(broadcast = %key.0, track = %key.1, reason, "refusing publish"); + let error = ietf::RequestError { + request_id: None, + error_code: code, + reason_phrase: reason.into(), + retry_interval: 0, + }; + return request_stream::reject(stream, error).await; + } + Offer::Hold(handoff) => handoff, + }; + + let request_id = msg.request_id; + self.state.lock().subscribes.insert( + request_id, + TrackState { + epoch: self.epoch.clone(), + ..TrackState::pending(key.1.to_string(), key.0.clone(), kio::Producer::new(Fill::Done), None) + }, + ); + let ok = async { + self.bind_alias(request_id, msg.track_alias)?; + // PUBLISH_OK is a REQUEST_OK from draft-19. FORWARD=0 holds it paused through + // draft-19; from draft-20 the PUBLISH our FORWARD=0 asked for already is. + let id = match self.version { + Version::Draft18 => ietf::PublishOk::ID, + _ => ietf::RequestOk::ID, + }; + stream.writer.varint(id).await?; + stream + .writer + .encode(&ietf::PublishOk { + request_id: None, + forward: false, + subscriber_priority: None, + group_order: None, + filter: None, + new_group: None, + }) + .await + } + .await; + if let Err(err) = ok { + tracing::debug!(broadcast = %key.0, track = %key.1, %err, "failed to hold publish"); + self.remove_subscribe(request_id); + let mut listings = self.listings.lock(); + if listings.watched_by(&key, &handoff).is_some() { + listings.remove(&key); + listings.fail(&key.0, err); + } + return Ok(()); + } + tracing::debug!(broadcast = %self.origin.absolute(&key.0), track = %key.1, id = %request_id, "holding publish"); + let upstream = Upstream { + stream, + messages: Messages::new(self.session.clone(), self.control.client()), + request_id, + alias: msg.track_alias, + properties: msg.properties, + owed: 0, + }; + self.watch(key, upstream, handoff).await; + Ok(()) + } + + /// Watch a paused subscription until it ends, its entry is let go, or a subscription + /// takes it to resume. + async fn watch(&self, key: TrackKey, mut upstream: Upstream, handoff: kio::Shared>) { + let mut session = self.session.clone(); + enum Step { + Closed, + Gone, + Wanted, + Message(Result, Error>), + } + let end = loop { + let step = kio::wait(|waiter| { + let mut cx = waiter.context(); + if session.poll_closed(&mut cx).is_ready() { + return Poll::Ready(Step::Closed); + } + if let Poll::Ready(handoff) = handoff.poll(waiter, |handoff| match handoff.gone || handoff.wanted { + true => Poll::Ready(()), + false => Poll::Pending, + }) { + return Poll::Ready(match handoff.gone { + true => Step::Gone, + false => Step::Wanted, + }); + } + upstream + .messages + .poll_next(&mut upstream.stream.reader, &mut cx) + .map(Step::Message) + }) + .await; + match step { + Step::Closed => return, + Step::Wanted => { + let upstream = { + let mut held = handoff.lock(); + match held.gone { + true => upstream, + false => { + held.upstream = Some(upstream); + return; + } + } + }; + self.remove_subscribe(upstream.request_id); + self.cancel_subscribe(upstream.stream, upstream.request_id).await; + return; + } + Step::Gone => { + self.remove_subscribe(upstream.request_id); + self.cancel_subscribe(upstream.stream, upstream.request_id).await; + return; + } + Step::Message(Ok(Some(Framed(id, body)))) => match id { + // The answer to a pause, or to a resume that paused again before it landed. + ietf::RequestOk::ID | ietf::RequestError::ID if upstream.owed > 0 => { + upstream.owed -= 1; + } + ietf::PublishDone::ID => { + break unlisted( + body.message::(self.version) + .map_err(|err| upstream.messages.failed(err.into())) + .and_then(|done| done.end(self.version)), + ); + } + _ => break Err(upstream.messages.failed(Error::UnexpectedMessage)), + }, + // PUBLISH_DONE must come before the FIN (draft-19 section 3.3.2). + Step::Message(Ok(None)) => break Err(Error::ProtocolViolation), + Step::Message(Err(err)) => break Err(err), + } + }; + tracing::debug!(broadcast = %key.0, track = %key.1, ?end, "held subscription ended"); + self.remove_subscribe(upstream.request_id); + let _ = upstream.stream.writer.finish(); + let mut listings = self.listings.lock(); + if listings.watched_by(&key, &handoff).is_some() { + match end { + Ok(()) => listings.remove(&key), + Err(err) => { + listings.remove(&key); + listings.fail(&key.0, err); + } + } + } + } + + /// Ask for the paused subscription a listing holds for this track, to resume it. + pub(super) fn want(&self, key: &TrackKey) -> Option>> { + let listings = self.listings.lock(); + let handoff = listings.entries.get(key)?.handoff.clone()?; + handoff.lock().wanted = true; + Some(handoff) + } + + /// Ready with the subscription `handoff` hands over, or `None` once it ended instead. + pub(super) fn poll_handoff(handoff: &kio::Shared>, waiter: &kio::Waiter) -> Poll>> { + let mut handoff = ready!(handoff.poll(waiter, |handoff| match handoff.gone || handoff.upstream.is_some() { + true => Poll::Ready(()), + false => Poll::Pending, + })); + Poll::Ready(handoff.upstream.take()) + } + + /// Give up wanting `handoff`, holding again what it already handed over. + pub(super) fn unwant(&self, key: TrackKey, handoff: &kio::Shared>) { + let upstream = { + let mut held = handoff.lock(); + held.wanted = false; + held.upstream.take() + }; + if let Some(upstream) = upstream { + self.hold(key, upstream); + } + } + + /// The subscription with `request_id` took over the entry it resumes. + pub(super) fn adopted(&self, key: &TrackKey, request_id: RequestId) { + if let Some(entry) = self.listings.lock().held_by(key, request_id) { + entry.handoff = None; + } + } + + /// Whether the subscription with `request_id` holds this track's listing entry, so + /// it pauses rather than ends once nobody reads it. + pub(super) fn is_entry(&self, key: &TrackKey, request_id: RequestId) -> bool { + self.listings + .lock() + .held_by(key, request_id) + .is_some_and(|entry| entry.handoff.is_none()) + } + + /// The subscription with `request_id` learned the info of the track it holds, which + /// lists it if a skip made it the entry before its SUBSCRIBE_OK. + pub(super) fn entry_info(&self, key: &TrackKey, request_id: RequestId, info: &track::Info) { + let mut listings = self.listings.lock(); + let Some(entry) = listings.held_by(key, request_id) else { + return; + }; + if entry.info.is_some() { + return; + } + entry.info = Some(info.clone()); + for lister in listings.listers(&key.0) { + let _ = lister.add(key.1.clone(), info.clone()); + } + } + + /// The subscription with `request_id` ended: so does the entry it held. + pub(super) fn entry_ended(&self, key: &TrackKey, request_id: RequestId, end: Result<(), Error>) { + self.listings.lock().ended(key, request_id, end); + } + + /// Hold a paused subscription again as its track's entry, watched until a reader + /// resumes it, or cancel it if the entry is gone. + pub(super) fn hold(&self, key: TrackKey, upstream: Upstream) { + let handoff = kio::Shared::>::default(); + let held = match self.listings.lock().held_by(&key, upstream.request_id) { + Some(entry) => { + entry.handoff = Some(handoff.clone()); + true + } + None => false, + }; + let this = self.clone(); + self.tasks.push(async move { + match held { + true => this.watch(key, upstream, handoff).await, + false => { + this.remove_subscribe(upstream.request_id); + this.cancel_subscribe(upstream.stream, upstream.request_id).await; + } + } + }); + } + + + /// Pause a subscription nobody reads that is its track's entry, and hold it again. + pub(super) async fn pause(&self, key: TrackKey, mut upstream: Upstream) { + self.park_subscribe(upstream.request_id); + let pause = Forward { + forward: false, + ..Default::default() + }; + match self.write_forward(&mut upstream.stream.writer, &pause).await { + Ok(()) => { + upstream.owed += 1; + tracing::debug!(broadcast = %key.0, track = %key.1, "subscription paused"); + self.hold(key, upstream); + } + Err(err) => { + tracing::debug!(%err, "failed to pause the subscription"); + self.remove_subscribe(upstream.request_id); + self.entry_ended(&key, upstream.request_id, Err(err)); + } + } + } + + /// Reset a subscription's state to paused, keeping the alias it is bound to: objects + /// still arriving for it are refused rather than buffered. + fn park_subscribe(&self, request_id: RequestId) { + let mut state = self.state.lock(); + let Some(held) = state.subscribes.get_mut(&request_id) else { + return; + }; + if let Ok(mut fill) = held.fill.write() { + fill.cancel(); + } + let parked = TrackState { + alias: held.alias, + epoch: held.epoch.clone(), + tail: std::mem::take(&mut held.tail), + ..TrackState::pending( + std::mem::take(&mut held.name), + held.broadcast.clone(), + kio::Producer::new(Fill::Done), + None, + ) + }; + let fetch_id = std::mem::replace(held, parked).fetch_id; + if let Some(fetch_id) = fetch_id { + state.fetches.remove(&fetch_id); + } + } + + /// Set a held subscription's Forward State with REQUEST_UPDATE. + pub(super) async fn write_forward( + &self, + writer: &mut Writer, + forward: &Forward, + ) -> Result<(), Error> { + let request_id = self.control.next_request_id(&self.runtime).await?; + writer.varint(ietf::SubscribeUpdate::ID).await?; + writer + .encode(&ietf::SubscribeUpdate { + max_age: forward.max_age, + request_id, + subscription_request_id: None, + start_location: ietf::Location { group: 0, object: 0 }, + end_group: 0, + subscriber_priority: forward.priority.map(super::super::priority::to_wire), + forward: Some(forward.forward), + filter: forward.filter, + authorization_token: None, + new_group: forward.new_group, + fill: forward.fill, + }) + .await + } + + /// Read the answer to a SUBSCRIBE, or to the REQUEST_UPDATE resuming `held`. + pub(super) async fn read_answer( + &self, + stream: &mut Stream, + messages: &mut Messages, + held: Option<&mut Resumed>, + ) -> Result, Error> { + let Some(held) = held else { + return self.read_subscribe_response(stream, messages).await; + }; + loop { + let Framed(id, body) = messages.message(&mut stream.reader).await?; + match id { + // The answer to a pause that went out before this resume. + ietf::RequestOk::ID | ietf::RequestError::ID if held.owed > 0 => held.owed -= 1, + ietf::RequestOk::ID => { + let ok = body.message::(self.version)?; + tracing::debug!(message = ?ok, "subscription resumed"); + return Ok(Some(Accepted { + alias: held.alias, + properties: held.properties.clone(), + largest: ok.largest, + })); + } + ietf::RequestError::ID => { + let refused = body.message::(self.version)?; + tracing::debug!(message = ?refused, "resume refused"); + return Err(request::from_code( + refused.error_code, + request::Kind::Subscribe, + self.version, + )); + } + ietf::PublishDone::ID => { + let done = body.message::(self.version)?; + let end = done.end(self.version); + held.ended = Some(unlisted(end.clone())); + return Err(end.err().unwrap_or(Error::NotFound)); + } + _ => return Err(Error::UnexpectedMessage), + } + } + } +} + +/// A REQUEST_UPDATE setting a held subscription's Forward State. +#[derive(Default)] +pub(super) struct Forward { + pub(super) forward: bool, + /// The Location Filter it resumes with. + pub(super) filter: Option, + /// FILL_PARAMETERS (draft-20+), the backfill it resumes with. + pub(super) fill: Option, + /// The aggregate priority, in the model's higher-first terms. + pub(super) priority: Option, + pub(super) max_age: Option, + pub(super) new_group: Option, +} + +/// What a subscription resuming a held one keeps of it. +pub(super) struct Resumed { + pub(super) alias: u64, + pub(super) properties: ietf::Properties, + /// REQUEST_UPDATE answers still owed. + pub(super) owed: u64, + /// How a PUBLISH_DONE ended it before the resume was answered. + pub(super) ended: Option>, +} diff --git a/rs/moq-net/tests/integration/main.rs b/rs/moq-net/tests/integration/main.rs index 58f5881ff01..c0dd9ba47a4 100644 --- a/rs/moq-net/tests/integration/main.rs +++ b/rs/moq-net/tests/integration/main.rs @@ -62,6 +62,7 @@ mod track_info_cancel; mod track_stream_demand; mod track_tail; mod tracks; +mod tracks_ietf; mod unannounce_release; mod untimed; mod wide_sequence; diff --git a/rs/moq-net/tests/integration/tracks_ietf.rs b/rs/moq-net/tests/integration/tracks_ietf.rs new file mode 100644 index 00000000000..7f15ea6fb36 --- /dev/null +++ b/rs/moq-net/tests/integration/tracks_ietf.rs @@ -0,0 +1,221 @@ +#![cfg(feature = "async")] + +//! A TRACKS listing over a moq-transport session (draft-18+): the subscriber sends +//! SUBSCRIBE_TRACKS with FORWARD=0 and holds each PUBLISH paused as its track's entry, which +//! a reader resumes for data instead of subscribing again. +//! +//! Deterministic: paused time and a single-threaded runtime over the mock transport. + +use crate::support; + +use std::time::Duration; + +use moq_net::broadcast::TracksEvent; +use moq_net::{Hop, Version}; +use support::harness::{MockConnectOptions, MockPair, connect_mock}; + +const TIMEOUT: Duration = Duration::from_secs(10); + +/// Every draft that has SUBSCRIBE_TRACKS. +const DRAFTS: [&str; 5] = [ + "moq-transport-18", + "moq-transport-19", + "moq-transport-20", + "moq-transport-21", + "moq-transport-22", +]; + +/// SUBSCRIBE (0x03), as the first byte of a request stream. +const SUBSCRIBE: u8 = 0x03; + +fn produce_origin(hop: u64) -> moq_net::origin::Producer { + let (producer, driver) = moq_net::origin::Producer::new(moq_net::origin::Config::new(Hop::new(hop).unwrap())); + support::harness::spawn(driver); + producer +} + +/// The next event as `+name`, `-name`, `synced`, `end`, or `error: ..`. +async fn next(tracks: &mut moq_net::broadcast::Tracks) -> String { + match moq_clock::timeout(TIMEOUT, tracks.next()) + .await + .expect("listing stalled") + { + Ok(Some(TracksEvent::Added { name, .. })) => format!("+{name}"), + Ok(Some(TracksEvent::Removed { name })) => format!("-{name}"), + Ok(Some(TracksEvent::Synced)) => "synced".into(), + Ok(None) => "end".into(), + Err(err) => format!("error: {err}"), + } +} + +/// Whether the listing has nothing more to report for a while. +async fn quiet(tracks: &mut moq_net::broadcast::Tracks) -> bool { + moq_clock::timeout(Duration::from_millis(500), tracks.next()) + .await + .is_err() +} + +/// `publisher` served to a fresh origin over one session; returns that origin's copy. +async fn connect(publisher: &moq_net::origin::Producer, version: &str) -> (moq_net::origin::Producer, MockPair) { + let subscriber = produce_origin(2); + let mut options = MockConnectOptions::new(version.parse::().unwrap()); + options.server_publish = Some(publisher.consume()); + options.client_subscribe = Some(subscriber.clone()); + let pair = connect_mock(options).await; + (subscriber, pair) +} + +async fn resolve(origin: &moq_net::origin::Producer, path: &str) -> moq_net::broadcast::Consumer { + moq_clock::timeout(TIMEOUT, origin.consume().routed_broadcast(path)) + .await + .expect("announce timeout") + .expect("routed") +} + +/// How many SUBSCRIBE request streams the client has opened. +fn subscribes(pair: &MockPair) -> usize { + pair.client_transport + .bidi_types() + .iter() + .filter(|first| **first == SUBSCRIBE) + .count() +} + +/// Read one frame of the next group, or `None` once the subscription ends. +async fn read(sub: &mut moq_net::track::Subscriber) -> Option<(u64, Vec)> { + let mut group = moq_clock::timeout(TIMEOUT, sub.recv_group()) + .await + .expect("group timeout") + .ok()??; + let frame = moq_clock::timeout(TIMEOUT, group.read_frame()) + .await + .expect("frame timeout") + .ok()??; + Some((group.sequence, frame.payload.to_vec())) +} + +/// The listing syncs at once, then lists the peer's tracks and their changes: a track the +/// peer stops listing is removed, as its PUBLISH ends. +#[moq_clock::test] +async fn an_ietf_session_lists_its_peers_tracks() { + for version in DRAFTS { + let publisher = produce_origin(1); + let broadcast = publisher.create_broadcast("bcast").unwrap(); + let a = broadcast.create_track("a", None).unwrap(); + broadcast.announce(Default::default()).unwrap(); + + let (subscriber, _pair) = connect(&publisher, version).await; + let remote = resolve(&subscriber, "bcast").await; + let mut tracks = remote.tracks().unwrap(); + assert_eq!(next(&mut tracks).await, "synced", "{version}"); + assert_eq!(next(&mut tracks).await, "+a", "{version}"); + + let _b = broadcast.create_track("b", None).unwrap(); + assert_eq!(next(&mut tracks).await, "+b", "{version}"); + drop(a); + assert_eq!(next(&mut tracks).await, "-a", "{version}"); + assert!(quiet(&mut tracks).await, "{version}"); + } +} + +/// A listed track carries the info its PUBLISH declared. +#[moq_clock::test] +async fn a_listing_carries_track_info() { + let publisher = produce_origin(1); + let broadcast = publisher.create_broadcast("bcast").unwrap(); + let info = moq_net::track::Info::default() + .with_timescale(moq_net::Timescale::MILLI) + .with_priority(9); + let _a = broadcast.create_track("a", info).unwrap(); + broadcast.announce(Default::default()).unwrap(); + + let (subscriber, _pair) = connect(&publisher, "moq-transport-22").await; + let mut tracks = resolve(&subscriber, "bcast").await.tracks().unwrap(); + assert_eq!(next(&mut tracks).await, "synced"); + let event = moq_clock::timeout(TIMEOUT, tracks.next()) + .await + .expect("listing stalled") + .unwrap(); + let Some(TracksEvent::Added { name, info }) = event else { + panic!("expected an add, got {event:?}"); + }; + assert_eq!(&*name, "a"); + assert_eq!(info.timescale, Some(moq_net::Timescale::MILLI)); + assert_eq!(info.priority, 9); +} + +/// Before draft-18 there is no SUBSCRIBE_TRACKS, so the listing is refused rather than +/// answered empty. +#[moq_clock::test] +async fn before_draft_18_the_listing_is_refused() { + let publisher = produce_origin(1); + let broadcast = publisher.create_broadcast("bcast").unwrap(); + let _a = broadcast.create_track("a", None).unwrap(); + broadcast.announce(Default::default()).unwrap(); + + let (subscriber, _pair) = connect(&publisher, "moq-transport-17").await; + let mut tracks = resolve(&subscriber, "bcast").await.tracks().unwrap(); + assert_eq!(next(&mut tracks).await, format!("error: {}", moq_net::Error::Unsupported)); +} + +/// A reader of a listed track resumes its held PUBLISH, so its data arrives with no +/// SUBSCRIBE at all; draft-18 would refuse one as a second subscription to the track. +/// Once the reader leaves, the PUBLISH pauses and stays listed, and the next reader +/// resumes it again. +#[moq_clock::test] +async fn a_reader_resumes_the_held_publish() { + for version in DRAFTS { + let publisher = produce_origin(1); + let broadcast = publisher.create_broadcast("bcast").unwrap(); + let video = broadcast.create_track("video", None).unwrap(); + broadcast.announce(Default::default()).unwrap(); + + let (subscriber, pair) = connect(&publisher, version).await; + let remote = resolve(&subscriber, "bcast").await; + let mut tracks = remote.tracks().unwrap(); + assert_eq!(next(&mut tracks).await, "synced", "{version}"); + assert_eq!(next(&mut tracks).await, "+video", "{version}"); + + let mut sub = moq_clock::timeout(TIMEOUT, remote.track("video").unwrap().subscribe(None)) + .await + .expect("subscribe timeout") + .expect("subscribe"); + moq_clock::timeout(TIMEOUT, support::wanted(video.demand())) + .await + .expect("never resumed") + .unwrap(); + let mut group = video.append_group().unwrap(); + group.write_frame(None, &b"first"[..]).unwrap(); + group.finish().unwrap(); + assert_eq!(read(&mut sub).await, Some((0, b"first".to_vec())), "{version}"); + assert_eq!(subscribes(&pair), 0, "{version}: subscribed beside the held PUBLISH"); + + // The last reader leaving pauses the PUBLISH upstream, and the track stays listed. + drop(sub); + moq_clock::timeout(TIMEOUT, support::unwanted(video.demand())) + .await + .expect("never paused") + .unwrap(); + assert!(quiet(&mut tracks).await, "{version}"); + + let mut sub = moq_clock::timeout(TIMEOUT, remote.track("video").unwrap().subscribe(None)) + .await + .expect("subscribe timeout") + .expect("subscribe"); + moq_clock::timeout(TIMEOUT, support::wanted(video.demand())) + .await + .expect("never resumed again") + .unwrap(); + let mut group = video.append_group().unwrap(); + group.write_frame(None, &b"second"[..]).unwrap(); + group.finish().unwrap(); + let got = loop { + match read(&mut sub).await { + Some((sequence, payload)) if sequence < 1 => continue, + got => break got, + } + }; + assert_eq!(got, Some((1, b"second".to_vec())), "{version}"); + assert_eq!(subscribes(&pair), 0, "{version}"); + } +} From 93f46ac90da5989781bb9be9ae842eb87625b1f0 Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Wed, 21 Oct 2026 23:15:22 -0700 Subject: [PATCH 03/14] feat(ietf): hold listed PUBLISHes paused and resume them for readers Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/ietf/subscriber.rs | 63 +++- rs/moq-net/src/ietf/subscriber/tracks.rs | 319 +++++++++++++++++++- rs/moq-net/tests/integration/tracks_ietf.rs | 203 ++++++++++++- 3 files changed, 572 insertions(+), 13 deletions(-) diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index dd47f20555f..8d4717e6e90 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -56,6 +56,24 @@ enum Alias { /// promptly is what bounds the exposure, since it caps the arrival window at a round /// trip rather than leaving it open for the life of the session. Retired, + + /// A paused subscription a listing holds: the alias stays its own, but a group carrying + /// it is refused rather than buffered, since nothing reads the track. + Paused(RequestId), + + /// A paused subscription resuming, whose REQUEST_UPDATE is not answered yet. Its groups + /// can overtake the answer, so they wait on it as they would on a SUBSCRIBE_OK. + Resuming(RequestId), +} + +impl Alias { + /// The subscription holding the alias, if any. + fn holder(self) -> Option { + match self { + Self::Active(id) | Self::Paused(id) | Self::Resuming(id) => Some(id), + Self::Retired => None, + } + } } /// The aliases a remote publisher has bound on this session, plus the cancelled ones we @@ -90,7 +108,10 @@ fn insert_track_alias(aliases: &TrackAliases, alias: u64, request_id: RequestId) table.retired.retain(|&retired| retired != alias); Ok(()) } - Entry::Occupied(entry) if *entry.get() == Alias::Active(request_id) => Ok(()), + Entry::Occupied(mut entry) if entry.get().holder() == Some(request_id) => { + entry.insert(Alias::Active(request_id)); + Ok(()) + } Entry::Occupied(_) => Err(Error::Duplicate), Entry::Vacant(entry) => { entry.insert(Alias::Active(request_id)); @@ -117,6 +138,19 @@ pub(super) fn is_protocol_violation(err: &Error) -> bool { ) } +/// Move `alias` to `to` (paused, resuming, or active again), unless another subscription +/// than `request_id` holds it. +fn rebind_track_alias(aliases: &TrackAliases, alias: u64, request_id: RequestId, to: Alias) { + let Ok(mut aliases) = aliases.write() else { + return; + }; + if let Some(held) = aliases.map.get_mut(&alias) + && held.holder() == Some(request_id) + { + *held = to; + } +} + /// Retire an alias, so groups still in flight for it are dropped promptly rather than /// reported as unknown (draft-19 section 11.1). /// @@ -128,7 +162,7 @@ fn retire_track_alias(aliases: &TrackAliases, alias: u64, request_id: RequestId) }; let table = &mut *aliases; - if table.map.get(&alias) != Some(&Alias::Active(request_id)) { + if table.map.get(&alias).and_then(|held| held.holder()) != Some(request_id) { return; } @@ -814,8 +848,10 @@ async fn resolve_track_alias( // our STOP_SENDING. Discard the group now rather than waiting out the timeout // for a binding that is never coming. Some(Alias::Retired) => Poll::Ready(Err(Error::Cancel)), - None if aliases.ended => Poll::Ready(Err(Error::Cancel)), - None => Poll::Pending, + // Nothing reads a paused subscription, so its groups are refused. + Some(Alias::Paused(_)) => Poll::Ready(Err(Error::Cancel)), + Some(Alias::Resuming(_)) | None if aliases.ended => Poll::Ready(Err(Error::Cancel)), + Some(Alias::Resuming(_)) | None => Poll::Pending, }); if let Poll::Ready(result) = resolved { return Poll::Ready(result.unwrap_or(Err(Error::Cancel))); @@ -1067,11 +1103,19 @@ where Ok(()) } + /// Move the alias the subscription with `request_id` is bound to into `to`. + fn rebind_alias(&self, request_id: RequestId, to: Alias) { + let state = self.state.lock(); + if let Some(alias) = state.subscribes.get(&request_id).and_then(|track| track.alias) { + rebind_track_alias(&state.aliases, alias, request_id, to); + } + } + /// Whether the subscription already holding `alias` is for the same full track name as /// `request_id`, making the repeat legal sharing rather than a collision. fn alias_names_same_track(&self, state: &State, alias: u64, request_id: RequestId) -> bool { let aliases = state.aliases.read(); - let Some(Alias::Active(holder)) = aliases.map.get(&alias).copied() else { + let Some(holder) = aliases.map.get(&alias).and_then(|held| held.holder()) else { return false; }; @@ -2914,8 +2958,9 @@ where .filter(|_| super::subscribe::has_new_group_request(self.version)); let written = match &held { // Resume the held subscription: its group order is the one it was made with, - // since no update can change it. + // since no update can change it. Its groups wait on the answer from here. Some(held) => { + self.rebind_alias(request_id, Alias::Resuming(request_id)); let forward = tracks::Forward { forward: true, filter: Some(join.filter), @@ -3241,9 +3286,9 @@ where } self.entry_info(&key, request_id, track.info()); // A resumed subscription stays bound to the alias it was held with. - if held.is_none() - && let Err(err) = self.register_alias(request_id, alias) - { + if held.is_some() { + self.rebind_alias(request_id, Alias::Active(request_id)); + } else if let Err(err) = self.register_alias(request_id, alias) { if matches!(err, Error::Duplicate) { tracing::warn!(track_alias = %alias, "publisher reused a live track alias for another track"); self.session.close( diff --git a/rs/moq-net/src/ietf/subscriber/tracks.rs b/rs/moq-net/src/ietf/subscriber/tracks.rs index 6a35db36d86..faaad98b6ad 100644 --- a/rs/moq-net/src/ietf/subscriber/tracks.rs +++ b/rs/moq-net/src/ietf/subscriber/tracks.rs @@ -720,11 +720,14 @@ where })) } - /// Bind the alias a held subscription's PUBLISH or SUBSCRIBE_OK chose, closing the - /// session if it names another track. + /// Bind the alias a held subscription's PUBLISH or SUBSCRIBE_OK chose, paused, closing + /// the session if it names another track. fn bind_alias(&self, request_id: RequestId, alias: u64) -> Result<(), Error> { let err = match self.register_alias(request_id, alias) { - Ok(()) => return Ok(()), + Ok(()) => { + self.rebind_alias(request_id, Alias::Paused(request_id)); + return Ok(()); + } Err(err) => err, }; if matches!(err, Error::Duplicate) { @@ -1089,6 +1092,9 @@ where if let Some(fetch_id) = fetch_id { state.fetches.remove(&fetch_id); } + if let Some(alias) = state.subscribes.get(&request_id).and_then(|track| track.alias) { + rebind_track_alias(&state.aliases, alias, request_id, Alias::Paused(request_id)); + } } /// Set a held subscription's Forward State with REQUEST_UPDATE. @@ -1184,3 +1190,310 @@ pub(super) struct Resumed { /// How a PUBLISH_DONE ended it before the resume was answered. pub(super) ended: Option>, } + +#[cfg(test)] +mod tests { + use super::*; + use crate::model::ProduceTest as _; + use crate::transport::memory; + + const TIMEOUT: Duration = Duration::from_secs(1); + + type PeerStream = Stream; + + /// A subscriber listing `broadcast` over a raw peer that plays the publisher. + struct Harness { + subscriber: Subscriber, + peer: memory::Session, + tracks: crate::broadcast::Tracks, + listening: Listening, + version: Version, + _broadcast: crate::broadcast::Producer, + _driver: moq_clock::sim::JoinHandle<()>, + } + + async fn settle() { + moq_clock::sleep(Duration::from_millis(1)).await; + } + + fn harness(version: Version) -> Harness { + let (session, peer) = memory::pair(memory::Config::default()); + let (tasks, mut task_set) = TaskSet::new(); + let driver = moq_clock::sim::spawn(async move { kio::wait(|waiter| task_set.poll(waiter)).await }); + let subscriber = Subscriber::new( + crate::time::sim(), + session, + crate::origin::Config::new(crate::Hop::new(1).unwrap()).produce(), + Control::new(None, false), + None, + peer::PeerSetup::declared(peer::Peer::default()), + crate::Hop::new(1).unwrap(), + None, + version, + tasks, + Default::default(), + ); + let broadcast = crate::broadcast::Info::default().produce(); + let lister = Arc::new(broadcast.dynamic().lister().unwrap()); + let tracks = broadcast.consume().tracks().unwrap(); + let listening = subscriber.listen(PathOwned::from("bcast"), lister); + Harness { + subscriber, + peer, + tracks, + listening, + version, + _broadcast: broadcast, + _driver: driver, + } + } + + async fn read(stream: &mut PeerStream) -> (u64, ietf::Body) { + let read = async { + let id = stream.reader.varint().await.unwrap(); + (id, stream.reader.decode::().await.unwrap()) + }; + moq_clock::timeout(TIMEOUT, read).await.expect("the subscriber sent nothing") + } + + async fn write(stream: &mut PeerStream, id: u64, msg: &M) { + stream.writer.varint(id).await.unwrap(); + stream.writer.encode(msg).await.unwrap(); + settle().await; + } + + /// The next listing event as `+name`, `-name`, or `synced`; `None` while pending. + fn event(tracks: &mut crate::broadcast::Tracks) -> Option { + match tracks.poll_next(&kio::Waiter::noop()) { + Poll::Ready(Ok(Some(crate::broadcast::TracksEvent::Added { name, .. }))) => Some(format!("+{name}")), + Poll::Ready(Ok(Some(crate::broadcast::TracksEvent::Removed { name }))) => Some(format!("-{name}")), + Poll::Ready(Ok(Some(crate::broadcast::TracksEvent::Synced))) => Some("synced".into()), + Poll::Ready(other) => Some(format!("{other:?}")), + Poll::Pending => None, + } + } + + impl Harness { + /// Accept the SUBSCRIBE_TRACKS and establish it. + async fn establish(&mut self) -> PeerStream { + let mut stream = moq_clock::timeout(TIMEOUT, Stream::accept(&mut self.peer, self.version)) + .await + .expect("no SUBSCRIBE_TRACKS") + .unwrap(); + let (id, body) = read(&mut stream).await; + assert_eq!(id, ietf::SubscribeTracks::ID); + let msg: ietf::SubscribeTracks = body.message(self.version).unwrap(); + assert_eq!(msg.prefix.as_str(), "bcast"); + assert!(!msg.forward, "the listing asks for every track's objects"); + let ok = ietf::RequestOk { + request_id: None, + active: None, + largest: None, + }; + write(&mut stream, ietf::RequestOk::ID, &ok).await; + assert_eq!(event(&mut self.tracks).as_deref(), Some("synced")); + stream + } + + /// PUBLISH `name` paused, returning the stream once the subscriber holds it. + async fn publish(&mut self, name: &str, request_id: u64) -> PeerStream { + let (stream, id, _) = self.offer("bcast", name, request_id).await; + assert!( + [ietf::RequestOk::ID, ietf::PublishOk::ID].contains(&id), + "PUBLISH refused: {id:#x}" + ); + stream + } + + /// PUBLISH `name` in `namespace` paused, returning the answer. + async fn offer(&mut self, namespace: &str, name: &str, request_id: u64) -> (PeerStream, u64, ietf::Body) { + let mut stream = Stream::open(&mut self.peer, self.version).await.unwrap(); + let publish = ietf::Publish { + request_id: RequestId(request_id), + track_namespace: Path::new(namespace), + track_name: name.into(), + track_alias: request_id, + largest_location: None, + forward: false, + properties: ietf::Properties::default(), + subscriber_priority: None, + group_order: None, + filter: None, + }; + stream.writer.varint(ietf::Publish::ID).await.unwrap(); + stream.writer.encode(&publish).await.unwrap(); + + let mut ours = Stream::accept(&mut self.subscriber.session.clone(), self.version) + .await + .unwrap(); + let id = ours.reader.varint().await.unwrap(); + assert_eq!(id, ietf::Publish::ID); + let body: ietf::Body = ours.reader.decode().await.unwrap(); + let mut subscriber = self.subscriber.clone(); + let version = self.version; + moq_clock::sim::spawn(async move { + let msg: ietf::Publish = body.message(version).unwrap(); + let _ = subscriber.serve_publish(ours, msg).await; + }); + let (id, body) = read(&mut stream).await; + (stream, id, body) + } + } + + /// The error code a refused PUBLISH answered with. + fn refusal(id: u64, body: &ietf::Body, version: Version) -> u64 { + assert_eq!(id, ietf::RequestError::ID, "accepted"); + body.message::(version).unwrap().error_code + } + + /// A PUBLISH no listing asked for stays refused, and one for a track already held is + /// redundant: DUPLICATE_SUBSCRIPTION on draft-18, which allows one subscription per + /// track, and UNINTERESTED after. + #[moq_clock::test] + async fn an_unasked_or_redundant_publish_is_refused() { + for (version, duplicate) in [(Version::Draft18, 0x19), (Version::Draft19, 0x20)] { + let mut h = harness(version); + let _listing = h.establish().await; + let (_, id, body) = h.offer("other", "video", 1).await; + assert_eq!(refusal(id, &body, version), 0x3, "{version}: unsolicited"); + let _video = h.publish("video", 3).await; + let (_, id, body) = h.offer("bcast", "video", 5).await; + assert_eq!(refusal(id, &body, version), duplicate, "{version}: redundant"); + } + } + + /// A PUBLISH_DONE with TRACK_ENDED removes the track; INTERNAL_ERROR, which our own + /// answerer sends once a track is no longer listed, does too (decided 2026-10-22). + #[moq_clock::test] + async fn a_track_ended_publish_removes_the_track() { + for status in [ietf::PublishDoneStatus::TrackEnded, ietf::PublishDoneStatus::InternalError] { + let version = Version::Draft22; + let mut h = harness(version); + let _listing = h.establish().await; + let mut video = h.publish("video", 1).await; + assert_eq!(event(&mut h.tracks).as_deref(), Some("+video")); + + let done = ietf::PublishDone { + request_id: None, + status_code: status.code(version), + stream_count: 0, + reason_phrase: "".into(), + }; + write(&mut video, ietf::PublishDone::ID, &done).await; + assert_eq!(event(&mut h.tracks).as_deref(), Some("-video"), "{status:?}"); + assert!(h.listening.poll_failed(&kio::Waiter::noop()).is_pending()); + } + } + + /// Any other PUBLISH_DONE fails the listing rather than hide a track that may be live. + #[moq_clock::test] + async fn another_publish_done_fails_the_listing() { + let version = Version::Draft22; + let mut h = harness(version); + let _listing = h.establish().await; + let mut video = h.publish("video", 1).await; + assert_eq!(event(&mut h.tracks).as_deref(), Some("+video")); + + let done = ietf::PublishDone { + request_id: None, + status_code: ietf::PublishDoneStatus::Unauthorized.code(version), + stream_count: 0, + reason_phrase: "".into(), + }; + write(&mut video, ietf::PublishDone::ID, &done).await; + assert!(matches!( + h.listening.poll_failed(&kio::Waiter::noop()), + Poll::Ready(Error::Unauthorized) + )); + } + + /// A skipped track is listed through a paused SUBSCRIBE of ours, once it answers. + #[moq_clock::test] + async fn a_skipped_track_lists_once_its_paused_subscribe_answers() { + for version in [Version::Draft18, Version::Draft22] { + let mut h = harness(version); + let mut listing = h.establish().await; + let skipped = ietf::PublishSkipped { + suffix: Path::new(""), + track_name: "audio".into(), + }; + write(&mut listing, ietf::PublishSkipped::ID, &skipped).await; + assert_eq!(event(&mut h.tracks), None, "{version}: listed before it answered"); + + let mut stream = moq_clock::timeout(TIMEOUT, Stream::accept(&mut h.peer, version)) + .await + .expect("no paused SUBSCRIBE") + .unwrap(); + let (id, body) = read(&mut stream).await; + assert_eq!(id, ietf::Subscribe::ID, "{version}"); + let msg: ietf::Subscribe = body.message(version).unwrap(); + assert_eq!(msg.track_name, "audio", "{version}"); + assert!(!msg.forward, "{version}: the SUBSCRIBE forwards"); + + let ok = ietf::SubscribeOk { + request_id: None, + track_alias: 3, + largest: None, + properties: ietf::Properties { + timescale: Some(crate::Timescale::MILLI), + ..Default::default() + }, + }; + write(&mut stream, ietf::SubscribeOk::ID, &ok).await; + assert_eq!(event(&mut h.tracks).as_deref(), Some("+audio"), "{version}"); + } + } + + /// A refused paused SUBSCRIBE fails the listing. + #[moq_clock::test] + async fn a_refused_paused_subscribe_fails_the_listing() { + let version = Version::Draft22; + let mut h = harness(version); + let mut listing = h.establish().await; + let skipped = ietf::PublishSkipped { + suffix: Path::new(""), + track_name: "audio".into(), + }; + write(&mut listing, ietf::PublishSkipped::ID, &skipped).await; + let mut stream = moq_clock::timeout(TIMEOUT, Stream::accept(&mut h.peer, version)) + .await + .expect("no paused SUBSCRIBE") + .unwrap(); + let _ = read(&mut stream).await; + let refused = ietf::RequestError { + request_id: None, + error_code: 0x3, + reason_phrase: "".into(), + retry_interval: 0, + }; + write(&mut stream, ietf::RequestError::ID, &refused).await; + assert!(matches!( + h.listening.poll_failed(&kio::Waiter::noop()), + Poll::Ready(Error::Unsupported) + )); + } + + /// Dropping the listing cancels its SUBSCRIBE_TRACKS: FIN on draft-18, RESET_STREAM from + /// draft-19, where a FIN is no cancel. The held PUBLISHes are let go with it. + #[moq_clock::test] + async fn dropping_the_listing_cancels_it() { + for version in [Version::Draft18, Version::Draft19] { + let mut h = harness(version); + let mut listing = h.establish().await; + let mut video = h.publish("video", 1).await; + drop(h.listening); + settle().await; + let ended = moq_clock::timeout(TIMEOUT, listing.reader.varint_maybe()) + .await + .expect("the listing stayed open"); + match version { + Version::Draft18 => assert!(matches!(ended, Ok(None)), "{version}: {ended:?}"), + _ => assert!(ended.is_err(), "{version}: {ended:?}"), + } + let ended = moq_clock::timeout(TIMEOUT, video.reader.varint_maybe()) + .await + .expect("the PUBLISH stayed held"); + assert!(!matches!(ended, Ok(Some(_))), "{version}: {ended:?}"); + } + } +} diff --git a/rs/moq-net/tests/integration/tracks_ietf.rs b/rs/moq-net/tests/integration/tracks_ietf.rs index 7f15ea6fb36..e0ad1b7800a 100644 --- a/rs/moq-net/tests/integration/tracks_ietf.rs +++ b/rs/moq-net/tests/integration/tracks_ietf.rs @@ -211,7 +211,7 @@ async fn a_reader_resumes_the_held_publish() { group.finish().unwrap(); let got = loop { match read(&mut sub).await { - Some((sequence, payload)) if sequence < 1 => continue, + Some((sequence, _)) if sequence < 1 => continue, got => break got, } }; @@ -219,3 +219,204 @@ async fn a_reader_resumes_the_held_publish() { assert_eq!(subscribes(&pair), 0, "{version}"); } } + +/// A reader joining a listed track mid-group gets the objects already published in it: on +/// drafts 18 and 19, whose filters deliver nothing already published, through a Joining +/// FETCH on the held PUBLISH's Request ID, and from draft-20 through the resume's fill. +#[moq_clock::test] +async fn a_join_gets_the_current_groups_head() { + for version in DRAFTS { + let publisher = produce_origin(1); + let broadcast = publisher.create_broadcast("bcast").unwrap(); + let video = broadcast.create_track("video", None).unwrap(); + broadcast.announce(Default::default()).unwrap(); + + let (subscriber, pair) = connect(&publisher, version).await; + let remote = resolve(&subscriber, "bcast").await; + let mut tracks = remote.tracks().unwrap(); + assert_eq!(next(&mut tracks).await, "synced", "{version}"); + assert_eq!(next(&mut tracks).await, "+video", "{version}"); + + let mut group = video.create_group(moq_net::group::Info { sequence: 5 }).unwrap(); + group.write_frame(None, &b"head"[..]).unwrap(); + + let mut sub = moq_clock::timeout(TIMEOUT, remote.track("video").unwrap().subscribe(None)) + .await + .expect("subscribe timeout") + .expect("subscribe"); + moq_clock::timeout(TIMEOUT, support::wanted(video.demand())) + .await + .expect("never resumed") + .unwrap(); + moq_clock::sleep(Duration::from_millis(10)).await; + group.write_frame(None, &b"tail"[..]).unwrap(); + group.finish().unwrap(); + + let mut joined = moq_clock::timeout(TIMEOUT, sub.recv_group()) + .await + .expect("group timeout") + .unwrap() + .expect("the joined group"); + assert_eq!(joined.sequence, 5, "{version}"); + let mut frames = Vec::new(); + while let Some(frame) = moq_clock::timeout(TIMEOUT, joined.read_frame()) + .await + .expect("frame timeout") + .unwrap() + { + frames.push(frame.payload.to_vec()); + } + assert_eq!(frames, [b"head".to_vec(), b"tail".to_vec()], "{version}"); + assert_eq!(subscribes(&pair), 0, "{version}"); + } +} + +/// A nested listing reuses the broader SUBSCRIBE_TRACKS and filters locally: the peer +/// would refuse an overlapping prefix. +#[moq_clock::test] +async fn a_nested_listing_reuses_the_broader_one() { + for version in DRAFTS { + let publisher = produce_origin(1); + let outer = publisher.create_broadcast("a").unwrap(); + let _x = outer.create_track("x", None).unwrap(); + outer.announce(Default::default()).unwrap(); + let inner = publisher.create_broadcast("a/b").unwrap(); + let _y = inner.create_track("y", None).unwrap(); + inner.announce(Default::default()).unwrap(); + + let (subscriber, _pair) = connect(&publisher, version).await; + let mut outer_tracks = resolve(&subscriber, "a").await.tracks().unwrap(); + assert_eq!(next(&mut outer_tracks).await, "synced", "{version}"); + assert_eq!(next(&mut outer_tracks).await, "+x", "{version}"); + // The broader request holds `a/b`'s tracks already, so they list before syncing. + let mut inner_tracks = resolve(&subscriber, "a/b").await.tracks().unwrap(); + assert_eq!(next(&mut inner_tracks).await, "+y", "{version}"); + assert_eq!(next(&mut inner_tracks).await, "synced", "{version}"); + + let _z = inner.create_track("z", None).unwrap(); + assert_eq!(next(&mut inner_tracks).await, "+z", "{version}"); + assert!(quiet(&mut outer_tracks).await, "{version}: a nested track listed in its parent"); + } +} + +/// A broader listing replaces the nested requests only once the peer has closed them, so it +/// is never refused as overlapping, and the nested listings keep what they listed. +#[moq_clock::test] +async fn a_broader_listing_replaces_the_nested_ones() { + for version in DRAFTS { + let publisher = produce_origin(1); + let mut held = Vec::new(); + let mut broadcasts = Vec::new(); + for path in ["a/b", "a/c", "a"] { + let broadcast = publisher.create_broadcast(path).unwrap(); + held.push(broadcast.create_track("t", None).unwrap()); + broadcast.announce(Default::default()).unwrap(); + broadcasts.push(broadcast); + } + + let (subscriber, _pair) = connect(&publisher, version).await; + let mut nested = Vec::new(); + for path in ["a/b", "a/c"] { + let mut tracks = resolve(&subscriber, path).await.tracks().unwrap(); + assert_eq!(next(&mut tracks).await, "synced", "{version}"); + assert_eq!(next(&mut tracks).await, "+t", "{version}: {path}"); + nested.push(tracks); + } + + let mut outer = resolve(&subscriber, "a").await.tracks().unwrap(); + assert_eq!(next(&mut outer).await, "synced", "{version}"); + assert_eq!(next(&mut outer).await, "+t", "{version}"); + for tracks in &mut nested { + assert!(quiet(tracks).await, "{version}: a nested listing changed"); + } + + // The broader request lists what follows in the nested broadcasts too. + held.push(broadcasts[0].create_track("u", None).unwrap()); + assert_eq!(next(&mut nested[0]).await, "+u", "{version}"); + } +} + +/// A PUBLISH for a track we already SUBSCRIBEd is redundant: the SUBSCRIBE lists the track +/// and keeps carrying its data. Draft-18 skips it instead, which lists it the same way. +#[moq_clock::test] +async fn a_subscribed_track_is_listed_through_its_subscribe() { + for version in DRAFTS { + let publisher = produce_origin(1); + let broadcast = publisher.create_broadcast("bcast").unwrap(); + let video = broadcast.create_track("video", None).unwrap(); + broadcast.announce(Default::default()).unwrap(); + + let (subscriber, pair) = connect(&publisher, version).await; + let remote = resolve(&subscriber, "bcast").await; + let mut sub = moq_clock::timeout(TIMEOUT, remote.track("video").unwrap().subscribe(None)) + .await + .expect("subscribe timeout") + .expect("subscribe"); + moq_clock::timeout(TIMEOUT, support::wanted(video.demand())) + .await + .expect("never subscribed") + .unwrap(); + assert_eq!(subscribes(&pair), 1, "{version}"); + + let mut tracks = remote.tracks().unwrap(); + assert_eq!(next(&mut tracks).await, "synced", "{version}"); + assert_eq!(next(&mut tracks).await, "+video", "{version}"); + + let mut group = video.append_group().unwrap(); + group.write_frame(None, &b"live"[..]).unwrap(); + group.finish().unwrap(); + assert_eq!(read(&mut sub).await, Some((0, b"live".to_vec())), "{version}"); + assert!(quiet(&mut tracks).await, "{version}"); + assert_eq!(subscribes(&pair), 1, "{version}"); + } +} + +/// Each held PUBLISH counts against the session's `announces` cap, as a lite listed track +/// does: past it, the PUBLISH is refused and the listing reset rather than left short, and +/// the session stays. +#[moq_clock::test] +async fn a_listing_past_the_announces_cap_is_reset() { + for version in DRAFTS { + let publisher = produce_origin(1); + let broadcast = publisher.create_broadcast("bcast").unwrap(); + const CAP: usize = 10; + let _tracks: Vec<_> = (0..CAP) + .map(|i| broadcast.create_track(format!("t{i}"), None).unwrap()) + .collect(); + broadcast.announce(Default::default()).unwrap(); + + let mut limits = moq_net::session::Limits::default(); + limits.announces = CAP; + let subscriber = produce_origin(2); + let mut options = MockConnectOptions::new(version.parse::().unwrap()); + options.client_publish = Some(publisher.consume()); + options.server_subscribe = Some(subscriber.clone()); + options.server_limits = Some(limits); + let pair = connect_mock(options).await; + + let remote = resolve(&subscriber, "bcast").await; + let mut listing = remote.tracks().unwrap(); + assert_eq!(next(&mut listing).await, "synced", "{version}"); + // The announcement holds a slot too, so not every track fits. + let mut added = 0; + let end = loop { + match next(&mut listing).await { + event if event.starts_with('+') => added += 1, + event => break event, + } + }; + assert!(added < CAP, "{version}: listed {added} tracks under a cap of {CAP}"); + assert_eq!( + end, + format!("error: {}", moq_net::Error::TooManyRequests), + "{version}" + ); + + assert!( + moq_clock::timeout(Duration::from_millis(100), pair.server.closed()) + .await + .is_err(), + "{version}: the session closed" + ); + } +} From f52f2da38bab612003043d280f61e10e4a544e55 Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Wed, 21 Oct 2026 23:35:17 -0700 Subject: [PATCH 04/14] docs: describe outbound SUBSCRIBE_TRACKS and retire its quest Co-Authored-By: Claude Opus 5.5 --- doc/concept/standard.md | 5 +- quest/m1/archive/README.md | 7 +- quest/m1/archive/subscribe-tracks-outbound.md | 103 ------------------ rs/moq-net/src/ietf/subscriber/tracks.rs | 79 ++++++++++---- rs/moq-net/tests/integration/tracks_ietf.rs | 16 +-- 5 files changed, 71 insertions(+), 139 deletions(-) delete mode 100644 quest/m1/archive/subscribe-tracks-outbound.md diff --git a/doc/concept/standard.md b/doc/concept/standard.md index b84c326c9c7..b96142ccc17 100644 --- a/doc/concept/standard.md +++ b/doc/concept/standard.md @@ -25,8 +25,9 @@ maps everything else to "not supported" or a harmless equivalent. The [moq-lite page](/concept/moq-lite#what-moq-lite-leaves-out) lists what the subset drops. What a peer actually observes against this implementation: -- **Pull.** Subscribers ask. Single-track `PUBLISH` offers are declined; announce a namespace and serve the resulting subscriptions. Announcements go out unsolicited, and we also ask for every prefix we may discover. The solicit `SETUP` option makes us wait to be asked. Without it, a draft 16+ peer also gets each match as a `NAMESPACE` on its `SUBSCRIBE_NAMESPACE` stream, so it hears the namespace twice. We send `PUBLISH` only to answer a `SUBSCRIBE_TRACKS` (below): on drafts 16 and 17 a `SUBSCRIBE_NAMESPACE` asking only for `PUBLISH` is refused, one asking for both gets only `NAMESPACE`, and any other Subscribe Options value closes the session. -- **`SUBSCRIBE_TRACKS` lists, it never pushes.** In Rust, on draft 18 and later, it lists every track of every broadcast under its prefix, later ones included. With `FORWARD=0`, each track gets a paused `PUBLISH` carrying its Track Properties, and an error `PUBLISH_DONE` once the track is no longer listed, never `TRACK_ENDED`, since the track may go on elsewhere. A `REQUEST_UPDATE` with `FORWARD=1` resumes one, served from the cache like a `SUBSCRIBE` with the update's filter and answered with `LARGEST_OBJECT`; `FORWARD=0` pauses it again. Each paused `PUBLISH` holds a subscription slot, and past the cap a track gets `PUBLISH_SKIPPED` (`PUBLISH_BLOCKED` on draft 18) instead. A listing that omits `FORWARD` or sets it to 1 asks for every track's objects: from draft 19 each track gets `PUBLISH_SKIPPED`, and the subscriber `SUBSCRIBE`s to what it wants; draft 18 has no such skip, so the request is refused with `NOT_SUPPORTED`. A prefix overlapping another listing gets `PREFIX_OVERLAP`, a `TRACK_PROPERTY_FILTER` gets `NOT_SUPPORTED`, and a `REQUEST_UPDATE` on the listing itself ends it. On draft 18, a `SUBSCRIBE` to a track we `PUBLISH`ed gets `DUPLICATE_SUBSCRIPTION`. Cancelling the listing stops new `PUBLISH`es, while those sent live on. A broadcast is listed only while our publish grant covers it, from scratch once it does. A Rust relay does not yet send `SUBSCRIBE_TRACKS` upstream, and JavaScript refuses it with `NOT_SUPPORTED`. +- **Pull.** Subscribers ask. Single-track `PUBLISH` offers are declined, unless they answer our `SUBSCRIBE_TRACKS` (below); announce a namespace and serve the resulting subscriptions. Announcements go out unsolicited, and we also ask for every prefix we may discover. The solicit `SETUP` option makes us wait to be asked. Without it, a draft 16+ peer also gets each match as a `NAMESPACE` on its `SUBSCRIBE_NAMESPACE` stream, so it hears the namespace twice. We send `PUBLISH` only to answer a `SUBSCRIBE_TRACKS` (below): on drafts 16 and 17 a `SUBSCRIBE_NAMESPACE` asking only for `PUBLISH` is refused, one asking for both gets only `NAMESPACE`, and any other Subscribe Options value closes the session. +- **`SUBSCRIBE_TRACKS` lists, it never pushes.** In Rust, on draft 18 and later, it lists every track of every broadcast under its prefix, later ones included. With `FORWARD=0`, each track gets a paused `PUBLISH` carrying its Track Properties, and an error `PUBLISH_DONE` once the track is no longer listed, never `TRACK_ENDED`, since the track may go on elsewhere. A `REQUEST_UPDATE` with `FORWARD=1` resumes one, served from the cache like a `SUBSCRIBE` with the update's filter and answered with `LARGEST_OBJECT`; `FORWARD=0` pauses it again. Each paused `PUBLISH` holds a subscription slot, and past the cap a track gets `PUBLISH_SKIPPED` (`PUBLISH_BLOCKED` on draft 18) instead. A listing that omits `FORWARD` or sets it to 1 asks for every track's objects: from draft 19 each track gets `PUBLISH_SKIPPED`, and the subscriber `SUBSCRIBE`s to what it wants; draft 18 has no such skip, so the request is refused with `NOT_SUPPORTED`. A prefix overlapping another listing gets `PREFIX_OVERLAP`, a `TRACK_PROPERTY_FILTER` gets `NOT_SUPPORTED`, and a `REQUEST_UPDATE` on the listing itself ends it. On draft 18, a `SUBSCRIBE` to a track we `PUBLISH`ed gets `DUPLICATE_SUBSCRIPTION`. Cancelling the listing stops new `PUBLISH`es, while those sent live on. A broadcast is listed only while our publish grant covers it, from scratch once it does. JavaScript refuses it with `NOT_SUPPORTED`. +- **A Rust TRACKS listing sends `SUBSCRIBE_TRACKS` upstream.** On draft 18 and later, listing a broadcast from a moq-transport peer sends `SUBSCRIBE_TRACKS` with `FORWARD=0` and holds each `PUBLISH` paused as its track's entry, its info from the Track Properties; before draft 18 the listing is refused as unsupported. A reader resumes that `PUBLISH` with a `REQUEST_UPDATE` (`FORWARD=1` plus the join's filter, and `FILL_PARAMETERS` from draft 20; a Joining `FETCH` on the `PUBLISH`'s Request ID before), and the last reader leaving pauses it again, so a listed track is never subscribed twice. A `PUBLISH_DONE` with `TRACK_ENDED` or `INTERNAL_ERROR`, which our own answerer sends once a track is no longer listed, removes the track; any other status fails every listing the request serves, and the readers ask again. A skipped track is listed through a paused `SUBSCRIBE` once its `SUBSCRIBE_OK` arrives, and a track we already `SUBSCRIBE`d is listed through that `SUBSCRIBE`, its `PUBLISH` refused with `DUPLICATE_SUBSCRIPTION` on draft 18 and `UNINTERESTED` after. One request covers each chain of nested broadcasts: a nested listing reuses the broader one, and a broader one replaces the nested requests once the peer has closed them. Each held track counts against the session's announce cap; past it, the `PUBLISH` is refused with `EXCESSIVE_LOAD` and the listing reset. A Rust answerer refuses `FORWARD=0` on a `SUBSCRIBE`, so pausing a listed track we `SUBSCRIBE`d fails that listing once, which asks again. - **History is one group.** In Rust, Object ID gaps must be marked by Prior Object ID Gap properties for a group to be fetchable. A `FETCH` returns one group from the cache, or on drafts 14 through 19 the saved prefix of the group a new subscription just joined. A range of groups is refused, as is a draft 20+ `LOCATION_FILTER` that ends at Largest Object rather than an absolute End Location. On draft 20 and later, `FETCH_OK`'s End Location is the requested end, capped at Largest Object: a range holding no objects gets an empty fetch stream, and only a start past Largest Object is refused, with `INVALID_RANGE`. A relay's copy with no upstream subscription can't know Largest Object short of the track's end, so it echoes the requested end instead. JavaScript publishing refuses every `FETCH`. Datagrams are never fetchable. A Rust reader that only fetches learns the track from `TRACK_STATUS` instead of subscribing, so a finished track stays fetchable; draft 17 still subscribes, since its `TRACK_STATUS` answer cannot say whether the track is timed, and so does a reader whose publisher refuses `TRACK_STATUS` as `NOT_SUPPORTED`. - **Timing.** A track whose `SUBSCRIBE_OK` declares no `TIMESCALE` is untimed, as is every track on drafts 14 through 16. A Rust reader that never subscribed takes the units from `TRACK_STATUS` on draft 18 and later. - **Strict SETUP and parameters.** Repeated unknown `SETUP` options, GREASE included, are accepted if well-formed; a repeated known option is rejected. On draft 17 and later, a `GROUP_ORDER` other than Ascending (1) or Descending (2) closes the session. Message parameters follow the negotiated draft's lists: drafts 14 and 15 ignore an unknown or misplaced parameter, draft 16 ignores one defined only for another message but closes the session on an unknown one, and draft 17 and later close it on both. Other malformed control input closes the session with the draft's code too, such as a server `SETUP` carrying `PATH` or `AUTHORITY`, a request cut short by FIN, or a second `GOAWAY` on one stream; a first `GOAWAY` on a request stream is legal. diff --git a/quest/m1/archive/README.md b/quest/m1/archive/README.md index f8ddd743bc0..5b17edf8d85 100644 --- a/quest/m1/archive/README.md +++ b/quest/m1/archive/README.md @@ -31,9 +31,9 @@ archive (per-track `.timeline.z` records named by the catalog's root track, gating the lite-07 cut (`broadcast::Consumer::tracks` in Rust; [TRACKS in js/net](/quest/m1/archive/tracks-js.md)). moq-transport answers SUBSCRIBE_TRACKS through the same hook (Rust now, - [js/net](/quest/m1/archive/subscribe-tracks-js.md) next) and learns an - IETF peer's tracks with a FORWARD=0 SUBSCRIBE_TRACKS - ([outbound SUBSCRIBE_TRACKS](/quest/m1/archive/subscribe-tracks-outbound.md)). Rejected: + [js/net](/quest/m1/archive/subscribe-tracks-js.md) next) and, in Rust, learns + an IETF peer's tracks with a FORWARD=0 SUBSCRIBE_TRACKS whose held PUBLISHes + resume for data. Rejected: SUBSCRIBE_ALL, whose relay had to merge pushed feeds into pulled copies ([moq-dev/moq#5931](https://github.com/moq-dev/moq/pull/5931)). The archive no longer selects tracks from a catalog. @@ -88,7 +88,6 @@ from a host. Each child fixes the stale docs it touches. - [TRACKS in js/net](/quest/m1/archive/tracks-js.md) - `@moq/net` lists a broadcast's tracks over lite-07's Tracks Stream and answers listings of its own broadcasts, mirroring Rust - [Archive consumer](/quest/m1/archive/consumer.md) - `archive::Consumer` serves a stored prefix as a broadcast from its key listing, and `moq export/import archive` use the new pair - [Catalog HLS field](/quest/m1/archive/catalog-hls.md) - the root `archive` section is gone; an opt-in per-rendition `hls` field marks each aligned HLS segment's first group and pts and declares its nominal duration -- [Outbound SUBSCRIBE_TRACKS](/quest/m1/archive/subscribe-tracks-outbound.md) - an IETF peer's tracks are listed through the TRACKS hook by a FORWARD=0 SUBSCRIBE_TRACKS, whose held PUBLISH resumes for data - [SUBSCRIBE_TRACKS in js/net](/quest/m1/archive/subscribe-tracks-js.md) - `@moq/net` answers SUBSCRIBE_TRACKS as Rust does, instead of NOT_SUPPORTED - [Fixed HLS target duration](/quest/m1/archive/hls-target.md) - one `EXT-X-TARGETDURATION` for the run, from the declared `hls` duration; an overrun is listed with a warning - [History from the retained floor](/quest/m1/archive/history-floor.md) - HLS history over an archive consumer broadcast whose start was pruned lists from its oldest stored segment diff --git a/quest/m1/archive/subscribe-tracks-outbound.md b/quest/m1/archive/subscribe-tracks-outbound.md deleted file mode 100644 index a44489c106c..00000000000 --- a/quest/m1/archive/subscribe-tracks-outbound.md +++ /dev/null @@ -1,103 +0,0 @@ -# [L] Outbound SUBSCRIBE_TRACKS - -## Goal - -A lite TRACKS whose broadcast is served by a moq-transport peer (draft-18 on) -learns that peer's tracks by sending SUBSCRIBE_TRACKS with FORWARD=0 and -reading the PUBLISH each track produces, without its objects. A listed -track's data comes by resuming that same subscription when a reader wants it. -Today the Rust subscriber never sends SUBSCRIBE_TRACKS, so a lite listing over -a moq-transport upstream lists nothing. - -An unsolicited inbound PUBLISH stays refused: moq-net never merges a pushed -track into a pulled copy. A FORWARD=0 PUBLISH answering our own -SUBSCRIBE_TRACKS carries data only once we resume it with the filter our own -SUBSCRIBE would send, so it is a pull, not that merge. - -## Plan - -Split from the inbound half, which answers a peer's SUBSCRIBE_TRACKS through -`broadcast::Consumer::tracks` (`rs/moq-net/src/ietf/publisher/tracks.rs`). -The maintainer's 2026-10-19 decisions, recorded with TRACKS: "we don't need an -extension; we could issue forward=0 to learn about all tracks from IETF peers". - -TRACKS' events map as follows: - -| TRACKS event | We send SUBSCRIBE_TRACKS with FORWARD=0 | -|---|---| -| Track added, with TRACK_INFO | a PUBLISH, TRACK_INFO from its Track Properties; or a PUBLISH_SKIPPED (PUBLISH_BLOCKED on draft-18), TRACK_INFO from the SUBSCRIBE_OK of a paused SUBSCRIBE we open for it | -| Synced | not needed: the lite side sends SYNCED for this hop at once, and PUBLISHes arrive as live adds | -| Track removed | PUBLISH_DONE with TRACK_ENDED on the held paused PUBLISH or SUBSCRIBE; any other status fails the listing | - -- **One subscription per track: the held PUBLISH carries the data.** - PUBLISH_DONE is the only removal signal, so an outbound PUBLISH is accepted - paused (PUBLISH_OK, FORWARD=0) and held as the listing entry. It is also - the track's upstream copy: when a reader wants the data, REQUEST_UPDATE it - to FORWARD=1 with the filter our SUBSCRIBE would have sent - (SUBSCRIPTION_FILTER through draft-19, LOCATION_FILTER and FILL_PARAMETERS - from draft-20, whose section 3.6.2 names this join), and back to FORWARD=0 - when the last reader leaves, rather than unsubscribing. On draft-18 and - draft-19 a filter does not deliver objects already published, so a start - below the Largest Object also sends a Joining FETCH on the held - subscription's request ID, as the existing pre-draft-20 SUBSCRIBE path - does. Draft-18 section 5.1 allows one subscription per track per role and - fails a second with DUPLICATE_SUBSCRIPTION; draft-19 on allow several. - The upstream copy is one subscription carrying the union of reader ranges - either way, and the existing SUBSCRIBE path adopts a held PUBLISH as the - track's copy instead of opening one. Conversely, a PUBLISH for a track we - already SUBSCRIBEd (established or pending) is redundant: the existing - SUBSCRIBE becomes the entry, and the PUBLISH is refused with - DUPLICATE_SUBSCRIPTION on draft-18 and UNINTERESTED from draft-19. Only - TRACK_ENDED is a removal. Any other status fails the listing loudly: the - lite TRACKS stream resets and the lister requests again, never turning it - into a removal that would hide a live track for good. -- **A skipped track is still listed.** A PUBLISH_SKIPPED (PUBLISH_BLOCKED on - draft-18) names a track that exists, so open a paused SUBSCRIBE (FORWARD=0) - for it and hold that as the entry and the copy. Its SUBSCRIBE_OK supplies - the TRACK_INFO, so the add goes downstream once it arrives, and its - PUBLISH_DONE with TRACK_ENDED is the removal. A refused paused SUBSCRIBE, - or one ending with another status, fails the listing loudly. -- **One SUBSCRIBE_TRACKS per nesting chain, never widened in place.** Two - prefixes overlap only when one is a prefix of the other, which the peer - refuses with PREFIX_OVERLAP. Siblings get separate requests. A nested - listing under a broader request reuses it and filters locally. A broader - listing cancels the nested requests, keeping the PUBLISH subscriptions they - made, and opens only once the peer has closed every cancelled stream: close - our sending half (FIN on draft-18, RESET_STREAM from draft-19), keep - reading until the peer closes its half, and delay STOP_SENDING. If the - broader request is refused, every listing it was meant to serve resets - loudly and re-requests. Rejected: widening in place with REQUEST_UPDATE, - and one request per session at the common ancestor. -- **Push inventory only.** An IETF relay lists the tracks it has been - PUBLISHed or already holds. A track served only on request is unlisted, - which matches TRACKS' rule. -- **Properties.** A property TRACK_INFO needs but PUBLISH lacks takes the - same default it takes from SUBSCRIBE_OK today. -- **Draft-22 parameters.** Draft-22 section 9.18 drops SUBSCRIBER_PRIORITY, - LOCATION_FILTER, and NEW_GROUP_REQUEST from SUBSCRIBE_TRACKS, while section - 3.6.2 still allows any subscription parameter. Send only the section 9.18 - set on draft-22 (`ietf::SubscribeTracks` encodes all of them today), and put - the join filter on the resuming REQUEST_UPDATE. The inbound decoder accepts - both readings. -- **A non-conforming peer** may send objects despite FORWARD=0; stop reading - them rather than buffer. - -Untrusted input: a hostile publisher can PUBLISH without bound. Each held -paused PUBLISH counts against the session's `announces` cap, as a lite listed -track does; past it, refuse the PUBLISH (EXCESSIVE_LOAD). The stream and -request-ID credit we grant bounds what is in flight. - -Test on mock time over drafts 18 and later: a lite TRACKS over a -moq-transport upstream lists its tracks with FORWARD=0; a lite SUBSCRIBE -resumes the held PUBLISH with its join filter and gets a new track's first -group with no second upstream SUBSCRIBE; a past start on draft-18 and -draft-19 gets cached groups through a Joining FETCH; the last reader leaving -pauses it and keeps the entry; TRACK_ENDED removes the entry and another -status resets the listing; a skipped track lists once its paused SUBSCRIBE -answers; TRACKS(`/a/b`) after TRACKS(`/a`) sends nothing; TRACKS(`/a`) after -TRACKS(`/a/b`) and TRACKS(`/a/c`) cancels both and opens only after the peer -closes them; a PUBLISH for a track we already SUBSCRIBEd is refused; an -unsolicited PUBLISH is refused. - -Public API: none beyond the TRACKS hook. Wire: moq-transport support for an -existing message. diff --git a/rs/moq-net/src/ietf/subscriber/tracks.rs b/rs/moq-net/src/ietf/subscriber/tracks.rs index faaad98b6ad..b55412c8d04 100644 --- a/rs/moq-net/src/ietf/subscriber/tracks.rs +++ b/rs/moq-net/src/ietf/subscriber/tracks.rs @@ -29,7 +29,9 @@ pub(super) type TrackKey = (PathOwned, Arc); /// so it asks again rather than hide a track that may still be live. pub(super) fn unlisted(end: Result<(), Error>) -> Result<(), Error> { match end { - Err(Error::Remote(code)) if u64::from(code) == ietf::PublishDoneStatus::InternalError.code(Version::Draft18) => { + Err(Error::Remote(code)) + if u64::from(code) == ietf::PublishDoneStatus::InternalError.code(Version::Draft18) => + { Ok(()) } end => end, @@ -156,7 +158,11 @@ impl Listings { .map(|listener| &*listener.lister) } - fn listen(&mut self, path: PathOwned, lister: Arc) -> (u64, kio::Consumer>, Option) { + fn listen( + &mut self, + path: PathOwned, + lister: Arc, + ) -> (u64, kio::Consumer>, Option) { // What a broader listing already holds is listed at once. for ((namespace, name), entry) in &self.entries { if namespace == &path @@ -291,12 +297,9 @@ impl Listings { /// The entry `handoff` belongs to, if it still stands. fn watched_by(&mut self, key: &TrackKey, handoff: &kio::Shared>) -> Option<&mut Entry> { - self.entries.get_mut(key).filter(|entry| { - entry - .handoff - .as_ref() - .is_some_and(|held| held.same_channel(handoff)) - }) + self.entries + .get_mut(key) + .filter(|entry| entry.handoff.as_ref().is_some_and(|held| held.same_channel(handoff))) } /// End the entry held by the subscription with `request_id`: TRACK_ENDED unlists it, @@ -384,7 +387,10 @@ where let result = self.subscribe_tracks(&prefix, blockers, &live).await; let mut listings = self.listings.lock(); if let Err(err) = result - && listings.requests.get(&key).is_some_and(|request| request.live.is_some()) + && listings + .requests + .get(&key) + .is_some_and(|request| request.live.is_some()) { listings.fail(&prefix, err); } @@ -541,10 +547,17 @@ where /// A fresh subscription of ours to `name` in `namespace`, and its info once accepted. fn subscribed(&self, namespace: &PathOwned, name: &str) -> Option<(RequestId, Option)> { let state = self.state.lock(); + let aliases = state.aliases.read(); + // A paused one is on its way out with the entry it held. + let paused = |id: &RequestId, track: &TrackState| { + track + .alias + .is_some_and(|alias| aliases.map.get(&alias) == Some(&Alias::Paused(*id))) + }; state .subscribes .iter() - .find(|(_, track)| track.broadcast == *namespace && track.name == name) + .find(|(id, track)| track.broadcast == *namespace && track.name == name && !paused(id, track)) .map(|(id, track)| (*id, track.producer.as_ref().map(|producer| producer.info().clone()))) } @@ -597,7 +610,11 @@ where /// Open a paused SUBSCRIBE for a skipped track and list it once its SUBSCRIBE_OK /// arrives. `None` once its entry was let go. - async fn open_paused(&self, key: &TrackKey, handoff: &kio::Shared>) -> Result>, Error> { + async fn open_paused( + &self, + key: &TrackKey, + handoff: &kio::Shared>, + ) -> Result>, Error> { let gone = |waiter: &kio::Waiter| { handoff .poll(waiter, |handoff| match handoff.gone { @@ -742,7 +759,11 @@ where /// Serve a PUBLISH: hold one answering our SUBSCRIBE_TRACKS paused as its track's entry, /// refuse a redundant one, and decline one no listing asked for. - pub(super) async fn serve_publish(&mut self, mut stream: Stream, msg: ietf::Publish<'_>) -> Result<(), Error> { + pub(super) async fn serve_publish( + &mut self, + mut stream: Stream, + msg: ietf::Publish<'_>, + ) -> Result<(), Error> { let key: TrackKey = (msg.track_namespace.to_owned(), msg.track_name.as_ref().into()); let info = accepted_info(&msg.properties, self.version); let offer = { @@ -754,7 +775,11 @@ where _ => request::to_code(&Error::Unroutable, request::Kind::Publish, self.version), }; if listings.covering(&key.0).is_none() { - match listings.requests.values().any(|request| key.0.has_prefix(&request.prefix)) { + match listings + .requests + .values() + .any(|request| key.0.has_prefix(&request.prefix)) + { true => Offer::Refuse( request::to_code(&Error::Unroutable, request::Kind::Publish, self.version), "listing cancelled", @@ -905,9 +930,11 @@ where Step::Wanted => { let upstream = { let mut held = handoff.lock(); - match held.gone { - true => upstream, - false => { + match (held.gone, held.wanted) { + (true, _) => upstream, + // The subscription gave up before it was handed over. + (false, false) => continue, + (false, true) => { held.upstream = Some(upstream); return; } @@ -966,10 +993,12 @@ where /// Ready with the subscription `handoff` hands over, or `None` once it ended instead. pub(super) fn poll_handoff(handoff: &kio::Shared>, waiter: &kio::Waiter) -> Poll>> { - let mut handoff = ready!(handoff.poll(waiter, |handoff| match handoff.gone || handoff.upstream.is_some() { - true => Poll::Ready(()), - false => Poll::Pending, - })); + let mut handoff = ready!( + handoff.poll(waiter, |handoff| match handoff.gone || handoff.upstream.is_some() { + true => Poll::Ready(()), + false => Poll::Pending, + }) + ); Poll::Ready(handoff.upstream.take()) } @@ -1045,7 +1074,6 @@ where }); } - /// Pause a subscription nobody reads that is its track's entry, and hold it again. pub(super) async fn pause(&self, key: TrackKey, mut upstream: Upstream) { self.park_subscribe(upstream.request_id); @@ -1253,7 +1281,9 @@ mod tests { let id = stream.reader.varint().await.unwrap(); (id, stream.reader.decode::().await.unwrap()) }; - moq_clock::timeout(TIMEOUT, read).await.expect("the subscriber sent nothing") + moq_clock::timeout(TIMEOUT, read) + .await + .expect("the subscriber sent nothing") } async fn write(stream: &mut PeerStream, id: u64, msg: &M) { @@ -1366,7 +1396,10 @@ mod tests { /// answerer sends once a track is no longer listed, does too (decided 2026-10-22). #[moq_clock::test] async fn a_track_ended_publish_removes_the_track() { - for status in [ietf::PublishDoneStatus::TrackEnded, ietf::PublishDoneStatus::InternalError] { + for status in [ + ietf::PublishDoneStatus::TrackEnded, + ietf::PublishDoneStatus::InternalError, + ] { let version = Version::Draft22; let mut h = harness(version); let _listing = h.establish().await; diff --git a/rs/moq-net/tests/integration/tracks_ietf.rs b/rs/moq-net/tests/integration/tracks_ietf.rs index e0ad1b7800a..d7f8f6f5be8 100644 --- a/rs/moq-net/tests/integration/tracks_ietf.rs +++ b/rs/moq-net/tests/integration/tracks_ietf.rs @@ -155,7 +155,10 @@ async fn before_draft_18_the_listing_is_refused() { let (subscriber, _pair) = connect(&publisher, "moq-transport-17").await; let mut tracks = resolve(&subscriber, "bcast").await.tracks().unwrap(); - assert_eq!(next(&mut tracks).await, format!("error: {}", moq_net::Error::Unsupported)); + assert_eq!( + next(&mut tracks).await, + format!("error: {}", moq_net::Error::Unsupported) + ); } /// A reader of a listed track resumes its held PUBLISH, so its data arrives with no @@ -295,7 +298,10 @@ async fn a_nested_listing_reuses_the_broader_one() { let _z = inner.create_track("z", None).unwrap(); assert_eq!(next(&mut inner_tracks).await, "+z", "{version}"); - assert!(quiet(&mut outer_tracks).await, "{version}: a nested track listed in its parent"); + assert!( + quiet(&mut outer_tracks).await, + "{version}: a nested track listed in its parent" + ); } } @@ -406,11 +412,7 @@ async fn a_listing_past_the_announces_cap_is_reset() { } }; assert!(added < CAP, "{version}: listed {added} tracks under a cap of {CAP}"); - assert_eq!( - end, - format!("error: {}", moq_net::Error::TooManyRequests), - "{version}" - ); + assert_eq!(end, format!("error: {}", moq_net::Error::TooManyRequests), "{version}"); assert!( moq_clock::timeout(Duration::from_millis(100), pair.server.closed()) From fd04e757c418789cbc209dd3dc4d01e02452d33c Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Thu, 22 Oct 2026 00:08:40 -0700 Subject: [PATCH 05/14] refactor(ietf): name what a subscription acquires Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/ietf/subscriber.rs | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index 8d4717e6e90..a837d0a64e2 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -2835,6 +2835,12 @@ where // resume it rather than open a second one. let key: tracks::TrackKey = (broadcast_path.to_owned(), track_name.into()); let mut adopting = self.want(&key); + enum Acquired { + /// A Request ID for a SUBSCRIBE of our own. + Fresh(RequestId), + /// The paused subscription a listing held. + Held(tracks::Upstream), + } // Retirement and revocation cancel only the wait for an ID. On drafts 14-16 the peer // grants MAX_REQUEST_ID credit back only for requests it receives, so an allocated ID @@ -2847,12 +2853,14 @@ where validity.check(waiter)?; if let Some(handoff) = &adopting { match Self::poll_handoff(handoff, waiter) { - Poll::Ready(Some(upstream)) => return Poll::Ready(Ok(Err(upstream))), + Poll::Ready(Some(upstream)) => return Poll::Ready(Ok(Acquired::Held(upstream))), Poll::Ready(None) => adopting = None, Poll::Pending => return Poll::Pending, } } - self.control.poll_credit(waiter, &mut timeout).map(|id| id.map(Ok)) + self.control + .poll_credit(waiter, &mut timeout) + .map(|id| id.map(Acquired::Fresh)) }) .await; let acquired = match acquired { @@ -2869,7 +2877,7 @@ where // The resumed subscription's alias, properties, and owed answers, when resuming one. let mut held: Option = None; let (request_id, mut stream, mut messages) = match acquired { - Ok(request_id) => { + Acquired::Fresh(request_id) => { let stream = match Stream::open(&mut self.session.clone(), self.version).await { Ok(s) => s, Err(err) => { @@ -2881,7 +2889,7 @@ where let messages = super::request_stream::Messages::new(self.session.clone(), self.control.client()); (request_id, stream, messages) } - Err(upstream) => { + Acquired::Held(upstream) => { self.adopted(&key, upstream.request_id); let tracks::Upstream { stream, From 8c10c5d05689e50923d220c25f0816486e2efe1f Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Thu, 22 Oct 2026 00:12:20 -0700 Subject: [PATCH 06/14] quest: the IETF answerer pauses any subscription Co-Authored-By: Claude Opus 5.5 --- quest/m1/README.md | 1 + quest/m1/ietf-pause-subscribe.md | 36 ++++++++++++++++++++++++++++++++ 2 files changed, 37 insertions(+) create mode 100644 quest/m1/ietf-pause-subscribe.md diff --git a/quest/m1/README.md b/quest/m1/README.md index d55742c1dd8..d97b1924cff 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -78,6 +78,7 @@ lite-07 stream type here. - [A widened max age re-offers cached groups](/quest/m1/resolved-demand.md) - a warm relay serves a reader with a wider max age the cached groups a cold relay would, with no wire change - [Drop set](/quest/m1/drop-set.md) - each cursor judges missing groups against its own budget, so a narrow reader drops promptly and a widening re-offers groups already reported dropped on lite-07 - [Broadcast archives](/quest/m1/archive/README.md) - ANNOUNCE, TRACKS, and a SUBSCRIBE per track record every track under a prefix to any object_store, a host serves a stored broadcast back, and the catalog drops its archive pointer for an opt-in `hls` field +- [The IETF answerer pauses any subscription](/quest/m1/ietf-pause-subscribe.md) - a SUBSCRIBE with FORWARD=0, or a REQUEST_UPDATE setting FORWARD, pauses and resumes it on drafts 18+, so a Rust-to-Rust IETF listing never fails over a pause - [Compressed tracks](/quest/m1/compress/README.md) - a track flagged `compress` is DEFLATEd per group by moq-net, forwarded compressed, and inflated once on the relay for peers that cannot signal it; `catalog.json.z` and moq-flate go away - [Finalize moq-lite-07](/quest/m1/lite07-finalize.md) - when the maintainer cuts it, lite-07 negotiates as `moq-lite-07` and the next release ships it - [Moxygen minimal interop](/quest/m1/smoke-moxygen.md) - waiting on Moxygen to send a registered filter type, then the smoke lane stops hiding its failure diff --git a/quest/m1/ietf-pause-subscribe.md b/quest/m1/ietf-pause-subscribe.md new file mode 100644 index 00000000000..a117aa03c3a --- /dev/null +++ b/quest/m1/ietf-pause-subscribe.md @@ -0,0 +1,36 @@ +# [M] The IETF answerer pauses any subscription + +## Goal + +On drafts 18 and later, the Rust moq-transport answerer serves a SUBSCRIBE +with FORWARD=0 paused, and pauses or resumes any Established subscription +when a REQUEST_UPDATE sets FORWARD, as it already does for a PUBLISH it made +for SUBSCRIBE_TRACKS. Draft-22 section 3.1.1 lets the initiator set FORWARD on +SUBSCRIBE and the subscriber change it with REQUEST_UPDATE; today we refuse +both with NOT_SUPPORTED. + +This is what a clean Rust-to-Rust IETF listing needs +([moq-dev/moq#6280](https://github.com/moq-dev/moq/pull/6280)): a listed +track held through our own SUBSCRIBE pauses once its last reader leaves, and a +skipped track is listed through a paused SUBSCRIBE. Against a Rust answerer +both fail the listing today, so readers list again, and a track skipped at +the answerer's subscription cap is never listed at all. + +## Plan + +- Reuse what the paused PUBLISH already does in + `rs/moq-net/src/ietf/publisher/tracks.rs` (pause, resume with the update's + filter and fill, answer with LARGEST_OBJECT, a joining FETCH refused while + paused) rather than a second implementation for SUBSCRIBE. +- A paused subscription forwards nothing, so a hostile subscriber can park + many: count each against the same subscription slots a forwarding one + takes. +- Drafts 14-17 keep refusing FORWARD=0; check what each draft allows before + widening it. +- Test over drafts 18-22 on mock time, including the outbound listing from + #6280: a SUBSCRIBE-held listed track pauses with its listing intact, and a + skipped track lists. + +## Related + +- [Broadcast archives](/quest/m1/archive/README.md) - lists an IETF peer's tracks through SUBSCRIBE_TRACKS From 19a5f3acec12997f00ec5c5e1839f4221efe1d8d Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Thu, 22 Oct 2026 00:23:08 -0700 Subject: [PATCH 07/14] fix(ietf): remove a listed track only on TRACK_ENDED Co-Authored-By: Claude Opus 5.5 --- doc/concept/standard.md | 2 +- quest/m1/README.md | 1 + quest/m1/listing-end-reason.md | 33 +++++++ rs/moq-net/src/ietf/subscriber.rs | 2 +- rs/moq-net/src/ietf/subscriber/tracks.rs | 97 ++++++++++----------- rs/moq-net/tests/integration/tracks_ietf.rs | 49 +++++++++-- 6 files changed, 127 insertions(+), 57 deletions(-) create mode 100644 quest/m1/listing-end-reason.md diff --git a/doc/concept/standard.md b/doc/concept/standard.md index b96142ccc17..b64636d5dcc 100644 --- a/doc/concept/standard.md +++ b/doc/concept/standard.md @@ -27,7 +27,7 @@ subset drops. What a peer actually observes against this implementation: - **Pull.** Subscribers ask. Single-track `PUBLISH` offers are declined, unless they answer our `SUBSCRIBE_TRACKS` (below); announce a namespace and serve the resulting subscriptions. Announcements go out unsolicited, and we also ask for every prefix we may discover. The solicit `SETUP` option makes us wait to be asked. Without it, a draft 16+ peer also gets each match as a `NAMESPACE` on its `SUBSCRIBE_NAMESPACE` stream, so it hears the namespace twice. We send `PUBLISH` only to answer a `SUBSCRIBE_TRACKS` (below): on drafts 16 and 17 a `SUBSCRIBE_NAMESPACE` asking only for `PUBLISH` is refused, one asking for both gets only `NAMESPACE`, and any other Subscribe Options value closes the session. - **`SUBSCRIBE_TRACKS` lists, it never pushes.** In Rust, on draft 18 and later, it lists every track of every broadcast under its prefix, later ones included. With `FORWARD=0`, each track gets a paused `PUBLISH` carrying its Track Properties, and an error `PUBLISH_DONE` once the track is no longer listed, never `TRACK_ENDED`, since the track may go on elsewhere. A `REQUEST_UPDATE` with `FORWARD=1` resumes one, served from the cache like a `SUBSCRIBE` with the update's filter and answered with `LARGEST_OBJECT`; `FORWARD=0` pauses it again. Each paused `PUBLISH` holds a subscription slot, and past the cap a track gets `PUBLISH_SKIPPED` (`PUBLISH_BLOCKED` on draft 18) instead. A listing that omits `FORWARD` or sets it to 1 asks for every track's objects: from draft 19 each track gets `PUBLISH_SKIPPED`, and the subscriber `SUBSCRIBE`s to what it wants; draft 18 has no such skip, so the request is refused with `NOT_SUPPORTED`. A prefix overlapping another listing gets `PREFIX_OVERLAP`, a `TRACK_PROPERTY_FILTER` gets `NOT_SUPPORTED`, and a `REQUEST_UPDATE` on the listing itself ends it. On draft 18, a `SUBSCRIBE` to a track we `PUBLISH`ed gets `DUPLICATE_SUBSCRIPTION`. Cancelling the listing stops new `PUBLISH`es, while those sent live on. A broadcast is listed only while our publish grant covers it, from scratch once it does. JavaScript refuses it with `NOT_SUPPORTED`. -- **A Rust TRACKS listing sends `SUBSCRIBE_TRACKS` upstream.** On draft 18 and later, listing a broadcast from a moq-transport peer sends `SUBSCRIBE_TRACKS` with `FORWARD=0` and holds each `PUBLISH` paused as its track's entry, its info from the Track Properties; before draft 18 the listing is refused as unsupported. A reader resumes that `PUBLISH` with a `REQUEST_UPDATE` (`FORWARD=1` plus the join's filter, and `FILL_PARAMETERS` from draft 20; a Joining `FETCH` on the `PUBLISH`'s Request ID before), and the last reader leaving pauses it again, so a listed track is never subscribed twice. A `PUBLISH_DONE` with `TRACK_ENDED` or `INTERNAL_ERROR`, which our own answerer sends once a track is no longer listed, removes the track; any other status fails every listing the request serves, and the readers ask again. A skipped track is listed through a paused `SUBSCRIBE` once its `SUBSCRIBE_OK` arrives, and a track we already `SUBSCRIBE`d is listed through that `SUBSCRIBE`, its `PUBLISH` refused with `DUPLICATE_SUBSCRIPTION` on draft 18 and `UNINTERESTED` after. One request covers each chain of nested broadcasts: a nested listing reuses the broader one, and a broader one replaces the nested requests once the peer has closed them. Each held track counts against the session's announce cap; past it, the `PUBLISH` is refused with `EXCESSIVE_LOAD` and the listing reset. A Rust answerer refuses `FORWARD=0` on a `SUBSCRIBE`, so pausing a listed track we `SUBSCRIBE`d fails that listing once, which asks again. +- **A Rust TRACKS listing sends `SUBSCRIBE_TRACKS` upstream.** On draft 18 and later, listing a broadcast from a moq-transport peer sends `SUBSCRIBE_TRACKS` with `FORWARD=0` and holds each `PUBLISH` paused as its track's entry, its info from the Track Properties; before draft 18 the listing is refused as unsupported. A reader resumes that `PUBLISH` with a `REQUEST_UPDATE` (`FORWARD=1` plus the join's filter, and `FILL_PARAMETERS` from draft 20; a Joining `FETCH` on the `PUBLISH`'s Request ID before), and the last reader leaving pauses it again, so a listed track is never subscribed twice. Only a `PUBLISH_DONE` with `TRACK_ENDED` removes the track; any other status, including the error our own answerer sends once a track is no longer listed, fails every listing the request serves, and the readers ask again. A skipped track is listed through a paused `SUBSCRIBE` once its `SUBSCRIBE_OK` arrives, and a track we already `SUBSCRIBE`d is listed through that `SUBSCRIBE`, its `PUBLISH` refused with `DUPLICATE_SUBSCRIPTION` on draft 18 and `UNINTERESTED` after. One request covers each chain of nested broadcasts: a nested listing reuses the broader one, and a broader one replaces the nested requests once the peer has closed them. Each held track counts against the session's announce cap; past it, the `PUBLISH` is refused with `EXCESSIVE_LOAD` and the listing reset. A Rust answerer refuses `FORWARD=0` on a `SUBSCRIBE`, so pausing a listed track we `SUBSCRIBE`d fails that listing once, which asks again. - **History is one group.** In Rust, Object ID gaps must be marked by Prior Object ID Gap properties for a group to be fetchable. A `FETCH` returns one group from the cache, or on drafts 14 through 19 the saved prefix of the group a new subscription just joined. A range of groups is refused, as is a draft 20+ `LOCATION_FILTER` that ends at Largest Object rather than an absolute End Location. On draft 20 and later, `FETCH_OK`'s End Location is the requested end, capped at Largest Object: a range holding no objects gets an empty fetch stream, and only a start past Largest Object is refused, with `INVALID_RANGE`. A relay's copy with no upstream subscription can't know Largest Object short of the track's end, so it echoes the requested end instead. JavaScript publishing refuses every `FETCH`. Datagrams are never fetchable. A Rust reader that only fetches learns the track from `TRACK_STATUS` instead of subscribing, so a finished track stays fetchable; draft 17 still subscribes, since its `TRACK_STATUS` answer cannot say whether the track is timed, and so does a reader whose publisher refuses `TRACK_STATUS` as `NOT_SUPPORTED`. - **Timing.** A track whose `SUBSCRIBE_OK` declares no `TIMESCALE` is untimed, as is every track on drafts 14 through 16. A Rust reader that never subscribed takes the units from `TRACK_STATUS` on draft 18 and later. - **Strict SETUP and parameters.** Repeated unknown `SETUP` options, GREASE included, are accepted if well-formed; a repeated known option is rejected. On draft 17 and later, a `GROUP_ORDER` other than Ascending (1) or Descending (2) closes the session. Message parameters follow the negotiated draft's lists: drafts 14 and 15 ignore an unknown or misplaced parameter, draft 16 ignores one defined only for another message but closes the session on an unknown one, and draft 17 and later close it on both. Other malformed control input closes the session with the draft's code too, such as a server `SETUP` carrying `PATH` or `AUTHORITY`, a request cut short by FIN, or a second `GOAWAY` on one stream; a first `GOAWAY` on a request stream is legal. diff --git a/quest/m1/README.md b/quest/m1/README.md index d97b1924cff..ca4d1c6c659 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -79,6 +79,7 @@ lite-07 stream type here. - [Drop set](/quest/m1/drop-set.md) - each cursor judges missing groups against its own budget, so a narrow reader drops promptly and a widening re-offers groups already reported dropped on lite-07 - [Broadcast archives](/quest/m1/archive/README.md) - ANNOUNCE, TRACKS, and a SUBSCRIBE per track record every track under a prefix to any object_store, a host serves a stored broadcast back, and the catalog drops its archive pointer for an opt-in `hls` field - [The IETF answerer pauses any subscription](/quest/m1/ietf-pause-subscribe.md) - a SUBSCRIBE with FORWARD=0, or a REQUEST_UPDATE setting FORWARD, pauses and resumes it on drafts 18+, so a Rust-to-Rust IETF listing never fails over a pause +- [A listing says whether a removed track finished](/quest/m1/listing-end-reason.md) - a listing removal carries whether the track finished, at every hop, so the IETF answerer ends a finished track's PUBLISH with TRACK_ENDED and a Rust-to-Rust IETF listing removes it without a reset - [Compressed tracks](/quest/m1/compress/README.md) - a track flagged `compress` is DEFLATEd per group by moq-net, forwarded compressed, and inflated once on the relay for peers that cannot signal it; `catalog.json.z` and moq-flate go away - [Finalize moq-lite-07](/quest/m1/lite07-finalize.md) - when the maintainer cuts it, lite-07 negotiates as `moq-lite-07` and the next release ships it - [Moxygen minimal interop](/quest/m1/smoke-moxygen.md) - waiting on Moxygen to send a registered filter type, then the smoke lane stops hiding its failure diff --git a/quest/m1/listing-end-reason.md b/quest/m1/listing-end-reason.md new file mode 100644 index 00000000000..10294de9557 --- /dev/null +++ b/quest/m1/listing-end-reason.md @@ -0,0 +1,33 @@ +# [M] A listing says whether a removed track finished + +## Goal + +A track listing's removal says whether the track finished or left unfinished +(its producer dropped or aborted, or its broadcast's route withdrawn), at every +hop. The Rust moq-transport answerer then ends a finished track's +SUBSCRIBE_TRACKS PUBLISH with TRACK_ENDED, so a Rust-to-Rust IETF listing +([moq-dev/moq#6280](https://github.com/moq-dev/moq/pull/6280)) removes a +finished track quietly. An unfinished one keeps ending in error, which fails +the listing loudly as today. + +Today the answerer cannot tell: `TracksEvent::Removed` carries only the name, +and the instance that left is gone from the front the answerer reads through, +so it ends every unlisted PUBLISH in error and each removal resets the listing. +Decided by the maintainer on 2026-10-22: outbound removes only on TRACK_ENDED, +and the answerer sends TRACK_ENDED only for a track that really finished. + +## Plan + +- Public API and wire, so settle the shape with the maintainer first: how + `TracksEvent::Removed` and `broadcast::Lister::remove` carry the end, and a + lite-07 TRACKS_REMOVE field so a relay chain keeps it (`drafts/` and js/net + in the same change). +- A relay's copy reports what its upstream reported, never what its cache + happens to know. +- Test Rust-to-Rust over drafts 18-22: a finished track is removed, an + aborted one fails the listing. + +## Related + +- [Broadcast archives](/quest/m1/archive/README.md) - lists an IETF peer's tracks through SUBSCRIBE_TRACKS +- [The IETF answerer pauses any subscription](/quest/m1/ietf-pause-subscribe.md) - the other gap in a clean Rust-to-Rust IETF listing diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index a837d0a64e2..f5efc1ee822 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -3485,7 +3485,7 @@ where break true; } End::Done(res) => { - ended = Some(tracks::unlisted(res.as_ref().map(|_| ()).map_err(Clone::clone))); + ended = Some(res.as_ref().map(|_| ()).map_err(Clone::clone)); match res { Ok(count) => { tracing::info!(broadcast = %self.origin.absolute(broadcast_path), track = %track_name, "subscribe complete"); diff --git a/rs/moq-net/src/ietf/subscriber/tracks.rs b/rs/moq-net/src/ietf/subscriber/tracks.rs index b55412c8d04..bcb4d1a44cd 100644 --- a/rs/moq-net/src/ietf/subscriber/tracks.rs +++ b/rs/moq-net/src/ietf/subscriber/tracks.rs @@ -3,7 +3,7 @@ //! A listed broadcast sends SUBSCRIBE_TRACKS with FORWARD=0, and each track it lists is //! one paused subscription held for the session: the PUBLISH the peer answers with, //! accepted paused, or for a track the peer skips, a SUBSCRIBE we open paused. That -//! subscription is both the listing entry, removed by its PUBLISH_DONE with TRACK_ENDED, +//! subscription is both the listing entry, removed only by its PUBLISH_DONE with TRACK_ENDED, //! and the track's upstream copy: a reader resumes it with REQUEST_UPDATE and pauses it //! again once the last one leaves, rather than opening a second subscription. //! @@ -23,18 +23,16 @@ use crate::ietf::request_stream::{self, Framed, Messages}; /// A listed track, by its namespace and name. pub(super) type TrackKey = (PathOwned, Arc); -/// How a PUBLISH_DONE ending `end` leaves the listing: TRACK_ENDED removes the track, and -/// so does INTERNAL_ERROR, which is what our own answerer sends once a track is no longer -/// listed (PUBLISH_DONE registers no DOES_NOT_EXIST). Any other status fails the listing, -/// so it asks again rather than hide a track that may still be live. -pub(super) fn unlisted(end: Result<(), Error>) -> Result<(), Error> { - match end { - Err(Error::Remote(code)) - if u64::from(code) == ietf::PublishDoneStatus::InternalError.code(Version::Draft18) => - { - Ok(()) - } - end => end, +/// How a PUBLISH_DONE leaves the listing: only TRACK_ENDED removes the track. Any other +/// status, INTERNAL_ERROR included, fails the listing, so it asks again rather than hide a +/// track that may still be live. +fn listing_end(done: &ietf::PublishDone, version: Version) -> Result<(), Error> { + match done.status_code == ietf::PublishDoneStatus::TrackEnded.code(version) { + true => Ok(()), + false => Err(done + .end(version) + .err() + .unwrap_or(Error::Remote(u32::try_from(done.status_code).unwrap_or(u32::MAX)))), } } @@ -955,11 +953,10 @@ where upstream.owed -= 1; } ietf::PublishDone::ID => { - break unlisted( - body.message::(self.version) - .map_err(|err| upstream.messages.failed(err.into())) - .and_then(|done| done.end(self.version)), - ); + break body + .message::(self.version) + .map_err(|err| upstream.messages.failed(err.into())) + .and_then(|done| listing_end(&done, self.version)); } _ => break Err(upstream.messages.failed(Error::UnexpectedMessage)), }, @@ -1185,8 +1182,8 @@ where } ietf::PublishDone::ID => { let done = body.message::(self.version)?; - let end = done.end(self.version); - held.ended = Some(unlisted(end.clone())); + let end = listing_end(&done, self.version); + held.ended = Some(end.clone()); return Err(end.err().unwrap_or(Error::NotFound)); } _ => return Err(Error::UnexpectedMessage), @@ -1392,15 +1389,35 @@ mod tests { } } - /// A PUBLISH_DONE with TRACK_ENDED removes the track; INTERNAL_ERROR, which our own - /// answerer sends once a track is no longer listed, does too (decided 2026-10-22). + /// A PUBLISH_DONE with TRACK_ENDED removes the track, and the listing stands. #[moq_clock::test] async fn a_track_ended_publish_removes_the_track() { - for status in [ - ietf::PublishDoneStatus::TrackEnded, - ietf::PublishDoneStatus::InternalError, + let version = Version::Draft22; + let mut h = harness(version); + let _listing = h.establish().await; + let mut video = h.publish("video", 1).await; + assert_eq!(event(&mut h.tracks).as_deref(), Some("+video")); + + let done = ietf::PublishDone { + request_id: None, + status_code: ietf::PublishDoneStatus::TrackEnded.code(version), + stream_count: 0, + reason_phrase: "".into(), + }; + write(&mut video, ietf::PublishDone::ID, &done).await; + assert_eq!(event(&mut h.tracks).as_deref(), Some("-video")); + assert!(h.listening.poll_failed(&kio::Waiter::noop()).is_pending()); + } + + /// Any other PUBLISH_DONE, INTERNAL_ERROR included, fails the listing rather than hide a + /// track that may be live. + #[moq_clock::test] + async fn another_publish_done_fails_the_listing() { + let version = Version::Draft22; + for (status, expected) in [ + (ietf::PublishDoneStatus::Unauthorized, Error::Unauthorized), + (ietf::PublishDoneStatus::InternalError, Error::Remote(0)), ] { - let version = Version::Draft22; let mut h = harness(version); let _listing = h.establish().await; let mut video = h.publish("video", 1).await; @@ -1413,33 +1430,13 @@ mod tests { reason_phrase: "".into(), }; write(&mut video, ietf::PublishDone::ID, &done).await; - assert_eq!(event(&mut h.tracks).as_deref(), Some("-video"), "{status:?}"); - assert!(h.listening.poll_failed(&kio::Waiter::noop()).is_pending()); + match h.listening.poll_failed(&kio::Waiter::noop()) { + Poll::Ready(err) => assert_eq!(err.to_string(), expected.to_string(), "{status:?}"), + Poll::Pending => panic!("{status:?}: the listing stood"), + } } } - /// Any other PUBLISH_DONE fails the listing rather than hide a track that may be live. - #[moq_clock::test] - async fn another_publish_done_fails_the_listing() { - let version = Version::Draft22; - let mut h = harness(version); - let _listing = h.establish().await; - let mut video = h.publish("video", 1).await; - assert_eq!(event(&mut h.tracks).as_deref(), Some("+video")); - - let done = ietf::PublishDone { - request_id: None, - status_code: ietf::PublishDoneStatus::Unauthorized.code(version), - stream_count: 0, - reason_phrase: "".into(), - }; - write(&mut video, ietf::PublishDone::ID, &done).await; - assert!(matches!( - h.listening.poll_failed(&kio::Waiter::noop()), - Poll::Ready(Error::Unauthorized) - )); - } - /// A skipped track is listed through a paused SUBSCRIBE of ours, once it answers. #[moq_clock::test] async fn a_skipped_track_lists_once_its_paused_subscribe_answers() { diff --git a/rs/moq-net/tests/integration/tracks_ietf.rs b/rs/moq-net/tests/integration/tracks_ietf.rs index d7f8f6f5be8..2de2646df4f 100644 --- a/rs/moq-net/tests/integration/tracks_ietf.rs +++ b/rs/moq-net/tests/integration/tracks_ietf.rs @@ -94,14 +94,13 @@ async fn read(sub: &mut moq_net::track::Subscriber) -> Option<(u64, Vec)> { Some((group.sequence, frame.payload.to_vec())) } -/// The listing syncs at once, then lists the peer's tracks and their changes: a track the -/// peer stops listing is removed, as its PUBLISH ends. +/// The listing syncs at once, then lists the peer's tracks as they appear. #[moq_clock::test] async fn an_ietf_session_lists_its_peers_tracks() { for version in DRAFTS { let publisher = produce_origin(1); let broadcast = publisher.create_broadcast("bcast").unwrap(); - let a = broadcast.create_track("a", None).unwrap(); + let _a = broadcast.create_track("a", None).unwrap(); broadcast.announce(Default::default()).unwrap(); let (subscriber, _pair) = connect(&publisher, version).await; @@ -112,8 +111,6 @@ async fn an_ietf_session_lists_its_peers_tracks() { let _b = broadcast.create_track("b", None).unwrap(); assert_eq!(next(&mut tracks).await, "+b", "{version}"); - drop(a); - assert_eq!(next(&mut tracks).await, "-a", "{version}"); assert!(quiet(&mut tracks).await, "{version}"); } } @@ -422,3 +419,45 @@ async fn a_listing_past_the_announces_cap_is_reset() { ); } } + +/// Only TRACK_ENDED removes a listed track. Our answerer cannot tell a track that finished +/// from one that left the listing and may go on elsewhere, so it ends either's PUBLISH in +/// error: the listing fails loudly instead of removing the track quietly, and a reader +/// listing again sees what is still listed. +#[moq_clock::test] +async fn an_unlisted_track_fails_the_listing() { + for finish in [false, true] { + for version in DRAFTS { + let publisher = produce_origin(1); + let broadcast = publisher.create_broadcast("bcast").unwrap(); + let a = broadcast.create_track("a", None).unwrap(); + let _b = broadcast.create_track("b", None).unwrap(); + broadcast.announce(Default::default()).unwrap(); + + let (subscriber, _pair) = connect(&publisher, version).await; + let remote = resolve(&subscriber, "bcast").await; + let mut tracks = remote.tracks().unwrap(); + assert_eq!(next(&mut tracks).await, "synced", "{version}"); + let mut listed = vec![next(&mut tracks).await, next(&mut tracks).await]; + listed.sort(); + assert_eq!(listed, ["+a", "+b"], "{version}"); + + match finish { + true => { + a.finish().unwrap(); + drop(a); + } + false => { + let _ = a.abort(moq_net::Error::Cancel); + } + } + let failed = next(&mut tracks).await; + assert!(failed.starts_with("error:"), "{version} finish={finish}: {failed}"); + + let mut again = remote.tracks().unwrap(); + assert_eq!(next(&mut again).await, "synced", "{version}"); + assert_eq!(next(&mut again).await, "+b", "{version}"); + assert!(quiet(&mut again).await, "{version}"); + } + } +} From 6882b0923d3b2fb1894660cfbab81e93dd180e07 Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Thu, 22 Oct 2026 03:40:56 -0700 Subject: [PATCH 08/14] fix(ietf): end a listing entry quietly only on TRACK_ENDED, resumed or not Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/ietf/subscriber.rs | 19 ++++++---- rs/moq-net/src/ietf/subscriber/tracks.rs | 48 +++++++++++++++++++++++- 2 files changed, 59 insertions(+), 8 deletions(-) diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index f5efc1ee822..87a8b152d24 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -3323,7 +3323,7 @@ where enum End { Idle, Revoked, - Done(Result), + Done(Result, Error>), Fetch(group::Request), Update(Update), } @@ -3485,8 +3485,13 @@ where break true; } End::Done(res) => { - ended = Some(res.as_ref().map(|_| ()).map_err(Clone::clone)); - match res { + // Only TRACK_ENDED ends a listing entry quietly; a clean end of another + // kind, such as SUBSCRIPTION_ENDED, leaves the track's fate unknown. + ended = Some(match &res { + Ok(done) => tracks::listing_end(done, self.version), + Err(err) => Err(err.clone()), + }); + match res.map(|done| done.stream_count) { Ok(count) => { tracing::info!(broadcast = %self.origin.absolute(broadcast_path), track = %track_name, "subscribe complete"); // The publisher sends PUBLISH_DONE once every data stream it opened @@ -3697,17 +3702,17 @@ where version: Version, unanswered: &AtomicU64, messages: &mut super::request_stream::Messages, - ) -> Result { + ) -> Result, Error> { // A refused update is followed by PUBLISH_DONE, which ends the subscription. Its // count stays, so no further update goes out meanwhile, and no answer is owed. let mut refused = false; loop { let super::request_stream::Framed(type_id, body) = messages.message(reader).await?; if type_id == ietf::PublishDone::ID { - let msg: ietf::PublishDone = body.message(version)?; + let msg: ietf::PublishDone<'static> = body.message(version)?; tracing::debug!(message = ?msg, "received publish done"); msg.end(version)?; - return Ok(msg.stream_count); + return Ok(msg); } let answer = matches!(type_id, ietf::RequestOk::ID | ietf::RequestError::ID) && !refused && unanswered.load(Ordering::Relaxed) > 0; @@ -6024,7 +6029,7 @@ mod tests { ) .await; if clean { - assert_eq!(result.unwrap(), 0); + assert_eq!(result.unwrap().stream_count, 0); } else { assert!(matches!(result, Err(Error::ProtocolViolation))); } diff --git a/rs/moq-net/src/ietf/subscriber/tracks.rs b/rs/moq-net/src/ietf/subscriber/tracks.rs index bcb4d1a44cd..91650e2ec90 100644 --- a/rs/moq-net/src/ietf/subscriber/tracks.rs +++ b/rs/moq-net/src/ietf/subscriber/tracks.rs @@ -26,7 +26,7 @@ pub(super) type TrackKey = (PathOwned, Arc); /// How a PUBLISH_DONE leaves the listing: only TRACK_ENDED removes the track. Any other /// status, INTERNAL_ERROR included, fails the listing, so it asks again rather than hide a /// track that may still be live. -fn listing_end(done: &ietf::PublishDone, version: Version) -> Result<(), Error> { +pub(super) fn listing_end(done: &ietf::PublishDone, version: Version) -> Result<(), Error> { match done.status_code == ietf::PublishDoneStatus::TrackEnded.code(version) { true => Ok(()), false => Err(done @@ -1437,6 +1437,52 @@ mod tests { } } + /// A resumed listed track ending any way but TRACK_ENDED fails the listing, even a + /// clean SUBSCRIPTION_ENDED (drafts 18-19), which says nothing of the track itself. + #[moq_clock::test] + async fn a_resumed_track_ending_otherwise_fails_the_listing() { + let version = Version::Draft19; + let mut h = harness(version); + let _listing = h.establish().await; + let mut video = h.publish("video", 1).await; + assert_eq!(event(&mut h.tracks).as_deref(), Some("+video")); + + let mut dynamic = h._broadcast.dynamic(); + let track = h._broadcast.consume().track("video").unwrap(); + let _reader = track.subscribe(None); + let request = dynamic.requested_track().await.expect("no track requested"); + let mut subscriber = h.subscriber.clone(); + let _serving = moq_clock::sim::spawn(async move { + subscriber + .run_subscribe(Path::new("bcast"), dynamic, None, request) + .await; + }); + + let (id, body) = read(&mut video).await; + assert_eq!(id, ietf::SubscribeUpdate::ID, "not resumed"); + let resume: ietf::SubscribeUpdate = body.message(version).unwrap(); + assert_eq!(resume.forward, Some(true)); + let ok = ietf::RequestOk { + request_id: None, + active: None, + largest: None, + }; + write(&mut video, ietf::RequestOk::ID, &ok).await; + assert!(h.listening.poll_failed(&kio::Waiter::noop()).is_pending()); + + // SUBSCRIPTION_ENDED, which drafts 18 and 19 register. + let done = ietf::PublishDone { + request_id: None, + status_code: 0x3, + stream_count: 0, + reason_phrase: "".into(), + }; + write(&mut video, ietf::PublishDone::ID, &done).await; + // The subscription waits out its data streams before it ends. + moq_clock::sleep(Duration::from_secs(5)).await; + assert!(h.listening.poll_failed(&kio::Waiter::noop()).is_ready()); + } + /// A skipped track is listed through a paused SUBSCRIBE of ours, once it answers. #[moq_clock::test] async fn a_skipped_track_lists_once_its_paused_subscribe_answers() { From 601bad050ef09e49d15cb4a9665275bcb82e6b9f Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Thu, 22 Oct 2026 03:48:51 -0700 Subject: [PATCH 09/14] docs: name the SUBSCRIBE_TRACKS exceptions to deduplication Co-Authored-By: Claude Opus 5.5 --- doc/concept/standard.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/concept/standard.md b/doc/concept/standard.md index b64636d5dcc..b7a0409dcc0 100644 --- a/doc/concept/standard.md +++ b/doc/concept/standard.md @@ -105,8 +105,8 @@ choices. They follow the product model. termination code, so we close the session with it. - **Deduplicated subscriptions and discovery.** Shared subscriptions and overlapping - namespace prefixes are coalesced internally, so `DUPLICATE_SUBSCRIPTION` and - `PREFIX_OVERLAP` are never sent. + namespace prefixes are coalesced internally. Only `SUBSCRIBE_TRACKS`, described + above, sends `PREFIX_OVERLAP`, and on draft 18 `DUPLICATE_SUBSCRIPTION`. - **Subscriber max age is negotiated.** The [Timestamp extension](/draft/moq-timestamp) carries a subscriber's `max_delay` in `SUBSCRIBE` and `REQUEST_UPDATE` only From 77f7962b8302514d247426c95104c7ae0ff1d9fa Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Thu, 22 Oct 2026 03:58:04 -0700 Subject: [PATCH 10/14] fix(ietf): open a skipped track's paused SUBSCRIBE in the default order Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/ietf/subscriber/tracks.rs | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/rs/moq-net/src/ietf/subscriber/tracks.rs b/rs/moq-net/src/ietf/subscriber/tracks.rs index 91650e2ec90..fd9a9b742aa 100644 --- a/rs/moq-net/src/ietf/subscriber/tracks.rs +++ b/rs/moq-net/src/ietf/subscriber/tracks.rs @@ -656,7 +656,8 @@ where track_namespace: key.0.as_path(), track_name: key.1.as_ref().into(), subscriber_priority: super::super::priority::to_wire(0), - group_order: GroupOrder::Ascending, + // No update can change it, so it takes the order a reader gets by default. + group_order: track::Order::default().into(), filter: Filter::NextObject, fill: None, properties_wanted: true, @@ -1504,6 +1505,11 @@ mod tests { assert_eq!(id, ietf::Subscribe::ID, "{version}"); let msg: ietf::Subscribe = body.message(version).unwrap(); assert_eq!(msg.track_name, "audio", "{version}"); + assert_eq!( + msg.group_order, + crate::track::Order::default().into(), + "{version}: the order a reader gets by default" + ); assert!(!msg.forward, "{version}: the SUBSCRIBE forwards"); let ok = ietf::SubscribeOk { From f4f120f2c30e613d3f34a0e52c7047ebbae1eb8f Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Thu, 22 Oct 2026 05:10:32 -0700 Subject: [PATCH 11/14] quest: reuse the planned SUBSCRIBE pause quest instead of a duplicate Co-Authored-By: Claude Opus 5.5 --- quest/m1/README.md | 3 +-- quest/m1/ietf-pause-subscribe.md | 36 -------------------------------- quest/m1/ietf-subscribe-pause.md | 4 ++-- quest/m1/listing-end-reason.md | 2 +- 4 files changed, 4 insertions(+), 41 deletions(-) delete mode 100644 quest/m1/ietf-pause-subscribe.md diff --git a/quest/m1/README.md b/quest/m1/README.md index 359b73973fc..b54281eb474 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -77,7 +77,7 @@ lite-07 stream type here. - [A widened max age re-offers cached groups](/quest/m1/resolved-demand.md) - a warm relay serves a reader with a wider max age the cached groups a cold relay would, with no wire change - [Drop set](/quest/m1/drop-set.md) - each cursor judges missing groups against its own budget, so a narrow reader drops promptly and a widening re-offers groups already reported dropped on lite-07 - [Broadcast archives](/quest/m1/archive/README.md) - ANNOUNCE, TRACKS, and a SUBSCRIBE per track record every track under a prefix to any object_store, a host serves a stored broadcast back, and the catalog drops its archive pointer for an opt-in `hls` field -- [The IETF answerer pauses any subscription](/quest/m1/ietf-pause-subscribe.md) - a SUBSCRIBE with FORWARD=0, or a REQUEST_UPDATE setting FORWARD, pauses and resumes it on drafts 18+, so a Rust-to-Rust IETF listing never fails over a pause +- [Pause an IETF SUBSCRIBE](/quest/m1/ietf-subscribe-pause.md) - Forward=0 pauses a SUBSCRIBE without demand upstream and Forward=1 resumes it, instead of ending it - [A listing says whether a removed track finished](/quest/m1/listing-end-reason.md) - a listing removal carries whether the track finished, at every hop, so the IETF answerer ends a finished track's PUBLISH with TRACK_ENDED and a Rust-to-Rust IETF listing removes it without a reset - [Compressed tracks](/quest/m1/compress/README.md) - a track flagged `compress` is DEFLATEd per group by moq-net, forwarded compressed, and inflated once on the relay for peers that cannot signal it; `catalog.json.z` and moq-flate go away - [Finalize moq-lite-07](/quest/m1/lite07-finalize.md) - when the maintainer cuts it, lite-07 negotiates as `moq-lite-07` and the next release ships it @@ -87,7 +87,6 @@ lite-07 stream type here. - [A public model](/quest/m1/public-model/README.md) - every model item a built-in session reaches is public, unnecessary, or marked deliberately private, so a custom publisher, subscriber, or relay builds from the public model alone - [JSON window timestamps](/quest/m1/json-window-timestamps.md) - Rust and JS window consumers return each event's frame timestamp like the snapshot and stream consumers - [FETCH_OK whole group](/quest/m1/ietf-fetch-end-location.md) - on drafts 14 to 19, FETCH_OK End Object 0 means the whole group in both directions, and a FETCH ending at the maximum group is refused as unsupported -- [Pause an IETF SUBSCRIBE](/quest/m1/ietf-subscribe-pause.md) - Forward=0 pauses a SUBSCRIBE without demand upstream and Forward=1 resumes it, instead of ending it - [JavaScript FETCH](/quest/m1/js-fetch.md) - browser publishers answer IETF FETCH through the JS ranges request surface - [IETF fill timeout](/quest/m1/ietf-fill-timeout.md) - native FILL_TIMEOUT bounds upstream waiting on drafts 18-22, alongside local content-age enforcement - [Rust identity enforcement](/quest/m1/catalog-identity-rs.md) - `moq-mux` refuses a redefined rendition, and every Rust publisher mints a new rendition name for a decoder identity change and updates everything else in place diff --git a/quest/m1/ietf-pause-subscribe.md b/quest/m1/ietf-pause-subscribe.md deleted file mode 100644 index a117aa03c3a..00000000000 --- a/quest/m1/ietf-pause-subscribe.md +++ /dev/null @@ -1,36 +0,0 @@ -# [M] The IETF answerer pauses any subscription - -## Goal - -On drafts 18 and later, the Rust moq-transport answerer serves a SUBSCRIBE -with FORWARD=0 paused, and pauses or resumes any Established subscription -when a REQUEST_UPDATE sets FORWARD, as it already does for a PUBLISH it made -for SUBSCRIBE_TRACKS. Draft-22 section 3.1.1 lets the initiator set FORWARD on -SUBSCRIBE and the subscriber change it with REQUEST_UPDATE; today we refuse -both with NOT_SUPPORTED. - -This is what a clean Rust-to-Rust IETF listing needs -([moq-dev/moq#6280](https://github.com/moq-dev/moq/pull/6280)): a listed -track held through our own SUBSCRIBE pauses once its last reader leaves, and a -skipped track is listed through a paused SUBSCRIBE. Against a Rust answerer -both fail the listing today, so readers list again, and a track skipped at -the answerer's subscription cap is never listed at all. - -## Plan - -- Reuse what the paused PUBLISH already does in - `rs/moq-net/src/ietf/publisher/tracks.rs` (pause, resume with the update's - filter and fill, answer with LARGEST_OBJECT, a joining FETCH refused while - paused) rather than a second implementation for SUBSCRIBE. -- A paused subscription forwards nothing, so a hostile subscriber can park - many: count each against the same subscription slots a forwarding one - takes. -- Drafts 14-17 keep refusing FORWARD=0; check what each draft allows before - widening it. -- Test over drafts 18-22 on mock time, including the outbound listing from - #6280: a SUBSCRIBE-held listed track pauses with its listing intact, and a - skipped track lists. - -## Related - -- [Broadcast archives](/quest/m1/archive/README.md) - lists an IETF peer's tracks through SUBSCRIBE_TRACKS diff --git a/quest/m1/ietf-subscribe-pause.md b/quest/m1/ietf-subscribe-pause.md index 319846d446a..04fa6bd39a8 100644 --- a/quest/m1/ietf-subscribe-pause.md +++ b/quest/m1/ietf-subscribe-pause.md @@ -31,7 +31,7 @@ paused wait watches only listing removal, session close, and the auth gate, so a SUBSCRIBE paused there would never see its track end. Keep a watcher for the track's end while paused, so a track that ends sends PUBLISH_DONE with TRACK_ENDED, which the paused-SUBSCRIBE removal in -[outbound SUBSCRIBE_TRACKS](/quest/m1/archive/subscribe-tracks-outbound.md) +outbound SUBSCRIBE_TRACKS ([moq-dev/moq#6280](https://github.com/moq-dev/moq/pull/6280)) relies on. Carry the SUBSCRIBE's grant across the pause too: `apply_subscription_update` returns `Served::Paused` before it starts `verify_renewal`, and the paused loop refuses AUTHORIZATION TOKEN. A @@ -58,4 +58,4 @@ served instead of refused. ## Related -- [Outbound SUBSCRIBE_TRACKS](/quest/m1/archive/subscribe-tracks-outbound.md) - the subscriber side that sends Forward=0 and toggles it +- [Broadcast archives](/quest/m1/archive/README.md) - lists an IETF peer's tracks through SUBSCRIBE_TRACKS, which sends Forward=0 and toggles it diff --git a/quest/m1/listing-end-reason.md b/quest/m1/listing-end-reason.md index 10294de9557..7aafb0d0173 100644 --- a/quest/m1/listing-end-reason.md +++ b/quest/m1/listing-end-reason.md @@ -30,4 +30,4 @@ and the answerer sends TRACK_ENDED only for a track that really finished. ## Related - [Broadcast archives](/quest/m1/archive/README.md) - lists an IETF peer's tracks through SUBSCRIBE_TRACKS -- [The IETF answerer pauses any subscription](/quest/m1/ietf-pause-subscribe.md) - the other gap in a clean Rust-to-Rust IETF listing +- [Pause an IETF SUBSCRIBE](/quest/m1/ietf-subscribe-pause.md) - the other gap in a clean Rust-to-Rust IETF listing From 960f0ba8ca2e3b47ea3aad4cc50d69d36efe7148 Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Thu, 22 Oct 2026 10:05:10 -0700 Subject: [PATCH 12/14] quest(m1): settle the listing end reason's API and lite-07 event Co-Authored-By: Claude Opus 5.5 --- quest/m1/listing-end-reason.md | 16 ++++++++++++---- quest/m1/lite07-finalize.md | 1 + 2 files changed, 13 insertions(+), 4 deletions(-) diff --git a/quest/m1/listing-end-reason.md b/quest/m1/listing-end-reason.md index 7aafb0d0173..8825201dc58 100644 --- a/quest/m1/listing-end-reason.md +++ b/quest/m1/listing-end-reason.md @@ -18,10 +18,18 @@ and the answerer sends TRACK_ENDED only for a track that really finished. ## Plan -- Public API and wire, so settle the shape with the maintainer first: how - `TracksEvent::Removed` and `broadcast::Lister::remove` carry the end, and a - lite-07 TRACKS_REMOVE field so a relay chain keeps it (`drafts/` and js/net - in the same change). +Decided 2026-10-22 (maintainer), public API and wire: + +- Rust and JS gain a `TracksEvent::Finished { name }` variant beside + `Removed { name }`, which now means unfinished, and `Lister::finish(name)` + beside `remove`. Rejected: a `finished: bool` flag, and an `End` enum on + `Removed`. +- lite-07 gains a TRACKS_FINISH event type on the Tracks Stream, with the same + body as TRACKS_REMOVE, so a relay chain keeps the distinction. TRACKS_REMOVE + keeps its meaning. Rejected: a reason field on TRACKS_REMOVE. Update + `drafts/draft-lcurley-moq-lite.md` and js/net in the same change. +- It lands before the lite-07 freeze: [Finalize moq-lite-07](/quest/m1/lite07-finalize.md) + Requires it. - A relay's copy reports what its upstream reported, never what its cache happens to know. - Test Rust-to-Rust over drafts 18-22: a finished track is removed, an diff --git a/quest/m1/lite07-finalize.md b/quest/m1/lite07-finalize.md index 2948209b5f4..1f342c9339f 100644 --- a/quest/m1/lite07-finalize.md +++ b/quest/m1/lite07-finalize.md @@ -96,6 +96,7 @@ is published; older versions are unchanged. - [Announcement takeover](/quest/m1/announce-takeover.md) - ANNOUNCE_TAKEOVER preserves a proven instance under a new independent route - [Compressed tracks in js/net](/quest/m1/compress/js.md) - JS reads and writes compressed lite-07 tracks instead of refusing them - [TRACKS in js/net](/quest/m1/archive/tracks-js.md) - JS speaks lite-07's Tracks Stream, which Rust already does +- [Listing end reason](/quest/m1/listing-end-reason.md) - lite-07's TRACKS_FINISH says a listed track finished, so an IETF answerer can end it with TRACK_ENDED - [lite-07 padding](/quest/m1/lite07-padding.md) - lite-07 reserves the padding stream type the browser probes with ## Related From 5b42255d77bedd325806067be50a9e495a99cd3a Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 22 Oct 2026 11:42:29 -0700 Subject: [PATCH 13/14] fix(ietf): fail a listing on an unsupported PUBLISH, check owed answers, end a failed paused copy - A listed PUBLISH whose properties we cannot take now fails the listing, as a refused paused SUBSCRIBE already did, instead of leaving it silently short a track. - The REQUEST_UPDATE answers a held subscription owes are decoded before they count, so a malformed one closes the session like any other malformed control message. - A paused upstream ending in error aborts the copy a reader left lingering. TRACK_ENDED leaves it idle, since its end lies past groups the paused copy never saw. - Tests prove SUBSCRIBE_TRACKS goes out only for a listing, and that a peer refusing, resetting, or ignoring it leaves a plain SUBSCRIBE working. - The concept page keeps the behavior a user needs; the wire accounting stays in rustdoc. Co-Authored-By: Claude Opus 5.5 --- doc/concept/standard.md | 2 +- rs/moq-net/src/ietf/subscriber.rs | 4 + rs/moq-net/src/ietf/subscriber/tracks.rs | 276 +++++++++++++++++--- rs/moq-net/tests/integration/tracks_ietf.rs | 68 ++++- 4 files changed, 311 insertions(+), 39 deletions(-) diff --git a/doc/concept/standard.md b/doc/concept/standard.md index d6cbc7046b8..894ca553d4b 100644 --- a/doc/concept/standard.md +++ b/doc/concept/standard.md @@ -27,7 +27,7 @@ subset drops. What a peer actually observes against this implementation: - **Pull.** Subscribers ask. Single-track `PUBLISH` offers are declined, unless they answer our `SUBSCRIBE_TRACKS` (below); announce a namespace and serve the resulting subscriptions. Announcements go out unsolicited, and we also ask for every prefix we may discover. The solicit `SETUP` option makes us wait to be asked. Without it, a draft 16+ peer also gets each match as a `NAMESPACE` on its `SUBSCRIBE_NAMESPACE` stream, so it hears the namespace twice. We send `PUBLISH` only to answer a `SUBSCRIBE_TRACKS` (below): on drafts 16 and 17 a `SUBSCRIBE_NAMESPACE` asking only for `PUBLISH` is refused, one asking for both gets only `NAMESPACE`, and any other Subscribe Options value closes the session. - **`SUBSCRIBE_TRACKS` lists, it never pushes.** In Rust, on draft 18 and later, it lists every track of every broadcast under its prefix, later ones included. With `FORWARD=0`, each track gets a paused `PUBLISH` carrying its Track Properties, and an error `PUBLISH_DONE` once the track is no longer listed, never `TRACK_ENDED`, since the track may go on elsewhere. A `REQUEST_UPDATE` with `FORWARD=1` resumes one, served from the cache like a `SUBSCRIBE` with the update's filter and answered with `LARGEST_OBJECT`; `FORWARD=0` pauses it again. Each paused `PUBLISH` holds a subscription slot, and past the cap a track gets `PUBLISH_SKIPPED` (`PUBLISH_BLOCKED` on draft 18) instead. A listing that omits `FORWARD` or sets it to 1 asks for every track's objects: from draft 19 each track gets `PUBLISH_SKIPPED`, and the subscriber `SUBSCRIBE`s to what it wants; draft 18 has no such skip, so the request is refused with `NOT_SUPPORTED`. A prefix overlapping another listing gets `PREFIX_OVERLAP`, a `TRACK_PROPERTY_FILTER` gets `NOT_SUPPORTED`, and a `REQUEST_UPDATE` on the listing itself ends it. On draft 18, a `SUBSCRIBE` to a track we `PUBLISH`ed gets `DUPLICATE_SUBSCRIPTION`. Cancelling the listing stops new `PUBLISH`es, while those sent live on. A broadcast is listed only while our publish grant covers it, from scratch once it does. JavaScript refuses it with `NOT_SUPPORTED`. -- **A Rust TRACKS listing sends `SUBSCRIBE_TRACKS` upstream.** On draft 18 and later, listing a broadcast from a moq-transport peer sends `SUBSCRIBE_TRACKS` with `FORWARD=0` and holds each `PUBLISH` paused as its track's entry, its info from the Track Properties; before draft 18 the listing is refused as unsupported. A reader resumes that `PUBLISH` with a `REQUEST_UPDATE` (`FORWARD=1` plus the join's filter, and `FILL_PARAMETERS` from draft 20; a Joining `FETCH` on the `PUBLISH`'s Request ID before), and the last reader leaving pauses it again, so a listed track is never subscribed twice. Only a `PUBLISH_DONE` with `TRACK_ENDED` removes the track; any other status, including the error our own answerer sends once a track is no longer listed, fails every listing the request serves, and the readers ask again. A skipped track is listed through a paused `SUBSCRIBE` once its `SUBSCRIBE_OK` arrives, and a track we already `SUBSCRIBE`d is listed through that `SUBSCRIBE`, its `PUBLISH` refused with `DUPLICATE_SUBSCRIPTION` on draft 18 and `UNINTERESTED` after. One request covers each chain of nested broadcasts: a nested listing reuses the broader one, and a broader one replaces the nested requests once the peer has closed them. Each held track counts against the session's announce cap; past it, the `PUBLISH` is refused with `EXCESSIVE_LOAD` and the listing reset. A Rust answerer refuses `FORWARD=0` on a `SUBSCRIBE`, so pausing a listed track we `SUBSCRIBE`d fails that listing once, which asks again. +- **A Rust TRACKS listing sends `SUBSCRIBE_TRACKS` upstream, only on demand.** Listing a broadcast from a moq-transport peer on draft 18 and later sends `SUBSCRIBE_TRACKS` with `FORWARD=0` while someone lists it, never on connect, announce, or subscribe, so a peer that refuses, resets, or ignores it affects only that listing. Before draft 18 the listing is refused as unsupported. Each listed track's paused `PUBLISH` is its upstream copy, which a reader resumes rather than subscribing again. Only a `PUBLISH_DONE` with `TRACK_ENDED` removes a listed track; any other end, including the error our own answerer sends for an unlisted track, fails the listing, and readers list again. - **History is one group.** In Rust, Object ID gaps must be marked by Prior Object ID Gap properties for a group to be fetchable. A `FETCH` returns one group from the cache, or on drafts 14 through 19 the saved prefix of the group a new subscription just joined. A range of groups is refused, as is a draft 20+ `LOCATION_FILTER` that ends at Largest Object rather than an absolute End Location. On draft 20 and later, `FETCH_OK`'s End Location is the requested end, capped at Largest Object: a range holding no objects gets an empty fetch stream, and only a start past Largest Object is refused, with `INVALID_RANGE`. A relay's copy with no upstream subscription can't know Largest Object short of the track's end, so it echoes the requested end instead. JavaScript publishing refuses every `FETCH`. Datagrams are never fetchable. A Rust reader that only fetches learns the track from `TRACK_STATUS` instead of subscribing, so a finished track stays fetchable; draft 17 still subscribes, since its `TRACK_STATUS` answer cannot say whether the track is timed, and so does a reader whose publisher refuses `TRACK_STATUS` as `NOT_SUPPORTED`. - **Compression.** Rust peers on draft 17 and later exchange compressed tracks when both offer the [Flate extension](/draft/moq-flate). Older peers receive one shared inflated copy. A publisher that seals the compression declaration makes that fallback unavailable: an incompatible peer is refused, preserving the sealed metadata. JavaScript does not offer the IETF extension. - **Timing.** A track whose `SUBSCRIBE_OK` declares no `TIMESCALE` is untimed, as is every track on drafts 14 through 16. A Rust reader that never subscribed takes the units from `TRACK_STATUS` on draft 18 and later. diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index 95b9421316e..da5acf5618a 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -2887,6 +2887,8 @@ where alias, properties, owed, + // This subscription forwards into the copy itself from here. + copy: _, } = upstream; held = Some(tracks::Resumed { alias, @@ -3168,6 +3170,7 @@ where alias: held.alias, properties: held.properties, owed: held.owed + 1, + copy: resumed.as_ref().map(|idle| idle.track.clone()), }; self.pause(key, upstream).await; return resumed; @@ -3586,6 +3589,7 @@ where alias, properties: held_properties, owed: unanswered.load(Ordering::Relaxed), + copy: Some(track.clone()), }; self.pause(key, upstream).await; return Some(Idle { diff --git a/rs/moq-net/src/ietf/subscriber/tracks.rs b/rs/moq-net/src/ietf/subscriber/tracks.rs index c5a7c82cb62..66315a6e217 100644 --- a/rs/moq-net/src/ietf/subscriber/tracks.rs +++ b/rs/moq-net/src/ietf/subscriber/tracks.rs @@ -13,6 +13,10 @@ //! keeping the subscriptions they made. Any end of a held subscription other than //! TRACK_ENDED fails every listing its request serves, which then asks again, rather //! than hide a track that may still be live. +//! +//! Nothing goes out until a broadcast is listed: many peers do not implement +//! SUBSCRIBE_TRACKS yet, and one that refuses, resets, or ignores it fails or empties only +//! that listing, leaving the session and its SUBSCRIBEs alone. use std::sync::Arc; @@ -46,6 +50,8 @@ pub(super) struct Upstream { pub(super) properties: ietf::Properties, /// REQUEST_UPDATE answers still owed, read before anything else. pub(super) owed: u64, + /// The copy a reader left lingering, which a failed upstream aborts. + pub(super) copy: Option, } /// Hands a paused subscription from the task watching it to a subscription resuming it. @@ -733,6 +739,7 @@ where alias: accepted.alias, properties: accepted.properties, owed: 0, + copy: None, })) } @@ -789,10 +796,11 @@ where } else if listings.entries.contains_key(&key) { Offer::Refuse(duplicate, "already subscribed") } else if let Some(err) = refused(&msg.properties, self.version, flate) { - Offer::Refuse( - request::to_code(&err, request::Kind::Publish, self.version), - "track properties not supported", - ) + // The peer sends nothing else for the track, so a listing left standing would + // silently miss it, as with a refused paused SUBSCRIBE. + let code = request::to_code(&err, request::Kind::Publish, self.version); + listings.fail(&key.0, err); + Offer::Refuse(code, "track properties not supported") } else { match self.announces.acquire() { Err(err) => { @@ -889,6 +897,7 @@ where alias: msg.track_alias, properties: msg.properties, owed: 0, + copy: None, }; self.watch(key, upstream, handoff).await; Ok(()) @@ -952,6 +961,9 @@ where Step::Message(Ok(Some(Framed(id, body)))) => match id { // The answer to a pause, or to a resume that paused again before it landed. ietf::RequestOk::ID | ietf::RequestError::ID if upstream.owed > 0 => { + if let Err(err) = self.owed_answer(id, &body) { + break Err(upstream.messages.failed(err)); + } upstream.owed -= 1; } ietf::PublishDone::ID => { @@ -970,6 +982,12 @@ where tracing::debug!(broadcast = %key.0, track = %key.1, ?end, "held subscription ended"); self.remove_subscribe(upstream.request_id); let _ = upstream.stream.writer.finish(); + // A failed upstream fails the copy, as it would while forwarding. TRACK_ENDED leaves it + // idle: the end is past groups it never saw, so a returning reader's SUBSCRIBE learns + // where, as for a copy whose subscription was cancelled. + if let (Err(err), Some(copy)) = (&end, upstream.copy.take()) { + let _ = copy.abort(err.clone()); + } let mut listings = self.listings.lock(); if listings.watched_by(&key, &handoff).is_some() { match end { @@ -1149,6 +1167,16 @@ where .await } + /// Check the answer to a REQUEST_UPDATE a held subscription still owes. It carries + /// nothing to act on: a refused one is followed by the PUBLISH_DONE that ends it. + fn owed_answer(&self, id: u64, body: &ietf::Body) -> Result<(), Error> { + match id { + ietf::RequestOk::ID => body.message::(self.version).map(|_| ())?, + _ => body.message::(self.version).map(|_| ())?, + } + Ok(()) + } + /// Read the answer to a SUBSCRIBE, or to the REQUEST_UPDATE resuming `held`. pub(super) async fn read_answer( &self, @@ -1163,7 +1191,10 @@ where let Framed(id, body) = messages.message(&mut stream.reader).await?; match id { // The answer to a pause that went out before this resume. - ietf::RequestOk::ID | ietf::RequestError::ID if held.owed > 0 => held.owed -= 1, + ietf::RequestOk::ID | ietf::RequestError::ID if held.owed > 0 => { + self.owed_answer(id, &body)?; + held.owed -= 1; + } ietf::RequestOk::ID => { let ok = body.message::(self.version)?; tracing::debug!(message = ?ok, "subscription resumed"); @@ -1326,7 +1357,7 @@ mod tests { /// PUBLISH `name` paused, returning the stream once the subscriber holds it. async fn publish(&mut self, name: &str, request_id: u64) -> PeerStream { - let (stream, id, _) = self.offer("bcast", name, request_id).await; + let (stream, id, _) = self.offer("bcast", name, request_id, Default::default()).await; assert!( [ietf::RequestOk::ID, ietf::PublishOk::ID].contains(&id), "PUBLISH refused: {id:#x}" @@ -1334,8 +1365,78 @@ mod tests { stream } - /// PUBLISH `name` in `namespace` paused, returning the answer. - async fn offer(&mut self, namespace: &str, name: &str, request_id: u64) -> (PeerStream, u64, ietf::Body) { + /// A reader of `name`, served by the subscriber as a broadcast's request would be. + async fn read_track( + &mut self, + name: &str, + ) -> ( + crate::track::Consumer, + kio::Pending, + moq_clock::sim::JoinHandle<()>, + ) { + let mut dynamic = self._broadcast.dynamic(); + let track = self._broadcast.consume().track(name).unwrap(); + let reader = track.subscribe(None); + let request = dynamic.requested_track().await.expect("no track requested"); + let mut subscriber = self.subscriber.clone(); + let serving = moq_clock::sim::spawn(async move { + subscriber + .run_subscribe(Path::new("bcast"), dynamic, None, request) + .await; + }); + (track, reader, serving) + } + + /// Resume the held `video` for a reader, returning it once accepted. + async fn resume( + &mut self, + video: &mut PeerStream, + ) -> ( + crate::track::Consumer, + crate::track::Subscriber, + moq_clock::sim::JoinHandle<()>, + ) { + let (track, reader, serving) = self.read_track("video").await; + let (id, body) = read(video).await; + assert_eq!(id, ietf::SubscribeUpdate::ID, "not resumed"); + let resume: ietf::SubscribeUpdate = body.message(self.version).unwrap(); + assert_eq!(resume.forward, Some(true)); + let ok = ietf::RequestOk { + request_id: None, + active: None, + largest: None, + }; + write(video, ietf::RequestOk::ID, &ok).await; + let reader = moq_clock::timeout(TIMEOUT, reader) + .await + .expect("never accepted") + .unwrap(); + (track, reader, serving) + } + + /// Resume the held `video` for a reader, then let it go so the subscription pauses. + async fn resume_and_pause( + &mut self, + video: &mut PeerStream, + ) -> (crate::track::Consumer, moq_clock::sim::JoinHandle<()>) { + let (track, reader, serving) = self.resume(video).await; + drop(reader); + let (id, body) = read(video).await; + assert_eq!(id, ietf::SubscribeUpdate::ID, "not paused"); + let pause: ietf::SubscribeUpdate = body.message(self.version).unwrap(); + assert_eq!(pause.forward, Some(false)); + settle().await; + (track, serving) + } + + /// PUBLISH `name` in `namespace` paused with `properties`, returning the answer. + async fn offer( + &mut self, + namespace: &str, + name: &str, + request_id: u64, + properties: ietf::Properties, + ) -> (PeerStream, u64, ietf::Body) { let mut stream = Stream::open(&mut self.peer, self.version).await.unwrap(); let publish = ietf::Publish { request_id: RequestId(request_id), @@ -1344,7 +1445,7 @@ mod tests { track_alias: request_id, largest_location: None, forward: false, - properties: ietf::Properties::default(), + properties, subscriber_priority: None, group_order: None, filter: None, @@ -1383,10 +1484,10 @@ mod tests { for (version, duplicate) in [(Version::Draft18, 0x19), (Version::Draft19, 0x20)] { let mut h = harness(version); let _listing = h.establish().await; - let (_, id, body) = h.offer("other", "video", 1).await; + let (_, id, body) = h.offer("other", "video", 1, Default::default()).await; assert_eq!(refusal(id, &body, version), 0x3, "{version}: unsolicited"); let _video = h.publish("video", 3).await; - let (_, id, body) = h.offer("bcast", "video", 5).await; + let (_, id, body) = h.offer("bcast", "video", 5, Default::default()).await; assert_eq!(refusal(id, &body, version), duplicate, "{version}: redundant"); } } @@ -1449,27 +1550,7 @@ mod tests { let mut video = h.publish("video", 1).await; assert_eq!(event(&mut h.tracks).as_deref(), Some("+video")); - let mut dynamic = h._broadcast.dynamic(); - let track = h._broadcast.consume().track("video").unwrap(); - let _reader = track.subscribe(None); - let request = dynamic.requested_track().await.expect("no track requested"); - let mut subscriber = h.subscriber.clone(); - let _serving = moq_clock::sim::spawn(async move { - subscriber - .run_subscribe(Path::new("bcast"), dynamic, None, request) - .await; - }); - - let (id, body) = read(&mut video).await; - assert_eq!(id, ietf::SubscribeUpdate::ID, "not resumed"); - let resume: ietf::SubscribeUpdate = body.message(version).unwrap(); - assert_eq!(resume.forward, Some(true)); - let ok = ietf::RequestOk { - request_id: None, - active: None, - largest: None, - }; - write(&mut video, ietf::RequestOk::ID, &ok).await; + let (_track, _reader, _serving) = h.resume(&mut video).await; assert!(h.listening.poll_failed(&kio::Waiter::noop()).is_pending()); // SUBSCRIPTION_ENDED, which drafts 18 and 19 register. @@ -1556,6 +1637,137 @@ mod tests { )); } + /// A listed PUBLISH whose properties we cannot take fails the listing: the peer sends + /// nothing else for that track, so a listing left standing would silently miss it. + #[moq_clock::test] + async fn an_unsupported_publish_fails_the_listing() { + let version = Version::Draft22; + let mut h = harness(version); + let _listing = h.establish().await; + let compressed = ietf::Properties { + compress: true, + ..Default::default() + }; + let (_, id, _) = h.offer("bcast", "video", 1, compressed).await; + assert_eq!(id, ietf::RequestError::ID, "accepted"); + assert!(matches!( + h.listening.poll_failed(&kio::Waiter::noop()), + Poll::Ready(Error::UnsupportedExtension) + )); + } + + /// A paused track's upstream failing aborts the copy a reader left lingering, rather + /// than leave it open with nothing upstream. + #[moq_clock::test] + async fn a_paused_track_failing_aborts_its_lingering_copy() { + let version = Version::Draft22; + let mut h = harness(version); + let _listing = h.establish().await; + let mut video = h.publish("video", 1).await; + let (track, serving) = h.resume_and_pause(&mut video).await; + assert!(!serving.is_finished(), "the copy did not linger"); + + let done = ietf::PublishDone { + request_id: None, + status_code: ietf::PublishDoneStatus::InternalError.code(version), + stream_count: 0, + reason_phrase: "".into(), + }; + write(&mut video, ietf::PublishDone::ID, &done).await; + assert!(serving.is_finished(), "the copy outlived its upstream"); + drop(track); + } + + /// The answer a pause owes is decoded like any other, so a malformed one closes the + /// session rather than count as an answer. + #[moq_clock::test] + async fn a_malformed_pause_answer_closes_the_session() { + let version = Version::Draft22; + let mut h = harness(version); + let _listing = h.establish().await; + let mut video = h.publish("video", 1).await; + let (_track, _serving) = h.resume_and_pause(&mut video).await; + + // A REQUEST_OK with no parameters, then a trailing byte. + video.writer.varint(ietf::RequestOk::ID).await.unwrap(); + video + .writer + .write_all(&mut &[0x00, 0x02, 0x00, 0xff][..]) + .await + .unwrap(); + let mut peer = h.peer.clone(); + let closed = + kio::wait(move |waiter| crate::transport::poll::Session::poll_closed(&mut peer, &mut waiter.context())); + moq_clock::timeout(TIMEOUT, closed) + .await + .expect("the session stayed up"); + } + + /// A peer that refuses SUBSCRIBE_TRACKS, resets it, or never answers it fails at most + /// that listing: a plain SUBSCRIBE still goes out and is accepted on the session. + #[moq_clock::test] + async fn a_peer_not_answering_the_listing_still_serves_subscribe() { + let version = Version::Draft22; + for case in ["refused", "reset", "silent"] { + let mut h = harness(version); + let mut listing = moq_clock::timeout(TIMEOUT, Stream::accept(&mut h.peer, version)) + .await + .expect("no SUBSCRIBE_TRACKS") + .unwrap(); + let (id, _) = read(&mut listing).await; + assert_eq!(id, ietf::SubscribeTracks::ID); + let _held = match case { + "refused" => { + let refused = ietf::RequestError { + request_id: None, + error_code: 0x3, + reason_phrase: "".into(), + retry_interval: 0, + }; + write(&mut listing, ietf::RequestError::ID, &refused).await; + None + } + "reset" => { + let Stream { writer, reader } = listing; + writer.abort(&Error::Cancel); + settle().await; + Some(reader) + } + _ => { + settle().await; + Some(listing.reader) + } + }; + let failed = h.listening.poll_failed(&kio::Waiter::noop()); + match case { + "refused" => assert!(matches!(failed, Poll::Ready(Error::Unsupported)), "{case}: {failed:?}"), + "reset" => assert!(failed.is_ready(), "{case}: the listing stood"), + _ => assert!(failed.is_pending(), "{case}: the listing failed"), + } + + let (_track, reader, _serving) = h.read_track("video").await; + let mut stream = moq_clock::timeout(TIMEOUT, Stream::accept(&mut h.peer, version)) + .await + .expect("no SUBSCRIBE") + .unwrap(); + let (id, body) = read(&mut stream).await; + assert_eq!(id, ietf::Subscribe::ID, "{case}"); + let msg: ietf::Subscribe = body.message(version).unwrap(); + assert!(msg.forward, "{case}: a paused SUBSCRIBE"); + let ok = ietf::SubscribeOk { + request_id: None, + track_alias: 7, + largest: None, + properties: ietf::Properties::default(), + }; + write(&mut stream, ietf::SubscribeOk::ID, &ok).await; + moq_clock::timeout(TIMEOUT, reader) + .await + .expect("never accepted") + .unwrap_or_else(|err| panic!("{case}: {err}")); + } + } + /// Dropping the listing cancels its SUBSCRIBE_TRACKS: FIN on draft-18, RESET_STREAM from /// draft-19, where a FIN is no cancel. The held PUBLISHes are let go with it. #[moq_clock::test] diff --git a/rs/moq-net/tests/integration/tracks_ietf.rs b/rs/moq-net/tests/integration/tracks_ietf.rs index 2de2646df4f..ac3472acf67 100644 --- a/rs/moq-net/tests/integration/tracks_ietf.rs +++ b/rs/moq-net/tests/integration/tracks_ietf.rs @@ -28,6 +28,9 @@ const DRAFTS: [&str; 5] = [ /// SUBSCRIBE (0x03), as the first byte of a request stream. const SUBSCRIBE: u8 = 0x03; +/// SUBSCRIBE_TRACKS (0x51), as the first byte of a request stream. +const SUBSCRIBE_TRACKS: u8 = 0x51; + fn produce_origin(hop: u64) -> moq_net::origin::Producer { let (producer, driver) = moq_net::origin::Producer::new(moq_net::origin::Config::new(Hop::new(hop).unwrap())); support::harness::spawn(driver); @@ -72,15 +75,20 @@ async fn resolve(origin: &moq_net::origin::Producer, path: &str) -> moq_net::bro .expect("routed") } -/// How many SUBSCRIBE request streams the client has opened. -fn subscribes(pair: &MockPair) -> usize { +/// How many request streams of `kind` the client has opened. +fn opened(pair: &MockPair, kind: u8) -> usize { pair.client_transport .bidi_types() .iter() - .filter(|first| **first == SUBSCRIBE) + .filter(|first| **first == kind) .count() } +/// How many SUBSCRIBE request streams the client has opened. +fn subscribes(pair: &MockPair) -> usize { + opened(pair, SUBSCRIBE) +} + /// Read one frame of the next group, or `None` once the subscription ends. async fn read(sub: &mut moq_net::track::Subscriber) -> Option<(u64, Vec)> { let mut group = moq_clock::timeout(TIMEOUT, sub.recv_group()) @@ -115,6 +123,40 @@ async fn an_ietf_session_lists_its_peers_tracks() { } } +/// SUBSCRIBE_TRACKS goes out only for a listing, since many peers do not answer it yet: +/// connecting, an announce, and a reader's SUBSCRIBE send none. +#[moq_clock::test] +async fn only_a_listing_sends_subscribe_tracks() { + for version in DRAFTS { + let publisher = produce_origin(1); + let broadcast = publisher.create_broadcast("bcast").unwrap(); + let video = broadcast.create_track("video", None).unwrap(); + broadcast.announce(Default::default()).unwrap(); + + let (subscriber, pair) = connect(&publisher, version).await; + let remote = resolve(&subscriber, "bcast").await; + let mut sub = moq_clock::timeout(TIMEOUT, remote.track("video").unwrap().subscribe(None)) + .await + .expect("subscribe timeout") + .expect("subscribe"); + moq_clock::timeout(TIMEOUT, support::wanted(video.demand())) + .await + .expect("never subscribed") + .unwrap(); + let mut group = video.append_group().unwrap(); + group.write_frame(None, &b"frame"[..]).unwrap(); + group.finish().unwrap(); + assert_eq!(read(&mut sub).await, Some((0, b"frame".to_vec())), "{version}"); + assert_eq!(subscribes(&pair), 1, "{version}"); + assert_eq!(opened(&pair, SUBSCRIBE_TRACKS), 0, "{version}: listed unasked"); + + let mut tracks = remote.tracks().unwrap(); + assert_eq!(next(&mut tracks).await, "synced", "{version}"); + assert_eq!(next(&mut tracks).await, "+video", "{version}"); + assert_eq!(opened(&pair, SUBSCRIBE_TRACKS), 1, "{version}"); + } +} + /// A listed track carries the info its PUBLISH declared. #[moq_clock::test] async fn a_listing_carries_track_info() { @@ -142,20 +184,34 @@ async fn a_listing_carries_track_info() { } /// Before draft-18 there is no SUBSCRIBE_TRACKS, so the listing is refused rather than -/// answered empty. +/// answered empty, and a reader still subscribes. #[moq_clock::test] async fn before_draft_18_the_listing_is_refused() { let publisher = produce_origin(1); let broadcast = publisher.create_broadcast("bcast").unwrap(); - let _a = broadcast.create_track("a", None).unwrap(); + let a = broadcast.create_track("a", None).unwrap(); broadcast.announce(Default::default()).unwrap(); let (subscriber, _pair) = connect(&publisher, "moq-transport-17").await; - let mut tracks = resolve(&subscriber, "bcast").await.tracks().unwrap(); + let remote = resolve(&subscriber, "bcast").await; + let mut tracks = remote.tracks().unwrap(); assert_eq!( next(&mut tracks).await, format!("error: {}", moq_net::Error::Unsupported) ); + + let mut sub = moq_clock::timeout(TIMEOUT, remote.track("a").unwrap().subscribe(None)) + .await + .expect("subscribe timeout") + .expect("subscribe"); + moq_clock::timeout(TIMEOUT, support::wanted(a.demand())) + .await + .expect("never subscribed") + .unwrap(); + let mut group = a.append_group().unwrap(); + group.write_frame(None, &b"frame"[..]).unwrap(); + group.finish().unwrap(); + assert_eq!(read(&mut sub).await, Some((0, b"frame".to_vec()))); } /// A reader of a listed track resumes its held PUBLISH, so its data arrives with no From 3b354f3d47ac6133a5c88b732d90489ab5b2caf5 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 22 Oct 2026 11:53:37 -0700 Subject: [PATCH 14/14] fix(ietf): refuse a forwarding PUBLISH for a paused listing, resubscribe a track that ends mid-resume - From draft-20 a PUBLISH answering our FORWARD=0 SUBSCRIBE_TRACKS with FORWARD=1 has no PUBLISH_OK field to pause it, so it is refused and the listing fails instead of having its objects refused unseen. Through draft-19 PUBLISH_OK still pauses it. - A lingering copy whose track ends with TRACK_ENDED before its resume is answered lingers again, so its waiting reader's SUBSCRIBE learns the real end, rather than aborting a clean finish it cannot place. Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/ietf/subscriber.rs | 6 ++ rs/moq-net/src/ietf/subscriber/tracks.rs | 132 ++++++++++++++++++----- 2 files changed, 111 insertions(+), 27 deletions(-) diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index da5acf5618a..5f1e0b191ed 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -3231,7 +3231,13 @@ where // cancelled since its PUBLISH_DONE has yet to come. let ended = held.as_mut().and_then(|held| held.ended.take()); let cancel = unanswered || (held.is_some() && ended.is_none()); + let finished = matches!(ended, Some(Ok(()))); self.entry_ended(&key, request_id, ended.unwrap_or_else(|| Err(err.clone()))); + // A resumed copy whose track finished before the resume was answered cannot + // place the end, so it lingers again and its reader's SUBSCRIBE learns it. + if finished && resumed.is_some() { + return resumed; + } if let Some(idle) = resumed { let _ = idle.track.abort(err); } diff --git a/rs/moq-net/src/ietf/subscriber/tracks.rs b/rs/moq-net/src/ietf/subscriber/tracks.rs index 66315a6e217..ec478786a07 100644 --- a/rs/moq-net/src/ietf/subscriber/tracks.rs +++ b/rs/moq-net/src/ietf/subscriber/tracks.rs @@ -795,6 +795,15 @@ where } } else if listings.entries.contains_key(&key) { Offer::Refuse(duplicate, "already subscribed") + } else if msg.forward && !matches!(self.version, Version::Draft18 | Version::Draft19) { + // From draft-20 the PUBLISH sets its own Forward State, and PUBLISH_OK has no + // FORWARD to pause it: its objects would be refused unseen behind a healthy + // listing. + listings.fail(&key.0, Error::Unsupported); + Offer::Refuse( + request::to_code(&Error::Unsupported, request::Kind::Publish, self.version), + "PUBLISH forwards for a paused listing", + ) } else if let Some(err) = refused(&msg.properties, self.version, flate) { // The peer sends nothing else for the track, so a listing left standing would // silently miss it, as with a refused paused SUBSCRIBE. @@ -1357,7 +1366,7 @@ mod tests { /// PUBLISH `name` paused, returning the stream once the subscriber holds it. async fn publish(&mut self, name: &str, request_id: u64) -> PeerStream { - let (stream, id, _) = self.offer("bcast", name, request_id, Default::default()).await; + let (stream, id, _) = self.offer(offered("bcast", name, request_id)).await; assert!( [ietf::RequestOk::ID, ietf::PublishOk::ID].contains(&id), "PUBLISH refused: {id:#x}" @@ -1429,27 +1438,9 @@ mod tests { (track, serving) } - /// PUBLISH `name` in `namespace` paused with `properties`, returning the answer. - async fn offer( - &mut self, - namespace: &str, - name: &str, - request_id: u64, - properties: ietf::Properties, - ) -> (PeerStream, u64, ietf::Body) { + /// Send `publish`, returning the answer. + async fn offer(&mut self, publish: ietf::Publish<'_>) -> (PeerStream, u64, ietf::Body) { let mut stream = Stream::open(&mut self.peer, self.version).await.unwrap(); - let publish = ietf::Publish { - request_id: RequestId(request_id), - track_namespace: Path::new(namespace), - track_name: name.into(), - track_alias: request_id, - largest_location: None, - forward: false, - properties, - subscriber_priority: None, - group_order: None, - filter: None, - }; stream.writer.varint(ietf::Publish::ID).await.unwrap(); stream.writer.encode(&publish).await.unwrap(); @@ -1470,6 +1461,22 @@ mod tests { } } + /// A paused PUBLISH of `name` in `namespace`, aliased by its request ID. + fn offered<'a>(namespace: &'a str, name: &'a str, request_id: u64) -> ietf::Publish<'a> { + ietf::Publish { + request_id: RequestId(request_id), + track_namespace: Path::new(namespace), + track_name: name.into(), + track_alias: request_id, + largest_location: None, + forward: false, + properties: ietf::Properties::default(), + subscriber_priority: None, + group_order: None, + filter: None, + } + } + /// The error code a refused PUBLISH answered with. fn refusal(id: u64, body: &ietf::Body, version: Version) -> u64 { assert_eq!(id, ietf::RequestError::ID, "accepted"); @@ -1484,10 +1491,10 @@ mod tests { for (version, duplicate) in [(Version::Draft18, 0x19), (Version::Draft19, 0x20)] { let mut h = harness(version); let _listing = h.establish().await; - let (_, id, body) = h.offer("other", "video", 1, Default::default()).await; + let (_, id, body) = h.offer(offered("other", "video", 1)).await; assert_eq!(refusal(id, &body, version), 0x3, "{version}: unsolicited"); let _video = h.publish("video", 3).await; - let (_, id, body) = h.offer("bcast", "video", 5, Default::default()).await; + let (_, id, body) = h.offer(offered("bcast", "video", 5)).await; assert_eq!(refusal(id, &body, version), duplicate, "{version}: redundant"); } } @@ -1644,11 +1651,14 @@ mod tests { let version = Version::Draft22; let mut h = harness(version); let _listing = h.establish().await; - let compressed = ietf::Properties { - compress: true, - ..Default::default() + let compressed = ietf::Publish { + properties: ietf::Properties { + compress: true, + ..Default::default() + }, + ..offered("bcast", "video", 1) }; - let (_, id, _) = h.offer("bcast", "video", 1, compressed).await; + let (_, id, _) = h.offer(compressed).await; assert_eq!(id, ietf::RequestError::ID, "accepted"); assert!(matches!( h.listening.poll_failed(&kio::Waiter::noop()), @@ -1656,6 +1666,74 @@ mod tests { )); } + /// From draft-20 a PUBLISH that forwards contradicts the paused listing it answers, and + /// nothing we send can pause it: it is refused and the listing fails, rather than have its + /// objects refused unseen. Through draft-19 our PUBLISH_OK pauses it. + #[moq_clock::test] + async fn a_forwarding_publish_fails_the_listing_from_draft_20() { + for version in [Version::Draft19, Version::Draft20] { + let mut h = harness(version); + let _listing = h.establish().await; + let forwarding = ietf::Publish { + forward: true, + ..offered("bcast", "video", 1) + }; + let (_, id, _) = h.offer(forwarding).await; + let failed = h.listening.poll_failed(&kio::Waiter::noop()); + match version { + Version::Draft19 => { + assert_ne!(id, ietf::RequestError::ID, "{version}: refused"); + assert!(failed.is_pending(), "{version}: {failed:?}"); + } + _ => { + assert_eq!(id, ietf::RequestError::ID, "{version}: accepted"); + assert!( + matches!(failed, Poll::Ready(Error::Unsupported)), + "{version}: {failed:?}" + ); + } + } + } + } + + /// A listed track that finishes before its resume is answered goes back to lingering, and + /// its waiting reader SUBSCRIBEs: the idle copy cannot place the end, which the SUBSCRIBE + /// learns, rather than abort a clean finish. + #[moq_clock::test] + async fn a_track_ending_before_its_resume_resubscribes() { + let version = Version::Draft22; + let mut h = harness(version); + let _listing = h.establish().await; + let mut video = h.publish("video", 1).await; + let (track, _serving) = h.resume_and_pause(&mut video).await; + + let _reader = track.subscribe(None); + let (id, body) = read(&mut video).await; + assert_eq!(id, ietf::SubscribeUpdate::ID, "not resumed"); + assert_eq!( + body.message::(version).unwrap().forward, + Some(true) + ); + let done = ietf::PublishDone { + request_id: None, + status_code: ietf::PublishDoneStatus::TrackEnded.code(version), + stream_count: 0, + reason_phrase: "".into(), + }; + write(&mut video, ietf::PublishDone::ID, &done).await; + assert!( + h.listening.poll_failed(&kio::Waiter::noop()).is_pending(), + "TRACK_ENDED failed the listing" + ); + + let mut stream = moq_clock::timeout(TIMEOUT, Stream::accept(&mut h.peer, version)) + .await + .expect("the copy did not SUBSCRIBE") + .unwrap(); + let (id, _) = read(&mut stream).await; + assert_eq!(id, ietf::Subscribe::ID); + } + /// A paused track's upstream failing aborts the copy a reader left lingering, rather /// than leave it open with nothing upstream. #[moq_clock::test]