diff --git a/src/hhstream/capture.py b/src/hhstream/capture.py index ebd8b71..e100cd7 100644 --- a/src/hhstream/capture.py +++ b/src/hhstream/capture.py @@ -7,9 +7,24 @@ produces frames in a unit test. from __future__ import annotations +import os +import struct import subprocess from typing import Protocol +#: MIME types the contract allows, and the pixel-size probe for each. +_SOF_MARKERS = frozenset( + m for m in range(0xC0, 0xD0) if m not in (0xC4, 0xC8, 0xCC) +) + + +class CaptureError(RuntimeError): + """One capture attempt failed; the server catches this and keeps serving. + + Covers every way the helper command can let us down: it is missing, it + exits non-zero, it times out, or it writes nothing. + """ + class CaptureBackend(Protocol): def grab(self) -> bytes: @@ -22,17 +37,137 @@ class CaptureBackend(Protocol): class CommandCapture: - """Runs a helper that writes one frame to stdout (default: grim).""" + """Runs a helper that writes one frame to stdout (default: grim). + + `env` is overlaid on the server's own environment (that is how the session + variables -- `WAYLAND_DISPLAY`, `XDG_RUNTIME_DIR` -- reach the helper + without having to restate `PATH`). The helper's stdout is the frame and its + stderr is captured, so a chatty or failing helper never writes to the + server's own stdout/stderr; the message ends up in the raised + `CaptureError` instead. + """ def __init__(self, argv: list[str], env: dict[str, str] | None = None, timeout: float = 5.0) -> None: - raise NotImplementedError + argv = list(argv) + if not argv: + raise ValueError("capture command must not be empty") + if timeout is not None and timeout <= 0: + raise ValueError(f"capture timeout must be positive, got {timeout!r}") + self.argv = argv + self.env = dict(env) if env is not None else None + self.timeout = timeout + self._size: tuple[int, int] | None = None def grab(self) -> bytes: - raise NotImplementedError + """Run the helper once and return the bytes it wrote to stdout.""" + child_env = None + if self.env is not None: + child_env = dict(os.environ) + child_env.update(self.env) + try: + proc = subprocess.run( + self.argv, + stdin=subprocess.DEVNULL, + stdout=subprocess.PIPE, + stderr=subprocess.PIPE, + env=child_env, + timeout=self.timeout, + check=False, + ) + except subprocess.TimeoutExpired as exc: + raise CaptureError( + f"capture command {self.argv!r} timed out after {self.timeout}s" + ) from exc + except OSError as exc: + raise CaptureError( + f"capture command {self.argv!r} could not be run: {exc}" + ) from exc + if proc.returncode != 0: + raise CaptureError( + f"capture command {self.argv!r} exited {proc.returncode}: " + f"{_tail(proc.stderr)}" + ) + if not proc.stdout: + raise CaptureError( + f"capture command {self.argv!r} produced no output: " + f"{_tail(proc.stderr)}" + ) + measured = image_size(proc.stdout) + if measured is not None: + self._size = measured + return proc.stdout def size(self) -> tuple[int, int]: - raise NotImplementedError + """Pixel size of the captured output, for the Hello. + + Measured from the frame itself (the PNG/JPEG header), so no compositor + query is needed and an injected fake command works the same way. The + first successful measurement is remembered; `grab` refreshes it, so + after a frame has been captured this costs nothing. + """ + if self._size is None: + self.grab() + if self._size is None: + raise CaptureError( + f"cannot determine pixel size from the output of {self.argv!r} " + "(not a PNG or JPEG?)" + ) + return self._size -__all__ = ["CaptureBackend", "CommandCapture", "subprocess"] \ No newline at end of file +def image_size(data: bytes) -> tuple[int, int] | None: + """Pixel size of a PNG or JPEG frame, or None if it cannot be read.""" + return _png_size(data) or _jpeg_size(data) + + +def _png_size(data: bytes) -> tuple[int, int] | None: + if not data.startswith(b"\x89PNG\r\n\x1a\n") or len(data) < 24: + return None + if data[12:16] != b"IHDR": + return None + width, height = struct.unpack(">II", data[16:24]) + return (width, height) if width and height else None + + +def _jpeg_size(data: bytes) -> tuple[int, int] | None: + if not data.startswith(b"\xff\xd8"): + return None + i, n = 2, len(data) + while i + 1 < n: + if data[i] != 0xFF: + i += 1 # resync on the next marker + continue + marker = data[i + 1] + if marker == 0xFF: + i += 1 # fill byte + continue + if marker in (0x01, 0xD8, 0xD9) or 0xD0 <= marker <= 0xD7: + i += 2 # standalone marker, no payload + continue + if i + 4 > n: + return None + seglen = int.from_bytes(data[i + 2:i + 4], "big") + if seglen < 2: + return None + if marker in _SOF_MARKERS: + if i + 9 > n: + return None + height = int.from_bytes(data[i + 5:i + 7], "big") + width = int.from_bytes(data[i + 7:i + 9], "big") + return (width, height) if width and height else None + i += 2 + seglen + return None + + +def _tail(stderr: bytes | None, limit: int = 400) -> str: + if not stderr: + return "no stderr" + text = stderr.decode("utf-8", "replace").strip() + if len(text) > limit: + text = "..." + text[-limit:] + return text or "no stderr" + + +__all__ = ["CaptureBackend", "CommandCapture", "CaptureError", "image_size", + "subprocess"] diff --git a/src/hhstream/client.py b/src/hhstream/client.py index 136d85a..7c6b28e 100644 --- a/src/hhstream/client.py +++ b/src/hhstream/client.py @@ -3,22 +3,119 @@ from __future__ import annotations import argparse +import json +import pathlib +import socket +import sys from typing import Iterable +from . import protocol + DEFAULT_SOCKET = "/run/hyprland-headless-stream/stream.sock" def fetch(socket_path: str, count: int = 1, timeout: float = 10.0) -> list[bytes]: - """Connect and return up to `count` frame payloads (Hello consumed).""" - raise NotImplementedError + """Connect and return up to `count` frame payloads (Hello consumed). + + `timeout` bounds each socket operation, not the whole call: at the + advertised fps a frame is expected well inside it. Fewer than `count` + frames come back if the server closes the connection first. + """ + return read_stream(socket_path, count, timeout)[1] + + +def read_stream(socket_path: str, count: int = 1, + timeout: float = 10.0) -> tuple[dict, list[bytes]]: + """Like `fetch`, but also returns the parsed Hello.""" + conn = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) + conn.settimeout(timeout) + try: + conn.connect(socket_path) + with conn.makefile("rb") as stream: + hello = protocol.read_hello(stream) + frames: list[bytes] = [] + while len(frames) < count: + payload = protocol.read_frame(stream) + if payload is None: + break # server closed; return what we got + frames.append(payload) + return hello, frames + finally: + conn.close() def build_parser() -> argparse.ArgumentParser: - raise NotImplementedError + parser = argparse.ArgumentParser( + prog="hhstream-client", + description="Read frames from a hyprland-headless-stream socket.", + ) + parser.add_argument( + "--socket", default=DEFAULT_SOCKET, metavar="PATH", + help="socket to read from (default: %(default)s)", + ) + parser.add_argument( + "--count", type=int, default=1, metavar="N", + help="how many frames to read (default: %(default)s)", + ) + parser.add_argument( + "--out", metavar="PATH", + help="write each frame here, suffixed when --count > 1; " + "'-' writes the payloads to stdout", + ) + parser.add_argument( + "--timeout", type=float, default=10.0, metavar="SECONDS", + help="per-read socket timeout (default: %(default)s)", + ) + return parser def main(argv: Iterable[str] | None = None) -> int: - raise NotImplementedError + args = build_parser().parse_args(argv) + if args.count < 0: + print("--count must not be negative", file=sys.stderr) + return 2 + to_stdout = args.out == "-" + # Keep stdout for the payloads when they are going there. + report = sys.stderr if to_stdout else sys.stdout + + try: + hello, frames = read_stream(args.socket, args.count, args.timeout) + except (OSError, EOFError, ValueError) as exc: + print(f"hhstream-client: {exc}", file=sys.stderr) + return 1 + + print(json.dumps(hello, separators=(",", ":")), file=report) + for index, payload in enumerate(frames, start=1): + if to_stdout: + sys.stdout.buffer.write(payload) + sys.stdout.buffer.flush() + print(f"frame {index}: {len(payload)} bytes", file=report) + elif args.out: + target = output_path(args.out, index, args.count) + target.write_bytes(payload) + print(f"frame {index}: {len(payload)} bytes -> {target}", file=report) + else: + print(f"frame {index}: {len(payload)} bytes", file=report) + report.flush() + + if len(frames) < args.count: + print( + f"hhstream-client: wanted {args.count} frames, got {len(frames)} " + "(server closed the connection)", + file=sys.stderr, + ) + return 1 + return 0 -__all__ = ["fetch", "DEFAULT_SOCKET", "build_parser", "main"] \ No newline at end of file +def output_path(out: str, index: int, count: int) -> pathlib.Path: + """`frame.png` -> itself for one frame, `frame-1.png`, `frame-2.png` beyond.""" + path = pathlib.Path(out) + if count <= 1: + return path + width = len(str(count)) + return path.with_name(f"{path.stem}-{index:0{width}d}{path.suffix}") + + +__all__ = ["fetch", "read_stream", "DEFAULT_SOCKET", "build_parser", "main", + "output_path"] diff --git a/src/hhstream/protocol.py b/src/hhstream/protocol.py index 0bef7c3..af2941b 100644 --- a/src/hhstream/protocol.py +++ b/src/hhstream/protocol.py @@ -10,23 +10,77 @@ from typing import BinaryIO from . import MAGIC +#: Longest length prefix we will read before giving up. The contract allows +#: plain ASCII digits with no bound; 20 digits is past 2**63 and keeps a garbage +#: stream from making us read forever. +MAX_LENGTH_DIGITS = 20 + +#: Longest Hello line we will read before giving up, for the same reason. +MAX_HELLO_BYTES = 65536 + +_READ_CHUNK = 1 << 20 + def hello(width: int, height: int, fmt: str, fps: int) -> bytes: """The one-line JSON Hello, `\\n`-terminated. `fmt` is a MIME type ("image/png" / "image/jpeg"). """ - raise NotImplementedError + for name, value in (("width", width), ("height", height), ("fps", fps)): + if isinstance(value, bool) or not isinstance(value, int) or value <= 0: + raise ValueError(f"{name} must be a positive int, got {value!r}") + if not isinstance(fmt, str) or not fmt: + raise ValueError(f"format must be a non-empty str, got {fmt!r}") + obj = { + "magic": MAGIC, + "width": width, + "height": height, + "format": fmt, + "fps": fps, + } + line = json.dumps(obj, separators=(",", ":"), ensure_ascii=False).encode("utf-8") + if b"\n" in line: + raise ValueError("Hello would contain a newline") + return line + b"\n" def parse_hello(line: bytes) -> dict: """Inverse of `hello`: validate `magic` and required fields, or raise.""" - raise NotImplementedError + if not isinstance(line, (bytes, bytearray)): + raise ValueError(f"Hello must be bytes, got {type(line).__name__}") + text = bytes(line) + if text.endswith(b"\n"): + text = text[:-1] + if not text: + raise ValueError("empty Hello line") + try: + obj = json.loads(text.decode("utf-8")) + except UnicodeDecodeError as exc: + raise ValueError(f"Hello is not UTF-8: {exc}") from exc + except json.JSONDecodeError as exc: + raise ValueError(f"Hello is not valid JSON: {exc}") from exc + if not isinstance(obj, dict): + raise ValueError(f"Hello must be a JSON object, got {type(obj).__name__}") + if obj.get("magic") != MAGIC: + raise ValueError(f"bad magic {obj.get('magic')!r}, expected {MAGIC!r}") + for name in ("width", "height", "format", "fps"): + if name not in obj: + raise ValueError(f"Hello is missing {name!r}") + for name in ("width", "height", "fps"): + value = obj[name] + if isinstance(value, bool) or not isinstance(value, int) or value <= 0: + raise ValueError(f"Hello {name} must be a positive int, got {value!r}") + if not isinstance(obj["format"], str) or not obj["format"]: + raise ValueError(f"Hello format must be a non-empty str, got {obj['format']!r}") + return obj def frame(payload: bytes) -> bytes: """`\\n` for one complete image.""" - raise NotImplementedError + if not isinstance(payload, (bytes, bytearray, memoryview)): + raise ValueError(f"payload must be bytes, got {type(payload).__name__}") + body = bytes(payload) + return str(len(body)).encode("ascii") + b"\n" + body def read_frame(stream: BinaryIO) -> bytes | None: @@ -35,12 +89,67 @@ def read_frame(stream: BinaryIO) -> bytes | None: Returns None on a clean EOF before any byte of the next frame. Raises ValueError on a malformed length prefix and EOFError on a truncated payload. """ - raise NotImplementedError + digits = bytearray() + while True: + byte = stream.read(1) + if not byte: + if not digits: + return None # clean EOF between frames + raise EOFError( + f"EOF in length prefix after {bytes(digits)!r}" + ) + if byte == b"\n": + break + if not (b"0" <= byte <= b"9"): + raise ValueError( + f"malformed length prefix: unexpected byte {byte!r} " + f"after {bytes(digits)!r}" + ) + digits += byte + if len(digits) > MAX_LENGTH_DIGITS: + raise ValueError( + f"length prefix longer than {MAX_LENGTH_DIGITS} digits" + ) + if not digits: + raise ValueError("malformed length prefix: empty") + if len(digits) > 1 and digits[:1] == b"0": + raise ValueError(f"malformed length prefix: leading zero in {bytes(digits)!r}") + length = int(digits) + return _read_exactly(stream, length) def read_hello(stream: BinaryIO) -> dict: """Read and parse the Hello line from `stream`.""" - raise NotImplementedError + line = bytearray() + while True: + byte = stream.read(1) + if not byte: + raise EOFError(f"EOF in Hello line after {len(line)} bytes") + if byte == b"\n": + break + line += byte + if len(line) > MAX_HELLO_BYTES: + raise ValueError(f"Hello line longer than {MAX_HELLO_BYTES} bytes") + return parse_hello(bytes(line)) -__all__ = ["json", "hello", "parse_hello", "frame", "read_frame", "read_hello", "MAGIC"] \ No newline at end of file +def _read_exactly(stream: BinaryIO, length: int) -> bytes: + """Read exactly `length` bytes or raise EOFError. + + Reads in chunks so a bogus (huge) length prefix cannot make us allocate a + buffer for data that is not there. + """ + if length == 0: + return b"" + out = bytearray() + while len(out) < length: + chunk = stream.read(min(_READ_CHUNK, length - len(out))) + if not chunk: + raise EOFError( + f"truncated payload: wanted {length} bytes, got {len(out)}" + ) + out += chunk + return bytes(out) + + +__all__ = ["json", "hello", "parse_hello", "frame", "read_frame", "read_hello", "MAGIC"] diff --git a/src/hhstream/server.py b/src/hhstream/server.py index 63c3ffb..5518dd0 100644 --- a/src/hhstream/server.py +++ b/src/hhstream/server.py @@ -8,31 +8,395 @@ synchronously, and a slow write blocks only that client. from __future__ import annotations import argparse +import errno +import logging +import os +import selectors +import signal import socket +import stat +import sys +import threading +import time from typing import Iterable +from . import protocol from .capture import CaptureBackend, CommandCapture DEFAULT_SOCKET = "/run/hyprland-headless-stream/stream.sock" +#: Contract: the published socket is mode 0660 (ownership is the unit's job). +SOCKET_MODE = 0o660 +#: Contract default for `services.hyprland-headless-stream.captureCommand`. +DEFAULT_CAPTURE_COMMAND = ["grim", "-t", "png", "-"] + +_BACKLOG = 64 +_WAIT_TICK = 0.2 # how often a blocked client thread re-checks for shutdown + +log = logging.getLogger("hhstream.server") class FrameServer: + """Publishes one capture stream to any number of clients. + + A single capture thread holds exactly one frame -- the most recent one -- + and every client thread sends whatever is in that slot when it is ready for + another frame. That is how frames get dropped for a slow client instead of + queued: there is no queue, and memory does not grow with the number of + stalled clients. + """ + def __init__(self, socket_path: str, capture: CaptureBackend, fps: int, fmt: str = "image/png") -> None: - raise NotImplementedError + if isinstance(fps, bool) or not isinstance(fps, int) or fps <= 0: + raise ValueError(f"fps must be a positive int, got {fps!r}") + self.socket_path = socket_path + self.capture = capture + self.fps = fps + self.fmt = fmt + + #: set once the socket is bound and listening (tests wait on it) + self.ready = threading.Event() + self.frames_captured = 0 + self.capture_failures = 0 + + self._cond = threading.Condition() + self._frame: bytes | None = None + self._seq = 0 + self._hello: bytes | None = None + self._stop = threading.Event() + self._listener: socket.socket | None = None + self._bound_inode: tuple[int, int] | None = None + self._clients: list[threading.Thread] = [] + # Closing a listening socket does not reliably interrupt a blocked + # accept(), so the accept loop selects on this pair as well and stop() + # pokes it. + self._wake_r, self._wake_w = socket.socketpair() + + # -- serving --------------------------------------------------------- def serve_forever(self) -> None: """Bind, then serve until stopped. A stale socket file is replaced.""" - raise NotImplementedError + try: + self._bind() + listener = self._listener + assert listener is not None + threading.Thread(target=self._capture_loop, name="hhstream-capture", + daemon=True).start() + log.info("serving %s at %d fps (%s)", + self.socket_path, self.fps, self.fmt) + self._accept_loop(listener) + finally: + self.stop() + self._wake_r.close() + self._wake_w.close() + + def _accept_loop(self, listener: socket.socket) -> None: + with selectors.DefaultSelector() as selector: + try: + selector.register(listener, selectors.EVENT_READ) + selector.register(self._wake_r, selectors.EVENT_READ) + except (OSError, ValueError): + if self._stop.is_set(): + return # stopped between binding and the accept loop + raise + while not self._stop.is_set(): + try: + events = selector.select() + except OSError as exc: + if self._stop.is_set(): + return + log.warning("select failed: %s", exc) + self._stop.wait(0.05) # never spin on a repeating error + continue + if any(key.fileobj is self._wake_r for key, _ in events): + return + try: + conn, _ = listener.accept() + except OSError as exc: + if self._stop.is_set(): + return + log.warning("accept failed: %s", exc) + self._stop.wait(0.05) + continue + self._clients = [t for t in self._clients if t.is_alive()] + thread = threading.Thread( + target=self._serve_client, args=(conn,), + name="hhstream-client", daemon=True, + ) + self._clients.append(thread) + thread.start() + + def stop(self) -> None: + """Ask the accept loop, the capture thread and every client to finish.""" + self._stop.set() + with self._cond: + self._cond.notify_all() + try: + self._wake_w.send(b"\x00") # unblock the accept loop + except OSError: + pass + listener, self._listener = self._listener, None + if listener is not None: + try: + listener.close() + except OSError: + pass + self._unlink_own_socket() + + # -- capture --------------------------------------------------------- + + def _capture_loop(self) -> None: + interval = 1.0 / self.fps + while not self._stop.is_set(): + started = time.monotonic() + try: + payload = self.capture.grab() + width, height = self.capture.size() + except Exception as exc: # a backend may raise anything + self.capture_failures += 1 + # Contract: capture erroring keeps the socket up and retries; it + # never exits and never publishes a partial frame. + log.warning("capture failed (%d so far): %s", + self.capture_failures, exc) + else: + self._publish(payload, width, height) + remaining = interval - (time.monotonic() - started) + if remaining > 0: + self._stop.wait(remaining) + + def _publish(self, payload: bytes, width: int, height: int) -> None: + with self._cond: + if self._hello is None: + if width > 0 and height > 0: + # Contract: never a Hello with zero size. + self._hello = protocol.hello(width, height, self.fmt, self.fps) + else: + log.warning("ignoring frame with zero size %dx%d", width, height) + return + self._frame = payload + self._seq += 1 + self.frames_captured += 1 + self._cond.notify_all() + + # -- one client ------------------------------------------------------ + + def _serve_client(self, conn: socket.socket) -> None: + peer = conn.fileno() + drain = threading.Thread( + target=self._drain, args=(conn,), name="hhstream-drain", daemon=True + ) + drain.start() + try: + hello = self._wait_for_hello() + if hello is None: + return + conn.sendall(hello) + last_seq = 0 + while not self._stop.is_set(): + payload, last_seq = self._wait_for_frame(last_seq) + if payload is None: + return + conn.sendall(protocol.frame(payload)) + except OSError as exc: + # The whole point: one client dying mid-frame is this thread's + # problem and nobody else's. + log.info("client %s went away: %s", peer, exc) + except Exception: + log.exception("client %s failed", peer) + finally: + try: + conn.shutdown(socket.SHUT_RDWR) + except OSError: + pass + try: + conn.close() + except OSError: + pass + + def _drain(self, conn: socket.socket) -> None: + """Read and discard anything a client sends (contract: v1 reserved).""" + try: + while not self._stop.is_set(): + if not conn.recv(4096): + return + except OSError: + return + + def _wait_for_hello(self) -> bytes | None: + """Block until the Hello is known (a frame has been captured).""" + with self._cond: + while self._hello is None and not self._stop.is_set(): + self._cond.wait(_WAIT_TICK) + return self._hello + + def _wait_for_frame(self, last_seq: int) -> tuple[bytes | None, int]: + """Block until a frame newer than `last_seq` exists, then take the latest. + + Everything captured while this client was busy is simply skipped. + """ + with self._cond: + while self._seq == last_seq and not self._stop.is_set(): + self._cond.wait(_WAIT_TICK) + if self._seq == last_seq: + return None, last_seq + return self._frame, self._seq + + # -- socket ---------------------------------------------------------- + + def _bind(self) -> None: + path = self.socket_path + parent = os.path.dirname(os.path.abspath(path)) + if parent: + os.makedirs(parent, exist_ok=True) + self._replace_stale(path) + listener = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) + try: + listener.bind(path) + os.chmod(path, SOCKET_MODE) + listener.listen(_BACKLOG) + except OSError: + listener.close() + raise + self._listener = listener + info = os.lstat(path) + self._bound_inode = (info.st_dev, info.st_ino) + self.ready.set() + + @staticmethod + def _replace_stale(path: str) -> None: + """Remove a leftover socket file so a stale one cannot block startup.""" + try: + info = os.lstat(path) + except FileNotFoundError: + return + if not stat.S_ISSOCK(info.st_mode): + raise OSError( + errno.EEXIST, + f"{path} exists and is not a socket; refusing to remove it", + ) + os.unlink(path) + + def _unlink_own_socket(self) -> None: + """Tidy the socket file away, but only if it is still the one we bound. + + A restart that has already put its own socket there must keep it. + """ + if self._bound_inode is None: + return + try: + info = os.lstat(self.socket_path) + if (info.st_dev, info.st_ino) == self._bound_inode: + os.unlink(self.socket_path) + except OSError: + pass + self._bound_inode = None + + +# -- CLI ----------------------------------------------------------------- + +#: `--format png` is the module's spelling; the Hello carries the MIME type. +_MIME = {"png": "image/png", "jpeg": "image/jpeg"} +_CAPTURE_FLAG = "--capture-command" def build_parser() -> argparse.ArgumentParser: - raise NotImplementedError + parser = argparse.ArgumentParser( + prog="hhstream-server", + description="Publish a headless Hyprland session's frames on a Unix socket.", + ) + parser.add_argument( + "--socket", default=DEFAULT_SOCKET, metavar="PATH", + help="socket to publish frames on (default: %(default)s)", + ) + parser.add_argument( + "--fps", type=_positive_int, default=30, metavar="N", + help="target capture rate, advertised in the Hello (default: %(default)s)", + ) + parser.add_argument( + "--format", choices=sorted(_MIME), default="png", + help="frame encoding (default: %(default)s)", + ) + parser.add_argument( + _CAPTURE_FLAG, action="append", dest="capture_command", metavar="TOKEN", + help="one argv token of the capture command; repeat once per token " + "(default: %s). Use --capture-command=-t for tokens starting " + "with a dash." % " ".join(DEFAULT_CAPTURE_COMMAND), + ) + return parser def main(argv: Iterable[str] | None = None) -> int: - raise NotImplementedError + args = build_parser().parse_args(_join_capture_tokens(argv)) + logging.basicConfig( + level=logging.INFO, stream=sys.stderr, + format="%(asctime)s %(levelname)s %(message)s", + ) + capture_command = args.capture_command or _default_capture_command(args.format) + server = FrameServer( + args.socket, + CommandCapture(capture_command), + args.fps, + fmt=_MIME[args.format], + ) + _install_signal_handlers(server) + try: + server.serve_forever() + except KeyboardInterrupt: + server.stop() + except OSError as exc: + log.error("cannot serve on %s: %s", args.socket, exc) + return 1 + return 0 + + +def _default_capture_command(fmt: str) -> list[str]: + return ["grim", "-t", fmt, "-"] + + +def _positive_int(text: str) -> int: + value = int(text) + if value <= 0: + raise argparse.ArgumentTypeError(f"must be positive, got {text!r}") + return value + + +def _join_capture_tokens(argv: Iterable[str] | None) -> list[str] | None: + """Rewrite `--capture-command X` as `--capture-command=X`. + + Capture tokens are argv tokens, and real ones start with a dash (`-t`, `-` + in the default `grim -t png -`). argparse would read those as options, so + the separated form is folded into the `=` form before it sees them. + """ + if argv is None: + argv = sys.argv[1:] + tokens = list(argv) + out: list[str] = [] + i = 0 + while i < len(tokens): + token = tokens[i] + if token == "--": # everything after this is positional; leave it alone + out.extend(tokens[i:]) + break + if token == _CAPTURE_FLAG and i + 1 < len(tokens): + out.append(f"{_CAPTURE_FLAG}={tokens[i + 1]}") + i += 2 + continue + out.append(token) + i += 1 + return out + + +def _install_signal_handlers(server: FrameServer) -> None: + def handler(signum, _frame): # pragma: no cover - needs a real signal + log.info("signal %d, shutting down", signum) + server.stop() + + for signum in (signal.SIGINT, signal.SIGTERM): + try: + signal.signal(signum, handler) + except ValueError: + pass # not the main thread (embedded in a test); nothing to do __all__ = ["FrameServer", "DEFAULT_SOCKET", "CaptureBackend", "CommandCapture", - "socket", "build_parser", "main"] \ No newline at end of file + "socket", "build_parser", "main"] diff --git a/tests/unit/conftest.py b/tests/unit/conftest.py new file mode 100644 index 0000000..5cc0cd1 --- /dev/null +++ b/tests/unit/conftest.py @@ -0,0 +1,59 @@ +"""Shared fixtures. Nothing here touches a compositor, a GPU or the network.""" + +from __future__ import annotations + +import contextlib +import pathlib +import shutil +import sys +import tempfile +import threading + +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 hhstream.server import FrameServer # noqa: E402 (needs sys.path above) + + +@pytest.fixture +def workdir(): + """A short-lived directory with a short path (AF_UNIX paths are ~108 bytes).""" + path = tempfile.mkdtemp(prefix="hhs") + try: + yield pathlib.Path(path) + finally: + shutil.rmtree(path, ignore_errors=True) + + +@pytest.fixture +def sock_path(workdir): + return str(workdir / "s.sock") + + +@pytest.fixture +def serve(): + """`with serve(path, capture, fps=...) as server:` -- bound and listening.""" + started: list[tuple[FrameServer, threading.Thread]] = [] + + @contextlib.contextmanager + def _serve(path, capture, fps=20, fmt="image/png"): + server = FrameServer(path, capture, fps, fmt=fmt) + thread = threading.Thread(target=server.serve_forever, daemon=True) + started.append((server, thread)) + thread.start() + assert server.ready.wait(5), "server never bound its socket" + try: + yield server + finally: + server.stop() + thread.join(5) + + yield _serve + for server, thread in started: + server.stop() + thread.join(5) diff --git a/tests/unit/fake_capture.py b/tests/unit/fake_capture.py new file mode 100644 index 0000000..3f14cfb --- /dev/null +++ b/tests/unit/fake_capture.py @@ -0,0 +1,102 @@ +#!/usr/bin/env python3 +"""A stand-in for `grim`: writes one fake PNG frame to stdout. + +Injected through `captureCommand` (see docs/CONTRACT.md) so no unit test needs a +compositor or a GPU. One script plays every part the server has to cope with: a +healthy backend, a broken one, a silent one, a slow one, and one that only +starts working later. +""" + +from __future__ import annotations + +import argparse +import os +import struct +import sys +import time +import zlib + + +def png_bytes(width: int = 16, height: int = 8, color: tuple[int, int, int] = (0, 0, 0), + level: int = 6) -> bytes: + """A real, decodable RGB PNG of a solid colour. + + `level` 0 stores the pixels uncompressed, which is how the tests get a frame + big enough to fill a socket buffer. + """ + def chunk(tag: bytes, data: bytes) -> bytes: + return (struct.pack(">I", len(data)) + tag + data + + struct.pack(">I", zlib.crc32(tag + data) & 0xFFFFFFFF)) + + ihdr = struct.pack(">IIBBBBB", width, height, 8, 2, 0, 0, 0) + row = bytes(color) * width + raw = b"".join(b"\x00" + row for _ in range(height)) + return (b"\x89PNG\r\n\x1a\n" + + chunk(b"IHDR", ihdr) + + chunk(b"IDAT", zlib.compress(raw, level)) + + chunk(b"IEND", b"")) + + +def build_parser() -> argparse.ArgumentParser: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--width", type=int, default=16) + parser.add_argument("--height", type=int, default=8) + parser.add_argument("--counter", metavar="PATH", + help="file holding a call count; each frame's colour " + "differs so frames are distinguishable") + parser.add_argument("--gate", metavar="PATH", + help="fail until this path exists (a compositor that " + "is not up yet)") + parser.add_argument("--fail", action="store_true", help="exit non-zero") + parser.add_argument("--empty", action="store_true", + help="exit 0 having written nothing") + parser.add_argument("--garbage", action="store_true", + help="write output that is not an image") + parser.add_argument("--delay", type=float, default=0.0, + help="sleep this long before answering") + parser.add_argument("--big", action="store_true", + help="store the pixels uncompressed (a large frame)") + parser.add_argument("--message", default="fake_capture: simulated failure") + return parser + + +def main(argv: list[str] | None = None) -> int: + args = build_parser().parse_args(argv) + if args.delay: + time.sleep(args.delay) + if args.gate and not os.path.exists(args.gate): + sys.stderr.write(f"fake_capture: gate {args.gate} is missing\n") + return 4 + if args.fail: + sys.stderr.write(args.message + "\n") + return 3 + if args.empty: + sys.stderr.write("fake_capture: nothing to capture\n") + return 0 + + count = 0 + if args.counter: + try: + with open(args.counter) as handle: + count = int(handle.read() or 0) + except FileNotFoundError: + count = 0 + count += 1 + with open(args.counter, "w") as handle: + handle.write(str(count)) + + if args.garbage: + sys.stdout.buffer.write(b"fake_capture: not an image, sorry\n") + sys.stdout.buffer.flush() + return 0 + + colour = (count % 251, (count * 7) % 251, (count * 13) % 251) + sys.stdout.buffer.write( + png_bytes(args.width, args.height, colour, 0 if args.big else 6) + ) + sys.stdout.buffer.flush() + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/tests/unit/helpers.py b/tests/unit/helpers.py new file mode 100644 index 0000000..a3a0cc1 --- /dev/null +++ b/tests/unit/helpers.py @@ -0,0 +1,64 @@ +"""Test doubles: an in-process capture backend and the fake capture command.""" + +from __future__ import annotations + +import pathlib +import socket +import struct +import sys +import threading +import time + +from fake_capture import png_bytes # noqa: F401 (re-exported for the tests) +from hhstream.capture import CaptureError + +#: argv prefix for the fake `grim`; append its flags. +FAKE_CAPTURE = [sys.executable, str(pathlib.Path(__file__).with_name("fake_capture.py"))] + + +class FakeCapture: + """A `CaptureBackend` with no subprocess: deterministic, fast, scriptable.""" + + def __init__(self, frames=None, size=(1280, 720), fail_until=0, delay=0.0): + self.frames = list(frames) if frames else [png_bytes(4, 2)] + self._size = size + self.fail_until = fail_until + 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_until: + raise CaptureError(f"simulated capture failure {call}") + return self.frames[(call - 1 - self.fail_until) % len(self.frames)] + + def size(self) -> tuple[int, int]: + if self.calls <= self.fail_until: + raise CaptureError("size is not known yet") + return self._size + + +def distinct_frames(count: int) -> list[bytes]: + """`count` unique, decodable PNGs, in order.""" + return [png_bytes(4, 2, (i % 251, (i * 7) % 251, (i * 13) % 251)) + for i in range(1, count + 1)] + + +def connect(path: str, timeout: float = 5.0, rcvbuf: int | None = None) -> socket.socket: + conn = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) + if rcvbuf is not None: + conn.setsockopt(socket.SOL_SOCKET, socket.SO_RCVBUF, rcvbuf) + conn.settimeout(timeout) + conn.connect(path) + return conn + + +def abort(conn: socket.socket) -> None: + """Close with SO_LINGER 0: the peer sees the connection torn down, not EOF.""" + conn.setsockopt(socket.SOL_SOCKET, socket.SO_LINGER, struct.pack("ii", 1, 0)) + conn.close() diff --git a/tests/unit/test_capture.py b/tests/unit/test_capture.py new file mode 100644 index 0000000..6b8d606 --- /dev/null +++ b/tests/unit/test_capture.py @@ -0,0 +1,116 @@ +"""The capture backend, driven by the fake capture command (no compositor).""" + +from __future__ import annotations + +import os +import sys + +import pytest +from helpers import FAKE_CAPTURE, png_bytes + +from hhstream.capture import CaptureError, CommandCapture, image_size + + +def fake(*flags: str) -> list[str]: + return [*FAKE_CAPTURE, *flags] + + +def test_grab_returns_the_frame_and_size_comes_from_its_header(): + capture = CommandCapture(fake("--width", "1280", "--height", "720")) + frame = capture.grab() + assert frame.startswith(b"\x89PNG\r\n\x1a\n") + assert capture.size() == (1280, 720) + + +def test_size_grabs_once_when_nothing_has_been_captured_yet(): + capture = CommandCapture(fake("--width", "64", "--height", "32")) + assert capture.size() == (64, 32) + + +def test_a_failing_command_raises_and_reports_its_stderr(capfd): + capture = CommandCapture(fake("--fail", "--message", "grim: no outputs")) + with pytest.raises(CaptureError) as excinfo: + capture.grab() + assert "exited 3" in str(excinfo.value) + assert "grim: no outputs" in str(excinfo.value) + out, err = capfd.readouterr() + assert (out, err) == ("", ""), "the helper must not write to our stdio" + + +def test_empty_output_is_a_failure_not_an_empty_frame(capfd): + with pytest.raises(CaptureError) as excinfo: + CommandCapture(fake("--empty")).grab() + assert "no output" in str(excinfo.value) + assert capfd.readouterr() == ("", "") + + +def test_a_hanging_command_times_out(): + capture = CommandCapture(fake("--delay", "10"), timeout=0.5) + with pytest.raises(CaptureError) as excinfo: + capture.grab() + assert "timed out" in str(excinfo.value) + + +def test_a_missing_command_is_a_capture_error(): + with pytest.raises(CaptureError) as excinfo: + CommandCapture(["hhstream-no-such-program"]).grab() + assert "could not be run" in str(excinfo.value) + + +def test_unmeasurable_output_cannot_produce_a_hello(): + capture = CommandCapture(fake("--garbage")) + assert capture.grab() == b"fake_capture: not an image, sorry\n" + with pytest.raises(CaptureError) as excinfo: + capture.size() + assert "pixel size" in str(excinfo.value) + + +def test_a_failure_after_a_good_frame_keeps_the_known_size(): + good = CommandCapture(fake("--width", "100", "--height", "50")) + assert good.size() == (100, 50) + good.argv = fake("--fail") + with pytest.raises(CaptureError): + good.grab() + assert good.size() == (100, 50) + + +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'))"] + 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" + + +def test_empty_argv_and_bad_timeout_are_rejected_up_front(): + with pytest.raises(ValueError): + CommandCapture([]) + with pytest.raises(ValueError): + CommandCapture(["true"], timeout=0) + + +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')") + assert CommandCapture([sys.executable, "-c", code]).grab() == b"EMPTY" + + +@pytest.mark.parametrize("width,height", [(1, 1), (16, 9), (3840, 2160)]) +def test_image_size_reads_png_headers(width, height): + assert image_size(png_bytes(width, height)) == (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) + 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"]) +def test_image_size_returns_none_when_it_cannot_tell(data): + assert image_size(data) is None diff --git a/tests/unit/test_cli.py b/tests/unit/test_cli.py new file mode 100644 index 0000000..48778fe --- /dev/null +++ b/tests/unit/test_cli.py @@ -0,0 +1,172 @@ +"""The command line: the flag names the NixOS module passes, end to end. + +The server and the client run as real processes here, with the fake capture +command standing in for `grim`, so nothing needs a compositor. +""" + +from __future__ import annotations + +import json +import os +import pathlib +import subprocess +import sys +import time + +import pytest +from helpers import FAKE_CAPTURE + +from hhstream import client, server + +SRC = str(pathlib.Path(__file__).resolve().parents[2] / "src") +RUN_SERVER = [sys.executable, "-c", + "from hhstream.server import main; raise SystemExit(main())"] +RUN_CLIENT = [sys.executable, "-c", + "from hhstream.client import main; raise SystemExit(main())"] + + +def child_env() -> dict[str, str]: + env = dict(os.environ) + env["PYTHONPATH"] = SRC + (os.pathsep + env["PYTHONPATH"] if "PYTHONPATH" in env else "") + return env + + +def capture_flags(*flags: str) -> list[str]: + """`--capture-command` once per argv token, as the module passes it.""" + out = [] + for token in (*FAKE_CAPTURE, *flags): + out += ["--capture-command", token] + return out + + +def wait_for_socket(path: str, proc: subprocess.Popen, timeout: float = 10.0) -> None: + deadline = time.monotonic() + timeout + while time.monotonic() < deadline: + if os.path.exists(path): + return + if proc.poll() is not None: + raise AssertionError(f"server exited {proc.returncode}: {proc.stderr.read()}") + time.sleep(0.05) + raise AssertionError(f"{path} never appeared") + + +# -- argument parsing ---------------------------------------------------- + +def test_server_defaults_match_the_contract(): + args = server.build_parser().parse_args([]) + assert args.socket == "/run/hyprland-headless-stream/stream.sock" + assert (args.fps, args.format, args.capture_command) == (30, "png", None) + assert server.DEFAULT_CAPTURE_COMMAND == ["grim", "-t", "png", "-"] + + +def test_capture_command_is_one_argv_token_per_flag(): + argv = ["--capture-command", "grim", "--capture-command", "-t", + "--capture-command", "png", "--capture-command", "-"] + parsed = server.build_parser().parse_args(server._join_capture_tokens(argv)) + assert parsed.capture_command == ["grim", "-t", "png", "-"] + + +def test_capture_command_also_accepts_the_equals_form(): + argv = ["--capture-command=grim", "--capture-command=-t", "--capture-command=-"] + parsed = server.build_parser().parse_args(server._join_capture_tokens(argv)) + assert parsed.capture_command == ["grim", "-t", "-"] + + +@pytest.mark.parametrize("bad", [["--fps", "0"], ["--fps", "-3"], + ["--format", "webp"]]) +def test_the_server_rejects_bad_flags(bad): + with pytest.raises(SystemExit): + server.build_parser().parse_args(bad) + + +def test_client_defaults(): + args = client.build_parser().parse_args([]) + assert (args.socket, args.count, args.out, args.timeout) == ( + client.DEFAULT_SOCKET, 1, None, 10.0) + + +# -- the real thing ------------------------------------------------------ + +def test_server_and_client_processes_talk_to_each_other(workdir): + sock = str(workdir / "s.sock") + server_proc = subprocess.Popen( + [*RUN_SERVER, "--socket", sock, "--fps", "10", "--format", "png", + *capture_flags("--width", "1280", "--height", "720", "--counter", + str(workdir / "n"))], + env=child_env(), stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, + ) + try: + wait_for_socket(sock, server_proc) + done = subprocess.run( + [*RUN_CLIENT, "--socket", sock, "--count", "2", + "--out", str(workdir / "frame.png"), "--timeout", "10"], + env=child_env(), capture_output=True, text=True, timeout=30, + ) + assert done.returncode == 0, done.stderr + lines = done.stdout.splitlines() + assert json.loads(lines[0]) == { + "magic": "HHS1", "width": 1280, "height": 720, + "format": "image/png", "fps": 10, + } + assert len(lines) == 3 + first = (workdir / "frame-1.png").read_bytes() + second = (workdir / "frame-2.png").read_bytes() + assert first.startswith(b"\x89PNG\r\n\x1a\n") + assert second.startswith(b"\x89PNG\r\n\x1a\n") + assert first != second, "the two frames should be two different captures" + assert server_proc.poll() is None, "the server must still be running" + finally: + server_proc.terminate() + out, err = server_proc.communicate(timeout=10) + assert server_proc.returncode == 0 + assert out == "", "the server must keep its stdout clean" + assert os.path.exists(sock) is False, "the socket file should be cleaned up" + + +def test_the_format_flag_becomes_the_mime_type_in_the_hello(workdir): + sock = str(workdir / "s.sock") + server_proc = subprocess.Popen( + [*RUN_SERVER, "--socket", sock, "--fps", "5", "--format", "jpeg", + *capture_flags("--width", "640", "--height", "480")], + env=child_env(), stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, + ) + try: + wait_for_socket(sock, server_proc) + hello, frames = client.read_stream(sock, count=1, timeout=10) + assert hello == {"magic": "HHS1", "width": 640, "height": 480, + "format": "image/jpeg", "fps": 5} + assert len(frames) == 1 + finally: + server_proc.terminate() + server_proc.communicate(timeout=10) + + +def test_a_broken_capture_command_does_not_kill_the_server(workdir): + sock = str(workdir / "s.sock") + server_proc = subprocess.Popen( + [*RUN_SERVER, "--socket", sock, "--fps", "20", *capture_flags("--fail")], + env=child_env(), stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, + ) + try: + wait_for_socket(sock, server_proc) + time.sleep(1.0) + assert server_proc.poll() is None, "the server exited on a capture failure" + assert os.path.exists(sock), "the socket went away" + finally: + server_proc.terminate() + out, err = server_proc.communicate(timeout=10) + assert out == "" + assert "capture failed" in err + assert "simulated failure" in err, "the helper's stderr should be reported" + + +def test_the_server_exits_nonzero_when_the_socket_cannot_be_bound(workdir): + blocked = workdir / "regular-file" + blocked.write_text("not a socket") + done = subprocess.run( + [*RUN_SERVER, "--socket", str(blocked), *capture_flags()], + env=child_env(), capture_output=True, text=True, timeout=30, + ) + assert done.returncode == 1 + assert "cannot serve" in done.stderr + assert blocked.read_text() == "not a socket" diff --git a/tests/unit/test_client.py b/tests/unit/test_client.py new file mode 100644 index 0000000..6fd7241 --- /dev/null +++ b/tests/unit/test_client.py @@ -0,0 +1,147 @@ +"""The client, against the real server and against a hand-written stub server.""" + +from __future__ import annotations + +import contextlib +import json +import socket +import threading + +import pytest +from helpers import FakeCapture, connect, distinct_frames + +from hhstream import client, protocol + + +@contextlib.contextmanager +def stub_server(path: str, payload: bytes): + """A server that writes exactly `payload` to one client, then hangs up.""" + listener = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) + listener.bind(path) + listener.listen(1) + + def run(): + try: + conn, _ = listener.accept() + except OSError: + return + with conn: + try: + conn.sendall(payload) + except OSError: + pass + + thread = threading.Thread(target=run, daemon=True) + thread.start() + try: + yield + finally: + listener.close() + thread.join(5) + + +def test_fetch_returns_the_payloads(sock_path, serve): + frames = distinct_frames(30) + with serve(sock_path, FakeCapture(frames=frames), fps=50): + got = client.fetch(sock_path, count=3, timeout=5) + assert len(got) == 3 + assert all(payload in frames for payload in got) + + +def test_read_stream_also_returns_the_hello(sock_path, serve): + with serve(sock_path, FakeCapture(frames=distinct_frames(5)), fps=25): + hello, frames = client.read_stream(sock_path, count=1, timeout=5) + assert hello == {"magic": "HHS1", "width": 1280, "height": 720, + "format": "image/png", "fps": 25} + assert len(frames) == 1 + + +def test_fetch_returns_fewer_frames_when_the_server_hangs_up(sock_path): + wire = protocol.hello(4, 2, "image/png", 1) + protocol.frame(b"only one") + with stub_server(sock_path, wire): + assert client.fetch(sock_path, count=5, timeout=5) == [b"only one"] + + +def test_fetch_on_a_missing_socket_raises_oserror(sock_path): + with pytest.raises(OSError): + client.fetch(sock_path, count=1, timeout=1) + + +def test_fetch_rejects_a_bad_hello(sock_path): + with stub_server(sock_path, b'{"magic":"NOPE"}\n'): + with pytest.raises(ValueError): + client.fetch(sock_path, count=1, timeout=5) + + +def test_fetch_rejects_a_truncated_frame(sock_path): + wire = protocol.hello(4, 2, "image/png", 1) + b"100\nshort" + with stub_server(sock_path, wire): + with pytest.raises(EOFError): + client.fetch(sock_path, count=1, timeout=5) + + +# -- the CLI ------------------------------------------------------------- + +def test_main_prints_the_hello_and_writes_one_frame(sock_path, serve, workdir, capsys): + frames = distinct_frames(5) + with serve(sock_path, FakeCapture(frames=frames), fps=25): + out = workdir / "frame.png" + assert client.main(["--socket", sock_path, "--count", "1", + "--out", str(out), "--timeout", "5"]) == 0 + printed = capsys.readouterr().out.splitlines() + assert json.loads(printed[0])["magic"] == "HHS1" + assert f"-> {out}" in printed[1] + assert out.read_bytes() in frames + + +def test_main_suffixes_the_output_when_count_is_more_than_one(sock_path, serve, + workdir, capsys): + with serve(sock_path, FakeCapture(frames=distinct_frames(20)), fps=50): + assert client.main(["--socket", sock_path, "--count", "2", + "--out", str(workdir / "shot.png"), "--timeout", "5"]) == 0 + assert (workdir / "shot-1.png").exists() + assert (workdir / "shot-2.png").exists() + assert not (workdir / "shot.png").exists() + assert len(capsys.readouterr().out.splitlines()) == 3 # hello + two frames + + +def test_main_writes_payloads_to_stdout_with_out_dash(sock_path, serve, capsysbinary): + frame = distinct_frames(1)[0] + with serve(sock_path, FakeCapture(frames=[frame]), fps=25): + assert client.main(["--socket", sock_path, "--count", "2", "--out", "-", + "--timeout", "5"]) == 0 + captured = capsysbinary.readouterr() + assert captured.out == frame * 2, "payloads must be the only thing on stdout" + assert b'"magic":"HHS1"' in captured.err + + +def test_main_reports_a_missing_socket_without_a_traceback(sock_path, capsys): + assert client.main(["--socket", sock_path, "--timeout", "1"]) == 1 + assert "hhstream-client:" in capsys.readouterr().err + + +def test_main_reports_a_short_stream(sock_path, capsys): + wire = protocol.hello(4, 2, "image/png", 1) + protocol.frame(b"one") + with stub_server(sock_path, wire): + assert client.main(["--socket", sock_path, "--count", "3", + "--timeout", "5"]) == 1 + assert "wanted 3 frames, got 1" in capsys.readouterr().err + + +def test_main_rejects_a_negative_count(sock_path, capsys): + assert client.main(["--socket", sock_path, "--count", "-1"]) == 2 + assert "--count" in capsys.readouterr().err + + +def test_default_socket_matches_the_contract(): + assert client.DEFAULT_SOCKET == "/run/hyprland-headless-stream/stream.sock" + assert client.build_parser().parse_args([]).socket == client.DEFAULT_SOCKET + + +def test_a_client_can_be_interrupted_without_disturbing_the_server(sock_path, serve): + """Two sequential fetches: the first client's exit leaves the socket usable.""" + with serve(sock_path, FakeCapture(frames=distinct_frames(40)), fps=50): + assert len(client.fetch(sock_path, count=2, timeout=5)) == 2 + conn = connect(sock_path) + conn.close() # leave mid-stream + assert len(client.fetch(sock_path, count=2, timeout=5)) == 2 diff --git a/tests/unit/test_protocol.py b/tests/unit/test_protocol.py new file mode 100644 index 0000000..c0b29d9 --- /dev/null +++ b/tests/unit/test_protocol.py @@ -0,0 +1,186 @@ +"""The framing. Other people's clients depend on these bytes being exact.""" + +from __future__ import annotations + +import io +import json + +import pytest + +from hhstream import MAGIC, protocol + + +# -- Hello --------------------------------------------------------------- + +def test_hello_matches_the_contract_byte_for_byte(): + assert protocol.hello(1280, 720, "image/png", 30) == ( + b'{"magic":"HHS1","width":1280,"height":720,"format":"image/png","fps":30}\n' + ) + + +def test_hello_round_trip(): + line = protocol.hello(640, 480, "image/jpeg", 15) + assert line.endswith(b"\n") and line.count(b"\n") == 1 + assert protocol.parse_hello(line) == { + "magic": MAGIC, "width": 640, "height": 480, + "format": "image/jpeg", "fps": 15, + } + + +def test_parse_hello_tolerates_a_missing_trailing_newline(): + line = protocol.hello(8, 8, "image/png", 1) + assert protocol.parse_hello(line.rstrip(b"\n")) == protocol.parse_hello(line) + + +@pytest.mark.parametrize("width,height,fps", [(0, 720, 30), (1280, 0, 30), + (1280, 720, 0), (-1, 720, 30)]) +def test_hello_refuses_a_zero_or_negative_size(width, height, fps): + with pytest.raises(ValueError): + protocol.hello(width, height, "image/png", fps) + + +@pytest.mark.parametrize("payload", [ + b"", + b"not json at all", + b"[1,2,3]", + b'"a string"', + b'{"magic":"HHS0","width":1,"height":1,"format":"image/png","fps":1}', + b'{"width":1,"height":1,"format":"image/png","fps":1}', + b'{"magic":"HHS1","height":1,"format":"image/png","fps":1}', + b'{"magic":"HHS1","width":1,"height":1,"fps":1}', + b'{"magic":"HHS1","width":1,"height":1,"format":"image/png"}', + b'{"magic":"HHS1","width":0,"height":1,"format":"image/png","fps":1}', + b'{"magic":"HHS1","width":"1","height":1,"format":"image/png","fps":1}', + b'{"magic":"HHS1","width":true,"height":1,"format":"image/png","fps":1}', + b'{"magic":"HHS1","width":1,"height":1,"format":"","fps":1}', + b'{"magic":"HHS1","width":1,"height":1,"format":"image/png","fps":1}\xff', +]) +def test_parse_hello_rejects_bad_input(payload): + with pytest.raises(ValueError): + protocol.parse_hello(payload) + + +def test_read_hello_then_frames_from_one_stream(): + stream = io.BytesIO( + protocol.hello(2, 2, "image/png", 5) + protocol.frame(b"one") + protocol.frame(b"two") + ) + assert protocol.read_hello(stream)["width"] == 2 + assert protocol.read_frame(stream) == b"one" + assert protocol.read_frame(stream) == b"two" + assert protocol.read_frame(stream) is None + + +def test_read_hello_on_a_truncated_line(): + with pytest.raises(EOFError): + protocol.read_hello(io.BytesIO(b'{"magic":"HHS1"')) + + +def test_read_hello_gives_up_on_an_endless_line(): + with pytest.raises(ValueError): + protocol.read_hello(_Endless(b"x")) + + +# -- frames -------------------------------------------------------------- + +@pytest.mark.parametrize("payload", [ + b"", + b"\n", + b"a\nb", + b"\n\n\n", + b"12\n34", # payload that looks like a frame itself + b"\x89PNG\r\n\x1a\n", + bytes(range(256)), + b"x" * (1 << 20), +]) +def test_frame_round_trip(payload): + wire = protocol.frame(payload) + assert wire.startswith(str(len(payload)).encode("ascii") + b"\n") + assert len(wire) == len(payload) + len(str(len(payload))) + 1 + assert protocol.read_frame(io.BytesIO(wire)) == payload + + +def test_zero_length_frame_is_a_frame_not_an_eof(): + stream = io.BytesIO(protocol.frame(b"") + protocol.frame(b"after")) + assert protocol.frame(b"") == b"0\n" + assert protocol.read_frame(stream) == b"" + assert protocol.read_frame(stream) == b"after" + + +def test_payload_containing_newlines_is_not_resplit(): + payload = b"row1\nrow2\n" * 500 + stream = io.BytesIO(protocol.frame(payload) + protocol.frame(b"next")) + assert protocol.read_frame(stream) == payload + assert protocol.read_frame(stream) == b"next" + + +def test_length_prefix_has_no_leading_zeros_and_no_sign(): + assert protocol.frame(b"abc") == b"3\nabc" + assert not protocol.frame(b"x" * 10).startswith(b"+") + + +def test_read_frame_stops_exactly_at_the_end_of_the_payload(): + stream = io.BytesIO(protocol.frame(b"abc") + b"LEFTOVER") + assert protocol.read_frame(stream) == b"abc" + assert stream.read() == b"LEFTOVER" + + +def test_clean_eof_between_frames_is_none(): + assert protocol.read_frame(io.BytesIO(b"")) is None + + +@pytest.mark.parametrize("wire", [ + b"\nabc", # empty length prefix + b"007\nabcdefg", # leading zero + b"0012\n", # leading zeros + b"12x\nabc", # not a digit + b" 3\nabc", # leading space + b"+3\nabc", # sign + b"-3\nabc", # negative + b"3.0\nabc", # not an integer + b"1" * 21 + b"\n", # absurdly long prefix +]) +def test_garbage_length_prefix_raises_value_error(wire): + with pytest.raises(ValueError): + protocol.read_frame(io.BytesIO(wire)) + + +@pytest.mark.parametrize("wire", [ + b"5\nabc", # payload short + b"5\n", # payload absent + b"1048576\n" + b"x" * 1000, + b"12", # EOF inside the length prefix +]) +def test_truncated_payload_raises_eof_error(wire): + with pytest.raises(EOFError): + protocol.read_frame(io.BytesIO(wire)) + + +def test_read_frame_gives_up_on_endless_digits_instead_of_hanging(): + with pytest.raises(ValueError): + protocol.read_frame(_Endless(b"1")) + + +def test_a_huge_length_prefix_does_not_preallocate(): + # 10**19 bytes is not going to arrive; we must notice the EOF, not the RAM. + with pytest.raises(EOFError): + protocol.read_frame(io.BytesIO(b"9999999999999999999\nshort")) + + +def test_frame_rejects_non_bytes(): + with pytest.raises(ValueError): + protocol.frame("a str is not bytes") # type: ignore[arg-type] + + +def test_hello_is_valid_json_with_the_documented_field_order(): + line = protocol.hello(1280, 720, "image/png", 30).decode("utf-8") + assert list(json.loads(line)) == ["magic", "width", "height", "format", "fps"] + + +class _Endless: + """A stream that never ends and never blocks -- proves we bail out.""" + + def __init__(self, byte: bytes): + self.byte = byte + + def read(self, size: int = -1) -> bytes: + return self.byte * (1 if size in (-1, None) else size) diff --git a/tests/unit/test_server.py b/tests/unit/test_server.py new file mode 100644 index 0000000..1aea6c2 --- /dev/null +++ b/tests/unit/test_server.py @@ -0,0 +1,253 @@ +"""The server's obligations from docs/CONTRACT.md, none of which need a GPU.""" + +from __future__ import annotations + +import os +import socket +import stat +import threading +import time + +import pytest +from helpers import (FAKE_CAPTURE, FakeCapture, abort, connect, distinct_frames, + png_bytes) + +from hhstream import protocol +from hhstream.capture import CommandCapture +from hhstream.server import FrameServer + +HELLO_WAIT = 5.0 + + +def read_hello(conn, timeout=HELLO_WAIT): + conn.settimeout(timeout) + return protocol.read_hello(conn.makefile("rb")) + + +def test_fps_must_be_positive(sock_path): + for bad in (0, -1, True, 1.5): + with pytest.raises(ValueError): + FrameServer(sock_path, FakeCapture(), bad) + + +def test_two_clients_each_get_their_own_hello_and_frames(sock_path, serve): + capture = FakeCapture(frames=distinct_frames(20), size=(1280, 720)) + with serve(sock_path, capture, fps=30): + first, second = connect(sock_path), connect(sock_path) + streams = [first.makefile("rb"), second.makefile("rb")] + hellos = [protocol.read_hello(s) for s in streams] + assert hellos[0] == hellos[1] == { + "magic": "HHS1", "width": 1280, "height": 720, + "format": "image/png", "fps": 30, + } + for stream in streams: + for _ in range(3): + payload = protocol.read_frame(stream) + assert payload and payload.startswith(b"\x89PNG\r\n\x1a\n") + first.close() + second.close() + + +def test_a_client_arriving_later_is_served_too(sock_path, serve): + with serve(sock_path, FakeCapture(frames=distinct_frames(50)), fps=50): + early = connect(sock_path) + early_stream = early.makefile("rb") + protocol.read_hello(early_stream) + assert protocol.read_frame(early_stream) + time.sleep(0.3) # let a pile of frames go by + late = connect(sock_path) + late_stream = late.makefile("rb") + assert protocol.read_hello(late_stream)["width"] == 1280 + assert protocol.read_frame(late_stream) # not made to wait for a backlog + early.close() + late.close() + + +def test_a_stalled_client_does_not_block_another(sock_path, serve): + """Contract: a stalled client is slowed, not queued -- and it is alone.""" + big = png_bytes(1024, 1024, (1, 2, 3), level=0) # ~3 MiB, fills any buffer + assert len(big) > 2 << 20 + with serve(sock_path, FakeCapture(frames=[big]), fps=20): + stalled = connect(sock_path, rcvbuf=2048) + assert read_hello(stalled)["width"] == 1280 + # ...and now `stalled` reads nothing at all, so the server's write to it + # blocks part-way through a frame. + time.sleep(0.5) + + started = time.monotonic() + healthy = connect(sock_path) + stream = healthy.makefile("rb") + assert protocol.read_hello(stream)["width"] == 1280 + assert len(protocol.read_frame(stream)) == len(big) + assert len(protocol.read_frame(stream)) == len(big) + assert time.monotonic() - started < HELLO_WAIT, "the stall spread" + healthy.close() + stalled.close() + + +def test_frames_are_dropped_for_a_slow_client_not_queued(sock_path, serve): + frames = distinct_frames(400) + index_of = {payload: i for i, payload in enumerate(frames, start=1)} + capture = FakeCapture(frames=frames) + with serve(sock_path, capture, fps=100) as server: + conn = connect(sock_path) + stream = conn.makefile("rb") + protocol.read_hello(stream) + seen = [] + for _ in range(3): + time.sleep(0.2) # far slower than 100 fps + seen.append(index_of[protocol.read_frame(stream)]) + conn.close() + assert server.frames_captured > len(seen) + 2, "capture did not outrun the client" + assert seen == sorted(seen) + assert seen[-1] > len(seen), f"frames were queued, not dropped: {seen}" + + +def test_server_survives_a_client_dying_mid_frame(sock_path, serve): + big = png_bytes(1024, 1024, (9, 9, 9), level=0) + with serve(sock_path, FakeCapture(frames=[big]), fps=20) as server: + doomed = connect(sock_path, rcvbuf=2048) + stream = doomed.makefile("rb") + assert protocol.read_hello(stream)["width"] == 1280 + assert len(stream.read(4096)) == 4096 # a fragment of the first frame + abort(doomed) # torn down mid-frame, with an RST + + survivor = connect(sock_path) + survivor_stream = survivor.makefile("rb") + assert protocol.read_hello(survivor_stream)["width"] == 1280 + assert len(protocol.read_frame(survivor_stream)) == len(big) + survivor.close() + assert server.ready.is_set() + + +def test_server_survives_many_clients_connecting_and_vanishing(sock_path, serve): + with serve(sock_path, FakeCapture(frames=distinct_frames(10)), fps=50): + for _ in range(25): + conn = connect(sock_path) + protocol.read_hello(conn.makefile("rb")) + abort(conn) + survivor = connect(sock_path) + stream = survivor.makefile("rb") + assert protocol.read_hello(stream)["width"] == 1280 + assert protocol.read_frame(stream) + survivor.close() + + +def test_bytes_sent_by_a_client_are_read_and_ignored(sock_path, serve): + with serve(sock_path, FakeCapture(frames=distinct_frames(10)), fps=30): + conn = connect(sock_path) + conn.sendall(b"v2 control channel?\n" * 500) + stream = conn.makefile("rb") + assert protocol.read_hello(stream)["magic"] == "HHS1" + assert protocol.read_frame(stream) + conn.sendall(b"more chatter") + assert protocol.read_frame(stream) + conn.close() + + +def test_capture_failure_keeps_the_server_up_and_holds_the_hello(sock_path, serve, + workdir): + """Contract: no compositor -> keep the socket up, retry, send no Hello yet.""" + gate = workdir / "gate" + capture = CommandCapture( + [*FAKE_CAPTURE, "--gate", str(gate), "--width", "800", "--height", "600"], + timeout=10, + ) + with serve(sock_path, capture, fps=20) as server: + waiting = connect(sock_path, timeout=1.0) + with pytest.raises(TimeoutError): + protocol.read_hello(waiting.makefile("rb")) + assert server.capture_failures > 0 + assert server.frames_captured == 0 + waiting.close() + + gate.write_text("the compositor is up now\n") + recovered = connect(sock_path) + stream = recovered.makefile("rb") + hello = protocol.read_hello(stream) + assert (hello["width"], hello["height"]) == (800, 600) + assert protocol.read_frame(stream).startswith(b"\x89PNG\r\n\x1a\n") + recovered.close() + assert server.frames_captured > 0 + + +def test_capture_failing_in_the_middle_does_not_break_the_stream(sock_path, serve): + capture = FakeCapture(frames=distinct_frames(10)) + with serve(sock_path, capture, fps=50) as server: + conn = connect(sock_path) + stream = conn.makefile("rb") + protocol.read_hello(stream) + assert protocol.read_frame(stream) + capture.fail_until = capture.calls + 20 # a burst of failures + time.sleep(0.3) + assert server.capture_failures >= 1 + assert protocol.read_frame(stream) # recovers without a reconnect + conn.close() + + +def test_a_stale_socket_file_does_not_prevent_startup(sock_path, serve): + stale = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) + stale.bind(sock_path) + stale.close() + assert stat.S_ISSOCK(os.lstat(sock_path).st_mode) + with serve(sock_path, FakeCapture(), fps=20): + conn = connect(sock_path) + assert protocol.read_hello(conn.makefile("rb"))["magic"] == "HHS1" + conn.close() + + +def test_the_socket_is_mode_0660(sock_path, serve): + with serve(sock_path, FakeCapture(), fps=20): + assert stat.S_IMODE(os.stat(sock_path).st_mode) == 0o660 + + +def test_a_non_socket_file_in_the_way_is_never_deleted(workdir): + precious = workdir / "precious" + precious.write_text("someone else's data") + server = FrameServer(str(precious), FakeCapture(), 20) + with pytest.raises(OSError): + server.serve_forever() + assert precious.read_text() == "someone else's data" + + +def test_the_socket_path_is_created_and_removed_around_the_run(workdir, serve): + path = workdir / "nested" / "dir" / "s.sock" + with serve(str(path), FakeCapture(), fps=20): + assert path.is_socket() + assert not path.exists(), "the socket file outlived the server" + + +def test_stop_releases_the_client_threads(sock_path, serve): + with serve(sock_path, FakeCapture(frames=distinct_frames(5)), fps=30) as server: + conn = connect(sock_path) + stream = conn.makefile("rb") + protocol.read_hello(stream) + assert protocol.read_frame(stream) + server.stop() + deadline = time.monotonic() + 5 + while time.monotonic() < deadline: + if not any(t.name.startswith("hhstream-client") and t.is_alive() + for t in threading.enumerate()): + break + time.sleep(0.05) + else: + pytest.fail("a client thread outlived stop()") + conn.close() + + +def test_stopping_twice_does_not_delete_a_restarts_socket(sock_path, serve): + """A second stop() after a restart must not take the new server's socket.""" + first = FrameServer(sock_path, FakeCapture(), 20) + thread = threading.Thread(target=first.serve_forever, daemon=True) + thread.start() + assert first.ready.wait(5) + first.stop() + thread.join(5) + assert not os.path.exists(sock_path) + + with serve(sock_path, FakeCapture(), fps=20): # the "restart" + first.stop() # a late, duplicate stop from the old instance + assert os.path.exists(sock_path), "the restart's socket was removed" + conn = connect(sock_path) + assert protocol.read_hello(conn.makefile("rb"))["magic"] == "HHS1" + conn.close()