`sessions.stream { port, bind, openFirewall }` -- the piece of stage 3 that
does not need the broker. It exists because a machine had to be able to *reach*
a stream before the rest of the app is settled: the operator asked for the port
to be open on the deployment machine, where the app still runs by hand, and a
bare `networking.firewall.allowedTCPPorts` line in one machine's config is the
wrong place for a fact about this flake.
- `openFirewall` defaults false and is deliberately not implied by
`sessions.enable`: a live view of the desktop is readable by anyone who can
reach the port, the phrase in the URL is its only credential, and there is no
TLS. It opens exactly one port -- the one the option names.
- `bind` defaults to loopback and is *checked*: `openFirewall = true` beside a
loopback bind is refused, because that is a hole with no service behind it.
- `checks/vm-stream-firewall.nix` boots the module with a configured port that
is not the module's default, puts listeners on that port and on a neighbour,
and asserts from a second machine on the same VLAN that the peer reaches the
configured port and is refused on the other -- while both answer on loopback
inside the guest, so the refusal is the firewall's doing and not an empty
socket. The peer is a second machine because a probe from the test driver
proves nothing: the driver is not on the test VLAN.
Nothing here turns a stream on -- no unit, no phrases, no `session stream`
verbs, which stay stage 2+3 -- and docs/plans/2026-10-04-session-stream-webapp.md
now records which part of its stage 3 landed and why out of order.
195 lines
12 KiB
Markdown
195 lines
12 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 lines, ~70 KB, in the
|
||
repo — no network at runtime, no dependency) and the tail is five characters
|
||
of `[a-z0-9]`. Four of those lines are hyphenated (`drop-down`, `felt-tip`,
|
||
`t-shirt`, `yo-yo`) and are dropped on load, because a hyphen is the phrase's
|
||
own separator and such a word would make a six-token phrase nobody could hear
|
||
the shape of; **7772 words** are usable. Four words is `4 · log2(7772) ≈ 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, and it is held to **exactly the generated
|
||
shape** (four `[a-z]{3,}` words plus a five-character `[a-z0-9]` tail): the
|
||
phrase is the stream's only credential, so anything a `--phrase` may be is a
|
||
password an operator can choose, and a looser check would accept `a-b-c`.
|
||
`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.
|
||
|
||
**Stage 3 has started, out of order and on purpose** (2026-10-11). A machine
|
||
had to be able to *reach* a stream before the rest of the app is settled: the
|
||
operator asked for the port to be open on the deployment machine, where the app
|
||
runs by hand, and a hand-written firewall line in one machine's config is the
|
||
wrong place for a fact about this flake. So `sessions.stream { port, bind,
|
||
openFirewall }` and the single rule it stands for are in `nix/module.nix`, with
|
||
`checks/vm-stream-firewall.nix` asking the *running* firewall — and a peer
|
||
outside the guest — whether the configured port is the one that opened.
|
||
|
||
What that does **not** do: no unit, no phrases, no `session stream
|
||
enable|disable|list|status`, and nothing in the module turns a stream on. The
|
||
app is still started by hand, and the option's whole job is to describe where a
|
||
stream will be reachable from. |