feat(live): one port, a router, and a phrase per session (stage 1)
The session-stream web app: a single HTTP listener (9988) that serves a page
per enabled session, keyed by a spoken phrase. Off by default, so a stream
exists only for the sessions it was enabled on.
src/hhstream_live/phrase.py four EFF-large words + a 5-char base-36 tail
(~77.5 bits); the phrase is the password
src/hhstream_live/publisher.py one capture thread + one frame slot per
output; one slot/no queue; capture paused at
zero viewers
src/hhstream_live/server.py the router: /, /<phrase>/, /stream.mjpg,
/frame.jpg, /status.json; unknown phrase is
an empty 404, rate-limited
src/hhstream_live/pages.py the built-in dark pages (no CDN, no build)
src/hhstream_live/__main__.py hhstream-live serve|phrase, standalone
The root page is a form, never a list: the phrase is known only by whoever
enabled the stream. Transport is MJPEG (multipart/x-mixed-replace), reusing
the JPEG grim already produces. Not yet wired to the broker -- that is
stage 2. Tests: tests/live (51).
This commit is contained in:
1 parent
4b5cb5197a
commit
9744d35945
18 files changed
+9611
No files matched your search
@@ -0,0 +1,129 @@
|
||||
> **Superseded (2026-10-04):** the operator asked for one port (9988) with a
|
||||
> router and a phrase per session, only for enabled sessions — see
|
||||
> `docs/plans/2026-10-04-session-stream-webapp.md`. This file is kept for its
|
||||
> transport table and its capture/idle-clock reasoning, which the new plan
|
||||
> inherits.
|
||||
|
||||
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.
|
||||
@@ -0,0 +1,175 @@
|
||||
# Plan — a session-stream webapp (one port, a router, a phrase per session)
|
||||
|
||||
Supersedes `docs/plans/2026-10-03-network-stream.md` (call it v1). v1 spread a
|
||||
listener over a **port range** and handed each session a **128-bit URL token**;
|
||||
the operator asked for the opposite shape: **one port, a router with a page per
|
||||
session, and a spoken phrase** to open each one, with a stream existing **only
|
||||
for the sessions it was enabled on**. Everything v1 says about the *capture*
|
||||
path and the *separate unit* still holds and is not repeated here; this file
|
||||
replaces §2–§4 of v1 and keeps its §1 (transport) and §6 stages in spirit.
|
||||
|
||||
Decisions below are the ones worth disagreeing with. **Nothing is built yet** —
|
||||
the branch carries only a plan.
|
||||
|
||||
---
|
||||
|
||||
## 1. What is new, and why
|
||||
|
||||
| v1 | Now | Why |
|
||||
| --- | --- | --- |
|
||||
| Lowest free port in `9120–9131`, one per session | **One port, default 9988**, shared by every stream | A phrase is easier to read out when there is one address, not one per session. One listener is also one thing to firewall and one thing to stop. |
|
||||
| `/<token>/…`, a `secrets.token_urlsafe` blob | **`/<phrase>/…`**, four words off a fixed list | A URL a person can say out loud and retype on a phone. Same job as the token — it is the only credential — but shaped for a human. Entropy is discussed in §4. |
|
||||
| `stream start` on any live session | **`stream enable`** on a session, remembered, default **off** | "Not on for all sessions at all times": a session does not stream because it exists; it streams because it was switched on. |
|
||||
| Pages are token routes under one session's listener | **A router**: an index, and **four routes per session** (viewer, stream, snapshot, status) | A small app, not a file dump: `/` lists what is on, `/<phrase>/` is the thing you watch. |
|
||||
|
||||
The transport is unchanged: **MJPEG over HTTP** (`multipart/x-mixed-replace`),
|
||||
the JPEG `grim` already produces (`-c -t jpeg -q 80 -`), 5 fps default, hard cap
|
||||
10, capture **only while a viewer is connected**. A still browser `<img>` is the
|
||||
whole client. No WebSocket, no HLS, no TLS in this slice.
|
||||
|
||||
## 2. The unit, and the port
|
||||
|
||||
`hhstream-live.service`, **one process**, exactly as v1 argued: an executor
|
||||
beside the pointer driver, not the frame server (whose one-socket contract must
|
||||
not grow a LAN parser) and not the broker (`grim` blocks tens to hundreds of ms
|
||||
and must not stall `touch`/`kill`). It runs as the compositor user `hhstream`,
|
||||
finds `WAYLAND_DISPLAY` the way `hyprland-headless-stream` does, does **not**
|
||||
take `RuntimeDirectory=/run/hhstream` (that would delete the broker's socket),
|
||||
and speaks newline-JSON to the broker on `/run/hhstream/live.sock`.
|
||||
|
||||
It owns **the port**. A single listener means no allocator, no `TIME_WAIT`
|
||||
dance, and one URL prefix. The port is a module option (`sessions.stream.port`,
|
||||
default **9988**); the unit binds `sessions.stream.bind` (default `127.0.0.1`).
|
||||
If the port is taken the unit fails loudly and says so — it does not hunt for
|
||||
another one, because a stream at a port nobody was told is worse than a stream
|
||||
that is down.
|
||||
|
||||
**Bind and firewall defaults stay closed.** `openFirewall` defaults false; the
|
||||
module adds no `networking.firewall.allowedTCPPorts` unless it is set. Until
|
||||
that opt-in, the phone path is `ssh -L 9988:127.0.0.1:9988` from the device.
|
||||
|
||||
## 3. The router
|
||||
|
||||
One handler, four shapes, phrase-keyed. Everything else is a `404` with an
|
||||
empty body; a wrong phrase is never echoed back.
|
||||
|
||||
```
|
||||
GET / index: the enabled streams, their names, viewer
|
||||
counts, and links into them
|
||||
GET /<phrase>/ the viewer page — an <img src="stream.mjpg">
|
||||
in a dark frame with the session's name
|
||||
GET /<phrase>/stream.mjpg the multipart/x-mixed-replace stream
|
||||
GET /<phrase>/frame.jpg the most recent single JPEG (snapshot)
|
||||
GET /<phrase>/status.json {session, output, fps, viewers, last_frame_age_s}
|
||||
```
|
||||
|
||||
- The phrase is matched **case-insensitively** and tolerates a missing trailing
|
||||
slash, because a person will type it by hand; it is stored lowercase.
|
||||
- **The root page is a form, never a list.** The phrase is the password to a
|
||||
stream and is known only by whoever enabled it, so `/` must not enumerate
|
||||
sessions or leak phrases: it is a box you type a phrase into, which forwards
|
||||
to `/<phrase>/`. `/<phrase>/…` always works from whatever the bind allows.
|
||||
- The pages are **built-in** — one small HTML/CSS/JS string in the package, no
|
||||
CDN, no framework, no extra Python dependency. "Webapp" here means a real
|
||||
router and legible pages, not a build step.
|
||||
- Multiple pages **per session output**: a session's output `hh-<id>` gets its
|
||||
own four routes; adding a session adds routes under its phrase, never a new
|
||||
port.
|
||||
- Wrong-phrase lookups are **rate-limited** (a small per-IP counter, ~20/min) so
|
||||
the phrase is not enumerable at line speed over the LAN.
|
||||
|
||||
## 4. The phrase
|
||||
|
||||
Generated when the stream is **first enabled** for a session, and kept in the
|
||||
session record so it survives a broker restart and a re-enable.
|
||||
|
||||
- Shape: `<word>-<word>-<word>-<word>-<xxxxx>`, e.g.
|
||||
`amber-otter-lantern-harbor-7k2qp`.
|
||||
- Words come from a **vendored EFF large wordlist** (7776 words, ~70 KB, in the
|
||||
repo — no network at runtime, no dependency) and the tail is five characters
|
||||
of `[a-z0-9]`. Four words is `4 · log2(7776) ≈ 51.7` bits and the tail adds
|
||||
`5 · log2(36) ≈ 25.8`, for **≈ 77.5 bits** — comfortably past anything a LAN
|
||||
request rate can enumerate, and the operator's stated shape ("5 with a random
|
||||
5 character string for the last word").
|
||||
- `--phrase` on enable sets your own (checked against the shape); `disable`
|
||||
then `enable` **rotates** it. A rotation is one record write.
|
||||
- The phrase is the only credential. It is in the URL, in cleartext on the LAN
|
||||
when the LAN is opted into — the threat model is "another device on the LAN
|
||||
can watch if it can guess the phrase", not "the phrase is hidden from the
|
||||
network". Stated plainly so nobody mistakes it for TLS.
|
||||
- Secrets discipline from v1 carries over: the audit log records session id,
|
||||
output, port and bind; it **never** records the phrase.
|
||||
|
||||
## 5. Enable / disable, and the idle clock
|
||||
|
||||
Only an enabled session has a phrase, a listener entry, and any capture at all.
|
||||
Enabling is an explicit act, remembered in the record:
|
||||
|
||||
```
|
||||
hhstream session stream enable <id> [--phrase PHRASE] [--fps N]
|
||||
hhstream session stream disable <id>
|
||||
hhstream session stream list # enabled streams, phrases, viewers
|
||||
hhstream session stream status [id]
|
||||
```
|
||||
|
||||
- `enable` requires the session to have a container output (`hh-<id>`); without
|
||||
one it is the existing `no_container` error (exit 10). A stream never falls
|
||||
back to the main output — that would put every other session on the phone.
|
||||
- `enable` prints **only the URL** on stdout (`http://127.0.0.1:9988/<phrase>/`);
|
||||
stderr names the output and prints the `disable` command. `--json` adds
|
||||
`url`, `phrase`, `output`, `fps`, `viewers`. Re-enabling while enabled returns
|
||||
the same phrase; `--phrase` mismatch is `stream_busy` (exit 8).
|
||||
- No new exit numbers: reuse 2 (bad port/fps), 6 (`stream_budget` — the module's
|
||||
per-process viewer cap), 8 (busy), 10 (`stream_unavailable`/no container).
|
||||
- `enable`, `disable`, `list`, `status` do **not** touch the idle clock — the
|
||||
same rule as `pointer.*`. A **connected viewer is activity**: about once a
|
||||
minute the broker asks the daemon for viewer counts and stamps `touch` when
|
||||
any is non-zero. That is the one new way the clock moves; it is what keeps a
|
||||
session the operator is watching on his phone from being reaped at three
|
||||
hours. An enabled stream with nobody watching runs **no** `grim` and keeps no
|
||||
session alive.
|
||||
- The session record gains `stream = {enabled, phrase, fps, viewers, port}`
|
||||
(or `null`). **Registry schema 3 → 4**; older records migrate to
|
||||
`stream: null` and are adopted, not refused.
|
||||
- Teardown order is v1's and it is load-bearing: `disable` the stream (close the
|
||||
listener, drop the route) **before** `hyprctl output remove`.
|
||||
|
||||
## 6. Restart behaviour
|
||||
|
||||
A broker restart does **not** invent listeners. 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. If the daemon restarted too, the enabled
|
||||
records keep their phrases but the streams are off until re-enabled — an open
|
||||
port and a running capture are explicit acts, and the phrase is not a licence to
|
||||
capture without one.
|
||||
|
||||
## 7. What to build, in what order
|
||||
|
||||
| Stage | What | Size | Risk |
|
||||
| --- | --- | --- | --- |
|
||||
| 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`. |
|
||||
| 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-<id>` first. |
|
||||
|
||||
Test layers are v1's: `tests/unit` for the HTTP/router/phrase with a fake
|
||||
capture (multipart framing, each route, wrong phrase → empty 404, rate limit,
|
||||
capture idle at zero viewers, "unknown output" ends the stream), `tests/sessions`
|
||||
for the verbs and the clock, one integration test that runs a real daemon and a
|
||||
real `hhstream-live` on loopback with `urllib` reading two JPEGs. VM checks stay
|
||||
one at a time; no browser in a VM check.
|
||||
|
||||
## 8. Decisions taken (2026-10-04)
|
||||
|
||||
1. **The root page is a form, never a list.** The phrase is a password; the
|
||||
index must not hand it out. (Was "loopback-only index".)
|
||||
2. **Phrase = four EFF-large words + a five-character base-36 tail (~77.5
|
||||
bits).** The tail is what the operator asked for in place of a fifth word.
|
||||
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.
|
||||
Reference in new issue
Block a user