Free, open-source screen sharing for private live streams with friends. Watch together in a browser or self-host Piik. 免费开源的私密屏幕共享,支持游戏直播、一起看电影与自部署。
test(media): gate explicit cap3 topology (#168)
AAA0389364731d3
diff --git a/docs/research/peer-assisted-media.md b/docs/research/peer-assisted-media.mdindex d095bb78..fe3d0057 100644--- a/docs/research/peer-assisted-media.md+++ b/docs/research/peer-assisted-media.md@@ -255,6 +255,11 @@ no fatal error. The run proves the two-child control path and bound on localChrome only. It does not prove shared encoding, CPU/GPU cost, visual quality,games, mobile resources, public networking, or endurance.+The loopback runner retains cap2 by default; `BENCHMARK_EXPECTED_ENDPOINT_CAP=3`+configures only its local server and gate. A 2026-08-22 Chrome 151 two-second+smoke passed with three Viewers at Host2/relay1 and six at Host3/relay3, with all+Viewers decoding. This is not a production-default, SFU-capacity, or resource claim.+Peer multicast research such as SplitStream demonstrates why load-balanced,failure-tolerant overlays normally introduce multiple trees and contentstriping. Those mechanisms are intentionally excluded: needing them is a reasondiff --git a/scripts/peer-assisted-benchmark.ts b/scripts/peer-assisted-benchmark.tsindex 0a7d33d2..fcf43dc6 100644--- a/scripts/peer-assisted-benchmark.ts+++ b/scripts/peer-assisted-benchmark.ts@@ -6,7 +6,11 @@ import { basename, dirname, isAbsolute, join, resolve } from "node:path";import { fileURLToPath, pathToFileURL } from "node:url";import WebSocket from "ws";-import type { ParticipantRouteAssignment } from "../src/shared/protocol";+import {+ DEFAULT_PEER_RELAY_DOWNSTREAM_EDGES,+ MAX_PEER_RELAY_DOWNSTREAM_EDGES,+ type ParticipantRouteAssignment,+} from "../src/shared/protocol";import {createScreenerServer,type ScreenerServer,@@ -30,6 +34,7 @@ type PageRole = "host" | "viewer";export interface BenchmarkConfig {chromePath: string;viewerCounts: number[];+ expectedEndpointCap: number;profileId: ProfileId;durationMs: number;settleMs: number;@@ -358,6 +363,22 @@ function parseBoolean(value: string | undefined, fallback: boolean, name: stringthrow new Error(`${name} must be true, false, 1, or 0`);}+export function parseExpectedEndpointCap(value: string | undefined): number {+ const parsed = value?.trim()+ ? Number(value)+ : DEFAULT_PEER_RELAY_DOWNSTREAM_EDGES;+ if (+ !Number.isSafeInteger(parsed) ||+ parsed < DEFAULT_PEER_RELAY_DOWNSTREAM_EDGES ||+ parsed > MAX_PEER_RELAY_DOWNSTREAM_EDGES+ ) {+ throw new Error(+ `BENCHMARK_EXPECTED_ENDPOINT_CAP must be an integer from ${DEFAULT_PEER_RELAY_DOWNSTREAM_EDGES} to ${MAX_PEER_RELAY_DOWNSTREAM_EDGES}`,+ );+ }+ return parsed;+}+export function parseBenchmarkConfig(environment: NodeJS.ProcessEnv = process.env,): BenchmarkConfig {@@ -395,6 +416,9 @@ export function parseBenchmarkConfig(return {chromePath,viewerCounts,+ expectedEndpointCap: parseExpectedEndpointCap(+ environment.BENCHMARK_EXPECTED_ENDPOINT_CAP,+ ),profileId,durationMs:parseNumber(@@ -694,7 +718,12 @@ export function buildRunChecks(summary: NonNullable<BenchmarkRun["summary"]>,viewerCount: number,profileId: ProfileId,+ expectedEndpointCap = DEFAULT_PEER_RELAY_DOWNSTREAM_EDGES,): RunCheck[] {+ const endpointCapObserved =+ summary.maxHostAssignedChildren === expectedEndpointCap &&+ (viewerCount < expectedEndpointCap * 2 ||+ summary.maxRelayActiveMediaEdges === expectedEndpointCap);const sfuConsistencyCheck: RunCheck = summary.sfuPublicationObserved? {name: "sfu-route-consistency",@@ -712,22 +741,33 @@ export function buildRunChecks(return [{name: "host-active-media-edges",- passed: summary.maxHostActiveMediaEdges <= 2,+ passed: summary.maxHostActiveMediaEdges <= expectedEndpointCap,actual: summary.maxHostActiveMediaEdges,- expected: "<= 2",+ expected: `<= ${expectedEndpointCap}`,},{name: "host-assigned-children",- passed: summary.maxHostAssignedChildren <= 2,+ passed: summary.maxHostAssignedChildren <= expectedEndpointCap,actual: summary.maxHostAssignedChildren,- expected: "<= 2",+ expected: `<= ${expectedEndpointCap}`,},{name: "relay-active-media-edges",- passed: summary.maxRelayActiveMediaEdges <= 2,+ passed: summary.maxRelayActiveMediaEdges <= expectedEndpointCap,actual: summary.maxRelayActiveMediaEdges,- expected: "<= 2",+ expected: `<= ${expectedEndpointCap}`,},+ ...(expectedEndpointCap > DEFAULT_PEER_RELAY_DOWNSTREAM_EDGES &&+ viewerCount >= expectedEndpointCap+ ? [+ {+ name: "endpoint-cap-observed",+ passed: endpointCapObserved,+ actual: endpointCapObserved,+ expected: `${expectedEndpointCap} Host children and required relay fanout`,+ },+ ]+ : []),{name: "all-viewers-decoded",passed: summary.everyViewerDecoded,@@ -752,20 +792,23 @@ export function buildRunChecks(];}-export function buildRecoveryCheck(recovery: RecoveryResult): RunCheck {+export function buildRecoveryCheck(+ recovery: RecoveryResult,+ expectedEndpointCap = DEFAULT_PEER_RELAY_DOWNSTREAM_EDGES,+): RunCheck {const passed =recovery.triggered &&recovery.error === undefined &&recovery.recoveredAtEpochMs !== undefined &&recovery.maxHostActiveMediaEdges !== undefined &&- recovery.maxHostActiveMediaEdges <= 2 &&+ recovery.maxHostActiveMediaEdges <= expectedEndpointCap &&recovery.maxHostAssignedChildren !== undefined &&- recovery.maxHostAssignedChildren <= 2;+ recovery.maxHostAssignedChildren <= expectedEndpointCap;return {name: "relay-recovery-correctness",passed,actual: passed,- expected: "decoded frames resume with host media edges and assigned children <= 2",+ expected: `decoded frames resume with host media edges and assigned children <= ${expectedEndpointCap}`,};}@@ -777,6 +820,7 @@ export function buildBenchmarkInitScript(options: {width: number;height: number;frameRate: number;+ expectedEndpointCap: number;}): string {const serialized = JSON.stringify(options);return `(() => {@@ -835,7 +879,7 @@ export function buildBenchmarkInitScript(options: {}if (!Array.isArray(value.childPeerIds) ||- value.childPeerIds.length > 2 ||+ value.childPeerIds.length > options.expectedEndpointCap ||!value.childPeerIds.every(isOpaqueId) ||new Set(value.childPeerIds).size !== value.childPeerIds.length ||(value.sfuPublicationGeneration !== null &&@@ -2030,6 +2074,7 @@ async function runCase(width: captureResolution.width,height: captureResolution.height,frameRate: capture.maxFramerate,+ expectedEndpointCap: config.expectedEndpointCap,};const hostPage = await createPage(cdp, baseUrl, {...commonInit,@@ -2088,7 +2133,12 @@ async function runCase(samples.push(await samplePages(cdp, pages, measurementStartedAt));const summary = summarizeSamples(samples, viewerCount);- const checks = buildRunChecks(summary, viewerCount, config.profileId);+ const checks = buildRunChecks(+ summary,+ viewerCount,+ config.profileId,+ config.expectedEndpointCap,+ );if (config.qualityControlSmoke && viewerCount >= 3) {const qualityControl = await runQualityControlSmoke(cdp,@@ -2129,7 +2179,7 @@ async function runCase(config.recoveryTimeoutMs,signal,);- checks.push(buildRecoveryCheck(recovery));+ checks.push(buildRecoveryCheck(recovery, config.expectedEndpointCap));}return {viewerCount,@@ -2211,6 +2261,7 @@ export async function main(): Promise<number> {},configuration: {viewerCounts: config.viewerCounts,+ expectedEndpointCap: config.expectedEndpointCap,profileId: config.profileId,durationMs: config.durationMs,settleMs: config.settleMs,@@ -2266,6 +2317,7 @@ export async function main(): Promise<number> {ALLOWED_ORIGINS: baseUrl,ROOM_DATABASE_PATH: "",PEER_ASSISTED_MEDIA: "true",+ MAX_PEER_RELAY_DOWNSTREAM_EDGES: String(config.expectedEndpointCap),MAX_VIEWERS_PER_ROOM: String(Math.max(...config.viewerCounts)),STUN_URLS: "",});diff --git a/tests/peer-assisted-benchmark.test.ts b/tests/peer-assisted-benchmark.test.tsindex b230a3ac..771f48da 100644--- a/tests/peer-assisted-benchmark.test.ts+++ b/tests/peer-assisted-benchmark.test.ts@@ -11,6 +11,7 @@ import {everyViewerRecoveredMedia,mergeRecoveryHostPeaks,parseBenchmarkConfig,+ parseExpectedEndpointCap,parseViewerCounts,summarizeSamples,} from "../scripts/peer-assisted-benchmark";@@ -142,7 +143,7 @@ interface ObserverSnapshot {maxAssignedChildren: number;}-function createObserverHarness() {+function createObserverHarness(expectedEndpointCap = 2) {const context: Record<string, unknown> = {WebSocket: FakeWebSocket,RTCPeerConnection: class FakePeerConnection {},@@ -162,6 +163,7 @@ function createObserverHarness() {width: 1280,height: 720,frameRate: 30,+ expectedEndpointCap,}).replace('const statsModule = import("/src/client/webrtc/stats.ts");',"const statsModule = new Promise(() => undefined);",@@ -230,6 +232,19 @@ describe("peer topology loopback configuration", () => {).toThrow(/selected viewer count/);});+ it("keeps cap2 by default and accepts only an explicit cap3 expectation", () => {+ expect(parseExpectedEndpointCap(undefined)).toBe(2);+ for (const value of ["1", "2.5", "4"]) {+ expect(() => parseExpectedEndpointCap(value)).toThrow(/integer from 2 to 3/);+ }+ expect(+ parseBenchmarkConfig({+ CHROME_PATH: "chrome",+ BENCHMARK_EXPECTED_ENDPOINT_CAP: "3",+ }).expectedEndpointCap,+ ).toBe(3);+ });+it("requires a relay-sized case for the optional quality control smoke", () => {expect(() =>parseBenchmarkConfig({@@ -298,6 +313,38 @@ describe("peer topology loopback observations", () => {).toBe(true);});+ it("requires an explicit cap3 run to exercise cap3 fanout", () => {+ const initial = [+ page("host", "host", 3, 0),+ ...Array.from({ length: 6 }, (_, index) =>+ page("viewer", `viewer-${index + 1}`, index === 0 ? 3 : 0, 1),+ ),+ ];+ const final = structuredClone(initial);+ for (const viewer of final.filter((entry) => entry.role === "viewer")) {+ viewer.connections.at(-1)!.receiveTotals!.framesTotal = 20;+ }+ const summary = summarizeSamples(+ [+ { atEpochMs: 2_000, elapsedMs: 0, pages: initial },+ { atEpochMs: 4_000, elapsedMs: 2_000, pages: final },+ ],+ 6,+ );+ const checks = buildRunChecks(summary, 6, "720p30", 3);+ expect(checks.find((check) => check.name === "endpoint-cap-observed")?.passed).toBe(true);+ const underused = {+ ...summary,+ maxHostAssignedChildren: 2,+ maxRelayActiveMediaEdges: 2,+ };+ expect(+ buildRunChecks(underused, 6, "720p30", 3).find(+ (check) => check.name === "endpoint-cap-observed",+ )?.passed,+ ).toBe(false);+ });+it("fails continuity when frames freeze or stats collection errors", () => {const frozenInitial = [page("host", "host", 1, 0),@@ -830,6 +877,25 @@ describe("peer topology loopback observations", () => {});});+ it("accepts a three-child route only for an explicit cap3 observer", () => {+ const assignment = routeAssignment(["child_peer_0001", "child_peer_0002", "child_peer_0003"]);+ for (const [cap, accepted] of [[2, false], [3, true]] as const) {+ const observer = createObserverHarness(cap);+ const socket = observer.socket();+ authenticate(socket);+ socket.emitMessage({+ type: "authenticated",+ role: "host",+ peerId: "host_peer_0001",+ mediaMode: "peer-assisted",+ routeRevision: 1,+ routeAssignment: assignment,+ qualitySettings: lowQualitySettings,+ });+ expect(observer.snapshot().routeAssignment !== null).toBe(accepted);+ }+ });+it("clears hybrid state only from the current authenticated socket", () => {const observer = createObserverHarness();const previous = observer.socket();@@ -891,6 +957,7 @@ describe("peer topology loopback observations", () => {width: 1280,height: 720,frameRate: 30,+ expectedEndpointCap: 2,});expect(source).toContain('"width":1280');expect(source).toContain('"frameRate":30');