diff --git a/quest/m0/ci/README.md b/quest/m0/ci/README.md index e7414fffb59..a96b24693d7 100644 --- a/quest/m0/ci/README.md +++ b/quest/m0/ci/README.md @@ -163,3 +163,4 @@ The historical samples locate candidates; they are not controlled benchmarks. - [Release credentials off main](/quest/m0/ci/publish-release-only.md) - `publish` admits only `release` and release tags once its `workflow_run` publishers run on their tag - [The queue host keeps the queue's disk](/quest/m0/ci/queue-host-disk.md) - agent sessions can't starve the queue runner of disk, and a crashed runner restarts - [Biome checks every file it can parse](/quest/m0/ci/biome-whole-repo.md) - Biome runs over the whole repository and main is clean under it +- [One nextest pin](/quest/m0/ci/nextest-pin.md) - cargo-nextest's version lives in one place diff --git a/quest/m0/ci/nextest-pin.md b/quest/m0/ci/nextest-pin.md new file mode 100644 index 00000000000..36cb925a954 --- /dev/null +++ b/quest/m0/ci/nextest-pin.md @@ -0,0 +1,15 @@ +# [XS] One nextest pin + +## Goal + +The cargo-nextest version is pinned in one place. Today it's written three +times, all at 0.9.146: `platform.yml`'s Windows and macOS jobs +(`tool: nextest@0.9.146`), and `.oss-scanner/Dockerfile`'s `NEXTEST_VERSION` +build arg. + +## Plan + +Planned 2026-11-01 (maintainer, follow-up planning after the 2026-11-01 /quest-complete run). Raised by [moq-dev/moq#7217](https://github.com/moq-dev/moq/pull/7217), +which pinned the Dockerfile to match. Use whatever mechanism the workflows +already share for pins, such as a shared action, a repo variable, or a file +the jobs read, and keep the Dockerfile reading the same value. diff --git a/quest/m0/test-flakes-2/README.md b/quest/m0/test-flakes-2/README.md index 0a53c93816c..7a304e10420 100644 --- a/quest/m0/test-flakes-2/README.md +++ b/quest/m0/test-flakes-2/README.md @@ -62,4 +62,7 @@ Public API: none. Wire: none. - [IETF22 fallback](/quest/m0/test-flakes-2/ietf22-fallback.md) - an IETF22 browser viewer follows a fallback within the media lane's bound, keeping its session and its audio - [Draft-22 interop with a native publisher](/quest/m0/test-flakes-2/draft22-interop.md) - no "invalid fetch range" or audio gap with a Rust or C++ publisher +- [moq-tokio's close-drain test survives load](/quest/m0/test-flakes-2/tokio-close-drain.md) - `quic_client_close_drains_finished_track` stops failing land batches with "Unroutable" +- [@moq/net's close-drain tests survive load](/quest/m0/test-flakes-2/js-close-drain.md) - the lite close-drain cases pass on every full suite run +- [@moq/net's boundary-sync test survives load](/quest/m0/test-flakes-2/js-boundary-sync.md) - "a version without a boundary syncs" passes under load - [A Kotlin cancel test and a JS late-publisher test hold up](/quest/m0/test-flakes-2/kotlin-js-flakes.md) - the Kotlin flow-cancel test stops failing `unroutable` and the IETF blind-handle test passes under load diff --git a/quest/m0/test-flakes-2/js-boundary-sync.md b/quest/m0/test-flakes-2/js-boundary-sync.md new file mode 100644 index 00000000000..a2f34752c7b --- /dev/null +++ b/quest/m0/test-flakes-2/js-boundary-sync.md @@ -0,0 +1,15 @@ +# [XS] @moq/net's boundary-sync test survives load + +## Goal + +"a version without a boundary syncs once the request is out" +(`js/net/src/lite/subscriber.test.ts`, around line 2895) passes on every full +`@moq/net` suite run. + +## Plan + +Planned 2026-11-01 (maintainer, follow-up planning after the 2026-11-01 /quest-complete run). It failed once in a full run under load during +[moq-dev/moq#7371](https://github.com/moq-dev/moq/pull/7371), and passed 5 of 5 +runs alone. Find the ordering it assumes, and drive it with the manual clock. + +Follow the rules in [More tests under load](/quest/m0/test-flakes-2/README.md). diff --git a/quest/m0/test-flakes-2/js-close-drain.md b/quest/m0/test-flakes-2/js-close-drain.md new file mode 100644 index 00000000000..fc8e79f30e8 --- /dev/null +++ b/quest/m0/test-flakes-2/js-close-drain.md @@ -0,0 +1,25 @@ +# [S] @moq/net's close-drain tests survive load + +## Goal + +The `js/net/src/lite/connection.test.ts` close-drain cases, including "a peer +close drains the overtaken fin over moq-lite-0x", pass on every full +`@moq/net` suite run. They're fixed at their cause, never by raising a +timeout or adding a retry. + +## Plan + +Planned 2026-11-01 (maintainer, follow-up planning after the 2026-11-01 /quest-complete run). The cases fail 3 to 4 times per full-suite run on main and pass when the +file runs alone. Three agents hit this on 2026-11-01: +[moq-dev/moq#7367](https://github.com/moq-dev/moq/pull/7367), +[moq-dev/moq#7489](https://github.com/moq-dev/moq/pull/7489) (3 of 570 runs on +main), and [moq-dev/moq#7296](https://github.com/moq-dev/moq/pull/7296)'s +area. One failure fails a whole land batch's `test js`. + +#7296 has since landed and reworked these cases (lite-05/06 now wait for the +subscriber's FIN), so first reproduce the flake on main as it is now. + +Look for wall-clock waits, or ordering that depends on the event loop's load, +and drive them with the manual clock. + +Follow the rules in [More tests under load](/quest/m0/test-flakes-2/README.md). diff --git a/quest/m0/test-flakes-2/tokio-close-drain.md b/quest/m0/test-flakes-2/tokio-close-drain.md new file mode 100644 index 00000000000..bafbd08cca4 --- /dev/null +++ b/quest/m0/test-flakes-2/tokio-close-drain.md @@ -0,0 +1,25 @@ +# [S] moq-tokio's close-drain test survives load + +## Goal + +`moq-tokio::integration backend::quic_client_close_drains_finished_track` +(`rs/moq-tokio/tests/integration/backend.rs`) passes reliably under a loaded +`just ci`. It's fixed at its cause, never by raising a timeout or adding a +retry. + +## Plan + +Planned 2026-11-01 (maintainer, follow-up planning after the 2026-11-01 /quest-complete run). The test failed with "subscribe failed: Unroutable" and passed on rerun. +On 2026-11-01 it ejected two land batches, at 20:24Z and 20:44Z (see +[moq-dev/moq#7258](https://github.com/moq-dev/moq/pull/7258) and +[moq-dev/moq#7439](https://github.com/moq-dev/moq/pull/7439)), and it failed +once in [moq-dev/moq#7490](https://github.com/moq-dev/moq/pull/7490)'s full +run. + +- It runs on moq-lite (`moq-lite-07-wip`, around line 801). Find the race that + lets the subscribe reach the publisher before its route exists, or after the + route has gone. +- Reproduce it under load first, for example by running it beside a full + `cargo nextest`. + +Follow the rules in [More tests under load](/quest/m0/test-flakes-2/README.md). diff --git a/quest/m1/README.md b/quest/m1/README.md index bbbeb62b6ef..0fc72701be8 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -150,6 +150,11 @@ per-frame CPU growth since #5926. - [Subscribe ranges](/quest/m1/subscribe-ranges/README.md) - a lite-07 SUBSCRIBE asks for past and live ranges with absolute or relative ends, in either order, and replaces FETCH; merged ranges never starve a subscriber; relays fill misses by range, including over moq-transport - [Drop set](/quest/m1/drop-set.md) - each cursor judges missing groups against its own budget, so a narrow reader drops promptly and a widening re-offers groups already reported dropped on lite-07 - [Subscriptions take a Delay { min, max }](/quest/m1/subscription-delay.md) - one Delay type across every subscription API, and omitted max means 0 in every binding +- [A step back smaller than the delay keeps the TS export](/quest/m1/ts-small-step-back.md) - audio restarts instead of regressing; video stays within its declared depth +- [A replaced copy's grace wakes its reader](/quest/m1/grace-deadline.md) - the grace arms a deadline, so a clean end is on time +- [moq-boy's status loop stops on an errored track](/quest/m1/moq-boy-status-loop.md) - only schema errors are caught +- [JS tests and docs say what keeps a group cached](/quest/m1/js-cache-window.md) - none assume maxAge is retention +- [release carries the fanout-threads bench](/quest/m1/release-fanout-bench.md) - a bench-only port of session_fanout_threads for the pre-cut pairing - [Finalize moq-lite-07](/quest/m1/lite07-finalize.md) - when the maintainer cuts it, lite-07 negotiates as `moq-lite-07` and the next release ships it - [Moxygen pin bump](/quest/m1/moxygen-pin-bump.md) - waiting on moxygen#264, then the TRACK_STATUS patch is dropped - [A smaller, safer API than release](/quest/m1/api-audit/README.md) - every surface added since release has a consumer or is gone, overlapping operations are collapsed, names mirror across Rust, JS, and the bindings, and every break says how to migrate diff --git a/quest/m1/grace-deadline.md b/quest/m1/grace-deadline.md new file mode 100644 index 00000000000..ba89bd79a33 --- /dev/null +++ b/quest/m1/grace-deadline.md @@ -0,0 +1,14 @@ +# [S] A replaced copy's grace wakes its reader + +## Goal + +When a replaced copy's grace for a missing group runs out, a wall-clock deadline +wakes the waiting reader, so a clean end is reported on time instead of up to +one budget late. + +## Plan + +Planned 2026-11-01 (maintainer, follow-up planning after the 2026-11-01 /quest-complete run). Found by [moq-dev/moq#7504](https://github.com/moq-dev/moq/pull/7504). It +predates that PR. Arm the grace's deadline wherever the grace starts in the +resume and miss paths (`rs/moq-net/src/model/resume.rs`, `track/miss.rs`), and +test it on a manual clock: the end arrives at the grace, not a budget later. diff --git a/quest/m1/js-cache-window.md b/quest/m1/js-cache-window.md new file mode 100644 index 00000000000..2bd36170359 --- /dev/null +++ b/quest/m1/js-cache-window.md @@ -0,0 +1,15 @@ +# [XS] JS tests and docs say what keeps a group cached + +## Goal + +No `@moq/net` test or doc assumes a track's `maxAge` controls how long the JS +cache keeps a group. That is the fixed 30 s `CACHE_WINDOW` in +`js/net/src/track.ts`. Each one either uses the window or says why it doesn't. + +## Plan + +Planned 2026-11-01 (maintainer, follow-up planning after the 2026-11-01 /quest-complete run). Found by [moq-dev/moq#7219](https://github.com/moq-dev/moq/pull/7219), whose +eviction test passed with eviction disabled because it assumed `maxAge`. + +- Search the JS tests and `doc/` for `maxAge` used as retention, and fix each. +- Check that each fixed test fails with eviction disabled. diff --git a/quest/m1/moq-boy-status-loop.md b/quest/m1/moq-boy-status-loop.md new file mode 100644 index 00000000000..0844da15236 --- /dev/null +++ b/quest/m1/moq-boy-status-loop.md @@ -0,0 +1,14 @@ +# [XS] moq-boy's status loop stops on an errored track + +## Goal + +`js/moq-boy/src/game.ts` `#runStatus` catches only schema errors from +`consumer.latest()`. A track that closes with an error ends the loop instead of +spinning it hot. + +## Plan + +Planned 2026-11-01 (maintainer, follow-up planning after the 2026-11-01 /quest-complete run). Found by [moq-dev/moq#7216](https://github.com/moq-dev/moq/pull/7216), which +made `@moq/room` catch only schema errors. A closed-with-error track throws on +every call (`js/net/src/track.ts` `#nextGroup`). Match that, and add a test +that an errored track ends the loop. diff --git a/quest/m1/release-fanout-bench.md b/quest/m1/release-fanout-bench.md new file mode 100644 index 00000000000..e72f33c4339 --- /dev/null +++ b/quest/m1/release-fanout-bench.md @@ -0,0 +1,23 @@ +# [S] release carries the fanout-threads bench + +## Goal + +`release` has `session_fanout_threads`, under main's case ID, so the pre-cut +pairing compares [moq-dev/moq#7493](https://github.com/moq-dev/moq/pull/7493)'s +contention win. + +## Plan + +Planned 2026-11-01 (maintainer, follow-up planning after the 2026-11-01 /quest-complete run). The maintainer allowed bench-only backports on 2026-11-01 +([moq-dev/moq#7581](https://github.com/moq-dev/moq/pull/7581)). +[moq-dev/moq#7586](https://github.com/moq-dev/moq/pull/7586) backported the +other cases, but this one isn't a plain cherry-pick. Main's split +`session/mod.rs` doesn't build on `release`. + +Port it into release's single-file `session.rs`, adding the process CPU clock +and a multi-threaded runtime with bench-local shims only, and follow +`CONTRIBUTING.md`'s bench-only backport rules. #7493 has landed on main. + +## Related + +- [Release performance](/quest/m1/release-perf/README.md) - the pairing this feeds diff --git a/quest/m1/subscribe-ranges/lite.md b/quest/m1/subscribe-ranges/lite.md index b528dc5d1d9..3a7e229f7d0 100644 --- a/quest/m1/subscribe-ranges/lite.md +++ b/quest/m1/subscribe-ranges/lite.md @@ -20,7 +20,10 @@ Decided 2026-11-01 (maintainer, on waits for [Fetch as a range](/quest/m1/subscribe-ranges/fetch-range.md)'s miss judging (a miss with no feed frontier, and holes below where a live feed started) and its cached backfill rule. Without them a range fill is a -functional regression from FETCH, which answers a miss at once. +functional regression from FETCH, which answers a miss at once. Both landed +in [moq-dev/moq#7545](https://github.com/moq-dev/moq/pull/7545) on +2026-11-02, so this quest is unblocked. Fetch as a range's remaining work, +such as the explicit end signal, doesn't block it. ### Range fill through the subscription @@ -40,7 +43,7 @@ The first attempt ([moq-dev/moq#7487](https://github.com/moq-dev/moq/pull/7487), WIP commit [b7f573d](https://github.com/moq-dev/moq/commit/b7f573d755ae53e6f2bdb94cc480ae47fd6ba254)) built this in `rs/moq-net/src/lite/subscriber.rs` and was moved back out until the -requirement lands. Reuse its design: +requirement landed. Reuse its design: - A `RangeFills` set holds each fill and asks for its next owed run (`Fill::next_run`), added as an absolute bounded range after the demand's @@ -65,7 +68,7 @@ requirement lands. Reuse its design: Its integration tests (`range_fill.rs`: a miss subscribes and sends no FETCH, a miss rides the live subscription then retires its range, a group the publisher never had becomes a miss after the grace, a cut group is filled -whole) passed. These failed, and must pass once the requirement lands: +whole) passed. These failed, and must pass on #7545's miss judging: - On-demand `requests()` tracks with no live feed, such as moq-archive's, never ask a fill and park (`untimed::a_fetched_untimed_frame_arrives_untimed`, @@ -106,6 +109,16 @@ Open questions the attempt raised, each with the attempt's recommendation: since the failing fill is a recovery fill, and rerun the test. The alternatives fill under the demand's budget, refusing older groups as Old, or add a per-range budget to the wire. +- **A range added after SUBSCRIBE_OK has no reported start.** SUBSCRIBE_OK's + Range Starts are positional and sent once, yet the subscriber judges a + bounded range complete from them, on a stream that stays open for later + updates. So a Relative or Time range a SUBSCRIBE_UPDATE adds never learns + where it started. Raised by the closed Range ID prototype + ([moq-dev/moq#7207](https://github.com/moq-dev/moq/pull/7207)), whose + recommendation was to decide here whether ranges get implicit IDs so a later + message can report a start. SUBSCRIBE_UPDATE keeps restating the whole list + either way: each range is a few bytes, and restating stays stateless. If IDs + are adopted, #7207 is the reference encoding. - `auth::lite_07_narrowing_resets_a_fetch_in_flight` read `Stream(Cancel)` instead of `Unauthorized`/`Unroutable` when the grant narrowed mid-group; the refusal must carry the grant's error. @@ -113,18 +126,14 @@ Open questions the attempt raised, each with the attempt's recommendation: The Rust copy sends a relative or time end as open, since nothing names a resolved end and it resolves the end itself (`wire_ranges`), so only absolute bounded ranges complete upstream. A hole on a live track counts as dropped -only once the feed gives up on it, past the arrivals grace, until Fetch as a -range judges such a miss sooner. +once the feed gives up on it, past the arrival grace (#7545's bounded wait, +`TrackState::miss_grace`). Update `drafts/draft-lcurley-moq-lite.md` with each wire change here, including that a subscriber fills missing groups through its ranges. Run `just drafts check` and `just test interop --all`, and the `moq-net-tests` `restart::retired_fetch_lite07` and `moq-relay` suites. -## Required - -- [Fetch as a range](/quest/m1/subscribe-ranges/fetch-range.md) - its miss judging and cached backfill rule, which a range fill needs to answer a miss as FETCH does - ## Related - [Remove FETCH from lite-07](/quest/m1/subscribe-ranges/lite07-fetch.md) - removes FETCH from lite-07 in both implementations once this and JS ranges land diff --git a/quest/m1/ts-small-step-back.md b/quest/m1/ts-small-step-back.md new file mode 100644 index 00000000000..839dcdd961a --- /dev/null +++ b/quest/m1/ts-small-step-back.md @@ -0,0 +1,30 @@ +# [S] A step back smaller than the delay keeps the TS export + +## Goal + +An unmarked timestamp step back smaller than the export's delay no longer +fails the MPEG-TS export. Audio restarts its clock instead of regressing within +one clock period. Declared-reorder video stays within its declared depth. + +## Plan + +Planned 2026-11-01 (maintainer, follow-up planning after the 2026-11-01 /quest-complete run). Found by [moq-dev/moq#7221](https://github.com/moq-dev/moq/pull/7221), which +fixed steps larger than the delay. With a −300 ms step at lag 0, audio +regresses within one clock period, and declared-reorder video fails with +"video reorders past its declared depth 2". + +- The threshold differs by track type: any regression for audio, and the + declared depth for video. +- #7221's `Track::steps_back` (`rs/moq-mux/src/container/ts/export.rs`) is + where it goes. +- Check the narrow case #7221 also raised: a slow, deep B-frame stream that + declares no reorder depth must not be mistaken for a step. +- Extend `an_unmarked_step_keeps_the_export_rendering`. + +## Required + +- [A small step back keeps the TS export's video](/quest/m1/ts-reliability/step-back.md) - adds `Track::steps_back`, which this extends, in [moq-dev/moq#7221](https://github.com/moq-dev/moq/pull/7221) + +## Related + +- [TS reliability](/quest/m1/ts-reliability/README.md) - the epic whose step-back fix this extends diff --git a/quest/m2/README.md b/quest/m2/README.md index b72e6da55be..707913ff12f 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -242,3 +242,9 @@ lite-07; bitrate enforcement is not part of this release. - [moq-video's Apple Sink encodes on its own thread](/quest/m2/apple-sink-thread.md) - macOS and iOS ladders never encode on a tokio worker - [The test inventory sees JS bench scripts](/quest/m2/js-bench-inventory.md) - JS bench entry points are resolved by the inventory gate - [/fetch answers from the announce sync](/quest/m2/fetch-synced.md) - a missing broadcast gets a 404 once announcements are synced, not after 30 s +- [moq auth sign mints capped tokens](/quest/m2/auth-sign-caps.md) - CLI flags for the bitrate caps +- [QUIC-LB forwarding reads the cluster's peers and reports its counts](/quest/m2/quic-lb-forward-extras.md) - a cluster-API peer map and forward counters +- [An audio-only broadcast that can't play hides its play button](/quest/m2/audio-only-play.md) - center-play follows the audio-only rule +- [The browser bench keeps its page consoles](/quest/m2/browser-bench-consoles.md) - publisher and consumer page logs in the run directory +- [moq-quic's long header type is one variant](/quest/m2/quic-long-type.md) - collapse LongType after the 0-RTT removal +- [One predicate for the lite close wait](/quest/m2/subscriber-fin-fold.md) - fold waits_for_subscriber_fin into has_track_stream diff --git a/quest/m2/audio-only-play.md b/quest/m2/audio-only-play.md new file mode 100644 index 00000000000..8cc5e7f67ee --- /dev/null +++ b/quest/m2/audio-only-play.md @@ -0,0 +1,11 @@ +# [XS] An audio-only broadcast that can't play hides its play button + +## Goal + +`js/watch`'s `center-play` hides for an audio-only broadcast that can't play, +as it does when video has an error. The unsupported notice from +[moq-dev/moq#7359](https://github.com/moq-dev/moq/pull/7359) then stands alone. + +## Plan + +Planned 2026-11-01 (maintainer, follow-up planning after the 2026-11-01 /quest-complete run). Use #7359's rule: a broadcast with no video renditions counts as audio. diff --git a/quest/m2/auth-sign-caps.md b/quest/m2/auth-sign-caps.md new file mode 100644 index 00000000000..285aee8ab50 --- /dev/null +++ b/quest/m2/auth-sign-caps.md @@ -0,0 +1,13 @@ +# [XS] moq auth sign mints capped tokens + +## Goal + +`moq auth sign` takes flags for the bitrate caps from +[moq-dev/moq#7535](https://github.com/moq-dev/moq/pull/7535), its publish and +subscribe rates and the object role's `rate`, so a capped token doesn't need +the library. + +## Plan + +Planned 2026-11-01 (maintainer, follow-up planning after the 2026-11-01 /quest-complete run). Mirror the grant fields #7535 added, and document them in +`doc/bin/cli.md` and the relay auth guide. diff --git a/quest/m2/browser-bench-consoles.md b/quest/m2/browser-bench-consoles.md new file mode 100644 index 00000000000..47ddca22ca7 --- /dev/null +++ b/quest/m2/browser-bench-consoles.md @@ -0,0 +1,19 @@ +# [XS] The browser bench keeps its page consoles + +## Goal + +A `bench/browser` run directory keeps the publisher's and consumer's page +console logs beside `report.json`, so a binding's error reason survives the run +and a failed nightly cell can be diagnosed from its artifacts. + +## Plan + +Planned 2026-11-01 (maintainer, follow-up planning after the 2026-11-01 /quest-complete run). Follow-up from [moq-dev/moq#7135](https://github.com/moq-dev/moq/pull/7135), +whose diagnosis was slowed by the missing page logs. + +The other half of that follow-up, a relay that says why a relayed track ended, +is already owned: [moq-dev/moq#7396](https://github.com/moq-dev/moq/pull/7396) +made a relay abort of a malformed track send PUBLISH_DONE `MALFORMED_TRACK` +instead of `INTERNAL_ERROR`, and +[PUBLISH_DONE says why a subscription ended](/quest/m2/publish-done-codes.md) +covers the remaining codes. diff --git a/quest/m2/perf/README.md b/quest/m2/perf/README.md index f313ea51027..862e69e1404 100644 --- a/quest/m2/perf/README.md +++ b/quest/m2/perf/README.md @@ -94,3 +94,6 @@ revisions on the same host and worker count, and profiles with - [Cluster route memory](/quest/m2/perf/cluster-route-memory.md) - a full-mesh cluster's ~3.7 KB per route per broadcast shrinks, the in-memory hop is profiled, and `bench-profile lock` tolerates lost records - [Lock-free single-delivery writes](/quest/m2/perf/single-delivery-write.md) - a frame with one delivery writes without a lock, recovering #6922's remaining FETCH cost - [Small hot-path waste](/quest/m2/perf/hot-path-waste.md) - one track-name copy per lite subscription, no full-history `#drift` walk, and one header buffer per JS object +- [Track-state reads skip when nothing changed](/quest/m2/perf/cursor-version-skip.md) - `Cursor::sync`, `probe` and `GroupExpiry` skip unchanged reads, then group reads move onto a Watch +- [An idle TS export with a delay costs what one without does](/quest/m2/perf/ts-idle-jitter.md) - the jitter scan and memcmp stop leading the idle poll +- [Fanout takes the route lock less](/quest/m2/perf/route-lock.md) - fewer than 41 route-lock acquisitions per fanout round diff --git a/quest/m2/perf/cursor-version-skip.md b/quest/m2/perf/cursor-version-skip.md new file mode 100644 index 00000000000..34fcc7ec750 --- /dev/null +++ b/quest/m2/perf/cursor-version-skip.md @@ -0,0 +1,21 @@ +# [M] Track-state reads skip when nothing changed + +## Goal + +`Cursor::sync`, `Cursor::probe` and `GroupExpiry::is_expired` skip their +track-state reads when the track's version is unchanged, and fanout's mutex wait +falls with them. `Subscriber::poll_recv_group` and `poll_recv_datagram` then +move onto a `kio::Watch`. The watch resets when the tail-grace deadline arms +or the floor moves. + +## Plan + +Planned 2026-11-01 (maintainer, follow-up planning after the 2026-11-01 /quest-complete run). Found by [moq-dev/moq#7532](https://github.com/moq-dev/moq/pull/7532). With +`poll_finished` on the watch, `Cursor::sync`'s track-state read is the largest +fanout wait (52% at 16 workers), followed by `probe`. + +- First make sure each read depends only on state that bumps the version. + `poll_recv_group` reads the wall clock (a copy's tail grace), and its floor + changes without a `Ready`, so it moves only with explicit resets. +- Measure fanout and chat with `just bench-profile lock` against main, at 4 + and 16 workers, on a quiet host. #7532 couldn't capture 16-worker chat. diff --git a/quest/m2/perf/quic-lock-contention.md b/quest/m2/perf/quic-lock-contention.md index 789d2e7a005..fd768bece7d 100644 --- a/quest/m2/perf/quic-lock-contention.md +++ b/quest/m2/perf/quic-lock-contention.md @@ -52,9 +52,12 @@ altogether (2026-10-25). The borrow-free mechanism report ([moq-dev/moq#7531](https://github.com/moq-dev/moq/pull/7531)) measured the designs on one core: the `Mutex` costs 1.1 to 3.5% over context passing, and a driver-owned channel (this quest's staging queue in full) costs about 4.5k -instructions per stream plus about 320 per extra write. Adopting a design, or -keeping the lock, is decided separately; this profile is the contended baseline -that decision weighs. +instructions per stream plus about 320 per extra write. Its recommendation is +to keep the `Mutex` and `RefCell` on the data path and not build the channel +design: they cost 1.1 to 3.5% and under 1% over context passing on one core, +and the channel costs 5 to 29% more. Adopting a design, or keeping the lock, is +still decided separately; this profile is the contended baseline that decision +weighs. A measured no-win is a valid outcome. Report public API and wire impact; the staging queue and batch dispatch should need none. diff --git a/quest/m2/perf/route-lock.md b/quest/m2/perf/route-lock.md new file mode 100644 index 00000000000..2c5a66f467f --- /dev/null +++ b/quest/m2/perf/route-lock.md @@ -0,0 +1,14 @@ +# [S] Fanout takes the route lock less + +## Goal + +A fanout round takes moq-net's route lock far fewer than the 41 times per round +[moq-dev/moq#7493](https://github.com/moq-dev/moq/pull/7493) measured, and the +lock's share of mutex wait falls. + +## Plan + +Planned 2026-11-01 (maintainer, follow-up planning after the 2026-11-01 /quest-complete run). Profile with `just bench-profile lock fanout`, and remove each acquisition +that reads state already held. Also make `bench/profile.py lock` accept +`tokio-rt-worker` threads, which #7493 flagged. `GroupExpiry::is_expired` is +covered by [track-state reads](/quest/m2/perf/cursor-version-skip.md). diff --git a/quest/m2/perf/ts-idle-jitter.md b/quest/m2/perf/ts-idle-jitter.md new file mode 100644 index 00000000000..1c06067e00c --- /dev/null +++ b/quest/m2/perf/ts-idle-jitter.md @@ -0,0 +1,17 @@ +# [S] An idle TS export with a delay costs what one without does + +## Goal + +An idle MPEG-TS export poll with a delay costs about what one without a delay +does, about 1.4k instructions per track. Today it is about 3k. + +## Plan + +Planned 2026-11-01 (maintainer, follow-up planning after the 2026-11-01 /quest-complete run). Found by [moq-dev/moq#7504](https://github.com/moq-dev/moq/pull/7504). With +a delay, `jitter::Acquire::freshest` (18%) and `memcmp` (26%) lead the idle +poll (`rs/moq-mux`). Skip the freshest scan when nothing arrived, and find what +the memcmp compares on an idle poll. Measure with #7504's export idle bench. + +## Required + +- [An export poll nothing woke is cheap](/quest/m2/perf/export-idle-poll.md) - adds the export idle bench and the baseline this measures against, in [moq-dev/moq#7504](https://github.com/moq-dev/moq/pull/7504) diff --git a/quest/m2/quic-lb-forward-extras.md b/quest/m2/quic-lb-forward-extras.md new file mode 100644 index 00000000000..72f091432b5 --- /dev/null +++ b/quest/m2/quic-lb-forward-extras.md @@ -0,0 +1,31 @@ +# [S] QUIC-LB forwarding reads the cluster's peers and reports its counts + +## Goal + +The QUIC-LB forward peer map can come from the `cluster.api.url` peer entries, +not only the watched TOML file. Relay stats count packets forwarded, dropped for +an unknown server ID, and refused. + +## Plan + +Planned 2026-11-01 (maintainer, follow-up planning after the 2026-11-01 /quest-complete run). Follow-ups from [moq-dev/moq#7539](https://github.com/moq-dev/moq/pull/7539), +which landed the forwarding on 2026-11-02. +The maintainer kept the TOML file as the source there (decision 4), with the +cluster API as this follow-up. Use the cluster API only if the deployment's API +already serves the mesh peer list. + +Peer map: each map entry is a QUIC-LB server ID and that relay's forward +socket address (`[listen.lb.forward] bind`), the same pair the TOML file +holds. A `cluster.api.url` peer object carries only `url`, `cost`, `egress`, +`token`, and `upstream` today, so it gains optional fields for the two, with +names to settle in the PR. A peer without both stays out of the forward map, +so a packet naming its server ID is still refused as unknown. Decide whether +the API replaces the TOML file or merges with it when both are set. + +Counters: the forwarding module from #7539 (`moq_tokio::quic::driver::forward`) +owns them and the relay exposes them in its stats and `/metrics`: + +- forwarded: a short-header packet sent to another server's forward socket; +- unknown server ID: a short header naming a server ID the map lacks, dropped; +- refused: a received forward dropped for an unlisted source, a bad tag, or + naming a server other than this one. diff --git a/quest/m2/quic-long-type.md b/quest/m2/quic-long-type.md new file mode 100644 index 00000000000..6d71e79b8bf --- /dev/null +++ b/quest/m2/quic-long-type.md @@ -0,0 +1,18 @@ +# [XS] moq-quic's long header type is one variant + +## Goal + +`LongType`, left with only `Handshake` after +[moq-dev/moq#7492](https://github.com/moq-dev/moq/pull/7492) moved 0-RTT out, +collapses into a `Handshake` header variant, and `LongHeaderType::Standard` +goes with it. + +## Plan + +Planned 2026-11-01 (maintainer, follow-up planning after the 2026-11-01 /quest-complete run). A mechanical change in `rs/moq-quic/src/packet.rs`. Keep the packet fuzz +target and its regression seeds passing. +On main, `LongType` still has `ZeroRtt` until #7492 lands. + +## Required + +- [moq-quic deletes its remaining 0-RTT code](/quest/m1/quic-zero-rtt-leftovers.md) - moves 0-RTT out of `LongType`, in [moq-dev/moq#7492](https://github.com/moq-dev/moq/pull/7492) diff --git a/quest/m2/subscriber-fin-fold.md b/quest/m2/subscriber-fin-fold.md new file mode 100644 index 00000000000..82d67cc10c3 --- /dev/null +++ b/quest/m2/subscriber-fin-fold.md @@ -0,0 +1,17 @@ +# [XS] One predicate for the lite close wait + +## Goal + +`waits_for_subscriber_fin` / `waitsForSubscriberFin` folds into +`has_track_stream` / `hasTrackStream`, or goes. + +## Plan + +Planned 2026-11-01 (maintainer, follow-up planning after the 2026-11-01 /quest-complete run). Remove whichever has fewer callers, in Rust and JS together. + +[moq-dev/moq#7296](https://github.com/moq-dev/moq/pull/7296) made lite-05/06 +wait for the subscriber's FIN, so on main both predicates now return +`has_track_stream()` / `hasTrackStream(version)`: the wait is only an alias. +`has_track_stream` has far more callers, so fold the alias into it, keep its +doc comment's reasoning at the subscriber and publisher call sites, and leave +every version's close behavior unchanged.