{ 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. # # The name is short on purpose, and the assertion below is what keeps it that # way. A Unix socket address carries its path inside `sun_path`, which is 108 # bytes including the terminating NUL (linux/un.h), and the compositor puts # its IPC sockets under this directory: # # /hypr//.socket.sock requests # /hypr//.socket2.sock events # # Of that budget, 20 characters are fixed and the instance signature (~30) is # Hyprland's to choose; this directory's name is the only part we control. At # the previous name -- `/run/hyprland-headless-stream`, 29 characters -- the # event socket did not fit and the compositor refused to bind it: # # ERR ]: Socket2 path is too long. (2) IPC will not work. # # The *request* socket kept answering `hyprctl` anyway (both ends agreed on a # residual truncated path), which is why the broken event socket went # unnoticed. docs/CONTRACT-sessions.md §5 freezes the ceiling at 25. runtimeDirName = "hypr-stream"; runtimeDir = "/run/${runtimeDirName}"; runtimeDirMaxLength = 25; 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/hypr-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 = , 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 { 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. ''; }; stateDir = lib.mkOption { type = lib.types.str; default = "/var/lib/hhstream"; description = '' Where the broker keeps what outlives a broker restart: the live-record mirrors it adopts on the way back up, tombstones of ended sessions, and `events.jsonl`, the audit trail of every accepted command. Point this at durable storage. The default is a system path, which on a machine whose root is rebuilt from scratch — the usual shape of a declaratively-managed server — means the audit trail dies with the next reinstall. On such a machine this belongs on the same disk as the rest of the state that cannot be rebuilt. ''; }; }; }; 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."; } # Structural, not cosmetic: see the `runtimeDirName` comment above. The # ceiling exists so the compositor's *event* socket still fits in # `sun_path`, and the symptom of breaking it is silent -- the request # socket keeps answering, so `hyprctl` looks fine while every event-driven # feature is dead. { assertion = builtins.stringLength runtimeDir <= runtimeDirMaxLength; message = '' The compositor runtime directory "${runtimeDir}" is ${ toString (builtins.stringLength runtimeDir) } characters; it must be at most ${toString runtimeDirMaxLength}. Hyprland's event socket is /hypr//.socket2.sock. A longer directory pushes that path past the 108 bytes a Unix socket address has for `sun_path`, and the compositor then refuses to bind it: ERR ]: Socket2 path is too long. (2) IPC will not work. Nothing appears broken when that happens -- the shorter request socket still answers `hyprctl` -- but the event stream never arrives, so every feature that watches the compositor (window and workspace tracking, session containers) stops working. docs/CONTRACT-sessions.md §5 freezes this limit; shorten the directory rather than raising it. ''; } { 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 {}); # The broker's state directory and the moved socket directory are two # different reasons to write a tmpfiles entry, and this option takes one # definition — so they are merged here rather than assigned twice (which # does not evaluate at all). systemd.tmpfiles.settings = lib.mkMerge [ # The broker keeps the records it adopts on the way back up, its # tombstones, and `events.jsonl`, the audit trail of every accepted # command. It is declared here rather than left to the daemon so its owner # and mode are declarative and survive a restart of the unit. (lib.mkIf cfg.sessions.enable { "10-hhstream-sessions".${cfg.sessions.stateDir}.d = { user = cfg.sessions.user; group = cfg.sessions.group; mode = "0700"; }; }) # Only needed when the socket was moved out of the runtime directory that # `RuntimeDirectory=` already creates for us. (lib.mkIf (socketDir != runtimeDir) { "10-hyprland-headless-stream".${socketDir}.d = { user = cfg.user; group = cfg.group; mode = "0750"; }; }) ]; users.users.${cfg.user} = { isSystemUser = true; group = cfg.group; description = "Headless Hyprland stream session"; }; users.groups.${cfg.group} = {}; 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"; 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" cfg.sessions.stateDir "--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 ]; }; }; }; }