From 34b973f00dc42909e7c8c963fb44273d61444c2f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 13 Oct 2026 11:04:57 -0700 Subject: [PATCH 1/5] quest: plan the #5288 follow-ups - m1 read-backfill: JS drops groups below the cursor like Rust. - m1 export-source-read: ExportSource reads Read items; delete the private counters. - m2 play-resume: moq-cli play plays out pre-end pictures on a quick resume. Co-Authored-By: Claude Opus 5.5 --- quest/m1/README.md | 2 ++ quest/m1/export-source-read.md | 23 +++++++++++++++++++++++ quest/m1/read-backfill.md | 24 ++++++++++++++++++++++++ quest/m2/README.md | 1 + quest/m2/play-resume.md | 24 ++++++++++++++++++++++++ 5 files changed, 74 insertions(+) create mode 100644 quest/m1/export-source-read.md create mode 100644 quest/m1/read-backfill.md create mode 100644 quest/m2/play-resume.md diff --git a/quest/m1/README.md b/quest/m1/README.md index 9ea44466da9..981bc6c7cd4 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -175,6 +175,8 @@ disabled rung strands WHEP, HLS, and moq-mux export viewers. - [Publish channel count](/quest/m1/publish-audio-channel-count.md) - forcing a channel count on an Audio.Capture stops costing the subscriber gaps of silence - [JS request deadline](/quest/m1/js-request-deadline.md) - each JS request, PUBLISH_NAMESPACE included, has one fatal 10 s timer from create to answer and fails fast without stream credit, so nothing queues or retries - [JS cancellation bench](/quest/m1/js-forget-bench.md) - the requests bench sweeps cancellation over competing dynamic routes, so a per-cancel cost that grows with routes shows as a slope +- [Container reads drop backfill](/quest/m1/read-backfill.md) - the JS container consumer drops groups below its read cursor like Rust +- [ExportSource reads Read items](/quest/m1/export-source-read.md) - exporters learn of gaps and ends from the read stream, and the private counters go - [Rust request credit](/quest/m1/rs-request-credit.md) - a moq-net request fails at once without stream credit instead of waiting - [qmux no-wait opens](/quest/m1/qmux-no-wait.md) - @moq/qmux rejects an over-limit create when waitUntilAvailable is false, like Chrome - [E2EE](/quest/m1/e2ee/README.md) - TypeScript and Rust peers interoperate over encrypted broadcasts no relay can decrypt diff --git a/quest/m1/export-source-read.md b/quest/m1/export-source-read.md new file mode 100644 index 00000000000..b5ecf49d05a --- /dev/null +++ b/quest/m1/export-source-read.md @@ -0,0 +1,23 @@ +# [XS] ExportSource reads gaps and ends as Read items + +## Goal + +`moq_mux::container::ExportSource` (`rs/moq-mux/src/container/source.rs`) +consumes the container read's `Read::{Frame, Gap, End}` items instead of +polling the consumer's crate-private `discontinuity()` and `markers()` +counters, and those counters are deleted. + +## Plan + +#5288 made gaps and declared ends items in the read stream but left +`ExportSource` on the old counters, so the exporters (fMP4, TS, MKV, FLV, and +the raw H.264/H.265 exports) still learn of a gap after the fact. + +- Map `Gap` to the exporter's discontinuity handling and `End` to its + declared-end handling, in delivery order. +- Delete `Consumer::discontinuity()` and `Consumer::markers()` once nothing + reads them, along with `ExportSource::markers()` if it only forwards. +- Existing exporter tests must pass unchanged; add one where a gap and an end + arrive back to back to pin the order. + +Public API: none (crate-private). Wire: none. diff --git a/quest/m1/read-backfill.md b/quest/m1/read-backfill.md new file mode 100644 index 00000000000..f16bf5b17dd --- /dev/null +++ b/quest/m1/read-backfill.md @@ -0,0 +1,24 @@ +# [S] Rust and JS container reads drop groups below the cursor + +## Goal + +The Rust and JS container consumers agree on groups that arrive below the read +cursor: neither delivers them. The read stays `Frame | Gap | End` in delivery +order past the cursor, and what lies below is already covered by the `Gap` +that moved the cursor. + +## Plan + +Found while landing #5288: JS (`js/hang/src/container/consumer.ts`) still +delivers a group that arrives below the cursor as a late backfill; Rust +(`rs/moq-mux/src/container/consumer.rs`) never does. + +- ✅ Decided 2026-10-13: both drop, matching Rust. Not chosen: both deliver, + flagged so readers can skip; leave it open. +- Change the JS consumer to discard groups below the cursor, and add a test + mirroring Rust's: a reordered group older than the cursor is never yielded + and no extra `Gap` appears. +- Check JS readers that relied on backfill (watch's audio/video decoders, + `Sync`, the arrivals handle from #5311 if it has landed) and adjust them. + +Public API: no type change; JS read behavior changes. Wire: none. diff --git a/quest/m2/README.md b/quest/m2/README.md index 4d90a14ebbd..ab84cd96099 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -120,3 +120,4 @@ and bench readiness. Refusal reasons folded the same day into - [Binding track resolver](/quest/m2/binding-track-helper.md) - binding apps subscribe to a rendition without inlining `track` or the key - [Exporters follow a rendition to a new track](/quest/m2/export-rendition-rebind.md) - the fMP4, TS, MKV and FLV exporters rebuild a rendition whose resolved `track` or `broadcast` changes under the same ID - [IETF driver double poll](/quest/m2/ietf-driver-double-poll.md) - a fired deadline costs a moq-transport session's driver one poll, as #5393 makes moq-lite's +- [Play resume](/quest/m2/play-resume.md) - `moq-cli play` plays out pictures buffered before a declared end when new media arrives quickly diff --git a/quest/m2/play-resume.md b/quest/m2/play-resume.md new file mode 100644 index 00000000000..59348d5a522 --- /dev/null +++ b/quest/m2/play-resume.md @@ -0,0 +1,24 @@ +# [M] moq-cli play plays out pictures before a quick resume + +## Goal + +When new media arrives before the pictures buffered ahead of a declared end +have played (a source switch, say), `moq-cli play` plays the old timeline out +first instead of dropping it. + +## Plan + +#5288 fixed `rs/moq-cli/src/play/video.rs` so `Read::End` no longer discards +the buffered pictures, with the restart waiting for the first frame of a later +group. A resume that arrives before those pictures play still drops them, as +it did before #5288. + +Playing them out needs a sequential timeline in `play`: queue the new group's +frames behind the remaining pre-end pictures, then rebase the clock at the +boundary. Decide in this quest whether audio follows the same queue or snaps +to the new timeline. + +Test with a declared end followed immediately by a new group: every pre-end +picture is shown before the first new one. + +Public API: none. Wire: none. From c322fc61e7fb22106f4f99bb1d91f9dd60e599ff Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 13 Oct 2026 11:10:38 -0700 Subject: [PATCH 2/5] quest: keep fMP4 group ends and JS startup media in the #5288 follow-ups Co-Authored-By: Claude Opus 5.5 --- quest/m1/export-source-read.md | 5 +++++ quest/m1/read-backfill.md | 14 +++++++++++--- 2 files changed, 16 insertions(+), 3 deletions(-) diff --git a/quest/m1/export-source-read.md b/quest/m1/export-source-read.md index b5ecf49d05a..281fc5f4328 100644 --- a/quest/m1/export-source-read.md +++ b/quest/m1/export-source-read.md @@ -15,6 +15,11 @@ the raw H.264/H.265 exports) still learn of a gap after the fact. - Map `Gap` to the exporter's discontinuity handling and `End` to its declared-end handling, in delivery order. +- Keep group boundaries reaching the exporters. `Read` has no group-end item, + but fMP4 cuts a fragment on `Event::GroupEnd` while the track stays live; + losing it stalls live fMP4 until the track closes. Keep a crate-private + boundary signal alongside the Read items, with a test that a live fMP4 export + still emits a fragment at each group end. - Delete `Consumer::discontinuity()` and `Consumer::markers()` once nothing reads them, along with `ExportSource::markers()` if it only forwards. - Existing exporter tests must pass unchanged; add one where a gap and an end diff --git a/quest/m1/read-backfill.md b/quest/m1/read-backfill.md index f16bf5b17dd..b41b890f226 100644 --- a/quest/m1/read-backfill.md +++ b/quest/m1/read-backfill.md @@ -15,9 +15,17 @@ delivers a group that arrives below the cursor as a late backfill; Rust - ✅ Decided 2026-10-13: both drop, matching Rust. Not chosen: both deliver, flagged so readers can skip; leave it open. -- Change the JS consumer to discard groups below the cursor, and add a test - mirroring Rust's: a reordered group older than the cursor is never yielded - and no extra `Gap` appears. +- Match Rust's startup first. Groups are served newest-first, so the head of a + retained window can arrive after the live edge; JS sets its cursor from the + first arrival, so dropping alone would lose valid startup media + (`consumer.outoforder.test.ts` covers that order). Rust keeps it by waiting + for an explicit start floor under the max-delay budget + (`startup_keeps_late_arriving_head_group_within_max_delay`); give JS the same + startup so the window head is never below the cursor. If that is not enough + to keep startup media, stop and re-plan rather than drop it. +- Then change the JS consumer to discard groups below the cursor, and add a + test mirroring Rust's: a reordered group older than the cursor is never + yielded and no extra `Gap` appears. - Check JS readers that relied on backfill (watch's audio/video decoders, `Sync`, the arrivals handle from #5311 if it has landed) and adjust them. From d331a1a5d38ef6bf16d4054f664b857fdf33ae5f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 13 Oct 2026 11:15:57 -0700 Subject: [PATCH 3/5] quest: flush held pictures at the play resume boundary; audio policy goes to the maintainer Co-Authored-By: Claude Opus 5.5 --- quest/m2/play-resume.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/quest/m2/play-resume.md b/quest/m2/play-resume.md index 59348d5a522..c5c22535117 100644 --- a/quest/m2/play-resume.md +++ b/quest/m2/play-resume.md @@ -15,10 +15,17 @@ it did before #5288. Playing them out needs a sequential timeline in `play`: queue the new group's frames behind the remaining pre-end pictures, then rebase the clock at the -boundary. Decide in this quest whether audio follows the same queue or snaps -to the new timeline. +boundary. Queueing encoded frames is not enough when the decoder reorders: the +declared end has to reach the decode loop so it flushes the pictures it still +holds before decoding the resumed group, which today happens only when the +track ends. -Test with a declared end followed immediately by a new group: every pre-end -picture is shown before the first new one. +Open: whether audio follows the same queue or snaps to the new timeline. Audio +owns the presentation anchor, so this sets the latency and sync policy; ask +the maintainer before implementing. + +Test with a declared end followed immediately by a new group, using a decoder +that holds pictures (depth above zero): every pre-end picture is shown before +the first new one. Public API: none. Wire: none. From 13b3ac50d83a4d4cfb5ff80c38e59d0bd8773e00 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 13 Oct 2026 11:20:23 -0700 Subject: [PATCH 4/5] quest: keep trailing frame ends for fMP4 in the ExportSource plan Co-Authored-By: Claude Opus 5.5 --- quest/m1/export-source-read.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/quest/m1/export-source-read.md b/quest/m1/export-source-read.md index 281fc5f4328..5cdea5890f2 100644 --- a/quest/m1/export-source-read.md +++ b/quest/m1/export-source-read.md @@ -15,11 +15,13 @@ the raw H.264/H.265 exports) still learn of a gap after the fact. - Map `Gap` to the exporter's discontinuity handling and `End` to its declared-end handling, in delivery order. -- Keep group boundaries reaching the exporters. `Read` has no group-end item, - but fMP4 cuts a fragment on `Event::GroupEnd` while the track stays live; - losing it stalls live fMP4 until the track closes. Keep a crate-private - boundary signal alongside the Read items, with a test that a live fMP4 export - still emits a fragment at each group end. +- Keep the events `Read` filters reaching the exporters. fMP4 cuts a fragment + on `Event::GroupEnd` while the track stays live, and sizes a durationless + final sample from a trailing `Event::FrameEnd { opens: false }`; losing + either stalls fMP4 or writes the wrong duration. Keep a crate-private path + for both alongside the Read items. Tests: a live fMP4 export still emits a + fragment at each group end, and + `zero_fragment_duration_waits_for_the_exact_video_endpoint` passes. - Delete `Consumer::discontinuity()` and `Consumer::markers()` once nothing reads them, along with `ExportSource::markers()` if it only forwards. - Existing exporter tests must pass unchanged; add one where a gap and an end From 6248b8c1e6c3ed89f5cf0a77da2b0f881b22ec63 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 13 Oct 2026 11:25:20 -0700 Subject: [PATCH 5/5] quest: leave the no-floor startup case open for the maintainer in the backfill plan Co-Authored-By: Claude Opus 5.5 --- quest/m1/read-backfill.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/quest/m1/read-backfill.md b/quest/m1/read-backfill.md index b41b890f226..be0ac649890 100644 --- a/quest/m1/read-backfill.md +++ b/quest/m1/read-backfill.md @@ -21,8 +21,13 @@ delivers a group that arrives below the cursor as a late backfill; Rust (`consumer.outoforder.test.ts` covers that order). Rust keeps it by waiting for an explicit start floor under the max-delay budget (`startup_keeps_late_arriving_head_group_within_max_delay`); give JS the same - startup so the window head is never below the cursor. If that is not enough - to keep startup media, stop and re-plan rather than drop it. + startup so the window head is never below the cursor. +- Open: a subscription with only a max delay and no start (as in + `consumer.outoforder.test.ts`) has no floor to wait for, so the window head + can still land below the cursor, in Rust too. Options include requiring a + start floor for retained windows or settling the floor before the first + delivery. Ask the maintainer before dropping groups in that case; do not + ship a drop that loses startup media. - Then change the JS consumer to discard groups below the cursor, and add a test mirroring Rust's: a reordered group older than the cursor is never yielded and no extra `Gap` appears.