docs(plan): one port, a router, and a phrase per session
The operator rejected the port-range/token shape: a single port (9988) with a router, four routes per session output, and a spoken phrase as the key. Streams are opt-in per session (default off) and capture only while watched. Phrase is four EFF-large words (~51.6 bits); index is loopback-only by default. Supersedes 2026-10-03-network-stream.md.
This commit is contained in:
1 parent
deccfb592c
commit
02d5006524
2 files changed
+176
No files matched your search
@@ -1,3 +1,9 @@
|
||||
> **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
|
||||
|
||||
@@ -0,0 +1,170 @@
|
||||
# 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 index is loopback-only by default.** Over the LAN, `/` is a `404` unless
|
||||
`sessions.stream.publicIndex = true`. It lists phrases, so serving it to the
|
||||
network hands out every key at once; on the operator's own machine it is the
|
||||
convenient landing page. `/<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>`, e.g. `amber-otter-lantern-harbor`.
|
||||
- Words come from a **vendored EFF large wordlist** (7776 words, ~70 KB, in the
|
||||
repo — no network at runtime, no dependency). Four words is
|
||||
`4 · log2(7776) ≈ 51.6` bits, which is the number that matters: at a LAN's
|
||||
request rate that is not brute-forceable, and it matches what the 128-bit
|
||||
token bought in practice (the token was only ever a bearer string in a URL).
|
||||
Raise to five words with one constant if that is judged thin.
|
||||
- `--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. Open questions to answer before Stage 1
|
||||
|
||||
1. **Public index.** Loopback-only by default — agreed? (It lists phrases.)
|
||||
2. **Phrase length.** Four EFF-large words (~51.6 bits). Five if you want more
|
||||
head-room at the cost of typing.
|
||||
3. **Port 9988.** Fixed, single, no range fallback. Confirm the number.
|
||||
4. **Capture at zero viewers.** Paused (v1's choice, kept here) versus always-on
|
||||
while enabled. Paused is cheaper and the reason the idle rule is safe.
|
||||
Reference in new issue
Block a user