From 1fd970e02b5fac78b481f27766df24322633b8a6 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 23 Sep 2026 11:58:19 -0700 Subject: [PATCH 1/4] docs(quest): plan follow-ups from the 2026-09-23 quest wave Co-Authored-By: Claude Opus 5.5 --- quest/m1/README.md | 4 ++++ quest/m1/auth-expiry-clock.md | 19 +++++++++++++++++++ quest/m1/binding-surface.md | 24 ++++++++++++++++++++++++ quest/m1/fetch-missing-group.md | 18 ++++++++++++++++++ quest/m1/perf/README.md | 1 + quest/m1/perf/json-decode.md | 17 +++++++++++++++++ quest/m1/play-harness.md | 23 +++++++++++++++++++++++ 7 files changed, 106 insertions(+) create mode 100644 quest/m1/auth-expiry-clock.md create mode 100644 quest/m1/binding-surface.md create mode 100644 quest/m1/fetch-missing-group.md create mode 100644 quest/m1/perf/json-decode.md create mode 100644 quest/m1/play-harness.md diff --git a/quest/m1/README.md b/quest/m1/README.md index 1bbdba0c12d..ebee9066040 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -17,8 +17,12 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. ## Quests +- [Play harness](/quest/m1/play-harness.md) - moq play's tune-in, rendition-switch, and drain logic runs in per-PR CI without a device +- [Missing fetch group](/quest/m1/fetch-missing-group.md) - HTTP /fetch answers 404 and `moq fetch` fails cleanly for a group the track lacks +- [Auth expiry clock](/quest/m1/auth-expiry-clock.md) - moq-auth and the relay hold one fixed expiry deadline and honour the same skew allowance - [Origin narrowing](/quest/m1/origin-narrowing.md) - a live origin grant narrows in place and ends the subscriptions it no longer covers, the deafen boundary #2714 asked for - [Auth embedder](/quest/m1/auth-embedder.md) - the lease owns its re-check clock, a gateway session holds a lease, and `Cluster::admit` scopes and tags origins in one call +- [Binding surface](/quest/m1/binding-surface.md) - moq-ffi and every wrapper expose the decode delay, route source, and connection timing - [Binding docs](/quest/m1/binding-docs.md) - every binding doc sample names a symbol that exists, checked nightly - [Go vanity docs](/quest/m1/go-vanity-docs.md) - the Go page names only `moq.dev/moq` again, reverting #3847 - [Gateway embedding](/quest/m1/gateway-embed.md) - moq-hls, moq-rtmp, and moq-rtc expose the loop their binaries run to an in-process embedder diff --git a/quest/m1/auth-expiry-clock.md b/quest/m1/auth-expiry-clock.md new file mode 100644 index 00000000000..e8f09398247 --- /dev/null +++ b/quest/m1/auth-expiry-clock.md @@ -0,0 +1,19 @@ +# [S] Grant expiry is one fixed deadline everywhere + +## Goal + +A grant's expiry is a deadline fixed when the grant arrives, in both +`moq-auth`'s `Client::drive` and the relay, and both honour `moq-auth`'s 5 s +clock-skew allowance. Today `Client::drive` recomputes the time left from the +wall clock on every re-check, so the countdown restarts, and the relay ignores +the skew allowance, so a grant just past expiry stays live in the client but +ends immediately in the relay. + +## Plan + +- `Client::drive` sets its deadline once per grant and measures it on the + tokio clock, so its outage tests run on a paused clock like the relay's + (#3969 fixed the relay side). +- Apply the skew allowance in one place both sides share. +- Test: re-polling keeps the deadline; a grant within the skew window is live + on both sides; the client outage tests run on a paused clock. diff --git a/quest/m1/binding-surface.md b/quest/m1/binding-surface.md new file mode 100644 index 00000000000..62d2f29c7cc --- /dev/null +++ b/quest/m1/binding-surface.md @@ -0,0 +1,24 @@ +# [M] The bindings reach the new decode, route, and connection APIs + +## Goal + +moq-ffi and every wrapper (Python, Go, Swift, Kotlin, Dart) expose three +surfaces that landed in Rust only: the audio decode delay +(`decode::Options::delay` and `Consumer::delay()`), where a route came from +(`Route::source()` and `origin::Consumer::local()`), and libmoq's connection +timing (`failover_delay_us`, `resolution_delay_us`) beside the WebSocket +fallback settings. moq.pro's Python sidecar reads route sources from here. + +## Plan + +- One PR, each wrapper touched once, in its own idiom: durations as the + language's duration type where the wrapper already uses one, handles over + flat methods where a surface has more than one call. +- Update `doc/lib/{py,swift,kt,go,dart,c}` in the same PR. +- Test each surface in every wrapper that has tests. + +## Required + +- Native decode delay (#3967) has merged +- Route source (#3972) has merged +- moq-ffi WebSocket fallback settings (#3961) have merged diff --git a/quest/m1/fetch-missing-group.md b/quest/m1/fetch-missing-group.md new file mode 100644 index 00000000000..e144de69aa7 --- /dev/null +++ b/quest/m1/fetch-missing-group.md @@ -0,0 +1,18 @@ +# [S] Fetching a missing group fails before any output + +## Goal + +HTTP `/fetch//?group=N` answers 404 for a group the track +does not have, and `moq fetch --group N` exits with a clean "not found" +before writing anything. Today the lookup hands back a group consumer that +only fails on its first frame read, so the endpoint answers 200 with a +cut-off body. + +## Plan + +- Resolve whether the group exists before the response starts, in the + shared lookup the relay and the CLI both use. Where the check belongs (the + relay helper or a `moq-net` track consumer method) is the implementer's + call; propose it in the PR. +- Test: a missing group is a 404 over HTTP and a non-zero `moq fetch` exit + with no stdout; an existing group is byte-identical to today. diff --git a/quest/m1/perf/README.md b/quest/m1/perf/README.md index b1a0a9cf4ff..914a05054af 100644 --- a/quest/m1/perf/README.md +++ b/quest/m1/perf/README.md @@ -49,6 +49,7 @@ row per io_uring worker. - [Ingest batch](/quest/m1/perf/ingest-batch.md) - relay ingest pays one lock, wake, and clock read per chunk burst instead of per chunk - [Egress cache refresh](/quest/m1/perf/egress-keepalive.md) - measure refresh costs while preserving slow-reader retention - [Owned decoding copies](/quest/m1/perf/coding-decode.md) - measure and reduce owned decode allocations and copies +- [JSON snapshot decode](/quest/m1/perf/json-decode.md) - moq-json patches the typed value, cutting stats decode allocations by more than 10x - [#3122](/quest/m1/perf/3122-moq-uring-2-5-of-relay-cpu-is-vdso-clock-reads-the-drive.md) - moq-uring: ~2.5% of relay CPU is vdso clock reads; the drive loop and its callers each re-read Instant::now() - [Cache shard](/quest/m1/perf/cache-shard.md) - stop hammering one process-global cache line from every worker - [#3199](/quest/m1/perf/3199-moq-uring-remove-sq-indirection-and-per-enter-ring-fd.md) - moq-uring: remove SQ indirection and per-enter ring fd lookup diff --git a/quest/m1/perf/json-decode.md b/quest/m1/perf/json-decode.md new file mode 100644 index 00000000000..b85fd55b393 --- /dev/null +++ b/quest/m1/perf/json-decode.md @@ -0,0 +1,17 @@ +# [M] moq-json snapshot decode patches the typed value + +## Goal + +Decoding a `.json.z` snapshot frame applies its patch to the typed value +instead of merging into a `serde_json::Value` and deserializing again. At +4096 broadcasts the stats decode costs about 400k allocations per tick today; +it drops by more than 10x on the stats benchmark #3955 added, with the same +wire. + +## Plan + +- Profile the current decode on that benchmark first and record the baseline + in the PR. +- Patch in place on the typed value where the shape allows it; fall back to + the `Value` merge only for shapes that cannot be patched, and say which. +- Public API: none expected. Wire: none. diff --git a/quest/m1/play-harness.md b/quest/m1/play-harness.md new file mode 100644 index 00000000000..8413d1621c0 --- /dev/null +++ b/quest/m1/play-harness.md @@ -0,0 +1,23 @@ +# [M] moq play's task logic runs in CI without a device + +## Goal + +`moq play`'s media tasks (`rs/moq-cli/src/play/media.rs`: tune-in, rendition +switches, drains, and the playout queue) run in CI tests on every PR, without +a speaker, window, or display. Today the module sits behind the `play` +feature, which CI only compiles in the nightly clippy run, so its regressions +(#3946's tune-in burst, #3966's rendition-switch gap) are measured by hand. + +## Plan + +- Separate the task logic from the device: the tasks talk to a sink and a + wake handle the test replaces with a fake that records what was played and + when, on a paused tokio clock. Keep the seam private to `moq-cli`; no + test-only hooks in production paths beyond it. +- Run `cargo test -p moq-cli --features play` in the per-PR Test job, headless. +- Land the rendition-switch gap test from #3966 and the tune-in burst test + from #3946 on it, each failing without its fix. + +## Related + +- [Play tune-in backpressure](/quest/m1/play-tunein-backpressure.md) - its regression test runs here From 2485dfecec27b1502c3cf61d2c3a70082df6d313 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 23 Sep 2026 12:47:30 -0700 Subject: [PATCH 2/4] docs(quest): record follow-up prerequisites Co-Authored-By: Claude Opus 5.5 --- quest/m1/auth-expiry-clock.md | 4 ++++ quest/m1/fetch-missing-group.md | 4 ++++ quest/m1/perf/json-decode.md | 9 +++++---- quest/m1/play-harness.md | 10 ++++++++-- 4 files changed, 21 insertions(+), 6 deletions(-) diff --git a/quest/m1/auth-expiry-clock.md b/quest/m1/auth-expiry-clock.md index e8f09398247..a3e2dde2c64 100644 --- a/quest/m1/auth-expiry-clock.md +++ b/quest/m1/auth-expiry-clock.md @@ -17,3 +17,7 @@ ends immediately in the relay. - Apply the skew allowance in one place both sides share. - Test: re-polling keeps the deadline; a grant within the skew window is live on both sides; the client outage tests run on a paused clock. + +## Required + +- The relay's fixed expiry deadline (#3969) has merged diff --git a/quest/m1/fetch-missing-group.md b/quest/m1/fetch-missing-group.md index e144de69aa7..ae1002961e3 100644 --- a/quest/m1/fetch-missing-group.md +++ b/quest/m1/fetch-missing-group.md @@ -16,3 +16,7 @@ cut-off body. call; propose it in the PR. - Test: a missing group is a 404 over HTTP and a non-zero `moq fetch` exit with no stdout; an existing group is byte-identical to today. + +## Required + +- `moq fetch` (#3965) has merged diff --git a/quest/m1/perf/json-decode.md b/quest/m1/perf/json-decode.md index b85fd55b393..9c53d8536a7 100644 --- a/quest/m1/perf/json-decode.md +++ b/quest/m1/perf/json-decode.md @@ -5,13 +5,14 @@ Decoding a `.json.z` snapshot frame applies its patch to the typed value instead of merging into a `serde_json::Value` and deserializing again. At 4096 broadcasts the stats decode costs about 400k allocations per tick today; -it drops by more than 10x on the stats benchmark #3955 added, with the same -wire. +it drops by more than 10x on a stats decode benchmark, with the same wire. ## Plan -- Profile the current decode on that benchmark first and record the baseline - in the PR. +- Land the benchmark first: recover the `.json.z` half of the stats + benchmark from #3955's prototype commit `d86496be2` (1 to 4096 broadcasts, + 1 or 4 tiers, 100% or 10% changed per tick), which that PR does not merge. + Record the baseline in the PR. - Patch in place on the typed value where the shape allows it; fall back to the `Value` merge only for shapes that cannot be patched, and say which. - Public API: none expected. Wire: none. diff --git a/quest/m1/play-harness.md b/quest/m1/play-harness.md index 8413d1621c0..63b9047db38 100644 --- a/quest/m1/play-harness.md +++ b/quest/m1/play-harness.md @@ -15,9 +15,15 @@ feature, which CI only compiles in the nightly clippy run, so its regressions when, on a paused tokio clock. Keep the seam private to `moq-cli`; no test-only hooks in production paths beyond it. - Run `cargo test -p moq-cli --features play` in the per-PR Test job, headless. -- Land the rendition-switch gap test from #3966 and the tune-in burst test - from #3946 on it, each failing without its fix. +- Land the rendition-switch gap test on it, failing without #3966's fix. + The tune-in burst test moves onto the harness with + [Play tune-in backpressure](/quest/m1/play-tunein-backpressure.md), which + owns that fix. ## Related - [Play tune-in backpressure](/quest/m1/play-tunein-backpressure.md) - its regression test runs here + +## Required + +- The rendition-switch gap fix (#3966) has merged From 8c84a768b9db41912d2c71a99976a0789fd2f72d Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 23 Sep 2026 13:20:21 -0700 Subject: [PATCH 3/4] docs(quest): require the play harness for tune-in, add libmoq to binding scope Co-Authored-By: Claude Opus 5.5 --- quest/m1/binding-surface.md | 8 ++++++-- quest/m1/play-harness.md | 4 ---- quest/m1/play-tunein-backpressure.md | 4 ++++ 3 files changed, 10 insertions(+), 6 deletions(-) diff --git a/quest/m1/binding-surface.md b/quest/m1/binding-surface.md index 62d2f29c7cc..e239dd22d7a 100644 --- a/quest/m1/binding-surface.md +++ b/quest/m1/binding-surface.md @@ -2,8 +2,8 @@ ## Goal -moq-ffi and every wrapper (Python, Go, Swift, Kotlin, Dart) expose three -surfaces that landed in Rust only: the audio decode delay +moq-ffi, libmoq, and every wrapper (Python, Go, Swift, Kotlin, Dart) expose +three surfaces that landed in Rust only: the audio decode delay (`decode::Options::delay` and `Consumer::delay()`), where a route came from (`Route::source()` and `origin::Consumer::local()`), and libmoq's connection timing (`failover_delay_us`, `resolution_delay_us`) beside the WebSocket @@ -14,8 +14,12 @@ fallback settings. moq.pro's Python sidecar reads route sources from here. - One PR, each wrapper touched once, in its own idiom: durations as the language's duration type where the wrapper already uses one, handles over flat methods where a surface has more than one call. +- libmoq gets the decode delay and route source in `rs/libmoq` itself, with + tests, not only in the C docs; regenerate `moq.h`. - Update `doc/lib/{py,swift,kt,go,dart,c}` in the same PR. - Test each surface in every wrapper that has tests. +- This adds methods in today's flat FFI shape; FFI shape (#3976) reshapes + them later. ## Required diff --git a/quest/m1/play-harness.md b/quest/m1/play-harness.md index 63b9047db38..2efdd2c7bb1 100644 --- a/quest/m1/play-harness.md +++ b/quest/m1/play-harness.md @@ -20,10 +20,6 @@ feature, which CI only compiles in the nightly clippy run, so its regressions [Play tune-in backpressure](/quest/m1/play-tunein-backpressure.md), which owns that fix. -## Related - -- [Play tune-in backpressure](/quest/m1/play-tunein-backpressure.md) - its regression test runs here - ## Required - The rendition-switch gap fix (#3966) has merged diff --git a/quest/m1/play-tunein-backpressure.md b/quest/m1/play-tunein-backpressure.md index 2ecc1fe0091..bb20b74b80a 100644 --- a/quest/m1/play-tunein-backpressure.md +++ b/quest/m1/play-tunein-backpressure.md @@ -34,6 +34,10 @@ Either way the regression test is a video-only burst larger than the queue with a delay wider than the queue holds, asserting the clock ends up at the live edge rather than a delay behind it. +## Required + +- [Play harness](/quest/m1/play-harness.md) - the regression test runs on it + ## Related - [Playout clock](https://github.com/moq-dev/moq/pull/3528) - added the clock this bounds From 27f2ef7c3f943594c5b4c6ea8494207cd5a0a449 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 23 Sep 2026 13:35:30 -0700 Subject: [PATCH 4/4] docs(quest): build auth expiry on the lease clock, scope OBS in bindings Co-Authored-By: Claude Opus 5.5 --- quest/m1/README.md | 2 +- quest/m1/auth-expiry-clock.md | 8 +++++--- quest/m1/binding-surface.md | 3 ++- 3 files changed, 8 insertions(+), 5 deletions(-) diff --git a/quest/m1/README.md b/quest/m1/README.md index ebee9066040..e082683b879 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -22,7 +22,7 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [Auth expiry clock](/quest/m1/auth-expiry-clock.md) - moq-auth and the relay hold one fixed expiry deadline and honour the same skew allowance - [Origin narrowing](/quest/m1/origin-narrowing.md) - a live origin grant narrows in place and ends the subscriptions it no longer covers, the deafen boundary #2714 asked for - [Auth embedder](/quest/m1/auth-embedder.md) - the lease owns its re-check clock, a gateway session holds a lease, and `Cluster::admit` scopes and tags origins in one call -- [Binding surface](/quest/m1/binding-surface.md) - moq-ffi and every wrapper expose the decode delay, route source, and connection timing +- [Binding surface](/quest/m1/binding-surface.md) - moq-ffi, libmoq, and every wrapper expose the decode delay, route source, and connection timing - [Binding docs](/quest/m1/binding-docs.md) - every binding doc sample names a symbol that exists, checked nightly - [Go vanity docs](/quest/m1/go-vanity-docs.md) - the Go page names only `moq.dev/moq` again, reverting #3847 - [Gateway embedding](/quest/m1/gateway-embed.md) - moq-hls, moq-rtmp, and moq-rtc expose the loop their binaries run to an in-process embedder diff --git a/quest/m1/auth-expiry-clock.md b/quest/m1/auth-expiry-clock.md index a3e2dde2c64..89d7e3b892b 100644 --- a/quest/m1/auth-expiry-clock.md +++ b/quest/m1/auth-expiry-clock.md @@ -11,13 +11,15 @@ ends immediately in the relay. ## Plan -- `Client::drive` sets its deadline once per grant and measures it on the - tokio clock, so its outage tests run on a paused clock like the relay's - (#3969 fixed the relay side). +- Build on the lease clock auth-embedder introduces: `lease::Producer` sets + its deadline once per grant and measures it on the tokio clock, so the + client's outage tests run on a paused clock like the relay's (#3969 fixed + the relay side). - Apply the skew allowance in one place both sides share. - Test: re-polling keeps the deadline; a grant within the skew window is live on both sides; the client outage tests run on a paused clock. ## Required +- [Auth embedder](/quest/m1/auth-embedder.md) - introduces the lease clock this fixes - The relay's fixed expiry deadline (#3969) has merged diff --git a/quest/m1/binding-surface.md b/quest/m1/binding-surface.md index e239dd22d7a..e4d597c49a1 100644 --- a/quest/m1/binding-surface.md +++ b/quest/m1/binding-surface.md @@ -15,7 +15,8 @@ fallback settings. moq.pro's Python sidecar reads route sources from here. language's duration type where the wrapper already uses one, handles over flat methods where a surface has more than one call. - libmoq gets the decode delay and route source in `rs/libmoq` itself, with - tests, not only in the C docs; regenerate `moq.h`. + tests, not only in the C docs; regenerate `moq.h`. The additions are + additive, so `cpp/obs/src` and `doc/bin/obs.md` change only if OBS uses them. - Update `doc/lib/{py,swift,kt,go,dart,c}` in the same PR. - Test each surface in every wrapper that has tests. - This adds methods in today's flat FFI shape; FFI shape (#3976) reshapes