diff --git a/quest/m1/api-audit/README.md b/quest/m1/api-audit/README.md index 70972ce01e8..feb7890423f 100644 --- a/quest/m1/api-audit/README.md +++ b/quest/m1/api-audit/README.md @@ -73,7 +73,7 @@ Rejected in planning: ## Required -- [Two broadcast resolutions](/quest/m1/api-audit/resolve.md) - Rust, JS, and the bindings resolve a broadcast with `request(path, epoch)` or `follow(path, epoch)`, and every racy two-step caller is gone +- [Two broadcast resolutions](/quest/m1/api-audit/resolve/README.md) - Rust, JS, and the bindings resolve a broadcast with `request(path, epoch)` or `follow(path, epoch)`, and every racy two-step caller is gone - [Bindings default to zero max delay](/quest/m1/api-audit/binding-max-delay.md) - a no-argument subscription skips superseded groups in every binding, as Rust, JS, and Python do, and no subscriber limit is asked for explicitly - [Demand is wanted, everywhere](/quest/m1/api-audit/wanted.md) - every `used`/`unused` pair becomes `wanted()` and `wanted_changed()`, and unused ones go - [One strict path rule](/quest/m1/api-audit/strict-paths.md) - `Relative` refuses empty segments, `Path` refuses non-canonical escapes, the error is `path::Error`, and auth mints only strict paths diff --git a/quest/m1/api-audit/resolve.md b/quest/m1/api-audit/resolve.md deleted file mode 100644 index d0a7ea317fc..00000000000 --- a/quest/m1/api-audit/resolve.md +++ /dev/null @@ -1,78 +0,0 @@ -# [L] Two broadcast resolutions - -## Goal - -An application resolves a broadcast in one of two ways, named the same in -Rust, JS, and every binding: - -- `request(path, epoch)` resolves one publisher instance. It owns the - discovery interest it needs, so on a watch-driven lite client it finds a - broadcast the peer serves without the caller watching the path first, and - it retries across route churn. It answers `Unroutable` only once discovery - has synced with no covering route. -- `follow(path, epoch)` follows the path across publisher instances (today's - `announced_broadcast`), pinned to `epoch` when given. - -No caller can assemble a racy two-step resolve, and no crate hand-rolls -"resolve once discovery synced". - -## Plan - -Decided 2026-10-22 (API audit, maintainer approved the recommendation). - -The behavioral checkpoint makes `request_broadcast` own scoped discovery and -retry route churn. It reports table absence only after sync; a selected handler's -explicit refusal stays terminal, including a dropped Prepared answer. The front -records that refusal privately at its existing standing-route decision, rather -than guessing from unrelated mutations of the table. The old immediate lookup -is private to sessions. `Requesting::is_queued` and the public `Routing` task are -gone; `Requesting` is the owned task. The stats reader uses it instead of its -own retry on `is_queued`; the mux binding keeps its pinned `routed_broadcast` -wait. Rust and JS have same-epoch follow-return coverage, and every JS request -owns its discovery watch from creation. A pending plain JS request fails -`Unroutable` once that discovery syncs with no route for it, matching Rust. JS -announcement-following no longer silently uses a blind peer. The existing -`routed_broadcast` helper retains its route-change retry policy for the CLI, -gateway, mux binding, and relay HTTP consumers. Its removal belongs to the remaining rollout. - -The approved public method names have not rolled out. What remains: - -- Rust: name the owned operation `request(path, epoch)` and today's - `announced_broadcast` operation `follow(path, epoch)`. Keep the immediate - table lookup private. Delete `routed` and `routed_broadcast` and fix their - callers. Preserve terminal selected-handler refusals, private deferred - validity checks, and instance identity across route churn. -- Move the remaining route-level `Follow` consumers before making it private: - the moq-hls server's resolve and the tests that read its events. `moq play` - and `moqsrc` already follow through `moq_mux::Source::follow`. Do not add a - new public route API or compatibility shim to make the privatization pass. -- JS: expose `request(path, {epoch})` and `follow(path, {epoch})` instead of the - `announced` option and migrate actual callers. Keep the checkpoint's - synced-absence `Unroutable` for `request` while `follow` stays open, and its - pending retry through a route gap without retargeting a resolved instance. - Retain synchronous request peeks and path-local wakeups. - `Producer` pass-throughs stay only where `Table` needs them. -- Bindings: mirror `request` and `follow`, including the optional epoch, in - the FFI and every actual wrapper/consumer. Regenerate from source, update - package migrations, and run all-language interop. Existing binding names - currently inherit the owned-discovery behavior, not the final naming. -- Callers: remove the racy two-step lookup and hidden error in moq-wasm, - route waits in moq-cli subscribe/report, and the HLS hand-rolled discovery - and `RESOLVE_TIMEOUT`. Review SRT, transcode, benchmark connections, relay - HTTP fetch deadlines, the e2ee epoch advice, and the demo's announce-derived - epoch pin. No caller should hand-roll synced resolution or rely on a wall - clock to decide table absence. - -Tests cover an announced but unwatched path over lite-05/06/07-wip, Rust and JS -synced absence, discovery retention and release, pinned follow return, no follower -fallback on a blind peer, and unchanged explicit refusal. Finish the API and -caller rollout with the same lifecycle and churn checks, then the required -Nix gate and all-language interop. - -Public API: breaking task shape in moq-net; behavior changes in `@moq/net` and -the bindings. Final method/epoch naming remains breaking across every wrapper. -Wire: none. - -## Related - -- [Origin fronts park](/quest/m2/origin-front-parks.md) - touches the same retry diff --git a/quest/m1/api-audit/resolve/README.md b/quest/m1/api-audit/resolve/README.md new file mode 100644 index 00000000000..215dd750002 --- /dev/null +++ b/quest/m1/api-audit/resolve/README.md @@ -0,0 +1,60 @@ +# Two broadcast resolutions + +## Goal + +An application resolves a broadcast in one of two ways, named the same in +Rust, JS, and every binding: + +- `request(path, epoch)` resolves one publisher instance. It owns the + discovery interest it needs, so on a watch-driven lite client it finds a + broadcast the peer serves without the caller watching the path first, and + it retries across route churn. It answers `Unroutable` only once discovery + has synced with no covering route. +- `follow(path, epoch)` follows the path across publisher instances (today's + `announced_broadcast`), pinned to `epoch` when given. + +No caller can assemble a racy two-step resolve, and no crate hand-rolls +"resolve once discovery synced". + +## Plan + +Decided 2026-10-22 (API audit, maintainer approved the recommendation). + +The behavioral checkpoint makes `request_broadcast` own scoped discovery and +retry route churn. It reports table absence only after sync; a selected handler's +explicit refusal stays terminal, including a dropped Prepared answer. The front +records that refusal privately at its existing standing-route decision, rather +than guessing from unrelated mutations of the table. The old immediate lookup +is private to sessions. `Requesting::is_queued` and the public `Routing` task are +gone; `Requesting` is the owned task. The stats reader uses it instead of its +own retry on `is_queued`; the mux binding keeps its pinned `routed_broadcast` +wait. Rust and JS have same-epoch follow-return coverage, and every JS request +owns its discovery watch from creation. A pending plain JS request fails +`Unroutable` once that discovery syncs with no route for it, matching Rust. JS +announcement-following no longer silently uses a blind peer. The existing +`routed_broadcast` helper retains its route-change retry policy for the CLI, +gateway, mux binding, and relay HTTP consumers. Its removal belongs to the remaining rollout. + +The approved public method names have not rolled out. Decided 2026-10-28 +(maintainer, /quest-plan): the rollout splits into the four children below, so +each language and the callers review on their own. Rust and JS proceed in +parallel; the bindings follow Rust, and the callers follow both. + +This README's own work, once every child lands: the lifecycle and churn checks +across languages, the required Nix gate, and all-language interop +(`just test interop --all`). + +Public API: breaking task shape in moq-net; behavior changes in `@moq/net` and +the bindings. Final method/epoch naming remains breaking across every wrapper. +Wire: none. + +## Required + +- [Rust request and follow](/quest/m1/api-audit/resolve/rust.md) - Rust names the two resolutions `request` and `follow`, deletes `routed` and `routed_broadcast`, and makes the route-level `Follow` private +- [JS request and follow](/quest/m1/api-audit/resolve/js.md) - `@moq/net` exposes `request(path, {epoch})` and `follow(path, {epoch})` instead of the `announced` option +- [Bindings request and follow](/quest/m1/api-audit/resolve/bindings.md) - moq-ffi, the C ABI, and every wrapper mirror `request` and `follow` with an optional epoch +- [Callers resolve once](/quest/m1/api-audit/resolve/callers.md) - no caller hand-rolls synced resolution or decides table absence by wall clock + +## Related + +- [Origin fronts park](/quest/m2/origin-front-parks.md) - touches the same retry diff --git a/quest/m1/api-audit/resolve/bindings.md b/quest/m1/api-audit/resolve/bindings.md new file mode 100644 index 00000000000..938e9776298 --- /dev/null +++ b/quest/m1/api-audit/resolve/bindings.md @@ -0,0 +1,25 @@ +# [M] Bindings request and follow + +## Goal + +moq-ffi, the C ABI, and every wrapper (py, swift, kt, dart, go, cpp, OBS) +mirror `request` and `follow`, each with an optional epoch, and their +consumers use them. + +## Plan + +Split from [Two broadcast resolutions](/quest/m1/api-audit/resolve/README.md) +on 2026-10-28 (maintainer). Today's binding names already inherit the +owned-discovery behavior from +[moq-dev/moq#6445](https://github.com/moq-dev/moq/pull/6445), not the final +naming. + +Regenerate bindings from source, update every wrapper's tests, READMEs and +`doc/lib/*`, add an Impact migration note per package, and run +`just test interop --all`. + +Public API: breaking in moq-ffi, the C ABI, and every wrapper. Wire: none. + +## Required + +- [Rust request and follow](/quest/m1/api-audit/resolve/rust.md) - the Rust names the bindings mirror diff --git a/quest/m1/api-audit/resolve/callers.md b/quest/m1/api-audit/resolve/callers.md new file mode 100644 index 00000000000..40978216747 --- /dev/null +++ b/quest/m1/api-audit/resolve/callers.md @@ -0,0 +1,28 @@ +# [M] Callers resolve once + +## Goal + +No caller hand-rolls synced resolution or relies on a wall clock to decide a +broadcast is absent. Each first-party caller resolves with `request` or +`follow`. + +## Plan + +Split from [Two broadcast resolutions](/quest/m1/api-audit/resolve/README.md) +on 2026-10-28 (maintainer). + +- Remove the racy two-step lookup and its hidden error in moq-wasm. +- Replace the route waits in moq-cli's subscribe and report. +- Review SRT, transcode, the benchmark connections, relay HTTP fetch + deadlines, the e2ee epoch advice, and the demo's announce-derived epoch pin; + fix each that hand-rolls resolution or decides absence by time. + +List every caller in the PR with what it now uses. Run the affected packages' +tests and `just test interop --all`. + +Public API: none beyond the callers' own surfaces. Wire: none. + +## Required + +- [Rust request and follow](/quest/m1/api-audit/resolve/rust.md) - the Rust names the callers move to +- [JS request and follow](/quest/m1/api-audit/resolve/js.md) - the JS names the callers move to diff --git a/quest/m1/api-audit/resolve/js.md b/quest/m1/api-audit/resolve/js.md new file mode 100644 index 00000000000..38890233630 --- /dev/null +++ b/quest/m1/api-audit/resolve/js.md @@ -0,0 +1,25 @@ +# [M] JS request and follow + +## Goal + +`@moq/net` exposes `request(path, {epoch})` and `follow(path, {epoch})` +instead of the `announced` option, and its in-package callers use them. + +## Plan + +Split from [Two broadcast resolutions](/quest/m1/api-audit/resolve/README.md) +on 2026-10-28 (maintainer); its Plan holds the behavior already landed in +[moq-dev/moq#6445](https://github.com/moq-dev/moq/pull/6445). + +- Keep the landed synced-absence `Unroutable` for `request` while `follow` + stays open, and its pending retry through a route gap without retargeting a + resolved instance. +- Retain synchronous request peeks and path-local wakeups. +- `Producer` pass-throughs stay only where `Table` needs them. +- Mirror the Rust names from [Rust request and follow](/quest/m1/api-audit/resolve/rust.md). + +Tests: synced absence, no follower fallback on a blind peer, pinned follow +return, and discovery retention and release, on mocked time. + +Public API: breaking in `@moq/net` (the `announced` option goes), with an +Impact migration note and a regenerated API report. Wire: none. diff --git a/quest/m1/api-audit/resolve/rust.md b/quest/m1/api-audit/resolve/rust.md new file mode 100644 index 00000000000..be9ef749807 --- /dev/null +++ b/quest/m1/api-audit/resolve/rust.md @@ -0,0 +1,32 @@ +# [M] Rust request and follow + +## Goal + +Rust names the two resolutions `request(path, epoch)` and `follow(path, +epoch)` (today's `announced_broadcast`). The immediate table lookup stays +private, `routed` and `routed_broadcast` are deleted with their callers +fixed, and the route-level `Follow` is private. + +## Plan + +Split from [Two broadcast resolutions](/quest/m1/api-audit/resolve/README.md) +on 2026-10-28 (maintainer); its Plan holds the behavior already landed in +[moq-dev/moq#6445](https://github.com/moq-dev/moq/pull/6445). + +- Preserve terminal selected-handler refusals, private deferred validity + checks, and instance identity across route churn. +- Move the remaining route-level `Follow` consumers before making it private: + the moq-hls server's resolve, with its hand-rolled discovery and + `RESOLVE_TIMEOUT`, and the tests that read its events. `moq play` and + `moqsrc` already follow through `moq_mux::Source::follow`. Add no new public + route API or compatibility shim to make the privatization pass. +- Fix the in-tree Rust callers of `routed` and `routed_broadcast` that this + deletion breaks (the CLI, gateway, mux binding, relay HTTP), keeping their + route-change retry where they need it. Reworking their resolution logic + beyond the rename belongs to [Callers resolve once](/quest/m1/api-audit/resolve/callers.md). + +Tests: an announced but unwatched path over lite-05, 06 and 07-wip; synced +absence; discovery retention and release; pinned follow return; unchanged +explicit refusal. + +Public API: breaking in moq-net, with an Impact migration note. Wire: none. diff --git a/quest/m1/ts-reliability/README.md b/quest/m1/ts-reliability/README.md index 2263286d940..1a5fc0bc8a2 100644 --- a/quest/m1/ts-reliability/README.md +++ b/quest/m1/ts-reliability/README.md @@ -102,6 +102,7 @@ catalog linger (#5305). - [A timebase step restarts the TS import](/quest/m1/ts-reliability/step-restart.md) - an unflagged step or a rewind republishes under a new epoch instead of ending the import and every subscriber's export - [Export re-acquires a step](/quest/m1/ts-reliability/export-reacquire.md) - `moq export ts` re-acquires an unmarked timeline step instead of exiting on fake drift - [A restart keeps its catalog](/quest/m1/ts-reliability/restart-catalog.md) - a restarted import publishes its catalog with its first media +- [Tables from current state](/quest/m1/ts-reliability/psi-state.md) - the TS export lays its PAT and PMT from current state when their slot comes up, with byte-identical output for a static program - [PAT changes](/quest/m1/ts-reliability/pat-lifecycle.md) - a running export follows a moved PMT PID - [A demoted subscriber priority reaches the publisher](/quest/m1/ts-reliability/stitch-catch-up.md) - a mid-stream priority demotion reaches the publisher on lite-07 and moq-transport, including an old instance after an epoch switch diff --git a/quest/m1/ts-reliability/pat-lifecycle.md b/quest/m1/ts-reliability/pat-lifecycle.md index b101662f07a..d78ca6172cf 100644 --- a/quest/m1/ts-reliability/pat-lifecycle.md +++ b/quest/m1/ts-reliability/pat-lifecycle.md @@ -21,7 +21,9 @@ The maintainer's plan, from closing follows a new `program.pmtPid` with a new PAT, built on the table rework that lays the PAT and PMT from the current table state when their slot is laid instead of riding queued units, so a move is one more state change -rather than a rewrite of queued copies. That rework has not landed. +rather than a rewrite of queued copies. That rework is its own quest, +[tables from current state](/quest/m1/ts-reliability/psi-state.md) +(planned 2026-10-28), so this quest keeps only the PMT move and its tests. The draft then says that `pmtPid` can change in place, and when a consumer rebuilding the stream moves the PMT. @@ -34,3 +36,7 @@ old one after it, and a move while every copy is still queued goes out as one PAT naming the new PID. `revision_test`'s `a_track_recorded_on_the_pmt_pid_after_the_catalog_moves_it_takes_another` then pins the move instead of the PMT staying put. + +## Required + +- [Tables from current state](/quest/m1/ts-reliability/psi-state.md) - the export lays the PAT and PMT from current state, so a move is one more state change diff --git a/quest/m1/ts-reliability/psi-state.md b/quest/m1/ts-reliability/psi-state.md new file mode 100644 index 00000000000..857bc42adc9 --- /dev/null +++ b/quest/m1/ts-reliability/psi-state.md @@ -0,0 +1,29 @@ +# [M] The TS export lays its tables from current state + +## Goal + +The TS export lays its PAT and PMT from the current table state when their +slot comes up, as `--sync` already does, instead of carrying queued copies +alongside media units. A static program's output is byte-identical to today. + +## Plan + +Planned 2026-10-28 (maintainer). The maintainer named this rework when +closing [moq-dev/moq#6301](https://github.com/moq-dev/moq/pull/6301): the +export's table handling from +[moq-dev/moq#6289](https://github.com/moq-dev/moq/pull/6289) queues copies of +the PAT and PMT with media units, so a table change rewrites queued copies. +Laying each table from current state when its slot is laid makes a change +one more state update, which [PAT changes](/quest/m1/ts-reliability/pat-lifecycle.md) +builds on. + +- Reuse what `--sync` already does to lay tables, rather than adding a second + path. +- Keep #6289's revision rule: a PMT revision goes out at the next version. +- Prove byte-identical output on the existing export fixtures and round + trips, and keep the T-STD schedule and the opening order from + [moq-dev/moq#7048](https://github.com/moq-dev/moq/pull/7048) unchanged. + +Rust: `rs/moq-mux` TS export (`build_psi`, the PSI schedule). + +Public API: none. Wire: none.