feat(nix): the hhstream-live unit, and the two things it has to be handed
`services.hyprland-headless-stream.sessions.stream.enable` (default **false**) runs `hhstream-live` and hands the broker `/run/hhstream/live.sock`. Running it still turns nothing on: a stream exists only for the sessions `hhstream session stream enable` was run on, which is the plan's rule that a stream is never on for all sessions at all times. A fourth unit rather than a flag on an existing one, for the pointer driver's reason: `grim` blocks tens to hundreds of milliseconds, so the capture must not run where `touch` and `kill` are answered, and a LAN-facing HTTP parser must not run in the frame server whose one-socket contract cannot grow one. Two things the unit must be handed, both of them MEASURED failures rather than precautions: 1. **The capture command, spelled out, with grim's store path.** A unit's `PATH` has no `grim` (`docs/TODO/capture-binary-and-the-unit-path.md`), and the symptom is a stream that answers with an empty frame area and says why only in the daemon's journal. Every word is passed as `--capture-command=<word>` and not `--capture-command <word>`, because grim's last word is a bare `-` and argparse reads a lone dash as an option prefix rather than a value -- a unit crash-looping with "expected one argument", which is how that form was chosen. 2. **The compositor's session.** `XDG_RUNTIME_DIR` on the unit plus `execLive`, which discovers whichever `wayland-N` the compositor actually bound and exports it -- `execServer`'s trick, for `execServer`'s reason: the name is only known once the compositor is up, so it cannot be an `Environment=` line. Without it the unit was `active (running)`, the broker attached, `stream status` said `attached: true`, and every capture exited 1 with "XDG_RUNTIME_DIR is invalid or not set in the environment" until the publisher gave up after ten in a row. checks/vm-stream.nix found that on its first real run, which is the whole reason that check reads bytes instead of asserting a 200. `SupplementaryGroups` gets the compositor's group for the pointer driver's reason one step further -- this one has to *capture*, not merely find the socket -- and there is deliberately no `RuntimeDirectory=`: a second one on /run/hhstream would delete the broker's control socket when this unit stopped, which the plan names as the Stage 3 risk. `sessions.stream.fps` is the daemon's own default and nothing else sends one, so the option changes what actually happens; the port and bind address are the daemon's too, and the broker learns the URL from it. `nix/package.nix` names `hhstream_live.control` and `hhstreamd.live` in `pythonImportsCheck`: they are the one pair in this package that has to agree with each other across two processes, so an import error in either is worth finding at build time rather than the first time an operator enables a stream. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
This commit is contained in:
1 parent
850f9caa1d
commit
ca5dbfb2ea
2 files changed
+177
-7
No files matched your search
+170
-7
@@ -46,6 +46,7 @@ let
|
||||
brokerRuntimeDir = "/run/${brokerRuntimeDirName}";
|
||||
controlSocket = "${brokerRuntimeDir}/control.sock";
|
||||
pointerSocket = "${brokerRuntimeDir}/pointer.sock";
|
||||
liveSocket = "${brokerRuntimeDir}/live.sock";
|
||||
|
||||
# Addresses that mean "this listener answers on loopback only". The spelling
|
||||
# `localhost` is included because it is what a person writes; it is not a
|
||||
@@ -164,6 +165,35 @@ let
|
||||
done
|
||||
exec ${lib.getExe' cfg.package "hhstream-server"} "$@"
|
||||
'';
|
||||
|
||||
# The same problem, for the stream daemon, one step worse.
|
||||
#
|
||||
# `grim` is an ordinary Wayland client: it needs XDG_RUNTIME_DIR *and* the
|
||||
# name of the socket the compositor actually bound, and that name is only
|
||||
# known once the compositor is up -- so, exactly as above, it cannot be an
|
||||
# `Environment=` line.
|
||||
#
|
||||
# MEASURED, in checks/vm-stream.nix, which is the check that exists to find
|
||||
# this: with the group but without the environment, the unit came up
|
||||
# `active (running)`, the broker attached, `stream status` said
|
||||
# `attached: true`, and every capture failed with
|
||||
#
|
||||
# grim: error: XDG_RUNTIME_DIR is invalid or not set in the environment.
|
||||
#
|
||||
# until the publisher gave up after ten in a row. A viewer with the right
|
||||
# phrase got a page and no frames, and nothing in the session's own state
|
||||
# said why -- the sibling failure to
|
||||
# docs/TODO/capture-binary-and-the-unit-path.md, and the reason this unit
|
||||
# spells out the whole capture command *and* hands it a session.
|
||||
execLive = pkgs.writeShellScript "hhstream-exec-live" ''
|
||||
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-live"} "$@"
|
||||
'';
|
||||
hyprlandConf = pkgs.writeText "hyprland.conf" (import ./hyprland-conf.nix {
|
||||
inherit lib;
|
||||
inherit (cfg) outputs extraConfig;
|
||||
@@ -701,15 +731,57 @@ in {
|
||||
|
||||
# The session-stream web app — `hhstream-live`, the router that serves a
|
||||
# live view of one session per phrase, over one port
|
||||
# (`docs/plans/2026-10-04-session-stream-webapp.md`).
|
||||
# (`docs/plans/2026-10-04-session-stream-webapp.md`, Stage 2 and 3).
|
||||
#
|
||||
# Only the *reach* of it is declared here so far: the port every stream
|
||||
# shares, the address it will bind, and whether that port is opened in
|
||||
# the firewall. The unit that runs the app, the phrases the broker keeps
|
||||
# in its records and the `session stream enable` verbs are later stages
|
||||
# of that plan — and deliberately so: a stream is switched on per
|
||||
# session, never for all of them, so nothing here turns one on.
|
||||
# `enable` runs the unit and hands the broker `/run/hhstream/live.sock`,
|
||||
# over which `hhstream session stream enable <id>` switches one stream
|
||||
# on. Everything else here is the *reach* of it: the port every stream
|
||||
# shares, the address it binds, and whether that port is opened in the
|
||||
# firewall.
|
||||
#
|
||||
# Running it still turns nothing on. A stream exists only for the
|
||||
# sessions it was enabled on — a stream is switched on per session, never
|
||||
# for all of them — so `enable = true` is a listener serving one form
|
||||
# until somebody asks for a session.
|
||||
stream = {
|
||||
enable = lib.mkOption {
|
||||
type = lib.types.bool;
|
||||
default = false;
|
||||
description = ''
|
||||
Run `hhstream-live`, the web app that publishes one session's
|
||||
screen at a URL whose path is a spoken phrase, and give the broker
|
||||
the socket it switches streams on over
|
||||
(`/run/hhstream/live.sock`).
|
||||
|
||||
Off by default, and running it turns **nothing** on: a stream
|
||||
exists only for the sessions `hhstream session stream enable` was
|
||||
called on, and until then this is a listener serving one form.
|
||||
That is deliberate — a live view of a desktop is readable by
|
||||
anyone who can reach the port and guess the phrase, so switching
|
||||
one on is a per-session act and never a consequence of the service
|
||||
being up.
|
||||
|
||||
Needs {option}`sessions.enable`: the phrase lives in the session
|
||||
record, and there are no sessions without the broker.
|
||||
'';
|
||||
};
|
||||
|
||||
fps = lib.mkOption {
|
||||
type = lib.types.ints.positive;
|
||||
default = 5;
|
||||
description = ''
|
||||
Frames a second a stream captures at when nobody says otherwise.
|
||||
|
||||
Five is one frame per ~200 ms plus a ~46 ms `grim`, measured rather
|
||||
than guessed; the daemon's own hard cap is 10, because this box is
|
||||
also running the compositor and the main frame publisher. Capture
|
||||
happens **only while somebody is connected**, so an enabled stream
|
||||
nobody is watching costs nothing at any rate.
|
||||
|
||||
`hhstream session stream enable --fps N` overrides it per stream.
|
||||
'';
|
||||
};
|
||||
|
||||
port = lib.mkOption {
|
||||
type = lib.types.port;
|
||||
default = 9988;
|
||||
@@ -1236,5 +1308,96 @@ in {
|
||||
];
|
||||
};
|
||||
};
|
||||
|
||||
# The stream daemon. A third executor beside the pointer driver, and the
|
||||
# split is the driver's: `grim` blocks tens to hundreds of milliseconds, so
|
||||
# the capture must not run where `touch` and `kill` are answered, and a
|
||||
# LAN-facing HTTP parser must not run in the frame server whose one-socket
|
||||
# contract cannot grow one (docs/CONTRACT-sessions.md §3.5).
|
||||
systemd.services.hhstream-live = lib.mkIf (cfg.sessions.enable && cfg.sessions.stream.enable) {
|
||||
description = "Per-session live stream for the headless Hyprland desktop";
|
||||
wantedBy = ["multi-user.target"];
|
||||
after = ["hyprland-headless.service"];
|
||||
# `BindsTo` for the pointer driver's reason: this process captures from
|
||||
# that compositor's outputs through `grim`, so when the compositor goes
|
||||
# it has nothing left to capture. The broker reports such a stream as
|
||||
# `attached: false` rather than pretending, and re-enabling re-attaches.
|
||||
bindsTo = ["hyprland-headless.service"];
|
||||
|
||||
environment = {
|
||||
PYTHONUNBUFFERED = "1";
|
||||
# The compositor's session, not this unit's own: `grim` has to find the
|
||||
# Wayland socket in here. `WAYLAND_DISPLAY` is set by `execLive` at
|
||||
# start, because the socket's name is only known once the compositor
|
||||
# has bound it. HOME is deliberately NOT redirected here the way the
|
||||
# frame server's is -- this unit runs as the operator's account, and
|
||||
# the compositor's runtime directory is not writable by it.
|
||||
XDG_RUNTIME_DIR = runtimeDir;
|
||||
};
|
||||
|
||||
serviceConfig = {
|
||||
Type = "simple";
|
||||
User = cfg.sessions.user;
|
||||
# The compositor's runtime directory is 0750 and owned by this group,
|
||||
# and `grim` is a Wayland client of it -- same reason the pointer
|
||||
# driver needs the group, one step further: this one has to *capture*,
|
||||
# not merely find the socket.
|
||||
SupplementaryGroups = [cfg.sessions.group];
|
||||
|
||||
# No `RuntimeDirectory`: /run/hhstream belongs to the broker's unit and
|
||||
# to the tmpfiles entry above, and a second RuntimeDirectory= on the
|
||||
# same path would delete the broker's control socket when this unit
|
||||
# stopped. The plan calls this out by name as the Stage 3 risk.
|
||||
WorkingDirectory = brokerRuntimeDir;
|
||||
UMask = "0007";
|
||||
|
||||
Restart = "on-failure";
|
||||
RestartSec = 1;
|
||||
NoNewPrivileges = true;
|
||||
KillMode = "process";
|
||||
|
||||
# `grim` is NOT on a unit's PATH, and the symptom of leaving it off is
|
||||
# a stream that serves an empty frame area without saying why --
|
||||
# docs/TODO/capture-binary-and-the-unit-path.md, found the first time
|
||||
# the capture ran as a unit rather than from a login shell. So the
|
||||
# whole capture command is spelled out here, with grim's store path.
|
||||
#
|
||||
# `--capture-command=<word>` and not `--capture-command <word>`:
|
||||
# MEASURED, as a unit crash-looping with
|
||||
#
|
||||
# hhstream-live serve: error: argument --capture-command: expected
|
||||
# one argument
|
||||
#
|
||||
# because grim's last word is a bare `-` (its "write to stdout"), and
|
||||
# argparse reads a lone dash as an option prefix rather than a value.
|
||||
# The `=` form is unambiguous for every word, so it is used for every
|
||||
# word rather than only the one that needs it.
|
||||
# Same second line of defence as the frame server's: `BindsTo=` stops
|
||||
# this unit when the compositor goes, but the compositor is only
|
||||
# *ready* once its socket is bound, and `execLive` has to find that
|
||||
# socket to export its name.
|
||||
ExecStartPre = "${findSession} >/dev/null";
|
||||
|
||||
ExecStart = lib.escapeShellArgs (
|
||||
[
|
||||
execLive
|
||||
"serve"
|
||||
"--control-socket=${liveSocket}"
|
||||
"--bind=${cfg.sessions.stream.bind}"
|
||||
"--port=${toString cfg.sessions.stream.port}"
|
||||
"--fps=${toString cfg.sessions.stream.fps}"
|
||||
]
|
||||
++ map (word: "--capture-command=${word}") [
|
||||
(lib.getExe pkgs.grim)
|
||||
"-c" # include the cursor
|
||||
"-t"
|
||||
"jpeg"
|
||||
"-q"
|
||||
"80"
|
||||
"-" # write to stdout
|
||||
]
|
||||
);
|
||||
};
|
||||
};
|
||||
};
|
||||
}
|
||||
@@ -38,6 +38,13 @@ python3.pkgs.buildPythonApplication {
|
||||
# The web app: importing the server pulls in the router, the publisher and
|
||||
# the pages.
|
||||
"hhstream_live.server"
|
||||
# The two halves of `live.sock` (CONTRACT-sessions.md §3.5). Both are
|
||||
# stdlib-only, and they are named here because they are the one pair in
|
||||
# this package that has to agree with each other across two processes --
|
||||
# so an import error in either is worth finding at build time rather than
|
||||
# the first time an operator enables a stream.
|
||||
"hhstream_live.control"
|
||||
"hhstreamd.live"
|
||||
];
|
||||
|
||||
# `pythonImportsCheck` only *imports*, and `hhstream_live.phrase` reads its
|
||||
|
||||
Reference in new issue
Block a user