From 3eeb55bc82365d822d2ecc6213e67d8320b08477 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 7 Oct 2026 18:50:31 -0700 Subject: [PATCH 1/4] quest: plan moqsrc following a restart moqsrc follows the path's announcements and switches to the new broadcast on an announce Restart, keeping each pad by rendition name, with an opt-in linger for an uncoalesced End then Start. Requires the Restart quest, whose Players bullet now links it. Co-Authored-By: Claude Opus 5.5 --- quest/m0/broadcast-epoch/README.md | 1 + quest/m0/broadcast-epoch/moqsrc.md | 71 +++++++++++++++++++++++++++++ quest/m0/broadcast-epoch/restart.md | 2 +- 3 files changed, 73 insertions(+), 1 deletion(-) create mode 100644 quest/m0/broadcast-epoch/moqsrc.md diff --git a/quest/m0/broadcast-epoch/README.md b/quest/m0/broadcast-epoch/README.md index a1e4f77c55e..1df35633012 100644 --- a/quest/m0/broadcast-epoch/README.md +++ b/quest/m0/broadcast-epoch/README.md @@ -84,5 +84,6 @@ newest epoch falls back to a still-live older one. - [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 - [TS restart](/quest/m0/broadcast-epoch/ts-restart.md) - a signalled backward TS discontinuity finishes the broadcast and continues the same input under a fresh epoch - [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 - [Stats epochs](/quest/m0/broadcast-epoch/stats-epoch.md) - moq-stats publishes each group announcement under its own epoch, so neither a restarted node nor a returning idle group stalls its viewers - [Stats totals and prefix tracks](/quest/m0/broadcast-epoch/stats-split.md) - the same release retires the per-path stats maps for totals and on-demand prefix tracks (decided 2026-10-05) diff --git a/quest/m0/broadcast-epoch/moqsrc.md b/quest/m0/broadcast-epoch/moqsrc.md new file mode 100644 index 00000000000..305333a8816 --- /dev/null +++ b/quest/m0/broadcast-epoch/moqsrc.md @@ -0,0 +1,71 @@ +# [M] moqsrc follows a restart + +## Goal + +When the source behind `moqsrc`'s path restarts (an announce `Restart`), the +pipeline keeps running and switches to the new broadcast: a fresh catalog on +the same pads, with no error on the bus. Once subscriptions are sticky, +`moqsrc` would otherwise keep playing the replaced broadcast until its route +goes, then end or error. A broadcast that ends with no successor still ends as +it does today, unless the opt-in `linger` holds it. + +## Plan + +Decided in planning (2026-10-06, after #4955 found that no quest covered +`moqsrc`), re-scoped onto [Restart](/quest/m0/broadcast-epoch/restart.md) +(2026-10-07): + +- **Follow announcements.** `moqsrc` follows the path's announcements + (`origin::Consumer::announced`) rather than resolving once with + `routed_broadcast`. It plays on `Start`, switches on `Restart` by + re-requesting the path (which resolves the new route), and ends on `End`. + An `Update` (a re-price or same-epoch failover) changes nothing, so it + stays a seamless mid-group resume. Restart owns deciding what is a source + change, so `moqsrc` never compares epochs itself. +- **Errors stay fatal.** A replacement no longer ends the old subscriptions, + so an error on the catalog or a track posts the session error as today. + The earlier rule treating `Unroutable` as a switch in flight is dropped: it + could not tell a switch from a dead route and could hang. +- **Cutover.** Cancel the old pumps as soon as the `Restart` is seen, without + waiting for their subscriptions to end. +- **Pads (decided 2026-10-07, reconfirmed after the Restart re-scope).** Keep each pad by rendition name across a + switch, so a `gst-launch` pipeline linked by name (`s.video_0 ! queue`) + keeps playing. Fresh pads were rejected: pad ids come from a process-wide + counter, so a new run's pads get new names, stay unlinked, and the pipeline + goes idle silently. Pad state outlives a pump: a pump hands its pad back to + the session instead of removing it. On the switch, push stream-start, the + new caps (even when they differ, so a codec change fails loudly as + not-negotiated rather than going quiet), and a segment whose `base` is the + current running time, so a synced sink does not drop the new run (PTS + restarts at 0) as late. An in-run caps or container change keeps its pad + the same way. A rendition the new catalog drops ends with EOS; a new or + renamed one gets a new pad. +- **Linger (decided 2026-10-07).** A `linger` property, default 0. After + `End`, keep the pads idle for that long; a `Start` in the window resumes on + the same pads, otherwise EOS. This covers a lite-06 or moq-transport + restart whose END and START are not coalesced into a `Restart`. While + lingering is possible, a track that ends does not push EOS or drop its pad, + since the old tracks can finish before the `End` arrives; EOS goes out when + the window expires or the next catalog drops the rendition. The default + keeps today's ending. +- **Where.** The logic stays in `rs/moq-gst/src/source`. If + [Apps](/quest/m0/broadcast-epoch/apps.md) lands a shared helper for + following announcements first, use it instead. +- **Test.** An in-process test republishes the path under a newer epoch while + the old publisher stays up: the new run's buffers render through a synced + sink, a pad linked by name keeps flowing, and the bus carries no error. + Cover an epochless source change that also switches, a same-epoch + re-announce (`Update`) that does not, a switch with new caps that keeps the + pad, and an `End` then `Start` that resumes on the same pads with `linger` + set (the old tracks finish before the `End` is delivered) and ends with it + at 0. Drive the linger window with mocked time. + +Update the `moqsrc` section of `doc/bin/gstreamer.md`: a restart keeps each +pad by rendition name, a format change keeps its pad, a dropped rendition gets +EOS, and `linger`. + +Public API: a new `linger` property on `moqsrc`. Wire: none. + +## Required + +- [Restart](/quest/m0/broadcast-epoch/restart.md) - delivers the `Restart` announce event and sticky subscriptions this follows diff --git a/quest/m0/broadcast-epoch/restart.md b/quest/m0/broadcast-epoch/restart.md index 097a1d36b65..82a2cfef95e 100644 --- a/quest/m0/broadcast-epoch/restart.md +++ b/quest/m0/broadcast-epoch/restart.md @@ -90,7 +90,7 @@ Decided in planning (2026-10-07, from #4970's review): instead of treating every epochless `Update` as a restart, so a re-price that keeps its winner, or a same-epoch failover, no longer restarts playback. An epochless drain onto a different entry still does. - `moqsrc` (planned in #4960) switches on `Restart` too. On lite-06 and + [moqsrc](/quest/m0/broadcast-epoch/moqsrc.md) switches on `Restart` too. On lite-06 and moq-transport, a pair not coalesced reaches players as `End` then `Start`: a stop, then a fresh play. - **Rejected** (in #5013): `@moq/watch` resubscribing on `Internal` or From 2a9104c6e9c1e7f2b56671d035309ef4d866edff Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 7 Oct 2026 19:05:42 -0700 Subject: [PATCH 2/4] quest(moqsrc): bound linger over source loss and a finished output Start the linger window on End, the catalog finishing, or a source-loss error, and post the error at expiry if a loss opened it. Correct the error rule: track errors end their pad, only catalog errors are fatal. Co-Authored-By: Claude Opus 5.5 --- quest/m0/broadcast-epoch/moqsrc.md | 43 ++++++++++++++++++------------ 1 file changed, 26 insertions(+), 17 deletions(-) diff --git a/quest/m0/broadcast-epoch/moqsrc.md b/quest/m0/broadcast-epoch/moqsrc.md index 305333a8816..b0ed7c3abb3 100644 --- a/quest/m0/broadcast-epoch/moqsrc.md +++ b/quest/m0/broadcast-epoch/moqsrc.md @@ -22,14 +22,16 @@ Decided in planning (2026-10-06, after #4955 found that no quest covered An `Update` (a re-price or same-epoch failover) changes nothing, so it stays a seamless mid-group resume. Restart owns deciding what is a source change, so `moqsrc` never compares epochs itself. -- **Errors stay fatal.** A replacement no longer ends the old subscriptions, - so an error on the catalog or a track posts the session error as today. - The earlier rule treating `Unroutable` as a switch in flight is dropped: it - could not tell a switch from a dead route and could hang. +- **Errors keep today's handling.** A replacement no longer ends the old + subscriptions, so a catalog error posts the session error and a track error + logs and ends that pad, as today. The earlier rule treating `Unroutable` as + a switch in flight is dropped: it could not tell a switch from a dead route + and could hang. Only `linger` below defers an error, and only for its + window. - **Cutover.** Cancel the old pumps as soon as the `Restart` is seen, without waiting for their subscriptions to end. -- **Pads (decided 2026-10-07, reconfirmed after the Restart re-scope).** Keep each pad by rendition name across a - switch, so a `gst-launch` pipeline linked by name (`s.video_0 ! queue`) +- **Pads (decided 2026-10-07, reconfirmed after the Restart re-scope).** + Keep each pad by rendition name across a switch, so a `gst-launch` pipeline linked by name (`s.video_0 ! queue`) keeps playing. Fresh pads were rejected: pad ids come from a process-wide counter, so a new run's pads get new names, stay unlinked, and the pipeline goes idle silently. Pad state outlives a pump: a pump hands its pad back to @@ -40,14 +42,18 @@ Decided in planning (2026-10-06, after #4955 found that no quest covered restarts at 0) as late. An in-run caps or container change keeps its pad the same way. A rendition the new catalog drops ends with EOS; a new or renamed one gets a new pad. -- **Linger (decided 2026-10-07).** A `linger` property, default 0. After - `End`, keep the pads idle for that long; a `Start` in the window resumes on - the same pads, otherwise EOS. This covers a lite-06 or moq-transport - restart whose END and START are not coalesced into a `Restart`. While - lingering is possible, a track that ends does not push EOS or drop its pad, - since the old tracks can finish before the `End` arrives; EOS goes out when - the window expires or the next catalog drops the rendition. The default - keeps today's ending. +- **Linger (decided 2026-10-07).** A `linger` property, default 0, that + covers a lite-06 or moq-transport restart whose END and START are not + coalesced into a `Restart`, and a crashed or withdrawn source. The window + starts on the first of `End`, the catalog finishing (a prefix can stay + announced after its output finishes), or a source-loss error on the catalog + or a track (the route went, `Dropped`, or the upstream session closed), + since these arrive on different streams in either order. Inside it, a track + that ends or loses its source hands its pad back without EOS, and a + `Start` or `Restart` resumes on the same pads. At expiry every held pad gets + EOS, or the error posts if a source loss opened the window; a pump still + streaming ends as it would without linger. The bound keeps this from + becoming a silent hang. At 0 nothing changes from today. - **Where.** The logic stays in `rs/moq-gst/src/source`. If [Apps](/quest/m0/broadcast-epoch/apps.md) lands a shared helper for following announcements first, use it instead. @@ -56,9 +62,12 @@ Decided in planning (2026-10-06, after #4955 found that no quest covered sink, a pad linked by name keeps flowing, and the bus carries no error. Cover an epochless source change that also switches, a same-epoch re-announce (`Update`) that does not, a switch with new caps that keeps the - pad, and an `End` then `Start` that resumes on the same pads with `linger` - set (the old tracks finish before the `End` is delivered) and ends with it - at 0. Drive the linger window with mocked time. + pad, and with `linger` set: an `End` then `Start` that resumes on the same + pads (the old tracks finish before the `End` is delivered), an old + publisher's session closed (not finished) over a relay that resumes on the + next `Start`, and a finished output under a still-announced prefix that + gets EOS by the deadline. With `linger` at 0, each of these ends or errors + as today. Drive the linger window with mocked time. Update the `moqsrc` section of `doc/bin/gstreamer.md`: a restart keeps each pad by rendition name, a format change keeps its pad, a dropped rendition gets From 19cf8fe6f59a68415352c8bef4839434d38cec57 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 7 Oct 2026 19:12:49 -0700 Subject: [PATCH 3/4] quest(moqsrc): hold pads before the linger window, keep lone track loss local While linger is set, a track that ends or loses its source holds its pad before the window opens, and a lone track's source loss ends only that pad rather than posting the session error. Co-Authored-By: Claude Opus 5.5 --- quest/m0/broadcast-epoch/moqsrc.md | 30 +++++++++++++++++------------- 1 file changed, 17 insertions(+), 13 deletions(-) diff --git a/quest/m0/broadcast-epoch/moqsrc.md b/quest/m0/broadcast-epoch/moqsrc.md index b0ed7c3abb3..08938684885 100644 --- a/quest/m0/broadcast-epoch/moqsrc.md +++ b/quest/m0/broadcast-epoch/moqsrc.md @@ -44,16 +44,19 @@ Decided in planning (2026-10-06, after #4955 found that no quest covered renamed one gets a new pad. - **Linger (decided 2026-10-07).** A `linger` property, default 0, that covers a lite-06 or moq-transport restart whose END and START are not - coalesced into a `Restart`, and a crashed or withdrawn source. The window - starts on the first of `End`, the catalog finishing (a prefix can stay - announced after its output finishes), or a source-loss error on the catalog - or a track (the route went, `Dropped`, or the upstream session closed), - since these arrive on different streams in either order. Inside it, a track - that ends or loses its source hands its pad back without EOS, and a - `Start` or `Restart` resumes on the same pads. At expiry every held pad gets - EOS, or the error posts if a source loss opened the window; a pump still - streaming ends as it would without linger. The bound keeps this from - becoming a silent hang. At 0 nothing changes from today. + coalesced into a `Restart`, and a crashed or withdrawn source. While + `linger` > 0, a track that ends or loses its source (the route went, + `Dropped`, or the upstream session closed) hands its pad back without EOS, + since tracks, the catalog, and `End` arrive on different streams in either + order. A rendition the catalog already retired still drains to EOS as today. + The window starts on the first of `End`, the catalog finishing (a prefix + can stay announced after its output finishes), or the catalog losing its + source. A `Start` or `Restart` in it resumes on the same pads. At expiry + every held pad gets EOS, and the session error posts only if the catalog + lost its source; a pump still streaming ends as it would without linger. A + held track whose catalog and path stay live waits the same bound from its + own end, then ends its pad as it would at 0. The bound keeps this from becoming a + silent hang. At 0 nothing changes from today. - **Where.** The logic stays in `rs/moq-gst/src/source`. If [Apps](/quest/m0/broadcast-epoch/apps.md) lands a shared helper for following announcements first, use it instead. @@ -63,11 +66,12 @@ Decided in planning (2026-10-06, after #4955 found that no quest covered Cover an epochless source change that also switches, a same-epoch re-announce (`Update`) that does not, a switch with new caps that keeps the pad, and with `linger` set: an `End` then `Start` that resumes on the same - pads (the old tracks finish before the `End` is delivered), an old + pads (media FIN, then catalog FIN, then `End`, then `Start`), an old publisher's session closed (not finished) over a relay that resumes on the next `Start`, and a finished output under a still-announced prefix that - gets EOS by the deadline. With `linger` at 0, each of these ends or errors - as today. Drive the linger window with mocked time. + gets EOS by the deadline, and a lone track losing its source while its + siblings and the catalog stay live, which ends only that pad. With + `linger` at 0, each of these ends or errors as today. Drive the linger window with mocked time. Update the `moqsrc` section of `doc/bin/gstreamer.md`: a restart keeps each pad by rendition name, a format change keeps its pad, a dropped rendition gets From a5a37ca44093cc76450df14afe22f64082de4897 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 7 Oct 2026 19:39:08 -0700 Subject: [PATCH 4/4] quest(moqsrc): the linger window cancels per-track timers Co-Authored-By: Claude Opus 5.5 --- quest/m0/broadcast-epoch/moqsrc.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/quest/m0/broadcast-epoch/moqsrc.md b/quest/m0/broadcast-epoch/moqsrc.md index 08938684885..f13518d01d3 100644 --- a/quest/m0/broadcast-epoch/moqsrc.md +++ b/quest/m0/broadcast-epoch/moqsrc.md @@ -31,8 +31,9 @@ Decided in planning (2026-10-06, after #4955 found that no quest covered - **Cutover.** Cancel the old pumps as soon as the `Restart` is seen, without waiting for their subscriptions to end. - **Pads (decided 2026-10-07, reconfirmed after the Restart re-scope).** - Keep each pad by rendition name across a switch, so a `gst-launch` pipeline linked by name (`s.video_0 ! queue`) - keeps playing. Fresh pads were rejected: pad ids come from a process-wide + Keep each pad by rendition name across a switch, so a `gst-launch` + pipeline linked by name (`s.video_0 ! queue`) keeps playing. Fresh pads + were rejected: pad ids come from a process-wide counter, so a new run's pads get new names, stay unlinked, and the pipeline goes idle silently. Pad state outlives a pump: a pump hands its pad back to the session instead of removing it. On the switch, push stream-start, the @@ -55,8 +56,9 @@ Decided in planning (2026-10-06, after #4955 found that no quest covered every held pad gets EOS, and the session error posts only if the catalog lost its source; a pump still streaming ends as it would without linger. A held track whose catalog and path stay live waits the same bound from its - own end, then ends its pad as it would at 0. The bound keeps this from becoming a - silent hang. At 0 nothing changes from today. + own end, then ends its pad as it would at 0; opening the window cancels + those per-track timers, so held pads follow the window's expiry. The bound + keeps this from becoming a silent hang. At 0 nothing changes from today. - **Where.** The logic stays in `rs/moq-gst/src/source`. If [Apps](/quest/m0/broadcast-epoch/apps.md) lands a shared helper for following announcements first, use it instead. @@ -66,12 +68,13 @@ Decided in planning (2026-10-06, after #4955 found that no quest covered Cover an epochless source change that also switches, a same-epoch re-announce (`Update`) that does not, a switch with new caps that keeps the pad, and with `linger` set: an `End` then `Start` that resumes on the same - pads (media FIN, then catalog FIN, then `End`, then `Start`), an old + pads (media FIN, a delay, catalog FIN, `End`, then `Start`), an old publisher's session closed (not finished) over a relay that resumes on the next `Start`, and a finished output under a still-announced prefix that gets EOS by the deadline, and a lone track losing its source while its siblings and the catalog stay live, which ends only that pad. With - `linger` at 0, each of these ends or errors as today. Drive the linger window with mocked time. + `linger` at 0, each of these ends or errors as today. Drive the linger + window with mocked time. Update the `moqsrc` section of `doc/bin/gstreamer.md`: a restart keeps each pad by rendition name, a format change keeps its pad, a dropped rendition gets