#!/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())