Free, open-source screen sharing for private live streams with friends. Watch together in a browser or self-host Piik. 免费开源的私密屏幕共享,支持游戏直播、一起看电影与自部署。
fix(media): retry healthy SFU after cooldown [skip ci] (#160)
AAA2cf4746ee7e8
diff --git a/docs/adr/0005-automatic-hybrid-media-routing.md b/docs/adr/0005-automatic-hybrid-media-routing.mdindex 1c2c6e8d..bcb76144 100644--- a/docs/adr/0005-automatic-hybrid-media-routing.md+++ b/docs/adr/0005-automatic-hybrid-media-routing.md@@ -530,12 +530,21 @@ failure, only the exact current SFU owner may abort. Ordinary transport uses anull connection; selected Host ingress must match its activated connectionidentity. The rollback active revision then drives the existing one-refreshrecovery. Success and abort share the room's 30-second migration cooldown.+If one otherwise-current healthy event arrives during that cooldown, the room+retains only the latest root/session/revision/share/publication tuple. At the+cooldown boundary it reasserts the same authoritative SFU assignment only when+that tuple and the one-root topology are still current. The Viewer must then+produce two new positive RTP/decoded-frame windows before sending another+ready event; the pre-cooldown proof never authorizes a delayed peer probe.The implemented source slice deliberately handles exactly one active SFU rootand only its parent retained in the deterministic peer baseline. The acceptedcapacity `0 -> 1` trigger and deterministic selection among multiple SFU roots-remain follow-ups. No timer/polling trigger, global score, new dependency,-ordinary-peer TURN grant, or second route controller was added.+remain follow-ups. No periodic polling trigger, global score, new dependency,+ordinary-peer TURN grant, or second route controller was added. The single+cooldown-bound timer above is an event continuation and is cleared on session,+room-stop, or room-delete changes; a changed route or generation discards it at+the boundary.The bounded cost model and privacy-safe ICE fieldslive in [Low-Server-Cost Media Routes](../research/low-server-media-routes.md).diff --git a/docs/project-memory.md b/docs/project-memory.mdindex 438f3b3d..c7dc7a24 100644--- a/docs/project-memory.md+++ b/docs/project-memory.md@@ -27,7 +27,7 @@ Last updated: 2026-08-22- Web defaults to browser/LiveKit codec negotiation; advanced settings offer Automatic, H.264, or VP8 for the next share while retaining fallback codecs and `backupCodec=false`. A codec choice neither proves hardware encoding nor shared encode. ADR-0006's browser bridge remains no-go.- Mobile endpoints are Web Viewer-only. Current Android/iOS browsers do not expose Web Host capture; AirPlay/system mirroring is Viewer-local output.- ADR-0005: direct/peer UDP -> bounded SFU roots -> selected-edge TURN. The deployed controller caps pending/answered `peer-selected` at one per room; Host ingress is independent. A pre-`ecc794d` exact-source/production-media canary proves active Host ingress only. Ordinary peers stay STUN-only.-- `PEER_ASSISTED_MEDIA=true` enables isolated all-room controllers; room `1` is historical. Keep sticky P2P and one recovery attempt per layer. Deployed healthy-SFU MBB covers one root and retained parent after reauth/recovery, gated by media proof, Host2/browser1 overlap and cooldown. It excludes `peer-selected`; active-SFU loss aborts into normal recovery. Capacity `0 -> 1`, multi-root and browser gates remain open.+- `PEER_ASSISTED_MEDIA=true` enables all-room controllers; room `1` is historical. One-root healthy-SFU MBB is deployed with retained parent, media proof, Host2/browser1 overlap and cooldown. A cooldown-time ready is retained; expiry needs two fresh windows. It excludes `peer-selected`; active-SFU loss uses normal recovery. Capacity `0 -> 1`, multi-root and browser gates remain open.- C+B reparenting stays edge-local: severe uses fallback; relative relay FPS uses fresh parent evidence and peers only. No scoring or global penalty.- Flagship media is UDP; HTTPS/WSS stays TLS/TCP; the old release remains rollback-only.- Treat settings as ceilings and degradation as unclassified. Use correlated Host A+B/Viewer C and one-variable evidence; never force AV1, infer by UA, or create a composite score.@@ -43,7 +43,7 @@ Last updated: 2026-08-22## Current Implementation- The repository is one npm package using Node.js 24, React, TypeScript, Vite, native WebRTC, `ws`, Zod, Vitest, and separate coturn.-- Production: exact `25b725fdfcccc181a22ef020d77f5668470ba636`, release `25b725fdfccc`, Web wire `screener-v4`.+- Production: exact `27ad90ddf9f85d0a88a7d06fd366461622653649`, release `27ad90ddf9f8`, Web wire `screener-v4`.- Web keeps one SFU stream, clears unavailable video, exposes evidence-backed routes/transports and paused preview, and drops signals to a grace-retained offline current-edge target. Routing is automatic; entry/nickname UI is live; Native remains source-only.- Web relay is cap2 with one upstream; child3 rejects and no UA/visibility split exists.- Deployed relay evidence reaches opted-in Host rosters; direct proof stays local-edge-only.diff --git a/docs/status.md b/docs/status.mdindex 9f2277e4..a147f732 100644--- a/docs/status.md+++ b/docs/status.md@@ -4,7 +4,7 @@ Last updated: 2026-08-22## Phase-Production is exact `25b725fdfcccc181a22ef020d77f5668470ba636` at `https://share.bonfire.icu`, release `25b725fdfccc`, wire `screener-v4`. SQLite v3/five rooms keeps SHA-256 `aef724ae52c4107be8ec8791e72f8dcaa11b0ec849fb432d022e2cfb9cfe0974`, owner/mode `screener:screener`/0600. Four services and local/public health are green.+Production is exact `27ad90ddf9f85d0a88a7d06fd366461622653649` at `https://share.bonfire.icu`, release `27ad90ddf9f8`, wire `screener-v4`. SQLite v3/five rooms keeps SHA-256 `aef724ae52c4107be8ec8791e72f8dcaa11b0ec849fb432d022e2cfb9cfe0974`, owner/mode `screener:screener`/0600. Four services and local/public health are green.Ordinary ICE is STUN-only; limits are SFU roots <=2, one `peer-selected` attempt excluding Host ingress, and selected UDP TTL 120. No browser/media/SFU/TURN/performance canary ran; exact-`16f6eab` Host-ingress proof is separate.Stable SFU, route/transport truth, preview notice, entry/nickname UI and Web relay cap2 are live. Native is source-only. The controlled production A/B uses browser/LiveKit codec defaults; explicit codec controls are source-complete.@@ -18,9 +18,9 @@ Parallel flagship work; use minimum relevant checks and rollback proof. Target-d- Deployed `screener-v4` admits private fragment grants directly; code-only Viewers need site access, and private rooms additionally need their password. Credentials remain unstored. Web presence fields remain opt-in and Native does not subscribe to them.- Deployed UI has nickname editing, room entry, Viewer roster, duplicate-only ID suffixes, pause notice, and session-bound SFU first-media truth that clears on track/route/session loss. P2P/SFU/TURN labels require evidence. Guarded relay evidence reaches opted-in Web Host rosters without Host-local transport claims or false parent-edge proof.- Native v4 is source-only (memory rooms, 300s reclaim); it does not subscribe to Web presence, follows authenticated direct-child assignments up to two, and fails unsupported SFU/selected ingress boundedly.-- Production is roots/Web relay <=2; every Viewer has one upstream and rejects child3. One-root healthy-SFU MBB is deployed but media-unverified; capacity `0 -> 1`, multi-root and browser gates remain open. Room `1` is historical; HTTPS/WSS is TLS/TCP.+- Production roots/Web relay <=2; Viewer upstream1, child3 rejected. One-root healthy-SFU MBB is deployed/media-unverified; source defers one cooldown ready for expiry reproof. Capacity `0 -> 1`, multi-root and browser gates remain open. Room `1` is historical; HTTPS/WSS is TLS/TCP.- After an answer, a generation-bound 15s initial-connect deadline enters ICE restart; success/replacement/disposal cancels it. It is deployed but not mobile-verified.-- C+B reparenting remains uncalibrated. Source compares relay-child FPS with fresh parent input and tries peers only; no candidate keeps the old edge. This correction is not deployed. Admission rescue stays deterministic.+- C+B reparenting remains uncalibrated. Production compares relay-child FPS with fresh parent input and tries peers only; no candidate keeps the old edge. Admission rescue stays deterministic.## Verified Evidencediff --git a/src/client/media/viewer-sfu-route.ts b/src/client/media/viewer-sfu-route.tsindex c6d12d8d..8b70ee4f 100644--- a/src/client/media/viewer-sfu-route.ts+++ b/src/client/media/viewer-sfu-route.ts@@ -84,6 +84,10 @@ export class ViewerSfuRoute {if (result === "stale") {return result;}+ const rearmHealthySfu =+ result === "duplicate" &&+ update.phase === "active" &&+ update.assignment.upstream.kind === "sfu";if (previousRevision !== update.revision) {this.recovery = null;this.peerProbeRevision = null;@@ -120,6 +124,9 @@ export class ViewerSfuRoute {return result;}void this.queueActiveRoute(token, acknowledge);+ if (rearmHealthySfu) {+ this.armHealthySfuReselection(update.revision);+ }return result;}diff --git a/src/server/hybrid-media-router.ts b/src/server/hybrid-media-router.tsindex 9be96162..2f093875 100644--- a/src/server/hybrid-media-router.ts+++ b/src/server/hybrid-media-router.ts@@ -104,6 +104,15 @@ interface HealthySfuReselectionProbe {parentPeerId: string;}+interface DeferredHealthySfuReselection {+ activeRevision: number;+ shareGeneration: string;+ publicationGeneration: string;+ rootPeerId: string;+ rootSessionId: string;+ timer: NodeJS.Timeout | null;+}+interface QualityRouteIntentGuard {kind: ViewerQualityBadWindowKind;viewerSessionId: string;@@ -244,6 +253,10 @@ export class HybridMediaRouter {string,number>();+ private readonly deferredHealthySfuReselections = new Map<+ string,+ DeferredHealthySfuReselection+ >();constructor(private readonly options: HybridMediaRouterOptions) {const fallback = options.sfuFallback;@@ -279,6 +292,12 @@ export class HybridMediaRouter {clearTimeout(attempt.timer);}this.selectedSfuIngressAttempts.clear();+ for (const deferred of this.deferredHealthySfuReselections.values()) {+ if (deferred.timer) {+ clearTimeout(deferred.timer);+ }+ }+ this.deferredHealthySfuReselections.clear();this.activeSelectedSfuIngresses.clear();this.mediaRouteControllers.clear();this.failedParentPeerIdsByViewer.clear();@@ -296,6 +315,10 @@ export class HybridMediaRouter {this.clearHeldQualityParentExclusion(input.roomId, input.peerId);this.clearSfuRefreshesForPeer(input.roomId, input.peerId);if (input.role === "viewer") {+ this.clearDeferredHealthySfuReselectionForParticipant(+ input.roomId,+ input.peerId,+ );const connectionKey = viewerConnectionKey(input.roomId, input.peerId);this.failedParentPeerIdsByViewer.delete(connectionKey,@@ -836,18 +859,31 @@ export class HybridMediaRouter {active?.revision !== revision ||active.sfu.rootPeerIds.length !== 1 ||active.sfu.rootPeerIds[0] !== participant.peerId ||+ this.options.roomStore.getConnectedViewer(roomId, participant.peerId)+ ?.sessionId !== participant.sessionId ||!publicationGeneration ||!shareGeneration) {return;}const now = this.options.now?.() ?? Date.now();- if (- !Number.isFinite(now) ||- (this.roomQualityMigrationCooldownUntilMs.get(roomId) ?? 0) > now- ) {+ const cooldownUntil =+ this.roomQualityMigrationCooldownUntilMs.get(roomId) ?? 0;+ if (!Number.isFinite(now)) {return;}+ if (cooldownUntil > now) {+ this.deferHealthySfuReselection(+ participant,+ revision,+ shareGeneration,+ publicationGeneration,+ cooldownUntil,+ now,+ );+ return;+ }+ this.clearDeferredHealthySfuReselection(roomId);this.startRoomQualityMigrationCooldown(roomId);const hostPeerId = this.peerRelayTopology.getHostPeerId(roomId);const parentPeerId = this.peerRelayTopology.getAssignment(@@ -1294,6 +1330,7 @@ export class HybridMediaRouter {disconnectParticipant(roomId: string, peerId: string): void {this.clearSelectedEdgeTurnsForParticipant(roomId, peerId);this.clearViewerQualityStateForParticipant(roomId, peerId);+ this.clearDeferredHealthySfuReselectionForParticipant(roomId, peerId);const pending = this.pendingRoutePreparations.get(roomId);if (!pending || this.pendingSessionsAreCurrent(roomId, pending)) {return;@@ -1304,6 +1341,7 @@ export class HybridMediaRouter {removeViewer(roomId: string, peerId: string): void {this.clearSelectedEdgeTurnsForParticipant(roomId, peerId);this.clearViewerQualityStateForParticipant(roomId, peerId);+ this.clearDeferredHealthySfuReselectionForParticipant(roomId, peerId);this.abortPendingRouteForTopologyChange(roomId);const changes = this.peerRelayTopology.removeViewer(roomId,@@ -3049,6 +3087,7 @@ export class HybridMediaRouter {this.selectedSfuIngressAttempts.delete(roomId);}this.activeSelectedSfuIngresses.delete(roomId);+ this.clearDeferredHealthySfuReselection(roomId);this.consumedSfuRefreshesByRoom.delete(roomId);this.sfuDisabledRoomIds.delete(roomId);this.clearRoomViewerQualityEvidenceStates(roomId);@@ -3105,6 +3144,104 @@ export class HybridMediaRouter {);}+ private deferHealthySfuReselection(+ participant: AuthenticatedRouteParticipant,+ activeRevision: number,+ shareGeneration: string,+ publicationGeneration: string,+ cooldownUntil: number,+ now: number,+ ): void {+ this.clearDeferredHealthySfuReselection(participant.roomId);+ const deferred: DeferredHealthySfuReselection = {+ activeRevision,+ shareGeneration,+ publicationGeneration,+ rootPeerId: participant.peerId,+ rootSessionId: participant.sessionId,+ timer: null,+ };+ const schedule = (delayMs: number) => {+ deferred.timer = setTimeout(reassert, Math.max(0, delayMs));+ deferred.timer.unref();+ };+ const reassert = () => {+ if (+ this.deferredHealthySfuReselections.get(participant.roomId) !== deferred+ ) {+ return;+ }+ deferred.timer = null;+ const currentTime = this.options.now?.() ?? Date.now();+ if (!Number.isFinite(currentTime)) {+ this.deferredHealthySfuReselections.delete(participant.roomId);+ return;+ }+ const currentCooldown =+ this.roomQualityMigrationCooldownUntilMs.get(participant.roomId) ?? 0;+ if (currentCooldown > currentTime) {+ schedule(currentCooldown - currentTime);+ return;+ }++ this.deferredHealthySfuReselections.delete(participant.roomId);+ const viewer = this.options.roomStore.getConnectedViewer(+ participant.roomId,+ deferred.rootPeerId,+ );+ const controller = this.mediaRouteControllers.get(participant.roomId);+ const active = controller?.getActiveRoute();+ const assignment = active?.assignments.get(deferred.rootPeerId);+ if (+ viewer?.sessionId !== deferred.rootSessionId ||+ !controller ||+ controller.getPendingRoute() ||+ this.roomPeerMigrationAttempt(participant.roomId) !== null ||+ active?.revision !== deferred.activeRevision ||+ active.sfu.publicationGeneration !== deferred.publicationGeneration ||+ active.sfu.rootPeerIds.length !== 1 ||+ active.sfu.rootPeerIds[0] !== deferred.rootPeerId ||+ assignment?.upstream.kind !== "sfu" ||+ this.options.getShareGeneration(participant.roomId) !==+ deferred.shareGeneration+ ) {+ return;+ }++ // Duplicate authority asks the Viewer for fresh media proof.+ this.options.sendToSession(deferred.rootSessionId, {+ type: "route-update",+ revision: active.revision,+ phase: "active",+ assignment,+ });+ };+ this.deferredHealthySfuReselections.set(participant.roomId, deferred);+ schedule(cooldownUntil - now);+ }++ private clearDeferredHealthySfuReselection(roomId: string): void {+ const deferred = this.deferredHealthySfuReselections.get(roomId);+ if (!deferred) {+ return;+ }+ if (deferred.timer) {+ clearTimeout(deferred.timer);+ }+ this.deferredHealthySfuReselections.delete(roomId);+ }++ private clearDeferredHealthySfuReselectionForParticipant(+ roomId: string,+ peerId: string,+ ): void {+ if (+ this.deferredHealthySfuReselections.get(roomId)?.rootPeerId === peerId+ ) {+ this.clearDeferredHealthySfuReselection(roomId);+ }+ }+private clearViewerQualityStateForParticipant(roomId: string,peerId: string,diff --git a/tests/route-transition.test.ts b/tests/route-transition.test.tsindex 27f5b508..e6815d7a 100644--- a/tests/route-transition.test.ts+++ b/tests/route-transition.test.ts@@ -1159,7 +1159,7 @@ describe("ViewerSfuRoute", () => {expect(subscriber.deactivate).not.toHaveBeenCalled();});- it("retries a sticky authoritative SFU route only after stable decoded RTP", async () => {+ it("re-proves a sticky SFU route after a cooldown-bound authority reassertion", async () => {const healthy: number[] = [];const messages: ClientMessage[] = [];let subscriber!: ReturnType<typeof createFakeSubscriber>;@@ -1217,6 +1217,21 @@ describe("ViewerSfuRoute", () => {intervalFramesDecoded: 1,} as ConnectionMetrics);expect(healthy).toEqual([7]);++ expect(route.accept({+ revision: 7,+ phase: "active",+ assignment: sfuAssignment(),+ })).toBe("duplicate");+ subscriber.events.onStats?.({+ intervalPacketsReceived: 3,+ intervalFramesDecoded: 2,+ } as ConnectionMetrics);+ subscriber.events.onStats?.({+ intervalPacketsReceived: 5,+ intervalFramesDecoded: 4,+ } as ConnectionMetrics);+ expect(healthy).toEqual([7, 7]);});it("switches on first SFU video and forwards loss across same-publication revision reuse", async () => {diff --git a/tests/server-signal.test.ts b/tests/server-signal.test.tsindex 2eb095e1..4ab7f5b2 100644--- a/tests/server-signal.test.ts+++ b/tests/server-signal.test.ts@@ -5203,8 +5203,12 @@ describe("WebSocket signaling", () => {expect(hostRecovery.assignment.sfuPublicationGeneration).toBeTruthy();});- it("rolls a failed healthy probe back to SFU and applies room cooldown", async () => {+ it("rolls back and reasserts one healthy ready after room cooldown", async () => {let now = 50_000;+ const reselections = vi.spyOn(+ HybridMediaRouter.prototype,+ "handleHealthySfuReselection",+ );const harness = await startSfuHarness({tokenIssuer: { async issueToken({ peerId }) { return `token-${peerId}`; } },prepareTimeoutMs: 200,@@ -5244,9 +5248,48 @@ describe("WebSocket signaling", () => {expect(rootRollback.assignment.upstream).toEqual({ kind: "sfu" });expect(hostRollback.assignment.sfuPublicationGeneration).toBeTruthy();- requestHealthyReselection(active.viewer, rootRollback.revision);- await expect(active.viewer.inbox.next("route-update", 40)).rejects.toThrow("Timed out");- now += 30_001;+ const router = reselections.mock.instances.at(-1) as+ | HybridMediaRouter+ | undefined;+ const currentViewer = harness.roomStore.getConnectedViewer(+ harness.room.roomId,+ active.viewerAuth.peerId,+ );+ expect(router).toBeDefined();+ expect(currentViewer).toBeDefined();+ const deferredState = (router as unknown as {+ deferredHealthySfuReselections: Map<+ string,+ { timer: NodeJS.Timeout | null }+ >;+ }).deferredHealthySfuReselections;+ vi.useFakeTimers();+ try {+ router!.handleHealthySfuReselection(+ {+ roomId: harness.room.roomId,+ role: "viewer",+ peerId: active.viewerAuth.peerId,+ sessionId: currentViewer!.sessionId,+ },+ rootRollback.revision,+ );+ const deferred = deferredState.get(harness.room.roomId);+ expect(deferred?.timer?.hasRef()).toBe(false);++ now += 30_001;+ await vi.advanceTimersByTimeAsync(30_000);+ expect(await active.viewer.inbox.next("route-update")).toMatchObject({+ revision: rootRollback.revision,+ phase: "active",+ assignment: { upstream: { kind: "sfu" } },+ });+ } finally {+ vi.useRealTimers();+ reselections.mockRestore();+ }++ // The real Viewer re-proves two fresh stats windows before this second ready.requestHealthyReselection(active.viewer, rootRollback.revision);const retried = await nextPreparedRoute(active.viewer);expect(retried.assignment.upstream).toEqual({@@ -5255,6 +5298,20 @@ describe("WebSocket signaling", () => {});const timedOut = await nextActiveRouteAfter(active.viewer, retried.revision);expect(timedOut.assignment.upstream).toEqual({ kind: "sfu" });++ router!.handleHealthySfuReselection(+ {+ roomId: harness.room.roomId,+ role: "viewer",+ peerId: active.viewerAuth.peerId,+ sessionId: currentViewer!.sessionId,+ },+ timedOut.revision,+ );+ expect(deferredState.has(harness.room.roomId)).toBe(true);+ active.host.socket.send(JSON.stringify({ type: "stop-sharing" }));+ await active.viewer.inbox.next("sharing-stopped");+ expect(deferredState.has(harness.room.roomId)).toBe(false);});it("does not swallow active SFU loss while a healthy probe is pending", async () => {