diff --git a/README.dev.md b/README.dev.md index 75dbdb4..7b3170f 100644 --- a/README.dev.md +++ b/README.dev.md @@ -52,7 +52,7 @@ import the SDK: ```bash nix develop hhstream-mcp --list-tools # the 21 acting verbs -hhstream-mcp --list-resources # the 8 read-only URIs +hhstream-mcp --list-resources # the 10 read-only URIs ``` ## The checks @@ -68,8 +68,9 @@ hhstream-mcp --list-resources # the 8 read-only URIs | `vm-pointer` | the **lease and the driver**: a version-2 virtual pointer, a warp that lands where it was aimed *as the application reports it*, a click delivered as one press and one release, a contended acquire refused with BUSY, an expired lease swept with its held button lifted, and a broker restart that leaves the lock free, the bookmark intact and the driver reachable | yes | | `vm-keyboard` | the **keymap, the focus and a decoded symbol**: the keymap the driver uploads reaching a real compositor, `pointer acquire` leaving the aimed window holding the *keyboard* and not merely the cursor, and `hhs-keyboard-target` decoding `hello` from the keymap it was **forwarded** — so a driver that stopped uploading one arrives as `sym=?` and goes red | yes | | `vm-keyboard-de` | the same file with `sessions.keyboard.layout = "de"`, because that option reaches the uploaded keymap through exactly one path — `--xkb-layout` on the driver unit — and a single-layout check cannot tell that path from a hardcoded `us`: keysym `y`'s evdev code swaps (21 against 44), the forwarded `symbols=` name with it, and `ü` goes from exit 2 to `udiaeresis` | yes | +| `vm-stream` | the **live stream end to end**: `stream enable` on a live session mints a phrase the daemon accepts, a real HTTP viewer reads JPEGs off `//stream.mjpg` from *inside* the guest, `stream list` reports that viewer, the broker's idle-clock sweep stamps `touch` for it (and does not when nobody is watching), a wrong phrase 404s, and `kill` detaches the stream before the output is removed | yes | | `vm-stream-firewall` | the stream's **port**: the guest's own running firewall accepts the configured port and not the module's default, a peer outside the guest reaches it, and is refused on a port beside it that was never opened | yes | -| `vm-mcp` | the **MCP server over stdio**: `mcp.enable` puts the binary on PATH and starts no unit, the `initialize` handshake completes over a real pipe, all 21 tools and 8 resources are listed with their annotations and their two rules, both a tool call and a resource read reach the live broker and return its own protocol object, two reads of a session do **not** move its idle deadline while `session_touch` does, a frame arrives as a blob at exactly its output's configured size, the pointer lease is granted/used/returned against the real driver, `--toolsets` narrows the tools and leaves the resources alone, and a refusal arrives as a tool error (or, for a read, a protocol error) carrying the frozen exit code | yes | +| `vm-mcp` | the **MCP server over stdio**: `mcp.enable` puts the binary on PATH and starts no unit, the `initialize` handshake completes over a real pipe, all 23 tools and 10 resources are listed with their annotations and their two rules, both a tool call and a resource read reach the live broker and return its own protocol object, two reads of a session do **not** move its idle deadline while `session_touch` does, a frame arrives as a blob at exactly its output's configured size, the pointer lease is granted/used/returned against the real driver, `--toolsets` narrows the tools and leaves the resources alone, and a refusal arrives as a tool error (or, for a read, a protocol error) carrying the frozen exit code | yes | All of them at once: @@ -95,6 +96,7 @@ nix build -L .#checks.x86_64-linux.vm-keyboard nix build -L .#checks.x86_64-linux.vm-keyboard-de nix build -L .#checks.x86_64-linux.vm-stream-firewall nix build -L .#checks.x86_64-linux.vm-mcp +nix build -L .#checks.x86_64-linux.vm-stream ``` `-L` is not optional in practice: without it, Nix hides the build log, and the @@ -262,6 +264,8 @@ checks/ vm-stream-firewall.nix nixosTest, the stream's port in the guest's firewall vm-mcp.nix nixosTest, hhstream-mcp driven over stdio by a raw JSON-RPC client against the live broker + vm-stream.nix nixosTest, `session stream enable` and a real HTTP + viewer reading MJPEG from inside the guest lib/mcp_client.py that client: hhs-mcp-call, stdlib only and deliberately NOT the MCP SDK's -- the SDK on both ends would agree with itself about a framing neither side had to get right diff --git a/README.md b/README.md index 5bdb2a1..f0b4442 100644 --- a/README.md +++ b/README.md @@ -35,6 +35,52 @@ hhstream-client --socket /run/hypr-stream/stream.sock --count 1 --out frame.png The socket is a plain file descriptor: the server serves every client that connects, and keeps running when one disconnects. +## Watching a session: one port, a phrase per session + +A session can publish its own screen on a web page, so a person can watch what +an agent is doing from a phone. One port for the whole machine, and a path that +is four words and a short tail: + +```bash +hhstream session stream enable chromium-k3f9d2 +# http://127.0.0.1:9988/amber-otter-lantern-harbor-7k2qp/ +``` + +That URL is the whole interface — a browser `` is the entire client, over +MJPEG — and the phrase in it is its **only** protection. No TLS, no second +factor: anyone who can reach the port and guess four words can watch. It is +never written to the audit log, and `stream list` does not print it. + +Four things worth knowing before switching one on: + +- **It is per session and off by default.** A session does not stream because + it exists; it streams because somebody enabled it. What is published is that + session's own container output, never the main one — the main output carries + every other session, and putting it behind one session's phrase is the + mistake this refuses to make. +- **The phrase survives a restart.** It lives in the session's record, so + somebody you read it out to keeps the URL you gave them. `disable` then + `enable` rotates it. +- **Capture runs only while somebody is connected.** An enabled stream nobody + is watching costs no `grim` and no CPU. +- **Watching counts as activity.** This is the one exception to "`touch` is the + only mark of activity": about once a minute the broker notices a connected + viewer and resets that session's idle clock, so a long job you are watching + on a phone is not reaped at three hours. An enabled stream with nobody + watching keeps nothing alive. + +```nix +services.hyprland-headless-stream.sessions.stream = { + enable = true; # runs hhstream-live; turns no stream on + # bind = "0.0.0.0"; # and openFirewall, to reach it from another device + # openFirewall = true; +}; +``` + +Loopback by default, where the path to a phone is `ssh -L 9988:127.0.0.1:9988`. +`hhstream session start --stream` starts an application and prints its +URL in one go, which is the usual way an agent sets one up. + ## Driving it from an agent: the MCP server `hhstream-mcp` is the `hhstream` CLI behind a [Model Context @@ -45,14 +91,16 @@ application without writing command lines. The interface is frozen in It is split the way the protocol splits things: -- **Resources are the state** — eight of them, read by URI, and reading one +- **Resources are the state** — ten of them, read by URI, and reading one changes nothing. `hhstream://status` is whether the desktop is up, `hhstream://sessions` is what is running, `hhstream://sessions//logs` is an application's own output, `hhstream://pointer` is who holds the input - lease, `hhstream://screen` is a frame of the screen. -- **Tools are the acts** — twenty-one, one per CLI verb that does something. + lease, `hhstream://screen` is a frame of the screen, `hhstream://streams` is + what is being published and who is watching. +- **Tools are the acts** — twenty-three, one per CLI verb that does something. `session_start` puts an application on the screen, `pointer_acquire` takes the - input lease, `keyboard_type` types, `session_kill` ends a session. + input lease, `keyboard_type` types, `session_stream_enable` publishes the + screen for a person to watch, `session_kill` ends a session. A host decides what state to put in front of its model; the model decides what to do. That is the whole of the split, and it is why `shot` is still a tool @@ -104,7 +152,7 @@ account in the group. `hhstream-mcp --list-tools` and `--list-resources` print the two tables and exit, which is the quickest way to check an install. -If twenty-one tools is more than a client has room for, `--toolsets` narrows +If twenty-three tools is more than a client has room for, `--toolsets` narrows what is offered to whichever families are wanted — `frames`, `sessions`, `pointer`, `keyboard`: diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index c26f7c1..0c05cb1 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -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 ┘ // │ 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 diff --git a/docs/CONTRACT-mcp.md b/docs/CONTRACT-mcp.md index f4b6ff8..f647164 100644 --- a/docs/CONTRACT-mcp.md +++ b/docs/CONTRACT-mcp.md @@ -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 diff --git a/docs/TODO/README.md b/docs/TODO/README.md index dae4329..099bc10 100644 --- a/docs/TODO/README.md +++ b/docs/TODO/README.md @@ -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: diff --git a/docs/TODO/a-stream-that-gave-up-still-reports-attached.md b/docs/TODO/a-stream-that-gave-up-still-reports-attached.md new file mode 100644 index 0000000..7d4d64f --- /dev/null +++ b/docs/TODO/a-stream-that-gave-up-still-reports-attached.md @@ -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. diff --git a/docs/TODO/capture-binary-and-the-unit-path.md b/docs/TODO/capture-binary-and-the-unit-path.md index c2a0a76..b3ca37a 100644 --- a/docs/TODO/capture-binary-and-the-unit-path.md +++ b/docs/TODO/capture-binary-and-the-unit-path.md @@ -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)*. diff --git a/docs/TODO/stream-does-not-reattach-after-a-broker-restart.md b/docs/TODO/stream-does-not-reattach-after-a-broker-restart.md new file mode 100644 index 0000000..4a82de6 --- /dev/null +++ b/docs/TODO/stream-does-not-reattach-after-a-broker-restart.md @@ -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. diff --git a/docs/plans/2026-10-04-session-stream-webapp.md b/docs/plans/2026-10-04-session-stream-webapp.md index e423e67..4d98517 100644 --- a/docs/plans/2026-10-04-session-stream-webapp.md +++ b/docs/plans/2026-10-04-session-stream-webapp.md @@ -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. \ No newline at end of file +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. \ No newline at end of file