From 6510e315d4dc711152e34614eb8ceadf5ef9c367 Mon Sep 17 00:00:00 2001 From: Hermenix Date: Mon, 28 Sep 2026 21:51:24 +0000 Subject: [PATCH] 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 Claude-Session: https://claude.ai/code/session_01M5GEju6XhoRXDWvEiaAX2r --- README.md | 4 +- checks/lib/gpu-session.nix | 41 ++---------- checks/vm-basic.nix | 8 ++- checks/vm-hyprland.nix | 125 +++++++++++++++++++++++++++++-------- docs/CONTRACT.md | 2 +- nix/hyprland-conf.nix | 17 ++++- nix/module.nix | 51 +++++++++++++-- 7 files changed, 175 insertions(+), 73 deletions(-) diff --git a/README.md b/README.md index 865e110..944b620 100644 --- a/README.md +++ b/README.md @@ -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; } ]; }; } ``` diff --git a/checks/lib/gpu-session.nix b/checks/lib/gpu-session.nix index b86b1b4..df604fb 100644 --- a/checks/lib/gpu-session.nix +++ b/checks/lib/gpu-session.nix @@ -11,14 +11,15 @@ # # 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 that a bare test machine does not provide. Each is -# one of the blocks below, and each was confirmed in the guest by removing it -# again and watching the compositor die on the next line down. +# 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 -# below were separated. +# were separated. { ... }: { # 1. A DRM render node. @@ -49,36 +50,4 @@ # 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; - - # 3. A seat that is not bound to a VT. - # - # This one is not really the test machine's business, and it is flagged rather - # than fixed: it belongs in nix/module.nix, which this slice may not edit. - # - # Only the DRM backend ever yields a buffer allocator -- - # `CHeadlessBackend::drmFD()` returns -1 unconditionally (aquamarine - # src/backend/Headless.cpp), and CBackend::start() takes the allocator from the - # first implementation with a drm fd. So "headless" here does not mean "no - # GPU": the headless backend still rides on the DRM backend's allocator, and if - # the DRM backend fails there is none, whatever /dev/dri holds. - # - # The DRM backend opens /dev/dri/card0 through libseat. For this unit libseat - # finds no /run/seatd.sock and no logind session (it is a system service, not a - # login), so it falls back to its embedded seatd -- whose seat is VT-bound by - # default. It then tries to open /dev/tty0, which the unprivileged `hhstream` - # user cannot, so the client never becomes active and every device open is - # refused: - # - # ERR ]: [libseat] [common/terminal.c:162] Could not open target tty: Permission denied - # ERR ]: [libseat] [seatd/seat.c:557] Could not open VT for client - # ERR ]: libseat: Couldn't open device at /dev/dri/card0 - # ERR ]: drm: Skipping device /sys/devices/.../drm/card0, not a KMS device - # ERR ]: drm: Found no gpus to use, cannot continue - # ERR ]: DRM Backend failed - # - # SEATD_VTBOUND=0 (seatd/server.c) asks that embedded seatd for a seat with no - # VT at all, which is the truth about this session: there is no terminal to - # switch away from. A headless session run as a system user will need this on - # any machine, not just in the test. - systemd.services.hyprland-headless.environment.SEATD_VTBOUND = "0"; } diff --git a/checks/vm-basic.nix b/checks/vm-basic.nix index 96a36c5..2bac106 100644 --- a/checks/vm-basic.nix +++ b/checks/vm-basic.nix @@ -24,7 +24,9 @@ testers.runNixOSTest { nodes.machine = { # gpu-session.nix is what makes the compositor able to start at all; see - # that file for the three things a bare test machine is missing. + # 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 = { @@ -35,9 +37,11 @@ testers.runNixOSTest { 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 = [ { - name = "HEADLESS-1"; inherit width height; refresh = fps; } diff --git a/checks/vm-hyprland.nix b/checks/vm-hyprland.nix index adeb680..a85af35 100644 --- a/checks/vm-hyprland.nix +++ b/checks/vm-hyprland.nix @@ -3,9 +3,13 @@ # compositor through grim. # # 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 -# 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. +# 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, @@ -25,7 +29,9 @@ testers.runNixOSTest { nodes.machine = { # gpu-session.nix is what makes the compositor able to start at all; see - # that file for the three things a bare test machine is missing. + # 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 = { @@ -35,14 +41,42 @@ testers.runNixOSTest { 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 = [ { - name = "HEADLESS-1"; 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 @@ -67,9 +101,21 @@ testers.runNixOSTest { }; 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} ##########") @@ -87,17 +133,27 @@ testers.runNixOSTest { dump("hyprland-headless.service did not start") raise - with subtest("the compositor reports the configured headless output"): + with subtest("the compositor reports a monitor at the configured mode"): try: - # Proves the compositor is really running a 1280x720 HEADLESS-1 - # before we blame the capture for a wrong-sized frame. - out = machine.succeed("hhs-hyprland-diagnostics", timeout=120) - print(out) - assert "HEADLESS-1" in out, ( - "hyprctl never reported a HEADLESS-1 monitor; see the dump above" + # 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 f"{WIDTH}x{HEIGHT}" in out, ( - f"hyprctl never reported a {WIDTH}x{HEIGHT} mode; see the dump above" + 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") @@ -112,20 +168,39 @@ testers.runNixOSTest { raise with subtest("grim can capture the session at all"): - # Separates "grim cannot see the compositor" from "the server is wrong", - # which are the two failures that look identical from the socket. + # 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/, 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: - print( - machine.succeed( - "systemd-run --pipe --wait --uid=hhstream" - " --setenv=XDG_RUNTIME_DIR=/run/user/$(id -u hhstream)" - " grim -t png /tmp/direct.png 2>&1 || true", - timeout=120, - ) + machine.wait_until_succeeds( + f"hhs-assert-stream --socket {SOCKET} --frames 1 --timeout 30" + " --require-png --reject-blank", + timeout=120, ) - print(machine.execute("stat -c '%s bytes' /tmp/direct.png")[1]) except Exception: - dump("direct grim capture failed") + 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"): diff --git a/docs/CONTRACT.md b/docs/CONTRACT.md index 2ddb051..9b8ccb1 100644 --- a/docs/CONTRACT.md +++ b/docs/CONTRACT.md @@ -82,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 | diff --git a/nix/hyprland-conf.nix b/nix/hyprland-conf.nix index f74fb48..9ffe62e 100644 --- a/nix/hyprland-conf.nix +++ b/nix/hyprland-conf.nix @@ -9,14 +9,25 @@ extraConfig, }: let # `monitor = , x@, auto, ` -- "auto" - # lets the compositor lay the virtual outputs out left to right. + # 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 - # creates the virtual outputs or switches off something that assumes a user. + # 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} diff --git a/nix/module.nix b/nix/module.nix index 32406cc..331431b 100644 --- a/nix/module.nix +++ b/nix/module.nix @@ -171,7 +171,16 @@ in { outputs = lib.mkOption { type = lib.types.listOf (lib.types.submodule { options = { - name = lib.mkOption {type = lib.types.str;}; + 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; @@ -195,14 +204,26 @@ in { }); default = [ { - name = "HEADLESS-1"; + name = ""; width = 1280; height = 720; refresh = 30; scale = 1.0; } ]; - description = "Virtual monitors the compositor should create."; + description = '' + Monitor rules applied to the outputs the machine has. Each entry becomes + one `monitor = , x@, auto, ` 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 { @@ -271,8 +292,8 @@ in { # 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. With no seat and no DRM device it falls back to headless, - # which is exactly what the virtual outputs in hyprland.conf want. + # 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 // { @@ -285,6 +306,26 @@ in { 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 =