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
This commit is contained in:
1 parent
9d33639c04
commit
887ed17be2
9 files changed
+341
-33
No files matched your search
@@ -175,12 +175,54 @@ one at a time; no browser in a VM check.
|
||||
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 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 3 has started, out of order and on purpose** (2026-10-11). A machine
|
||||
**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
|
||||
@@ -189,7 +231,12 @@ 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.
|
||||
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.
|
||||
Reference in new issue
Block a user