Free, open-source screen sharing for private live streams with friends. Watch together in a browser or self-host Piik. 免费开源的私密屏幕共享,支持游戏直播、一起看电影与自部署。
feat(web): observe selected pair responses (#181)
AAAf81577c4c5e1
diff --git a/docs/research/peer-assisted-media.md b/docs/research/peer-assisted-media.mdindex 7d50d4d0..384218cb 100644--- a/docs/research/peer-assisted-media.md+++ b/docs/research/peer-assisted-media.md@@ -367,6 +367,55 @@ zero, then the current Web client advertises an explicit per-session capacityof one. The first production smoke scoped it to room `1`; current production nolonger has that room boundary. There is no mobile/iPad, UA, or visibility branch.+## Selected-Pair Response Observation++The W3C Stats specification makes `RTCTransportStats.selectedCandidatePairId`+the exact reference to the current `RTCIceCandidatePairStats`. A stats object's+`id` identifies the monitored object, while `responsesReceived` is the+cumulative number of connectivity-check responses received by that candidate+pair. Stats snapshots carry timestamps and applications derive interval values+from two snapshots. Unsupported fields are omitted, and a current pair is+deleted when the transport switches to a newly generated pair. These semantics+support a local observation; they do not define an application failure signal.+The existing compatibility fallback is retained only when that exact reference+is absent and exactly one same-transport succeeded nominated/selected pair is+available; an ambiguous or broken relationship remains unknown.++RFC 7675 binds consent to one transport 5-tuple. An authenticated matching STUN+response refreshes consent, but the default consent-check interval is randomized+between four and six seconds and a response can match an earlier request.+Therefore zero `responsesReceived` growth over one two-second application sample+does not prove a silent partition. Conversely, growth proves only that a STUN+response was observed on that pair, not that media quality or future reachability+is healthy. Video-frame counters are independent, so a static shared frame must+not be classified as a transport failure.++The bounded implementation uses one accumulator per `RTCPeerConnection` and the+selected pair's own stats timestamp. It reports the cumulative counter plus a+delta and elapsed milliseconds only across adjacent samples of the same pair.+The first sample, PC replacement, pair change or disappearance, missing/invalid+counter or timestamp, non-increasing timestamp, counter retreat, or a sampling+gap above five seconds reports the interval fields as unknown and establishes a+new baseline. The five-second ceiling is a named observation-window bound for+the current two-second sampler; it is not a consent timeout or a route policy.++Acceptance for this slice is observation-only:++- expanded local connection details show the opaque selected-pair identity,+ cumulative `responsesReceived`, and the adjacent bounded delta/window;+- the click-only diagnostic allowlist may contain the cumulative counter,+ interval delta, and interval duration, but not the pair ID, candidate+ addresses/ports, raw stats, signaling, or credentials;+- a missing response counter or required timestamp remains unknown rather than+ zero; and+- no value starts ICE restart, emits `route-failed`, changes topology/quality,+ adds a wire or server ping, or uploads/persists telemetry.++Sources, accessed 2026-08-22:++- [W3C Identifiers for WebRTC's Statistics API](https://www.w3.org/TR/webrtc-stats/)+- [RFC 7675, Consent Freshness for WebRTC](https://www.rfc-editor.org/rfc/rfc7675.html)+## Bounded Spike And GatesThis historical gate assumed default-off configuration throughdiff --git a/docs/status.md b/docs/status.mdindex f5eba5cd..cc2f9327 100644--- a/docs/status.md+++ b/docs/status.md@@ -15,6 +15,7 @@ This file is the current execution index. Load [verification status](./verificat- Capture precedes room creation. Balanced, automatic codec, and 128 kbps screen audio are defaults; clarity/fluid, H.264/VP8, and 64/128/256 kbps audio are deployed next-share choices. Codec and audio quality lock during a share.- Local-only connection details expose current Host SFU sender evidence, actual codec/fmtp and encoder fields, media-source/encode FPS evidence, A/V playout/jitter/concealment evidence, and selected candidate endpoints. These fields do not enter quality signaling, server state, logs, persistence, or route selection.+- A source candidate additionally shows the selected pair's local cumulative STUN responses and a bounded same-pair sample delta. It is observation-only, is not deployed, and does not trigger recovery or upload the pair identity.- The deployed pre-share self-check uses disposable, no-room resources for health, WSS, and STUN `srflx` checks and treats configured SFU as unverified until a real route. Expanded connection details provide click-only, versioned JSON export; its fixed allowlist excludes candidate addresses/ports, participant and room identity, raw signaling, URLs, and credentials, and no report is uploaded or persisted.- Private fragment grants enter directly; code-only Viewers need site access and private rooms additionally need their password. Credentials remain unstored. Web names and presence are session-only; duplicate names alone show an ID suffix.- 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.diff --git a/docs/verification-status.md b/docs/verification-status.mdindex 391cff9a..3b0d7f1f 100644--- a/docs/verification-status.md+++ b/docs/verification-status.md@@ -33,7 +33,7 @@ This is the demand-loaded ledger for cross-cutting validation evidence and open- Relay resources: production is Host2/ordinary Browser Viewer1 and rejects any Viewer child2 regardless of advertised capacity. Two-child relay corroboration is therefore a future-capacity experiment, while the triggering child's edge-local MBB remains active. Relay CPU/GPU/upload cost and heterogeneous-network behavior remain unverified. Finish the role-aware matrix before the 20-viewer gate or any future capacity-tier change.- SFU: production deploys ordered `q,h`, roots <=2, and Dynacast off. Real zero-child shaped LiveKit packet flow, BWE downshift/recovery, resource cost, and root-with-children behavior remain open. Use Linux `tc` or a public canary for per-leaf shaping, never CDP throttling.- Audio: verify the 64/128/256 kbps Share settings, negotiated/observed bitrate, audible music quality, route changes, and game A/V synchronization. Bitrate settings are ceilings, not quality proof.-- Observability: the UI and local stats plumbing are deployed, but target-browser availability and actual values remain unverified for Host SFU sender evidence, codec/fmtp and encoder implementation/power efficiency, media-source and encoded FPS, A/V playout/jitter/concealment, and selected candidate endpoints. These fields diagnose; they do not by themselves prove hardware encode, synchronization quality, or route quality.+- Observability: the UI and local stats plumbing are deployed, but target-browser availability and actual values remain unverified for Host SFU sender evidence, codec/fmtp and encoder implementation/power efficiency, media-source and encoded FPS, A/V playout/jitter/concealment, and selected candidate endpoints. A source-only candidate adds bounded same-pair STUN-response observation without recovery authority. These fields diagnose; they do not by themselves prove hardware encode, synchronization quality, or route quality.- Mobile: Android/iOS remain Viewer-only. Autoplay, rotation, iOS lock-screen/page reclamation, background reconnection, and network changes need device evidence. AirPlay/system mirroring is Viewer-local output, not a portable in-app WebRTC output contract.- Native: ADR-0006 has one-Viewer evidence only. Viewer2/FIFO, hardware diversity, endurance, downloaded-package/public-host, game A/V, and browser diversity remain open.- Access and operations: run headful/production checks for fragment consumption, rotate/revoke, and request/nginx/journal/SQLite leakage. The isolated VM/IP gate remains required before clean-port migration; shared-IP smoke cannot approve it.diff --git a/src/client/components/StatsGrid.tsx b/src/client/components/StatsGrid.tsxindex cd1f174c..d15cd583 100644--- a/src/client/components/StatsGrid.tsx+++ b/src/client/components/StatsGrid.tsx@@ -53,6 +53,21 @@ function candidateEndpoint(return `${host}:${port}`;}+function candidatePairResponses(metrics: ConnectionMetrics): string {+ if (metrics.candidatePairResponsesReceived === null) {+ return "未知";+ }+ if (+ metrics.intervalCandidatePairResponsesReceived === null ||+ metrics.candidatePairSampleWindowMs === null+ ) {+ return `${metrics.candidatePairResponsesReceived} 累计 · 区间未知`;+ }+ return `${metrics.candidatePairResponsesReceived} 累计 · +${+ metrics.intervalCandidatePairResponsesReceived+ } / ${(metrics.candidatePairSampleWindowMs / 1_000).toFixed(1)} s`;+}+function Metric({ label, value, title }: { label: string; value: string; title?: string }) {return (<div className="metric" title={title}>@@ -164,6 +179,16 @@ export function StatsGrid({title={remoteCandidateEndpoint}/>)}+ <Metric+ label="候选对 ID"+ value={metrics.selectedCandidatePairId ?? "未知"}+ title={metrics.selectedCandidatePairId ?? undefined}+ />+ <Metric+ label="STUN 响应"+ value={candidatePairResponses(metrics)}+ title="当前候选对的累计响应,以及同一候选对相邻有效采样窗的增量;零增量不代表断链"+ /><Metric label="视频 Codec" value={metrics.codec ?? "未知"} />{metrics.codecProfile && (<Metric label="视频 Codec profile token" value={metrics.codecProfile} />diff --git a/src/client/lib/diagnostic-export.ts b/src/client/lib/diagnostic-export.tsindex b502d9d0..a2e0e9e5 100644--- a/src/client/lib/diagnostic-export.ts+++ b/src/client/lib/diagnostic-export.ts@@ -4,6 +4,8 @@ export const DIAGNOSTIC_SCHEMA_VERSION = 1;const DIAGNOSTIC_METRIC_KEYS = ["sampleWindowMs", "captureWidth", "captureHeight",+ "candidatePairResponsesReceived", "intervalCandidatePairResponsesReceived",+ "candidatePairSampleWindowMs","captureFramesPerSecond", "mediaSourceFramesPerSecond", "path","iceProtocol", "localRelayProtocol", "localCandidateType","remoteCandidateType", "rttMs", "bitrateKbps", "availableOutgoingKbps",diff --git a/src/client/types.ts b/src/client/types.tsindex 6db01acf..0cad9a21 100644--- a/src/client/types.ts+++ b/src/client/types.ts@@ -15,6 +15,9 @@ export interface ConnectionMetrics {rtpRid: string | null;trackIdentifier: string | null;selectedCandidatePairId: string | null;+ candidatePairResponsesReceived: number | null;+ intervalCandidatePairResponsesReceived: number | null;+ candidatePairSampleWindowMs: number | null;captureWidth: number | null;captureHeight: number | null;captureFramesPerSecond: number | null;@@ -93,6 +96,9 @@ export const EMPTY_METRICS: ConnectionMetrics = {rtpRid: null,trackIdentifier: null,selectedCandidatePairId: null,+ candidatePairResponsesReceived: null,+ intervalCandidatePairResponsesReceived: null,+ candidatePairSampleWindowMs: null,captureWidth: null,captureHeight: null,captureFramesPerSecond: null,diff --git a/src/client/webrtc/stats.ts b/src/client/webrtc/stats.tsindex 2a6fec99..f90d9ef8 100644--- a/src/client/webrtc/stats.ts+++ b/src/client/webrtc/stats.ts@@ -10,7 +10,12 @@ type StatsRecord = Record<string, unknown> & {timestamp: number;};+const MAX_CANDIDATE_PAIR_SAMPLE_WINDOW_MS = 5_000;+export interface StatsAccumulator {+ candidatePairId: string | null;+ candidatePairResponsesReceived: number | null;+ candidatePairTimestamp: number | null;mediaId: string | null;ssrc: number | null;trackIdentifier: string | null;@@ -76,6 +81,9 @@ export function captureMetrics(export function createStatsAccumulator(): StatsAccumulator {return {+ candidatePairId: null,+ candidatePairResponsesReceived: null,+ candidatePairTimestamp: null,mediaId: null,ssrc: null,trackIdentifier: null,@@ -354,6 +362,16 @@ function positiveIntegerValue(return value !== null && Number.isInteger(value) && value > 0 ? value : null;}+function nonNegativeIntegerValue(+ record: StatsRecord | null,+ key: string,+): number | null {+ const value = numberValue(record, key);+ return value !== null && Number.isSafeInteger(value) && value >= 0+ ? value+ : null;+}+function candidateAddressValue(record: StatsRecord | null): string | null {const value = stringValue(record, "address");return value !== null &&@@ -433,6 +451,34 @@ export function collectConnectionMetricsFromReport(? "direct": "unknown";+ const candidatePairId = pair?.id ?? null;+ const candidatePairResponsesReceived = nonNegativeIntegerValue(+ pair,+ "responsesReceived",+ );+ const candidatePairTimestamp = numberValue(pair, "timestamp");+ const candidatePairSampleWindowMs =+ candidatePairId !== null &&+ candidatePairId === previous.candidatePairId &&+ candidatePairResponsesReceived !== null &&+ previous.candidatePairResponsesReceived !== null &&+ candidatePairResponsesReceived >= previous.candidatePairResponsesReceived &&+ candidatePairTimestamp !== null &&+ previous.candidatePairTimestamp !== null &&+ candidatePairTimestamp > previous.candidatePairTimestamp &&+ candidatePairTimestamp - previous.candidatePairTimestamp <=+ MAX_CANDIDATE_PAIR_SAMPLE_WINDOW_MS+ ? candidatePairTimestamp - previous.candidatePairTimestamp+ : null;+ const intervalCandidatePairResponsesReceived = intervalDelta(+ candidatePairResponsesReceived,+ previous.candidatePairResponsesReceived,+ candidatePairSampleWindowMs !== null,+ );+ previous.candidatePairId = candidatePairId;+ previous.candidatePairResponsesReceived = candidatePairResponsesReceived;+ previous.candidatePairTimestamp = candidatePairTimestamp;+const mediaId = media?.id ?? null;const ssrc = numberValue(media, "ssrc");const trackIdentifier = media@@ -763,6 +809,9 @@ export function collectConnectionMetricsFromReport(rtpRid: stringValue(media, "rid"),trackIdentifier,selectedCandidatePairId: pair?.id ?? null,+ candidatePairResponsesReceived,+ intervalCandidatePairResponsesReceived,+ candidatePairSampleWindowMs,path,iceProtocol,localRelayProtocol,diff --git a/tests/client-state.test.ts b/tests/client-state.test.tsindex f75b5d6e..9babde2e 100644--- a/tests/client-state.test.ts+++ b/tests/client-state.test.ts@@ -33,7 +33,11 @@ import {labelViewerPresence,} from "../src/client/lib/viewer-presence.ts";import { qualityEvidenceWindowFromMetrics } from "../src/client/media/viewer-quality-evidence.ts";-import { createStatsAccumulator, collectConnectionMetrics } from "../src/client/webrtc/stats.ts";+import {+ collectConnectionMetrics,+ collectConnectionMetricsFromReport,+ createStatsAccumulator,+} from "../src/client/webrtc/stats.ts";afterEach(() => {vi.unstubAllGlobals();@@ -798,6 +802,139 @@ describe("client signaling recovery policy", () => {});describe("WebRTC stats parsing", () => {+ it("rebases selected-pair response observations across identity and sampling gaps", () => {+ const report = (+ pairId: string,+ timestamp: number,+ responsesReceived?: unknown,+ ) =>+ new Map<string, unknown>([+ [+ "transport",+ {+ id: "transport",+ type: "transport",+ timestamp,+ selectedCandidatePairId: pairId,+ },+ ],+ [+ pairId,+ {+ id: pairId,+ type: "candidate-pair",+ timestamp,+ transportId: "transport",+ localCandidateId: "local",+ remoteCandidateId: "remote",+ ...(responsesReceived === undefined ? {} : { responsesReceived }),+ },+ ],+ [+ "local",+ {+ id: "local",+ type: "local-candidate",+ timestamp,+ candidateType: "host",+ protocol: "udp",+ },+ ],+ [+ "remote",+ {+ id: "remote",+ type: "remote-candidate",+ timestamp,+ candidateType: "srflx",+ protocol: "udp",+ },+ ],+ [+ "inbound",+ {+ id: "inbound",+ type: "inbound-rtp",+ timestamp,+ kind: "video",+ transportId: "transport",+ bytesReceived: 1_000,+ framesDecoded: 10,+ },+ ],+ ]) as unknown as RTCStatsReport;+ const accumulator = createStatsAccumulator();+ const sample = (+ pairId: string,+ timestamp: number,+ responsesReceived?: unknown,+ ) =>+ collectConnectionMetricsFromReport(+ report(pairId, timestamp, responsesReceived),+ "receive",+ accumulator,+ );++ expect(sample("pair-a", 1_000, 5)).toMatchObject({+ selectedCandidatePairId: "pair-a",+ candidatePairResponsesReceived: 5,+ intervalCandidatePairResponsesReceived: null,+ candidatePairSampleWindowMs: null,+ });+ expect(sample("pair-a", 3_000, 6)).toMatchObject({+ candidatePairResponsesReceived: 6,+ intervalCandidatePairResponsesReceived: 1,+ candidatePairSampleWindowMs: 2_000,+ });+ expect(sample("pair-a", 5_000, 6)).toMatchObject({+ intervalCandidatePairResponsesReceived: 0,+ candidatePairSampleWindowMs: 2_000,+ });+ expect(sample("pair-a", 7_000, 1)).toMatchObject({+ candidatePairResponsesReceived: 1,+ intervalCandidatePairResponsesReceived: null,+ candidatePairSampleWindowMs: null,+ });+ expect(sample("pair-a", 9_000, 2)).toMatchObject({+ intervalCandidatePairResponsesReceived: 1,+ candidatePairSampleWindowMs: 2_000,+ });+ expect(sample("pair-b", 11_000, 10)).toMatchObject({+ selectedCandidatePairId: "pair-b",+ intervalCandidatePairResponsesReceived: null,+ candidatePairSampleWindowMs: null,+ });+ expect(sample("pair-b", 16_001, 11)).toMatchObject({+ intervalCandidatePairResponsesReceived: null,+ candidatePairSampleWindowMs: null,+ });+ expect(sample("pair-b", 18_001, 12)).toMatchObject({+ intervalCandidatePairResponsesReceived: 1,+ candidatePairSampleWindowMs: 2_000,+ });+ expect(sample("pair-b", 20_001)).toMatchObject({+ candidatePairResponsesReceived: null,+ intervalCandidatePairResponsesReceived: null,+ candidatePairSampleWindowMs: null,+ });+ expect(sample("pair-b", 22_001, 13)).toMatchObject({+ candidatePairResponsesReceived: 13,+ intervalCandidatePairResponsesReceived: null,+ candidatePairSampleWindowMs: null,+ });+ expect(+ collectConnectionMetricsFromReport(+ report("pair-b", 24_001, 14),+ "receive",+ createStatsAccumulator(),+ ),+ ).toMatchObject({+ candidatePairResponsesReceived: 14,+ intervalCandidatePairResponsesReceived: null,+ candidatePairSampleWindowMs: null,+ });+ });+it("binds media, remote evidence, transport, and pair without guessing", async () => {const entry = (id: string,diff --git a/tests/diagnostic-export.test.ts b/tests/diagnostic-export.test.tsindex 98de8f39..76c07353 100644--- a/tests/diagnostic-export.test.ts+++ b/tests/diagnostic-export.test.ts@@ -29,6 +29,9 @@ describe("diagnostic export privacy boundary", () => {framesPerSecond: 59.8,codec: "video/VP8",audioVideoPlayoutDeltaMs: -12.5,+ candidatePairResponsesReceived: 18,+ intervalCandidatePairResponsesReceived: 1,+ candidatePairSampleWindowMs: 2_000,},},],@@ -50,6 +53,9 @@ describe("diagnostic export privacy boundary", () => {framesPerSecond: 59.8,codec: "video/VP8",audioVideoPlayoutDeltaMs: -12.5,+ candidatePairResponsesReceived: 18,+ intervalCandidatePairResponsesReceived: 1,+ candidatePairSampleWindowMs: 2_000,audioJitterMs: null,},});diff --git a/tests/stats-grid.test.ts b/tests/stats-grid.test.tsindex 75ffa159..fe7395cd 100644--- a/tests/stats-grid.test.ts+++ b/tests/stats-grid.test.ts@@ -23,6 +23,10 @@ const metrics = {localCandidatePort: 50_000,remoteCandidateAddress: "2001:db8::10",remoteCandidatePort: 50_001,+ selectedCandidatePairId: "candidate-pair-7",+ candidatePairResponsesReceived: 18,+ intervalCandidatePairResponsesReceived: 1,+ candidatePairSampleWindowMs: 2_000,codec: "video/VP8",codecParameters: "max-fs=8160",captureWidth: 1920,@@ -75,6 +79,10 @@ describe("StatsGrid progressive disclosure", () => {expect(html.indexOf("远端候选地址")).toBeGreaterThan(panelStart);expect(html).toContain("192.0.2.10:50000");expect(html).toContain("[2001:db8::10]:50001");+ expect(html).toContain("候选对 ID");+ expect(html).toContain("candidate-pair-7");+ expect(html).toContain("STUN 响应");+ expect(html).toContain("18 累计 · +1 / 2.0 s");expect(html.indexOf("视频 Codec")).toBeGreaterThan(panelStart);expect(html.indexOf("音频发送码率")).toBeGreaterThan(panelStart);expect(html.indexOf("编码输入帧率")).toBeGreaterThan(panelStart);