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.

  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. Tests: tests/live (51), all green with the full suite
(958). Not yet wired to the broker -- that is stage 2.
This commit is contained in:
Hermenix committed 2026-10-06 13:26:02 +00:00
1 parent edbf15f259
commit d770bcd298
17 files changed
+9330 -18

No files matched your search

+23 -18
View File
@@ -65,11 +65,10 @@ 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 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.
@@ -84,13 +83,14 @@ GET /<phrase>/status.json {session, output, fps, viewers, last_frame_age_s}
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`.
- 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). 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.
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
@@ -160,11 +160,16 @@ 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
## 8. Decisions taken (2026-10-04)
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.
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.