Files
hyprland-headless-stream-pl…/tests/assert_stream.py
T
HermenixandClaude Opus 5 75a05cd72f tests: checks.{unit,vm-basic,vm-hyprland} + the harness behind them
Wires a `checks` output into the flake, one file per check under checks/,
all three asserting docs/CONTRACT.md rather than the implementation:

- unit: pytest over tests/unit/ in the build sandbox, against the
  nix/package.nix build. Refuses an empty suite -- pytest exits 0 when
  every test was skipped or deselected, so checks/lib/check_report.py
  parses the JUnit report and fails on zero collected or zero executed.
- vm-basic: nixosTest with captureCommand pointed at tests/fake_capture.py,
  which emits one fixed deterministic PNG. Because the image never changes,
  "two frames arrived and they are the same bytes" is an assertion about
  the framing rather than a coincidence.
- vm-hyprland: the same machine with no captureCommand override, so grim
  captures the real compositor. Deliberately impatient -- bounded timeouts,
  no retry loops, and a full diagnostics dump (compositor log, hyprctl
  monitors, both journals) before any failure propagates.

tests/assert_stream.py is a second, independent reader of the contract: it
shares no code with hhstream.client, so a framing bug present in both the
server's writer and the shipped client's reader still fails. The unit
suite's negative tests use a `rejects` fixture instead of
pytest.raises(Exception), which an unimplemented stub's
NotImplementedError would otherwise satisfy.

Three defects found in code this branch does not own, recorded in
README.dev.md rather than worked around:
- nix/module.nix has no config side, so neither unit exists and both VM
  checks fail at their first wait;
- services.hyprland-headless-stream.package is declared with no default,
  against docs/CONTRACT.md;
