diff --git a/js/net/api/index.api.md b/js/net/api/index.api.md index e15238f0213..fe2b8194f5f 100644 --- a/js/net/api/index.api.md +++ b/js/net/api/index.api.md @@ -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; diff --git a/js/net/src/announced.test.ts b/js/net/src/announced.test.ts index 6cdeb8aaca3..3150cbe359d 100644 --- a/js/net/src/announced.test.ts +++ b/js/net/src/announced.test.ts @@ -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 () => { diff --git a/js/net/src/hop.ts b/js/net/src/hop.ts index 797787dcf6e..415b9ff5355 100644 --- a/js/net/src/hop.ts +++ b/js/net/src/hop.ts @@ -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"; @@ -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; } /** @@ -124,6 +137,7 @@ export function routeInfo(route: WireRoute): RouteInfo { instance: route.instance, cost: route.cost, available: route.available ?? true, + rtt: route.rtt, }; } @@ -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 */ @@ -193,6 +209,7 @@ export const WireRoute = { draining: route.draining, available: route.available, node: route.node, + rtt: route.rtt, }; }, }; @@ -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 */ @@ -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]) ); diff --git a/js/net/src/lite/link_rtt.test.ts b/js/net/src/lite/link_rtt.test.ts new file mode 100644 index 00000000000..802fe466928 --- /dev/null +++ b/js/net/src/lite/link_rtt.test.ts @@ -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); +}); diff --git a/js/net/src/lite/link_rtt.ts b/js/net/src/lite/link_rtt.ts new file mode 100644 index 00000000000..122675f1a53 --- /dev/null +++ b/js/net/src/lite/link_rtt.ts @@ -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; + } +} diff --git a/js/net/src/lite/subscriber.test.ts b/js/net/src/lite/subscriber.test.ts index dc3d26819cf..f252a6877d7 100644 --- a/js/net/src/lite/subscriber.test.ts +++ b/js/net/src/lite/subscriber.test.ts @@ -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) { 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); @@ -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 +// 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 }); diff --git a/js/net/src/lite/subscriber.ts b/js/net/src/lite/subscriber.ts index 808db75da13..a5b97e1756a 100644 --- a/js/net/src/lite/subscriber.ts +++ b/js/net/src/lite/subscriber.ts @@ -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"; @@ -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"; @@ -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(); + 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(); + 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(); + 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); + } + 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); @@ -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, }), ); @@ -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": { @@ -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); @@ -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); diff --git a/quest/m2/lite07-finalize.md b/quest/m2/lite07-finalize.md index 3aa3d2b8e75..376f73a04e7 100644 --- a/quest/m2/lite07-finalize.md +++ b/quest/m2/lite07-finalize.md @@ -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 diff --git a/quest/m2/route-latency.md b/quest/m2/route-latency.md deleted file mode 100644 index 17b803e2cea..00000000000 --- a/quest/m2/route-latency.md +++ /dev/null @@ -1,39 +0,0 @@ -# [S] Route latency in js/net - -## Goal - -`js/net` reports a lite-07 route's RTT as Rust does: its announced routes -carry the sum the relay advertised plus its own first hop, unknown when the -browser's transport reports no RTT. The sum never ranks or selects a route. - -## Plan - -Decided 2026-11-10 (maintainer, on -[moq-dev/moq#8458](https://github.com/moq-dev/moq/pull/8458)): ✅ lite-07's -ROUTE carries the latency sum, as RTT. Each node adds its link's windowed -minimum, the lowest of the last 30 once-a-second reads of the smoothed RTT, -re-advertised only past max(5 ms, 25%), never QUIC's lifetime min_rtt, which -never rises after a path change. The endpoint adds its own first hop from its -connection. Rejected: no wire change, leaving applications a track of their -own. - -[moq-dev/moq#8458](https://github.com/moq-dev/moq/pull/8458) landed the -draft, the Rust codec and route layer, `origin::RouteInfo::rtt`, and the -bindings' `RouteInfo.rtt`, with no option to withhold it. Its PR body -keeps the sizing simulation: one real shift sends one ROUTE_UPDATE per origin -on each stream downstream of the link, and jitter sends none. - -[moq-dev/moq#8443](https://github.com/moq-dev/moq/pull/8443) landed the -JS route layer with the Flags and RTT codec: a browser advertises its own -route at 0, and the subscriber decodes each route's RTT into its `Advert` -and drops it. What remains: - -- Add `rtt` to `js/net`'s `RouteInfo`, named as Rust's: the advertised sum - plus the same windowed minimum over WebTransport `getStats()`'s smoothed - RTT, and `undefined` while either is unknown. -- Run `just test interop --all`. - -## Related - -- [Routes and announces](/quest/m2/cluster-routing/routes/README.md) - the ROUTE messages this extends -- [Link quality](/quest/m5/link-quality.md) - measured link cost, which feeds selection where this never does