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
378 lines
13 KiB
Nix
378 lines
13 KiB
Nix
{
|
|
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";
|
|
|
|
socketPath = lib.mkOption {
|
|
type = lib.types.str;
|
|
default = "/run/hyprland-headless-stream/stream.sock";
|
|
description = "Where the frame server publishes frames.";
|
|
};
|
|
|
|
user = lib.mkOption {
|
|
type = lib.types.str;
|
|
default = "hhstream";
|
|
description = "User the compositor and frame server run as.";
|
|
};
|
|
|
|
group = lib.mkOption {
|
|
type = lib.types.str;
|
|
default = "hhstream";
|
|
description = "Group owning the socket.";
|
|
};
|
|
|
|
frameRate = lib.mkOption {
|
|
type = lib.types.ints.positive;
|
|
default = 30;
|
|
description = "Target capture rate; becomes `fps` in the protocol Hello.";
|
|
};
|
|
|
|
format = lib.mkOption {
|
|
type = lib.types.enum ["png" "jpeg"];
|
|
default = "png";
|
|
description = "Frame encoding.";
|
|
};
|
|
|
|
outputs = lib.mkOption {
|
|
type = lib.types.listOf (lib.types.submodule {
|
|
options = {
|
|
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 = "";
|
|
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 {
|
|
type = lib.types.lines;
|
|
default = "";
|
|
description = "Extra lines appended to hyprland.conf.";
|
|
};
|
|
|
|
hyprlandPackage = lib.mkOption {
|
|
type = lib.types.package;
|
|
default = pkgs.hyprland;
|
|
defaultText = lib.literalExpression "pkgs.hyprland";
|
|
description = "Compositor to run.";
|
|
};
|
|
|
|
package = lib.mkOption {
|
|
type = lib.types.package;
|
|
description = "The frame server / client package.";
|
|
};
|
|
|
|
captureCommand = lib.mkOption {
|
|
type = lib.types.listOf lib.types.str;
|
|
default = ["grim" "-t" "png" "-"];
|
|
description = "Command that writes one frame to stdout; overridable for tests.";
|
|
};
|
|
};
|
|
|
|
config = lib.mkIf cfg.enable {
|
|
assertions = [
|
|
{
|
|
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);
|
|
};
|
|
};
|
|
};
|
|
}
|