Files
hyprland-headless-stream-pl…/src/hhstream/server.py
T
HermenixandClaude Opus 5 4af6f7072a server, client: implement the v1 frame protocol end to end
Fill in the bodies the skeleton left as NotImplementedError, to docs/CONTRACT.md:

- protocol: the `\n`-terminated JSON Hello and the `<ascii length>\n<payload>`
  frame, both directions. Malformed input raises (ValueError for a bad length
  prefix, EOFError for a truncated payload), never hangs on endless garbage and
  never silently truncates; a huge length prefix is not pre-allocated.
- capture: CommandCapture runs the configured command and reports a missing
  binary, a non-zero exit, a timeout and empty output as CaptureError, with the
  helper's stderr folded into the message so nothing leaks to the server's own
  stdio. The Hello's pixel size is read from the frame's PNG/JPEG header, so no
  compositor query is needed and an injected fake command behaves the same.
- server: one capture thread holding only the newest frame plus one thread per
  client, which is what drops frames for a slow client instead of queueing
  them. Survives a client dying mid-write, keeps the socket up across capture
  failures, withholds the Hello until a size is known, replaces a stale socket
  file (but never a non-socket one) and publishes it mode 0660.
- client: fetch()/read_stream() and the CLI, with --out suffixing per frame.

--capture-command folds its separated form into `--flag=value` before argparse
sees it, so the contract's default `grim -t png -` can actually be passed: its
tokens start with a dash.

Unit tests under tests/unit cover framing round-trips (including a payload
containing `\n` and a zero-length frame), truncated and garbage prefixes, a
stalled client not blocking a second one, a client dying mid-frame, frames being
dropped rather than queued, and every capture failure mode. A fake capture
command stands in for grim, so nothing needs a compositor or a GPU. They are
deliberately not wired into flake.nix: `checks` belongs to another workstream.

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

403 lines
14 KiB
Python

"""The frame server: catches each client up, then feeds it every frame.
One thread per client is the simple design that satisfies the contract ("a
stalled client is slowed, not queued"): a client's socket is written to
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:
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."""
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:
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:
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"]