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: set simple routing and room scale constraints

AAA3ced92b500cc
diff --git a/AGENTS.md b/AGENTS.md
index 1c48a4df..a5a6111a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -3,6 +3,7 @@
## 1. Decision And Durable Truth
- Highest priority: before implementation, cleanup, or deployment, settle the meaning against the whole product model and evidence, challenge contradictions or needless complexity, and write the accepted decision to its owning truth documents. Discussions, examples, review suggestions, experiments, checkboxes, and agent ideas are inputs, not implementation authority; never turn a partial interpretation into code or a branch.
+- Apply Occam's razor as "simple, not simplistic": prefer standards, mature framework behavior, and one small general mechanism that covers the product model. When a concrete failure appears, fix the owning invariant or reconciliation loop first; add a case-specific branch, gate, probe, timer, state container, or test only when evidence shows the general mechanism cannot cover it. Do not implement by repeatedly patching examples.
- Before dependent work starts, update every affected owning requirement, design, ADR or research conclusion, plus `docs/project-memory.md` and `docs/status.md` when their snapshots change. Checkpoint the consistent truth in Git; chat is not durable truth.
- If semantics remain disputed, record the hold in `docs/todo.md` and freeze only dependent work. Do not encode a guess as accepted truth.
- **Current-truth ("Dongpo pork") rule:** after a correction, current docs, UI, code, comments, configuration, and PR copy state only the accepted behavior and rationale that still constrains it. Remove rejected alternatives and explanations of their removal; Git history owns that history.
@@ -16,12 +17,13 @@
## 3. Product Contract
-- Build private, low-latency game screen sharing for one broadcaster and a small group of trusted friends, not a public or large-scale streaming service.
+- Build private, low-latency game screen sharing for one broadcaster and up to `20` authenticated Viewers, not a public or large-scale streaming service.
- A normal desktop or mobile browser is the initial Viewer target. A packaged sender or native capture helper is a later optimization.
- Keep media distributed and automatic. Central services own rooms, authentication, signaling, STUN, observability, and bounded fallback resources; do not silently make the product always-SFU.
- STUN and direct/peer UDP remain first. Ordinary peer edges receive no TURN candidates by default, and every accepted path ends in bounded success or clear failure. HTTPS/WSS transport is independent of media transport.
- Every non-server endpoint uses one server-authoritative steady outbound media-copy cap: default `2`, configurable as `1`, `2`, or `3`. A peer child or the Host's single SFU publication consumes one slot; upstream receive is free, selected TURN replaces the transport of the same copy, and SFU subscriber egress is accounted at the server. Browser role, UA, visibility, and client advertisement do not create another tier.
-- The accepted route model is one room controller with three operations: allocate/distribute, child reparent, and relay abdicate/drain. SFU is one Host publication with per-Viewer subscriptions; TURN is a selected transport for an authorized edge or Host-SFU ingress, not a topology node. These paths use exact generations, media proof, bounded overlap, and independent server admission; they do not create a fixed root-count or room-wide lease rule.
+- The accepted route model is one committed graph, one event-driven reconciliation loop, and at most one room-serial child operation. That operation owns one deterministic candidate list/cursor, one current candidate with its reservations, and one total deadline; its exact child commits on the first newly decoded frame. Join/waiting, child reparent, relay ingress repair with subtree retention, confirmed departure, and effective-capacity reduction all use this operation. A failed exact `parent + transport` tuple is already tried for that operation, so other direct parents come first; another transport on the old parent may follow, and no persistent parent blacklist is created.
+- WebRTC and LiveKit own ICE/DTLS/consent, congestion control, transient reconnect, and SFU stream state. Screener does not add all-pairs endpoint probing, parent-wide quality inference, a weighted route score, periodic rebalancing, or an independent depth cap. SFU is one Host publication with per-Viewer subscriptions; TURN is a selected transport for an authorized edge or Host-SFU ingress, not a topology node. Endpoint overlap and SFU/TURN resources remain independently admitted and bounded.
## 4. Canonical Repository And Integration
diff --git a/docs/adr/0005-automatic-hybrid-media-routing.md b/docs/adr/0005-automatic-hybrid-media-routing.md
index c8c2569d..0c34f96e 100644
--- a/docs/adr/0005-automatic-hybrid-media-routing.md
+++ b/docs/adr/0005-automatic-hybrid-media-routing.md
@@ -116,6 +116,16 @@ needed, rather than enumerating Host-TURN Viewer edges. The operation records
only exact tuples already tried; failure does not globally exclude that parent
from later room events.
+If an SFU subscription is needed while the Host has no publication and all Host
+slots are occupied, reconciliation uses the same child operation to convert one
+deterministic current Host direct child into the first SFU subscriber. It uses
+the affected child when that child is already a Host direct child; otherwise it
+uses the newest connected Host direct child in stable join order. The candidate
+creates the single Host publication, preserves that child's subtree, and commits
+on its first newly decoded frame. The publication then replaces the released
+Host peer slot, and the next reconciliation handles the original waiting or
+failed child. This creates no bootstrap state or second graph.
+
### Authorization and transition
Every prepare, signal, recovery, commit, and rollback is bound to the
diff --git a/docs/deployment.md b/docs/deployment.md
index 24772bca..6b076ffe 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -289,7 +289,10 @@ key, even blank, fails startup.
Omit the database path to keep random temporary rooms; `ROOM_TTL_SECONDS`
applies only to those rooms.
`MAX_VIEWERS_PER_ROOM` defaults to 8 and accepts 1 through 16. It is an admission
-limit, not evidence that the publisher can sustain that many streams.
+limit in the deployed release, not current product policy or evidence that the
+publisher can sustain that many streams. The accepted source target is 20
+Viewers; deployment default promotion follows the route release's 20-Viewer
+smoke.
`ENDPOINT_MEDIA_COPY_CAPACITY` defaults to 2 and accepts only 1, 2, or 3. It is
the single server-authoritative steady outbound media-copy cap for Host and
Viewer endpoints; role, browser, UA, and visibility do not create another tier.
@@ -612,7 +615,8 @@ Run these checks from real external networks before calling the deployment usabl
6. Repeat at 1, 3, 5, and 8 viewers across representative consumer networks.
Record selected protocol, RTT, bitrate, frame rate, packet loss, publisher
upload/encode load, LiveKit ingress/egress, and final decoded quality. A real
- 1:8 session remains unverified until this matrix passes.
+ 1:20 session remains unverified until the route-release smoke passes; this
+ longer matrix remains the heterogeneous-network quality gate.
References: [coturn 4.17.2 release](https://github.com/coturn/coturn/releases/tag/4.17.2),
[pinned turnserver documentation](https://github.com/coturn/coturn/blob/4.17.2/README.turnserver),
diff --git a/docs/project-memory.md b/docs/project-memory.md
index 73cbf524..54c798b8 100644
--- a/docs/project-memory.md
+++ b/docs/project-memory.md
@@ -5,6 +5,7 @@ Last updated: 2026-08-23
## Current Product Truth
- Build private, low-latency game screen sharing for one broadcaster and a small group of trusted friends. Public or large broadcasts belong on OBS/Twitch-class services.
+- A room supports one Host and up to `20` authenticated Viewers. Admission is independent of endpoint fanout and SFU/TURN capacity; the event-driven route controller must remain efficient at that bound without all-pairs probing.
- Authenticated Hosts and shipped clients are trusted media participants in these private rooms; route authority, generation fencing, and server admission remain fail-closed.
- Web is the current delivery target. Viewers join from desktop or mobile browsers; a packaged or native sender is a later optimization.
- Keep routing automatic and media distributed. Direct/peer UDP is preferred; centralized media is fallback infrastructure, not the default topology.
@@ -22,7 +23,7 @@ Last updated: 2026-08-23
## Current Source And Production
- Canonical source is the clean `main` branch. New branches and worktrees start from its exact current commit after accepted truth is merged.
-- Current source implements the uniform `1/2/3` endpoint cap through one shared accounting guard, advances Web/server/Native to `screener-v6`, rejects v5 before room authority, and carries the exact deployment cap in every authenticated snapshot so ordinary Host authorization, Native admission, peer-assisted assignments, and sender slots use the same authority. Its current SFU-fed-leaf and route-quality behavior predates the accepted generic reconciliation model. SFU admission uses explicit no-default ingress/egress capacities, exact `reserved | committed | draining` lifecycle accounting, and a listener-fenced dedicated LiveKit owner. Selected TURN uses its own explicit no-default deployment capacity and exact logical-allocation ledger shared by independent peer edges and Host-SFU ingress.
+- Current source implements the uniform `1/2/3` endpoint cap through one shared accounting guard, advances Web/server/Native to `screener-v6`, rejects v5 before room authority, and carries the exact deployment cap in every authenticated snapshot so ordinary Host authorization, Native admission, peer-assisted assignments, and sender slots use the same authority. Its current room admission still stops at `16` Viewers, and its SFU-fed-leaf and route-quality behavior predates the accepted `20`-Viewer generic reconciliation model. SFU admission uses explicit no-default ingress/egress capacities, exact `reserved | committed | draining` lifecycle accounting, and a listener-fenced dedicated LiveKit owner. Selected TURN uses its own explicit no-default deployment capacity and exact logical-allocation ledger shared by independent peer edges and Host-SFU ingress.
- Production runs exact `9461e207af62b4f38f6b7a8aa16f8beb49e0e4ee`, release `9461e20`, wire `screener-v5`; `21d5cd9f7139` is the rollback release.
- Production still enforces Host downstream `2`, ordinary Browser downstream `1`, deployment values `1/2`, a fixed SFU-root limit of `2`, and legacy publication/selected accounting. This is a dated implementation divergence, not current product policy.
- Production has automatic routing, bad-relay corroboration, peer-quality make-before-break with Viewer and Host provisional parents, selected-edge transport, stable route/connection details, 64/128/256 audio choices, access controls, self-check, diagnostic export, and signaling watchdog behavior.
@@ -37,6 +38,7 @@ Last updated: 2026-08-23
## Working Rules
- Discussion and evidence are inputs, not executable TODOs. Accepted semantics are written to their owners before implementation.
+- Prefer standards and mature framework behavior, then one general reconciliation mechanism. Repair an invariant before adding a case branch; a specialized gate, probe, timer, state container, or test requires evidence that the general mechanism cannot cover the failure.
- Current documents state the current model directly. Rejected alternatives and removal narratives are deleted; Git history owns them.
- Old branches may contribute scoped code or evidence only after reconciliation. Their memory, requirements, ADRs, status, and deployment snapshots never overwrite newer mainline truth.
- Preserve dirty, unique, open-stack, and evidence worktrees until their disposition is explicitly decided. Workspace counts are sampled on demand rather than stored here.
diff --git a/docs/research/advanced-peer-distribution.md b/docs/research/advanced-peer-distribution.md
index baf5f59b..c111f0cb 100644
--- a/docs/research/advanced-peer-distribution.md
+++ b/docs/research/advanced-peer-distribution.md
@@ -1,8 +1,9 @@
# Advanced Peer Distribution
- Research date: 2026-08-23
-- Scope: at most eight trusted viewers, sub-second interactive media, endpoint
- downstream fanout at most two, and minimal central-server media egress
+- Scope: current route admission up to twenty trusted viewers, sub-second
+ interactive media, endpoint downstream cap `1..3`, and minimal central-server
+ media egress; retained advanced-media measurements may cover smaller cohorts
- Status: deterministic peer distribution and provisional make-before-break are
retained evidence; current routing converges through ADR-0005's single
child-reparent reconciliation, while advanced encoded-media routes remain
diff --git a/docs/research/peer-assisted-media.md b/docs/research/peer-assisted-media.md
index e2b9d643..7f5823ad 100644
--- a/docs/research/peer-assisted-media.md
+++ b/docs/research/peer-assisted-media.md
@@ -1,8 +1,9 @@
# Peer-Assisted Media Research
- Research date: 2026-08-22
-- Scope: one game-screen broadcaster, explicit admission up to sixteen trusted
- viewers, with the retained resource/quality gate at eight
+- Scope: one game-screen broadcaster and an accepted admission target of twenty
+ trusted viewers; retained executable evidence currently reaches sixteen and
+ the earlier resource/quality gate remains eight
- Status: historical evidence plus the deployed bounded controller;
accepted ADR-0005 owns automatic peer/SFU routing. Production later removed
the room-`1` rollout boundary; retained SFU media remains unverified.
@@ -437,9 +438,9 @@ This historical gate assumed default-off configuration through
rooms.
It uses the existing standard WebRTC screen stream, current Chrome/Edge as the
controlled relay cohort, Android Chrome and iOS Safari as compatibility
-observations, and the configured downstream edge cap. The runner accepts the
-shared room admission ceiling of sixteen while the representative
-resource/quality gate remains at eight. It may carry the existing screen-audio
+observations, and the configured downstream edge cap. The runner must accept the
+shared room admission ceiling of twenty; the current retained run reaches
+sixteen while the representative resource/quality gate remains at eight. It may carry the existing screen-audio
track when the browser provides one. SVC/simulcast,
custom encoded transport, FEC changes, multi-tree striping, transcoding,
background mobile relay, and the later ADR-0005 SFU controller are outside this
diff --git a/docs/status.md b/docs/status.md
index 2afcf5ca..a9b104a7 100644
--- a/docs/status.md
+++ b/docs/status.md
@@ -15,6 +15,7 @@ This is the current execution index. Git history owns completed timelines; [veri
- Canonical source is the clean `main` branch; auxiliary branches and worktrees do not own current truth.
- Current source implements one steady outbound media-copy cap for every non-server endpoint: default `2`, static `1/2/3`, a peer child or Host publication consumes one slot, upstream receive is free, a committed selected TURN transport replaces the same copy while hidden carry consumes another, and no Browser/UA/visibility tier exists. One shared guard owns the accounting and transition work is bounded by `min(C + 1, 3)`.
+- Accepted room admission is one Host plus up to `20` Viewers. Current source still validates at most `16`; the route release must update that bound and pass one 20-Viewer smoke without changing endpoint or server-resource accounting.
- The v6 release boundary rejects v5 before room authority and carries the exact deployment cap in every authenticated snapshot so ordinary Host authorization, Native admission, peer-assisted child assignments, and sender slots share the server authority. Current `main` still carries the legacy childless-SFU-fed and route-quality slices that the pending generic reconciliation replaces.
- Current source also implements explicit no-default SFU ingress/egress capacities and exact `reserved | committed | draining` accounting. The listener owner reconciles its dedicated non-auto-create LiveKit namespace before serving, creates each generation before token issuance, releases only after delete-plus-absence proof, and reclaims Host-offline generations through bounded exact-participant checks. Selected TURN has an independent explicit no-default deployment capacity; one process-local ledger charges every exact peer-selected edge and Host-SFU ingress through reserve, commit, drain, and release.
- Automatic P2P-first routing, one active upstream, an acyclic source-reachable graph, exact attempt authority, first-decoded-frame make-before-break, and bounded failure remain accepted.
@@ -24,7 +25,7 @@ This is the current execution index. Git history owns completed timelines; [veri
## Current Milestone
-1. Complete and release the generic route reconciliation loop with deterministic parent selection and one first-frame candidate transaction.
+1. Complete and release the generic route reconciliation loop with deterministic parent selection, one first-frame candidate transaction, and efficient admission through 20 Viewers.
2. Release live audio-ceiling mutation and paused-share codec switching on the resulting generation/transition boundary.
3. Reproduce the H.264 startup report before any codec-specific repair, and build the strict-NAT emulator gate before any manually approved canary in an operator-owned test room.
4. Add first-frame-driven Viewer connection stages and finish the remaining accepted functional and real-network work.
diff --git a/docs/todo.md b/docs/todo.md
index 5d558460..9c9ca038 100644
--- a/docs/todo.md
+++ b/docs/todo.md
@@ -12,7 +12,7 @@ Only items in **Now** are executable after their stated decision gate. A branch
4. **Diagnose the production H.264/blur report.** Reproduce exact release `769de201f7cc` against current `main` on the same Host/browser/driver/game and one wired direct Viewer, changing one variable at a time. Implement a codec-specific repair only if codec/encoder evidence identifies it; otherwise fix the proven capture, sender, BWE, or lifecycle cause.
5. **Gate the strict-NAT guessed-candidate experiment.** Build only the isolated endpoint-dependent NAT emulator and browser harness first. Standard ICE must fail in the owned fixture, the capped candidate set must pass the documented repeatability, deadline, privacy, and cleanup gates in stable Chrome and Firefox, and fallback must remain unchanged. Only then may one manually approved, operator-owned test room run a default-off, kill-switched canary with explicit consent from both endpoints and exact room/edge/generation/budget bounds; failure closes the candidate. Do not ship guessed candidates to ordinary rooms or infer NAT type from IP, UA, carrier, or two STUN observations.
6. **Make Viewer connection progress explicit.** Derive one stable stage from existing access, route, peer/SFU, media, autoplay, and bounded-failure state. Keep the overlay until a composited current-generation frame, show `Play` only for actual autoplay rejection, preserve a still-valid old frame during recovery, and expose retry only through the bounded controller. Measure the existing token-free SFU prewarm and route stages before adding another connection mechanism.
-7. **Validate and release in priority order.** Review, merge, and deploy each coherent slice from canonical `main`: route first, then audio/codec mutation, then H.264/NAT evidence and any proven repair, then connection feedback and remaining tools. Before the route release, exercise `C=1/2/3`, effective capacity `0..C`, first-frame commit and rollback, stale ready, candidate cursor/total deadline, relay ingress reparent, disconnect/cap drain, SFU-fed first child, selected TURN, and pause/resume through focused contract tests plus one bounded browser/network smoke. Run independent review, builds, production preflight, postflight, and rollback verification. A parallel branch may finish early but does not jump this rollout order.
+7. **Validate and release in priority order.** Review, merge, and deploy each coherent slice from canonical `main`: route first, then audio/codec mutation, then H.264/NAT evidence and any proven repair, then connection feedback and remaining tools. Before the route release, exercise `C=1/2/3`, effective capacity `0..C`, first-frame commit and rollback, stale ready, candidate cursor/total deadline, relay ingress reparent, disconnect/cap drain, SFU-fed first child, selected TURN, and pause/resume through focused contract tests plus one 20-Viewer browser smoke. Record route depth, first-frame time, endpoint sender counts, server CPU/memory and SFU/TURN usage; keep the one-operation controller event-driven and free of all-pairs probes. Run independent review, builds, production preflight, postflight, and rollback verification. A parallel branch may finish early but does not jump this rollout order.
The existing route implementation is an input, not an integration base. Reuse only scoped authorization, capacity, admission, deterministic-planning, and provisional-media primitives that fit the accepted single-loop model; rebuild the controller from the truth checkpoint rather than carrying role-specific state forward.
@@ -33,7 +33,6 @@ These items are real product work, ordered after the current release boundary; t
| Deployed or retained item | Decision |
| --- | --- |
| #169 connection self-check | Keep, revise, or remove the user-facing pre-share probe. Do not extend it automatically. |
-| #170 explicit 1-16 Viewer admission | Confirm the small-room admission range independently of endpoint fanout. |
| #171 diagnostic JSON export | Confirm a support workflow or remove the extra surface. |
| #181 selected-pair response counter | Keep as local observation or remove; it has no route authority. |
| #182 signaling watchdog | Confirm Host, mobile/background, and selected-edge session semantics before calling it complete. |
diff --git a/docs/verification-status.md b/docs/verification-status.md
index 42f703b2..bdcb3944 100644
--- a/docs/verification-status.md
+++ b/docs/verification-status.md
@@ -36,6 +36,7 @@ Capacity and routing entries below describe the exact tested source or release o
- Routing: verify current-release initial ingress, exact candidate first-frame commit and rollback, `peer-selected` expiry/failure, relay-ingress reparent with subtree retention, disconnect/effective-capacity drain, pause/resume, 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; a non-paused decoded-frame stall may invalidate only that exact child edge.
- 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: current source has the authenticated `1/2/3` endpoint-cap boundary, while production `9461e20` remains Host2/ordinary Browser Viewer1 and rejects Viewer child2 regardless of advertised capacity. Before release, explicitly exercise Native `C=1/2/3` admission, waiting promotion, peer-assisted assignment, and physical sender slots; CPU/GPU/upload and heterogeneous-network measurements remain evidence, not authority to change the contract.
+- Room scale: accepted admission is 20 Viewers plus one Host; current source and production stop at 16 and 8-by-default respectively. Before route release, update the source bound and run one 20-Viewer smoke for admission, route convergence, first-frame/bounded-failure, endpoint copies, application CPU/memory, and SFU/TURN accounting.
- SFU: production `9461e20` deploys ordered `q,h`, roots <=2, and Dynacast off. Those are release facts; the accepted model has no fixed root-count or room-wide lease rule. Current source still needs real LiveKit lifecycle/JWT replay and shaped packet-flow, BWE downshift/recovery, resource, and SFU-fed first-child validation. Use Linux `tc` or an authorized 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, including identity-bound relayed-detail retention and export freshness guards, 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, selected candidate endpoints, and bounded same-pair STUN-response observation. These fields diagnose and have no recovery authority; 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 38b354bc..3b0a198f 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"
@@ -92,7 +92,7 @@ rotate、revoke 或从 public-watch 切回 private-link 都是当前 Viewer 的
房间规则:
-- 一名在线分享者;房间 admission 与 endpoint capacity 分离,当前 production 默认八名、显式接受 1 至 16,未来范围另行决策和验收;
+- 一名在线分享者、最多 `20` 名 authenticated Viewer;房间 admission 与 endpoint/SFU/TURN capacity 分离,当前 production 默认八名且 source 只接受 1 至 16 是待本轮发布替换的部署事实;
- 分享者明确停止或捕获轨结束时只停止当前发布并通知观看者进入等待,不删除房间或使链接失效;host 信令短断仅更新在线状态并触发恢复,不能主动关闭仍健康的 P2P 媒体;
- 临时房间到达 TTL 后才拒绝新连接、通知现有参与者并从内存清理;持久房间没有 TTL,进程启动时从 SQLite 恢复房间身份;
- 设置全局房间上限防止内存耗尽;持久房间没有自动删除策略,运维方必须保护和备份数据库文件;
@@ -346,7 +346,7 @@ Token-free SFU standby prewarm 保持可选且不创建 participant、publicatio
- guessed-candidate 只先在 owned endpoint-dependent NAT emulator 中运行 ordinary-ICE failure 与 bounded-candidate A/B;没有通过双浏览器重复性、首帧 deadline、privacy 和 cleanup gate 时不得进入任何 production room,通过后也只在一个人工批准的 operator-owned test room 运行一次 canary,并要求双方 endpoint 显式同意、default-off kill switch 以及 exact room/edge/ICE-generation/deadline/aggregate-budget 约束;
- Windows Chrome/Edge 的 tab/window/monitor 音轨有/无、同时语音通话和 video-only;一个可区分左右声道的 fixture 只验证 Web P2P 与 SFU 的 channel correctness、协商 fmtp 和 route switch 后持久 `MediaStream`,不做听感/性能标定;Windows 11 原生候选另测 game process tree、通知、无渲染流与进程重启,Windows 10 记录明确不支持/未解决;
- Android Chrome 与 iOS Safari 的播放手势、旋转、前后台和网络切换;
-- 一名分享者、八名异构观看者连续 30 分钟,同时记录较低人数基线、实际上行、编码负载和首帧时间。真实 1:8 未完成前不得把默认上限写成性能承诺。
+- 一名分享者、20 名观看者先运行 bounded smoke,记录路由深度、首帧、sender 数、应用 CPU/内存和 SFU/TURN 用量;端点 `C=1/2/3` 分开解释。30 分钟异构公网 endurance 仍是后续质量证据,不阻止已经有界失败的 20-Viewer admission。
- 真实桌面 Chrome 对 balanced 与 clarity 做控制传播和连接身份 smoke;该项只证明直播中应用与不重建,不代替清晰度、负载或公网矩阵。
真实矩阵未完成前,状态文档必须把这些列为待验证,而不是把设计目标写成产品能力。
@@ -375,6 +375,8 @@ Token-free SFU standby prewarm 保持可选且不创建 participant、publicatio
`reconcileRoom` 在没有 pending operation 时先删除 disconnected childless participant,再找一个 waiting Viewer,或 parent offline/effective-capacity 不足、exact edge 已失效的 child。Candidate planning 拒绝 stale session、不可 source-reachable、成环、无 sender/overlap slot或 server resource 未准入的 tuple;由 failed edge 启动时还把当前 `parent + transport` tuple 预先记为已尝试。对剩余 upstream 依次比较结果深度、剩余 sender slots、稳定加入顺序与 peer identity,先建立其他 direct/STUN,再建立 selected TURN 与 SFU 的有界顺序;同一 parent 的不同 transport 仍是不同 tuple。每次只 reserve/prepare cursor 指向的 candidate。WebRTC 负责 ICE/DTLS/consent;exact candidate child 解码出第一帧新画面后发送一次 ready,controller 才 commit。失败先幂等清理并推进 cursor,operation 总 deadline 或耗尽进入 waiting/failure。新的外部事实才开启新 operation 并重新计算候选。无环和房间 admission 已约束最大深度,不增加独立 depth hard cap。
+首次需要 SFU 但 Host 已满时不建立另一条 rescue 流程。若 affected child 已是 Host direct child,就用它;否则用稳定加入顺序中最新的 connected Host direct child。`reconcileRoom` 为该 child 建立普通 SFU candidate,创建唯一 publication,保持其 subtree,并在该 child 首帧后提交。Host publication 取代释放的 peer slot,随后同一 fixed-point scan 再处理原 waiting/failed child。若旧 Host peer sender 在首帧前仍保留,candidate 必须持有同一 `TransitionOverlapSlot`;没有 overlap 时只允许既有 bounded-gap cutover,不得产生额外 endpoint copy。
+
所有非服务器端点共享一个 server-authoritative steady outbound media-copy cap `C`:唯一配置 `ENDPOINT_MEDIA_COPY_CAPACITY` 默认 `2`,只接受 `1`、`2` 或 `3`,不兼容旧键。服务端将 endpoint 当前广告的 `0..C` 可用值 clamp 为唯一 `effectiveDownstreamCapacity`;该值只表示当前可用 sender slots,不建立角色、浏览器、UA、设备或页面可见性 tier。peer child 或 Host publication 各占一份,upstream receive 免费,committed selected TURN 只替换同一份 edge transport;SFU subscriber egress 与 TURN allocation 使用独立 server admission。服务端通过 v6 `authenticated.endpointMediaCopyCapacity` 把部署 `C` 交给 Web 与 Native;Native 不从 `maxViewers` 推导发送预算。代码通过一个 shared accounting guard 执行,不重复 magic number;client/server/native wire 随该能力原子升级。Selected TURN 使用显式无默认值的正 safe-integer deployment capacity;同一个进程内 ledger 对每条 exact peer-selected edge 和 Host-SFU ingress 在 credential 签发前 reserve `1`,并让 reserved、committed、draining authorization 持续计费至 exact logical release。`C=3` 满载时只阻止会产生第四份 endpoint media copy 的 token/grant;同一 edge 改用 TURN 不增加 endpoint copy,但仍需独立 TURN admission。
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;exact candidate child 的 first decoded frame 后 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 使用独立的进程内 logical ledger;多应用进程部署必须先增加共享原子 admission/lifecycle owner。
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 cbc858bd..5c7348bb 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"
@@ -23,9 +23,9 @@ SFU/TURN 的 publication、subscription、transport、server-resource accounting
- 游戏声音:Windows Chrome/Edge 目标环境可请求系统音频;没有返回音轨时必须明确提示,而不是静默无声。
- 观看端本地音量:播放控制栏提供 `0%` 至 `100%` 音量条和静音按钮,只改变当前浏览器的媒体元素,不修改 Host 音轨、编码、房间状态或其他观看者。切流、换父和 ICE 恢复保留当前页面内的值;刷新后不持久化。静音保留上次非零音量,拖动到非零值自动取消静音。
- 本地昵称与房间成员:用户可设置一个只保存在当前浏览器同源 `localStorage` 的显示名,界面统一称为“昵称”;默认以只读文本显示,铅笔编辑按钮紧贴昵称,点击后才进入编辑。Viewer 顶部标题直接显示“{Host 名称} 的屏幕”,不得在下方重复一行 Host 名称。信令只在当前在线 socket 会话内保存和广播 NFC 规范化、最多 24 个 Unicode code points、拒绝控制/换行/双向覆盖符与孤立 surrogate 的纯文本标签,不写 SQLite 或日志。空值使用通用角色 fallback。Web Host 与 Viewer 都必须看到全部当前在线 Viewer 的权威总数与 roster,不能拿最多两条 Host 媒体直连数冒充在线人数;presence 更新也不得创建媒体连接。展示身份默认只显示名称;仅当房内出现同名时追加当前房间 `peerId` 的至少六字符短后缀,并只在同名项后缀碰撞时有界延长。显示名、后缀和 `clientId` 都不是账号、授权身份或全局 UUID,重复名称允许且不得参与授权、路由或质量决策。Web Host 与 Viewer 通过同一 opt-in participant roster 看到 Host 名称;Native 使用同一版本化鉴权 wire,但不发送 presence capability,也不接收 Web roster。
-- 一对多观看:房间 admission 与端点下游容量分别配置,超额加入必须明确拒绝。Production 当前默认 8、显式接受 1 至 16;未来默认值和上限是独立产品决策,必须经过相应资源、质量、深度和恢复验收,不能从端点 cap 或一次短跑推导。
+- 一对多观看:每个房间允许一名 Host 和最多 `20` 名 authenticated Viewer;房间 admission 与端点下游容量、SFU/TURN admission 分别配置,超额加入必须明确拒绝。Production 当前默认 8、显式接受 1 至 16 是部署事实;本轮 route release 把 source hard limit 提升到 20,并以一个 20-Viewer smoke 验收,不从 endpoint cap 推导房间人数。
- 端点发送容量:所有非服务器端点使用同一个服务端权威稳态 outbound media-copy capacity,由唯一部署项 `ENDPOINT_MEDIA_COPY_CAPACITY` 配置,默认 `2` 且只接受 `1`、`2` 或 `3`;不读取旧键或保留第二套 tier。peer child 或 Host 的唯一 SFU publication 各消耗一份,上游接收不消耗该预算,committed selected TURN 只替换同一份 logical edge 的 transport。客户端只能声明不高于部署值的可用容量,角色、浏览器、UA、设备类型和页面可见性不产生不同上限。服务端在每次 `authenticated` 权威快照中返回最终 `endpointMediaCopyCapacity`;普通非 peer-assisted 模式也只授权稳定加入顺序中的至多 `C` 个 Host child,超额 Viewer 保持入房等待并在槽位释放后提升,信令不能绕过该集合。Web 与 Native 严格校验该值,Native Host 的普通 Viewer admission、peer-assisted child assignment 和实际发送槽位都使用同一值,且不得从独立的房间 `maxViewers` 推导。并行产生媒体的 candidate 必须持有唯一的 `TransitionOverlapSlot`,并在 commit 后回到稳态上限;SFU subscriber egress 与 TURN allocation 由独立 server admission 记账。该不兼容能力变化与单一 signaling wire 原子升级;缺失或非法 cap 与旧客户端都在取得房间或 route authority 前 fail closed。
-- P2P 优先:每条普通逻辑媒体边先尝试 direct/peer UDP,服务器不得默认中转可直连媒体。更多观看者优先沿满足统一端点容量的无环 peer 图分布;每名 Viewer 同时至多一个 active upstream,失败时只影响需要重选的 child。任何 source-reachable endpoint 在 effective capacity 有空位时都可作为 parent candidate;Peer-fed 与 SFU-fed endpoint 使用同一个 provisional-child transaction,并在 candidate child 解码出第一帧新画面后独立提交该 edge。
+- P2P 优先:每条普通逻辑媒体边先尝试 direct/peer UDP,服务器不得默认中转可直连媒体。更多观看者优先沿满足统一端点容量的无环 peer 图分布;每名 Viewer 同时至多一个 active upstream,失败时只影响需要重选的 child。任何 source-reachable endpoint 在 effective capacity 有空位时都可作为 parent candidate;Peer-fed 与 SFU-fed endpoint 使用同一个 provisional-child transaction,并在 candidate child 解码出第一帧新画面后独立提交该 edge。Host 已满且首次需要 SFU 时,同一 reconcile 将 affected Host direct child(若无则稳定顺序中最新的 connected Host direct child)作为本次 child operation,创建唯一 Host publication 并把该 child 变为首个 SFU subscriber,subtree 不动;publication 取代释放的 Host peer slot,下一次扫描再处理原受限 Viewer,不建立 bootstrap 状态机。
- NAT 与传输边界:STUN 必须可用,所有 ordinary peer `RTCPeerConnection` 只接收 STUN ICE servers,普通边不得预发 TURN candidate。所有恢复和候选授权必须绑定 authenticated room/endpoint session、share generation、base/pending route revision 与 candidate connection identity;成功即停止,失败、超时或绑定失效即撤销,全部可用路径耗尽后明确等待或失败。已接受的顺序是保持既有 logical edge,必要时 direct/STUN 后使用 exact selected TURN;只有 logical ingress 不可用时才使用当前 Host publication 的 SFU subscription。Host 无 direct first-level path 时优先一条可经 TURN 的 Host-SFU publication,而不是逐 Viewer 建 Host-TURN peer 边。凭据不得进入应用页面 URL、日志、浏览器持久化或 SQLite;TURN 凭据和 Screener route grant 不进入任何 URL,LiveKit join JWT 仅按协议进入不得记录的 WebSocket request target。HTTPS/WSS 继续独立使用 TLS/TCP。
- 质量控制:保留 1080p60(8 Mbps)、1080p30(5 Mbps)、720p30(3 Mbps)三档推荐上限,三档与高级设置初始值统一采用 `balanced`(平衡)与 `automatic`(自动编码),`maintain-resolution`(清晰优先)、`maintain-framerate`(流畅优先)和 H.264/VP8 保留为显式选择。分享期间可直接换视频档位和 64/128/256 kbps 音频 sender ceiling,不重新选择来源或重建健康连接;视频 codec 首个可交付切换边界是在分享已显式暂停时执行有界重协商,未暂停热切换是后续复用同一事务的扩展。Peer-assisted relay 与已配置的 SFU 必须接收同一个严格校验的房间级权威设置,覆盖当前和以后建立的 sender;普通 P2P 信令结构保持不变。任何设置都只是浏览器上限和偏好,具体降级由浏览器决定;必须读回实际 sender 参数并通过 stats 观测结果、显示参数拒绝、改写和持续受限原因。不做自定义动态 FPS、综合评分或周期性全房间调档。
- 路径隔离双表示:direct/peer 继续使用每条 PeerConnection 独立的 stock WebRTC GCC,不把 viewer 反馈合成全房目标。每条 SFU path 从 `HIGH` ceiling 开始;优先使用 pinned LiveKit 的标准两层 screen-share simulcast,让内建 per-subscriber BWE 独立降层和恢复,Screener 不实现媒体层 selector。应用只诊断实际接收层、硬件编码、游戏性能、资源和上传;SFU 自动降层不改变拓扑。`LOW` 停编只是资源优化,active representation/layer 硬上限为二且不随 viewer 增长。当前 Web P2P simulcast 与 Web/LiveKit SVC 不能证明跨 direct/peer 共享编码或可移植硬件路径;全部标准路径失败后才考虑 custom/native dual encode。
@@ -83,7 +83,7 @@ SFU/TURN 的 publication、subscription、transport、server-resource accounting
- 首版不包含远程键鼠控制、公开/大规模直播、录制、社区系统或完整语音聊天;大规模分享直接使用现有直播服务。
- public-watch 只省略房间级 grant/password,不省略站点访问;房间码只定位,不提供隐私保证、目录或防转发承诺。现有每房 Viewer 上限、全局/未鉴权连接上限、房间上限和中央 egress/admission cap 仍适用,public-watch 不能创建无界服务器 fanout。
- SQLite 只用于持久房间身份与最小授权材料:房间 ID、Host token 摘要、nullable Viewer grant 摘要和 nullable 48-byte Viewer-password salt+verifier。不得保存 site access 密码、房间观看密码、token/grant 明文、cookie、显示名、成员、`clientId`、`peerId`、SDP、ICE candidate、IP 地址、媒体或 TURN 凭据;首版仍是单进程、单实例控制面。
-- Production 当前八名观看者和 1 至 16 配置范围只是接入边界,不承诺任意机器、档位、网络或跨洲路径都稳定承载;任何未来 admission 变化另行决策和验收。
+- 20-Viewer admission 是产品边界,不承诺任意机器、档位、网络或跨洲路径都达到相同画质;endpoint cap、SFU/TURN admission 和明确 wait/failure 继续保护资源。
- 浏览器规范要求每次由用户主动选择分享源,权限不能永久保存;纯网页不能保证指定游戏窗口或始终获得系统音频。
- 1080p60 是能力目标,实际分辨率、帧率和硬件编码由浏览器、GPU、驱动、画面复杂度及网络共同决定。
- 旗舰 release 的正常房间都可使用同一自动 controller;部署未启用总开关的轻量实例才保持标准 WebRTC P2P。Peer relay 只复用标准 remote-track WebRTC,不加入 Encoded Transform/DataChannel/WebCodecs 媒体协议,也不自研 UDP、编解码器、拥塞控制、FEC/RTX、多树、转码、codec ladder 或综合评分器。独立 native shared encode sender 不在本实验内;跨模式迁移受 ADR-0005 的 exact attempt、candidate-child first frame 和 typed resource admission 共同约束。
@@ -133,8 +133,8 @@ SFU/TURN 的 publication、subscription、transport、server-resource accounting
### 一对多与带宽保护
- Given `ENDPOINT_MEDIA_COPY_CAPACITY=C`,其中 `C` 只能是 `1`、`2` 或 `3` 且默认 `2`,When Host 或任一 Viewer 建立、恢复、重鉴权或迁移媒体路径,Then peer child 与 Host publication 的稳态实际发送副本总数不超过 `C`,upstream receive 不计数,committed selected TURN 不重复计数,角色、浏览器和 UA 不改变 `C`;每个 `authenticated` 快照都携带同一个 `C`,Native Host 不用 `maxViewers` 或本地常量代替它,并行候选只有持有 `TransitionOverlapSlot` 时才可达到 `min(C + 1, 3)`,并在 commit/abort 后释放。When 此能力合同上线,Then client/server/native wire 同一 release 原子升级,缺失或越界的 `C` 与旧 wire 都在房间授权前得到明确 mismatch,且 `C=3` 满载 Host 在取得会产生第四份 endpoint media copy 的 publication/token/grant 前明确等待或失败。
-- Given peer-assisted 路径分别运行 1、3、5、8 名观看者,When 用户加入、容量释放、节点离开、重鉴权或当前 edge 失效,Then 服务端只为新 Viewer、等待 Viewer 或失去 parent 的 subtree root 选择一个 active parent;每名 Viewer 同时至多一个 active upstream,活动图无环,其余健康边保持 sticky。没有可用 parent 时明确等待或拒绝,不主动重平衡或引入常驻多源媒体。
-- Given 一名分享者和八名观看者,When 在受控网络中运行已记录的质量档位,Then 记录每条边的拓扑深度、候选类型、码率、编码/解码负载、分享端与 relay 上行、首帧和玻璃到玻璃延迟;该条在真实矩阵完成前保持未验收。
+- Given peer-assisted 路径分别运行 1、5、10、20 名观看者,When 用户加入、容量释放、节点离开、重鉴权或当前 edge 失效,Then 服务端只为新 Viewer、等待 Viewer 或失去 parent 的 subtree root 选择一个 active parent;每名 Viewer 同时至多一个 active upstream,活动图无环,其余健康边保持 sticky。没有可用 parent 时明确等待或拒绝,不主动重平衡或引入常驻多源媒体。
+- Given 一名分享者和 20 名观看者,When 运行 bounded browser smoke,Then 全部 Viewer 取得明确媒体或 bounded wait/failure,非服务器端点不超过 `C`,并记录 route depth、首帧时间、实际 sender 数、应用服务器 CPU/内存以及 SFU/TURN 用量。该 smoke 验证 admission、控制面效能和资源上界,不单独证明任意公网画质或 30 分钟 endurance。
- Given candidate 改变房间 admission 默认值或上限,When 在目标数量与代表性路径上运行规定时长并注入 relay departure、重连和一个弱路径,Then 每名观看者持续解码、每个非服务器端点不超过配置容量、深度与故障半径有界、未受影响 subtree 不迁移,并记录端点与中央服务的 CPU、GPU、内存、上行、出口、帧率、丢包率、冻结和恢复;任一门槛失败时不得切换默认值。
- Given peer-assisted host 鉴权或直播中连续修改质量设置,When 服务端校验其分辨率、FPS、码率和偏好,Then 只有 host 的完整有界设置被接受,last-wins 地应用到当前和以后建立的 relay child sender 以及启用的 SFU publisher;越界、缺字段和多余字段被拒绝,普通 P2P 的鉴权 wire 不新增该字段且不接受同步消息。
- Given 标准浏览器把收到的 remote track 直接加入下游 `RTCPeerConnection`,When 检查 relay 统计和 libwebrtc 路径,Then 明确记录新的 outbound encoder、编码耗时和 CPU/GPU 限制,不把它当作 encoded forwarding 或 shared encode 成果。
@@ -180,7 +180,7 @@ SFU/TURN 的 publication、subscription、transport、server-resource accounting
## 待确认事项
-- 哪些分享端硬件、质量档位和网络条件能稳定承载默认 1:8 工作负载,以及实测后是否需要降低默认值。
+- 哪些分享端硬件、质量档位和网络条件能让 20-Viewer admission 全部持续取得目标画质,以及生产默认值应在 20 人 smoke 后设为多少。
- 项目许可证及是否计划闭源商用。
- 首批用户主要位于香港、内地还是跨地区;该信息决定 TURN 部署位置和测试矩阵。
- iOS Safari 与 Android Chrome 作为 Viewer 的最低版本及是否要求平板适配。