Files
hyprland-headless-stream-pl…/nix/module.nix
T
Hermenix 30f456c07e integrate the session broker: one CLI, a module unit, and a VM check
M0 of the sessions design, wired into the flake and gated by a real check.

What is here now:

- `src/hhstreamd/` — the broker: session registry, lifecycle verbs, process-group
  teardown, app allowlist, audit log, idle reaper on CLOCK_BOOTTIME.
- `src/hhstream_session/` — the CLI handlers, registered into the one front door.
- `src/hhstream/cli.py` — `hhstream status|shot|run|record|session …`, so the
  frame verbs and the session namespace are one binary.
- `nix/module.nix` — `sessions.*` options and the `hhstream-sessions.service`
  unit: the operator's own account (never a service account, because launched
  applications should see that account's home), the compositor's group as a
  supplementary group (without it a launched GUI client cannot open the Wayland
  socket), the generated app allowlist, and `--compositor-runtime-dir` so
  applications are handed the compositor's session rather than the broker's.
- `checks/vm-sessions.nix` — 18 subtests on a real compositor in a VM.

Two bugs found by driving it, both fixed:

- BUG-01: launched applications could not reach the compositor at all — the
  broker spawned them with its own inherited environment, which names the login
  session. `hhstreamd/compositor.py` discovers the socket and builds the child
  environment; a directory with no usable socket is a startup refusal, not a
  warning.
- BUG-02: `kill` refused to signal a live application and said nothing was
  wrong. The identity gate hashed `/proc/<pid>/cmdline`, which every `execve`
  replaces — and on NixOS applications are reached through wrapper scripts that
  do exactly that. The gate now rests on `starttime` (+ boot id, + session id
  where it is immutable) and records command-line drift as evidence of nothing.

KillMode=process is set on the unit on purpose: the default control-group kill
would take the applications down with the broker, which would make adoption and
a broker restart pointless.
2026-10-01 12:23:16 +00:00

