Files
hyprland-headless-stream-pl…/docs/plans/2026-10-04-session-stream-webapp.md
T
HermenixandClaude Opus 5 887ed17be2 docs(stream): mcp-v3, the seventh box, and two TODOs the check wrote
`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
2026-10-11 22:54:26 +00:00

15 KiB
Raw Blame History

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.