feat(live): one port, a router, and a phrase per session (stage 1)
The session-stream web app: a single HTTP listener (9988) that serves a page
per enabled session, keyed by a spoken phrase.
src/hhstream_live/phrase.py four EFF-large words + a 5-char base-36 tail
(~77.5 bits); the phrase is the password
src/hhstream_live/publisher.py one capture thread + one frame slot per
output, one slot/no queue, capture paused at
zero viewers
src/hhstream_live/server.py the router: /, /<phrase>/, /stream.mjpg,
/frame.jpg, /status.json; unknown phrase is
an empty 404, rate-limited
src/hhstream_live/pages.py the built-in dark pages (no CDN, no build)
src/hhstream_live/__main__.py hhstream-live serve|phrase, standalone
The root page is a form, never a list: the phrase is known only by whoever
enabled the stream. Tests: tests/live (51), all green with the full suite
(958). Not yet wired to the broker -- that is stage 2.
This commit is contained in:
1 parent
edbf15f259
commit
d770bcd298
17 files changed
+9330
-18
No files matched your search
@@ -65,11 +65,10 @@ GET /<phrase>/status.json {session, output, fps, viewers, last_frame_age_s}
|
|||||||
|
|
||||||
- The phrase is matched **case-insensitively** and tolerates a missing trailing
|
- The phrase is matched **case-insensitively** and tolerates a missing trailing
|
||||||
slash, because a person will type it by hand; it is stored lowercase.
|
slash, because a person will type it by hand; it is stored lowercase.
|
||||||
- **The index is loopback-only by default.** Over the LAN, `/` is a `404` unless
|
- **The root page is a form, never a list.** The phrase is the password to a
|
||||||
`sessions.stream.publicIndex = true`. It lists phrases, so serving it to the
|
stream and is known only by whoever enabled it, so `/` must not enumerate
|
||||||
network hands out every key at once; on the operator's own machine it is the
|
sessions or leak phrases: it is a box you type a phrase into, which forwards
|
||||||
convenient landing page. `/<phrase>/…` always works from whatever the bind
|
to `/<phrase>/`. `/<phrase>/…` always works from whatever the bind allows.
|
||||||
allows.
|
|
||||||
- The pages are **built-in** — one small HTML/CSS/JS string in the package, no
|
- 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
|
CDN, no framework, no extra Python dependency. "Webapp" here means a real
|
||||||
router and legible pages, not a build step.
|
router and legible pages, not a build step.
|
||||||
@@ -84,13 +83,14 @@ GET /<phrase>/status.json {session, output, fps, viewers, last_frame_age_s}
|
|||||||
Generated when the stream is **first enabled** for a session, and kept in the
|
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.
|
session record so it survives a broker restart and a re-enable.
|
||||||
|
|
||||||
- Shape: `<word>-<word>-<word>-<word>`, e.g. `amber-otter-lantern-harbor`.
|
- Shape: `<word>-<word>-<word>-<word>-<xxxxx>`, e.g.
|
||||||
|
`amber-otter-lantern-harbor-7k2qp`.
|
||||||
- Words come from a **vendored EFF large wordlist** (7776 words, ~70 KB, in the
|
- Words come from a **vendored EFF large wordlist** (7776 words, ~70 KB, in the
|
||||||
repo — no network at runtime, no dependency). Four words is
|
repo — no network at runtime, no dependency) and the tail is five characters
|
||||||
`4 · log2(7776) ≈ 51.6` bits, which is the number that matters: at a LAN's
|
of `[a-z0-9]`. Four words is `4 · log2(7776) ≈ 51.7` bits and the tail adds
|
||||||
request rate that is not brute-forceable, and it matches what the 128-bit
|
`5 · log2(36) ≈ 25.8`, for **≈ 77.5 bits** — comfortably past anything a LAN
|
||||||
token bought in practice (the token was only ever a bearer string in a URL).
|
request rate can enumerate, and the operator's stated shape ("5 with a random
|
||||||
Raise to five words with one constant if that is judged thin.
|
5 character string for the last word").
|
||||||
- `--phrase` on enable sets your own (checked against the shape); `disable`
|
- `--phrase` on enable sets your own (checked against the shape); `disable`
|
||||||
then `enable` **rotates** it. A rotation is one record write.
|
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
|
- The phrase is the only credential. It is in the URL, in cleartext on the LAN
|
||||||
@@ -160,11 +160,16 @@ for the verbs and the clock, one integration test that runs a real daemon and a
|
|||||||
real `hhstream-live` on loopback with `urllib` reading two JPEGs. VM checks stay
|
real `hhstream-live` on loopback with `urllib` reading two JPEGs. VM checks stay
|
||||||
one at a time; no browser in a VM check.
|
one at a time; no browser in a VM check.
|
||||||
|
|
||||||
## 8. Open questions to answer before Stage 1
|
## 8. Decisions taken (2026-10-04)
|
||||||
|
|
||||||
1. **Public index.** Loopback-only by default — agreed? (It lists phrases.)
|
1. **The root page is a form, never a list.** The phrase is a password; the
|
||||||
2. **Phrase length.** Four EFF-large words (~51.6 bits). Five if you want more
|
index must not hand it out. (Was "loopback-only index".)
|
||||||
head-room at the cost of typing.
|
2. **Phrase = four EFF-large words + a five-character base-36 tail (~77.5
|
||||||
3. **Port 9988.** Fixed, single, no range fallback. Confirm the number.
|
bits).** The tail is what the operator asked for in place of a fifth word.
|
||||||
4. **Capture at zero viewers.** Paused (v1's choice, kept here) versus always-on
|
3. **Port 9988**, fixed and single, no range fallback.
|
||||||
while enabled. Paused is cheaper and the reason the idle rule is safe.
|
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.keymap"
|
||||||
"hhstream_pointer._protocol.wlr_virtual_pointer_unstable_v1"
|
"hhstream_pointer._protocol.wlr_virtual_pointer_unstable_v1"
|
||||||
"hhstream_pointer._protocol.virtual_keyboard_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 = {
|
meta = {
|
||||||
|
|||||||
@@ -27,6 +27,16 @@ hhstreamd = "hhstreamd.__main__:main"
|
|||||||
# The pointer driver. Its own process because a Wayland client needs its own
|
# The pointer driver. Its own process because a Wayland client needs its own
|
||||||
# connection, and a blocked one must not stall the broker.
|
# connection, and a blocked one must not stall the broker.
|
||||||
hhstream-pointer = "hhstream_pointer.__main__:main"
|
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]
|
[tool.setuptools.packages.find]
|
||||||
where = ["src"]
|
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