From 02d5006524337b202c55499983ae490dfecb5bd2 Mon Sep 17 00:00:00 2001 From: Hermenix Date: Sun, 4 Oct 2026 00:30:21 +0000 Subject: [PATCH] docs(plan): one port, a router, and a phrase per session The operator rejected the port-range/token shape: a single port (9988) with a router, four routes per session output, and a spoken phrase as the key. Streams are opt-in per session (default off) and capture only while watched. Phrase is four EFF-large words (~51.6 bits); index is loopback-only by default. Supersedes 2026-10-03-network-stream.md. --- docs/plans/2026-10-03-network-stream.md | 6 + .../plans/2026-10-04-session-stream-webapp.md | 170 ++++++++++++++++++ 2 files changed, 176 insertions(+) create mode 100644 docs/plans/2026-10-04-session-stream-webapp.md diff --git a/docs/plans/2026-10-03-network-stream.md b/docs/plans/2026-10-03-network-stream.md index 537b685..4c60882 100644 --- a/docs/plans/2026-10-03-network-stream.md +++ b/docs/plans/2026-10-03-network-stream.md @@ -1,3 +1,9 @@ +> **Superseded (2026-10-04):** the operator asked for one port (9988) with a +> router and a phrase per session, only for enabled sessions — see +> `docs/plans/2026-10-04-session-stream-webapp.md`. This file is kept for its +> transport table and its capture/idle-clock reasoning, which the new plan +> inherits. + I'll explore the frame server, session CLI, broker, contracts, and the NixOS module first, then write a plan only — no edits.The tree is a Python frame server, a session broker, and a pointer daemon. Next I’ll read the contracts and the capture/session paths those decisions depend on.The publisher cannot select a session today. `hhstream-server` serves one output on `/run/hypr-stream/stream.sock` and its command line is frozen. `hhstream shot --output hh-` and `record --output` are separate `grim -o` one-shots. A phone view should be a new, view-only listener beside that, not a change to the socket Hermenix already reads. ## Decisions diff --git a/docs/plans/2026-10-04-session-stream-webapp.md b/docs/plans/2026-10-04-session-stream-webapp.md new file mode 100644 index 0000000..0bee3cd --- /dev/null +++ b/docs/plans/2026-10-04-session-stream-webapp.md @@ -0,0 +1,170 @@ +# Plan — a session-stream webapp (one port, a router, a phrase per session) + +Supersedes `docs/plans/2026-10-03-network-stream.md` (call it v1). v1 spread a +listener over a **port range** and handed each session a **128-bit URL token**; +the operator asked for the opposite shape: **one port, a router with a page per +session, and a spoken phrase** to open each one, with a stream existing **only +for the sessions it was enabled on**. Everything v1 says about the *capture* +path and the *separate unit* still holds and is not repeated here; this file +replaces §2–§4 of v1 and keeps its §1 (transport) and §6 stages in spirit. + +Decisions below are the ones worth disagreeing with. **Nothing is built yet** — +the branch carries only a plan. + +--- + +## 1. What is new, and why + +| v1 | Now | Why | +| --- | --- | --- | +| Lowest free port in `9120–9131`, one per session | **One port, default 9988**, shared by every stream | A phrase is easier to read out when there is one address, not one per session. One listener is also one thing to firewall and one thing to stop. | +| `//…`, a `secrets.token_urlsafe` blob | **`//…`**, four words off a fixed list | A URL a person can say out loud and retype on a phone. Same job as the token — it is the only credential — but shaped for a human. Entropy is discussed in §4. | +| `stream start` on any live session | **`stream enable`** on a session, remembered, default **off** | "Not on for all sessions at all times": a session does not stream because it exists; it streams because it was switched on. | +| Pages are token routes under one session's listener | **A router**: an index, and **four routes per session** (viewer, stream, snapshot, status) | A small app, not a file dump: `/` lists what is on, `//` is the thing you watch. | + +The transport is unchanged: **MJPEG over HTTP** (`multipart/x-mixed-replace`), +the JPEG `grim` already produces (`-c -t jpeg -q 80 -`), 5 fps default, hard cap +10, capture **only while a viewer is connected**. A still browser `` is the +whole client. No WebSocket, no HLS, no TLS in this slice. + +## 2. The unit, and the port + +`hhstream-live.service`, **one process**, exactly as v1 argued: an executor +beside the pointer driver, not the frame server (whose one-socket contract must +not grow a LAN parser) and not the broker (`grim` blocks tens to hundreds of ms +and must not stall `touch`/`kill`). It runs as the compositor user `hhstream`, +finds `WAYLAND_DISPLAY` the way `hyprland-headless-stream` does, does **not** +take `RuntimeDirectory=/run/hhstream` (that would delete the broker's socket), +and speaks newline-JSON to the broker on `/run/hhstream/live.sock`. + +It owns **the port**. A single listener means no allocator, no `TIME_WAIT` +dance, and one URL prefix. The port is a module option (`sessions.stream.port`, +default **9988**); the unit binds `sessions.stream.bind` (default `127.0.0.1`). +If the port is taken the unit fails loudly and says so — it does not hunt for +another one, because a stream at a port nobody was told is worse than a stream +that is down. + +**Bind and firewall defaults stay closed.** `openFirewall` defaults false; the +module adds no `networking.firewall.allowedTCPPorts` unless it is set. Until +that opt-in, the phone path is `ssh -L 9988:127.0.0.1:9988` from the device. + +## 3. The router + +One handler, four shapes, phrase-keyed. Everything else is a `404` with an +empty body; a wrong phrase is never echoed back. + +``` +GET / index: the enabled streams, their names, viewer + counts, and links into them +GET // the viewer page — an + in a dark frame with the session's name +GET //stream.mjpg the multipart/x-mixed-replace stream +GET //frame.jpg the most recent single JPEG (snapshot) +GET //status.json {session, output, fps, viewers, last_frame_age_s} +``` + +- The phrase is matched **case-insensitively** and tolerates a missing trailing + slash, because a person will type it by hand; it is stored lowercase. +- **The index is loopback-only by default.** Over the LAN, `/` is a `404` unless + `sessions.stream.publicIndex = true`. It lists phrases, so serving it to the + network hands out every key at once; on the operator's own machine it is the + convenient landing page. `//…` always works from whatever the bind + allows. +- The pages are **built-in** — one small HTML/CSS/JS string in the package, no + CDN, no framework, no extra Python dependency. "Webapp" here means a real + router and legible pages, not a build step. +- Multiple pages **per session output**: a session's output `hh-` gets its + own four routes; adding a session adds routes under its phrase, never a new + port. +- Wrong-phrase lookups are **rate-limited** (a small per-IP counter, ~20/min) so + the phrase is not enumerable at line speed over the LAN. + +## 4. The phrase + +Generated when the stream is **first enabled** for a session, and kept in the +session record so it survives a broker restart and a re-enable. + +- Shape: `---`, e.g. `amber-otter-lantern-harbor`. +- Words come from a **vendored EFF large wordlist** (7776 words, ~70 KB, in the + repo — no network at runtime, no dependency). Four words is + `4 · log2(7776) ≈ 51.6` bits, which is the number that matters: at a LAN's + request rate that is not brute-forceable, and it matches what the 128-bit + token bought in practice (the token was only ever a bearer string in a URL). + Raise to five words with one constant if that is judged thin. +- `--phrase` on enable sets your own (checked against the shape); `disable` + then `enable` **rotates** it. A rotation is one record write. +- The phrase is the only credential. It is in the URL, in cleartext on the LAN + when the LAN is opted into — the threat model is "another device on the LAN + can watch if it can guess the phrase", not "the phrase is hidden from the + network". Stated plainly so nobody mistakes it for TLS. +- Secrets discipline from v1 carries over: the audit log records session id, + output, port and bind; it **never** records the phrase. + +## 5. Enable / disable, and the idle clock + +Only an enabled session has a phrase, a listener entry, and any capture at all. +Enabling is an explicit act, remembered in the record: + +``` +hhstream session stream enable [--phrase PHRASE] [--fps N] +hhstream session stream disable +hhstream session stream list # enabled streams, phrases, viewers +hhstream session stream status [id] +``` + +- `enable` requires the session to have a container output (`hh-`); without + one it is the existing `no_container` error (exit 10). A stream never falls + back to the main output — that would put every other session on the phone. +- `enable` prints **only the URL** on stdout (`http://127.0.0.1:9988//`); + stderr names the output and prints the `disable` command. `--json` adds + `url`, `phrase`, `output`, `fps`, `viewers`. Re-enabling while enabled returns + the same phrase; `--phrase` mismatch is `stream_busy` (exit 8). +- No new exit numbers: reuse 2 (bad port/fps), 6 (`stream_budget` — the module's + per-process viewer cap), 8 (busy), 10 (`stream_unavailable`/no container). +- `enable`, `disable`, `list`, `status` do **not** touch the idle clock — the + same rule as `pointer.*`. A **connected viewer is activity**: about once a + minute the broker asks the daemon for viewer counts and stamps `touch` when + any is non-zero. That is the one new way the clock moves; it is what keeps a + session the operator is watching on his phone from being reaped at three + hours. An enabled stream with nobody watching runs **no** `grim` and keeps no + session alive. +- The session record gains `stream = {enabled, phrase, fps, viewers, port}` + (or `null`). **Registry schema 3 → 4**; older records migrate to + `stream: null` and are adopted, not refused. +- Teardown order is v1's and it is load-bearing: `disable` the stream (close the + listener, drop the route) **before** `hyprctl output remove`. + +## 6. Restart behaviour + +A broker restart does **not** invent listeners. If `hhstream-live` is still up, +the broker asks it for the list and re-attaches them to the session records, so +`status` and teardown still see them. If the daemon restarted too, the enabled +records keep their phrases but the streams are off until re-enabled — an open +port and a running capture are explicit acts, and the phrase is not a licence to +capture without one. + +## 7. What to build, in what order + +| Stage | What | Size | Risk | +| --- | --- | --- | --- | +| 0 | Contract text: `docs/CONTRACT-sessions.md` → **sessions-v3** (the four verbs, `/run/hhstream/live.sock`, `hhstream-live`, the single port, the viewer-touch exception, schema 4, error names). | S | Freezing the wrong default. This plan is the review. | +| 1 | `hhstream-live`: the HTTP server, the router, the phrase (wordlist + generator), one output, injected capture, **unit tests**. No broker. | M | A phone that will not paint `multipart/x-mixed-replace`; the index leaking phrases when made public. | +| 2 | Broker + CLI: the record field, schema 4, the four verbs, teardown order, viewer heartbeat, integration test on `127.0.0.1`. | L | A second capture on re-enable; `disable` racing `output remove`; a heartbeat that keeps a session alive with zero viewers. | +| 3 | Module: the unit, `/run/hhstream/live.sock`, `port` 9988, `bind` loopback, `fps` 5/cap 10, `enable` false, `openFirewall` false, `publicIndex` false. No host firewall edit here. | M | A second `RuntimeDirectory` on `/run/hhstream` deleting `control.sock`. | +| 4 | Host pass: enable a real session, open the URL in the machine's own Chromium, confirm pixels change without a reload; write down what was on screen. | S | An empty container looking like a broken stream. Confirm the window is on `hh-` first. | + +Test layers are v1's: `tests/unit` for the HTTP/router/phrase with a fake +capture (multipart framing, each route, wrong phrase → empty 404, rate limit, +capture idle at zero viewers, "unknown output" ends the stream), `tests/sessions` +for the verbs and the clock, one integration test that runs a real daemon and a +real `hhstream-live` on loopback with `urllib` reading two JPEGs. VM checks stay +one at a time; no browser in a VM check. + +## 8. Open questions to answer before Stage 1 + +1. **Public index.** Loopback-only by default — agreed? (It lists phrases.) +2. **Phrase length.** Four EFF-large words (~51.6 bits). Five if you want more + head-room at the cost of typing. +3. **Port 9988.** Fixed, single, no range fallback. Confirm the number. +4. **Capture at zero viewers.** Paused (v1's choice, kept here) versus always-on + while enabled. Paused is cheaper and the reason the idle rule is safe. \ No newline at end of file