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
2 changes: 1 addition & 1 deletion .claude/skills/verify-route/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -125,4 +125,4 @@ Sync commit: `857f2eea4ac4cc7a3fb821f7d250637eb464b248`, where [the switch](http

SYNCED is left out: the router only records it per prefix (`Router::synced`, `Router::is_synced`), and nothing it decides reads it. So are scope regions: a relay asks for what it watches, and `interest.rs`'s `a_scope_with_several_regions_asks_for_each` and the sweeps cover a scope met with the interest.

One publisher, so routes for several publishers are left out, and so are the copies and copy rank of cache-aware routing, which `rs/moq-net/src/route/tests/cache.rs` sweeps; the DEAD message's per-publisher batching reduces to one route per prefix. Two prefixes, one nested in the other, so an edit adds, removes, widens, or narrows one prefix at a time: no wildcards, swaps of several prefixes for one, stream cancellation, grants, qualified keys, or hidden claims. Leaves out two sessions between one pair of nodes at once, as a GOAWAY migration has: the model keeps one per pair, and among equal routes the router stays on the next hop's node and takes its latest session there (`a_later_session_to_the_next_hop_takes_over_among_equals`). Leaves out restarts, priorities other than 0 and 1, a priority that differs between a link's two ends, costs other than 1 and 2, RTT, and the hop limit. Down-only routes appear only where every relay's best route is also its only exportable one, so the model never shows a down-only best route hiding an exportable alternative, a cost the routes epic's contract accepts, and a relay that accepted a request from an upstream link never ends it when its route turns down-only. The hold deadline (`HOLD`), the stalled-writer close, and a scoped session's DEAD (`fail_heard`, which doubts and remembers nothing) are left out: a hold that ends early only lets go sooner, and the model's sessions are all unscoped. So are the node's per-stream keys: lite-07 files each announce stream as its own router key, whose one edit is the prefix the stream opened with (`route/node.rs`), where the model has one neighbour per session and edits it in place; [the route stream](/quest/m2/cluster-routes/route-stream.md) joins them. Messages come only from honest routers: validation of an unrelated DEAD or its far node, and empty or overlong replacement paths, is outside the model's input domain. Rust fixtures cover those guards and exportable covering-source selection, including keeping a covering hold when every live source is unexportable. Interest-edit fixtures also cover a cancelled stream retaining its pending child replies; the model has no stream cancellation. A claims message carries the sender's whole view for its prefix, equal to applying its changes on a FIFO stream. A route is sent on every stream whether or not the publisher has a claim there. The publisher ignores what it hears. `Overlap.cfg` also simulates five relays with every session up. No exhaustive pass has more than four relays or two session changes; `Sim`'s sweeps on the path rule (`sweep_handoff`, `sweep_scoped_handoff`, `sweep_scoped_meshes_show_what_the_rule_says`, and `compare.rs`'s churn) cover larger meshes, grants, qualified keys, interest edits, restarts, and churn.
One publisher, so routes for several publishers are left out, and so are the copies and copy rank of cache-aware routing, which `rs/moq-net/src/route/tests/cache.rs` sweeps; the DEAD message's per-publisher batching reduces to one route per prefix. Two prefixes, one nested in the other, so an edit adds, removes, widens, or narrows one prefix at a time: no wildcards, swaps of several prefixes for one, stream cancellation, grants, qualified keys, or hidden claims. Leaves out two sessions between one pair of nodes at once, as a GOAWAY migration has: the model keeps one per pair, and among equal routes the router stays on the next hop's node and takes its latest session there (`a_later_session_to_the_next_hop_takes_over_among_equals`). Leaves out restarts, priorities other than 0 and 1, a priority that differs between a link's two ends, costs other than 1 and 2, and the hop limit. Down-only routes appear only where every relay's best route is also its only exportable one, so the model never shows a down-only best route hiding an exportable alternative, a cost the routes epic's contract accepts, and a relay that accepted a request from an upstream link never ends it when its route turns down-only. The hold deadline (`HOLD`), the stalled-writer close, and a scoped session's DEAD (`fail_heard`, which doubts and remembers nothing) are left out: a hold that ends early only lets go sooner, and the model's sessions are all unscoped. So are the node's per-stream keys: lite-07 files each announce stream as its own router key, whose one edit is the prefix the stream opened with (`route/node.rs`), where the model has one neighbour per session and edits it in place; [the route stream](/quest/m2/cluster-routes/route-stream.md) joins them. Messages come only from honest routers: validation of an unrelated DEAD or its far node, and empty or overlong replacement paths, is outside the model's input domain. Rust fixtures cover those guards and exportable covering-source selection, including keeping a covering hold when every live source is unexportable. Interest-edit fixtures also cover a cancelled stream retaining its pending child replies; the model has no stream cancellation. A claims message carries the sender's whole view for its prefix, equal to applying its changes on a FIFO stream. A route is sent on every stream whether or not the publisher has a claim there. The publisher ignores what it hears. `Overlap.cfg` also simulates five relays with every session up. No exhaustive pass has more than four relays or two session changes; `Sim`'s sweeps on the path rule (`sweep_handoff`, `sweep_scoped_handoff`, `sweep_scoped_meshes_show_what_the_rule_says`, and `compare.rs`'s churn) cover larger meshes, grants, qualified keys, interest edits, restarts, and churn.
2 changes: 1 addition & 1 deletion dart/moq/lib/src/aliases.dart
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ typedef AnnounceConfig = MoqAnnounceConfig;
typedef Following = MoqFollowing;

