diff --git a/nix/module.nix b/nix/module.nix index 7a11c8f..2896664 100644 --- a/nix/module.nix +++ b/nix/module.nix @@ -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 ` 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=` and not `--capture-command `: + # 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 + ] + ); + }; + }; }; } diff --git a/nix/package.nix b/nix/package.nix index fcdaa13..e5078c0 100644 --- a/nix/package.nix +++ b/nix/package.nix @@ -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