diff --git a/quest/m1/subscribe-ranges/README.md b/quest/m1/subscribe-ranges/README.md index 6cb9c8ebe87..ad6cefbdf7b 100644 --- a/quest/m1/subscribe-ranges/README.md +++ b/quest/m1/subscribe-ranges/README.md @@ -76,7 +76,6 @@ every sequence delivered or dropped. - [Model ranges](/quest/m1/subscribe-ranges/model.md) - `Subscription` carries ranges, and `Dynamic` fills misses by range - [SUBSCRIBE_DROP](/quest/m1/subscribe-drop.md) - publishers name every group they won't deliver - [Lite-07 ranges](/quest/m1/subscribe-ranges/lite.md) - the lite-07 wire, Rust publisher and subscriber, and the draft -- [moq-transport FETCH and fill streams in the session queue](/quest/m1/subscribe-ranges/ietf-fetch-queue.md) - Rust FETCH and fill streams ranked against group streams; JS already ranks its fill and serves no FETCH - [moq-transport upstream updates](/quest/m1/subscribe-ranges/ietf-update.md) - the upstream request follows the aggregate priority; its order stays fixed, as every draft requires - [moq-transport ranges](/quest/m1/subscribe-ranges/ietf.md) - range FETCH upstream per missing run, and non-blocking FETCH served downstream - [JS ranges](/quest/m1/subscribe-ranges/js.md) - `@moq/net` model and lite-07 parity diff --git a/quest/m1/subscribe-ranges/ietf-fetch-queue.md b/quest/m1/subscribe-ranges/ietf-fetch-queue.md deleted file mode 100644 index 6c467747334..00000000000 --- a/quest/m1/subscribe-ranges/ietf-fetch-queue.md +++ /dev/null @@ -1,57 +0,0 @@ -# [S] moq-transport FETCH and fill streams in the session queue - -## Goal - -Under congestion, a moq-transport FETCH or fill stream competes with the -session's group streams through the same priority queue: a fill as the group -it fills, a standalone FETCH by its subscriber priority. Today the Rust -moq-transport publisher gives these streams the raw subscriber priority as -their send order, mixing an absolute priority with the queue's relative ranks -(send order `255 - rank`), so how they compare with group streams is -arbitrary. - -## Plan - -Where it stands after #5385 (`rs/moq-net/src/ietf/publisher.rs`): - -- Group streams take a `Rank` from the session `PriorityQueue` through - `TrackServe::rank(sequence)`, keyed by the subscription's request id and - ordered by its `Order`. -- `run_fill` calls `stream.set_priority(priority)` with the raw subscriber - priority, and so does the FETCH stream in `run_fetch_stream`. - -The work: - -- A draft-20 fill joins its subscription's ranking as the group it fills, - the way JS already ranks it (`js/net/src/ietf/publisher.ts`, `#runFill`). - A joining FETCH, used before draft-20, ranks the same way within the - subscription it joins. -- A standalone FETCH gets its own queue entry, keyed by its own request id. - `Priority::cmp` compares that id before order or group, so the FETCH ranks - against group streams by subscriber priority alone, with the id breaking - ties. Its group and GROUP_ORDER do not affect the rank. It follows - priority changes the way a group stream's `Rank` does. -- JS parity (decided 2026-10-13 in #5400). JS already ranks its fill through - the subscription's `Priority`. It serves no standalone FETCH: `runFetch` - (`js/net/src/ietf/publisher.ts`) refuses every one. So JS has nothing to - change now, and any FETCH serving it gains later ranks through the same - `Priority`. -- Keep each stream ranked until it settles, not just until its FIN is - written (the #5385 review fix for JS group streams). -- Tests, on mock time, in Rust: a fill and a FETCH stream ranked against open - group streams of the same and a different priority, asserting - the recorded send orders the way `group_stream_preserves_model_priority` - does. - -This is unblocked and lands before [moq-transport ranges](/quest/m1/subscribe-ranges/ietf.md), -which makes a FETCH span several groups on one stream that keeps this one -entry. - -Out of scope: lite FETCH. lite-07 removes it, and published lite versions -answer FETCH through the range model that [Model ranges](/quest/m1/subscribe-ranges/model.md) -builds. - -## Related - -- [Scope and sign track priority](/quest/m1/track-priority-scope.md) - changes what the queue compares across subscriptions -- [FETCH max-delay](/quest/m1/fetch-max-delay.md) - the same FETCH serving path diff --git a/quest/m1/subscribe-ranges/ietf-update.md b/quest/m1/subscribe-ranges/ietf-update.md index 53b8f39db94..09f6128134a 100644 --- a/quest/m1/subscribe-ranges/ietf-update.md +++ b/quest/m1/subscribe-ranges/ietf-update.md @@ -64,4 +64,3 @@ at a higher priority raises the upstream priority, and leaving lowers it again. ## Related - [Scope and sign track priority](/quest/m1/track-priority-scope.md) - may stop forwarding downstream priority upstream on relay-to-relay links, which changes what this sends -- [moq-transport FETCH and fill streams in the session queue](/quest/m1/subscribe-ranges/ietf-fetch-queue.md) - the same publisher queue the updated priority lands in diff --git a/quest/m1/subscribe-ranges/ietf.md b/quest/m1/subscribe-ranges/ietf.md index 200f78828e3..02337884a76 100644 --- a/quest/m1/subscribe-ranges/ietf.md +++ b/quest/m1/subscribe-ranges/ietf.md @@ -24,6 +24,8 @@ groups not supported") in `run_fetch_stream` `FetchType::Filtered`. Capping at the Largest Object also lifts the draft-20 refusal of a filter bounded by it ("FETCH relative to Largest Object not supported"): no filter, a relative start, or an absolute start with no end. +A multi-group FETCH keeps its one queue entry and moves with priority updates +(decided 2026-10-13). The same FETCH-end path sets End of Track only when the read hits FIN, so a bounded FETCH that ends exactly at the track's last object reports diff --git a/rs/moq-net/src/ietf/publisher.rs b/rs/moq-net/src/ietf/publisher.rs index 76b2da615c6..7ec7c4788a6 100644 --- a/rs/moq-net/src/ietf/publisher.rs +++ b/rs/moq-net/src/ietf/publisher.rs @@ -402,6 +402,8 @@ enum Joined { cache: track::Consumer, /// The subscription's namespace, which the fetch is held to the grant on. namespace: crate::PathOwned, + /// The subscription's ranking, which the fetch joins. + ranking: Ranking, }, } @@ -775,7 +777,6 @@ where let order = msg.group_order.to_order(); let mut subscription = serving_subscription(msg.subscriber_priority).with_order(order); - let priority = subscription.priority; // Subscribe before resolving the filter: on a routed broadcast the live edge only // becomes readable once the subscription's demand attaches a route, so the edge @@ -818,6 +819,12 @@ where .timescale .filter(|_| ietf::Properties::sends_timescale(self.version)); + // Serve the track while reading updates; only abrupt closure cancels on draft-19+. + // A fill or joining FETCH ranks in the same subscription as the group it carries. + let mut track_serve = + TrackServe::new(self.session.clone(), track, request_id, self.version, range, timescale) + .ranked(self.priority.clone()); + // Draft-20 replaced joining FETCH with subscription fills. Older drafts save // the same boundary used by the subscription so the two streams never overlap. if let Some(join) = &_join { @@ -829,6 +836,7 @@ where }, cache: cache.clone(), namespace: msg.track_namespace.to_owned(), + ranking: track_serve.ranking.clone(), }, (Filter::NextObject, None) => Joined::Empty, _ => Joined::Unsupported, @@ -856,7 +864,7 @@ where // The subscription floor and FETCH/FILL cap use this same snapshot. largest: edge.largest, properties: { - let mut properties = track_properties(track.info(), msg.properties_wanted); + let mut properties = track_properties(track_serve.track.info(), msg.properties_wanted); // Through draft-15 this restates the order the subscription is served in. // Later drafts carry the publisher's default instead. if matches!(self.version, Version::Draft14 | Version::Draft15) { @@ -869,17 +877,13 @@ where let mut request_finished = false; - // Serve the track while reading updates; only abrupt closure cancels on draft-19+. // The fill (when one was requested) runs alongside on its own fetch stream; // its failures reset that stream and never touch the subscription. - let mut track_serve = - TrackServe::new(self.session.clone(), track, request_id, self.version, range, timescale) - .ranked(self.priority.clone()); let opened = track_serve.opened.clone(); + let ranking = track_serve.ranking.clone(); let fill = async { if let Some((fill, cache, timescale)) = fill { - self.run_fill(request_id, priority, fill, cache, timescale, &opened) - .await; + self.run_fill(fill, &ranking, cache, timescale, &opened).await; } }; // Ends the subscription once our grant (MoQ Auth) stops covering it. @@ -910,7 +914,7 @@ where && res.is_ok() && let Some(end) = track_serve.end() { - let mut marker = std::pin::pin!(track_serve.write_end_of_track(end, priority)); + let mut marker = std::pin::pin!(track_serve.write_end_of_track(end)); let mut closed_session = self.session.clone(); let written = kio::wait(|waiter| { if let Poll::Ready(res) = waiter.poll_future(marker.as_mut()) { @@ -1171,19 +1175,27 @@ where /// draft's fill-failure signal. Nothing here touches the subscription either way. /// /// Counts its stream into `opened` once it opens, like a group stream, so - /// PUBLISH_DONE's Stream Count includes it however the subscription ends. + /// PUBLISH_DONE's Stream Count includes it however the subscription ends. It ranks in + /// its subscription's `ranking` as the group it fills. async fn run_fill( &self, - request_id: RequestId, - priority: u8, fill: FillServe, + ranking: &Ranking, track: track::Consumer, timescale: Option, opened: &AtomicU64, ) { - if matches!(fill, FillServe::Empty) { - return; - } + let request_id = ranking.request_id; + let priority = *ranking.priority.read(); + let rank = match fill { + FillServe::Empty => return, + FillServe::Group { sequence, skip, .. } => Some(ranking.rank(Location { + group: sequence, + object: skip, + })), + // Only the refusal goes out on its stream, so it competes with nothing. + FillServe::Unsupported => None, + }; let mut session = self.session.clone(); let stream = match session.open_uni().await { @@ -1194,8 +1206,7 @@ where } }; opened.fetch_add(1, Ordering::Relaxed); - let mut stream = Writer::new(stream, self.version); - stream.set_priority(priority); + let mut stream = Writer::new(Ranked::new(stream, rank), self.version); let res = async { stream.varint(FetchHeader::TYPE).await?; @@ -1220,9 +1231,7 @@ where match res { Ok(()) => { - // Close waits for the acknowledgement, and consuming the writer disarms - // the Drop fallback that would reset a finished stream. - if let Err(err) = stream.close().await { + if let Err(err) = settle(&mut stream).await { tracing::debug!(%err, fill = %request_id, "fill stream close failed"); } else { tracing::debug!(fill = %request_id, "fill complete"); @@ -1242,7 +1251,7 @@ where /// properties (the timestamp) and the payload go on the wire. A fetch object has no /// status field from draft-16 onward; older drafts require Normal for an empty object. async fn write_fetch_group( - stream: &mut Writer, + stream: &mut Writer, Version>, mut group: group::Consumer, sequence: u64, skip: u64, @@ -1378,7 +1387,7 @@ where /// Write one fetch object's header and timestamp properties in the negotiated layout. async fn write_fetch_object( - stream: &mut Writer, + stream: &mut Writer, Version>, sequence: u64, object: u64, prior: FetchPrior, @@ -1446,7 +1455,7 @@ where /// Write a whole fetch object's length and payload, after its header. async fn write_fetch_payload( - stream: &mut Writer, + stream: &mut Writer, Version>, payload: bytes::Bytes, version: Version, ) -> Result<(), Error> { @@ -1547,7 +1556,7 @@ where // Every FETCH is held to the grant while its group loads and its response is written. // A standalone one is also checked here, before it reaches the origin; a joining one // was checked when its subscription was. - let (track, start, end, joined, mut gate) = match fetch_type { + let (track, start, end, joined, ranking, mut gate) = match fetch_type { FetchType::Standalone { namespace, track, @@ -1584,7 +1593,15 @@ where Err(err) => return self.reject_fetch(stream, msg.request_id, &err, &err.to_string()).await, }; - (track, start, end, false, gate) + // Its own entry in the queue, so it competes with group streams by its priority + // alone, its request id breaking ties. Nothing updates a FETCH's priority. + let ranking = Ranking { + queue: self.priority.clone(), + request_id: msg.request_id, + priority: kio::Producer::new(priority).consume(), + order: Order::Descending, + }; + (track, start, end, false, ranking, gate) } FetchType::RelativeJoining { subscriber_request_id, .. @@ -1592,7 +1609,7 @@ where | FetchType::AbsoluteJoining { subscriber_request_id, .. } => { - let (end, cache, namespace) = match self.joined(&mut stream, subscriber_request_id).await? { + let (end, cache, namespace, ranking) = match self.joined(&mut stream, subscriber_request_id).await? { Ok(joined) => joined, Err((err, reason)) => return self.reject_fetch(stream, msg.request_id, &err, reason).await, }; @@ -1621,6 +1638,7 @@ where }, end, true, + ranking, gate, ) } @@ -1782,8 +1800,7 @@ where .await?; let uni = self.session.open_uni().await.map_err(Error::from_transport)?; - let mut writer = Writer::new(uni, self.version); - writer.set_priority(priority); + let mut writer = Writer::new(Ranked::new(uni, Some(ranking.rank(start))), self.version); writer.varint(FetchHeader::TYPE).await?; writer .encode(&FetchHeader { @@ -1804,7 +1821,7 @@ where .await?; Self::write_fetch_payload(&mut writer, frame.payload, self.version).await?; } - writer.close().await?; + settle(&mut writer).await?; Ok::<(), Error>(()) }; let res = { @@ -1838,7 +1855,7 @@ where &mut self, stream: &mut Stream, subscribe_id: RequestId, - ) -> Result, Error> { + ) -> Result, Error> { // Request streams can arrive out of order. Wait on registration, while bounding // the lifetime of a request whose subscription never arrives or resolves. let joined = { @@ -1875,7 +1892,12 @@ where let refusal = match joined { Err(Error::Timeout) => (Error::Timeout, "subscription not ready"), Err(err) => return Err(err), - Ok(Some(Joined::Group { end, cache, namespace })) => return Ok(Ok((end, cache, namespace))), + Ok(Some(Joined::Group { + end, + cache, + namespace, + ranking, + })) => return Ok(Ok((end, cache, namespace, ranking))), Ok(None) => ( match self.version { Version::Draft14 @@ -2911,7 +2933,7 @@ struct TrackServe { /// The subscriber priority, which every group stream follows while it is open. priority: kio::Producer, /// Where the group streams are ranked: the session's queue once [`Self::ranked`]. - queue: PriorityQueue, + ranking: Ranking, /// The track finished: the in-flight group machines drain, then FIN. draining: bool, /// Group streams opened, shared with the group machines. @@ -2950,6 +2972,12 @@ impl TrackServe { // objects on those drafts go out unstamped. let timescale = timescale.filter(|_| ietf::Properties::sends_timescale(version)); let priority = kio::Producer::new(track.subscription().priority); + let ranking = Ranking { + queue: PriorityQueue::default(), + request_id, + priority: priority.consume(), + order: track.subscription().order, + }; Self { datagrams, @@ -2961,7 +2989,7 @@ impl TrackServe { timescale, children: kio::Tasks::new(), priority, - queue: PriorityQueue::default(), + ranking, draining: false, opened: Default::default(), end: None, @@ -2973,25 +3001,10 @@ impl TrackServe { /// Rank this subscription's group streams in `queue`, shared with the session's other /// subscriptions. Without it they are only ranked against each other. fn ranked(mut self, queue: PriorityQueue) -> Self { - self.queue = queue; + self.ranking.queue = queue; self } - /// This group's place in the queue, in the subscription's order. - fn rank(&self, sequence: u64) -> Rank { - let priority = self.priority.consume(); - let current = *priority.read(); - let order = self.track.subscription().order; - Rank { - handle: self - .queue - .insert(Priority::new(current, self.request_id.0, sequence).with_order(order)), - priority, - applied: current, - order, - } - } - /// Move the subscriber priority, for the group streams already open as well as later ones. fn set_priority(&mut self, priority: u8) -> Result<(), Error> { let mut subscription = self.track.subscription(); @@ -3029,13 +3042,20 @@ impl TrackServe { reached.then_some(end) } - /// Send the original terminal on a separate stream when its group already sent FIN. - async fn write_end_of_track(&mut self, end: track::Position, priority: u8) -> Result<(), Error> { - let mut stream = std::future::poll_fn(|cx| self.session.poll_open_uni(cx)) + /// Send the original terminal on a separate stream when its group already sent FIN, + /// ranked as the group it ends. + async fn write_end_of_track(&mut self, end: track::Position) -> Result<(), Error> { + let stream = std::future::poll_fn(|cx| self.session.poll_open_uni(cx)) .await .map_err(Error::from_transport)?; self.opened.fetch_add(1, Ordering::Relaxed); - stream.set_priority(priority.into()); + let stream = Ranked::new( + stream, + Some(self.ranking.rank(Location { + group: end.group, + object: end.frame, + })), + ); let mut writer = Writer::new(stream, self.version); writer.buffer(&ietf::GroupHeader { track_alias: self.request_id.0, @@ -3051,7 +3071,7 @@ impl TrackServe { writer.buffer_varint(end.frame)?; writer.buffer_varint(0)?; writer.varint(END_OF_TRACK).await?; - writer.close().await + settle(&mut writer).await } fn poll(&mut self, waiter: &kio::Waiter) -> Poll> { @@ -3111,7 +3131,10 @@ impl TrackServe { }, }; - let rank = self.rank(sequence); + let rank = self.ranking.rank(Location { + group: sequence, + object: slice.skip, + }); self.children.push( GroupServe::new( self.session.clone(), @@ -3199,6 +3222,113 @@ impl TrackServe { } } +/// Where one request's streams are ranked: the session's queue, keyed by the request's id +/// and following its subscriber priority. +#[derive(Clone)] +struct Ranking { + queue: PriorityQueue, + request_id: RequestId, + priority: kio::Consumer, + /// The request's GROUP_ORDER, fixed for its life: no update carries it. + order: Order, +} + +impl Ranking { + /// A stream carrying a group from `start` on, ranked among the request's others. + fn rank(&self, start: Location) -> Rank { + let applied = *self.priority.read(); + Rank { + handle: self.queue.insert( + Priority::new(applied, self.request_id.0, start.group) + .with_order(self.order) + .with_start(start.object), + ), + priority: self.priority.clone(), + applied, + order: self.order, + } + } +} + +/// A send stream that follows its [`Rank`] until it settles, for one written by async code +/// rather than a [`GroupServe`] machine, which follows its own. +/// +/// Every write and close poll applies a move first. A stream parked on its group still +/// polls its close to notice the subscriber leaving, so a move reaches the transport +/// whatever the stream waits on. +struct Ranked { + stream: T, + /// Absent for a stream that only carries a refusal. + rank: Option, + park: kio::Park, +} + +impl Ranked { + fn new(mut stream: T, mut rank: Option) -> Self { + if let Some(rank) = &mut rank { + stream.set_priority(rank.handle.send_order().into()); + } + Self { + stream, + rank, + park: kio::Park::default(), + } + } + + fn follow(&mut self, cx: &std::task::Context<'_>) { + if let Some(rank) = &mut self.rank + && let Some(order) = rank.poll_moved(self.park.hold(cx)) + { + self.stream.set_priority(order.into()); + } + } +} + +impl crate::transport::poll::SendStream for Ranked { + type Error = T::Error; + + fn poll_write(&mut self, cx: &mut std::task::Context<'_>, buf: &[u8]) -> Poll> { + self.follow(cx); + self.stream.poll_write(cx, buf) + } + + fn poll_write_buf( + &mut self, + cx: &mut std::task::Context<'_>, + buf: &mut B, + ) -> Poll> { + self.follow(cx); + self.stream.poll_write_buf(cx, buf) + } + + fn set_priority(&mut self, order: i32) { + self.stream.set_priority(order); + } + + fn finish(&mut self) -> Result<(), Self::Error> { + self.stream.finish() + } + + fn reset(&mut self, code: u32) { + self.stream.reset(code); + } + + fn poll_closed(&mut self, cx: &mut std::task::Context<'_>) -> Poll> { + self.follow(cx); + self.stream.poll_closed(cx) + } +} + +/// Finish a ranked stream and wait for the peer to acknowledge it, holding its rank until then. +/// +/// Unlike [`Writer::close`], the writer keeps the stream while it waits, so cancelling resets +/// the stream as a cancelled group stream's is, rather than leaving it sending once its rank +/// is released. Once acknowledged, the stream is released and dropping the writer resets nothing. +async fn settle(writer: &mut Writer, Version>) -> Result<(), Error> { + writer.finish()?; + std::future::poll_fn(|cx| writer.poll_close(cx)).await +} + /// A group stream's place in the session's send order: its subscription's priority, then /// its sequence in the subscription's GROUP_ORDER. struct Rank { @@ -3652,7 +3782,7 @@ mod group_priority_test { ServeRange::default(), None, ); - serve.write_end_of_track(track::Position::group(0), 0).await.unwrap(); + serve.write_end_of_track(track::Position::group(0)).await.unwrap(); let bytes = log.writes.lock().unwrap().clone(); let mut decoder = crate::coding::Decoder::new(&bytes, Version::Draft22.into()); let header = ietf::GroupHeader::decode(&mut decoder, Version::Draft22).unwrap(); @@ -3662,6 +3792,67 @@ mod group_priority_test { ); } + /// The standalone END_OF_TRACK stream ranks as the group it ends, not at the raw + /// subscriber priority. + #[moq_net_sim::test] + async fn standalone_end_of_track_ranks_as_its_group() { + let log = crate::lite::test_transport::Log::default(); + let queue = PriorityQueue::default(); + let track = track::Producer::new( + std::sync::Arc::new(crate::broadcast::Info::default()), + "test", + crate::track::Info::timed(), + ); + let mut serve = TrackServe::new( + SinkSession::new(log.clone()), + track.subscribe(None), + RequestId(1), + Version::Draft22, + ServeRange::default(), + None, + ) + .ranked(queue.clone()); + let _higher = queue.insert(Priority::new(u8::MAX, 0, 0)); + serve.write_end_of_track(track::Position::group(0)).await.unwrap(); + assert_eq!(log.priorities(), [254], "second, behind the higher priority"); + } + + /// Cancelled while its FIN waits for the acknowledgement, a ranked stream resets as it + /// gives up its rank, rather than sending on with a send order the queue has reused. + #[moq_net_sim::test] + async fn a_ranked_stream_cancelled_after_its_fin_resets() { + let log = crate::lite::test_transport::Log::default(); + let queue = PriorityQueue::default(); + let track = track::Producer::new( + std::sync::Arc::new(crate::broadcast::Info::default()), + "test", + crate::track::Info::timed(), + ); + let mut serve = TrackServe::new( + SinkSession::new(log.clone()).with_unacked_fin(), + track.subscribe(None), + RequestId(0), + Version::Draft22, + ServeRange::default(), + None, + ) + .ranked(queue.clone()); + let mut rival = queue.insert(Priority::new(0, 1, 0)); + assert_eq!(rival.current(), 0); + + { + let mut marker = std::pin::pin!(serve.write_end_of_track(track::Position::group(0))); + assert!( + futures::poll!(marker.as_mut()).is_pending(), + "the FIN is unacknowledged" + ); + assert_eq!(rival.current(), 1, "the marker holds its rank until acknowledged"); + } + + assert_eq!(log.resets().len(), 1, "cancelling reset the unacknowledged stream"); + assert_eq!(rival.current(), 0, "and released its rank"); + } + #[moq_net_sim::test] async fn exact_end_of_track_survives_the_final_group_fin() { use crate::lite::test_transport::Sent; @@ -3707,7 +3898,7 @@ mod group_priority_test { } kio::wait(|waiter| serve.poll(waiter)).await.unwrap(); if let Some(end) = serve.end() { - serve.write_end_of_track(end, 0).await.unwrap(); + serve.write_end_of_track(end).await.unwrap(); } assert_eq!(serve.opened(), if finished { 2 } else { 1 }); let marker_stream = usize::from(finished); @@ -6020,6 +6211,170 @@ mod serve_tests { assert_eq!(h.log.resets().len(), 1, "and is reset as the failure signal"); } + /// Subscriber priority 128 on the wire, which every request in these tests carries. + const PRIORITY: u8 = 127; + + /// The streams a FETCH or fill competes with: one at a higher priority and one at a lower + /// one, plus two at its own priority on either side of `request_id`. + fn rival_streams(queue: &PriorityQueue, request_id: RequestId) -> [PriorityHandle; 4] { + [ + queue.insert(Priority::new(200, 1, 0)), + queue.insert(Priority::new(PRIORITY, request_id.0 - 1, 0)), + queue.insert(Priority::new(PRIORITY, request_id.0 + 1, 0)), + queue.insert(Priority::new(50, 2, 0)), + ] + } + + /// A fill ranks as the group it fills, in its subscription's GROUP_ORDER, and follows + /// that rank while it is open: the queue moving it, and its subscriber priority. + #[moq_net_sim::test] + async fn a_fill_ranks_as_the_group_it_fills() { + let h = serve(Version::Draft20); + let mut group = h.track.create_group(group::Info { sequence: 4 }).unwrap(); + group.write_frame(timestamp(), b"fill".as_slice()).unwrap(); + + let queue = h.publisher.priority.clone(); + let priority = kio::Producer::new(PRIORITY); + let ranking = Ranking { + queue: queue.clone(), + request_id: RequestId(REQUEST_ID), + priority: priority.consume(), + order: Order::Descending, + }; + let [higher, _older, _later, _lower] = rival_streams(&queue, ranking.request_id); + // Newest first: the subscription's group 5 goes ahead of the fill, and group 3 after. + let _groups = [5, 3].map(|group| ranking.rank(Location { group, object: 0 })); + + let opened = AtomicU64::new(0); + let fill = FillServe::Group { + sequence: 4, + skip: 0, + until: None, + }; + let mut fill = std::pin::pin!(h.publisher.run_fill(fill, &ranking, h.track.consume(), None, &opened)); + assert!(futures::poll!(fill.as_mut()).is_pending(), "the group is still open"); + assert_eq!( + h.log.priorities(), + [252], + "behind the higher priority, the older subscription, and group 5" + ); + + drop(higher); + assert!(futures::poll!(fill.as_mut()).is_pending()); + assert_eq!(h.log.priorities(), [252, 253], "the queue moved it up"); + + let Ok(mut current) = priority.write() else { + unreachable!("this test holds the producer") + }; + *current = 255; + drop(current); + assert!(futures::poll!(fill.as_mut()).is_pending()); + assert_eq!( + h.log.priorities(), + [252, 253, 255], + "a REQUEST_UPDATE moved it to the top" + ); + + group.finish().unwrap(); + fill.await; + assert_eq!(occurrences(&h.log, b"fill"), 1); + assert!(h.log.resets().is_empty(), "a served fill must not reset"); + } + + /// A fill of the current group outranks the live stream carrying the rest of that group, + /// which the subscriber cannot use without the fill's objects first. + #[moq_net_sim::test] + async fn a_fill_outranks_the_rest_of_its_group() { + let h = serve(Version::Draft20); + let mut group = h.track.create_group(group::Info { sequence: 4 }).unwrap(); + group.write_frame(timestamp(), b"head".as_slice()).unwrap(); + + let ranking = Ranking { + queue: h.publisher.priority.clone(), + request_id: RequestId(REQUEST_ID), + priority: kio::Producer::new(PRIORITY).consume(), + order: Order::Descending, + }; + // The live stream, from object 1 on, queued first so the slab id alone would favor it. + let mut live = ranking.rank(Location { group: 4, object: 1 }); + assert_eq!(live.handle.send_order(), 255); + + let opened = AtomicU64::new(0); + let fill = FillServe::Group { + sequence: 4, + skip: 0, + until: Some(1), + }; + h.publisher + .run_fill(fill, &ranking, h.track.consume(), None, &opened) + .await; + assert_eq!(h.log.priorities(), [255], "the start of the group goes first"); + assert_eq!(occurrences(&h.log, b"head"), 1); + } + + /// A standalone FETCH competes with group streams by its subscriber priority alone, its + /// request id breaking ties, whatever group and GROUP_ORDER it asks for. + #[moq_net_sim::test] + async fn a_standalone_fetch_ranks_by_its_priority() { + for version in [Version::Draft16, Version::Draft20] { + for (group, group_order) in [(1, GroupOrder::Ascending), (3, GroupOrder::Descending)] { + let mut h = serve(version); + publish_groups(&mut h, 3); + settle().await; + let _rivals = rival_streams(&h.publisher.priority, FETCH_ID); + + let whole = Location { group, object: 0 }; + let wire = standalone_fetch(&h, whole, whole, group_order).await; + assert_eq!(fetch_answer(wire, version).1.len(), 1, "{version}: one object"); + // The fetch stream opens last, after the request stream. + assert_eq!( + h.log.priorities().last(), + Some(&253), + "{version} {group_order:?}: between its rivals at the same priority" + ); + } + } + } + + /// A joining FETCH ranks as the group it fetches in the subscription it joins, not as a + /// request of its own. + #[moq_net_sim::test] + async fn a_joining_fetch_ranks_in_its_subscription() { + const LATEST: u64 = 5; + + for version in JOINING_DRAFTS { + let mut h = serve(version); + publish_groups(&mut h, LATEST); + settle().await; + + let stream = Stream::open(&mut h.session.clone(), version).await.unwrap(); + let mut serve = std::pin::pin!( + h.publisher + .clone() + .run_subscribe_stream(stream, subscribe(Filter::NextObject, None)) + ); + registered(&h, serve.as_mut()).await; + + // Keyed by the FETCH's own id, it would land after both of the subscription's. + let queue = h.publisher.priority.clone(); + let subscription = RequestId(REQUEST_ID); + let _streams = [ + queue.insert(Priority::new(PRIORITY, subscription.0, LATEST + 1)), + queue.insert(Priority::new(PRIORITY, subscription.0, LATEST - 1)), + ]; + let _rivals = rival_streams(&queue, subscription); + + let mark = h.log.writes.lock().unwrap().len(); + joining_fetch(&h, mark).await.unwrap(); + // The fetch stream opens last, after the request stream. + assert_eq!( + h.log.priorities().last(), + Some(&252), + "{version}: behind the higher priority, the older subscription, and the newer group" + ); + } + } + /// The request id of the joining FETCH, distinct from the subscription's. const FETCH_ID: RequestId = RequestId(0x2C); diff --git a/rs/moq-net/src/priority.rs b/rs/moq-net/src/priority.rs index 8ddac9269c3..7c8707dad6e 100644 --- a/rs/moq-net/src/priority.rs +++ b/rs/moq-net/src/priority.rs @@ -21,7 +21,8 @@ use crate::track::Order; // group sequence in that subscription's own direction. /// A group stream's rank: its subscription's track priority, the subscription it -/// belongs to, and its group sequence in that subscription's [`Order`]. +/// belongs to, its group sequence in that subscription's [`Order`], and the first object +/// it carries. /// /// Higher `track` always wins. `group` breaks ties only *within* one `subscribe`: /// newest first by default, so a congested track sheds its backlog rather than its live @@ -30,12 +31,16 @@ use crate::track::Order; /// Scoping the tie-break to a subscription is what keeps group sequence from deciding /// between tracks. The draft gives that job to `Priority` alone, so a session carrying /// two tracks at equal priority interleaves them rather than draining one first. +/// +/// `start` only splits two streams of one group: the one starting earlier goes first, +/// since the rest of a group is undecodable without its start. #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub struct Priority { track: u8, subscribe: u64, order: Order, group: u64, + start: u64, } impl Priority { @@ -46,6 +51,7 @@ impl Priority { subscribe, order: Order::Descending, group, + start: 0, } } @@ -54,6 +60,12 @@ impl Priority { self.order = order; self } + + /// Rank a stream that starts at object `start` of its group, behind any earlier start. + pub fn with_start(mut self, start: u64) -> Self { + self.start = start; + self + } } impl Ord for Priority { @@ -75,6 +87,9 @@ impl Ord for Priority { Order::Descending => other.group.cmp(&self.group), Order::Ascending => self.group.cmp(&other.group), }) + // Two streams of one group, such as a joining prefix beside the live rest: the + // earlier objects first, whatever the order. + .then(self.start.cmp(&other.start)) } } @@ -674,6 +689,30 @@ mod tests { assert_eq!(group1.current(), 2); } + /// Two streams of one group rank by the object each starts at, earliest first in either + /// order, and only after the group itself. + #[test] + fn test_earlier_start_ranks_first_within_a_group() { + for order in [Order::Descending, Order::Ascending] { + let queue = PriorityQueue::default(); + let stream = |group, start| Priority::new(100, 0, group).with_order(order).with_start(start); + // Queued first, so the slab id alone would rank it ahead. + let mut rest = queue.insert(stream(5, 3)); + let mut head = queue.insert(stream(5, 0)); + let mut other = queue.insert(stream(4, 0)); + + let expected = match order { + Order::Descending => (0, 1, 2), + Order::Ascending => (1, 2, 0), + }; + assert_eq!( + (head.current(), rest.current(), other.current()), + expected, + "{order:?}: the start of a group goes first, after the group order" + ); + } + } + #[test] fn test_track_priority_overrides_group() { let queue = PriorityQueue::default();