/// The read-only facts on a received route: a static cost, the stream's instance, and
/// its informational `rtt` to the origin node.
/// whether a usable path reaches it.
typedef RouteInfo = MoqRouteInfo;

/// One continuous stream at a path: `Instance.parse` names one, and only a session mints one.
Expand Down
22 changes: 1 addition & 21 deletions dart/moq_ffi/lib/src/moq.dart
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,7 @@ import "dart:ffi";
import "dart:io" show Platform, File, Directory;
import "dart:isolate";
import "dart:typed_data";

import "package:ffi/ffi.dart";

import "uniffi_runtime.dart";
export "uniffi_runtime.dart";

Expand Down Expand Up @@ -3012,12 +3010,10 @@ class MoqRouteInfo {
final int cost;
final MoqInstance instance;
final bool available;
final Duration? rtt;
MoqRouteInfo({
required this.cost,
required this.instance,
required this.available,
this.rtt,
});
}

Expand All @@ -3043,18 +3039,8 @@ class FfiConverterMoqRouteInfo {
);
final available = available_lifted.value;
new_offset += available_lifted.bytesRead;
final rtt_lifted = FfiConverterOptionalDuration.read(
Uint8List.view(buf.buffer, new_offset),
);
final rtt = rtt_lifted.value;
new_offset += rtt_lifted.bytesRead;
return LiftRetVal(
MoqRouteInfo(
cost: cost,
instance: instance,
available: available,
rtt: rtt,
),
MoqRouteInfo(cost: cost, instance: instance, available: available),
new_offset - buf.offsetInBytes,
);
}
Expand All @@ -3064,7 +3050,6 @@ class FfiConverterMoqRouteInfo {
FfiConverterUInt64.allocationSize(value.cost) +
FfiConverterMoqInstance.allocationSize(value.instance) +
FfiConverterBool.allocationSize(value.available) +
FfiConverterOptionalDuration.allocationSize(value.rtt) +
0;
final buf = Uint8List(total_length);
write(value, buf);
Expand All @@ -3085,18 +3070,13 @@ class FfiConverterMoqRouteInfo {
value.available,
Uint8List.view(buf.buffer, new_offset),
);
new_offset += FfiConverterOptionalDuration.write(
value.rtt,
Uint8List.view(buf.buffer, new_offset),
);
return new_offset - buf.offsetInBytes;
}

static int allocationSize(MoqRouteInfo value) {
return FfiConverterUInt64.allocationSize(value.cost) +
FfiConverterMoqInstance.allocationSize(value.instance) +
FfiConverterBool.allocationSize(value.available) +
FfiConverterOptionalDuration.allocationSize(value.rtt) +
0;
}
}
Expand Down
14 changes: 0 additions & 14 deletions doc/bin/relay/cluster.md
Original file line number Diff line number Diff line change
Expand Up @@ -228,20 +228,6 @@ itself, stays until that process closes it, and the relay redials only then.
A route's price is the publisher's production cost plus the link costs it
crosses. A live publisher seeds 0, and caching never changes it.

## Route latency

A moq-lite-07-wip route also carries its RTT: each relay adds its link's
lowest smoothed RTT over the last 30 seconds to the sum it received, so an
application reads the round trip through any number of relays to the route's
origin node, the one the broadcast is published to, from the route it was
announced on (`RouteInfo::rtt`). The publisher's own connection to that node is
not included. The value is absent
while any link on the path has no RTT measurement, and on a route this node
serves itself, such as a broadcast published to it. It is informational and
never picks a route; the link cost does that. A link's value changes only
when its minimum moves past the larger of 5 ms and a quarter, so jitter and
short queues send no route updates.

## LAN discovery

On a LAN there may be no one to list. `[cluster.lan]` advertises this relay
Expand Down
25 changes: 4 additions & 21 deletions drafts/draft-lcurley-moq-lite.md
Original file line number Diff line number Diff line change
Expand Up @@ -407,7 +407,7 @@ The subscriber creates the stream with an ANNOUNCE_REQUEST message.
The publisher replies with a single ANNOUNCE_OK message followed by the matching routes and claims and any future changes:

