Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion doc/lib/rs/moq-net.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
1 change: 0 additions & 1 deletion quest/m1/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
13 changes: 4 additions & 9 deletions quest/m1/lazy-discovery/rust.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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
53 changes: 0 additions & 53 deletions quest/m1/net-announced-follow.md

This file was deleted.

7 changes: 2 additions & 5 deletions quest/m1/sink-restart-follow.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
7 changes: 0 additions & 7 deletions rs/moq-c/src/consume.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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<Id, Error> {
let ConsumeBroadcast { broadcast, origin } =
self.broadcast.get(broadcast).ok_or(Error::BroadcastNotFound)?.clone();
Expand Down
86 changes: 7 additions & 79 deletions rs/moq-c/src/origin.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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<Id> = 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);
}
Expand Down Expand Up @@ -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<Id>) -> Option<bool> {
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<Id>, 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::*;
Expand Down
95 changes: 10 additions & 85 deletions rs/moq-ffi/src/origin.rs
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
use std::sync::{Arc, Weak};
use std::sync::Arc;

use crate::consumer::MoqBroadcastConsumer;
use crate::error::MoqError;
Expand Down Expand Up @@ -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<MoqBroadcastConsumer>,
driver: Background,
}

impl AnnouncedBroadcast {
async fn available(&mut self) -> Result<Arc<MoqBroadcastConsumer>, 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<bool, MoqError> {
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<moq_net::announce::Event>) -> Result<bool, MoqError> {
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(),
)))
}
}

Expand Down Expand Up @@ -517,23 +451,14 @@ impl MoqOriginConsumer {
pub fn announced_broadcast(&self, path: String) -> Result<Arc<MoqAnnouncedBroadcast>, 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(),
}),
}))
Expand Down
Loading
Loading