Repository navigation
chore(quest): rescope routing quests after prefix routes #3274
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
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,101 @@ | ||
| # [XL] Route resume identity | ||
|
|
||
| ## Goal | ||
|
|
||
| A subscription whose serving route goes away resumes through the next best | ||
| route without the consumer noticing, as it did before announcements became | ||
| prefix routes. A route change that preserves the origin identity re-splices at | ||
| a group boundary; one that does not ends the subscription so the consumer | ||
| starts a new one. | ||
|
|
||
| This supplies the per-path identity two other questlines are built on top of. | ||
|
|
||
| ## Plan | ||
|
|
||
| ### Root cause, and the decision | ||
|
|
||
| [moq#3225](https://github.com/moq-dev/moq/pull/3225) made announcements prefix | ||
| routes and moved route state out of `broadcast::Broadcast` into `origin`. A | ||
| front used to hold the routes for its path and the identity of whoever was | ||
| serving it: `FrontState.publisher` was the first hop of the best route, and | ||
| `same_identity` decided whether an arriving route joined the existing front | ||
| (splice) or started a fresh broadcast. Both are gone, and the PR specified the | ||
| loss into the draft: "A route carries no content identity", and a relay "MUST | ||
| NOT splice a live subscription across sources reached through different | ||
| routes". Failover on dev is abort and resubscribe | ||
| (`origin::Consumer::routed_broadcast` retries), and every reader sees the | ||
| subscription end. | ||
|
|
||
| Decision (2026-09-01): that spec point is reversed. Routes keep carrying the | ||
| hops and cost of what they serve, and a relay resumes/stitches a broadcast | ||
| across routes when the first hop is the same. `Epoch` stays dead; it was a | ||
| per-broadcast content generation, and nothing per-broadcast survives prefix | ||
| routes. What identifies a source is the route's first hop, which is still on | ||
| the wire, still in `RouteEntry`, and still ranked on by `route_order`. What was | ||
| lost is the structure that read it, not the value. | ||
|
|
||
| ### What to restore | ||
|
|
||
| Give the per-path serve state an identity, derived from the first hop of the | ||
| route currently serving it, and re-splice rather than abort when a route change | ||
| preserves it: | ||
|
|
||
| - Equal non-zero first hops are the same origin endpoint reached another way (a | ||
| reconnect, a cheaper path, a relay restarting). Splice at a group boundary. | ||
| - Different first hops are different sources at one path. End the subscription | ||
| rather than splicing one source's subscribers onto another's frames. | ||
| - `Hop::UNKNOWN` identifies nobody and never matches itself, which is what | ||
| `same_identity` existed to encode. Two anonymous peers must not pass for one | ||
| reconnecting. | ||
|
|
||
| An empty hop chain is a local publish and keeps the local-source behavior it | ||
| has now. | ||
|
|
||
| This is more than restoring a field, which is why the quest is sized XL. On dev | ||
| `ServeState` is per-announcer, and `create_source` mints a broadcast that is | ||
| deliberately not inserted into the broadcast tree, so nothing per-path spans | ||
| routes. The work includes rebuilding that front: a per-path structure that | ||
| outlives any single route, holds the serving identity, and is what a | ||
| replacement route splices into. | ||
|
|
||
| ### Draft | ||
|
|
||
| The implementing PR amends `drafts/draft-lcurley-moq-lite.md` in the same | ||
| change, per the wire-behavior rule. The "route carries no content identity" | ||
| paragraph becomes the first-hop rule: two routes covering one path with the | ||
| same non-zero first hop are the same origin reached different ways, and a | ||
| relay MAY move a live subscription between them at a group boundary; across | ||
| differing or unknown first hops a relay MUST NOT splice, and the subscription | ||
| ends with the serving session as it does today. Record the change in the | ||
| moq-lite-06 changelog. | ||
|
|
||
| ### Boundaries | ||
|
|
||
| Identity here is a routing-layer property, not a media one. The first hop | ||
| identifies the endpoint that originated the route, which for a prefix route is | ||
| whoever serves the subtree; equal first hops mean the same endpoint, not that | ||
| two encodings are interchangeable. That media-generation question is what | ||
| `Epoch` was reaching for and what | ||
| [plan-hls-identity](/quest/m2/plan-hls-identity.md) still owns for cacheable | ||
| URLs. | ||
|
|
||
| The fix lands on `dev`, where prefix routes live; `main` has no prefix routes. | ||
|
|
||
| ### Tests | ||
|
|
||
| The pre-#3225 goaway and cluster tests are the specification: a draining | ||
| session serves through the handover window and its subscribers move to the | ||
| surviving route without the subscription ending. Add the first-hop cases the | ||
| old front covered: a reconnecting publisher splices, a different publisher at | ||
| the same path does not, two anonymous peers never pass for one, and a | ||
| metadata-only reprice changes nothing visible. | ||
|
|
||
| ## Related | ||
|
|
||
| - [Rank](/quest/m2/pop-skipping/rank.md) - reuses this comparison rule on the | ||
| route's *last* hop, since adopting a parent is about the adjacent relay rather | ||
| than about who produced the content | ||
| - [Resolve](/quest/m2/wildcard/resolve.md) - two publishers colliding at one | ||
| literal path resolve through this identity | ||
| - [plan-hls-identity](/quest/m2/plan-hls-identity.md) - the media-generation | ||
| identity this deliberately does not supply | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -12,6 +12,23 @@ dev's reshaped announce/origin surface only; the 0.1.x backport half is | |
| dropped unless a maintenance branch appears. See also the pattern-scoped | ||
| origin work at /quest/m2/path-patterns/origin.md. | ||
|
|
||
| ### After prefix routes | ||
|
|
||
| A per-path predicate does not mean what it did when this was filed. | ||
| [moq#3225](https://github.com/moq-dev/moq/pull/3225) made `announced()` yield | ||
| covering prefixes rather than broadcast paths, so a predicate applied to the | ||
| announce stream is deciding about a *set*: a route at `room/` carries every | ||
| path under it, including the ones a deafen rule wants blocked, and blocking the | ||
|
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 Use “to be blocked” in this sentence. Replace “the ones a deafen rule wants blocked” with “the ones a deafen rule wants to be blocked.” 🧰 Tools🪛 LanguageTool[style] ~21-~21: The double modal “wants blocked” is nonstandard (only accepted in certain dialects). Consider “to be blocked”. (NEEDS_FIXED) 🤖 Prompt for AI AgentsSource: Linters/SAST tools |
||
| whole prefix hides paths the subscriber may use. The filter also cannot be the | ||
| enforcement point on its own, because `request_broadcast` resolves against the | ||
| route table directly. | ||
|
|
||
| So this needs the enforcement boundary settled before an API: a predicate over | ||
| announcements (discovery), a predicate at resolution (access), or the | ||
| pattern-scoped consumer in | ||
| [origin](/quest/m2/path-patterns/origin.md). The reporter's requirement, which a | ||
| forked client cannot bypass, points away from a discovery-time filter. | ||
|
|
||
| ### Issue context | ||
|
|
||
| Hi @kixelated 👋 | ||
|
|
||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -11,6 +11,22 @@ Use the public issue's scope, implementation notes, and acceptance criteria | |
| below as the starting plan. Reconcile paths and assumptions with the current | ||
| tree before implementation. | ||
|
|
||
| ### After prefix routes | ||
|
|
||
| Half of the stated problem is gone. | ||
| [moq#3225](https://github.com/moq-dev/moq/pull/3225) made | ||
| `origin::Producer::create_broadcast` stop announcing: the blessed order is | ||
| create, populate, announce, and `announce` is a separate call returning a guard. | ||
| So a broadcast is no longer announced before its tracks exist, and | ||
| `broadcast::Route::announce = false` (which the issue correctly says is not a | ||
| readiness gate) does not exist either. | ||
|
Comment on lines
+18
to
+22
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. 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win Update the stale readiness requirements. This paragraph says 🤖 Prompt for AI Agents |
||
|
|
||
| What remains is the exact-path half: `create_broadcast` still makes the source | ||
| visible to `request_broadcast` immediately, so a concurrent consumer can find a | ||
| broadcast whose tracks and `broadcast::Dynamic` handler are not installed yet. | ||
| Re-scope to that, and weigh it against the convention now being sufficient for | ||
| the announced path. | ||
|
|
||
| ### Issue context | ||
|
|
||
| #### Problem | ||
|
|
||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -11,6 +11,28 @@ Use the public issue's scope, implementation notes, and acceptance criteria | |
| below as the starting plan. Reconcile paths and assumptions with the current | ||
| tree before implementation. | ||
|
|
||
| ### After prefix routes | ||
|
|
||
| [moq#3225](https://github.com/moq-dev/moq/pull/3225) deleted both APIs the | ||
| issue names. `MoqBroadcastConsumer::route_updates` and | ||
| `MoqBroadcastProducer::set_route` are gone; a broadcast no longer carries a | ||
| route at all. | ||
|
Comment on lines
+16
to
+19
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. 🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win Replace the stale API path in the issue context. This section says 🤖 Prompt for AI Agents |
||
|
|
||
| The bug survived the move. `MoqOriginProducer::announce(prefix, MoqRoute)` is | ||
| the input, `MoqAnnouncement.route` is the output, and the two conversions are | ||
| unchanged: `From<origin::Route>` reports `route.cost.warm` and drops `cold`, | ||
| while `TryFrom<MoqRoute>` calls `with_cost(u64)`, which sets both halves. So | ||
| observing a route through `announced()` and re-announcing it still rewrites a | ||
| truthful `{warm: 0, cold: N}` into `{warm: 0, cold: 0}`, claiming to be the | ||
| publisher. | ||
|
|
||
| The severity argument in the issue no longer holds either: it rested on | ||
| `FrontState::handover_allowed` only consulting cold at two or more hops, and | ||
| that gate was deleted with the rest of the handover machinery. Cold is still | ||
| ranked on by `route_order`, so an understated cold still wins ties it should | ||
| lose. Re-read the options below against `announce`/`announced` rather than | ||
| `set_route`/`route_updates`. | ||
|
|
||
| ### Issue context | ||
|
|
||
| Found by the Codex reviewer during [#2925](https://github.com/moq-dev/moq/pull/2925), which splits the route cost into `broadcast::Cost { warm, cold }`. Filing rather than fixing in that PR because it is a public-API decision spanning five language bindings. | ||
|
|
||
| Original file line number | Diff line number | Diff line change | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
@@ -11,6 +11,21 @@ Use the public issue's scope, implementation notes, and acceptance criteria | |||||||||||||||
| below as the starting plan. Reconcile paths and assumptions with the current | ||||||||||||||||
| tree before implementation. | ||||||||||||||||
|
|
||||||||||||||||
| ### After prefix routes | ||||||||||||||||
|
|
||||||||||||||||
| This is now a semantics divergence, not only a naming one. | ||||||||||||||||
| [moq#3225](https://github.com/moq-dev/moq/pull/3225) made Rust's | ||||||||||||||||
| `origin::Producer::create_broadcast` stop announcing, while the FFI's | ||||||||||||||||
| `create_broadcast` still announces the exact path on the caller's behalf (it | ||||||||||||||||
| calls `announce(path, Default::default())` and hands back the guard), so | ||||||||||||||||
| wrappers keep announcing by convention. Two surfaces now share one name and do | ||||||||||||||||
|
Comment on lines
+19
to
+21
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. 🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win Correct the documented FFI announcement behavior. The implementation in Rewrite this section to describe the actual announcement-enabled creation behavior before choosing the canonical rename contract. The Suggested wording-`create_broadcast` still announces the exact path on the caller's behalf (it
-calls `announce(path, Default::default())` and hands back the guard), so
-wrappers keep announcing by convention.
+`create_broadcast` creates an announced broadcast by passing
+`Route::new().with_announce(true)` to the Rust origin and returns an
+`Arc<MoqBroadcastProducer>`. It does not return an announcement guard.📝 Committable suggestion
Suggested change
🤖 Prompt for AI Agents |
||||||||||||||||
| different things. | ||||||||||||||||
|
|
||||||||||||||||
| Settle that before the rename: either the FFI's auto-announce becomes explicit | ||||||||||||||||
| in the wrappers too, or the fused operation keeps a distinct name of its own. | ||||||||||||||||
| Renaming both to `create_broadcast` without deciding hides the difference behind | ||||||||||||||||
| matching spelling, which is worse than the inconsistency it fixes. | ||||||||||||||||
|
|
||||||||||||||||
| ### Issue context | ||||||||||||||||
|
|
||||||||||||||||
| #### Problem | ||||||||||||||||
|
|
||||||||||||||||
This file was deleted.
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
Use the canonical
GOAWAYspelling.This line names the protocol message. Write
GOAWAYso readers can find the related protocol tests and terminology consistently.🧰 Tools
🪛 LanguageTool
[grammar] ~66-~66: Ensure spelling is correct
Context: ...refix routes. ### Tests The pre-#3225 goaway and cluster tests are the specification...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🤖 Prompt for AI Agents
Source: Linters/SAST tools