diff --git a/quest/m1/README.md b/quest/m1/README.md index 860cc978deb..4f7274f83f4 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -17,9 +17,13 @@ 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 - [Hidden broadcasts](/quest/m1/hidden-broadcasts.md) - announce discovery skips `.`-named paths unless a request opts in over lite-07 or an IETF parameter, so older clients (bar authenticated cluster peers during rollout) never see them - [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, 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 - [FFI shape](/quest/m1/ffi-shape/README.md) - the bindings mirror Rust's layers: net at the root, then media, json, audio, and video namespaces built from the handle below - [Track demand](/quest/m1/track-demand.md) - Rust and JS watch a track's subscribers through `demand()` alone diff --git a/quest/m1/auth-expiry-clock.md b/quest/m1/auth-expiry-clock.md new file mode 100644 index 00000000000..89d7e3b892b --- /dev/null +++ b/quest/m1/auth-expiry-clock.md @@ -0,0 +1,25 @@ +# [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 + +- 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 new file mode 100644 index 00000000000..db6b94268cf --- /dev/null +++ b/quest/m1/binding-surface.md @@ -0,0 +1,31 @@ +# [M] The bindings reach the new decode, route, and connection APIs + +## Goal + +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 +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. +- libmoq gets the decode delay and route source in `rs/libmoq` itself, with + 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. + +## Required + +- Native decode delay (#3967) has merged +- Route source (#3972) has merged +- moq-ffi WebSocket fallback settings (#3961) have merged + +## Related + +- [FFI shape](/quest/m1/ffi-shape/README.md) - reshapes the flat methods this adds diff --git a/quest/m1/fetch-missing-group.md b/quest/m1/fetch-missing-group.md new file mode 100644 index 00000000000..ae1002961e3 --- /dev/null +++ b/quest/m1/fetch-missing-group.md @@ -0,0 +1,22 @@ +# [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. + +## Required + +- `moq fetch` (#3965) has merged 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..9c53d8536a7 --- /dev/null +++ b/quest/m1/perf/json-decode.md @@ -0,0 +1,18 @@ +# [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 a stats decode benchmark, with the same wire. + +## Plan + +- 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 new file mode 100644 index 00000000000..2efdd2c7bb1 --- /dev/null +++ b/quest/m1/play-harness.md @@ -0,0 +1,25 @@ +# [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 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. + +## 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