Repository navigation
quest: import #5052 and #5101 as no-stitch and fresh TS export restarts #5108
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
4 commits
Select commit
Hold shift + click to select a range
7bd56d1
quest: import #5052 and #5101 as no-stitch and fresh TS export restarts
kixelated 8015e0f
quest: split export ts --linger (same epoch) from --stitch (replacement)
kixelated 890da34
quest: bound SRT egress linger and name the TS export successor API
kixelated 29769c7
quest: settle ts::Export::follow, SRT Config policy, and PAT versioning
kixelated File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 <dur>` 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 | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The same options cannot be added to SRT egress solely as CLI flags: embedders use the exported
moq_srt::Config,Server, andSubscribe::acceptinterfaces, none of which currently accepts a linger or stitch policy. The planned public API impact lists only the TS-export successor and CLI change, leaving library consumers no specified way to select this behavior; decide where this policy belongs and report that public surface.AGENTS.md reference: AGENTS.md:L59-L60
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Addressed in 29769c7: decided that the policy lives on
moq_srt::Configaslinger: Duration(default 0) andstitch: bool(default false), mirrored as CLI flags. The Public API line reports it.(Written by Claude Opus 5.5)