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
308 lines
12 KiB
Python
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())
|