Repository navigation
docs(quest): plan follow-ups from the 2026-09-23 quest wave #3974
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
1fd970e
a0bfd1d
2485dfe
8c84a76
27f2ef7
8fcfe02
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. | ||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
The revised conditional on line 19 is fresh evidence that the earlier omission remains: regenerating AGENTS.md reference: AGENTS.md:L105-L105 Useful? React with 👍 / 👎. |
||
| - Update `doc/lib/{py,swift,kt,go,dart,c}` in the same PR. | ||
|
kixelated marked this conversation as resolved.
Resolved
|
||
| - 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 | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,22 @@ | ||
| # [S] Fetching a missing group fails before any output | ||
|
|
||
| ## Goal | ||
|
|
||
| HTTP `/fetch/<broadcast>/<track>?group=N` answers 404 for a group the track | ||
| does not have, and `moq fetch --group N` exits with a clean "not found" | ||
|
kixelated marked this conversation as resolved.
Resolved
|
||
| 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 | ||
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
|
|
@@ -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 | ||||||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win 🔎 Supported by static analysis🏁 Script executed: set -eu
printf '%s\n' '--- diff stat ---'
git diff --stat b79ee841710934ca8927ab58c122c35a8c172370 8fcfe021d87563a4cfac2970ae390521080f9772 -- quest/m1/perf
printf '%s\n' '--- changed diff ---'
git diff --unified=40 b79ee841710934ca8927ab58c122c35a8c172370 8fcfe021d87563a4cfac2970ae390521080f9772 -- quest/m1/perf/README.md quest/m1/perf/json-decode.md
printf '%s\n' '--- perf files ---'
git ls-files quest/m1/perf
printf '%s\n' '--- 10x references ---'
rg -n -i '10x|allocation|allocations|benchmark|baseline|stats decode|json snapshot' quest/m1/perfRepository: moq-dev/moq Length of output: 10816 🤖 get_repo_knowledge executed:
Length of output: 47441 Describe the 10x reduction as a target. The quest plan requires recovering the benchmark and recording the baseline before reporting a measured result. Until that measurement is recorded, use target wording in both entries. Suggested wording- [JSON snapshot decode](/quest/m1/perf/json-decode.md) - moq-json patches the typed value, cutting stats decode allocations by more than 10x
+ [JSON snapshot decode](/quest/m1/perf/json-decode.md) - moq-json patches the typed value, targeting a more-than-10x reduction in stats decode allocations-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.
+At 4096 broadcasts the stats decode costs about 400k allocations per tick today; the goal is to reduce it by more than 10x on a stats decode benchmark, with the same wire.📝 Committable suggestion
Suggested change
📍 Affects 2 files
🤖 Prompt for AI Agents |
||||||
| - [#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 | ||||||
|
|
||||||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. | ||
|
Comment on lines
+16
to
+18
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
For the stats AGENTS.md reference: AGENTS.md:L52-L59 Useful? React with 👍 / 👎. |
||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. | ||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
When this plan is implemented, adding the literal AGENTS.md reference: AGENTS.md:L81-L90 Useful? React with 👍 / 👎. |
||
| - 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 | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Clarify the connection-timing scope.
rs/libmoq/src/api.rs:927-1022already declaresfailover_delay_usandresolution_delay_uswith presence flags.rs/libmoq/src/client.rs:29-127already maps them into the client configuration. Describing these fields as landed only in Rust could prompt duplicate C API work. Clarify whether this quest targets wrapper exposure, documentation, and tests for the existing fields.🤖 Prompt for AI Agents