diff --git a/bun.lock b/bun.lock index 25c962a4954..1e1a013bda9 100644 --- a/bun.lock +++ b/bun.lock @@ -524,6 +524,20 @@ "@moq/web-transport": "^0.1.6", }, }, + "test/stream-credit": { + "name": "@moq/stream-credit-test", + "dependencies": { + "@moq/clock": "workspace:*", + "@moq/net": "workspace:*", + }, + "devDependencies": { + "@types/bun": "^1.4.4", + "@typescript/lib-dom": "npm:@types/web@^0.0.358", + "playwright": "1.64.1", + "typescript": "7.0.2", + "vite": "^8.3.5", + }, + }, "test/video": { "name": "@moq/video-test", "dependencies": { @@ -882,6 +896,8 @@ "@moq/stats": ["@moq/stats@workspace:js/stats"], + "@moq/stream-credit-test": ["@moq/stream-credit-test@workspace:test/stream-credit"], + "@moq/ui": ["@moq/ui@workspace:js/ui"], "@moq/video": ["@moq/video@workspace:js/video"], diff --git a/package.json b/package.json index a8c40917a1d..2b4cfd9c75e 100644 --- a/package.json +++ b/package.json @@ -64,6 +64,7 @@ "test/interop/clients/js-native", "test/drain", "test/receive-credit", + "test/stream-credit", "test/video", "test/p2p", "test/qmux", diff --git a/quest/m1/stream-credit/README.md b/quest/m1/stream-credit/README.md index aa945f1cbeb..2645b26c654 100644 --- a/quest/m1/stream-credit/README.md +++ b/quest/m1/stream-credit/README.md @@ -1,4 +1,4 @@ -# [L] Stream credit by priority +# Stream credit by priority ## Goal @@ -54,7 +54,18 @@ wire message and multi-group streams. The 2026-11-04 choice of takeover before cancelling is superseded. ✅ m2 no longer requires this epic (rejected: keep the gate); it was an ordering rule, not a code dependency. -This epic owns the end-to-end test: a browser reader and a Rust relay over -WebTransport, 300 live tracks of mixed priority, the highest-priority ones -receiving every group, and nothing hanging. It builds its own harness, since -takeover no longer supplies one. +The end-to-end test is `just test stream-credit` (`test/stream-credit/`), from +[moq-dev/moq#8652](https://github.com/moq-dev/moq/pull/8652): a Chromium or +Firefox tab reads 300 live tracks of mixed priority through `moq-relay` over +WebTransport, on lite-07 and lite-06. The highest-priority tier receives every +group, the tiers read in priority order, and on lite-07 the relay continues +paused groups. It runs locally only until +[browser-resets](/quest/m1/stream-credit/browser-resets.md) makes it pass +reliably, since about one lite-07 cell in 20 still fails. + +Decided 2026-11-13 (implementer, #8652, unattended): a lite-06 reader may lose a +starved track's final group at the track's end, and that is lite-06's limit, +not a defect: lite-06 has no drops, so a reader cannot wait for a group the +relay may have shed. The harness checks the final group on lite-07 only. +Rejected: holding the relay's lite-06 SUBSCRIBE_FINISH until no group waits for +credit, a heuristic for a version lite-07 replaces. diff --git a/quest/m1/stream-credit/browser-resets.md b/quest/m1/stream-credit/browser-resets.md new file mode 100644 index 00000000000..91692ba4798 --- /dev/null +++ b/quest/m1/stream-credit/browser-resets.md @@ -0,0 +1,46 @@ +# [L] A browser group stream reset reaches the reader + +## Goal + +`just test stream-credit` passes reliably on lite-07 in Chromium and Firefox, +and runs in the nightly interop workflow. Each group stream the relay resets +reaches the tab's reader as a reset with its code, so a YIELDED group pauses +and a subscription ends once its groups are accounted for. + +## Plan + +Decided 2026-11-13 (maintainer, the pick round for [moq-dev/moq#8652](https://github.com/moq-dev/moq/pull/8652)): ✅ keep this follow-up (rejected: drop it and leave the harness a manual recipe). + +[moq-dev/moq#8652](https://github.com/moq-dev/moq/pull/8652)'s harness found +two rare failures, both where a relay's reset of a tab's group stream meets the +browser. Heavy logging in the page hides them, so reproduce with the harness as +is and add tracing that buffers in memory. + +- Chromium (about 1 lite-07 cell in 20): one subscription never ends. The page + read the header of a group the relay paused (YIELDED), continued, and then + dropped as stale (`SUBSCRIBE_DROP`, OLD), and that stream never ended or + errored in the page, so the lite-07 tail waits on it forever. No second header + for the group reached the page. Chromium 156 does not negotiate + RESET_STREAM_AT, so the relay sends a plain RESET_STREAM once the 3-byte + WebTransport header is acknowledged (`moq_quic` `take_held_reset`). Next: log + each group stream's ID in the relay and whether Chromium acknowledges its + RESET_STREAM. If Chromium acknowledges it, the loss is Chromium's: report it + upstream, and make the JS reader stop waiting on a stream whose group a drop + or a continuation accounted for. If not, fix the relay's reset. +- Firefox (1 lite-07 cell in about 25): a few starved tracks' final groups fail + with `TypeError: Error in input stream` and no stream error code, which the + reader cannot tell from a YIELDED reset, so the group aborts instead of + pausing. Firefox 157 negotiates RESET_STREAM_AT, and the relay resets with a + Reliable Size of 3. Next: reproduce in a minimal WebTransport page, and report + it upstream if Firefox drops the code. +- Then add `just test stream-credit` to `.github/workflows/interop.yml` after + "Stream limits over WebSocket", and delete the epic README, whose last work + this is. + +To reproduce, loop `just test stream-credit --version moq-lite-07-wip --engine +chromium` until one fails; it keeps the run directory with the relay log, the +page console, and `pending.json`. The page's `console.debug` logs each pause. + +## Related + +- [moq-dev/moq#8643](https://github.com/moq-dev/moq/pull/8643) - a JS copy-fill duplicate group; the harness saw no duplicate group diff --git a/sh/gh/test-inventory.allow b/sh/gh/test-inventory.allow index 7dbbf139b7b..27e36737d82 100644 --- a/sh/gh/test-inventory.allow +++ b/sh/gh/test-inventory.allow @@ -37,6 +37,7 @@ ignore moq-video::render::export::dx12::tests::exports_an_nv12_texture /quest/m5 ignore moq-video::render::export::dx12::tests::media_foundation_encodes_the_export_in_place /quest/m5/video-hardware.md # Flaked under load; disabled until fixed at its cause. +recipe test::stream-credit /quest/m1/stream-credit/browser-resets.md # Too slow for the merge gate; the quest runs it nightly once every scenario settles. ignore moq-net::route::tests::cache::sweep_cache_routing_long /quest/m2/cache-routing-proof.md diff --git a/test/README.md b/test/README.md index 32320d4f7d4..9f54a250896 100644 --- a/test/README.md +++ b/test/README.md @@ -18,6 +18,7 @@ questions to a harness. For builds and CI selection, see the | [native-play](native-play/README.md) | `just test native-play` | the shipped headless player follows overlapping publishers and fallback through decoded PCM on a private Linux null audio device | | [audio-quality](audio-quality/README.md) | `just test audio-quality` | browser and native audio playout stay within budget over an impaired path | | [drain](drain/README.md) | `just test drain` | a JS viewer migrates off a draining relay without a dropped group | +| [stream-credit](stream-credit/README.md) | `just test stream-credit` | a browser tab reads 300 live tracks past its ~100-stream WebTransport cap, the highest priority first, and nothing hangs | | qmux | `just test qmux` | `@moq/qmux`, as client and as server, interoperates with the Rust qmux 0.6.3 release on every QMux draft | | video | `just test video` | the `@moq/video` renderer paints through WebGPU and falls back to Canvas2D after losing the GPU | | [json-properties](json-properties.md) | `just test json-properties` | both Snapshot codecs reconstruct, and both Window codecs emit the exact events for, random JSON sequences with replayable seeds | diff --git a/test/justfile b/test/justfile index e51d7f17ea2..23bb2a28c40 100644 --- a/test/justfile +++ b/test/justfile @@ -249,6 +249,14 @@ ts-controls: drain *args: ./drain/run.sh {{ args }} +# A browser tab reads 300 live tracks of mixed priority through a Rust relay over WebTransport, +# past its ~100-stream cap: the top priority gets every group and nothing hangs. Runs lite-07 and +# lite-06 in Chromium and Firefox; `--version` and `--engine` pick one. See stream-credit/README.md. + +# Stream credit by priority in the browser, end to end. +stream-credit *args: + ./stream-credit/run.sh {{ args }} + # The @moq/video renderer in headless Chromium: WebGPU, a lost device, and the Canvas2D fallback. video: uv run --no-project python ../sh/js/install.py frozen diff --git a/test/stream-credit/README.md b/test/stream-credit/README.md new file mode 100644 index 00000000000..c56f8d500ac --- /dev/null +++ b/test/stream-credit/README.md @@ -0,0 +1,61 @@ +# Stream credit harness + +A browser tab reads 300 live tracks through a Rust relay over WebTransport, +three times the ~100 streams Chromium and Firefox let a server open to one +session. The relay hands the streams it can open to the highest-priority +groups and, on lite-07, makes room with a YIELDED reset that pauses a +lower-priority group for a later stream to continue. + +## Running + +```bash +just test stream-credit +``` + +```bash +just test stream-credit --version moq-lite-07-wip --engine chromium --timeout 120 +``` + +Each run covers lite-07 and lite-06 in Chromium and Firefox, about 15 seconds +per cell. `cargo build -p moq-relay` builds the relay from this checkout. +`STREAM_CREDIT_PROFILE` picks its cargo profile, and `RELAY_BIN` points at a +prebuilt relay instead. A failing run keeps its run directory: the relay log +(with the publisher's scheduling at debug level), and per cell the page's +console, `report.json` with every group each track read, or `pending.json` +with the tracks still open. + +## Shape + +`run.sh` starts the relay, then runs `driver.ts` once per version and engine. +The driver plays every other part: + +- **The publisher** is `@moq/net` in Bun, over WebSocket, whose qmux stream + limit is far above 300, so the browser's cap is the only one in play. Each + track keeps one group open at a time, as a live video track keeps its GOP + open: a frame at its start, one halfway through, and its end as the next + group starts, 40 groups at 200 ms. +- **The reader** is a page built from `src/` with Vite, in Playwright's + Chromium or Firefox. It dials the relay over WebTransport only and subscribes + to every track in three tiers of subscriber priority: + + | Tier | Priority | Tracks | Delay budget | + | --- | --- | --- | --- | + | high | 2 | 30 | 500 ms | + | mid | 1 | 120 | live edge | + | low | 0 | 150 | live edge | + +A cell passes when: + +- the high tier read every group whole, every frame in order; +- every subscription ended cleanly within 10 s of the publisher finishing + (the relay drains the last groups in under a second on loopback); +- on lite-07, every track read its final group whole, since its readers wait + for every group the relay owes them. A lite-06 reader has no drops to wait + on, so it ends at the end it was told, and a starved track may lose the + final group still queued for credit; +- the tiers read frames in priority order, and the low tier lost some, so the + cap bound; +- on lite-07, the relay log shows paused groups continued, the YIELDED path. + +With every tier at one priority, the high tier misses groups past its budget +and the relay continues no paused group, so the run fails. diff --git a/test/stream-credit/driver.ts b/test/stream-credit/driver.ts new file mode 100644 index 00000000000..2b52d031069 --- /dev/null +++ b/test/stream-credit/driver.ts @@ -0,0 +1,284 @@ +/** + * Drives the stream credit test: a JS publisher over WebSocket writes live groups on 300 tracks + * to the relay, and a Chromium or Firefox tab reads all of them over WebTransport, whose + * ~100-stream cap leaves the relay far short of the streams it wants to open. + * + * bun driver.ts --port 4480 --version moq-lite-07-wip --engine chromium --out DIR --relay-log FILE [--timeout 60] + * + * Each track keeps one group open at a time, the way a live video track keeps its GOP open, so + * the relay wants 300 streams to the tab at once. Tiers of subscriber priority decide who gets + * them. Exits 0 when the top tier received every group whole, every subscription ended cleanly + * soon after the publisher finished (on lite-07 with its final group whole), and the lower tiers + * lost frames in priority order; 1 otherwise. + * + * @module + */ + +import { readFileSync } from "node:fs"; +import { parseArgs, stripVTControlCharacters } from "node:util"; +import * as Moq from "@moq/net"; +import { build } from "vite"; +import { launch } from "../interop/clients/js/harness.ts"; +import type { Group, Plan, Report, Track } from "./src/plan.ts"; + +const { values } = parseArgs({ + options: { + port: { type: "string" }, + version: { type: "string" }, + engine: { type: "string" }, + out: { type: "string" }, + "relay-log": { type: "string" }, + timeout: { type: "string", default: "60" }, + }, +}); + +const port = Number(values.port); +const version = values.version ?? ""; +const engine = values.engine; +const out = values.out ?? ""; +const pageDir = `${out}/page`; +const relayLog = values["relay-log"] ?? ""; +const timeoutMs = Number(values.timeout) * 1000; +if ( + !Number.isInteger(port) || + !version || + (engine !== "chromium" && engine !== "firefox") || + !out || + !relayLog || + !(timeoutMs > 0) +) { + console.error( + "usage: driver.ts --port P --version V --engine chromium|firefox --out DIR --relay-log FILE [--timeout S]", + ); + process.exit(2); +} + +// Chromium and Firefox cap a WebTransport session at about 100 incoming streams. The top tier fits +// inside it with room to spare; the rest compete for what is left. Its readers want every group +// within a budget of a few group intervals, which only priority can meet under that contention: +// at one priority for all, its groups wait their turn and go stale. The rest read the live edge. +const TIERS = [ + { name: "high", priority: 2, count: 30, budget: 500, every: true }, + { name: "mid", priority: 1, count: 120, budget: 0, every: false }, + { name: "low", priority: 0, count: 150, budget: 0, every: false }, +] as const; +type Tier = (typeof TIERS)[number]; + +// Groups per track, one every interval, each with a frame at its start and one halfway through, +// so a group is open across the whole interval and a paused one has a frame left to continue. +const GROUPS = 40; +const INTERVAL_MS = 200; +// How long every subscription has to end once the publisher finishes. On loopback the relay +// drains the last groups in under a second; a subscription still open past this is stuck. +const DRAIN_MS = 10_000; + +const broadcastName = "credit"; +const relay = `http://127.0.0.1:${port}/`; + +// @moq/net logs every finished publication at debug level; 300 of them bury the verdict. +console.debug = () => {}; + +function log(message: string) { + console.error(`[stream-credit] ${message}`); +} + +const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms)); + +const plan: Plan = { + url: relay, + version, + broadcast: broadcastName, + tracks: TIERS.flatMap((tier) => + Array.from({ length: tier.count }, (_, i) => ({ + name: `${tier.name}-${i}`, + priority: tier.priority, + budget: tier.budget, + })), + ), +}; +const tierOf = new Map( + TIERS.flatMap((tier) => plan.tracks.filter((t) => t.name.startsWith(`${tier.name}-`)).map((t) => [t.name, tier])), +); + +const payload = (track: Track, sequence: number, frame: number) => `${track.name}:${sequence}:${frame}`; + +// ── the publisher ──────────────────────────────────────────────────────────── +const origin = new Moq.Origin.Producer(); +const publication = origin.route(Moq.Path.from(broadcastName)); +// No publisher age limit: each reader's budget alone decides which groups are still worth sending. +const tracks = plan.tracks.map((track) => publication.broadcast.createTrack(track.name, { maxAge: null })); +publication.announce(); +// Bun has no WebTransport, so this dials the WebSocket, whose qmux stream limit @moq/net raises +// far past what 300 subscriptions need: the only cap in play is the browser's. +const publisher = await Moq.Connection.connect({ url: new URL(relay), versions: [version], publish: origin.consume() }); +log(`publisher connected on ${publisher.version}`); + +// ── the page ───────────────────────────────────────────────────────────────── +await build({ + configFile: false, + root: import.meta.dir, + logLevel: "warn", + build: { target: "esnext", outDir: pageDir, emptyOutDir: true }, +}); +const server = Bun.serve({ + port: 0, + hostname: "127.0.0.1", + async fetch(req) { + const path = new URL(req.url).pathname; + const file = Bun.file(`${pageDir}${path === "/" ? "/index.html" : path}`); + return (await file.exists()) ? new Response(file) : new Response("not found", { status: 404 }); + }, +}); + +const browser = await launch([], engine); +// Every page log line, kept with the run: @moq/net logs each pause at debug level. +const pageLog = Bun.file(`${out}/console.log`).writer(); +const failures: string[] = []; +let report: Report | undefined; +try { + const page = await browser.newPage(); + page.on("pageerror", (error) => failures.push(`page error: ${error.message}`)); + page.on("console", (message) => { + pageLog.write(`${performance.now().toFixed(0)} ${message.type()} ${message.text()}\n`); + if (message.type() === "error") log(`page: ${message.text()}`); + }); + await page.goto(`http://127.0.0.1:${server.port}/`); + log(`${engine} ${browser.version()}`); + + const subscribed = page.evaluate((plan) => window.subscribe(plan), plan).then(() => true); + if (!(await Promise.race([subscribed, sleep(timeoutMs).then(() => false)]))) + throw new Error(`the tab did not subscribe within ${timeoutMs} ms`); + log(`tab subscribed to ${plan.tracks.length} tracks`); + + const reading = page.evaluate(() => window.report()); + // Left pending if the drain times out, and rejected once the browser closes. + reading.catch(() => {}); + // Every track keeps one group open: the previous one finishes as the next one starts. + let open: Moq.Group.Producer[] = []; + const write = (sequence: number, frame: number) => { + for (const [i, group] of open.entries()) + group.writeFrame({ payload: new TextEncoder().encode(payload(plan.tracks[i], sequence, frame)) }); + }; + for (let sequence = 0; sequence < GROUPS; sequence++) { + for (const group of open) group.finish(); + open = tracks.map((track) => track.appendGroup()); + write(sequence, 0); + await sleep(INTERVAL_MS / 2); + write(sequence, 1); + await sleep(INTERVAL_MS / 2); + } + for (const group of open) group.finish(); + for (const track of tracks) track.finish(); + log(`published ${GROUPS} groups on each track`); + + const drained = await Promise.race([reading, sleep(DRAIN_MS).then(() => undefined)]); + if (drained) { + report = drained; + } else { + const pending = await page.evaluate(() => window.pending()); + failures.push(`${pending.length} subscriptions still open ${DRAIN_MS} ms after the publisher finished`); + for (const received of pending.slice(0, 5)) { + const groups = received.groups + .slice(-4) + .map((g) => `${g.sequence}:${g.frames.length}${g.error ? `:${g.error}` : ""}`); + failures.push(`${received.name} is still open; last groups ${groups.join(" ")}`); + } + await Bun.write(`${out}/pending.json`, JSON.stringify(pending)); + } +} catch (err) { + failures.push(err instanceof Error ? err.message : String(err)); +} finally { + await browser.close().catch(() => {}); + await pageLog.end(); + server.stop(true); + await publisher.close(); + origin.close(); +} + +if (report) { + await Bun.write(`${out}/report.json`, JSON.stringify(report)); + judge(report); +} + +function judge(report: Report) { + if (report.version !== version) failures.push(`the tab negotiated ${report.version}, not ${version}`); + if (report.closed) failures.push(`the tab's session closed with ${report.closed}`); + const accounted = !/^moq-lite-0[0-6]$/.test(version); + + // Frames read per tier, the measure of who the streams went to: a live-edge reader's group + // goes stale as its successor starts, so most of its groups end early by design. + const frames = new Map(TIERS.map((tier) => [tier, 0])); + for (const received of report.tracks) { + const track = plan.tracks.find((t) => t.name === received.name); + const tier = tierOf.get(received.name); + if (!track || !tier) throw new Error(`unknown track ${received.name}`); + const fail = (detail: string) => failures.push(`${received.name}: ${detail}`); + + if (received.ended) fail(`ended with ${received.ended}`); + const seen = new Set(); + let last: Group | undefined; + for (const group of received.groups) { + if (seen.has(group.sequence)) fail(`group ${group.sequence} handed out twice`); + seen.add(group.sequence); + if (group.sequence === GROUPS - 1) last = group; + // A frame read is never wrong, only missing: each one read is the next one written. + const expected = [0, 1].map((frame) => payload(track, group.sequence, frame)); + if (group.frames.some((frame, i) => frame !== expected[i])) + fail(`group ${group.sequence} read ${JSON.stringify(group.frames)}`); + frames.set(tier, (frames.get(tier) ?? 0) + group.frames.length); + // The top tier asks for every group, so none may stop early. + if (tier.every && (group.error || group.frames.length !== expected.length)) + fail(`group ${group.sequence} stopped after ${group.frames.length} frames: ${group.error}`); + } + if (tier.every) { + const missing = Array.from({ length: GROUPS }, (_, i) => i).filter((i) => !seen.has(i)); + if (missing.length) fail(`missed groups ${missing.join(",")}`); + } + // Once the publisher stops, the backlog drains: the newest group reaches every reader whole. + // Only lite-07 accounts for every group, so only there does a reader wait for one still + // queued for credit at the track's end. A lite-06 reader cannot tell a group still coming + // from one the relay shed, so it ends at the end it was told, and a starved track loses + // the final group the relay had not opened yet. + if ((accounted || tier.every) && (!last || last.error || last.frames.length !== 2)) + fail(`final group ${last ? `stopped after ${last.frames.length} frames: ${last.error}` : "never arrived"}`); + } + + const share = TIERS.map((tier) => { + const tracks = report.tracks.filter((t) => tierOf.get(t.name) === tier); + const ratio = (frames.get(tier) ?? 0) / (tracks.length * GROUPS * 2); + const slowest = tracks.reduce((a, b) => ((b.at ?? 0) > (a.at ?? 0) ? b : a)); + const ended = slowest.at ?? 0; + log( + `${tier.name} (priority ${tier.priority}, ${tracks.length} tracks): read ${(ratio * 100).toFixed(1)}% of frames, all ended ${ended.toFixed(0)} ms after subscribing (${slowest.name})`, + ); + return ratio; + }); + // More live groups than the cap must cost something, and it must fall on the lowest priority. + const [high, mid, low] = share; + if (!(low < 1)) failures.push("the low tier read every frame: the browser's stream cap never bound"); + if (!(high >= mid && mid > low)) failures.push(`frames read did not follow priority: ${share.join(", ")}`); + + // The relay's own account of its scheduling, independent of what the tab read: the tab's + // session is the last WebTransport one negotiated on this version. + const lines = stripVTControlCharacters(readFileSync(relayLog, "utf8")).split("\n"); + const negotiated = new RegExp(`conn\\{id=(\\d+) .*negotiated version=${version} transport=webtransport`); + const id = lines.flatMap((line) => negotiated.exec(line)?.[1] ?? []).at(-1); + if (id === undefined) { + failures.push(`the relay log names no WebTransport session on ${version}`); + return; + } + const ours = lines.filter((line) => line.includes(`conn{id=${id} `)); + const count = (what: string) => ours.filter((line) => line.includes(what)).length; + const continued = count("continuing paused group"); + log(`relay: ${continued} paused groups continued`); + // Lite-07's YIELDED reset pauses a group to make room, and a later stream continues it. + if (accounted && continued === 0) failures.push("the relay never continued a paused group"); +} + +if (failures.length) { + for (const failure of failures.slice(0, 50)) console.error(`FAIL ${failure}`); + if (failures.length > 50) console.error(`... and ${failures.length - 50} more`); + process.exit(1); +} +console.log(`PASS ${plan.tracks.length} tracks through the browser's stream cap on ${version}`); +process.exit(0); diff --git a/test/stream-credit/index.html b/test/stream-credit/index.html new file mode 100644 index 00000000000..7f50e6c3212 --- /dev/null +++ b/test/stream-credit/index.html @@ -0,0 +1,2 @@ + +MoQ stream credit test diff --git a/test/stream-credit/package.json b/test/stream-credit/package.json new file mode 100644 index 00000000000..c9cd87bb165 --- /dev/null +++ b/test/stream-credit/package.json @@ -0,0 +1,19 @@ +{ + "name": "@moq/stream-credit-test", + "private": true, + "type": "module", + "scripts": { + "check": "tsc --noEmit" + }, + "dependencies": { + "@moq/clock": "workspace:*", + "@moq/net": "workspace:*" + }, + "devDependencies": { + "@types/bun": "^1.4.4", + "@typescript/lib-dom": "npm:@types/web@^0.0.358", + "playwright": "1.64.1", + "typescript": "7.0.2", + "vite": "^8.3.5" + } +} diff --git a/test/stream-credit/relay.toml b/test/stream-credit/relay.toml new file mode 100644 index 00000000000..da21adbd18a --- /dev/null +++ b/test/stream-credit/relay.toml @@ -0,0 +1,19 @@ +# Relay config for the stream credit harness: anonymous, a self-signed localhost +# certificate the browser pins through /certificate.sha256, QUIC and HTTP on +# 127.0.0.1. run.sh overrides the ports on the command line. + +[log] +level = "info" + +[listen] +bind = "127.0.0.1:4480" +tls.generate = ["localhost", "127.0.0.1"] +# The YIELDED reset that pauses a group is lite-07's; lite-06 resets cancel it. +version = ["moq-lite-07-wip", "moq-lite-06"] + +[web.http] +# The JS publisher's WebSocket, and /certificate.sha256 for the browser's WebTransport. +listen = "127.0.0.1:4480" + +[auth] +public = "**" diff --git a/test/stream-credit/run.sh b/test/stream-credit/run.sh new file mode 100755 index 00000000000..fdd946bfc80 --- /dev/null +++ b/test/stream-credit/run.sh @@ -0,0 +1,116 @@ +#!/usr/bin/env bash +# Stream credit by priority, end to end: a Chromium or Firefox tab reads 300 +# live tracks through a Rust relay over WebTransport, past the browser's +# ~100-stream cap. +# See README.md. +set -euo pipefail + +if [[ "${GITHUB_ACTIONS:-}" != true && "${LOCAL_SUPERVISED:-}" != 1 ]]; then + exec bash "$(dirname "$0")/../../sh/local.sh" bash "$0" "$@" +fi + +DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd) +WORKSPACE=$(cd "$DIR/../.." && pwd) + +# Run directory, reserved ports, and process-group ownership. See test/README.md. +# shellcheck source-path=SCRIPTDIR source=../lib/harness.sh +source "$DIR/../lib/harness.sh" + +RERUN="$(harness_env STREAM_CREDIT_PROFILE RELAY_BIN)just test stream-credit$(harness_argv "$@")" + +TIMEOUT=60 +PROFILE="${STREAM_CREDIT_PROFILE:-debug}" +RELAY="${RELAY_BIN:-}" +VERSIONS=(moq-lite-07-wip moq-lite-06) +ENGINES=(chromium firefox) + +while [[ $# -gt 0 ]]; do + case "$1" in + --timeout | --version | --engine) + if [[ $# -lt 2 || -z "${2:-}" || "$2" == -* ]]; then + echo "error: $1 requires a value" >&2 + exit 2 + fi + case "$1" in + --timeout) TIMEOUT="$2" ;; + --version) VERSIONS=("$2") ;; + --engine) ENGINES=("$2") ;; + esac + shift 2 + ;; + *) + echo "unknown arg: $1" >&2 + exit 2 + ;; + esac +done + +if [[ ! "$TIMEOUT" =~ ^[1-9][0-9]*$ ]]; then + echo "error: timeout must be a positive whole number of seconds (got '$TIMEOUT')" >&2 + exit 2 +fi + +harness_begin stream-credit "$RERUN" + +for tool in cargo bun curl; do + command -v "$tool" >/dev/null 2>&1 || { + echo "error: $tool not found; run inside 'nix develop'" >&2 + exit 1 + } +done + +# ── build ─────────────────────────────────────────────────────────────────── +if [[ -z "$RELAY" ]]; then + echo "building moq-relay ($PROFILE)..." + flag=() + [[ "$PROFILE" == "debug" ]] || flag=(--profile "$PROFILE") + (cd "$WORKSPACE" && cargo build --locked ${flag[@]+"${flag[@]}"} -p moq-relay) + harness_stage moq-relay "${CARGO_TARGET_DIR:-$WORKSPACE/target}/$PROFILE/moq-relay" + RELAY="$HARNESS_RUN/moq-relay" +fi + +uv run --no-project python "$WORKSPACE/sh/js/install.py" frozen + +# ── relay ─────────────────────────────────────────────────────────────────── +harness_port relay +PORT="$HARNESS_PORT" +URL="http://127.0.0.1:$PORT" +if harness_probe "$URL/certificate.sha256"; then + echo "error: something is already listening on 127.0.0.1:$PORT (stale relay?)" >&2 + exit 1 +fi +# The publisher's scheduling decisions, which show the cap bound and groups yielded. +RUST_LOG="info,moq_net::lite::publisher=debug" harness_spawn relay "$HARNESS_RUN/relay.log" \ + "$RELAY" "$DIR/relay.toml" --listen "127.0.0.1:$PORT" --web-http-listen "127.0.0.1:$PORT" +RELAY_PID="$HARNESS_PID" +if ! harness_ready "$URL/certificate.sha256" 30 "$RELAY_PID"; then + echo "relay never became ready" >&2 + sed 's/^/ relay: /' "$HARNESS_RUN/relay.log" >&2 || true + exit 1 +fi +harness_endpoint relay "$URL" + +# ── run ───────────────────────────────────────────────────────────────────── +status=0 +for version in "${VERSIONS[@]}"; do + for engine in "${ENGINES[@]}"; do + echo "── $engine on $version ──" + started=$SECONDS + case_status=0 + # Spawned rather than run in the foreground so a SIGTERM lands while the shell + # is in `wait`, where a trap can run. + harness_spawn "driver-$engine-$version" - bun "$DIR/driver.ts" --port "$PORT" --version "$version" \ + --engine "$engine" --out "$HARNESS_RUN/$engine-$version" --relay-log "$HARNESS_RUN/relay.log" \ + --timeout "$TIMEOUT" + harness_wait "$HARNESS_PID" || case_status=$? + cell=(suite=stream-credit case="stream credit $engine" subscriber=js transport=webtransport version="$version") + if [[ $case_status -eq 0 ]]; then + harness_result pass "${cell[@]}" seconds=$((SECONDS - started)) + else + harness_result fail "${cell[@]}" seconds=$((SECONDS - started)) log="$HARNESS_RUN/relay.log" + status=1 + fi + done +done + +exit $status diff --git a/test/stream-credit/src/main.ts b/test/stream-credit/src/main.ts new file mode 100644 index 00000000000..6a9f45c9b35 --- /dev/null +++ b/test/stream-credit/src/main.ts @@ -0,0 +1,100 @@ +/** + * The browser reader: one WebTransport session to the relay, subscribed to every track of the + * broadcast at its tier's priority, reading each group's frames as they arrive. + * + * The driver calls {@link Window.subscribe} first, publishes once it resolves, then waits on + * {@link Window.report} for every subscription to end. + * + * @module + */ +import * as Moq from "@moq/net"; +import type { Plan, Received, Report, Track } from "./plan.ts"; + +declare global { + interface Window { + /** Dial `plan.url` and subscribe to every track, resolving once each subscription is live. */ + subscribe(plan: Plan): Promise; + /** Resolve once every subscription ended, with what each one read. */ + report(): Promise; + /** What each subscription still reading has read so far. */ + pending(): Received[]; + } +} + +let reading: Promise | undefined; +// Each subscription's reads so far, filled in as they happen. +const progress: Received[] = []; + +window.subscribe = async (plan) => { + const origin = new Moq.Origin.Producer(); + const connection = await Moq.Connection.connect({ + url: new URL(plan.url), + versions: [plan.version], + consume: origin, + // The browser's own stream cap is the point, and only WebTransport has one. + websocket: { enabled: false }, + }); + const request = origin.request(Moq.Path.from(plan.broadcast)); + let broadcast = request.active.peek(); + while (!broadcast) broadcast = await request.active.changed(); + const active = broadcast; + + const subscribers = plan.tracks.map((track) => + active.track(track.name).subscribe({ + priority: track.priority, + delay: { max: Moq.Clock.Duration.millis(track.budget) }, + }), + ); + // Each subscription is a stream the browser opens; its info arrives once the relay answers. + await Promise.all(subscribers.map((subscriber) => subscriber.info())); + + const started = performance.now(); + reading = (async () => { + const tracks = await Promise.all(plan.tracks.map((track, i) => read(track, subscribers[i], started))); + const closed = connection.closed; + await connection.close(); + return { version: connection.version, tracks, closed: String((await closed) ?? "") || null }; + })(); +}; + +window.report = () => { + if (!reading) throw new Error("subscribe first"); + return reading; +}; + +window.pending = () => progress.filter((received) => received.at === undefined); + +// Read every group the subscription hands out until it ends. Frames are read concurrently with +// the next group, since a group paused for credit must not hold back the groups after it. +async function read(track: Track, subscriber: Moq.Track.Subscriber, started: number): Promise { + const received: Received = { name: track.name, groups: [], ended: null }; + progress.push(received); + const frames: Promise[] = []; + try { + for (;;) { + const group = await subscriber.recvGroup(); + if (!group) break; + const entry: Received["groups"][number] = { sequence: Number(group.sequence), frames: [] }; + received.groups.push(entry); + frames.push( + (async () => { + try { + for (;;) { + const frame = await group.readString(); + if (frame === undefined) break; + entry.frames.push(frame); + } + entry.at = performance.now() - started; + } catch (err) { + entry.error = String(err); + } + })(), + ); + } + } catch (err) { + received.ended = String(err); + } + await Promise.all(frames); + received.at = performance.now() - started; + return received; +} diff --git a/test/stream-credit/src/plan.ts b/test/stream-credit/src/plan.ts new file mode 100644 index 00000000000..d604befd995 --- /dev/null +++ b/test/stream-credit/src/plan.ts @@ -0,0 +1,48 @@ +/** What the driver hands the page, and what the page reports back. @module */ + +/** One track the page subscribes to. */ +export interface Track { + name: string; + /** The subscriber priority, higher first. */ + priority: number; + /** How long, in milliseconds, a superseded group stays worth reading; zero reads the live edge. */ + budget: number; +} + +/** The page's whole job. */ +export interface Plan { + /** The relay, over WebTransport. */ + url: string; + version: string; + broadcast: string; + tracks: Track[]; +} + +/** One group the reader was handed. */ +export interface Group { + sequence: number; + /** Each frame's payload, in the order read. */ + frames: string[]; + /** Milliseconds after subscribing that the group's last frame was read. */ + at?: number; + /** Why reading its frames stopped early. */ + error?: string; +} + +/** What one subscription read. */ +export interface Received { + name: string; + groups: Group[]; + /** Why the subscription ended with an error, or `null` for a clean end. */ + ended: string | null; + /** Milliseconds after subscribing that it ended, once it has. */ + at?: number; +} + +/** What the page read. */ +export interface Report { + version: string; + tracks: Received[]; + /** The session's close error, or `null` for a clean close. */ + closed: string | null; +} diff --git a/test/stream-credit/tsconfig.json b/test/stream-credit/tsconfig.json new file mode 100644 index 00000000000..fdfb3b3ac99 --- /dev/null +++ b/test/stream-credit/tsconfig.json @@ -0,0 +1,5 @@ +{ + "extends": "../../js/tsconfig.json", + "compilerOptions": { "types": ["bun", "vite/client"], "noEmit": true }, + "include": ["driver.ts", "src", "../../js/common/worklet.d.ts"] +}