- ROUTE_START: the publisher reaches an origin node for a prefix.
- ROUTE_UPDATE: a route's path, drain, priority, metric, down-only bit, or RTT changed.
- ROUTE_UPDATE: a route's path, drain, priority, metric, or down-only bit changed.
- ROUTE_HOLD: the publisher has no usable route but holds it while it recovers.
- ROUTE_END: the publisher let go of a route and every claim under it.
- DEAD: a session on the path of routes the publisher sent closed, or a node on it sent a GOAWAY.
Expand Down Expand Up @@ -484,7 +484,7 @@ This specification marks each such value "refused"; the receiver skips the rest
- A refused ANNOUNCE_START still assigns its Announce ID, and a refused ANNOUNCE_UPDATE or ANNOUNCE_RESTART keeps it; the claim goes offline at its route's next floor, which is not an ANNOUNCE_END. A claim whose path was refused stays refused; any other comes back with a later ANNOUNCE_RESTART the receiver can use. Its origin withdrew nothing, so while a route has a live claim the receiver refused, the receiver takes the route's floors as certifying nothing, and a relay forwards no withdrawal for the claim.
- A refused WARM_START still assigns its Warm ID.

Only the publisher's own framing and stream state close the session: a message that does not decode within its Message Length, such as an RTT flag without its RTT, and a message naming an id that was never assigned or already retired, or breaking the stream's order, as above.
Only the publisher's own framing and stream state close the session: a message that does not decode within its Message Length, and a message naming an id that was never assigned or already retired, or breaking the stream's order, as above.
A relay never forwards content a peer would refuse for the relay's own part in it: a route that arrives with 32 hops is unusable, so the relay's own hop never takes one past 32.

#### Hidden Paths {#hidden}
Expand Down Expand Up @@ -525,18 +525,6 @@ An origin's own route has a Path of its own hop alone, with Session Number 0, an
A relay forwards the other hops unchanged and never qualifies them.
A route that arrives with 32 hops is unusable, since the receiver's own hop would take it past 32.

A route may also carry an RTT: the round trip to its origin node in milliseconds, summed link by link.
It is informational: nothing ranks or selects a route by its RTT.
An origin advertises its own route with an RTT of 0.
A receiver adds its link min RTT for the session to the RTT of every route the peer sends; the sum is its RTT through that peer, which it advertises on the route it selects.
A link min RTT is the lowest smoothed RTT [RFC9002] the connection measured over the last 30 seconds, read once a second, in milliseconds rounded up.
A lifetime minimum never rises after a path change, so it is not a link min RTT.
A node SHOULD keep the link min RTT it adds until the lowest reading differs from it by more than the larger of 5 ms and a quarter of it, so jitter and short queues send no ROUTE_UPDATE and a lasting change sends one per route.
A node whose connection reports no RTT has no link min RTT, so it sends the routes it learned there without one, and a route without one stays without one past every later node.
A sum too large to encode is sent without one too.
An endpoint learns its round trip to an origin node by adding its own link min RTT to the RTT of the route it selected; without its own, the RTT alone covers every hop past its first.
Like the Metric, an RTT is unverified: a peer can misstate only what crosses it.

A route is draining when a node on its Path sent a GOAWAY, as the route's draining flag or a [DEAD](#dead) says, or when its session received one.
Its priority is the lowest local priority of a session on its Path: a receiver takes the lower of the priority the route carries and its own local priority for the session, and an origin's own route carries the highest.
A node ranks its usable routes to an origin node at a prefix: one that is not draining first, then the highest priority, then the lowest metric.
Expand Down Expand Up @@ -1287,7 +1275,6 @@ Route Offer {
Flags (8),
Priority (8),
Metric (i),
[RTT (i),]
}

