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
+27
-8
@@ -26,9 +26,17 @@
|
||||
│ hhstream-sessions.service │─────▶│ hhstream-pointer.service │
|
||||
│ hhstreamd │ │ one Wayland connection │
|
||||
│ registry, containers, │ JSON │ one virtual pointer │
|
||||
│ the pointer lease │ over │ per output │
|
||||
└────────────┬──────────────┘ a └──────────────────────────┘
|
||||
│ private socket
|
||||
│ the pointer lease, │ over │ per output │
|
||||
│ the stream phrases │ a └──────────────────────────┘
|
||||
└────────────┬────────┬─────┘ private socket
|
||||
│ │ ┌──────────────────────────┐
|
||||
│ └─────────────▶│ hhstream-live.service │
|
||||
│ live.sock │ one port (9988) │
|
||||
│ │ grim ─▶ MJPEG per │
|
||||
│ │ phrase, while watched │
|
||||
│ └───────────┬──────────────┘
|
||||
│ │ HTTP
|
||||
│ a browser ┘ /<phrase>/
|
||||
│ AF_UNIX control.sock, mode 0660
|
||||
▼
|
||||
hhstream session ... (the CLI an agent drives)
|
||||
@@ -37,12 +45,12 @@
|
||||
│
|
||||
┌────────────┴──────────────┐
|
||||
│ hhstream-mcp │ spawned per client, stdio only
|
||||
│ 21 tools (the acts) │◀─── an MCP client's JSON-RPC
|
||||
│ 8 resources (the state)│
|
||||
│ 23 tools (the acts) │◀─── an MCP client's JSON-RPC
|
||||
│ 10 resources (the state)│
|
||||
└───────────────────────────┘
|
||||
```
|
||||
|
||||
Five pieces, deliberately separate, and a sixth that is deliberately not a
|
||||
Six pieces, deliberately separate, and a seventh that is deliberately not a
|
||||
piece at all:
|
||||
|
||||
1. **The compositor** (`Hyprland`, unchanged upstream) renders into virtual
|
||||
@@ -62,9 +70,20 @@ piece at all:
|
||||
a separate process because a Wayland client needs its own connection and a
|
||||
driver blocked on the compositor must not stall session lifecycle.
|
||||
|
||||
And the sixth, which is a *shim* and not a layer:
|
||||
6. **The stream daemon** (`hhstream-live`) publishes one session's output as
|
||||
MJPEG on one port, behind a four-word phrase, while somebody is connected.
|
||||
A third executor on the pointer driver's pattern and for its reasons: `grim`
|
||||
blocks tens to hundreds of milliseconds so it must not run where `touch` and
|
||||
`kill` are answered, and a LAN-facing HTTP parser must not run in the frame
|
||||
server whose one-socket contract cannot grow one. The broker owns the
|
||||
*decision* (which session, under which phrase, in the record); the daemon
|
||||
owns the port, the capture and the URL. It knows nothing about sessions or
|
||||
idle clocks — it publishes what it is told to publish, and reports a viewer
|
||||
count the broker chooses to read as activity.
|
||||
|
||||
6. **The MCP server** (`hhstream-mcp`, `docs/CONTRACT-mcp.md`) is the CLI with a
|
||||
And the seventh, which is a *shim* and not a layer:
|
||||
|
||||
7. **The MCP server** (`hhstream-mcp`, `docs/CONTRACT-mcp.md`) is the CLI with a
|
||||
Model Context Protocol surface on it, so an agent reads state by URI and
|
||||
acts by calling tools instead of writing command lines. It is drawn above
|
||||
the CLI rather than beside the broker because that is where it sits: every
|
||||
|
||||
+59
-8
@@ -1,4 +1,4 @@
|
||||
# CONTRACT — the MCP server (mcp-v2)
|
||||
# CONTRACT — the MCP server (mcp-v3)
|
||||
|
||||
This file is the interface of `hhstream-mcp`: the resource URIs, the tool names,
|
||||
the arguments each takes, what comes back, and which of the CLI's exit codes
|
||||
@@ -10,7 +10,19 @@ containers and the input lease).
|
||||
these argument shapes is a consumer like any other, and renaming a tool breaks
|
||||
it exactly as renaming a wire verb would.
|
||||
|
||||
Version: mcp-v2 (2026-10-11). v1 was the first freeze and lasted one day.
|
||||
Version: mcp-v3 (2026-10-11). v1 was the first freeze and lasted one day; v2
|
||||
split state out into resources; v3 adds the live stream. v3 is **additive** —
|
||||
every v2 name still means what it meant.
|
||||
|
||||
v3 changes, all of them the per-session live stream
|
||||
(`docs/CONTRACT-sessions.md` §4, v4):
|
||||
|
||||
| § | Change | Why |
|
||||
| --- | --- | --- |
|
||||
| §3 | Tools `session_stream_enable` and `session_stream_disable`. 21 tools became 23. | Switching a stream on is an *act*, and a consequential one: it publishes a desktop on the LAN behind a phrase. Nothing about it is a read. |
|
||||
| §3 | `session_start` gains `stream`, `stream_phrase` and `stream_fps`, and its reply carries the URL. | A stream needs the container output that starting creates, so sequencing start-then-enable in the caller means every caller repeats the ordering and the half-done case. One call, one answer, and the phrase comes back with the session. |
|
||||
| §4 | Resources `hhstream://streams` and `hhstream://sessions/{id}/stream`. 8 resources became 10. | What is being published, and who is watching, is state — so it is read, not called. |
|
||||
| §6 | A connected viewer is the **one exception** to the idle-clock rule. | About once a minute the broker stamps `touch` on any session somebody is watching. It is not a verb and cannot be invoked; it is the broker noticing that a person is looking. |
|
||||
|
||||
**v2 is a breaking change, and the only one: the verbs that merely read are
|
||||
resources now, not tools.**
|
||||
@@ -120,7 +132,7 @@ to an argv list.
|
||||
| family | tools |
|
||||
| --- | --- |
|
||||
| `frames` | `shot`, `record`, `run` |
|
||||
| `sessions` | `session_start`, `session_touch`, `session_kill`, `session_gc`, `session_adopt`, `session_container`, `session_reconcile` |
|
||||
| `sessions` | `session_start`, `session_touch`, `session_kill`, `session_gc`, `session_adopt`, `session_container`, `session_reconcile`, `session_stream_enable`, `session_stream_disable` |
|
||||
| `pointer` | `pointer_acquire`, `pointer_move`, `pointer_click`, `pointer_scroll`, `pointer_down`, `pointer_up`, `pointer_release` |
|
||||
| `keyboard` | `keyboard_type`, `keyboard_key`, `keyboard_down`, `keyboard_up` |
|
||||
|
||||
@@ -154,13 +166,15 @@ running.
|
||||
|
||||
| Tool | Arguments |
|
||||
| --- | --- |
|
||||
| `session_start` | `app`, `argv?`, `idle_timeout?`, `wait_ready?`, `home?`, `ephemeral_home?`, `request_id?` |
|
||||
| `session_start` | `app`, `argv?`, `idle_timeout?`, `wait_ready?`, `home?`, `ephemeral_home?`, `stream?`, `stream_phrase?`, `stream_fps?`, `request_id?` |
|
||||
| `session_touch` | `id` |
|
||||
| `session_kill` | `id`, `grace?`, `signal?`, `request_id?` |
|
||||
| `session_gc` | `request_id?` |
|
||||
| `session_adopt` | `pid`, `app?`, `idle_timeout?`, `request_id?` |
|
||||
| `session_container` | `id` |
|
||||
| `session_reconcile` | `id?`, `request_id?` |
|
||||
| `session_stream_enable` | `id`, `phrase?`, `fps?` |
|
||||
| `session_stream_disable` | `id` |
|
||||
|
||||
Every one of these runs with `--json`, so what comes back is the broker's own
|
||||
protocol object: in the text part verbatim, and in `structuredContent` parsed.
|
||||
@@ -170,6 +184,21 @@ second wire format.
|
||||
`home` and `ephemeral_home` are mutually exclusive, and the schema says so —
|
||||
the CLI's argparse group, moved forward to where the refusal is free.
|
||||
|
||||
`session_stream_enable` returns the **URL** on the first line of its text part,
|
||||
because that is the whole point of the call: it is what gets handed to a person.
|
||||
It publishes the session's own container output and never the main one — that
|
||||
output carries every other session, and putting it behind one session's phrase
|
||||
is the mistake the broker refuses to make (exit 10 with no container). Re-enabling
|
||||
returns the same URL; a different `phrase` is exit 8, not a silent rotation,
|
||||
because rotating under somebody holding the old URL is the one outcome neither
|
||||
answer can be mistaken for. `session_stream_disable` is marked **destructive**:
|
||||
it forgets the phrase, so anyone holding that URL loses it.
|
||||
|
||||
`session_start` with `stream: true` is one call rather than two, and a stream
|
||||
that cannot be opened **does not fail the start** — the application is on the
|
||||
screen, and killing it over a web page would be the wrong trade. The reply
|
||||
carries `stream_error` whenever `stream` was asked for, `null` when it worked.
|
||||
|
||||
`session_container` is **not** marked read-only, and that is not an oversight:
|
||||
with an `id` the CLI runs `container.reconcile`, which writes the record back.
|
||||
That is also why it is a tool rather than a resource. The no-id listing, which
|
||||
@@ -232,6 +261,13 @@ verb a tool would have, with `--json` where the verb has it.
|
||||
| `hhstream://sessions/{id}` | `application/json` — one session with its recent audit events | `?events=N` |
|
||||
| `hhstream://sessions/{id}/logs` | `application/json` — the application's own captured output | `?lines=N` |
|
||||
| `hhstream://outputs/{name}` | one output captured alone, as an image blob. Exactly that output's configured size, which is the coordinate space the pointer tools aim in. | — |
|
||||
| `hhstream://streams` | `application/json` — every session a stream was enabled on, with its URL, rate and connected viewer count, plus `available` (whether the stream daemon answered) | — |
|
||||
| `hhstream://sessions/{id}/stream` | `application/json` — one session's stream, or `null`. `attached` is separate from `enabled`, and the URL is absent rather than stale when it is false. | — |
|
||||
|
||||
**The URLs in those two bodies contain their phrases**, which are the only thing
|
||||
protecting those streams. Both descriptions say so, because a host that puts
|
||||
`hhstream://streams` into a model's context has put a credential there — and
|
||||
the one place it must never go is anywhere the streamed session can see.
|
||||
|
||||
Rules this surface keeps:
|
||||
|
||||
@@ -349,13 +385,22 @@ in terms of this surface. They are on the individual tools and resources and
|
||||
not only in the server instructions, because a client shows a thing's own
|
||||
description at the point of use:
|
||||
|
||||
1. **`session_touch` is the only thing that resets a session's idle clock.**
|
||||
Reading `hhstream://sessions`, `hhstream://sessions/{id}` or its logs does
|
||||
not, `session_gc` does not, and neither does any pointer or keyboard tool. A
|
||||
1. **`session_touch` is the only thing a *caller* can do that resets a
|
||||
session's idle clock.** Reading `hhstream://sessions`,
|
||||
`hhstream://sessions/{id}` or its logs does not, `session_gc` does not, the
|
||||
stream tools do not, and neither does any pointer or keyboard tool. A
|
||||
session being driven is still a session nobody has said they want kept. The
|
||||
three resources it applies to say so in their own descriptions, because a
|
||||
resources it applies to say so in their own descriptions, because a
|
||||
description is what a host shows beside the thing it describes.
|
||||
|
||||
**The one exception is a connected viewer** (`docs/CONTRACT-sessions.md` §4,
|
||||
v4): about once a minute the broker stamps `touch` on any session somebody
|
||||
is watching through its live stream. It is not a tool and cannot be
|
||||
invoked — it is the broker noticing that a person is looking, which is the
|
||||
one form of "still wanted" that does not come down the control socket. It
|
||||
cannot hold a session open by itself: an enabled stream with no viewer
|
||||
captures nothing and stamps nothing.
|
||||
|
||||
2. **Every keyboard tool needs the pointer lease, and holds only while it
|
||||
holds.** There is no keyboard lease: one compositor seat means one keyboard
|
||||
focus. A held non-modifier key floods the window until it is lifted or the
|
||||
@@ -376,6 +421,12 @@ socket, the CLI and the broker are stdlib-only by policy. `packages.hhstream`
|
||||
must not grow that dependency; the root `pyproject.toml` excludes
|
||||
`hhstream_mcp*` from its package discovery so it cannot acquire it by accident.
|
||||
|
||||
The stream tools and the two stream resources additionally need
|
||||
`services.hyprland-headless-stream.sessions.stream.enable`, which runs the
|
||||
`hhstream-live` unit and gives the broker the socket it switches streams on
|
||||
over. Without it they answer exit 10 (`stream_unavailable`) — the session is
|
||||
unaffected, which is what that code means.
|
||||
|
||||
`services.hyprland-headless-stream.mcp.enable` (default `false`) puts the
|
||||
binary on the system PATH. That is the whole of the option: there is no unit, no
|
||||
socket and no state directory, because the server is spawned per client over
|
||||
|
||||
+3
-1
@@ -14,9 +14,11 @@ Each file answers three questions and stops:
|
||||
| [scroll-has-no-compositor-proof](scroll-has-no-compositor-proof.md) | medium | works live; unproven in a gate |
|
||||
| [reconcile-while-containers-are-off](reconcile-while-containers-are-off.md) | medium | partly fixed: discovery now survives a restart; teardown still lives inside the feature |
|
||||
| [kill-can-leave-the-app-alive](kill-can-leave-the-app-alive.md) | medium | found by counting windows, not sessions |
|
||||
| [capture-binary-and-the-unit-path](capture-binary-and-the-unit-path.md) | medium | found the first time the app was run as a unit: a unit's `PATH` has no `grim` |
|
||||
| [capture-binary-and-the-unit-path](capture-binary-and-the-unit-path.md) | medium | partly fixed: the module passes grim's store path and a check reads real frames; the app still never checks its capture binary |
|
||||
| [mcp-in-process-has-no-call-deadline](mcp-in-process-has-no-call-deadline.md) | medium | two costs of running the CLI in process: no killable deadline, and no `sg` recovery |
|
||||
| [mcp-resources-cannot-be-subscribed-to](mcp-resources-cannot-be-subscribed-to.md) | medium | the SDK hardcodes `subscribe=False`, so a log resource can only be re-read |
|
||||
| [stream-does-not-reattach-after-a-broker-restart](stream-does-not-reattach-after-a-broker-restart.md) | low | the phrase survives and the sweep works; `attached` reports false until re-enabled |
|
||||
| [a-stream-that-gave-up-still-reports-attached](a-stream-that-gave-up-still-reports-attached.md) | low | the other direction: a capture that permanently gave up still reads `LIVE: YES` |
|
||||
|
||||
Closed since this folder was written:
|
||||
|
||||
|
||||
@@ -0,0 +1,58 @@
|
||||
# A stream whose capture gave up still reports `attached: true`
|
||||
|
||||
## The issue
|
||||
|
||||
`hhstream_live.publisher` stops a stream after `FAILURE_LIMIT` (10) consecutive
|
||||
capture failures, and the stop is sticky on purpose — the case it guards is an
|
||||
output that was removed, and that does not come back. The stream object stays in
|
||||
`StreamRegistry` with `stopped = True`; the HTTP handler returns as soon as it
|
||||
notices, so viewers are dropped and new ones get a page that ends immediately.
|
||||
|
||||
Nothing on the broker side can see that. `Control._describe` returns
|
||||
`spec.public()` plus `url` and `viewers` — not `stopped`, `captured`,
|
||||
`failures` or `last_frame_age_s`, all of which `Stream.status()` already
|
||||
computes. So `LiveStreams.list()` reports the phrase, `_attachments()` finds it
|
||||
and `_stream_public` sets `attached = True`. `hhstream session stream status`
|
||||
says `LIVE: YES` for a capture that has permanently given up.
|
||||
|
||||
MEASURED, in checks/vm-stream.nix, by the bug that check found: the
|
||||
`hhstream-live` unit had the compositor's group but not its environment, so
|
||||
every `grim` exited 1 with
|
||||
|
||||
error: XDG_RUNTIME_DIR is invalid or not set in the environment.
|
||||
|
||||
The unit was `active (running)`, the broker's record was intact, `stream status`
|
||||
said `attached: true` with a URL, and the only place the truth appeared was a
|
||||
single `WARNING` in the daemon's journal. The environment bug is fixed
|
||||
(`execLive` in nix/module.nix); the reporting gap it exposed is not.
|
||||
|
||||
## Ideas
|
||||
|
||||
1. **Carry the publisher's health through `list`.** *(recommended)* Add
|
||||
`stopped` and `last_frame_age_s` to `Control._describe` — both already exist
|
||||
on `Stream.status()` — parse them in `hhstreamd.live.Attachment`, and have
|
||||
`_stream_public` report `attached: false` (or a third state) when the daemon
|
||||
says the capture is dead. The cost is one more field pair in
|
||||
CONTRACT-sessions.md §3.5 and a `render_stream` line; the gain is that
|
||||
`attached` means what it was added to mean.
|
||||
2. **Drop a stopped stream from the registry.** Then `list` stops naming it and
|
||||
`attached` goes false for free, with no new fields. Rejected as the first
|
||||
move because it destroys the evidence: `failures` and the phrase are what an
|
||||
operator needs in order to understand what happened, and a 404 on the URL
|
||||
reads as "wrong phrase".
|
||||
3. **Leave it.** What ships. `stream disable` then `stream enable` revives it
|
||||
(a fresh `Stream`, same phrase, same URL), which is what an operator reaches
|
||||
for anyway, and the daemon's journal does say what happened.
|
||||
|
||||
## Why it matters
|
||||
|
||||
Low severity because the capture only gives up for a reason that is itself a
|
||||
failure — a removed output, a compositor that went away, a misconfigured unit —
|
||||
and in two of those three the session is in trouble in ways `status` does show.
|
||||
|
||||
It matters because `attached` exists specifically to separate "the operator
|
||||
asked for this" from "a capture is running right now" (CONTRACT-sessions.md
|
||||
§3.5), and this is the second case where it answers the second question wrongly;
|
||||
see [stream-does-not-reattach-after-a-broker-restart](stream-does-not-reattach-after-a-broker-restart.md)
|
||||
for the first. A field that is right only when nothing is wrong is not worth
|
||||
reading.
|
||||
@@ -27,6 +27,19 @@ worst way. The unit starts, the port opens, the landing page answers, and
|
||||
`"failures": 10`. A viewer sees an empty frame area and nothing else says why.
|
||||
Only the unit's log names the reason, one line above the giving-up entry.
|
||||
|
||||
**Half of this is now fixed.** The module passes grim's absolute store path
|
||||
(idea 1), checks/vm-stream.nix starts the unit and reads real JPEGs off the
|
||||
stream — the check this file asked for — and that check immediately found the
|
||||
sibling fault: the unit had the compositor's *group* but not its *environment*,
|
||||
so grim exited 1 with "XDG_RUNTIME_DIR is invalid or not set", ten times, with
|
||||
the same silence. Fixed too (`execLive`). What is still open is idea 2: the app
|
||||
resolves its capture command by name and never checks it, so a standalone
|
||||
`hhstream-live serve` and any deployment shape that is not this module still
|
||||
discover a missing or unusable capture binary ten failures later. The quiet
|
||||
half — a stream that gave up while the broker still reports it attached — has
|
||||
its own file now:
|
||||
[a-stream-that-gave-up-still-reports-attached](a-stream-that-gave-up-still-reports-attached.md).
|
||||
|
||||
## Ideas
|
||||
|
||||
1. **An absolute binary, as the module already does elsewhere** *(recommended)*.
|
||||
|
||||
@@ -0,0 +1,66 @@
|
||||
# A broker restart leaves an enabled stream recorded but not attached
|
||||
|
||||
## The issue
|
||||
|
||||
`docs/plans/2026-10-04-session-stream-webapp.md` §6 says what a restart should
|
||||
do:
|
||||
|
||||
> 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.
|
||||
|
||||
Stage 2 did not build that half. What happens today, measured in
|
||||
`tests/sessions/unit/test_stream_verbs.py`
|
||||
(`test_a_down_daemon_turns_attached_false_rather_than_failing_the_read`) and by
|
||||
reading `SessionManager.startup`:
|
||||
|
||||
* the record keeps its phrase, so nothing is lost and a later `enable` restores
|
||||
the *same* URL — which is the property §4 exists for, and it works;
|
||||
* but `startup` does not call `LiveStreams.list()`, so the broker does not
|
||||
learn about streams the daemon is still publishing;
|
||||
* so `stream list` and `stream status` report `attached: false` for a stream
|
||||
that is, in fact, up and serving. The viewer sweep then skips it, because it
|
||||
only touches sessions whose phrase the daemon reports a viewer for — and it
|
||||
asks `viewers`, which *would* name it. So the sweep actually still works;
|
||||
what is wrong is the reporting.
|
||||
|
||||
The symptom is therefore narrow and confusing rather than broad: after
|
||||
`systemctl restart hhstream-sessions`, somebody watching a stream keeps
|
||||
watching it, the session keeps being touched, and `hhstream session stream
|
||||
list` says `LIVE: NO`. An operator reading that would reasonably `enable`
|
||||
again — which is harmless (`attach` is idempotent on the phrase) but should not
|
||||
be necessary.
|
||||
|
||||
The other half of §6 *is* implemented: if the daemon restarted too, the records
|
||||
keep their phrases and the streams stay off until re-enabled, because an open
|
||||
port and a running capture are explicit acts.
|
||||
|
||||
## Ideas
|
||||
|
||||
1. **Ask the daemon in `startup` and merge.** *(recommended)* One
|
||||
`LiveStreams.list()` where `reconcile_containers()` already runs, matching
|
||||
attachments to records by phrase. Small and local: `_stream_public` already
|
||||
merges an attachment into a record, so this is about *having* the
|
||||
attachments at start-up rather than only at read time. The one thing to get
|
||||
right is a phrase the daemon is publishing that no live record claims —
|
||||
which is the stream equivalent of an orphan `hh-*` output, and should
|
||||
probably be detached rather than adopted.
|
||||
2. **Ask on every read instead.** `_attachments()` already does, which is why
|
||||
the *reads* are nearly right. The reason it is not enough: there is no
|
||||
record-side state to update, so a restart's first `stream list` is correct
|
||||
and `attached` is still computed per call — this is really just (1) done
|
||||
lazily, and it hides the orphan case entirely.
|
||||
3. **Leave it.** What ships. The phrase survives, re-enabling is idempotent and
|
||||
costs one record write, and the sweep keeps working. The cost is a status
|
||||
field that lies after a restart.
|
||||
|
||||
## Why it matters
|
||||
|
||||
Low severity because nothing breaks and nothing is lost: the stream keeps
|
||||
serving, the viewer keeps being counted, and the fix an operator will reach for
|
||||
by instinct (`enable` again) is exactly the right one and is idempotent.
|
||||
|
||||
It matters at all because `attached` was added specifically so that "the
|
||||
operator asked for this" and "a capture is running right now" could be told
|
||||
apart — and after a restart it reports the second one wrongly, which is the one
|
||||
job that field has.
|
||||
@@ -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