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
21 changes: 17 additions & 4 deletions drafts/draft-lcurley-moq-lite.md
Original file line number Diff line number Diff line change
Expand Up @@ -440,6 +440,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.

Expand Down Expand Up @@ -591,8 +592,8 @@ 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.
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.
Only the most specific covering claims are consulted: those with the longest prefix, which for a claim shown below its own prefix is the path it is shown at less its 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 shown at the same path form one tier, and among those shown at different paths the deepest wins (see [Above](#announce-start)).
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.

Expand Down Expand Up @@ -1421,6 +1422,7 @@ ANNOUNCE_START Message {
Minted (8),
Epoch (i),
Announce Cost (i),
Above (i),
[Lite-06 Chain (..)],
}
~~~
Expand Down Expand Up @@ -1460,6 +1462,14 @@ 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 own prefix is broader than the path it is shown at (see [Announce](#announce)): 0 for a claim exactly there.
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, and no more than the path has segments below the publisher's root.
A claim is no more above its path than the path has segments; a receiver MUST close the session with a PROTOCOL_VIOLATION otherwise.
A receiver treats a claim as covering its path less its Above, and ranks the claims of a request by that prefix first, longest first, then, among claims of the same prefix, by the path each is shown at, deepest first (see [Resolution](#resolution)), so the claim of a broadcast at exactly the requested path outranks a broader claim shown there or deeper, however the two compare otherwise.
The claims of one tier are those of the winning prefix shown at the winning depth; claims of the same prefix shown at a shallower depth are not consulted.
A relay forwards a claim's Above unchanged, adding the distance when it shows 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.
Expand Down Expand Up @@ -1501,6 +1511,7 @@ ANNOUNCE_UPDATE Message {
Message Length (i)
Announce ID (i),
Announce Cost (i),
Above (i),
[Lite-06 Chain (..)],
}
~~~
Expand All @@ -1511,7 +1522,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.


Expand All @@ -1530,6 +1541,7 @@ ANNOUNCE_RESTART Message {
Minted (8),
Epoch (i),
Announce Cost (i),
Above (i),
[Lite-06 Chain (..)],
}
~~~
Expand All @@ -1540,7 +1552,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}
Expand Down Expand Up @@ -2404,6 +2416,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 take a claim to cover its path less its Above.
- 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 the temporary Lite-06 Chain Setup Parameter (0x9) and a trailing Lite-06 Chain on ANNOUNCE_START, ANNOUNCE_UPDATE, and ANNOUNCE_RESTART: the moq-lite-06 Hop ID list of a claim learned over moq-lite-06, which a node drops when it names that node.
Expand Down
49 changes: 27 additions & 22 deletions js/net/src/consume.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ import type * as broadcast from "./broadcast.ts";
import { StreamCode, StreamError } from "./error.ts";
import type { WireRoute } from "./hop.ts";
import * as Instance from "./instance.ts";
import { bestCandidate, coveringPrefixes } from "./internal.ts";
import { bestCandidate, coveringPrefixes, mostSpecific } from "./internal.ts";
import type * as Path from "./path.ts";
import { type Served, sameInstance } from "./wire.ts";

Expand Down Expand Up @@ -117,21 +117,23 @@ export class BroadcastCache {

/** Resolve the same most-specific-prefix and route preference as the origin. */
instance(path: Path.Valid): Selection {
for (const prefix of coveringPrefixes(path)) {
const best = bestCandidate(path, prefix, this.#eligible(path, prefix), (entry) => entry.route);
if (best) {
const cached = this.#cache.get(path)?.get(best.route.instance ?? best.identity);
// A minted instance names the announcement, not the publisher's stream, so a
// request for it can only name the path: it holds while this route is selected.
const named = best.route.instance !== undefined && !Instance.isMinted(best.route.instance);
return {
...best,
validity: !named
? ((cached?.consumer.closed.peek() === undefined ? cached?.selection.validity : undefined) ??
new Validity())
: undefined,
};
}
const best = mostSpecific(
path,
(prefix) => bestCandidate(path, prefix, this.#eligible(path, prefix), (entry) => entry.route),
(entry) => entry.route,
);
if (best) {
const cached = this.#cache.get(path)?.get(best.route.instance ?? best.identity);
// A minted instance names the announcement, not the publisher's stream, so a
// request for it can only name the path: it holds while this route is selected.
const named = best.route.instance !== undefined && !Instance.isMinted(best.route.instance);
return {
...best,
validity: !named
? ((cached?.consumer.closed.peek() === undefined ? cached?.selection.validity : undefined) ??
new Validity())
: undefined,
};
}
return this.#blind.get(path) ?? new Blind();
}
Expand All @@ -142,12 +144,15 @@ export class BroadcastCache {
* resolves or refuses.
*/
pinned(path: Path.Valid, instance: Instance.Valid): Selection {
for (const prefix of coveringPrefixes(path)) {
const entries = this.#eligible(path, prefix).filter((entry) => entry.route.instance === instance);
const best = bestCandidate(path, prefix, entries, (entry) => entry.route);
if (best) return best;
}
return { identity: {}, route: { instance } };
const best = mostSpecific(
path,
(prefix) => {
const entries = this.#eligible(path, prefix).filter((entry) => entry.route.instance === instance);
return bestCandidate(path, prefix, entries, (entry) => entry.route);
},
(entry) => entry.route,
);
return best ?? { identity: {}, route: { instance } };
}

/**
Expand Down
10 changes: 9 additions & 1 deletion js/net/src/hop.ts
Original file line number Diff line number Diff line change
Expand Up @@ -183,6 +183,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;
}

/** Constructors and helpers for {@link WireRoute}. @internal */
Expand All @@ -207,6 +213,7 @@ export const WireRoute = {
node: route.node,
depth: route.depth,
priority: route.priority,
above: route.above,
};
},
};
Expand All @@ -225,7 +232,7 @@ export function isAnonymous(route: WireRoute): boolean {

/**
* Whether two routes name the same instance, epoch, hop chain, cost, auth, drain state,
* availability, origin node, and route depth and priority.
* availability, origin node, route depth, priority, and how far above its path a claim is.
*
* @internal
*/
Expand All @@ -242,6 +249,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.hops.length === b.hops.length &&
a.hops.every((hop, i) => hop === b.hops[i])
);
Expand Down
64 changes: 54 additions & 10 deletions js/net/src/internal.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<Path.Valid, Advertised> {
const out = new Map<Path.Valid, Advertised>();
let rootLen = -1;
Expand All @@ -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);
Expand Down Expand Up @@ -1421,6 +1429,32 @@ export function bestCandidate<T>(
return best;
}

/**
* What `pick` finds at the most specific claim covering `path`: it picks at each covering prefix,
* deepest first, and a claim shown above its own prefix counts for the shallower prefix it is
* really at. Of claims as specific as each other the deepest prefix wins. Mirrors
* `RouteTable::best_route` in rs/moq-net.
*/
export function mostSpecific<T>(
path: Path.Valid,
pick: (prefix: Path.Valid) => T | undefined,
route: (found: T) => WireRoute,
): T | undefined {
let best: T | undefined;
let bestSpecificity = -1;
let depth = Path.parts(path).length;
for (const prefix of coveringPrefixes(path)) {
const found = pick(prefix);
const specificity = found === undefined ? 0 : depth - Number(route(found).above ?? 0n);
if (found !== undefined && specificity > bestSpecificity) {
best = found;
bestSpecificity = specificity;
}
depth--;
}
return best;
}

/** Covering prefixes, most specific first, including the empty root. */
export function* coveringPrefixes(path: Path.Valid): Generator<Path.Valid> {
for (;;) {
Expand All @@ -1441,25 +1475,33 @@ export function superseded(route: WireRoute, others: Iterable<WireRoute>): boole
}

/**
* The highest epoch each instance reaches among a set of routes, built in one pass so ranking
* N routes stays linear. Only epochs above 0 are kept, since nothing is below 0: the common
* case, where every instance announces epoch 0, stores nothing. Mirrors `Epochs` in rs/moq-net.
* The highest epoch each instance reaches among a set of routes, per claim: a claim is its prefix
* and how far above it was shown, so a broader claim shown at a prefix is another claim than the
* one made there, and its epoch supersedes nothing of it. Built in one pass so ranking N routes
* stays linear. Only epochs above 0 are kept, since nothing is below 0: the common case, where
* every instance announces epoch 0, stores nothing. Mirrors `Epochs` in rs/moq-net, whose routes
* are all of one prefix here.
*/
export class Epochs {
readonly #highest = new Map<Instance.Valid | undefined, bigint>();
readonly #highest = new Map<Instance.Valid | undefined, Map<bigint, bigint>>();

constructor(routes: Iterable<WireRoute>) {
for (const route of routes) {
const epoch = route.epoch ?? 0n;
if (epoch === 0n) continue;
const highest = this.#highest.get(route.instance);
if (highest === undefined || epoch > highest) this.#highest.set(route.instance, epoch);
let above = this.#highest.get(route.instance);
if (!above) {
above = new Map();
this.#highest.set(route.instance, above);
}
const highest = above.get(route.above ?? 0n);
if (highest === undefined || epoch > highest) above.set(route.above ?? 0n, epoch);
}
}

/** Whether a route carries `route`'s instance at a higher epoch. */
/** Whether a route carries `route`'s instance at a higher epoch on the same claim. */
supersedes(route: WireRoute): boolean {
const highest = this.#highest.get(route.instance);
const highest = this.#highest.get(route.instance)?.get(route.above ?? 0n);
return highest !== undefined && highest > (route.epoch ?? 0n);
}
}
Expand Down Expand Up @@ -1489,7 +1531,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);
Expand Down
Loading