From 4fefb448acaefeea4f392d915cd1e4c82be7d4cb Mon Sep 17 00:00:00 2001 From: Hermenix Date: Sun, 11 Oct 2026 02:31:52 +0000 Subject: [PATCH] docs(todo): the capture binary needs an absolute path under a unit Found on the deployment machine on 2026-10-11, the first time `hhstream-live` was run **as a unit** rather than from a login shell: a systemd unit's PATH has no system profile, so the capture command `grim` is not found, ten times, and the stream gives up. It answers on its port, serves the landing page and reports `"stopped": true, "failures": 10` while showing nothing -- the quiet half of the failure is what makes it worth a file. The module already solves this for `sessions.apps` by requiring an absolute store path; the stream's unit has to do the same (or set PATH, which is what made the deployment run work). Recorded in `docs/TODO/` with the two fixes, and named as a risk on stage 3 of the plan, which is the stage that turns this from an experiment into the only path. --- docs/TODO/README.md | 1 + docs/TODO/capture-binary-and-the-unit-path.md | 56 +++++++++++++++++++ .../plans/2026-10-04-session-stream-webapp.md | 2 +- 3 files changed, 58 insertions(+), 1 deletion(-) create mode 100644 docs/TODO/capture-binary-and-the-unit-path.md diff --git a/docs/TODO/README.md b/docs/TODO/README.md index e371bbe..4a57b10 100644 --- a/docs/TODO/README.md +++ b/docs/TODO/README.md @@ -14,6 +14,7 @@ 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` | Closed since this folder was written: diff --git a/docs/TODO/capture-binary-and-the-unit-path.md b/docs/TODO/capture-binary-and-the-unit-path.md new file mode 100644 index 0000000..c2a0a76 --- /dev/null +++ b/docs/TODO/capture-binary-and-the-unit-path.md @@ -0,0 +1,56 @@ +# The capture command needs an absolute path under a unit + +## The issue + +`hhstream-live` runs its capture command (`grim -c -t jpeg -q 80 -o -`) +by name, from the `PATH` it inherits. Under **systemd** that path is +`/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin` — the system +profile is deliberately not on it — so the capture fails, ten times, and the +stream gives up: + +``` +WARNING hhstream.live: stream on hh-chromium-yhvpms: giving up after 10 +consecutive capture failures: capture command ['grim', '-c', '-t', 'jpeg', +'-q', '80', '-o', 'hh-chromium-yhvpms', '-'] could not be run: +[Errno 2] No such file or directory: 'grim' +``` + +Measured on 2026-10-11 on the deployment machine, the first time the app was +run **as a unit** rather than from a login shell. A login shell has +`/run/current-system/sw/bin` on its `PATH`, which is why every run before this +one — the stage-1 work, the standalone `serve --stream` runs, the whole test +suite — never saw it. + +What makes it worth a file rather than a line: the failure is quiet in the +worst way. The unit starts, the port opens, the landing page answers, and +`status.json` reports a stream that is simply `"stopped": true` with +`"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. + +## Ideas + +1. **An absolute binary, as the module already does elsewhere** *(recommended)*. + `sessions.apps` requires an absolute store path for exactly this reason — + "a unit's default `PATH` does not include the system profile", which is why + the allowlist spells `foot` as `${pkgs.foot}/bin/foot`. The stream's unit + should not inherit `grim` by name either: pass + `${pkgs.grim}/bin/grim` as the capture command from the module (or set + `PATH` on the unit, which is what made it work on the deployment machine). + The absolute path is also the stronger control: it names one exact binary + instead of whatever `PATH` resolves to at the moment the unit starts. +2. **Resolve early and fail loudly.** Have the app resolve the binary itself at + start-up and refuse to serve with a named error (`capture_binary_missing`) + if it is not there. A unit that dies at start is a five-second diagnosis; a + unit that serves an empty frame is an afternoon. +3. **Both.** The module passes the absolute path *and* the app checks it once + at start-up: the first is the fix, the second is what catches the next + deployment shape nobody has thought of yet. + +## Why it matters + +Stage 3's unit is the point at which running under systemd stops being an +experiment and becomes the only path every deployment takes — and a stream +that answers, reports a healthy port, and shows nothing is a worse failure than +one that does not start. Whichever idea is taken, the check for it belongs in +the same stage as the unit: a `vm-*` check that starts the unit and reads one +frame would have caught this on the day it was written. \ No newline at end of file diff --git a/docs/plans/2026-10-04-session-stream-webapp.md b/docs/plans/2026-10-04-session-stream-webapp.md index 7be79cc..e423e67 100644 --- a/docs/plans/2026-10-04-session-stream-webapp.md +++ b/docs/plans/2026-10-04-session-stream-webapp.md @@ -156,7 +156,7 @@ capture without one. | 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`. | +| 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-` first. | Test layers are v1's: `tests/unit` for the HTTP/router/phrase with a fake