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
1 change: 1 addition & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,7 @@ A bad shape costs a breaking change in every language, and the surface is huge.
- Never add `foo_with_x`, `foo_checked`, or a compatibility shim. Make the breaking change to `foo` instead.
- Let the type system make misuse unrepresentable
- A broadcast, track, or group name always means the same content. MoQ has no ETag-style invalidation, so a publisher that reuses a name for different content (such as restarting group numbers) is a bug; publish a new broadcast instead of working around it.
- Each publisher produces its own stream. With several publishers, the end subscriber decides how to subscribe to them (switch between, combine, or keep separate); never make independent publishers produce identical output so the relay can stitch them.
- Avoid callback parameters. Return a handle, an event, or a Producer/Consumer split.
- Avoid 4+ args; use a struct or object.
- Prefer nesting related API, configuration, and structured output fields under their shared role.
Expand Down
6 changes: 4 additions & 2 deletions quest/m0/broadcast-epoch/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,8 +33,9 @@ clients that retain objects across broadcasts. The negotiated
[IETF extension](/quest/m1/ietf-epochs.md) follows in m1, independently of
this release gate; seamless JS handover stays in m1 too.

Non-goals: pooling, which needs nothing here; a redundant pair shares an
explicit epoch through `moq --epoch`.
Non-goals: pooling, which needs nothing here. A redundant ingest pair runs on
distinct epochs (decided 2026-10-19), so only replicas of one publisher's
bytes share one.
Also out of scope: trusting the publisher's clock (a far-future epoch wins
until its route goes away).

Expand Down Expand Up @@ -124,6 +125,7 @@ End+Start. The child quests own their focused regressions.
## Required

- [Catalog references](/quest/m0/broadcast-epoch/catalog-references.md) - announcement followers restart replaced siblings; other readers retain pins, with optional epochs and legacy best effort
- [Distinct importer epochs](/quest/m0/broadcast-epoch/distinct-importer-epochs.md) - `moq --epoch` never ships, a redundant importer pair fails over as a marked restart, and the shared-epoch alignment code is reverted

## Related

Expand Down
87 changes: 87 additions & 0 deletions quest/m0/broadcast-epoch/distinct-importer-epochs.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
# [L] Redundant importers run on distinct epochs

## Goal

Two importers fed one stream and publishing one path, a redundant ingest
pair, each mint their own epoch, and every consumer follows a failover
between them as a marked restart. `moq --epoch` is gone, so only replicas of
Comment thread
kixelated marked this conversation as resolved.
Resolved
one publisher's bytes (one process announced through several relays or CDNs)
share an epoch, and same-epoch identity holds by construction. The importer
and mux machinery that existed only so independent importers agree is
reverted.

