diff --git a/AGENTS.md b/AGENTS.md index 2bb81c771f0..363b71dae23 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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. diff --git a/quest/m0/broadcast-epoch/README.md b/quest/m0/broadcast-epoch/README.md index 93883bdba61..fee88e7bfa7 100644 --- a/quest/m0/broadcast-epoch/README.md +++ b/quest/m0/broadcast-epoch/README.md @@ -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). @@ -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 diff --git a/quest/m0/broadcast-epoch/distinct-importer-epochs.md b/quest/m0/broadcast-epoch/distinct-importer-epochs.md new file mode 100644 index 00000000000..4885bb8189c --- /dev/null +++ b/quest/m0/broadcast-epoch/distinct-importer-epochs.md @@ -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 +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 diff --git a/quest/m1/README.md b/quest/m1/README.md index e7b219fab96..a0085108875 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -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). - 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 @@ -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 @@ -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 diff --git a/quest/m1/cluster-routing/README.md b/quest/m1/cluster-routing/README.md index 425a0e5b128..03c05c8cbf1 100644 --- a/quest/m1/cluster-routing/README.md +++ b/quest/m1/cluster-routing/README.md @@ -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 diff --git a/quest/m1/cluster-routing/routes.md b/quest/m1/cluster-routing/routes.md index 99ff6a1aa65..e822cc63ea9 100644 --- a/quest/m1/cluster-routing/routes.md +++ b/quest/m1/cluster-routing/routes.md @@ -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 diff --git a/quest/m1/redundancy-model.md b/quest/m1/redundancy-model.md deleted file mode 100644 index 6f3293c7377..00000000000 --- a/quest/m1/redundancy-model.md +++ /dev/null @@ -1,43 +0,0 @@ -# [S] Decide how a redundant publisher pair fails over - -## Goal - -The maintainer picks how a broadcast survives losing one of two redundant -publishers, and the planned TS redundancy work is kept, rewritten, or deleted -to match. The two candidates: - -- **Active-active:** both publishers share one epoch and derive identical - groups, timestamps, and catalogs from the epoch and the source, so a relay - resumes a subscription across them mid-group. This is what the m2 chains - below build. -- **Switchover:** each publisher mints its own epoch, the newest route wins - the path, and viewers follow the new epoch as a fresh instance with a - bounded gap, on the routing and takeover work already in m1. - -## Plan - -Reopened 2026-10-19 (maintainer): active-active was decided on 2026-10-13 -while planning #5412's leftovers. It is now challenged on whether the feature -is worth supporting at all, not only on how to build it. - -Gather the facts, then ask the maintainer with a recommendation: - -- What each costs: the code and invariants active-active needs (epoch-derived - clocks and eras, deterministic group cuts, identical catalogs, and their - tests) versus what switchover adds on top of - [announcement takeover](/quest/m1/announce-takeover.md) and - [cluster routing](/quest/m1/cluster-routing/README.md). -- What a viewer sees on failover under each, measured on the bufferbloat - harness: gap length, and whether playback recovers without a reload. -- Which consumers need hitless output (ST 2022-7 style merging of identical - legs) that switchover cannot give, and whether one exists today. -- What breaks if the source feeds the two publishers differently (a forked - encoder, a dropped packet on one side), since active-active silently - assumes identical input. - -Delete or rewrite every quest that depends on this one once it is decided, -and update the identity guide if the contract changes. - -## Related - -- [Feature review](/quest/m2/release/feature-review.md) - re-judges the rest of the TS work before the cut diff --git a/quest/m1/redundant-ingest-guide.md b/quest/m1/redundant-ingest-guide.md new file mode 100644 index 00000000000..22a0ec11318 --- /dev/null +++ b/quest/m1/redundant-ingest-guide.md @@ -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 diff --git a/quest/m1/ts-reliability/README.md b/quest/m1/ts-reliability/README.md index 2300c371410..508d8a836f0 100644 --- a/quest/m1/ts-reliability/README.md +++ b/quest/m1/ts-reliability/README.md @@ -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 diff --git a/quest/m1/ts-reliability/pes-import.md b/quest/m1/ts-reliability/pes-import.md index 0f9128f9f68..e4dafade4a5 100644 --- a/quest/m1/ts-reliability/pes-import.md +++ b/quest/m1/ts-reliability/pes-import.md @@ -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. - **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 diff --git a/quest/m2/README.md b/quest/m2/README.md index ca976c6d75b..49f6d7a22d1 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -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 diff --git a/quest/m2/e2ee/README.md b/quest/m2/e2ee/README.md index aa27673602f..1df2f6637e4 100644 --- a/quest/m2/e2ee/README.md +++ b/quest/m2/e2ee/README.md @@ -20,7 +20,7 @@ The contract is [draft-lcurley-moq-e2ee](/drafts/draft-lcurley-moq-e2ee.md), pro ### Epoch and identity - Every publisher instance mints an epoch, a UUIDv7 in lowercase text, and publishes at `` with the epoch on its route, where `` derives from the credential and the semantic broadcast name without the epoch. The epoch is an input to every HKDF derivation, so a restart, takeover, or explicit group sequence cannot repeat a nonce under a key: nothing is persisted across instances and no generation counter is redistributed. The epoch is the shared [`Epoch`](/doc/concept/moq-lite.md#publisher-epochs) primitive. Subscribers resolve `` and take the epoch from its route, where the newest wins; on a wire without route epochs the application supplies it. -- An encrypting publisher refuses a shared or explicit epoch (maintainer, 2026-10-08). A redundant pair under one `moq --epoch`, or the same-epoch importers of [Same-epoch importers](/quest/m2/hop-aligned-import.md), would derive the same keys and repeat every nonce. Both cores produce only under an epoch they minted themselves; consuming still binds a discovered one. Rejected: a per-instance salt. State the rule in the draft's epoch section. +- An encrypting publisher refuses a shared or explicit epoch (maintainer, 2026-10-08). Two producers handed one epoch would derive the same keys and repeat every nonce. Both cores produce only under an epoch they minted themselves; consuming still binds a discovered one. Rejected: a per-instance salt. State the rule in the draft's epoch section. - The epoch is untrusted and unauthenticated. A wrong epoch fails authentication and a withheld one denies service; neither can make a nonce repeat, because only the publisher instance chooses what it encrypts under. This is the same trust a cache needs to serve the right instance. Plaintext broadcasts adopt the same epoch by default through [broadcast epochs](/quest/m0/broadcast-epoch/README.md). - Nothing in the path says the bytes are encrypted. The format after decryption (`meeting.hang`) is inside the opaque name; a plaintext player, exporter, or matcher that opens a protected broadcast finds no catalog it can read and fails with its usual typed refusal, the same as for any format it does not support. - One 32-byte secret authorizes the whole broadcast; HKDF-SHA-256 derives separate AES-128-GCM keys for each physical track and for grouped-frame versus datagram domains. A grouped frame uses the 96-bit nonce `uint64_be(group) || uint32_be(frame)`; a datagram uses its sequence with frame zero under the datagram domain. Empty AAD: every immutable end-to-end field is in the HKDF info or the nonce. @@ -76,5 +76,4 @@ Decided with the maintainer on 2026-10-17: physical names are a one-way hash, so ## Related - [archive](/quest/m1/archive/README.md) - protected broadcasts are deliberately outside recording and replay formats -- [Same-epoch importers](/quest/m2/hop-aligned-import.md) - the shared-epoch redundancy an encrypting publisher refuses - [Wrapper seam over moq-net](/quest/m2/net-wrap-trait.md) - whether a moq-net trait replaces the bridge the e2ee mux path uses diff --git a/quest/m2/e2ee/cli.md b/quest/m2/e2ee/cli.md index 44b2de150b3..b0a07472d5e 100644 --- a/quest/m2/e2ee/cli.md +++ b/quest/m2/e2ee/cli.md @@ -11,9 +11,9 @@ Existing plaintext commands remain the default; an explicit application credenti - Integrate the Rust E2EE layer into `moq-cli` publication and playback before semantic mux output and after protected track input. Keep codec, capture, playback, and synchronization logic outside the crypto layer. - Accept the credential through a dedicated file descriptor, otherwise-unused stdin, or a permission-checked file (`0600` on Unix), never a command argument or environment variable. Redact errors and tracing, zeroize owned secret bytes, and document shell-safe invocation. - Inject opaque physical names into mux, video, audio, timeline, and catalog construction. Take the semantic broadcast name from the user and publish under its opaque derivation; mint a UUIDv7 epoch per publisher run and discover the newest one under the opaque prefix when playing; derive and decrypt the protected catalog before existing selection, and suppress every plaintext Hang or MSF catalog representation. -- Refuse `--epoch` together with a credential, and any other path that hands an encrypting publisher an epoch it did not mint, before connecting (maintainer, 2026-10-08): a shared epoch repeats AES-GCM nonces. +- Refuse any path that hands an encrypting publisher an epoch it did not mint, before connecting (maintainer, 2026-10-08): a shared epoch repeats AES-GCM nonces. `moq --epoch` is removed by [distinct importer epochs](/quest/m0/broadcast-epoch/distinct-importer-epochs.md). - Refuse `--stats` and `--echo` together with a credential: they would publish rendition IDs and per-track counters in plaintext beside the protected broadcast. This quest owns the refusal (decided 2026-10-08), since the stats quests have no encrypted mode to refuse until this credential exists. -- Cover native audio/video publication and playback, late subscription, a restarted publisher under a new epoch, `--epoch` with a credential refused, `--stats` or `--echo` with a credential refused, clean authentication errors, and both lite and IETF transports. +- Cover native audio/video publication and playback, late subscription, a restarted publisher under a new epoch, `--stats` or `--echo` with a credential refused, clean authentication errors, and both lite and IETF transports. ## Required diff --git a/quest/m2/epoch-anchor.md b/quest/m2/epoch-anchor.md deleted file mode 100644 index 938d8a915ae..00000000000 --- a/quest/m2/epoch-anchor.md +++ /dev/null @@ -1,129 +0,0 @@ -# [M] Same-epoch importers derive one coordinate from the epoch - -## Goal - -Every importer publishing one path under one explicit `--epoch`, fed one -stream, derives its catalog root clock and each timestamp's era from the -epoch and the source alone. They all stay live (active-active) and publish -identical timestamps and catalogs whenever each started, including on -opposite sides of a 33-bit TS wrap or a flagged forward break, and after a -restart under the same epoch. No importer reads another's broadcast, waits -on one, or exits because one exists. - -Today each importer places its clock at its own first frame's arrival, or -shifts onto a clock already in use by `clock.now()` minus its first -timestamp (#5082), and each TS importer unwraps from its own first PCR or -PTS. Two importers agree only if they started at the same packet. - -## Plan - -Decided 2026-10-13 by the maintainer: importers sharing an explicit epoch -derive the same coordinate without coordination, and none is first. This -supersedes the same day's #5412 plan, where the epoch's first importer fixed -the clock and era and every later one read the live catalog and adopted -them: adoption needs a first importer, and a co-start (routine, since both -importers of a pair restart together) has none that either can name. -Rejected with it: a co-started importer that watches its peer's announcement -and exits, an external leader or anchor flag, and co-start as an unsupported -precondition. - -- The epoch is a UUIDv7, so it carries a millisecond wall time that every - importer shares exactly. Each importer reads only its own input, the epoch, - and its own wall clock, and never the relay or the cluster. -- The era comes from the epoch (maintainer, superseding #5412's era from the - incumbent's published timeline and the join-time verification against its - objects): for each timestamp base (in TS the PCR, and each stream's PTS and - DTS), the whole number of periods (2^33 at 90 kHz for TS) that lands the - value nearest its arrival on the epoch's clock, as the importer's wall clock - reads it. The source's offset from the wall clock is the same for every - importer, so they agree unless their delivery and host-clock skew straddles - a half-period boundary of that offset. Add the periods in - source ticks before converting to microseconds, since a period is not a - whole microsecond count. -- Recommended: derive every value's era this way, not only each base's first, - so no importer state enters the coordinate. A restart, a base a PMT - revision adds after a wrap, and a sparse base (verbatim subtitles or - teletext) then need no special case, and `PtsUnwrap`'s history goes away. - The cost is that media time stays within half a period of the epoch - clock's reading. A flagged forward break that would carry it further reads - as a step back, which stays fatal on every importer alike, as does a file - read faster than real time for half a period. The raw importer's clamp after a small flagged jump - (`(last + step).max(self.written)` in `passthrough.rs`) depends on history; - remove it. -- Two known failure cases, documented rather than guarded (maintainer, - 2026-10-13, over refusing to start inside a guard band of the halfway - point): importers that start together split onto adjacent eras when their - skew straddles the halfway point, with odds of about skew over the period - (near 1e-7 at 10 ms against TS's 26.5 h); and the gap between the source - clock and wall time drifts by seconds a day, so over weeks it can drift - onto the halfway point mid-run, where even a single importer reads a - rewind and fails. -- The catalog's wall mapping derives from the epoch too (maintainer): media - time maps to wall through the epoch's wall time plus the deterministic era, - so every importer writes the same root `clock`. Rejected: no wall mapping - under a shared epoch, and quantizing each importer's measured offset, whose - rounding boundary splits importers far more often than a period's. The - accuracy is bounded by how well the epoch's wall time matches the source: - the mapping is off by the source clock's reading at the epoch's wall time, - modulo the period, which for an arbitrary TS program clock is anywhere - within half a period (13.25 h). Document that with `--epoch`. The exact rule - is open; recommended: PTS zero sits one period before the epoch's wall time - (`E - period`, deterministically rounded to a whole microsecond), and the - era is chosen against that clock's reading. Then timestamps never land - below zero for an importer whose clock reads after the epoch's wall time - minus half a period, and a source whose clock reads zero at the epoch's - wall time (a stream started when the epoch was minted) maps exactly and - sits half a period from the boundary. A format whose timestamps never wrap - has no era: PTS zero is the epoch's wall time and its timestamps stay - verbatim. Install it through `Timebase::place`, which keeps whole - microseconds; nothing reads a catalog back, so the millisecond flooring in - `Clock::wall_clock` never enters it. -- Every catalog field an importer derives from its history rather than the - content at hand derives from the epoch and the content instead (maintainer, - superseding #5412's adoption from the live catalog). TS passthrough's M2ts - section already does; audit the other importers for more. -- A restart under the same epoch re-derives the same coordinate, including - after a total outage, so the epoch keeps naming one timeline and resuming - across the outage is a gap, not a stitch (maintainer, reversing #5412's - "an explicit epoch names one continuous run; mint a successor after a total - outage"). Nothing persists beyond the live route. -- A rewind stays fatal (#4543), so both importers of a pair exit and restart - under a successor epoch. An importer never rolls to a successor in-process - (maintainer: "Never"). Open: how a supervisor obtains the successor so both - importers of a pair land on the same one without coordination. Proposed: - derive it from the old epoch and the last frame's catalog time. Its wall - time then fixes the successor's coordinate like any explicit epoch's. -- Same stream stays the operator's precondition, unchecked. Known gap, not - planned now (maintainer): nothing refuses two routes with the same epoch - but different content, and failover resumes mid-group across them - (`rs/moq-net/src/model/resume.rs`), so a misfed pair splices two streams. -- The mapping drifts from UTC at the source's clock error for the epoch's - life. Nothing re-measures it. - -Tests, on mocked time where possible: for each importer that takes -`--epoch`, two instances started at different source offsets publish -identical catalogs and timestamps; the same with the second started after a -33-bit wrap the first crossed, at a wrap with its streams' first values on -opposite sides of it, after flagged forward breaks, and with different -delivery skew into each; a stream a PMT revision adds after a wrap; forward -breaks carrying media time past half a period from the epoch clock fail on -both alike; a co-start across two clustered relays leaves both live and -byte-identical; a restart under the same epoch, alone and after both -stopped, rejoins identically; the derived root `clock` matches the -recommended rule, including a source that reads zero at the epoch's wall -time. - -Public API: no new items. Under a shared epoch the root `clock` and the -timestamps move from arrival to the epoch's derivation; the `--epoch` docs -state the accuracy bound. `--epoch` needs no subscribe right (#5412's -breaking grant for publish-only tokens is dropped). Wire: none. - - -## Required - -- [Redundancy model](/quest/m1/redundancy-model.md) - whether a redundant pair stays active-active or fails over by epoch switchover - -## Related - -- [Same-epoch importers](/quest/m2/hop-aligned-import.md) - group sequences and the end-to-end pair on this coordinate -- [Broadcast epochs](/quest/m0/broadcast-epoch/README.md) - same-epoch routes resume each other's subscriptions diff --git a/quest/m2/hop-aligned-import.md b/quest/m2/hop-aligned-import.md deleted file mode 100644 index 7b68bb78af2..00000000000 --- a/quest/m2/hop-aligned-import.md +++ /dev/null @@ -1,84 +0,0 @@ -# [M] Same-epoch importers publish identical tracks - -## Goal - -Two importers publishing one path, such as a redundant pair sharing an -explicit `--epoch`, and fed the same encoded stream publish identical tracks, -so a relay can fail over between them. Today two `moq import ts` fed one -forked stream break that contract: each numbers its groups from its own -counter, so after a failover `export ts` sees a timestamp rewind and exits -(#4354). - -## Plan - -Decided: every publisher of one path and epoch MUST publish the same -broadcasts and tracks, since routes with the same epoch resume each other's -subscriptions. A redundant pair is keyed by a shared explicit epoch (decided -2026-10-03: `--hop` no longer exists to key it). Every importer that -`moq import --epoch` accepts meets the contract when fed one encoded stream: -ts with one program, ts `--passthrough` (a whole multiplex included), fmp4, -flv, and the HLS pull that reuses them. RTMP and SRT imports, the WHIP -listener, and `ts --program all` are out: they mint an epoch per ingest -connection (#4962), so two of them never share one. Publishers whose -timestamps or bytes come from the instance (avc3, capture, `rtc --connect`, -archive, and transcode) refuse a shared epoch. - -Decided 2026-10-13 by the maintainer: every importer of an epoch stays live -and derives one coordinate from the epoch and its source alone -([Epoch anchor](/quest/m2/epoch-anchor.md)), superseding the same day's plan -where later importers adopted the first one's. This quest numbers groups on -that coordinate and proves the pair end to end. A raw PTS or PCR value alone -does not supply it, and arrival time chooses only the era. Considered -instead: one importer per epoch with redundancy only downstream, which stays -the supported 1+1 until this lands, and a contract narrowed to what one input -proves, which fails at the first failover across a timestamp wrap. - -- A group's sequence derives from its first frame's time on the epoch - timeline (the keyframe in the demultiplexed lane, the group's first object - in passthrough), not a per-process counter, so two importers number the - same group alike wherever each started. A source may start consecutive - groups at one timestamp (`container::Producer` accepts a keyframe at the - previous group's start), which time alone cannot number without a - history-derived counter: settle a tie-breaker the source carries, or - refuse equal starts under a shared epoch, and cover it in the pair test. -- Frame timestamps derive from the input and the epoch's coordinate alone, - never from `clock.now()` (2026-10-06 audit), and importers refuse a rewind. -- The catalog's root `clock` is the epoch's, never an importer's arrival - (2026-10-05 audit; narrowing the contract to exclude the catalog clock was - rejected). Every other catalog field an importer derives from its history - derives from the epoch and the content instead, never from the live - catalog. -- The tracks an importer generates are tracks too: the catalog tracks - (hang, compressed, MSF) and `*.timeline`. Today catalog groups are - numbered locally (`Outputs::emit`), the MSF frame is stamped with - `Timestamp::now()`, and timeline records start at zero, so an importer - started later would reuse earlier group or record numbers for newer bytes. - Their numbering and timestamps come from the epoch timeline and the - content, never the instance or the live track. -- Docs (the `--epoch` paragraph in `doc/bin/cli.md`, the `--epoch` doc - comment) state the contract: one encoded stream fed to each publisher, no - access to the live broadcast needed, and a wall mapping only as accurate as - the epoch's wall time matches the source. - -Tests: per importer, two instances started at different offsets into one -input, including the later one starting after a timestamp wrap the earlier -crossed, publish identical catalogs, group sequences, and timestamps, on -the generated catalog and timeline tracks too, starting after earlier -catalog updates and timeline records. End to end: the issues' 1+1 setup (one -relay, two `import ts` sharing one `--epoch`, two `export ts`) survives the -second importer starting, before and after a wrap, and either importer -stopping and restarting; repeat it with `--passthrough`. - -## Closes - -- [#4354](https://github.com/moq-dev/moq/issues/4354) - close this issue when the quest finishes - -## Required - -- [Epoch anchor](/quest/m2/epoch-anchor.md) - every importer derives one catalog clock and timestamp era from the epoch - -## Related - -- [Broadcast epochs](/quest/m0/broadcast-epoch/README.md) - a redundant pair shares one epoch -- [E2EE](/quest/m2/e2ee/README.md) - an encrypting publisher refuses a shared epoch, so a redundant pair is plaintext only -- [Deterministic TS legs](/quest/m2/ts-hitless.md) - what two exports of the pair render from the common coordinate diff --git a/quest/m2/release/feature-review.md b/quest/m2/release/feature-review.md index 7bbc1fbd178..c52b5d3005e 100644 --- a/quest/m2/release/feature-review.md +++ b/quest/m2/release/feature-review.md @@ -30,8 +30,9 @@ ship as is. The first run must cover the MPEG-TS work (decided 2026-10-19 instead of a separate TS audit): everything since the 2026-10-11 TS audit, judged against the contracts in [TS fidelity and recovery](/quest/m1/ts-reliability/README.md). -Question each TS capability's premise the way the [redundancy -model](/quest/m1/redundancy-model.md) questions active-active publishers. +Question each TS capability's premise the way [distinct importer +epochs](/quest/m0/broadcast-epoch/distinct-importer-epochs.md) dropped +active-active publishers. ## Required diff --git a/quest/m2/ts-hitless.md b/quest/m2/ts-hitless.md index 48fa7da3099..0371fe5d4e8 100644 --- a/quest/m2/ts-hitless.md +++ b/quest/m2/ts-hitless.md @@ -24,8 +24,9 @@ Decided 2026-10-13 by the maintainer: the coordinate the legs share is the broadcast's media timeline, each object's timestamp on its catalog clock, with a constant mux rate. Two exports of one broadcast already read the same objects and timestamps, so this needs no importer -alignment; [same-epoch importers](/quest/m2/hop-aligned-import.md) extend it -to legs fed by different importers of one epoch. Every byte a `--sync` leg +alignment. Legs fed by different importers read different broadcasts +([distinct epochs](/quest/m0/broadcast-epoch/distinct-importer-epochs.md)), +so identity across them is a non-goal. Every byte a `--sync` leg renders from the objects it has (slot, PCR, table, PES header, continuity counter) is a function of those objects, that coordinate, the catalog, and the rate, never of what the leg has sent or when it joined. 2022-7 is a differentiator for primary distribution, not @@ -84,11 +85,6 @@ agreement alone. Public API: `moq export ts --sync`. -## Required - -- [Redundancy model](/quest/m1/redundancy-model.md) - whether a redundant pair stays active-active or fails over by epoch switchover - ## Related - [TS over RTP legs](/quest/m2/ts-rtp-egress.md) - packetizes these slots with matching RTP headers for ST 2022-7 -- [Same-epoch importers](/quest/m2/hop-aligned-import.md) - extends the coordinate to legs fed by different importers