From fd9d56b5b0d1bb4edd4900f6c9dcab688fabbf88 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 15 Nov 2026 04:40:29 -0800 Subject: [PATCH 1/9] chore(quest): claim quest/m1/transcode-unroutable.md Quest-Claim: d555294ecf6247f9 From 0962fb4aec673325a4b7d0ad6110ffbe32aed871 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 15 Nov 2026 07:20:53 -0800 Subject: [PATCH 2/9] fix(net)!: a claim presented above its path says how far above A claim covers every path beneath its prefix, and an announce stream presents the most specific claim at or above the requested prefix at that prefix itself. A source's covering claim for `src` and a derivative's own claim for `src/derived` therefore looked alike to a viewer requesting `src/derived`, and the order the relay listed them in, by node id, decided which one it asked. The source's publisher refuses a path it does not serve, so a viewer reached the derivative on some runs and got `unroutable` on others. ANNOUNCE_START, ANNOUNCE_UPDATE and ANNOUNCE_RESTART carry `Above`: how many segments broader than the requested prefix the claim is. A stream presenting a broader claim at a narrower prefix adds the distance, and a receiver ranks the lowest `Above` first, so a claim exactly at the path shadows every broader one at any cost, as the draft says. A receiver refuses an `Above` on a claim that is not at the requested prefix, or larger than its path has segments. The wire change is to the unpublished moq-lite-07-wip, mirrored in js/net and the draft. Co-Authored-By: Claude Sonnet 5.5 --- drafts/draft-lcurley-moq-lite.md | 18 ++- js/net/src/hop.ts | 8 + js/net/src/internal.ts | 14 +- js/net/src/lite/announce.test.ts | 46 ++++-- js/net/src/lite/announce.ts | 30 +++- js/net/src/lite/floors.test.ts | 15 +- js/net/src/lite/floors.ts | 15 +- js/net/src/lite/publisher.ts | 12 +- js/net/src/lite/subscriber.ts | 38 ++++- js/net/src/origin.test.ts | 11 ++ quest/m1/transcode-unroutable.md | 14 -- rs/moq-net/fixtures/lite.json | 4 +- rs/moq-net/src/fuzz.rs | 5 + rs/moq-net/src/lite/announce.rs | 139 +++++++++++++++--- rs/moq-net/src/lite/compress.rs | 5 +- rs/moq-net/src/lite/publisher.rs | 21 ++- rs/moq-net/src/lite/publisher/routed.rs | 6 +- rs/moq-net/src/lite/subscriber.rs | 20 ++- rs/moq-net/src/lite/subscriber/routed.rs | 29 +++- .../src/lite/subscriber/routed/tests.rs | 6 + rs/moq-net/src/model/origin.rs | 12 ++ rs/moq-net/src/route/mod.rs | 24 +++ rs/moq-net/src/route/node.rs | 14 ++ rs/moq-net/src/route/node/tests.rs | 1 + rs/moq-net/src/route/path.rs | 16 +- rs/moq-net/src/route/tests/mod.rs | 8 +- rs/moq-net/src/route/view.rs | 22 +-- rs/moq-net/tests/integration/main.rs | 1 + rs/moq-net/tests/integration/nested_claim.rs | 112 ++++++++++++++ 29 files changed, 562 insertions(+), 104 deletions(-) delete mode 100644 quest/m1/transcode-unroutable.md create mode 100644 rs/moq-net/tests/integration/nested_claim.rs diff --git a/drafts/draft-lcurley-moq-lite.md b/drafts/draft-lcurley-moq-lite.md index 37e6584c5bb..530cd5e46bf 100644 --- a/drafts/draft-lcurley-moq-lite.md +++ b/drafts/draft-lcurley-moq-lite.md @@ -444,6 +444,7 @@ When the stream is closed, the subscriber MUST assume that every route and claim A broadcast path has at most 32 segments and at most 4,096 bytes; a receiver MUST close the session with a PROTOCOL_VIOLATION on a longer one, except in a claim, which it refuses instead (see [Refused Content](#refused-content)), including one resolved by [Compression](#announce-compression). A claim covers a path when its prefix is a leading run of the path's segments; matching is per path segment, so a prefix never matches half a segment, and equality is byte-by-byte within each segment. A publisher answering a request stream presents, per route, each claim inside the requested prefix and only the most specific claim at or above it, at the requested prefix itself (an empty suffix), which is exactly the covered set the subscriber may see. +A claim presented above its own prefix carries how many segments broader it is than the requested prefix, its Above, so the subscriber can tell it from a claim exactly at the prefix. When that most specific covering claim changes, such as when it is withdrawn and a broader one still covers the request, the publisher moves the presented claim to the new one with an ANNOUNCE_UPDATE or ANNOUNCE_RESTART, and ends it only when no claim of the route covers the requested prefix. There MAY be multiple Announce Streams, potentially containing overlapping prefixes, that get their own ANNOUNCE_OK and messages. @@ -606,7 +607,7 @@ It MAY also close it when the stream falls behind repeated failures of the route #### Resolution {#resolution} A SUBSCRIBE, FETCH, or TRACK request naming no origin node names a path, and the receiver resolves it against the claims covering that path whose route it selected and is usable. -Only the most specific covering claims are consulted: those with the longest prefix. +Only the most specific covering claims are consulted: those with the longest prefix, or for a claim presented above the requested prefix, the lowest Above (see [ANNOUNCE_START](#announce-start)). A claim strictly inside another's paths always ranks above it, and a broadcast's exact path is the most specific claim there is, so a concrete announcement shadows every broader claim covering it at any cost; claims over the same prefix form one tier. The winning tier is the whole answer: a refusal from it never falls through to a less specific claim, so a service refusing a path does not leak the request to a catch-all, and one unserved path costs one round trip rather than a walk down the candidates. Nor is a refusal retried at another claim of the same prefix. @@ -1469,6 +1470,7 @@ ANNOUNCE_START Message { Minted (8), Epoch (i), Announce Cost (i), + Above (i), [Lite-06 Chain (..)], } ~~~ @@ -1508,6 +1510,13 @@ Only an ANNOUNCE_RESTART changes the Instance or the Epoch; ANNOUNCE_UPDATE neve The origin's price for this prefix, in the units of the [Cost Parameter](#cost-parameter): 0 for content it already produces, larger for a standby that starts work on demand. A relay forwards it unchanged; the cost of a path through the claim is the Announce Cost plus the route's metric. +**Above**: +How many segments the claim's prefix is broader than the requested prefix it is presented at (see [Announce](#announce)): 0 for a claim at or inside the requested prefix. +A publisher presenting a claim above the requested prefix at the requested prefix itself writes the distance between them, plus the Above the claim already had where it learned it from a stream of a broader request. +A claim with a non-zero Above sits at the requested prefix, and is no more above it than the prefix has segments; a receiver MUST close the session with a PROTOCOL_VIOLATION otherwise. +A receiver ranks the claims of a request by their Above first, lowest first (see [Resolution](#resolution)), so the claim of a broadcast at exactly the requested path outranks a broader claim presented there, however the two compare otherwise. +A relay forwards a claim's Above unchanged, adding the distance when it presents the claim at a narrower prefix than the one it learned it at. + **Lite-06 Chain**: The moq-lite-06 Hop ID list a claim arrived with where its origin node learned it over moq-lite-06, encoded as that list: a count, then each Hop ID. A publisher sends it, as the message's last field, only to a peer that sent the [Lite-06 Chain Parameter](#lite06-chain-parameter), and only when the claim has one; a received chain that is empty, or names a Hop ID twice, is refused. @@ -1549,6 +1558,7 @@ ANNOUNCE_UPDATE Message { Message Length (i) Announce ID (i), Announce Cost (i), + Above (i), [Lite-06 Chain (..)], } ~~~ @@ -1559,7 +1569,7 @@ Set to 0x2 to indicate an ANNOUNCE_UPDATE message. **Announce ID**: As defined for [ANNOUNCE_END](#announce-end). -**Announce Cost** and **Lite-06 Chain**: +**Announce Cost**, **Above**, and **Lite-06 Chain**: As defined for [ANNOUNCE_START](#announce-start), replacing the claim's; an absent chain replaces it with none. @@ -1578,6 +1588,7 @@ ANNOUNCE_RESTART Message { Minted (8), Epoch (i), Announce Cost (i), + Above (i), [Lite-06 Chain (..)], } ~~~ @@ -1588,7 +1599,7 @@ Set to 0x3 to indicate an ANNOUNCE_RESTART message. **Announce ID**: As defined for [ANNOUNCE_END](#announce-end). -**Instance**, **Minted**, **Epoch**, **Announce Cost**, and **Lite-06 Chain**: +**Instance**, **Minted**, **Epoch**, **Announce Cost**, **Above**, and **Lite-06 Chain**: As defined for [ANNOUNCE_START](#announce-start), replacing the claim's. ## ANNOUNCE_FLOOR {#announce-floor} @@ -2561,6 +2572,7 @@ An application-specific payload. - Added `Node ID` and `Route Depth` to TRACK, TRACKS, SUBSCRIBE, FETCH, and DATAGRAMS: the origin node the first hop selected and the prefix of the route it follows, which every later hop follows. - Replaced Warm and Cold Route Cost with the origin's Announce Cost, unchanged in transit. ANNOUNCE_UPDATE carries only the Announce Cost. - The Cost parameter must be at least 1. +- Added `Above` to ANNOUNCE_START, ANNOUNCE_UPDATE, and ANNOUNCE_RESTART: how many segments broader than the requested prefix a presented claim is. A claim presented at the requested prefix from above otherwise looked exactly like a claim at the prefix, so a broadcast nested under another's path could lose to the broader claim covering it, depending on the order a relay listed them in. Receivers rank the lowest Above first. - Replaced the shortest-path, Hop ID, Instance Hash, and Chain Hash tie-breaks with the route's drain and priority, the Announce Cost plus the route's metric, and a Rendezvous Hash of the requested path and the origin's Node ID. - Removed the standby-ordering deployment requirements on Route Cost seeds and bounds. - Added warm routes: WARM_START (0xC), WARM_UPDATE (0xD), and WARM_END (0xE) on the Announce Stream, and `Warm` on SUBSCRIBE and SUBSCRIBE_UPDATE. A relay MAY pull each broadcast through a neighbor that offers a copy of it, carrying the copy's Hops from its carrier, its Warm Cost, its drain, and its priority. A carrier offers its copy whatever it pulls and joins only a lower-ranked carrier's; a relay with no reader offers each neighbor its best source that avoids it, pulls it only while that is what it offered each relay it serves, and follows its route when a neighbor following its own pulls through it. The offers settle as a path vector does, and the pulls are then free of loops. diff --git a/js/net/src/hop.ts b/js/net/src/hop.ts index 02aacf8340e..437be293c9d 100644 --- a/js/net/src/hop.ts +++ b/js/net/src/hop.ts @@ -197,6 +197,12 @@ export interface WireRoute { * priority of a link no one set. Local, as `node` is. */ readonly priority?: number; + /** + * How many segments broader the lite-07 claim is than the path it is presented at: a claim + * exactly at a path outranks every broader one shown there, before anything else. Unset ranks + * as 0. Local, as `node` is. + */ + readonly above?: bigint; /** See {@link RouteInfo.rtt}. */ readonly rtt?: Duration; } @@ -223,6 +229,7 @@ export const WireRoute = { node: route.node, depth: route.depth, priority: route.priority, + above: route.above, rtt: route.rtt, }; }, @@ -259,6 +266,7 @@ export function routesEqual(a: WireRoute | undefined, b: WireRoute | undefined): a.node === b.node && a.depth === b.depth && (a.priority ?? 0) === (b.priority ?? 0) && + (a.above ?? 0n) === (b.above ?? 0n) && (a.rtt === b.rtt || (!!a.rtt && !!b.rtt && a.rtt.eq(b.rtt))) && a.hops.length === b.hops.length && a.hops.every((hop, i) => hop === b.hops[i]) diff --git a/js/net/src/internal.ts b/js/net/src/internal.ts index 164c671d701..3ef5b3c96e7 100644 --- a/js/net/src/internal.ts +++ b/js/net/src/internal.ts @@ -111,6 +111,8 @@ export function presented( prefix: Path.Valid, table: Advertisements, carries: (covered: Path.Valid) => boolean, + // Lite-07: a route above the prefix keeps how many segments broader than the prefix it is. + keepAbove = false, ): Map { const out = new Map(); let rootLen = -1; @@ -126,7 +128,13 @@ export function presented( ); if (!snap) continue; rootLen = covered.length; - out.set(Path.empty(), snap); + const above = BigInt(Path.parts(prefix).length - Path.parts(covered).length); + out.set( + Path.empty(), + keepAbove && above > 0n + ? { ...snap, route: { ...snap.route, above: (snap.route.above ?? 0n) + above } } + : snap, + ); continue; } const suffix = Path.stripPrefix(prefix, covered); @@ -1525,7 +1533,9 @@ export function compareRoutes(a: WireRoute, b: WireRoute): number { * get from a cluster peer, which is every route here. */ export function compareRouteCandidates(path: Path.Valid, prefix: Path.Valid, a: WireRoute, b: WireRoute): number { - const order = compareRoutes(a, b) || routeHops(a) - routeHops(b); + // The most specific claim wins outright: an exact claim shadows broader ones shown at its path. + const above = (a.above ?? 0n) - (b.above ?? 0n); + const order = (above < 0n ? -1 : above > 0n ? 1 : 0) || compareRoutes(a, b) || routeHops(a) - routeHops(b); if (order !== 0 || path === prefix) return order; const [a1, a2] = routeKey(path, a); const [b1, b2] = routeKey(path, b); diff --git a/js/net/src/lite/announce.test.ts b/js/net/src/lite/announce.test.ts index 1374a58283f..d09c3d8aa5c 100644 --- a/js/net/src/lite/announce.test.ts +++ b/js/net/src/lite/announce.test.ts @@ -80,8 +80,8 @@ test("AnnounceBroadcast round-trips on draft-06", async () => { test("AnnounceBroadcast carries a restart only on draft-07", async () => { const instance = Instance.random(); for (const msg of [ - { status: "restart" as const, id: 3n, instance, epoch: 0n, cost: 12n }, - { status: "restart" as const, id: 3n, instance, epoch: 7n, cost: 12n }, + { status: "restart" as const, id: 3n, instance, epoch: 0n, cost: 12n, above: 0n }, + { status: "restart" as const, id: 3n, instance, epoch: 7n, cost: 12n, above: 2n }, ]) { expect(await roundTrip(msg, Version.DRAFT_07)).toEqual(msg); } @@ -339,7 +339,7 @@ const GOLDEN_RESOLVED = [ // Rust's compressed output, pinned by `lite::compress::tests::golden_stream_is_pinned`. const GOLDEN = - "001300000a726f6f6d2f612f63616d000161000000000c0102036d696300016100000002020000010101000a02010162000161000000"; + "001400000a726f6f6d2f612f63616d00016100000000000d0102036d6963000161000000000203000000010101000b0201016200016100000000"; test("AnnounceHistory resolves the Rust encoder's compressed stream", async () => { expect(await resolveStream(unhex(GOLDEN))).toEqual(GOLDEN_RESOLVED); @@ -347,8 +347,8 @@ test("AnnounceHistory resolves the Rust encoder's compressed stream", async () = // JS always encodes literally. Rust's `js_literal_stream_decodes` pins the same bytes. const JS_LITERAL = - "001300000a726f6f6d2f612f63616d000161000000001300000a726f6f6d2f612f6d6963000161000000020200000101010" + - "00f000006726f6f6d2f62000161000000"; + "001400000a726f6f6d2f612f63616d00016100000000001400000a726f6f6d2f612f6d69630001610000000002030000000101010" + + "010000006726f6f6d2f6200016100000000"; test("the literal draft-07 stream matches what Rust decodes", async () => { const wire = await bytes(async (w) => { @@ -475,7 +475,7 @@ test("the route layer round-trips on draft-07", async () => { // Lite-07 claims name their route and carry no hop chain. const literal: AnnounceBroadcast = { status: "active", suffix: Path.from("x"), route: 2n, instance: a, epoch: 1n }; - expect(await roundTrip(literal, v)).toEqual({ ...literal, cost: 0n }); + expect(await roundTrip(literal, v)).toEqual({ ...literal, cost: 0n, above: 0n }); await expect(bytes((w) => encodeAnnounceBroadcast(w, { ...literal, route: undefined }, v), v)).rejects.toThrow(); await expect(bytes((w) => encodeAnnounceBroadcast(w, { ...literal, hops: [toHop(1n)] }, v), v)).rejects.toThrow(); }); @@ -688,12 +688,13 @@ test("route costs saturate at 2^62-1 on every version", async () => { } // ANNOUNCE_START: path base, path keep, empty suffix, route 0, instance "a", unminted, epoch 0, - // then a cost of 2^64-1, which only lite-07's varints can carry. + // then a cost of 2^64-1, which only lite-07's varints can carry, and its above. const wire = await bytes(async (w) => { await w.u53(0); - await w.u53(17); + await w.u53(18); for (const byte of [0, 0, 0, 0, 1, 0x61, 0, 0]) await w.u8(byte); await w.u62(huge); + await w.u8(0); }, Version.DRAFT_07); const got = await decodeAnnounceBroadcast(new Reader(undefined, wire, Version.DRAFT_07), Version.DRAFT_07); expect(got).toMatchObject({ cost: ceiling }); @@ -710,10 +711,33 @@ test("wip start and update carry one static cost", async () => { ), v, ); - // Path base, path keep, empty suffix, route 0, instance "b", unminted, epoch 0, cost. - expect([...start]).toEqual([0, 9, 0, 0, 0, 0, 1, 0x62, 0, 0, 0]); + // Path base, path keep, empty suffix, route 0, instance "b", unminted, epoch 0, cost, above. + expect([...start]).toEqual([0, 10, 0, 0, 0, 0, 1, 0x62, 0, 0, 0, 0]); const update = await bytes((w) => encodeAnnounceBroadcast(w, { status: "update", id: 0n, cost: Cost.zero }, v), v); - expect([...update]).toEqual([2, 2, 0, 0]); + expect([...update]).toEqual([2, 3, 0, 0, 0]); +}); + +test("a lite-07 claim carries how far above its path it is", async () => { + const v = Version.DRAFT_07; + const start: AnnounceBroadcast = { status: "active", suffix: Path.empty(), route: 0n, instance: b, above: 3n }; + expect(await roundTrip(start, v)).toEqual({ ...start, cost: 0n, epoch: 0n }); + const update: AnnounceBroadcast = { status: "update", id: 0n, cost: Cost.zero, above: 2n }; + expect(await roundTrip(update, v)).toEqual(update); + const wire = await bytes((w) => encodeAnnounceBroadcast(w, update, v), v); + expect([...wire]).toEqual([2, 3, 0, 0, 2]); + + // Earlier versions have no such field, so a claim above its path cannot travel on them. + await expect( + bytes( + (w) => + encodeAnnounceBroadcast( + w, + { status: "active", suffix: Path.empty(), hops: [], above: 1n }, + Version.DRAFT_06, + ), + Version.DRAFT_06, + ), + ).rejects.toThrow(); }); test("lite06 ignores a legacy cold price and writes its saturation ceiling", async () => { diff --git a/js/net/src/lite/announce.ts b/js/net/src/lite/announce.ts index 6decfbed045..918a30ee3a2 100644 --- a/js/net/src/lite/announce.ts +++ b/js/net/src/lite/announce.ts @@ -134,6 +134,8 @@ export type AnnounceBroadcast = epoch?: bigint; hops?: Hop[]; cost?: Cost; + /** Lite07+: how many segments broader the claim is than the path it is presented at. */ + above?: bigint; pathBase?: Base; } /** Pre-lite-06: a broadcast is no longer available, retracted by path. */ @@ -143,11 +145,11 @@ export type AnnounceBroadcast = | { status: "endedId"; id: bigint } /** Lite06+: atomically replace the metadata of the announcement with this id: its cost, and * before lite-07 its hop chain. The id stays live. */ - | { status: "update"; id: bigint; hops?: Hop[]; cost?: Cost } + | { status: "update"; id: bigint; hops?: Hop[]; cost?: Cost; above?: bigint } /** Lite07+: the announcement with this id now serves the instance and epoch given. Another * instance is another stream, so what the receiver resolved under its prefix is stale; a * higher epoch of the same one continues it. The id stays live. */ - | { status: "restart"; id: bigint; instance?: Instance.Valid; epoch?: bigint; cost?: Cost } + | { status: "restart"; id: bigint; instance?: Instance.Valid; epoch?: bigint; cost?: Cost; above?: bigint } /** An unknown lite-06+ announce type, skipped by length. Does not assign an id. */ | { status: "skipped" } /** Lite07+: the initial set has been delivered. */ @@ -300,6 +302,18 @@ async function encodeRouteCost(w: Writer, version: Version, cost: Cost | undefin if (version === Version.DRAFT_06) await w.u62(MAX_COST); } +// Lite07 follows the cost with how many segments broader the claim is than the path it is +// presented at, so a claim exactly at a path outranks every broader one shown there. Older versions +// carry no such field, and a claim they forward is never broader than its own path. +async function encodeAbove(w: Writer, version: Version, above: bigint | undefined) { + if (hasRoutes(version)) await w.u62(above ?? 0n); + else if (above) throw new Error("a claim above its path needs lite-07"); +} + +async function decodeAbove(r: Reader, version: Version): Promise { + return hasRoutes(version) ? await r.u62() : undefined; +} + async function decodeRouteCost(r: Reader, version: Version): Promise { if (!hasRouteCost(version)) return undefined; const cost = saturate(await r.u62()); @@ -422,7 +436,8 @@ async function decodeStart(r: Reader, version: Version): Promise