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: record current routing lifecycle and rollout (#178)

AAA7f32dd16df6a
diff --git a/docs/adr/0005-automatic-hybrid-media-routing.md b/docs/adr/0005-automatic-hybrid-media-routing.md
index 82096531..3fd2e9eb 100644
--- a/docs/adr/0005-automatic-hybrid-media-routing.md
+++ b/docs/adr/0005-automatic-hybrid-media-routing.md
@@ -100,9 +100,12 @@ LiveKit/coturn tuple proves the active Host/SFU relay route; initial Host ingres
and `peer-selected` relay media remain open.
The wire has two explicit edge kinds: `peer-selected` for the last-mile failed
peer edge and `host-sfu-ingress` for a restricted Host-to-SFU retry. Ordinary
-Peer ICE remains STUN-only. Each room admits at most one pending or answered
-`peer-selected` attempt; `host-sfu-ingress` is an independent source transport
-attempt and does not consume that last-mile admission slot.
+Peer ICE remains STUN-only. Each room admits at most one `peer-selected` lease
+across its negotiating and answered states; `host-sfu-ingress` is an independent
+source transport attempt and does not consume that last-mile admission slot. A
+negotiating lease is a selected-edge migration attempt. After answer it becomes
+the exact edge's long-lived active transport authority, not a room-wide
+migration lock.
The current runtime removes the old all-room coturn contract. Production
requires STUN and authenticated ICE snapshots contain only STUN servers in
@@ -541,14 +544,17 @@ healthy room. Only these discrete events open one opportunity:
windows with positive current-generation RTP and decoded-frame progress.
2. A connected Viewer advertises relay capacity transitioning from zero to one.
-One room owns at most one peer migration attempt: either one healthy probe or
-one pending/answered `peer-selected` attempt. It may overlap active media only
-when `Host peer children + active SFU publication + probe <= 2` and `browser
-relay children + probe <= 1`. Without a free slot the opportunity is consumed
-and the active route is left unchanged. The probe is bound to the current
-share/publication, active and pending revisions, root, parent and Host sessions,
-and one pinned connection ID. Signaling from any other pair or generation fails
-closed.
+One room owns at most one soft peer migration attempt. A healthy or quality
+probe and a negotiating `peer-selected` lease are serialized. An answered exact
+edge lease is active transport and may coexist with an unrelated soft migration;
+each route change first revalidates its share, endpoint sessions, topology and
+parent downstream budget, then sends the carry grant before active route
+authority. A soft probe may overlap active media only when `Host peer children +
+active SFU publication + probe <= 2` and `browser relay children + probe <= 1`.
+Without a free slot the opportunity is consumed and the active route is left
+unchanged. The probe is bound to the current share/publication, active and
+pending revisions, root, parent and Host sessions, and one pinned connection
+ID. Signaling from any other pair or generation fails closed.
During prepare the Viewer keeps rendering SFU while the existing peer parent
creates one provisional edge. ICE `connected` is insufficient. The Viewer
diff --git a/docs/deployment.md b/docs/deployment.md
index 9f67d3c7..1cdfa305 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -20,9 +20,9 @@ tracked coturn example remains `stun-only`; the shared host retains its older
authenticated-relay daemon configuration and firewall range. The application
does not pre-advertise TURN credentials to ordinary peers.
-Production currently runs exact `93e4681915768db0bf3b0165c0fd9ec3f54f95c8`
-from `/opt/screener/releases/93e468191576`; immediate rollback is
-`/opt/screener/releases/66eb33717193`. Local and public health return 200;
+Production currently runs exact `01a77ae331ded864819003b532695470d7777e7d`
+from `/opt/screener/releases/01a77ae331de`; immediate rollback is
+`/opt/screener/releases/93e468191576`. Local and public health return 200;
Screener, LiveKit, coturn, and nginx are active, and Screener reports
`NRestarts=0`.
@@ -30,16 +30,17 @@ The current release deploys the bounded pre-share health/WSS/STUN self-check,
privacy-safe click-only diagnostic JSON export, room admission default eight
with explicit limits from one through sixteen, and peer-quality MBB. One
ordinary Viewer with a peer or SFU upstream may own the provisional child;
-Host provisional children remain open. Production keeps its two-edge endpoint
-default; the next source release clamps Host to two and an
-ordinary Browser Viewer to one. The retained capacity-two/cap3 sixteen-Viewer
+Host provisional children remain open. The endpoint-cap environment is unset,
+so the production default yields Host two and ordinary Browser Viewer one; the
+wire remains unchanged. The retained capacity-two/cap3 sixteen-Viewer
and resource runs are historical ordinary-PC experiments only and do not define
release policy or close performance gates.
-The cutover used audited tree `848f1588000006d91546468abae858bf027929e6`,
+The cutover used audited tree `746fadb809b09199d4511cb99f5d34b99687a209`,
an independent production dependency tree with zero shared regular-file inodes,
-and byte-identical public client assets. A no-room Chrome 151 canary passed
-health, WSS open/close, STUN-only configuration, and `srflx` gathering in 2.49
-seconds; it did not exercise room media, route migration, SFU, or TURN.
+and byte-identical public client assets. The prior `93e4681` no-room Chrome 151
+canary passed health, WSS open/close, STUN-only configuration, and `srflx`
+gathering in 2.49 seconds; it was not rerun for `01a77ae` and did not exercise
+room media, route migration, SFU, or TURN.
## Topology and prerequisites
@@ -129,7 +130,7 @@ ICE. The accepted ladder is direct/peer UDP, then the revision-bound SFU/UDP
virtual parent, then optional authenticated TURN for one controller-selected
exceptional edge. LiveKit participants receive only revision-bound `sfu-config`
URL/token messages and negotiate within LiveKit's separate ICE domain. The
-selected-edge TURN config/wire is deployed in the current `93e468191576` release with one
+selected-edge TURN config/wire is deployed in the current `01a77ae331de` release with one
UDP URL and a 120-second credential TTL. It was not exercised by a real media
session during this cutover.
@@ -536,7 +537,8 @@ Run these checks from real external networks before calling the deployment usabl
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/relay downstream caps remain two/two.
+ ordinary direct UDP and Host/ordinary Browser Viewer downstream caps remain
+ two/one.
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/project-memory.md b/docs/project-memory.md
index a38459ff..8cd57930 100644
--- a/docs/project-memory.md
+++ b/docs/project-memory.md
@@ -26,7 +26,7 @@ Last updated: 2026-08-22
- Keep experiments bounded: the standard representation sequence is below; native RTP relay, encoded-object striping, and FEC remain separate.
- Web defaults to browser/LiveKit codec negotiation; advanced settings offer Automatic, H.264, or VP8 for the next share while retaining fallback codecs and `backupCodec=false`. A codec choice neither proves hardware encoding nor shared encode. ADR-0006's browser bridge remains no-go.
- Mobile endpoints are Web Viewer-only. Current Android/iOS browsers do not expose Web Host capture; AirPlay/system mirroring is Viewer-local output.
-- ADR-0005: direct/peer UDP -> bounded SFU roots -> selected-edge TURN. The deployed controller caps pending/answered `peer-selected` at one per room; Host ingress is independent. A pre-`ecc794d` exact-source/production-media canary proves active Host ingress only. Ordinary peers stay STUN-only.
+- ADR-0005: direct/peer UDP -> bounded SFU roots -> selected-edge TURN. The deployed controller caps each room at one `peer-selected` lease across negotiating and answered states; Host ingress is independent. Negotiation serializes with soft migration, while an answered exact lease is active transport and may coexist with unrelated soft MBB after route/session/share/topology/budget revalidation and carry-before-route authority. A pre-`ecc794d` exact-source/production-media canary proves active Host ingress only. Ordinary peers stay STUN-only.
- `PEER_ASSISTED_MEDIA=true` covers all rooms. One-root healthy-SFU MBB is deployed with retained parent, media proof, Host2/browser1 overlap, cooldown and fresh two-window proof; it excludes `peer-selected`. Active-SFU loss uses normal recovery; the manual control keeps its route: peer restarts its edge, SFU reauthenticates signaling and rebuilds that subscriber. Capacity `0 -> 1`, multi-root/browser gates remain open.
- C+B stays edge-local: deployed MBB gives only the triggering child one attempt to an ordinary Viewer whose active upstream is peer or SFU while its old edge remains active; Host remains excluded. Current-generation RTP, decoded frames, and live video atomically promote the same provisional PC. A ready-then-failed identity survives until active/rollback, while session/share change or an unrelated authoritative failure aborts the soft probe. Failure, timeout, or no candidate keeps the old edge without SFU/TURN. Sibling MBB remains separate. No score.
- Flagship media is UDP; HTTPS/WSS stays TLS/TCP; the old release remains rollback-only.
@@ -43,12 +43,12 @@ Last updated: 2026-08-22
## Current Implementation
- The repository is one npm package using Node.js 24, React, TypeScript, Vite, native WebRTC, `ws`, Zod, Vitest, and separate coturn.
-- Production: exact `93e4681915768db0bf3b0165c0fd9ec3f54f95c8`, release `93e468191576`, Web wire `screener-v5`; `66eb33717193` is the rollback release.
+- Production: exact `01a77ae331ded864819003b532695470d7777e7d`, release `01a77ae331de`, Web wire `screener-v5`; `93e468191576` is the rollback release.
- Web keeps one SFU stream, clears unavailable video, exposes evidence-backed routes/transports and paused preview, and drops signals to a grace-retained offline current-edge target. Routing is automatic; entry/nickname UI is live; Native remains source-only.
-- Production rooms default to eight Viewers and accept an explicit admission limit from one through sixteen. The deployed older release uses Web cap2; current source is Host2/ordinary Browser Viewer1 and accepts deployment 1/2 only as further tightening, without a UA/visibility split. The unchanged `0/1/2/3` relay-capacity wire is a future envelope, not current authority.
+- Production rooms default to eight Viewers and accept an explicit admission limit from one through sixteen. The deployed release is Host2/ordinary Browser Viewer1 and accepts deployment 1/2 only as further tightening, without a UA/visibility split. The unchanged `0/1/2/3` relay-capacity wire is a future envelope, not current authority.
- Relay evidence is opt-in; direct proof and selected-pair addresses stay local, never in relayed evidence. The deployed pre-share self-check uses disposable health/WSS/STUN probes and reports configured SFU as unverified until a real route. Click-only diagnostic JSON uses a fixed privacy allowlist; neither path uploads or persists a report.
-- `screener`, LiveKit, coturn, and nginx are active; `screener` has `NRestarts=0`, local/public health are 200, and the endpoint-cap environment is unset so the parameterized default is two. SQLite v3 has five rooms, SHA-256 `aef724ae52c4107be8ec8791e72f8dcaa11b0ec849fb432d022e2cfb9cfe0974`, owner/mode `screener:screener`/0600.
-- Production keeps ordinary ICE STUN-only, SFU roots <=2, selected-edge UDP TTL 120, and one pending/answered `peer-selected` attempt per room excluding Host ingress. A post-deploy no-room browser self-check passed health, unauthenticated WSS open/close, and STUN `srflx` gathering without exposing candidate data; room media, SFU, TURN, and performance remain unverified. Earlier exact-`16f6eab` evidence proves active Host ingress only.
+- `screener`, LiveKit, coturn, and nginx are active; `screener` has `NRestarts=0`, local/public health are 200, and the endpoint-cap environment is unset so effective capacity is Host2/ordinary Browser Viewer1. SQLite v3 has five rooms, SHA-256 `aef724ae52c4107be8ec8791e72f8dcaa11b0ec849fb432d022e2cfb9cfe0974`, owner/mode `screener:screener`/0600.
+- Production keeps ordinary ICE STUN-only, SFU roots <=2, selected-edge UDP TTL 120, and one `peer-selected` lease per room excluding Host ingress. The `01a77ae` release has an independent dependency tree, public client assets byte-identical to its local build, and healthy bounded services. The prior `93e4681` no-room browser self-check passed health, unauthenticated WSS open/close, and STUN `srflx` gathering without exposing candidate data; it was not rerun for `01a77ae`, and room media, SFU, TURN, and performance remain unverified. Earlier exact-`16f6eab` evidence proves active Host ingress only.
- Production requires independent `SITE_ACCESS_PASSWORD`: its stateless cookie authorizes creation/Host and code-only Viewer attempts; private grants stay direct, while public/private code entry needs site access alone/plus room password. Env/endpoint/cookie/nginx naming migrated atomically; failures remain neutral; there are no accounts/JWT/session rows. Local `gate:access-privacy` proves fragment isolation, site/grant transport-log absence, and raw room-password SQLite absence; room-password WebSocket/log ingress and live/headful evidence remain open.
- Production uses nginx, Node.js 24.19.0, coturn 4.17.2, and LiveKit 1.13.5 on UDP 7882 (TCP fallback off). Ordinary peer ICE receives no TURN; the selected-edge tuple is configured only for the current controller edge, with no credential pre-advertised to ordinary peers. Coturn retains the old authenticated-relay ports. Services are healthy with zero restarts.
- ADR-0005 rejects `PEER_ASSISTED_ROOM_IDS`; `PEER_ASSISTED_MEDIA=true` enables every room and ordinary peers stay STUN-only. Initial or active Host ingress may consume one bound relay-only grant; ready/abort clears it and failure restores peer baseline. Stale room-ID config fails startup. Production and source-only Native use `screener-v5`; Native does not subscribe to Web presence.
diff --git a/docs/research/built-in-peer-ice-turn.md b/docs/research/built-in-peer-ice-turn.md
index 29df75bc..298ff384 100644
--- a/docs/research/built-in-peer-ice-turn.md
+++ b/docs/research/built-in-peer-ice-turn.md
@@ -83,11 +83,14 @@ coherent controller-owned change with a current consumer:
- a complete default-off deployment tuple with an independent secret, one
explicit TURN/UDP URI, bounded TTL, quota, bandwidth, and relay-port limits;
- issuance only after the current edge exhausts direct/peer UDP and SFU/UDP;
-- one in-memory attempt bound to room/share generation, viewer and parent
+- one in-memory negotiating attempt bound to room/share generation, viewer and parent
sessions, route revision, the replaced connection, and a server-generated new
connection identity;
-- at most one pending or answered `peer-selected` attempt per room, with the
- separate Host-to-SFU ingress attempt excluded from that last-mile cap;
+- at most one `peer-selected` lease per room across negotiating and answered
+ states, with the separate Host-to-SFU ingress attempt excluded from that
+ last-mile cap; negotiation is serialized with other soft migrations, while an
+ answered exact lease is active transport and may coexist with an unrelated
+ soft migration under route carry revalidation;
- coordinated parent and child rebuild for exactly that edge, using relay-only
ICE only on the new connection;
- revalidation at grant, rebuild, ready, failure, timeout, route change,
diff --git a/docs/status.md b/docs/status.md
index b8ca004f..5c0df6e6 100644
--- a/docs/status.md
+++ b/docs/status.md
@@ -6,10 +6,10 @@ This file is the current execution index. Load [verification status](./verificat
## Production
-- `https://share.bonfire.icu` runs exact `93e4681915768db0bf3b0165c0fd9ec3f54f95c8`, release `93e468191576`, wire `screener-v5`; `66eb33717193` is the rollback release.
+- `https://share.bonfire.icu` runs exact `01a77ae331ded864819003b532695470d7777e7d`, release `01a77ae331de`, wire `screener-v5`; `93e468191576` is the rollback release.
- `screener`, LiveKit, coturn, and nginx are active, local/public health return 200, and `screener` has `NRestarts=0`. SQLite remains schema v3 with five rooms and mode 0600.
-- Ordinary ICE is STUN-only. Production allows SFU roots <=2, one `peer-selected` attempt excluding Host ingress, selected UDP TTL 120, room admission default eight with explicit limits from one through sixteen, and two downstream edges per Web endpoint. `MAX_PEER_RELAY_DOWNSTREAM_EDGES` is unset, so that release's parameterized default is active. The next source release changes the endpoint policy to Host2/ordinary Browser Viewer1 without changing the wire.
-- Stable SFU, route/transport truth, pause notices, entry/nickname UI, selected-edge lease authority, corroborated bad-relay demotion, Share audio presets, local media-path diagnostics, pre-share self-check, privacy-safe diagnostic export, and peer-quality MBB are live. A candidate ordinary Viewer may have a peer or SFU upstream; Host provisional children and sibling MBB remain open. Native remains source-only.
+- Ordinary ICE is STUN-only. Production allows SFU roots <=2, one `peer-selected` lease across negotiating and answered states excluding Host ingress, selected UDP TTL 120, and room admission default eight with explicit limits from one through sixteen. `MAX_PEER_RELAY_DOWNSTREAM_EDGES` is unset, so effective downstream capacity is Host2/ordinary Browser Viewer1; active, provisional, selected, and Host SFU publication edges count. The wire remains `screener-v5`.
+- Stable SFU, route/transport truth, pause notices, entry/nickname UI, selected-edge lease authority, corroborated bad-relay handling, Share audio presets, local media-path diagnostics, pre-share self-check, privacy-safe diagnostic export, and peer-quality MBB are live. An ordinary Viewer with a peer or SFU upstream may own one provisional child; Host provisional children and sibling MBB remain open. Native remains source-only.
## Current Product Snapshot
diff --git a/docs/verification-status.md b/docs/verification-status.md
index 53f3d47e..c86c6fc6 100644
--- a/docs/verification-status.md
+++ b/docs/verification-status.md
@@ -8,9 +8,9 @@ This is the demand-loaded ledger for cross-cutting validation evidence and open
## Deployment Evidence
-- Production runs exact `93e4681915768db0bf3b0165c0fd9ec3f54f95c8`, release `93e468191576`, with `66eb33717193` retained for rollback. Its audited runtime tree has no regular-file inode shared with rollback, and all public client assets matched the local build byte-for-byte. A post-deploy no-room Chrome 151 canary passed health, unauthenticated WSS open/close, STUN-only configuration, and `srflx` gathering in 2.49 seconds without logging candidate data; room media, route migration, SFU, TURN, and performance remain unverified.
+- Production runs exact `01a77ae331ded864819003b532695470d7777e7d`, release `01a77ae331de`, with `93e468191576` retained for rollback. Its audited runtime tree has no regular-file inode shared with rollback, and all public client assets matched the exact local build byte-for-byte. The prior `93e4681` no-room Chrome 151 canary passed health, unauthenticated WSS open/close, STUN-only configuration, and `srflx` gathering in 2.49 seconds without logging candidate data; it was not rerun for `01a77ae`, and room media, route migration, SFU, TURN, and performance remain unverified.
- Local/public health return 200; `screener`, LiveKit, coturn, and nginx are active; `screener` reports zero restarts. SQLite v3 has five rooms, SHA-256 `aef724ae52c4107be8ec8791e72f8dcaa11b0ec849fb432d022e2cfb9cfe0974`, owner `screener:screener`, and mode 0600.
-- Room admission defaults to eight and accepts explicit limits from one through sixteen. The endpoint-cap environment is unset, so Web endpoints use the parameterized default of two. Ordinary peer ICE stays STUN-only, SFU roots stay <=2, and selected-edge UDP authority is bounded to one pending/answered `peer-selected` attempt per room excluding Host ingress.
+- Room admission defaults to eight and accepts explicit limits from one through sixteen. The endpoint-cap environment is unset, so the deployment default yields Host2/ordinary Browser Viewer1; active, provisional, selected, and Host SFU publication edges count. Ordinary peer ICE stays STUN-only, SFU roots stay <=2, and selected-edge UDP authority is bounded to one `peer-selected` lease per room excluding Host ingress.
- Share audio presets and local-only Host SFU, codec/encoder, A/V, and selected-candidate diagnostics are deployed. Their target-browser field availability and actual media values remain unverified.
- The bounded pre-share self-check, privacy-safe local JSON export, and peer-quality MBB are deployed. An ordinary Viewer with a peer or SFU upstream may own the provisional child; Host provisional children and sibling MBB remain open. Real-route behavior remains part of the routing gate.
- Earlier exact-`16f6eab` evidence proves active Host ingress only; it does not prove the current release, initial Viewer ingress, healthy reselection, last-mile quality, or TURN performance.
@@ -29,7 +29,7 @@ This is the demand-loaded ledger for cross-cutting validation evidence and open
- Routing: verify current-release initial ingress, `peer-selected` expiry/failure, corroborated bad-relay reassignment, one-root healthy SFU reselection, silent partitions, and bounded failure on real browser/media paths. Silent control partitions may wait 30 to 60 seconds for heartbeat detection before the default five-second grace.
- Quality: production startup blur remains unclassified. One same-`balanced` local A/B retained route/PC/SSRC/track while 720p rose to 1080p, but natural ramp prevents causal, production, or SFU conclusions. Correlate Host capture/encode/send with Viewer receive/decode before changing policy.
-- Relay resources: the deployed older release is Host2/Viewer2; current source policy is Host2/ordinary Browser Viewer1 and rejects any Viewer child2 regardless of advertised capacity. Relay CPU/GPU/upload cost and heterogeneous-network behavior remain unverified. Finish the role-aware matrix before the 20-viewer gate or any future capacity-tier change.
+- Relay resources: production is Host2/ordinary Browser Viewer1 and rejects any Viewer child2 regardless of advertised capacity. Two-child relay corroboration is therefore a future-capacity experiment, while the triggering child's edge-local MBB remains active. Relay CPU/GPU/upload cost and heterogeneous-network behavior remain unverified. Finish the role-aware matrix before the 20-viewer gate or any future capacity-tier change.
- SFU: active publication already uses `q,h`; exactly-two, Dynacast-off, zero-child, BWE, resource, and root-with-children gates remain. Use Linux `tc` or a public canary for per-leaf shaping, never CDP throttling.
- Audio: verify the 64/128/256 kbps Share settings, negotiated/observed bitrate, audible music quality, route changes, and game A/V synchronization. Bitrate settings are ceilings, not quality proof.
- Observability: the UI and local stats plumbing are deployed, but target-browser availability and actual values remain unverified for Host SFU sender evidence, codec/fmtp and encoder implementation/power efficiency, media-source and encoded FPS, A/V playout/jitter/concealment, and selected candidate endpoints. These fields diagnose; they do not by themselves prove hardware encode, synchronization quality, or route quality.
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 39cfe051..bc85510f 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"
@@ -250,7 +250,9 @@ budget 仍成立时才先发 carry、再发新的 active authority;否则撤
Source-only Native 与 authenticated snapshot 继续 STUN-only。凭据不进入 URL、日志、browser
storage、room row 或 SQLite。
-该临时 edge 不改写 active SFU assignment 或另建 route owner;attempt 存续期间
+该 selected edge 不改写 active SFU assignment 或另建 route owner。未 answer 的
+negotiating attempt 与同房其他 soft MBB 串行;answer 后 exact lease 成为绑定有效期间的
+长期 active transport authority,不是房间级迁移锁,可与无关 soft MBB 共存。两种状态下
presence 的 active upstream 仍为 `sfu`,本地 ICE path 才报告 TURN transport。签发前按当前 assignment
重新计算 parent 下游预算,Host 的 SFU publication 也占一边;Host 或 ViewerRelay
两边已满且 target 不是现有 child 时 fail closed,不替换无关 child。
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 5fa7a1f9..a68cbfd4 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"
@@ -26,7 +26,7 @@
- [ ] 一对多观看:当前安全默认上限为 8、可配置范围为 1 至 16;自动分布式拓扑验收后,同一 release 将默认值和上限改为 20。当前 PoC 的逐观看者连接是测量基线,不再是超过两名观看者时的目标拓扑;未通过 20 人门禁时继续明确拒绝超额加入。
- [ ] 端点 fanout 硬上限:当前 release 的 Host 任何时刻最多维护两条 active downstream media edges,普通 Browser Viewer 最多一条;普通 upstream receive 不消耗上传预算。服务端按已鉴权角色执行有效上限,旧版或恶意 Web Viewer 即使广告 `relay-capacity=2/3` 也只能得到一条,部署配置只能把 Host/Viewer 分别从 `2/1` 进一步收紧,不能提高上限。Web 客户端还必须在执行服务端 assignment、建立物理 PC 前按当前角色截断为 Host2/Viewer1;这是服务端回归或版本错配时的 defense-in-depth,不把 wire envelope 变成执行许可。预算计入 active、provisional 和 selected physical overlays,Host 的 active SFU publication 也占一条;不能用 logical replacement 名义临时超额。不按 UA、设备类型或页面可见性另建容量策略;实际 edge 失败进入同一有界换父路径。第三名及后续观看者由系统自动分配给通过验收的 peer-assisted 拓扑,不能隐藏地回退为 Host 第三条连接。没有可行 peer path 时,SFU 作为主要中央兜底 virtual parent 正常向一至两个必要 roots 送流;媒体到达 root 后其余可行观看者仍优先沿受限 peer descendants 扩散。多个无法挂到健康 root 的极端 viewer 可成为额外 server-fed 例外,但必须受显式中央 egress/admission 上限约束,不能无界整房 fanout。TURN 只作为可选的极端网络 transport 兼容层,不定义房间拓扑。
- [ ] P2P 优先:每条逻辑媒体边的 ICE 必须先尝试直接 UDP 路径,服务器不得默认中转可直连的媒体。一个或两个观看者优先直接连接分享端;更多观看者的 peer-assisted 行为须先通过 ADR-0004 的实验门槛。
-- [ ] NAT 与传输兜底:STUN 必须可用,所有 ordinary peer `RTCPeerConnection` 只接收 STUN ICE servers。PC 失败后按一次 ICE restart、一次同 parent rebuild、一个 alternate peer、再 SFU/UDP virtual parent 的顺序恢复,任一步成功即停止;只有该 edge 的 SFU/UDP 也失败后,controller 才可授权一次短期 authenticated selected-edge TURN/UDP rebuild。授权必须绑定 room/share generation、viewer/parent session、签发时 route revision 与 old/new connection identity;answer 后只在 exact edge/session/share 与 parent downstream budget 仍成立时跨无关 route revision carry,且 carry 必须先于新 active authority。失败、超时或任一绑定/预算失效即撤销;同一房间同时 pending 或 active 的 `peer-selected` attempt 总数最多为一,`host-sfu-ingress` 使用独立状态且不占该 last-mile 名额。不得按 participant、房间或普通 peer PC 下发,source-only Native 保持 STUN-only。凭据不进入 URL、日志、浏览器持久化或 SQLite。Coturn 只验证 HMAC 与 expiry,应用必须重验 edge 代次并用短 TTL、one-use state 与 quota 限界。媒体路径保持 UDP-only;全部 UDP 路径耗尽后明确失败。HTTPS/WSS 仍独立使用 TLS/TCP。
+- [ ] NAT 与传输兜底:STUN 必须可用,所有 ordinary peer `RTCPeerConnection` 只接收 STUN ICE servers。PC 失败后按一次 ICE restart、一次同 parent rebuild、一个 alternate peer、再 SFU/UDP virtual parent 的顺序恢复,任一步成功即停止;只有该 edge 的 SFU/UDP 也失败后,controller 才可授权一次短期 authenticated selected-edge TURN/UDP rebuild。授权必须绑定 room/share generation、viewer/parent session、签发时 route revision 与 old/new connection identity;answer 后只在 exact edge/session/share 与 parent downstream budget 仍成立时跨无关 route revision carry,且 carry 必须先于新 active authority。失败、超时或任一绑定/预算失效即撤销;同一房间最多一个 `peer-selected` lease(negotiating 或 answered active)。未 answer 的协商与其他 soft MBB 串行;answered lease 是该 exact edge 的长期 active transport,不是全房迁移锁,可与无关 soft MBB 共存,carry 仍按上述绑定和预算重验。`host-sfu-ingress` 使用独立状态且不占该 last-mile 名额。不得按 participant、房间或普通 peer PC 下发,source-only Native 保持 STUN-only。凭据不进入 URL、日志、浏览器持久化或 SQLite。Coturn 只验证 HMAC 与 expiry,应用必须重验 edge 代次并用短 TTL、one-use state 与 quota 限界。媒体路径保持 UDP-only;全部 UDP 路径耗尽后明确失败。HTTPS/WSS 仍独立使用 TLS/TCP。
- [ ] 质量控制:保留 1080p60(8 Mbps)、1080p30(5 Mbps)、720p30(3 Mbps)三档推荐上限,三档与高级设置初始值统一采用 `balanced`(平衡)与 `automatic`(自动编码),`maintain-resolution`(清晰优先)、`maintain-framerate`(流畅优先)和 H.264/VP8 保留为显式选择;分享期间可直接换档或应用有界高级设置,不重新选择来源或重建健康连接,codec 在直播中锁定并于下一次分享生效。Peer-assisted relay 与已配置的 SFU 必须接收同一个严格校验的房间级权威设置,覆盖当前和以后建立的 sender;普通 P2P 信令结构保持不变。任何设置都只是浏览器上限和偏好,具体降级由浏览器决定;必须读回实际 sender 参数并通过 stats 观测结果、显示参数拒绝、改写和持续受限原因。不做自定义动态 FPS、综合评分或周期性全房间调档。
- [ ] 路径隔离双表示:direct/peer 继续使用每条 PeerConnection 独立的 stock WebRTC GCC,不把任何 viewer 反馈合成全房目标。每条 SFU path 从 `HIGH` ceiling 开始;优先用 pinned LiveKit 2.22.0/1.13.5 的标准两层 screen-share simulcast,在 Dynacast off 下常驻 exactly `HIGH+LOW`,让内建 per-subscriber BWE 独立降层和恢复。若该 gate 通过,Screener 不实现媒体层 selector。首 gate 使用 zero-descendant SFU leaf;root-with-children 的自动 downshift 与有界迁移是 default-on 前独立硬门。只有内建选择不满足门槛时才用标准 subscriber quality 显式限制,常驻成本不合格时再测标准 sender 手动启停。`LOW` 停编只是资源优化;active representation/layer 硬上限为二,禁止按 viewer 增长。必须实测实际接收层、硬件编码证据、游戏 FPS/p1 low、CPU/GPU、区间 encode cost、上传和分层 bytes。当前 Web P2P simulcast 缺少 receiver 选 RID 和跨 PeerConnection shared-encode 契约;当前 Web/LiveKit SVC 也缺少 direct/peer 独立选层与可移植硬件保证,且 pinned screen share 强制三层 temporal-only `L1T3`,二者按现契约静态 no-go。全部标准路径失败后才考虑 custom/native dual encode。没有合格 hardware/power-efficient 路径或额外表示破坏游戏/上传预算时 fail closed:保护健康路径并明确显示弱路径降级或不可用。
- [ ] 路径级质量状态:应用的 `HIGH`/`FALLBACK` 非对称窗口只决定拓扑资格和诊断,不命令正常的媒体层切换,也不计算综合分数。SFU BWE downshift 先进入 `suspect`;多个连续窗口的 sender/viewer 关联证据确认 `FALLBACK` 后,应用不得稳定保留该 parent,并把 downstream capacity 降为 0。计划或显式质量 fallback 仅是内建路径失败后的候选:已有 children 时先在 connection/assignment generation guard 下全部迁走,失败或代次过期则保持原 assignment/quality。Autonomous downshift 无法 packet-level 预先迁移,default-on 前必须验收 descendants 的短暂影响。只有更长的稳定恢复窗口和 cooldown 后才能重新声明 relay capacity。Viewer 请求必须鉴权、限频、去重,并由 sender 的 GCC/Transport-CC、实际码率、RTT、丢包、重传、编码限制、协商 codec/profile/parameters 与 viewer 解码、丢帧、冻结证据交叉验证;不能仅凭自报生效,也不得上传 raw SDP、candidate 地址或原始设备/网络标识。