593 lines
22 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.
# The session broker's app allowlist, in the daemon's own config format. The
# daemon treats a missing file as an empty allowlist and refuses every `start`
# with the path it looked for, so generating this is what makes
# `sessions.enable = true` useful rather than decorative.
sessionsConfig = pkgs.writeText "hhstream-sessions.toml" ''
[defaults]
max_sessions = ${toString cfg.sessions.maxSessions}
idle_timeout_s = ${toString cfg.sessions.idleTimeout}
${lib.concatStringsSep "\n" (
lib.mapAttrsToList (name: app: ''
[apps.${name}]
exec = ${builtins.toJSON (toString app.exec)}
args_allow = [${
lib.concatStringsSep ", " (map (arg: builtins.toJSON arg) app.argsAllow)
}]
'') cfg.sessions.apps
)}
'';
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.";
};
sessions = {
enable = lib.mkOption {
type = lib.types.bool;
default = false;
description = ''
Run the session broker (`hhstreamd`) that launches GUI applications
into this compositor as *tracked sessions*: started by name, kept
alive by an explicit `touch`, killed by name, and reaped when they go
quiet for {option}`sessions.idleTimeout`.
It is off by default because it is a different capability from
streaming frames: a frame server can be read by anyone in the group,
while this one starts processes on the machine.
Its CLI is `hhstream session …` on the same binary as the frame
commands; the daemon itself is the unit `hhstream-sessions.service`.
'';
};
user = lib.mkOption {
type = lib.types.str;
default = config.services.hyprland-headless-stream.user;
defaultText = lib.literalExpression "services.hyprland-headless-stream.user";
description = ''
The account the broker runs as, and the account every launched
application runs as. It must already exist: the module does not create
it, because its whole point is usually to be a real person's account
whose home directory and files the applications should see.
Set it to the account that will actually drive the CLI. The broker is
granted {option}`sessions.group` as a supplementary group so the
applications it launches can reach the compositor's socket.
'';
};
group = lib.mkOption {
type = lib.types.str;
default = config.services.hyprland-headless-stream.group;
defaultText = lib.literalExpression "services.hyprland-headless-stream.group";
description = ''
The group that owns the compositor's runtime directory. The broker gets
it as a supplementary group, and passes it to every application it
launches — without it a launched GUI client cannot open the Wayland
socket and dies at startup.
'';
};
idleTimeout = lib.mkOption {
type = lib.types.ints.positive;
default = 10800;
description = ''
Seconds a session may go without a `touch` before the broker kills it
and everything it spawned. The clock lives in the broker, not in the
CLI, so it keeps running after the CLI exits.
Only `touch` resets it: `list`, `status`, `logs` and `gc` deliberately
do not, or a monitoring loop would keep abandoned sessions alive
forever.
'';
};
maxSessions = lib.mkOption {
type = lib.types.ints.positive;
default = 4;
description = ''
Hard cap on live sessions. Without cgroup limits this is the main
containment control against a looping caller spawning applications
until the machine gives up.
'';
};
apps = lib.mkOption {
type = lib.types.attrsOf (lib.types.submodule {
options = {
exec = lib.mkOption {
type = lib.types.path;
description = "Absolute path to the executable. Never a shell command.";
};
argsAllow = lib.mkOption {
type = lib.types.listOf lib.types.str;
default = [];
description = ''
Arguments a caller may pass to this application. Anything else is
refused, so `exec` must be able to do its job with these and
nothing more. A trailing `*` matches a prefix
(`--user-data-dir=*`).
'';
};
};
});
default = {};
description = ''
The allowlist: which applications may be started as a session, and with
which arguments. This is the primary security control —
without it, `session start /bin/sh` would make every other control
decorative. An application that is not listed here cannot be started
at all.
'';
example = lib.literalExpression ''
{
chromium.exec = "''${pkgs.chromium}/bin/chromium";
chromium.argsAllow = [ "--new-window" "--user-data-dir=*" "https://*" ];
}
'';
};
configFile = lib.mkOption {
type = lib.types.nullOr lib.types.path;
default = null;
description = ''
Use this TOML allowlist instead of the one generated from
{option}`sessions.apps`, for configurations the option shape cannot
express.
'';
};
};
};
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.";
}
{
assertion = !cfg.sessions.enable || lib.hasAttr cfg.sessions.user config.users.users;
message = ''
services.hyprland-headless-stream.sessions.user = "${cfg.sessions.user}" is not a
declared user. The module deliberately does not create it: launched applications
run as that account, so it is normally a real person's account whose home
directory and files they should see. Declare it (or point the option at an
existing account).
'';
}
];
# 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);
};
};
# ── the session broker ─────────────────────────────────────────────
#
# A different capability from the frame server, and a different account: this
# one starts processes, so it runs as the operator's own user and everything
# it launches runs as that user too.
systemd.services.hhstream-sessions = lib.mkIf cfg.sessions.enable {
description = "Session broker for the headless Hyprland desktop";
wantedBy = ["multi-user.target"];
after = ["hyprland-headless.service"];
bindsTo = ["hyprland-headless.service"];
environment = {
PYTHONUNBUFFERED = "1";
};
serviceConfig = {
Type = "simple";
User = cfg.sessions.user;
# The broker does not need the group itself -- but the applications it
# launches do, and they inherit its supplementary groups. Without it a
# GUI client cannot open the compositor's socket (0770, this group) and
# dies with "Failed to connect to Wayland display".
SupplementaryGroups = [cfg.sessions.group];
RuntimeDirectory = "hhstream";
RuntimeDirectoryMode = "0750";
StateDirectory = "hhstream";
WorkingDirectory = "/run/hhstream";
UMask = "0007";
Restart = "on-failure";
RestartSec = 1;
NoNewPrivileges = true;
# Sessions must outlive the broker, because a broker restart is an
# ordinary event (an upgrade, a crash, `systemctl restart`) and the whole
# point of the registry is to adopt what it finds afterwards.
#
# systemd's default is KillMode=control-group, which SIGTERMs every
# process in the unit's cgroup when the unit stops -- i.e. it kills the
# applications from outside, undoing the broker's own care (it spawns
# them with a plain Popen precisely so its own death does not reach them).
# KillMode=process signals only the broker; the applications are left
# running and are adopted on the way back up.
KillMode = "process";
ExecStart = lib.escapeShellArgs [
(lib.getExe' cfg.package "hhstreamd")
"--socket"
"/run/hhstream/control.sock"
"--runtime-dir"
"/run/hhstream"
"--state-dir"
"/var/lib/hhstream"
"--config"
(toString (
if cfg.sessions.configFile != null then cfg.sessions.configFile else sessionsConfig
))
# Where the compositor's own session lives. The broker discovers the
# `wayland-N` socket in there and hands XDG_RUNTIME_DIR / WAYLAND_DISPLAY
# to every application it launches; the daemon was built to fail loudly
# if this directory holds no usable socket.
"--compositor-runtime-dir"
runtimeDir
];
};
};
};
}