Compare commits

...
Author SHA1 Message Date
Hermenix d770bcd298 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.
2026-10-06 13:26:02 +00:00
Hermenix edbf15f259 Merge keyboard input (feat/keyboard-input @561e0c2) for a live trial on this machine
The merge request stays open for review; this is a local trial only.
Undo: git reset --hard 02d5006, then rebuild.
2026-10-05 12:31:41 +00:00
Hermenix 02d5006524 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.
2026-10-04 00:30:21 +00:00
Hermenix deccfb592c docs(plan): a live network stream per session — approach and open questions 2026-10-03 23:55:44 +00:00
18 changed files with 9611 additions and 0 deletions

No files matched your search

+129
View File
@@ -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.
+4
View File
@@ -35,6 +35,10 @@ python3.pkgs.buildPythonApplication {
"hhstream_pointer.keymap"
"hhstream_pointer._protocol.wlr_virtual_pointer_unstable_v1"
"hhstream_pointer._protocol.virtual_keyboard_unstable_v1"
# The web app. Importing the server pulls in the router, the publisher and
# the pages; the phrase generator's wordlist is checked by the unit suite,
# which reads the *installed* package.
"hhstream_live.server"
];
meta = {
+10
View File
@@ -27,6 +27,16 @@ hhstreamd = "hhstreamd.__main__:main"
# The pointer driver. Its own process because a Wayland client needs its own
# connection, and a blocked one must not stall the broker.
hhstream-pointer = "hhstream_pointer.__main__:main"
# The session-stream web app (one port, a page per enabled session). Its own
# process beside the pointer driver: a LAN-facing HTTP parser must not be able
# to stall session lifecycle, and `grim` blocking must not reach the broker.
hhstream-live = "hhstream_live.__main__:main"
[tool.setuptools.packages.find]
where = ["src"]
# The phrase generator reads this at runtime, so it has to be *installed*, not
# just present in the checkout: a wheel (and the Nix build) that dropped it
# would make every `enable` fail with an empty wordlist.
[tool.setuptools.package-data]
hhstream_live = ["wordlist.txt"]
+15
View File
@@ -0,0 +1,15 @@
"""The per-session live web stream: one port, a router, a phrase per session.
Stage 1 of `docs/plans/2026-10-04-session-stream-webapp.md`: the web application
itself -- the HTTP router, the viewer/snapshot/status pages, the MJPEG
publisher, and the phrase generator. No broker wiring yet; the broker's verbs
and the `/run/hhstream/live.sock` control channel are a separate stage.
The design in one line: a session's stream exists only once it is *enabled*,
its key is a spoken phrase, and every enabled session is a route under one
listener rather than a port of its own.
"""
from __future__ import annotations
__all__ = ["phrase", "publisher", "server", "pages"]
+139
View File
@@ -0,0 +1,139 @@
"""``hhstream-live`` -- run the session-stream web app.
Stage 1 runs it **standalone**: the streams are named on the command line as
``--stream <phrase>=<output>``, which is enough to watch a real container and to
drive the unit tests. Stage 2 adds the broker's control socket
(``/run/hhstream/live.sock``), at which point ``--stream`` becomes the way a
human debugs it rather than the way the broker configures it.
hhstream-live serve --stream four-words-and-a-tail=hh-demo
hhstream-live phrase
The capture command is one list of words; the output is aimed by inserting
``-o <output>`` before the trailing ``-``, which is grim's "write to stdout".
"""
from __future__ import annotations
import argparse
import logging
import sys
from . import phrase as phrase_mod
from .publisher import DEFAULT_FPS, FPS_CAP, StreamRegistry, StreamSpec
from .server import DEFAULT_HOST, DEFAULT_PORT, LiveServer
#: The session's own capture command, JPEG for the same reason the host config
#: spells it out: a 1280x720 JPEG q80 is ~46 ms and the point is a video, not a
#: slideshow. `-c` asks grim to include the cursor.
DEFAULT_CAPTURE = ["grim", "-c", "-t", "jpeg", "-q", "80", "-"]
def capture_argv(base: list[str], output: str) -> list[str]:
"""Aim the base capture command at one output.
``grim`` writes to stdout when its last argument is ``-``; the output
selector goes just before it so the shape holds for any tool that keeps that
convention, and a base without a trailing ``-`` simply gets ``-o`` appended.
"""
base = list(base)
if base and base[-1] == "-":
return base[:-1] + ["-o", output, "-"]
return base + ["-o", output]
def parse_stream(arg: str) -> tuple[str, str]:
"""``<phrase>=<output>`` -> the pair, each side checked non-empty."""
phrase, sep, output = arg.partition("=")
if not sep or not phrase.strip() or not output.strip():
raise argparse.ArgumentTypeError(f"expected PHRASE=OUTPUT, got {arg!r}")
try:
return phrase_mod.validate(phrase), output.strip()
except ValueError as exc:
raise argparse.ArgumentTypeError(str(exc)) from exc
def build_parser() -> argparse.ArgumentParser:
parser = argparse.ArgumentParser(prog="hhstream-live", description=__doc__)
parser.add_argument("--log-level", default="info",
choices=["debug", "info", "warning", "error"])
subs = parser.add_subparsers(dest="command")
serve = subs.add_parser("serve", help="run the web app (default)")
serve.add_argument("--port", type=int, default=DEFAULT_PORT,
help=f"the one port every stream shares (default {DEFAULT_PORT})")
serve.add_argument("--bind", default=DEFAULT_HOST,
help=f"address to bind (default {DEFAULT_HOST}, loopback)")
serve.add_argument("--fps", type=int, default=DEFAULT_FPS,
help=f"capture rate for streams that do not set one "
f"(default {DEFAULT_FPS}, cap {FPS_CAP})")
serve.add_argument("--stream", action="append", default=[], type=parse_stream,
metavar="PHRASE=OUTPUT",
help="enable a stream on this output; repeatable")
serve.add_argument("--capture-command", action="append", default=None,
metavar="WORD",
help="capture argv word; repeat (a repeated flag is the "
"only shape that survives words starting with '-')")
gen = subs.add_parser("phrase", help="print a fresh phrase and exit")
gen.add_argument("--count", type=int, default=1)
return parser
def make_registry(streams: list[tuple[str, str]], capture_base: list[str],
fps: int) -> StreamRegistry:
from hhstream.capture import CommandCapture
registry = StreamRegistry()
for phrase, output in streams:
spec = StreamSpec(phrase=phrase, output=output, fps=fps, label=output)
registry.add(spec, CommandCapture(capture_argv(capture_base, output)))
return registry
def cmd_serve(args: argparse.Namespace) -> int:
capture_base = args.capture_command or DEFAULT_CAPTURE
registry = make_registry(args.stream, capture_base, args.fps)
server = LiveServer(registry, host=args.bind, port=args.port)
print(f"landing page: http://{server.address}:{args.port}/", file=sys.stderr)
if not args.stream:
print("no --stream given; only the landing page will answer", file=sys.stderr)
server.start() # raises OSError loudly if the port is taken
for phrase in registry.phrases():
print(server.url_for(phrase))
sys.stdout.flush()
try:
import time
while True:
time.sleep(3600)
except KeyboardInterrupt:
print("stopping", file=sys.stderr)
finally:
server.stop()
return 0
def main(argv: list[str] | None = None) -> int:
parser = build_parser()
args = parser.parse_args(argv)
logging.basicConfig(
level=getattr(logging, (args.log_level or "info").upper()),
format="%(asctime)s %(levelname)s %(name)s: %(message)s",
)
command = args.command or "serve"
if command == "phrase":
for _ in range(args.count):
print(phrase_mod.generate())
return 0
if command == "serve":
return cmd_serve(args)
parser.error(f"unknown command {command!r}") # pragma: no cover
return 2
if __name__ == "__main__":
sys.exit(main())
+115
View File
@@ -0,0 +1,115 @@
"""The pages the router serves: the landing form and the per-session viewer.
Everything here is one self-contained HTML string. No CDN, no framework, no
build step -- "webapp" means a router and legible pages, not a toolchain. The
viewer page is the one that matters: it is an ``<img>`` pointed at the MJPEG
route, because a top-level ``multipart/x-mixed-replace`` document is unreliable
on phones while an image tag is not.
The landing page is a **form, never a list**. The phrase is the password to a
stream and is known only by whoever enabled it, so the root page must not
enumerate sessions or leak phrases; it just hands the typed phrase to
``/<phrase>/``.
"""
from __future__ import annotations
import html
from functools import lru_cache
_STYLE = """
:root{color-scheme:dark}
*{box-sizing:border-box}
body{margin:0;background:#0b0d12;color:#e6e8ee;font:15px/1.5 ui-sans-serif,system-ui,sans-serif}
main{max-width:960px;margin:0 auto;padding:24px}
h1{font-size:20px;margin:0 0 4px}
a{color:#7cc4ff}
.muted{color:#8b93a7}
.card{background:#141821;border:1px solid #232838;border-radius:12px;padding:20px}
img{width:100%;height:auto;display:block;border-radius:8px;background:#000}
input{width:100%;padding:12px 14px;margin:10px 0 14px;border-radius:8px;
border:1px solid #2c3346;background:#0e121b;color:inherit;font:inherit}
button{padding:11px 16px;border:0;border-radius:8px;background:#3b82f6;color:#fff;
font:inherit;cursor:pointer}
button:hover{background:#2f6fd6}
.badge{display:inline-flex;align-items:center;gap:6px;font-size:13px;color:#8b93a7}
.dot{width:8px;height:8px;border-radius:50%;background:#3ddc84;box-shadow:0 0 8px #3ddc84}
.row{display:flex;align-items:center;justify-content:space-between;gap:12px;margin-bottom:12px}
.tools{display:flex;gap:14px;font-size:13px;margin-top:12px}
"""
def _esc(text: str) -> str:
return html.escape(text, quote=True)
@lru_cache(maxsize=1)
def landing_page(app_name: str = "hhstream live") -> str:
"""The root page: a box to type a phrase into. No session list, ever."""
return f"""<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>{_esc(app_name)}</title><style>{_STYLE}</style>
</head><body><main>
<h1>{_esc(app_name)}</h1>
<p class="muted">A live view is opened with the phrase printed when its session
was enabled.</p>
<div class="card">
<label for="p">Session phrase</label>
<input id="p" autocomplete="off" autocapitalize="off" spellcheck="false"
placeholder="four-words-and-a-tail">
<button id="go">Open stream</button>
</div>
<script>
const input = document.getElementById('p');
function open() {{
const phrase = input.value.trim().toLowerCase();
if (phrase) location.href = '/' + encodeURIComponent(phrase) + '/';
}}
document.getElementById('go').addEventListener('click', open);
input.addEventListener('keydown', e => {{ if (e.key === 'Enter') open(); }});
input.focus();
</script>
</main></body></html>
"""
def viewer_page(phrase: str, label: str, output: str, fps: int) -> str:
"""The page you watch: an `<img>` on the stream, plus a small live readout."""
base = f"/{phrase}"
return f"""<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>{_esc(label)} — live</title><style>{_STYLE}</style>
</head><body><main>
<div class="row">
<div>
<h1>{_esc(label)}</h1>
<div class="muted">{_esc(output)} · {fps} fps</div>
</div>
<span class="badge"><span class="dot"></span><span id="v">live</span></span>
</div>
<div class="card">
<img id="stream" src="{base}/stream.mjpg" alt="live view of {_esc(label)}">
</div>
<div class="tools">
<a href="{base}/frame.jpg">snapshot</a>
<a href="{base}/status.json">status</a>
<a href="/">another phrase</a>
</div>
<script>
const out = document.getElementById('v');
async function tick() {{
try {{
const s = await (await fetch('{base}/status.json', {{cache:'no-store'}})).json();
out.textContent = s.viewers + (s.viewers === 1 ? ' viewer' : ' viewers') +
(s.last_frame_age_s == null ? '' : ' · ' + s.last_frame_age_s.toFixed(1) + 's ago');
}} catch (e) {{ out.textContent = 'offline'; }}
}}
tick(); setInterval(tick, 2000);
</script>
</main></body></html>
"""
__all__ = ["landing_page", "viewer_page"]
+102
View File
@@ -0,0 +1,102 @@
"""The phrase: a stream's only credential, shaped to be said out loud.
A phrase is ``word-word-word-word-xxxxx``: four words off the EFF large
wordlist and a five-character base-36 tail. That is ``4*log2(7776) +
5*log2(36)`` ~= **77.5 bits** of entropy, against a word set small enough to be
a file in the repository and a tail short enough to type on a phone.
Why words and not the ``secrets.token_urlsafe`` blob the first plan proposed:
the phrase is read out -- "open amber-otter-lantern-harbor-7k2qp" -- and a
base64 string is not. The job is identical (it *is* the password to the
stream); only the shape is chosen for a human.
The list is vendored (`wordlist.txt`, 7776 lines) so a stream never needs the
network to start. `generate` uses `SystemRandom`/`secrets`, so the phrase is
not reproducible from the process seed.
"""
from __future__ import annotations
import math
import random
import re
import secrets
from pathlib import Path
#: Four words plus the tail. The plan's answer to "how many"; four is
#: `4 * log2(7776)` ~= 51.7 bits on its own, and the tail pushes it past 77.
WORD_COUNT = 4
SUFFIX_LEN = 5
#: Lowercase letters and digits: what a person can retype without a shift key,
#: and 36 symbols is still `5 * log2(36)` ~= 25.8 bits.
SUFFIX_ALPHABET = "abcdefghijklmnopqrstuvwxyz0123456789"
#: A phrase is one or more hyphen-joined tokens of lowercase letters/digits,
#: at least three of them (so a caller-supplied phrase cannot be a single word
#: or a passcode-free stub). Generated phrases are five tokens; this is the
#: looser shape a `--phrase` must satisfy.
_SHAPE = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+){2,}$")
MAX_LENGTH = 96
_WORDLIST = Path(__file__).with_name("wordlist.txt")
_cache: tuple[str, ...] | None = None
def words() -> tuple[str, ...]:
"""The wordlist, read once and remembered.
Raises `RuntimeError` on an empty file rather than returning nothing: a
generator that picks from an empty list would raise a confusing `IndexError`
later, and the empty file is a packaging bug worth naming here.
"""
global _cache
if _cache is None:
text = _WORDLIST.read_text(encoding="utf-8")
loaded = tuple(word.strip() for word in text.splitlines() if word.strip())
if not loaded:
raise RuntimeError(f"wordlist {_WORDLIST} is empty")
_cache = loaded
return _cache
def entropy_bits(word_count: int = WORD_COUNT, suffix_len: int = SUFFIX_LEN) -> float:
"""How many bits a phrase of this shape carries, for the record."""
return word_count * math.log2(len(words())) + suffix_len * math.log2(len(SUFFIX_ALPHABET))
def generate(*, word_count: int = WORD_COUNT, suffix_len: int = SUFFIX_LEN) -> str:
"""A fresh phrase, drawn from the system entropy pool."""
if word_count < 1 or suffix_len < 0:
raise ValueError("word_count must be >= 1 and suffix_len >= 0")
rng = random.SystemRandom()
chosen = [rng.choice(words()) for _ in range(word_count)]
tail = "".join(secrets.choice(SUFFIX_ALPHABET) for _ in range(suffix_len))
return "-".join([*chosen, tail]) if tail else "-".join(chosen)
def normalize(phrase: str) -> str:
"""Fold a phrase to the one form the registry and the router compare on.
Lowercase and trimmed, because a phrase is typed by hand; the router also
accepts it without a trailing slash. Nothing else is folded -- a phrase with
an internal space is simply invalid, not silently rewritten.
"""
return phrase.strip().lower()
def validate(phrase: str) -> str:
"""Return the normalized phrase, or raise `ValueError` naming the shape."""
normalized = normalize(phrase)
if len(normalized) > MAX_LENGTH:
raise ValueError(f"phrase is {len(normalized)} characters; the maximum is {MAX_LENGTH}")
if not _SHAPE.match(normalized):
raise ValueError(
"phrase must be lowercase words/digits joined by hyphens, at least "
"three tokens (e.g. four-words-and-a-tail), not "
f"{phrase!r}"
)
return normalized
__all__ = ["WORD_COUNT", "SUFFIX_LEN", "generate", "normalize", "validate",
"entropy_bits", "words", "MAX_LENGTH"]
+264
View File
@@ -0,0 +1,264 @@
"""The publisher: one capture thread and one frame slot per enabled session.
This is the same shape as the frame server's inner loop (`hhstream/server.py`),
scaled from one output to many and given two rules the network side needs:
* **one slot, no queue.** A viewer reads the most recent frame when it is ready
for another one; a slow viewer misses frames instead of forcing a backlog, so
memory does not grow with viewers and one stalled phone cannot delay another.
* **no capture unless someone is watching.** The capture thread sleeps while a
stream has zero viewers. That is what lets a stream be *enabled* without a
`grim` running: the port is open, the route exists, and the CPU is idle until
a request arrives. It is also why the broker can safely treat a connected
viewer as activity and an enabled-but-unwatched stream as nothing at all.
A `Stream` never touches the broker or the HTTP layer; it is a capture loop with
a frame slot and a viewer count, and the server hands it viewers.
"""
from __future__ import annotations
import logging
import threading
import time
from dataclasses import dataclass
from typing import Any, Callable, Protocol
log = logging.getLogger("hhstream.live")
#: The plan's cap. 5 fps default is "one frame per ~200 ms plus a ~46 ms grim",
#: chosen from the measured JPEG cost, not a guess; 10 is the ceiling because
#: the box is also running the compositor and the main publisher.
DEFAULT_FPS = 5
FPS_CAP = 10
#: After this many capture failures with no successful frame, a stream gives up
#: and closes its viewers. `grim` against a removed output ("unknown output")
#: fails every time, and retrying forever would be a busy loop on a dead session.
FAILURE_LIMIT = 10
class Capture(Protocol):
def grab(self) -> bytes: # pragma: no cover - structural
...
@dataclass(frozen=True)
class StreamSpec:
"""What to publish, and under which phrase.
`session` is the broker's session id (``None`` in a standalone run); `label`
is what the viewer page shows. `output` is the compositor output the capture
is aimed at (``hh-<session-id>``), kept here so the page and the status
payload can name it without re-deriving it.
"""
phrase: str
output: str
fps: int = DEFAULT_FPS
session: str | None = None
label: str = ""
def public(self) -> dict[str, Any]:
return {
"phrase": self.phrase,
"output": self.output,
"fps": self.fps,
"session": self.session,
"label": self.label or self.session or self.output,
}
class Stream:
"""One output's capture loop, frame slot and viewer count."""
def __init__(self, spec: StreamSpec, capture: Capture,
clock: Callable[[], float] = time.monotonic) -> None:
if isinstance(spec.fps, bool) or not isinstance(spec.fps, int) or spec.fps <= 0:
raise ValueError(f"fps must be a positive int, got {spec.fps!r}")
if spec.fps > FPS_CAP:
raise ValueError(f"fps {spec.fps} exceeds the cap of {FPS_CAP}")
self.spec = spec
self.capture = capture
self._clock = clock
self._cond = threading.Condition()
self._frame: bytes | None = None
self._seq = 0
self._viewers = 0
self._captured = 0
self._failures = 0
self._consecutive_failures = 0
self._last_frame_at: float | None = None
self._stopped = False
self._thread: threading.Thread | None = None
# ---- lifecycle ---------------------------------------------------
def start(self) -> None:
self._thread = threading.Thread(
target=self._run, name=f"hhstream-live-{self.spec.phrase}", daemon=True
)
self._thread.start()
def stop(self) -> None:
with self._cond:
self._stopped = True
self._cond.notify_all()
if self._thread is not None:
self._thread.join(timeout=5)
def _sleep(self, seconds: float) -> bool:
"""Wait `seconds`, or until stopped. True means 'stop now'."""
with self._cond:
return self._cond.wait_for(lambda: self._stopped, timeout=seconds)
def _run(self) -> None:
interval = 1.0 / self.spec.fps
while True:
# Idle at zero viewers: this is the "not on for all sessions at all
# times" rule made concrete -- an enabled stream costs nothing until
# a request arrives.
with self._cond:
while not self._stopped and self._viewers == 0:
self._cond.wait(0.5)
if self._stopped:
return
try:
frame = self.capture.grab()
except Exception as exc: # noqa: BLE001 - any backend failure is a skip
with self._cond:
self._failures += 1
self._consecutive_failures += 1
give_up = self._consecutive_failures >= FAILURE_LIMIT and self._captured == 0
if give_up:
self._stopped = True
self._cond.notify_all()
if give_up:
log.warning("stream %s: giving up after %d capture failures: %s",
self.spec.phrase, FAILURE_LIMIT, exc)
return
log.debug("stream %s: capture failed: %s", self.spec.phrase, exc)
if self._sleep(0.5):
return
continue
with self._cond:
self._frame = frame
self._seq += 1
self._captured += 1
self._consecutive_failures = 0
self._last_frame_at = self._clock()
self._cond.notify_all()
if self._sleep(interval):
return
# ---- viewers -----------------------------------------------------
def add_viewer(self) -> int:
with self._cond:
self._viewers += 1
self._cond.notify_all()
return self._viewers
def remove_viewer(self) -> int:
with self._cond:
self._viewers = max(0, self._viewers - 1)
self._cond.notify_all()
return self._viewers
@property
def viewers(self) -> int:
with self._cond:
return self._viewers
def wait_frame(self, last_seq: int, timeout: float = 2.0) -> tuple[bytes | None, int]:
"""Block for a frame newer than `last_seq`.
Returns `(frame, seq)`; `(None, last_seq)` on timeout or after the
stream stopped with no new frame, which tells a viewer loop to re-check
whether it should keep going.
"""
with self._cond:
self._cond.wait_for(
lambda: self._seq > last_seq or self._stopped, timeout=timeout
)
if self._seq > last_seq:
return self._frame, self._seq
return None, last_seq
@property
def stopped(self) -> bool:
with self._cond:
return self._stopped
def snapshot(self) -> bytes | None:
with self._cond:
return self._frame
# ---- reporting ---------------------------------------------------
def status(self) -> dict[str, Any]:
with self._cond:
age = None if self._last_frame_at is None else max(0.0, self._clock() - self._last_frame_at)
return {
"session": self.spec.session,
"label": self.spec.label or self.spec.session or self.spec.output,
"output": self.spec.output,
"fps": self.spec.fps,
"viewers": self._viewers,
"captured": self._captured,
"failures": self._failures,
"last_frame_age_s": age,
"stopped": self._stopped,
}
class StreamRegistry:
"""The router's table: phrase -> `Stream`, compared case-insensitively.
A `Stream` is added already started; removing it stops the capture thread.
This is the whole of what "enabled" means on the publisher side -- there is
no disabled stream held in reserve, so an unknown phrase and a never-enabled
session are the same 404.
"""
def __init__(self) -> None:
self._streams: dict[str, Stream] = {}
def add(self, spec: StreamSpec, capture: Capture, *, start: bool = True) -> Stream:
from . import phrase as phrase_mod
key = phrase_mod.validate(spec.phrase)
if key in self._streams:
raise ValueError(f"phrase {key!r} is already enabled")
stream = Stream(spec, capture)
self._streams[key] = stream
if start:
stream.start()
return stream
def remove(self, phrase: str) -> Stream | None:
from . import phrase as phrase_mod
stream = self._streams.pop(phrase_mod.normalize(phrase), None)
if stream is not None:
stream.stop()
return stream
def get(self, phrase: str) -> Stream | None:
from . import phrase as phrase_mod
return self._streams.get(phrase_mod.normalize(phrase))
def phrases(self) -> list[str]:
return sorted(self._streams)
def all(self) -> list[Stream]:
return [self._streams[key] for key in sorted(self._streams)]
def stop_all(self) -> None:
for stream in self.all():
stream.stop()
__all__ = ["StreamSpec", "Stream", "StreamRegistry", "Capture", "DEFAULT_FPS",
"FPS_CAP", "FAILURE_LIMIT"]
+280
View File
@@ -0,0 +1,280 @@
"""The web app: one HTTP listener, a router, a page per enabled session.
One port (default 9988) serves every stream. The routes are keyed by *phrase*,
which is the only credential:
GET / the landing form (never a list of sessions)
GET /<phrase>/ the viewer page
GET /<phrase>/stream.mjpg multipart/x-mixed-replace, JPEG parts
GET /<phrase>/frame.jpg the most recent single frame
GET /<phrase>/status.json {session, output, fps, viewers, ...}
Anything else is `404` with an **empty** body, and a wrong phrase is never
echoed back. Unknown phrases are rate-limited per client so the phrase is not
enumerable at line speed.
Deliberately the standard library: `http.server` plus the framing rules this
module writes itself. A phone's `<img>` is the only client that must work, and
that needs `multipart/x-mixed-replace` with `Content-Type: image/jpeg` parts --
nothing a dependency would make easier.
"""
from __future__ import annotations
import logging
import threading
import time
from collections import deque
from http import HTTPStatus
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from urllib.parse import unquote, urlsplit
from . import pages
from .publisher import Stream, StreamRegistry
log = logging.getLogger("hhstream.live")
#: The multipart separator. Fixed and simple; it never appears in a JPEG.
BOUNDARY = "hhstreamboundary"
#: How long a viewer loop waits for a new frame before re-checking liveness.
FRAME_WAIT_S = 2.0
DEFAULT_PORT = 9988
DEFAULT_HOST = "127.0.0.1"
#: Wrong-phrase lookups allowed per client per window before 429.
RATE_LIMIT = 30
RATE_WINDOW_S = 60.0
class RateLimiter:
"""A small per-client counter for failed phrase lookups.
A phrase carries ~77 bits, so guessing is already hopeless; this is here so
that a LAN attacker cannot even *try* at line speed, and so the attempt is
visible in one place. Only misses are counted.
"""
def __init__(self, limit: int = RATE_LIMIT, window: float = RATE_WINDOW_S,
clock=time.monotonic) -> None:
self.limit = limit
self.window = window
self._clock = clock
self._hits: dict[str, deque[float]] = {}
self._lock = threading.Lock()
def allow(self, key: str) -> bool:
now = self._clock()
with self._lock:
hits = self._hits.setdefault(key, deque())
cutoff = now - self.window
while hits and hits[0] < cutoff:
hits.popleft()
if len(hits) >= self.limit:
return False
hits.append(now)
return True
def reset(self) -> None:
with self._lock:
self._hits.clear()
class _Server(ThreadingHTTPServer):
daemon_threads = True
allow_reuse_address = True
def __init__(self, address, handler, registry: StreamRegistry,
limiter: RateLimiter) -> None:
self.registry = registry
self.limiter = limiter
super().__init__(address, handler)
class _Handler(BaseHTTPRequestHandler):
protocol_version = "HTTP/1.1"
server_version = "hhstream-live"
sys_version = ""
# ---- plumbing ----------------------------------------------------
@property
def registry(self) -> StreamRegistry:
return self.server.registry # type: ignore[attr-defined]
def log_message(self, format: str, *args) -> None: # noqa: A002 - base signature
log.debug("%s %s", self.address_string(), format % args)
def _send(self, status: HTTPStatus, body: bytes, content_type: str,
headers: dict[str, str] | None = None) -> None:
self.send_response(status)
self.send_header("Content-Type", content_type)
self.send_header("Content-Length", str(len(body)))
self.send_header("Cache-Control", "no-store")
self.send_header("X-Content-Type-Options", "nosniff")
for name, value in (headers or {}).items():
self.send_header(name, value)
self.end_headers()
if body:
self.wfile.write(body)
def _empty(self, status: HTTPStatus) -> None:
self._send(status, b"", "text/plain; charset=utf-8")
# ---- routes ------------------------------------------------------
def do_GET(self) -> None: # noqa: N802 - the name http.server dispatches to
path = unquote(urlsplit(self.path).path)
try:
self._route(path)
except (BrokenPipeError, ConnectionResetError):
pass # the viewer went away mid-write; that is not an error
except OSError as exc:
log.debug("client error on %s: %s", path, exc)
def _route(self, path: str) -> None:
if path in ("", "/"):
body = pages.landing_page().encode("utf-8")
self._send(HTTPStatus.OK, body, "text/html; charset=utf-8")
return
if path == "/healthz":
self._send(HTTPStatus.OK, b"ok\n", "text/plain; charset=utf-8")
return
if not path.startswith("/"):
self._empty(HTTPStatus.NOT_FOUND)
return
head, _, rest = path.lstrip("/").partition("/")
stream = self.registry.get(head)
if stream is None:
# A miss. `head` is user input and is never reflected anywhere.
if not self.server.limiter.allow(self.client_address[0]): # type: ignore[attr-defined]
self._empty(HTTPStatus.TOO_MANY_REQUESTS)
else:
self._empty(HTTPStatus.NOT_FOUND)
return
if rest in ("", "index.html"):
self._viewer(stream)
elif rest == "stream.mjpg":
self._mjpeg(stream)
elif rest == "frame.jpg":
self._snapshot(stream)
elif rest == "status.json":
self._status(stream)
else:
self._empty(HTTPStatus.NOT_FOUND)
# ---- handlers ----------------------------------------------------
def _viewer(self, stream: Stream) -> None:
spec = stream.spec
label = spec.label or spec.session or spec.output
body = pages.viewer_page(spec.phrase, label, spec.output, spec.fps).encode("utf-8")
self._send(HTTPStatus.OK, body, "text/html; charset=utf-8")
def _status(self, stream: Stream) -> None:
import json
body = json.dumps(stream.status()).encode("utf-8")
self._send(HTTPStatus.OK, body, "application/json; charset=utf-8")
def _snapshot(self, stream: Stream) -> None:
frame = stream.snapshot()
if frame is None:
# No frame yet: nobody has watched this stream, so nothing has been
# captured. 503 is the honest answer, not a blank image.
self._empty(HTTPStatus.SERVICE_UNAVAILABLE)
return
self._send(HTTPStatus.OK, frame, "image/jpeg")
def _mjpeg(self, stream: Stream) -> None:
self.send_response(HTTPStatus.OK)
self.send_header("Content-Type", f"multipart/x-mixed-replace; boundary={BOUNDARY}")
self.send_header("Cache-Control", "no-store")
self.send_header("X-Content-Type-Options", "nosniff")
self.end_headers()
stream.add_viewer()
# The connection is the stream: after this handler returns there is no
# next request to read, so it must not be kept alive.
self.close_connection = True
last_seq = 0
try:
while True:
frame, seq = stream.wait_frame(last_seq, timeout=FRAME_WAIT_S)
if frame is None:
if stream.stopped:
return
continue # nothing new yet; loop and re-check liveness
last_seq = seq
self.wfile.write(self._part(frame))
# unreachable; the loop exits by return/exception
finally:
stream.remove_viewer()
@staticmethod
def _part(frame: bytes) -> bytes:
header = (
f"--{BOUNDARY}\r\n"
"Content-Type: image/jpeg\r\n"
f"Content-Length: {len(frame)}\r\n"
"\r\n"
).encode("ascii")
return header + frame + b"\r\n"
class LiveServer:
"""Owns the listener and its lifetime. One instance, many streams."""
def __init__(self, registry: StreamRegistry, *, host: str = DEFAULT_HOST,
port: int = DEFAULT_PORT, limiter: RateLimiter | None = None) -> None:
self.registry = registry
self.host = host
self.requested_port = port
self.limiter = limiter or RateLimiter()
self._httpd: _Server | None = None
self._thread: threading.Thread | None = None
self.ready = threading.Event()
@property
def port(self) -> int:
"""The bound port (resolves a requested port of 0 to the real one)."""
if self._httpd is None:
return self.requested_port
return self._httpd.server_address[1]
@property
def address(self) -> str:
advertised = self.host
if advertised in ("0.0.0.0", "::"):
advertised = "127.0.0.1"
return advertised
def url_for(self, phrase: str) -> str:
return f"http://{self.address}:{self.port}/{phrase}/"
def start(self) -> None:
"""Bind and serve. Raises `OSError` if the port is taken -- loudly.
Deliberately no hunting for a free port: a stream at a port nobody was
told is worse than a stream that refuses to start.
"""
self._httpd = _Server((self.host, self.requested_port), _Handler,
self.registry, self.limiter)
self._thread = threading.Thread(target=self._httpd.serve_forever,
name="hhstream-live-http", daemon=True)
self._thread.start()
self.ready.set()
log.info("listening on http://%s:%d", self.host, self.port)
def stop(self) -> None:
if self._httpd is not None:
self._httpd.shutdown()
self._httpd.server_close()
self._httpd = None
if self._thread is not None:
self._thread.join(timeout=5)
self._thread = None
self.registry.stop_all()
__all__ = ["LiveServer", "RateLimiter", "DEFAULT_PORT", "DEFAULT_HOST", "BOUNDARY"]
File diff suppressed because it is too large. Load diff
+86
View File
@@ -0,0 +1,86 @@
"""Fixtures for the session-stream web app suite.
Everything is standard library and everything is in-process: a real
`LiveServer` on a loopback ephemeral port, fed by a stub capture, with plain
`http.client` for the requests. No compositor, no `grim`, no broker.
The doubles (`StubCapture`, `read_parts`, `PHRASE`) live in `live_helpers.py`, not
here, so the tests import them by a plain module name -- the same shape as
`tests/unit`.
"""
from __future__ import annotations
import contextlib
import http.client
import pathlib
import sys
import pytest
_HERE = pathlib.Path(__file__).resolve().parent
_SRC = _HERE.parents[1] / "src"
for _path in (str(_HERE), str(_SRC)):
if _path not in sys.path:
sys.path.insert(0, _path)
from fake_jpeg import jpeg_bytes # noqa: E402
from live_helpers import PHRASE, StubCapture # noqa: E402
from hhstream_live.publisher import StreamRegistry, StreamSpec # noqa: E402
from hhstream_live.server import LiveServer, RateLimiter # noqa: E402
@pytest.fixture
def jpg():
return jpeg_bytes
@pytest.fixture
def registry():
reg = StreamRegistry()
yield reg
reg.stop_all()
@pytest.fixture
def serve(registry):
"""`with serve(phrase=..., capture=..., fps=...) as (server, capture)`."""
servers: list[LiveServer] = []
@contextlib.contextmanager
def _serve(*, phrase: str = PHRASE, capture: StubCapture | None = None,
fps: int = 5, label: str = "demo", limit: int = 30):
capture = capture or StubCapture()
spec = StreamSpec(phrase=phrase, output="hh-demo", fps=fps, session="demo",
label=label)
registry.add(spec, capture)
server = LiveServer(registry, host="127.0.0.1", port=0,
limiter=RateLimiter(limit=limit))
servers.append(server)
server.start()
assert server.ready.wait(5)
try:
yield server, capture
finally:
server.stop()
yield _serve
for server in servers:
with contextlib.suppress(Exception):
server.stop()
@pytest.fixture
def http_conn():
"""Open an HTTP connection to a running server; closed at teardown."""
connections: list[http.client.HTTPConnection] = []
def _connect(server: LiveServer, timeout: float = 10.0) -> http.client.HTTPConnection:
conn = http.client.HTTPConnection("127.0.0.1", server.port, timeout=timeout)
connections.append(conn)
return conn
yield _connect
for conn in connections:
with contextlib.suppress(Exception):
conn.close()
+31
View File
@@ -0,0 +1,31 @@
"""A tiny real JPEG, for tests that need decodable image bytes.
The frame server's tests use a fake that writes a PNG (zlib is in the standard
library). MJPEG needs *JPEG* parts, and there is no JPEG encoder in the stdlib,
so the smallest honest thing is one real 1x1 JPEG embedded as base64 and reused.
`jpeg_bytes(marker)` rewrites one *quantisation-table* byte, so two frames differ
byte-for-byte (a test can prove "a new frame arrived") while the image stays
valid: the EOI marker, the headers and the scan data are untouched.
"""
from __future__ import annotations
import base64
#: A 1x1 JPEG. Real enough that `hhstream.capture.image_size` reports (1, 1).
_ONE_PIXEL = (
"/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRof"
"Hh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/wAALCAABAAEBAREA/8QAFAAB"
"AAAAAAAAAAAAAAAAAAAACf/EABQQAQAAAAAAAAAAAAAAAAAAAAD/2gAIAQEAAD8AVN//2Q=="
)
#: The start of the quantisation table: `FFDB`, length `0043`, precision/id `00`.
_DQT = b"\xff\xdb\x00C\x00"
def jpeg_bytes(marker: int = 0) -> bytes:
"""The 1x1 JPEG with one table byte varied by `marker` (0..249)."""
data = bytearray(base64.b64decode(_ONE_PIXEL))
start = data.index(_DQT) + len(_DQT)
data[start + 63] = (marker % 250) + 1 # a nonzero quantiser keeps it decodable
return bytes(data)
+82
View File
@@ -0,0 +1,82 @@
"""Shared doubles for the session-stream web app suite.
Kept out of `conftest.py` on purpose: the rest of the suite imports its doubles
from a plain module (`tests/unit/helpers.py`), and `import conftest` by name is
fragile across directories.
"""
from __future__ import annotations
import pathlib
import sys
import threading
import time
_HERE = pathlib.Path(__file__).resolve().parent
_SRC = _HERE.parents[1] / "src"
for _path in (str(_HERE), str(_SRC)):
if _path not in sys.path:
sys.path.insert(0, _path)
from fake_jpeg import jpeg_bytes # noqa: E402
#: The one phrase the suite enables. Shape matters, not the words.
PHRASE = "amber-otter-lantern-harbor-7k2qp"
class StubCapture:
"""A `Capture` under the test's control: counts grabs, can be told to fail."""
def __init__(self, frames=None, fail_first: int = 0, delay: float = 0.0):
self.frames = list(frames) if frames else [jpeg_bytes(i) for i in range(1, 50)]
self.fail_first = fail_first
self.delay = delay
self.calls = 0
self._lock = threading.Lock()
def grab(self) -> bytes:
with self._lock:
self.calls += 1
call = self.calls
if self.delay:
time.sleep(self.delay)
if call <= self.fail_first:
raise RuntimeError(f"stub capture failing on purpose (call {call})")
return self.frames[(call - 1 - self.fail_first) % len(self.frames)]
def read_parts(resp, count: int, timeout: float = 10.0) -> list[bytes]:
"""Read up to `count` JPEG parts out of a multipart MJPEG response."""
from hhstream_live.server import BOUNDARY
boundary = ("--" + BOUNDARY).encode("ascii")
parts: list[bytes] = []
buf = b""
deadline = time.monotonic() + timeout
while len(parts) < count and time.monotonic() < deadline:
chunk = resp.read(4096)
if not chunk:
break
buf += chunk
while True:
start = buf.find(boundary)
if start < 0:
break
header_end = buf.find(b"\r\n\r\n", start)
if header_end < 0:
break
header = buf[start:header_end].decode("latin-1")
length = None
for line in header.splitlines():
if line.lower().startswith("content-length:"):
length = int(line.split(":", 1)[1].strip())
if length is None:
break
body_start = header_end + 4
if len(buf) < body_start + length:
break
parts.append(buf[body_start:body_start + length])
buf = buf[body_start + length + 2:]
if len(parts) >= count:
break
return parts[:count]
+50
View File
@@ -0,0 +1,50 @@
"""The command line: it aims a capture at an output, and it can mint a phrase."""
from __future__ import annotations
import io
from contextlib import redirect_stdout
import pytest
from hhstream_live.__main__ import DEFAULT_CAPTURE, capture_argv, main, parse_stream
def test_capture_command_is_aimed_by_inserting_the_output_before_stdout():
assert capture_argv(DEFAULT_CAPTURE, "hh-demo") == [
"grim", "-c", "-t", "jpeg", "-q", "80", "-o", "hh-demo", "-",
]
def test_capture_command_without_a_trailing_dash_gets_the_output_appended():
assert capture_argv(["grim", "-t", "jpeg"], "hh-x") == [
"grim", "-t", "jpeg", "-o", "hh-x",
]
def test_parse_stream_reads_a_pair_and_normalizes_the_phrase():
assert parse_stream("Amber-Otter-Lantern-Harbor-7K2QP=hh-demo") == (
"amber-otter-lantern-harbor-7k2qp", "hh-demo",
)
@pytest.mark.parametrize("bad", ["no-equals-sign", "=hh-demo", "phrase=", "ab=hh"])
def test_parse_stream_rejects_a_bad_pair(bad):
import argparse
with pytest.raises(argparse.ArgumentTypeError):
parse_stream(bad)
def test_the_phrase_subcommand_prints_a_phrase():
out = io.StringIO()
with redirect_stdout(out):
assert main(["phrase"]) == 0
printed = out.getvalue().strip()
assert printed.count("-") == 4 # four words + tail
def test_the_phrase_subcommand_can_print_several():
out = io.StringIO()
with redirect_stdout(out):
main(["phrase", "--count", "3"])
assert len(out.getvalue().split()) == 3
+63
View File
@@ -0,0 +1,63 @@
"""The phrase: shape, entropy, and the rejection of anything unusable."""
from __future__ import annotations
import re
import pytest
from hhstream_live import phrase
SHAPE = re.compile(r"^[a-z]+(-[a-z]+){3}-[a-z0-9]{5}$")
def test_generated_phrase_has_the_agreed_shape():
for _ in range(50):
generated = phrase.generate()
assert SHAPE.match(generated), generated
head, _, tail = generated.rpartition("-")
assert len(tail) == 5
assert all(word in phrase.words() for word in head.split("-"))
def test_entropy_is_what_the_plan_claims():
# Four EFF-large words plus a five-character base-36 tail, ~77.5 bits.
assert phrase.entropy_bits() > 75
def test_wordlist_is_the_eff_large_list():
words = phrase.words()
assert len(words) == 7776
assert len(set(words)) == 7776
assert "abacus" in words
def test_generate_is_not_reproducible_from_a_seed():
# SystemRandom/secrets: seeding the module RNG must not pin the output.
import random
random.seed(1234)
first = phrase.generate()
random.seed(1234)
second = phrase.generate()
assert first != second
def test_normalize_lowercases_and_trims():
assert phrase.normalize(" Amber-Otter-7K2 ") == "amber-otter-7k2"
def test_validate_accepts_a_good_phrase_and_returns_the_normalized_form():
assert phrase.validate("Amber-Otter-Lantern-7K2QP") == "amber-otter-lantern-7k2qp"
@pytest.mark.parametrize("bad", ["", "single", "two-tokens", "has space-phrase-x",
"dash--double-phrase", "-leading-hyphen",
"trailing-hyphen-", "under_score-in-phrase"])
def test_validate_rejects_a_phrase_that_is_not_the_shape(bad):
with pytest.raises(ValueError):
phrase.validate(bad)
def test_validate_rejects_an_overlong_phrase():
with pytest.raises(ValueError):
phrase.validate("-".join(["averyverylongword"] * 8))
+125
View File
@@ -0,0 +1,125 @@
"""The publisher: no capture while unwatched, one slot, and giving up when dead."""
from __future__ import annotations
import time
import pytest
from live_helpers import PHRASE, StubCapture
from hhstream_live.publisher import (FPS_CAP, FAILURE_LIMIT, Stream, StreamRegistry,
StreamSpec)
def make_stream(capture, *, fps=10, phrase=PHRASE):
return Stream(StreamSpec(phrase=phrase, output="hh-demo", fps=fps), capture)
@pytest.mark.parametrize("bad", [0, -1, True, 1.5, FPS_CAP + 1])
def test_fps_must_be_a_positive_int_within_the_cap(bad):
with pytest.raises(ValueError):
make_stream(StubCapture(), fps=bad)
def test_no_capture_while_nobody_is_watching():
"""An enabled stream costs nothing until a request arrives."""
capture = StubCapture()
stream = make_stream(capture)
stream.start()
try:
time.sleep(0.4)
assert capture.calls == 0
finally:
stream.stop()
def test_capture_starts_when_a_viewer_arrives_and_stops_when_it_leaves():
capture = StubCapture()
stream = make_stream(capture)
stream.start()
try:
stream.add_viewer()
frame, seq = stream.wait_frame(0, timeout=5)
assert frame and seq >= 1
stream.remove_viewer()
time.sleep(0.3)
settled = capture.calls
time.sleep(0.4)
assert capture.calls == settled # idle again
finally:
stream.stop()
def test_snapshot_is_none_before_anyone_watches_and_bytes_after():
stream = make_stream(StubCapture())
stream.start()
try:
assert stream.snapshot() is None
stream.add_viewer()
frame, _ = stream.wait_frame(0, timeout=5)
stream.remove_viewer()
assert frame is not None
assert stream.snapshot() == frame
finally:
stream.stop()
def test_a_slow_viewer_does_not_queue_frames():
"""One slot: a viewer that sleeps sees the latest frame, never a backlog."""
stream = make_stream(StubCapture(delay=0.01), fps=10)
stream.start()
try:
stream.add_viewer()
first, seq = stream.wait_frame(0, timeout=5)
time.sleep(0.3) # let many frames go by unsent
later, seq2 = stream.wait_frame(seq, timeout=5)
assert later is not None
# seq jumped by more than one: the frames in between were dropped, not
# buffered for us.
assert seq2 > seq + 1
finally:
stream.stop()
def test_a_dead_capture_gives_up_and_closes_viewers():
capture = StubCapture(fail_first=10_000) # never succeeds
stream = make_stream(capture, fps=10)
stream.start()
try:
stream.add_viewer()
frame, _ = stream.wait_frame(0, timeout=10)
assert frame is None
assert stream.stopped
assert capture.calls >= FAILURE_LIMIT
finally:
stream.stop()
# ---- registry --------------------------------------------------------------
def test_registry_adds_and_finds_a_phrase_case_insensitively():
registry = StreamRegistry()
try:
registry.add(StreamSpec(phrase=PHRASE, output="hh-demo"), StubCapture())
assert registry.get("Amber-Otter-Lantern-Harbor-7K2QP") is not None
assert registry.get("nope-not-here-at-all") is None
finally:
registry.stop_all()
def test_registry_refuses_a_duplicate_phrase():
registry = StreamRegistry()
try:
registry.add(StreamSpec(phrase=PHRASE, output="hh-demo"), StubCapture())
with pytest.raises(ValueError):
registry.add(StreamSpec(phrase=PHRASE, output="hh-other"), StubCapture())
finally:
registry.stop_all()
def test_registry_remove_stops_the_stream():
registry = StreamRegistry()
stream = registry.add(StreamSpec(phrase=PHRASE, output="hh-demo"), StubCapture())
assert registry.remove(PHRASE) is stream
assert registry.get(PHRASE) is None
assert stream.stopped
assert registry.remove(PHRASE) is None
+165
View File
@@ -0,0 +1,165 @@
"""The web app's obligations: the router, the pages, and MJPEG over one port."""
from __future__ import annotations
import threading
import time
from live_helpers import PHRASE, StubCapture, read_parts
from hhstream_live.server import BOUNDARY
WRONG = "no-such-phrase-here-00000"
def get(conn, path):
conn.request("GET", path)
resp = conn.getresponse()
body = resp.read()
return resp.status, resp, body
def test_landing_page_is_a_form_and_names_no_phrase(serve, http_conn):
with serve() as (server, _capture):
conn = http_conn(server)
status, resp, body = get(conn, "/")
assert status == 200
assert resp.getheader("Content-Type").startswith("text/html")
assert PHRASE not in body.decode()
assert "hh-demo" not in body.decode()
assert b"phrase" in body.lower()
def test_healthz(serve, http_conn):
with serve() as (server, _):
status, _, body = get(http_conn(server), "/healthz")
assert status == 200 and body.strip() == b"ok"
def test_unknown_phrase_is_404_with_an_empty_body(serve, http_conn):
with serve() as (server, _):
status, resp, body = get(http_conn(server), f"/{WRONG}/")
assert status == 404
assert body == b""
assert WRONG not in resp.getheader("Content-Type", "")
def test_a_wrong_subpath_under_a_valid_phrase_is_404(serve, http_conn):
with serve() as (server, _):
status, _, body = get(http_conn(server), f"/{PHRASE}/secrets.txt")
assert status == 404 and body == b""
def test_viewer_page_names_the_output_and_points_at_the_stream(serve, http_conn):
with serve() as (server, _):
status, _, body = get(http_conn(server), f"/{PHRASE}/")
assert status == 200
page = body.decode()
assert f"/{PHRASE}/stream.mjpg" in page
assert "hh-demo" in page
def test_phrase_is_case_insensitive(serve, http_conn):
with serve() as (server, _):
status, _, _ = get(http_conn(server), f"/{PHRASE.upper()}/")
assert status == 200
def test_status_json_shape(serve, http_conn):
import json
with serve() as (server, _):
status, resp, body = get(http_conn(server), f"/{PHRASE}/status.json")
assert status == 200
assert resp.getheader("Content-Type").startswith("application/json")
doc = json.loads(body)
assert doc["session"] == "demo"
assert doc["output"] == "hh-demo"
assert doc["fps"] == 5
assert doc["viewers"] == 0
assert doc["stopped"] is False
def test_snapshot_is_503_until_someone_has_watched(serve, http_conn):
with serve() as (server, _):
status, _, body = get(http_conn(server), f"/{PHRASE}/frame.jpg")
assert status == 503 and body == b""
def test_stream_is_mjpeg_and_delivers_valid_jpeg_parts(serve, http_conn):
with serve(fps=10) as (server, capture):
conn = http_conn(server)
conn.request("GET", f"/{PHRASE}/stream.mjpg")
resp = conn.getresponse()
assert resp.status == 200
assert resp.getheader("Content-Type") == (
f"multipart/x-mixed-replace; boundary={BOUNDARY}"
)
parts = read_parts(resp, 2)
assert len(parts) == 2
for part in parts:
assert part.startswith(b"\xff\xd8") # JPEG SOI
assert part.endswith(b"\xff\xd9") # JPEG EOI
conn.close()
def test_snapshot_works_after_a_viewer_has_pulled_a_frame(serve, http_conn):
with serve(fps=10) as (server, _):
stream_conn = http_conn(server)
stream_conn.request("GET", f"/{PHRASE}/stream.mjpg")
resp = stream_conn.getresponse()
assert read_parts(resp, 1)
stream_conn.close()
time.sleep(0.05)
status, ctype, body = get(http_conn(server), f"/{PHRASE}/frame.jpg")
assert status == 200
assert ctype.getheader("Content-Type") == "image/jpeg"
assert body.startswith(b"\xff\xd8")
def test_two_viewers_both_receive_frames(serve, http_conn):
with serve(fps=10) as (server, _):
results: dict[str, object] = {}
def watch(name: str) -> None:
conn = http_conn(server)
conn.request("GET", f"/{PHRASE}/stream.mjpg")
resp = conn.getresponse()
results[name] = read_parts(resp, 1)
conn.close()
threads = [threading.Thread(target=watch, args=(n,)) for n in ("a", "b")]
for t in threads:
t.start()
for t in threads:
t.join(timeout=10)
assert results["a"] and results["b"]
def test_no_capture_until_a_request_arrives(serve):
with serve() as (server, capture):
time.sleep(0.4)
assert capture.calls == 0
import http.client
conn = http.client.HTTPConnection("127.0.0.1", server.port, timeout=10)
conn.request("GET", f"/{PHRASE}/stream.mjpg")
resp = conn.getresponse()
assert read_parts(resp, 1)
conn.close()
assert capture.calls >= 1
def test_repeated_wrong_phrases_are_rate_limited(serve, http_conn):
with serve(limit=3) as (server, _):
conn = http_conn(server)
seen = [get(conn, f"/{WRONG}-{i}/")[0] for i in range(3)]
assert seen == [404, 404, 404]
assert get(conn, f"/{WRONG}-9/")[0] == 429
def test_the_server_binds_and_reports_its_port(serve):
with serve() as (server, _):
assert server.ready.is_set()
assert server.port > 0
assert server.url_for(PHRASE) == f"http://127.0.0.1:{server.port}/{PHRASE}/"