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
2 changes: 1 addition & 1 deletion quest/m1/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion quest/m1/archive/history-floor.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
91 changes: 65 additions & 26 deletions quest/m1/hls-failure-signal.md
Original file line number Diff line number Diff line change
@@ -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.
Comment thread
kixelated marked this conversation as resolved.
Resolved
- 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.
Comment thread
kixelated marked this conversation as resolved.
Resolved
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<String>`, becoming `Result<Option<String>>`) and `Rendition::playlist`
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
(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

Expand Down
3 changes: 0 additions & 3 deletions quest/m1/quic/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
60 changes: 0 additions & 60 deletions quest/m1/quic/group-reset.md

This file was deleted.

2 changes: 1 addition & 1 deletion quest/m1/sink-restart-follow.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions quest/m2/e2ee/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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
Expand Down
10 changes: 7 additions & 3 deletions quest/m2/e2ee/dynamic-names.md
Original file line number Diff line number Diff line change
Expand Up @@ -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):
Expand All @@ -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
Expand Down
12 changes: 5 additions & 7 deletions quest/m2/e2ee/rust-publish.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion quest/m3/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
33 changes: 19 additions & 14 deletions quest/m3/interop-runner-approval.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Loading