# 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`: ```json {"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: ``` <0x0A> ``` `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 `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. ## 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 --fps --format \ [--capture-command ...] ``` - `--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=` form is accepted as well, and the two may be mixed. When absent, the server derives `grim -t -`. - 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.