Free, open-source screen sharing for private live streams with friends. Watch together in a browser or self-host Piik. 免费开源的私密屏幕共享,支持游戏直播、一起看电影与自部署。
docs(route): fence LiveKit cleanup behind listener ownership
AAAa30f9c2382af
diff --git a/docs/adr/0005-automatic-hybrid-media-routing.md b/docs/adr/0005-automatic-hybrid-media-routing.mdindex 28b317be..ecda2634 100644--- a/docs/adr/0005-automatic-hybrid-media-routing.md+++ b/docs/adr/0005-automatic-hybrid-media-routing.md@@ -204,11 +204,14 @@ follow-up lookup must prove the room absent before its ingress or egress unitsare released. Because joining cannot recreate a deleted room, a staleself-hosted token cannot produce an off-ledger participant.-Before accepting application traffic, the single owner lists its dedicated-LiveKit instance, rejects foreign room names, deletes every stale Screener room,-and confirms the owned namespace is empty. Graceful shutdown drains the same-namespace before forgetting counters. A Host signaling disconnect keeps a-committed generation charged while its exact LiveKit Host participant exists;+The single owner first binds the configured application listener exclusively;+a competing process that cannot bind makes no LiveKit control-plane call. While+bound but not initialized, HTTP returns `503` and no signaling upgrade handler+is installed. The owner then lists its dedicated LiveKit instance, rejects+foreign room names, deletes every stale Screener room, confirms the owned+namespace empty, and only then accepts application traffic. Graceful shutdown+drains the same namespace before forgetting counters. A Host signaling+disconnect keeps a committed generation charged while its exact LiveKit Host participant exists;an interval-bounded control-plane check retires it after that participantdisappears. A multi-process application deployment requires a shared atomicadmission and lifecycle owner before it may claim these values are@@ -236,8 +239,9 @@ Before a revised controller ships:- route changes preserve unaffected branches and never commit before mediaproof;- SFU lifecycle tests keep reserved, committed, and draining generations charged- until deletion plus absence proof, reject stale-token room recreation, fence- startup against stale or foreign rooms, reclaim an abandoned Host generation+ until deletion plus absence proof, reject stale-token room recreation, prove a+ competing listener owner makes no LiveKit call, fence startup against stale or+ foreign rooms, reclaim an abandoned Host generationwithout cutting a live Host participant, and keep two rooms under one globalcapacity owner;- candidate lists are deterministic under input permutation, preserve a healthydiff --git a/docs/deployment.md b/docs/deployment.mdindex ef51caee..51cfd646 100644--- a/docs/deployment.md+++ b/docs/deployment.md@@ -302,17 +302,22 @@ production permits plaintext only on loopback and otherwise requires `https:`.`SITE_ACCESS_PASSWORD`. These credentials authorize short-lived LiveKit roomtokens and do not provide E2EE: the LiveKit operator can access ordinary SFUmedia. The LiveKit instance is dedicated to this Screener process and has-`room.auto_create: false`. Before the HTTP listener accepts traffic, Screener-rejects any foreign room name, deletes every stale managed room, and confirms-the namespace empty. Each exact-generation room is then created before its token-is issued. Reserved, committed, and draining generations remain charged until+`room.auto_create: false`. Screener first binds the configured application+listener exclusively; a competing process that cannot bind makes no LiveKit+call. While bound but not initialized it returns `503` and has no signaling+upgrade handler. It then rejects any foreign room name, deletes every stale+managed room, confirms the namespace empty, and begins serving. Each+exact-generation room is then created before its token is issued. Reserved,+committed, and draining generations remain charged until`DeleteRoom` succeeds and a follow-up lookup proves absence. Run only oneapplication process until a shared atomic admission and lifecycle owner exists.For the first candidate canary, use an isolated instance and a protectedpersistent room whose ID is stable across restarts. Restart the application andverify startup removes a seeded stale managed LiveKit room before serving-traffic. Verify that both the persistent room and a second normal room contain+traffic. Hold the application port with another process and verify a competing+startup makes zero LiveKit calls. Verify that both the persistent room and a+second normal room contain`mediaMode: "peer-assisted"`, with independent route revisions and no sharedroom state or capacity bypass. Exercise join, offer and answer, stale-tokenreconnect after abort, Host signaling loss with and without a live Hostdiff --git a/docs/research/low-server-media-routes.md b/docs/research/low-server-media-routes.mdindex 48522ec2..f003ff5c 100644--- a/docs/research/low-server-media-routes.md+++ b/docs/research/low-server-media-routes.md@@ -559,9 +559,12 @@ used as resource-release proof. The dedicated LiveKit instance instead disablesautomatic room creation. Screener explicitly creates an exact-generation roomthrough `RoomService` before token issuance and uses `DeleteRoom` plus an absentroom readback as the only drain proof. A deleted room cannot be recreated by a-stale token when `room.auto_create` is false. At process startup, the one owner-rejects foreign room names, drains all stale Screener rooms, and confirms the-namespace empty before it admits a new generation. Host signaling loss is+stale token when `room.auto_create` is false. At process startup, the application+first acquires its configured listener; a competing process that cannot bind+performs no LiveKit operation. The bound owner returns `503` and installs no+signaling upgrade handler while it rejects foreign room names, drains all stale+Screener rooms, and confirms the namespace empty before it admits a new+generation. Host signaling loss ischecked against the exact LiveKit Host participant on a bounded interval, sohealthy media stays charged while an abandoned generation is reclaimed afterthe participant disappears.diff --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 a6f515cd..e4241186 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"@@ -370,6 +370,8 @@ Token-free SFU standby prewarm 保持可选且不创建 participant、publicatio## 自动路由设计+启动 owner fence 复用配置的应用监听地址:进程必须先完成独占 bind,绑定失败时不得调用 LiveKit;bind 成功但 LiveKit 初始化未完成时,HTTP 只返回 `503` 且不安装 signaling upgrade handler。唯一 owner 完成 foreign-room 拒绝、遗留 managed-room 删除和 empty readback 后,才开放 HTTP 与 signaling。这个顺序使重启或竞争进程不能在失去应用 owner 身份时清理仍在使用的 LiveKit room。+服务端维护每个房间唯一的版本化 route owner。候选 parent 可以形成图,但 committed media graph 必须无环;Host 没有 upstream,每名 Viewer 同时只有零或一个 active upstream,且每个 active Viewer 必须沿 peer edges 到达 Host 或沿当前 authoritative Host publication 到达 source。加入、容量释放、节点离开、当前边失败和已接受的 path-health evidence 才能触发一次有界重选,未受影响分支保持 sticky。Parent selection 使用硬过滤加字典序,不建立综合质量评分器。先拒绝 stale session、不可 source-reachable、成环、超深、无 sender/overlap slot、relay-ineligible、位于 failed-edge cooldown 或 server resource 未准入的候选;对剩余候选依次比较结果深度、分配后剩余稳态 sender slots、稳定加入顺序与 peer identity。controller 每次只 reserve/prepare 一个候选,使用该 `RTCPeerConnection` 自带的 ICE checklist/connectivity checks,再以 current-generation RTP、live track 与 decoded frame 验证;初次加入或 hard failure 采用达到 media-usable floor 的首个候选,soft-quality reparent 还需 quality owner 证明候选达到 recovery threshold 且优于仍健康旧 edge。失败先幂等清理候选再取下一个;受管 SFU room 完成删除证明前仍占 server capacity。应用不做 all-pairs ping、raw-IP/NAT/地理排名、周期探测或全房重平衡。一个 exact edge 的近期失败只进入该 edge 的有界 exclusion/cooldown,不污染其他路径。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 fac4f114..350e748a 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"@@ -109,6 +109,8 @@ SFU/TURN 的 publication、subscription、transport、server-resource accounting### P2P、SFU 与可选 TURN 兜底+- Given 一个应用进程已经持有配置的监听地址,When 另一个进程以相同地址启动,Then 竞争进程必须在任何 LiveKit list/delete/create 前因 bind 失败退出。Given owner 已 bind 但 LiveKit startup reconciliation 尚未完成,Then HTTP 只返回 `503` 且 signaling 不接受连接;只有 foreign-room 检查、managed-room 清场和 empty readback 全部成功后才开放服务。+- Given 两端网络允许 UDP 打洞,When 观看者加入,Then `getStats()` 显示选中的候选对不是 `relay`,且服务器没有承载媒体流量。- Given ordinary peer edge 被创建或重建,When 检查其 ICE 配置,Then 只包含部署 STUN,不包含预发给 participant、房间或普通 peer 的 TURN candidate。- Given route candidate、signal、recovery 或 commit 的 room/share/session/revision/assignment/connection/media-binding identity,及适用时 publication generation,任一不匹配,When 旧消息或异步结果到达,Then 该操作 fail closed 且不能替换当前媒体。