diff --git a/quest/m0/broadcast-epoch/README.md b/quest/m0/broadcast-epoch/README.md index 7a1c727a206..394b1eceb8d 100644 --- a/quest/m0/broadcast-epoch/README.md +++ b/quest/m0/broadcast-epoch/README.md @@ -95,7 +95,9 @@ then. MoQ Pro's VOD `storage.json` moves from the same seed to its own epoch. ## Required - [Restart](/quest/m0/broadcast-epoch/restart.md) - a replaced broadcast reaches announce consumers as an explicit Restart, subscriptions stay sticky, and new requests never join a replaced route's front +- [No stitch](/quest/m0/broadcast-epoch/no-stitch.md) - an epochless track ends on an upstream error instead of re-splicing onto whatever instance now wins upstream - [Apps](/quest/m0/broadcast-epoch/apps.md) - moq-cli, the browser publish and watch components, and demo/web restart into a new epoch and reset on the switch +- [Export ts](/quest/m0/broadcast-epoch/export-ts.md) - `export ts` and SRT egress linger only for the same epoch, and switch to a replacement only with `--stitch`, as a full program switch - [Publish catalog restart](/quest/m0/broadcast-epoch/publish-catalog-restart.md) - `@moq/publish` never reuses catalog group numbers under one name and epoch after a re-announce - [Bindings](/quest/m0/broadcast-epoch/bindings.md) - moq-ffi and every wrapper expose the epoch and let a publisher announce one - [moqsrc](/quest/m0/broadcast-epoch/moqsrc.md) - moqsrc switches to the new broadcast on a `Restart`, keeping its pads by rendition name diff --git a/quest/m0/broadcast-epoch/export-ts.md b/quest/m0/broadcast-epoch/export-ts.md new file mode 100644 index 00000000000..73657478e56 --- /dev/null +++ b/quest/m0/broadcast-epoch/export-ts.md @@ -0,0 +1,103 @@ +# [M] TS export lingers within an epoch and stitches across one only on request + +## Goal + +`moq export ts` and moq-srt's egress never splice two broadcasts into one TS +stream unless asked: + +- `--linger ` waits up to that long for the *same* broadcast (the same + epoch) to come back after its route goes, and carries on with the same + stream. +- A replacement (a newer epoch, or another instance of an epochless route) + ends the export with an error that names `--stitch`. On an epochless route + every return is a replacement. +- `--stitch` opts in to following a replacement. The export is rebuilt on the + new broadcast with a full program switch: a new PMT from the new catalog, so tracks, codecs, and PIDs may + change, plus PCR and continuity discontinuities. Nothing from the old + broadcast survives except the output pipe or SRT connection, and the + PSI version numbers. + +Non-goal: identical output across a replacement. Two legs that are +byte-identical within an epoch may differ after one (#5101). + +## Plan + +Decided 2026-10-09. Today `--linger` (#4504) waits for the ended broadcast to +close and the path to route again, then calls `ts::Export::resume()`. That +call clears the decode clocks, jitter buffer, and schedule, but keeps the old +PMT and PIDs and matches the returned tracks by name only, so a renamed codec +goes out under the old stream_type and continuity counters run on unflagged. +That is a splice of whatever returns, assuming the layout matches without +checking. It also keys on errors and the broadcast closing, so an old +publisher that stays alive holds the export on a replaced broadcast. + +- Delete `Export::resume()` and its partial reset. +- Drive both flags from announcements, as players do: `Start`, `Restart`, and + `End` with their epochs. An export that fails while its broadcast is still + announced exits 1 without lingering, as today. +- Same epoch within `--linger`: `follow` continues the same stream. + It is the same content, so the existing skip handling covers the gap (late + frames drop, and a forward leap opens a new generation). Within an epoch, + moq-net already resumes across routes, so this only matters once every + route has gone. +- Without `--stitch`: subscriptions are sticky, so a `Restart` leaves the + export on the old broadcast until it ends. If the path then serves a + different instance, the export exits 1 with an error naming `--stitch`. +- With `--stitch`: on `Restart` (or `End` then `Start` with another + instance) `follow` it at once, which builds a fresh `Export`. Every PID's first packet carries + `discontinuity_indicator`, the PAT and PMT `version_number`s advance (the only + values handed from the old `Export`, since a version-caching demux such as + TSDuck's ignores a changed PAT under an unchanged version), and each + elementary stream starts at a keyframe. Rejected: continuing only when the layout is identical, and + deleting `--linger`. Exiting does not hide the switch from a receiver + downstream of `tsp`, it only drops the flags. +- moq-srt's egress (`rs/moq-srt/src/ts.rs`) gets the same two options and keeps + its SRT connection across a stitch. Its linger defaults to 0, like the CLI: + an `End` that nothing replaces within the linger closes the SRT stream, so + a finished broadcast never leaves a caller connected indefinitely. +- Decided: the SRT policy lives on `moq_srt::Config` as `linger: Duration` + (default 0) and `stitch: bool` (default false), mirrored as CLI flags. +- Decided: one successor operation, `ts::Export::follow(self, broadcast) -> + Export`, used by both callers. On the same epoch it continues the stream + with the same PSI. On another instance it does the full program switch, + carrying the PAT and PMT `version_number`s, both advanced. The caller calls + it for a replacement only under `--stitch`. Rejected: separate continue and + stitch methods, and a builder policy that has the export watch announces + itself. +- Decided: the TS output has no epoch. A re-import of an export is out of + scope. +- Fold in the stale wording from the marker audit: a marker group only + declares a pause or forward break, since rewinds are refused (#3711). Rename + `Consumer::restarts` / `ExportSource::restarts` for what they count, and fix + the comments that say the publisher restarted or rewound its timeline + (`rs/moq-mux/src/container/consumer.rs`, `rs/moq-srt/src/server.rs`). +- Tests, with mocked time: + - A same-epoch return within the linger continues the stream with no PSI + version change. + - A replacement without `--stitch` exits 1, and an old publisher that stays + alive keeps the export on it until it ends. + - With `--stitch`, a replacement with a different codec and track set + writes a new PMT version, flags every PID's first packet, starts each + stream at a keyframe, and writes nothing from the old broadcast after the + break. + - A stitch that keeps the transport-stream ID but moves the PMT PID + advances the PAT version. + - Update #4504's relay-backed CLI tests, and add the stitch case for SRT + egress, plus an unreplaced `End` closing the SRT stream at the linger. +- Docs: the `--linger` paragraph in `doc/bin/cli.md` (plus `--stitch`), any + restart behavior in `doc/bin/srt.md`, and every example invocation using + `--linger`. + +Public API: breaking, `ts::Export::resume` is removed and `restarts()` is +renamed. New: `ts::Export::follow`, and `linger` and `stitch` on +`moq_srt::Config`. CLI: new `--stitch` on `export ts` and SRT egress, and `--linger` +no longer follows a replacement. Wire: none. + +## Required + +- [Restart](/quest/m0/broadcast-epoch/restart.md) - the announce event and epoch the export follows + +## Related + +- [No stitch](/quest/m0/broadcast-epoch/no-stitch.md) - stops moq-net hiding a replacement from the export +- [Two TS export legs](/quest/m2/ts-hitless.md) - identical output within one epoch diff --git a/quest/m0/broadcast-epoch/no-stitch.md b/quest/m0/broadcast-epoch/no-stitch.md new file mode 100644 index 00000000000..03fa8c9cd69 --- /dev/null +++ b/quest/m0/broadcast-epoch/no-stitch.md @@ -0,0 +1,61 @@ +# [M] An epochless track ends on an upstream error instead of re-splicing + +## Goal + +A delivered track whose front has no epoch ends with the upstream error +instead of re-subscribing. A re-subscribe through the same session can land on +a different instance one hop upstream. Only a front with an epoch re-splices +after an error, and its re-request carries that epoch, so it resumes the same +broadcast or fails. Consumers of an epochless broadcast recover on the announce +`Restart` (or `End` then `Start`), never on a silent re-splice. + +## Plan + +Found in #5052 (t0ms), decided 2026-10-09. On lite-06, a relay times out the +dead publisher's session and ends the downstream copy with `internal error`. +The downstream front takes `Front::track_ended`'s `Err(_) if delivered` arm +(`rs/moq-net/src/model/front.rs`), "normal failover", and `redispatch`es to +the same serving source, which is the relay session, about 2 ms later. The +relay resolves the epochless SUBSCRIBE to whatever wins the path now, the +replacement publisher, and the resume layer fetches the rest of the +in-flight group from it. The consumer sees no error and no restart. So two +epochless instances are stitched across a hop, against "routes without an +epoch never splice". #5087 does not change this: the redispatch arm is +untouched, and its held END/START reaches the downstream relay hundreds of ms +after the re-subscribe. In `moq export ts`, frames read before the death sat +in the decode hold through the silence and came out 13-26 s late, and the +export bailed on "missed a decode deadline". + +- Decided: resume after an error only within an epoch. Rejected: a distinct + terminal error from the relay for "upstream instance gone" (a new wire + distinction every hop must classify), and accepting the stitch on lite-06. +- Accepted consequence: on lite-06, and on any epochless route, any upstream + track error now ends the track. The epoch README already accepts that + default sessions end subscriptions on failover instead of resuming them. +- Decided: no exporter-side guard. A unit due at or behind the TS schedule's + `next` still bails. Once the stitch is gone, a stale unit reaching the + schedule is a bug to fail loud on. The replaced broadcast's state is dropped + by [Export ts](/quest/m0/broadcast-epoch/export-ts.md). +- Fix the module docs that claim an epochless front is never swapped + (`front.rs` header, `origin.rs` around `pick`): today that holds only when + the replacement is in the front's own table. +- Tests, with mocked time: an epochless publisher behind a relay is replaced + (the old session times out, a new one is already announced) on lite-06 and + lite-07. The downstream track ends with the error and never fetches a + group from the replacement. A 1+1 pair sharing an epoch on lite-07 still + fails over with no error downstream. The same pair reaching the relay on + lite-06 ends the downstream track. +- After landing, ask t0ms to re-run both #5052 rigs. One rig-2 run exited + 1.4 s after a mid-GOP join, before any failover, which the stitch does not + explain. If it reproduces, it is a separate issue. + +Public API: none. Behavior: an epochless subscription now surfaces an +upstream error instead of healing. Wire: none. + +## Required + +- [Restart](/quest/m0/broadcast-epoch/restart.md) - reworks the same front and instance code, and supplies the `Restart` consumers recover on + +## Closes + +- [#5052](https://github.com/moq-dev/moq/issues/5052) - export ts bails after re-requesting onto a replacement publisher diff --git a/quest/m2/ts-hitless.md b/quest/m2/ts-hitless.md index 1b578656bd0..5eb40a8815c 100644 --- a/quest/m2/ts-hitless.md +++ b/quest/m2/ts-hitless.md @@ -4,9 +4,14 @@ Two `moq export ts --sync` legs of one broadcast, joined at different moments, emit packet-identical TS from their first common packet, across -skips and source drift, continuity counters included. A ST 2022-7 selector +skips and source drift, continuity counters included, within one epoch. A ST 2022-7 selector can then switch between them hitlessly. +Non-goal: identity across a replaced broadcast. A leg ends on a replacement, or +starts a fresh stream with `--stitch` ([Export ts](/quest/m0/broadcast-epoch/export-ts.md)), +so legs may differ after one (#5101, maintainer 2026-10-09: byte-identical +output across restarts is not supported). + ## Plan Decided (2026-10-01), from t0ms's review of the fixed-delay export (#4645).