Files
hyprland-headless-stream-pl…/docs/CONTRACT.md
T
HermenixandClaude Opus 5 6510e315d4 module: make outputs monitor rules for real connectors, and own the seat flag
A machine running this module has a GPU. aquamarine's headless backend has
no allocator of its own -- `CHeadlessBackend::drmFD()` returns -1 and
`CBackend::start()` takes the allocator from the first backend with a drm fd
-- so the session always rides on the DRM backend and always has the host's
own connectors. `HEADLESS-1` is a name no connector will ever have, which
made the shipped default a monitor rule Hyprland silently ignored, and made
`vm-hyprland`'s assertion on that name unsatisfiable.

`outputs` now means "monitor rules applied to whatever outputs the machine
has". `name` is a regex against the real connector names and defaults to the
empty string -- Hyprland's own wildcard form, as in its shipped
`monitor=,preferred,auto,1` -- so `enable = true` alone gives a session at a
known size on any host. Nothing else about the option changed.

SEATD_VTBOUND=0 moves from checks/lib/gpu-session.nix into the compositor
unit, where it belongs: libseat finds no seatd socket and no logind session
for a system service, falls back to its embedded seatd, and that seat is
VT-bound by default -- so it opens /dev/tty0, which the service user cannot,
and every device open is refused. That is true on any host, not just in the
test. gpu-session.nix keeps only the two things that really are the test
machine's business: a render node and Mesa.

vm-hyprland now asserts over `hyprctl -j monitors` that at least one monitor
exists at the configured mode, with no monitor name anywhere in the check.
It also gains a wallpaper, because `--reject-blank` could not otherwise mean
anything: the session the module configures by default is a flat black
field, which grim captures as an all-zero 1280x720 RGBA PNG of exactly 3653
bytes -- `blank_png_size()` to the byte. Runs that passed that assertion were
reading Hyprland's startup notification overlay, which expires after about
fifteen seconds. With `misc:force_default_wallpaper` on, the frame is 85267
bytes with all 921600 pixels non-zero and is byte-identical at +15s, +30s and
+60s.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01M5GEju6XhoRXDWvEiaAX2r
2026-09-28 21:51:24 +00:00

5.7 KiB
Raw Blame History

Wire contract (v1)

This file is the interface. Code on either side may change freely; this document may not, without bumping the version.

Socket

  • Transport: AF_UNIX, SOCK_STREAM.
  • Path: whatever services.hyprland-headless-stream.socketPath says. Default /run/hyprland-headless-stream/stream.sock.
  • Ownership: the service user (user option, default hhstream), mode 0660.
  • The server accepts any number of concurrent clients. Each client gets its own copy of the header and of every subsequent frame. A client disconnecting (or dying mid-frame) must never take the server down and must never disturb the other clients.
  • The server runs whether or not anyone is connected. No client is privileged.
  • The socket path is removed and recreated on start; a stale socket file must not prevent startup.

Message sequence

1. Hello. Immediately on connect, the server writes exactly one UTF-8 JSON object followed by a single \n:

{"magic":"HHS1","width":1280,"height":720,"format":"image/png","fps":30}

Fields: magic (protocol tag, HHS1), width/height (pixels of the captured output), format (image/png or image/jpeg), fps (target capture rate, advisory — the server does not buffer to keep up).

2. Frames. Then, forever, one frame per message:

<ascii-decimal byte length><0x0A><payload — exactly that many bytes>

payload is one complete, independently decodable image in format.

Notes:

  • Byte length counts the payload only, never the length prefix.
  • The length prefix is plain ASCII digits; no leading zeros, no +, no spaces.
  • Frames are never split, merged or interleaved on the wire. One length, one payload.
  • A client that stalls or reads slowly is slowed, not queued: the server drops frames for that client rather than buffering them. Backpressure must never grow unbounded memory.
  • Shutdown: either side closes the socket. Nothing else is negotiated.

Client → server direction

Reserved. In v1 a client sends nothing; any bytes received from a client are read and ignored. (This leaves room to add a control channel later without breaking v1 readers, which never expect inbound data.)

Failure semantics

  • Compositor not running / capture tool erroring: the server keeps the socket up and retries; it does not exit and it does not send partial frames.
  • Hello timing. The Hello is written the moment the server can produce it, which in practice is the moment of the first successful capture. A client that connects before that has received zero bytes and simply waits: the server never sends a Hello with a zero or unknown size. ("Immediately" above means "before any frame", not "before the first capture".)
  • width/height in the Hello are measured from the captured frame, not taken from configuration, so they cannot disagree with the pixels actually being sent.
  • A client that is torn down or killed mid-frame may see a truncated final frame. "Never sends partial frames" is about the server failing to capture, not about a client that has already gone away.

NixOS module surface

Namespace: services.hyprland-headless-stream

Option Type Default Meaning
enable bool false turn everything on
socketPath str /run/hyprland-headless-stream/stream.sock published socket
user / group str hhstream owner of the session and the socket
frameRate int 30 capture target, becomes fps in Hello
format enum png/jpeg png frame encoding
outputs list of attrsets one 1280×720@30 rule with an empty name monitor rules applied to the outputs the machine has: name, width, height, refresh, scale. name is a regex matched against the real connector names (eDP-1, Virtual-1, …) and empty means every output; a name no connector has is silently ignored. The compositor never creates an output — a session started by this module drives the host's GPU.
extraConfig str "" extra lines appended to hyprland.conf
hyprlandPackage package pkgs.hyprland which compositor
package package the flake's own build the frame server/client
captureCommand list of str [ "grim" … ] override the capture backend — used by tests

Services (names are part of the contract, tests refer to them):

  • hyprland-headless.service — the compositor, running as user, on a private XDG_RUNTIME_DIR, with no physical output.
  • hyprland-headless-stream.service — the frame server, After= the compositor, with Restart=always, connected to the same session.

Server command line

The module drives the server, so its flags are an interface too — the same status as the wire format. Exactly this shape, and no others:

hhstream-server --socket <socketPath> --fps <frameRate> --format <png|jpeg> \
                [--capture-command <token> ...]
  • --format takes the short name (png, jpeg), not a MIME type; the server maps it to image/png / image/jpeg for the Hello.
  • --capture-command is repeated, one argv token per occurrence: --capture-command grim --capture-command -t --capture-command png --capture-command -. A single shell string cannot carry a leading - unambiguously. The --capture-command=<token> form is accepted as well, and the two may be mixed. When absent, the server derives grim -t <format> -.
  • There is deliberately no --width / --height: the Hello reports the captured frame's real size (see above).
  • The socket's mode (0660) is the server's business; its ownership is the systemd unit's (user/group), because the server cannot chown.