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. 免费开源的私密屏幕共享,支持游戏直播、一起看电影与自部署。

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.md
index 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 units
are released. Because joining cannot recreate a deleted room, a stale
self-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 participant
disappears. A multi-process application deployment requires a shared atomic
admission 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 media
proof;
- 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 generation
without cutting a live Host participant, and keep two rooms under one global
capacity owner;
- candidate lists are deterministic under input permutation, preserve a healthy
diff --git a/docs/deployment.md b/docs/deployment.md
index 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 room
tokens and do not provide E2EE: the LiveKit operator can access ordinary SFU
media. 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 one
application process until a shared atomic admission and lifecycle owner exists.
For the first candidate canary, use an isolated instance and a protected
persistent room whose ID is stable across restarts. Restart the application and
verify 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 shared
room state or capacity bypass. Exercise join, offer and answer, stale-token
reconnect after abort, Host signaling loss with and without a live Host
diff --git a/docs/research/low-server-media-routes.md b/docs/research/low-server-media-routes.md
index 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 disables
automatic room creation. Screener explicitly creates an exact-generation room
through `RoomService` before token issuance and uses `DeleteRoom` plus an absent
room 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 is
checked against the exact LiveKit Host participant on a bounded interval, so
healthy media stays charged while an abandoned generation is reclaimed after
the 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 且不能替换当前媒体。