The session-stream web app: a single HTTP listener (9988) that serves a page
per enabled session, keyed by a spoken phrase.
src/hhstream_live/phrase.py four EFF-large words + a 5-char base-36 tail
(~77.5 bits); the phrase is the password
src/hhstream_live/publisher.py one capture thread + one frame slot per
output, one slot/no queue, capture paused at
zero viewers
src/hhstream_live/server.py the router: /, /<phrase>/, /stream.mjpg,
/frame.jpg, /status.json; unknown phrase is
an empty 404, rate-limited
src/hhstream_live/pages.py the built-in dark pages (no CDN, no build)
src/hhstream_live/__main__.py hhstream-live serve|phrase, standalone
The root page is a form, never a list: the phrase is known only by whoever
enabled the stream. Tests: tests/live (51), all green with the full suite
(958). Not yet wired to the broker -- that is stage 2.
175 lines
11 KiB
Markdown
175 lines
11 KiB
Markdown
# 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 root page is a form, never a list.** The phrase is the password to a
|
||
stream and is known only by whoever enabled it, so `/` must not enumerate
|
||
sessions or leak phrases: it is a box you type a phrase into, which forwards
|
||
to `/<phrase>/`. `/<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>-<xxxxx>`, e.g.
|
||
`amber-otter-lantern-harbor-7k2qp`.
|
||
- Words come from a **vendored EFF large wordlist** (7776 words, ~70 KB, in the
|
||
repo — no network at runtime, no dependency) and the tail is five characters
|
||
of `[a-z0-9]`. Four words is `4 · log2(7776) ≈ 51.7` bits and the tail adds
|
||
`5 · log2(36) ≈ 25.8`, for **≈ 77.5 bits** — comfortably past anything a LAN
|
||
request rate can enumerate, and the operator's stated shape ("5 with a random
|
||
5 character string for the last word").
|
||
- `--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. Decisions taken (2026-10-04)
|
||
|
||
1. **The root page is a form, never a list.** The phrase is a password; the
|
||
index must not hand it out. (Was "loopback-only index".)
|
||
2. **Phrase = four EFF-large words + a five-character base-36 tail (~77.5
|
||
bits).** The tail is what the operator asked for in place of a fifth word.
|
||
3. **Port 9988**, fixed and single, no range fallback.
|
||
4. **Capture pauses at zero viewers** (v1's choice, kept).
|
||
|
||
**Stage 1 is built** (`src/hhstream_live/`, `tests/live/`, 51 unit tests): the
|
||
router, the pages, the phrase and the publisher, runnable standalone via
|
||
`hhstream-live serve --stream PHRASE=OUTPUT`. The broker verbs and
|
||
`/run/hhstream/live.sock` are Stage 2. |