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
12 changes: 6 additions & 6 deletions quest/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,10 +8,11 @@ grouped into milestones ordered by priority.
## Plan

m0 is everything in flight now: relay hardening and the IETF interop
fixes ahead of Seattle, wildcard routing, broadcast epochs, and audio playout (the jitter target). m1 is the next wave across reliability, features, performance, and
fixes ahead of Seattle, and broadcast epochs. m1 is the next wave across reliability, features, performance, and
planning. m2 holds later features, design studies, and experiments. m3 is
gated on the outside world (hardware, a partner, a consumer, or a provider's
offer) or is speculative work with no named consumer yet. m4 waits on an upstream release.
gated on the outside world (hardware, a partner, a consumer, a provider's
offer, or an upstream release) or is speculative work with no named consumer
yet.

A quest waiting on the outside world, in any milestone, requires a small quest
beside it that names the condition. That condition quest stays ready, so
Expand All @@ -20,8 +21,7 @@ move the blocked quest to the milestone its priority belongs in.

## Required

- [m0: immediate priorities](/quest/m0/README.md) - everything in flight now: relay hardening and the IETF interop fixes for Seattle, wildcard routing, broadcast epochs, and audio playout
- [m0: immediate priorities](/quest/m0/README.md) - everything in flight now: relay hardening and the IETF interop fixes for Seattle, and broadcast epochs
- [m1: next wave](/quest/m1/README.md) - reliability, capabilities, performance, and the planning that settles their contracts
- [m2: later work](/quest/m2/README.md) - deferred features, design studies, and experiments
- [m3: deferred](/quest/m3/README.md) - gated on the outside world (hardware, a partner, a consumer, or a provider's offer), or speculative with no named consumer
- [m4: upstream](/quest/m4/README.md) - waiting on an upstream release, re-checked periodically
- [m3: deferred](/quest/m3/README.md) - gated on the outside world (hardware, a partner, a consumer, a provider's offer, or an upstream release), or speculative with no named consumer
33 changes: 13 additions & 20 deletions quest/m0/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,12 @@

## Goal

The work in flight now, in three independent tracks. Relay hardening: legal
The work in flight now, in two independent tracks. Relay hardening: legal
moq-transport input never fails a session ahead of Seattle interop on
2026-10-12, every resource a peer can make the relay hold is bounded by what
it sent or by a budget, and no peer input panics the process. Identity: nothing treats who published a route as what it carries; a path and
the epoch on its route are the only content identity, and every first-party
publisher that can restart mints a fresh epoch, so #4741 stalls nobody.
Audio playout: the target is a measured estimate of arrival timing in both
languages, and a browser regression fails a nightly run.

## Plan

Expand All @@ -18,8 +16,9 @@ done. moq.pro pins this repository's `release` line, so the release gate below
also keeps #4741 from reaching it early.
The Pronto GPU integration lives in moq.pro.

The DoS hardening from an external review on 2026-09-29, verified against `main`, stays in m0
as security work. Its quests describe fixes, not exploits.
Relay hardening left in m0 is idle fronts: per-session request caps landed
in #4820, and the rest of the 2026-09-29 DoS review moved to m1 with
relay session limits.

Routing: Wildcard landed in #4403, so a service claims the prefix it could
serve instead of enumerating broadcasts. Serving the relay's ingested-only
Expand All @@ -33,37 +32,31 @@ Interop: Fastly's moq-relay-interop report (run of 2026-09-23, build
7ee2b02) was triaged against `main` on 2026-10-07. Its SETUP, UNSUBSCRIBE
and error-code items were already fixed. Fastly's reruns that day found
that a relay moves End of Track's Location and refuses imquic's End of
Group status. The seven fixes below LOCATION_FILTER come from them and go
ahead of Seattle. The cold-relay Largest and the deviations it flagged are
in m1.
Group status. The fixes below LOCATION_FILTER come from them and go ahead
of Seattle. The cold-relay Largest stays compliant with INVALID_RANGE
(decided 2026-10-08), and the deviations doc landed in #5022.

Identity: the [broadcast epoch](/quest/m0/broadcast-epoch/README.md) line
gates the next release (decided 2026-10-03:
#4741 resumes an un-epoched republish into the old broadcast and stalls its
viewers). #4741 can merge to main, but no release ships until first-party
publishers mint epochs.

Audio playout: the jitter target replaces the round-trip guess. The browser
audio quality harness in `test/audio-quality/` has landed; it grades playout
nightly and records the traces it replays. Its native lane is a standalone m1
quest, since nothing here waits on it. The [A/V clock](/quest/m1/av-clock.md)
moved to m1 in the 2026-09-30 audit: it waits on the whole jitter line and is
a published `@moq/watch` break.
Audio playout: the jitter target is default in both languages (#4162); the
[line](/quest/m1/audio-jitter-target/README.md) moved to m1 in the
2026-10-08 audit, since only a manual browser proof and a native trace replay
remain and no release waits on them.

## Required

- [Held group wakes](/quest/m0/held-group-wakes.md) - a group held across a route switch is woken when its successor's first timestamp or abort makes it stale, not at the next unrelated append
- [Draft-22 LOCATION_FILTER](/quest/m0/ietf-location-filter-22.md) - moqt-22 LOCATION_FILTER carries its type instead of a Length in Rust and JS, so a draft-22 peer reads our Next Object correctly
- [End of Track Location](/quest/m0/ietf-end-of-track-location.md) - a relay forwards END_OF_TRACK at its upstream's Location, on the last group's stream, instead of re-sending it at the next group's object 0
- [Capped stream END_OF_GROUP](/quest/m0/ietf-end-of-track-location.md) - a stream capped by the subscription's end Location never claims END_OF_GROUP; moving End of Track's Location is deferred
- [End of Group status](/quest/m0/ietf-end-of-group-status.md) - an End of Group status on a stream whose header already marks the group's end is accepted, so imquic's last object per group arrives
- [Prefix route fronts](/quest/m0/prefix-route-fronts.md) - a prefix route cannot be made to mint one front per requested path
- [TRACK stream demand](/quest/m0/track-stream-demand.md) - a lite-05+ subscribe shows the publisher one `used` edge, not a flap between TRACK and SUBSCRIBE
- [Idle fronts](/quest/m0/idle-fronts.md) - a front nobody has read for the linger ends with its per-path state, so a standing claim stops accumulating fronts and sources
- [Upstream position regression](/quest/m0/largest-regression.md) - a relay copy that sees upstream's largest group go backwards ends instead of serving the old instance's cache
- [qmux credit](/quest/m0/qmux-credit.md) - qmux returns connection credit for dropped and stopped streams and delivers its close frame, on both lines
- [web-transport releases the qmux fixes](/quest/m0/qmux-credit-upstream.md) - waiting on moq-dev/web-transport#412 and #413 to merge and ship, which qmux credit bumps to
- [qmux credit](/quest/m0/qmux-credit.md) - qmux returns connection credit for dropped and stopped streams and delivers its close frame, on both lines
- [Broadcast epochs](/quest/m0/broadcast-epoch/README.md) - every first-party publisher that can restart mints a fresh route epoch, the newest wins a path, and only routes with the same epoch resume a subscription
- [Audio jitter target](/quest/m0/audio-jitter-target/README.md) - the audio playout target is a measured estimate of arrival timing in both languages, not a round-trip guess

## Related

Expand Down
15 changes: 7 additions & 8 deletions quest/m0/broadcast-epoch/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,13 +54,14 @@ Decided:
explicit `Restart` announce event tells players to follow, through
[Restart](/quest/m0/broadcast-epoch/restart.md). When the newest goes and
an older one is still live, the older one wins again as a new broadcast.
- On lite-07 a claim's answer will carry the served broadcast's own epoch
([Claim-served epochs](/quest/m0/broadcast-epoch/claim-epochs.md), planned
2026-10-07), which adds it to TRACK_INFO.
- [Claim-served epochs](/quest/m1/claim-epochs.md), where a
lite-07 claim's answer carries the served broadcast's own epoch, no longer
gates this line (decided 2026-10-08): it is a lite-07 opt-in, so it moved
to m1.
- A catalog `broadcast` reference by name follows the newest epoch, since a
path cannot name one.
- Every first-party publisher that can restart mints its own: the apps,
moq-boy, and moq-room through [Apps](/quest/m0/broadcast-epoch/apps.md), the
- Every first-party publisher that can restart mints its own: the apps and
moq-boy through [Apps](/quest/m0/broadcast-epoch/apps.md), the
ingest gateways, moqsink, and the bindings below. moq-stats mints one per
[group announcement](/doc/concept/stats.md#broadcasts), which also gated
the release (decided 2026-10-04).
Expand Down Expand Up @@ -93,12 +94,10 @@ then. MoQ Pro's VOD `storage.json` moves from the same seed to its own epoch.

## Required

- [Apps](/quest/m0/broadcast-epoch/apps.md) - moq-cli, the browser publish and watch components, and demo/web restart into a new epoch and reset on the switch
- [Restart](/quest/m0/broadcast-epoch/restart.md) - a replaced broadcast reaches announce consumers as an explicit Restart, subscriptions stay sticky, and new requests never join a replaced route's front
- [Apps](/quest/m0/broadcast-epoch/apps.md) - moq-cli, the browser publish and watch components, and demo/web restart into a new epoch and reset on the switch
- [Publish catalog restart](/quest/m0/broadcast-epoch/publish-catalog-restart.md) - `@moq/publish` never reuses catalog group numbers under one name and epoch after a re-announce
- [TS restart](/quest/m0/broadcast-epoch/ts-restart.md) - a signalled backward TS discontinuity finishes the broadcast and continues the same input under a fresh epoch
- [Bindings](/quest/m0/broadcast-epoch/bindings.md) - moq-ffi and every wrapper expose the epoch and let a publisher announce one
- [moqsrc](/quest/m0/broadcast-epoch/moqsrc.md) - moqsrc switches to the new broadcast on a `Restart`, keeping its pads by rendition name
- [Claim-served epochs](/quest/m0/broadcast-epoch/claim-epochs.md) - a claim's answer names the instance that served it, so a restarted output is never spliced and a per-output epoch costs no restart
- [Stats totals and prefix tracks](/quest/m0/broadcast-epoch/stats-split.md) - the same release retires the per-path stats maps for totals and on-demand prefix tracks (decided 2026-10-05)
- [Dynamic epoch update](/quest/m0/broadcast-epoch/dynamic-epoch.md) - an epoch change through `Dynamic::update` announces a `Restart` downstream, so subscribers drop the old copy and resubscribe, while the origin keeps serving
8 changes: 4 additions & 4 deletions quest/m0/broadcast-epoch/apps.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@

## Goal

`moq-cli` publish and play, `@moq/publish`, `@moq/watch`, `demo/web`,
moq-boy, and moq-room announce a freshly minted epoch per run. Each publish
`moq-cli` publish and play, `@moq/publish`, `@moq/watch`, `demo/web`, and
moq-boy announce a freshly minted epoch per run. Each publish
run is a new epoch, so a restart while the
old route lingers is a new broadcast rather than a resume into the old one,
which stalls viewers until the new run's group sequence catches up. A viewer
Expand All @@ -20,8 +20,8 @@ switches to a republish within an RTT. Logs show the epoch.
failover (an `Update`) never restarts playback. #4970, which drove them
from announcements, closed unmerged. Test a republish mid-playback in the
browser and native players.
- Update `doc/bin/cli.md` and every example invocation that shows a published
path.
- moq-room is out (decided 2026-10-08): it only discovers participants, and
the caller that publishes into a room mints the epoch.

## Required

Expand Down
7 changes: 5 additions & 2 deletions quest/m0/broadcast-epoch/bindings.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,8 @@
`moq-ffi` and the py, swift, kt, go, and dart wrappers can announce an epoch like Rust, with a minting helper. The generated C and C++
bindings pick it up from moq-ffi; libmoq gets no new API. The epoch on an announced route is
readable, and a publisher can pass an explicit one. Every wrapper surfaces
the `Restart` announce event. The reconnect counter `session.epoch()` is
renamed so "epoch" has one meaning.
the `Restart` announce event. The reconnect counter `session.epoch()` and the
audio timeline re-anchor `reset_epoch` are renamed so "epoch" has one meaning.

## Plan

Expand All @@ -15,6 +15,9 @@ renamed so "epoch" has one meaning.
- Rename the reconnect counter, `moq_tokio::Connection::epoch()` and
`session.epoch()` in every binding (for example to `connects()`). That is
a break.
- Rename the audio re-anchor the same way (decided 2026-10-08, since it also
says "epoch"): `moq_audio::encode::Producer::reset_epoch`, its moq-ffi
method, the wrappers that expose it, and moq-boy's copy.
- `MoqAnnounceEvent::Restart` lands in moq-ffi with
[Restart](/quest/m0/broadcast-epoch/restart.md); each wrapper maps it.
- Update `doc/lib/{py,swift,kt,go,dart}` per the cross-package sync table,
Expand Down
2 changes: 1 addition & 1 deletion quest/m0/broadcast-epoch/dynamic-epoch.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ since two epochs may carry the same content; a handler that wants fresh
content under the new epoch closes its old broadcast itself.

Non-goals: the epoch a claim-served answer carries
([#5010](https://github.com/moq-dev/moq/pull/5010)'s claim-epochs plan), and
([Claim-served epochs](/quest/m1/claim-epochs.md)), and
same-epoch repricing, which keeps every handle and stays an `Update`.

## Plan
Expand Down
59 changes: 26 additions & 33 deletions quest/m0/broadcast-epoch/moqsrc.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,8 @@ When the source behind `moqsrc`'s path restarts (an announce `Restart`), the
pipeline keeps running and switches to the new broadcast: a fresh catalog on
the same pads, with no error on the bus. Once subscriptions are sticky,
`moqsrc` would otherwise keep playing the replaced broadcast until its route
goes, then end or error. A broadcast that ends with no successor still ends as
it does today, unless the opt-in `linger` holds it.
goes, then end or error. A broadcast that ends holds its pads until the path
is announced again, like a player going offline and back online.

## Plan

Expand All @@ -27,12 +27,15 @@ Decided in planning (2026-10-06, after #4955 found that no quest covered
than the path itself. `moqsrc` switches on a `Restart` of the route its
path resolves through; the re-request re-resolves upstream, and if it
lands on the same source the run still restarts on the same pads.
- **Errors keep today's handling.** A replacement no longer ends the old
subscriptions, so a catalog error posts the session error and a track error
logs and ends that pad, as today. The earlier rule treating `Unroutable` as
- **Errors keep today's handling, except source loss.** A replacement no
longer ends the old subscriptions, so a malformed catalog or track posts
the session error or ends that pad, as today. Losing the source (the
publisher's session closing, or the route going away) is not fatal: it
enters the held state below even when it arrives before the announce
`End`, since `catalog.next()` and session completion
(`rs/moq-gst/src/source/imp.rs`) see it first today. The earlier rule treating `Unroutable` as
a switch in flight is dropped: it could not tell a switch from a dead route
and could hang. Only `linger` below defers an error, and only for its
window.
and could hang.
- **Cutover.** Cancel the old pumps as soon as the `Restart` is seen, without
waiting for their subscriptions to end.
- **Pads (decided 2026-10-07, reconfirmed after the Restart re-scope).**
Expand All @@ -48,22 +51,16 @@ Decided in planning (2026-10-06, after #4955 found that no quest covered
restarts at 0) as late. An in-run caps or container change keeps its pad
the same way. A rendition the new catalog drops ends with EOS; a new or
renamed one gets a new pad.
- **Linger (decided 2026-10-07).** A `linger` property, default 0, that
covers a lite-06 or moq-transport restart whose END and START are not
coalesced into a `Restart`, and a crashed or withdrawn source. While
`linger` > 0, a track that ends or loses its source (the route went,
`Dropped`, or the upstream session closed) hands its pad back without EOS,
since tracks, the catalog, and `End` arrive on different streams in either
order. A rendition the catalog already retired still drains to EOS as today.
The window starts on the first of `End`, the catalog finishing (a prefix
can stay announced after its output finishes), or the catalog losing its
source. A `Start` or `Restart` in it resumes on the same pads. At expiry
every held pad gets EOS, and the session error posts only if the catalog
lost its source; a pump still streaming ends as it would without linger. A
held track whose catalog and path stay live waits the same bound from its
own end, then ends its pad as it would at 0; opening the window cancels
those per-track timers, so held pads follow the window's expiry. The bound
keeps this from becoming a silent hang. At 0 nothing changes from today.
- **Hold pads from `End` to `Start` (decided 2026-10-08, replacing the
`linger` timer).** This covers a lite-06 or moq-transport restart whose END
and START are not coalesced into a `Restart`, and a withdrawn source. A
track that ends or loses its source hands its pad back without EOS, since
tracks, the catalog, and `End` arrive on different streams in either order;
the next `Start` resumes on the same pads. The regression covers both
orders: source loss before `End`, and `End` before source loss. A rendition the catalog retired
still drains to EOS. No timer and no property: announcements already say
when the source is back, and a timer cannot tell a slow restart from a
dead source.
- **Where.** The logic stays in `rs/moq-gst/src/source`. If
[Apps](/quest/m0/broadcast-epoch/apps.md) lands a shared helper for
following announcements first, use it instead.
Expand All @@ -73,20 +70,16 @@ Decided in planning (2026-10-06, after #4955 found that no quest covered
Cover an epochless source change that also switches, a `Restart` of a
prefix route covering the path that switches too, a same-epoch
re-announce (`Update`) that does not, a switch with new caps that keeps the
pad, and with `linger` set: an `End` then `Start` that resumes on the same
pads (media FIN, a delay, catalog FIN, `End`, then `Start`), an old
publisher's session closed (not finished) over a relay that resumes on the
next `Start`, and a finished output under a still-announced prefix that
gets EOS by the deadline, and a lone track losing its source while its
siblings and the catalog stay live, which ends only that pad. With
`linger` at 0, each of these ends or errors as today. Drive the linger
window with mocked time.
pad, an `End` then `Start` that resumes on the same pads (media FIN, a
delay, catalog FIN, `End`, then `Start`), and an old publisher's session
closed (not finished) over a relay that resumes on the next `Start`.

Update the `moqsrc` section of `doc/bin/gstreamer.md`: a restart keeps each
pad by rendition name, a format change keeps its pad, a dropped rendition gets
EOS, and `linger`.
EOS, and an ended broadcast holds its pads until the next `Start`.

Public API: a new `linger` property on `moqsrc`. Wire: none.
Public API: no new property, but an ended broadcast no longer sends EOS on
its pads. Wire: none.

## Required

Expand Down
7 changes: 7 additions & 0 deletions quest/m0/broadcast-epoch/publish-catalog-restart.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,4 +22,11 @@ re-announce. `js/publish/src/broadcast.ts` mints the epoch once and keeps the
publisher across unannounce and announce on purpose, which points at
continuing the sequence.

#4929 (merged) made an on-demand producer continue a name's sequences
across replacements in both languages, but JS `createTrack` and
`insertTrack` still start at 0 (`doc/lib/js/net.md`). If this reproduces,
consider fixing it there, in `@moq/net`'s `createTrack`, so every JS
publisher continues the sequence, rather than in `@moq/publish` alone.

Public API: none expected. Wire: none.

Loading
Loading