Compare commits
4
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
d770bcd298 | ||
|
|
edbf15f259 | ||
|
|
02d5006524 | ||
|
|
deccfb592c |
No files matched your search
@@ -0,0 +1,129 @@
|
||||
> **Superseded (2026-10-04):** the operator asked for one port (9988) with a
|
||||
> router and a phrase per session, only for enabled sessions — see
|
||||
> `docs/plans/2026-10-04-session-stream-webapp.md`. This file is kept for its
|
||||
> transport table and its capture/idle-clock reasoning, which the new plan
|
||||
> inherits.
|
||||
|
||||
I'll explore the frame server, session CLI, broker, contracts, and the NixOS module first, then write a plan only — no edits.The tree is a Python frame server, a session broker, and a pointer daemon. Next I’ll read the contracts and the capture/session paths those decisions depend on.The publisher cannot select a session today. `hhstream-server` serves one output on `/run/hypr-stream/stream.sock` and its command line is frozen. `hhstream shot --output hh-<id>` and `record --output` are separate `grim -o` one-shots. A phone view should be a new, view-only listener beside that, not a change to the socket Hermenix already reads.
|
||||
|
||||
## Decisions
|
||||
|
||||
### 1. Transport
|
||||
|
||||
**Primary: MJPEG over HTTP.** **Fallback: a WebSocket carrying the existing `HHS1` frames, only if a real phone browser will not render the MJPEG.** Not HLS, not VNC, not WebRTC.
|
||||
|
||||
| Option | Latency | CPU on this box | Already here | Plain browser |
|
||||
|---|---|---|---|---|
|
||||
| MJPEG (`multipart/x-mixed-replace`) | One frame. At the recommended 5 fps that is about 200 ms plus a ~46 ms `grim` JPEG. | Reuses the JPEG the host already measured: 1280×720 q80 is ~46 ms; PNG is ~326 ms and is the wrong codec. One capture, many viewers. | `CommandCapture`, the single-slot drop policy, JPEG size parsing. Stdlib HTTP only. | Yes. An `<img>` needs no plugin and no script. |
|
||||
| WebSocket of `HHS1` | Same pixels, same latency. | Same capture cost. | The framing code. | No. A phone that opens the URL sees nothing unless we also serve a page that blits JPEGs. |
|
||||
| HLS | Seconds (segment delay). | A second encode (`libx264`) on top of `grim`. `ffmpeg` is only used today to mux a finished recording. | Nothing of the live path. | Safari yes, Chrome only with a script. |
|
||||
| VNC / RFB | Fine. | A new codec, and a client can click. | Nothing. | No. noVNC is a script, and clicks would bypass the pointer lease. |
|
||||
| WebRTC | Best, and irrelevant. | An encoder plus ICE/DTLS. Worst cost for a two-core software renderer. | Nothing. | Only via a script and a signaling dance. |
|
||||
|
||||
The URL we print is a tiny same-origin HTML page whose only job is `<img src="stream.mjpg">`. Top-level multipart documents are unreliable; the image tag is the one that works on phones. The same process also serves one `frame.jpg` for tests. No CDN, no extra Python dependencies. The WebSocket fallback is the same JPEG bytes and the same page, and it is not built in the first slice.
|
||||
|
||||
Capture rate for a session stream defaults to **5 fps, hard cap 10**. The main publisher already spends roughly one core on its own `grim`. A second full-rate capture would take the other core. Five frames times ~46 ms is about a quarter of one core, and only while someone is connected.
|
||||
|
||||
### 2. Where the listener lives
|
||||
|
||||
**A new long-lived unit, `hhstream-live.service`. One process, many session outputs. Not the frame server, not the broker, and not one unit per session.**
|
||||
|
||||
It follows the pointer driver, not the frame server:
|
||||
|
||||
- The frame server's contract is one socket, one output, one slot, and a command line of `--socket`, `--fps`, `--format`, and `--capture-command`. Clients send nothing. A LAN parser bug or a slow phone must not be able to take down the socket Hermenix reads. The server also does not know session ids, idle deadlines, or teardown.
|
||||
- The broker is the control plane (`/run/hhstream/control.sock`, newline JSON, mode `0660`). `grim` takes tens to hundreds of milliseconds and its timeout is 5 s. That block must not freeze `touch`, `kill`, or the reaper. That is why the pointer is already a separate process.
|
||||
- A systemd template per session would be a second supervisor. Sessions are broker records, and `SessionManager.teardown` is deliberately the only kill path. A child unit also races `KillMode=` and adopt-on-restart.
|
||||
|
||||
`hhstream-live` is an executor. It holds no session policy. The broker tells it what to publish over a private socket, `/run/hhstream/live.sock` (mode `0660`, next to `pointer.sock`). It must not take `RuntimeDirectory=/run/hhstream`; the pointer unit's comments record that a second owner deletes the broker's socket.
|
||||
|
||||
It runs as the compositor user `hhstream`, with `video` and `render`, `ProtectHome` and `ProtectSystem=strict`, the same shape as `hyprland-headless-stream`. It discovers `WAYLAND_DISPLAY` the way that unit already does. It does not run as `hermes`: a network process should not have the agent's home. Group `hhstream` can already open the broker socket; this does not widen that.
|
||||
|
||||
**One session's picture.** The broker sends the output name `hh-<session-id>` and the full capture argv, built from the module's `captureCommand` plus `-o hh-<id>`. On this host that is `grim -o hh-<id> -c -t jpeg -q 80 -`. One capture thread and one frame slot per output, same drop rule as `FrameServer`: a slow viewer skips frames and is never queued. The daemon does not touch `stream.sock` and does not capture the main output.
|
||||
|
||||
**No container, no stream.** If the session's container is missing or `degraded`, `stream start` returns the existing `no_container` error (exit 10). Falling back to the main output would put every other session on the phone. Containers are on in `/etc/nixos/hyprland-stream.nix` as a trial, and a window that ignores `HHSTREAM_APP_ID` still lands in quarantine. The stream will then honestly show an empty output. That is a container bug, not a reason to capture the main screen.
|
||||
|
||||
**When the session dies.** `teardown` (kill, reap, and gc) tells the daemon to stop that output and close its clients **before** `hyprctl output remove`. If the output disappears anyway, `grim`'s "unknown output" ends the stream after a few failures. It does not retry forever the way the main publisher must. The port is freed when the listener closes.
|
||||
|
||||
A broker restart does not rebind anything. If the daemon is still up, the broker asks it for the list and reattaches those listeners to the session records so status and teardown still see them. If the daemon restarted too, the stream is gone and status says so. An open port is an explicit act.
|
||||
|
||||
### 3. Addressing and lifecycle
|
||||
|
||||
**The caller may pass a port. Otherwise the broker takes the lowest free port in a configured range. Default range `9120–9131`.** Not a single configured port (two sessions must fit; `max_containers` is 2). Not an ephemeral port (a phone URL has to be writable, and a firewall cannot name port 0). `9120` starts just above **9119**, which `/etc/nixos/common.nix` already opens for the Hermes dashboard. Twelve ports covers the container budget plus a restart where the old socket is still in `TIME_WAIT`.
|
||||
|
||||
```
|
||||
hhstream session stream start <id> [--port N] [--bind ADDR] [--fps N]
|
||||
hhstream session stream stop <id>
|
||||
hhstream session stream status [id]
|
||||
```
|
||||
|
||||
Nested like `pointer`: one precondition (a container output) and one warning (this is a network listener). `start` prints **only the URL** on stdout, the same trick as the session id and the lease id:
|
||||
|
||||
```
|
||||
http://127.0.0.1:9120/<token>/
|
||||
```
|
||||
|
||||
Stderr says it is view-only, names the output, and prints the stop command. `--json` adds `url`, `port`, `bind`, `token`, `output`, `fps`, and `viewers`. When bind is `0.0.0.0`, the printed host is the default-route IPv4, overridable with `--advertise ADDR`, plus the loopback URL. Do not print `0.0.0.0`.
|
||||
|
||||
`start` on a session that already has a listener returns that listener (and its token) when port and bind match, and `stream_busy` (exit 8) when they do not. `request_id` covers `start` and `stop` so a retry cannot open a second port. `stop` only stops the listener; the session keeps running. A port outside the range is exit 2. The range being full is `stream_budget`, exit 6. The daemon being down is `stream_unavailable`, exit 10. No new exit-code numbers.
|
||||
|
||||
The session record gains a `stream` object (`port`, `bind`, `token`, `output`, `fps`, `pid` or daemon id). Registry schema bumps to 4; older records migrate to `stream: null` and are adopted, not refused.
|
||||
|
||||
**Idle clock.** `start`, `stop`, and `status` do **not** touch. Same rule as `pointer`: setting something up is not "still wanted". A **connected viewer is activity**. About once a minute the broker asks the daemon for viewer counts and, if any are non-zero, stamps `touch`. That is the one new way the clock moves, and it is not a CLI verb. It has to be: the idle timeout is three hours, and a session the operator is watching from his phone must not be reaped out from under him. An open port with nobody connected does not stamp, and it does not run `grim`. The reaper then kills the session on the normal deadline, and teardown closes the listener. A forgotten URL is a bound socket, not a hot core and not a pinned session.
|
||||
|
||||
### 4. Security
|
||||
|
||||
This would be the first listener meant to be opened from another device. Everything else is a unix socket in a `0750` directory, mode `0660`, group `hhstream`, with no authentication. The host firewall allows inbound TCP **22 and 9119 only**. The pixels can be a logged-in browser.
|
||||
|
||||
**Default bind is `127.0.0.1`. The firewall stays closed. A path token is always required, including on loopback.**
|
||||
|
||||
Loopback is still weaker than the group-gated frame socket: any local user can open a TCP port. The token is what replaces the group check. It is a 128-bit `secrets.token_urlsafe` value in the path, because an `<img>` will send a path and will not send a custom header:
|
||||
|
||||
```
|
||||
GET /<token>/ the page
|
||||
GET /<token>/stream.mjpg the multipart stream
|
||||
GET /<token>/frame.jpg one JPEG
|
||||
```
|
||||
|
||||
Anything else is a 404 with an empty body. Wrong-token responses do not echo the token. The audit log records port, bind, and output, and does not record the token. The token lives in the session record under the broker state dir (`/var/lib/hermes/hhstream-sessions` on this machine). `stop` then `start` rotates it.
|
||||
|
||||
LAN is opt-in twice, in the host config, not in the module defaults:
|
||||
|
||||
- `sessions.stream.bind = "0.0.0.0"` (or a specific address). `--bind` on the CLI can do the same for one session.
|
||||
- `sessions.stream.openFirewall`, default **false**. The module must not add ports to `networking.firewall.allowedTCPPorts` unless that option is on. This machine should turn it on in `/etc/nixos` only when the phone path is wanted, and the range must not include 9119.
|
||||
|
||||
The token is cleartext on the LAN. The threat model is "another device on the LAN can watch if it has the URL", not "the URL is secret from the network". There is no TLS in this slice; a private CA and a phone trust prompt are a worse default. Until the firewall is opened, the phone path is an SSH forward to loopback (`ssh -L 9120:127.0.0.1:9120`), which keeps the current posture.
|
||||
|
||||
The listener is view-only. No pointer, no keyboard, no `hyprctl`. At most four viewers. The broker pulls viewer counts; the daemon cannot ask the broker to touch an arbitrary session.
|
||||
|
||||
### 5. Tests
|
||||
|
||||
Same layers as the rest of the repo. No GPU for unit tests. No browser in the VM checks. VM checks stay one at a time.
|
||||
|
||||
| Test | Proves |
|
||||
|---|---|
|
||||
| `tests/unit` for the publisher, with `FakeCapture` | Multipart framing, one JPEG per part, `Content-Type`, token 404s with an empty body, a stalled viewer does not block another, capture does not run at zero viewers, "unknown output" ends the stream. This mirrors `tests/unit/test_server.py`. |
|
||||
| `tests/sessions/unit` | Port allocator (lowest free, range exhausted, clash), CLI parse, stdout is the bare URL, stderr carries the warning, `start`/`stop`/`status` do not touch, a viewer heartbeat does, teardown issues stop before the container is destroyed. New error names map to exits 2, 6, 8, and 10 without renumbering. |
|
||||
| `tests/sessions/integration` | A real daemon and a real `hhstream-live` on `127.0.0.1` with an ephemeral port. `urllib` reads two JPEGs, a wrong token fails, `stream stop` closes the port, and a real idle reap closes it too. Fake capture, no compositor. |
|
||||
| A human browser pass, not a check | On the host, `stream start` against a session whose window is actually on `hh-<id>` (the cooperating client from `checks/vm-containers.nix`, not `foot` or Chromium). Open the printed URL in the Chromium this machine already installs. Change pixels; they must show up without a reload. The phone pass is the same URL only after bind and firewall are opted in. |
|
||||
|
||||
`urllib` reading a multipart body is the automated proof that a browser's `<img>` has something valid to decode. A headless-Chrome screenshot is optional and is not a VM check: two software-rendered compositors plus a browser will flake on two cores.
|
||||
|
||||
### 6. Stages
|
||||
|
||||
Contracts bump first. `docs/CONTRACT.md` stays as it is (`stream.sock` is untouched). `docs/CONTRACT-sessions.md` needs a sessions-v3 for the verbs, `/run/hhstream/live.sock`, the unit name, the viewer-touch exception, and the error names. Schema 4 is the record bump. No v1 or v2 field changes meaning.
|
||||
|
||||
| Stage | What | Size | Risk |
|
||||
|---|---|---|---|
|
||||
| 0 | Contract text only. | S | Freezing the wrong default. This plan is the review. |
|
||||
| 1 | `hhstream-live`: HTTP, token, one output, injected capture, unit tests. No broker. | M | A phone that will not paint `multipart/x-mixed-replace`. That is the gate for the WebSocket fallback, and it is not built here. |
|
||||
| 2 | Broker verbs, registry field, CLI, teardown order, viewer heartbeat, integration test. | L | A second port on retry; stop racing `output remove`; token leaking into `events.jsonl`; a heartbeat that keeps a session alive with zero viewers. |
|
||||
| 3 | Module: the unit, the socket, `portRange`, `fps` default 5 cap 10, `bind` default loopback, `openFirewall` default false. No host firewall edit unless you ask for the phone path separately. | M | A second `RuntimeDirectory` on `/run/hhstream` deleting `control.sock`. Copy the pointer unit's avoidance. |
|
||||
| 4 | Browser pass on the host, written down with what was actually on screen. | S | An empty container looking like a broken stream. Confirm the window is on `hh-<id>` first. |
|
||||
|
||||
**Open questions**
|
||||
|
||||
1. Viewer-connected stamps the idle clock; the verbs do not. Rejected alternative: the operator must `touch` while watching, which will reap a session at three hours mid-view.
|
||||
2. Listeners are not re-created after a restart. They are reattached if `hhstream-live` is still holding them.
|
||||
3. The phone does not work until `/etc/nixos` opts into `0.0.0.0` and the port range. Defaults stay loopback and firewalled. SSH `-L` works before that.
|
||||
4. The 5 fps cap is from the main output's ~46 ms JPEG, not from a measured `grim -o` of a container. Raise it only from a measurement.
|
||||
5. IPv6 is out of this slice.
|
||||
@@ -0,0 +1,175 @@
|
||||
# Plan — a session-stream webapp (one port, a router, a phrase per session)
|
||||
|
||||
Supersedes `docs/plans/2026-10-03-network-stream.md` (call it v1). v1 spread a
|
||||
listener over a **port range** and handed each session a **128-bit URL token**;
|
||||
the operator asked for the opposite shape: **one port, a router with a page per
|
||||
session, and a spoken phrase** to open each one, with a stream existing **only
|
||||
for the sessions it was enabled on**. Everything v1 says about the *capture*
|
||||
path and the *separate unit* still holds and is not repeated here; this file
|
||||
replaces §2–§4 of v1 and keeps its §1 (transport) and §6 stages in spirit.
|
||||
|
||||
Decisions below are the ones worth disagreeing with. **Nothing is built yet** —
|
||||
the branch carries only a plan.
|
||||
|
||||
---
|
||||
|
||||
## 1. What is new, and why
|
||||
|
||||
| v1 | Now | Why |
|
||||
| --- | --- | --- |
|
||||
| Lowest free port in `9120–9131`, one per session | **One port, default 9988**, shared by every stream | A phrase is easier to read out when there is one address, not one per session. One listener is also one thing to firewall and one thing to stop. |
|
||||
| `/<token>/…`, a `secrets.token_urlsafe` blob | **`/<phrase>/…`**, four words off a fixed list | A URL a person can say out loud and retype on a phone. Same job as the token — it is the only credential — but shaped for a human. Entropy is discussed in §4. |
|
||||
| `stream start` on any live session | **`stream enable`** on a session, remembered, default **off** | "Not on for all sessions at all times": a session does not stream because it exists; it streams because it was switched on. |
|
||||
| Pages are token routes under one session's listener | **A router**: an index, and **four routes per session** (viewer, stream, snapshot, status) | A small app, not a file dump: `/` lists what is on, `/<phrase>/` is the thing you watch. |
|
||||
|
||||
The transport is unchanged: **MJPEG over HTTP** (`multipart/x-mixed-replace`),
|
||||
the JPEG `grim` already produces (`-c -t jpeg -q 80 -`), 5 fps default, hard cap
|
||||
10, capture **only while a viewer is connected**. A still browser `<img>` is the
|
||||
whole client. No WebSocket, no HLS, no TLS in this slice.
|
||||
|
||||
## 2. The unit, and the port
|
||||
|
||||
`hhstream-live.service`, **one process**, exactly as v1 argued: an executor
|
||||
beside the pointer driver, not the frame server (whose one-socket contract must
|
||||
not grow a LAN parser) and not the broker (`grim` blocks tens to hundreds of ms
|
||||
and must not stall `touch`/`kill`). It runs as the compositor user `hhstream`,
|
||||
finds `WAYLAND_DISPLAY` the way `hyprland-headless-stream` does, does **not**
|
||||
take `RuntimeDirectory=/run/hhstream` (that would delete the broker's socket),
|
||||
and speaks newline-JSON to the broker on `/run/hhstream/live.sock`.
|
||||
|
||||
It owns **the port**. A single listener means no allocator, no `TIME_WAIT`
|
||||
dance, and one URL prefix. The port is a module option (`sessions.stream.port`,
|
||||
default **9988**); the unit binds `sessions.stream.bind` (default `127.0.0.1`).
|
||||
If the port is taken the unit fails loudly and says so — it does not hunt for
|
||||
another one, because a stream at a port nobody was told is worse than a stream
|
||||
that is down.
|
||||
|
||||
**Bind and firewall defaults stay closed.** `openFirewall` defaults false; the
|
||||
module adds no `networking.firewall.allowedTCPPorts` unless it is set. Until
|
||||
that opt-in, the phone path is `ssh -L 9988:127.0.0.1:9988` from the device.
|
||||
|
||||
## 3. The router
|
||||
|
||||
One handler, four shapes, phrase-keyed. Everything else is a `404` with an
|
||||
empty body; a wrong phrase is never echoed back.
|
||||
|
||||
```
|
||||
GET / index: the enabled streams, their names, viewer
|
||||
counts, and links into them
|
||||
GET /<phrase>/ the viewer page — an <img src="stream.mjpg">
|
||||
in a dark frame with the session's name
|
||||
GET /<phrase>/stream.mjpg the multipart/x-mixed-replace stream
|
||||
GET /<phrase>/frame.jpg the most recent single JPEG (snapshot)
|
||||
GET /<phrase>/status.json {session, output, fps, viewers, last_frame_age_s}
|
||||
```
|
||||
|
||||
- The phrase is matched **case-insensitively** and tolerates a missing trailing
|
||||
slash, because a person will type it by hand; it is stored lowercase.
|
||||
- **The root page is a form, never a list.** The phrase is the password to a
|
||||
stream and is known only by whoever enabled it, so `/` must not enumerate
|
||||
sessions or leak phrases: it is a box you type a phrase into, which forwards
|
||||
to `/<phrase>/`. `/<phrase>/…` always works from whatever the bind allows.
|
||||
- The pages are **built-in** — one small HTML/CSS/JS string in the package, no
|
||||
CDN, no framework, no extra Python dependency. "Webapp" here means a real
|
||||
router and legible pages, not a build step.
|
||||
- Multiple pages **per session output**: a session's output `hh-<id>` gets its
|
||||
own four routes; adding a session adds routes under its phrase, never a new
|
||||
port.
|
||||
- Wrong-phrase lookups are **rate-limited** (a small per-IP counter, ~20/min) so
|
||||
the phrase is not enumerable at line speed over the LAN.
|
||||
|
||||
## 4. The phrase
|
||||
|
||||
Generated when the stream is **first enabled** for a session, and kept in the
|
||||
session record so it survives a broker restart and a re-enable.
|
||||
|
||||
- Shape: `<word>-<word>-<word>-<word>-<xxxxx>`, e.g.
|
||||
`amber-otter-lantern-harbor-7k2qp`.
|
||||
- Words come from a **vendored EFF large wordlist** (7776 words, ~70 KB, in the
|
||||
repo — no network at runtime, no dependency) and the tail is five characters
|
||||
of `[a-z0-9]`. Four words is `4 · log2(7776) ≈ 51.7` bits and the tail adds
|
||||
`5 · log2(36) ≈ 25.8`, for **≈ 77.5 bits** — comfortably past anything a LAN
|
||||
request rate can enumerate, and the operator's stated shape ("5 with a random
|
||||
5 character string for the last word").
|
||||
- `--phrase` on enable sets your own (checked against the shape); `disable`
|
||||
then `enable` **rotates** it. A rotation is one record write.
|
||||
- The phrase is the only credential. It is in the URL, in cleartext on the LAN
|
||||
when the LAN is opted into — the threat model is "another device on the LAN
|
||||
can watch if it can guess the phrase", not "the phrase is hidden from the
|
||||
network". Stated plainly so nobody mistakes it for TLS.
|
||||
- Secrets discipline from v1 carries over: the audit log records session id,
|
||||
output, port and bind; it **never** records the phrase.
|
||||
|
||||
## 5. Enable / disable, and the idle clock
|
||||
|
||||
Only an enabled session has a phrase, a listener entry, and any capture at all.
|
||||
Enabling is an explicit act, remembered in the record:
|
||||
|
||||
```
|
||||
hhstream session stream enable <id> [--phrase PHRASE] [--fps N]
|
||||
hhstream session stream disable <id>
|
||||
hhstream session stream list # enabled streams, phrases, viewers
|
||||
hhstream session stream status [id]
|
||||
```
|
||||
|
||||
- `enable` requires the session to have a container output (`hh-<id>`); without
|
||||
one it is the existing `no_container` error (exit 10). A stream never falls
|
||||
back to the main output — that would put every other session on the phone.
|
||||
- `enable` prints **only the URL** on stdout (`http://127.0.0.1:9988/<phrase>/`);
|
||||
stderr names the output and prints the `disable` command. `--json` adds
|
||||
`url`, `phrase`, `output`, `fps`, `viewers`. Re-enabling while enabled returns
|
||||
the same phrase; `--phrase` mismatch is `stream_busy` (exit 8).
|
||||
- No new exit numbers: reuse 2 (bad port/fps), 6 (`stream_budget` — the module's
|
||||
per-process viewer cap), 8 (busy), 10 (`stream_unavailable`/no container).
|
||||
- `enable`, `disable`, `list`, `status` do **not** touch the idle clock — the
|
||||
same rule as `pointer.*`. A **connected viewer is activity**: about once a
|
||||
minute the broker asks the daemon for viewer counts and stamps `touch` when
|
||||
any is non-zero. That is the one new way the clock moves; it is what keeps a
|
||||
session the operator is watching on his phone from being reaped at three
|
||||
hours. An enabled stream with nobody watching runs **no** `grim` and keeps no
|
||||
session alive.
|
||||
- The session record gains `stream = {enabled, phrase, fps, viewers, port}`
|
||||
(or `null`). **Registry schema 3 → 4**; older records migrate to
|
||||
`stream: null` and are adopted, not refused.
|
||||
- Teardown order is v1's and it is load-bearing: `disable` the stream (close the
|
||||
listener, drop the route) **before** `hyprctl output remove`.
|
||||
|
||||
## 6. Restart behaviour
|
||||
|
||||
A broker restart does **not** invent listeners. If `hhstream-live` is still up,
|
||||
the broker asks it for the list and re-attaches them to the session records, so
|
||||
`status` and teardown still see them. If the daemon restarted too, the enabled
|
||||
records keep their phrases but the streams are off until re-enabled — an open
|
||||
port and a running capture are explicit acts, and the phrase is not a licence to
|
||||
capture without one.
|
||||
|
||||
## 7. What to build, in what order
|
||||
|
||||
| Stage | What | Size | Risk |
|
||||
| --- | --- | --- | --- |
|
||||
| 0 | Contract text: `docs/CONTRACT-sessions.md` → **sessions-v3** (the four verbs, `/run/hhstream/live.sock`, `hhstream-live`, the single port, the viewer-touch exception, schema 4, error names). | S | Freezing the wrong default. This plan is the review. |
|
||||
| 1 | `hhstream-live`: the HTTP server, the router, the phrase (wordlist + generator), one output, injected capture, **unit tests**. No broker. | M | A phone that will not paint `multipart/x-mixed-replace`; the index leaking phrases when made public. |
|
||||
| 2 | Broker + CLI: the record field, schema 4, the four verbs, teardown order, viewer heartbeat, integration test on `127.0.0.1`. | L | A second capture on re-enable; `disable` racing `output remove`; a heartbeat that keeps a session alive with zero viewers. |
|
||||
| 3 | Module: the unit, `/run/hhstream/live.sock`, `port` 9988, `bind` loopback, `fps` 5/cap 10, `enable` false, `openFirewall` false, `publicIndex` false. No host firewall edit here. | M | A second `RuntimeDirectory` on `/run/hhstream` deleting `control.sock`. |
|
||||
| 4 | Host pass: enable a real session, open the URL in the machine's own Chromium, confirm pixels change without a reload; write down what was on screen. | S | An empty container looking like a broken stream. Confirm the window is on `hh-<id>` first. |
|
||||
|
||||
Test layers are v1's: `tests/unit` for the HTTP/router/phrase with a fake
|
||||
capture (multipart framing, each route, wrong phrase → empty 404, rate limit,
|
||||
capture idle at zero viewers, "unknown output" ends the stream), `tests/sessions`
|
||||
for the verbs and the clock, one integration test that runs a real daemon and a
|
||||
real `hhstream-live` on loopback with `urllib` reading two JPEGs. VM checks stay
|
||||
one at a time; no browser in a VM check.
|
||||
|
||||
## 8. Decisions taken (2026-10-04)
|
||||
|
||||
1. **The root page is a form, never a list.** The phrase is a password; the
|
||||
index must not hand it out. (Was "loopback-only index".)
|
||||
2. **Phrase = four EFF-large words + a five-character base-36 tail (~77.5
|
||||
bits).** The tail is what the operator asked for in place of a fifth word.
|
||||
3. **Port 9988**, fixed and single, no range fallback.
|
||||
4. **Capture pauses at zero viewers** (v1's choice, kept).
|
||||
|
||||
**Stage 1 is built** (`src/hhstream_live/`, `tests/live/`, 51 unit tests): the
|
||||
router, the pages, the phrase and the publisher, runnable standalone via
|
||||
`hhstream-live serve --stream PHRASE=OUTPUT`. The broker verbs and
|
||||
`/run/hhstream/live.sock` are Stage 2.
|
||||
@@ -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 = {
|
||||
|
||||
@@ -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"]
|
||||
@@ -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"]
|
||||
@@ -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())
|
||||
@@ -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"]
|
||||
@@ -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"]
|
||||
@@ -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"]
|
||||
@@ -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
@@ -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()
|
||||
@@ -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)
|
||||
@@ -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]
|
||||
@@ -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
|
||||
@@ -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))
|
||||
@@ -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
|
||||
@@ -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}/"
|
||||
Reference in new issue
Block a user