Merge origin/main into feat/keyboard-input: keep both the stream and the

keyboard sides

origin/main brought the session live-stream feature (stage 1): the
`hhstream_live` router, its phrase generator and wordlist, the
`sessions.stream.*` module options with their loopback-vs-openFirewall
assertion and the one firewall port, the `vm-stream-firewall` check, and
`tests/live/`. This branch adds keyboard input: the `key`/`type` ops, the
uploaded XKB keymap, `sessions.keyboard.{layout,model,variant,options}`
and the four `--xkb-*` flags on the driver unit, `vm-keyboard` and
`vm-keyboard-de`, and their docs.

The two features are independent, so every conflict wanted both sides.
Four files, resolved as follows.

checks/default.nix -- both the header list and the attribute set take all
three new checks: `vm-keyboard`, `vm-keyboard-de` (the same file with
`keyboardLayout = "de"`, because the layout reaches the keymap only
through the driver unit's argv) and `vm-stream-firewall`, which stays a
non-`sessionArgs` consumer with main's comment saying why. Neither side's
check list is reduced; the flake now exposes ten.

nix/package.nix -- one `pythonImportsCheck` list with both sides' entries:
`hhstream_pointer.keymap` and the vendored
`virtual_keyboard_unstable_v1` from here, `hhstream_live.server` from
main. The surrounding hunks were not in conflict, so the branch's
xkbcommon dependency and main's wordlist `postFixup` both survive, and
both ran in this merge's `checks.unit` build (`wordlist ok: 7772 words`).

nix/module.nix -- the sole conflict was textual: both sides open a new
sub-option block immediately after `sessions.pointer`. Both blocks are
kept, `keyboard` then `stream`, each with its own closing. Everything
else in the file merged cleanly, so `loopbackBinds`, the
openFirewall-on-loopback assertion and
`networking.firewall.allowedTCPPorts` are present alongside the driver
unit's `--xkb-layout`/`--xkb-model`/`--xkb-variant`/`--xkb-options`.

README.dev.md -- the `checks/` layout listing keeps both entries in the
file's existing order, `vm-keyboard.nix` then `vm-stream-firewall.nix`.

Verified: `nix flake check --no-build` evaluates every output green, and
`nix build .#checks.x86_64-linux.unit` passes -- 977 passed, 2 skipped,
0 failed, over both sides' suites. The VM checks were not run (they boot
a software-rendered compositor and must run one at a time).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PjpHyir6hxyjdw2o1RwQmn
This commit is contained in:
HermenixandClaude Opus 5 committed 2026-10-11 02:57:55 +00:00
commit 5f94833a76
26 files changed
+10544 -13

No files matched your search

