Free, open-source screen sharing for private live streams with friends. Watch together in a browser or self-host Piik. 免费开源的私密屏幕共享,支持游戏直播、一起看电影与自部署。
feat(routing): rescue blocked relay admission (#68)
AAA48f3b94fed0a
diff --git a/docs/adr/0004-peer-assisted-media-experiment.md b/docs/adr/0004-peer-assisted-media-experiment.mdindex 208d4076..65f2e9f9 100644--- a/docs/adr/0004-peer-assisted-media-experiment.md+++ b/docs/adr/0004-peer-assisted-media-experiment.md@@ -55,9 +55,11 @@ no UI, percentage rollout, or routing score.The signaling server assigns two sticky, balanced chains with a deterministicbreadth-first walk. The host has capacity for at most two children and eachviewer for at most one. Candidate parents are ordered by depth and server-issued-join sequence. Joining a viewer does not move existing assignments. If a parent-leaves, only its orphaned subtree root is assigned to the first available slot;-the root's descendants stay attached. No RTT, bandwidth, CPU, geography,+join sequence. Joining a viewer does not move existing assignments except for+ADR-0005's bounded admission rescue: an unassigned one-slot relay may replace+the oldest childless zero-capacity Host leaf when both Host slots are full. If a+parent leaves, only its orphaned subtree root is assigned to the first available+slot; the root's descendants stay attached. No RTT, bandwidth, CPU, geography,capability, or quality scoring is added.For this ADR, one media edge is one downstream `RTCPeerConnection` carrying thediff --git a/docs/adr/0005-automatic-hybrid-media-routing.md b/docs/adr/0005-automatic-hybrid-media-routing.mdindex c2023412..44a11e7f 100644--- a/docs/adr/0005-automatic-hybrid-media-routing.md+++ b/docs/adr/0005-automatic-hybrid-media-routing.md@@ -125,6 +125,18 @@ leaves and desktop-class browsers as one-child relays. The controller uses thisbinary capability only for future admission and recovery. Withdrawing capacitydoes not proactively migrate an otherwise healthy existing edge.+The source now implements one narrow admission exception to sticky assignment.+On an active peer-only route with no SFU publication or pending prepare, a+connected, childless Viewer that has no upstream or failed-parent history and+advertises one relay slot may replace the oldest connected, childless,+zero-capacity Host child when both Host slots are full. That leaf becomes the+new relay's only child. The synchronous change preserves Host fanout two,+browser fanout one and the depth bound, advances one route revision, and clears+both changed upstream connection generations. Host-side reconciliation closes+the stale child edge before starting the replacement. No healthy routed+candidate, quality score, timer, global parent penalty, or periodic rebalance is+part of this admission rescue.+The repository quality-reparent candidate adds one bounded parent-to-serverevidence message and no second route owner. Signaling authenticates andforwards Viewer C under its existing session, connection, revision, parent,@@ -152,7 +164,8 @@ The router may create the existing Viewer route intent;the subtree change, revision, generation, prepare, commit and rollback.Targeted tests cover the revision controller, protocol authorization, relay-capacity, ordered client transitions, stale asynchronous work, server-restart+capacity and deterministic admission rescue, ordered break-before-make client+transitions, stale asynchronous work, server-restartresynchronization, one-shot credential recovery, peer failback, and optionalstandby warming. The corrected cold Chrome 151/LiveKit 1.13.5 localhost run took1.481 seconds from failure report to active and 2.257 seconds to a new rendereddiff --git a/docs/project-memory.md b/docs/project-memory.mdindex e6c9fee0..3f1cfac8 100644--- a/docs/project-memory.md+++ b/docs/project-memory.md@@ -27,7 +27,7 @@ Last updated: 2026-08-20- Mobile Web Host is unsupported; feature-detect and fail clearly. Mobile Viewer stays leaf-only. After Windows native, gate Android 14+; iOS waits for stable iOS 27 ScreenCaptureKit.- ADR-0005 accepts direct-first Peer ICE and bounded SFU roots. Its default-off exact-room slice is undeployed; production/coturn stay STUN-only. PR #12/selected-edge superseded.- Keep the controller exact-room only: room `1` is the STUN/SFU smoke. Preserve sticky progressing P2P, mobile leaves and break-before-make. Recovery spends one attempt per layer (ICE restart, same-parent rebuild, alternate peer, then SFU), never three identical retries; active SFU gets one fresh grant before Peer failback.-- Quality reparenting needs three correlated C+B hard-bad windows and reuses the local-subtree peer/SFU/failure intent. Single-sided reports are diagnostic; one room cooldown blocks churn. No score, timer, or global parent penalty.+- C+B quality reparenting is edge-local and cooldown-bound; no score, timer, or global parent 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.- 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`.@@ -50,7 +50,7 @@ Last updated: 2026-08-20- Chrome 151/LiveKit localhost A/B cut failure-to-active/render from 1.481/2.257 seconds to 0.200/0.320; 31 new frames and 25 ms sampling kept host edges at two. It is headless synthetic 720p30 and includes SDK/network prewarm, not public-network evidence.- Chrome 151 synthetic topology/quality-control runs kept fanout 2/1 and all viewers decoding; one relay close recovered in 5.32 seconds. This is control evidence only.- Room `1` publishes `HIGH+LOW` with Dynacast off and subscriber `HIGH` ceilings, and now has bounded local quality reparenting. Both remain unverified on real media; test zero-child leaves and calibrated C+B loss before broad rollout.-- Generation-bound C+B needs three hard-bad windows; parent samples are one-use per connection. Pending SFU binds intent/guard. Stale/successful peer work releases quality exclusion; real failure may take it over. It uploads no raw endpoint metadata and computes no score.+- C+B uses three hard-bad pairs, one-use samples and guarded intent/cooldown. Source-only admission rescue moves the oldest childless zero-capacity Host leaf below an unassigned one-slot relay in one revision; focused/typecheck pass, real media unverified.- Undeployed Web name/presence leaves Native wire/media unchanged and separates Viewer roster from Host diagnostics; focused checks pass.## Provisional Quality Targetsdiff --git a/docs/research/advanced-peer-distribution.md b/docs/research/advanced-peer-distribution.mdindex 05000b34..c190ada1 100644--- a/docs/research/advanced-peer-distribution.md+++ b/docs/research/advanced-peer-distribution.md@@ -3,9 +3,9 @@- Research date: 2026-08-19- Scope: at most eight trusted viewers, sub-second interactive media, endpointdownstream fanout at most two, and minimal central-server media egress-- Status: candidate routes and bounded spike gates; only the Pion RTP- transport-fanout sub-oracle is implemented, with no advanced media route- integrated into Screener+- Status: bounded C+B local reparenting is deployed for one exact room and the+ deterministic admission-rescue slice is implemented source-only; advanced+ encoded-media routes remain isolated candidates## Terms@@ -235,6 +235,16 @@ freeze share, 100-packet floor, three windows, five-second gap and 30-secondcooldown are falsifiable candidate constants for production calibration, notstandards-derived or claimed optimum values.+The correlated pair can therefore attribute a problem only to the current+parent-to-child edge generation. It cannot prove that the parent is globally+bad: the remote-loss value is that child's RTCP report and+`qualityLimitationReason` belongs to one outbound video stream. LiveKit's pinned+server implementation deliberately reduces published-track and subscribed-+downtrack quality to a participant-wide minimum; that aggregate is useful for+conferencing UI but is not a directional P2P parent score. Screener consequently+excludes only the failed parent for the affected Viewer-rooted subtree and+releases the quality-owned exclusion after a successful move.+With host degree two and the current browser-relay degree one, two balancedchains already minimize maximum depth at `ceil(N/2)`. A tree for `N` viewersstill has `N` media edges, approximately `N*B` useful upload in aggregate, and@@ -243,10 +253,10 @@ not reduce either bandwidth quantity. Reordering an already balanced healthytree also cannot reduce depth; a move needs a discrete admission, path, TURN,relay-resource, recovery, or future native-capacity benefit.-The admission-rescue slice is limited to its discrete capacity case. If a-relay-capable viewer is unassigned because two zero-capacity roots, especially-mobile leaves, occupy both host slots, insert that viewer above one-deterministic childless root:+The source admission-rescue slice is limited to its discrete capacity case. If+a relay-capable viewer is unassigned because two zero-capacity roots,+especially mobile leaves, occupy both host slots, it inserts that viewer above+one deterministic childless root:```texthost -> new relay -> existing leaf@@ -254,15 +264,25 @@ host -> other root```This admits the waiting viewer while keeping host fanout two and browser relay-fanout one. It must pass the existing depth, codec, authorization, and recovery-gates; otherwise the controller proceeds to the ADR-0005 SFU-root fallback or-visible wait.--Eligibility is discrete: an active authenticated session, explicit relay+fanout one. The router permits it only on an active peer-only route with no SFU+publication or pending prepare, when the connected candidate currently has no+upstream or children, newly offers one relay slot, and has no failed-parent+history. The host must have exactly two children and the chosen child must be a+connected, childless, zero-capacity leaf. Existing server join order chooses the+oldest eligible leaf. One synchronous topology snapshot changes the host,+candidate, and leaf; one route revision replaces both upstream generations and+clears their old connection IDs. The Host reconciler closes every stale child+edge before starting replacement children, so its physical fanout does not+temporarily exceed two.++Eligibility remains discrete: an active authenticated session, explicit relaycapacity, compatible representation, a free downstream slot, acyclicity, and-depth/edge budgets; a candidate already in the tree must also have healthy-inbound media. For admission rescue, choose the eligible childless root by-server join order; do not probe or rank alternate paths. Broader experiments+depth/edge budgets. The implemented rescue never moves a candidate that already+has an upstream, never handles a failed-path intent, and never selects a root by+quality. An authenticated viewer can still lie about its relay capacity, so the+exact-room canary and ordinary route-failure recovery remain required; the lie+can cause at most this one local move before the candidate is no longer+unassigned. Broader experimentsmay react to a hard media failure, a reviewed threshold-crossing event fromcorrelated path evidence, or a proven native capacity change, but never acontinuous optimizer. Do not use a weighted score, UA/device model, IP@@ -379,6 +399,9 @@ Sources checked on 2026-08-20:[room defaults](https://github.com/livekit/client-sdk-js/blob/v2.22.0/src/room/defaults.ts),and [state reconciliation](https://github.com/livekit/client-sdk-js/blob/v2.22.0/src/room/Room.ts)- pinned implementation behavior, not a universal timeout prescription.+- [LiveKit server 1.13.5 participant quality aggregation](https://github.com/livekit/livekit/blob/v1.13.5/pkg/rtc/participant.go)+ and [connection scorer](https://github.com/livekit/livekit/blob/v1.13.5/pkg/sfu/connectionquality/scorer.go)+ - Apache-2.0; studied only, with no source copied.- [Jitsi Videobridge endpoint status defaults](https://github.com/jitsi/jitsi-videobridge/blob/master/jvb/src/main/resources/reference.conf)- first-transfer and inactivity reference values.- [SplitStream](https://www.microsoft.com/en-us/research/publication/splitstream-high-bandwidth-multicast-in-a-cooperative-environment/)diff --git a/docs/status.md b/docs/status.mdindex b88e2a11..af730f25 100644--- a/docs/status.md+++ b/docs/status.md@@ -24,7 +24,7 @@ also contains a no-go Native v2 candidate, but production does not run it.- Fallback prewarm is token-free and limited to room `1`; mobile/iPad viewers are leaves and healthy edges stay sticky.- 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.- Room `1` can publish exactly `HIGH+LOW` with Dynacast/backup codec off and subscriber `HIGH` ceilings; it has no retained real media frame.-- Room `1` quality reparenting needs three C+B hard-bad pairs, reuses peer/SFU/failure and has one room cooldown; single-side reports do nothing. Thresholds need calibration.+- Room `1` C+B reparenting remains uncalibrated; source-only admission rescue promotes an unassigned relay over one zero-capacity Host leaf without scores or periodic optimization.- Source-only roster; Native wire/media unchanged.## Verified Evidencediff --git "a/docs/\346\226\271\346\241\210\350\256\276\350\256\241.md" "b/docs/\346\226\271\346\241\210\350\256\276\350\256\241.md"index a39c6cd0..55ab497a 100644--- "a/docs/\346\226\271\346\241\210\350\256\276\350\256\241.md"+++ "b/docs/\346\226\271\346\241\210\350\256\276\350\256\241.md"@@ -394,7 +394,7 @@ Native v2 保持 STUN-only。该边界不增加 UI、用户选择或百分比框恢复目标按证据和成本逐级升级:短暂 `disconnected` 先观察同代 bytes/stats,`failed` 才执行一次 ICE restart;仍失败时重建一次相同 parent,再尝试不同的合格 peer parent,peer 候选耗尽后才申请 SFU。每个动作最多一次且成功即停,不实现“三次相同重试”。初始 `connecting`/`checking` 的软提示和硬窗口尚未实现;硬窗口必须先用移动网络实测确定,不能直接复用现有 3 秒恢复常量。已实现的 SFU active 失败只刷新一次短期 grant,第二次失败回到新 peer baseline。Host 只保留当前 route revision 的 `connect | source | video-publish | sender-config | audio-publish | transport` 枚举阶段作为本地事件提示,不上传原始错误、URL、token、candidate 或地址。-实验只实现一个由服务端确定的广度优先拓扑:host 最多两个 child,每名 viewer 最多一个 child,因此形成两条按加入顺序平衡的 sticky 链。父节点只按深度和 `serverJoinSequence` 选择第一个空 slot。新 viewer 加入时不搬动已有节点;parent 离开时只把失去 parent 的 subtree root 重新分配到第一个空 slot,其 descendants 保持连接。该规则不采集或组合 RTT、带宽、CPU、地理位置与质量评分,也不主动重平衡。没有 parent 时明确等待或拒绝,不能创建分享端第三条边。+实验只实现一个由服务端确定的广度优先拓扑:host 最多两个 child,每名 viewer 最多一个 child,因此形成两条按加入顺序平衡的 sticky 链。父节点只按深度和 `serverJoinSequence` 选择第一个空 slot。新 viewer 加入通常不搬动已有节点;唯一例外是纯 peer active route 没有 pending/SFU 时,无上游、无 child、无失败 parent 历史且刚声明一槽容量的 viewer,可在 Host 两槽已满时按加入序替换一个 childless、零容量 Host leaf,并把该 leaf 作为自己的唯一 child。Host 客户端先关闭旧 leaf edge 再启动新 relay edge,同一同步拓扑变更只推进一个 route revision。Parent 离开时仍只把失去 parent 的 subtree root 重新分配到第一个空 slot,其 descendants 保持连接。该规则不采集或组合 RTT、带宽、CPU、地理位置与质量评分,也不主动重平衡。没有 parent 时明确等待或拒绝,不能创建分享端第三条边。该 one-child 浏览器实验在深度四时只能覆盖八名观看者,不能证明 20 人能力。目标 20 人需要资源门禁通过的 relay `downstreamCapacity=2`(两棵深度四二叉树理论可容纳 30 人,但这只是可达性)或受独立中央 egress cap 约束的 SFU 例外;必须实测逐跳重编码、上行、延迟和故障半径。未通过时保持当前默认八人,不增加深度或 Host fanout 来凑容量。diff --git "a/docs/\351\234\200\346\261\202\347\220\206\350\247\243.md" "b/docs/\351\234\200\346\261\202\347\220\206\350\247\243.md"index 8776329c..f7f72313 100644--- "a/docs/\351\234\200\346\261\202\347\220\206\350\247\243.md"+++ "b/docs/\351\234\200\346\261\202\347\220\206\350\247\243.md"@@ -123,7 +123,7 @@### 一对多与带宽保护- Given 一名分享者和一至两名观看者,When 运行直接 P2P,Then 分享端为每人建立独立媒体边且总 fanout 不超过二。-- Given peer-assisted spike 分别运行 1、3、5、8 名观看者,When 用户加入、离开或 relay 失效,Then 服务端使用同一个确定性广度优先规则形成两条 sticky 链,只为新 viewer 或失去 parent 的 subtree root 分配 parent,不主动搬动其他节点;分享端在任何瞬间都不超过两个 child 且每名 viewer 不超过一个,没有可用 parent 时明确等待或拒绝,而不是增加分享端 fanout。+- Given peer-assisted spike 分别运行 1、3、5、8 名观看者,When 用户加入、离开或 relay 失效,Then 服务端使用同一个确定性广度优先规则形成两条 sticky 链,只为新 viewer 或失去 parent 的 subtree root 分配 parent;唯一的健康边搬动例外是:无上游的一槽 relay 在纯 peer active route、无 pending/SFU、Host 两槽已满时,按加入序把一个 childless、零容量 Host leaf 放到自己下游。分享端在任何瞬间都不超过两个 child 且每名 viewer 不超过一个;除此之外没有可用 parent 时明确等待或拒绝,不主动重平衡或增加分享端 fanout。- Given 一名分享者和八名观看者,When 在受控网络中运行已记录的质量档位,Then 记录每条边的拓扑深度、候选类型、码率、编码/解码负载、分享端与 relay 上行、首帧和玻璃到玻璃延迟;该条在真实矩阵完成前保持未验收。- Given candidate 将房间默认上限改为 20,When 在 exact-room 中连续运行 20 名观看者 30 分钟并注入 relay departure、重连和一个弱路径,Then 每名观看者持续解码、Host 下游边不超过二、每个 relay 不超过已验收能力、深度与故障半径有界、未受影响 subtree 不迁移,并记录端点/SFU 的 CPU、GPU、内存、上行、出口、帧率、丢包率、冻结和恢复;任一门槛失败时不得切换默认值。- Given peer-assisted host 鉴权或直播中连续修改质量设置,When 服务端校验其分辨率、FPS、码率和偏好,Then 只有 host 的完整有界设置被接受,last-wins 地应用到当前和以后建立的 relay child sender 以及启用的 SFU publisher;越界、缺字段和多余字段被拒绝,普通 P2P 的鉴权 wire 不新增该字段且不接受同步消息。diff --git a/src/client/pages/HostPage.tsx b/src/client/pages/HostPage.tsxindex a22ca363..efb167fd 100644--- a/src/client/pages/HostPage.tsx+++ b/src/client/pages/HostPage.tsx@@ -75,8 +75,8 @@ import type {} from "../types";import { HostPeer } from "../webrtc/host-peer";import {- limitMediaAssignment,MAX_HOST_MEDIA_CHILDREN,+ reconcileBoundedMediaChildren,} from "../webrtc/media-assignment";import { sourceSwitchNotice } from "./host-page-notices";@@ -757,23 +757,19 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {childPeerIds: string[],generation: number,): void {- const assignment = limitMediaAssignment(- { parentPeerId: null, childPeerIds },+ reconcileBoundedMediaChildren(+ peersRef.current.keys(),+ childPeerIds,MAX_HOST_MEDIA_CHILDREN,+ removePeer,+ (peerId) => {+ void startPeer(peerId, generation).catch((error: unknown) => {+ if (isCurrentGeneration(generation)) {+ setNotice(readableError(error));+ }+ });+ },);- const assignedChildren = new Set(assignment.childPeerIds);- for (const peerId of peersRef.current.keys()) {- if (!assignedChildren.has(peerId)) {- removePeer(peerId);- }- }- for (const peerId of assignedChildren) {- void startPeer(peerId, generation).catch((error: unknown) => {- if (isCurrentGeneration(generation)) {- setNotice(readableError(error));- }- });- }}function handleSignalMessage(diff --git a/src/client/webrtc/media-assignment.ts b/src/client/webrtc/media-assignment.tsindex c416cdc8..120f76cf 100644--- a/src/client/webrtc/media-assignment.ts+++ b/src/client/webrtc/media-assignment.ts@@ -17,6 +17,29 @@ export function limitMediaAssignment(};}+export function reconcileBoundedMediaChildren(+ currentPeerIds: Iterable<string>,+ nextChildPeerIds: readonly string[],+ maxChildren: number,+ removeChild: (peerId: string) => void,+ startChild: (peerId: string) => void,+): void {+ const nextPeerIds = new Set(+ limitMediaAssignment(+ { parentPeerId: null, childPeerIds: [...nextChildPeerIds] },+ maxChildren,+ ).childPeerIds,+ );+ for (const peerId of currentPeerIds) {+ if (!nextPeerIds.has(peerId)) {+ removeChild(peerId);+ }+ }+ for (const peerId of nextPeerIds) {+ startChild(peerId);+ }+}+export function viewerSignalMessage(peerAssisted: boolean,targetPeerId: string,diff --git a/src/server/hybrid-media-router.ts b/src/server/hybrid-media-router.tsindex 6aca6f8f..69eca4a8 100644--- a/src/server/hybrid-media-router.ts+++ b/src/server/hybrid-media-router.ts@@ -512,11 +512,27 @@ export class HybridMediaRouter {this.relayCapacitySessionsByRoom.set(participant.roomId, advertised);}advertised.set(participant.peerId, participant.sessionId);+ const controller = this.mediaRouteControllers.get(participant.roomId);+ const active = controller?.getActiveRoute();+ const routeIntent = this.viewerRouteIntentsByRoom+ .get(participant.roomId)+ ?.get(participant.peerId);+ const allowAdmissionRescue =+ downstreamEdges === 1 &&+ active?.sfu.publicationGeneration === null &&+ active.assignments.get(participant.peerId)?.upstream.kind === "none" &&+ controller?.getPendingRoute() === undefined &&+ !this.pendingRoutePreparations.has(participant.roomId) &&+ (routeIntent === undefined || routeIntent.failedParentPeerId === null) &&+ !this.failedParentPeerIdsByViewer.get(+ viewerConnectionKey(participant.roomId, participant.peerId),+ )?.size;const changes = this.peerRelayTopology.setViewerRelayCapacity(participant.roomId,participant.peerId,downstreamEdges,this.connectedPeerIds(participant.roomId),+ { rescueUnassignedRelay: allowAdmissionRescue },);if (changes.length > 0) {this.clearChangedConnectionIds(participant.roomId, changes);diff --git a/src/server/peer-relay-topology.ts b/src/server/peer-relay-topology.tsindex e99b6ff4..fb693023 100644--- a/src/server/peer-relay-topology.ts+++ b/src/server/peer-relay-topology.ts@@ -9,6 +9,10 @@ export interface MediaAssignmentChange {mediaAssignment: MediaAssignment;}+export interface RelayCapacityUpdateOptions {+ rescueUnassignedRelay?: boolean;+}+export const MAX_PEER_RELAY_DEPTH = 4;interface RelayViewer {@@ -87,6 +91,7 @@ export class PeerRelayTopology {peerId: string,downstreamEdges: RelayDownstreamEdges,connectedPeerIds: ReadonlySet<string>,+ options: RelayCapacityUpdateOptions = {},): MediaAssignmentChange[] {const room = this.rooms.get(roomId);const viewer = room?.viewers.get(peerId);@@ -95,12 +100,20 @@ export class PeerRelayTopology {}const before = snapshot(room);+ const previousDownstreamEdges = viewer.downstreamEdges;viewer.downstreamEdges = downstreamEdges;for (const [candidatePeerId, candidate] of orderedViewers(room)) {if (candidate.parentPeerId === null) {this.assignViewer(room, candidatePeerId, connectedPeerIds);}}+ if (+ options.rescueUnassignedRelay &&+ previousDownstreamEdges === 0 &&+ downstreamEdges === 1+ ) {+ this.rescueUnassignedRelay(room, peerId, connectedPeerIds);+ }return changedAssignments(before, snapshot(room));}@@ -284,6 +297,51 @@ export class PeerRelayTopology {children.splice(childIndex, 1);}}++ private rescueUnassignedRelay(+ room: RelayRoom,+ peerId: string,+ connectedPeerIds: ReadonlySet<string>,+ ): void {+ const hostPeerId = room.hostPeerId;+ const candidate = room.viewers.get(peerId);+ if (+ !hostPeerId ||+ !candidate ||+ !connectedPeerIds.has(hostPeerId) ||+ !connectedPeerIds.has(peerId) ||+ candidate.parentPeerId !== null ||+ candidate.childPeerIds.length !== 0 ||+ candidate.downstreamEdges !== 1 ||+ room.hostChildPeerIds.length !== downstreamCapacity(room, hostPeerId)+ ) {+ return;+ }++ const leafPeerId = room.hostChildPeerIds.find((childPeerId) => {+ const child = room.viewers.get(childPeerId);+ return (+ connectedPeerIds.has(childPeerId) &&+ child?.parentPeerId === hostPeerId &&+ child.childPeerIds.length === 0 &&+ child.downstreamEdges === 0+ );+ });+ if (!leafPeerId) {+ return;+ }++ const leaf = room.viewers.get(leafPeerId)!;+ const leafIndex = room.hostChildPeerIds.indexOf(leafPeerId);+ room.hostChildPeerIds.splice(leafIndex, 1, peerId);+ room.hostChildPeerIds.sort(+ (left, right) =>+ room.viewers.get(left)!.order - room.viewers.get(right)!.order,+ );+ candidate.parentPeerId = hostPeerId;+ candidate.childPeerIds.push(leafPeerId);+ leaf.parentPeerId = peerId;+ }}function findShallowestAvailableParent(diff --git a/tests/media-assignment.test.ts b/tests/media-assignment.test.tsindex eda386e0..ea2df928 100644--- a/tests/media-assignment.test.ts+++ b/tests/media-assignment.test.ts@@ -5,6 +5,7 @@ import {limitMediaAssignment,MAX_HOST_MEDIA_CHILDREN,MAX_VIEWER_MEDIA_CHILDREN,+ reconcileBoundedMediaChildren,viewerRestartMessage,viewerSignalMessage,} from "../src/client/webrtc/media-assignment.ts";@@ -40,6 +41,24 @@ describe("peer-assisted client assignment", () => {});});+ it("removes stale host edges before starting replacement children", () => {+ const operations: string[] = [];++ reconcileBoundedMediaChildren(+ new Set(["old-child", "kept-child"]),+ ["kept-child", "new-child", "overflow-child"],+ MAX_HOST_MEDIA_CHILDREN,+ (peerId) => operations.push(`remove:${peerId}`),+ (peerId) => operations.push(`start:${peerId}`),+ );++ expect(operations).toEqual([+ "remove:old-child",+ "start:kept-child",+ "start:new-child",+ ]);+ });+it("leaves ordinary viewer signaling untargeted", () => {expect(viewerSignalMessage(false, "host_12345678", offer)).toEqual({type: "signal",diff --git a/tests/peer-relay-topology.test.ts b/tests/peer-relay-topology.test.tsindex 3213388d..e69c8af9 100644--- a/tests/peer-relay-topology.test.ts+++ b/tests/peer-relay-topology.test.ts@@ -92,6 +92,87 @@ describe("PeerRelayTopology", () => {);});+ it("deterministically promotes an unassigned relay over the oldest zero-capacity host leaf", () => {+ const topology = new PeerRelayTopology();+ const peers = connected("host", "viewer-a", "viewer-b", "viewer-c");+ topology.setHost("room", "host", peers);+ for (const peerId of ["viewer-a", "viewer-b", "viewer-c"]) {+ topology.addViewer("room", peerId, peers);+ }++ const changes = topology.setViewerRelayCapacity(+ "room",+ "viewer-c",+ 1,+ peers,+ { rescueUnassignedRelay: true },+ );++ expect(changes.map(({ peerId }) => peerId)).toEqual([+ "host",+ "viewer-a",+ "viewer-c",+ ]);+ expect(topology.getAssignment("room", "host")).toEqual({+ parentPeerId: null,+ childPeerIds: ["viewer-b", "viewer-c"],+ });+ expect(topology.getAssignment("room", "viewer-c")).toEqual({+ parentPeerId: "host",+ childPeerIds: ["viewer-a"],+ });+ expect(topology.getAssignment("room", "viewer-a")).toEqual({+ parentPeerId: "viewer-c",+ childPeerIds: [],+ });+ expect(+ expectValidTree(+ topology,+ "room",+ "host",+ ["viewer-a", "viewer-b", "viewer-c"],+ ),+ ).toBe(2);++ const afterRescue = topology.getAssignments("room");+ topology.setViewerRelayCapacity("room", "viewer-c", 0, peers);+ expect(+ topology.setViewerRelayCapacity(+ "room",+ "viewer-c",+ 1,+ peers,+ { rescueUnassignedRelay: true },+ ),+ ).toEqual([]);+ expect(topology.getAssignments("room")).toEqual(afterRescue);+ });++ it("does not rescue admission through a host child that already owns a subtree", () => {+ const topology = new PeerRelayTopology();+ const peers = connected("host", "a", "b", "c", "d", "candidate");+ topology.setHost("room", "host", peers);+ topology.addViewer("room", "a", peers);+ topology.addViewer("room", "b", peers);+ topology.setViewerRelayCapacity("room", "a", 1, peers);+ topology.setViewerRelayCapacity("room", "b", 1, peers);+ topology.addViewer("room", "c", peers);+ topology.addViewer("room", "d", peers);+ topology.addViewer("room", "candidate", peers);+ const before = topology.getAssignments("room");++ expect(+ topology.setViewerRelayCapacity(+ "room",+ "candidate",+ 1,+ peers,+ { rescueUnassignedRelay: true },+ ),+ ).toEqual([]);+ expect(topology.getAssignments("room")).toEqual(before);+ });+it("does not migrate healthy edges when a relay withdraws capacity", () => {const topology = new PeerRelayTopology();const peers = connected("host", "viewer-a", "viewer-b", "viewer-c", "viewer-d");diff --git a/tests/server-signal.test.ts b/tests/server-signal.test.tsindex 59bd5742..647c3bc0 100644--- a/tests/server-signal.test.ts+++ b/tests/server-signal.test.ts@@ -1435,6 +1435,108 @@ describe("WebSocket signaling", () => {expect((await host.inbox.next("error")).code).toBe("FORBIDDEN");});+ it("rescues an unassigned relay in one bounded route generation", async () => {+ const harness = await startHarness({ peerAssistedMedia: true });+ const host = await openClient(harness.webSocketUrl);+ const hostAuth = peerAssisted(+ await authenticate(host, harness.room, "host", "rescue-host"),+ );+ const first = await openClient(harness.webSocketUrl);+ const firstAuth = peerAssisted(+ await authenticate(+ first,+ harness.room,+ "viewer",+ "rescue-first",+ null,+ ),+ );+ const second = await openClient(harness.webSocketUrl);+ const secondAuth = peerAssisted(+ await authenticate(+ second,+ harness.room,+ "viewer",+ "rescue-second",+ null,+ ),+ );+ const relay = await openClient(harness.webSocketUrl);+ const relayAuth = peerAssisted(+ await authenticate(+ relay,+ harness.room,+ "viewer",+ "rescue-relay",+ null,+ ),+ );+ expect(relayAuth.routeAssignment.upstream).toEqual({ kind: "none" });++ host.socket.send(+ JSON.stringify({+ type: "signal",+ targetPeerId: firstAuth.peerId,+ payload: {+ kind: "description",+ connectionId: "admission-rescue-old-generation",+ description: { type: "offer", sdp: "v=0\r\n" },+ },+ }),+ );+ await first.inbox.next("signal");++ relay.socket.send(+ JSON.stringify({ type: "relay-capacity", downstreamEdges: 1 }),+ );+ const [hostRoute, firstRoute, secondRoute, relayRoute] = await Promise.all([+ nextActiveRouteAfter(host, relayAuth.routeRevision),+ nextActiveRouteAfter(first, relayAuth.routeRevision),+ nextActiveRouteAfter(second, relayAuth.routeRevision),+ nextActiveRouteAfter(relay, relayAuth.routeRevision),+ ]);++ expect(+ new Set([+ hostRoute.revision,+ firstRoute.revision,+ secondRoute.revision,+ relayRoute.revision,+ ]),+ ).toEqual(new Set([relayAuth.routeRevision + 1]));+ expect(hostRoute.assignment).toMatchObject({+ upstream: { kind: "none" },+ childPeerIds: [secondAuth.peerId, relayAuth.peerId],+ sfuPublicationGeneration: null,+ });+ expect(firstRoute.assignment).toMatchObject({+ upstream: { kind: "peer", peerId: relayAuth.peerId },+ childPeerIds: [],+ });+ expect(secondRoute.assignment.upstream).toEqual({+ kind: "peer",+ peerId: hostAuth.peerId,+ });+ expect(relayRoute.assignment).toMatchObject({+ upstream: { kind: "peer", peerId: hostAuth.peerId },+ childPeerIds: [firstAuth.peerId],+ });+ expect(hostRoute.assignment.childPeerIds).toHaveLength(2);+ expect(relayRoute.assignment.childPeerIds).toHaveLength(1);++ first.inbox.ignore("route-update");+ first.inbox.ignore("media-assignment");+ first.socket.send(+ JSON.stringify({+ type: "route-failed",+ revision: firstRoute.revision,+ phase: "active",+ connectionId: "admission-rescue-old-generation",+ }),+ );+ await first.inbox.expectNone(30);+ });+it("keeps the P2P authenticated wire unchanged and forbids profile updates", async () => {const harness = await startHarness();const host = await openClient(harness.webSocketUrl);