Free, open-source screen sharing for private live streams with friends. Watch together in a browser or self-host Piik. 免费开源的私密屏幕共享,支持游戏直播、一起看电影与自部署。
feat(quality): add authenticated viewer evidence
AAAa949fbaf159d
diff --git a/docs/project-memory.md b/docs/project-memory.mdindex adbe22a4..57c11cb7 100644--- a/docs/project-memory.md+++ b/docs/project-memory.md@@ -25,7 +25,7 @@ Last updated: 2026-08-19- Keep the current failure-only controller default-off until config migration and exact-room gates pass. Preserve break-before-make, sticky healthy subtrees, mobile leaves, and PR #20 prewarm; public transport/load remains open.- Local reparenting is a later candidate: start with unassigned relay admission rescue; do not block current work.- Flagship media defaults to UDP; HTTPS/WSS remains TLS/TCP. Current production still requires coturn UDP/TCP. Future TURN absence is normal, partial config fails, and any media-TCP/port compatibility mode is chosen only by canary.-- Treat settings as ceilings and deployed degradation as unclassified. Use local Host A+B to compare exact `769de201f7cc` against current `main` for Host-only recovery, game FPS/load, preview cost, actual codec/encoder and one-variable rebuilds; then add authenticated C and test standard simulcast/LiveKit/SVC before custom `LOW`. Never use UA or a composite score.+- Treat settings as ceilings and deployed degradation as unclassified. Use correlated Host A+B/Viewer C to compare exact `769de201f7cc` against current `main` for Host-only recovery, game FPS/load, preview cost, actual codec/encoder and one-variable rebuilds; then test standard simulcast/LiveKit/SVC before custom `LOW`. Never use UA or a composite score.- Production reports poor film audio and self-echo when system capture includes voice software. Diagnose audio A/B/C and sync; Web cannot isolate arbitrary processes and `maxBitrate` is not quality-up. A Windows 11 native candidate defaults to game-process-tree audio and never widens silently; Windows 10 remains unresolved/unsupported. See `docs/research/browser-screen-audio-quality.md`.- Do not add scene detection, dynamic-FPS control, or forced AV1 until stats and target hardware prove the need. Codec acceptance requires actual negotiation, power-efficient candidate evidence, interval encode cost, game FPS, CPU/GPU and sender count; Discord's native capture/hardware tuning is comparison evidence, not proof of server re-encoding or a reusable preset.- Keep room policy deployment-driven: public/password-only rooms are random and temporary; password plus SQLite enables sequential persistent rooms and reusable stopped links.@@ -45,9 +45,9 @@ Last updated: 2026-08-19- Draft native ladder #16/#18/#22/#23/#25/#28 has one bounded Chrome 720p30 loop: one WebCodecs object feeds two Pion/browser legs, applies an experiment-only minimum stock-GCC target, and recovers one isolated loss. It does not prove one hardware encode.- Stock Pion GCC plus negotiated RTX is a no-go. The no-RTX candidate can distort loss statistics and stays outside product code until audio, heterogeneous estimates, broader loss, TURN/reconnect, and browser-diversity gates pass; do not add custom congestion control to bypass them.- Chrome 151 short synthetic `1/3/5/8` runs kept host edges at two, relay edges at one, and all viewers decoding; a three-viewer relay close recovered in 5.32 seconds. This proves topology/control only, not quality, load, endurance, or silent partitions.-- The current quality stack uses one strict, non-persistent `QualitySettings` value with bounded ceilings and clarity/balanced/fluid preference. Sender readback and limitation warnings remain manual diagnostics. ADR-0007's automatic per-path `HIGH`/`FALLBACK` and unique on-demand shared `LOW` are accepted mainline behavior, but the C report, state controller, and `LOW` runtime are unimplemented.+- The current quality stack uses one strict, non-persistent `QualitySettings` value with bounded ceilings and clarity/balanced/fluid preference. Sender readback and limitation warnings remain manual diagnostics. ADR-0007's automatic per-path `HIGH`/`FALLBACK` and unique on-demand shared `LOW` are accepted mainline behavior, but the state controller and `LOW` runtime are unimplemented.- Chrome 151 synthetic 720p30 propagated balanced/clarity to one host and three viewers without changing peer identities; all viewers kept decoding and fanout stayed host two/relay one. This proves control continuity only.-- Local Host A+B aligns current capture settings with one unique outbound RTP/remote/transport pair per tick, rebases deltas on ambiguity, identity change, or reset, and rejects stale source generations. Codec evidence is nullable and transport-bound; no defaults or profile capability are inferred, raw fmtp/SDP/stats are not retained, and multiple RTP/encodings remain unknown. Authenticated C, automatic control, and `LOW` remain absent.+- Local Host A+B aligns capture with one unique outbound RTP/remote/transport pair and rejects ambiguous or stale generations. Authenticated Viewer C now adds a nullable, sanitized two-second receive window of at most 2 KiB for each current ordinary or peer-assisted P2P hop; the server derives identity and current connection/revision, and the parent correlates only matching local B. It retains no raw fmtp/SDP/stats, performs no media action, and fails closed for SFU-fed roots. Automatic control and `LOW` remain absent.- Release `769de201f7cc` passed CI/hygiene/typecheck, 22 files/274 tests, both builds, zero production dependency vulnerabilities, atomic activation, public health/access, exact bundle, and service/log checks.## Provisional Quality Targetsdiff --git a/docs/research/realtime-quality-adaptation.md b/docs/research/realtime-quality-adaptation.mdindex d68724a3..b7bdd52a 100644--- a/docs/research/realtime-quality-adaptation.md+++ b/docs/research/realtime-quality-adaptation.md@@ -164,20 +164,28 @@ This is a diagnostic classification, not a weighted health score. Missing orreset evidence remains unknown and rebases the interval.The smallest implementation sequence is local A+B correlation in one host-sampling tick, including the interval, media/stat identity, and valid deltas.-Only after that is trustworthy should a minimal authenticated C report carry-the receive/decode and derived negotiation signals needed by the two-state+sampling tick, followed by a minimal authenticated C report carrying the+receive/decode and derived negotiation signals needed by the two-statepredicate. It never carries raw SDP, raw stats, candidate addresses, or raw-device/network identifiers. Opaque server-issued path and connection-generation-IDs provide authorization and correlation; a general remote stats stream or+device/network identifiers. Server-authoritative path and connection generations+provide authorization and correlation; a general remote stats stream ortelemetry pipeline is unnecessary.-The repository now implements the local host A+B foundation: same-tick capture+The repository implements the local host A+B foundation: same-tick capturesettings plus one uniquely matched outbound RTP sample, explicit sample/mediaidentity and adjacent deltas, `remoteId` linkage, and the selected path reachedthrough that RTP stream's transport. Source replacement blocks sampling andinvalidates in-flight generations.+Authenticated Viewer C is also implemented for each current ordinary or+peer-assisted P2P hop. A viewer sends one nullable, sanitized aggregate window+on the existing two-second stats cadence, bounded to 2 KiB; the server derives+the current viewer, parent, connection, and route revision, while the parent+accepts only the matching local generation and expires it. The report contains+no raw SDP, stats, candidates, addresses, device identifiers, or room identity,+is neither stored nor used for media or routing action, and fails closed for an+SFU-fed root until a real SFU last-hop B/generation exists.+Codec evidence follows only that outbound RTP object's `codecId`, and thereferenced `RTCCodecStats` must use the same transport. The local diagnosticsexpose nullable, bounded MIME plus a normalized profile token and an ASCII allowlist of@@ -195,9 +203,10 @@ The same unique outbound object supplies nullable current configured`scalabilityMode`. Sender parameter readback exposes an applied mode only forone unambiguous encoding. Current quality settings do not request a mode, sothe requested value remains null and a browser-reported default is not called-a mismatch; multiple encodings remain unknown. This still does not implement-an authenticated C report, two-state controller, or on-demand `LOW` runtime,-and browser support remains subject to the controlled matrix.+a mismatch; multiple encodings remain unknown. Inbound stats provide no current+standard `scalabilityMode` source, so C does not carry a null-only placeholder.+The two-state controller and on-demand `LOW` runtime remain unimplemented, and+browser support remains subject to the controlled matrix.Official W3C text checked 2026-08-19 defines names ending in `Id` as stats-objectreferences. In particular, outbound [`mediaSourceId`](https://www.w3.org/TR/webrtc-stats/#dom-rtcoutboundrtpstreamstats-mediasourceid)diff --git a/docs/status.md b/docs/status.mdindex b4a7d25a..45c3eb4b 100644--- a/docs/status.md+++ b/docs/status.md@@ -17,7 +17,7 @@ unconfigured, so production remains one host connection per viewer and P2P/TURN.- SFU normally feeds one or two roots. Downstream cap is two, browser relay one; exceptional central edges need a separate cap. Production routing is off.- Configured fallback adds a non-secret standby URL and token-free DNS/TLS warmup; absent configuration adds no field, import, request, participant, or edge.- Each viewer advertises relay capacity 0/1; detected mobile/iPad clients are leaves. Withdrawal does not move a healthy edge. Browser relays stay one-child and host two-child.-- Production has memory-only video settings and manual readback. Automatic `HIGH`/`FALLBACK` plus one shared on-demand `LOW` is accepted but not deployed; host A+B exists, while C/actions do not. Browser audio is request/presence-only.+- Production has memory-only video settings and manual readback. Automatic `HIGH`/`FALLBACK` plus one shared on-demand `LOW` is accepted but not deployed; local A+B and authenticated P2P Viewer C are read-only evidence. Browser audio is request/presence-only.## Verified Evidence@@ -26,7 +26,7 @@ unconfigured, so production remains one host connection per viewer and P2P/TURN.- Synthetic Chrome 151 720p30 propagated balanced/clarity to one host and three viewers without peer changes; decoding and 2/1 fanout continued. This proves control continuity only.- Chrome 151/LiveKit localhost A/B measured cold active/render at 1.481/2.257 seconds versus standby 0.200/0.320 with host edges at two. It includes SDK/prewarm and is not public-network evidence.- Atomic activation passed health/access, exact bundle, SQLite preservation, services, and logs; the old release is rollback-ready. Responsive 320/375/390 px checks passed without live media.-- Host A+B aligns capture/outbound identity, deltas, path, and nullable transport-bound codec/`scalabilityMode`; stale or ambiguous data stays unknown and no raw media metadata is retained. Review found no P1/P2; 22 files/299 tests and both builds passed.+- Host A+B aligns capture/outbound identity, deltas, path, and nullable transport-bound codec/`scalabilityMode`. Authenticated Viewer C is limited to the current ordinary or peer-assisted P2P hop and its connection/revision; two-second windows are at most 2 KiB, sanitized, generation-bound, and read-only. Stale, ambiguous, and SFU-fed evidence fails closed; no raw media metadata is retained.- HTTPS/WSS, access and room/WebSocket auth, renewal, public STUN, and authenticated TURN/UDP/TCP relay-only paths pass; TURN/TLS is off.- Draft #16/#18/#22/#23/#25/#28 passed isolated experiments only. ADR-0006 reached host setup/one encoder output, then timed out before viewer 1 decoded/rendered.@@ -37,7 +37,7 @@ unconfigured, so production remains one host connection per viewer and P2P/TURN.- Silent partitions can wait 30 to 60 seconds for heartbeat detection before the default 5-second grace; this remains unverified.- Real audio and heterogeneous clients remain unverified. Production reports poor film audio and voice-call self-echo under system capture; there is no app audio ceiling or Web process isolation. Diagnose A/B/C and sync, then gate Windows 11 game-process audio; Windows 10 stays unresolved without system fallback.- Production `769de201f7cc` reportedly sustains native `qualityLimitationReason=bandwidth` and severe blur with one capable LAN/direct viewer; only Host refresh restores quality. Within the five-second grace, stable-clientId Viewer refresh retains its `peerId`/`HostPeer`, while Host refresh rebuilds peers/capture; churn persistence is also reported. This prioritizes but does not prove sender/PC/GCC/capture generation over network or lifecycle causes.-- ADR-0007 remains incomplete. Host A+B codec fields exist, but browser support and the reported case are unverified; authenticated C, the controller, and `LOW` are absent. Weak paths must share one `LOW`; fail closed protects `HIGH` only exceptionally, and an unreliable supported cohort fails acceptance.+- ADR-0007 remains incomplete. A+B/C browser support and the reported case are unverified; the controller, `LOW`, and an authenticated SFU last-hop C generation are absent. Weak paths must share one `LOW`; fail closed protects `HIGH` only exceptionally, and an unreliable supported cohort fails acceptance.- Browser relays re-encode. ADR-0006 is no-go-unclassified: downstream checkpoints and two-edge/FIFO/TURN gates are absent. Spikes prove one WebCodecs object, not hardware; GCC+RTX is no-go and no-RTX weakens stats.- Browser fanout is host two/viewer one; any accepted endpoint relay stays capped at two downstream edges.- ADR-0005 accepts SFU-root fallback, but code is failure-only/TURN-required; UDP-first config, edge grants, bounded failure, cost/trust, and public canary are absent.@@ -46,14 +46,13 @@ unconfigured, so production remains one host connection per viewer and P2P/TURN.## Next Milestone-Use Host A+B to compare exact production and current `main` on one wired/direct+Use correlated Host A+B/Viewer C to compare exact production and current `main` on one wired/directgame fixture. Record actual codec/encoder, game FPS, CPU/GPU, preview on/off andA+B while separately rebuilding one `HostPeer`, replacing capture, and fully-refreshing Host; retain the matching Viewer-local sample until authenticated C-lands. Only a proven stuck generation justifies guarded recovery; never+refreshing Host. Only a proven stuck generation justifies guarded recovery; neverreconnect periodically, force AV1, or raise ceilings blindly.-After authenticated video C, test simulcast/LiveKit/SVC in order and stop at the+After that reproduction, test simulcast/LiveKit/SVC in order and stop at thefirst fit before custom `LOW`, independently of ADR-0006. Diagnose audio A/B/C,sync, and voice-source leakage in parallel when it does not displace that P0;`maxBitrate` is not a quality fix. WebRTC/LiveKit owns congestion/layers; the appdiff --git a/src/client/media/viewer-quality-evidence.ts b/src/client/media/viewer-quality-evidence.tsnew file mode 100644index 00000000..2f7973df--- /dev/null+++ b/src/client/media/viewer-quality-evidence.ts@@ -0,0 +1,250 @@+import {+ MAX_MEDIA_ROUTE_REVISION,+ MAX_VIEWER_QUALITY_EVIDENCE_BYTES,+ VIEWER_QUALITY_EVIDENCE_INTERVAL_MS,+ viewerQualityEvidenceMessageSchema,+ viewerQualityEvidenceMetricsSchema,+ type ClientMessage,+ type ServerMessage,+ type ViewerQualityEvidenceMetrics,+} from "../../shared/protocol";+import {+ EMPTY_METRICS,+ type ConnectionMetrics,+ type PeerSnapshot,+} from "../types";++type ViewerQualityEvidence = Extract<+ ServerMessage,+ { type: "viewer-quality-evidence" }+>;++type ViewerQualityEvidenceWindow = Pick<+ Extract<ClientMessage, { type: "viewer-quality-evidence" }>,+ "windowMs" | "metrics"+>;++function boundedNumber(value: number | null, maximum: number): number | null {+ return value !== null && Number.isFinite(value) && value >= 0 && value <= maximum+ ? value+ : null;+}++function boundedInteger(value: number | null, maximum: number): number | null {+ return value !== null && Number.isInteger(value) && value >= 0 && value <= maximum+ ? value+ : null;+}++function boundedString(+ value: string | null,+ maximumLength: number,+ pattern: RegExp,+): string | null {+ return value !== null &&+ value.length <= maximumLength &&+ pattern.test(value)+ ? value+ : null;+}++export function qualityEvidenceWindowFromMetrics(+ metrics: ConnectionMetrics,+): ViewerQualityEvidenceWindow | null {+ if (metrics.sampleWindowMs === null || !Number.isFinite(metrics.sampleWindowMs)) {+ return null;+ }+ const windowMs = Math.round(metrics.sampleWindowMs);+ if (windowMs < 1_000 || windowMs > 5_000) {+ return null;+ }++ const boundedWidth = boundedInteger(metrics.frameWidth, 16_384);+ const boundedHeight = boundedInteger(metrics.frameHeight, 16_384);+ const width = boundedWidth !== null && boundedWidth >= 1 ? boundedWidth : null;+ const height =+ boundedHeight !== null && boundedHeight >= 1 ? boundedHeight : null;+ const dimensions =+ width !== null && height !== null+ ? { width, height }+ : { width: null, height: null };+ const freezeDuration = boundedNumber(+ metrics.intervalFreezeDurationMs,+ windowMs,+ );+ const candidate: ViewerQualityEvidenceMetrics = {+ ...dimensions,+ framesPerSecond: boundedNumber(metrics.framesPerSecond, 240),+ bitrateKbps: boundedNumber(metrics.bitrateKbps, 100_000),+ packetsReceivedDelta: boundedInteger(+ metrics.intervalPacketsReceived,+ 1_000_000,+ ),+ packetsLostDelta: boundedInteger(metrics.intervalPacketsLost, 1_000_000),+ jitterMs: boundedNumber(metrics.jitterMs, 60_000),+ framesDecodedDelta: boundedInteger(+ metrics.intervalFramesDecoded,+ 10_000,+ ),+ framesDroppedDelta: boundedInteger(+ metrics.intervalFramesDropped,+ 10_000,+ ),+ decodeMsPerFrame: boundedNumber(metrics.intervalDecodeMs, 60_000),+ freezeCountDelta: boundedInteger(metrics.intervalFreezeCount, 10_000),+ freezeDurationMsDelta: freezeDuration,+ codec: boundedString(+ metrics.codec,+ 64,+ /^video\/[A-Za-z0-9.+-]{1,32}$/i,+ ),+ codecProfile: boundedString(+ metrics.codecProfile,+ 64,+ /^[a-z0-9-]+=[a-z0-9]+$/,+ ),+ codecParameters: boundedString(+ metrics.codecParameters,+ 128,+ /^[a-z0-9-]+=[a-z0-9]+(?:; [a-z0-9-]+=[a-z0-9]+)*$/,+ ),+ };+ const parsed = viewerQualityEvidenceMetricsSchema.safeParse(candidate);+ return parsed.success ? { windowMs, metrics: parsed.data } : null;+}++export class ViewerQualityEvidenceReporter {+ private connectionId: string | null = null;+ private routeRevision: number | null = null;+ private sequence = 0;+ private lastSentAtMs: number | null = null;+ private lastSampleTimestampMs: number | null = null;++ constructor(+ private readonly send: (message: ClientMessage) => boolean,+ private readonly now: () => number = Date.now,+ ) {}++ offer(snapshot: PeerSnapshot, routeRevision: number): boolean {+ if (+ !Number.isSafeInteger(routeRevision) ||+ routeRevision < 0 ||+ routeRevision > MAX_MEDIA_ROUTE_REVISION+ ) {+ return false;+ }+ const window = qualityEvidenceWindowFromMetrics(snapshot.metrics);+ const sampleTimestampMs = snapshot.metrics.sampleTimestampMs;+ if (+ !window ||+ sampleTimestampMs === null ||+ !Number.isFinite(sampleTimestampMs) ||+ sampleTimestampMs < 0+ ) {+ return false;+ }+ if (this.connectionId !== snapshot.connectionId) {+ this.connectionId = snapshot.connectionId;+ this.routeRevision = routeRevision;+ this.sequence = 0;+ this.lastSentAtMs = null;+ this.lastSampleTimestampMs = null;+ } else if (this.routeRevision !== routeRevision) {+ this.routeRevision = routeRevision;+ this.lastSentAtMs = null;+ this.lastSampleTimestampMs = null;+ }+ if (this.sequence > Number.MAX_SAFE_INTEGER) {+ return false;+ }++ if (+ this.lastSampleTimestampMs !== null &&+ sampleTimestampMs <= this.lastSampleTimestampMs+ ) {+ return false;+ }+ const now = this.now();+ if (+ !Number.isFinite(now) ||+ (this.lastSentAtMs !== null &&+ now - this.lastSentAtMs < VIEWER_QUALITY_EVIDENCE_INTERVAL_MS)+ ) {+ return false;+ }++ const message = {+ type: "viewer-quality-evidence" as const,+ guard: {+ connectionId: snapshot.connectionId,+ routeRevision,+ },+ sequence: this.sequence,+ ...window,+ };+ const parsed = viewerQualityEvidenceMessageSchema.safeParse(message);+ if (+ !parsed.success ||+ new TextEncoder().encode(JSON.stringify(parsed.data)).byteLength >+ MAX_VIEWER_QUALITY_EVIDENCE_BYTES ||+ !this.send(parsed.data)+ ) {+ return false;+ }++ this.sequence += 1;+ this.lastSentAtMs = now;+ this.lastSampleTimestampMs = sampleTimestampMs;+ return true;+ }++ reset(): void {+ this.connectionId = null;+ this.routeRevision = null;+ this.sequence = 0;+ this.lastSentAtMs = null;+ this.lastSampleTimestampMs = null;+ }+}++export function qualityEvidenceMatchesSnapshot(+ evidence: ViewerQualityEvidence,+ snapshot: PeerSnapshot | null,+): boolean {+ return (+ snapshot !== null &&+ snapshot.peerId === evidence.viewerPeerId &&+ snapshot.connectionId === evidence.guard.connectionId+ );+}++export function metricsFromQualityEvidence(+ evidence: ViewerQualityEvidence,+): ConnectionMetrics {+ const metrics = evidence.metrics;+ return {+ ...EMPTY_METRICS,+ sampleWindowMs: evidence.windowMs,+ framesPerSecond: metrics.framesPerSecond,+ frameWidth: metrics.width,+ frameHeight: metrics.height,+ resolution:+ metrics.width !== null && metrics.height !== null+ ? `${metrics.width}x${metrics.height}`+ : null,+ bitrateKbps: metrics.bitrateKbps,+ packetsLost: metrics.packetsLostDelta,+ intervalPacketsReceived: metrics.packetsReceivedDelta,+ intervalPacketsLost: metrics.packetsLostDelta,+ jitterMs: metrics.jitterMs,+ framesDropped: metrics.framesDroppedDelta,+ intervalFramesDecoded: metrics.framesDecodedDelta,+ intervalFramesDropped: metrics.framesDroppedDelta,+ intervalDecodeMs: metrics.decodeMsPerFrame,+ intervalFreezeCount: metrics.freezeCountDelta,+ intervalFreezeDurationMs: metrics.freezeDurationMsDelta,+ codec: metrics.codec,+ codecProfile: metrics.codecProfile,+ codecParameters: metrics.codecParameters,+ };+}diff --git a/src/client/pages/HostPage.tsx b/src/client/pages/HostPage.tsxindex ad8e9a77..71503901 100644--- a/src/client/pages/HostPage.tsx+++ b/src/client/pages/HostPage.tsx@@ -12,6 +12,7 @@ import {import { useEffect, useMemo, useRef, useState } from "react";import {DEFAULT_QUALITY_SETTINGS,+ VIEWER_QUALITY_EVIDENCE_EXPIRY_MS,type CreateRoomResponse,type IceConfig,type ServerMessage,@@ -52,6 +53,7 @@ import {} from "../media/quality";import { HostSfuRoute } from "../media/host-sfu-route";import { SfuStandbyPrewarmer } from "../media/sfu-standby-prewarmer";+import { metricsFromQualityEvidence } from "../media/viewer-quality-evidence";import type {PeerSnapshot,SignalConnectionState,@@ -65,6 +67,11 @@ import { sourceSwitchNotice } from "./host-page-notices";type HostPhase = "idle" | "starting" | "live" | "ended" | "error";+type ViewerQualityEvidence = Extract<+ ServerMessage,+ { type: "viewer-quality-evidence" }+>;+interface CaptureDetails {resolution: string;frameRate: number | null;@@ -142,6 +149,9 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {const [peerSnapshots, setPeerSnapshots] = useState<Map<string, PeerSnapshot>>(() => new Map(),);+ const [viewerQualityEvidence, setViewerQualityEvidence] = useState<+ Map<string, ViewerQualityEvidence>+ >(() => new Map());const [notice, setNotice] = useState<string | null>(null);const [copied, setCopied] = useState(false);const [switchingSource, setSwitchingSource] = useState(false);@@ -154,7 +164,14 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {const signalRef = useRef<SignalingClient | null>(null);const iceConfigRef = useRef<IceConfig | null>(null);const peersRef = useRef(new Map<string, HostPeer>());+ const viewerQualityEvidenceRef = useRef(+ new Map<string, ViewerQualityEvidence>(),+ );+ const viewerQualityEvidenceTimersRef = useRef(+ new Map<string, number>(),+ );const peerAssistedRef = useRef(false);+ const activeRouteRevisionRef = useRef(0);const generationRef = useRef(0);const activeGenerationRef = useRef<number | null>(null);const sourceSwitchRef = useRef<object | null>(null);@@ -193,6 +210,12 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {signalRef.current?.stop();peersRef.current.forEach((peer) => peer.dispose());peersRef.current.clear();+ viewerQualityEvidenceTimersRef.current.forEach((timer) =>+ window.clearTimeout(timer),+ );+ viewerQualityEvidenceTimersRef.current.clear();+ viewerQualityEvidenceRef.current.clear();+ activeRouteRevisionRef.current = 0;void hostSfuRouteRef.current?.disconnect();hostSfuRouteRef.current = null;sfuStandbyPrewarmerRef.current?.dispose();@@ -301,6 +324,13 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {setRelayAvailable(false);setMaxViewers(null);setPeerSnapshots(new Map());+ viewerQualityEvidenceTimersRef.current.forEach((timer) =>+ window.clearTimeout(timer),+ );+ viewerQualityEvidenceTimersRef.current.clear();+ viewerQualityEvidenceRef.current = new Map();+ setViewerQualityEvidence(new Map());+ activeRouteRevisionRef.current = 0;setSignalStatus("offline");setSwitchingSource(false);setChangingQuality(false);@@ -327,6 +357,13 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {}function updatePeerSnapshot(snapshot: PeerSnapshot): void {+ const evidence = viewerQualityEvidenceRef.current.get(snapshot.peerId);+ if (+ evidence &&+ evidence.guard.connectionId !== snapshot.connectionId+ ) {+ clearViewerQualityEvidence(snapshot.peerId);+ }setPeerSnapshots((current) => {const next = new Map(current);next.set(snapshot.peerId, snapshot);@@ -334,6 +371,59 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {});}+ function clearViewerQualityEvidence(peerId: string): void {+ const timer = viewerQualityEvidenceTimersRef.current.get(peerId);+ if (timer !== undefined) {+ window.clearTimeout(timer);+ viewerQualityEvidenceTimersRef.current.delete(peerId);+ }+ if (!viewerQualityEvidenceRef.current.has(peerId)) {+ return;+ }+ const next = new Map(viewerQualityEvidenceRef.current);+ next.delete(peerId);+ viewerQualityEvidenceRef.current = next;+ setViewerQualityEvidence(next);+ }++ function clearAllViewerQualityEvidence(): void {+ viewerQualityEvidenceTimersRef.current.forEach((timer) =>+ window.clearTimeout(timer),+ );+ viewerQualityEvidenceTimersRef.current.clear();+ viewerQualityEvidenceRef.current = new Map();+ setViewerQualityEvidence(new Map());+ }++ function acceptViewerQualityEvidence(evidence: ViewerQualityEvidence): void {+ const peer = peersRef.current.get(evidence.viewerPeerId);+ if (+ !peer ||+ peer.connectionId !== evidence.guard.connectionId ||+ evidence.guard.routeRevision !== activeRouteRevisionRef.current+ ) {+ return;+ }+ const next = new Map(viewerQualityEvidenceRef.current);+ next.set(evidence.viewerPeerId, evidence);+ viewerQualityEvidenceRef.current = next;+ setViewerQualityEvidence(next);+ const previousTimer = viewerQualityEvidenceTimersRef.current.get(+ evidence.viewerPeerId,+ );+ if (previousTimer !== undefined) {+ window.clearTimeout(previousTimer);+ }+ const timer = window.setTimeout(() => {+ if (+ viewerQualityEvidenceRef.current.get(evidence.viewerPeerId) === evidence+ ) {+ clearViewerQualityEvidence(evidence.viewerPeerId);+ }+ }, VIEWER_QUALITY_EVIDENCE_EXPIRY_MS);+ viewerQualityEvidenceTimersRef.current.set(evidence.viewerPeerId, timer);+ }+function watchCaptureEnd(captured: MediaStream,generation: number,@@ -471,6 +561,7 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {}function removePeer(peerId: string): void {+ clearViewerQualityEvidence(peerId);peersRef.current.get(peerId)?.dispose();peersRef.current.delete(peerId);setPeerSnapshots((current) => {@@ -625,6 +716,7 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {return;}if (message.type === "authenticated" && message.role === "host") {+ clearAllViewerQualityEvidence();setSfuStandbyUrl("sfuStandbyUrl" in message ? message.sfuStandbyUrl : null,);@@ -633,6 +725,7 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {"mediaMode" in message &&message.mediaMode === "peer-assisted") {+ activeRouteRevisionRef.current = message.routeRevision;peerAssistedRef.current = true;signalRef.current?.send({type: "set-quality-settings",@@ -648,6 +741,7 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {.then(() => showHostSfuQualityWarning(route, generation));return;}+ activeRouteRevisionRef.current = 0;peerAssistedRef.current = false;clearHostSfuRoute();const currentViewerIds = new Set(message.viewerPeerIds);@@ -660,6 +754,13 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {}if (message.type === "route-update") {if (peerAssistedRef.current) {+ if (+ message.phase === "active" &&+ message.revision !== activeRouteRevisionRef.current+ ) {+ activeRouteRevisionRef.current = message.revision;+ clearAllViewerQualityEvidence();+ }const route = ensureHostSfuRoute(generation);void route.acceptAndWait(message)@@ -667,6 +768,10 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {}return;}+ if (message.type === "viewer-quality-evidence") {+ acceptViewerQualityEvidence(message);+ return;+ }if (message.type === "sfu-config") {if (peerAssistedRef.current) {const route = ensureHostSfuRoute(generation);@@ -1432,11 +1537,24 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {)}</div>{showConnectionDetails && (- <StatsGrid- metrics={viewer.metrics}- direction="send"- senderParameters={viewer.senderParameters}- />+ <>+ <StatsGrid+ metrics={viewer.metrics}+ direction="send"+ senderParameters={viewer.senderParameters}+ />+ {viewerQualityEvidence.get(viewer.peerId) && (+ <>+ <p className="section-meta">观看端接收</p>+ <StatsGrid+ metrics={metricsFromQualityEvidence(+ viewerQualityEvidence.get(viewer.peerId)!,+ )}+ direction="receive"+ />+ </>+ )}+ </>)}{viewer.error && <p className="inline-error">{viewer.error}</p>}</article>diff --git a/src/client/pages/ViewerPage.tsx b/src/client/pages/ViewerPage.tsxindex 7b9f1d4d..d6d5e87f 100644--- a/src/client/pages/ViewerPage.tsx+++ b/src/client/pages/ViewerPage.tsx@@ -9,6 +9,7 @@ import {import { useEffect, useMemo, useRef, useState } from "react";import {DEFAULT_QUALITY_SETTINGS,+ VIEWER_QUALITY_EVIDENCE_EXPIRY_MS,type IceConfig,type MediaAssignment,type ServerMessage,@@ -28,6 +29,11 @@ import { SignalingClient } from "../lib/signaling";import type { QualitySettings } from "../media/quality";import { relayCapacityMessageForBrowser } from "../media/relay-capability";import { SfuStandbyPrewarmer } from "../media/sfu-standby-prewarmer";+import {+ metricsFromQualityEvidence,+ qualityEvidenceMatchesSnapshot,+ ViewerQualityEvidenceReporter,+} from "../media/viewer-quality-evidence";import { ViewerMessageAuthority } from "../media/viewer-message-authority";import { ViewerSfuRoute } from "../media/viewer-sfu-route";import type {@@ -48,6 +54,11 @@ interface ViewerPageProps {onAuthorizationRequired: () => void;}+type ViewerQualityEvidence = Extract<+ ServerMessage,+ { type: "viewer-quality-evidence" }+>;+export function ViewerPage({ roomId, onAuthorizationRequired }: ViewerPageProps) {const forceRelay = useMemo(() => new URLSearchParams(window.location.search).get("relay") === "1",@@ -61,6 +72,8 @@ export function ViewerPage({ roomId, onAuthorizationRequired }: ViewerPageProps)const [remoteStream, setRemoteStream] = useState<MediaStream | null>(null);const [peerSnapshot, setPeerSnapshot] = useState<PeerSnapshot | null>(null);const [relaySnapshot, setRelaySnapshot] = useState<PeerSnapshot | null>(null);+ const [relayChildEvidence, setRelayChildEvidence] =+ useState<ViewerQualityEvidence | null>(null);const [playbackBlocked, setPlaybackBlocked] = useState(false);const [muted, setMuted] = useState(false);const [showConnectionDetails, setShowConnectionDetails] = useState(false);@@ -83,6 +96,8 @@ export function ViewerPage({ roomId, onAuthorizationRequired }: ViewerPageProps)let currentIceConfig: IceConfig | null = null;let currentHostOnline = false;let peerAssisted = false;+ let currentPeerId: string | null = null;+ let currentRouteRevision = 0;let currentQualitySettings: QualitySettings = DEFAULT_QUALITY_SETTINGS;let currentAssignment: MediaAssignment = {parentPeerId: null,@@ -96,6 +111,8 @@ export function ViewerPage({ roomId, onAuthorizationRequired }: ViewerPageProps)> = [];const messageAuthority = new ViewerMessageAuthority();let sfuStandbyPrewarmer: SfuStandbyPrewarmer | null = null;+ let relayChildEvidenceCurrent: ViewerQualityEvidence | null = null;+ let relayChildEvidenceTimer: number | null = null;function setSfuStandbyUrl(url: string | null | undefined): void {if (!url) {@@ -150,6 +167,37 @@ export function ViewerPage({ roomId, onAuthorizationRequired }: ViewerPageProps)},},);+ const qualityEvidenceReporter = new ViewerQualityEvidenceReporter(+ (message) => active && signal.send(message),+ );++ function clearRelayChildEvidence(): void {+ relayChildEvidenceCurrent = null;+ setRelayChildEvidence(null);+ if (relayChildEvidenceTimer !== null) {+ window.clearTimeout(relayChildEvidenceTimer);+ relayChildEvidenceTimer = null;+ }+ }++ function acceptRelayChildEvidence(evidence: ViewerQualityEvidence): void {+ if (+ !peerAssisted ||+ evidence.parentPeerId !== currentPeerId ||+ evidence.guard.routeRevision !== currentRouteRevision ||+ !qualityEvidenceMatchesSnapshot(evidence, viewerRelay?.getSnapshot() ?? null)+ ) {+ return;+ }+ clearRelayChildEvidence();+ relayChildEvidenceCurrent = evidence;+ setRelayChildEvidence(evidence);+ relayChildEvidenceTimer = window.setTimeout(() => {+ if (relayChildEvidenceCurrent === evidence) {+ clearRelayChildEvidence();+ }+ }, VIEWER_QUALITY_EVIDENCE_EXPIRY_MS);+ }function ensureViewerRelay(): ViewerRelay | null {if (viewerRelay) {@@ -175,6 +223,15 @@ export function ViewerPage({ roomId, onAuthorizationRequired }: ViewerPageProps)onUpdate: (snapshot) => {if (active) {setRelaySnapshot(snapshot);+ if (+ relayChildEvidenceCurrent &&+ !qualityEvidenceMatchesSnapshot(+ relayChildEvidenceCurrent,+ snapshot,+ )+ ) {+ clearRelayChildEvidence();+ }}},},@@ -301,6 +358,7 @@ export function ViewerPage({ roomId, onAuthorizationRequired }: ViewerPageProps)}function clearUpstreamState(): void {+ qualityEvidenceReporter.reset();peerRef.current?.dispose();peerRef.current = null;setRemoteStream(null);@@ -319,12 +377,16 @@ export function ViewerPage({ roomId, onAuthorizationRequired }: ViewerPageProps)MAX_VIEWER_MEDIA_CHILDREN,);const previousParentId = currentAssignment.parentPeerId;+ const previousChildId = currentAssignment.childPeerIds[0] ?? null;currentAssignment = nextAssignment;if (previousParentId !== nextAssignment.parentPeerId) {clearUpstreamState();setStatusText("正在恢复连接");}+ if (previousChildId !== (nextAssignment.childPeerIds[0] ?? null)) {+ clearRelayChildEvidence();+ }ensureViewerRelay()?.setChild(nextAssignment.childPeerIds[0] ?? null);}@@ -362,6 +424,7 @@ export function ViewerPage({ roomId, onAuthorizationRequired }: ViewerPageProps)},onUpdate: (snapshot) => {if (active) {+ qualityEvidenceReporter.offer(snapshot, currentRouteRevision);if (!currentHostOnline &&snapshot.connectionState === "failed"@@ -395,6 +458,8 @@ export function ViewerPage({ roomId, onAuthorizationRequired }: ViewerPageProps)authorityToken: number,): Promise<void> {if (message.type === "authenticated") {+ clearRelayChildEvidence();+ currentPeerId = message.peerId;setSfuStandbyUrl("sfuStandbyUrl" in message ? message.sfuStandbyUrl : null,);@@ -408,6 +473,14 @@ export function ViewerPage({ roomId, onAuthorizationRequired }: ViewerPageProps)currentAssignment = { parentPeerId: null, childPeerIds: [] };}peerAssisted = nextPeerAssisted;+ const nextRouteRevision =+ nextPeerAssisted && "routeRevision" in message+ ? message.routeRevision+ : 0;+ if (nextRouteRevision !== currentRouteRevision) {+ clearRelayChildEvidence();+ }+ currentRouteRevision = nextRouteRevision;const relayCapacity = relayCapacityMessageForBrowser(nextPeerAssisted);if (relayCapacity) {signal.send(relayCapacity);@@ -467,10 +540,20 @@ export function ViewerPage({ roomId, onAuthorizationRequired }: ViewerPageProps)}if (message.type === "route-update") {if (peerAssisted) {+ if (message.phase === "active") {+ if (message.revision !== currentRouteRevision) {+ clearRelayChildEvidence();+ }+ currentRouteRevision = message.revision;+ }ensureViewerSfuRoute().accept(message);}return;}+ if (message.type === "viewer-quality-evidence") {+ acceptRelayChildEvidence(message);+ return;+ }if (message.type === "sfu-config") {if (peerAssisted) {await ensureViewerSfuRoute().acceptConfig(message);@@ -591,6 +674,13 @@ export function ViewerPage({ roomId, onAuthorizationRequired }: ViewerPageProps)signal.start();return () => {active = false;+ currentPeerId = null;+ qualityEvidenceReporter.reset();+ relayChildEvidenceCurrent = null;+ if (relayChildEvidenceTimer !== null) {+ window.clearTimeout(relayChildEvidenceTimer);+ relayChildEvidenceTimer = null;+ }sfuStandbyPrewarmer?.dispose();signal.stop();void viewerSfuRoute?.disconnect();@@ -797,6 +887,18 @@ export function ViewerPage({ roomId, onAuthorizationRequired }: ViewerPageProps)/></section>)}+ {showConnectionDetails && relayChildEvidence && (+ <section+ className="viewer-stats"+ aria-labelledby="relay-child-stats-heading"+ >+ <h2 id="relay-child-stats-heading">下游接收数据</h2>+ <StatsGrid+ metrics={metricsFromQualityEvidence(relayChildEvidence)}+ direction="receive"+ />+ </section>+ )}</main></div>);diff --git a/src/client/types.ts b/src/client/types.tsindex 5ac4efac..2e726780 100644--- a/src/client/types.ts+++ b/src/client/types.ts@@ -26,10 +26,15 @@ export interface ConnectionMetrics {bitrateKbps: number | null;availableOutgoingKbps: number | null;framesPerSecond: number | null;+ frameWidth: number | null;+ frameHeight: number | null;resolution: string | null;packetsLost: number | null;+ intervalPacketsReceived: number | null;+ intervalPacketsLost: number | null;jitterMs: number | null;framesDropped: number | null;+ intervalFramesDecoded: number | null;intervalFramesDropped: number | null;intervalFreezeCount: number | null;intervalFreezeDurationMs: number | null;@@ -77,10 +82,15 @@ export const EMPTY_METRICS: ConnectionMetrics = {bitrateKbps: null,availableOutgoingKbps: null,framesPerSecond: null,+ frameWidth: null,+ frameHeight: null,resolution: null,packetsLost: null,+ intervalPacketsReceived: null,+ intervalPacketsLost: null,jitterMs: null,framesDropped: null,+ intervalFramesDecoded: null,intervalFramesDropped: null,intervalFreezeCount: null,intervalFreezeDurationMs: null,diff --git a/src/client/webrtc/stats.ts b/src/client/webrtc/stats.tsindex 475540e4..95d38c67 100644--- a/src/client/webrtc/stats.ts+++ b/src/client/webrtc/stats.ts@@ -2,6 +2,7 @@ import {EMPTY_METRICS,type ConnectionMetrics,} from "../types";+import { deriveVideoCodecEvidence } from "../../shared/video-codec-evidence";type StatsRecord = Record<string, unknown> & {id: string;@@ -18,6 +19,8 @@ export interface StatsAccumulator {timestamp: number | null;previousTotalEncodeTime: number | null;previousTotalDecodeTime: number | null;+ previousPacketsReceived: number | null;+ previousPacketsLost: number | null;previousFramesDropped: number | null;previousFreezeCount: number | null;previousTotalFreezesDuration: number | null;@@ -39,6 +42,8 @@ export function createStatsAccumulator(): StatsAccumulator {timestamp: null,previousTotalEncodeTime: null,previousTotalDecodeTime: null,+ previousPacketsReceived: null,+ previousPacketsLost: null,previousFramesDropped: null,previousFreezeCount: null,previousTotalFreezesDuration: null,@@ -200,56 +205,6 @@ function linkedRemoteInbound(: null;}-interface CodecEvidence {- codec: string | null;- profile: string | null;- parameters: string | null;-}--type CodecParameterRule = {- profileKey: string | null;- parameterKeys: readonly string[];- validators: Readonly<Record<string, RegExp>>;-};--const CODEC_PARAMETER_RULES: Readonly<Record<string, CodecParameterRule>> = {- "video/h264": {- profileKey: "profile-level-id",- parameterKeys: ["packetization-mode", "level-asymmetry-allowed"],- validators: {- "profile-level-id": /^[0-9a-f]{6}$/i,- "packetization-mode": /^[0-2]$/,- "level-asymmetry-allowed": /^[01]$/,- },- },- "video/vp9": {- profileKey: "profile-id",- parameterKeys: ["max-fr", "max-fs"],- validators: {- "profile-id": /^[0-3]$/,- "max-fr": /^[1-9][0-9]{0,9}$/,- "max-fs": /^[1-9][0-9]{0,9}$/,- },- },- "video/vp8": {- profileKey: null,- parameterKeys: ["max-fr", "max-fs"],- validators: {- "max-fr": /^[1-9][0-9]{0,9}$/,- "max-fs": /^[1-9][0-9]{0,9}$/,- },- },- "video/av1": {- profileKey: "profile",- parameterKeys: ["level-idx", "tier"],- validators: {- profile: /^[0-2]$/,- "level-idx": /^(?:[0-9]|[12][0-9]|3[01])$/,- tier: /^[01]$/,- },- },-};-function linkedVideoCodec(report: RTCStatsReport,media: StatsRecord | null,@@ -266,62 +221,12 @@ function linkedVideoCodec(: null;}-function deriveCodecEvidence(codec: StatsRecord | null): CodecEvidence {+function deriveCodecEvidence(codec: StatsRecord | null) {const mimeType = stringValue(codec, "mimeType");- if (!mimeType) {- return { codec: null, profile: null, parameters: null };- }- const rule = CODEC_PARAMETER_RULES[mimeType.toLowerCase()];- const fmtp = stringValue(codec, "sdpFmtpLine");- if (!rule || !fmtp || fmtp.length > 2_048) {- return { codec: mimeType, profile: null, parameters: null };- }-- const segments = fmtp.split(";");- if (segments.length > 32) {- return { codec: mimeType, profile: null, parameters: null };- }- const values = new Map<string, string>();- const seenKeys = new Set<string>();- for (const segment of segments) {- const separator = segment.indexOf("=");- if (separator < 1) {- continue;- }- const key = segment.slice(0, separator).trim().toLowerCase();- const validator = rule.validators[key];- if (!validator) {- continue;- }- if (seenKeys.has(key)) {- values.delete(key);- continue;- }- seenKeys.add(key);- const value = segment.slice(separator + 1).trim().toLowerCase();- if (!validator.test(value)) {- continue;- }- values.set(key, value);- }-- const profileValue = rule.profileKey- ? values.get(rule.profileKey)- : undefined;- const parameters = rule.parameterKeys- .flatMap((key) => {- const value = values.get(key);- return value ? [`${key}=${value}`] : [];- })- .join("; ");- return {- codec: mimeType,- profile:- rule.profileKey && profileValue- ? `${rule.profileKey}=${profileValue}`- : null,- parameters: parameters || null,- };+ return deriveVideoCodecEvidence(+ mimeType,+ stringValue(codec, "sdpFmtpLine"),+ );}function scalabilityModeValue(media: StatsRecord | null): string | null {@@ -383,6 +288,11 @@ export async function collectConnectionMetrics(const timestamp = numberValue(media, "timestamp");const framesEncoded = numberValue(media, "framesEncoded");const framesDecoded = numberValue(media, "framesDecoded");+ const packetsReceived = numberValue(media, "packetsReceived");+ const packetsLost = numberValue(+ direction === "send" ? remoteInbound : media,+ "packetsLost",+ );const totalEncodeTime = numberValue(media, "totalEncodeTime");const totalDecodeTime = numberValue(media, "totalDecodeTime");const framesDropped = numberValue(media, "framesDropped");@@ -441,6 +351,30 @@ export async function collectConnectionMetrics(sampleWindowMs !== null ? previous.frames : null,): null;+ const intervalPacketsReceived =+ direction === "receive"+ ? intervalDelta(+ packetsReceived,+ previous.previousPacketsReceived,+ sampleWindowMs !== null,+ )+ : null;+ const intervalPacketsLost =+ direction === "receive"+ ? intervalDelta(+ packetsLost,+ previous.previousPacketsLost,+ sampleWindowMs !== null,+ )+ : null;+ const intervalFramesDecoded =+ direction === "receive"+ ? intervalDelta(+ framesDecoded,+ previous.frames,+ sampleWindowMs !== null,+ )+ : null;const intervalFramesDropped = intervalDelta(framesDropped,previous.previousFramesDropped,@@ -474,6 +408,8 @@ export async function collectConnectionMetrics(previous.timestamp = timestamp;previous.previousTotalEncodeTime = totalEncodeTime;previous.previousTotalDecodeTime = totalDecodeTime;+ previous.previousPacketsReceived = packetsReceived;+ previous.previousPacketsLost = packetsLost;previous.previousFramesDropped = framesDropped;previous.previousFreezeCount = freezeCount;previous.previousTotalFreezesDuration = totalFreezesDuration;@@ -481,14 +417,7 @@ export async function collectConnectionMetrics(previous.previousRetransmittedBytes = retransmittedBytes;const linkedCodec = linkedVideoCodec(report, media, transport);- const codecEvidence =- direction === "send"- ? deriveCodecEvidence(linkedCodec)- : {- codec: stringValue(linkedCodec, "mimeType"),- profile: null,- parameters: null,- };+ const codecEvidence = deriveCodecEvidence(linkedCodec);const width = numberValue(media, "frameWidth");const height = numberValue(media, "frameHeight");const iceProtocol =@@ -523,15 +452,19 @@ export async function collectConnectionMetrics(? numberValue(pair, "availableOutgoingBitrate")! / 1_000: null,framesPerSecond: numberValue(media, "framesPerSecond") ?? derivedFps,+ frameWidth: width,+ frameHeight: height,resolution: width !== null && height !== null ? `${width}x${height}` : null,- packetsLost:- numberValue(direction === "send" ? remoteInbound : media, "packetsLost"),+ packetsLost,+ intervalPacketsReceived,+ intervalPacketsLost,jitterMs:numberValue(direction === "send" ? remoteInbound : media, "jitter") !== null? numberValue(direction === "send" ? remoteInbound : media, "jitter")! *1_000: null,framesDropped,+ intervalFramesDecoded,intervalFramesDropped,intervalFreezeCount,intervalFreezeDurationMs:diff --git a/src/server/hybrid-media-router.ts b/src/server/hybrid-media-router.tsindex e6fe6521..941c4bf6 100644--- a/src/server/hybrid-media-router.ts+++ b/src/server/hybrid-media-router.ts@@ -207,17 +207,35 @@ export class HybridMediaRouter {parentPeerId: string,childPeerId: string,): boolean {+ return (+ this.resolveActivePeerEdge(roomId, childPeerId)?.parentPeerId ===+ parentPeerId+ );+ }++ resolveActivePeerEdge(+ roomId: string,+ childPeerId: string,+ ): { revision: number; parentPeerId: string } | undefined {const controller = this.mediaRouteControllers.get(roomId);if (!controller) {- return false;+ return undefined;}- const assignments = controller.getActiveRoute().assignments;+ const active = controller.getActiveRoute();+ const assignments = active.assignments;const child = assignments.get(childPeerId);- return (- child?.upstream.kind === "peer" &&- child.upstream.peerId === parentPeerId &&- assignments.get(parentPeerId)?.childPeerIds.includes(childPeerId) === true- );+ if (+ child?.upstream.kind !== "peer" ||+ assignments+ .get(child.upstream.peerId)+ ?.childPeerIds.includes(childPeerId) !== true+ ) {+ return undefined;+ }+ return {+ revision: active.revision,+ parentPeerId: child.upstream.peerId,+ };}setViewerRelayCapacity(diff --git a/src/server/signaling.ts b/src/server/signaling.tsindex 41edf99b..ef84c999 100644--- a/src/server/signaling.ts+++ b/src/server/signaling.ts@@ -7,13 +7,19 @@ import WebSocket, { WebSocketServer } from "ws";import {DEFAULT_QUALITY_SETTINGS,MAX_SIGNAL_BYTES,+ MAX_VIEWER_QUALITY_EVIDENCE_BYTES,+ VIEWER_QUALITY_EVIDENCE_INTERVAL_MS,decodeClientMessage,type ClientMessage,type QualitySettings,type Role,type ServerMessage,} from "../shared/protocol.js";-import { RoomStore, RoomStoreError } from "./room-store.js";+import {+ RoomStore,+ RoomStoreError,+ type ConnectedPeer,+} from "./room-store.js";import {HybridMediaRouter,type SfuFallbackOptions,@@ -41,6 +47,16 @@ interface SocketState {authenticated?: AuthenticatedSession;}+interface ViewerQualityEvidenceGate {+ viewerSessionId: string;+ parentSessionId: string;+ parentPeerId: string;+ connectionId: string;+ routeRevision: number;+ sequence: number;+ acceptedAtMs: number;+}+export interface SignalingOptions {server: HttpServer;roomStore: RoomStore;@@ -70,6 +86,10 @@ export class SignalingServer {private readonly socketsBySessionId = new Map<string, WebSocket>();private readonly viewerGraceTimers = new Map<string, NodeJS.Timeout>();private readonly connectionIdsByViewer = new Map<string, string>();+ private readonly viewerQualityEvidenceGates = new Map<+ string,+ ViewerQualityEvidenceGate+ >();private readonly qualitySettingsByRoom = new Map<string, QualitySettings>();private readonly shareGenerationsByRoom = new Map<string, string>();private readonly hybridMediaRouter?: HybridMediaRouter;@@ -122,9 +142,7 @@ export class SignalingServer {viewerConnectionKey(roomId, viewerPeerId),),deleteConnectionId: (roomId, viewerPeerId) =>- this.connectionIdsByViewer.delete(- viewerConnectionKey(roomId, viewerPeerId),- ),+ this.deleteViewerConnectionId(roomId, viewerPeerId),});}@@ -185,6 +203,7 @@ export class SignalingServer {}this.viewerGraceTimers.clear();this.hybridMediaRouter?.close();+ this.viewerQualityEvidenceGates.clear();this.shareGenerationsByRoom.clear();this.options.server.off("upgrade", this.upgradeHandler);@@ -242,6 +261,13 @@ export class SignalingServer {this.rejectInvalidMessage(socket);return;}+ if (+ message.type === "viewer-quality-evidence" &&+ Buffer.byteLength(encoded, "utf8") > MAX_VIEWER_QUALITY_EVIDENCE_BYTES+ ) {+ this.rejectInvalidMessage(socket);+ return;+ }const state = this.socketStates.get(socket);if (!state) {@@ -339,6 +365,11 @@ export class SignalingServer {: Date.parse(participant.expiresAt),shareGeneration,};+ if (participant.role === "viewer") {+ this.viewerQualityEvidenceGates.delete(+ viewerConnectionKey(participant.roomId, participant.peerId),+ );+ }this.clearViewerGrace(participant.roomId, participant.peerId);const routeParticipant = {roomId: participant.roomId,@@ -570,6 +601,9 @@ export class SignalingServer {message.revision,);return;+ case "viewer-quality-evidence":+ this.handleViewerQualityEvidence(socket, authenticated, message);+ return;case "stop-sharing":case "close-room":if (authenticated.role !== "host") {@@ -613,6 +647,98 @@ export class SignalingServer {}}+ private handleViewerQualityEvidence(+ socket: WebSocket,+ source: AuthenticatedSession,+ message: Extract<ClientMessage, { type: "viewer-quality-evidence" }>,+ ): void {+ if (source.role !== "viewer") {+ return;+ }+ const viewerState = this.socketStates.get(socket);+ if (!viewerState || viewerState.authenticated !== source) {+ return;+ }++ const connectionId = this.connectionIdsByViewer.get(+ viewerConnectionKey(source.roomId, source.peerId),+ );+ if (!connectionId || message.guard.connectionId !== connectionId) {+ return;+ }++ let routeRevision = 0;+ let parent: ConnectedPeer | undefined;+ if (this.isPeerAssistedRoom(source.roomId)) {+ const edge = this.hybridMediaRouter?.resolveActivePeerEdge(+ source.roomId,+ source.peerId,+ );+ if (!edge) {+ return;+ }+ routeRevision = edge.revision;+ parent = this.connectedPeer(source.roomId, edge.parentPeerId);+ } else {+ parent = this.options.roomStore.getConnectedHost(source.roomId);+ }+ if (+ !parent ||+ message.guard.routeRevision !== routeRevision ||+ parent.peerId === source.peerId+ ) {+ return;+ }++ const gateKey = viewerConnectionKey(source.roomId, source.peerId);+ const previous = this.viewerQualityEvidenceGates.get(gateKey);+ const sameGeneration =+ previous?.viewerSessionId === viewerState.sessionId &&+ previous.parentSessionId === parent.sessionId &&+ previous.parentPeerId === parent.peerId &&+ previous.connectionId === connectionId &&+ previous.routeRevision === routeRevision;+ const now = this.now();+ if (+ sameGeneration &&+ previous &&+ (message.sequence <= previous.sequence ||+ now - previous.acceptedAtMs < VIEWER_QUALITY_EVIDENCE_INTERVAL_MS)+ ) {+ return;+ }++ const forwarded = {+ type: "viewer-quality-evidence" as const,+ viewerPeerId: source.peerId,+ parentPeerId: parent.peerId,+ guard: {+ connectionId,+ routeRevision,+ },+ sequence: message.sequence,+ windowMs: message.windowMs,+ metrics: message.metrics,+ };+ const encoded = JSON.stringify(forwarded);+ if (+ Buffer.byteLength(encoded, "utf8") >+ MAX_VIEWER_QUALITY_EVIDENCE_BYTES ||+ !this.sendEncodedToSession(parent.sessionId, encoded)+ ) {+ return;+ }+ this.viewerQualityEvidenceGates.set(gateKey, {+ viewerSessionId: viewerState.sessionId,+ parentSessionId: parent.sessionId,+ parentPeerId: parent.peerId,+ connectionId,+ routeRevision,+ sequence: message.sequence,+ acceptedAtMs: now,+ });+ }+private routeSignal(sourceSocket: WebSocket,source: AuthenticatedSession,@@ -640,8 +766,9 @@ export class SignalingServer {return;}if (description?.type === "offer") {- this.connectionIdsByViewer.set(- viewerConnectionKey(source.roomId, viewer.peerId),+ this.setViewerConnectionId(+ source.roomId,+ viewer.peerId,message.payload.connectionId,);}@@ -713,8 +840,9 @@ export class SignalingServer {}if (description?.type === "offer") {- this.connectionIdsByViewer.set(- viewerConnectionKey(source.roomId, targetPeerId),+ this.setViewerConnectionId(+ source.roomId,+ targetPeerId,message.payload.connectionId,);}@@ -819,8 +947,9 @@ export class SignalingServer {disconnected.peerId,)) {- this.connectionIdsByViewer.delete(- viewerConnectionKey(disconnected.roomId, disconnected.peerId),+ this.deleteViewerConnectionId(+ disconnected.roomId,+ disconnected.peerId,);if (this.isPeerAssistedRoom(disconnected.roomId)) {this.hybridMediaRouter!.removeViewer(@@ -977,6 +1106,19 @@ export class SignalingServer {}}+ private sendEncodedToSession(sessionId: string, encoded: string): boolean {+ const socket = this.socketsBySessionId.get(sessionId);+ if (!socket || socket.readyState !== WebSocket.OPEN) {+ return false;+ }+ if (socket.bufferedAmount > MAX_BUFFERED_SIGNAL_BYTES) {+ socket.terminate();+ return false;+ }+ socket.send(encoded);+ return true;+ }+private send(socket: WebSocket, message: ServerMessage): void {if (socket.readyState !== WebSocket.OPEN) {return;@@ -1023,6 +1165,32 @@ export class SignalingServer {this.connectionIdsByViewer.delete(key);}}+ for (const key of this.viewerQualityEvidenceGates.keys()) {+ if (key.startsWith(prefix)) {+ this.viewerQualityEvidenceGates.delete(key);+ }+ }+ }++ private setViewerConnectionId(+ roomId: string,+ viewerPeerId: string,+ connectionId: string,+ ): void {+ const key = viewerConnectionKey(roomId, viewerPeerId);+ if (this.connectionIdsByViewer.get(key) !== connectionId) {+ this.viewerQualityEvidenceGates.delete(key);+ }+ this.connectionIdsByViewer.set(key, connectionId);+ }++ private deleteViewerConnectionId(+ roomId: string,+ viewerPeerId: string,+ ): void {+ const key = viewerConnectionKey(roomId, viewerPeerId);+ this.connectionIdsByViewer.delete(key);+ this.viewerQualityEvidenceGates.delete(key);}}diff --git a/src/shared/protocol.ts b/src/shared/protocol.tsindex 1c9db32a..15c94ff9 100644--- a/src/shared/protocol.ts+++ b/src/shared/protocol.ts@@ -1,10 +1,15 @@import { z } from "zod";+import { isCanonicalVideoCodecEvidence } from "./video-codec-evidence.js";+export const MAX_VIEWERS_PER_ROOM_LIMIT = 16;export const MAX_SIGNAL_BYTES = 64 * 1024;export const ROOM_CODE_LENGTH = 12;export const MAX_MEDIA_ROUTE_REVISION = Number.MAX_SAFE_INTEGER;export const MAX_SFU_TOKEN_LENGTH = 8 * 1024;+export const MAX_VIEWER_QUALITY_EVIDENCE_BYTES = 2 * 1024;+export const VIEWER_QUALITY_EVIDENCE_INTERVAL_MS = 2_000;+export const VIEWER_QUALITY_EVIDENCE_EXPIRY_MS = 5_000;const opaqueIdSchema = z.string()@@ -181,6 +186,94 @@ export type ParticipantRouteAssignment = z.infer<typeof participantRouteAssignmentSchema>;+const nullableEvidenceNumber = (maximum: number) =>+ z.number().finite().min(0).max(maximum).nullable();++const nullableEvidenceInteger = (maximum: number) =>+ z.number().int().min(0).max(maximum).nullable();++export const viewerQualityEvidenceMetricsSchema = z+ .object({+ width: z.number().int().min(1).max(16_384).nullable(),+ height: z.number().int().min(1).max(16_384).nullable(),+ framesPerSecond: nullableEvidenceNumber(240),+ bitrateKbps: nullableEvidenceNumber(100_000),+ packetsReceivedDelta: nullableEvidenceInteger(1_000_000),+ packetsLostDelta: nullableEvidenceInteger(1_000_000),+ jitterMs: nullableEvidenceNumber(60_000),+ framesDecodedDelta: nullableEvidenceInteger(10_000),+ framesDroppedDelta: nullableEvidenceInteger(10_000),+ decodeMsPerFrame: nullableEvidenceNumber(60_000),+ freezeCountDelta: nullableEvidenceInteger(10_000),+ freezeDurationMsDelta: nullableEvidenceNumber(5_000),+ codec: z+ .string()+ .max(64)+ .regex(/^video\/[A-Za-z0-9.+-]{1,32}$/i)+ .nullable(),+ codecProfile: z+ .string()+ .max(64)+ .regex(/^[a-z0-9-]+=[a-z0-9]+$/)+ .nullable(),+ codecParameters: z+ .string()+ .max(128)+ .regex(/^[a-z0-9-]+=[a-z0-9]+(?:; [a-z0-9-]+=[a-z0-9]+)*$/)+ .nullable(),+ })+ .strict()+ .refine(+ (metrics) =>+ (metrics.width === null && metrics.height === null) ||+ (metrics.width !== null && metrics.height !== null),+ { message: "Viewer quality dimensions must be present together" },+ )+ .refine(isCanonicalVideoCodecEvidence, {+ message: "Viewer codec evidence is not canonical",+ path: ["codecParameters"],+ });+export type ViewerQualityEvidenceMetrics = z.infer<+ typeof viewerQualityEvidenceMetricsSchema+>;++const viewerQualityEvidenceGuardSchema = z+ .object({+ connectionId: opaqueIdSchema,+ routeRevision: mediaRouteRevisionSchema,+ })+ .strict();++const viewerQualityEvidenceWindowShape = {+ sequence: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),+ windowMs: z.number().int().min(1_000).max(5_000),+ metrics: viewerQualityEvidenceMetricsSchema,+};++function freezeFitsEvidenceWindow(value: {+ windowMs: number;+ metrics: ViewerQualityEvidenceMetrics;+}): boolean {+ return (+ value.metrics.freezeDurationMsDelta === null ||+ value.metrics.freezeDurationMsDelta <= value.windowMs+ );+}++export const viewerQualityEvidenceMessageSchema = z+ .object({+ type: z.literal("viewer-quality-evidence"),+ guard: viewerQualityEvidenceGuardSchema,+ ...viewerQualityEvidenceWindowShape,+ })+ .strict()+ .refine(freezeFitsEvidenceWindow, {+ message: "Viewer freeze duration exceeds its evidence window",+ });+export type ViewerQualityEvidenceMessage = z.infer<+ typeof viewerQualityEvidenceMessageSchema+>;+const authenticateMessageSchema = z.discriminatedUnion("role", [z.object({@@ -253,6 +346,7 @@ export const clientMessageSchema = z.union([revision: mediaRouteRevisionSchema,}).strict(),+ viewerQualityEvidenceMessageSchema,z.object({type: z.literal("stop-sharing"),@@ -361,6 +455,18 @@ export const serverMessageSchema = z.union([qualitySettings: qualitySettingsSchema,}).strict(),+ z+ .object({+ type: z.literal("viewer-quality-evidence"),+ viewerPeerId: opaqueIdSchema,+ parentPeerId: opaqueIdSchema,+ guard: viewerQualityEvidenceGuardSchema,+ ...viewerQualityEvidenceWindowShape,+ })+ .strict()+ .refine(freezeFitsEvidenceWindow, {+ message: "Viewer freeze duration exceeds its evidence window",+ }),z.object({type: z.literal("ice-config"),diff --git a/src/shared/video-codec-evidence.ts b/src/shared/video-codec-evidence.tsnew file mode 100644index 00000000..81b596e3--- /dev/null+++ b/src/shared/video-codec-evidence.ts@@ -0,0 +1,166 @@+export interface VideoCodecEvidence {+ codec: string | null;+ profile: string | null;+ parameters: string | null;+}++interface CodecParameterRule {+ profileKey: string | null;+ parameterKeys: readonly string[];+ validators: Readonly<Record<string, RegExp>>;+}++const VIDEO_CODEC_PARAMETER_RULES: Readonly<+ Record<string, CodecParameterRule>+> = {+ "video/h264": {+ profileKey: "profile-level-id",+ parameterKeys: ["packetization-mode", "level-asymmetry-allowed"],+ validators: {+ "profile-level-id": /^[0-9a-f]{6}$/,+ "packetization-mode": /^[0-2]$/,+ "level-asymmetry-allowed": /^[01]$/,+ },+ },+ "video/vp9": {+ profileKey: "profile-id",+ parameterKeys: ["max-fr", "max-fs"],+ validators: {+ "profile-id": /^[0-3]$/,+ "max-fr": /^[1-9][0-9]{0,9}$/,+ "max-fs": /^[1-9][0-9]{0,9}$/,+ },+ },+ "video/vp8": {+ profileKey: null,+ parameterKeys: ["max-fr", "max-fs"],+ validators: {+ "max-fr": /^[1-9][0-9]{0,9}$/,+ "max-fs": /^[1-9][0-9]{0,9}$/,+ },+ },+ "video/av1": {+ profileKey: "profile",+ parameterKeys: ["level-idx", "tier"],+ validators: {+ profile: /^[0-2]$/,+ "level-idx": /^(?:[0-9]|[12][0-9]|3[01])$/,+ tier: /^[01]$/,+ },+ },+};++const VIDEO_MIME_TYPE = /^video\/[A-Za-z0-9.+-]{1,32}$/i;++export function deriveVideoCodecEvidence(+ codec: string | null,+ rawParameters: string | null,+): VideoCodecEvidence {+ if (!codec || !VIDEO_MIME_TYPE.test(codec)) {+ return { codec: null, profile: null, parameters: null };+ }+ const rule = VIDEO_CODEC_PARAMETER_RULES[codec.toLowerCase()];+ if (!rule || !rawParameters || rawParameters.length > 2_048) {+ return { codec, profile: null, parameters: null };+ }++ const segments = rawParameters.split(";");+ if (segments.length > 32) {+ return { codec, profile: null, parameters: null };+ }+ const values = new Map<string, string>();+ const seenKeys = new Set<string>();+ for (const segment of segments) {+ const separator = segment.indexOf("=");+ if (separator < 1) {+ continue;+ }+ const key = segment.slice(0, separator).trim().toLowerCase();+ const validator = rule.validators[key];+ if (!validator) {+ continue;+ }+ if (seenKeys.has(key)) {+ values.delete(key);+ continue;+ }+ seenKeys.add(key);+ const value = segment.slice(separator + 1).trim().toLowerCase();+ if (validator.test(value)) {+ values.set(key, value);+ }+ }++ const profileValue = rule.profileKey+ ? values.get(rule.profileKey)+ : undefined;+ const parameters = rule.parameterKeys+ .flatMap((key) => {+ const value = values.get(key);+ return value ? [`${key}=${value}`] : [];+ })+ .join("; ");+ return {+ codec,+ profile:+ rule.profileKey && profileValue+ ? `${rule.profileKey}=${profileValue}`+ : null,+ parameters: parameters || null,+ };+}++export function isCanonicalVideoCodecEvidence(value: {+ codec: string | null;+ codecProfile: string | null;+ codecParameters: string | null;+}): boolean {+ const rule = value.codec+ ? VIDEO_CODEC_PARAMETER_RULES[value.codec.toLowerCase()]+ : undefined;+ if (!rule) {+ return value.codecProfile === null && value.codecParameters === null;+ }+ return (+ canonicalValuesMatch(+ value.codecProfile,+ rule.profileKey ? [rule.profileKey] : [],+ rule.validators,+ ) &&+ canonicalValuesMatch(+ value.codecParameters,+ rule.parameterKeys,+ rule.validators,+ )+ );+}++function canonicalValuesMatch(+ encoded: string | null,+ orderedKeys: readonly string[],+ validators: Readonly<Record<string, RegExp>>,+): boolean {+ if (encoded === null) {+ return true;+ }+ const segments = encoded.split("; ");+ if (segments.length > orderedKeys.length) {+ return false;+ }+ let previousKeyIndex = -1;+ for (const segment of segments) {+ const separator = segment.indexOf("=");+ const key = separator < 1 ? "" : segment.slice(0, separator);+ const keyIndex = orderedKeys.indexOf(key);+ const candidate = separator < 1 ? "" : segment.slice(separator + 1);+ if (+ keyIndex <= previousKeyIndex ||+ keyIndex < 0 ||+ !validators[key]?.test(candidate)+ ) {+ return false;+ }+ previousKeyIndex = keyIndex;+ }+ return true;+}diff --git a/tests/client-state.test.ts b/tests/client-state.test.tsindex f5333cc9..d6a09633 100644--- a/tests/client-state.test.ts+++ b/tests/client-state.test.ts@@ -17,6 +17,7 @@ import {shouldReconnectSignaling,SignalingClient,} from "../src/client/lib/signaling.ts";+import { qualityEvidenceWindowFromMetrics } from "../src/client/media/viewer-quality-evidence.ts";import { createStatsAccumulator, collectConnectionMetrics } from "../src/client/webrtc/stats.ts";afterEach(() => {@@ -574,18 +575,27 @@ describe("WebRTC stats parsing", () => {getStats: async () => report,} as unknown as RTCPeerConnection;- await expect(- collectConnectionMetrics(- connection,- "send",- createStatsAccumulator(),- ),- ).resolves.toMatchObject({+ const metrics = await collectConnectionMetrics(+ connection,+ "send",+ createStatsAccumulator(),+ );+ expect(metrics).toMatchObject({codec: mimeType,codecProfile: profile,codecParameters: parameters,scalabilityMode: null,});+ expect(+ qualityEvidenceWindowFromMetrics({+ ...metrics,+ sampleWindowMs: 2_000,+ })?.metrics,+ ).toMatchObject({+ codec: mimeType,+ codecProfile: profile,+ codecParameters: parameters,+ });},);@@ -996,4 +1006,93 @@ describe("WebRTC stats parsing", () => {intervalRetransmittedBytes: 800,});});++ it("derives a bounded inbound C window from adjacent RTP counters", async () => {+ const inbound = (+ timestamp: number,+ packetsReceived: number,+ packetsLost: number,+ framesDecoded: number,+ totalDecodeTime: number,+ ) =>+ new Map<string, unknown>([+ [+ "transport",+ { id: "transport", type: "transport", timestamp },+ ],+ [+ "codec",+ {+ id: "codec",+ type: "codec",+ timestamp,+ transportId: "transport",+ mimeType: "video/H264",+ sdpFmtpLine:+ "profile-level-id=42e01f; packetization-mode=1; " ++ "sprop-parameter-sets=must-not-leave-stats",+ },+ ],+ [+ "inbound",+ {+ id: "inbound",+ type: "inbound-rtp",+ timestamp,+ kind: "video",+ ssrc: 101,+ transportId: "transport",+ codecId: "codec",+ bytesReceived: timestamp * 10,+ packetsReceived,+ packetsLost,+ framesDecoded,+ framesDropped: 3,+ freezeCount: 1,+ totalFreezesDuration: 0.25,+ totalDecodeTime,+ frameWidth: 1_920,+ frameHeight: 1_080,+ scalabilityMode: "L3T3_KEY",+ },+ ],+ ]) as unknown as RTCStatsReport;+ const reports = [+ inbound(1_000, 1_000, 10, 60, 0.12),+ inbound(3_000, 2_500, 12, 180, 0.42),+ inbound(5_000, 4_000, 11, 300, 0.72),+ ];+ const connection = {+ getStats: async () => reports.shift()!,+ } as unknown as RTCPeerConnection;+ const accumulator = createStatsAccumulator();++ await collectConnectionMetrics(connection, "receive", accumulator);+ const stable = await collectConnectionMetrics(+ connection,+ "receive",+ accumulator,+ );+ const correctedLoss = await collectConnectionMetrics(+ connection,+ "receive",+ accumulator,+ );++ expect(stable).toMatchObject({+ sampleWindowMs: 2_000,+ frameWidth: 1_920,+ frameHeight: 1_080,+ intervalPacketsReceived: 1_500,+ intervalPacketsLost: 2,+ intervalFramesDecoded: 120,+ intervalDecodeMs: 2.5,+ codec: "video/H264",+ codecProfile: "profile-level-id=42e01f",+ codecParameters: "packetization-mode=1",+ scalabilityMode: null,+ });+ expect(JSON.stringify(stable)).not.toContain("sprop-parameter-sets");+ expect(correctedLoss.intervalPacketsLost).toBeNull();+ });});diff --git a/tests/protocol.test.ts b/tests/protocol.test.tsindex 15845e79..e262ba23 100644--- a/tests/protocol.test.ts+++ b/tests/protocol.test.ts@@ -3,6 +3,7 @@ import { describe, expect, it } from "vitest";import {MAX_MEDIA_ROUTE_REVISION,MAX_SFU_TOKEN_LENGTH,+ MAX_VIEWER_QUALITY_EVIDENCE_BYTES,MAX_VIEWERS_PER_ROOM_LIMIT,clientMessageSchema,decodeClientMessage,@@ -19,6 +20,34 @@ const qualitySettings = {degradationPreference: "maintain-resolution",} as const;+const qualityEvidence = {+ type: "viewer-quality-evidence",+ guard: {+ connectionId: "connection_12345678",+ routeRevision: 0,+ },+ sequence: 0,+ windowMs: 2_000,+ metrics: {+ width: 1_920,+ height: 1_080,+ framesPerSecond: 59.8,+ bitrateKbps: 7_500,+ packetsReceivedDelta: 1_500,+ packetsLostDelta: 2,+ jitterMs: 3.5,+ framesDecodedDelta: 120,+ framesDroppedDelta: 1,+ decodeMsPerFrame: 2.4,+ freezeCountDelta: 0,+ freezeDurationMsDelta: 0,+ codec: "video/H264",+ codecProfile: "profile-level-id=42e01f",+ codecParameters:+ "packetization-mode=1; level-asymmetry-allowed=1",+ },+} as const;+describe("client signaling protocol", () => {it("accepts a bounded authentication message", () => {expect(@@ -220,6 +249,87 @@ describe("client signaling protocol", () => {).toBe(false);});+ it("accepts only strict, bounded viewer quality evidence", () => {+ expect(clientMessageSchema.safeParse(qualityEvidence).success).toBe(true);+ expect(+ Buffer.byteLength(JSON.stringify(qualityEvidence), "utf8"),+ ).toBeLessThanOrEqual(MAX_VIEWER_QUALITY_EVIDENCE_BYTES);++ for (const invalid of [+ { ...qualityEvidence, roomId },+ {+ ...qualityEvidence,+ guard: { ...qualityEvidence.guard, peerId: "viewer_12345678" },+ },+ { ...qualityEvidence, windowMs: 999 },+ { ...qualityEvidence, sequence: -1 },+ {+ ...qualityEvidence,+ metrics: { ...qualityEvidence.metrics, width: null },+ },+ {+ ...qualityEvidence,+ metrics: { ...qualityEvidence.metrics, bitrateKbps: Number.POSITIVE_INFINITY },+ },+ {+ ...qualityEvidence,+ metrics: { ...qualityEvidence.metrics, freezeDurationMsDelta: 2_001 },+ },+ {+ ...qualityEvidence,+ metrics: {+ ...qualityEvidence.metrics,+ codecParameters: "sprop-parameter-sets=deadbeef",+ },+ },+ {+ ...qualityEvidence,+ metrics: {+ ...qualityEvidence.metrics,+ codecProfile: "device-id=deadbeef",+ },+ },+ {+ ...qualityEvidence,+ metrics: {+ ...qualityEvidence.metrics,+ scalabilityMode: "DEVICE_ABC123",+ },+ },+ {+ ...qualityEvidence,+ metrics: {+ ...qualityEvidence.metrics,+ decoderImplementation: "device-specific-decoder",+ },+ },+ ]) {+ expect(clientMessageSchema.safeParse(invalid).success).toBe(false);+ }+ });++ it.each([+ ["video/VP8", null, "max-fr=60; max-fs=8160"],+ ["video/VP9", "profile-id=2", "max-fs=8160"],+ ["video/AV1", "profile=1", "level-idx=31; tier=0"],+ ["video/unknown", null, null],+ ])(+ "accepts canonical viewer codec evidence for %s",+ (codec, codecProfile, codecParameters) => {+ expect(+ clientMessageSchema.safeParse({+ ...qualityEvidence,+ metrics: {+ ...qualityEvidence.metrics,+ codec,+ codecProfile,+ codecParameters,+ },+ }).success,+ ).toBe(true);+ },+ );+it("accepts bounded route acknowledgements, failures, and SFU refreshes", () => {expect(clientMessageSchema.safeParse({@@ -500,6 +610,27 @@ describe("server signaling protocol", () => {}});+ it("accepts only canonical server-derived viewer evidence envelopes", () => {+ const forwarded = {+ ...qualityEvidence,+ viewerPeerId: "viewer_12345678",+ parentPeerId: "host_12345678",+ };+ expect(serverMessageSchema.safeParse(forwarded).success).toBe(true);+ expect(+ Buffer.byteLength(JSON.stringify(forwarded), "utf8"),+ ).toBeLessThanOrEqual(MAX_VIEWER_QUALITY_EVIDENCE_BYTES);+ expect(+ serverMessageSchema.safeParse({ ...forwarded, roomId }).success,+ ).toBe(false);+ expect(+ serverMessageSchema.safeParse({+ ...qualityEvidence,+ viewerPeerId: "viewer_12345678",+ }).success,+ ).toBe(false);+ });+it.each([0, 1.5, MAX_VIEWERS_PER_ROOM_LIMIT + 1])("rejects viewer limit %s outside the protocol boundary",(maxViewers) => {diff --git a/tests/server-signal.test.ts b/tests/server-signal.test.tsindex 64d8313b..24c77439 100644--- a/tests/server-signal.test.ts+++ b/tests/server-signal.test.ts@@ -6,6 +6,7 @@ import WebSocket from "ws";import {MAX_SIGNAL_BYTES,+ MAX_VIEWER_QUALITY_EVIDENCE_BYTES,decodeServerMessage,type Role,type ServerMessage,@@ -161,6 +162,7 @@ async function startHarness(persistent?: boolean;peerAssistedMedia?: boolean;peerAssistedPrimaryRoomOnly?: boolean;+ now?: () => number;} = {},): Promise<SignalHarness> {const config = testConfig();@@ -182,6 +184,7 @@ async function startHarness(config,roomStore,serveFrontend: false,+ now: overrides.now,authenticationTimeoutMs: overrides.authenticationTimeoutMs ?? 500,viewerDisconnectGraceMs: overrides.viewerDisconnectGraceMs ?? 50,heartbeatIntervalMs: 60_000,@@ -199,6 +202,38 @@ async function startHarness(};}+function viewerQualityEvidence(+ connectionId: string,+ routeRevision: number,+ sequence: number,+ bitrateKbps = 7_500,+) {+ return {+ type: "viewer-quality-evidence",+ guard: { connectionId, routeRevision },+ sequence,+ windowMs: 2_000,+ metrics: {+ width: 1_920,+ height: 1_080,+ framesPerSecond: 60,+ bitrateKbps,+ packetsReceivedDelta: 1_500,+ packetsLostDelta: 2,+ jitterMs: 3.5,+ framesDecodedDelta: 120,+ framesDroppedDelta: 1,+ decodeMsPerFrame: 2.4,+ freezeCountDelta: 0,+ freezeDurationMsDelta: 0,+ codec: "video/H264",+ codecProfile: "profile-level-id=42e01f",+ codecParameters:+ "packetization-mode=1; level-asymmetry-allowed=1",+ },+ } as const;+}+async function startSfuHarness(options: {tokenIssuer: SfuTokenIssuer;prepareTimeoutMs?: number;@@ -1119,6 +1154,314 @@ describe("WebSocket signaling", () => {expect(harness.roomStore.size).toBe(0);});+ it("forwards only current, bounded ordinary-P2P viewer C evidence", async () => {+ let now = Date.now();+ const harness = await startHarness({ now: () => now });+ const host = await openClient(harness.webSocketUrl);+ const hostAuth = await authenticate(+ host,+ harness.room,+ "host",+ "quality-host-client",+ );+ const viewer = await openClient(harness.webSocketUrl);+ const viewerAuth = await authenticate(+ viewer,+ harness.room,+ "viewer",+ "quality-viewer-client",+ );+ await host.inbox.next("peer-joined");++ host.socket.send(+ JSON.stringify({+ type: "signal",+ targetPeerId: viewerAuth.peerId,+ payload: {+ kind: "description",+ connectionId: "quality_connection_first",+ description: { type: "offer", sdp: "v=0\r\n" },+ },+ }),+ );+ await viewer.inbox.next("signal");++ viewer.socket.send(+ JSON.stringify(viewerQualityEvidence("quality_connection_first", 0, 0)),+ );+ expect(await host.inbox.next("viewer-quality-evidence")).toEqual({+ ...viewerQualityEvidence("quality_connection_first", 0, 0),+ viewerPeerId: viewerAuth.peerId,+ parentPeerId: hostAuth.peerId,+ });++ viewer.socket.send(+ JSON.stringify(viewerQualityEvidence("quality_connection_first", 0, 1)),+ );+ viewer.socket.send(+ JSON.stringify(+ viewerQualityEvidence("quality_connection_first", 0, 1, 7_000),+ ),+ );+ await host.inbox.expectNone(30);++ now += 2_000;+ viewer.socket.send(+ JSON.stringify(+ viewerQualityEvidence("quality_connection_first", 0, 1, 7_000),+ ),+ );+ expect(+ (await host.inbox.next("viewer-quality-evidence")).metrics.bitrateKbps,+ ).toBe(7_000);++ now += 2_000;+ viewer.socket.send(+ JSON.stringify(+ viewerQualityEvidence("quality_connection_first", 0, 2, 7_000),+ ),+ );+ expect(+ (await host.inbox.next("viewer-quality-evidence")).metrics.bitrateKbps,+ ).toBe(7_000);++ viewer.socket.send(+ JSON.stringify(+ viewerQualityEvidence("quality_connection_stale", 0, 3, 6_500),+ ),+ );+ viewer.socket.send(+ JSON.stringify(+ viewerQualityEvidence("quality_connection_first", 1, 3, 6_500),+ ),+ );+ await host.inbox.expectNone(30);++ host.socket.send(+ JSON.stringify({+ type: "signal",+ targetPeerId: viewerAuth.peerId,+ payload: {+ kind: "description",+ connectionId: "quality_connection_second",+ description: { type: "offer", sdp: "v=0\r\n" },+ },+ }),+ );+ await viewer.inbox.next("signal");+ viewer.socket.send(+ JSON.stringify(+ viewerQualityEvidence("quality_connection_first", 0, 3, 6_000),+ ),+ );+ await host.inbox.expectNone(30);+ viewer.socket.send(+ JSON.stringify(+ viewerQualityEvidence("quality_connection_second", 0, 0, 6_000),+ ),+ );+ expect(+ (await host.inbox.next("viewer-quality-evidence")).guard.connectionId,+ ).toBe("quality_connection_second");++ host.socket.send(+ JSON.stringify(+ viewerQualityEvidence("quality_connection_second", 0, 1, 5_500),+ ),+ );+ await host.inbox.expectNone(30);++ const replacementViewer = await openClient(harness.webSocketUrl);+ const replacementAuth = await authenticate(+ replacementViewer,+ harness.room,+ "viewer",+ "quality-viewer-client",+ );+ expect(replacementAuth).toMatchObject({+ peerId: viewerAuth.peerId,+ connectionId: "quality_connection_second",+ });+ expect(await host.inbox.next("peer-joined")).toMatchObject({+ peerId: viewerAuth.peerId,+ });+ replacementViewer.socket.send(+ JSON.stringify(+ viewerQualityEvidence("quality_connection_second", 0, 0, 5_000),+ ),+ );+ expect(await host.inbox.next("viewer-quality-evidence")).toMatchObject({+ viewerPeerId: viewerAuth.peerId,+ guard: { connectionId: "quality_connection_second" },+ sequence: 0,+ metrics: { bitrateKbps: 5_000 },+ });+ });++ it("derives peer-assisted C routing from the active assignment", async () => {+ const harness = await startHarness({ peerAssistedMedia: true });+ const host = await openClient(harness.webSocketUrl);+ const hostAuth = peerAssisted(+ await authenticate(host, harness.room, "host", "peer-quality-host"),+ );+ host.inbox.ignore("route-update");+ host.inbox.ignore("media-assignment");+ const viewer = await openClient(harness.webSocketUrl);+ const viewerAuth = peerAssisted(+ await authenticate(+ viewer,+ harness.room,+ "viewer",+ "peer-quality-viewer",+ ),+ );+ expect(viewerAuth.routeAssignment.upstream).toEqual({+ kind: "peer",+ peerId: hostAuth.peerId,+ });++ host.socket.send(+ JSON.stringify({+ type: "signal",+ targetPeerId: viewerAuth.peerId,+ payload: {+ kind: "description",+ connectionId: "peer_quality_connection",+ description: { type: "offer", sdp: "v=0\r\n" },+ },+ }),+ );+ await viewer.inbox.next("signal");+ viewer.socket.send(+ JSON.stringify(+ viewerQualityEvidence(+ "peer_quality_connection",+ viewerAuth.routeRevision,+ 0,+ ),+ ),+ );+ expect(await host.inbox.next("viewer-quality-evidence")).toMatchObject({+ viewerPeerId: viewerAuth.peerId,+ parentPeerId: hostAuth.peerId,+ guard: {+ connectionId: "peer_quality_connection",+ routeRevision: viewerAuth.routeRevision,+ },+ });++ viewer.socket.send(+ JSON.stringify(+ viewerQualityEvidence(+ "peer_quality_connection",+ viewerAuth.routeRevision + 1,+ 1,+ 7_000,+ ),+ ),+ );+ await host.inbox.expectNone(30);++ viewer.inbox.ignore("route-update");+ viewer.inbox.ignore("media-assignment");+ const secondViewer = await openClient(harness.webSocketUrl);+ await authenticate(+ secondViewer,+ harness.room,+ "viewer",+ "peer-quality-viewer-two",+ );+ const relayChild = await openClient(harness.webSocketUrl);+ const relayChildAuth = peerAssisted(+ await authenticate(+ relayChild,+ harness.room,+ "viewer",+ "peer-quality-relay-child",+ ),+ );+ expect(relayChildAuth.routeAssignment.upstream).toEqual({+ kind: "peer",+ peerId: viewerAuth.peerId,+ });++ viewer.socket.send(+ JSON.stringify(+ viewerQualityEvidence(+ "peer_quality_connection",+ relayChildAuth.routeRevision,+ 1,+ 6_500,+ ),+ ),+ );+ expect(await host.inbox.next("viewer-quality-evidence")).toMatchObject({+ viewerPeerId: viewerAuth.peerId,+ guard: {+ connectionId: "peer_quality_connection",+ routeRevision: relayChildAuth.routeRevision,+ },+ sequence: 1,+ });++ viewer.socket.send(+ JSON.stringify({+ type: "signal",+ targetPeerId: relayChildAuth.peerId,+ payload: {+ kind: "description",+ connectionId: "relay_child_quality_connection",+ description: { type: "offer", sdp: "v=0\r\n" },+ },+ }),+ );+ await relayChild.inbox.next("signal");+ relayChild.socket.send(+ JSON.stringify(+ viewerQualityEvidence(+ "relay_child_quality_connection",+ relayChildAuth.routeRevision,+ 0,+ ),+ ),+ );+ expect(await viewer.inbox.next("viewer-quality-evidence")).toMatchObject({+ viewerPeerId: relayChildAuth.peerId,+ parentPeerId: viewerAuth.peerId,+ guard: {+ connectionId: "relay_child_quality_connection",+ routeRevision: relayChildAuth.routeRevision,+ },+ });+ await host.inbox.expectNone(30);+ });++ it("rejects viewer C evidence above the byte cap", async () => {+ const harness = await startHarness();+ const viewer = await openClient(harness.webSocketUrl);+ await authenticate(+ viewer,+ harness.room,+ "viewer",+ "oversized-quality-viewer",+ );+ const closed = new Promise<number>((resolve) =>+ viewer.socket.once("close", (code) => resolve(code)),+ );+ const valid = JSON.stringify(+ viewerQualityEvidence("oversized_quality_connection", 0, 0),+ );++ viewer.socket.send(+ `${valid}${" ".repeat(MAX_VIEWER_QUALITY_EVIDENCE_BYTES + 1)}`,+ );++ expect(await viewer.inbox.next("error")).toMatchObject({+ code: "INVALID_MESSAGE",+ });+ expect(await closed).toBe(1008);+ });+it("routes offer and answer only between the host and the targeted viewer", async () => {const harness = await startHarness();const secondRoom = harness.roomStore.createRoom();diff --git a/tests/viewer-quality-evidence.test.ts b/tests/viewer-quality-evidence.test.tsnew file mode 100644index 00000000..ad42da51--- /dev/null+++ b/tests/viewer-quality-evidence.test.ts@@ -0,0 +1,247 @@+import { describe, expect, it } from "vitest";++import type { ClientMessage, ServerMessage } from "../src/shared/protocol.ts";+import {+ metricsFromQualityEvidence,+ qualityEvidenceMatchesSnapshot,+ qualityEvidenceWindowFromMetrics,+ ViewerQualityEvidenceReporter,+} from "../src/client/media/viewer-quality-evidence.ts";+import {+ EMPTY_METRICS,+ type ConnectionMetrics,+ type PeerSnapshot,+} from "../src/client/types.ts";++function receiveMetrics(+ overrides: Partial<ConnectionMetrics> = {},+): ConnectionMetrics {+ return {+ ...EMPTY_METRICS,+ sampleTimestampMs: 10_000,+ sampleWindowMs: 2_000,+ framesPerSecond: 60,+ frameWidth: 1_920,+ frameHeight: 1_080,+ resolution: "1920x1080",+ bitrateKbps: 7_500,+ intervalPacketsReceived: 1_500,+ intervalPacketsLost: 2,+ jitterMs: 3.5,+ intervalFramesDecoded: 120,+ intervalFramesDropped: 1,+ intervalDecodeMs: 2.4,+ intervalFreezeCount: 0,+ intervalFreezeDurationMs: 0,+ codec: "video/H264",+ codecProfile: "profile-level-id=42e01f",+ codecParameters:+ "packetization-mode=1; level-asymmetry-allowed=1",+ scalabilityMode: "L3T3_KEY",+ ...overrides,+ };+}++function snapshot(+ connectionId: string,+ metrics = receiveMetrics(),+): PeerSnapshot {+ return {+ peerId: "host_12345678",+ connectionId,+ connectionState: "connected",+ iceConnectionState: "connected",+ metrics,+ error: null,+ };+}++describe("viewer quality evidence", () => {+ it("normalizes only bounded adjacent receive evidence", () => {+ expect(qualityEvidenceWindowFromMetrics(receiveMetrics())).toEqual({+ windowMs: 2_000,+ metrics: {+ width: 1_920,+ height: 1_080,+ framesPerSecond: 60,+ bitrateKbps: 7_500,+ packetsReceivedDelta: 1_500,+ packetsLostDelta: 2,+ jitterMs: 3.5,+ framesDecodedDelta: 120,+ framesDroppedDelta: 1,+ decodeMsPerFrame: 2.4,+ freezeCountDelta: 0,+ freezeDurationMsDelta: 0,+ codec: "video/H264",+ codecProfile: "profile-level-id=42e01f",+ codecParameters:+ "packetization-mode=1; level-asymmetry-allowed=1",+ },+ });++ expect(+ qualityEvidenceWindowFromMetrics(+ receiveMetrics({+ sampleWindowMs: 9_000,+ rtpStatsId: "must-not-leave-the-client",+ }),+ ),+ ).toBeNull();+ const bounded = qualityEvidenceWindowFromMetrics(+ receiveMetrics({+ frameWidth: 0,+ frameHeight: 0,+ bitrateKbps: 200_000,+ intervalPacketsLost: -1,+ codecParameters: "raw fmtp; secret=value/with/slash",+ }),+ );+ expect(bounded?.metrics).toMatchObject({+ width: null,+ height: null,+ bitrateKbps: null,+ packetsLostDelta: null,+ codecParameters: null,+ });+ expect(JSON.stringify(bounded)).not.toContain("rtpStatsId");+ expect(JSON.stringify(bounded)).not.toContain("must-not-leave-the-client");+ expect(JSON.stringify(bounded)).not.toContain("scalabilityMode");+ expect(JSON.stringify(bounded)).not.toContain("L3T3_KEY");+ });++ it("rate-limits, deduplicates, and resets sequence per connection", () => {+ let now = 10_000;+ const sent: ClientMessage[] = [];+ const reporter = new ViewerQualityEvidenceReporter(+ (message) => {+ sent.push(message);+ return true;+ },+ () => now,+ );+ const first = snapshot("connection_first_12345678");++ expect(reporter.offer(first, 0)).toBe(true);+ expect(reporter.offer(first, 0)).toBe(false);+ now += 1_000;+ expect(+ reporter.offer(+ snapshot(+ first.connectionId,+ receiveMetrics({ sampleTimestampMs: 11_000, bitrateKbps: 7_000 }),+ ),+ 0,+ ),+ ).toBe(false);+ now += 1_000;+ expect(+ reporter.offer(+ snapshot(+ first.connectionId,+ receiveMetrics({ sampleTimestampMs: 12_000, bitrateKbps: 6_500 }),+ ),+ 0,+ ),+ ).toBe(true);+ expect(+ reporter.offer(+ snapshot(+ first.connectionId,+ receiveMetrics({ sampleTimestampMs: 12_000, bitrateKbps: 6_000 }),+ ),+ 2,+ ),+ ).toBe(true);+ expect(+ reporter.offer(snapshot("connection_second_12345678"), 2),+ ).toBe(true);+ now += 2_000;+ expect(+ reporter.offer(+ snapshot(+ "connection_second_12345678",+ receiveMetrics({ sampleTimestampMs: 14_000 }),+ ),+ 2,+ ),+ ).toBe(true);++ expect(+ sent.map((message) =>+ message.type === "viewer-quality-evidence"+ ? {+ connectionId: message.guard.connectionId,+ revision: message.guard.routeRevision,+ sequence: message.sequence,+ }+ : null,+ ),+ ).toEqual([+ {+ connectionId: "connection_first_12345678",+ revision: 0,+ sequence: 0,+ },+ {+ connectionId: "connection_first_12345678",+ revision: 0,+ sequence: 1,+ },+ {+ connectionId: "connection_first_12345678",+ revision: 2,+ sequence: 2,+ },+ {+ connectionId: "connection_second_12345678",+ revision: 2,+ sequence: 0,+ },+ {+ connectionId: "connection_second_12345678",+ revision: 2,+ sequence: 1,+ },+ ]);+ });++ it("pairs and renders only the current parent connection", () => {+ const evidence = {+ type: "viewer-quality-evidence",+ viewerPeerId: "viewer_12345678",+ parentPeerId: "host_12345678",+ guard: {+ connectionId: "connection_12345678",+ routeRevision: 0,+ },+ sequence: 3,+ ...qualityEvidenceWindowFromMetrics(receiveMetrics())!,+ } as Extract<ServerMessage, { type: "viewer-quality-evidence" }>;+ const current = {+ ...snapshot(evidence.guard.connectionId),+ peerId: evidence.viewerPeerId,+ };++ expect(qualityEvidenceMatchesSnapshot(evidence, current)).toBe(true);+ expect(+ qualityEvidenceMatchesSnapshot(evidence, {+ ...current,+ connectionId: "connection_replaced_12345678",+ }),+ ).toBe(false);+ expect(metricsFromQualityEvidence(evidence)).toMatchObject({+ sampleWindowMs: 2_000,+ frameWidth: 1_920,+ frameHeight: 1_080,+ resolution: "1920x1080",+ bitrateKbps: 7_500,+ packetsLost: 2,+ framesDropped: 1,+ intervalFramesDecoded: 120,+ intervalFramesDropped: 1,+ intervalFreezeCount: 0,+ codec: "video/H264",+ });+ });+});