+86
View File
@@ -0,0 +1,86 @@
"""Fixtures for the session-stream web app suite.
Everything is standard library and everything is in-process: a real
`LiveServer` on a loopback ephemeral port, fed by a stub capture, with plain
`http.client` for the requests. No compositor, no `grim`, no broker.
The doubles (`StubCapture`, `read_parts`, `PHRASE`) live in `live_helpers.py`, not
here, so the tests import them by a plain module name -- the same shape as
`tests/unit`.
"""
from __future__ import annotations
import contextlib
import http.client
import pathlib
import sys
import pytest
_HERE = pathlib.Path(__file__).resolve().parent
_SRC = _HERE.parents[1] / "src"
for _path in (str(_HERE), str(_SRC)):
if _path not in sys.path:
sys.path.insert(0, _path)
from fake_jpeg import jpeg_bytes # noqa: E402
from live_helpers import PHRASE, StubCapture # noqa: E402
from hhstream_live.publisher import StreamRegistry, StreamSpec # noqa: E402
from hhstream_live.server import LiveServer, RateLimiter # noqa: E402
@pytest.fixture
def jpg():
return jpeg_bytes
@pytest.fixture
def registry():
reg = StreamRegistry()
yield reg
reg.stop_all()
@pytest.fixture
def serve(registry):
"""`with serve(phrase=..., capture=..., fps=...) as (server, capture)`."""
servers: list[LiveServer] = []
@contextlib.contextmanager
def _serve(*, phrase: str = PHRASE, capture: StubCapture | None = None,
fps: int = 5, label: str = "demo", limit: int = 30):
capture = capture or StubCapture()
spec = StreamSpec(phrase=phrase, output="hh-demo", fps=fps, session="demo",
label=label)
registry.add(spec, capture)
server = LiveServer(registry, host="127.0.0.1", port=0,
limiter=RateLimiter(limit=limit))
servers.append(server)
server.start()
assert server.ready.wait(5)
try:
yield server, capture
finally:
server.stop()
yield _serve
for server in servers:
with contextlib.suppress(Exception):
server.stop()
@pytest.fixture
def http_conn():
"""Open an HTTP connection to a running server; closed at teardown."""
connections: list[http.client.HTTPConnection] = []
def _connect(server: LiveServer, timeout: float = 10.0) -> http.client.HTTPConnection:
conn = http.client.HTTPConnection("127.0.0.1", server.port, timeout=timeout)
connections.append(conn)
return conn
yield _connect
for conn in connections:
with contextlib.suppress(Exception):
conn.close()
+31
View File
@@ -0,0 +1,31 @@
"""A tiny real JPEG, for tests that need decodable image bytes.
The frame server's tests use a fake that writes a PNG (zlib is in the standard
library). MJPEG needs *JPEG* parts, and there is no JPEG encoder in the stdlib,
so the smallest honest thing is one real 1x1 JPEG embedded as base64 and reused.
`jpeg_bytes(marker)` rewrites one *quantisation-table* byte, so two frames differ
byte-for-byte (a test can prove "a new frame arrived") while the image stays
valid: the EOI marker, the headers and the scan data are untouched.
"""
from __future__ import annotations
import base64
#: A 1x1 JPEG. Real enough that `hhstream.capture.image_size` reports (1, 1).
_ONE_PIXEL = (
"/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRof"
"Hh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/wAALCAABAAEBAREA/8QAFAAB"
"AAAAAAAAAAAAAAAAAAAACf/EABQQAQAAAAAAAAAAAAAAAAAAAAD/2gAIAQEAAD8AVN//2Q=="
)
#: The start of the quantisation table: `FFDB`, length `0043`, precision/id `00`.
_DQT = b"\xff\xdb\x00C\x00"
def jpeg_bytes(marker: int = 0) -> bytes:
"""The 1x1 JPEG with one table byte varied by `marker` (0..249)."""
data = bytearray(base64.b64decode(_ONE_PIXEL))
start = data.index(_DQT) + len(_DQT)
data[start + 63] = (marker % 250) + 1 # a nonzero quantiser keeps it decodable
return bytes(data)
+92
View File
@@ -0,0 +1,92 @@
"""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.
`fail_first` is a capture that is broken from the start (a cold start that
never works); `fail_after` is one that works and then stops -- the output
was removed while someone was watching, which is grim's "unknown output" on
every grab from then on.
"""
def __init__(self, frames=None, fail_first: int = 0, delay: float = 0.0,
fail_after: int | None = None):
self.frames = list(frames) if frames else [jpeg_bytes(i) for i in range(1, 50)]
self.fail_first = fail_first
self.fail_after = fail_after
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})")
if self.fail_after is not None and call > self.fail_after:
raise RuntimeError(f"stub capture: unknown output (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]
+125
View File
@@ -0,0 +1,125 @@
"""The command line: it aims a capture at an output, and it can mint a phrase."""
from __future__ import annotations
import io
import os
import pathlib
import re
import signal
import subprocess
import sys
import time
from contextlib import redirect_stdout
import pytest
from hhstream_live.__main__ import (DEFAULT_CAPTURE, capture_argv, main, parse_args,
parse_stream)
#: What `hhstream-live phrase` must print: four alphabetic words and a tail.
PHRASE_SHAPE = re.compile(r"^[a-z]+(?:-[a-z]+){3}-[a-z0-9]{5}$")
_SRC = pathlib.Path(__file__).resolve().parents[2] / "src"
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()
# Not just `count("-") == 4`: a hyphenated word on the list would satisfy
# the count with five words and four hyphens in the wrong places.
assert PHRASE_SHAPE.match(printed), printed
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
# ---- the default subcommand, and shutdown ----------------------------------
def test_a_bare_command_line_means_serve():
"""`hhstream-live` with no subcommand is `hhstream-live serve`.
The serve options live on the `serve` subparser, so the namespace has to be
the subparser's; reading `capture_command` off the top-level one is the
`AttributeError` this guards.
"""
args = parse_args([])
assert args.command == "serve"
assert args.capture_command is None
assert args.port and args.bind and args.stream == []
assert args.log_level == "info"
def test_serve_options_work_without_naming_the_subcommand():
args = parse_args(["--port", "0", "--bind", "0.0.0.0"])
assert (args.command, args.port, args.bind) == ("serve", 0, "0.0.0.0")
def test_a_global_option_survives_the_subcommand():
"""`--log-level` is on both parsers; the subparser must not reset it."""
assert parse_args(["--log-level", "debug"]).log_level == "debug"
assert parse_args(["--log-level", "debug", "serve"]).log_level == "debug"
assert parse_args(["--log-level", "debug", "phrase"]).log_level == "debug"
def test_a_bare_run_serves_and_sigterm_stops_it_cleanly():
"""The whole path: no subcommand, then the signal a service is stopped with.
`SIGTERM`'s default action kills the process outright, so without a handler
`server.stop()` never runs and the exit status is a signal, not a 0.
"""
env = dict(os.environ, PYTHONPATH=os.pathsep.join(
[str(_SRC), os.environ.get("PYTHONPATH", "")]).rstrip(os.pathsep))
proc = subprocess.Popen(
[sys.executable, "-m", "hhstream_live", "--port", "0"],
stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, env=env,
)
try:
deadline = time.monotonic() + 20
banner = ""
while "landing page:" not in banner and time.monotonic() < deadline:
line = proc.stderr.readline()
if not line:
break
banner += line
assert "landing page:" in banner, banner
assert "bound to 127.0.0.1:" in banner, banner
proc.send_signal(signal.SIGTERM)
out, err = proc.communicate(timeout=20)
except BaseException:
proc.kill()
proc.communicate()
raise
assert proc.returncode == 0, (proc.returncode, banner, err)
assert "Traceback" not in err, err
+105
View File
@@ -0,0 +1,105 @@
"""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}$")
WORD = re.compile(r"^[a-z]+$")
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_minus_its_hyphenated_entries():
words = phrase.words()
# The file is the EFF large list, 7776 lines; four of them are hyphenated
# and the loader drops them, because a hyphen is the phrase's separator.
assert len(words) == 7772
assert len(set(words)) == 7772
assert "abacus" in words
assert "drop-down" not in words
def test_every_loaded_word_is_plain_lowercase_letters():
"""Not a sampling test: one hyphenated word makes a six-token phrase.
`test_generated_phrase_has_the_agreed_shape` would only catch that by luck
-- four draws out of 7776 hit a hyphenated entry about 0.2% of the time --
so the property is asserted over the whole list instead.
"""
assert all(WORD.match(word) for word in phrase.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-Harbor-7K2QP") == (
"amber-otter-lantern-harbor-7k2qp"
)
def test_validate_accepts_everything_generate_produces():
for _ in range(50):
generated = phrase.generate()
assert phrase.validate(generated) == generated
@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)
@pytest.mark.parametrize("weak", [
"a-b-c", # the reviewer's example: three letters
"ab-cd-ef-gh-12345", # four "words" of two letters
"amber-otter-lantern-7k2qp", # three words, not four
"amber-otter-lantern-harbor", # four words, no tail
"amber-otter-lantern-harbor-7k2", # a three-character tail
"amber-otter-lantern-harbor-7k2qpz", # a six-character tail
"amber-otter-lantern-harbor-hill-7k2qp", # five words
"amber-0tter-lantern-harbor-7k2qp", # a digit inside a word
])
def test_validate_rejects_a_phrase_weaker_than_the_generated_shape(weak):
"""`--phrase` is a password for a LAN-facing stream, not a label.
Anything `validate` accepts is something an operator can set, so the floor
has to be the shape `generate` produces -- otherwise `a-b-c` opens a stream.
"""
with pytest.raises(ValueError):
phrase.validate(weak)
def test_validate_rejects_an_overlong_phrase():
with pytest.raises(ValueError):
phrase.validate("-".join(["averyverylongword"] * 8))
+184
View File
@@ -0,0 +1,184 @@
"""The publisher: no capture while unwatched, one slot, and giving up when dead."""
from __future__ import annotations
import logging
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()
def test_a_capture_that_dies_after_a_good_frame_also_gives_up():
"""The cap counts failures *in a row*, not failures before the first frame.
An output removed while someone is watching fails every grab from then on.
A give-up rule that only applied to a cold start would leave this stream
retrying twice a second for as long as the viewer held the page open --
exactly the busy loop on a dead session the cap exists to stop.
"""
capture = StubCapture(fail_after=1) # one good frame, then the output is gone
stream = make_stream(capture, fps=10)
stream.start()
try:
stream.add_viewer() # and the viewer stays attached for the whole test
frame, seq = stream.wait_frame(0, timeout=5)
assert frame is not None and seq >= 1
# Poll through the viewer's own wait, so a `wait_frame` that hangs is a
# failure here rather than a test that quietly waits for the deadline.
deadline = time.monotonic() + 15
while not stream.stopped and time.monotonic() < deadline:
assert stream.wait_frame(seq, timeout=1.0) == (None, seq)
assert stream.stopped, "a dead output must stop the stream, frame or no frame"
# And the viewer in the loop is released at once rather than on timeout.
started = time.monotonic()
assert stream.wait_frame(seq, timeout=10.0) == (None, seq)
assert time.monotonic() - started < 1.0
assert capture.calls >= FAILURE_LIMIT
finally:
stream.stop()
def test_giving_up_never_writes_the_phrase_to_the_log(caplog):
"""A log line is the easiest place for the stream's one credential to leak.
faulthandler and `threading.excepthook` print thread names, so the capture
thread is checked here too.
"""
capture = StubCapture(fail_first=10_000)
stream = make_stream(capture, fps=10)
with caplog.at_level(logging.DEBUG, logger="hhstream.live"):
stream.start()
thread_name = stream._thread.name
try:
stream.add_viewer()
assert stream.wait_frame(0, timeout=15) == (None, 0)
assert stream.stopped
finally:
stream.stop()
messages = [record.getMessage() for record in caplog.records]
assert messages, "the give-up must be logged at all"
assert any("hh-demo" in message for message in messages)
for message in messages:
assert PHRASE not in message, message
assert PHRASE not in thread_name and "hh-demo" in thread_name
# ---- 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
+269
View File
@@ -0,0 +1,269 @@
"""The web app's obligations: the router, the pages, and MJPEG over one port."""
from __future__ import annotations
import logging
import socket
import threading
import time
from live_helpers import PHRASE, StubCapture, read_parts
from hhstream_live.server import BOUNDARY, HEADER_TIMEOUT_S, LiveServer, RateLimiter
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}"
)
# The stream has no length and is not chunked, so the only thing that
# can delimit it is the close -- which an intermediary is only entitled
# to expect if the response says so.
assert resp.getheader("Connection") == "close"
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_a_silent_client_does_not_pin_a_handler_thread(serve):
"""A connection that never sends a request line must not hold a thread.
The socket timeout is the only thing that ends it; without one the handler
sits in `readline` for the life of the process.
"""
assert HEADER_TIMEOUT_S <= 30 # a cap that never fires is not a cap
with serve() as (server, _):
before = threading.active_count()
sock = socket.create_connection(("127.0.0.1", server.port), timeout=5)
try:
time.sleep(0.2)
assert threading.active_count() > before # a handler is waiting on us
sock.settimeout(HEADER_TIMEOUT_S + 10)
started = time.monotonic()
# The server closes on timeout, which arrives here as EOF.
assert sock.recv(4096) == b""
waited = time.monotonic() - started
assert waited <= HEADER_TIMEOUT_S + 5, waited
finally:
sock.close()
def test_a_viewer_that_drops_mid_stream_releases_its_slot(serve, http_conn):
"""A dropped viewer must bring `viewers` back to 0, or grim keeps running."""
import json
with serve(fps=10) as (server, _):
sock = socket.create_connection(("127.0.0.1", server.port), timeout=10)
sock.sendall(f"GET /{PHRASE}/stream.mjpg HTTP/1.1\r\n"
f"Host: 127.0.0.1\r\n\r\n".encode("ascii"))
assert sock.recv(4096) # headers, and at least the start of a part
def viewers() -> int:
return json.loads(get(http_conn(server), f"/{PHRASE}/status.json")[2])["viewers"]
# The headers can reach us a moment before the handler counts itself in.
deadline = time.monotonic() + 10
while viewers() == 0 and time.monotonic() < deadline:
time.sleep(0.05)
assert viewers() == 1
sock.close() # the phone walked out of range
deadline = time.monotonic() + 10
while viewers() and time.monotonic() < deadline:
time.sleep(0.1)
assert viewers() == 0
def test_the_access_log_never_carries_the_phrase(serve, http_conn, caplog):
"""Debug logging is on in development, and the request line is the phrase."""
with caplog.at_level(logging.DEBUG, logger="hhstream.live"):
with serve() as (server, _):
assert get(http_conn(server), f"/{PHRASE}/status.json")[0] == 200
assert get(http_conn(server), f"/{WRONG}/")[0] == 404
messages = [record.getMessage() for record in caplog.records]
assert messages, "something must be logged, or this proves nothing"
for message in messages:
assert PHRASE not in message, message
assert WRONG not in message, message
def test_the_server_says_when_it_is_bound_to_every_interface(registry):
"""`url_for` must print something dialable; the bind line tells the truth."""
loopback = LiveServer(registry, host="127.0.0.1", port=9988)
assert loopback.describe_bind() == "bound to 127.0.0.1:9988"
assert not loopback.binds_everywhere
everywhere = LiveServer(registry, host="0.0.0.0", port=9988)
assert everywhere.binds_everywhere
assert everywhere.address == "127.0.0.1" # still dialable
described = everywhere.describe_bind()
assert "0.0.0.0:9988" in described and "all interfaces" in described
def test_the_rate_limiter_counts_each_client_separately_and_forgets_them():
"""One noisy client must not spend another's budget, and must not be kept.
`_hits` is keyed by client address, so a table that only grew would be a
memory leak any LAN host could drive.
"""
now = [0.0]
limiter = RateLimiter(limit=2, window=60.0, clock=lambda: now[0])
assert limiter.allow("10.0.0.1")
assert limiter.allow("10.0.0.1")
assert not limiter.allow("10.0.0.1") # that client is out of budget
assert limiter.allow("10.0.0.2") # this one is not
assert limiter.tracked == 2
now[0] += 61.0 # both windows have passed
assert limiter.allow("10.0.0.1")
assert limiter.tracked == 1, "a client that went quiet is not kept"
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}/"
+38 -13
View File
@@ -75,12 +75,18 @@ def test_a_failure_after_a_good_frame_keeps_the_known_size():
def test_env_is_overlaid_on_our_own_environment():
argv = [sys.executable, "-c",
"import os,sys;sys.stdout.write(os.environ['WAYLAND_DISPLAY']+':'+"
"('PATH' in os.environ and 'haspath' or 'nopath'))"]
argv = [
sys.executable,
"-c",
"import os,sys;sys.stdout.write(os.environ['WAYLAND_DISPLAY']+':'+"
+ "('PATH' in os.environ and 'haspath' or 'nopath'))",
]
before = os.environ.get("WAYLAND_DISPLAY")
capture = CommandCapture(argv, env={"WAYLAND_DISPLAY": "wayland-9"})
assert capture.grab() == b"wayland-9:haspath"
assert "WAYLAND_DISPLAY" not in os.environ, "our own environment was mutated"
assert os.environ.get("WAYLAND_DISPLAY") == before, (
"our own environment was mutated"
)
def test_empty_argv_and_bad_timeout_are_rejected_up_front():
@@ -91,8 +97,10 @@ def test_empty_argv_and_bad_timeout_are_rejected_up_front():
def test_the_helpers_stdin_is_closed_so_it_cannot_steal_ours():
code = ("import sys;"
"sys.stdout.buffer.write(b'EMPTY' if not sys.stdin.read() else b'DATA')")
code = (
"import sys;"
"sys.stdout.buffer.write(b'EMPTY' if not sys.stdin.read() else b'DATA')"
)
assert CommandCapture([sys.executable, "-c", code]).grab() == b"EMPTY"
@@ -102,15 +110,32 @@ def test_image_size_reads_png_headers(width, height):
def test_image_size_reads_a_jpeg_sof_header():
jpeg = (b"\xff\xd8"
+ b"\xff\xe0" + (16).to_bytes(2, "big") + b"JFIF\x00" + b"\x00" * 9
+ b"\xff\xc0" + (17).to_bytes(2, "big") + b"\x08"
+ (720).to_bytes(2, "big") + (1280).to_bytes(2, "big")
+ b"\x03" + b"\x00" * 9)
jpeg = (
b"\xff\xd8"
+ b"\xff\xe0"
+ (16).to_bytes(2, "big")
+ b"JFIF\x00"
+ b"\x00" * 9
+ b"\xff\xc0"
+ (17).to_bytes(2, "big")
+ b"\x08"
+ (720).to_bytes(2, "big")
+ (1280).to_bytes(2, "big")
+ b"\x03"
+ b"\x00" * 9
)
assert image_size(jpeg) == (1280, 720)
@pytest.mark.parametrize("data", [b"", b"not an image", b"\x89PNG\r\n\x1a\n",
b"\xff\xd8", b"\xff\xd8\xff\xc0\x00\x11"])
@pytest.mark.parametrize(
"data",
[
b"",
b"not an image",
b"\x89PNG\r\n\x1a\n",
b"\xff\xd8",
b"\xff\xd8\xff\xc0\x00\x11",
],
)
def test_image_size_returns_none_when_it_cannot_tell(data):
assert image_size(data) is None