diff --git a/quest/m1/README.md b/quest/m1/README.md index 0520ca02390..5a571c72672 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -108,7 +108,7 @@ lands before the cut. - [Received timestamps are media time](/quest/m1/lite-time-provenance.md) - a received timed track's timestamps are media time, so the rewind check can run across hops - [WebGPU on Safari](/quest/m1/webgpu-safari.md) - the WebGPU renderer is verified on Safari 26 for macOS and iOS - [HLS export drains after End](/quest/m1/hls-export-end-drain.md) - a cleanly ended broadcast still exports its retained segments -- [Plan: HLS export failure signal](/quest/m1/hls-failure-signal.md) - decide what players see when the exporter's timeline fails, live or history, so a truncated recording never looks complete +- [A failed HLS export answers with an error](/quest/m1/hls-failure-signal.md) - playlists answer a no-store 5xx once their timeline fails, and so does the DASH manifest for a shared reference failure, so a truncated recording never looks complete - [Close tail drain](/quest/m1/close-tail-drain.md) - after a peer close, subscribers read the group streams their transport already delivered instead of aborting them, so a finished tail arrives on every version - [Binding linger](/quest/m1/linger-ffi.md) - `moq-ffi` and every binding finish a broadcast cleanly, so subscribers drain it until its media is stale - [JS linger](/quest/m1/linger-js.md) - `js/net` finishes a broadcast cleanly like Rust, and `@moq/publish` uses it when a source stops diff --git a/quest/m1/archive/history-floor.md b/quest/m1/archive/history-floor.md index dafdddb9f08..2db8414f7c0 100644 --- a/quest/m1/archive/history-floor.md +++ b/quest/m1/archive/history-floor.md @@ -38,5 +38,5 @@ stored segment, and a hole after it still fails. ## Related -- [HLS failure signal](/quest/m1/hls-failure-signal.md) - the other history-mode gap left by #5236 +- [Failed HLS exports error](/quest/m1/hls-failure-signal.md) - the other history-mode gap left by #5236 - [DVR rewind](/quest/m2/archive-dvr.md) - seeks through the same bounded archive diff --git a/quest/m1/hls-failure-signal.md b/quest/m1/hls-failure-signal.md index c9a5b5b5721..9ed656d9cc9 100644 --- a/quest/m1/hls-failure-signal.md +++ b/quest/m1/hls-failure-signal.md @@ -1,35 +1,74 @@ -# [S] Plan: HLS export failure signal +# [S] A failed HLS export answers with an error ## Goal -Decide what an HLS or DASH player sees when the exporter's timeline fails, in -both live and history mode, so a truncated recording never looks complete. -The output is an implementation quest, or a recorded reason to keep today's -behaviour. +Once an exporter's timeline fails, in live or history mode, its media +playlists and the DASH manifest answer a 5xx with `Cache-Control: no-store` +instead of ending with `EXT-X-ENDLIST`, so a truncated recording never looks +complete and no CDN caches a short one. `EXT-X-ENDLIST` and the DASH static +manifest stay reserved for a clean finish. A rendition whose own timeline +fails errors only its own playlist, so players can switch to a sibling. ## Plan -Today any timeline failure ends every playlist like a clean finish -(`EXT-X-ENDLIST`; see `watch_timeline` in `rs/moq-hls/src/export/mod.rs`), -because a window left live would freeze players with no signal. A rendition -whose own timeline fails ends the same way. In history mode -(`export::Config::history`), a missing or corrupt stored timeline group after -group 0 therefore ends a playlist that lists only the records before it, -indistinguishable from a complete recording. Found by the Codex review of -#5236, which deferred it here. - -Options to weigh: - -- Keep `EXT-X-ENDLIST` for a clean finish only, and answer a failed export's - playlist with an HTTP error once it fails, so players and CDNs stop rather - than cache a short recording. -- In history mode only, clear the partial listing on failure (an ended, - empty playlist), leaving live mode as it is. -- Keep listing what resolved, and mark the failure in band, if HLS or DASH - has a tag players honour for it. - -Cover live and history alike, and the DASH manifest, which shares the -windows. Test a mid-history group that fails to FETCH or decode. +Decided by the maintainer on 2026-10-19, over clearing a history playlist to +an ended empty one (still reads as finished) and an in-band marker (HLS and +DASH have none; `EXT-X-GAP` needs durations a failed timeline cannot give). + +Failures take three paths today, and all three end the playlist as finished: + +- The shared reference timeline: `watch_timeline` + (`rs/moq-hls/src/export/mod.rs`) calls `renditions::Fanout::finish` on + success and failure alike. Give the feed a failed state beside `ended`, set + on a timeline error; late-created renditions start failed like they start + ended. +- A retained past reference: in history mode `watch_catalog` keeps old + reference watchers after a handoff, and when one errors `watch_timeline` + takes the `finish(...) == false` branch and retires its rows + (`renditions.pop`), so the recording loses a prefix and still ends as + complete. Mark the feed failed there too instead of only retiring the rows. +- A rendition's own timeline: `watch_spans` calls `Spans::fail` + (`rs/moq-hls/src/export/spans.rs`), and `Rendition::snapshot_as` + (`rendition.rs`) folds a failed last row into `finished`. Expose that + rendition-local failure to the playlist route instead of rendering + `EXT-X-ENDLIST`. `Rendition::playlist` waits in `playable()` (and then + `init()`), which watch only the live window, so the failure must also wake + those waits: otherwise a request pending before the first row times out as a + 404, and a router-free caller waits forever. + +The media playlist routes (`rs/moq-hls/src/server/routes.rs`) answer the +existing no-store error response for any of these failures. The DASH manifest +is broadcast-wide, so it answers that error only for a shared or retained +reference failure; a rendition-local failure omits that representation and +keeps its siblings available. Segments already listed may stay fetchable; +only the listings refuse. + +Test a mid-history group that fails to FETCH or decode, a ranged clip over a +failed timeline (5xx, not 416), a playlist request already pending when the +timeline fails before its first row, a retained reference +failing after a handoff, a live timeline error, a single failed rendition +beside a healthy one (its playlist errors, the sibling's and the DASH +manifest's do not), and the DASH manifest after a shared failure. +Update `doc/` where it describes how an export ends. + +Embedders that skip the server router read the same failure from the public +API: every public accessor that renders a listing reports it as an error, so a +failed timeline differs from a listing that is not available yet. Today those +are `Broadcaster::manifest` and `Rendition::media_playlist` (both +`Option`, becoming `Result>`) and `Rendition::playlist` +(already a `Result`). `Broadcaster::manifest` errors only for a shared or +retained reference failure; a failed rendition drops from the manifest while its +own `Rendition` accessors error. The routes map those errors to the 5xx. This +includes the ranged history +path: `snapshot_range` turns a failed timeline into `Error::RangeUnavailable`, +which answers 416 as if the client asked for a bad range; it returns the +failed-timeline error instead. Audit every snapshot path for the same fold +rather than relying on this list. + +Public API: breaking, `export::Broadcaster::manifest` and +`export::Rendition::media_playlist` return a `Result`, and a new `Error` +variant for a failed timeline; add a `MIGRATE.md` entry. Wire: none; HTTP +responses change for a failed export. ## Related diff --git a/quest/m1/quic/README.md b/quest/m1/quic/README.md index e3bbaf9a0a6..e465c2b06a4 100644 --- a/quest/m1/quic/README.md +++ b/quest/m1/quic/README.md @@ -64,9 +64,6 @@ cache limits remain separate; bitrate pacing composes with this memory cap. ## Required - [Bound message assembly](/quest/m1/quic/receive-memory.md) - complete headers and frames return credit, and receiver priority cancellation restores progress -- [A reset group keeps its header](/quest/m1/quic/group-reset.md) - a lite - publisher resets a group with `RESET_STREAM_AT`, so its subscriber drops the - tail grace ## Related diff --git a/quest/m1/quic/group-reset.md b/quest/m1/quic/group-reset.md deleted file mode 100644 index f24cb454b9d..00000000000 --- a/quest/m1/quic/group-reset.md +++ /dev/null @@ -1,60 +0,0 @@ -# [M] A reset group keeps its header - -## Goal - -A moq-lite publisher on a native QUIC or WebTransport stack resets a group -stream with `RESET_STREAM_AT`, still delivering the group header, so the -subscriber can always tell which group the reset belongs to. A subscriber -that knows its publisher does this stops waiting out the tail grace for -groups whose reset lost the header (`rs/moq-net/src/tail.rs`, -`js/net/src/tail.ts`). Subscribers whose publisher cannot do it, such as a -browser, keep the grace. - -## Plan - -Split from the transport half, which landed in `moq-quic`, -`moq_tokio::quic::web`, and moq-uring's WebTransport adapter (#5690). There, -`SendStream::reset_at(offset, code)` sends `RESET_STREAM_AT` with that -offset as the Reliable Size. A peer without the extension instead gets a plain -`RESET_STREAM` once it has acknowledged the data before the checkpoint, a round -trip later. The WebTransport adapters already keep their own stream header -this way. - -That fallback is weaker than it looks. An ACK only means the peer's QUIC stack -holds the bytes, not that its application read them, and RFC 9000 lets a -receiver discard unread data on `RESET_STREAM`. The WebTransport header -survives because receiving stacks parse it on arrival. A MoQ group header is -read by the application, so check whether Chrome hands it to JS when a plain -`RESET_STREAM` follows the ACK, and treat a peer without `reset_stream_at` as -unable to keep the header unless it does. - -- Give moq-net's `transport::poll::SendStream` a reset that keeps the first - `offset` bytes, matching `moq-quic`'s `reset_at(offset, code)`. Decided - 2026-10-17 on #5817: a byte offset rather than a `Checkpoint` handle; an - offset past the written data panics instead of being unrepresentable. - Implement it in the moq-tokio and - moq-uring adapters. Backends that cannot do it (browser, qmux, iroh) report - that rather than silently sending a plain reset. -- The lite publisher checkpoints right after writing a group header and - resets the group from that checkpoint. -- QUIC negotiation alone cannot drop the grace. A peer's stack can advertise - `reset_stream_at` while its application never sends one, as a browser - publisher whose WebTransport API has no reliable reset. Dropping the grace - on negotiation would hang the tail. So the publisher declares it with a - MoQ-level signal, per session, since each relay hop re-serves groups on its - own streams. Open: the signal's shape (a SETUP parameter or a version - feature), and how it composes with SUBSCRIBE_DROP, which already names a - group reset before its header on lite-05 and later. Any wire change updates - `drafts/draft-lcurley-moq-lite.md`. -- Remove the grace for subscriptions on sessions that declare it, in Rust and - `@moq/net`. Datagram holes still wait out the grace. - -Test a group reset before any payload with and without the signal, both -directions between Rust and `@moq/net`, and through a relay hop. Cover it in -the Chrome wasm harness and the native interop matrix, which the transport -half did not reach. - -## Related - -- [qmux on the QUIC stream state machine](/quest/m2/quic-qmux.md) - qmux reuses - `moq-quic`'s reset state diff --git a/quest/m1/sink-restart-follow.md b/quest/m1/sink-restart-follow.md index dde69b0bdee..a0e7a48a2c6 100644 --- a/quest/m1/sink-restart-follow.md +++ b/quest/m1/sink-restart-follow.md @@ -18,7 +18,7 @@ and fix the rest the same way: - `export hls`: `moq-hls`'s server resolves per request; check that a restart moves new requests to the new instance and how a playlist marks the break (`EXT-X-DISCONTINUITY`). Coordinate with - [HLS export failure signal](/quest/m1/hls-failure-signal.md). + [Failed HLS exports error](/quest/m1/hls-failure-signal.md). - `export rtmp`, `export srt`, `export rtc`, both `--listen` (per-viewer streams in `moq-rtmp`, `moq-srt`, `moq-rtc`) and `--connect` (one push). SRT already rides the TS follower (`--linger`, `--stitch`); confirm its diff --git a/quest/m2/e2ee/README.md b/quest/m2/e2ee/README.md index 6249e12ee9e..5de9378fe31 100644 --- a/quest/m2/e2ee/README.md +++ b/quest/m2/e2ee/README.md @@ -46,7 +46,7 @@ The Rust and TypeScript cores expose the same surface, and nothing else: ### Dynamic names -Decided with the maintainer on 2026-10-17: physical names are a one-way hash, so a publisher cannot answer a request for a name it never declared. [Dynamic names](/quest/m2/e2ee/dynamic-names.md) designs that before any implementation, and [#5876](https://github.com/moq-dev/moq/pull/5876) (the broadcast wrappers, whose `reserve_track` covers only names declared in advance) is held until it decides. +Decided with the maintainer on 2026-10-17: physical names are a one-way hash, so a publisher cannot answer a request for a name it never declared. [Dynamic names](/quest/m2/e2ee/dynamic-names.md) designs that before any dynamic-name implementation. The broadcast wrappers merged in [#5876](https://github.com/moq-dev/moq/pull/5876) with `reserve_track`, which covers names declared in advance; that is every track the Rust publishers serve, so [rust-publish](/quest/m2/e2ee/rust-publish.md) does not wait on the design (maintainer, 2026-10-19). [Reopen](/quest/m2/e2ee/reopen.md) and the [consumer shape](/quest/m2/e2ee/consumer.md) still do. ## Required @@ -55,7 +55,7 @@ Decided with the maintainer on 2026-10-17: physical names are a one-way hash, so semantic catalog in E2EE mode - [Dynamic names](/quest/m2/e2ee/dynamic-names.md) - a reviewed design for answering requests for undeclared track names, split into implementation - quests; #5876 waits on it + quests - [Refuse a re-created track](/quest/m2/e2ee/reopen.md) - a name the producer already carried fails loudly - [Encrypted consumer shape](/quest/m2/e2ee/consumer.md) - one consumer shape, the producer's mirror, shared by browser, CLI, and FFI - [Encrypted browser components](/quest/m2/e2ee/browser.md) - browser publish diff --git a/quest/m2/e2ee/dynamic-names.md b/quest/m2/e2ee/dynamic-names.md index b88c9e3b541..1116777c747 100644 --- a/quest/m2/e2ee/dynamic-names.md +++ b/quest/m2/e2ee/dynamic-names.md @@ -2,7 +2,7 @@ ## Goal -A written design, approved by the maintainer before any implementation, for +A written design, approved by the maintainer before any dynamic-name implementation, for how an e2ee publisher answers a request for a track name it never declared. It compares at least three options against the threat model of [draft-lcurley-moq-e2ee](/drafts/draft-lcurley-moq-e2ee.md): @@ -20,8 +20,12 @@ Decided with the maintainer on 2026-10-17: - Design-only, with a design-review gate: open the PR as a draft and get the maintainer's approval of the choice before any implementation quest starts. -- [#5876](https://github.com/moq-dev/moq/pull/5876) (the e2ee broadcast - wrappers, with `reserve_track`) is held until this quest decides. +- The Rust publishers do not wait on it (maintainer, 2026-10-19): the + broadcast wrappers merged in [#5876](https://github.com/moq-dev/moq/pull/5876), + and [rust-publish](/quest/m2/e2ee/rust-publish.md) declares every track it + serves. [Reopen](/quest/m2/e2ee/reopen.md) and the + [consumer shape](/quest/m2/e2ee/consumer.md) still wait, since the chosen + mapping can change the physical names they handle. Background: a physical track name is a one-way HKDF of the semantic name (the draft's Key Derivation section). Only the CDN sees physical names, and a diff --git a/quest/m2/e2ee/rust-publish.md b/quest/m2/e2ee/rust-publish.md index f53958a9a70..00eeae5805c 100644 --- a/quest/m2/e2ee/rust-publish.md +++ b/quest/m2/e2ee/rust-publish.md @@ -11,14 +11,12 @@ The reusable crypto crate remains independent of Hang and codec-specific publish Publishers use `Credential::produce()` and its `generation::Producer`; the producing/consuming split landed separately in #5313. -- After the dynamic-name design is approved, adapt mux, video, audio, - timeline, and catalog publishers to its chosen naming contract. - Applications keep semantic track names; the e2ee broadcast wrappers own +- Adapt mux, video, audio, timeline, and catalog publishers to the e2ee + broadcast wrappers (`create_track`, `reserve_track`). Every track these + publishers serve is declared in advance, so this does not wait on the + [dynamic names](/quest/m2/e2ee/dynamic-names.md) design (maintainer, + 2026-10-19). Applications keep semantic track names; the wrappers own their translation to physical names, as the epic specifies. - Derive the protected catalog name from its well-known logical role, then put media roles, codecs, quality, timelines, and custom-track mappings only inside the encrypted catalog. - Encrypt both Hang catalog representations and encrypt or suppress the MSF catalog. Compress protected catalog bodies before encryption and retain ordinary plaintext publication unchanged outside E2EE mode. - Cover every current Rust importer and capture path so a convenience API cannot silently recreate `.avc3`, `.opus`, timeline, or other semantic suffixes. - -## Required - -- [Dynamic names](/quest/m2/e2ee/dynamic-names.md) - the maintainer approves the naming design before implementation starts diff --git a/quest/m3/README.md b/quest/m3/README.md index 8e545ba22b1..00e5db6741f 100644 --- a/quest/m3/README.md +++ b/quest/m3/README.md @@ -66,6 +66,6 @@ m4's upstream waits in here and moved m2 work with no consumer. - [Paced replay](/quest/m3/archive-paced-replay.md) - an archive consumer pushes stored groups to live subscribers on one shared clock, so any live player plays it - [Encoder feedback](/quest/m3/stats-encoder-feedback.md) - a Rust encoder reads its viewers' feedback and adapts its bitrate -- [Interop runner withdraws before disconnecting](/quest/m3/interop-runner-approval.md) - condition: the maintainer approves posting and a released moq-tokio and @moq/net carry close() withdrawals +- [Interop runner withdraws before disconnecting](/quest/m3/interop-runner-approval.md) - condition: a released moq-tokio and @moq/net carry close() withdrawals; then the runner's moq.dev clients switch to close() - [Safari ships the WebKit 319818 fix](/quest/m3/webkit-319818.md) - the Safari release the gate admits - [Safari WebTransport](/quest/m3/safari-webtransport.md) - WebKit browsers return to WebTransport once WebKit 319818 ships fixed diff --git a/quest/m3/interop-runner-approval.md b/quest/m3/interop-runner-approval.md index 0296364f325..7b27f81424a 100644 --- a/quest/m3/interop-runner-approval.md +++ b/quest/m3/interop-runner-approval.md @@ -2,22 +2,27 @@ ## Goal -Condition: the maintainer approves changing moq-interop-runner -(englishm/moq-interop-runner, outside this repository), and a released -moq-tokio and `@moq/net` carry the session `close()` that withdraws this -session's announcements before disconnecting. Then post the one-line change: -a completed publish in the runner calls `close()` instead of aborting, so a -subsequent run can publish the same namespace without an already-published -error. +Condition: a released moq-tokio and `@moq/net` carry the session `close()` +that withdraws this session's announcements before disconnecting. Then the +moq.dev clients in englishm/moq-interop-runner (`builds/moq-dev-rs`, +`builds/moq-dev-js`) bump to that release and end each publishing session +with `close()` instead of aborting. -Check: ask the maintainer, or look for the approval on the runner's -repository, and read the moq-tokio and `@moq/net` changelogs for a release -with the withdrawing `close()`. Delete this quest once the change is posted. +Check: read the moq-tokio and `@moq/net` changelogs for a release with the +withdrawing `close()`. Delete this quest once the runner's moq.dev clients use that release's +`close()`. ## Plan -The runner found this in [#4209](https://github.com/moq-dev/moq/pull/4209). -Exercise successive runs against the same relay before posting. +The maintainer approved changing the runner on 2026-10-19. +[englishm/moq-interop-runner#167](https://github.com/englishm/moq-interop-runner/pull/167) +moved both clients to the latest releases (moq-tokio 0.19.28, `@moq/net` +0.4.4) and kept their teardown, because 0.19.28's `close()` does not withdraw +announcements and adds about 500 ms per session against a distant relay, +which pushed `announce-subscribe` past its 3 s budget. -Decided 2026-10-08: the graceful-close quest folds in here as one condition -quest, since the runner change is one line once both conditions hold. +The stale namespace that motivated this ([#4209](https://github.com/moq-dev/moq/pull/4209): +a publisher that aborts without PUBLISH_NAMESPACE_DONE blocks the next run's +publish) no longer reproduces against imquic or any other public relay as of +2026-10-19, so this is cleanup rather than a fix. Re-measure `close()`'s cost +against imquic before switching, and keep each test inside its budget.