`docs/CONTRACT-mcp.md` goes to mcp-v3 with a change table: two tools, two resources, three `session_start` arguments, and the one rule that is not a name at all -- a connected viewer is the single exception to the idle-clock rule, and it cannot be invoked, so it is documented in §6 rather than offered in §3. v3 is additive; every v2 name still means what it meant. README.md leads the stream with the shape of it rather than the options: one port for the machine, a phrase per session, a browser `<img>` as the entire client, and the four things worth knowing before switching one on -- that it is per session and off by default, that the phrase survives a restart, that capture runs only while somebody is connected, and that watching counts as activity. The phrase is called what it is: the only protection, with no TLS and no second factor. ARCHITECTURE.md gains the fourth unit as a seventh box -- `hhstream-live`, hanging off the broker by `live.sock` with one port and a browser at the end of it -- and the counts move to 23 and 10. Two TODOs, both written by `checks/vm-stream.nix`: * `a-stream-that-gave-up-still-reports-attached.md`. The publisher stops a stream after ten consecutive capture failures and the stop is sticky on purpose, but `Control._describe` does not pass `stopped` on, so `_stream_public` reports `attached: true` for a capture that has permanently given up. That is the second place `attached` answers "is a capture running right now" wrongly, and a field that is right only when nothing is wrong is not worth reading. * `capture-binary-and-the-unit-path.md` is now half fixed, and says so. The module passes grim's store path and this check reads real frames -- which immediately found the sibling fault, the unit's missing `XDG_RUNTIME_DIR`. What is still open is the other half: the app resolves its capture command by name and never checks it, so any deployment that is not this module still discovers a broken capture ten failures later. The plan's status section records Stage 2 and Stage 3 as built, the two decisions §5 left open (that `start` takes `--stream`, and that the default rate is the daemon's), and what Stage 2 deliberately did not do -- §6's restart re-attachment, which has its own TODO. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
242 lines
15 KiB
Markdown
242 lines
15 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`; and the capture binary — a unit's `PATH` has no `grim`, so the stream serves an empty frame area without saying why (`docs/TODO/capture-binary-and-the-unit-path.md`). |
|
||
| 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/`): the router, the
|
||
pages, the phrase and the publisher, runnable standalone via `hhstream-live
|
||
serve --stream PHRASE=OUTPUT`.
|
||
|
||
**Stage 2 is built** (2026-10-11), and §5's surface is what shipped:
|
||
`stream.enable|disable|list|status` on the control socket, `hhstream session
|
||
stream …` on the CLI, the record field at **registry schema 4**,
|
||
`/run/hhstream/live.sock` with `hhstreamd/live.py` on the broker's end and
|
||
`hhstream_live/control.py` on the daemon's, the teardown order, and the viewer
|
||
heartbeat. `docs/CONTRACT-sessions.md` went to **sessions-v4** for it.
|
||
|
||
Two decisions §5 left open, settled in the building:
|
||
|
||
1. **`start` takes `--stream`.** A stream needs the container output that
|
||
starting creates, so "start, then enable" made every caller repeat the
|
||
ordering and the half-done case in between. One call, and the URL comes
|
||
back with the session id. A stream that cannot be opened does **not** fail
|
||
the start — the application is on the screen, and `stream_error` says what
|
||
went wrong.
|
||
2. **The default rate is the daemon's, not the broker's.** §5 did not say who
|
||
owns it, and the first cut had the broker send its own default on every
|
||
attach — which would have made `sessions.stream.fps` a setting that changed
|
||
nothing, the exact failure `--xkb-layout` exists to avoid. `fps` is now
|
||
omitted from `attach` unless a caller named one.
|
||
|
||
What Stage 2 did **not** do: `stream.enable` carries no `--port`, and §6's
|
||
restart re-attachment is not implemented. A broker restart leaves the records'
|
||
phrases intact and their streams off until re-enabled, which is §6's own
|
||
fallback ("an open port and a running capture are explicit acts") — but it does
|
||
*not* ask a surviving daemon for its list and re-attach, so `attached` reads
|
||
false until somebody enables again. Recorded in `docs/TODO/`.
|
||
|
||
**Stage 3 is built** (2026-10-11), the unit included — `hhstream-live.service`
|
||
runs the app with `--control-socket`, the module's own capture command (`grim`
|
||
is not on a unit's PATH), and `sessions.stream.{enable,fps,port,bind,openFirewall}`.
|
||
What follows is why the firewall half landed first.
|
||
|
||
The unit has to be handed two things, and both were found by
|
||
`checks/vm-stream.nix` rather than reasoned about: the capture command with
|
||
grim's store path, because a unit's `PATH` has no `grim`; and the compositor's
|
||
session — `XDG_RUNTIME_DIR` plus the `wayland-N` the compositor actually bound,
|
||
discovered at start by `execLive`. Without the second the unit was
|
||
`active (running)`, the broker attached, `stream status` said `attached: true`,
|
||
and every capture exited 1 with "XDG_RUNTIME_DIR is invalid or not set" until
|
||
the publisher gave up. Both failures are silent in the same way, which is why
|
||
the check reads JPEG bytes instead of asserting a 200.
|
||
|
||
**Stage 3 started out of order and on purpose.** 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.
|
||
|
||
At the time that did **not** include a unit, phrases or the verbs; those are
|
||
above. What is still true of it is the last sentence: nothing in the module
|
||
turns a stream *on*. `sessions.stream.enable` runs a listener serving one form,
|
||
and a stream exists only for the sessions somebody enabled it on.
|
||
|
||
**Stage 4 — the host pass — has not been done.** Nothing here has had a real
|
||
browser pointed at it; `checks/vm-stream.nix` reads the MJPEG with a
|
||
hand-rolled client inside the guest, which proves the framing and the capture
|
||
but not that a phone paints it. |