Hop {
Expand All @@ -1306,7 +1293,7 @@ A Hop ID of 0 is refused.
The Path comes first, so a receiver that refuses the rest of the offer still learns the hops a later [DEAD](#dead) may name.

**Flags**:
A bit field: 0x1 when the route is down-only, 0x2 when an RTT follows, and 0x4 when the route is draining (see [Routing](#routing)).
A bit field: 0x1 when the route is down-only and 0x2 when the route is draining (see [Routing](#routing)).
Any other bit set is refused, rather than ignored: a later version may give a bit a meaning that changes the route, or a field ahead of the ones defined here.

**Priority**:
Expand All @@ -1315,9 +1302,6 @@ The route's priority, the lowest local priority of a session on its Path, as a u
**Metric**:
The publisher's metric to the origin node, 0 when it is the origin.

**RTT**:
The publisher's RTT to the origin node in milliseconds (see [Routing](#routing)), 0 when it is the origin.
Present only when Flags has 0x2 set, and absent when the publisher has none.


## ROUTE_UPDATE {#route-update}
Expand Down Expand Up @@ -2549,8 +2533,7 @@ An application-specific payload.
- A receiver mints an Instance for each announcement a session of an earlier version delivers, and a `Minted` field beside every Instance (ANNOUNCE_START, ANNOUNCE_RESTART, TRACK, TRACKS, SUBSCRIBE, FETCH, and DATAGRAMS) says whether a receiver minted it, so no Instance text is reserved for minting.
- Added announce compression: ANNOUNCE_START gains `Path Base` and `Path Keep` to copy the head of a live claim's suffix.
- Split routing into two layers on the Announce Stream. ROUTE_START (0x6), ROUTE_UPDATE (0x7), and ROUTE_END (0x8) advertise how the publisher reaches an origin node, named by a Node ID, for the paths under a prefix, with an additive metric and a down-only bit. Every ANNOUNCE_START names its route's Route ID in place of the Hop ID list, so a link change sends one ROUTE_UPDATE per origin and prefix rather than an update per claim. Removed the Hop ID list and ANNOUNCE_OK's Hop ID, and replaced the SETUP Hop parameter (0x5) with a [Node ID parameter](#node-id-parameter), so an endpoint that reaches itself detects it at setup.
- ROUTE_START and ROUTE_UPDATE carry Flags, whose 0x2 bit adds an optional RTT: the informational sum of each link's lowest smoothed RTT over the last 30 seconds to the origin node, which never selects a route.
- ROUTE_START and ROUTE_UPDATE carry a Route Offer that leads with the route's Path: one hop per node the route crossed, each a Hop ID and the Session Number that node learned the route on, at most 32. A node never uses a route whose Path names it. ROUTE_START also carries a Route Suffix naming the prefix the route covers, and the offer carries the route's drain (Flags 0x4) and priority, which rank before its metric.
- ROUTE_START and ROUTE_UPDATE carry a Route Offer that leads with the route's Path: one hop per node the route crossed, each a Hop ID and the Session Number that node learned the route on, at most 32. A node never uses a route whose Path names it. ROUTE_START also carries a Route Suffix naming the prefix the route covers, and the offer carries the route's drain (Flags 0x2) and priority, which rank before its metric.
- Added ROUTE_HOLD (0xB), which holds a route while it may recover, for at most 10 seconds; ROUTE_END lets it go. Neither withdraws the origin's claims.
- Added DEAD (0xF): a node that loses a session names that hop once to each neighbour it sent a route through it, listing the routes that moved, and every node drops every route through the hop and doubts the node at the far end for a second; a DRAIN names a node that sent a GOAWAY, whose routes rank draining. The path, the dead hop, holds, and the doubt keep routes free of loops and stale copies, with no distance, sequence number, route request, or echo. On a scoped session a DEAD applies only to the routes heard there.
- A node closes a session whose peer leaves an Announce Stream undrained for 10 seconds, and the subscriber sends nothing on the stream after ANNOUNCE_REQUEST.
Expand Down
2 changes: 1 addition & 1 deletion go/wrapper/types.go
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ type (
ProtocolKind = ffi.MoqProtocolKind
// OriginConfig configures a new origin, such as its maximum cache size in bytes.
OriginConfig = ffi.MoqOriginConfig
// RouteInfo is the read-only facts on a received route: the Instance of the stream it serves (routes with one instance are one continuous stream) and its static production and link cost (lower wins), and its informational Rtt to the origin node.
// RouteInfo is the read-only facts on a received route: the Instance of the stream it serves (routes with one instance are one continuous stream), its static production and link cost (lower wins), and whether a usable path reaches it (Available).
RouteInfo = ffi.MoqRouteInfo
// Instance names one continuous stream at a path. Compare two with Eq: a session mints one
// for a route whose wire carries none, and it differs from a named instance with the same Text.
Expand Down
1 change: 0 additions & 1 deletion js/net/api/index.api.md
Original file line number Diff line number Diff line change
Expand Up @@ -530,7 +530,6 @@ export namespace Origin {
readonly available: boolean;
readonly cost: Origin.Cost;
readonly instance?: Instance.Valid;
readonly rtt?: Clock.Duration;
}
export interface RouteOptions {
auth?: Auth.Credential;
Expand Down
2 changes: 1 addition & 1 deletion js/net/src/announced.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ test("a listing shows a route's facts, never its epoch, hops, credential, or dra
captures: undefined,
route: { instance, cost: 5n, available: true },
});
expect(Object.keys(event?.route ?? {}).sort()).toEqual(["available", "cost", "instance", "rtt"]);
expect(Object.keys(event?.route ?? {}).sort()).toEqual(["available", "cost", "instance"]);
});

test("a listing reports availability flips and tells an offline path from an absent one", async () => {
Expand Down
Loading