Skip to content

armgit / Piik

Public Imported from GitHub
0

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

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.md
index 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 a
null connection; selected Host ingress must match its activated connection
identity. The rollback active revision then drives the existing one-refresh
recovery. 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 root
and only its parent retained in the deterministic peer baseline. The accepted
capacity `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 fields
live in [Low-Server-Cost Media Routes](../research/low-server-media-routes.md).
diff --git a/docs/project-memory.md b/docs/project-memory.md
index 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.md
index 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 Evidence
diff --git a/src/client/media/viewer-sfu-route.ts b/src/client/media/viewer-sfu-route.ts
index 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.ts
index 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.ts
index 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.ts
index 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 () => {