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: accept per-share route policy gates (#298)

AAA2307714af02b
diff --git a/docs/adr/0005-automatic-hybrid-media-routing.md b/docs/adr/0005-automatic-hybrid-media-routing.md
index f8cb958c..b6c737c9 100644
--- a/docs/adr/0005-automatic-hybrid-media-routing.md
+++ b/docs/adr/0005-automatic-hybrid-media-routing.md
@@ -227,6 +227,12 @@ result converges gradually to a local stable topology: no current degraded edge
has a proved healthy candidate under the current graph and resource facts. It
does not promise a static mathematical global optimum.
+Two pre-share gates constrain this same controller. Peer-only policy removes
+every SFU tuple and bootstrap path before reservation, so exhaustion keeps the
+existing explicit failure. The initial topology-convergence rollout is opt-in;
+when disabled, native evidence never creates quality work. Both gates are bound
+to share generation and cannot change while sharing.
+
## Consequences
Positive:
diff --git a/docs/product/routing-transport.md b/docs/product/routing-transport.md
index a660840a..c79064cf 100644
--- a/docs/product/routing-transport.md
+++ b/docs/product/routing-transport.md
@@ -20,6 +20,21 @@ The flagship deployment enables the all-room controller. A lightweight
deployment may disable peer assistance and keep only bounded direct Host edges;
it does not gain another transport or compatibility protocol.
+## Per-Share Route Policy
+
+The Host chooses route policy before sharing and it remains fixed for that
+share generation:
+
+- default hybrid mode keeps P2P first and permits the bounded SFU suffix;
+- peer-only mode excludes SFU publication, subscription, bootstrap, and quality
+ candidates, while retaining the same bounded Peer graph and clear exhausted
+ failure; and
+- native-edge topology convergence is initially opt-in. When disabled, quality
+ evidence stays diagnostic and availability routing is unchanged.
+
+These are route-policy gates, not new routing algorithms. Changing either
+policy requires stopping the current share and starting another generation.
+
## Endpoint And Server Capacity
Every non-server endpoint has one server-authoritative steady outbound media-
diff --git a/docs/project-memory.md b/docs/project-memory.md
index 73acb204..991d68c6 100644
--- a/docs/project-memory.md
+++ b/docs/project-memory.md
@@ -31,7 +31,8 @@ implementation and routine UI detail.
participants, routes, and media remain process-only.
- Media is automatic and distributed. Ordinary peers are STUN-only and prefer
direct/peer UDP. The only application fallback is one bounded LiveKit SFU/UDP
- publication; Screener configures no TURN or TCP media route.
+ publication; Screener configures no TURN or TCP media route. A pre-share
+ peer-only policy can exclude that SFU suffix for one share generation.
- Every endpoint shares one steady outbound-copy cap, default `2` and limited to
`1..3`. One room controller owns one committed graph, one reconcile loop, and
one serial child operation. First decoded frame commits availability work;
@@ -39,8 +40,9 @@ implementation and routine UI detail.
- WebRTC and LiveKit own congestion control, media adaptation, reconnect, and SFU
layers. Current source keeps route quality diagnostic. The accepted next slice
is event-driven local topology convergence from their native edge state, with
- bounded SFU only after healthy Peer escape fails. No weighted score, all-pairs
- probe, parent-wide prediction, or periodic rebalance is accepted.
+ bounded SFU only after healthy Peer escape fails. Its initial per-share gate is
+ opt-in; no weighted score, all-pairs probe, parent-wide prediction, or periodic
+ rebalance is accepted.
- Browser video uses `motion`; each share chooses H.264 with VP8 fallback through
an actual sender probe unless the Host explicitly selects VP8 or H264. Screen
audio uses 64/128/192 kbps ceilings with 128 default.
diff --git a/docs/todo.md b/docs/todo.md
index 764bfdb0..92a7b499 100644
--- a/docs/todo.md
+++ b/docs/todo.md
@@ -9,7 +9,8 @@ topics are not implementation authority.
1. **Native-edge topology convergence.** Implement ADR-0005's categorical
`unknown | healthy | degraded` evidence, availability-first local moves, one
- serial candidate, and bounded Host-to-SFU suffix. Current production remains
+ serial candidate, bounded Host-to-SFU suffix, default-off pre-share rollout
+ gate, and default-off peer-only policy. Current production remains
observation-only until focused route and Browser gates pass.
## Parked Repository Work
@@ -33,23 +34,21 @@ topics are not implementation authority.
3. **Representative network acceptance.** Complete public-network direct,
Browser relay, SFU, recovery, Pause/Resume, screen-audio, real-game A/V,
two-room SFU, 20-Viewer endurance, and all-UDP-blocked bounded failure.
-4. **Per-share peer-only mode.** Add one default-off pre-share Host setting that
- excludes SFU for that share and ends in the existing bounded failure.
-5. **Whole-product UI and bilingual decision.** Review copy, responsive
+4. **Whole-product UI and bilingual decision.** Review copy, responsive
hierarchy, visual consistency, restrained motion, rendering cost, terminal
navigation, and Chinese/English scope once media behavior stabilizes.
-6. **Client-input security review.** Audit HTTP/WebSocket schema, auth,
+5. **Client-input security review.** Audit HTTP/WebSocket schema, auth,
authorization, rate/body/resource bounds, errors, logs, and secrets without
adding a parallel security framework.
-7. **Public-server package.** Package the exact Web/signaling, STUN/SFU, proxy,
+6. **Public-server package.** Package the exact Web/signaling, STUN/SFU, proxy,
secrets, health, and recovery contract for a user-owned server.
-8. **Fully local package.** Package Host capture, application server, and local
+7. **Fully local package.** Package Host capture, application server, and local
state for Windows/macOS/Linux with honest TLS, gateway, NAT, and firewall
limits.
-9. **Native Host and shared encode.** Revisit Windows first only after capture,
+8. **Native Host and shared encode.** Revisit Windows first only after capture,
hardware encode, audio, RTP feedback, resources, packaging, licensing, and
Browser interoperability are proved.
-10. **Platform output.** Revisit AirPlay/Cast only when a target Browser and
+9. **Platform output.** Revisit AirPlay/Cast only when a target Browser and
physical receiver prove the live `MediaStream` contract.
## Decision Needed