M0 of the sessions design, wired into the flake and gated by a real check. What is here now: - `src/hhstreamd/` — the broker: session registry, lifecycle verbs, process-group teardown, app allowlist, audit log, idle reaper on CLOCK_BOOTTIME. - `src/hhstream_session/` — the CLI handlers, registered into the one front door. - `src/hhstream/cli.py` — `hhstream status|shot|run|record|session …`, so the frame verbs and the session namespace are one binary. - `nix/module.nix` — `sessions.*` options and the `hhstream-sessions.service` unit: the operator's own account (never a service account, because launched applications should see that account's home), the compositor's group as a supplementary group (without it a launched GUI client cannot open the Wayland socket), the generated app allowlist, and `--compositor-runtime-dir` so applications are handed the compositor's session rather than the broker's. - `checks/vm-sessions.nix` — 18 subtests on a real compositor in a VM. Two bugs found by driving it, both fixed: - BUG-01: launched applications could not reach the compositor at all — the broker spawned them with its own inherited environment, which names the login session. `hhstreamd/compositor.py` discovers the socket and builds the child environment; a directory with no usable socket is a startup refusal, not a warning. - BUG-02: `kill` refused to signal a live application and said nothing was wrong. The identity gate hashed `/proc/<pid>/cmdline`, which every `execve` replaces — and on NixOS applications are reached through wrapper scripts that do exactly that. The gate now rests on `starttime` (+ boot id, + session id where it is immutable) and records command-line drift as evidence of nothing. KillMode=process is set on the unit on purpose: the default control-group kill would take the applications down with the broker, which would make adoption and a broker restart pointless.
4.5 KiB
Architecture
┌──────────────────────────────────────────┐
│ hyprland-headless.service │
│ Hyprland 0.56.2, no physical monitor │
│ private XDG_RUNTIME_DIR, as `user` │
│ outputs come from `outputs[]` │
└───────────────┬──────────────────────────┘
│ Wayland session
▼
┌──────────────────────────────────────────┐
│ hyprland-headless-stream.service │
│ hhstream-server │
│ capture ──▶ one "latest frame" slot │
│ accept ──▶ a thread per client │
└───────────────┬──────────────────────────┘
│ AF_UNIX, mode 0660
▼
many clients ── hhstream-client / any socket reader
Three pieces, deliberately separate:
- The compositor (
Hyprland, unchanged upstream) renders into virtual outputs. It knows nothing about frames on a socket. - The frame server (
hhstream) captures, holds exactly one frame, and publishes it. It owns the socket, the framing and the drop policy. - The client is any process that can open a Unix socket and read the
contract's byte format. The shipped
hhstream-clientis a convenience, not a requirement.
Why one frame, not a queue
The server keeps a single slot holding the most recent frame. Each client thread
sends whatever is in that slot when it is ready. A client that cannot keep up
therefore misses frames instead of forcing the server to buffer them: memory use
does not grow with the number of stalled clients, and a stalled client cannot
delay the others. See docs/CONTRACT.md for exactly what a client observes.
Capture
Capturing is a separate program (by default grim, a wlr-screencopy client) run
inside the compositor's session and pointed at stdout. That choice is what keeps
hhstream free of Wayland and GPU code — the awkward part lives in a tool that
already exists and is already tested — and it is why the capture command is a
module option: tests inject a fake, and a future backend (a native screencopy
client, a hardware encoder) is a command-line swap rather than a rewrite.
The hardware requirement, stated plainly
Hyprland 0.56.2 asks aquamarine for its headless backend as mandatory
(src/Compositor.cpp) and does not accept the DRM backend if it is
unavailable. Aquamarine's headless backend still needs an EGL/GBM render
node; there is no software-only path that works without one. Consequently a
host with no graphics device at all (/dev/dri missing) cannot run this, and
Pyprland fails with CBackend::create() failed! before any of its managers come
up.
So the requirements are:
- a render node, i.e.
/dev/dri/renderD*— from a real GPU, a virtual GPU (virtio-gpu,virtio-gpu-gl, QXL) or a NixOS test VM's own QEMU display; - the
video/rendergroups for whichever user runs it (the module sets them).
Testing, and what each layer proves
| Layer | Proves |
|---|---|
tests/unit |
the framing, the capture wrapper and the server's client handling, with no compositor and no GPU |
checks.vm-basic |
the module actually starts both units, the socket appears with the right owner/mode, the Hello parses and two frames arrive — with a fake capture program |
checks.vm-hyprland |
the real thing: headless Hyprland comes up in the VM and grim captures a frame of the configured size |
checks.vm-sessions |
the session broker side: a real application runs as a tracked session on the compositor, the compositor's IPC sees its window, the idle reaper fires for real (and does not fire when the session is touched), and a broker restart adopts its sessions back |
vm-hyprland is the only check that can fail for reasons outside this repo, so
it is kept separate from vm-basic on purpose: when it fails, the compositor's
log is the answer and the other two layers are already known good.