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 js/net/api/index.api.md
Original file line number Diff line number Diff line change
Expand Up @@ -527,6 +527,7 @@ 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"]);
expect(Object.keys(event?.route ?? {}).sort()).toEqual(["available", "cost", "instance", "rtt"]);
});

test("a listing reports availability flips and tells an offline path from an absent one", async () => {
Expand Down
20 changes: 19 additions & 1 deletion js/net/src/hop.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@
*
* @module
*/
import type { Duration } from "@moq/clock";
import * as z from "zod/mini";
import type { Credential } from "./auth.ts";
import type * as Instance from "./instance.ts";
Expand Down Expand Up @@ -111,6 +112,18 @@ export interface RouteInfo {
* it recovers: request again once it turns available.
*/
readonly available: boolean;
/**
* The round trip to the route's origin node over moq-lite-07, informational: it never ranks
* or selects a route.
*
* Each link on the path adds its min RTT, the lowest smoothed RTT it measured over the last
* 30 seconds, this session's own link included. Undefined on any other wire, on a route this
* origin serves itself, and while any link on the path has no measurement.
*
* A listing reports it as of the event that carries the route: a change to the RTT alone is
* no event.
*/
readonly rtt?: Duration;
}

/**
Expand All @@ -124,6 +137,7 @@ export function routeInfo(route: WireRoute): RouteInfo {
instance: route.instance,
cost: route.cost,
available: route.available ?? true,
rtt: route.rtt,
};
}

Expand Down Expand Up @@ -171,6 +185,8 @@ export interface WireRoute {
* see it.
*/
readonly node?: bigint;
/** See {@link RouteInfo.rtt}. */
readonly rtt?: Duration;
}

/** Constructors and helpers for {@link WireRoute}. @internal */
Expand All @@ -193,6 +209,7 @@ export const WireRoute = {
draining: route.draining,
available: route.available,
node: route.node,
rtt: route.rtt,
};
},
};
Expand All @@ -211,7 +228,7 @@ export function isAnonymous(route: WireRoute): boolean {

/**
* Whether two routes name the same instance, epoch, hop chain, cost, auth, drain state,
* availability, and origin node.
* availability, origin node, and RTT.
*
* @internal
*/
Expand All @@ -226,6 +243,7 @@ export function routesEqual(a: WireRoute | undefined, b: WireRoute | undefined):
(a.draining ?? false) === (b.draining ?? false) &&
(a.available ?? true) === (b.available ?? true) &&
a.node === b.node &&
(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])
);
Expand Down
65 changes: 65 additions & 0 deletions js/net/src/lite/link_rtt.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
import { expect, test } from "bun:test";
import { Duration } from "@moq/clock";
import { LinkRtt } from "./link_rtt.ts";

// Mirrors the tests of `route/rtt.rs` in rs/moq-net.

const ms = (n: number) => Duration.millis(n);
const asMs = (rtt: Duration | undefined) => rtt?.asMillis();
const feed = (link: LinkRtt, reads: (Duration | undefined)[]) => reads.map((rtt) => asMs(link.read(rtt)));

test("the first read reports at once", () => {
expect(asMs(new LinkRtt().read(ms(30)))).toBe(30);
});

test("a queue shorter than the window reports nothing", () => {
const link = new LinkRtt();
link.read(ms(30));
const queued = Array.from({ length: 29 }, (_, i) => ms(30 + (i + 1) * 3));
expect(feed(link, queued).every((report) => report === 30)).toBe(true);
expect(asMs(link.read(ms(31)))).toBe(30);
});

test("a rise reports once the window passes it", () => {
const link = new LinkRtt();
link.read(ms(30));
const reports = feed(link, Array(30).fill(ms(55)));
expect(reports.slice(0, 29).every((report) => report === 30)).toBe(true);
expect(reports[29]).toBe(55);
});

test("a drop reports at once", () => {
const link = new LinkRtt();
link.read(ms(80));
expect(asMs(link.read(ms(40)))).toBe(40);
});

test("a change within the band reports nothing", () => {
let link = new LinkRtt();
link.read(ms(10));
expect(asMs(link.read(ms(5)))).toBe(10);
expect(asMs(link.read(ms(4)))).toBe(4);
link = new LinkRtt();
link.read(ms(100));
expect(asMs(link.read(ms(75)))).toBe(100);
expect(asMs(link.read(ms(74)))).toBe(74);
});

test("a transport without rtt reports none and starts over", () => {
const link = new LinkRtt();
link.read(ms(80));
expect(link.read(undefined)).toBeUndefined();
expect(asMs(link.read(ms(90)))).toBe(90);
});

