From 106f575cfadfe16619aca258c144f64ac7ad9a8f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 1 Nov 2026 01:25:02 -0700 Subject: [PATCH 1/9] chore(quest): claim quest/m2/performance-survey/browser-idle-stats.md Quest-Claim: 5f02c10328684627 From d38cddafd102a817c1ed34967ddbb739f2a39c96 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 1 Nov 2026 01:43:04 -0700 Subject: [PATCH 2/9] perf(net): sample the send-rate estimate only while a reservation reads it Add a real-browser stats scenario sweeping distinct connections, reservations, receive-only playback, pool linger, pooled handles and qmux. Co-Authored-By: Claude Opus 5.5 --- bench/README.md | 21 +- bench/browser/build.ts | 2 +- bench/browser/calls.ts | 39 ++++ bench/browser/driver.ts | 257 +++++++++++++++++++-- bench/browser/package.json | 1 + bench/browser/page/stats.ts | 292 ++++++++++++++++++++++++ bun.lock | 1 + doc/lib/js/net.md | 2 +- js/net/src/bandwidth.ts | 24 ++ js/net/src/connection/bandwidth.test.ts | 55 ++++- js/net/src/connection/reload.ts | 13 +- 11 files changed, 682 insertions(+), 25 deletions(-) create mode 100644 bench/browser/calls.ts create mode 100644 bench/browser/page/stats.ts diff --git a/bench/README.md b/bench/README.md index 82427ba0cb9..4adde50f65d 100644 --- a/bench/README.md +++ b/bench/README.md @@ -355,7 +355,7 @@ extra copy of every received stream chunk injected into `@moq/net`, the control that shows the suite can see a copy-heavy change), and `base` when a revision is given. Each variant resolves `@moq/*` from its own checkout. Variants alternate within each round, with the starting variant rotated, after one warmup round -(`--rounds`, `--warmup`, `--scenarios transport,cmaf,media`). +(`--rounds`, `--warmup`, `--scenarios transport,cmaf,media,stats`). - `transport`: a publisher page writes 160 B through 1 MiB frames, a consumer page subscribes and reads them all. Connection setup and fixture generation stay @@ -371,6 +371,19 @@ within each round, with the starting variant rotated, after one warmup round window's edges, so decoded-but-unpainted can be off by a frame or two; decoder queue depth (mean, and maximum within the window) comes from a thin `VideoDecoder` wrapper present in every pass. +- `stats`: one page holds `Moq.Connection` handles open while they do nothing + else, to measure local send-rate sampling. Distinct reconnect loops (1, 4, 16) + cross reservations held on each (0, 1, 4); receive-only playback of a 30 fps + track, pooled connections inside the linger window after their last handle + closed, four identical pooled handles (one connection, the control) and qmux + complete the sweep. After a settle, a 2 s window (1.2 s for linger) reports + `getStats` calls and `setTimeout` calls per second, main-thread and process + CPU, and how many reservations hold a send-rate slice. `stats resume` releases + and re-takes a reservation ten times, 500 ms apart, timing its first slice. + Shipping Chromium has no `WebTransport.getStats()`, so this scenario runs in a + second browser with `--enable-blink-features=WebTransportStats`; its `absent` + shapes delete the method again, as shipping Chromium and Safari present it. The + `copy` control does not run here: nothing receives stream chunks in bulk. Costs are split by where they run. Main-thread CPU is CDP `TaskDuration` in thread ticks; process CPU is each page's renderer (every thread, including @@ -380,8 +393,10 @@ keep instrumentation out of timed samples: a traced pass retains a gzipped Chrom trace per workload and reports GC pauses and reclaimed JS heap; a counted pass wraps typed-array constructors, `set` and `slice` to report JS-visible bytes copied and allocated per payload byte during delivery, with connection setup -subtracted; a probed pass reads each presented -frame's painted id back to report frame delay percentiles. Native copies inside +subtracted (for `stats`, V8's sampling heap profiler reports every byte the +window allocated, collected or not); a probed pass reads each presented +frame's painted id back to report frame delay percentiles. The `stats` call +counters are one increment per call and run in every pass. Native copies inside WebTransport and WebCodecs are unavailable, and the report says so. Chromium runs headless with `--disable-gpu`, so decode and rendering are diff --git a/bench/browser/build.ts b/bench/browser/build.ts index 32e2342e395..ed15a036dd5 100644 --- a/bench/browser/build.ts +++ b/bench/browser/build.ts @@ -13,7 +13,7 @@ import { basename, join, resolve } from "node:path"; import type { BunPlugin } from "bun"; import { workspace } from "./workspace.ts"; -const PAGES = ["transport", "cmaf", "media"].map((page) => join(import.meta.dir, "page", `${page}.ts`)); +const PAGES = ["transport", "cmaf", "media", "stats"].map((page) => join(import.meta.dir, "page", `${page}.ts`)); // The one statement every received byte passes through; the control copies it. const CHUNK = "this.#chunks.push(result.value);"; diff --git a/bench/browser/calls.ts b/bench/browser/calls.ts new file mode 100644 index 00000000000..d49d0de79cd --- /dev/null +++ b/bench/browser/calls.ts @@ -0,0 +1,39 @@ +/** + * Init scripts for the sampling scenario, installed before any page module runs. + * + * Each function is serialized into the page, so it must not close over anything. + */ + +/** + * Counts `WebTransport.getStats` calls and every `setTimeout`, the primitive behind + * `@moq/clock` sleeps, on `globalThis.__sampling`. One increment per call, in every pass and + * every variant. The page patches `@moq/qmux`'s `getStats` into the same counter. + */ +export function install(): void { + const counts = { getstats: 0, timers: 0 }; + Object.defineProperty(globalThis, "__sampling", { value: counts }); + const timeout = globalThis.setTimeout; + globalThis.setTimeout = ((handler: TimerHandler, delay?: number, ...args: unknown[]) => { + counts.timers++; + return timeout(handler, delay, ...args); + }) as typeof setTimeout; + const transport = (globalThis as { WebTransport?: { prototype: { getStats?: () => Promise } } }) + .WebTransport?.prototype; + const getStats = transport?.getStats; + if (transport && getStats) + transport.getStats = function (this: unknown) { + counts.getstats++; + return getStats.call(this); + }; +} + +/** Removes WebTransport, as in a browser lacking it, so every dial takes the qmux fallback. */ +export function withoutWebTransport(): void { + Object.defineProperty(globalThis, "WebTransport", { value: undefined, configurable: true, writable: true }); +} + +/** Deletes WebTransport getStats(), which shipping Chromium and Safari do not expose. */ +export function withoutGetStats(): void { + const transport = (globalThis as { WebTransport?: { prototype: { getStats?: unknown } } }).WebTransport; + if (transport) delete transport.prototype.getStats; +} diff --git a/bench/browser/driver.ts b/bench/browser/driver.ts index 174910381db..eb5ba549c7f 100644 --- a/bench/browser/driver.ts +++ b/bench/browser/driver.ts @@ -10,10 +10,12 @@ import { cpus, freemem, loadavg, platform, totalmem } from "node:os"; import { join } from "node:path"; import { parseArgs } from "node:util"; import { type Browser, type CDPSession, chromium, type Page } from "playwright"; +import { install as countCalls, withoutGetStats, withoutWebTransport } from "./calls.ts"; import { install, read } from "./counters.ts"; import { check, digest, payload } from "./fixture.ts"; import type { Cmaf, Phase } from "./page/cmaf.ts"; import type { Media } from "./page/media.ts"; +import type { Counts, Outcome, Sampling } from "./page/stats.ts"; import type { Delivery, Transport } from "./page/transport.ts"; import { compare, type Row, summarize } from "./summary.ts"; @@ -25,7 +27,7 @@ const { values } = parseArgs({ variants: { type: "string" }, rounds: { type: "string", default: "5" }, warmup: { type: "string", default: "1" }, - scenarios: { type: "string", default: "transport,cmaf,media" }, + scenarios: { type: "string", default: "transport,cmaf,media,stats" }, smoke: { type: "boolean", default: false }, timeout: { type: "string", default: "60" }, }, @@ -52,7 +54,7 @@ const warmup = smoke ? 0 : integer("warmup", values.warmup, 0); const timeout = integer("timeout", values.timeout, 1) * 1000; const scenarios = new Set(values.scenarios.split(",")); for (const scenario of scenarios) - if (!["transport", "cmaf", "media"].includes(scenario)) throw new Error(`unknown scenario: ${scenario}`); + if (!["transport", "cmaf", "media", "stats"].includes(scenario)) throw new Error(`unknown scenario: ${scenario}`); // Fixed so a run on another host or day compares like with like. Software rendering and decode: // a hardware path appearing or disappearing would change what is measured. @@ -63,6 +65,10 @@ const FLAGS = [ "--disable-backgrounding-occluded-windows", "--autoplay-policy=no-user-gesture-required", ]; +// Shipping Chromium has no WebTransport getStats(); the stats scenario runs in a second browser +// exposing it, so sampling does the transport work a browser with the API does. Its `absent` +// shapes delete it again, which is what shipping Chromium and Safari present. +const STATS_FLAGS = [...FLAGS, "--enable-blink-features=WebTransportStats"]; // The costs worth reading at a glance; report.json keeps every metric. const HEADLINE = new Set([ @@ -73,6 +79,9 @@ const HEADLINE = new Set([ "watcher_ms_per_s", "publisher_ms_per_s", "presented_fps", + "getstats_per_s", + "main_ms_per_s", + "first_estimate_p50_ms", ]); // Deterministic or one-off metrics from the traced, counted and probed passes. const INSTRUMENTED = /^(copied|allocated|gc_|frame_delay)/; @@ -96,6 +105,36 @@ const CMAF: Cmaf[] = [ const MEDIA = { width: 1280, height: 720, fps: 30, codec: "avc1", bitrate: 2_500_000, keyframe_ms: 1000 }; const MEDIA_WARMUP_MS = smoke ? 1000 : 3000; const MEDIA_WINDOW_MS = smoke ? 3000 : 10000; +/** A sampling shape; `absent` deletes WebTransport getStats(), as shipping Chromium lacks it. */ +type SamplingShape = Omit & { absent?: boolean }; +const grid = (mode: Sampling["mode"], connections: number[], reservations: number[], absent?: boolean) => + connections.flatMap((c) => reservations.map((r): SamplingShape => ({ mode, connections: c, reservations: r, absent }))); +// Distinct connections crossed with reservations held on each, plus receive-only playback, +// pool linger, identical pooled handles (one connection, the control), qmux, and private +// loops on a WebTransport without getStats(). +const SAMPLING: SamplingShape[] = smoke + ? [ + ...grid("private", [1, 4], [0, 1]), + ...grid("receive", [1], [0]), + ...grid("linger", [1], [0]), + ...grid("pooled", [4], [0]), + ...grid("qmux", [1], [0, 1]), + ...grid("private", [1], [0, 1], true), + ] + : [ + ...grid("private", [1, 4, 16], [0, 1, 4]), + ...grid("receive", [1, 16], [0]), + ...grid("linger", [1, 16], [0]), + ...grid("pooled", [4], [0, 1]), + ...grid("qmux", [4], [0, 1]), + ...grid("private", [1, 16], [0, 1], true), + ]; +// Each shape settles before its window, so connection setup stays out of it. Linger's window +// must close inside the pool's two-second linger. +const SAMPLING_SETTLE_MS = 500; +const SAMPLING_WINDOW_MS = smoke ? 1000 : 2000; +const LINGER_WINDOW_MS = 1200; +const RESUME = { cycles: smoke ? 3 : 10, idle_ms: 500, limit_ms: 2000 }; const server = Bun.serve({ hostname: "127.0.0.1", @@ -104,7 +143,7 @@ const server = Bun.serve({ const path = new URL(request.url).pathname; if (path === "/cmaf-fixtures.json") return new Response(Bun.file(new URL("../../js/hang/src/cmaf/fixtures.json", import.meta.url))); - const page = /^\/([a-z0-9-]+)\/(transport|cmaf|media)$/.exec(path); + const page = /^\/([a-z0-9-]+)\/(transport|cmaf|media|stats)$/.exec(path); if (page) return new Response( ``, @@ -129,7 +168,13 @@ const report = { revisions: JSON.parse(process.env.BENCH_REVISIONS ?? "{}"), rounds, warmup, - browser: { executable: process.env.BROWSER_BIN ?? "playwright chromium", version: "", flags: FLAGS, page: {} }, + browser: { + executable: process.env.BROWSER_BIN ?? "playwright chromium", + version: "", + flags: FLAGS, + stats_flags: STATS_FLAGS, + page: {}, + }, host: { platform: platform(), cpu: cpus()[0]?.model, @@ -157,14 +202,25 @@ const save = () => { return saving; }; -const browser: Browser = await chromium.launch({ - channel: process.env.BROWSER_BIN ? undefined : "chromium", - executablePath: process.env.BROWSER_BIN, - headless: true, - args: FLAGS, -}); +interface Chromium { + browser: Browser; + system: CDPSession; +} + +async function launch(args: string[]): Promise { + const browser = await chromium.launch({ + channel: process.env.BROWSER_BIN ? undefined : "chromium", + executablePath: process.env.BROWSER_BIN, + headless: true, + args, + }); + return { browser, system: await browser.newBrowserCDPSession() }; +} + +const main = await launch(FLAGS); +const { browser } = main; report.browser.version = browser.version(); -const system = await browser.newBrowserCDPSession(); +const exposed = scenarios.has("stats") ? await launch(STATS_FLAGS) : undefined; try { for (let round = 0; round < warmup + rounds; round++) { @@ -178,6 +234,13 @@ try { if (scenarios.has("cmaf")) for (const shape of CMAF) for (const variant of order) await sample(cmaf(variant, shape, round, "timed")); if (scenarios.has("media")) for (const variant of order) await sample(media(variant, round, "timed")); + if (scenarios.has("stats")) { + // Nothing here receives stream chunks in bulk, so the copy control measures nothing. + const measured = order.filter((variant) => variant !== "copy"); + for (const shape of SAMPLING) + for (const variant of measured) await sample(sampling(variant, shape, round, "timed")); + for (const variant of measured) await sample(resume(variant, round)); + } } console.log("── traced and counted passes"); for (const variant of variants) { @@ -191,9 +254,15 @@ try { await sample(media(variant, -1, "traced")); await sample(media(variant, -1, "probed")); } + if (scenarios.has("stats") && variant !== "copy") + for (const shape of SAMPLING) { + await sample(sampling(variant, shape, -1, "traced")); + await sample(sampling(variant, shape, -1, "counted")); + } } } finally { await browser.close(); + await exposed?.browser.close(); server.stop(true); const timed = report.samples.filter((row) => row.pass === "timed" && row.round >= warmup); report.summary = summarize(timed); @@ -208,17 +277,25 @@ type Pass = "timed" | "traced" | "counted" | "probed"; interface Opened { page: Page; cdp: CDPSession; + chromium: Chromium; pid: number; errors: string[]; close: () => Promise; } -async function open(variant: string, kind: string, counted = false): Promise { - const context = await browser.newContext({ viewport: { width: 1280, height: 720 } }); +async function open( + variant: string, + kind: string, + counted = false, + init: (() => void)[] = [], + on: Chromium = main, +): Promise { + const context = await on.browser.newContext({ viewport: { width: 1280, height: 720 } }); const page = await context.newPage(); const errors: string[] = []; page.on("pageerror", (error) => errors.push(error.message)); if (counted) await page.addInitScript(install); + for (const script of init) await page.addInitScript(script); await page.goto(`${origin}/${variant}/${kind}`); await page.waitForFunction((kind) => kind in window && "environment" in window, kind); const environment = await page.evaluate(() => window.environment()); @@ -228,11 +305,11 @@ async function open(variant: string, kind: string, counted = false): Promise context.close() }; + return { page, cdp, chromium: on, pid: await rendererPid(page, on.browser), errors, close: () => context.close() }; } // The renderer process behind a page, from the frame list a trace starts with. -async function rendererPid(page: Page): Promise { +async function rendererPid(page: Page, browser: Browser): Promise { await browser.startTracing(page, { categories: ["disabled-by-default-devtools.timeline"] }); const events = traceEvents(await browser.stopTracing()); const url = page.url(); @@ -284,7 +361,7 @@ async function metrics(opened: Opened) { return { main_s: task, heap: value("JSHeapUsedSize") ?? null }; } -async function processes() { +async function processes(system = main.system) { const { processInfo } = (await system.send("SystemInfo.getProcessInfo")) as { processInfo: { type: string; id: number; cpuTime: number }[]; }; @@ -345,6 +422,7 @@ async function trace( page: Page, name: string, run: () => Promise, + browser = main.browser, ): Promise { if (pass !== "traced") { await run(); @@ -633,6 +711,153 @@ async function media(variant: string, round: number, pass: Pass) { } } +async function sampling(variant: string, shape: SamplingShape, round: number, pass: Pass) { + const { absent, ...rest } = shape; + const config: Sampling = { url: relay, path: `stats/${crypto.randomUUID()}`, ...rest }; + const key = `stats ${shape.mode}${absent ? " absent" : ""} c${shape.connections} r${shape.reservations}`; + const init = [countCalls]; + if (shape.mode === "qmux") init.push(withoutWebTransport); + if (absent) init.push(withoutGetStats); + if (!exposed) throw new Error("the stats browser is not running"); + const opened = await open(variant, "stats", false, init, exposed); + try { + await bounded( + opened.page.evaluate((config) => window.stats.setup(config), config), + `${key} setup`, + ); + await Bun.sleep(SAMPLING_SETTLE_MS); + const span = shape.mode === "linger" ? LINGER_WINDOW_MS : SAMPLING_WINDOW_MS; + const snapshot = async () => ({ + at: performance.now(), + counts: await opened.page.evaluate(() => window.stats.counts()), + outcome: await opened.page.evaluate(() => window.stats.outcome()), + page: await metrics(opened), + processes: await processes(exposed.system), + }); + const before = await snapshot(); + if (pass === "counted") { + // Collected objects included: the cost is what the window allocated, not what it kept. + await opened.cdp.send("HeapProfiler.enable"); + await opened.cdp.send("HeapProfiler.startSampling", { + samplingInterval: 256, + includeObjectsCollectedByMajorGC: true, + includeObjectsCollectedByMinorGC: true, + }); + } + const events = await trace( + pass, + opened.page, + `${key.replaceAll(" ", "-")}-${variant}`, + () => Bun.sleep(span), + exposed.browser, + ); + const allocated = + pass === "counted" ? allocatedBytes((await opened.cdp.send("HeapProfiler.stopSampling")).profile.head) : 0; + const after = await snapshot(); + if (opened.errors.length) throw new Error(opened.errors.join("; ")); + const seconds = (after.at - before.at) / 1000; + verify(key, variant, shape, before.outcome, after.outcome); + const rate = (value: number) => value / seconds; + const cpu = processCpu(before.processes, after.processes, { renderer: opened.pid }); + const delta = (name: keyof Counts) => after.counts[name] - before.counts[name]; + const row: Row = { + scenario: "stats", + key, + shape: { ...shape, transport: after.outcome.transport, window_s: seconds }, + variant, + round, + pass, + delivered: { + frames: after.outcome.received - before.outcome.received, + bytes: 0, + digest: after.outcome.estimated, + }, + metrics: { + getstats_per_s: rate(delta("getstats")), + timers_per_s: rate(delta("timers")), + main_ms_per_s: rate((after.page.main_s - before.page.main_s) * 1000), + ...Object.fromEntries(Object.entries(cpu).map(([name, value]) => [`${name}_per_s`, rate(value)])), + estimated: after.outcome.estimated, + received_fps: rate(after.outcome.received - before.outcome.received), + ...(pass === "counted" && { allocated_kib_per_s: rate(allocated / 1024) }), + ...(events && gcMetrics(collections(events, opened.pid))), + }, + heap: { before: before.page.heap, after: after.page.heap }, + load: loadavg(), + }; + record(row); + log(row); + await opened.page.evaluate(() => window.stats.stop()); + } finally { + await opened.close(); + } +} + +// The window must leave every connection working, so doing less cannot read as cheaper. +function verify(key: string, variant: string, shape: SamplingShape, before: Outcome, after: Outcome) { + const fail = (what: string) => { + throw new Error(`${key} ${variant}: ${what}`); + }; + if (after.connected !== shape.connections) fail(`${after.connected} of ${shape.connections} connected`); + const distinct = shape.mode === "pooled" ? 1 : shape.connections; + if (after.estimated > distinct * shape.reservations) fail(`${after.estimated} estimates`); + // Every playing connection reads frames throughout the window. + if (shape.mode === "receive" && after.received - before.received < shape.connections) + fail(`received ${after.received - before.received} frames in the window`); +} + +// Bytes a sampled allocation profile attributes, summed over the whole call tree. +function allocatedBytes(node: { selfSize: number; children: { selfSize: number; children: unknown[] }[] }): number { + let sum = node.selfSize; + for (const child of node.children) sum += allocatedBytes(child as typeof node); + return sum; +} + +// Releases and re-takes a reservation on an idle connection, timing its first send-rate slice. +async function resume(variant: string, round: number) { + const config = { + url: relay, + path: `stats/${crypto.randomUUID()}`, + mode: "private" as const, + connections: 1, + reservations: 0, + ...RESUME, + }; + const key = `stats resume x${RESUME.cycles}`; + if (!exposed) throw new Error("the stats browser is not running"); + const opened = await open(variant, "stats", false, [countCalls], exposed); + try { + const waits = await bounded( + opened.page.evaluate((config) => window.stats.resume(config), config), + `${key} cycles`, + ); + if (opened.errors.length) throw new Error(opened.errors.join("; ")); + const found = waits.filter(Number.isFinite).sort((a, b) => a - b); + const at = (q: number) => found[Math.min(found.length - 1, Math.floor(q * found.length))] ?? Number.NaN; + const row: Row = { + scenario: "stats", + key, + shape: { ...RESUME }, + variant, + round, + pass: "timed", + delivered: { frames: found.length, bytes: 0, digest: waits.length }, + metrics: { + first_estimate_p50_ms: at(0.5), + first_estimate_max_ms: found.at(-1) ?? Number.NaN, + first_estimate_missing: waits.length - found.length, + }, + heap: { before: null, after: null }, + load: loadavg(), + }; + record(row); + log(row); + await opened.page.evaluate(() => window.stats.stop()); + } finally { + await opened.close(); + } +} + // Least-squares bytes per second over [ms, bytes] samples; 0 with fewer than two. function slope(points: [number, number][]): number { if (points.length < 2) return 0; diff --git a/bench/browser/package.json b/bench/browser/package.json index b48d9204666..1f10350c576 100644 --- a/bench/browser/package.json +++ b/bench/browser/package.json @@ -11,6 +11,7 @@ "@moq/hang": "workspace:*", "@moq/net": "workspace:*", "@moq/publish": "workspace:*", + "@moq/qmux": "workspace:*", "@moq/watch": "workspace:*" }, "devDependencies": { diff --git a/bench/browser/page/stats.ts b/bench/browser/page/stats.ts new file mode 100644 index 00000000000..829adb70a02 --- /dev/null +++ b/bench/browser/page/stats.ts @@ -0,0 +1,292 @@ +/** + * Connections held open over a real WebTransport (or qmux) session, to measure what local + * transport-stat sampling costs while they idle, publish, receive, or linger in the pool. + * + * Every connection is a `Moq.Connection` handle, the reconnect loop applications hold. The + * receive shape's publisher dials once with `Moq.Connection.connect`, which runs no loop, so it + * adds the same delivery work to every variant without sampling of its own. + */ +import { Milli } from "@moq/clock"; +import * as Moq from "@moq/net"; +import Session from "@moq/qmux"; +import { check, payload } from "../fixture.ts"; +import "./observe.ts"; + +/** One sampling workload. */ +export interface Sampling { + url: string; + path: string; + /** + * `private`: distinct reconnect loops. `receive`: distinct loops each playing one track. + * `linger`: distinct pooled connections whose last handle closed, inside the linger window. + * `pooled`: identical handles sharing one pooled connection, the control. + * `qmux`: distinct loops over the WebSocket fallback. + */ + mode: "private" | "receive" | "linger" | "pooled" | "qmux"; + /** Distinct connections, or handles on the one connection for `pooled`. */ + connections: number; + /** Reservations held on each distinct connection's allocator. */ + reservations: number; +} + +/** What the window left behind, so a variant that stopped working cannot read as cheaper. */ +export interface Outcome { + connected: number; + /** Reservations reporting a send-rate slice at the end of the window. */ + estimated: number; + /** Frames the receive shape read during the whole run, every byte checked. */ + received: number; + /** The transport the connections negotiated. */ + transport: string; +} + +/** Calls the page made, counted by `calls.ts` wrappers installed before any module ran. */ +export interface Counts { + getstats: number; + timers: number; +} + +const RECEIVE_FPS = 30; +const RECEIVE_BYTES = 1200; + +function counters(): Counts { + const counts = (globalThis as { __sampling?: Counts }).__sampling; + if (!counts) throw new Error("sampling counters are not installed"); + return counts; +} + +// The qmux session's own getStats, which reports nothing, counted alongside WebTransport's. +{ + const proto = Session.prototype as unknown as { getStats: () => Promise }; + const getStats = proto.getStats; + proto.getStats = function (this: Session) { + const counts = (globalThis as { __sampling?: Counts }).__sampling; + if (counts) counts.getstats++; + return getStats.call(this); + }; +} + +const cleanup: (() => void)[] = []; +let handles: Moq.Connection[] = []; +let reservations: Moq.Bandwidth.Reservation[] = []; +let received = 0; +let readers: Promise[] = []; +let lingering = false; + +async function connected(connection: Moq.Connection): Promise { + while (connection.status.peek() !== "connected") { + const error = connection.error.peek(); + if (error) throw error; + await connection.status.changed(); + } +} + +async function allocator(connection: Moq.Connection): Promise { + for (;;) { + const handle = connection.allocator.peek(); + if (handle) return handle; + await connection.allocator.changed(); + } +} + +/** A reservation on `handle` for a fresh, unannounced track: the allocator sees only its demand. */ +function reserve(handle: Moq.Bandwidth.Handle, origin: Moq.Origin.Producer, name: string) { + const publication = origin.createBroadcast(Moq.Path.from(name)); + const track = publication.broadcast.createTrack("video", { priority: 1 }); + const reservation = handle.reserve(track.demand(), 2_500_000); + cleanup.push(() => { + reservation.close(); + track.close(); + publication.broadcast.close(); + }); + return reservation; +} + +/** Opens every connection, waits until each is connected, and leaves the shape's steady state. */ +async function setup(config: Sampling): Promise { + const origin = new Moq.Origin.Producer(); + cleanup.push(() => origin.close()); + const url = (index: number) => { + const url = new URL(config.url); + // Distinct pool keys for linger; private loops ignore sharing anyway. + if (config.mode === "linger") url.searchParams.set("connection", String(index)); + return url; + }; + for (let index = 0; index < config.connections; index++) { + const shared = config.mode === "linger" || config.mode === "pooled"; + const connection = new Moq.Connection({ + url: config.mode === "pooled" ? url(0) : url(index), + share: shared ? undefined : false, + // Any WebSocket option forces a private loop, so pooled shapes take the defaults. + websocket: config.mode === "private" || config.mode === "receive" ? { enabled: false } : undefined, + }); + handles.push(connection); + cleanup.push(() => connection.close()); + } + await Promise.all(handles.map(connected)); + for (const connection of handles) { + const expected = config.mode === "qmux" ? "websocket" : "webtransport"; + if (connection.transport.peek() !== expected) + throw new Error(`negotiated ${connection.transport.peek()}, expected ${expected}`); + } + + // One allocator per distinct connection: pooled handles all lend the same one. + const distinct = config.mode === "pooled" ? handles.slice(0, 1) : handles; + for (const [index, connection] of distinct.entries()) { + const handle = await allocator(connection); + for (let slot = 0; slot < config.reservations; slot++) + reservations.push(reserve(handle, origin, `${config.path}/reserve/${index}/${slot}`)); + } + + if (config.mode === "receive") await receive(config); + if (config.mode === "linger") { + // The handles go; the pooled connections stay up for the linger window. + for (const connection of handles) connection.close(); + lingering = true; + } +} + +/** Publishes one small-frame track and plays it on every connection. */ +async function receive(config: Sampling): Promise { + const publishing = new Moq.Origin.Producer(); + const publication = publishing.createBroadcast(Moq.Path.from(`${config.path}/live`)); + const track = publication.broadcast.createTrack("data", { timescale: Moq.Time.Timescale.MILLI }); + publication.announce(); + const publisher = await Moq.Connection.connect({ + url: new URL(config.url), + publish: publishing.consume(), + websocket: { enabled: false }, + }); + let frame = 0; + const timer = setInterval(() => { + const group = track.appendGroup(); + group.writeFrame({ payload: payload(RECEIVE_BYTES, frame), timestamp: Moq.Time.Timestamp.fromMillis(frame) }); + group.finish(); + frame++; + }, 1000 / RECEIVE_FPS); + cleanup.push(() => { + clearInterval(timer); + track.close(); + publication.broadcast.close(); + publisher.abort(); + publishing.close(); + }); + + for (const connection of handles) { + const origin = await originOf(connection); + const request = origin.follow(Moq.Path.from(`${config.path}/live`)); + cleanup.push(() => request.close()); + const broadcast = await active(request); + const subscriber = broadcast.track("data").subscribe({ maxDelay: Milli(1000) }); + cleanup.push(() => subscriber.close()); + readers.push( + (async () => { + for (;;) { + const group = await subscriber.recvGroup(); + if (!group) return; + try { + const got = await group.readFrame(); + if (!got) continue; + const index = new DataView(got.payload.buffer, got.payload.byteOffset, 4).getUint32(0, true); + check(got.payload, RECEIVE_BYTES, index, true); + received++; + } finally { + group.close(); + } + } + })(), + ); + } + // The window starts once every connection is playing. + const want = received + handles.length; + while (received < want) await new Promise((resolve) => setTimeout(resolve, 10)); +} + +async function originOf(connection: Moq.Connection): Promise { + for (;;) { + const origin = connection.origin.peek(); + if (origin) return origin; + await connection.origin.changed(); + } +} + +async function active(request: Moq.Origin.Requesting): Promise { + for (;;) { + const broadcast = request.active.peek(); + if (broadcast) return broadcast; + const closed = request.closed.peek(); + if (closed !== undefined) throw closed ?? new Error("broadcast request closed"); + await Promise.race([request.active.changed(), request.closed]); + } +} + +function counts(): Counts { + return { ...counters() }; +} + +function outcome(): Outcome { + return { + // A closed handle no longer reports; the pooled connection behind it is still counted live. + connected: lingering ? handles.length : handles.filter((h) => h.status.peek() === "connected").length, + estimated: reservations.filter((reservation) => reservation.peek() !== undefined).length, + received, + transport: handles[0]?.transport.peek() ?? "none", + }; +} + +/** + * Releases and re-takes one reservation `cycles` times, `idle_ms` apart, timing how long each + * new reservation waits for its first send-rate slice. + * + * `undefined` tells a sender to hold its rate, so this is the latency until publishing that + * resumes on an idle connection can follow the estimate again. + */ +async function resume(config: Sampling & { cycles: number; idle_ms: number; limit_ms: number }) { + await setup({ ...config, reservations: 0 }); + const handle = await allocator(handles[0]); + const origin = new Moq.Origin.Producer(); + cleanup.push(() => origin.close()); + const waits: number[] = []; + for (let cycle = 0; cycle < config.cycles; cycle++) { + await new Promise((resolve) => setTimeout(resolve, config.idle_ms)); + const publication = origin.createBroadcast(Moq.Path.from(`${config.path}/resume/${cycle}`)); + const track = publication.broadcast.createTrack("video", { priority: 1 }); + const start = performance.now(); + const reservation = handle.reserve(track.demand(), 2_500_000); + const deadline = start + config.limit_ms; + while (reservation.peek() === undefined && performance.now() < deadline) + await Promise.race([ + reservation.rate.changed(), + new Promise((resolve) => setTimeout(resolve, deadline - performance.now())), + ]); + const rate = reservation.peek(); + waits.push(rate === undefined ? Number.NaN : performance.now() - start); + reservation.close(); + track.close(); + publication.broadcast.close(); + } + return waits; +} + +async function stop(): Promise { + for (const close of cleanup.splice(0).reverse()) close(); + await Promise.allSettled(readers); + handles = []; + reservations = []; + readers = []; + received = 0; + lingering = false; +} + +declare global { + interface Window { + stats: { + setup: typeof setup; + counts: typeof counts; + outcome: typeof outcome; + resume: typeof resume; + stop: typeof stop; + }; + } +} +window.stats = { setup, counts, outcome, resume, stop }; diff --git a/bun.lock b/bun.lock index 19e1320f058..d69dab6ccb3 100644 --- a/bun.lock +++ b/bun.lock @@ -28,6 +28,7 @@ "@moq/hang": "workspace:*", "@moq/net": "workspace:*", "@moq/publish": "workspace:*", + "@moq/qmux": "workspace:*", "@moq/watch": "workspace:*", }, "devDependencies": { diff --git a/doc/lib/js/net.md b/doc/lib/js/net.md index 75fac1d3423..96642f9b7b4 100644 --- a/doc/lib/js/net.md +++ b/doc/lib/js/net.md @@ -46,7 +46,7 @@ publication.announce(); - **Discovery follows what you watch.** A `consume` origin asks the relay for announcements only under the prefixes its readers watch with `announced(scope)`, `request(path)`, or `follow(path)`, stops asking about a prefix 2s after nothing at or beneath it is watched, and asks again on reconnect. Every request and follower watches its path from creation until closed, so it outlives the listing that found it. A relay that refuses an announce request downgrades that session: requests subscribe blind through it, and followers keep waiting for a session that can discover. - **Connections share by URL and versions.** `new Connection({ url })` pools and reconnects with backoff, which the elements use. An ordered `versions` list, spelled like `moq-lite-06` as in Rust, applies to both WebTransport and WebSocket; equivalent lists share, while a different order or an omitted list gets its own pool entry. Supplying your own transport options or origin selects a private loop. Receive estimates are on demand: observe `connection.probe` reactively or subscribe while you need them; `peek()` alone opens no PROBE stream. - **GOAWAY moves the session.** The connection dials the replacement at once while the old session keeps serving its groups, up to `goaway.handover` (default 10s, or the relay's deadline when that is sooner). New requests keep opening on the old session until the replacement's route outranks it, which is a restart without an epoch: an unpinned announced request follows the replacement, while a blind or epoch-pinned request stays on its accepted instance. With an epoch, which travels only when `moq-lite-07-wip` is offered, the replacement serves the same broadcast, so open subscriptions move across without missing a group. An empty GOAWAY redials the same URL. A redirect stays on the same host unless `goaway.redirect` is `"follow"`, which also presents the tokens on the connection's `auth` handle to the new host. -- **One send estimate per connection.** `Bandwidth.Allocator` divides it by track priority, max-min fair within a tier. An idle track claims nothing, though its reservation still reads the share it would get. Publishers reserve against it so their targets sum to the estimate. +- **One send estimate per connection.** `Bandwidth.Allocator` divides it by track priority, max-min fair within a tier. An idle track claims nothing, though its reservation still reads the share it would get. Publishers reserve against it so their targets sum to the estimate. A connection samples the estimate from its transport only while a reservation reads it, so receive-only and lingering connections do no stats work, and the first reservation after none reads `undefined` until one fresh snapshot lands. - **List a broadcast's tracks.** `for await (const event of broadcast.tracks())` reports each track the broadcast lists (`added`, with its `Track.Info`), one `synced`, then `added` and `removed` as tracks come and go, until the broadcast ends; leaving the loop stops listing. Over a session it needs `moq-lite-07-wip`, syncs at once with what this side holds, and the peer's tracks follow as `added`. A track served only on request is never listed. See [discovery](/concept/moq-lite#discovery). - **One track per name.** Concurrent subscriptions share one request and producer. `createTrack` on a name with a request still queued answers it. The application owns sequence numbers: the broadcast keeps nothing of an ended track, so a track that replaces it, created or requested, starts at 0. A name always means the same content, so the replacement continues past its predecessor's groups by writing its first group with an explicit sequence. - **Timing is per track, with no default.** A track that declares a `timescale` carries a `timestamp` on every frame; one without is [untimed](/concept/moq-lite#subscriptions) and its frames carry none. Omitting it means untimed, as in Rust. Nothing stamps a frame for you: the publisher passes the timestamp, and the `Timed` type (`{ value, at }`) carries one into the `@moq/json` producers. diff --git a/js/net/src/bandwidth.ts b/js/net/src/bandwidth.ts index 5e2788d2d1a..45affb56737 100644 --- a/js/net/src/bandwidth.ts +++ b/js/net/src/bandwidth.ts @@ -136,6 +136,20 @@ export interface Handle { reserve(track: Demand, max: number): Reservation; } +// Assigned by Allocator's static block, which runs before any instance exists. +let reservedOf: (allocator: Allocator) => Getter; + +/** + * Whether `allocator` holds a reservation that reads the estimate. + * + * The estimate's source can stop sampling while this is false: nothing reads it. + * + * @internal + */ +export function reserved(allocator: Allocator): Getter { + return reservedOf(allocator); +} + /** * Divides one connection's bandwidth estimate among the tracks sharing it. * @@ -154,6 +168,7 @@ export class Allocator implements Handle { #estimate: Getter | undefined; #entries = new Signal([]); #alive = new Signal(true); + #reserved = new Signal(false); #nextId = 0; #signals = new Effect(); #registry: Registry; @@ -177,14 +192,22 @@ export class Allocator implements Handle { if (!effect.get(this.#alive)) return; if (this.#estimate) effect.get(this.#estimate); const entries = effect.get(this.#entries); + let reserved = false; for (const entry of entries) { effect.get(entry.demand.wanted); effect.get(hooks.demandReleased(entry.demand)); + // The same test shareOf applies: a closed demand reads no slice. + if (effect.get(entry.demand.closed) === undefined) reserved = true; } + this.#reserved.set(reserved); this.#publish(); }); } + static { + reservedOf = (allocator) => allocator.#reserved; + } + /** * An allocator with nothing to divide, so every reservation reports `undefined`. * @@ -246,6 +269,7 @@ export class Allocator implements Handle { close(): void { if (!this.#alive.peek()) return; this.#alive.set(false); + this.#reserved.set(false); for (const entry of this.#entries.peek()) { entry.rate.set(undefined); } diff --git a/js/net/src/connection/bandwidth.test.ts b/js/net/src/connection/bandwidth.test.ts index 49b370d7492..1a6084ac208 100644 --- a/js/net/src/connection/bandwidth.test.ts +++ b/js/net/src/connection/bandwidth.test.ts @@ -1,5 +1,5 @@ import { afterEach, expect, test } from "bun:test"; -import { Instant, Milli, Nano, now, yieldNow } from "@moq/clock"; +import { Instant, Milli, Nano, now, sleep, yieldNow } from "@moq/clock"; import * as Lite from "../lite/index.ts"; import { createMockTransportPair } from "../mock.ts"; import { Producer as TrackProducer } from "../track.ts"; @@ -116,6 +116,59 @@ test("an idle track on a live connection claims nothing", async () => { } }); +test("a connection samples the transport only while a reservation reads the estimate", async () => { + let calls = 0; + const stub = function StubWebTransport() { + const pair = createMockTransportPair(Lite.ALPN_06, { stats: { estimatedSendRate: 2_000_000 } }); + const getStats = pair.client.getStats.bind(pair.client); + pair.client.getStats = () => { + calls++; + return getStats(); + }; + void accept(pair.server, url); + return pair.client; + }; + globalThis.WebTransport = stub as unknown as typeof WebTransport; + const idle = async () => { + const before = calls; + await sleep(Nano.fromMilli(Milli(350))); + return calls - before; + }; + + const connection = new Connection({ url }); + try { + await waitUntil(() => connection.status.peek() === "connected"); + const allocator = connection.allocator.peek(); + if (!allocator) throw new Error("missing allocator"); + // Connected with nothing reserved: no snapshots at all. + expect(await idle()).toBe(0); + + const track = new TrackProducer("video").accept({ priority: 60 }); + track.subscribe(); + const first = allocator.reserve(track.demand(), 4_000_000); + await waitUntil(() => first.peek() === 2_000_000); + expect(await idle()).toBeGreaterThan(0); + + // A snapshot already in flight may land; nothing is scheduled after it. + first.close(); + await sleep(Nano.fromMilli(Milli(50))); + expect(await idle()).toBe(0); + + // The estimate cleared with the last reservation, so the next reads nothing stale. + const second = allocator.reserve(track.demand(), 4_000_000); + expect(second.peek()).toBeUndefined(); + await waitUntil(() => second.peek() === 2_000_000); + + // A closed track's reservation reads no slice, so it stops the sampling too. + track.close(); + await sleep(Nano.fromMilli(Milli(50))); + expect(await idle()).toBe(0); + second.close(); + } finally { + connection.close(); + } +}); + test("a private connection still exposes an allocator", async () => { stubTransport({ estimatedSendRate: 2_000_000 }); diff --git a/js/net/src/connection/reload.ts b/js/net/src/connection/reload.ts index 92326220384..570f3e9a241 100644 --- a/js/net/src/connection/reload.ts +++ b/js/net/src/connection/reload.ts @@ -3,7 +3,7 @@ import { Effect, type GetPromise, type Getter, Once, Signal } from "@moq/signals import type * as Announce from "../announced.ts"; import { Handle as AuthHandle } from "../auth.ts"; import { ended } from "../auth_session.ts"; -import { Allocator } from "../bandwidth.ts"; +import { Allocator, reserved } from "../bandwidth.ts"; import { error, reason, SessionCode, SessionError } from "../error.ts"; import type { Consumer as OriginConsumer, Producer as OriginProducer } from "../origin.ts"; import * as Path from "../path.ts"; @@ -162,7 +162,7 @@ function pacing(delay: ReloadDelay) { }; } -/** How often the send-rate estimate is sampled from the live transport. */ +/** How often the send-rate estimate is sampled from the live transport while a reservation reads it. */ const BANDWIDTH_POLL = Nano.fromMilli(Milli(100)); /** Current state of a reconnecting connection. */ @@ -219,7 +219,9 @@ export class Reload { * * The same instance across reconnects, so reservations survive a drop. The * estimate is `undefined` while disconnected, which tells a sender to hold - * its rate rather than encode at zero. + * its rate rather than encode at zero. It is sampled from the transport only + * while a reservation reads it, so the first reservation after none waits one + * snapshot for its slice. */ readonly allocator: Allocator; @@ -410,8 +412,13 @@ export class Reload { // The transport has no event for the send-rate estimate, so sample on our // own schedule and skip a tick while the previous snapshot is outstanding. + // Only while a reservation reads it: a receive-only or lingering connection + // would otherwise snapshot the transport ten times a second for nobody. The + // estimate clears with the last reservation, so the next one never reads a + // stale figure. this.#signals.run((effect) => { effect.set(this.#estimate, undefined); + if (!effect.get(reserved(this.allocator))) return; const connection = effect.get(this.established); if (!connection) return; From 2fdf68043bbc1400bc3d48b3c0d14f5575d084c6 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 1 Nov 2026 01:11:57 -0800 Subject: [PATCH 3/9] quest: finish browser idle stats Format the stats driver and delete the completed quest. Co-Authored-By: Claude Opus 5.5 --- bench/browser/driver.ts | 4 ++- quest/m2/performance-survey/README.md | 1 - .../performance-survey/browser-idle-stats.md | 26 ------------------- 3 files changed, 3 insertions(+), 28 deletions(-) delete mode 100644 quest/m2/performance-survey/browser-idle-stats.md diff --git a/bench/browser/driver.ts b/bench/browser/driver.ts index eb5ba549c7f..7d87a873fc4 100644 --- a/bench/browser/driver.ts +++ b/bench/browser/driver.ts @@ -108,7 +108,9 @@ const MEDIA_WINDOW_MS = smoke ? 3000 : 10000; /** A sampling shape; `absent` deletes WebTransport getStats(), as shipping Chromium lacks it. */ type SamplingShape = Omit & { absent?: boolean }; const grid = (mode: Sampling["mode"], connections: number[], reservations: number[], absent?: boolean) => - connections.flatMap((c) => reservations.map((r): SamplingShape => ({ mode, connections: c, reservations: r, absent }))); + connections.flatMap((c) => + reservations.map((r): SamplingShape => ({ mode, connections: c, reservations: r, absent })), + ); // Distinct connections crossed with reservations held on each, plus receive-only playback, // pool linger, identical pooled handles (one connection, the control), qmux, and private // loops on a WebTransport without getStats(). diff --git a/quest/m2/performance-survey/README.md b/quest/m2/performance-survey/README.md index c25cce3d3b9..82cb91fca53 100644 --- a/quest/m2/performance-survey/README.md +++ b/quest/m2/performance-survey/README.md @@ -184,7 +184,6 @@ No duplicate quest or workflow edit belongs here. - [QUIC scheduling churn](/quest/m2/performance-survey/quic-schedule-churn.md) - priority and retirement work across unrelated groups - [HLS request fan-out](/quest/m2/performance-survey/hls-serving.md) - repeated fetch, remux and playlist construction per viewer - [Buffered browser groups](/quest/m2/performance-survey/hang-buffered.md) - per-frame scans and bulk skip work -- [Idle browser stats](/quest/m2/performance-survey/browser-idle-stats.md) - local transport polling without active publishing demand - [Transport preference history](/quest/m2/performance-survey/transport-history.md) - full URL retention across retired sessions - [Resume identity history](/quest/m2/performance-survey/resume-history.md) - historical source graphs held by first-seen track metadata - [UDP socket queues](/quest/m2/performance-survey/socket-queues.md) - drop attribution and queue-size tradeoffs across workers and load diff --git a/quest/m2/performance-survey/browser-idle-stats.md b/quest/m2/performance-survey/browser-idle-stats.md deleted file mode 100644 index 6ab8cfd8e2b..00000000000 --- a/quest/m2/performance-survey/browser-idle-stats.md +++ /dev/null @@ -1,26 +0,0 @@ -# [M] Local bandwidth sampling follows demand - -## Goal - -Browser connections avoid unnecessary local transport-stat work while -preserving useful send-rate estimates when publishing needs them. - -## Plan - -[Reload](/js/net/src/connection/reload.ts) samples `connection.stats()` every -100 ms whenever established, independently of active bandwidth reservations. -This includes receive-only connections and pooled sessions during linger. -[QMux stats](/js/net/src/connection/stats.ts) still allocates an empty result -when the transport has no `getStats`. Remote PROBE observation is separate. - -In the real browser harness, sweep distinct connections × active publishing -reservations. Include zero reservations, receive-only playback, active/idle -transitions, pool linger and QMux. Identical pooled handles are a control, -not distinct network connections. Count timers, real `getStats` calls, -allocations/GC and main-thread CPU; measure first useful estimate latency -after publishing resumes. Keep current cadence as the baseline before -choosing demand gating or any changed sampling policy. - -Follow the [survey benchmark contract](/quest/m2/performance-survey/README.md): -baseline first, paired evidence, equivalent work and nightly coverage. A -measured no-win is valid. No API or wire change is expected; report actual impact. From 6fb280dcb9bb5d7076a502da1031d475b161311c Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 1 Nov 2026 01:19:54 -0800 Subject: [PATCH 4/9] test(net): drive the sampling gate test with a manual clock Co-Authored-By: Claude Opus 5.5 --- js/net/src/connection/bandwidth.test.ts | 33 +++++++++++++++---------- 1 file changed, 20 insertions(+), 13 deletions(-) diff --git a/js/net/src/connection/bandwidth.test.ts b/js/net/src/connection/bandwidth.test.ts index 1a6084ac208..a757a54a588 100644 --- a/js/net/src/connection/bandwidth.test.ts +++ b/js/net/src/connection/bandwidth.test.ts @@ -1,5 +1,5 @@ import { afterEach, expect, test } from "bun:test"; -import { Instant, Milli, Nano, now, sleep, yieldNow } from "@moq/clock"; +import { Instant, Manual, Milli, Nano, now, yieldNow } from "@moq/clock"; import * as Lite from "../lite/index.ts"; import { createMockTransportPair } from "../mock.ts"; import { Producer as TrackProducer } from "../track.ts"; @@ -117,6 +117,8 @@ test("an idle track on a live connection claims nothing", async () => { }); test("a connection samples the transport only while a reservation reads the estimate", async () => { + const clock = new Manual(); + const installed = clock.install(); let calls = 0; const stub = function StubWebTransport() { const pair = createMockTransportPair(Lite.ALPN_06, { stats: { estimatedSendRate: 2_000_000 } }); @@ -129,43 +131,48 @@ test("a connection samples the transport only while a reservation reads the esti return pair.client; }; globalThis.WebTransport = stub as unknown as typeof WebTransport; - const idle = async () => { + const advance = (ms: number) => clock.advance(Nano.fromMilli(Milli(ms))); + // Snapshots taken over 350 ms of manual time, enough for three 100 ms ticks. + const sampled = async () => { const before = calls; - await sleep(Nano.fromMilli(Milli(350))); + await advance(350); return calls - before; }; const connection = new Connection({ url }); try { - await waitUntil(() => connection.status.peek() === "connected"); + await advance(0); + expect(connection.status.peek()).toBe("connected"); const allocator = connection.allocator.peek(); if (!allocator) throw new Error("missing allocator"); // Connected with nothing reserved: no snapshots at all. - expect(await idle()).toBe(0); + expect(await sampled()).toBe(0); const track = new TrackProducer("video").accept({ priority: 60 }); track.subscribe(); const first = allocator.reserve(track.demand(), 4_000_000); - await waitUntil(() => first.peek() === 2_000_000); - expect(await idle()).toBeGreaterThan(0); + await advance(0); + expect(first.peek()).toBe(2_000_000); + expect(await sampled()).toBe(3); - // A snapshot already in flight may land; nothing is scheduled after it. first.close(); - await sleep(Nano.fromMilli(Milli(50))); - expect(await idle()).toBe(0); + await advance(0); + expect(await sampled()).toBe(0); // The estimate cleared with the last reservation, so the next reads nothing stale. const second = allocator.reserve(track.demand(), 4_000_000); expect(second.peek()).toBeUndefined(); - await waitUntil(() => second.peek() === 2_000_000); + await advance(0); + expect(second.peek()).toBe(2_000_000); // A closed track's reservation reads no slice, so it stops the sampling too. track.close(); - await sleep(Nano.fromMilli(Milli(50))); - expect(await idle()).toBe(0); + await advance(0); + expect(await sampled()).toBe(0); second.close(); } finally { connection.close(); + installed.close(); } }); From d8a305ceabb5e0c7ad8a2ae0e53363ab19726714 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 1 Nov 2026 14:29:34 -0800 Subject: [PATCH 5/9] perf(net): skip send-rate sampling on transports that cannot report it A reservation no longer starts the 100 ms getStats loop over the WebSocket fallback, WebRTC, or WebTransport without getStats(). Each session records at construction whether its transport can report an estimate; the estimate stays undefined there, as before. Co-Authored-By: Claude Opus 5.5 --- doc/lib/js/net.md | 2 +- js/net/src/connection/bandwidth.test.ts | 53 ++++++++++++++++++++++- js/net/src/connection/reload.ts | 10 +++-- js/net/src/connection/stats.test.ts | 57 ++++++++++++++++++++++++- js/net/src/connection/stats.ts | 31 ++++++++++++++ js/net/src/ietf/connection.ts | 3 +- js/net/src/lite/connection.ts | 3 +- 7 files changed, 148 insertions(+), 11 deletions(-) diff --git a/doc/lib/js/net.md b/doc/lib/js/net.md index fe6924db1d0..2172a15d5e5 100644 --- a/doc/lib/js/net.md +++ b/doc/lib/js/net.md @@ -46,7 +46,7 @@ publication.announce(); - **Discovery follows what you watch.** A `consume` origin asks the relay for announcements only under the prefixes its readers watch with `announced(scope)`, `request(path)`, or `follow(path)`, stops asking about a prefix 2s after nothing at or beneath it is watched, and asks again on reconnect. Every request and follower watches its path from creation until closed, so it outlives the listing that found it. A relay that refuses an announce request downgrades that session: requests subscribe blind through it, and followers keep waiting for a session that can discover. - **Connections share by URL and versions.** `new Connection({ url })` pools and reconnects with backoff, which the elements use. An ordered `versions` list, spelled like `moq-lite-06` as in Rust, applies to both WebTransport and WebSocket; equivalent lists share, while a different order or an omitted list gets its own pool entry. Supplying your own transport options or origin selects a private loop. Receive estimates are on demand: observe `connection.probe` reactively or subscribe while you need them; `peek()` alone opens no PROBE stream. - **GOAWAY moves the session.** The connection dials the replacement at once while the old session keeps serving its groups, up to `goaway.handover` (default 10s, or the relay's deadline when that is sooner). New requests keep opening on the old session until the replacement's route outranks it, which is a restart without an epoch: an unpinned announced request follows the replacement, while a blind or epoch-pinned request stays on its accepted instance. With an epoch, which travels only when `moq-lite-07-wip` is offered, the replacement serves the same broadcast, so open subscriptions move across without missing a group. An empty GOAWAY redials the same URL. A redirect stays on the same host unless `goaway.redirect` is `"follow"`, which also presents the tokens on the connection's `auth` handle to the new host. -- **One send estimate per connection.** `Bandwidth.Allocator` divides it by track priority, max-min fair within a tier. An idle track claims nothing, though its reservation still reads the share it would get. Publishers reserve against it so their targets sum to the estimate. A connection samples the estimate from its transport only while a reservation reads it, so receive-only and lingering connections do no stats work, and the first reservation after none reads `undefined` until one fresh snapshot lands. +- **One send estimate per connection.** `Bandwidth.Allocator` divides it by track priority, max-min fair within a tier. An idle track claims nothing, though its reservation still reads the share it would get. Publishers reserve against it so their targets sum to the estimate. A connection samples the estimate from its transport only while a reservation reads it, so receive-only and lingering connections do no stats work, and the first reservation after none reads `undefined` until one fresh snapshot lands. A transport that cannot report one is never sampled and reads `undefined`: the WebSocket fallback, WebRTC, and WebTransport without `getStats()` (shipping Chromium and Safari). - **List a broadcast's tracks.** `for await (const event of broadcast.tracks())` reports each track the broadcast lists (`added`, with its `Track.Info`), one `synced`, then `added` and `removed` as tracks come and go, until the broadcast ends; leaving the loop stops listing. Over a session it needs `moq-lite-07-wip`, syncs at once with what this side holds, and the peer's tracks follow as `added`. A track served only on request is never listed. See [discovery](/concept/moq-lite#discovery). - **One track per name.** Concurrent subscriptions share one request and producer. `createTrack` on a name with a request still queued answers it. The application owns sequence numbers: the broadcast keeps nothing of an ended track, so a track that replaces it, created or requested, starts at 0. A name always means the same content, so the replacement continues past its predecessor's groups by writing its first group with an explicit sequence. - **Timing is per track, with no default.** A track that declares a `timescale` carries a `timestamp` on every frame; one without is [untimed](/concept/moq-lite#subscriptions) and its frames carry none. Omitting it means untimed, as in Rust. Nothing stamps a frame for you: the publisher passes the timestamp, and the `Timed` type (`{ value, at }`) carries one into the `@moq/json` producers. diff --git a/js/net/src/connection/bandwidth.test.ts b/js/net/src/connection/bandwidth.test.ts index a757a54a588..50081cccbc0 100644 --- a/js/net/src/connection/bandwidth.test.ts +++ b/js/net/src/connection/bandwidth.test.ts @@ -1,7 +1,7 @@ -import { afterEach, expect, test } from "bun:test"; +import { afterEach, expect, spyOn, test } from "bun:test"; import { Instant, Manual, Milli, Nano, now, yieldNow } from "@moq/clock"; import * as Lite from "../lite/index.ts"; -import { createMockTransportPair } from "../mock.ts"; +import { createMockTransportPair, type MockTransport } from "../mock.ts"; import { Producer as TrackProducer } from "../track.ts"; import { type AcceptProps, accept as acceptSession } from "./index.ts"; import { Connection, resetShared } from "./pool.ts"; @@ -176,6 +176,55 @@ test("a connection samples the transport only while a reservation reads the esti } }); +// The WebSocket fallback is covered where sessions detect their transport (stats.test.ts): +// a dial that reads as one would mark the URL as WebSocket-preferred for later tests. +const silent: { name: string; shape: (quic: MockTransport) => void }[] = [ + { + name: "WebTransport without getStats", + shape: (quic) => { + (quic as unknown as { getStats?: unknown }).getStats = undefined; + }, + }, + { name: "WebRTC", shape: (quic) => Object.assign(quic, { transport: "webrtc" }) }, +]; + +for (const kind of silent) { + test(`a reservation over ${kind.name} starts no sampling`, async () => { + const clock = new Manual(); + const installed = clock.install(); + const stub = function StubWebTransport() { + const pair = createMockTransportPair(Lite.ALPN_06, { stats: { estimatedSendRate: 2_000_000 } }); + kind.shape(pair.client); + void accept(pair.server, url); + return pair.client; + }; + globalThis.WebTransport = stub as unknown as typeof WebTransport; + const snapshots = spyOn(Lite.Connection.prototype, "stats"); + + const connection = new Connection({ url }); + try { + await clock.advance(Nano.zero); + expect(connection.status.peek()).toBe("connected"); + const allocator = connection.allocator.peek(); + if (!allocator) throw new Error("missing allocator"); + + const track = new TrackProducer("video").accept({ priority: 60 }); + track.subscribe(); + const reservation = allocator.reserve(track.demand(), 4_000_000); + await clock.advance(Nano.fromMilli(Milli(350))); + expect(snapshots).toHaveBeenCalledTimes(0); + // The estimate stays unknown, so the sender holds its rate. + expect(reservation.peek()).toBeUndefined(); + reservation.close(); + track.close(); + } finally { + connection.close(); + snapshots.mockRestore(); + installed.close(); + } + }); +} + test("a private connection still exposes an allocator", async () => { stubTransport({ estimatedSendRate: 2_000_000 }); diff --git a/js/net/src/connection/reload.ts b/js/net/src/connection/reload.ts index 570f3e9a241..0e9dcb5c7e4 100644 --- a/js/net/src/connection/reload.ts +++ b/js/net/src/connection/reload.ts @@ -19,7 +19,7 @@ import { import type { Established } from "./established.ts"; import { DISCOVERY_REMOVED } from "./forward.ts"; import { DEFAULT_HANDOVER, type Drain, dialed, type GoawayProps, handover, pinnedTransport, target } from "./goaway.ts"; -import type { Probe } from "./stats.ts"; +import { estimates, type Probe } from "./stats.ts"; import { heldOf } from "./tokens.ts"; function sameTokens(a: readonly string[], b: readonly string[]): boolean { @@ -221,7 +221,9 @@ export class Reload { * estimate is `undefined` while disconnected, which tells a sender to hold * its rate rather than encode at zero. It is sampled from the transport only * while a reservation reads it, so the first reservation after none waits one - * snapshot for its slice. + * snapshot for its slice. It stays `undefined` on a transport that cannot + * report one: the WebSocket fallback, WebRTC, or WebTransport without + * `getStats()`. */ readonly allocator: Allocator; @@ -415,12 +417,12 @@ export class Reload { // Only while a reservation reads it: a receive-only or lingering connection // would otherwise snapshot the transport ten times a second for nobody. The // estimate clears with the last reservation, so the next one never reads a - // stale figure. + // stale figure. A transport that can never report one is not sampled at all. this.#signals.run((effect) => { effect.set(this.#estimate, undefined); if (!effect.get(reserved(this.allocator))) return; const connection = effect.get(this.established); - if (!connection) return; + if (!connection || !estimates(connection)) return; let pending = false; const sample = async () => { diff --git a/js/net/src/connection/stats.test.ts b/js/net/src/connection/stats.test.ts index 48680f57190..87117c84316 100644 --- a/js/net/src/connection/stats.test.ts +++ b/js/net/src/connection/stats.test.ts @@ -1,12 +1,13 @@ import { expect, spyOn, test } from "bun:test"; import { Manual, Milli, Nano, yieldNow } from "@moq/clock"; +import QmuxSession from "@moq/qmux"; import { Effect } from "@moq/signals"; import * as Ietf from "../ietf/index.ts"; import * as Lite from "../lite/index.ts"; -import { createMockTransportPair } from "../mock.ts"; +import { createMockTransportPair, MockTransport } from "../mock.ts"; import { type AcceptProps, accept as acceptSession, type ConnectProps, connect as connectSession } from "./index.ts"; import { Reload } from "./reload.ts"; -import { type TransportStats, transportStats } from "./stats.ts"; +import { canEstimate, estimates, type TransportStats, transportStats } from "./stats.ts"; function connect(url: URL, props: Omit = {}) { return connectSession({ url, ...props }); @@ -103,6 +104,58 @@ test("probe starts empty and stays empty without PROBE support", async () => { } }); +// Each wire transport, imitated on a mock so only what it can report differs. +const kinds: { name: string; estimates: boolean; shape: (quic: MockTransport) => void }[] = [ + { name: "WebTransport with getStats", estimates: true, shape: () => {} }, + { + name: "WebTransport without getStats", + estimates: false, + // Shipping Chromium and Safari implement no getStats(). + shape: (quic) => { + (quic as unknown as { getStats?: unknown }).getStats = undefined; + }, + }, + { + name: "the WebSocket fallback", + estimates: false, + // A qmux session is what marks the fallback; the mock keeps its own behavior. + shape: (quic) => { + const proto = Object.create(QmuxSession.prototype); + Object.defineProperties(proto, Object.getOwnPropertyDescriptors(MockTransport.prototype)); + Object.setPrototypeOf(quic, proto); + }, + }, + { + name: "WebRTC", + estimates: false, + shape: (quic) => { + Object.assign(quic, { transport: "webrtc" }); + }, + }, +]; + +for (const kind of kinds) { + for (const alpn of [Lite.ALPN_06, Ietf.ALPN.DRAFT_18]) { + test(`a ${alpn} session over ${kind.name} ${kind.estimates ? "can" : "cannot"} report a send-rate estimate`, async () => { + const pair = createMockTransportPair(alpn, { stats: { estimatedSendRate: 2_000_000 } }); + kind.shape(pair.client); + expect(canEstimate(pair.client)).toBe(kind.estimates); + const url = new URL("https://example.com/"); + const [client, server] = await Promise.all([ + connect(url, { transport: pair.client }), + accept(pair.server, url), + ]); + try { + expect(estimates(client)).toBe(kind.estimates); + expect(estimates(server)).toBe(true); + } finally { + client.abort(); + server.abort(); + } + }); + } +} + test("Reload exposes its established session stats and probe only while connected", async () => { const original = globalThis.WebTransport; const pair = createMockTransportPair(Lite.ALPN_06, { stats: { bytesSent: 99 } }); diff --git a/js/net/src/connection/stats.ts b/js/net/src/connection/stats.ts index 66db14449af..25fccbe8578 100644 --- a/js/net/src/connection/stats.ts +++ b/js/net/src/connection/stats.ts @@ -1,4 +1,6 @@ import { Milli } from "@moq/clock"; +import type { Established } from "./established.ts"; +import { transportOf } from "./transport.ts"; /** * Connection statistics: what the local transport counts, and what the peer reports. * @@ -119,3 +121,32 @@ export async function transportStats(quic: WebTransport): Promise { return {}; } } + +/** + * Whether `quic` can report a send-rate estimate: only a WebTransport session with + * `getStats()`. The WebSocket fallback's qmux session reports no counters, the WebRTC + * data channel's throws, and shipping Chromium and Safari implement none. + * + * @internal + */ +export function canEstimate(quic: WebTransport): boolean { + if (transportOf(quic) !== "webtransport") return false; + return typeof (quic as { getStats?: unknown }).getStats === "function"; +} + +// The sessions whose transport can report a send-rate estimate. +const estimating = new WeakSet(); + +/** Record whether `session`'s transport `quic` can report a send-rate estimate. @internal */ +export function detect(session: Established, quic: WebTransport): void { + if (canEstimate(quic)) estimating.add(session); +} + +/** + * Whether `session` can report a send-rate estimate, so sampling it is worth a timer. + * + * @internal + */ +export function estimates(session: Established): boolean { + return estimating.has(session); +} diff --git a/js/net/src/ietf/connection.ts b/js/net/src/ietf/connection.ts index f8f67b9e022..e7214ff2b36 100644 --- a/js/net/src/ietf/connection.ts +++ b/js/net/src/ietf/connection.ts @@ -5,7 +5,7 @@ import type * as Auth from "../auth.ts"; import { AuthSession } from "../auth_session.ts"; import type { Established } from "../connection/established.ts"; import type { Drain } from "../connection/goaway.ts"; -import { type Probe, type Stats, transportStats } from "../connection/stats.ts"; +import { detect, type Probe, type Stats, transportStats } from "../connection/stats.ts"; import { type Transport, transportOf } from "../connection/transport.ts"; import { error, fromClose, ProtocolViolation, SessionCode, StreamCode, StreamError, sessionClosed } from "../error.ts"; import type { Consumer as OriginConsumer } from "../origin.ts"; @@ -169,6 +169,7 @@ export class Connection implements Established { this.url = url; this.version = versionName(version); this.transport = transportOf(quic); + detect(this, quic); this.#quic = quic; this.#client = client; this.peerImplementation = Promise.resolve(peerImplementation); diff --git a/js/net/src/lite/connection.ts b/js/net/src/lite/connection.ts index 4e01c5fb2fd..6bf4327dace 100644 --- a/js/net/src/lite/connection.ts +++ b/js/net/src/lite/connection.ts @@ -5,7 +5,7 @@ import type * as Auth from "../auth.ts"; import { AuthSession } from "../auth_session.ts"; import type { Established } from "../connection/established.ts"; import type { Drain } from "../connection/goaway.ts"; -import { type Probe, type Stats, transportStats } from "../connection/stats.ts"; +import { detect, type Probe, type Stats, transportStats } from "../connection/stats.ts"; import { type Transport, transportOf } from "../connection/transport.ts"; import { closeError, error, fromClose, ProtocolViolation, StreamCode, sessionCause } from "../error.ts"; import { type Hop, randomHop } from "../hop.ts"; @@ -186,6 +186,7 @@ export class Connection implements Established { this.version = versionName(version); this.#version = version; this.transport = transportOf(quic); + detect(this, quic); this.probe = this.#probe; From 1dedce190ee147592876405115ac88952c4dc19c Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 2 Nov 2026 22:30:30 -0800 Subject: [PATCH 6/9] fix(bench): fail the stats scenario when supported reservations lose their estimate A window now requires every reservation over a WebTransport with getStats() to hold a slice, and none over qmux or without getStats(), so a regression that stops sampling cannot read as cheaper. A resume cycle that never gets its slice fails the run. The checks move to sampling.ts with negative tests. Also migrates the stats page to main's track Delay { min, max }. Co-Authored-By: Claude Opus 5.5 --- bench/README.md | 7 ++++-- bench/browser/build.ts | 4 ++- bench/browser/driver.ts | 29 +++++++--------------- bench/browser/page/stats.ts | 2 +- bench/browser/sampling.test.ts | 45 ++++++++++++++++++++++++++++++++++ bench/browser/sampling.ts | 35 ++++++++++++++++++++++++++ 6 files changed, 98 insertions(+), 24 deletions(-) create mode 100644 bench/browser/sampling.test.ts create mode 100644 bench/browser/sampling.ts diff --git a/bench/README.md b/bench/README.md index e2ffc5f2092..04019736bb9 100644 --- a/bench/README.md +++ b/bench/README.md @@ -482,8 +482,11 @@ order-independent digest must match, so skipped work cannot read as a speedup. CMAF output is decoded and checked byte for byte in a separate call after each phase's CPU and trace snapshots. Crashes, wrong bytes, missing frames, a window that presents nothing, a racing -dial that fails or a forced racing arm won by the other transport, or an -unavailable CPU clock fail the run; timing never does. The nightly runs +dial that fails or a forced racing arm won by the other transport, a stats +window whose reservations hold more or fewer send-rate slices than the transport +can give (every one over WebTransport with `getStats()`, none over qmux or +without it), a resume cycle that never gets its slice, or an unavailable CPU +clock fail the run; timing never does. The nightly runs `--smoke`, whose racing sweep runs every mode and a rotated query at 4 URLs x 2 reconnects x 64 characters, and keeps its run directory as the `bench-browser` artifact. diff --git a/bench/browser/build.ts b/bench/browser/build.ts index 12900940575..dd631651e53 100644 --- a/bench/browser/build.ts +++ b/bench/browser/build.ts @@ -13,7 +13,9 @@ import { basename, join, resolve } from "node:path"; import type { BunPlugin } from "bun"; import { workspace } from "./workspace.ts"; -const PAGES = ["transport", "cmaf", "media", "racing", "stats"].map((page) => join(import.meta.dir, "page", `${page}.ts`)); +const PAGES = ["transport", "cmaf", "media", "racing", "stats"].map((page) => + join(import.meta.dir, "page", `${page}.ts`), +); // The one statement every received byte passes through; the control copies it. const CHUNK = "this.#chunks.push(result.value);"; diff --git a/bench/browser/driver.ts b/bench/browser/driver.ts index 3c063b9b3ee..acae4ed1300 100644 --- a/bench/browser/driver.ts +++ b/bench/browser/driver.ts @@ -16,8 +16,9 @@ import { check, digest, payload } from "./fixture.ts"; import type { Cmaf, Phase } from "./page/cmaf.ts"; import type { Media } from "./page/media.ts"; import type { Dial, Mode, Racing } from "./page/racing.ts"; -import type { Counts, Outcome, Sampling } from "./page/stats.ts"; +import type { Counts, Sampling } from "./page/stats.ts"; import type { Delivery, Transport } from "./page/transport.ts"; +import { resumeFailure, type SamplingShape, samplingFailure } from "./sampling.ts"; import { compare, type Row, summarize } from "./summary.ts"; import { collections, GC_CATEGORIES, rendererPid, type TraceEvent, traceEvents } from "./trace.ts"; @@ -56,7 +57,8 @@ const warmup = smoke ? 0 : integer("warmup", values.warmup, 0); const timeout = integer("timeout", values.timeout, 1) * 1000; const scenarios = new Set(values.scenarios.split(",")); for (const scenario of scenarios) - if (!["transport", "cmaf", "media", "racing", "stats"].includes(scenario)) throw new Error(`unknown scenario: ${scenario}`); + if (!["transport", "cmaf", "media", "racing", "stats"].includes(scenario)) + throw new Error(`unknown scenario: ${scenario}`); // Fixed so a run on another host or day compares like with like. Software rendering and decode: // a hardware path appearing or disappearing would change what is measured. @@ -149,8 +151,6 @@ const RACING_LINGER_MS = 2500; const MEDIA = { width: 1280, height: 720, fps: 30, codec: "avc1", bitrate: 2_500_000, keyframe_ms: 1000 }; const MEDIA_WARMUP_MS = smoke ? 1000 : 3000; const MEDIA_WINDOW_MS = smoke ? 3000 : 10000; -/** A sampling shape; `absent` deletes WebTransport getStats(), as shipping Chromium lacks it. */ -type SamplingShape = Omit & { absent?: boolean }; const grid = (mode: Sampling["mode"], connections: number[], reservations: number[], absent?: boolean) => connections.flatMap((c) => reservations.map((r): SamplingShape => ({ mode, connections: c, reservations: r, absent })), @@ -897,7 +897,8 @@ async function sampling(variant: string, shape: SamplingShape, round: number, pa const after = await snapshot(); if (opened.errors.length) throw new Error(opened.errors.join("; ")); const seconds = (after.at - before.at) / 1000; - verify(key, variant, shape, before.outcome, after.outcome); + const failure = samplingFailure(shape, before.outcome, after.outcome); + if (failure) throw new Error(`${key} ${variant}: ${failure}`); const rate = (value: number) => value / seconds; const cpu = processCpu(before.processes, after.processes, { renderer: opened.pid }); const delta = (name: keyof Counts) => after.counts[name] - before.counts[name]; @@ -934,19 +935,6 @@ async function sampling(variant: string, shape: SamplingShape, round: number, pa } } -// The window must leave every connection working, so doing less cannot read as cheaper. -function verify(key: string, variant: string, shape: SamplingShape, before: Outcome, after: Outcome) { - const fail = (what: string) => { - throw new Error(`${key} ${variant}: ${what}`); - }; - if (after.connected !== shape.connections) fail(`${after.connected} of ${shape.connections} connected`); - const distinct = shape.mode === "pooled" ? 1 : shape.connections; - if (after.estimated > distinct * shape.reservations) fail(`${after.estimated} estimates`); - // Every playing connection reads frames throughout the window. - if (shape.mode === "receive" && after.received - before.received < shape.connections) - fail(`received ${after.received - before.received} frames in the window`); -} - // Bytes a sampled allocation profile attributes, summed over the whole call tree. function allocatedBytes(node: { selfSize: number; children: { selfSize: number; children: unknown[] }[] }): number { let sum = node.selfSize; @@ -973,7 +961,9 @@ async function resume(variant: string, round: number) { `${key} cycles`, ); if (opened.errors.length) throw new Error(opened.errors.join("; ")); - const found = waits.filter(Number.isFinite).sort((a, b) => a - b); + const failure = resumeFailure(waits); + if (failure) throw new Error(`${key} ${variant}: ${failure}`); + const found = waits.toSorted((a, b) => a - b); const at = (q: number) => found[Math.min(found.length - 1, Math.floor(q * found.length))] ?? Number.NaN; const row: Row = { scenario: "stats", @@ -986,7 +976,6 @@ async function resume(variant: string, round: number) { metrics: { first_estimate_p50_ms: at(0.5), first_estimate_max_ms: found.at(-1) ?? Number.NaN, - first_estimate_missing: waits.length - found.length, }, heap: { before: null, after: null }, load: loadavg(), diff --git a/bench/browser/page/stats.ts b/bench/browser/page/stats.ts index 829adb70a02..66620dfc39e 100644 --- a/bench/browser/page/stats.ts +++ b/bench/browser/page/stats.ts @@ -177,7 +177,7 @@ async function receive(config: Sampling): Promise { const request = origin.follow(Moq.Path.from(`${config.path}/live`)); cleanup.push(() => request.close()); const broadcast = await active(request); - const subscriber = broadcast.track("data").subscribe({ maxDelay: Milli(1000) }); + const subscriber = broadcast.track("data").subscribe({ delay: { max: Milli(1000) } }); cleanup.push(() => subscriber.close()); readers.push( (async () => { diff --git a/bench/browser/sampling.test.ts b/bench/browser/sampling.test.ts new file mode 100644 index 00000000000..72e9f9a5fa9 --- /dev/null +++ b/bench/browser/sampling.test.ts @@ -0,0 +1,45 @@ +import { expect, test } from "bun:test"; +import type { Outcome } from "./page/stats.ts"; +import { expectedEstimates, resumeFailure, type SamplingShape, samplingFailure } from "./sampling.ts"; + +const outcome = (estimated: number, connected = 4, received = 0): Outcome => ({ + connected, + estimated, + received, + transport: "webtransport", +}); + +test("only reservations over a WebTransport with getStats() expect a slice", () => { + expect(expectedEstimates({ mode: "private", connections: 4, reservations: 4 })).toBe(16); + expect(expectedEstimates({ mode: "pooled", connections: 4, reservations: 1 })).toBe(1); + expect(expectedEstimates({ mode: "private", connections: 4, reservations: 0 })).toBe(0); + expect(expectedEstimates({ mode: "qmux", connections: 4, reservations: 1 })).toBe(0); + expect(expectedEstimates({ mode: "private", connections: 4, reservations: 1, absent: true })).toBe(0); +}); + +test("a window where sampling stopped fails rather than reading as cheaper", () => { + const shape: SamplingShape = { mode: "private", connections: 4, reservations: 1 }; + expect(samplingFailure(shape, outcome(0), outcome(4))).toBeUndefined(); + expect(samplingFailure(shape, outcome(0), outcome(0))).toBe("0 of 4 expected estimates"); + expect(samplingFailure(shape, outcome(0), outcome(3))).toBe("3 of 4 expected estimates"); +}); + +test("an estimate where none can exist fails", () => { + const shape: SamplingShape = { mode: "qmux", connections: 4, reservations: 1 }; + expect(samplingFailure(shape, outcome(0), outcome(0))).toBeUndefined(); + expect(samplingFailure(shape, outcome(0), outcome(1))).toBe("1 of 0 expected estimates"); +}); + +test("lost connections and stalled playback fail", () => { + expect(samplingFailure({ mode: "private", connections: 4, reservations: 0 }, outcome(0), outcome(0, 3))).toBe( + "3 of 4 connected", + ); + const receive: SamplingShape = { mode: "receive", connections: 4, reservations: 0 }; + expect(samplingFailure(receive, outcome(0, 4, 10), outcome(0, 4, 13))).toBe("received 3 frames in the window"); + expect(samplingFailure(receive, outcome(0, 4, 10), outcome(0, 4, 70))).toBeUndefined(); +}); + +test("a resume cycle that never got its slice fails", () => { + expect(resumeFailure([0.4, 0.5, 0.6])).toBeUndefined(); + expect(resumeFailure([0.4, Number.NaN, Number.NaN])).toBe("2 of 3 cycles never got a send-rate slice"); +}); diff --git a/bench/browser/sampling.ts b/bench/browser/sampling.ts new file mode 100644 index 00000000000..f64418aaf48 --- /dev/null +++ b/bench/browser/sampling.ts @@ -0,0 +1,35 @@ +/** Checks that a stats scenario window left every connection doing its work, so doing less cannot read as cheaper. */ +import type { Outcome, Sampling } from "./page/stats.ts"; + +/** A sampling shape; `absent` deletes WebTransport getStats(), as shipping Chromium lacks it. */ +export type SamplingShape = Omit & { absent?: boolean }; + +/** + * Reservations that must hold a send-rate slice at the end of the window. + * + * Each one on a WebTransport with getStats() does; none can over qmux or without getStats(). + * Identical pooled handles share one connection, so only its reservations count. + */ +export function expectedEstimates(shape: SamplingShape): number { + if (shape.mode === "qmux" || shape.absent) return 0; + const distinct = shape.mode === "pooled" ? 1 : shape.connections; + return distinct * shape.reservations; +} + +/** Why the window does not count as equivalent work, or `undefined` when it does. */ +export function samplingFailure(shape: SamplingShape, before: Outcome, after: Outcome): string | undefined { + if (after.connected !== shape.connections) return `${after.connected} of ${shape.connections} connected`; + const expected = expectedEstimates(shape); + if (after.estimated !== expected) return `${after.estimated} of ${expected} expected estimates`; + // Every playing connection reads frames throughout the window. + if (shape.mode === "receive" && after.received - before.received < shape.connections) + return `received ${after.received - before.received} frames in the window`; + return undefined; +} + +/** Why the resume cycles failed, or `undefined` when every cycle got its first slice. */ +export function resumeFailure(waits: number[]): string | undefined { + const missing = waits.filter((wait) => !Number.isFinite(wait)).length; + if (missing) return `${missing} of ${waits.length} cycles never got a send-rate slice`; + return undefined; +} From 959d6ba3dc3960216e765e4ca9f6caaab9cdfc83 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 2 Nov 2026 22:30:42 -0800 Subject: [PATCH 7/9] docs(bench): list the stats scenario in run.sh usage Co-Authored-By: Claude Opus 5.5 --- bench/browser/run.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/bench/browser/run.sh b/bench/browser/run.sh index ca8d613244c..b45d72b240b 100755 --- a/bench/browser/run.sh +++ b/bench/browser/run.sh @@ -1,7 +1,7 @@ #!/usr/bin/env bash # Real-browser transport and media benchmarks against a temporary relay. # -# bench/browser/run.sh [BASE] [--smoke] [--rounds N] [--scenarios transport,cmaf,media,racing] +# bench/browser/run.sh [BASE] [--smoke] [--rounds N] [--scenarios transport,cmaf,media,racing,stats] # # Variants, each bundled from the same page sources: # current this checkout, the reference From a4886dd3d49a90f6230967c316fb53ce18812348 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 2 Nov 2026 22:43:30 -0800 Subject: [PATCH 8/9] fix(bench): require every receive-shape reader to advance The stats receive shape counted frames across all readers, so one healthy reader could hide 15 stalled ones in the window and in setup. Count frames per connection: setup waits for each to play, and the window fails when any reader reads nothing. Co-Authored-By: Claude Opus 5.5 --- bench/browser/driver.ts | 6 +++--- bench/browser/page/stats.ts | 16 ++++++++-------- bench/browser/sampling.test.ts | 22 +++++++++++++++++----- bench/browser/sampling.ts | 13 +++++++++++-- 4 files changed, 39 insertions(+), 18 deletions(-) diff --git a/bench/browser/driver.ts b/bench/browser/driver.ts index acae4ed1300..09d3bcf4703 100644 --- a/bench/browser/driver.ts +++ b/bench/browser/driver.ts @@ -18,7 +18,7 @@ import type { Media } from "./page/media.ts"; import type { Dial, Mode, Racing } from "./page/racing.ts"; import type { Counts, Sampling } from "./page/stats.ts"; import type { Delivery, Transport } from "./page/transport.ts"; -import { resumeFailure, type SamplingShape, samplingFailure } from "./sampling.ts"; +import { resumeFailure, type SamplingShape, samplingFailure, total } from "./sampling.ts"; import { compare, type Row, summarize } from "./summary.ts"; import { collections, GC_CATEGORIES, rendererPid, type TraceEvent, traceEvents } from "./trace.ts"; @@ -910,7 +910,7 @@ async function sampling(variant: string, shape: SamplingShape, round: number, pa round, pass, delivered: { - frames: after.outcome.received - before.outcome.received, + frames: total(after.outcome.received) - total(before.outcome.received), bytes: 0, digest: after.outcome.estimated, }, @@ -920,7 +920,7 @@ async function sampling(variant: string, shape: SamplingShape, round: number, pa main_ms_per_s: rate((after.page.main_s - before.page.main_s) * 1000), ...Object.fromEntries(Object.entries(cpu).map(([name, value]) => [`${name}_per_s`, rate(value)])), estimated: after.outcome.estimated, - received_fps: rate(after.outcome.received - before.outcome.received), + received_fps: rate(total(after.outcome.received) - total(before.outcome.received)), ...(pass === "counted" && { allocated_kib_per_s: rate(allocated / 1024) }), ...(events && gcMetrics(collections(events, opened.pid))), }, diff --git a/bench/browser/page/stats.ts b/bench/browser/page/stats.ts index 66620dfc39e..39c6a2de2bc 100644 --- a/bench/browser/page/stats.ts +++ b/bench/browser/page/stats.ts @@ -34,8 +34,8 @@ export interface Outcome { connected: number; /** Reservations reporting a send-rate slice at the end of the window. */ estimated: number; - /** Frames the receive shape read during the whole run, every byte checked. */ - received: number; + /** Frames each receive-shape connection read during the whole run, every byte checked. */ + received: number[]; /** The transport the connections negotiated. */ transport: string; } @@ -69,7 +69,7 @@ function counters(): Counts { const cleanup: (() => void)[] = []; let handles: Moq.Connection[] = []; let reservations: Moq.Bandwidth.Reservation[] = []; -let received = 0; +let received: number[] = []; let readers: Promise[] = []; let lingering = false; @@ -179,6 +179,7 @@ async function receive(config: Sampling): Promise { const broadcast = await active(request); const subscriber = broadcast.track("data").subscribe({ delay: { max: Milli(1000) } }); cleanup.push(() => subscriber.close()); + const reader = received.push(0) - 1; readers.push( (async () => { for (;;) { @@ -189,7 +190,7 @@ async function receive(config: Sampling): Promise { if (!got) continue; const index = new DataView(got.payload.buffer, got.payload.byteOffset, 4).getUint32(0, true); check(got.payload, RECEIVE_BYTES, index, true); - received++; + received[reader]++; } finally { group.close(); } @@ -198,8 +199,7 @@ async function receive(config: Sampling): Promise { ); } // The window starts once every connection is playing. - const want = received + handles.length; - while (received < want) await new Promise((resolve) => setTimeout(resolve, 10)); + while (received.some((frames) => frames === 0)) await new Promise((resolve) => setTimeout(resolve, 10)); } async function originOf(connection: Moq.Connection): Promise { @@ -229,7 +229,7 @@ function outcome(): Outcome { // A closed handle no longer reports; the pooled connection behind it is still counted live. connected: lingering ? handles.length : handles.filter((h) => h.status.peek() === "connected").length, estimated: reservations.filter((reservation) => reservation.peek() !== undefined).length, - received, + received: [...received], transport: handles[0]?.transport.peek() ?? "none", }; } @@ -274,7 +274,7 @@ async function stop(): Promise { handles = []; reservations = []; readers = []; - received = 0; + received = []; lingering = false; } diff --git a/bench/browser/sampling.test.ts b/bench/browser/sampling.test.ts index 72e9f9a5fa9..81f830489e2 100644 --- a/bench/browser/sampling.test.ts +++ b/bench/browser/sampling.test.ts @@ -1,8 +1,8 @@ import { expect, test } from "bun:test"; import type { Outcome } from "./page/stats.ts"; -import { expectedEstimates, resumeFailure, type SamplingShape, samplingFailure } from "./sampling.ts"; +import { expectedEstimates, resumeFailure, type SamplingShape, samplingFailure, total } from "./sampling.ts"; -const outcome = (estimated: number, connected = 4, received = 0): Outcome => ({ +const outcome = (estimated: number, connected = 4, received: number[] = []): Outcome => ({ connected, estimated, received, @@ -30,13 +30,25 @@ test("an estimate where none can exist fails", () => { expect(samplingFailure(shape, outcome(0), outcome(1))).toBe("1 of 0 expected estimates"); }); -test("lost connections and stalled playback fail", () => { +test("lost connections fail", () => { expect(samplingFailure({ mode: "private", connections: 4, reservations: 0 }, outcome(0), outcome(0, 3))).toBe( "3 of 4 connected", ); +}); + +test("one stalled reader fails even while the others keep playing", () => { const receive: SamplingShape = { mode: "receive", connections: 4, reservations: 0 }; - expect(samplingFailure(receive, outcome(0, 4, 10), outcome(0, 4, 13))).toBe("received 3 frames in the window"); - expect(samplingFailure(receive, outcome(0, 4, 10), outcome(0, 4, 70))).toBeUndefined(); + const before = outcome(0, 4, [10, 10, 10, 10]); + expect(samplingFailure(receive, before, outcome(0, 4, [70, 70, 70, 70]))).toBeUndefined(); + expect(samplingFailure(receive, before, outcome(0, 4, [250, 10, 10, 10]))).toBe( + "3 of 4 connections received no frames in the window", + ); + expect(samplingFailure(receive, before, outcome(0, 4, [70, 70, 70]))).toBe("3 of 4 connections receiving"); +}); + +test("total sums every connection's frames", () => { + expect(total([1, 2, 3])).toBe(6); + expect(total([])).toBe(0); }); test("a resume cycle that never got its slice fails", () => { diff --git a/bench/browser/sampling.ts b/bench/browser/sampling.ts index f64418aaf48..a3f0c21da2e 100644 --- a/bench/browser/sampling.ts +++ b/bench/browser/sampling.ts @@ -22,11 +22,20 @@ export function samplingFailure(shape: SamplingShape, before: Outcome, after: Ou const expected = expectedEstimates(shape); if (after.estimated !== expected) return `${after.estimated} of ${expected} expected estimates`; // Every playing connection reads frames throughout the window. - if (shape.mode === "receive" && after.received - before.received < shape.connections) - return `received ${after.received - before.received} frames in the window`; + if (shape.mode === "receive") { + if (after.received.length !== shape.connections) + return `${after.received.length} of ${shape.connections} connections receiving`; + const stalled = after.received.filter((frames, index) => frames <= (before.received[index] ?? 0)).length; + if (stalled) return `${stalled} of ${shape.connections} connections received no frames in the window`; + } return undefined; } +/** Frames read across every connection. */ +export function total(received: number[]): number { + return received.reduce((sum, frames) => sum + frames, 0); +} + /** Why the resume cycles failed, or `undefined` when every cycle got its first slice. */ export function resumeFailure(waits: number[]): string | undefined { const missing = waits.filter((wait) => !Number.isFinite(wait)).length; From 1482af38c8617189de5fd261147753d76fae7f27 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 2 Nov 2026 22:56:14 -0800 Subject: [PATCH 9/9] fix(bench): type the stats page's follow handle as Origin.Following Co-Authored-By: Claude Opus 5.5 --- bench/browser/page/stats.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/bench/browser/page/stats.ts b/bench/browser/page/stats.ts index 39c6a2de2bc..1af8a34d759 100644 --- a/bench/browser/page/stats.ts +++ b/bench/browser/page/stats.ts @@ -210,7 +210,7 @@ async function originOf(connection: Moq.Connection): Promise { } } -async function active(request: Moq.Origin.Requesting): Promise { +async function active(request: Moq.Origin.Following): Promise { for (;;) { const broadcast = request.active.peek(); if (broadcast) return broadcast;