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.
This commit is contained in:
Hermenix committed 2026-10-04 00:30:21 +00:00
1 parent deccfb592c
commit 02d5006524
2 files changed
+176

No files matched your search

+6
View File
@@ -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-<id>` 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. 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-<id>` 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 ## Decisions
@@ -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. |
| `/<token>/…`, a `secrets.token_urlsafe` blob | **`/<phrase>/…`**, 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, `/<phrase>/` 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 `<img>` 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 /<phrase>/ the viewer page — an <img src="stream.mjpg">
in a dark frame with the session's name
GET /<phrase>/stream.mjpg the multipart/x-mixed-replace stream
GET /<phrase>/frame.jpg the most recent single JPEG (snapshot)
GET /<phrase>/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. `/<phrase>/…` 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-<id>` 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: `<word>-<word>-<word>-<word>`, 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 <id> [--phrase PHRASE] [--fps N]
hhstream session stream disable <id>
hhstream session stream list # enabled streams, phrases, viewers
hhstream session stream status [id]
```
- `enable` requires the session to have a container output (`hh-<id>`); 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/<phrase>/`);
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-<id>` 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.