Files
hyprland-headless-stream-pl…/docs/CONTRACT.md
T
2026-09-28 05:01:41 +00:00

3.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.
  • If a Hello cannot be produced (no output size known yet), the server waits until it can, then sends it. It never sends a Hello with zero size.

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 HEADLESS-1 virtual monitors: name, width, height, refresh, scale
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.