Compare commits

..
Author SHA1 Message Date
HermenixandClaude Opus 5 6510e315d4 module: make outputs monitor rules for real connectors, and own the seat flag
A machine running this module has a GPU. aquamarine's headless backend has
no allocator of its own -- `CHeadlessBackend::drmFD()` returns -1 and
`CBackend::start()` takes the allocator from the first backend with a drm fd
-- so the session always rides on the DRM backend and always has the host's
own connectors. `HEADLESS-1` is a name no connector will ever have, which
made the shipped default a monitor rule Hyprland silently ignored, and made
`vm-hyprland`'s assertion on that name unsatisfiable.

`outputs` now means "monitor rules applied to whatever outputs the machine
has". `name` is a regex against the real connector names and defaults to the
empty string -- Hyprland's own wildcard form, as in its shipped
`monitor=,preferred,auto,1` -- so `enable = true` alone gives a session at a
known size on any host. Nothing else about the option changed.

SEATD_VTBOUND=0 moves from checks/lib/gpu-session.nix into the compositor
unit, where it belongs: libseat finds no seatd socket and no logind session
for a system service, falls back to its embedded seatd, and that seat is
VT-bound by default -- so it opens /dev/tty0, which the service user cannot,
and every device open is refused. That is true on any host, not just in the
test. gpu-session.nix keeps only the two things that really are the test
machine's business: a render node and Mesa.

vm-hyprland now asserts over `hyprctl -j monitors` that at least one monitor
exists at the configured mode, with no monitor name anywhere in the check.
It also gains a wallpaper, because `--reject-blank` could not otherwise mean
anything: the session the module configures by default is a flat black
field, which grim captures as an all-zero 1280x720 RGBA PNG of exactly 3653
bytes -- `blank_png_size()` to the byte. Runs that passed that assertion were
reading Hyprland's startup notification overlay, which expires after about
fifteen seconds. With `misc:force_default_wallpaper` on, the frame is 85267
bytes with all 921600 pixels non-zero and is byte-identical at +15s, +30s and
+60s.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01M5GEju6XhoRXDWvEiaAX2r
2026-09-28 21:51:24 +00:00
Hermenix 231fa317cb module: discover the Wayland socket instead of assuming wayland-0 2026-09-28 21:24:27 +00:00
HermenixandClaude Opus 5 a37b3dd485 checks: give both VM machines a virtio GPU, and say why when it is not enough
`nix build .#checks.x86_64-linux.vm-basic` failed because Hyprland 0.56.2
aborted with `CBackend::create() failed!` on every start. Reading aquamarine
0.15.1 rather than guessing at it, that abort had three independent causes on a
NixOS test machine, and none of them is visible in the journal until
`debug:disable_logs = false` is set -- Hyprland mutes aquamarine, so the abort
is all that survives. checks/lib/gpu-session.nix now supplies all three and
records the evidence for each:

  * `-vga virtio`, for a DRM render node. `virtualisation.graphics = false`
    still leaves QEMU's default bochs-drm adapter, which gives card0 and no
    renderD*. Measured in the guest: `-vga virtio` -> card0 + renderD128;
    `-device virtio-gpu-pci` only *adds* a card next to bochs-drm, so it would
    need `-vga none` beside it.

  * `hardware.graphics.enable`, so Mesa's GBM backends exist at all. Without it
    gbm_create_device() fails with "MESA-LOADER: failed to open dri:
    /run/opengl-driver/lib/gbm/dri_gbm.so" and aquamarine reports "Cannot open
    backend: no allocator available".

  * `SEATD_VTBOUND=0`, so libseat's embedded seatd hands out a seat with no VT.
    `CHeadlessBackend::drmFD()` returns -1 unconditionally, so the *only*
    source of an allocator is the DRM backend, which opens /dev/dri/card0
    through libseat -- and the default VT-bound seat needs /dev/tty0, which the
    unprivileged service user cannot open.

The diagnostics dump grows a "graphics devices" section (`ls -l /dev/dri`,
`cat /proc/fb`) and a "wayland socket vs WAYLAND_DISPLAY" section, so the next
machine that is missing a render node, or that binds a socket the frame server
is not waiting on, says so in three lines instead of timing out mutely.
vm-basic's `dump()` is now vm-hyprland's, which reports the exit status too.

vm-basic also gained `python3` in the guest: its last subtest shells out to a
python one-liner and had been dying on exit code 127 -- invisible until the
compositor got far enough to reach that subtest.

Neither check passes yet, and the two remaining blockers both live in
nix/module.nix, which this slice may not edit, so they are reported rather
than patched:

  * vm-basic stops at "the module's two units come up". The compositor is up
    and healthy; the frame server sits in ExecStartPre forever. The module
    hardcodes `waylandDisplay = "wayland-0"`, but Hyprland's socket loop is
    `// get socket, avoid using 0` over candidates 1..32 (src/Compositor.cpp),
    so the session binds wayland-1. Forcing WAYLAND_DISPLAY=wayland-1 in the
    guest was verified to carry vm-basic through every other subtest.

  * vm-hyprland stops at "the compositor reports the configured headless
    output" with "hyprctl never reported a HEADLESS-1 monitor". hyprctl reports
    `Monitor Virtual-1` at 1280x800 -- the virtio-gpu output. A HEADLESS-N
    output only exists after `hyprctl output create headless`, which the module
    never issues; Hyprland's own fallback output is named FALLBACK. The
    `monitor = HEADLESS-1, ...` line in hyprland.conf is a rule for a monitor
    that is never created.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018fJZYyS4pqxt2FC37JsFYd
2026-09-28 12:28:01 +00:00
Hermenix db886faa38 docs: pin the server command line in the contract; add ARCHITECTURE.md 2026-09-28 11:53:19 +00:00
Hermenix 578e14286d tests: merge the two unit-test conftests into one fixture set 2026-09-28 11:52:32 +00:00
Hermenix 72f359932a Merge branch 'slice/tests'
# Conflicts:
#	tests/unit/conftest.py
#	tests/unit/test_capture.py
#	tests/unit/test_client.py
#	tests/unit/test_protocol.py
#	tests/unit/test_server.py
2026-09-28 11:51:07 +00:00
Hermenix 0fb515cc83 Merge branch 'slice/module' 2026-09-28 11:50:51 +00:00
HermenixandClaude Opus 5 75a05cd72f tests: checks.{unit,vm-basic,vm-hyprland} + the harness behind them
Wires a `checks` output into the flake, one file per check under checks/,
all three asserting docs/CONTRACT.md rather than the implementation:

- unit: pytest over tests/unit/ in the build sandbox, against the
  nix/package.nix build. Refuses an empty suite -- pytest exits 0 when
  every test was skipped or deselected, so checks/lib/check_report.py
  parses the JUnit report and fails on zero collected or zero executed.
- vm-basic: nixosTest with captureCommand pointed at tests/fake_capture.py,
  which emits one fixed deterministic PNG. Because the image never changes,
  "two frames arrived and they are the same bytes" is an assertion about
  the framing rather than a coincidence.
- vm-hyprland: the same machine with no captureCommand override, so grim
  captures the real compositor. Deliberately impatient -- bounded timeouts,
  no retry loops, and a full diagnostics dump (compositor log, hyprctl
  monitors, both journals) before any failure propagates.

tests/assert_stream.py is a second, independent reader of the contract: it
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 unit
suite's negative tests use a `rejects` fixture instead of
pytest.raises(Exception), which an unimplemented stub's
NotImplementedError would otherwise satisfy.

Three defects found in code this branch does not own, recorded in
README.dev.md rather than worked around:
- nix/module.nix has no config side, so neither unit exists and both VM
  checks fail at their first wait;
- services.hyprland-headless-stream.package is declared with no default,
  against docs/CONTRACT.md;
