diff --git a/bench/README.md b/bench/README.md index 503336e2200..ea7b418b9a6 100644 --- a/bench/README.md +++ b/bench/README.md @@ -404,7 +404,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,racing`). +(`--rounds`, `--warmup`, `--scenarios transport,cmaf,media,racing,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 @@ -437,6 +437,19 @@ within each round, with the starting variant rotated, after one warmup round collection, a heap snapshot counts the flat strings still holding the run's URL marker, with their V8 object bytes and characters. A forced arm's winner is checked; an open race's is only reported. +- `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 @@ -446,8 +459,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 @@ -472,8 +487,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 2d675c7f377..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"].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/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 9f2646f61c2..09d3bcf4703 100644 --- a/bench/browser/driver.ts +++ b/bench/browser/driver.ts @@ -10,12 +10,15 @@ 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 { 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, total } from "./sampling.ts"; import { compare, type Row, summarize } from "./summary.ts"; import { collections, GC_CATEGORIES, rendererPid, type TraceEvent, traceEvents } from "./trace.ts"; @@ -27,7 +30,7 @@ const { values } = parseArgs({ variants: { type: "string" }, rounds: { type: "string", default: "5" }, warmup: { type: "string", default: "1" }, - scenarios: { type: "string", default: "transport,cmaf,media,racing" }, + scenarios: { type: "string", default: "transport,cmaf,media,racing,stats" }, smoke: { type: "boolean", default: false }, timeout: { type: "string", default: "60" }, }, @@ -54,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"].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. @@ -65,6 +69,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([ @@ -75,6 +83,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", "connect_p50_ms", "retained_strings", ]); @@ -140,6 +151,36 @@ 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; +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", @@ -148,7 +189,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|racing)$/.exec(path); + const page = /^\/([a-z0-9-]+)\/(transport|cmaf|media|racing|stats)$/.exec(path); if (page) return new Response( ``, @@ -173,7 +214,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, @@ -203,14 +250,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++) { @@ -224,6 +282,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)); + } if (scenarios.has("racing")) for (const shape of RACING) for (const variant of order) await sample(racing(variant, shape, round)); } @@ -239,9 +304,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); @@ -256,17 +327,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()); @@ -276,11 +355,11 @@ async function open(variant: string, kind: string, counted = false): Promise context.close() }; + return { page, cdp, chromium: on, pid: await pagePid(page, on.browser), errors, close: () => context.close() }; } // The renderer process behind a page, from the frame list a trace starts with. -async function pagePid(page: Page): Promise { +async function pagePid(page: Page, browser: Browser): Promise { await browser.startTracing(page, { categories: ["disabled-by-default-devtools.timeline"] }); return rendererPid(traceEvents(await browser.stopTracing()), page.url()); } @@ -293,7 +372,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 }[]; }; @@ -354,6 +433,7 @@ async function trace( page: Page, name: string, run: () => Promise, + browser = main.browser, ): Promise { if (pass !== "traced") { await run(); @@ -772,6 +852,142 @@ 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; + 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]; + const row: Row = { + scenario: "stats", + key, + shape: { ...shape, transport: after.outcome.transport, window_s: seconds }, + variant, + round, + pass, + delivered: { + frames: total(after.outcome.received) - total(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(total(after.outcome.received) - total(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(); + } +} + +// 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 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", + 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, + }, + 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..1af8a34d759 --- /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 each receive-shape connection 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: number[] = []; +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({ delay: { max: Milli(1000) } }); + cleanup.push(() => subscriber.close()); + const reader = received.push(0) - 1; + 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[reader]++; + } finally { + group.close(); + } + } + })(), + ); + } + // The window starts once every connection is playing. + while (received.some((frames) => frames === 0)) 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.Following): 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: [...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 = []; + 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/bench/browser/run.sh b/bench/browser/run.sh index 3f4c2b3409b..596d8b9d0ee 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 diff --git a/bench/browser/sampling.test.ts b/bench/browser/sampling.test.ts new file mode 100644 index 00000000000..81f830489e2 --- /dev/null +++ b/bench/browser/sampling.test.ts @@ -0,0 +1,57 @@ +import { expect, test } from "bun:test"; +import type { Outcome } from "./page/stats.ts"; +import { expectedEstimates, resumeFailure, type SamplingShape, samplingFailure, total } from "./sampling.ts"; + +const outcome = (estimated: number, connected = 4, received: number[] = []): 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 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 }; + 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", () => { + 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..a3f0c21da2e --- /dev/null +++ b/bench/browser/sampling.ts @@ -0,0 +1,44 @@ +/** 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") { + 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; + if (missing) return `${missing} of ${waits.length} cycles never got a send-rate slice`; + return undefined; +} diff --git a/bun.lock b/bun.lock index 8a34739da90..fc9233c400c 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 307f5bffa71..b5146994597 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 when the instance did not cross: an unpinned announced request follows the replacement, while a blind or instance-pinned request stays on its accepted stream. When `moq-lite-07-wip` is offered the instance crosses, the replacement serves the same stream, and 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. A one-shot session from `Connection.connect` never moves on its own; its `draining` settles with the GOAWAY, so you can connect again and close it. Its URI is the peer's to choose and `goaway.redirect` does not apply, so validate it before dialing it or presenting tokens to it. -- **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. 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/bandwidth.ts b/js/net/src/bandwidth.ts index c2cccbc1356..c679196b875 100644 --- a/js/net/src/bandwidth.ts +++ b/js/net/src/bandwidth.ts @@ -196,6 +196,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. * @@ -214,6 +228,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; @@ -240,14 +255,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`. * @@ -309,6 +332,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..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 { Instant, Milli, Nano, now, yieldNow } from "@moq/clock"; +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"; @@ -116,6 +116,115 @@ 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 } }); + 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 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 advance(350); + return calls - before; + }; + + const connection = new Connection({ url }); + try { + 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 sampled()).toBe(0); + + const track = new TrackProducer("video").accept({ priority: 60 }); + track.subscribe(); + const first = allocator.reserve(track.demand(), 4_000_000); + await advance(0); + expect(first.peek()).toBe(2_000_000); + expect(await sampled()).toBe(3); + + first.close(); + 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 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 advance(0); + expect(await sampled()).toBe(0); + second.close(); + } finally { + connection.close(); + installed.close(); + } +}); + +// 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 243fb0b7862..5f54d89f33c 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"; @@ -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 { @@ -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,11 @@ 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. It stays `undefined` on a transport that cannot + * report one: the WebSocket fallback, WebRTC, or WebTransport without + * `getStats()`. */ readonly allocator: Allocator; @@ -410,10 +414,15 @@ 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. 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 f21f6e3dc76..abd10cb73b5 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 9214bddf444..cde3e63081c 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; diff --git a/quest/m2/performance-survey/README.md b/quest/m2/performance-survey/README.md index 11be7a70dfb..756655b7eb2 100644 --- a/quest/m2/performance-survey/README.md +++ b/quest/m2/performance-survey/README.md @@ -210,7 +210,6 @@ The `js/replay` nightly series and the browser smoke's `replay.json` protect it. - [Cache metadata](/quest/m2/performance-survey/cache-metadata.md) - bookkeeping capacity after cached groups expire - [PCM batch processing](/quest/m2/performance-survey/audio-batches.md) - repeated tail movement during encoding and resampling - [HLS request fan-out](/quest/m2/performance-survey/hls-serving.md) - repeated fetch, remux and playlist construction per viewer -- [Idle browser stats](/quest/m2/performance-survey/browser-idle-stats.md) - local transport polling without active publishing demand - [Announcement snapshots](/quest/m2/performance-survey/announced-snapshots.md) - HTTP polling cost versus result size and unrelated routes - [Selective session operations](/quest/m2/performance-survey/session-selection.md) - exact-ID lookups and registry lock hold time - [Browser media copies](/quest/m2/performance-survey/browser-media-copies.md) - CMAF sample and LOC framing copies versus retention 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.