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
3 changes: 2 additions & 1 deletion doc/concept/moq-lite.md
Original file line number Diff line number Diff line change
Expand Up @@ -88,7 +88,8 @@ authorization and hidden names work exactly as without one.
on the old instance until dropped or its route goes, while new requests get
the new one, so a player follows the restart by requesting the path again.
Held handles can still read their old cached content, but cannot open new
epochless requests after retirement. Request the path again for new content.
epochless requests once the restart is delivered. Request the path again for
new content.
That is how a restarted encoder, whose group numbers start over, takes the
name instead of stalling viewers on the old sequence. A relay drops its copy
of the old instance, so a new subscriber never sees its cached groups.
Expand Down
10 changes: 5 additions & 5 deletions quest/m0/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,10 +55,11 @@ Audio playout: the jitter target is default in both languages (#4162); the
remain and the release only requires the production clock and playback contracts
that depend on them.

Interop on main (2026-10-13): the cross-client matrix fails with `unroutable`
whenever WebSocket wins the connect race: since #5294, #4180's upgrade
retires epochless handles before its held `Restart` reaches anyone. It
stays in m0 (maintainer, 2026-10-13): a red Interop hides real regressions.
Interop on main (2026-10-13): the cross-client matrix failed with `unroutable`
whenever WebSocket won the connect race: since #5294, #4180's upgrade
retired epochless handles before its held `Restart` reached anyone. Handles
now retire only once it is deliverable. First-party consumers following it
moved to m1 (maintainer, 2026-10-13), since the upgrade is being removed.

Crashes (2026-10-13, #5407): a publisher on a host whose wall clock reads
before 2020 panics, and `panic = "abort"` turns any library panic into a
Expand All @@ -78,7 +79,6 @@ have fixes on `main`: macOS tests (#5335), drill-sensitivity (#5338), loom

- [CI cost and latency](/quest/m0/ci/README.md) - PRs stop queueing behind hosted runner caps: macOS and Windows move to the merge queue, caches move to R2, and setup is skipped when no work is selected
- [Draft-22 media on 0.17](/quest/m0/release-22/README.md) - a 0.17.x with the LOCATION_FILTER and FIRST_OBJECT fixes and moq-noq 1.3.5, then draft-20+ FETCH
- [Upgrade restarts epochless broadcasts](/quest/m0/upgrade-unroutable.md) - a WebSocket-to-QUIC upgrade retires epochless handles only once their `Restart` is delivered, and first-party consumers follow it, fixing Interop's `unroutable` rounds
- [Panic isolation](/quest/m0/panic-isolation.md) - unwind, ignore lock poison, and supervise every task, so a panic closes only its connection or exits on a long-lived task
- [nixpkgs ships the lld fix](/quest/m0/nixpkgs-lld-fix.md) - waiting on NixOS/nixpkgs#568680 to reach `nixpkgs-unstable`, which the release build fix bumps to
- [Release builds link](/quest/m0/release-link.md) - the Linux zigbuild release binaries and moq-gst packages link again after the 2026-10-11 nixpkgs bump, so the next release cut can publish
Expand Down
144 changes: 0 additions & 144 deletions quest/m0/upgrade-unroutable.md

This file was deleted.

2 changes: 1 addition & 1 deletion quest/m1/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,10 +54,10 @@ above them.
## Required

- [Epoch correctness](/quest/m0/broadcast-epoch/README.md) - publisher identity, duplicate suppression, and catalog pinning gate the breaking cut
- [Upgrade recovery](/quest/m0/upgrade-unroutable.md) - browser transport upgrades deliver Restart before retiring handles
- [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

- [Restart followers](/quest/m1/restart-followers.md) - first-party consumers follow an epochless `Restart`, from a GOAWAY drain or a publisher replacement, by resolving the path again
- [Cross-node flapping](/quest/m1/cross-node-flapping.md) - incident-sensitive baseline and residual stale-revival counterexamples before the route rewrite
- [Cluster routing](/quest/m1/cluster-routing/README.md) - prove shared routing contracts, implement per-origin routes, and connect outbound local clusters
- [P2P](/quest/m1/p2p/README.md) - application-selected peer sessions use shared priorities, routing, and same-epoch handover
Expand Down
63 changes: 63 additions & 0 deletions quest/m1/restart-followers.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
# [L] First-party consumers follow an epochless Restart

## Goal

Every first-party consumer that resolves a broadcast and keeps reading holds
the announce stream for its path, and on `Restart` drops its handles and
resolves the path again. On `Unroutable` it fails; it never retries a
request. A GOAWAY drain or a publisher replacement on an epochless route
then costs a long-lived consumer nothing but the restart.

## Plan

Moved to m1 on 2026-10-13 (maintainer): the WebSocket-to-QUIC upgrade is
being removed (separate m0 quest), so an epochless Restart no longer follows
every connect; it remains for GOAWAY drains and publisher replacement.

The origin side is done: a handle resolved through a peer keeps serving new
requests while the peer's epochless replacement is held, and refuses them
with `Unroutable` only once the `Restart` is deliverable (`Release` in `rs/moq-net/src/model/origin.rs`,
`rs/moq-net/tests/upgrade.rs`). So a consumer that never follows `Restart`
works through the hold (300 ms by default), and its open subscriptions stay
sticky on the old session until it closes, where they end cleanly. A
consumer that opens a request after the hold, or reads past the old
session's close, needs this quest.

Audit and fix:

- Rust: `moq export` and `moq subscribe` (the interop subscriber), and any
other moq-cli command that resolves a broadcast and keeps reading. The TS
export's `Follower` (`rs/moq-mux/src/container/ts/follower.rs`) already
watches the path, but treats any epochless return as a replacement:
sticky until the old instance ends, then `Error::Replaced`, unless
stitching. The fmp4, mkv, h264, h265, and flv exports don't follow at all.
Decide whether an epochless `Restart` restarts the output (a new init
segment mid-stream), stitches like TS, or ends the export.
`moq play` already follows `Restart` (`rs/moq-cli/src/play/media.rs`).
- Bindings: moq-ffi's catalog and container consumers, as Go, C++, and
Python reach them, and moq-c's (`moq_origin_announced_broadcast`,
`moq_consume_catalog`). Prefer following once in moq-ffi and moq-c over
duplicating it in every language wrapper. New API goes through the
Cross-Package Sync table.
- JS: `js/net`'s origin owns restart following (`js/watch/src/broadcast.ts`
mirrors its current handle). Confirm the js-native interop subscriber,
which requests with `announced: true`, follows a Rust relay's `Restart`.
- The interop clients under `test/interop/clients`, where they resolve a
broadcast themselves.

Regression: extend `rs/moq-net/tests/upgrade.rs` (or the consumer's own
tests) so each follower reads past the old session's close after an
epochless upgrade. Then run `just test interop --all`.

If a failing client still leaves its connection to idle out, fix that
client's error path to close its session, as a separate commit. The C
client's `fail()` (`_exit` without `moq_session_close`) and the C++ client
on a consumer error both look suspect.

Public API: consumer-follow API in moq-ffi and moq-c, if the audit needs it.
Wire: none.

## Related

- [Transport upgrade](/quest/m1/transport-upgrade/README.md) - its "epochless routes signal Restart and need a fresh follower resolution" decision
- [Broadcast epochs](/quest/m0/broadcast-epoch/README.md) - the players that already follow `Restart`
2 changes: 1 addition & 1 deletion quest/m1/transport-upgrade/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,4 +82,4 @@ and no cached groups splice across instances. Keep JS's matrix consistent.
## Related

- [Closed fallback](https://github.com/moq-dev/moq/pull/5284) - a WebSocket session that closes right after connecting falls back to the pending QUIC dial instead of redialing
- [Upgrade restarts epochless broadcasts](/quest/m0/upgrade-unroutable.md) - the Rust upgrade retires epochless handles before their `Restart` arrives, and the consumers that follow it
- [Restart followers](/quest/m1/restart-followers.md) - the first-party consumers that follow the `Restart` an epochless upgrade delivers
2 changes: 1 addition & 1 deletion rs/moq-net/src/fuzz.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1201,7 +1201,7 @@ impl RequestValidity {
/// Capture the lifetime of one pending request.
pub fn start(&self) -> kio::Consumer<()> {
match self.0.start() {
crate::model::broadcast::RequestValidity::Route(route) => route,
crate::model::broadcast::RequestValidity::Period(route, _) => route,
_ => unreachable!("a source watch always captures a route lease"),
}
}
Expand Down
10 changes: 9 additions & 1 deletion rs/moq-net/src/model/broadcast.rs
Original file line number Diff line number Diff line change
Expand Up @@ -534,6 +534,8 @@ pub(crate) enum RequestValidity {
Unrestricted,
Route(kio::Consumer<()>),
Selected(std::sync::Arc<crate::model::origin_impl::Selection>),
/// One period of a selection, captured by [`Self::start`].
Period(kio::Consumer<()>, std::sync::Arc<crate::model::origin_impl::Selection>),
}

impl RequestValidity {
Expand All @@ -551,14 +553,20 @@ impl RequestValidity {
/// Capture one selection period so a pending request never revives after a replacement.
pub(crate) fn start(&self) -> Self {
match self {
Self::Selected(selected) => Self::Route(selected.current()),
Self::Selected(selected) => Self::Period(selected.current(), selected.clone()),
other => other.clone(),
}
}

pub(crate) fn check(&self, waiter: &kio::Waiter) -> Result<(), crate::Error> {
match self {
Self::Route(route) if route.poll_closed(waiter).is_ready() => Err(crate::Error::Unroutable),
// A replacement retires the period only once its held `Restart` is released.
Self::Period(route, selected)
if route.poll_closed(waiter).is_ready() || selected.poll_retired(waiter).is_ready() =>
{
Err(crate::Error::Unroutable)
}
Self::Selected(_) => self.start().check(waiter),
_ => Ok(()),
}
Expand Down
Loading
Loading