Free, open-source screen sharing for private live streams with friends. Watch together in a browser or self-host Piik. 免费开源的私密屏幕共享,支持游戏直播、一起看电影与自部署。
docs: record persistent room deployment (#11)
AAA919c5588109d
diff --git a/docs/project-memory.md b/docs/project-memory.mdindex 94170092..bbaaf75c 100644--- a/docs/project-memory.md+++ b/docs/project-memory.md@@ -9,7 +9,7 @@ Last updated: 2026-08-18- The normal use case is a small, trusted friend group. Public or large-scale streaming is explicitly out of scope and can be handled by OBS/Twitch-class services.- Viewers should be able to open an invite link in a desktop or mobile browser without installing a dedicated client.- The system should resemble a Photon-style developer experience: a central room/rendezvous service establishes sessions while realtime traffic is carried by clients whenever possible.-- Server bandwidth cost is a primary constraint. The media path must be P2P-first, with servers used for signaling, STUN, TURN fallback, and observability. SFU is outside the normal small-room scope.+- Server bandwidth cost is a primary constraint. The default media path remains P2P-first, with servers used for signaling, STUN, TURN fallback, and observability. A deployment-level SFU mode is acceptable when measured multi-viewer P2P behavior is unusable; it must remain explicit and independently reversible.- Avoiding TeamSpeak-like partial reachability is a primary requirement: every broadcaster-viewer pair must independently have TURN/UDP and TURN/TCP candidates available when direct ICE cannot connect. TURN/TLS is an optional compatibility enhancement, not a production prerequisite.- A web experience is preferred for convenience, but using a desktop sender is acceptable when it materially improves game capture, audio capture, or hardware encoding.- All project documentation, memory, code, `AGENTS.md`, and `.codex/` configuration must live in this Git repository and remain tracked for cross-device development.@@ -28,7 +28,7 @@ Last updated: 2026-08-18- Do not add custom scene detection or dynamic-FPS control until WebRTC statistics and host resource measurements show that browser capture, encoding, and congestion behavior leave a material problem.- Leave codec order at the browser default in the first PoC and record the negotiated codec, encoder implementation, and power efficiency. Prefer H.264 only after target-machine measurements show that it is the hardware-efficient path; retain VP8 compatibility.- Add an Electron or native Windows sender only after browser measurements identify capture, application-audio, or encode bottlenecks.-- Do not plan an SFU for the normal small-room product path. Reconsider it only if the product scope or real telemetry later invalidates the P2P envelope; never implement peer forwarding trees in the MVP.+- Keep P2P as the default and add only an explicit deployment-level `p2p|sfu` choice. Multi-viewer use has already shown severe user-observed P2P degradation, consistent with one sender and encoder per viewer. The first SFU experiment should use a single node, one published layer, and no automatic switching, hybrid path, Redis, or peer forwarding tree.- Keep room policy deployment-driven and small. Public and password-only deployments use random temporary rooms. A deployment that configures both the whole-site password and a SQLite path gets sequential, non-expiring protected rooms; stopping a share leaves viewers waiting and does not destroy the room.## Current Implementation@@ -36,10 +36,10 @@ Last updated: 2026-08-18- The repository contains a single npm package using Node.js 24, React, TypeScript, Vite, native WebRTC, `ws`, Zod, Vitest, and a separate coturn deployment. The server defaults to an all-interface listener for LAN development and containers; the bare-metal reverse-proxy baseline explicitly binds loopback. It provides a process-only `/healthz` endpoint and requires STUN plus explicit TURN/UDP and TURN/TCP URLs before production startup. TURN/TLS is accepted but optional; configuration checks do not establish public-network reachability.- The Web PoC implements capture-before-room creation, live source replacement without renegotiating healthy peers, one independent peer connection per viewer, stable signaling reconnect identities that also work for LAN viewers on HTTP, explicit ICE restart or peer rebuild, host session generation isolation, viewer connection-generation guards for asynchronous signaling and stats, short-lived TURN credentials, three manual quality profiles, and local WebRTC statistics.- Access is deliberately small: `ACCESS_PASSWORD` is optional, site-wide, and accepts 1 through 128 visible ASCII characters when non-empty. When configured, host and viewer routes first establish a 12-hour stateless HMAC HttpOnly `SameSite=Strict` cookie; room creation and WebSocket upgrade accept that cookie and no direct room-creation Bearer bypass. There are no accounts, JWTs, server-side access-session maps, or logout flow.-- ADR-0002 accepts an optional `ROOM_DATABASE_PATH` only alongside `ACCESS_PASSWORD`. In that mode, built-in `node:sqlite` stores only an auto-incremented room ID and host-token digest; links do not expire and stopping sharing leaves the room waiting. Without the path, rooms remain random and temporary. Public mode can never use sequential persistent rooms. The branch's 102 Vitest tests and builds pass locally; `/var/lib/screener/rooms.sqlite` has not yet been deployed or verified in production.+- ADR-0002 accepts an optional `ROOM_DATABASE_PATH` only alongside `ACCESS_PASSWORD`. In that mode, built-in `node:sqlite` stores only an auto-incremented room ID and host-token digest; links do not expire and stopping sharing leaves the room waiting. Without the path, rooms remain random and temporary. Public mode can never use sequential persistent rooms. Commit `2f66770f8e90` is deployed with `/var/lib/screener/rooms.sqlite`; the state directory and database permissions are verified, and the empty database preserves ID `1` for the first real browser room.- `/r/{code}` carries no viewer token or fragment, `/join` accepts only the numeric code, and the 256-bit host token stays internal to host authentication. In public mode the random code is the sole viewing capability and is not a strong privacy guarantee, so private Internet deployments should configure `ACCESS_PASSWORD`.- The Web control plane is deployed at `https://share.bonfire.icu` behind nginx with Node.js 24.19.0, and `turn.bonfire.icu` runs authenticated coturn 4.17.2 on standard UDP/TCP 3478. HTTPS, WSS, room authentication, certificate renewal, public STUN, authenticated TURN/UDP and TURN/TCP allocations, and relay-only bidirectional data paths are verified. TURN/TLS is intentionally not enabled.-- Automated checks pass on the persistent-room branch with 102 Vitest tests and both production builds. Same-machine synthetic-media Chromium recovery and public relay-only DataChannel evidence remains from the deployed baseline. Production room-persistence, real screen/game audio, full Screener media sessions across heterogeneous networks, mobile lifecycle handling, and latency or quality targets remain unverified.+- Automated checks pass on current `main` with 102 Vitest tests and both production builds. Same-machine synthetic-media Chromium recovery and public relay-only DataChannel evidence remains from the earlier baseline. Production storage startup and permissions are verified; a real persistent-room stop/reuse/restart cycle, real screen/game audio, heterogeneous media sessions, mobile lifecycle handling, and latency or quality targets remain unverified.- No infrastructure blocker remains for the current staging deployment. The immediate control-plane milestone and the separate real-device/media matrix are bounded in `docs/status.md`; neither justifies a native sender yet.## Provisional Quality Targets@@ -52,7 +52,7 @@ Last updated: 2026-08-18## Open Decisions-- The sustainable viewer count for each publisher hardware, quality profile, and network class; real 1:8 behavior is still unverified.+- The sustainable viewer count for each publisher hardware, quality profile, network class, and media mode. Current P2P use degraded severely as viewers increased; that observation needs instrumented 1/3/5/8 comparison rather than a 1:8 support claim.- Exact mobile browser support matrix and the required behavior around autoplay, backgrounding, orientation changes, and network handoff.- Whether the first release is open source, source-available, or proprietary; this affects whether GPL/AGPL projects can be reused rather than only studied.- Initial deployment regions and expected mainland China/Hong Kong/overseas network mix.diff --git a/docs/status.md b/docs/status.mdindex 00a130b2..84cf1cf9 100644--- a/docs/status.md+++ b/docs/status.md@@ -4,7 +4,14 @@ Last updated: 2026-08-18## Phase-The WebRTC proof of concept is deployed at `https://share.bonfire.icu`. The `feat/persistent-rooms` branch adds optional protected SQLite persistence, sequential room IDs, reusable links, and a waiting state after sharing stops. Checks pass locally, but the branch is not yet deployed. Real capture, game audio, sustained 1:8 behavior, mobile lifecycle, and performance targets remain unverified.+The WebRTC proof of concept is deployed at `https://share.bonfire.icu`. Commit+`2f66770f8e90` adds protected SQLite persistence, sequential room IDs, reusable+links, and a waiting state after sharing stops. The production database is+initialized and empty, so the first real persistent room can receive ID `1`.+Real capture, game audio, mobile lifecycle, and performance targets remain+unverified. Increasing the P2P viewer count has already caused severe user-+observed degradation, so an explicitly configured SFU mode is the next media+experiment; P2P remains the default topology.## Established Baseline@@ -19,11 +26,11 @@ The WebRTC proof of concept is deployed at `https://share.bonfire.icu`. The `fea## Verification-- On the current persistent-room branch, `npm run check` passes type checking,+- On current `main`, `npm run check` passes type checking,102 Vitest tests, the client production build, and the server production build.-The remaining browser and network evidence predates this branch; it does not-verify the new storage or lifecycle contract.+The remaining browser and network evidence predates the persistent-room rollout;+it does not verify a real browser stop-and-republish cycle with room ID `1`.- Headless Chromium 151 created real local peer connections from animated canvas streams. The viewer reached `connected`, received a live video track, and reported a direct UDP path.- Browser fault injection recovered after dropping the first offer, dropping the first answer, and failing the first `createOffer`. A viewer-only signaling reconnect preserved the existing healthy media peer; replacing that viewer tab rebuilt media, released the old peer, and did not enter a reconnect loop.@@ -35,30 +42,29 @@ verify the new storage or lifecycle contract.- The application defaults to `LISTEN_HOST=0.0.0.0` for LAN development and containers, while the bare-metal reverse-proxy deployment explicitly uses loopback. It exposes a process-only `GET /healthz` liveness response.- Viewer session identities use `crypto.getRandomValues()` rather than the secure-context-only `crypto.randomUUID()`, so a phone can initialize the viewer over trusted LAN HTTP while the host keeps screen capture on `localhost`.- The staging host runs Debian 12, nginx, Node.js 24.19.0, and source-built coturn 4.17.2. Screener binds loopback behind nginx; authenticated STUN and TURN/UDP+TCP bind `turn.bonfire.icu:3478`. TURN/TLS remains intentionally disabled.-- Commit `8e6039d89bc8` is deployed. Production verification covered the anonymous session response, rejection of anonymous room creation and WebSocket upgrades, the `Secure`/`HttpOnly`/`SameSite=Strict` host-only cookie, numeric room creation, and host/token-free viewer WebSocket authentication. Certbot's renewal dry run also passed for both the existing blog and Screener certificates; the existing blog continued returning HTTP 200.+- Commit `2f66770f8e90` is deployed. Production verification covered rejection of the previous password, login with the current password, the `Secure`/`HttpOnly`/`SameSite=Strict` cookie, the initialized empty SQLite schema, service state directory mode `0700`, database mode `0600`, and a clean service restart with zero automatic restarts. The prior room and WebSocket authentication checks remain applicable. The existing blog continued returning HTTP 200.- Public STUN Binding succeeds over both UDP and TCP 3478. Chromium 151 obtained authenticated relay candidates through TURN/UDP and TURN/TCP, then two relay-only peer connections completed a bidirectional DataChannel ping/pong over each transport. Simultaneous guest conntrack samples observed both 3478 control traffic and relay-range UDP traffic, independently confirming the public TURN path through the cloud and host firewalls.- The existing TeamSpeak files, services, timers, and ports were not changed.## Next Milestone-First complete and record branch verification without conflating it with the deployed baseline:+Preserve the first real room for the normal browser workflow, then verify room ID+`1`, stop-and-republish waiting behavior, link reuse, and recovery after a service+restart. In a separate PR and ADR, add a deployment-level `p2p|sfu` media mode+using a single-node SFU; do not add automatic switching, hybrid sending, Redis,+or multi-node infrastructure before measurements justify them.-- configuration boundaries for 1 through 128 visible-ASCII access passwords and rejection of a database path without a password;-- SQLite allocation from `1`, restart recovery, data minimization, non-expiring room links, and stop-sharing waiting behavior;-- public and password-only random temporary rooms, including TTL cleanup;-- the writable `/var/lib/screener/rooms.sqlite` path under the tracked systemd hardening policy.--Performance measurement and any topology reconsideration stay in a separate PR/ADR. Execute and record the manual browser/network matrix there:+Execute and record the manual browser/network matrix for both applicable modes:- real screen/window capture and available game or system audio on Windows Chrome and Edge;-- one broadcaster with eight heterogeneous viewers for 30 minutes, while also recording lower viewer counts to locate the sustainable envelope;+- one broadcaster with 1, 3, 5, and 8 heterogeneous viewers, recording publisher upload and encode load plus server ingress and egress to locate each sustainable envelope;- same-LAN direct, cross-network direct, a forced-relay Screener media session, mixed direct/relay, and a UDP-blocked TURN/TCP path; test TURN/TLS separately only when deployed;- Android Chrome and iOS Safari playback, orientation, backgrounding, and network handoff;- actual codec implementation, encode load, publisher upload, bitrate, frame rate, first picture, and glass-to-glass latency. Custom dynamic-FPS logic remains intentionally unimplemented until these measurements show a gap in browser capture, encoding, and congestion behavior.## Current Blocker-- No infrastructure blocker remains for the current staging deployment. Automated restart persistence is covered locally; the persistent-room branch still needs real systemd filesystem-permission and deployment verification before rollout. The real-device and real-media matrix remains separate work.+- No infrastructure blocker remains for the current deployment. Persistent storage and systemd filesystem permissions are active; the first real browser room lifecycle and the separate P2P/SFU media matrix remain unverified.## Blocking Decisions