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
Implements the `config` side of the module surface in docs/CONTRACT.md:
- `hhstream` user/group, and one private runtime directory shared by both
units (RuntimeDirectory= with Preserve=yes, so the Wayland socket survives
a restart of either side).
- A rendered hyprland.conf (nix/hyprland-conf.nix): one `monitor =` line per
`outputs` entry plus `extraConfig` verbatim, with the logo/splash, config
autoreload, DPMS, cursor, animations, shadows and the update/donation and
guiutils/XDG checks switched off -- none of them mean anything in a session
with no seat, no input device and no user. Validated with
`Hyprland --verify-config`.
- `hyprland-headless.service`: Hyprland as the service user, Type=notify (it
sends READY=1), Restart=always, and deliberately no WAYLAND_DISPLAY or
DISPLAY in the environment so the compositor cannot pick a nested backend
and falls back to headless.
- `hyprland-headless-stream.service`: hhstream-server as the same user,
After=/BindsTo= the compositor, Restart=always, with --socket/--fps/
--format/--capture-command on the command line.
`outputs.*.scale` used `lib.types.positive`, which does not exist in nixpkgs
and made the whole `outputs` option unreadable; it is now
`lib.types.numbers.positive`. `package` gets its documented default (the
flake's own build) via mkDefault on the config side, so the declared option
surface is otherwise untouched.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015pS3JxTJZBufyBKwimwBxy