test("a window without rtt stops reading", () => {
const link = new LinkRtt();
feed(link, Array(29).fill(undefined));
expect(link.reading).toBe(true);
link.read(undefined);
expect(link.reading).toBe(false);
});

test("a fraction of a millisecond rounds up", () => {
expect(asMs(new LinkRtt().read(Duration.micros(300)))).toBe(1);
});
64 changes: 64 additions & 0 deletions js/net/src/lite/link_rtt.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
import { Duration } from "@moq/clock";

/** How many reads the minimum covers. */
const WINDOW = 30;
/** The smallest change reported. */
const FLOOR = Duration.millis(5);

/**
* A link's min RTT, as the route layer adds it to the routes learned over the link.
* Mirrors `route::LinkRtt` in rs/moq-net.
*
* Reads a link's smoothed RTT once per {@link LinkRtt.INTERVAL} and reports the lowest of
* the last 30 reads in whole milliseconds, changed only once it moves past the larger of
* 5 ms and a quarter of the value reported.
*
* The smoothed RTT follows every queue, and a lifetime minimum never rises after a path
* change; a windowed minimum ignores a queue shorter than the window and turns a path
* change into one new value.
*
* @internal
*/
export class LinkRtt {
/** How often to {@link read} the smoothed RTT. */
static readonly INTERVAL = Duration.secs(1);

#reads: Duration[] = [];
#reported: Duration | undefined;
/** Reads in a row that found no RTT. */
#misses = 0;

/** The min RTT last reported. */
get reported(): Duration | undefined {
return this.#reported;
}

/**
* Whether to keep reading: false once a window of reads found no RTT, since a transport
* that reports none that long, past a first ping, never will.
*/
get reading(): boolean {
return this.#misses < WINDOW;
}

/**
* Take one read of the smoothed RTT, `undefined` when the transport reports none, and
* return the min RTT to report.
*/
read(rtt: Duration | undefined): Duration | undefined {
if (rtt === undefined) {
this.#reads = [];
this.#reported = undefined;
this.#misses += 1;
return undefined;
}
this.#misses = 0;
if (this.#reads.length === WINDOW) this.#reads.shift();
this.#reads.push(rtt);
const lowest = this.#reads.reduce((a, b) => a.min(b));
const min = Duration.millis(Math.ceil(Math.floor(lowest.asMicros()) / 1000));
const reported = this.#reported;
if (!reported || min.absDiff(reported).gt(reported.div(4).max(FLOOR))) this.#reported = min;
return this.#reported;
}
}
31 changes: 30 additions & 1 deletion js/net/src/lite/subscriber.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3583,9 +3583,10 @@ test("a cancelled legacy datagram lookup cannot refuse a stream answer arriving

// A lite-07 peer's announce stream, after the request: what the peer writes, and the replies
// the subscriber sends back. `another` opens a further one on the session as its `index`th stream.
async function routedStream(options?: RouteOptions) {
async function routedStream(options?: RouteOptions, getStats?: () => Promise<unknown>) {
const version = Version.DRAFT_07;
const { quic, opened } = fakeSession();
if (getStats) Object.assign(quic, { getStats });
const subscriber = new Subscriber(quic, version, HopSchema.parse(1n));
const another = async (index: number, scope?: Path.Pattern) => {
const announced = subscriber.routes(scope, options);
Expand Down Expand Up @@ -4063,6 +4064,34 @@ test("a lite-07 consume pinned to an instance names its route's node", async ()
await info;
});

// A route's RTT is the relay's sum plus this link's own min RTT, unknown while either is, and it

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The pre-existing comment directly above (line 4067) documents the a lite-07 stream reports each node's claim with claims test at line 4092; this insertion now leaves it heading the rtt test instead. Move it down with the test it describes.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in e431c99: the comment is back above the claims test.

(Written by Claude Fable 5 with high)

// moves no pick: it only updates the route reported.
test("a lite-07 route reports its rtt as the relay's sum plus this link's", async () => {
// The link's first read answers only after the route's first batch is on the stream.
const stats = Promise.withResolvers<{ smoothedRtt: number }>();
const { subscriber, announced, send } = await routedStream(undefined, () => stats.promise);
const x = Path.from("x");
await send({ status: "routeStart", node: NODE_A, advert: ADVERT });
await send({ status: "active", suffix: x, route: 0n, instance: Instance.parse("a") });
await send({ status: "floor", id: 0n, revision: 0n });
const first = announced.next();
stats.resolve({ smoothedRtt: 10.2 });
// The claim waits for that read, so the path is first reported with the sum: a listing shows
// a route when its path turns present, and not again for an RTT.
let next = (await first) as { kind: string; route: WireRoute };
expect(next).toMatchObject({ kind: "start", route: { node: NODE_A } });
expect(next.route.rtt?.asMillis()).toBe(31);

// The relay could not measure a link on the path: the sum is unknown.
await send({ status: "routeUpdate", id: 0n, advert: { ...ADVERT, seqno: 2n, rtt: undefined } });
next = (await announced.next()) as { kind: string; route: WireRoute };
expect(next).toMatchObject({ kind: "update", route: { node: NODE_A } });
expect(next.route.rtt).toBeUndefined();

announced.close();
subscriber.close();
});

// Forwarding code asks for each origin node's claim at a path as its own route.
test("a lite-07 stream reports each node's claim with claims", async () => {
const { subscriber, announced, send } = await routedStream({ claims: true });
Expand Down
66 changes: 64 additions & 2 deletions js/net/src/lite/subscriber.ts
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
import { Duration, yieldNow } from "@moq/clock";
import { Duration, sleep, yieldNow } from "@moq/clock";
import { type Dispose, Effect, type GetPromise, type Getter, race, Signal } from "@moq/signals";
import * as announce from "../announced.ts";
import type { Grant } from "../auth.ts";
import type { AuthSession } from "../auth_session.ts";
import * as broadcast from "../broadcast.ts";
import type { Drain } from "../connection/goaway.ts";
import type { Probe as ProbeStats } from "../connection/stats.ts";
import { type Probe as ProbeStats, transportStats } from "../connection/stats.ts";
import { BroadcastCache } from "../consume.ts";
import type * as datagram from "../datagram.ts";
import * as DatagramStream from "../datagram_stream.ts";
Expand Down Expand Up @@ -74,6 +74,7 @@ import { closeViolation } from "./error.ts";
import { Fetch as FetchMessage } from "./fetch.ts";
import { type Carrier, type Claim, Floors } from "./floors.ts";
import { type Group as GroupMessage, readFrames } from "./group.ts";
import { LinkRtt } from "./link_rtt.ts";
import { Probe } from "./probe.ts";
import { ProbeLevel, type Setup } from "./setup.ts";
import { StreamId } from "./stream.ts";
Expand Down Expand Up @@ -933,6 +934,54 @@ export class Subscriber {
let synced = false;
// Set once the stream lets go of its routes, which then show nothing anew.
let closing = false;
// This link's min RTT, read once a second while the peer has a route, as Rust's
// `Routed::sample`: no route, no timer, and a pause restarts the window.
let link = new LinkRtt();
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
let linkRtt: Duration | undefined;
let sampler: AbortController | undefined;
// The running sampler's first read, settled once it landed or the sampler stopped.
let firstRead = Promise.resolve();
// Returns whether it started a sampler.
const sample = (): boolean => {
if (routes.size === 0 && sampler) {
sampler.abort();
sampler = undefined;
link = new LinkRtt();
linkRtt = undefined;
} else if (routes.size > 0 && !sampler) {
const ctrl = new AbortController();
sampler = ctrl;
const first = Promise.withResolvers<void>();
firstRead = first.promise;
void readLink(ctrl.signal, link, first.resolve);
return true;
}
return false;
};
const readLink = async (signal: AbortSignal, window: LinkRtt, read: () => void) => {
try {
while (!signal.aborted && window.reading) {
const rtt = (await transportStats(this.#quic)).rtt;
if (signal.aborted || closing || announced.closed.peek() !== undefined) return;
// A transport reporting 0 has not measured one.
const now = window.read(rtt?.isZero() ? undefined : rtt);
if (now !== linkRtt) {
linkRtt = now;
// RTT never selects a route, so the consume cache keeps its picks: only the
// reported routes change, each path once.
const paths = new Set<Path.Valid>();
for (const wire of routes.values()) for (const path of wire.view.claims.keys()) paths.add(path);
for (const path of paths) refresh(path, false);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This refresh only reaches the session's internal route stream. Connection.announced() wraps routes() in Announce.list (connection/pool.ts:361), whose next() drops every update that leaves available unchanged (announced.ts:358-361); with the first getStats() read async, a route's present normally carries rtt: undefined and nothing corrects it publicly, which I confirmed with Announce.list directly (this PR's test run also logs start then update). Rust reads the link before serving the first claims (routed.rs:1029), so its Present carries the value.

Technical details
# rtt-only updates are invisible to the public listing

## Affected sites
- `js/net/src/lite/subscriber.ts:961-968` — an RTT change is announced only as a `RouteEvent` of kind `update`, with `available` unchanged.
- `js/net/src/announced.ts:358-361` — `Consumer.next()` continues on any `update`/`restart` whose `available` matches the last report, so the event never becomes a public `Event`.
- `js/net/src/connection/pool.ts:361` — `Session.announced()` is `list(routes())`, so the public connection listing sees the filtered stream; `routes()` is `@internal`.
- `js/net/src/hop.ts:115-123` — `RouteInfo.rtt` reads as a live value, but the only public reader sees it as of `present`.
- `rs/moq-net/src/lite/subscriber/routed.rs:1029` — Rust reads the link synchronously before the first claims are served, so `AnnounceEvent::Present` already carries the rtt.

## Required outcome
- A `Connection.announced()` consumer sees the rtt for a route whose claims arrive before the first `getStats()` resolves, without waiting for an unrelated availability change.
- Behaviour stays equal to Rust: either the value is known by the first `present` (Rust's approach) or the listing reports route changes (Rust deliberately does not).

## Suggested approach (optional)
- Read the link once when the announce stream starts, or await the first read before the first `refresh` of a route's claims: that mirrors Rust's synchronous first read without adding a timer for peers with no route.
- If rtt is meant to stay a present-time snapshot, say so in `RouteInfo.rtt` and in the PR description instead of promising an update, and test what the public listing actually sees (the current `announced.test.ts` assertion only checks that the key exists).

## Open questions for the human (optional)
- Should a route-info change become a public listing event (a new or widened `Announce` event), or should the listing stay availability-only as in Rust?

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in e431c99. Confirmed: Consumer.next() drops every update that leaves availability unchanged, so a read landing after the first claims never reached a public reader. The peer's first route now waits for the sampler's first read before the next message is decoded, so the path's present carries the RTT, as Rust's synchronous read does (the_first_claims_served_carry_the_rtt). The listing stays availability-only, as in Rust, and RouteInfo.rtt's doc says it is as of the event that carries the route. The subscriber test now holds the first stats read until the route's batch is on the stream and expects the start itself to carry 31 ms.

(Written by Claude Fable 5 with high)

}
read();
await sleep(LinkRtt.INTERVAL, { signal });
}
} catch {
// Aborted: the routes went or the stream ended.
} finally {
read();
}
};

const route = (id: bigint): Route => {
const found = routes.get(id);
Expand Down Expand Up @@ -966,6 +1015,11 @@ export class Subscriber {
cost: claim.cost + wire.advert.metric + 1n,
node: wire.node,
available: !wire.held,
// The relay's sum plus this link's own, unknown while either is.
rtt:
wire.advert.rtt !== undefined && linkRtt !== undefined
? linkRtt.checkedAdd(Duration.millis(Number(wire.advert.rtt)))
: undefined,
}),
);

Expand Down Expand Up @@ -1090,8 +1144,14 @@ export class Subscriber {
owner: {},
};
routes.set(id, wire);
const started = sample();
nodes.add(msg.node);
this.#floors.join(msg.node, wire.carrier);
// The link's first read lands before the route's first claims show, as Rust
// reads the link before it serves them: a listing reports a path's route when
// it turns present and not again for an RTT, so a read landing after would
// never reach it.
if (started) await race([firstRead, announced.closed]);
break;
}
case "routeUpdate": {
Expand All @@ -1115,6 +1175,7 @@ export class Subscriber {
claims.delete(id);
}
routes.delete(msg.id);
sample();
nodes.delete(wire.node);
// What its last floor certified stays, so no other stream's lagging claim revives.
this.#floors.leave(wire.node, wire.carrier);
Expand Down Expand Up @@ -1220,6 +1281,7 @@ export class Subscriber {
} finally {
stopDrain?.();
closing = true;
sampler?.abort();
for (const wire of routes.values()) {
this.#floors.leave(wire.node, wire.carrier);
for (const path of wire.view.claims.keys()) this.#consumes.withdraw(path, wire.owner);
Expand Down
1 change: 0 additions & 1 deletion quest/m2/lite07-finalize.md
Original file line number Diff line number Diff line change
Expand Up @@ -133,7 +133,6 @@ transcript freezes at the cut and a flaw in it can only be fixed on the wire.
- [A group a subscriber gives up on is always reported](/quest/m2/group-drops.md) - may add SUBSCRIBE_DROP for a stopped group; leaves this list if it takes the no-wire path
- [Delete the old start bookkeeping](/quest/m2/subscribe-ranges/start-bookkeeping.md) - may change START per update on lite-07
- [Prove cache-aware routing](/quest/m2/cache-routing-proof.md) - may add the warm-route message to lite-07; leaves this list if the proof places it in a SETUP extension
- [Route latency in js/net](/quest/m2/route-latency.md) - js/net reads and writes ROUTE's RTT

## Related

Expand Down
Loading