- src/hhstream/*.py is all stubs, so 66 of 70 unit tests fail.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017YXMoCNxzScTaKNr43GQNz
2026-09-28 05:25:37 +00:00

308 lines
12 KiB
Python

#!/usr/bin/env python3
"""Read a hhstream socket and assert it obeys docs/CONTRACT.md.
This is deliberately a *second, independent* implementation of the reader: it
shares no code with `hhstream.client`, so a bug that lives in both the server's
writer and the shipped client's reader still fails the test. Pure standard
library; it runs inside the test VM, where only python3 is guaranteed.
Every run prints what it saw before it decides, so a failure in CI is readable
without reproducing it.
"""
from __future__ import annotations
import argparse
import hashlib
import json
import re
import socket
import struct
import sys
import zlib
MAGIC = "HHS1"
FORMATS = {"image/png", "image/jpeg"}
PNG_SIGNATURE = b"\x89PNG\r\n\x1a\n"
# Contract: plain ASCII digits, no leading zeros, no `+`, no spaces.
LENGTH_RE = re.compile(rb"\A(?:0|[1-9][0-9]*)\Z")
class ContractError(Exception):
"""The stream violated docs/CONTRACT.md."""
# --------------------------------------------------------------------------
# wire reading
# --------------------------------------------------------------------------
def read_line(sock: socket.socket, limit: int = 4096) -> bytes:
"""Read up to and including the next 0x0A. Never over-reads past it."""
out = bytearray()
while True:
b = sock.recv(1)
if not b:
raise ContractError(
f"socket closed after {len(out)} bytes while reading a line: {bytes(out)!r}"
)
if b == b"\n":
return bytes(out)
out += b
if len(out) > limit:
raise ContractError(f"no newline within {limit} bytes: {bytes(out[:120])!r}...")
def read_exact(sock: socket.socket, n: int) -> bytes:
out = bytearray()
while len(out) < n:
part = sock.recv(min(65536, n - len(out)))
if not part:
raise ContractError(
f"truncated payload: wanted {n} bytes, socket closed after {len(out)}"
)
out += part
return bytes(out)
def read_hello(sock: socket.socket) -> dict:
line = read_line(sock)
try:
obj = json.loads(line.decode("utf-8"))
except (UnicodeDecodeError, json.JSONDecodeError) as exc:
raise ContractError(f"Hello is not UTF-8 JSON ({exc}): {line!r}") from exc
if not isinstance(obj, dict):
raise ContractError(f"Hello is not a JSON object: {line!r}")
if obj.get("magic") != MAGIC:
raise ContractError(f"Hello magic is {obj.get('magic')!r}, contract says {MAGIC!r}")
for key in ("width", "height", "fps"):
val = obj.get(key)
if not isinstance(val, int) or isinstance(val, bool):
raise ContractError(f"Hello {key} is {val!r}, expected an integer")
if val <= 0:
raise ContractError(
f"Hello {key} is {val}; the contract forbids a Hello with zero size"
)
if obj.get("format") not in FORMATS:
raise ContractError(
f"Hello format is {obj.get('format')!r}, expected one of {sorted(FORMATS)}"
)
return obj
def read_frame(sock: socket.socket) -> bytes:
prefix = read_line(sock)
if not LENGTH_RE.match(prefix):
raise ContractError(
f"malformed length prefix {prefix!r}: contract requires plain ASCII "
"digits with no leading zeros, sign or spaces"
)
length = int(prefix)
if length == 0:
raise ContractError("frame length is 0; a frame must carry a complete image")
return read_exact(sock, length)
# --------------------------------------------------------------------------
# PNG inspection
# --------------------------------------------------------------------------
def png_chunks(data: bytes):
off = len(PNG_SIGNATURE)
while off + 8 <= len(data):
(size,) = struct.unpack(">I", data[off : off + 4])
kind = data[off + 4 : off + 8]
body = data[off + 8 : off + 8 + size]
if len(body) != size:
raise ContractError(f"PNG chunk {kind!r} truncated: want {size}, got {len(body)}")
crc = data[off + 8 + size : off + 12 + size]
if len(crc) != 4:
raise ContractError(f"PNG chunk {kind!r} has no CRC")
want = struct.pack(">I", zlib.crc32(kind + body) & 0xFFFFFFFF)
if crc != want:
raise ContractError(f"PNG chunk {kind!r} CRC mismatch: {crc.hex()} != {want.hex()}")
yield kind, body
off += 12 + size
if kind == b"IEND":
return
raise ContractError("PNG ended without an IEND chunk")
def inspect_png(payload: bytes) -> dict:
"""Parse enough of a PNG to know its size and whether it carries a picture."""
if not payload.startswith(PNG_SIGNATURE):
raise ContractError(
f"payload is not a PNG: first 8 bytes are {payload[:8]!r}, "
f"expected {PNG_SIGNATURE!r}"
)
ihdr = None
idat = bytearray()
for kind, body in png_chunks(payload):
if kind == b"IHDR":
if ihdr is not None:
raise ContractError("PNG has more than one IHDR")
if len(body) != 13:
raise ContractError(f"IHDR is {len(body)} bytes, expected 13")
w, h, depth, colour, comp, filt, interlace = struct.unpack(">IIBBBBB", body)
ihdr = dict(
width=w, height=h, bit_depth=depth, colour_type=colour,
compression=comp, filter=filt, interlace=interlace,
)
elif kind == b"IDAT":
if ihdr is None:
raise ContractError("PNG has IDAT before IHDR")
idat += body
if ihdr is None:
raise ContractError("PNG has no IHDR chunk")
if not idat:
raise ContractError("PNG has no IDAT chunk: there is no image data")
try:
raw = zlib.decompress(bytes(idat))
except zlib.error as exc:
raise ContractError(f"PNG image data does not decompress: {exc}") from exc
info = dict(ihdr)
info["payload_bytes"] = len(payload)
info["raw_bytes"] = len(raw)
info["distinct_raw_bytes"] = len(set(raw))
info["nonzero_raw_bytes"] = len(raw) - raw.count(0)
return info
def blank_png_size(width: int, height: int, colour_type: int, bit_depth: int) -> int:
"""Smallest plausible encoding of an all-zero image of the same geometry.
Used as the floor for "bigger than a trivial blank image": a zero-filled
framebuffer, packed with the best compression available, cannot exceed this.
"""
channels = {0: 1, 2: 3, 3: 1, 4: 2, 6: 4}.get(colour_type, 3)
stride = 1 + (width * channels * bit_depth + 7) // 8
raw = b"\x00" * (stride * height)
body = zlib.compress(raw, 9)
# signature + IHDR (25) + IDAT header/crc (12) + IEND (12)
return len(PNG_SIGNATURE) + 25 + 12 + len(body) + 12
# --------------------------------------------------------------------------
# driver
# --------------------------------------------------------------------------
def build_parser() -> argparse.ArgumentParser:
p = argparse.ArgumentParser(description=__doc__)
p.add_argument("--socket", required=True, help="path of the hhstream socket")
p.add_argument("--frames", type=int, default=1, help="how many frames to read")
p.add_argument("--timeout", type=float, default=30.0,
help="per-recv socket timeout, seconds")
p.add_argument("--expect-width", type=int, help="assert Hello/IHDR width")
p.add_argument("--expect-height", type=int, help="assert Hello/IHDR height")
p.add_argument("--expect-fps", type=int, help="assert Hello fps")
p.add_argument("--expect-format", help="assert Hello format, e.g. image/png")
p.add_argument("--min-bytes", type=int, default=1,
help="every payload must be at least this many bytes")
p.add_argument("--require-png", action="store_true",
help="every payload must parse as a PNG whose IHDR matches the Hello")
p.add_argument("--identical-frames", action="store_true",
help="all payloads read must be byte-identical")
p.add_argument("--reject-blank", action="store_true",
help="reject a frame that decodes to an all-zero or single-valued "
"image, or that is no bigger than a best-case blank PNG")
return p
def run(args) -> None:
sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
sock.settimeout(args.timeout)
sock.connect(args.socket)
try:
hello = read_hello(sock)
print(f"hello: {json.dumps(hello, sort_keys=True)}", flush=True)
for key, got in (("width", "expect_width"), ("height", "expect_height"),
("fps", "expect_fps"), ("format", "expect_format")):
want = getattr(args, got)
if want is not None and hello[key] != want:
raise ContractError(f"Hello {key} is {hello[key]!r}, expected {want!r}")
if args.require_png and hello["format"] != "image/png":
raise ContractError(
f"--require-png but Hello advertises format {hello['format']!r}"
)
payloads: list[bytes] = []
for i in range(args.frames):
payload = read_frame(sock)
digest = hashlib.sha256(payload).hexdigest()[:16]
print(f"frame {i}: {len(payload)} bytes sha256:{digest}", flush=True)
if len(payload) < args.min_bytes:
raise ContractError(
f"frame {i} is {len(payload)} bytes, below the {args.min_bytes}-byte floor"
)
payloads.append(payload)
if args.require_png:
info = inspect_png(payload)
print(f"frame {i}: png {json.dumps(info, sort_keys=True)}", flush=True)
if (info["width"], info["height"]) != (hello["width"], hello["height"]):
raise ContractError(
f"frame {i} IHDR is {info['width']}x{info['height']} but the Hello "
f"announced {hello['width']}x{hello['height']}"
)
if args.reject_blank:
floor = blank_png_size(
info["width"], info["height"], info["colour_type"], info["bit_depth"]
)
print(f"frame {i}: blank-png floor is {floor} bytes", flush=True)
if info["nonzero_raw_bytes"] == 0:
raise ContractError(
f"frame {i} decodes to {info['raw_bytes']} zero bytes: "
"this is a zero-filled buffer, not a captured frame"
)
if info["distinct_raw_bytes"] < 2:
raise ContractError(
f"frame {i} decodes to a single repeated byte value "
f"({info['raw_bytes']} bytes): a blank image, not a capture"
)
if len(payload) <= floor:
raise ContractError(
f"frame {i} is {len(payload)} bytes, no bigger than a "
f"best-case blank {info['width']}x{info['height']} PNG "
f"({floor} bytes)"
)
if args.identical_frames and len(payloads) > 1:
first = payloads[0]
for i, payload in enumerate(payloads[1:], start=1):
if payload != first:
raise ContractError(
f"frame {i} differs from frame 0 ({len(payload)} vs {len(first)} "
"bytes) but the fake capture emits one fixed image"
)
print(f"all {len(payloads)} frames byte-identical", flush=True)
finally:
sock.close()
def main(argv: list[str] | None = None) -> int:
args = build_parser().parse_args(argv)
if args.frames < 1:
print("assert-stream: --frames must be at least 1", file=sys.stderr)
return 2
try:
run(args)
except ContractError as exc:
print(f"CONTRACT VIOLATION: {exc}", file=sys.stderr)
return 1
except (OSError, socket.timeout) as exc:
print(f"SOCKET ERROR on {args.socket}: {exc!r}", file=sys.stderr)
return 1
print("OK", flush=True)
return 0
if __name__ == "__main__":
sys.exit(main())