- src/hhstream/*.py is all stubs, so 66 of 70 unit tests fail.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017YXMoCNxzScTaKNr43GQNz
2026-09-28 05:25:37 +00:00
HermenixandClaude Opus 5 464c93e8f4 module: wire up the headless session and the frame server
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
2026-09-28 05:20:16 +00:00
19 changed files with 2193 additions and 27 deletions

No files matched your search

+241
View File
@@ -0,0 +1,241 @@
# Developing and testing `hyprland-headless-stream-plugin`
The interface everything here asserts is [`docs/CONTRACT.md`](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 two VM checks. They are `nixosTest`s; 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
```bash
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
```bash
nix build .#hhstream # the package (server + client)
ls result/bin # hhstream-server, hhstream-client
```
Both entry points currently exit with `NotImplementedError` — see "Known gaps"
at the bottom. The package builds; it does not yet run.
## The checks
| Check | What it proves | Needs a VM |
|---|---|---|
| `unit` | the framing, the capture backend, the server's client handling, the client — 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 |
All three at once:
```bash
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. Prefer running them
individually — they are independent:
```bash
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
```
`-L` is not optional in practice: without it, Nix hides the build log, and the
build log *is* the test report.
### `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:
```bash
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:
```bash
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/hyprland-headless-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:
```bash
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:
```bash
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 three 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
lib/test-tools.nix packages the tests/ helpers for the guest
lib/check_report.py JUnit report -> build verdict (and the empty-suite guard)
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/ the pytest suite
```
`checks/lib/test-tools.nix` self-tests the two Python helpers at build time
(the fake emits a PNG of the size it was asked for; the asserter starts), because
a broken helper otherwise surfaces as a baffling failure three layers away.
Adding a unit test: drop a `test_*.py` in `tests/unit/`. Nothing needs
registering. Adding a check: one file in `checks/`, one line in
`checks/default.nix`.
## Known gaps in the interface (as of this branch)
These are defects in code this branch does not own; they are recorded here
because the tests are written against the contract and therefore trip over them.
1. **`nix/module.nix` has no `config` side yet.** Neither
`hyprland-headless.service` nor `hyprland-headless-stream.service` exists, so
both VM checks fail at their first wait with
`Unit hyprland-headless.service could not be found.` Nothing in `checks/`
works around this.
2. **`services.hyprland-headless-stream.package` is declared with no default.**
`docs/CONTRACT.md` says the default is "the flake's own build", but the option
has no `default`, so reading it fails with
```
error: The option `services.hyprland-headless-stream.package' was accessed but
has no value defined. Try setting the option.
```
Today that only bites code that reads `cfg.package`, which the unwritten
`config` side does not yet do; it will bite every consumer that sets only
`enable = true` the moment it does. Both VM checks set `package` explicitly.
3. **`src/hhstream/*.py` is stubs.** Every function raises
`NotImplementedError`, so 66 of the 70 unit tests fail. The 4 that pass are
`tests/unit/test_package.py`, which only reads constants — they are the
canary for the `unit` check's own wiring.
4. **The frame server's command line is unspecified.** `docs/CONTRACT.md` fixes
the module's option surface and the wire format but never says how the module
invokes `hhstream-server`. `tests/unit/test_server.py::test_build_parser_exposes_the_options_the_module_needs`
currently assumes `--socket PATH --fps N --format png -- <captureCommand...>`.
That is a guess; if the module ends up passing something else, that one test
is the thing to change, not the server.
+3 -1
View File
@@ -19,7 +19,9 @@ Two parts:
imports = [ inputs.hhstream.nixosModules.default ];
services.hyprland-headless-stream = {
enable = true;
outputs = [ { name = "HEADLESS-1"; width = 1280; height = 720; refresh = 30; } ];
# Optional: the default is one 1280x720@30 rule with an empty name, which
# is Hyprland's wildcard and applies to whatever outputs the GPU has.
outputs = [ { width = 1920; height = 1080; refresh = 60; } ];
};
}
```
+28
View File
@@ -0,0 +1,28 @@
# The flake's `checks` output. One file per check; this is only the wiring.
#
# unit -- pytest over tests/unit/, against the nix/package.nix build
# vm-basic -- nixosTest with a fake capture backend: module + wire contract
# vm-hyprland -- nixosTest with the real compositor and grim
#
# Everything the guests need lives in checks/lib/test-tools.nix.
{
pkgs,
self,
system,
}:
let
hhstream = self.packages.${system}.hhstream;
hhsModule = self.nixosModules.default;
testTools = pkgs.callPackage ./lib/test-tools.nix { };
in
{
unit = pkgs.callPackage ./unit.nix { inherit hhstream; };
vm-basic = pkgs.callPackage ./vm-basic.nix {
inherit hhstream hhsModule testTools;
};
vm-hyprland = pkgs.callPackage ./vm-hyprland.nix {
inherit hhstream hhsModule testTools;
};
}
+90
View File
@@ -0,0 +1,90 @@
#!/usr/bin/env python3
"""Turn a pytest JUnit report into a build verdict.
Two jobs pytest's exit code alone does not do well inside a Nix build:
* say out loud how many tests ran, and which ones failed, in the build log;
* refuse a suite that collected nothing. An empty suite exits 5, but it also
exits 0 if every test was deselected or skipped away, and a check that passes
because it tested nothing is worse than no check at all.
Exit codes: 0 all good, 1 the suite is empty or the report is unusable,
2 the suite ran and some tests failed. The caller distinguishes them so the
build log does not accuse an empty suite of being a failing one.
"""
from __future__ import annotations
import sys
import xml.etree.ElementTree as ET
def main(argv: list[str]) -> int:
if len(argv) != 2:
print("usage: check_report.py <junit.xml>", file=sys.stderr)
return 2
path = argv[1]
try:
root = ET.parse(path).getroot()
except FileNotFoundError:
print(
f"ERROR: pytest wrote no report at {path}: it collected nothing, or died "
"before it could run a single test.",
file=sys.stderr,
)
return 1
except ET.ParseError as exc:
print(f"ERROR: {path} is not parseable JUnit XML: {exc}", file=sys.stderr)
return 1
suites = root.findall("testsuite") or ([root] if root.tag == "testsuite" else [])
total = errors = failures = skipped = 0
failing: list[str] = []
for suite in suites:
total += int(suite.get("tests", 0))
errors += int(suite.get("errors", 0))
failures += int(suite.get("failures", 0))
skipped += int(suite.get("skipped", 0))
for case in suite.iter("testcase"):
for kind in ("failure", "error"):
for node in case.findall(kind):
name = f"{case.get('classname', '')}::{case.get('name', '')}"
message = (node.get("message") or "").splitlines()
head = message[0][:160] if message else node.get("type", kind)
failing.append(f" {kind.upper():7} {name}\n {head}")
executed = total - skipped
print(
f"unit suite: {total} collected, {executed} executed, "
f"{failures} failed, {errors} errored, {skipped} skipped"
)
if total == 0:
print(
"ERROR: the unit suite collected no tests. An empty suite is not a "
"passing suite -- check that tests/unit/ is in the build and that the "
"files are named test_*.py.",
file=sys.stderr,
)
return 1
if executed == 0:
print(
f"ERROR: all {total} collected tests were skipped; nothing was actually "
"exercised.",
file=sys.stderr,
)
return 1
if failing:
print(f"\n{len(failing)} failing test(s):")
for line in failing:
print(line)
return 2
print("unit suite: all executed tests passed")
return 0
if __name__ == "__main__":
sys.exit(main(sys.argv))
+53
View File
@@ -0,0 +1,53 @@
# What a NixOS test machine has to be given before Hyprland 0.56.2 will start.
#
# Imported by both VM checks. It is a machine definition, not a test: nothing
# here relaxes anything either check asserts, it only supplies hardware and
# session facts that a default `nodes.machine` does not have.
#
# The failure it fixes is the same one every time -- the compositor aborts with
#
# terminate called after throwing an instance of 'std::runtime_error'
# what(): CBackend::create() failed!
#
# and systemd restarts it until the test's timeout expires. `CBackend::create()`
# is aquamarine's, and reading aquamarine 0.15.1 rather than guessing at it, it
# needs three separate things. Two of them are hardware the bare test machine
# does not have and are the blocks below; the third -- a seat that is not bound
# to a VT -- is true of this session on any host, so it lives in nix/module.nix
# as `SEATD_VTBOUND=0` on the compositor unit rather than here.
#
# A note for whoever hits this next: none of it is visible in the journal until
# you also set `debug:disable_logs = false`, because Hyprland mutes aquamarine
# by default and the abort is all that survives. That is how the three causes
# were separated.
{ ... }:
{
# 1. A DRM render node.
#
# `virtualisation.graphics = false` still leaves QEMU's default bochs-drm
# adapter in the guest, which offers /dev/dri/card0 and *no* renderD*. Measured
# in the guest, not assumed:
#
# (default) card0 (bochs-drm)
# -vga virtio card0, renderD128 (virtio_gpu)
# -device virtio-gpu-pci card0, card1, renderD128 (bochs + virtio)
# -vga none -device virtio-gpu-pci card0, renderD128 (virtio_gpu)
#
# `-vga virtio` *replaces* the default adapter, so it is the one-option form of
# the last line. `-device virtio-gpu-pci` on its own only *adds* a second card
# next to bochs-drm, so it would need `-vga none` beside it to leave the guest
# with a single DRM device.
virtualisation.qemu.options = [ "-vga virtio" ];
# 2. Mesa, where the GBM loader looks for it.
#
# aquamarine's allocator is gbm_create_device() on that node. On NixOS the GBM
# backends live under /run/opengl-driver, which only exists when
# hardware.graphics is enabled -- a test machine has it off. Without it:
#
# MESA-LOADER: failed to open dri: /run/opengl-driver/lib/gbm/dri_gbm.so:
# cannot open shared object file: No such file or directory
# ERR from aquamarine ]: Couldn't open a GBM device at fd 21
# CRIT from aquamarine ]: Cannot open backend: no allocator available
hardware.graphics.enable = true;
}
+32
View File
@@ -0,0 +1,32 @@
# The helper programs the checks need inside the guest (and, for the fake
# capture, inside the guest's `captureCommand`). Plain python3/sh scripts from
# `tests/`, put on PATH with their shebangs pointing at the store.
{
runCommandLocal,
python3,
coreutils,
gnugrep,
findutils,
systemd,
}:
runCommandLocal "hhstream-test-tools"
{
nativeBuildInputs = [ python3 ];
# hhs-hyprland-diagnostics runs on a failing guest, where PATH is whatever
# systemd left behind; give it the tools it needs explicitly.
diagPath = "${coreutils}/bin:${gnugrep}/bin:${findutils}/bin:${systemd}/bin";
meta.description = "Fake capture backend and contract asserter for the hhstream checks";
} ''
install -Dm755 ${../../tests/fake_capture.py} $out/bin/hhs-fake-capture
install -Dm755 ${../../tests/assert_stream.py} $out/bin/hhs-assert-stream
install -Dm755 ${../../tests/hyprland_diagnostics.sh} $out/bin/hhs-hyprland-diagnostics
patchShebangs $out/bin
substituteInPlace $out/bin/hhs-hyprland-diagnostics --replace-fail '@diagPath@' "$diagPath"
# A broken helper shows up as a baffling test failure three layers away, so
# prove here that both python programs start and produce what they promise.
$out/bin/hhs-fake-capture --width 8 --height 4 > frame.png
python3 -c 'import struct,sys; d=open("frame.png","rb").read(); assert d[:8]==b"\x89PNG\r\n\x1a\n", d[:8]; assert struct.unpack(">II", d[16:24])==(8,4), d[16:24]'
$out/bin/hhs-assert-stream --help > /dev/null
$out/bin/hhs-hyprland-diagnostics --self-test > /dev/null
''
+74
View File
@@ -0,0 +1,74 @@
# checks.<system>.unit -- the Python unit suite from tests/unit/, run against the
# package built by nix/package.nix, inside the build sandbox.
#
# nix/package.nix sets doCheck = false deliberately, so this is the only place
# the suite runs in a build.
{
lib,
runCommand,
python3,
hhstream,
}:
let
pytestEnv = python3.withPackages (ps: [ ps.pytest ]);
# Only the suite itself, so an editor's droppings or a local .pytest_cache
# cannot change the derivation's hash.
testSrc = lib.cleanSourceWith {
name = "hhstream-unit-tests";
src = ../tests/unit;
filter =
path: type:
let
base = baseNameOf (toString path);
in
!(type == "directory" && (base == "__pycache__" || base == ".pytest_cache"))
&& !lib.hasSuffix ".pyc" base;
};
in
runCommand "hhstream-unit"
{
nativeBuildInputs = [ pytestEnv ];
passthru.testSrc = testSrc;
meta.description = "hhstream unit tests (pytest)";
} ''
cp -r ${testSrc} suite
chmod -R u+w suite
# The package is an application, so its library is not on the default path:
# point PYTHONPATH at what nix/package.nix installed. Importing it here rather
# than letting pytest do it makes a packaging problem distinguishable from a
# test failure.
export PYTHONPATH=${hhstream}/${python3.sitePackages}
export PYTHONDONTWRITEBYTECODE=1
export HOME=$PWD
python3 -c 'import hhstream; print("testing hhstream", hhstream.__version__, "from", hhstream.__file__)'
set +e
pytest suite \
--color=no -rf -q \
--junit-xml=report.xml \
-p no:cacheprovider \
--strict-markers \
--strict-config
pytest_rc=$?
set -e
echo
set +e
python3 ${./lib/check_report.py} report.xml
report_rc=$?
set -e
if [ "$report_rc" -eq 1 ]; then
echo "unit check: the suite is empty or its report is unusable -- failing." >&2
exit 1
fi
if [ "$report_rc" -ne 0 ] || [ "$pytest_rc" -ne 0 ]; then
echo "unit check: the suite ran but did not pass (pytest exit $pytest_rc)." >&2
exit 1
fi
mkdir -p $out
cp report.xml $out/junit.xml
''
+161
View File
@@ -0,0 +1,161 @@
# checks.<system>.vm-basic -- boot a real machine with the module enabled, point
# `captureCommand` at a fake capture program, and read the socket.
#
# This check is about the module's wiring and the wire contract, not about
# Hyprland: the fake capture emits one fixed PNG, so "two frames arrived and
# they are the same image" is a real assertion rather than a coincidence.
{
testers,
hhstream,
testTools,
python3,
hhsModule,
width ? 1280,
height ? 720,
fps ? 30,
socketPath ? "/run/hyprland-headless-stream/stream.sock",
}:
testers.runNixOSTest {
name = "hhstream-vm-basic";
# KVM is available, so this is a minute or two; cap it so a hang is a failure
# rather than a wedged builder.
globalTimeout = 900;
nodes.machine = {
# gpu-session.nix is what makes the compositor able to start at all; see
# that file for the two pieces of hardware a bare test machine is missing
# (the third thing it used to carry, SEATD_VTBOUND=0, is in nix/module.nix
# now -- it is a property of the session, not of the test machine).
imports = [ hhsModule ./lib/gpu-session.nix ];
services.hyprland-headless-stream = {
enable = true;
# The module declares `package` with no default (see README.dev.md), so the
# test has to supply the flake's build.
package = hhstream;
inherit socketPath;
frameRate = fps;
format = "png";
# The fake capture fixes the frame size, so the monitor rule does not
# matter here -- but it must not be a name no connector has either, or
# this file would keep advertising a shape that does nothing.
outputs = [
{
inherit width height;
refresh = fps;
}
];
captureCommand = [
"${testTools}/bin/hhs-fake-capture"
"--width"
(toString width)
"--height"
(toString height)
];
};
environment.systemPackages = [
testTools
hhstream
# The "client dying mid-stream" subtest opens the socket from a python
# one-liner in the guest. hhstream's own interpreter is reachable only
# through its wrapper, so without this the subtest dies on exit code 127
# (`python3: command not found`) rather than on anything it asserts.
python3
];
# Mesa and the compositor together need more than the fake capture alone
# did; the GPU itself comes from gpu-session.nix.
virtualisation = {
memorySize = 2048;
cores = 2;
diskSize = 4096;
graphics = false;
};
};
testScript = ''
SOCKET = "${socketPath}"
ASSERT = "hhs-assert-stream --socket " + SOCKET
def dump(label):
print(f"########## diagnostics: {label} ##########")
status, out = machine.execute("hhs-hyprland-diagnostics", timeout=120)
print(out)
print(f"########## end diagnostics (exit {status}) ##########")
start_all()
with subtest("the module's two units come up"):
try:
machine.wait_for_unit("hyprland-headless.service", timeout=120)
machine.wait_for_unit("hyprland-headless-stream.service", timeout=120)
except Exception:
dump("units did not start")
raise
with subtest("the socket exists, owned by the service user, mode 0660"):
try:
machine.wait_for_file(SOCKET, timeout=60)
print(machine.succeed(f"stat -c 'owner=%U group=%G mode=%a type=%F' {SOCKET}"))
machine.succeed(f"[ \"$(stat -c %a {SOCKET})\" = 660 ]")
machine.succeed(f"[ \"$(stat -c %U {SOCKET})\" = hhstream ]")
machine.succeed(f"[ \"$(stat -c %G {SOCKET})\" = hhstream ]")
machine.succeed(f"[ \"$(stat -c %F {SOCKET})\" = socket ]")
except Exception:
dump("socket missing or wrong ownership")
raise
with subtest("the Hello parses, magic is HHS1, size is non-zero"):
try:
print(machine.succeed(f"{ASSERT} --frames 1 --timeout 30"))
except Exception:
dump("Hello did not parse")
raise
with subtest("two frames arrive, non-empty, byte-identical, matching the Hello"):
try:
print(
machine.succeed(
f"{ASSERT} --frames 2 --timeout 60"
" --expect-width ${toString width} --expect-height ${toString height}"
" --expect-format image/png --expect-fps ${toString fps}"
" --require-png --identical-frames --min-bytes 1"
)
)
except Exception:
dump("frames did not satisfy the contract")
raise
with subtest("two clients are served concurrently and independently"):
try:
print(
machine.succeed(
f"{ASSERT} --frames 3 --timeout 60 --require-png > /tmp/a.log 2>&1 & p1=$!; "
f"{ASSERT} --frames 3 --timeout 60 --require-png > /tmp/b.log 2>&1 & p2=$!; "
"wait $p1; r1=$?; wait $p2; r2=$?; "
"echo '--- client a ---'; cat /tmp/a.log; "
"echo '--- client b ---'; cat /tmp/b.log; "
"exit $((r1 + r2))"
)
)
except Exception:
dump("concurrent clients were not both served")
raise
with subtest("a client dying mid-stream leaves the server serving"):
try:
machine.succeed(
"timeout 5 python3 -c 'import socket;"
f"s=socket.socket(socket.AF_UNIX);s.connect(\"{SOCKET}\");s.recv(1);s.close()'"
)
print(machine.succeed(f"{ASSERT} --frames 2 --timeout 60 --require-png"))
machine.succeed("systemctl is-active hyprland-headless-stream.service")
except Exception:
dump("server did not survive a client dying mid-frame")
raise
'';
}
+235
View File
@@ -0,0 +1,235 @@
# checks.<system>.vm-hyprland -- the real one. Same machine as vm-basic, but no
# `captureCommand` override, so the server captures the actual headless
# compositor through grim.
#
# This is the check expected to be flaky, so it is deliberately impatient: every
# wait has a bounded timeout, no assertion is retried, and any failure dumps the
# compositor's log and `hyprctl monitors` before it propagates. A flake you can
# read is worth more than a flake that eventually goes green.
#
# There is exactly one waiting loop, and it waits for the compositor to finish
# starting (see "the session settles ..." below) rather than for an assertion to
# pass. Every assertion after it runs once.
{
testers,
hhstream,
testTools,
hhsModule,
hyprland,
grim,
width ? 1280,
height ? 720,
fps ? 30,
socketPath ? "/run/hyprland-headless-stream/stream.sock",
}:
testers.runNixOSTest {
name = "hhstream-vm-hyprland";
globalTimeout = 1800;
nodes.machine = {
# gpu-session.nix is what makes the compositor able to start at all; see
# that file for the two pieces of hardware a bare test machine is missing
# (the third thing it used to carry, SEATD_VTBOUND=0, is in nix/module.nix
# now -- it is a property of the session, not of the test machine).
imports = [ hhsModule ./lib/gpu-session.nix ];
services.hyprland-headless-stream = {
enable = true;
package = hhstream;
hyprlandPackage = hyprland;
inherit socketPath;
frameRate = fps;
format = "png";
# No `name`, so the module's wildcard rule applies to whatever connector
# the virtio GPU gives this guest. The check must not know that name: on
# QEMU it is `Virtual-1`, on a real host it is whatever the DRM backend
# reports, and a rule naming a connector that does not exist is silently
# ignored rather than an error.
outputs = [
{
inherit width height;
refresh = fps;
}
];
# No captureCommand: the module's default (grim) is the point of this check.
# Put a picture on the screen, so that `--reject-blank` below is an
# assertion and not a formality.
#
# The session the module configures by default is a flat field: no logo,
# no splash, no wallpaper, `background_color = 0x000000`. Measured in this
# guest, grim captures that as 1280x720 RGBA in which every byte is zero,
# encoding to *exactly* 3653 bytes -- which is `blank_png_size()` in
# tests/assert_stream.py to the byte. A flat field is by construction
# indistinguishable from a zero-filled buffer, so against the default
# config `--reject-blank` cannot pass, and any run in which it appears to
# is reading something transient (the startup notification overlay lives
# for about fifteen seconds and is 9739 bytes).
#
# Turning Hyprland's own wallpaper back on costs no new package and gives
# the compositor real content to composite: measured 85267 bytes, all
# 921600 pixels non-zero, byte-identical at +15s, +30s and +60s. That is
# what makes "the frame is not blank" mean "grim captured composited
# pixels".
extraConfig = ''
misc:force_default_wallpaper = 1
misc:disable_hyprland_logo = false
misc:disable_splash_rendering = false
'';
};
# hyprctl and grim are here for the diagnostics dump and for the manual
# cross-check below, not for the code path under test.
environment.systemPackages = [
testTools
hhstream
hyprland
grim
];
# The compositor needs more room than the fake capture did, and its software
# renderer wants a CPU. The virtio GPU from gpu-session.nix is there for its
# render node and its DRM backend, not for acceleration: rendering is still
# Mesa's software path.
virtualisation = {
memorySize = 2048;
cores = 2;
diskSize = 4096;
graphics = false;
};
};
testScript = ''
import json
SOCKET = "${socketPath}"
WIDTH, HEIGHT = ${toString width}, ${toString height}
# The module pins XDG_RUNTIME_DIR; the instance signature under it is the
# only part that is not known ahead of time. Root may connect to the
# compositor's IPC socket even though it belongs to `hhstream`.
HYPRCTL_MONITORS = (
"set -eu; "
"sig=$(ls -1 /run/hyprland-headless-stream/hypr | head -n1); "
"XDG_RUNTIME_DIR=/run/hyprland-headless-stream"
" HYPRLAND_INSTANCE_SIGNATURE=$sig hyprctl -j monitors"
)
def dump(label):
print(f"########## diagnostics: {label} ##########")
status, out = machine.execute("hhs-hyprland-diagnostics", timeout=120)
print(out)
print(f"########## end diagnostics (exit {status}) ##########")
start_all()
with subtest("the compositor unit comes up"):
try:
machine.wait_for_unit("hyprland-headless.service", timeout=180)
except Exception:
dump("hyprland-headless.service did not start")
raise
with subtest("the compositor reports a monitor at the configured mode"):
try:
# Proves the compositor is really driving a WIDTHxHEIGHT output
# before we blame the capture for a wrong-sized frame. Asked over
# hyprctl's JSON so the assertion is on the mode, never on a
# monitor name: the name belongs to the host's connector.
monitors = json.loads(machine.succeed(HYPRCTL_MONITORS, timeout=120))
print(json.dumps(monitors, indent=2, sort_keys=True))
assert monitors, "hyprctl reported no monitors at all"
print(
"monitors: "
+ ", ".join(
f"{m['name']} {m['width']}x{m['height']}@{m.get('refreshRate')}"
for m in monitors
)
)
assert any(
m["width"] == WIDTH and m["height"] == HEIGHT for m in monitors
), (
f"no monitor is at the configured {WIDTH}x{HEIGHT}; the wildcard "
"monitor rule did not take"
)
except Exception:
dump("compositor output not as configured")
raise
with subtest("the frame server unit comes up and publishes the socket"):
try:
machine.wait_for_unit("hyprland-headless-stream.service", timeout=180)
machine.wait_for_file(SOCKET, timeout=120)
except Exception:
dump("frame server did not publish the socket")
raise
with subtest("grim can capture the session at all"):
# Diagnostic, not an assertion: it separates "grim cannot see the
# compositor" from "the server is wrong", which are the two failures
# that look identical from the socket. The session's XDG_RUNTIME_DIR is
# the module's private one, not /run/user/<uid>, and the socket name is
# whatever the compositor bound -- so discover both, as the unit does.
# The grim path is the store one: a transient systemd unit gets a
# minimal PATH, not the guest's environment.systemPackages.
status, out = machine.execute(
"systemd-run --pipe --wait --uid=hhstream"
" --setenv=XDG_RUNTIME_DIR=/run/hyprland-headless-stream"
" --setenv=WAYLAND_DISPLAY=$(cd /run/hyprland-headless-stream"
" && ls -1 wayland-* | grep -v '\.lock$' | head -n1)"
" sh -c '${grim}/bin/grim -t png - > /tmp/direct.png' 2>&1",
timeout=120,
)
print(f"direct grim exit {status}: {out}")
print(machine.execute("stat -c 'direct.png: %s bytes' /tmp/direct.png")[1])
with subtest("the session settles into a frame with a picture in it"):
# A bounded wait for the *end of startup*, in the same spirit as
# wait_for_unit -- not a retry until something goes green. The Wayland
# socket is bound before the wallpaper texture has been uploaded and
# composited, so the very first frames off the socket can still be the
# empty field. Everything below this point is a hard assertion, made
# once, on a session that has finished coming up.
try:
machine.wait_until_succeeds(
f"hhs-assert-stream --socket {SOCKET} --frames 1 --timeout 30"
" --require-png --reject-blank",
timeout=120,
)
except Exception:
dump("the session never rendered anything but a blank field")
raise
with subtest("a frame off the socket is a real PNG of the configured size"):
try:
print(
machine.succeed(
f"hhs-assert-stream --socket {SOCKET} --frames 1 --timeout 60"
f" --expect-width {WIDTH} --expect-height {HEIGHT}"
" --expect-format image/png --require-png --reject-blank",
timeout=180,
)
)
except Exception:
dump("frame off the socket failed the PNG assertions")
raise
with subtest("the stream keeps producing frames"):
try:
print(
machine.succeed(
f"hhs-assert-stream --socket {SOCKET} --frames 3 --timeout 60"
f" --expect-width {WIDTH} --expect-height {HEIGHT}"
" --require-png --reject-blank",
timeout=240,
)
)
machine.succeed("systemctl is-active hyprland-headless-stream.service")
except Exception:
dump("the stream stopped after the first frame")
raise
'';
}
+76
View File
@@ -0,0 +1,76 @@
# 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:
1. **The compositor** (`Hyprland`, unchanged upstream) renders into virtual
outputs. It knows nothing about frames on a socket.
2. **The frame server** (`hhstream`) captures, holds exactly one frame, and
publishes it. It owns the socket, the framing and the drop policy.
3. **The client** is any process that can open a Unix socket and read the
contract's byte format. The shipped `hhstream-client` is 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`/`render` groups 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 |
`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.
+35 -4
View File
@@ -59,8 +59,17 @@ breaking v1 readers, which never expect inbound data.)
- 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.
- **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
@@ -73,7 +82,7 @@ Namespace: `services.hyprland-headless-stream`
| `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` |
| `outputs` | list of attrsets | one 1280×720@30 rule with an empty `name` | monitor rules applied to the outputs the machine has: `name`, `width`, `height`, `refresh`, `scale`. `name` is a regex matched against the real connector names (`eDP-1`, `Virtual-1`, …) and **empty means every output**; a name no connector has is silently ignored. The compositor never creates an output — a session started by this module drives the host's GPU. |
| `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 |
@@ -84,4 +93,26 @@ 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.
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 <socketPath> --fps <frameRate> --format <png|jpeg> \
[--capture-command <token> ...]
```
- `--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=<token>` form is accepted as well, and
the two may be mixed. When absent, the server derives `grim -t <format> -`.
- 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.
+8 -2
View File
@@ -8,6 +8,10 @@
outputs = { self, nixpkgs, ... }: let
systems = [ "x86_64-linux" "aarch64-linux" ];
forAllSystems = f: nixpkgs.lib.genAttrs systems (system: f (import nixpkgs { inherit system; }));
# `checks` needs the system name as well as the package set, to reach
# self.packages.<system>; forAllSystems only hands over pkgs.
forAllSystems' = f: nixpkgs.lib.genAttrs systems (system:
f { inherit system; pkgs = import nixpkgs { inherit system; }; });
in {
packages = forAllSystems (pkgs: rec {
hhstream = pkgs.callPackage ./nix/package.nix {};
@@ -19,8 +23,10 @@
default = hyprland-headless-stream;
};
# `checks` (unit tests + the VM integration test) is owned by the
# test-harness workstream -- see docs/CONTRACT.md for the interface.
# Unit tests + the two VM integration tests. See checks/default.nix and
# README.dev.md; the interface they assert is docs/CONTRACT.md.
checks = forAllSystems' ({ pkgs, system }:
import ./checks { inherit pkgs self system; });
devShells = forAllSystems (pkgs: {
default = pkgs.mkShell {
+105
View File
@@ -0,0 +1,105 @@
# The hyprland.conf for a session nobody sits in front of.
#
# Split out of module.nix so the rendering is readable on its own (and diffable
# when an output list changes). Returns the file *text*; the caller puts it in
# the store.
{
lib,
outputs,
extraConfig,
}: let
# `monitor = <name>, <width>x<height>@<refresh>, auto, <scale>` -- "auto"
# lets the compositor lay the outputs out left to right.
#
# The name is a *rule selector*, not an output the compositor will create: it
# is matched as a regex against the names the backend hands up (`eDP-1`,
# `Virtual-1`, ...). Hyprland never invents an output to satisfy a rule, so a
# name that no connector has is a rule that is silently ignored.
#
# An empty name is the wildcard form -- the same shape as Hyprland's own
# shipped `monitor=,preferred,auto,1` -- and applies to every output the
# machine actually has. That is what a session which does not know the host's
# connector names wants, and it is the module's default.
monitorLine = o: "monitor = ${o.name}, ${toString o.width}x${toString o.height}@${toString o.refresh}, auto, ${toString o.scale}";
in ''
# Generated by services.hyprland-headless-stream. Do not edit.
#
# There is no seat, no libinput device, no cursor and no human here: the only
# consumer of this session is the frame server. Everything below either sets
# the mode of the outputs this machine has or switches off something that
# assumes a user.
${lib.concatMapStringsSep "\n" monitorLine outputs}
misc {
# Nothing should draw itself over the captured output.
disable_hyprland_logo = true
disable_splash_rendering = true
force_default_wallpaper = 0
background_color = 0x000000
# The config lives in the store and never changes under us; watching it
# would only cost inotify watches on a read-only path.
disable_autoreload = true
# A virtual output has no variable refresh rate to negotiate.
vrr = 0
# DPMS on a virtual output is meaningless, and there is no key or pointer
# event coming to wake it back up.
key_press_enables_dpms = false
mouse_move_enables_dpms = false
# Both of these check for a desktop that is not here: the Qt helper
# dialogs, and the XDG portal environment.
disable_hyprland_guiutils_check = true
disable_xdg_env_checks = true
}
debug {
# Capture wants a steady frame rate. With variable frame rate the
# compositor only renders on damage, so an idle session would starve the
# stream.
vfr = false
# The session is a systemd unit: its log belongs in the journal, not in a
# file under a runtime directory nobody will look in.
enable_stdout_logs = true
colored_stdout_logs = false
}
cursor {
# No hardware planes, no cursor theme on disk, nobody to warp.
invisible = true
no_hardware_cursors = true
enable_hyprcursor = false
no_warps = true
hide_on_key_press = false
inactive_timeout = 0
}
input {
# No pointer will ever exist; do not let focus depend on one.
follow_mouse = 0
}
# Frames cost capture bandwidth and CPU, and no one is watching the easing.
animations {
enabled = false
}
decoration {
blur {
enabled = false
}
shadow {
enabled = false
}
}
# Nothing here may reach the network or nag a user who is not there.
ecosystem {
no_update_news = true
no_donation_nag = true
}
${lib.optionalString (extraConfig != "") "\n${extraConfig}"}''
+304 -18
View File
@@ -1,10 +1,139 @@
{ lib, config, pkgs, ... }:
# Interface only: every option in docs/CONTRACT.md is declared here so tests and
# consumers can be written against a stable surface. The systemd wiring is the
# next piece of work (see docs/CONTRACT.md -> "Services").
{
lib,
config,
pkgs,
...
}:
# The option surface below is the interface described in docs/CONTRACT.md
# ("NixOS module surface"); the `config` block wires it to the two services
# named there.
let
cfg = config.services.hyprland-headless-stream;
# One private runtime directory, shared by both units: it holds the Wayland
# socket of the session and, by default, the published frame socket too.
# `RuntimeDirectoryPreserve` keeps it (and the Wayland socket) alive across a
# restart of either unit.
runtimeDirName = "hyprland-headless-stream";
runtimeDir = "/run/${runtimeDirName}";
socketDir = builtins.dirOf cfg.socketPath;
# Hyprland refuses `--socket` unless it is paired with `--wayland-fd` (that
# pair is the socket-handover path), so the socket name is not ours to choose:
# the compositor calls wl_display_add_socket_auto, which takes the first free
# `wayland-N` starting at 0.
#
# N is therefore not fixed. The runtime directory is preserved across restarts
# (`RuntimeDirectoryPreserve=yes`), so a crashed compositor leaves its
# `wayland-0` behind and the next start binds `wayland-1` — measured in the VM
# test, where the frame server then waited forever for a socket that would
# never exist. Neither unit may hardcode the name:
#
# * the compositor clears leftover sockets first (the directory is private to
# this session, so nothing else can own them) — that alone makes it
# `wayland-0` again, but the units below do not depend on that;
# * the server discovers whichever socket is actually there.
clearStaleSockets = pkgs.writeShellScript "hhstream-clear-stale-sockets" ''
for stale in "$XDG_RUNTIME_DIR"/wayland-* "$XDG_RUNTIME_DIR"/wayland-*.lock; do
if [ -e "$stale" ]; then
${lib.getExe' pkgs.coreutils "rm"} -f "$stale"
fi
done
'';
# Exit 0 once *any* Wayland socket is bound, and print its name so callers that
# want it do not have to glob again.
findSession = pkgs.writeShellScript "hhstream-find-session" ''
for _ in $(${lib.getExe' pkgs.coreutils "seq"} 1 300); do
for candidate in "$XDG_RUNTIME_DIR"/wayland-*; do
if [ -S "$candidate" ]; then
echo "''${candidate##*/}"
exit 0
fi
done
${lib.getExe' pkgs.coreutils "sleep"} 0.1
done
echo "no Wayland socket in $XDG_RUNTIME_DIR after 30s; is the compositor up?" >&2
exit 1
'';
# The server needs WAYLAND_DISPLAY pointing at the socket the compositor
# actually bound. This cannot be an `Environment=` line, because the name is
# only known once the compositor is up — systemd's ExecStartPre cannot export
# into the main process.
execServer = pkgs.writeShellScript "hhstream-exec-server" ''
for candidate in "$XDG_RUNTIME_DIR"/wayland-*; do
if [ -S "$candidate" ]; then
export WAYLAND_DISPLAY="''${candidate##*/}"
break
fi
done
exec ${lib.getExe' cfg.package "hhstream-server"} "$@"
'';
hyprlandConf = pkgs.writeText "hyprland.conf" (import ./hyprland-conf.nix {
inherit lib;
inherit (cfg) outputs extraConfig;
});
# `BindsTo=` already stops the frame server when the compositor goes away, but
# the compositor is only *ready* once its Wayland socket is bound. The
# compositor unit is `Type=notify`, so `findSession` above is a second line of
# defence for compositor builds that do not sd_notify, and it is why this is
# not a plain `After=` ordering.
serverArgs =
[
"--socket"
cfg.socketPath
"--fps"
(toString cfg.frameRate)
"--format"
cfg.format
]
# One occurrence per argv word. The capture command is a list whose words
# start with `-` (`grim -t png -`), and repeating the flag is the only
# shape that survives that without inventing a quoting convention.
# `hhstream.server.build_parser()` is still a stub, so this is the one
# place the module guesses at the server's CLI rather than reading it.
++ lib.concatMap (word: ["--capture-command" word]) cfg.captureCommand;
# Shared by both units: a private session, no parent display to nest in.
sessionEnvironment = {
XDG_RUNTIME_DIR = runtimeDir;
HOME = runtimeDir;
XDG_SESSION_TYPE = "wayland";
};
commonServiceConfig = {
User = cfg.user;
Group = cfg.group;
RuntimeDirectory = runtimeDirName;
RuntimeDirectoryMode = "0750";
RuntimeDirectoryPreserve = "yes";
WorkingDirectory = runtimeDir;
# docs/CONTRACT.md: the socket is owned by the service user, mode 0660.
UMask = "0007";
Restart = "always";
RestartSec = 2;
# A GPU render node is the one piece of hardware a headless session still
# needs; everything else is virtual.
SupplementaryGroups = ["video" "render"];
NoNewPrivileges = true;
PrivateTmp = true;
ProtectHome = true;
ProtectSystem = "strict";
ProtectControlGroups = true;
ProtectKernelTunables = true;
ProtectKernelModules = true;
RestrictSUIDSGID = true;
ReadWritePaths = lib.optional (socketDir != runtimeDir) socketDir;
};
in {
options.services.hyprland-headless-stream = {
enable = lib.mkEnableOption "a headless Hyprland session streamed to a Unix socket";
@@ -34,7 +163,7 @@ in {
};
format = lib.mkOption {
type = lib.types.enum [ "png" "jpeg" ];
type = lib.types.enum ["png" "jpeg"];
default = "png";
description = "Frame encoding.";
};
@@ -42,15 +171,59 @@ in {
outputs = lib.mkOption {
type = lib.types.listOf (lib.types.submodule {
options = {
name = lib.mkOption { type = lib.types.str; };
width = lib.mkOption { type = lib.types.ints.positive; default = 1280; };
height = lib.mkOption { type = lib.types.ints.positive; default = 720; };
refresh = lib.mkOption { type = lib.types.ints.positive; default = 30; };
scale = lib.mkOption { type = lib.types.positive; default = 1.0; };
name = lib.mkOption {
type = lib.types.str;
default = "";
description = ''
Regex matched against the names of the outputs this machine has
(`eDP-1`, `Virtual-1`, ...). Empty is Hyprland's wildcard form and
matches every output; a name no connector has is a rule that is
silently ignored.
'';
};
width = lib.mkOption {
type = lib.types.ints.positive;
default = 1280;
};
height = lib.mkOption {
type = lib.types.ints.positive;
default = 720;
};
refresh = lib.mkOption {
type = lib.types.ints.positive;
default = 30;
};
# Was `lib.types.positive`, which does not exist in nixpkgs and made
# `outputs` unreadable; `numbers.positive` is the int-or-float type
# that name meant.
scale = lib.mkOption {
type = lib.types.numbers.positive;
default = 1.0;
};
};
});
default = [ { name = "HEADLESS-1"; width = 1280; height = 720; refresh = 30; scale = 1.0; } ];
description = "Virtual monitors the compositor should create.";
default = [
{
name = "";
width = 1280;
height = 720;
refresh = 30;
scale = 1.0;
}
];
description = ''
Monitor rules applied to the outputs the machine has. Each entry becomes
one `monitor = <name>, <width>x<height>@<refresh>, auto, <scale>` line.
These are *not* outputs the compositor creates: aquamarine's headless
backend has no allocator of its own and rides on the DRM backend, so a
session started by this module always has the GPU's own connectors and
whatever names the host gives them. The default therefore uses the empty
name -- Hyprland's wildcard, as in its own shipped
`monitor=,preferred,auto,1` -- so that `enable = true` alone gives a
session at a known size on any machine. Naming a connector that does not
exist is not an error; the rule is simply never applied.
'';
};
extraConfig = lib.mkOption {
@@ -73,19 +246,132 @@ in {
captureCommand = lib.mkOption {
type = lib.types.listOf lib.types.str;
default = [ "grim" "-t" "png" "-" ];
default = ["grim" "-t" "png" "-"];
description = "Command that writes one frame to stdout; overridable for tests.";
};
};
config = lib.mkIf cfg.enable {
# TODO(module): user/group, runtime dir, hyprland.conf rendering, the two
# systemd units named in docs/CONTRACT.md.
assertions = [
{
assertion = cfg.outputs != [ ];
assertion = cfg.outputs != [];
message = "services.hyprland-headless-stream.outputs must not be empty.";
}
{
assertion = lib.hasPrefix "/" cfg.socketPath;
message = "services.hyprland-headless-stream.socketPath must be an absolute path.";
}
];
# The flake's own build, as docs/CONTRACT.md says; `mkDefault` so a
# consumer (or the test harness) can still point this at its own package.
services.hyprland-headless-stream.package =
lib.mkDefault (pkgs.callPackage ./package.nix {});
users.users.${cfg.user} = {
isSystemUser = true;
group = cfg.group;
description = "Headless Hyprland stream session";
};
users.groups.${cfg.group} = {};
# Only needed when the socket was moved out of the runtime directory that
# `RuntimeDirectory=` already creates for us.
systemd.tmpfiles.settings = lib.mkIf (socketDir != runtimeDir) {
"10-hyprland-headless-stream".${socketDir}.d = {
user = cfg.user;
group = cfg.group;
mode = "0750";
};
};
systemd.services.hyprland-headless = {
description = "Headless Hyprland session";
documentation = ["file://${hyprlandConf}"];
wantedBy = ["multi-user.target"];
# No WAYLAND_DISPLAY and no DISPLAY here on purpose: with either set the
# compositor would pick its nested backend and try to connect to a parent
# session. Without them it drives DRM directly, and the monitor rules in
# hyprland.conf set the mode of whatever connectors it finds there.
environment =
sessionEnvironment
// {
# We are a system service: there is no user bus and no user manager to
# import the session environment into.
HYPRLAND_NO_SD_VARS = "1";
HYPRLAND_NO_CRASHREPORTER = "1";
# Ignored by aquamarine-era Hyprland, honoured by wlroots-era builds
# someone may pin in `hyprlandPackage`.
WLR_BACKENDS = "headless";
WLR_LIBINPUT_NO_DEVICES = "1";
WLR_RENDERER_ALLOW_SOFTWARE = "1";
# Ask libseat's embedded seatd for a seat with no VT.
#
# This unit is a system service, not a login, so libseat finds no
# /run/seatd.sock and no logind session and falls back to the seatd it
# links in -- whose seat is VT-bound by default. That seatd then opens
# /dev/tty0, which `cfg.user` cannot, so its client never goes active
# and every device open is refused:
#
# [libseat] Could not open target tty: Permission denied
# [libseat] Could not open VT for client
# libseat: Couldn't open device at /dev/dri/card0
# drm: Found no gpus to use, cannot continue
#
# and with the DRM backend gone there is no allocator, so
# `CBackend::create()` aborts -- the headless backend takes its
# allocator from the DRM one. SEATD_VTBOUND=0 (seatd/server.c) is the
# truth about this session on any host: there is no terminal to switch
# away from.
SEATD_VTBOUND = "0";
};
serviceConfig =
commonServiceConfig
// {
# Hyprland sends READY=1 once the session is up, so the frame server's
# `After=` is an ordering on readiness, not just on fork.
Type = "notify";
NotifyAccess = "all";
TimeoutStartSec = 60;
# A preserved runtime directory can still hold the previous run's
# sockets, and that would push the new session to `wayland-1` (and
# leave the server waiting on a dead one).
ExecStartPre = "${clearStaleSockets}";
ExecStart = lib.escapeShellArgs [
(lib.getExe cfg.hyprlandPackage)
"--config"
"${hyprlandConf}"
];
};
};
systemd.services.hyprland-headless-stream = {
description = "Frame server for the headless Hyprland session";
wantedBy = ["multi-user.target"];
after = ["hyprland-headless.service"];
bindsTo = ["hyprland-headless.service"];
# `captureCommand` defaults to an unqualified `grim`.
path = [pkgs.grim];
environment =
sessionEnvironment
// {
# WAYLAND_DISPLAY is set by `execServer` at start, because the socket
# name is only known once the compositor has bound it.
PYTHONUNBUFFERED = "1";
};
serviceConfig =
commonServiceConfig
// {
Type = "simple";
ExecStartPre = "${findSession} >/dev/null";
ExecStart = lib.escapeShellArgs ([execServer] ++ serverArgs);
};
};
};
}
}
+307
View File
@@ -0,0 +1,307 @@
#!/usr/bin/env python3
"""Read a hhstream socket and assert it obeys docs/CONTRACT.md.
This is deliberately a *second, independent* implementation of the reader: it
shares no code with `hhstream.client`, so a bug that lives in both the server's
writer and the shipped client's reader still fails the test. Pure standard
library; it runs inside the test VM, where only python3 is guaranteed.
Every run prints what it saw before it decides, so a failure in CI is readable
without reproducing it.
"""
from __future__ import annotations
import argparse
import hashlib
import json
import re
import socket
import struct
import sys
import zlib
MAGIC = "HHS1"
FORMATS = {"image/png", "image/jpeg"}
PNG_SIGNATURE = b"\x89PNG\r\n\x1a\n"
# Contract: plain ASCII digits, no leading zeros, no `+`, no spaces.
LENGTH_RE = re.compile(rb"\A(?:0|[1-9][0-9]*)\Z")
class ContractError(Exception):
"""The stream violated docs/CONTRACT.md."""
# --------------------------------------------------------------------------
# wire reading
# --------------------------------------------------------------------------
def read_line(sock: socket.socket, limit: int = 4096) -> bytes:
"""Read up to and including the next 0x0A. Never over-reads past it."""
out = bytearray()
while True:
b = sock.recv(1)
if not b:
raise ContractError(
f"socket closed after {len(out)} bytes while reading a line: {bytes(out)!r}"
)
if b == b"\n":
return bytes(out)
out += b
if len(out) > limit:
raise ContractError(f"no newline within {limit} bytes: {bytes(out[:120])!r}...")
def read_exact(sock: socket.socket, n: int) -> bytes:
out = bytearray()
while len(out) < n:
part = sock.recv(min(65536, n - len(out)))
if not part:
raise ContractError(
f"truncated payload: wanted {n} bytes, socket closed after {len(out)}"
)
out += part
return bytes(out)
def read_hello(sock: socket.socket) -> dict:
line = read_line(sock)
try:
obj = json.loads(line.decode("utf-8"))
except (UnicodeDecodeError, json.JSONDecodeError) as exc:
raise ContractError(f"Hello is not UTF-8 JSON ({exc}): {line!r}") from exc
if not isinstance(obj, dict):
raise ContractError(f"Hello is not a JSON object: {line!r}")
if obj.get("magic") != MAGIC:
raise ContractError(f"Hello magic is {obj.get('magic')!r}, contract says {MAGIC!r}")
for key in ("width", "height", "fps"):
val = obj.get(key)
if not isinstance(val, int) or isinstance(val, bool):
raise ContractError(f"Hello {key} is {val!r}, expected an integer")
if val <= 0:
raise ContractError(
f"Hello {key} is {val}; the contract forbids a Hello with zero size"
)
if obj.get("format") not in FORMATS:
raise ContractError(
f"Hello format is {obj.get('format')!r}, expected one of {sorted(FORMATS)}"
)
return obj
def read_frame(sock: socket.socket) -> bytes:
prefix = read_line(sock)
if not LENGTH_RE.match(prefix):
raise ContractError(
f"malformed length prefix {prefix!r}: contract requires plain ASCII "
"digits with no leading zeros, sign or spaces"
)
length = int(prefix)
if length == 0:
raise ContractError("frame length is 0; a frame must carry a complete image")
return read_exact(sock, length)
# --------------------------------------------------------------------------
# PNG inspection
# --------------------------------------------------------------------------
def png_chunks(data: bytes):
off = len(PNG_SIGNATURE)
while off + 8 <= len(data):
(size,) = struct.unpack(">I", data[off : off + 4])
kind = data[off + 4 : off + 8]
body = data[off + 8 : off + 8 + size]
if len(body) != size:
raise ContractError(f"PNG chunk {kind!r} truncated: want {size}, got {len(body)}")
crc = data[off + 8 + size : off + 12 + size]
if len(crc) != 4:
raise ContractError(f"PNG chunk {kind!r} has no CRC")
want = struct.pack(">I", zlib.crc32(kind + body) & 0xFFFFFFFF)
if crc != want:
raise ContractError(f"PNG chunk {kind!r} CRC mismatch: {crc.hex()} != {want.hex()}")
yield kind, body
off += 12 + size
if kind == b"IEND":
return
raise ContractError("PNG ended without an IEND chunk")
def inspect_png(payload: bytes) -> dict:
"""Parse enough of a PNG to know its size and whether it carries a picture."""
if not payload.startswith(PNG_SIGNATURE):
raise ContractError(
f"payload is not a PNG: first 8 bytes are {payload[:8]!r}, "
f"expected {PNG_SIGNATURE!r}"
)
ihdr = None
idat = bytearray()
for kind, body in png_chunks(payload):
if kind == b"IHDR":
if ihdr is not None:
raise ContractError("PNG has more than one IHDR")
if len(body) != 13:
raise ContractError(f"IHDR is {len(body)} bytes, expected 13")
w, h, depth, colour, comp, filt, interlace = struct.unpack(">IIBBBBB", body)
ihdr = dict(
width=w, height=h, bit_depth=depth, colour_type=colour,
compression=comp, filter=filt, interlace=interlace,
)
elif kind == b"IDAT":
if ihdr is None:
raise ContractError("PNG has IDAT before IHDR")
idat += body
if ihdr is None:
raise ContractError("PNG has no IHDR chunk")
if not idat:
raise ContractError("PNG has no IDAT chunk: there is no image data")
try:
raw = zlib.decompress(bytes(idat))
except zlib.error as exc:
raise ContractError(f"PNG image data does not decompress: {exc}") from exc
info = dict(ihdr)
info["payload_bytes"] = len(payload)
info["raw_bytes"] = len(raw)
info["distinct_raw_bytes"] = len(set(raw))
info["nonzero_raw_bytes"] = len(raw) - raw.count(0)
return info
def blank_png_size(width: int, height: int, colour_type: int, bit_depth: int) -> int:
"""Smallest plausible encoding of an all-zero image of the same geometry.
Used as the floor for "bigger than a trivial blank image": a zero-filled
framebuffer, packed with the best compression available, cannot exceed this.
"""
channels = {0: 1, 2: 3, 3: 1, 4: 2, 6: 4}.get(colour_type, 3)
stride = 1 + (width * channels * bit_depth + 7) // 8
raw = b"\x00" * (stride * height)
body = zlib.compress(raw, 9)
# signature + IHDR (25) + IDAT header/crc (12) + IEND (12)
return len(PNG_SIGNATURE) + 25 + 12 + len(body) + 12
# --------------------------------------------------------------------------
# driver
# --------------------------------------------------------------------------
def build_parser() -> argparse.ArgumentParser:
p = argparse.ArgumentParser(description=__doc__)
p.add_argument("--socket", required=True, help="path of the hhstream socket")
p.add_argument("--frames", type=int, default=1, help="how many frames to read")
p.add_argument("--timeout", type=float, default=30.0,
help="per-recv socket timeout, seconds")
p.add_argument("--expect-width", type=int, help="assert Hello/IHDR width")
p.add_argument("--expect-height", type=int, help="assert Hello/IHDR height")
p.add_argument("--expect-fps", type=int, help="assert Hello fps")
p.add_argument("--expect-format", help="assert Hello format, e.g. image/png")
p.add_argument("--min-bytes", type=int, default=1,
help="every payload must be at least this many bytes")
p.add_argument("--require-png", action="store_true",
help="every payload must parse as a PNG whose IHDR matches the Hello")
p.add_argument("--identical-frames", action="store_true",
help="all payloads read must be byte-identical")
p.add_argument("--reject-blank", action="store_true",
help="reject a frame that decodes to an all-zero or single-valued "
"image, or that is no bigger than a best-case blank PNG")
return p
def run(args) -> None:
sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
sock.settimeout(args.timeout)
sock.connect(args.socket)
try:
hello = read_hello(sock)
print(f"hello: {json.dumps(hello, sort_keys=True)}", flush=True)
for key, got in (("width", "expect_width"), ("height", "expect_height"),
("fps", "expect_fps"), ("format", "expect_format")):
want = getattr(args, got)
if want is not None and hello[key] != want:
raise ContractError(f"Hello {key} is {hello[key]!r}, expected {want!r}")
if args.require_png and hello["format"] != "image/png":
raise ContractError(
f"--require-png but Hello advertises format {hello['format']!r}"
)
payloads: list[bytes] = []
for i in range(args.frames):
payload = read_frame(sock)
digest = hashlib.sha256(payload).hexdigest()[:16]
print(f"frame {i}: {len(payload)} bytes sha256:{digest}", flush=True)
if len(payload) < args.min_bytes:
raise ContractError(
f"frame {i} is {len(payload)} bytes, below the {args.min_bytes}-byte floor"
)
payloads.append(payload)
if args.require_png:
info = inspect_png(payload)
print(f"frame {i}: png {json.dumps(info, sort_keys=True)}", flush=True)
if (info["width"], info["height"]) != (hello["width"], hello["height"]):
raise ContractError(
f"frame {i} IHDR is {info['width']}x{info['height']} but the Hello "
f"announced {hello['width']}x{hello['height']}"
)
if args.reject_blank:
floor = blank_png_size(
info["width"], info["height"], info["colour_type"], info["bit_depth"]
)
print(f"frame {i}: blank-png floor is {floor} bytes", flush=True)
if info["nonzero_raw_bytes"] == 0:
raise ContractError(
f"frame {i} decodes to {info['raw_bytes']} zero bytes: "
"this is a zero-filled buffer, not a captured frame"
)
if info["distinct_raw_bytes"] < 2:
raise ContractError(
f"frame {i} decodes to a single repeated byte value "
f"({info['raw_bytes']} bytes): a blank image, not a capture"
)
if len(payload) <= floor:
raise ContractError(
f"frame {i} is {len(payload)} bytes, no bigger than a "
f"best-case blank {info['width']}x{info['height']} PNG "
f"({floor} bytes)"
)
if args.identical_frames and len(payloads) > 1:
first = payloads[0]
for i, payload in enumerate(payloads[1:], start=1):
if payload != first:
raise ContractError(
f"frame {i} differs from frame 0 ({len(payload)} vs {len(first)} "
"bytes) but the fake capture emits one fixed image"
)
print(f"all {len(payloads)} frames byte-identical", flush=True)
finally:
sock.close()
def main(argv: list[str] | None = None) -> int:
args = build_parser().parse_args(argv)
if args.frames < 1:
print("assert-stream: --frames must be at least 1", file=sys.stderr)
return 2
try:
run(args)
except ContractError as exc:
print(f"CONTRACT VIOLATION: {exc}", file=sys.stderr)
return 1
except (OSError, socket.timeout) as exc:
print(f"SOCKET ERROR on {args.socket}: {exc!r}", file=sys.stderr)
return 1
print("OK", flush=True)
return 0
if __name__ == "__main__":
sys.exit(main())
+89
View File
@@ -0,0 +1,89 @@
#!/usr/bin/env python3
"""A fake capture backend: writes one deterministic PNG to stdout and exits.
Stands in for `grim` so `vm-basic` can exercise the socket, the Hello and the
framing without a compositor. Two properties matter to the test:
* the bytes are a *valid* PNG of exactly the requested size, so a server that
derives the Hello's width/height from the captured image agrees with a server
that derives them from the configured output;
* the bytes are *byte-identical* on every invocation, so the test can assert
that two frames off the wire are the same image rather than the same length.
Pure standard library (zlib + struct), because the test VM has nothing else.
"""
from __future__ import annotations
import argparse
import struct
import sys
import zlib
def chunk(kind: bytes, data: bytes) -> bytes:
return (
struct.pack(">I", len(data))
+ kind
+ data
+ struct.pack(">I", zlib.crc32(kind + data) & 0xFFFFFFFF)
)
def encode_png(width: int, height: int) -> bytes:
"""A solid frame with one deterministic marker rectangle in the corner.
The marker keeps the image from being uniform, which is what makes it a
believable stand-in for a real capture; being fixed keeps it reproducible.
"""
bg = (0x20, 0x30, 0x40)
fg = (0xE0, 0xC0, 0x10)
mark_w = min(64, width)
mark_h = min(32, height)
plain = b"\x00" + bytes(bg) * width
marked = b"\x00" + bytes(fg) * mark_w + bytes(bg) * (width - mark_w)
raw = marked * mark_h + plain * (height - mark_h)
ihdr = struct.pack(">IIBBBBB", width, height, 8, 2, 0, 0, 0) # 8-bit truecolour
return (
b"\x89PNG\r\n\x1a\n"
+ chunk(b"IHDR", ihdr)
+ chunk(b"IDAT", zlib.compress(raw, 9))
+ chunk(b"IEND", b"")
)
def build_parser() -> argparse.ArgumentParser:
p = argparse.ArgumentParser(description=__doc__)
p.add_argument("--width", type=int, default=1280)
p.add_argument("--height", type=int, default=720)
# Accepted and ignored so the fake can be dropped in where a grim-shaped
# argv is expected (`-t png -`).
p.add_argument("-t", "--type", default="png")
p.add_argument("output", nargs="?", default="-")
return p
def main(argv: list[str] | None = None) -> int:
args = build_parser().parse_args(argv)
if args.type != "png":
print(f"fake-capture: only png is supported, got {args.type!r}", file=sys.stderr)
return 2
if args.width <= 0 or args.height <= 0:
print("fake-capture: width and height must be positive", file=sys.stderr)
return 2
data = encode_png(args.width, args.height)
out = sys.stdout.buffer if args.output == "-" else open(args.output, "wb")
try:
out.write(data)
out.flush()
finally:
if out is not sys.stdout.buffer:
out.close()
return 0
if __name__ == "__main__":
sys.exit(main())
+109
View File
@@ -0,0 +1,109 @@
#!/bin/sh
# Dump everything worth knowing when `vm-hyprland` fails.
#
# The compositor's own log is the thing you actually want and the thing that is
# hardest to find: Hyprland writes it under
# $XDG_RUNTIME_DIR/hypr/<instance-signature>/hyprland.log, and the service runs
# on a private XDG_RUNTIME_DIR. So rather than guess the path, look for it.
#
# Never fails: a diagnostics dump that exits non-zero hides the real error.
PATH="@diagPath@:$PATH"
export PATH
if [ "$1" = "--self-test" ]; then
echo "hhs-hyprland-diagnostics: ok"
exit 0
fi
SERVICE_UNIT=hyprland-headless-stream.service
COMPOSITOR_UNIT=hyprland-headless.service
say() { printf '\n----- %s -----\n' "$*"; }
run() { say "$*"; "$@" 2>&1 || echo "[exit $?]"; }
say "units"
systemctl --no-pager --plain list-units --all 'hyprland*' 2>&1 || true
for unit in "$COMPOSITOR_UNIT" "$SERVICE_UNIT"; do
run systemctl --no-pager --full status "$unit"
run journalctl --no-pager --boot --lines=200 --unit "$unit"
done
run systemctl --no-pager --full list-dependencies "$SERVICE_UNIT"
say "graphics devices"
# The one piece of hardware a headless Hyprland still needs. A NixOS test
# machine gets QEMU's default bochs-drm adapter, which gives a card0 and *no*
# renderD*; aquamarine's headless backend wants a render node and aborts with
# "CBackend::create() failed!" without one. So "card0 but no renderD128" here
# is the signature of a machine that needs a virtio GPU in qemu.options.
ls -l /dev/dri 2>&1 || echo "[no /dev/dri: this machine has no DRM device at all]"
run cat /proc/fb
say "socket and runtime directories"
ls -la /run/hyprland-headless-stream 2>&1 || echo "[no /run/hyprland-headless-stream]"
ls -la /run/user 2>&1 || echo "[no /run/user]"
for d in /run/user/*; do
[ -d "$d" ] && ls -la "$d" 2>&1
done
say "wayland socket vs WAYLAND_DISPLAY"
# The other silent killer: the frame server waits for
# $XDG_RUNTIME_DIR/$WAYLAND_DISPLAY, so if the compositor bound a different
# socket name the unit just sits in ExecStartPre until the test times out, with
# a healthy compositor next to it. Print both names side by side.
systemctl show -p Environment --value "$SERVICE_UNIT" 2>&1 \
| tr ' ' '\n' | grep -E '^(WAYLAND_DISPLAY|XDG_RUNTIME_DIR)=' \
|| echo "[no WAYLAND_DISPLAY/XDG_RUNTIME_DIR in the unit environment]"
for d in /run/hyprland-headless-stream /run/user/*; do
[ -d "$d" ] || continue
found_sock=$(find "$d" -xdev -maxdepth 1 -name 'wayland-*' ! -name '*.lock' 2>/dev/null)
if [ -n "$found_sock" ]; then
echo "bound sockets in $d: $found_sock"
else
echo "bound sockets in $d: [none]"
fi
done
say "hyprland logs"
# hyprland.log lives beside the compositor's IPC sockets; -xdev keeps this out
# of /nix/store and /proc.
found=0
for root in /run /var/log /tmp /home; do
[ -d "$root" ] || continue
for log in $(find "$root" -xdev -maxdepth 6 -name 'hyprland*.log' 2>/dev/null); do
found=1
say "tail -n 200 $log"
tail -n 200 "$log" 2>&1
done
done
[ "$found" = 1 ] || echo "[no hyprland*.log anywhere under /run /var/log /tmp /home]"
say "hyprctl monitors"
# Needs both XDG_RUNTIME_DIR and the instance signature, which is the directory
# name under <runtime>/hypr. Try every instance we can find.
tried=0
for hyprdir in /run/user/*/hypr/* /run/*/hypr/*; do
[ -d "$hyprdir" ] || continue
sig=$(basename "$hyprdir")
runtime=$(dirname "$(dirname "$hyprdir")")
owner=$(stat -c %U "$hyprdir" 2>/dev/null || echo root)
tried=1
say "hyprctl monitors (instance $sig, XDG_RUNTIME_DIR=$runtime, as $owner)"
if command -v hyprctl > /dev/null 2>&1; then
XDG_RUNTIME_DIR="$runtime" HYPRLAND_INSTANCE_SIGNATURE="$sig" \
hyprctl monitors 2>&1 || echo "[exit $?]"
XDG_RUNTIME_DIR="$runtime" HYPRLAND_INSTANCE_SIGNATURE="$sig" \
hyprctl version 2>&1 || echo "[exit $?]"
else
echo "[hyprctl not on PATH; add the hyprlandPackage to environment.systemPackages]"
fi
done
[ "$tried" = 1 ] || echo "[no hypr instance directory found: the compositor never came up]"
say "processes"
ps aux 2>&1 | grep -E 'hypr|hhstream|grim' | grep -v grep || echo "[no hyprland/hhstream/grim process]"
say "end of diagnostics"
exit 0
+205 -2
View File
@@ -1,13 +1,24 @@
"""Shared fixtures. Nothing here touches a compositor, a GPU or the network."""
"""Shared fixtures for the unit suite.
Two workstreams wrote fixtures for this directory (the server's own, and the
test harness's); this file is the merge of both. Everything here is standard
library. The tests never touch a socket outside their own ``tmp_path``, never
spawn a compositor, and never read the host's configuration: the capture
backend is an inline ``python3 -c`` program and the server is driven in-process.
"""
from __future__ import annotations
import contextlib
import os
import pathlib
import shutil
import socket
import struct
import sys
import tempfile
import threading
import zlib
import pytest
@@ -19,6 +30,38 @@ for _path in (str(_HERE), str(_SRC)):
from hhstream.server import FrameServer # noqa: E402 (needs sys.path above)
#: The path named in docs/CONTRACT.md and in the module's option default.
CONTRACT_SOCKET = "/run/hyprland-headless-stream/stream.sock"
# AF_UNIX addresses are capped near 108 bytes; a long tmp_path would fail with a
# confusing OSError instead of the assertion the test is about.
SUN_PATH_MAX = 100
def make_png(width: int = 4, height: int = 3, value: int = 0x7F) -> bytes:
"""A minimal valid truecolour PNG, built with zlib+struct only."""
def chunk(kind: bytes, data: bytes) -> bytes:
return (
struct.pack(">I", len(data))
+ kind
+ data
+ struct.pack(">I", zlib.crc32(kind + data) & 0xFFFFFFFF)
)
raw = (b"\x00" + bytes([value, value ^ 0x20, value ^ 0x40]) * width) * height
return (
b"\x89PNG\r\n\x1a\n"
+ chunk(b"IHDR", struct.pack(">IIBBBBB", width, height, 8, 2, 0, 0, 0))
+ chunk(b"IDAT", zlib.compress(raw, 9))
+ chunk(b"IEND", b"")
)
@pytest.fixture
def tiny_png() -> bytes:
return make_png()
@pytest.fixture
def workdir():
@@ -32,7 +75,10 @@ def workdir():
@pytest.fixture
def sock_path(workdir):
return str(workdir / "s.sock")
path = str(workdir / "s.sock")
if len(path) > SUN_PATH_MAX:
pytest.skip(f"workdir too long for an AF_UNIX socket: {len(path)} bytes")
return path
@pytest.fixture
@@ -57,3 +103,160 @@ def serve():
for server, thread in started:
server.stop()
thread.join(5)
@pytest.fixture
def emit_bytes():
"""Build an argv that writes exactly `data` to stdout and exits 0."""
def build(data: bytes) -> list[str]:
return [
sys.executable,
"-c",
"import sys;sys.stdout.buffer.write(bytes.fromhex(sys.argv[1]))",
data.hex(),
]
return build
@pytest.fixture
def python_argv():
"""Build an argv running an inline python program with extra arguments."""
def build(program: str, *args: str) -> list[str]:
return [sys.executable, "-c", program, *args]
return build
class StubCapture:
"""A capture backend under the test's control.
Satisfies `hhstream.capture.CaptureBackend` structurally: `grab()` and
`size()`. Counts calls so a test can tell whether the server actually
captured, and can be told to raise so failure semantics are observable.
"""
def __init__(self, frames=None, size=(1280, 720), raise_first: int = 0):
self._frames = list(frames) if frames is not None else [make_png()]
self._size = size
self._raise_first = raise_first
self.grabs = 0
self.lock = threading.Lock()
def grab(self) -> bytes:
with self.lock:
self.grabs += 1
n = self.grabs
if n <= self._raise_first:
raise RuntimeError(f"stub capture failing on purpose (call {n})")
return self._frames[(n - 1) % len(self._frames)]
def size(self) -> tuple[int, int]:
return self._size
@pytest.fixture
def stub_capture():
return StubCapture
@pytest.fixture
def connect():
"""Connect to an AF_UNIX socket, retrying until the server has bound it."""
opened: list[socket.socket] = []
def _connect(path: str, timeout: float = 10.0, deadline: float = 10.0) -> socket.socket:
import time
end = time.monotonic() + deadline
last: Exception | None = None
while time.monotonic() < end:
try:
s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
s.settimeout(timeout)
s.connect(path)
opened.append(s)
return s
except OSError as exc:
last = exc
s.close()
time.sleep(0.05)
raise AssertionError(f"never connected to {path}: {last!r}")
yield _connect
for s in opened:
try:
s.close()
except OSError:
pass
@pytest.fixture
def run_bg():
"""Run a callable on a daemon thread and surface the exception it raised."""
threads: list[tuple[threading.Thread, list]] = []
def _run(fn, *args, **kwargs) -> list:
box: list = []
def target():
try:
fn(*args, **kwargs)
except BaseException as exc: # recorded, re-raised by the test
box.append(exc)
t = threading.Thread(target=target, daemon=True)
t.start()
threads.append((t, box))
return box
yield _run
for t, box in threads:
t.join(timeout=0.5)
@pytest.fixture
def socket_mode():
def _mode(path: str) -> int:
return os.stat(path).st_mode & 0o7777
return _mode
@pytest.fixture(scope="session")
def rejects():
"""`pytest.raises`, but a stub does not count as a rejection.
docs/CONTRACT.md says which inputs are invalid, not which exception type
signals it, so these tests cannot pin the type. A bare
`pytest.raises(Exception)` would then be satisfied by the unimplemented
stubs' own `NotImplementedError` -- a test that is green precisely because
nothing is written yet. This refuses that one exception explicitly.
"""
@contextlib.contextmanager
def _rejects(*allowed: type[BaseException]):
expected = allowed or (Exception,)
try:
yield
except NotImplementedError as exc:
raise AssertionError(
"the code under test raised NotImplementedError, so it did not "
f"reject anything: {exc!r}"
) from exc
except expected:
return
except BaseException as exc:
raise AssertionError(
f"expected one of {[e.__name__ for e in expected]}, got {exc!r}"
) from exc
raise AssertionError(
f"expected one of {[e.__name__ for e in expected]}, nothing was raised"
)
return _rejects
+38
View File
@@ -0,0 +1,38 @@
"""The parts of the package that are plain constants, checked against the contract.
These are the only tests here that do not depend on an implementation, which
makes them the canary for the `unit` check's own wiring: if they fail, the
package is not importable from the build sandbox and nothing else means anything.
"""
from __future__ import annotations
import hhstream
from hhstream import capture, client, protocol, server
from conftest import CONTRACT_SOCKET
def test_magic_matches_the_contract():
# docs/CONTRACT.md: {"magic":"HHS1", ...}
assert hhstream.MAGIC == "HHS1"
assert protocol.MAGIC == "HHS1"
def test_default_socket_path_matches_the_contract():
assert server.DEFAULT_SOCKET == CONTRACT_SOCKET
assert client.DEFAULT_SOCKET == CONTRACT_SOCKET
def test_public_surface_is_present():
for name in ("hello", "parse_hello", "frame", "read_frame", "read_hello"):
assert callable(getattr(protocol, name)), f"protocol.{name}"
assert callable(client.fetch)
assert callable(client.main)
assert callable(server.main)
assert isinstance(server.FrameServer, type)
assert isinstance(capture.CommandCapture, type)
def test_version_is_the_packaged_version():
assert hhstream.__version__ == "0.1.0"