Files
hyprland-headless-stream-pl…/README.dev.md
HermenixandClaude Opus 5 de408e4b7f the surface: CLI verbs, the module's options, and three checks the compositor votes in
Everything below the CLI was merged and green against fakes; none of it was
reachable and none of it had ever met a compositor. This wires it up and then
puts the compositor in a position to disagree.

CLI (src/hhstream/cli.py, src/hhstream_session/**)

  session container [ID], session reconcile [ID], and the seven pointer verbs
  from PLAN §9. `start` still prints the bare session id and nothing else.
  `list` gains WS / OUTPUT / POINTER, with the gap marker where a value is
  genuinely unknown rather than a blank that reads as zero -- the POINTER
  column needs a second, read-only `pointer.state` call because the `list`
  reply carries no lease state.

  The lease id is cached in `hhstream_session.lease` (under
  $XDG_RUNTIME_DIR), because PLAN §9's gesture verbs take no --lease and the
  wire requires a lease_id on every one of them; --lease and $HHSTREAM_LEASE
  override it, and a `no_lease` refusal drops the stale entry.

  Exit codes are the contract's: a gesture with no lease is 9 and never
  reaches the broker, and a compositor failure is 10 with a message that says
  the session is still running. `kill` now warns about
  `session.container_survivors` -- windows the compositor still shows -- and
  distinguishes `null` ("could not ask") from `[]`.

  `shot`/`record --output NAME` capture one container through `grim -o`; the
  frame socket publishes the main output only, so it cannot do it.

Module (nix/module.nix)

  sessions.containers.{enable,max,mode,workspaceBase},
  sessions.pointer.{enable,leaseTtl,leaseMax}, rendered into the generated
  TOML with §10's key names. hhstream-pointer.service: the operator's account,
  supplementary group hhstream, After=/BindsTo= the compositor,
  Restart=on-failure, KillMode=process, and the command line §3.4 freezes.
  tmpfiles for /run/hhstream plus RuntimeDirectoryPreserve on the broker,
  without which restarting the broker deletes the driver's socket out from
  under it. The runtime-directory length assertion is untouched.

  And ExecStartPost on the compositor, opening its IPC directory to its own
  group: Hyprland creates <runtime>/hypr with S_IRWXU, so the broker -- a
  different account by design -- could not reach the request or event socket
  at all, and degraded silently exactly as it is built to.

Checks (checks/**)

  vm-ipc: both sockets at their frozen names, measured against sun_path's 108
  bytes, and a socket2 subscriber that receives an openwindow for a window the
  test creates. The subscriber is the shipped HyprlandIPC, not a second
  implementation: this check exists to prove that this client hears this
  compositor.

  vm-containers: one hh-* output per session at the container mode, the window
  on it, a second window of the same application beside it, an unmatched
  window quarantined, grim -o isolating one container, teardown removing the
  output and freeing the slot. PLAN experiment 3 is answered: `hyprctl output
  create headless` works.

  vm-pointer: a version-2 virtual pointer, a warp and a click whose
  coordinates the *application* reports, BUSY naming the holder, an expired
  lease swept with its held button lifted, and a broker restart that leaves
  the lock free, the bookmark intact and the driver reachable.

  checks/lib gains the guest the three share, their test-script helpers (no
  assertions live there), an event-socket subscriber and a Wayland client that
  says where it was clicked -- nothing in nixpkgs both honours
  $HHSTREAM_APP_ID and reports pointer events.

Reported, not worked around: the broker reads none of the container or
pointer config (policy.py takes [defaults] and [apps] only), `start` has no
no_container field so --no-container is refused rather than silently ignored,
and nix/hyprland-conf.nix sets input:follow_mouse = 0, which sends pointer
events to the focused window only -- measured, with the cursor at the aimed
pixel and no client told. README.dev.md has the evidence for each.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WQy29x9AfHWyzNd1f7XPGK
2026-10-03 06:58:44 +00:00

17 KiB

Developing and testing hyprland-headless-stream-plugin

The interface everything here asserts is docs/CONTRACT.md. That document is authoritative: if a test and the code disagree, the document decides, and if the document is wrong it gets a version bump, not an edit.

Prerequisites

  • Nix with flakes enabled.
  • /dev/kvm readable, for the six VM checks. They are nixosTests; without KVM they still run, just slowly enough that the timeouts below get tight.
  • No GPU. Nothing in the test suite needs one — the compositor runs on Hyprland's headless backend over software rendering.

Nothing in the checks touches the host: no /etc/nixos, no network, and no socket outside the build sandbox or the test VM.

The dev shell

nix develop

Puts python3, pytest, hyprland, grim, ffmpeg, jq and tmux on PATH and sets PYTHONPATH=$PWD/src, so import hhstream picks up the working tree rather than an installed copy.

Build

nix build .#hhstream          # the package
ls result/bin                 # hhstream-server, hhstream-client, hhstream,
                              # hhstreamd, hhstream-pointer

Five entry points: the frame server and a reference reader for it, the hhstream front-door CLI (frames, run, and the session namespace), the session broker, and the pointer driver.

The checks

Check What it proves Needs a VM
unit the framing, the capture backend, the server's client handling, the broker, the CLI, the containers, the lease and the pointer driver — in-process, against the nix/package.nix build no
vm-basic the NixOS module brings up both units and publishes a contract-conformant socket, with a fake capture backend yes
vm-hyprland the same, capturing the real headless compositor through grim yes
vm-sessions the session broker: a real GUI application launched into the compositor as a tracked session, seen by the compositor's own IPC, killed as a tree, reaped on its idle deadline (and not reaped when touched), and adopted back after the broker restarts yes
vm-ipc the compositor's IPC: both sockets exist at the names docs/CONTRACT-sessions.md §5 freezes and fit inside sun_path, hyprctl answers, the broker's own HyprlandIPC reaches it, and a subscriber on the event socket receives an openwindow for a window the test creates yes
vm-containers one hh-* output per session at the container mode, the application's window on it, a second window of the same application beside it, an unmatched window quarantined, grim -o capturing that container alone, and teardown removing the output and freeing its workspace slot yes
vm-pointer the lease and the driver: a version-2 virtual pointer, a warp that lands where it was aimed as the application reports it, a click delivered as one press and one release, a contended acquire refused with BUSY, an expired lease swept with its held button lifted, and a broker restart that leaves the lock free, the bookmark intact and the driver reachable yes

All of them at once:

nix flake check -L

nix flake check stops at the first failing check, which makes it a poor way to see the whole picture while the tree is still red. Run the VM checks one at a time anyway — each boots a guest with a software-rendered compositor, and two at once on a two-core machine make the timing-sensitive assertions flake. A flaky green is worth less than a slow one.

nix build -L .#checks.x86_64-linux.unit
nix build -L .#checks.x86_64-linux.vm-basic
nix build -L .#checks.x86_64-linux.vm-hyprland
nix build -L .#checks.x86_64-linux.vm-sessions
nix build -L .#checks.x86_64-linux.vm-ipc
nix build -L .#checks.x86_64-linux.vm-containers
nix build -L .#checks.x86_64-linux.vm-pointer

-L is not optional in practice: without it, Nix hides the build log, and the build log is the test report. Do not pipe a check into tail or grep: the pipeline's exit status is the last command's, so a build that cannot fail is not a test. Redirect to a file instead.

Each VM check's test script is type-checked before the guest boots, which is much cheaper than finding a typo after a five-minute boot:

nix build -L .#checks.x86_64-linux.vm-pointer.driver --no-link

Watch for names the driver already defines — log is an AbstractLogger in that namespace, and assigning a string to it is a type error, not a shadowing warning.

unit

pytest over tests/unit/, run in the build sandbox with PYTHONPATH pointing at what nix/package.nix installed (nix/package.nix sets doCheck = false on purpose, so this is the only place the suite runs in a build).

The check fails if the suite is empty, not just if it is red. pytest exits 5 on "collected nothing", but it exits 0 when every test was skipped or deselected, so checks/lib/check_report.py parses the JUnit report and refuses a run with zero collected or zero executed tests. A green check that tested nothing is worse than no check. On success the report is copied to result/junit.xml.

To run the same tests directly, without Nix:

nix develop
pytest tests/unit -v                      # PYTHONPATH=$PWD/src comes from the shell
pytest tests/unit/test_protocol.py -v     # one file
pytest tests/unit -k "hello or frame" -v  # one theme
pytest tests/unit -x --ff                 # stop at the first failure, failures first

Note that the unit suite's negative tests use the rejects fixture from tests/unit/conftest.py rather than pytest.raises(Exception). rejects treats NotImplementedError as a failure, because a plain raises(Exception) is satisfied by an unimplemented stub — the test would then be green precisely because nothing had been written.

vm-basic

Boots one machine with services.hyprland-headless-stream.enable = true and captureCommand pointed at tests/fake_capture.py, which writes one fixed, deterministic PNG of the configured size to stdout. Because the image never changes, "two frames arrived and they are the same bytes" is a real assertion about the framing rather than a coincidence.

It checks, in order: both units start; the socket exists and is hhstream:hhstream mode 0660; the Hello parses with magic = "HHS1" and non-zero width/height matching the configured output; two frames arrive with length > 0, identical bytes, and an IHDR matching the Hello; two clients are served concurrently; and a client that dies mid-frame leaves the server serving.

The reader is tests/assert_stream.py, a second, independent implementation of the contract that shares no code with hhstream.client — so a framing bug present in both the server's writer and the shipped client's reader still fails the test. It validates the length prefix strictly (0|[1-9][0-9]*: no leading zeros, no sign, no spaces), never reads past a newline, and prints the Hello, every frame's size and SHA-256, and the parsed IHDR before it decides anything.

vm-hyprland

The same machine with no captureCommand override, so the module's default (grim) captures the real compositor.

This is the check expected to be flaky, so it is deliberately impatient: every wait has a bounded timeout, nothing is retried in a loop, and any failure dumps diagnostics before it propagates. It asserts a frame is a valid PNG whose IHDR dimensions match the configured output, and that it is more than a blank buffer:

  • the IDAT must decompress;
  • the decompressed scanlines must contain a non-zero byte and at least two distinct byte values — a zero-filled framebuffer fails both;
  • the payload must be larger than a best-case blank PNG of the same geometry (blank_png_size() in tests/assert_stream.py: an all-zero raster at zlib level 9, i.e. the smallest a blank frame of that size can be encoded).

It also runs grim directly against the session as a separate subtest, which separates "grim cannot see the compositor" from "the server is wrong" — the two failures that look identical from the socket.

When vm-hyprland fails: where the logs are

Every failing subtest in both VM checks runs hhs-hyprland-diagnostics (tests/hyprland_diagnostics.sh) in the guest first and prints its output to the build log. So the answer to "where are the logs" is usually in the build log you already have, above the traceback, between ########## diagnostics: ... ########## markers. Re-read it with:

nix log .#checks.x86_64-linux.vm-hyprland

What the dump contains, and where it comes from in the guest:

Section Source
units systemctl list-units --all 'hyprland*'
per-unit status / journalctl hyprland-headless.service and hyprland-headless-stream.service, 200 lines each
socket and runtime directories /run/hypr-stream, /run/user/*
hyprland logs every hyprland*.log found under /run, /var/log, /tmp, /home
hyprctl monitors run once per instance found, with the right XDG_RUNTIME_DIR and HYPRLAND_INSTANCE_SIGNATURE
processes ps aux filtered to hypr, hhstream, grim

Hyprland writes its log to $XDG_RUNTIME_DIR/hypr/$HYPRLAND_INSTANCE_SIGNATURE/hyprland.log, and the compositor runs on a private XDG_RUNTIME_DIR, so the path is not knowable in advance — that is why the script searches for it rather than naming it. The instance signature is the directory name under <runtime>/hypr, which is also what hyprctl needs in the environment:

XDG_RUNTIME_DIR=/run/user/$(id -u hhstream) \
HYPRLAND_INSTANCE_SIGNATURE=$(ls /run/user/$(id -u hhstream)/hypr | head -1) \
  hyprctl monitors

Poking at a live VM

The nicest way to debug a VM failure is to keep the machine:

nix build .#checks.x86_64-linux.vm-hyprland.driverInteractive
./result/bin/nixos-test-driver

That drops you in a Python REPL with machine bound. start_all(), then machine.shell_interact() for a root shell in the guest, or run the test script a line at a time. machine.succeed("hhs-hyprland-diagnostics") works there too.

Layout

checks/
  default.nix            wiring only: the checks the flake exposes
  unit.nix               pytest in the sandbox, against the nix/package.nix build
  vm-basic.nix           nixosTest, fake capture backend
  vm-hyprland.nix        nixosTest, real compositor + grim
  vm-sessions.nix        nixosTest, the broker's lifecycle against the compositor
  vm-ipc.nix             nixosTest, the compositor's request and event sockets
  vm-containers.nix      nixosTest, one output and one workspace per session
  vm-pointer.nix         nixosTest, the lease, the driver and a click that lands
  lib/test-tools.nix     packages the tests/ helpers for the guest
  lib/session-tools.nix  packages the two guest programs below
  lib/session-machine.nix  the guest the three session checks share
  lib/session-prelude.nix  their test-script helpers (no assertions live here)
  lib/gpu-session.nix    the hardware a bare test machine does not have
  lib/check_report.py    JUnit report -> build verdict (and the empty-suite guard)
  lib/ipc_watch.py       subscribes to the event socket: hhs-ipc-watch
  lib/pointer_target.py  a Wayland window that reports pointer events it receives:
                         hhs-pointer-target
tests/
  fake_capture.py        writes one fixed PNG to stdout: hhs-fake-capture
  assert_stream.py       independent contract reader/asserter: hhs-assert-stream
  hyprland_diagnostics.sh  the failure dump: hhs-hyprland-diagnostics
  unit/ ipc/ containers/ pointer/ sessions/   the pytest suite

checks/lib/test-tools.nix and checks/lib/session-tools.nix self-test their programs at build time (the fake emits a PNG of the size it was asked for; the asserter starts; the event subscriber can import the broker's IPC client; the pointer target refuses to start without an app id), because a broken helper otherwise surfaces as a baffling failure three layers away.

hhs-ipc-watch deliberately runs the shipped hhstreamd.ipc.HyprlandIPC rather than a second implementation — the opposite choice from tests/assert_stream.py. The difference is what each proves: assert_stream asserts a wire format two programs must agree on, so a shared bug must still fail it; vm-ipc asserts that this client receives events from this compositor, which a reimplementation could not say anything about.

hhs-pointer-target exists because no application in nixpkgs does both of the things the session checks need: set its xdg_toplevel app id from $HHSTREAM_APP_ID (so its window matches its session's container rule) and print the pointer events it receives with the coordinates it was given. foot and wev do neither and ignore the environment entirely, which makes them good unmatched windows and useless as matched ones.

Adding a unit test: drop a test_*.py under tests/. Nothing needs registering, but the basename must be unique across the tree. Adding a check: one file in checks/, one line in checks/default.nix.

Known gaps in the interface (as of this branch)

Every item the previous revision of this section listed is closed: the module has a config side, package has a default, src/hhstream/*.py is written, and the frame server's command line is the one the module passes. What is open is below. These are defects in code this branch does not own; they are recorded here because the checks are written against the contract and therefore trip over them.

  1. The broker reads none of the container or pointer configuration. nix/module.nix renders sessions.containers.{max,mode,workspaceBase} and sessions.pointer.{leaseTtl,leaseMax} into the generated TOML as PLAN §10 names them, and hhstreamd/policy.py:policy_from_dict reads only [defaults] and [apps]. hhstreamd/__main__.py:serve builds its ManagerConfig from command-line flags that have no counterpart for any of those numbers either, so the broker runs on its own defaults (band 1000, 4 slots, 1280x720, lease 30 s / 300 s).

    Those defaults agree with the module's, so a deployment that leaves the options alone behaves as documented; one that changes them is ignored. vm-pointer prints the module's leaseTtl beside the TTL the broker reports, so the discrepancy is visible in the build log rather than inferred. The fix is in policy.py and __main__.py, not here.

  2. session start --no-container is refused, not honoured. PLAN §9 lists the flag; docs/CONTRACT-sessions.md §4 leaves start unchanged, and SessionManager.start takes no such argument. A request carrying a no_container field would be accepted and ignored, and the session would get a container anyway — so the CLI exits 2 and names the disagreement instead of lying about what it did.

  3. nix/hyprland-conf.nix sets input:follow_mouse = 0, and that stops pointer input reaching anything but the focused window. The comment justifying it — "No pointer will ever exist; do not let focus depend on one" — was true before this build and is false now.

    Measured by vm-pointer, with two sessions and the second holding focus because its window opened last:

    aimed at target-le22h7: it reports []     <- the session the warp named
    focused is  target-s76taj: it reports []  <- the session with focus
    cursor now at {'x': 2048, 'y': 288}       <- exactly where it was aimed
    

    The compositor moved the cursor to the right pixel, inside the right window, on the right output, and told no client at all. Every warp and click in the subtests before that one is delivered perfectly, because there the aimed-at session is also the focused one — which is why nothing noticed until a check put two sessions on the screen at once.

    It defeats the point of containers and the lease: an agent could only drive whichever session the compositor last focused. vm-pointer overrides the single line through the module's extraConfig and asserts the property that fails without it, so the check is green and the defect is still visible. The fix is one line in nix/hyprland-conf.nix; whether it should be 1 (Hyprland's own default, keyboard focus follows the cursor too) or a looser setting that leaves keyboard focus alone is a decision for the keyboard work in PLAN §6.7.

  4. A container's window rule only binds for an application that reads the environment. The broker's only lever on an application's class is $HHSTREAM_APP_ID and the three toolkit variables beside it (hhstreamd/launcher.py), so a GTK or Qt application — and foot, and wev — keeps its own class, matches no per-session rule, and is swept into the quarantine workspace. That is reported by the read-back rather than papered over, and it is why vm-containers and vm-pointer use a cooperating client (hhs-pointer-target) for the matched case and foot for the unmatched one. Closing it needs a per-app --app-id in the allowlist, which is a policy change.