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.
This commit is contained in:
1 parent
9dc9e0da9a
commit
30f456c07e
37 files changed
+9118
-1
No files matched your search
+215
@@ -82,6 +82,26 @@ let
|
||||
# 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"
|
||||
@@ -249,6 +269,123 @@ in {
|
||||
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 {
|
||||
@@ -261,6 +398,16 @@ in {
|
||||
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
|
||||
@@ -373,5 +520,73 @@ in {
|
||||
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
|
||||
];
|
||||
};
|
||||
};
|
||||
};
|
||||
}
|
||||
Reference in new issue
Block a user