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:
1 parent
edbf15f259
commit
d770bcd298
17 files changed
+9330
-18
No files matched your search
@@ -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.
|
||||
Reference in new issue
Block a user