Skip to content

armgit / Piik

Public Imported from GitHub
0

Free, open-source screen sharing for private live streams with friends. Watch together in a browser or self-host Piik. 免费开源的私密屏幕共享,支持游戏直播、一起看电影与自部署。

test(media): add viewer MBB relay canary (#191)

AAA2d240aef821e
diff --git a/docs/research/peer-assisted-media.md b/docs/research/peer-assisted-media.md
index a7f357d1..fcb8b3b1 100644
--- a/docs/research/peer-assisted-media.md
+++ b/docs/research/peer-assisted-media.md
@@ -292,6 +292,19 @@ real local `RTCPeerConnection` media and hard-participant-departure evidence. It
does not exercise correlated bad-quality detection or provisional MBB, a silent
socket partition, SFU, TURN, a public network, game capture, or resource quality.
+A 2026-08-22 opt-in `BENCHMARK_CANARY=viewer-mbb` run on the same Chrome build
+used one Host and three Viewers. The harness injected three valid two-second
+viewer-quality windows and parent-limited proof messages through the existing
+authenticated socket, then observed the real provisional `RTCPeerConnection`
+retain the old edge, promote to a Viewer candidate, and keep the same connection
+identity while decoded frames advanced. It also checked the ordinary one-edge
+cap and absence of route-failed messages. The report contains only booleans and
+sanitized counters; it emits no participant IDs, SDP, or ICE candidates. The
+windows are synthetic control input, so this proves the state-transition and
+continuity path only, not bad-relay detector quality, network performance, or a
+real heterogeneous route. Host-candidate and signaling-response-blackhole
+canaries remain deferred.
+
A 2026-08-21 local Chrome 151 capacity-two run used one Host and five Viewers
with a synthetic 720p30 stream. Host and relay fanout peaked at two; one Viewer
simultaneously served two children, whose inbound counters each advanced by 80
diff --git a/docs/status.md b/docs/status.md
index 0ececa0c..1035d6dd 100644
--- a/docs/status.md
+++ b/docs/status.md
@@ -22,6 +22,7 @@ This file is the current execution index. Load [verification status](./verificat
- Rooms default to eight Viewers and accept an explicit admission limit from one through sixteen. Current source is server-authoritative and role-aware: Host physical media edges are bounded to two, ordinary Browser Viewer downstream edges to one, and upstream receive is free. Active/provisional/selected overlays count, as does Host SFU publication. Deployment values 1/2 may only tighten these limits; old/malicious Viewer advertisements 2/3 cannot lift them. Web assignment execution also truncates physical children to Host2/Viewer1 as defense-in-depth, and deployment limit one promotes an occupied Host branch root before reserving the SFU publication slot. The wire retains `0/1/2/3` only as a future envelope, and SFU roots remain separately bounded to two.
- Production deploys the root <=2 controller/token invariant, Host-publication edge accounting, zero-child assignment/subscriber retention, and `dynacast: false` with ordered active `q,h`. Local `gate:sfu-root-invariants` proves that control-plane boundary; real shaped LiveKit packet flow, BWE downshift/recovery, and resource cost remain open.
- Relay quality handling compares fresh child FPS with parent input. Two-child corroboration is retained only for a future accepted capacity tier and is unreachable under the ordinary Browser Viewer1 release clamp. Deployed MBB keeps the triggering child's old edge while an ordinary Viewer with peer/SFU upstream or the Host, each with a strict spare slot, owns a separate provisional child PC. Matching current-generation RTP, decoded frames, live video, revision, and identity promote that same PC; Host2 accounting includes its SFU publication and selected/provisional overlays. Failure, timeout, session/share change, or no candidate keeps the old edge without SFU/TURN. Sibling MBB remains open.
+- The opt-in local Chrome `BENCHMARK_CANARY=viewer-mbb` now injects synthetic correlated bad-relay windows and verifies real provisional-PC retention, promotion, identity continuity, edge cap, and no route-failed output using sanitized counters only. It is control-path evidence, not detector or network-performance evidence; Host-candidate and signaling-response-blackhole canaries remain deferred.
- A generation-bound 15-second initial-connect deadline enters ICE restart. One-root healthy-SFU make-before-break is deployed but media-unverified; capacity `0 -> 1`, multi-root, browser, and mobile gates remain open.
## Active Milestone
diff --git a/scripts/peer-assisted-benchmark.ts b/scripts/peer-assisted-benchmark.ts
index aba698b9..ef28fff2 100644
--- a/scripts/peer-assisted-benchmark.ts
+++ b/scripts/peer-assisted-benchmark.ts
@@ -32,6 +32,15 @@ import {
const PROFILE_SETTINGS = QUALITY_PROFILES;
type ProfileId = QualityProfileId;
type PageRole = "host" | "viewer";
+export type BenchmarkCanaryMode = "none" | "viewer-mbb";
+
+interface ViewerMbbCanaryResult {
+ kind: "viewer-mbb";
+ status: "passed" | "failed";
+ assertions: Record<string, boolean>;
+ counters: Record<string, number>;
+ failureCode?: "topology-unavailable" | "probe-unavailable";
+}
export interface BenchmarkConfig {
chromePath: string;
@@ -48,6 +57,7 @@ export interface BenchmarkConfig {
headless: boolean;
noSandbox: boolean;
qualityControlSmoke: boolean;
+ canaryMode: BenchmarkCanaryMode;
}
interface MediaTotals {
@@ -368,6 +378,12 @@ function parseBoolean(value: string | undefined, fallback: boolean, name: string
throw new Error(`${name} must be true, false, 1, or 0`);
}
+export function parseBenchmarkCanaryMode(value: string | undefined): BenchmarkCanaryMode {
+ const mode = value?.trim() || "none";
+ if (mode === "none" || mode === "viewer-mbb") return mode;
+ throw new Error("BENCHMARK_CANARY must be none or viewer-mbb");
+}
+
export function parseExpectedEndpointCap(value: string | undefined): number {
const parsed = value?.trim()
? Number(value)
@@ -406,6 +422,7 @@ export function parseBenchmarkConfig(
"BENCHMARK_QUALITY_SMOKE requires a selected viewer count of at least 3",
);
}
+ const canaryMode = parseBenchmarkCanaryMode(environment.BENCHMARK_CANARY);
const recoveryText = environment.BENCHMARK_RECOVERY_VIEWERS?.trim();
const recoveryViewerCount = recoveryText ? Number(recoveryText) : null;
if (
@@ -477,6 +494,7 @@ export function parseBenchmarkConfig(
"BENCHMARK_CHROME_NO_SANDBOX",
),
qualityControlSmoke,
+ canaryMode,
};
}
@@ -976,6 +994,9 @@ export function buildBenchmarkInitScript(options: {
let transitionRevision = -1;
let transitionPhase = null;
let plannedRouteAssignment = null;
+ const canary = { droppedProofs: 0, prepareUpdates: 0, activeUpdates: 0, routeFailed: 0 };
+ let dropParentProof = false;
+ const nativeSends = new WeakMap();
function isOpaqueId(value) {
return typeof value === "string" &&
@@ -1059,6 +1080,8 @@ export function buildBenchmarkInitScript(options: {
transitionRevision = revision;
transitionPhase = phase;
plannedRouteAssignment = assignment;
+ if (phase === "prepare") canary.prepareUpdates += 1;
+ else canary.activeUpdates += 1;
if (phase === "active") {
state.routeRevision = revision;
state.routeAssignment = cloneRouteAssignment(assignment);
@@ -1119,6 +1142,8 @@ export function buildBenchmarkInitScript(options: {
state.routeAssignment.sfuPublicationGeneration,
});
if (state.activeRouteReady.length > 32) state.activeRouteReady.shift();
+ } else if (direction === "out" && message.type === "route-failed") {
+ canary.routeFailed += 1;
}
if (direction === "in" && message.type === "authenticated") {
state.peerId = message.peerId;
@@ -1151,7 +1176,15 @@ export function buildBenchmarkInitScript(options: {
construct(Target, args) {
const socket = Reflect.construct(Target, args, Target);
const nativeSend = socket.send;
+ nativeSends.set(socket, nativeSend);
socket.send = function(data) {
+ let parsed = null;
+ if (typeof data === "string") { try { parsed = JSON.parse(data); } catch {} }
+ if (dropParentProof && parsed?.type === "parent-edge-quality-evidence") {
+ canary.droppedProofs += 1;
+ handleSignalMessage(data, "out", socket);
+ return undefined;
+ }
const result = nativeSend.call(socket, data);
handleSignalMessage(data, "out", socket);
return result;
@@ -1166,6 +1199,16 @@ export function buildBenchmarkInitScript(options: {
},
});
+ function sendCanaryMessage(message) {
+ const socket = signalingSocket;
+ const nativeSend = socket ? nativeSends.get(socket) : null;
+ if (!socket || typeof nativeSend !== "function") return false;
+ try {
+ nativeSend.call(socket, JSON.stringify(message));
+ return true;
+ } catch { return false; }
+ }
+
const NativePeerConnection = globalThis.RTCPeerConnection;
function recordActiveOutboundEdges() {
const active = connections.filter(({ connection }) =>
@@ -1401,9 +1444,24 @@ export function buildBenchmarkInitScript(options: {
};
}
+ function configureCanary(value) {
+ if (!value || typeof value.dropParentProof !== "boolean") return false;
+ dropParentProof = value.dropParentProof;
+ return true;
+ }
+ function canarySnapshot() {
+ return { ...canary, connectionCount: connections.length, maxActiveOutboundMediaEdges: state.maxActiveOutboundMediaEdges };
+ }
+ function sendViewerQualityEvidence(message) {
+ return message?.type === "viewer-quality-evidence" && sendCanaryMessage(message);
+ }
+ function sendParentEdgeQualityEvidence(message) {
+ return message?.type === "parent-edge-quality-evidence" && sendCanaryMessage(message);
+ }
+
Object.defineProperty(globalThis, "__SCREENER_BENCHMARK__", {
configurable: false,
- value: { sample, progress, snapshot, stop: () => clearInterval(videoObserver) },
+ value: { sample, progress, snapshot, canarySnapshot, configureCanary, sendViewerQualityEvidence, sendParentEdgeQualityEvidence, stop: () => clearInterval(videoObserver) },
});
})();`;
}
@@ -2200,6 +2258,135 @@ async function runRecovery(
};
}
+async function runViewerMbbCanary(
+ cdp: CdpConnection,
+ pages: PageHandle[],
+ signal: AbortSignal,
+): Promise<ViewerMbbCanaryResult> {
+ const failed = (failureCode: ViewerMbbCanaryResult["failureCode"]): ViewerMbbCanaryResult => ({
+ kind: "viewer-mbb", status: "failed", assertions: {}, counters: {}, failureCode,
+ });
+ let parentHandle: PageHandle | null = null;
+ try {
+ const observations = await Promise.all(pages.map((page) => progressSample(cdp, page)));
+ const byPeer = new Map(observations.flatMap((page) => page.peerId ? [[page.peerId, page] as const] : []));
+ const viewers = observations.filter((page) => page.role === "viewer");
+ const target = viewers.find((page) => {
+ const upstream = page.routeAssignment?.upstream;
+ const parent = upstream?.kind === "peer" ? byPeer.get(upstream.peerId) : null;
+ return page.routeRevision !== null && upstream?.kind === "peer" &&
+ parent?.role === "viewer" && page.routeAssignment?.childPeerIds.length === 0;
+ });
+ const candidate = viewers.find((page) => page !== target && page.peerId &&
+ page.routeAssignment?.childPeerIds.length === 0 && hasAuthoritativeMediaUpstream(page) &&
+ activeVideoEdgeCount(page, "send") === 0);
+ if (!target || !candidate || target.routeAssignment?.upstream.kind !== "peer") return failed("topology-unavailable");
+ const parent = byPeer.get(target.routeAssignment.upstream.peerId);
+ if (!parent) return failed("topology-unavailable");
+ const targetHandle = pages.find((page) => page.label === target.label);
+ parentHandle = pages.find((page) => page.label === parent.label) ?? null;
+ const candidateHandle = pages.find((page) => page.label === candidate.label);
+ const old = target.connections.find((connection) =>
+ connection.hasInboundVideo && connection.connectionState === "connected" &&
+ connection.remotePeerId === parent.peerId && connection.connectionId,
+ );
+ if (!targetHandle || !parentHandle || !candidateHandle || !old || target.routeRevision === null || !target.peerId || !parent.peerId || !old.connectionId) return failed("probe-unavailable");
+ const oldFrames = old.receiveTotals?.framesTotal ?? 0;
+ const revision = target.routeRevision;
+ await evaluate(cdp, parentHandle, "globalThis.__SCREENER_BENCHMARK__.configureCanary({dropParentProof:true})");
+ const send = (page: PageHandle, method: string, message: unknown) =>
+ evaluate<boolean>(cdp, page, `globalThis.__SCREENER_BENCHMARK__.${method}(${JSON.stringify(message)})`);
+ let windows = 0;
+ let proofs = 0;
+ for (let sequence = 0; sequence < 3; sequence += 1) {
+ const windowSent = await send(targetHandle, "sendViewerQualityEvidence", {
+ type: "viewer-quality-evidence", guard: { connectionId: old.connectionId, routeRevision: revision },
+ sequence, windowMs: 2_000,
+ metrics: { width: null, height: null, framesPerSecond: 0, bitrateKbps: 0,
+ packetsReceivedDelta: 100, packetsLostDelta: 0, jitterMs: 0, framesDecodedDelta: 0,
+ framesDroppedDelta: 0, decodeMsPerFrame: 0, freezeCountDelta: 0, freezeDurationMsDelta: null,
+ codec: null, codecProfile: null, codecParameters: null },
+ });
+ if (windowSent) windows += 1;
+ await delay(100, signal);
+ const proofSent = await send(parentHandle, "sendParentEdgeQualityEvidence", {
+ type: "parent-edge-quality-evidence", viewerPeerId: target.peerId,
+ guard: { connectionId: old.connectionId, routeRevision: revision }, viewerSequence: sequence,
+ proof: { kind: "sender-limited", packetsSentDelta: 100, reason: "bandwidth" },
+ });
+ if (proofSent) proofs += 1;
+ if (sequence < 2) await delay(2_100, signal);
+ }
+ let retained = false, provisional = false, promoted = false, sameIdentity = false, framesAdvanced = false;
+ let newId: string | null = null, newIndex: number | null = null;
+ let targetTelemetry = await canary(cdp, targetHandle);
+ let parentTelemetry = await canary(cdp, parentHandle);
+ let candidateTelemetry = await canary(cdp, candidateHandle);
+ const deadline = Date.now() + 15_000;
+ while (Date.now() < deadline) {
+ const current = await progressSample(cdp, targetHandle);
+ targetTelemetry = await canary(cdp, targetHandle);
+ parentTelemetry = await canary(cdp, parentHandle);
+ candidateTelemetry = await canary(cdp, candidateHandle);
+ const currentOld = current.connections.find((connection) => connection.connectionId === old.connectionId);
+ const currentNew = current.connections.find((connection) => connection.hasInboundVideo && connection.index !== old.index && connection.connectionState === "connected" && connection.connectionId !== old.connectionId);
+ if (currentOld?.connectionState === "connected" && currentNew) {
+ retained = true; provisional = true; newId = currentNew.connectionId; newIndex = currentNew.index;
+ }
+ framesAdvanced ||= (currentOld?.receiveTotals?.framesTotal ?? oldFrames) > oldFrames;
+ const upstream = current.routeAssignment?.upstream;
+ const upstreamPeerId = upstream?.kind === "peer" ? upstream.peerId : null;
+ promoted = current.routeRevision !== null && current.routeRevision !== revision && upstreamPeerId !== null && upstreamPeerId !== parent.peerId;
+ if (promoted) {
+ const active = current.connections.find((connection) => connection.hasInboundVideo && connection.connectionState === "connected" && connection.remotePeerId === upstreamPeerId);
+ sameIdentity = Boolean(active && ((newId && active.connectionId === newId) || (!newId && active.index === newIndex)));
+ }
+ if (promoted && sameIdentity && retained && framesAdvanced) break;
+ await delay(100, signal);
+ }
+ await evaluate(cdp, parentHandle, "globalThis.__SCREENER_BENCHMARK__.configureCanary({dropParentProof:false})");
+ const assertions = {
+ syntheticCorrelatedEvidence: windows === 3 && proofs === 3,
+ parentProofSuppressed: parentTelemetry.droppedProofs > 0,
+ oldEdgeRetained: retained,
+ provisionalPcObserved: provisional,
+ promotedToViewerCandidate: promoted,
+ provisionalIdentityPromoted: sameIdentity,
+ oldMediaFramesAdvanced: framesAdvanced,
+ endpointCapRespected: Math.max(targetTelemetry.maxActiveOutboundMediaEdges, parentTelemetry.maxActiveOutboundMediaEdges, candidateTelemetry.maxActiveOutboundMediaEdges) <= 1,
+ noRouteFailed: targetTelemetry.routeFailed === 0 && parentTelemetry.routeFailed === 0 && candidateTelemetry.routeFailed === 0,
+ };
+ return { kind: "viewer-mbb", status: Object.values(assertions).every(Boolean) ? "passed" : "failed", assertions,
+ counters: { pages: pages.length, evidenceWindows: windows, parentProofs: proofs,
+ droppedParentProofs: parentTelemetry.droppedProofs, routePrepareUpdates: targetTelemetry.prepareUpdates + parentTelemetry.prepareUpdates + candidateTelemetry.prepareUpdates,
+ routeActiveUpdates: targetTelemetry.activeUpdates + parentTelemetry.activeUpdates + candidateTelemetry.activeUpdates,
+ maxActiveOutboundEdges: Math.max(targetTelemetry.maxActiveOutboundMediaEdges, parentTelemetry.maxActiveOutboundMediaEdges, candidateTelemetry.maxActiveOutboundMediaEdges),
+ routeFailedMessages: targetTelemetry.routeFailed + parentTelemetry.routeFailed + candidateTelemetry.routeFailed },
+ ...(Object.values(assertions).every(Boolean) ? {} : { failureCode: "probe-unavailable" as const }) };
+ } catch {
+ if (parentHandle) await evaluate(cdp, parentHandle, "globalThis.__SCREENER_BENCHMARK__.configureCanary({dropParentProof:false})").catch(() => undefined);
+ return failed("probe-unavailable");
+ }
+}
+
+async function canary(cdp: CdpConnection, page: PageHandle): Promise<{
+ droppedProofs: number; prepareUpdates: number; activeUpdates: number; routeFailed: number;
+ maxActiveOutboundMediaEdges: number;
+}> {
+ return evaluate(cdp, page, "globalThis.__SCREENER_BENCHMARK__.canarySnapshot()");
+}
+
+function canaryChecks(result: ViewerMbbCanaryResult): RunCheck[] {
+ return [
+ ...Object.entries(result.assertions).map(([name, passed]) => ({
+ name: `viewer-mbb-${name}`, passed, actual: passed, expected: "true",
+ })),
+ ...Object.entries(result.counters).map(([name, actual]) => ({
+ name: `viewer-mbb-counter-${name}`, passed: true, actual, expected: "sanitized counter",
+ })),
+ ];
+}
+
async function runCase(
cdp: CdpConnection,
baseUrl: string,
@@ -2263,6 +2450,19 @@ async function runCase(
if (config.settleMs > 0) {
await delay(config.settleMs, signal);
}
+ if (config.canaryMode === "viewer-mbb" && viewerCount === 3) {
+ const canaryResult = await runViewerMbbCanary(cdp, pages, signal);
+ return {
+ viewerCount,
+ startedAt: new Date(startedAtMs).toISOString(),
+ completedAt: new Date().toISOString(),
+ status: canaryResult.status,
+ checks: canaryChecks(canaryResult),
+ summary: null,
+ samples: [],
+ recovery: { triggered: false },
+ };
+ }
const measurementStartedAt = Date.now();
const deadline = measurementStartedAt + config.durationMs;
do {
@@ -2416,6 +2616,7 @@ export async function main(): Promise<number> {
headless: config.headless,
noSandbox: config.noSandbox,
qualityControlSmoke: config.qualityControlSmoke,
+ canaryMode: config.canaryMode,
chromeExecutable: basename(config.chromePath),
output: config.outputPath ?? "stdout",
},
@@ -2434,6 +2635,7 @@ export async function main(): Promise<number> {
"CDP SystemInfo exposes no resident-set field, so peakResidentSetBytes is null; GPU, NIC, glass-to-glass latency, generational visual quality, mobile browsers, and TURN require other measurement.",
"The local runner does not start LiveKit; SFU consistency is reported only when an SFU route is actually observed.",
"The harness emits raw gate fields and simple invariants; it does not implement a route score or runtime policy.",
+ "BENCHMARK_CANARY=viewer-mbb injects only sanitized control counters; it does not claim detector quality or network performance. Host-candidate and signaling-blackhole canaries remain deferred.",
],
runs: [],
};
@@ -2463,7 +2665,10 @@ export async function main(): Promise<number> {
ROOM_DATABASE_PATH: "",
PEER_ASSISTED_MEDIA: "true",
MAX_PEER_RELAY_DOWNSTREAM_EDGES: String(config.expectedEndpointCap),
- MAX_VIEWERS_PER_ROOM: String(Math.max(...config.viewerCounts)),
+ MAX_VIEWERS_PER_ROOM: String(Math.max(
+ ...config.viewerCounts,
+ config.canaryMode === "viewer-mbb" ? 3 : 1,
+ )),
STUN_URLS: "",
});
server = await createScreenerServer({
@@ -2505,7 +2710,8 @@ export async function main(): Promise<number> {
cdp = await CdpConnection.connect(version.webSocketDebuggerUrl);
report.chromium = await cdp.call("Browser.getVersion");
- for (const viewerCount of config.viewerCounts) {
+ const viewerCounts = config.canaryMode === "viewer-mbb" ? [3] : config.viewerCounts;
+ for (const viewerCount of viewerCounts) {
abortController.signal.throwIfAborted();
console.error(`Running peer-topology loopback with ${viewerCount} viewer(s)`);
report.runs.push(
diff --git a/tests/peer-assisted-benchmark.test.ts b/tests/peer-assisted-benchmark.test.ts
index 479b38ed..cd273f29 100644
--- a/tests/peer-assisted-benchmark.test.ts
+++ b/tests/peer-assisted-benchmark.test.ts
@@ -10,6 +10,7 @@ import {
everyViewerAdvanced,
everyViewerRecoveredMedia,
mergeRecoveryHostPeaks,
+ parseBenchmarkCanaryMode,
parseBenchmarkConfig,
parseExpectedEndpointCap,
parseViewerCounts,
@@ -172,10 +173,14 @@ function createObserverHarness(expectedEndpointCap = 2) {
const WebSocketConstructor = context.WebSocket as new () => FakeWebSocket;
const api = context.__SCREENER_BENCHMARK__ as {
snapshot: () => ObserverSnapshot;
+ canarySnapshot: () => Record<string, unknown>;
+ configureCanary: (value: Record<string, unknown>) => boolean;
};
return {
socket: () => new WebSocketConstructor(),
snapshot: () => structuredClone(api.snapshot()),
+ canarySnapshot: () => structuredClone(api.canarySnapshot()),
+ configureCanary: (value: Record<string, unknown>) => api.configureCanary(value),
};
}
@@ -213,6 +218,13 @@ function markActiveRouteReady(observation: ReturnType<typeof page>): void {
}
describe("peer topology loopback configuration", () => {
+ it("keeps the real-relay canary opt-in", () => {
+ expect(parseBenchmarkCanaryMode(undefined)).toBe("none");
+ expect(parseBenchmarkCanaryMode("viewer-mbb")).toBe("viewer-mbb");
+ expect(parseBenchmarkConfig({ CHROME_PATH: "chrome", BENCHMARK_CANARY: "viewer-mbb" }).canaryMode).toBe("viewer-mbb");
+ expect(() => parseBenchmarkCanaryMode("signaling")).toThrow(/BENCHMARK_CANARY/);
+ });
+
it("uses the bounded 1/3/5/8 matrix by default", () => {
expect(parseViewerCounts(undefined)).toEqual([1, 3, 5, 8]);
});
@@ -273,6 +285,16 @@ describe("peer topology loopback configuration", () => {
});
describe("peer topology loopback observations", () => {
+ it("suppresses parent proof only through the opt-in injected control", () => {
+ const observer = createObserverHarness();
+ const socket = observer.socket();
+ authenticate(socket);
+ expect(observer.configureCanary({ dropParentProof: true })).toBe(true);
+ socket.send(JSON.stringify({ type: "parent-edge-quality-evidence" }));
+ expect(observer.canarySnapshot()).toMatchObject({ droppedProofs: 1 });
+ expect(Object.keys(observer.canarySnapshot())).not.toContain("connectionId");
+ });
+
it("counts only active media connections in the requested direction", () => {
const host = page("host", "host", 2, 0);
host.connections[0]!.connectionState = "closed";