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): bind SFU admission to room lifecycle

AAA4469421e9173
diff --git a/docs/adr/0005-automatic-hybrid-media-routing.md b/docs/adr/0005-automatic-hybrid-media-routing.md
index c934349f..28b317be 100644
--- a/docs/adr/0005-automatic-hybrid-media-routing.md
+++ b/docs/adr/0005-automatic-hybrid-media-routing.md
@@ -184,19 +184,35 @@ SFU and TURN remain bounded fallback resources with independent deployment-wide
admission. Resource exhaustion produces the next bounded candidate, an explicit
wait, or failure; it never creates unbounded central fanout.
-For the single-process deployment, SFU admission is one injected in-memory
-authority with deployment-wide ingress and egress counters. Enabling LiveKit
-requires explicit positive safe-integer `SFU_INGRESS_CAPACITY` and
-`SFU_EGRESS_CAPACITY` values; neither has a product default and neither is
-derived from endpoint capacity, Viewer admission, or a fixed root count. One
-Host publication consumes one ingress unit and every SFU subscription consumes
-one egress unit. A concurrently media-producing candidate consumes its actual
-units in addition to the committed generation. The controller reserves against
-the exact room, share, and publication generation before token issuance,
-promotes that reservation at route commit, and idempotently releases it on
-abort, timeout, participant loss, share rollover, room stop, or room deletion.
-A multi-process application deployment requires a shared atomic admission
-authority before it may claim these values are deployment-wide.
+For the single-process deployment, SFU admission is one injected authority with
+deployment-wide ingress and egress counters. Enabling LiveKit requires explicit
+positive safe-integer `SFU_INGRESS_CAPACITY` and `SFU_EGRESS_CAPACITY` values;
+neither has a product default and neither is derived from endpoint capacity,
+Viewer admission, or a fixed root count. One Host publication consumes one
+ingress unit and every SFU subscription consumes one egress unit. A concurrent
+candidate and every generation still draining from LiveKit remain charged in
+addition to the committed generation.
+
+The accepted self-hosted deployment contract dedicates one LiveKit instance to Screener,
+sets `room.auto_create: false`, and gives the application an explicit private
+`LIVEKIT_API_URL`. The controller reserves the exact room, share, and publication
+generation, creates that managed LiveKit room through `RoomService`, and only
+then issues tokens. Commit moves the old generation to `draining`; abort,
+timeout, participant loss, share rollover, room stop, and room deletion move
+their generation to the same state. `RoomService.DeleteRoom` must complete and a
+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;
+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
+deployment-wide.
## Current Production Divergence
@@ -219,6 +235,11 @@ Before a revised controller ships:
signals, departure, rollback, and admission exhaustion;
- 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
+ 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
current edge, prefer the shallowest least-loaded eligible parent, and try only
the next eligible candidate after exact failure and idempotent cleanup;
@@ -231,6 +252,10 @@ Before a revised controller ships:
suspect/local-repair before drain while preserving unrelated sibling evidence;
- real-browser tests cover direct peer media, peer relay, server-assisted media,
selected transport when configured, failure, and recovery;
+- deployment preflight proves the LiveKit instance is dedicated, uses
+ `room.auto_create: false`, exposes `RoomService` only on its accepted private
+ control origin, and can drain its managed namespace before traffic or
+ rollback;
- measured endpoint upload and server ingress/egress prove the accepted
accounting under normal and migration overlap; and
- every exhausted path reaches a clear bounded wait or failure without leaking
diff --git a/docs/deployment.md b/docs/deployment.md
index 4e39efef..ef51caee 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -1,6 +1,6 @@
# Minimal Deployment
-Last verified against upstream documentation: 2026-08-21.
+Last verified against upstream documentation: 2026-08-22.
This page records exact release `9461e20` production facts and the current source
deployment contract. Product direction and pending migrations are owned by
@@ -9,12 +9,13 @@ deployment contract. Product direction and pending migrations are owned by
This section documents the repository's UDP-only deployment candidate: one
Node.js process provides the built Web client, room API, and WebSocket signaling
behind Caddy or nginx; application ICE advertises only STUN by default; LiveKit
-supplies bounded SFU-root capacity. Normal media remains distributed through
+supplies bounded SFU fallback capacity. Normal media remains distributed through
direct or peer edges whenever those paths work.
-A deployment may additionally provide one single-node LiveKit process as the
-current controller's automatic final media fallback. This capacity is dormant unless the complete
-`LIVEKIT_URL`/key/secret tuple is configured. It does not replace the P2P path,
+A deployment may additionally provide one dedicated single-node LiveKit process
+as the current controller's automatic final media fallback. This capacity is
+dormant unless the complete public URL, private API URL, key, secret, and capacity
+tuple is configured. It does not replace the P2P path,
the peer-assisted experiment, or required STUN discovery. LiveKit remains
ICE/UDP only. Source no longer contains the rejected participant-wide Peer ICE TURN
candidate; stale `PEER_ICE_TURN_*` keys fail startup even when blank. The
@@ -119,7 +120,10 @@ The optional same-host LiveKit layout needs no additional public hostname:
`LIVEKIT_URL=wss://share.example.com` and nginx proxies only current `/rtc/v1*`
requests to LiveKit. Retired `/rtc` and `/rtc/validate` endpoints return 404
without request-target logging. LiveKit's HTTP/WebSocket listener on TCP 7880 is
-private to nginx, while WebRTC media reaches LiveKit directly on UDP 7882.
+private to nginx and the Screener process uses
+`LIVEKIT_API_URL=http://127.0.0.1:7880` for `RoomService`; WebRTC media reaches
+LiveKit directly on UDP 7882. No unrelated application may create rooms on this
+instance, and its tracked configuration sets `room.auto_create: false`.
## Candidate boundary and rollback
@@ -217,6 +221,7 @@ To make automatic SFU fallback capacity available, add the complete tuple:
```dotenv
PEER_ASSISTED_MEDIA=true
LIVEKIT_URL=wss://share.example.com
+LIVEKIT_API_URL=http://127.0.0.1:7880
LIVEKIT_API_KEY=<GENERATED_LIVEKIT_API_KEY>
LIVEKIT_API_SECRET=<INDEPENDENT_SECRET_OF_AT_LEAST_32_BYTES>
SFU_INGRESS_CAPACITY=<MEASURED_DEPLOYMENT_INGRESS_COPIES>
@@ -274,15 +279,15 @@ consume a second copy, and an uncommitted selected carry does. Transition work
may reach only `min(C + 1, 3)`. A Host already sending three copies at `C=3`
must fail or wait before a fourth publication token or TURN grant is issued.
Supplying the removed `MAX_PEER_RELAY_DOWNSTREAM_EDGES`, even blank, fails
-startup. The fixed per-room SFU-root and selected-lease guards remain separate
-temporary server safety boundaries.
+startup. The room-wide selected-lease guard remains a temporary server safety
+boundary until per-edge TURN allocation admission replaces it.
Production release `9461e20` still runs the legacy Host-2/Browser-1 policy on
wire `screener-v5`. Deploy the current source server, Web assets, and Native
sender atomically on `screener-v6`; restore the exact prior environment and
release together when rolling back.
-The three `LIVEKIT_*` values must either all be absent or all be present, and a
+The four `LIVEKIT_*` values must either all be absent or all be present, and a
complete tuple requires `PEER_ASSISTED_MEDIA=true` plus explicit positive
safe-integer `SFU_INGRESS_CAPACITY` and `SFU_EGRESS_CAPACITY` values. The two
capacities have no defaults and must be selected from the instance's measured
@@ -291,23 +296,36 @@ capacity without the complete fallback configuration fails startup rather than
silently enabling or ignoring a partial policy. An empty tuple with neither
capacity keeps the optional SDK and server path dormant. `LIVEKIT_URL` must be a
plain `ws:` or `wss:` origin with no `/rtc` suffix; production requires `wss:`.
+`LIVEKIT_API_URL` must be a plain `http:` or `https:` origin with no path;
+production permits plaintext only on loopback and otherwise requires `https:`.
`LIVEKIT_API_SECRET` must contain at least 32 bytes and must not reuse
`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 current admission owner is one Screener process; run only one
-application process until a shared atomic ledger is implemented.
+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
+`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 that both that room and a second normal room contain
+verify startup removes a seeded stale managed LiveKit room before serving
+traffic. Verify that both the persistent room and a second normal room contain
`mediaMode: "peer-assisted"`, with independent route revisions and no shared
-room state. Exercise join, offer and answer, stop, reconnect, and room deletion
-in both rooms. Ordinary Web and
+room state or capacity bypass. Exercise join, offer and answer, stale-token
+reconnect after abort, Host signaling loss with and without a live Host
+participant, stop, restart, and room deletion in both rooms. Confirm each drain
+keeps capacity charged until the room is absent. Ordinary Web and
Native-shaped clients remain STUN-only. With the selected-edge tuple, only
the current controller-selected edge may receive a one-use grant; all other
sessions and connections remain STUN-only. Roll back by disabling application
-issuance before restoring the exact recorded pre-canary coturn/firewall baseline, or direct
-traffic to the unchanged old release. Do not treat disabling
+issuance, stopping Screener, and proving every managed LiveKit room absent before
+restoring the exact recorded application/LiveKit configuration and release; or
+direct traffic to the unchanged old instance. Restore the coturn/firewall
+baseline only after the application no longer issues its selected-edge grant.
+Do not treat disabling
`PEER_ASSISTED_MEDIA` alone as TURN rollback: disable the selected-edge tuple
independently, and no removed old
TURN wire is restored. During migration, remove the retired room-ID variable in
@@ -555,10 +573,10 @@ Run these checks from real external networks before calling the deployment usabl
are closed externally.
2. Create a normal Screener room on two different networks. Confirm media flows
and the selected-pair stats report a non-relay path when direct ICE succeeds.
-3. On a normal room, exhaust a peer route and verify the host plus at
- most two necessary roots select LiveKit UDP 7882. Peer descendants stay on
- ordinary direct UDP and Host/ordinary Browser Viewer downstream caps remain
- two/one.
+3. On a normal room, exhaust a peer route and verify exactly one Host
+ publication serves only the admitted SFU subscriptions over LiveKit UDP 7882.
+ Peer descendants stay on ordinary direct UDP and every non-server endpoint
+ obeys the configured `ENDPOINT_MEDIA_COPY_CAPACITY`.
4. Force one controller-eligible edge past SFU/UDP and verify only that edge gets
the short-lived TURN server plus relay policy and selects TURN/UDP. Ordinary
peer PCs must stay STUN-only. Then block all UDP and verify bounded recovery
diff --git a/docs/research/low-server-media-routes.md b/docs/research/low-server-media-routes.md
index 4db1003a..48522ec2 100644
--- a/docs/research/low-server-media-routes.md
+++ b/docs/research/low-server-media-routes.md
@@ -85,7 +85,7 @@ useful last-hop delivery is approximately `N*B`. Ignoring protocol overhead:
| --- | ---: | ---: | ---: |
| Peer roots, direct edges | `R*B` | `D*B` | none |
| Peer roots, all `R` seed edges through TURN | `R*B` | `D*B` | TURN ingress `R*B` + egress `R*B` |
-| SFU virtual parent to the same roots | `B_pub` | `D*B` | SFU ingress `B_pub` + egress `sum(B_i)` |
+| SFU virtual parent to the same relay seeds | `B_pub` | `D*B` | SFU ingress `B_pub` + egress `sum(B_i)` |
| Same-representation full-room SFU | `B` | `0` | SFU ingress `B` + egress `N*B` |
The table's `R*B` and `D*B` rows are equal-representation screening cases with
@@ -94,9 +94,9 @@ With mixed root representations, direct peer-root traffic is `sum(B_i)` and
descendant upload is `sum(B_edge)`. SFU host upload and ingress are `B_pub`, the
sum of all actively published representations; if simulcast `HIGH` and `LOW`
both remain active, that may be `B_HIGH+B_LOW`, not one root bitrate. The
-SFU-root row, not full-room SFU, is the retained fallback shape. For equal
+SFU-fed relay-seed row, not full-room SFU, is the retained fallback shape. For equal
representations, `B_pub = B` and `sum(B_i) = R*B`. Publisher-to-SFU and every
-SFU-to-root subscriber transport are independent ICE connections and may use a
+SFU-to-seed subscriber transport are independent ICE connections and may use a
separately deployed LiveKit transport. Ordinary descendants are STUN-only;
selected coturn is issued only for an exact authorized edge or Host-SFU ingress.
If a
@@ -107,7 +107,7 @@ ingress and egress `B_i`; a selected-edge relay adds both directions for that
edge's actual bitrate. They are one logical useful payload copy but real
physical hops, so NIC, service, and billing counters must never be folded.
-If `E>0`, SFU root/exception egress is
+If `E>0`, SFU relay-seed/exception egress is
`sum(B_i) + sum(B_exc,j)` and central SFU traffic is
`B_pub + sum(B_i) + sum(B_exc,j)`. Peer descendant upload remains
`sum(B_edge)`. Any separately TURN-relayed LiveKit subscription or
@@ -548,11 +548,23 @@ configured positive safe-integer capacities: each Host publication uses one
ingress unit and each authorized SFU subscription uses one egress unit. There is
no built-in default or fixed root count. A candidate reserves its full actual
ingress/egress demand under exact room/share/publication identity before any
-token is issued; concurrent old and candidate generations are both charged.
-Commit promotes the candidate and releases the superseded generation. Abort,
-timeout, disconnect, share rollover, room stop, and room deletion use the same
-idempotent release. Capacity exhaustion leaves the current route unchanged and
-returns control to the bounded fallback sequence.
+token is issued; reserved, committed, and draining generations are all charged.
+Capacity exhaustion leaves the current route unchanged and returns control to
+the bounded fallback sequence.
+
+Self-hosted LiveKit does not revoke an old token when a participant is removed,
+and token expiry governs connection admission rather than terminating an
+existing participant. A route commit or client disconnect therefore cannot be
+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
+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.
These capacities are operator inputs derived from the actual instance, codec,
representation, bitrate, and accepted concurrency matrix. LiveKit's published
@@ -563,8 +575,10 @@ counters would not be deployment-wide admission.
Primary sources accessed 2026-08-22:
- [LiveKit benchmarking](https://docs.livekit.io/transport/self-hosting/benchmark/)
-- [LiveKit server configuration sample](https://github.com/livekit/livekit/blob/master/config-sample.yaml)
+- [LiveKit 1.13.5 server configuration sample](https://github.com/livekit/livekit/blob/v1.13.5/config-sample.yaml)
- [LiveKit access tokens and room configuration](https://docs.livekit.io/frontends/reference/tokens-grants/)
+- [LiveKit RoomService API](https://docs.livekit.io/reference/other/roomservice-api/)
+- [LiveKit server SDK 2.17.0 RoomServiceClient](https://github.com/livekit/node-sdks/blob/livekit-server-sdk%402.17.0/packages/livekit-server-sdk/src/RoomServiceClient.ts)
## Route Screening
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 f5fbce05..a6f515cd 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"
@@ -372,11 +372,11 @@ Token-free SFU standby prewarm 保持可选且不创建 participant、publicatio
服务端维护每个房间唯一的版本化 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。失败释放 reservation 后才取下一个。应用不做 all-pairs ping、raw-IP/NAT/地理排名、周期探测或全房重平衡。一个 exact edge 的近期失败只进入该 edge 的有界 exclusion/cooldown,不污染其他路径。
+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,不污染其他路径。
所有非服务器端点共享一个 server-authoritative steady outbound media-copy capacity:唯一配置 `ENDPOINT_MEDIA_COPY_CAPACITY` 默认 `2`,只接受 `1`、`2` 或 `3`,不兼容旧键。peer child 或 Host publication 各占一份,upstream receive 免费,committed selected TURN 只替换同一份 edge transport;SFU subscriber egress 与 TURN allocation 使用独立 server admission。客户端 capability 只能收紧该值,不能按角色、浏览器、UA、设备或页面可见性建立另一套 policy。服务端通过 v6 `authenticated.endpointMediaCopyCapacity` 把最终值交给 Web 与 Native;Native 不从 `maxViewers` 推导发送预算,普通 admission、peer-assisted child assignment 和槽位分配共用该值。代码通过一个 shared accounting guard 执行,不在 Host、Viewer、active、recovery 或 migration 分支重复 magic number;client/server/native wire 随该能力原子升级。首个迁移波次在独立 server admission 就绪前保留现有 SFU subscriber 与 room-wide selected-lease 安全护栏,但不把其固定值当作产品 policy;`C=3` 满载时必须在发出会产生第四份 Host media copy 的 token/grant 前明确等待或失败。
-SFU admission 在应用单进程中只有一个注入实例。LiveKit credential tuple 完整时,`SFU_INGRESS_CAPACITY` 与 `SFU_EGRESS_CAPACITY` 都必须显式配置为正 safe integer;它们没有产品默认值,也不从 Viewer 数、endpoint cap 或历史 root 数推导。账本只保存全局已用计数和按 exact room/share/publication generation 索引的 `reserved | committed` 条目:Host publication 计 ingress `1`,每个订阅计 egress `1`,候选与旧 generation 并存时按实际副本同时计数。route controller 先 reserve,再 prepare 和签发 token;media proof 后 commit candidate 并释放同房旧 generation,任何失败、超时、失联、分享换代、停止或删房都调用同一幂等 release。所有操作是 Map lookup 与整数加减,不扫描房间或参与者。当前切片不实现 TURN allocation admission,不改 parent selection,也不预建多进程协调;多应用进程部署必须先增加共享原子 owner。
+SFU admission 在应用单进程中只有一个注入实例。LiveKit credential tuple 完整时,必须同时显式配置私有 `LIVEKIT_API_URL`、正 safe integer `SFU_INGRESS_CAPACITY` 与 `SFU_EGRESS_CAPACITY`;容量没有产品默认值,也不从 Viewer 数、endpoint cap 或历史 root 数推导。专用 LiveKit 实例设置 `room.auto_create: false`。账本只保存全局已用计数和按 exact room/share/publication generation 索引的 `reserved | committed | draining` 条目:Host publication 计 ingress `1`,每个订阅计 egress `1`,candidate、committed 和未完成 drain 的旧 generation 同时计数。route controller 先 reserve,再通过 `RoomService.CreateRoom` 创建 exact-generation room,成功后才 prepare 和签发 token;media proof 后 commit candidate 并把旧 generation 转入 draining,失败、超时、失联、分享换代、停止或删房也只转入同一状态。只有 `RoomService.DeleteRoom` 成功且 follow-up lookup 证明 room 不存在,账本才扣除对应资源;auto-create 关闭后,旧 token 不能重建已删除 room。进程启动在接受流量前拒绝任何非 Screener room,删除全部遗留 Screener room 并确认 namespace 为空;关闭时先 drain 再遗忘计数。Host 信令离线期间若 exact room 中的 Host participant 仍存在就继续计费并保留健康媒体,participant 消失后在一个有界轮询周期内回收。稳态 reserve/commit/drain bookkeeping 仍是 Map lookup 与整数加减;只有 generation 创建、删除、启动清场和 Host 离线检查访问 LiveKit control plane。当前切片不实现 TURN allocation admission,不改 parent selection,也不预建多进程协调;多应用进程部署必须先增加共享原子 admission/lifecycle owner。
普通 Web relay 把收到的 remote track 加入独立 downstream `RTCPeerConnection`,因此可能逐跳解码和重编码;浏览器不保证跨连接 shared encode。每条 ordinary child 是独立网络副本,实际 encode time、CPU/GPU、bitrate、loss、frame rate、depth 和 recovery 必须测量。
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 50f04f45..fac4f114 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"
@@ -52,7 +52,7 @@ SFU/TURN 的 publication、subscription、transport、server-resource accounting
- 原生 shared encode relay:具备原生 relay 能力的非服务器端点同样受统一服务端权威下游容量约束,并应复用兼容编码输出而不再次编码。当前普通浏览器 relay 使用逐边重编码的标准 WebRTC 路径,不伪称 shared encode。
- SVC 重开条件:当前标准 Web/LiveKit SVC 已静态拒绝为 `no-go-web-svc-cross-path-hardware-contract`。sender `scalabilityMode` 没有 direct/peer receiver 对应的按层选择或跨 PeerConnection shared-encode 契约;requested/applied mode、Media Capabilities `powerEfficient` 和 RTCStats encoder 字段也不能证明没有静默软件 fallback。Pinned client 2.22.0 还会把 screen-share SVC 覆盖为三层 temporal-only `L1T3`,不满足低分辨率 base 与最多两层。只有未来 native sender 能明确选择硬件编码器、最多发布两层、将同一编码输出复用于 direct/peer/SFU、保持每条路径独立选择并通过真实游戏和亚秒延迟门槛时,才可用新的 capability decision 重开 SVC;不能把浏览器 API 支持或 UA 推断当成采用理由。
- 分包/分层多树实验:把编码包、对象或可独立解码层拆到多个 peer 路径以分散上传,只能在独立 spike 中验证。必须保持亚秒级,处理多父重组、排序、丢包恢复、关键帧、同步和节点退出;未通过门槛前不进入产品路由控制器。
-- SFU/TURN 中央兜底:产品部署可以提供有界 SFU 与可选 TURN 资源,但不要求用户选模式,也不得默认变成整房 always-SFU。只有 Host 拥有一个 authoritative publication;SFU-fed Viewer 具备独立出站证明时才可继续 relay,严格受限 Viewer 保持 leaf。TURN 是某条授权 logical edge 或 Host-SFU ingress 的 selected transport,不是拓扑节点。启用 LiveKit fallback 时必须显式提供无默认值的正整数 `SFU_INGRESS_CAPACITY` 与 `SFU_EGRESS_CAPACITY`;一份 Host publication 占一个 ingress,每份 SFU subscription 占一个 egress,实际并行 candidate 另占资源。单进程部署由一个 O(1) 全局账本在发 token 前按 exact room/share/publication fence reserve,commit 后替换旧 generation,abort、timeout、disconnect、share rollover、room stop/delete 都幂等释放。固定 root 数和普通端点 child 数都不能代替该准入;资源耗尽进入下一条有界候选、明确等待或失败。多应用进程部署必须先引入共享原子账本,不能把各进程本地计数相加冒充全局准入。
+- SFU/TURN 中央兜底:产品部署可以提供有界 SFU 与可选 TURN 资源,但不要求用户选模式,也不得默认变成整房 always-SFU。只有 Host 拥有一个 authoritative publication;SFU-fed Viewer 具备独立出站证明时才可继续 relay,严格受限 Viewer 保持 leaf。TURN 是某条授权 logical edge 或 Host-SFU ingress 的 selected transport,不是拓扑节点。启用 LiveKit fallback 时必须使用专用且关闭 `room.auto_create` 的实例,并显式提供私有 `LIVEKIT_API_URL`、无默认值的正整数 `SFU_INGRESS_CAPACITY` 与 `SFU_EGRESS_CAPACITY`;一份 Host publication 占一个 ingress,每份 SFU subscription 占一个 egress,reserved、committed 和 draining generation 都计入容量。单进程全局账本在发 token 前按 exact room/share/publication fence reserve,并先通过 RoomService 创建对应 room;commit、abort、timeout、disconnect、share rollover、room stop/delete 只把 generation 转入 draining,只有 DeleteRoom 成功和 absent readback 才释放计数。启动时必须先拒绝外来 room、清除全部遗留 Screener room 并确认 namespace 为空;Host 信令离线但 LiveKit participant 仍存在时继续保留和计费,participant 消失后有界回收。固定 root 数和普通端点 child 数都不能代替该准入;资源耗尽进入下一条有界候选、明确等待或失败。多应用进程部署必须先引入共享原子 admission/lifecycle owner,不能把各进程本地计数相加冒充全局准入。
- 分享端桌面封装:用 Electron 固定 Chromium 版本、改善选源/热键/系统音频体验,同时保留 Web 观看端。
- Windows 应用音频:Windows 11 Native sender 使用本地 opaque window target 绑定 HWND、PID 与进程创建时间,只捕获所选游戏及其子进程的音频,避免把语音聊天或通知声一并分享;“全部系统声音”只能由分享者显式选择。普通 Windows 10 不具备当前 process-loopback API 门槛,必须明确标为未解决/不支持而不是伪兼容。浏览器无法证明或隔离任意进程音频时必须如实提示,原生捕获失败、无声或进程退出不得静默扩大为整机捕获。
- 受限网络增强:短期鉴权 TURN 只有在完整、默认关闭的部署配置和当前 route controller 明确授权时可用;普通 peer PC 从创建起保持 STUN-only,不得向整个 participant、房间或所有 peer connections 预发 TURN candidates。凭据必须绑定 exact room/share/session/route/connection generation,短期有效、内存态、受配额约束且不进入 URL、日志、浏览器持久化或 SQLite。TURN 只替换授权 edge 的 transport;Host 无 direct first-level path 时可作为单条 Host-SFU ingress 的 transport。TURN 不得被描述为更高清的传输方式。
@@ -114,7 +114,7 @@ SFU/TURN 的 publication、subscription、transport、server-resource accounting
- Given route candidate、signal、recovery 或 commit 的 room/share/session/revision/assignment/connection/media-binding identity,及适用时 publication generation,任一不匹配,When 旧消息或异步结果到达,Then 该操作 fail closed 且不能替换当前媒体。
- Given 新路线正在准备,When 尚未同时证明当前代 live track、正 RTP 与 decoded-frame progress,Then 旧路线保持权威;证明后只原子提交 exact candidate,失败或超时销毁候选并保留或恢复旧路线。
- Given 所有已接受且已配置的媒体路径耗尽,When 有界连接窗口结束,Then 界面显示通用等待或连接失败,不静默黑屏、不长时间假连接,也不尝试未授权路径。SFU/TURN 的精确 path order 和 resource accounting 按 ADR-0005 验证。
-- Given 同一 committed graph 和候选集合以不同枚举顺序输入 controller,When 新 Viewer 加入或 exact failed edge 触发换父,Then 硬过滤结果相同,选择稳定落到最浅且分配后剩余容量最多的合格 parent,并以加入顺序和 peer identity 打破平局;健康 current edge 不因出现更优候选而迁移。Given 第一候选 ICE 或媒体证明失败,Then 它的 reservation 先幂等释放,之后才尝试下一候选,且不会启动 all-pairs probe。
+- Given 同一 committed graph 和候选集合以不同枚举顺序输入 controller,When 新 Viewer 加入或 exact failed edge 触发换父,Then 硬过滤结果相同,选择稳定落到最浅且分配后剩余容量最多的合格 parent,并以加入顺序和 peer identity 打破平局;健康 current edge 不因出现更优候选而迁移。Given 第一候选 ICE 或媒体证明失败,Then controller 先幂等清理该候选再尝试下一候选,且不会启动 all-pairs probe;若候选创建了受管 SFU room,其 server capacity 在删除并证明 room 不存在前仍计费。
- Given owned endpoint-dependent NAT emulator 中 ordinary ICE 可重复失败,When isolated guessed-candidate harness 运行,Then 只有满足[低服务器成本媒体路由](./research/low-server-media-routes.md)的 candidate budget、双浏览器重复性、首帧 deadline、隐私和 cleanup gate 才可继续。门禁前 ordinary room 不接收 guessed candidate;门禁后也只允许一个人工批准的 operator-owned test room,在双方 endpoint 显式同意、default-off kill switch 以及 exact room/edge/ICE-generation/deadline/aggregate-budget 约束下运行 canary。任何失败都关闭该候选并保留现有 SFU/TURN fallback。
### 浏览器与移动端观看
@@ -139,7 +139,7 @@ SFU/TURN 的 publication、subscription、transport、server-resource accounting
- Given ADR-0004 的任一硬门槛只有在引入 Encoded Transform/DataChannel/WebCodecs 媒体、自定义拥塞控制、FEC/RTX、多树、综合评分、转码、codec ladder、浏览器 RTP 注入 hack 或放宽 endpoint capacity 后才能满足,When 结束 bounded spike,Then 放弃并删除该浏览器 relay 实验路径,保留标准 P2P 与整体路由模型已接受的 fallback;后续 native shared encode sender 仍按独立 ADR 推进,但不能据此把失败的 relay 拓扑判为通过。
- Given 新观看者会使预计总上行超过安全预算,When 其请求加入,Then 系统只选择整体路由模型已授权且满足配置容量与资源准入的路径;没有合格路线时明确等待或拒绝,而不是创建超过配置容量的 ordinary edge 或持续堆积发送队列。各 transport 的拥塞控制适应该路径,应用证据只改变拓扑资格,不能合成全房降档。
- Given SFU 或 TURN 参与路线,When 计算准入、迁移 overlap 或失败恢复,Then 同时检查统一端点容量和独立的 server ingress/egress、SFU、TURN 资源预算;不得把普通端点 child 数当作 server cap,也不得借兜底形成无界整房 fanout。
-- Given 配置完整 LiveKit credential tuple,When `SFU_INGRESS_CAPACITY` 或 `SFU_EGRESS_CAPACITY` 缺失、非正整数或超出 JavaScript safe-integer 范围,Then 服务必须在启动时 fail closed。Given 两项均有效,When 当前 committed 与 reserved 的 ingress 或 egress 会越过任一部署容量,Then controller 必须在签发任何新 SFU token 前拒绝该 candidate,并保持旧 route 和计数不变。
+- Given 配置完整 LiveKit credential tuple,When `LIVEKIT_API_URL` 缺失或不是允许的 control-plane origin,或 `SFU_INGRESS_CAPACITY` / `SFU_EGRESS_CAPACITY` 缺失、非正整数或超出 JavaScript safe-integer 范围,Then 服务必须在启动时 fail closed。Given 配置有效,When startup listing 出现非 Screener room、遗留 room 无法删除、删除后仍存在,或 exact candidate room 无法显式创建,Then 应用不得签发 token 或接受可能重复计算的 SFU generation。Given 当前 reserved、committed 与 draining 的 ingress 或 egress 会越过任一部署容量,Then controller 必须在签发任何新 SFU token 前拒绝该 candidate,并保持旧 route 和计数不变。Given generation 被 commit、abort、timeout、stop、delete 或 Host participant 离线回收,When DeleteRoom 尚未成功或 absent readback 尚未完成,Then 它必须继续占用账本资源且旧 token 不能创建 room。
- Given Host、relay parent 或 leaf 处于受限网络,When direct/peer 路径不足,Then 只执行 ADR-0005 授权的 publisher、subscriber、selected transport 和 fallback sequence;不得靠未授权的固定数量或静态 lease 假设猜测实现。
### 质量和恢复