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.mdindex 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-wideadmission. Resource exhaustion produces the next bounded candidate, an explicitwait, 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 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+ without cutting a live Host participant, and keep two rooms under one global+ capacity owner;- candidate lists are deterministic under input permutation, preserve a healthycurrent edge, prefer the shallowest least-loaded eligible parent, and try onlythe 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 acceptedaccounting under normal and migration overlap; and- every exhausted path reaches a clear bounded wait or failure without leakingdiff --git a/docs/deployment.md b/docs/deployment.mdindex 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 sourcedeployment contract. Product direction and pending migrations are owned by@@ -9,12 +9,13 @@ deployment contract. Product direction and pending migrations are owned byThis section documents the repository's UDP-only deployment candidate: oneNode.js process provides the built Web client, room API, and WebSocket signalingbehind 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 throughdirect 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 remainsICE/UDP only. Source no longer contains the rejected participant-wide Peer ICE TURNcandidate; 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 404without 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:```dotenvPEER_ASSISTED_MEDIA=trueLIVEKIT_URL=wss://share.example.com+LIVEKIT_API_URL=http://127.0.0.1:7880LIVEKIT_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 workmay 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 onwire `screener-v5`. Deploy the current source server, Web assets, and Nativesender atomically on `screener-v6`; restore the exact prior environment andrelease 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 acomplete tuple requires `PEER_ASSISTED_MEDIA=true` plus explicit positivesafe-integer `SFU_INGRESS_CAPACITY` and `SFU_EGRESS_CAPACITY` values. The twocapacities 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 thansilently enabling or ignoring a partial policy. An empty tuple with neithercapacity keeps the optional SDK and server path dormant. `LIVEKIT_URL` must be aplain `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 roomtokens 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 protectedpersistent 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 andNative-shaped clients remain STUN-only. With the selected-edge tuple, onlythe current controller-selected edge may receive a one-use grant; all othersessions 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 tupleindependently, and no removed oldTURN 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 usablare closed externally.2. Create a normal Screener room on two different networks. Confirm media flowsand 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 getsthe short-lived TURN server plus relay policy and selects TURN/UDP. Ordinarypeer PCs must stay STUN-only. Then block all UDP and verify bounded recoverydiff --git a/docs/research/low-server-media-routes.md b/docs/research/low-server-media-routes.mdindex 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)` anddescendant upload is `sum(B_edge)`. SFU host upload and ingress are `B_pub`, thesum 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 equalrepresentations, `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 aseparately 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 thatedge's actual bitrate. They are one logical useful payload copy but realphysical 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 oneingress unit and each authorized SFU subscription uses one egress unit. There isno built-in default or fixed root count. A candidate reserves its full actualingress/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 Screeningdiff --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 假设猜测实现。### 质量和恢复