docs(plan): a live network stream per session — approach and open questions
This commit is contained in:
1 parent
4b5cb5197a
commit
deccfb592c
1 file changed
+123
@@ -0,0 +1,123 @@
|
||||
I'll explore the frame server, session CLI, broker, contracts, and the NixOS module first, then write a plan only — no edits.The tree is a Python frame server, a session broker, and a pointer daemon. Next I’ll read the contracts and the capture/session paths those decisions depend on.The publisher cannot select a session today. `hhstream-server` serves one output on `/run/hypr-stream/stream.sock` and its command line is frozen. `hhstream shot --output hh-<id>` and `record --output` are separate `grim -o` one-shots. A phone view should be a new, view-only listener beside that, not a change to the socket Hermenix already reads.
|
||||
|
||||
## Decisions
|
||||
|
||||
### 1. Transport
|
||||
|
||||
**Primary: MJPEG over HTTP.** **Fallback: a WebSocket carrying the existing `HHS1` frames, only if a real phone browser will not render the MJPEG.** Not HLS, not VNC, not WebRTC.
|
||||
|
||||
| Option | Latency | CPU on this box | Already here | Plain browser |
|
||||
|---|---|---|---|---|
|
||||
| MJPEG (`multipart/x-mixed-replace`) | One frame. At the recommended 5 fps that is about 200 ms plus a ~46 ms `grim` JPEG. | Reuses the JPEG the host already measured: 1280×720 q80 is ~46 ms; PNG is ~326 ms and is the wrong codec. One capture, many viewers. | `CommandCapture`, the single-slot drop policy, JPEG size parsing. Stdlib HTTP only. | Yes. An `<img>` needs no plugin and no script. |
|
||||
| WebSocket of `HHS1` | Same pixels, same latency. | Same capture cost. | The framing code. | No. A phone that opens the URL sees nothing unless we also serve a page that blits JPEGs. |
|
||||
| HLS | Seconds (segment delay). | A second encode (`libx264`) on top of `grim`. `ffmpeg` is only used today to mux a finished recording. | Nothing of the live path. | Safari yes, Chrome only with a script. |
|
||||
| VNC / RFB | Fine. | A new codec, and a client can click. | Nothing. | No. noVNC is a script, and clicks would bypass the pointer lease. |
|
||||
| WebRTC | Best, and irrelevant. | An encoder plus ICE/DTLS. Worst cost for a two-core software renderer. | Nothing. | Only via a script and a signaling dance. |
|
||||
|
||||
The URL we print is a tiny same-origin HTML page whose only job is `<img src="stream.mjpg">`. Top-level multipart documents are unreliable; the image tag is the one that works on phones. The same process also serves one `frame.jpg` for tests. No CDN, no extra Python dependencies. The WebSocket fallback is the same JPEG bytes and the same page, and it is not built in the first slice.
|
||||
|
||||
Capture rate for a session stream defaults to **5 fps, hard cap 10**. The main publisher already spends roughly one core on its own `grim`. A second full-rate capture would take the other core. Five frames times ~46 ms is about a quarter of one core, and only while someone is connected.
|
||||
|
||||
### 2. Where the listener lives
|
||||
|
||||
**A new long-lived unit, `hhstream-live.service`. One process, many session outputs. Not the frame server, not the broker, and not one unit per session.**
|
||||
|
||||
It follows the pointer driver, not the frame server:
|
||||
|
||||
- The frame server's contract is one socket, one output, one slot, and a command line of `--socket`, `--fps`, `--format`, and `--capture-command`. Clients send nothing. A LAN parser bug or a slow phone must not be able to take down the socket Hermenix reads. The server also does not know session ids, idle deadlines, or teardown.
|
||||
- The broker is the control plane (`/run/hhstream/control.sock`, newline JSON, mode `0660`). `grim` takes tens to hundreds of milliseconds and its timeout is 5 s. That block must not freeze `touch`, `kill`, or the reaper. That is why the pointer is already a separate process.
|
||||
- A systemd template per session would be a second supervisor. Sessions are broker records, and `SessionManager.teardown` is deliberately the only kill path. A child unit also races `KillMode=` and adopt-on-restart.
|
||||
|
||||
`hhstream-live` is an executor. It holds no session policy. The broker tells it what to publish over a private socket, `/run/hhstream/live.sock` (mode `0660`, next to `pointer.sock`). It must not take `RuntimeDirectory=/run/hhstream`; the pointer unit's comments record that a second owner deletes the broker's socket.
|
||||
|
||||
It runs as the compositor user `hhstream`, with `video` and `render`, `ProtectHome` and `ProtectSystem=strict`, the same shape as `hyprland-headless-stream`. It discovers `WAYLAND_DISPLAY` the way that unit already does. It does not run as `hermes`: a network process should not have the agent's home. Group `hhstream` can already open the broker socket; this does not widen that.
|
||||
|
||||
**One session's picture.** The broker sends the output name `hh-<session-id>` and the full capture argv, built from the module's `captureCommand` plus `-o hh-<id>`. On this host that is `grim -o hh-<id> -c -t jpeg -q 80 -`. One capture thread and one frame slot per output, same drop rule as `FrameServer`: a slow viewer skips frames and is never queued. The daemon does not touch `stream.sock` and does not capture the main output.
|
||||
|
||||
**No container, no stream.** If the session's container is missing or `degraded`, `stream start` returns the existing `no_container` error (exit 10). Falling back to the main output would put every other session on the phone. Containers are on in `/etc/nixos/hyprland-stream.nix` as a trial, and a window that ignores `HHSTREAM_APP_ID` still lands in quarantine. The stream will then honestly show an empty output. That is a container bug, not a reason to capture the main screen.
|
||||
|
||||
**When the session dies.** `teardown` (kill, reap, and gc) tells the daemon to stop that output and close its clients **before** `hyprctl output remove`. If the output disappears anyway, `grim`'s "unknown output" ends the stream after a few failures. It does not retry forever the way the main publisher must. The port is freed when the listener closes.
|
||||
|
||||
A broker restart does not rebind anything. If the daemon is still up, the broker asks it for the list and reattaches those listeners to the session records so status and teardown still see them. If the daemon restarted too, the stream is gone and status says so. An open port is an explicit act.
|
||||
|
||||
### 3. Addressing and lifecycle
|
||||
|
||||
**The caller may pass a port. Otherwise the broker takes the lowest free port in a configured range. Default range `9120–9131`.** Not a single configured port (two sessions must fit; `max_containers` is 2). Not an ephemeral port (a phone URL has to be writable, and a firewall cannot name port 0). `9120` starts just above **9119**, which `/etc/nixos/common.nix` already opens for the Hermes dashboard. Twelve ports covers the container budget plus a restart where the old socket is still in `TIME_WAIT`.
|
||||
|
||||
```
|
||||
hhstream session stream start <id> [--port N] [--bind ADDR] [--fps N]
|
||||
hhstream session stream stop <id>
|
||||
hhstream session stream status [id]
|
||||
```
|
||||
|
||||
Nested like `pointer`: one precondition (a container output) and one warning (this is a network listener). `start` prints **only the URL** on stdout, the same trick as the session id and the lease id:
|
||||
|
||||
```
|
||||
http://127.0.0.1:9120/<token>/
|
||||
```
|
||||
|
||||
Stderr says it is view-only, names the output, and prints the stop command. `--json` adds `url`, `port`, `bind`, `token`, `output`, `fps`, and `viewers`. When bind is `0.0.0.0`, the printed host is the default-route IPv4, overridable with `--advertise ADDR`, plus the loopback URL. Do not print `0.0.0.0`.
|
||||
|
||||
`start` on a session that already has a listener returns that listener (and its token) when port and bind match, and `stream_busy` (exit 8) when they do not. `request_id` covers `start` and `stop` so a retry cannot open a second port. `stop` only stops the listener; the session keeps running. A port outside the range is exit 2. The range being full is `stream_budget`, exit 6. The daemon being down is `stream_unavailable`, exit 10. No new exit-code numbers.
|
||||
|
||||
The session record gains a `stream` object (`port`, `bind`, `token`, `output`, `fps`, `pid` or daemon id). Registry schema bumps to 4; older records migrate to `stream: null` and are adopted, not refused.
|
||||
|
||||
**Idle clock.** `start`, `stop`, and `status` do **not** touch. Same rule as `pointer`: setting something up is not "still wanted". A **connected viewer is activity**. About once a minute the broker asks the daemon for viewer counts and, if any are non-zero, stamps `touch`. That is the one new way the clock moves, and it is not a CLI verb. It has to be: the idle timeout is three hours, and a session the operator is watching from his phone must not be reaped out from under him. An open port with nobody connected does not stamp, and it does not run `grim`. The reaper then kills the session on the normal deadline, and teardown closes the listener. A forgotten URL is a bound socket, not a hot core and not a pinned session.
|
||||
|
||||
### 4. Security
|
||||
|
||||
This would be the first listener meant to be opened from another device. Everything else is a unix socket in a `0750` directory, mode `0660`, group `hhstream`, with no authentication. The host firewall allows inbound TCP **22 and 9119 only**. The pixels can be a logged-in browser.
|
||||
|
||||
**Default bind is `127.0.0.1`. The firewall stays closed. A path token is always required, including on loopback.**
|
||||
|
||||
Loopback is still weaker than the group-gated frame socket: any local user can open a TCP port. The token is what replaces the group check. It is a 128-bit `secrets.token_urlsafe` value in the path, because an `<img>` will send a path and will not send a custom header:
|
||||
|
||||
```
|
||||
GET /<token>/ the page
|
||||
GET /<token>/stream.mjpg the multipart stream
|
||||
GET /<token>/frame.jpg one JPEG
|
||||
```
|
||||
|
||||
Anything else is a 404 with an empty body. Wrong-token responses do not echo the token. The audit log records port, bind, and output, and does not record the token. The token lives in the session record under the broker state dir (`/var/lib/hermes/hhstream-sessions` on this machine). `stop` then `start` rotates it.
|
||||
|
||||
LAN is opt-in twice, in the host config, not in the module defaults:
|
||||
|
||||
- `sessions.stream.bind = "0.0.0.0"` (or a specific address). `--bind` on the CLI can do the same for one session.
|
||||
- `sessions.stream.openFirewall`, default **false**. The module must not add ports to `networking.firewall.allowedTCPPorts` unless that option is on. This machine should turn it on in `/etc/nixos` only when the phone path is wanted, and the range must not include 9119.
|
||||
|
||||
The token is cleartext on the LAN. The threat model is "another device on the LAN can watch if it has the URL", not "the URL is secret from the network". There is no TLS in this slice; a private CA and a phone trust prompt are a worse default. Until the firewall is opened, the phone path is an SSH forward to loopback (`ssh -L 9120:127.0.0.1:9120`), which keeps the current posture.
|
||||
|
||||
The listener is view-only. No pointer, no keyboard, no `hyprctl`. At most four viewers. The broker pulls viewer counts; the daemon cannot ask the broker to touch an arbitrary session.
|
||||
|
||||
### 5. Tests
|
||||
|
||||
Same layers as the rest of the repo. No GPU for unit tests. No browser in the VM checks. VM checks stay one at a time.
|
||||
|
||||
| Test | Proves |
|
||||
|---|---|
|
||||
| `tests/unit` for the publisher, with `FakeCapture` | Multipart framing, one JPEG per part, `Content-Type`, token 404s with an empty body, a stalled viewer does not block another, capture does not run at zero viewers, "unknown output" ends the stream. This mirrors `tests/unit/test_server.py`. |
|
||||
| `tests/sessions/unit` | Port allocator (lowest free, range exhausted, clash), CLI parse, stdout is the bare URL, stderr carries the warning, `start`/`stop`/`status` do not touch, a viewer heartbeat does, teardown issues stop before the container is destroyed. New error names map to exits 2, 6, 8, and 10 without renumbering. |
|
||||
| `tests/sessions/integration` | A real daemon and a real `hhstream-live` on `127.0.0.1` with an ephemeral port. `urllib` reads two JPEGs, a wrong token fails, `stream stop` closes the port, and a real idle reap closes it too. Fake capture, no compositor. |
|
||||
| A human browser pass, not a check | On the host, `stream start` against a session whose window is actually on `hh-<id>` (the cooperating client from `checks/vm-containers.nix`, not `foot` or Chromium). Open the printed URL in the Chromium this machine already installs. Change pixels; they must show up without a reload. The phone pass is the same URL only after bind and firewall are opted in. |
|
||||
|
||||
`urllib` reading a multipart body is the automated proof that a browser's `<img>` has something valid to decode. A headless-Chrome screenshot is optional and is not a VM check: two software-rendered compositors plus a browser will flake on two cores.
|
||||
|
||||
### 6. Stages
|
||||
|
||||
Contracts bump first. `docs/CONTRACT.md` stays as it is (`stream.sock` is untouched). `docs/CONTRACT-sessions.md` needs a sessions-v3 for the verbs, `/run/hhstream/live.sock`, the unit name, the viewer-touch exception, and the error names. Schema 4 is the record bump. No v1 or v2 field changes meaning.
|
||||
|
||||
| Stage | What | Size | Risk |
|
||||
|---|---|---|---|
|
||||
| 0 | Contract text only. | S | Freezing the wrong default. This plan is the review. |
|
||||
| 1 | `hhstream-live`: HTTP, token, one output, injected capture, unit tests. No broker. | M | A phone that will not paint `multipart/x-mixed-replace`. That is the gate for the WebSocket fallback, and it is not built here. |
|
||||
| 2 | Broker verbs, registry field, CLI, teardown order, viewer heartbeat, integration test. | L | A second port on retry; stop racing `output remove`; token leaking into `events.jsonl`; a heartbeat that keeps a session alive with zero viewers. |
|
||||
| 3 | Module: the unit, the socket, `portRange`, `fps` default 5 cap 10, `bind` default loopback, `openFirewall` default false. No host firewall edit unless you ask for the phone path separately. | M | A second `RuntimeDirectory` on `/run/hhstream` deleting `control.sock`. Copy the pointer unit's avoidance. |
|
||||
| 4 | Browser pass on the host, written down with what was actually on screen. | S | An empty container looking like a broken stream. Confirm the window is on `hh-<id>` first. |
|
||||
|
||||
**Open questions**
|
||||
|
||||
1. Viewer-connected stamps the idle clock; the verbs do not. Rejected alternative: the operator must `touch` while watching, which will reap a session at three hours mid-view.
|
||||
2. Listeners are not re-created after a restart. They are reattached if `hhstream-live` is still holding them.
|
||||
3. The phone does not work until `/etc/nixos` opts into `0.0.0.0` and the port range. Defaults stay loopback and firewalled. SSH `-L` works before that.
|
||||
4. The 5 fps cap is from the main output's ~46 ms JPEG, not from a measured `grim -o` of a container. Raise it only from a measurement.
|
||||
5. IPv6 is out of this slice.
|
||||
Reference in new issue
Block a user