From a70751911d00dc27b3ecde2fe897eab4930952a3 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 30 Oct 2026 14:51:42 -0700 Subject: [PATCH 1/3] quest: plan moq-transport gap signalling, a max-age defaults audit, and gapless audio switches Co-Authored-By: Claude Opus 5.5 --- quest/m1/README.md | 1 + quest/m1/max-age-defaults.md | 15 +++++++++++++++ quest/m2/README.md | 2 ++ quest/m2/gapless-audio-switch.md | 15 +++++++++++++++ quest/m2/ietf-gap-signal.md | 20 ++++++++++++++++++++ 5 files changed, 53 insertions(+) create mode 100644 quest/m1/max-age-defaults.md create mode 100644 quest/m2/gapless-audio-switch.md create mode 100644 quest/m2/ietf-gap-signal.md diff --git a/quest/m1/README.md b/quest/m1/README.md index a6a89d23d21..a53d8fb0724 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -186,6 +186,7 @@ removed). - [moqsrc max-delay](/quest/m1/gst-max-delay.md) - GStreamer's `moqsrc` takes a `max-delay` property instead of a hard-coded 1 s budget - [moq-clock moves into kio::clock](/quest/m1/kio-clock.md) - moq-clock and its test macro become `kio::clock` and `#[kio::test]` before the cut publishes them - [Poll-first async](/quest/m1/poll-first/README.md) - library crates compile no coroutines by default: async wrappers are generated from `poll_*` and gated behind an `async` feature +- [Audit retention defaults](/quest/m1/max-age-defaults.md) - every max-age default listed, with a proposed finite default for the maintainer ## Related diff --git a/quest/m1/max-age-defaults.md b/quest/m1/max-age-defaults.md new file mode 100644 index 00000000000..540b4aa42b0 --- /dev/null +++ b/quest/m1/max-age-defaults.md @@ -0,0 +1,15 @@ +# [S] Audit retention defaults and propose a finite max-age + +## Goal + +Every max-age and cache-retention default in Rust, JS, and FFI is listed with where it applies (producers, relay cache, the IETF absent-MAX_AGE meaning), and the maintainer has a concrete proposal for a finite default to decide on, so no retention is unlimited by accident. + +## Plan + +Decided 2026-10-30 (maintainer): asked whether max-age should default to 0 instead of infinite, like max_delay, which [moq-dev/moq#7403](https://github.com/moq-dev/moq/pull/7403) settled (JS and Rust default 0; unlimited is explicit `None`/`null`). For max-age, audit first and propose. + +- Inventory each default with path:line: `track::Producer`/catalog/media producers, the relay cache's eviction and pool, JS `maxAge` (which already defaults to 0 when omitted), FFI, and the IETF publisher treating an absent MAX_AGE as unlimited (wire semantics; likely kept). +- Say what 0 would break: late joiners, fetch of a non-latest group, DVR/archive. +- Propose a default with its reason and the migration; the maintainer decides, then a follow-up implements it. + +Public API: none in this quest. Wire: none. diff --git a/quest/m2/README.md b/quest/m2/README.md index 4f4f2452b0a..48c46c03390 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -272,3 +272,5 @@ lite-07; bitrate enforcement is not part of this release. - [Resume delivers late groups below its resume point](/quest/m2/resume-late-groups.md) - a bonus: groups that arrive late after a route change are delivered instead of written off - [The HLS server follows each path once](/quest/m2/hls-follow-once.md) - `Following` reports synced absence, so moq-hls resolves with one follow - [moq-bench pins the instances it measures](/quest/m2/bench-epoch-pin.md) - pooled requests pin their announced epoch, so a takeover is not counted as the same broadcast +- [moq-transport signals dropped groups](/quest/m2/ietf-gap-signal.md) - a negotiated SUBSCRIBE_DROP-style extension, built when an IETF client wants it +- [Audio track changes are gapless](/quest/m2/gapless-audio-switch.md) - no silence beyond a frame on audio format or rendition changes, enforced by media QA diff --git a/quest/m2/gapless-audio-switch.md b/quest/m2/gapless-audio-switch.md new file mode 100644 index 00000000000..4b36e85558a --- /dev/null +++ b/quest/m2/gapless-audio-switch.md @@ -0,0 +1,15 @@ +# [M] Audio track changes are gapless + +## Goal + +When a browser publisher changes audio sample rate or channel count, or a player switches audio renditions, playback has no silence beyond one decoder frame, and `just test media` fails when the longest gap exceeds that. + +## Plan + +Decided 2026-10-30 (maintainer, from [moq-dev/moq#7374](https://github.com/moq-dev/moq/pull/7374)): land the media QA cases with the gap reported, then fix the gap here. Today's longest gaps: 250 ms on a sample-rate change, 250–300 ms on a channel change, 50–70 ms switching to a second rendition, 200–280 ms switching back, and 200 ms native Opus to AAC. On the sample-rate change the publisher briefly drops audio from its catalog. + +- Publisher: keep the old audio track listed until the new one has its first group, so the catalog never goes without audio. +- Player: start decoding the new track before stopping the old one, and switch at a frame boundary. +- Turn #7374's `longest audio gap` report into a failing check with a one-frame bound. + +Public API: none expected. Wire: none. diff --git a/quest/m2/ietf-gap-signal.md b/quest/m2/ietf-gap-signal.md new file mode 100644 index 00000000000..ab31c4d8a70 --- /dev/null +++ b/quest/m2/ietf-gap-signal.md @@ -0,0 +1,20 @@ +# [M] moq-transport extension that signals dropped groups + +## Goal + +A moq-transport peer that negotiates a SUBSCRIBE_DROP-style extension tells its subscriber which groups it dropped. An ordered reader on that subscription stops waiting at the hole, as it already does on moq-lite with SUBSCRIBE_DROP. Peers without the extension behave as today. + +## Plan + +Decided 2026-10-30 (maintainer, from [moq-dev/moq#7403](https://github.com/moq-dev/moq/pull/7403)): + +- Unsignalled holes are a moq-transport protocol bug. Until a peer signals them, an ordered reader with an unlimited budget blocks at an owed hole on a moq-transport SUBSCRIBE. That's accepted for now and documented on `Ordered`/`max_delay`. +- No FETCH for holes: fetching a hole to learn whether it will ever fill races the live subscription, so it is rejected. +- No inference from later groups, and no grace periods. +- Build it only when an IETF client wants the fix: define the extension (a setup parameter plus a drop message modelled on moq-lite's SUBSCRIBE_DROP), implement it in Rust and JS, and propose it to the IETF draft. Until then this quest waits on that demand. + +Public API: none. Wire: a negotiated moq-transport extension. + +## Related + +- [Drop set](/quest/m1/drop-set.md) - moq-lite's per-cursor drop reporting this mirrors From 111a001f6031415dc77fa590f921fa79917b4bb8 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 31 Oct 2026 08:09:52 -0700 Subject: [PATCH 2/3] quest: fold gap signalling into hole markers, correct the JS maxAge baseline ietf-gap-signal planned the same negotiated SUBSCRIBE_DROP-style moq-transport extension as ietf-hole-marker. Fold its live ordered-reader outcome and the 2026-10-30 decisions into ietf-hole-marker and delete it. JS maxAge does not default to 0: @moq/net leaves it unlimited and @moq/hang's trackInfo substitutes 30 s. Co-Authored-By: Claude Opus 5.5 --- quest/m1/max-age-defaults.md | 2 +- quest/m2/README.md | 3 +-- quest/m2/ietf-gap-signal.md | 20 -------------------- quest/m2/ietf-hole-marker.md | 21 +++++++++++++++++++++ 4 files changed, 23 insertions(+), 23 deletions(-) delete mode 100644 quest/m2/ietf-gap-signal.md diff --git a/quest/m1/max-age-defaults.md b/quest/m1/max-age-defaults.md index 540b4aa42b0..52fcb3a82b8 100644 --- a/quest/m1/max-age-defaults.md +++ b/quest/m1/max-age-defaults.md @@ -8,7 +8,7 @@ Every max-age and cache-retention default in Rust, JS, and FFI is listed with wh Decided 2026-10-30 (maintainer): asked whether max-age should default to 0 instead of infinite, like max_delay, which [moq-dev/moq#7403](https://github.com/moq-dev/moq/pull/7403) settled (JS and Rust default 0; unlimited is explicit `None`/`null`). For max-age, audit first and propose. -- Inventory each default with path:line: `track::Producer`/catalog/media producers, the relay cache's eviction and pool, JS `maxAge` (which already defaults to 0 when omitted), FFI, and the IETF publisher treating an absent MAX_AGE as unlimited (wire semantics; likely kept). +- Inventory each default with path:line: `track::Producer`/catalog/media producers, the relay cache's eviction and pool, JS `maxAge` (omitted means no publisher limit in `@moq/net`'s `Info`, while `@moq/hang`'s `trackInfo` substitutes 30 s, matching `hang::container::MAX_AGE`), FFI, and the IETF publisher treating an absent MAX_AGE as unlimited (wire semantics; likely kept). - Say what 0 would break: late joiners, fetch of a non-latest group, DVR/archive. - Propose a default with its reason and the migration; the maintainer decides, then a follow-up implements it. diff --git a/quest/m2/README.md b/quest/m2/README.md index da4b3593f24..1c197b4310e 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -125,7 +125,7 @@ lite-07; bitrate enforcement is not part of this release. - [moq-transport requests end through one lease](/quest/m2/ietf-request-lease.md) - every IETF request ends through one polled lease, and the two 18k-line files split by mechanism - [A moq-transport group head fills its hole in place](/quest/m2/ietf-fill-refill.md) - fills and joining FETCHes write into the tail's group, deleting the `Fill` handoff - [Track publication is one state](/quest/m2/track-publication-state.md) - one enum replaces the published, staged, and claimed flags on `TrackState` -- [moq-transport hole markers](/quest/m2/ietf-hole-marker.md) - a negotiated extension names a SUBSCRIBE's holes, so our publishers answer multi-group FETCH from caches that know every group +- [moq-transport hole markers](/quest/m2/ietf-hole-marker.md) - a negotiated extension names a SUBSCRIBE's holes, so our publishers answer multi-group FETCH from caches that know every group; built when an IETF client wants it - [Announce interest streams share one route table](/quest/m2/announce-interest-memory.md) - per-stream announce cost follows what is in flight, not every route - [One relay serve path for every runtime](/quest/m2/relay-serve-path.md) - io_uring serves through the shared `Connection::serve` and config mapping - [A parked read of a resumed group reads its budget without re-syncing](/quest/m2/recover-budget.md) - measure, then drop the per-frame reader sync @@ -262,7 +262,6 @@ lite-07; bitrate enforcement is not part of this release. - [Resume delivers late groups below its resume point](/quest/m2/resume-late-groups.md) - a bonus: groups that arrive late after a route change are delivered instead of written off - [The HLS server follows each path once](/quest/m2/hls-follow-once.md) - `Following` reports synced absence, so moq-hls resolves with one follow - [moq-bench pins the instances it measures](/quest/m2/bench-epoch-pin.md) - pooled requests pin their announced epoch, so a takeover is not counted as the same broadcast -- [moq-transport signals dropped groups](/quest/m2/ietf-gap-signal.md) - a negotiated SUBSCRIBE_DROP-style extension, built when an IETF client wants it - [Audio track changes are gapless](/quest/m2/gapless-audio-switch.md) - no silence beyond a frame on audio format or rendition changes, enforced by media QA - [We own our WebRTC stack](/quest/m2/webrtc/README.md) - moq-rtc becomes moq-webrtc with moq-ice, the data-channel transport, and a vendored, trimmed str0m/dimpl/is/sctp-proto - [Certificate reload and qmux's tasks are supervised](/quest/m2/tls-reload-supervision.md) - a panic in either fails loudly instead of silently stopping diff --git a/quest/m2/ietf-gap-signal.md b/quest/m2/ietf-gap-signal.md deleted file mode 100644 index ab31c4d8a70..00000000000 --- a/quest/m2/ietf-gap-signal.md +++ /dev/null @@ -1,20 +0,0 @@ -# [M] moq-transport extension that signals dropped groups - -## Goal - -A moq-transport peer that negotiates a SUBSCRIBE_DROP-style extension tells its subscriber which groups it dropped. An ordered reader on that subscription stops waiting at the hole, as it already does on moq-lite with SUBSCRIBE_DROP. Peers without the extension behave as today. - -## Plan - -Decided 2026-10-30 (maintainer, from [moq-dev/moq#7403](https://github.com/moq-dev/moq/pull/7403)): - -- Unsignalled holes are a moq-transport protocol bug. Until a peer signals them, an ordered reader with an unlimited budget blocks at an owed hole on a moq-transport SUBSCRIBE. That's accepted for now and documented on `Ordered`/`max_delay`. -- No FETCH for holes: fetching a hole to learn whether it will ever fill races the live subscription, so it is rejected. -- No inference from later groups, and no grace periods. -- Build it only when an IETF client wants the fix: define the extension (a setup parameter plus a drop message modelled on moq-lite's SUBSCRIBE_DROP), implement it in Rust and JS, and propose it to the IETF draft. Until then this quest waits on that demand. - -Public API: none. Wire: a negotiated moq-transport extension. - -## Related - -- [Drop set](/quest/m1/drop-set.md) - moq-lite's per-cursor drop reporting this mirrors diff --git a/quest/m2/ietf-hole-marker.md b/quest/m2/ietf-hole-marker.md index a6e3c74328f..dbfdc669393 100644 --- a/quest/m2/ietf-hole-marker.md +++ b/quest/m2/ietf-hole-marker.md @@ -19,6 +19,10 @@ other range stays refused, as [moq-dev/moq#7204](https://github.com/moq-dev/moq/pull/7204) leaves it. +A live ordered reader on an extension-carrying SUBSCRIBE stops waiting at a +signalled hole, as it already does on moq-lite with SUBSCRIBE_DROP. Peers +without the extension behave as today. + ## Plan Decided with the maintainer on 2026-10-28 (`/quest-plan`, "what's not worth @@ -33,6 +37,19 @@ Decision prompts: - Scope: ✅ extension plus range FETCH from caches that know every hole, in m2; extension only; both in m1. +Decided 2026-10-30 (maintainer, from +[moq-dev/moq#7403](https://github.com/moq-dev/moq/pull/7403)), on detecting +unsignalled holes on a live moq-transport SUBSCRIBE: + +- Unsignalled holes are a moq-transport protocol bug. Until a peer signals + them, an ordered reader with an unlimited budget blocks at an owed hole on + a moq-transport SUBSCRIBE. That's accepted, and documented on + `Ordered`/`max_delay`. +- No FETCH to learn whether a hole will fill: it races the live + subscription. No inference from later groups, and no grace periods. +- Build this extension when an IETF client wants it; until then this quest + waits on that demand. + Only peers that implement the extension benefit, which today means our own Rust and JS moq-transport stacks. Our own peers talk moq-lite to each other, so the payoff is third-party adoption. Write the draft so it can be proposed @@ -61,3 +78,7 @@ Our publishers answer multi-group FETCH and fills over known caches. ## Required - [Drop set](/quest/m1/drop-set.md) - the per-track runs that say which groups are known holes + +## Related + +- [Ordered reads wait only on owed groups](/quest/m2/ordered-owed-wait.md) - the ordered-reader wait a signalled hole ends From 13815d2dec148a5d340c7ad61c1ae0ab5a288807 Mon Sep 17 00:00:00 2001 From: quest fixer Date: Sat, 31 Oct 2026 17:01:38 -0700 Subject: [PATCH 3/3] docs: point ordered-reader reference to landed PR --- quest/m2/ietf-hole-marker.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/quest/m2/ietf-hole-marker.md b/quest/m2/ietf-hole-marker.md index dbfdc669393..32267578599 100644 --- a/quest/m2/ietf-hole-marker.md +++ b/quest/m2/ietf-hole-marker.md @@ -81,4 +81,4 @@ Our publishers answer multi-group FETCH and fills over known caches. ## Related -- [Ordered reads wait only on owed groups](/quest/m2/ordered-owed-wait.md) - the ordered-reader wait a signalled hole ends +- [Ordered reads wait only on owed groups](https://github.com/moq-dev/moq/pull/7403) - the ordered-reader wait a signalled hole ends