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
1 change: 1 addition & 0 deletions quest/m1/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -131,6 +131,7 @@ QUIC studies there on that rule.
- [Frame slot charge](/quest/m1/frame-slot-charge.md) - a group's frame slots past the first four count against the cache pool, including capacity a released group keeps
- [Front deadlines](/quest/m1/front-deadline-index.md) - a front's per-event cost stops growing with its track count: an expiry index and per-track wakes, proven by a churn benchmark
- [Front parking](/quest/m1/origin-front-parks.md) - an unroutable request waits on a front instead of re-asking on every route-table move
- [Route wakes](/quest/m1/route-wakes.md) - a route change wakes only the fronts it can move, so pool churn stops scaling with served paths
- [Publish channel count](/quest/m1/publish-audio-channel-count.md) - forcing a channel count on an Audio.Capture stops costing the subscriber gaps of silence
- [JS abandonment](/quest/m1/js-subscribe-abandonment.md) - a viewer returning during IETF subscribe setup keeps its track across microtasks
- [Epoch primitive](/quest/m1/epoch.md) - one `Epoch` type in moq-net and @moq/net, carried as a trailing `@<uuidv7>` path segment, shared by e2ee and broadcast epochs
Expand Down
92 changes: 92 additions & 0 deletions quest/m1/route-wakes.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
# [M] A route change wakes only the fronts it affects

## Goal

A route change under a prefix (join, withdraw, re-price, restale) makes the
origin driver act only on the fronts that could change their selection:
fronts still waiting for a source, fronts served by the changed route, and
publisher-pinned fronts on its first hop. Today it wakes every front below
the prefix, so one equal-cost pool member joining or leaving a prefix that
serves 10k paths costs the driver 100 to 600 ms of single-threaded work
while no front switches (`origin/pool_churn`, #4607). A root claim, such as
an archive's catch-all, makes every front on the relay pay for every change
to it. Done when `origin/pool_churn` is flat in served paths.

## Plan

Facts from the wildcard line (`rs/moq-net/src/model/origin.rs` there):

- Every route change calls `sync_route`, which calls
`routes.poke_below(prefix)`. That bumps a counter-only `Watch` on every path
below the prefix, so a woken front cannot tell what changed. Each re-runs
`select` under the table read lock (`retain_routes`, then `best_route`,
which hashes every qualifying pool member unless a Stay front's route
still serves), then the driver polls every track and rescans deadlines.
- `route_order` is rendezvous-style: FNV over the path and hop ids, lowest
wins. A join moves only paths the newcomer wins, a leave only paths the
leaver was winning.
- A front's `Pin` limits which routes it can take. `Stay` (an origin-named
front while serving) keeps its route while it serves; `Route` qualifies
only its own route; `Publisher` only routes whose first hop matches;
`Local` only local routes; `Any` (identity not yet known, or origin-named
and not serving) every route. Pool fronts in `origin/pool_churn` never
get an origin-naming reply, so they are `Publisher`, each on a different
member's hop. So on a join the fronts that can act are the `Any` ones,
`Publisher` ones on the new route's first hop, and `Local` ones for a
local route. On a leave, the fronts served by or requesting through that
route, plus those same pin sets: a deeper prefix appearing shadows
shallower routes for them, and one leaving can unshadow a broader route
for a waiter it never served.

Decisions:

- Covers every route change, not only equal-cost pools. The pool is where
the benchmark found it, but the wake is per prefix regardless of cost.
(2026-09-30)
- An index, not a payload filter on the watch: each route records the
fronts it serves, and each prefix node records only its non-Stay watches
(waiting fronts, publisher- and local-pinned fronts, `routed_broadcast`
waiters). A change wakes the ones it qualifies for (next decision) plus
the changed route's own fronts. A
payload filter would still walk every watch under the prefix, which stays
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
linear in paths. (2026-09-30)
- The prefix node keys its watches by what they qualify for: `Any` and
`routed_broadcast` waiters in one set, `Publisher` by hop, `Local` in its
own set. `Route` fronts hang off their route only. A front moves its
entries when it selects, and drops them when it closes. Any change to a
route wakes the `Any` set, its first hop's `Publisher` set, the `Local`
set if local, and the fronts it serves or is requesting for, so an
unrelated publisher joining or leaving wakes no serving pool front. The
pin sets wake on a loss too: withdrawing a deeper claim can unshadow a
broader route for a parked waiter it never served. A withdrawal takes
the served set before dropping the record. Fronts sit at paths below the changed prefix, so the lookup
walks descendants but skips subtrees whose matching set is empty, keeping
cost in woken fronts rather than served paths. (2026-09-30)
- A same-publisher join still wakes that hop's whole `Publisher` set, even
where the new route cannot win. Narrowing it to the paths the route wins
is left out: the `Publisher` pin goes with `--hop` removal in the cluster
routing line. (2026-09-30)
- Builds on shared-fronts' keying, so the index hangs off the final front
identity. `origin-front-parks.md` replaces the `routed_broadcast` retry
loop, one of the watch consumers here; whichever lands second adapts it.
(2026-09-30)
- Stay fronts never need a join or re-price: the edge/core tiers decision
(2026-09-30) dropped route upgrades, so a serving front moves only on
failover.

Verification: `origin/pool_churn` flat in served paths at every pool width
it already sweeps, and a unit test that counts `select` calls per route
change and asserts only affected fronts re-select, with zero for an
unrelated publisher's join and leave, and a parked waiter retrying when a
deeper advertise-only claim over a served root is withdrawn. Keep `pool_resolve` unchanged.

Public API: none. Wire: none.

## Required

- [Viewer sessions share a front](/quest/m0/shared-fronts.md) - re-keys fronts, which this index hangs off; it lands after the wildcard line, which is where the pool code lives

## Related

- [Front deadlines](/quest/m1/front-deadline-index.md) - each spurious wake also pays that per-track poll and deadline scan
- [Front parking](/quest/m1/origin-front-parks.md) - replaces the `routed_broadcast` watch loop this wakes
Loading