diff --git a/doc/lib/rs/moq-net.md b/doc/lib/rs/moq-net.md index 1763f6251d2..a815bb91777 100644 --- a/doc/lib/rs/moq-net.md +++ b/doc/lib/rs/moq-net.md @@ -18,7 +18,7 @@ What you use it for, beyond what the concept page already describes: - **An origin outlives the session.** Broadcasts are created on the origin, and a reconnect announces them again. Closing the session does not delete them. - **Requests can pin an epoch.** `consumer.request_broadcast(path, Some(epoch))` resolves only through a route announcing that [publisher epoch](/concept/moq-lite#publisher-epochs); `None` takes whichever route wins. The resolved consumer names its epoch in `info().epoch`, pinned or not. - **Rank several CDNs.** Dial each with its own subscribe handle, `origin.clone().with_preference(origin::Preference::new(rank))` (higher wins; 0 is neutral and a negative rank demotes), all on one origin. Requests use the preferred link that has a route and fail over to the next; see [multiple CDNs](/concept/moq-lite#multiple-cdns). -- **Follow restarts.** `consumer.follow(path)` reduces the routes covering a path to the one a request resolves (the most specific) and yields its start, update, restart, and end. A restart says another publisher instance now serves the path: request it again. A broadcast already resolved stays on the old instance until dropped or its route goes. +- **Follow restarts.** `consumer.announced_broadcast(path, None)` hands out each publisher instance serving a path from `available()`: the first once announced, then each one that takes over or returns after an end, like JS `request(path, { announced: true })`. A broadcast already resolved stays on the old instance until dropped or its route goes. `consumer.follow(path)` yields the underlying start, update, restart, and end of the route a request resolves. - **One track per name.** Concurrent subscriptions share one request and producer. The application owns sequence numbers: a producer that replaces an ended one gets `Error::Duplicate` from an append that would reuse a sequence the name already wrote, so it starts with `create_group` at an explicit sequence. Only a new broadcast starts over. Readers of an aborted track resume onto the replacement only when the broadcast announces an epoch; otherwise their subscription ends with the error. - **End a broadcast with `finish()`.** When the input ends, finish the tracks, then call `broadcast.finish()`. The returned handle keeps the broadcast announced and serving its finished tracks for `linger()`, their longest max-age, so a subscriber still catching up can drain them. Await `wait()` on a runtime, or drop the handle once your own clock passes `linger()`. Dropping it early is the interrupt, and `close()` on another handle ends it at once. - **Publish only while someone is watching.** `demand()` on a track, group, or broadcast says whether a subscriber is attached, which is how capture and transcode skip work nobody asked for. Holding a broadcast or track consumer is not demand: a track consumer requests nothing until it queries, subscribes, or fetches, and those count until dropped. A shared fetch stays up until its last reader leaves. diff --git a/quest/m1/README.md b/quest/m1/README.md index 0520ca02390..ac21a350688 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -51,7 +51,6 @@ lands before the cut. - [Release builds](/quest/m0/release-link.md) - package artifacts can be built - [qmux credit](/quest/m0/qmux-credit.md) - dropped/stopped streams return credit and close is delivered -- [moq-net follows announced instances](/quest/m1/net-announced-follow.md) - the Rust equivalent of JS `request(path, { announced: true })`, replacing the follow loops in moq-ffi and moq-c - [Sink restart follow](/quest/m1/sink-restart-follow.md) - moq-cli's server and push sinks follow an epochless `Restart` where their output can mark it, and fail loud otherwise - [Cluster routing](/quest/m1/cluster-routing/README.md) - prove shared routing contracts, implement per-origin routes, and connect outbound local clusters - [Routing guide](/quest/m1/routing-guide.md) - concepts and practical outbound federation setup diff --git a/quest/m1/lazy-discovery/rust.md b/quest/m1/lazy-discovery/rust.md index 24de0ace746..67b87a9dfa1 100644 --- a/quest/m1/lazy-discovery/rust.md +++ b/quest/m1/lazy-discovery/rust.md @@ -23,11 +23,10 @@ Facts (2026-10-10, `origin/main` e5446b036): (`rs/moq-net/src/lite/subscriber.rs:601`); the IETF subscriber has the equivalent. - `OriginConsumer::follow` exists (`rs/moq-net/src/model/origin.rs:4473`); - Rust has no announced-gated request like JS's, so the fold's shape is open. -- Added 2026-10-17: [moq-net follows announced instances](/quest/m1/net-announced-follow.md) - lands first and gives Rust its announced request. This quest then makes - that request register discovery interest for its path, since the session - stops asking for its whole scope. + `origin::Consumer::announced_broadcast` is Rust's announced request. +- `origin::Consumer::announced_broadcast` registers no discovery interest + yet. This quest makes it register interest for its path, as JS does, since + the session stops asking for its whole scope. - moq-relay reads `origin.consume().announced()` for the root in its web, internal, and cluster paths, so a relay's watch set is the root. @@ -54,7 +53,3 @@ fallout (see the Cross-Package Sync table in `AGENTS.md`). Tests must pin the relay side: an origin in relay mode (cluster and upstream sessions on the client subscriber path) still sends a root request, so lazy discovery never narrows what a relay discovers. - -## Required - -- [moq-net follows announced instances](/quest/m1/net-announced-follow.md) - the Rust announced request this quest registers discovery interest for diff --git a/quest/m1/net-announced-follow.md b/quest/m1/net-announced-follow.md deleted file mode 100644 index 85187c17ea0..00000000000 --- a/quest/m1/net-announced-follow.md +++ /dev/null @@ -1,53 +0,0 @@ -# [M] moq-net follows announced instances - -## Goal - -moq-net offers the Rust equivalent of JS `request(path, { announced: true })` -(`js/net/src/origin.ts`): one request that follows each publisher instance -serving a path, unless an epoch is pinned. moq-ffi's -`MoqAnnouncedBroadcast::available()` (`rs/moq-ffi/src/origin.rs`) and moq-c's -`moq_origin_announced_broadcast` (`rs/moq-c/src/origin.rs`) use it and drop -their hand-rolled follow loops. - -## Plan - -Decided with the maintainer on 2026-10-17: the goal as drafted, from -decision 5 of [#5700](https://github.com/moq-dev/moq/pull/5700), which kept -the loops per binding until moq-net owns them. Mirror the JS name. - -The sink follow helper waits on this quest so it does not add a third loop; -the OBS source keeps calling `available()`, whose API does not change. - -The loops #5700 added drain `origin::Consumer::follow`, resolve the path with -`routed_broadcast`, and settle three cases moq-net should own once: - -- An `End` forgets the last instance, so the same instance returning after - a gap is handed out again. -- The last instance is held weakly, so a handle the caller let go of never - keeps its instance from retiring. -- A change that arrives while a resolution is in flight, such as an end and - a start for the instance it resolved, resolves afresh; and a resolution - that runs ahead of its held `Restart` is not handed out twice. - -Two JS behaviors have no Rust counterpart to mirror. JS falls back to blind -resolution while a `consume` session lacks discovery; moq-net has no blind -requests. Decided with the maintainer on 2026-10-17: no blind fallback. The -mode waits on an announced route as `routed_broadcast` does, and blind -requests stay out of scope, so it differs from JS when discovery is -unavailable. JS also watches the path so a `consume` session asks its peer about -it. A moq-net session asks for its whole granted scope at setup today -(`interest_prefixes` in `rs/moq-net/src/lite/subscriber.rs`), so this quest -registers no interest. [Rust lazy discovery](/quest/m1/lazy-discovery/rust.md) -narrows that to watched prefixes, lands after this quest, and owns making -this mode watch its path, as JS does. - -JS returns a handle whose current broadcast changes per instance -(`Request.active`); Rust's `request_broadcast` takes only an optional epoch -today. Propose the Rust shape in the PR. Keep #5700's binding tests passing -unchanged as the regression, and add moq-net tests for the three cases plus -a pinned epoch: an announced request that pins epoch A refuses a replacement -announced with epoch B instead of following it, mirroring JS `an -epoch-pinned announced request refuses another instance` -(`js/net/src/origin-request.test.ts`). -Public API: a new moq-net request mode or handle, and simpler binding -internals with no binding API change. Wire: none. diff --git a/quest/m1/sink-restart-follow.md b/quest/m1/sink-restart-follow.md index dde69b0bdee..72d96696e05 100644 --- a/quest/m1/sink-restart-follow.md +++ b/quest/m1/sink-restart-follow.md @@ -30,11 +30,8 @@ and fix the rest the same way: Share one helper (a `moq_mux` `Source::follow`-style API per [catalog references](/quest/m0/broadcast-epoch/catalog-references.md)) -rather than one rule per sink. Each fix lands with a test that replaces the +rather than one rule per sink, built on +`origin::Consumer::announced_broadcast` rather than another hand-rolled loop. Each fix lands with a test that replaces the publisher while the sink runs. Public API: possibly a shared follow helper in `moq-mux`. Wire: none. - -## Required - -- [moq-net follows announced instances](/quest/m1/net-announced-follow.md) - the shared follow helper builds on moq-net's announced request, not a third hand-rolled loop diff --git a/rs/moq-c/src/consume.rs b/rs/moq-c/src/consume.rs index 4b248c878c7..320c3dfee8a 100644 --- a/rs/moq-c/src/consume.rs +++ b/rs/moq-c/src/consume.rs @@ -216,13 +216,6 @@ impl Consume { self.broadcast.insert(ConsumeBroadcast { broadcast, origin }) } - /// Whether the caller still holds `id` as a handle to `broadcast`. - pub fn holds(&self, id: Id, broadcast: &moq_net::broadcast::Consumer) -> bool { - self.broadcast - .get(id) - .is_some_and(|held| held.broadcast.is_clone(broadcast)) - } - pub fn catalog(&mut self, broadcast: Id, on_catalog: OnStatus) -> Result { let ConsumeBroadcast { broadcast, origin } = self.broadcast.get(broadcast).ok_or(Error::BroadcastNotFound)?.clone(); diff --git a/rs/moq-c/src/origin.rs b/rs/moq-c/src/origin.rs index 389bf6126ef..ffadd5d6439 100644 --- a/rs/moq-c/src/origin.rs +++ b/rs/moq-c/src/origin.rs @@ -238,76 +238,30 @@ impl Origin { mut close: oneshot::Receiver<()>, ) -> Result<(), Error> { // An unreachable path and a closed origin both mean no broadcast can ever arrive here. - let mut follow = match consumer.follow(path.as_str()) { - Ok(follow) => follow, + let mut announced = match consumer.announced_broadcast(path.as_str(), None) { + Ok(announced) => announced, Err(moq_net::Error::Unauthorized) => return Err(Error::BroadcastNotFound), Err(err) => return Err(err.into()), }; - let mut unseen = false; let mut delivered = false; - // The handle delivered last, until the caller frees it or the path goes offline. An id - // rather than the broadcast, so it never keeps an instance the caller freed from retiring. - let mut last: Option = None; - // The origin closing ends the wait, cleanly once a handle was delivered. - let closed = |delivered: bool| match delivered { - true => Ok(()), - false => Err(Error::BroadcastNotFound), - }; // Deliver each publisher instance serving the path: the first, then each one that takes // over or returns. `biased` so a pending close always wins. loop { - // Apply every change on hand before resolving, so a burst of them delivers only the - // instance serving the path now. - if settle(&mut follow, &mut unseen, &mut last).is_none() { - return closed(delivered); - } - if !unseen { - let event = tokio::select! { - biased; - _ = &mut close => return Ok(()), - event = follow.next() => event, - }; - let Some(event) = event else { - return closed(delivered); - }; - apply(&mut unseen, &mut last, event); - continue; - } - - // `routed_broadcast` rides out the churn between something covering the path - // and the path actually resolving (failover, an advertise-only announce - // racing its handler). let broadcast = tokio::select! { biased; _ = &mut close => return Ok(()), - resolved = consumer.routed_broadcast(path.as_str()) => match resolved { + available = announced.available() => match available { Ok(broadcast) => broadcast, - Err(moq_net::Error::Closed) => return closed(delivered), - Err(moq_net::Error::Unauthorized) => return Err(Error::BroadcastNotFound), + // The origin closing ends the wait, cleanly once a handle was delivered. + Err(moq_net::Error::Closed) if delivered => return Ok(()), + Err(moq_net::Error::Closed) => return Err(Error::BroadcastNotFound), Err(err) => return Err(err.into()), }, }; - // A change that came through while resolving may predate the answer, such as an end - // and a start for the instance it resolved. Resolve afresh once caught up. - match settle(&mut follow, &mut unseen, &mut last) { - None => return closed(delivered), - Some(true) => continue, - Some(false) => unseen = false, - } - // Hold the lock only to buffer the broadcast; release it before the callback. - let broadcast_id = { - let mut state = State::lock(); - // Resolving can run ahead of the follower: a takeover resolves at once while its - // restart is held, and that restart then names the instance already delivered. - if last.is_some_and(|last| state.consume.holds(last, &broadcast)) { - continue; - } - state.consume.start(broadcast, Some(consumer.clone()))? - }; - last = Some(broadcast_id); + let broadcast_id = State::lock().consume.start(broadcast, Some(consumer.clone()))?; delivered = true; callback.call(broadcast_id); } @@ -487,32 +441,6 @@ impl Origin { } } -/// Apply every change on hand, returning whether any came through, or `None` once the origin -/// closed. -fn settle(follow: &mut moq_net::announce::Follow, unseen: &mut bool, last: &mut Option) -> Option { - let mut changed = false; - while let std::task::Poll::Ready(event) = follow.poll_next(&kio::Waiter::noop()) { - changed |= apply(unseen, last, event?); - } - Some(changed) -} - -/// Apply one change to the path, returning whether it is one. -fn apply(unseen: &mut bool, last: &mut Option, event: moq_net::announce::Event) -> bool { - match event { - moq_net::announce::Event::Start(_) | moq_net::announce::Event::Restart(_) => *unseen = true, - // An end is a gap that ended every request on the old route, so whatever serves the path - // next is delivered, even the same instance coming back. - moq_net::announce::Event::End(_) => { - *unseen = false; - *last = None; - } - // The same instance over another route, which its subscriptions ride out. - moq_net::announce::Event::Update(_) => return false, - } - true -} - #[cfg(test)] mod supervision_tests { use super::*; diff --git a/rs/moq-ffi/src/origin.rs b/rs/moq-ffi/src/origin.rs index d98f8f58f02..161d46be428 100644 --- a/rs/moq-ffi/src/origin.rs +++ b/rs/moq-ffi/src/origin.rs @@ -1,4 +1,4 @@ -use std::sync::{Arc, Weak}; +use std::sync::Arc; use crate::consumer::MoqBroadcastConsumer; use crate::error::MoqError; @@ -204,85 +204,19 @@ impl Announced { /// Follows one exact path, resolving each publisher instance that serves it. struct AnnouncedBroadcast { + inner: moq_net::origin::AnnouncedBroadcast, origin: moq_net::origin::Consumer, - path: moq_net::PathOwned, - follow: moq_net::announce::Follow, - /// An instance serves the path that was not handed out yet. - unseen: bool, - /// The handle handed out last, until the caller drops it or the path goes offline. Weak, so - /// it never keeps an instance the caller let go of from retiring. - last: Weak, driver: Background, } impl AnnouncedBroadcast { async fn available(&mut self) -> Result, MoqError> { - let driver = self.driver.clone(); - driver - .watch(async { - loop { - // Apply every change on hand before resolving, so a burst of them hands out - // only the instance serving the path now. - self.settle()?; - if !self.unseen { - let event = self.follow.next().await; - self.apply(event)?; - continue; - } - - // `routed_broadcast` rides out the churn between something covering the path - // and the path actually resolving (failover, an advertise-only announce - // racing its handler). The instance stays unseen until it resolves: a foreign - // cancel only drops this future, and the caller may call again. - let broadcast = self.origin.routed_broadcast(&self.path).await?; - - // A change that came through while resolving may predate the answer, such as - // an end and a start for the instance it resolved. Resolve afresh once caught up. - if self.settle()? { - continue; - } - self.unseen = false; - - // Resolving can run ahead of the follower: a takeover resolves at once while - // its restart is held, and that restart then names the instance handed out. - if self.last.upgrade().is_some_and(|last| last.inner.is_clone(&broadcast)) { - continue; - } - let broadcast = Arc::new(MoqBroadcastConsumer::routed( - broadcast, - self.origin.clone(), - self.driver.clone(), - )); - self.last = Arc::downgrade(&broadcast); - return Ok(broadcast); - } - }) - .await - } - - /// Apply every change on hand, returning whether any came through. - fn settle(&mut self) -> Result { - let mut changed = false; - while let std::task::Poll::Ready(event) = self.follow.poll_next(&kio::Waiter::noop()) { - changed |= self.apply(event)?; - } - Ok(changed) - } - - /// Apply one change to the path, returning whether it is one. - fn apply(&mut self, event: Option) -> Result { - match event.ok_or(MoqError::Closed)? { - moq_net::announce::Event::Start(_) | moq_net::announce::Event::Restart(_) => self.unseen = true, - // An end is a gap that ended every request on the old route, so whatever serves the - // path next is handed out, even the same instance coming back. - moq_net::announce::Event::End(_) => { - self.unseen = false; - self.last = Weak::new(); - } - // The same instance over another route, which its subscriptions ride out. - moq_net::announce::Event::Update(_) => return Ok(false), - } - Ok(true) + let broadcast = self.driver.watch(async { Ok(self.inner.available().await?) }).await?; + Ok(Arc::new(MoqBroadcastConsumer::routed( + broadcast, + self.origin.clone(), + self.driver.clone(), + ))) } } @@ -517,23 +451,14 @@ impl MoqOriginConsumer { pub fn announced_broadcast(&self, path: String) -> Result, MoqError> { let _guard = crate::ffi::enter(); self.driver.check()?; - let path = moq_net::Path::new(&path).to_owned(); - // Following checks the permission eagerly, so an unreachable path fails here rather // than surfacing later as a `Closed` the caller can't tell from the origin ending. - let follow = self.inner.follow(&path)?; + let inner = self.inner.announced_broadcast(path.as_str(), None)?; Ok(Arc::new(MoqAnnouncedBroadcast { task: Task::new(AnnouncedBroadcast { - // The wait runs on the *unrooted* cursor, so the broadcast is handed out named - // by its full path. Rooting the cursor at `path` would name it "" instead, - // making it its own root, and a catalog's `../sibling` reference would read as - // escaping. + inner, origin: self.inner.clone(), - path, - follow, - unseen: false, - last: Weak::new(), driver: self.driver.clone(), }), })) diff --git a/rs/moq-net/src/model/follow.rs b/rs/moq-net/src/model/follow.rs index ec9a6713ef4..4623bcf359a 100644 --- a/rs/moq-net/src/model/follow.rs +++ b/rs/moq-net/src/model/follow.rs @@ -1,7 +1,8 @@ use std::task::{Poll, ready}; -use super::origin_impl::{Announce, AnnounceConsumer, AnnounceEvent}; -use crate::PathOwned; +use super::WeakEntry; +use super::origin_impl::{Announce, AnnounceConsumer, AnnounceEvent, Consumer, Routing}; +use crate::{Epoch, Error, PathOwned, broadcast}; /// The announcements covering one path, as one broadcast coming online, being replaced, and /// going offline. Created by [`Consumer::follow`](crate::origin::Consumer::follow). @@ -177,6 +178,107 @@ impl Follow { } } +/// Each publisher instance serving one path, handed out as it takes over. Created by +/// [`Consumer::announced_broadcast`](crate::origin::Consumer::announced_broadcast). +pub struct AnnouncedBroadcast { + consumer: Consumer, + path: PathOwned, + /// The only instance handed out, if pinned. + epoch: Option, + follow: Follow, + /// An instance serves the path that was not handed out yet. + unseen: bool, + /// The resolution in flight, kept across a dropped wait so a retry picks it up. + resolving: Option, + /// The broadcast handed out last, until the path goes offline. Weak, so it never keeps an + /// instance the caller let go of from retiring. + last: Option, +} + +impl AnnouncedBroadcast { + pub(super) fn new(consumer: Consumer, path: PathOwned, epoch: Option, follow: Follow) -> Self { + Self { + consumer, + path, + epoch, + follow, + unseen: false, + resolving: None, + last: None, + } + } + + /// Wait for the next publisher instance serving the path; see + /// [`Consumer::announced_broadcast`](crate::origin::Consumer::announced_broadcast). + /// + /// Returns [`Error::Closed`] once the origin closes, and any other resolution failure + /// as-is. Dropping the future keeps the wait's progress for the next call. + #[cfg(feature = "async")] + pub async fn available(&mut self) -> Result { + kio::wait(|waiter| self.poll_available(waiter)).await + } + + /// Poll for the next publisher instance serving the path, registering `waiter` when there + /// is none yet. + pub fn poll_available(&mut self, waiter: &kio::Waiter) -> Poll> { + loop { + // Apply every change on hand before reading an answer, so a burst of them hands out + // only the instance serving the path now. A resolution in flight answers for the + // routes before the change, such as an end and a start for the instance it resolved, + // so it starts over. + if self.settle(waiter)? { + self.resolving = None; + } + if !self.unseen { + return Poll::Pending; + } + + let resolving = self + .resolving + .get_or_insert_with(|| self.consumer.routing(self.path.clone(), self.epoch.clone())); + let resolved = ready!(kio::Task::poll(resolving, waiter)); + self.resolving = None; + let broadcast = resolved?; + self.unseen = false; + + // Resolving can run ahead of the follower: a takeover resolves at once while the + // origin holds its restart, and that restart then names the instance handed out. + let weak = broadcast.weak(); + if self.last.as_ref().is_some_and(|last| last.same_channel(&weak)) { + continue; + } + self.last = Some(weak); + return Poll::Ready(Ok(broadcast)); + } + } + + /// Apply every change on hand, returning whether any came through. + fn settle(&mut self, waiter: &kio::Waiter) -> Result { + let mut changed = false; + while let Poll::Ready(event) = self.follow.poll_next(waiter) { + changed |= self.apply(event.ok_or(Error::Closed)?); + } + Ok(changed) + } + + /// Apply one change to the path, returning whether it is one. + fn apply(&mut self, event: AnnounceEvent) -> bool { + match event { + // A pinned resolution refuses any other instance, waiting until its own serves again. + AnnounceEvent::Start(_) | AnnounceEvent::Restart(_) => self.unseen = true, + // An end is a gap that ended every request on the old route, so whatever serves the + // path next is handed out, even the same instance coming back. + AnnounceEvent::End(_) => { + self.unseen = false; + self.last = None; + } + // The same instance over another route, which its subscriptions ride out. + AnnounceEvent::Update(_) => return false, + } + true + } +} + #[cfg(all(test, feature = "async"))] mod tests { use std::time::Duration; @@ -354,6 +456,126 @@ mod tests { ); } + /// The next instance handed out, which must arrive within the origin's update hold. + async fn available(announced: &mut AnnouncedBroadcast) -> broadcast::Consumer { + moq_clock::timeout(Duration::from_secs(1), announced.available()) + .await + .expect("no instance") + .expect("the wait failed") + } + + /// Nothing more is handed out past the origin's update hold. + async fn none(announced: &mut AnnouncedBroadcast) { + let hold = crate::origin::DEFAULT_UPDATE_HOLD * 2; + if let Ok(result) = moq_clock::timeout(hold, announced.available()).await { + panic!( + "expected nothing, got {:?}", + result.map(|broadcast| broadcast.info().epoch.clone()) + ); + } + } + + /// The next request a dynamic route receives for its path. + async fn requested(dynamic: &crate::origin::Dynamic) -> crate::origin::Request { + moq_clock::timeout(Duration::from_secs(1), dynamic.requested_broadcast()) + .await + .expect("never asked") + .expect("the route closed") + } + + /// Another instance taking over while a wait resolves is the one it hands out, so the + /// restart the origin holds for it must not hand it out again while the caller holds it. + #[moq_clock::test] + async fn announced_hands_out_a_held_takeover_once() { + let origin = Hop::new(1).unwrap().produce(); + let dynamic = origin.dynamic("live", Route::default()).unwrap(); + let mut announced = origin.consume().announced_broadcast("live", None).unwrap(); + + // The wait is on the dynamic route's answer when the exact path takes over without an epoch. + let (_takeover, _publish) = futures::join!(available(&mut announced), async { + let _unanswered = requested(&dynamic).await; + origin.publish("live", Route::default()).unwrap() + }); + none(&mut announced).await; + } + + /// The follower holds what it handed out weakly: a takeover the caller let go of retires, + /// and the restart the origin held for it hands out a fresh front. + #[moq_clock::test] + async fn announced_hands_out_a_dropped_takeover_again() { + let origin = Hop::new(1).unwrap().produce(); + let dynamic = origin.dynamic("live", Route::default()).unwrap(); + let mut announced = origin.consume().announced_broadcast("live", None).unwrap(); + + let (dropped, _publish) = futures::join!(available(&mut announced), async { + let _unanswered = requested(&dynamic).await; + origin.publish("live", Route::default()).unwrap() + }); + let front = dropped.weak(); + drop(dropped); + let again = available(&mut announced).await; + assert!(front.is_closed(), "the follower kept the dropped front alive"); + assert!(!again.weak().same_channel(&front)); + } + + /// The route a wait resolves through leaving, and another instance arriving before it + /// resolves, reach the follower as an end and a start alongside the answer. That start must + /// not hand the newcomer out again. + #[moq_clock::test] + async fn announced_hands_out_a_gap_while_resolving_once() { + let origin = Hop::new(1).unwrap().produce(); + let dynamic = origin.dynamic("", Route::default()).unwrap(); + let mut announced = origin.consume().announced_broadcast("live", None).unwrap(); + + let (_arrival, _publish) = futures::join!(available(&mut announced), async { + let _unanswered = requested(&dynamic).await; + drop(dynamic); + moq_clock::sleep(crate::origin::DEFAULT_UPDATE_HOLD * 2).await; + origin.publish("live", Route::default()).unwrap() + }); + none(&mut announced).await; + } + + /// An end is a gap that ended every request on the old route, even when a route above the + /// path with the same epoch carries the instance on. So the instance serving the path + /// afterwards is handed out again, though it is the one the caller still holds. + #[moq_clock::test] + async fn announced_hands_out_the_instance_again_after_an_end() { + let origin = Hop::new(1).unwrap().produce(); + let epoch = Epoch::mint(); + let mut announced = origin.consume().announced_broadcast("live", None).unwrap(); + let exact = origin.publish("live", route(&epoch)).unwrap(); + let first = available(&mut announced).await; + + let dynamic = origin.dynamic("", route(&epoch)).unwrap(); + exact.unannounce(); + let served = broadcast::Info::new().produce(); + let (again, ()) = futures::join!(available(&mut announced), async { + requested(&dynamic).await.accept(&served); + }); + assert!(again.is_clone(&first), "the route above did not carry the instance on"); + } + + /// An announced request that pins an epoch refuses another instance taking over instead of + /// following it. + #[moq_clock::test] + async fn announced_pinned_refuses_another_instance() { + let origin = Hop::new(1).unwrap().produce(); + let epoch = Epoch::mint(); + let _first = origin.publish("live", route(&epoch)).unwrap(); + let mut announced = origin.consume().announced_broadcast("live", epoch.clone()).unwrap(); + let pinned = available(&mut announced).await; + assert_eq!(pinned.info().epoch.as_ref(), Some(&epoch)); + + let _second = origin.publish("live", route(&Epoch::mint())).unwrap(); + none(&mut announced).await; + + // Unpinned, the same takeover is followed. + let mut unpinned = origin.consume().announced_broadcast("live", None).unwrap(); + let current = available(&mut unpinned).await; + assert_ne!(current.info().epoch.as_ref(), Some(&epoch)); + } + /// A path no pattern can spell is refused rather than followed through the whole scope, /// where a route that never serves it could win its prefix. #[test] diff --git a/rs/moq-net/src/model/mod.rs b/rs/moq-net/src/model/mod.rs index 6d8fcd85ef8..be55c91c72b 100644 --- a/rs/moq-net/src/model/mod.rs +++ b/rs/moq-net/src/model/mod.rs @@ -51,6 +51,7 @@ pub use timed::Timed; /// Publishing broadcasts, announcing routes, and consuming both through an origin. pub mod origin { + pub use super::follow::AnnouncedBroadcast; pub use super::origin_impl::{ Config, Consumer, Cost, DEFAULT_UPDATE_HOLD, Driver, Dynamic, Preference, Producer, Request, Requesting, Route, Routing, Source, diff --git a/rs/moq-net/src/model/origin.rs b/rs/moq-net/src/model/origin.rs index 607e23345ab..69931a14557 100644 --- a/rs/moq-net/src/model/origin.rs +++ b/rs/moq-net/src/model/origin.rs @@ -15,6 +15,7 @@ use rand::RngExt; use super::{ Requests, WeakCache, WeakEntry, + follow::AnnouncedBroadcast, front::{Action, Candidate, Event, Front, Refusal}, }; use crate::{ @@ -5035,6 +5036,8 @@ pub struct Routing { watch: Option<(Watch, u64)>, // The ask in flight, dropped once it fails `Unroutable` until the routes move. request: Option, + // The publisher instance every ask is pinned to, if any. + epoch: Option, } impl kio::Task for Routing { @@ -5073,7 +5076,11 @@ impl kio::Task for Routing { let seen = watch.seen(); drop(table); self.watch = Some((watch, seen)); - self.request = Some(self.consumer.request(self.path.as_path(), None).into_inner()); + self.request = Some( + self.consumer + .request(self.path.as_path(), self.epoch.as_ref()) + .into_inner(), + ); } } } @@ -5472,7 +5479,7 @@ impl Consumer { /// Follow the announcements of the routes covering `path`, reduced to the one serving it. /// - /// This is how a player follows a broadcast across publisher restarts: play on a + /// [`Self::announced_broadcast`] resolves each instance this reports. Following by hand: play on a /// [`Start`](AnnounceEvent::Start), drop everything and request the path afresh on a /// [`Restart`](AnnounceEvent::Restart), and stop on an [`End`](AnnounceEvent::End). An /// [`Update`](AnnounceEvent::Update) is the same publisher instance re-priced or failed @@ -5515,17 +5522,50 @@ impl Consumer { /// [`Error::Closed`] once the origin closes, and any other resolution /// failure as-is. Await it, or poll it through [`kio::Task`]. pub fn routed_broadcast(&self, path: impl AsPath) -> kio::Pending { - let path = path.as_path().to_owned(); + kio::Pending::new(self.routing(path.as_path().to_owned(), None)) + } + /// [`Self::routed_broadcast`], refusing any instance but `epoch` when one is pinned. + pub(super) fn routing(&self, path: PathOwned, epoch: Option) -> Routing { // `allowed` keeps narrower permissions intact: if the whole path is not // reachable, no route can ever cover it, so bail rather than loop forever. let request = (!self.allowed().matches(path.as_str())).then(|| Requesting::failed(Error::Unauthorized)); - kio::Pending::new(Routing { + Routing { consumer: self.clone(), path, watch: None, request, - }) + epoch, + } + } + + /// Follow the broadcast at `path`, resolving each publisher instance that serves it. + /// + /// The Rust form of JS `request(path, { announced: true })`. The first + /// [`available`](AnnouncedBroadcast::poll_available) resolves the instance serving the path + /// once one is announced, riding out churn as [`Self::routed_broadcast`] does. Each + /// later call waits for another instance to take over (an + /// [`AnnounceEvent::Restart`]), or for the path to be served again after an + /// [`AnnounceEvent::End`], even by the same instance. Drop what was read from the + /// previous instance then: its tracks end with an error once its routes go. + /// + /// Pass an owned [`crate::Epoch`] to follow only that instance: another one taking + /// over is never handed out, and the instance is handed out again if it returns after + /// an end. Fails with [`Error::Unauthorized`] when this consumer's scope can never + /// cover the path, and with [`Error::InvalidPath`] when no pattern can spell it. + pub fn announced_broadcast( + &self, + path: impl AsPath, + epoch: impl Into>, + ) -> Result { + let path = path.as_path(); + let follow = self.follow(&path)?; + Ok(AnnouncedBroadcast::new( + self.clone(), + path.to_owned(), + epoch.into(), + follow, + )) } /// Returns a consumer rooted at `root` and restricted to matching `patterns`.