Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion quest/m1/api-audit/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
78 changes: 0 additions & 78 deletions quest/m1/api-audit/resolve.md

This file was deleted.

60 changes: 60 additions & 0 deletions quest/m1/api-audit/resolve/README.md
Original file line number Diff line number Diff line change
@@ -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
25 changes: 25 additions & 0 deletions quest/m1/api-audit/resolve/bindings.md
Original file line number Diff line number Diff line change
@@ -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
28 changes: 28 additions & 0 deletions quest/m1/api-audit/resolve/callers.md
Original file line number Diff line number Diff line change
@@ -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
25 changes: 25 additions & 0 deletions quest/m1/api-audit/resolve/js.md
Original file line number Diff line number Diff line change
@@ -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.
32 changes: 32 additions & 0 deletions quest/m1/api-audit/resolve/rust.md
Original file line number Diff line number Diff line change
@@ -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.
1 change: 1 addition & 0 deletions quest/m1/ts-reliability/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
8 changes: 7 additions & 1 deletion quest/m1/ts-reliability/pat-lifecycle.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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
29 changes: 29 additions & 0 deletions quest/m1/ts-reliability/psi-state.md
Original file line number Diff line number Diff line change
@@ -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.
Loading