Today two `moq import ts` sharing an `--epoch` number groups per process, so
a relay resumes a subscription mid-group on other media and `moq export ts`
exits on a rewind (#4354).

Non-goal: hitless failover between importers. That stays downstream, as
2022-7 legs of one broadcast ([Redundant TS exports](/quest/m2/ts-hitless.md)),
or upstream, by merging legs before a single importer.

## Plan

Decided 2026-10-19 by the maintainer, settling the redundancy-model
decision quest for switchover and superseding the 2026-10-13 active-active
plan (the deleted `epoch-anchor` and `hop-aligned-import` quests) and
#5895's one-second group grid: independently fed importers
cannot publish identical tracks. Each sees its own loss, start point, and
history, and once loss or reordering reaches one, "same epoch, same content"
is false and a mid-group resume splices two streams. Every alignment rule so
far (#5625's epoch-derived clock and eras, #5894's catalog-clock grid cuts
and windows, #5895's grid numbering) added cost and still left audio after
loss, the catalog tracks, and the timeline divergent. Considered instead:
numbering groups by their start time (DASH `$Time$` style), which fixes audio
under loss but keeps every other alignment rule.

- Remove `moq --epoch` and its plumbing: `epoch_refusal`, the shared-epoch
placement in `rs/moq-cli/src/publish.rs` (`timebase`), and the `--epoch`
text in `doc/bin/cli.md`, `doc/concept/moq-lite.md`, and
`doc/bin/relay/cluster.md`. It never shipped (absent from `release`), so no
MIGRATE entry. Every `moq` run mints its own epoch. Route-level epochs in
moq-net and the bindings stay: an application that forwards or replicates
one publisher's bytes still announces that publisher's epoch.
- Failover uses what exists: the newest epoch wins new requests, losing it
makes a still-live older one win as a new broadcast, players follow the
announce `Restart`, and `export ts --stitch` follows a replacement as a
program switch. Unchanged (maintainer, over staying on the current instance
until it ends): `--stitch` follows a newer epoch at once, so starting or
restarting the backup importer is a marked seam for every stitching export
even when nothing failed.
- Audit the importers and `moq-mux`: revert every behavior that exists only
so same-epoch importers agree, even a harmless one, unless a single
importer is better or simpler with it, and justify each kept item in the
PR (maintainer, over reverting only what has a user-visible cost).
Candidates: #5625's clock placement and per-value eras from the epoch (the
13.25 h wall-mapping bound and the half-period failure cases go with
them), #5894's catalog-clock grid fallback cuts and the two-second
`randomAccess` and `muxRate` windows of the m2ts section, history-free
rules that replaced simpler history-based ones (such as the removed
passthrough clamp), and catalog fields derived from the epoch instead of
the importer's history. Update `drafts/draft-lcurley-moq-mpegts.md` for
every wire-visible reversal (the m2ts section is in no published draft),
and drop the e2ee draft's "explicit or shared epoch" wording if nothing
can hand a core one anymore.
- One quest and one PR (maintainer, over splitting the removal from the
audit).

Tests: #4354's 1+1 setup on distinct epochs, on lite-07: one relay, two
`moq import ts` fed one stream (and again with `--passthrough`), two
`moq export ts --stitch`. Stopping the serving importer, and starting a
backup, each produce one marked program switch and no exit, and a restarted
importer wins again as the newest. Run it on the bufferbloat harness and
report the gap a viewer sees at each switch. Tests that only proved same-epoch
agreement go with the code they covered.

Public API: removes `moq --epoch`, plus whatever `moq-mux` surface the audit
reverts; report each item. Wire: the m2ts catalog section changes as the
audit decides, in no published draft.

## Closes

- [#4354](https://github.com/moq-dev/moq/issues/4354) - close this issue when the quest finishes

## Related

- [Redundant ingest guide](/quest/m1/redundant-ingest-guide.md) - documents running a redundant pair over multiple routes, for any publisher
- [Redundant TS exports](/quest/m2/ts-hitless.md) - hitless legs of one broadcast, downstream of the importer
- [E2EE](/quest/m2/e2ee/README.md) - an encrypting publisher never takes an epoch it did not mint
12 changes: 6 additions & 6 deletions quest/m1/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,11 +19,11 @@ release, with clustering stability and the in-tree QUIC stack first.
expansion in m1. Keep their correctness, interoperability, memory, and
performance evidence with them.
- Defer P2P, watch-worker planning and implementation, AMD Vulkan encode and
Intel VA-API/Vulkan import, QoS lag and prefix stats, and active-active
same-epoch importers to m2 with their prerequisites. Their possible API
breaks do not make them prerequisites of this cut. Existing playback and
A/V clock validation remain here. Same-epoch importers require the epoch
anchor and raw TS epoch cuts before claiming redundant-import support.
Intel VA-API/Vulkan import, and QoS lag and prefix stats to m2 with their
prerequisites. Their possible API breaks do not make them prerequisites of
this cut. Existing playback and A/V clock validation remain here.
Same-epoch importers were dropped (maintainer, 2026-10-19): a redundant
ingest pair runs on [distinct epochs](/quest/m0/broadcast-epoch/distinct-importer-epochs.md).
Comment thread
kixelated marked this conversation as resolved.
Resolved
- Finalized lite-07 is preferred by first-party Rust and JS clients, with
older-version negotiation fallback. Servers accept it by default. Never
reuse a published identifier for an incompatible wire change; deferred
Expand Down Expand Up @@ -85,6 +85,7 @@ lands before the cut.
- [Announcement takeover](/quest/m1/announce-takeover.md) - a new independent route explicitly continues instances served through its predecessor, with shared Rust/JS semantics and lite-07 wire
- [IETF takeover](/quest/m1/ietf-takeover.md) - carry the shared takeover contract through the negotiated IETF epoch extension
- [Identity and recovery guide](/quest/m1/identity-guide.md) - explain pinned catalogs, lazy jobs, takeover, restart and version compatibility
- [Redundant ingest guide](/quest/m1/redundant-ingest-guide.md) - a setup page on redundant ingest over multiple routes, for any publisher
- [Generated C bindings](/quest/m1/c/README.md) - C generated from moq-ffi ships as `moq-c` 0.8.0 and replaces the hand-written libmoq
- [moq-ffi reports why a first dial fails](/quest/m1/ffi-first-dial-failure.md) - OBS names the reason while the first dial retries, as moq-c already can
- [Typed refusal reason](/quest/m1/refusal-reason.md) - an auth server's 403 names the reason (including `expired`) and the root and tier, so the relay's session outcomes count and attribute refusals
Expand All @@ -105,7 +106,6 @@ lands before the cut.
- [Bufferbloat harness](/quest/m1/bufferbloat.md) - acceptance and performance checks impair paths with a rate limit and a deep queue, not random loss
- [Random-loss audit](/quest/m1/random-loss-audit.md) - every decision random-loss gates drove is kept, reworked, or reverted on shaped paths
- [Timed-out requests clean up](/quest/m1/legacy-request-timeout-cleanup.md) - on drafts 14-16, Rust and JS send PUBLISH_NAMESPACE_DONE or UNSUBSCRIBE_NAMESPACE for a timed-out request before its local reset
- [Redundancy model](/quest/m1/redundancy-model.md) - decide between same-epoch active-active publishers and epoch switchover before the m2 redundancy work builds on either
- [TS fidelity and recovery](/quest/m1/ts-reliability/README.md) - both modes have explicit profiles, automated validation, loss tests, and a dedicated guide
- [Resume reorder](/quest/m1/resume-reorder.md) - a group whose stream header arrives after its successor's still resumes on failover; only a dropped or long-gone group fails
- [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
Expand Down
1 change: 0 additions & 1 deletion quest/m1/cluster-routing/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -130,4 +130,3 @@ setup after the capabilities land.
- [Routing guide](/quest/m1/routing-guide.md) - concept page and federation setup; P2P extends it in m2
- [Route wakes](/quest/m2/route-wakes.md) - local work follows affected fronts rather than the whole covered table
- [Link quality](/quest/m2/link-quality.md) - optional measured link cost, distinct from delivery-health failover
- [Same-epoch importers](/quest/m2/hop-aligned-import.md) - independent origins serving the same explicit epoch
2 changes: 1 addition & 1 deletion quest/m1/cluster-routing/routes.md
Original file line number Diff line number Diff line change
Expand Up @@ -236,7 +236,7 @@ The handoff contract below, decided 2026-10-16, settles claim freshness:
that identity, and every later hop follows its own route to it, so
forwarding needs a route but not the claim.
- Reselecting the origin at every hop loops although each origin's routes are
loop-free (RFC 8966 s2.7): a ring of same-epoch importers whose relays
loop-free (RFC 8966 s2.7): a ring of same-epoch origins whose relays
prioritize different links, and nested wildcards where a relay has not
heard the specific claim, both cycle past requester exclusion; joining
another relay's subscription by path or epoch deadlocks; and without an
Expand Down
43 changes: 0 additions & 43 deletions quest/m1/redundancy-model.md

This file was deleted.

41 changes: 41 additions & 0 deletions quest/m1/redundant-ingest-guide.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
# [S] Redundant ingest guide

## Goal

A setup page, `doc/setup/redundancy.md` next to Production in the Setup
sidebar, tells an operator how to make ingest redundant with multiple
routes, for any publisher rather than TS alone. Nothing says today that two
publishers announcing one path is the supported way, so operators reach for
a shared epoch instead.

It covers:

- Two publishers of one path, each minting its own epoch: the relay serves
the newest, and losing it falls back to a still-live older one as a new
broadcast.
- What a switch looks like: players follow the announce `Restart`,
`moq export ts --stitch` follows as a program switch, and other exports
end. Starting a backup is a switch too.
- Each publisher on its own path instead, so the end subscriber subscribes
to both and decides whether to switch between, combine, or keep them
separate (maintainer: each publisher produces its own stream, and the
subscriber chooses).
- One publisher announced through several relays or CDNs under its own
epoch, which resumes without a seam when a path fails.
- Where hitless importer protection lives instead: 2022-7 legs of one
broadcast downstream, or merging legs before a single importer.

## Plan

Decided 2026-10-19 by the maintainer: a general page, not a TS section,
since multiple routes are the non-obvious part. Link it from the relay
cluster page and the `moq` publisher-runs section of `doc/bin/cli.md`.

## Required

- [Redundant importers run on distinct epochs](/quest/m0/broadcast-epoch/distinct-importer-epochs.md) - `--epoch` is removed and the failover behavior the page describes is tested

## Related

- [Identity and recovery guide](/quest/m1/identity-guide.md) - restart and takeover semantics the page links to
- [Routing guide](/quest/m1/routing-guide.md) - route ranking and federation
1 change: 0 additions & 1 deletion quest/m1/ts-reliability/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -108,7 +108,6 @@ remain with their current quests.

## Related

- [Epoch anchor](/quest/m2/epoch-anchor.md) - shared identity across importers requires one source coordinate per epoch, derived from the epoch
- [TS over RTP legs](/quest/m2/ts-rtp-egress.md) - TS identity alone is not ST 2022-7, which also needs matching RTP headers
- [TS health counters](/quest/m2/ts-health-stats.md) - ingress and egress evidence need distinct monitoring points
- [MSFTS mapping](/quest/m3/msfts-convergence.md) - document the exact equivalence and differences between the carriage modes
Expand Down
6 changes: 2 additions & 4 deletions quest/m1/ts-reliability/pes-import.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,14 +29,12 @@ round-trip test first.
under half a wrap) so a start near the wrap does not split them, shifted onto the catalog clock by the timebase
offset that shifts the PTS. A PES waits for the next PCR, within the
existing `Retained` bound; it never spans a PCR discontinuity. The value
depends only on the input bytes and the timebase offset, so it adds no
disagreement of its own; same-epoch importers agree once the
[epoch anchor](/quest/m2/epoch-anchor.md) fixes that offset. A program
depends only on the input bytes and the timebase offset. A program
with no PCR PID cannot place its PES, so its private PES streams are
refused. The timebase offset is anchored only by a PTS today, so a PES
also waits for that anchor within the same bound; a program whose PES
never carry a PTS (data only) is refused and tested, unless the PCR can
anchor the timebase without breaking same-epoch agreement.
anchor the timebase.
Comment thread
kixelated marked this conversation as resolved.
Resolved
- **Trailing PES.** A PES that starts after its timebase's last PCR (end of
input, or a PCR discontinuity before the next PCR) has no PCR on the far
side. Place it by extrapolating from that timebase's last two PCRs, which
Expand Down
2 changes: 0 additions & 2 deletions quest/m2/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,8 +25,6 @@ ranked just below deterministic TS legs, which it requires.

- [Release execution](/quest/m2/release/README.md) - publication, installed-artifact proof, cleanup, and downstream adoption after m1
- [P2P](/quest/m2/p2p/README.md) - application-selected peer sessions use shared priorities, routing, and same-epoch handover
- [Epoch anchor](/quest/m2/epoch-anchor.md) - same-epoch importers each derive the catalog clock and timestamp era from the epoch and stay live, so they agree across a 33-bit wrap, a forward clock break, and a restart
- [Same-epoch importers](/quest/m2/hop-aligned-import.md) - importers sharing one `--epoch` and fed one stream publish identical groups and timestamps, so failover between a redundant pair survives
- [Hard-fork the binding generator](/quest/m2/uniffi-fork.md) - one moq-dev repo holds the chosen generator's core and every language backend, released under one tag and one pin
- [Benchmark trend site](/quest/m2/bench-site.md) - a GitHub Pages site charts the binding, Rust, and JS nightly benchmarks over time
- [Link the benchmark trends](/quest/m2/bench-site-doc.md) - the docs point language choosers at the trend site
Expand Down
Loading