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/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ let mut announced = consumer.announced();
while let Some(event) = announced.next().await {
// Skip updates and retractions.
let moq_net::announce::Event::Start(update) = event else { continue };
let broadcast = consumer.request_broadcast(&update.prefix, update.route.epoch).await?;
let broadcast = consumer.request(&update.prefix, update.route.epoch).await?;
let catalog = broadcast
.track(hang::Catalog::DEFAULT_NAME)?
.subscribe(hang::Catalog::default_subscription())
Expand Down
6 changes: 3 additions & 3 deletions doc/lib/rs/moq-net.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,10 +16,10 @@ moq-transport at setup and presents one API either way. Media is a layer above
What you use it for, beyond what the concept page already describes:

- **An origin outlives the session.** Creating a broadcast returns an origin publication that controls its announcement and exposes the broadcast to fill. Standalone and Prepared fill producers cannot announce; only publishing the Prepared answer admits its publication. A reconnect announces existing publications again, and 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.
- **Requests can pin an epoch.** `consumer.request(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.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 `follow(path)`. 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.
- **Discovery follows what you watch.** A client session asks the relay for announcements only under the prefixes its subscribe origin's readers watch, with `announced()`, `routed_broadcast`, or `announced_broadcast`, stops asking about a prefix 2s after nothing at or beneath it is watched, and asks again on reconnect. A broadcast resolved through a discovered route keeps its path watched until dropped. `request_broadcast` owns discovery of its path and reports absence only once discovery has synced; no separate watch is needed. A server session, or a client fed into an origin handle marked `with_link(origin::Link::Peer)` or `Link::Upstream`, asks for everything it may, so a relay discovers everything. An HTTP gateway (the moq-hls `Server`, the moq-rtc WHEP router) watches its whole scope while it lives, so the paths its callers name never open a request each. moq-lite-03/04 sessions, whose announcements mark no initial set, still ask for everything.
- **Request one instance, or follow them all.** `consumer.request(path, None)` resolves the instance serving a path now, and fails `Unroutable` only once discovery has synced with no route for it. `consumer.follow(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 `follow(path)`. A broadcast already resolved stays on the old instance until dropped or its route goes.
- **Discovery follows what you watch.** A client session asks the relay for announcements only under the prefixes its subscribe origin's readers watch, with `announced()`, `request`, or `follow`, stops asking about a prefix 2s after nothing at or beneath it is watched, and asks again on reconnect. A broadcast resolved through a discovered route keeps its path watched until dropped. `request` owns discovery of its path, so no separate watch is needed. A server session, or a client fed into an origin handle marked `with_link(origin::Link::Peer)` or `Link::Upstream`, asks for everything it may, so a relay discovers everything. An HTTP gateway (the moq-hls `Server`, the moq-rtc WHEP router) watches its whole scope while it lives, so the paths its callers name never open a request each. moq-lite-03/04 sessions, whose announcements mark no initial set, still ask for everything.
- **One track per name.** Concurrent subscriptions share one request and producer. The application owns sequence numbers: the broadcast keeps nothing of an ended track, so a producer that replaces it starts at 0. A name always means the same content, so the replacement continues past its predecessor's groups with `create_group` at an explicit sequence. Readers of an aborted track resume onto the replacement only when the broadcast announces an epoch; otherwise their subscription ends with the error.
- **End content by finishing tracks.** A broadcast has no finished state. When the input ends, finish each track; the broadcast stays announced and keeps serving them until you close it or drop its last producer. How long to keep it up for late readers is yours to decide: `moq_mux::Linger` holds a hang broadcast for a fixed window.
- **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. Demand rolls up: a frame being read keeps its group wanted, a group a subscription or fetch handed out keeps its track wanted until read to its end, and any wanted track keeps its broadcast wanted.
Expand Down
27 changes: 13 additions & 14 deletions quest/m1/api-audit/resolve/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,25 +20,25 @@ No caller can assemble a racy two-step resolve, and no crate hand-rolls

Decided 2026-10-22 (API audit, maintainer approved the recommendation).

The behavioral checkpoint makes `request_broadcast` own scoped discovery and
The behavioral checkpoint makes the Rust request own scoped discovery and
retry route churn. It reports table absence only after sync; a selected handler's
explicit refusal stays terminal, including a dropped Prepared answer. The front
records that refusal privately at its existing standing-route decision, rather
than guessing from unrelated mutations of the table. The old immediate lookup
is private to sessions. `Requesting::is_queued` and the public `Routing` task are
gone; `Requesting` is the owned task. The stats reader uses it instead of its
own retry on `is_queued`; the mux binding keeps its pinned `routed_broadcast`
wait. Rust and JS have same-epoch follow-return coverage, and every JS request
owns its discovery watch from creation. A pending plain JS request fails
`Unroutable` once that discovery syncs with no route for it, matching Rust. JS
announcement-following no longer silently uses a blind peer. The existing
`routed_broadcast` helper retains its route-change retry policy for the CLI,
gateway, mux binding, and relay HTTP consumers. Its removal belongs to the remaining rollout.

The approved public method names have not rolled out. Decided 2026-10-28
(maintainer, /quest-plan): the rollout splits into the four children below, so
each language and the callers review on their own. Rust and JS proceed in
parallel; the bindings follow Rust, and the callers follow both.
own retry on `is_queued`. Rust and JS have same-epoch follow-return coverage,
and every JS request owns its discovery watch from creation. A pending plain JS
request fails `Unroutable` once that discovery syncs with no route for it,
matching Rust. JS announcement-following no longer silently uses a blind peer.

Decided 2026-10-28 (maintainer, /quest-plan): the rollout splits into a child
per language and one for the callers, so each reviews on its own. Rust has
landed: `request(path, epoch)` and `follow(path, epoch)` (returning
`origin::Following`), with `routed`, `routed_broadcast`, and the route-level
`announce::Follow` gone, and its in-tree callers following the path where they
used to wait for a route. JS proceeds in parallel; the bindings follow Rust,
and the callers follow both.

This README's own work, once every child lands: the lifecycle and churn checks
across languages, the required Nix gate, and all-language interop
Expand All @@ -50,7 +50,6 @@ Wire: none.

## Required

- [Rust request and follow](/quest/m1/api-audit/resolve/rust.md) - Rust names the two resolutions `request` and `follow`, deletes `routed` and `routed_broadcast`, and makes the route-level `Follow` private
- [Bindings request and follow](/quest/m1/api-audit/resolve/bindings.md) - moq-ffi, the C ABI, and every wrapper mirror `request` and `follow` with an optional epoch
- [Callers resolve once](/quest/m1/api-audit/resolve/callers.md) - no caller hand-rolls synced resolution or decides table absence by wall clock

Expand Down
4 changes: 0 additions & 4 deletions quest/m1/api-audit/resolve/bindings.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,3 @@ Regenerate bindings from source, update every wrapper's tests, READMEs and
`just test interop --all`.

Public API: breaking in moq-ffi, the C ABI, and every wrapper. Wire: none.

## Required

- [Rust request and follow](/quest/m1/api-audit/resolve/rust.md) - the Rust names the bindings mirror
16 changes: 8 additions & 8 deletions quest/m1/api-audit/resolve/callers.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,17 +11,17 @@ broadcast is absent. Each first-party caller resolves with `request` or
Split from [Two broadcast resolutions](/quest/m1/api-audit/resolve/README.md)
on 2026-10-28 (maintainer).

- Remove the racy two-step lookup and its hidden error in moq-wasm.
- Replace the route waits in moq-cli's subscribe and report.
- Remove the hidden error in moq-wasm's resolve, which follows the path but
still discards why it failed.
- Replace moq-cli's resolve-and-drop waits before its stdout, RTMP, and WHIP
exports, which follow the path only to wait for its announcement and then
resolve it again.
- Review SRT, transcode, the benchmark connections, relay HTTP fetch
deadlines, the e2ee epoch advice, and the demo's announce-derived epoch pin;
fix each that hand-rolls resolution or decides absence by time.
deadlines, the moq-hls server's `RESOLVE_TIMEOUT` handler-stall bound, the
e2ee epoch advice, and the demo's announce-derived epoch pin; fix each that
hand-rolls resolution or decides absence by time.

List every caller in the PR with what it now uses. Run the affected packages'
tests and `just test interop --all`.

Public API: none beyond the callers' own surfaces. Wire: none.

## Required

- [Rust request and follow](/quest/m1/api-audit/resolve/rust.md) - the Rust names the callers move to
32 changes: 0 additions & 32 deletions quest/m1/api-audit/resolve/rust.md

This file was deleted.

4 changes: 1 addition & 3 deletions rs/hang/examples/subscribe.rs
Original file line number Diff line number Diff line change
Expand Up @@ -72,9 +72,7 @@ async fn run_subscribe(consumer: moq_net::origin::Consumer) -> anyhow::Result<()

// Resolve an announced broadcast and read media frames.
async fn play(consumer: moq_net::origin::Consumer, announce: moq_net::announce::Announce) -> anyhow::Result<()> {
let broadcast = consumer
.request_broadcast(&announce.prefix, announce.route.epoch)
.await?;
let broadcast = consumer.request(&announce.prefix, announce.route.epoch).await?;

// Read the catalog to discover available tracks.
let catalog_track = broadcast
Expand Down
3 changes: 1 addition & 2 deletions rs/moq-audio/src/decode/consumer.rs
Original file line number Diff line number Diff line change
Expand Up @@ -925,8 +925,7 @@ mod tests {
let relay = origin(2);
let _link = link(&publisher, &relay).await;
let consumer = relay.consume();
consumer.routed("bcast").await.unwrap();
let remote = consumer.request_broadcast("bcast", None).await.unwrap();
let remote = consumer.follow("bcast", None).unwrap().available().await.unwrap();

// A first reader warms the relay's copy with every group.
{
Expand Down
10 changes: 3 additions & 7 deletions rs/moq-bench/src/connection.rs
Original file line number Diff line number Diff line change
Expand Up @@ -315,11 +315,7 @@ async fn subscribe_named(
max_delay: Duration,
stats: Arc<Stats>,
) -> anyhow::Result<()> {
consume
.routed(path.as_str())
.await
.ok_or_else(|| anyhow::anyhow!("target broadcast was never announced: {path}"))?;
let broadcast = consume.request_broadcast(path.as_str(), None).await?;
let broadcast = consume.follow(path.as_str(), None)?.available().await?;
drain(broadcast, max_delay, &stats).await
}

Expand Down Expand Up @@ -380,7 +376,7 @@ async fn subscribe(

let mut selected = pool.len() as u64;
for path in pool {
let Ok(broadcast) = consume.request_broadcast(path.as_str(), None).await else {
let Ok(broadcast) = consume.request(path.as_str(), None).await else {
continue;
};
spawn_drain(&mut tasks, path, broadcast, max_delay, stats.clone());
Expand All @@ -402,7 +398,7 @@ async fn subscribe(
if own.contains(&path) || !seen.insert(path.clone()) {
continue;
}
let Ok(broadcast) = consume.request_broadcast(path.as_str(), None).await else {
let Ok(broadcast) = consume.request(path.as_str(), None).await else {
continue;
};
selected += 1;
Expand Down
2 changes: 1 addition & 1 deletion rs/moq-boy/src/input.rs
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ pub async fn handle_viewers(
if !restart && readers.get(&viewer_id).is_some_and(|reader| !reader.is_finished()) {
continue;
}
let Ok(broadcast) = viewer_origin.request_broadcast(&update.prefix, None).await else {
let Ok(broadcast) = viewer_origin.request(&update.prefix, None).await else {
continue;
};
tracing::info!(%viewer_id, restart, "viewer connected");
Expand Down
4 changes: 2 additions & 2 deletions rs/moq-c/src/origin.rs
Original file line number Diff line number Diff line change
Expand Up @@ -240,7 +240,7 @@ 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 announced = match consumer.announced_broadcast(path.as_str(), None) {
let mut announced = match consumer.follow(path.as_str(), None) {
Ok(announced) => announced,
Err(moq_net::Error::Unauthorized) => return Err(Error::BroadcastNotFound),
Err(err) => return Err(err.into()),
Expand Down Expand Up @@ -299,7 +299,7 @@ impl Origin {
mut close: oneshot::Receiver<()>,
) -> Result<(), Error> {
// Resolves to an error when no announced route can serve the path.
let pending = consumer.request_broadcast(path.as_str(), None);
let pending = consumer.request(path.as_str(), None);

// `biased` so a pending close always wins over a ready broadcast.
let broadcast = tokio::select! {
Expand Down
4 changes: 2 additions & 2 deletions rs/moq-c/src/publish.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1491,7 +1491,7 @@ mod supervision_tests {
async fn admission_must_match_the_broadcast_it_filled() {
let origin = moq_tokio::origin::spawn();
let claim = origin.requests("room").unwrap();
let pending = origin.consume().request_broadcast("room/first", None);
let pending = origin.consume().request("room/first", None);
let prepared = claim
.requested_broadcast()
.await
Expand Down Expand Up @@ -1520,7 +1520,7 @@ mod supervision_tests {
pending.await.unwrap();
publish.unannounce(publication).unwrap();

let pending = origin.consume().request_broadcast("room/second", None);
let pending = origin.consume().request("room/second", None);
let prepared = claim
.requested_broadcast()
.await
Expand Down
2 changes: 1 addition & 1 deletion rs/moq-cli/src/announced.rs
Original file line number Diff line number Diff line change
Expand Up @@ -229,7 +229,7 @@ mod tests {

// Every broadcast is on the relay before anything follows it.
for (path, _) in &broadcasts {
tokio::time::timeout(TIMEOUT, relay.routed_broadcast(*path))
tokio::time::timeout(TIMEOUT, relay.follow(*path, None).unwrap().available())
.await
.expect("relay routes the broadcast")
.expect("broadcast");
Expand Down
4 changes: 2 additions & 2 deletions rs/moq-cli/src/archive.rs
Original file line number Diff line number Diff line change
Expand Up @@ -107,7 +107,7 @@ pub async fn export(origin: moq_net::origin::Consumer, prefix: String, args: Exp
let store = moq_archive::Store::new(store.clone(), key);
// Requested now, so an announcement resolves the instance serving it when read, not
// whichever one serves by the time its task runs.
let request = origin.request_broadcast(&instance.0, instance.1.clone());
let request = origin.request(&instance.0, instance.1.clone());
recordings.spawn(record(request, instance, store, config.clone(), claims.clone()));
}
}
Expand Down Expand Up @@ -430,7 +430,7 @@ mod tests {
})
.await
.expect("the replay is announced");
let broadcast = origin.consume().request_broadcast("replay", None).await.unwrap();
let broadcast = origin.consume().request("replay", None).await.unwrap();
let track = broadcast.track("video").unwrap();
let mut group = track.fetch_group(0, None).await.unwrap();
let frame = group.read_frame().await.unwrap().unwrap();
Expand Down
3 changes: 2 additions & 1 deletion rs/moq-cli/src/fetch.rs
Original file line number Diff line number Diff line change
Expand Up @@ -119,7 +119,8 @@ async fn fetch_from<C>(
// is still in flight right after connecting.
let broadcast = origin
.consume()
.routed_broadcast(path)
.follow(path, None)?
.available()
.await
.with_context(|| format!("broadcast `{}` not found", crate::display_name(path)))?;
let track = broadcast.track(&args.track)?;
Expand Down
5 changes: 3 additions & 2 deletions rs/moq-cli/src/hls.rs
Original file line number Diff line number Diff line change
Expand Up @@ -299,7 +299,8 @@ pub async fn export(origin: moq_net::origin::Consumer, args: ExportArgs, name: S
// Wait for a covering route rather than asking on the spot: a recording started beside
// its publisher, or over a session that discovers only watched paths, sees no route yet.
let broadcast = scoped
.routed_broadcast(name.as_str())
.follow(name.as_str(), None)?
.available()
.await
.with_context(|| format!("failed to resolve broadcast `{name}`"))?;
let source = moq_mux::Source::new(scoped.clone(), broadcast);
Expand Down Expand Up @@ -523,7 +524,7 @@ mod test {
let importing = tokio::spawn(import(target, args, moq_net::Epoch::mint()));

announced.next().await.expect("announced");
let broadcast = consumer.request_broadcast("hls", None).await.unwrap();
let broadcast = consumer.request("hls", None).await.unwrap();
let mut catalogs = hang::catalog::Catalog::<()>::subscribe(&broadcast).await.unwrap();
let catalog = catalogs.next().await.unwrap().expect("a catalog");
let name = catalog.audio.renditions.keys().next().expect("an audio rendition");
Expand Down
Loading
Loading