From 30f456c07e7df7033059fc3a5ff455968b79389f Mon Sep 17 00:00:00 2001 From: Hermenix Date: Thu, 1 Oct 2026 12:23:16 +0000 Subject: [PATCH] integrate the session broker: one CLI, a module unit, and a VM check MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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//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. --- README.dev.md | 3 +- checks/default.nix | 5 + checks/vm-sessions.nix | 649 ++++++++++ docs/ARCHITECTURE.md | 1 + .../hhstream-sessions.config.example.toml | 51 + nix/module.nix | 215 ++++ pyproject.toml | 4 + src/hhstream/cli.py | 345 +++++ src/hhstream_session/__init__.py | 508 ++++++++ src/hhstream_session/__main__.py | 9 + src/hhstream_session/client.py | 109 ++ src/hhstream_session/format.py | 155 +++ src/hhstreamd/__init__.py | 8 + src/hhstreamd/__main__.py | 253 ++++ src/hhstreamd/audit.py | 116 ++ src/hhstreamd/clock.py | 101 ++ src/hhstreamd/compositor.py | 240 ++++ src/hhstreamd/launcher.py | 237 ++++ src/hhstreamd/manager.py | 1000 +++++++++++++++ src/hhstreamd/policy.py | 237 ++++ src/hhstreamd/procmon.py | 406 ++++++ src/hhstreamd/protocol.py | 186 +++ src/hhstreamd/reaper.py | 187 +++ src/hhstreamd/registry.py | 394 ++++++ src/hhstreamd/server.py | 335 +++++ src/hhstreamd/textio.py | 51 + tests/sessions/conftest.py | 80 ++ tests/sessions/integration/test_lifecycle.py | 1125 +++++++++++++++++ tests/sessions/unit/test_cli_registration.py | 306 +++++ tests/sessions/unit/test_compositor.py | 414 ++++++ tests/sessions/unit/test_exit_codes.py | 104 ++ tests/sessions/unit/test_policy.py | 240 ++++ tests/sessions/unit/test_procmon.py | 383 ++++++ tests/sessions/unit/test_protocol.py | 110 ++ tests/sessions/unit/test_reaper.py | 215 ++++ tests/sessions/unit/test_registry.py | 270 ++++ tests/sessions/unit/test_textio.py | 67 + 37 files changed, 9118 insertions(+), 1 deletion(-) create mode 100644 checks/vm-sessions.nix create mode 100644 examples/hhstream-sessions.config.example.toml create mode 100644 src/hhstream/cli.py create mode 100644 src/hhstream_session/__init__.py create mode 100644 src/hhstream_session/__main__.py create mode 100644 src/hhstream_session/client.py create mode 100644 src/hhstream_session/format.py create mode 100644 src/hhstreamd/__init__.py create mode 100644 src/hhstreamd/__main__.py create mode 100644 src/hhstreamd/audit.py create mode 100644 src/hhstreamd/clock.py create mode 100644 src/hhstreamd/compositor.py create mode 100644 src/hhstreamd/launcher.py create mode 100644 src/hhstreamd/manager.py create mode 100644 src/hhstreamd/policy.py create mode 100644 src/hhstreamd/procmon.py create mode 100644 src/hhstreamd/protocol.py create mode 100644 src/hhstreamd/reaper.py create mode 100644 src/hhstreamd/registry.py create mode 100644 src/hhstreamd/server.py create mode 100644 src/hhstreamd/textio.py create mode 100644 tests/sessions/conftest.py create mode 100644 tests/sessions/integration/test_lifecycle.py create mode 100644 tests/sessions/unit/test_cli_registration.py create mode 100644 tests/sessions/unit/test_compositor.py create mode 100644 tests/sessions/unit/test_exit_codes.py create mode 100644 tests/sessions/unit/test_policy.py create mode 100644 tests/sessions/unit/test_procmon.py create mode 100644 tests/sessions/unit/test_protocol.py create mode 100644 tests/sessions/unit/test_reaper.py create mode 100644 tests/sessions/unit/test_registry.py create mode 100644 tests/sessions/unit/test_textio.py diff --git a/README.dev.md b/README.dev.md index c22ffa4..37073f0 100644 --- a/README.dev.md +++ b/README.dev.md @@ -42,8 +42,9 @@ at the bottom. The package builds; it does not yet run. | `unit` | the framing, the capture backend, the server's client handling, the client — in-process, against the `nix/package.nix` build | no | | `vm-basic` | the NixOS module brings up both units and publishes a contract-conformant socket, with a **fake** capture backend | yes | | `vm-hyprland` | the same, capturing the **real** headless compositor through `grim` | yes | +| `vm-sessions` | the **session broker**: a real GUI application launched into the compositor as a tracked session, seen by the compositor's own IPC, killed as a tree, reaped on its idle deadline (and *not* reaped when touched), and adopted back after the broker restarts | yes | -All three at once: +All of them at once: ```bash nix flake check -L diff --git a/checks/default.nix b/checks/default.nix index 6b691c1..75e1942 100644 --- a/checks/default.nix +++ b/checks/default.nix @@ -3,6 +3,7 @@ # unit -- pytest over tests/unit/, against the nix/package.nix build # vm-basic -- nixosTest with a fake capture backend: module + wire contract # vm-hyprland -- nixosTest with the real compositor and grim +# vm-sessions -- nixosTest with the real compositor and the session broker # # Everything the guests need lives in checks/lib/test-tools.nix. { @@ -25,4 +26,8 @@ in vm-hyprland = pkgs.callPackage ./vm-hyprland.nix { inherit hhstream hhsModule testTools; }; + + vm-sessions = pkgs.callPackage ./vm-sessions.nix { + inherit hhstream hhsModule testTools; + }; } diff --git a/checks/vm-sessions.nix b/checks/vm-sessions.nix new file mode 100644 index 0000000..5740ce0 --- /dev/null +++ b/checks/vm-sessions.nix @@ -0,0 +1,649 @@ +# checks..vm-sessions -- the session broker, on a real machine, against +# the real compositor. +# +# Same machine as `vm-hyprland` (compositor + gpu-session.nix), plus +# `sessions.enable = true` and one allowlisted victim application: `foot`, a +# real Wayland client with no GPU demands. Nothing here reads the frame socket: +# the source of truth for "the application is on the screen" is **the compositor +# itself**, asked over its own IPC, because the frame publisher could be happy +# about a screen with nothing on it. +# +# Habits copied from vm-hyprland, deliberately: every wait is bounded, each +# subtest makes its assertions once, and a failure dumps the compositor's +# diagnostics *and* the broker's journal, registry and the application's own +# captured output before it propagates. +# +# Every wait in the script is one of five kinds, and each waits for an *event +# that must happen* rather than for an assertion to come good: +# +# 1. the compositor's unit and the broker's unit coming up (wait_for_unit); +# 2. the compositor's and the broker's sockets appearing (wait_for_file); +# 3. the compositor mapping the client foot just connected with; +# 4. a process finishing dying after a kill; +# 5. the idle reaper firing, and the restarted broker answering again. +# +# The two real-time sleeps are the idle-reaper subtests, and they are the point +# of those subtests: no clock is injected anywhere, because an injected clock +# would prove the arithmetic (the unit tests already do) and not the daemon. +# +# ───────────────────────────────────────────────────────────────────────────── +# KNOWN DEFECTS this check is pointed at, as of 2026-10-01. +# +# Nothing below is worked around here. No WAYLAND_DISPLAY is injected into the +# unit, no ExecStart is overridden, and no assertion is softened to let a +# known-broken path through: a check that accommodated the daemon would go +# green while the capability it exists to prove stayed broken. +# +# * BUG-01 and the unknown `--compositor-runtime-dir` flag -- **fixed**. This +# check found both on its first run. The module passed the daemon a flag its +# parser did not define, so hhstreamd exited 2/INVALIDARGUMENT before it +# ever listened (restart counter past 40 by the time the test gave up), and +# even past that, a launched application was handed the daemon's own private +# per-session XDG_RUNTIME_DIR with no WAYLAND_DISPLAY and died inside a +# second. `hhstreamd/compositor.py` and `--compositor-runtime-dir` are the +# fix, and this check is what holds them honest. +# +# Worth keeping from that run: `wait_for_unit` *passed* against the crash +# loop, because the unit is `Type=simple` and systemd calls it active as +# soon as it has forked, and each attempt was slow enough (~3 s) that the +# default start limit never tripped. That is why the unit subtest asserts on +# the socket and on `NRestarts` rather than trusting `wait_for_unit` alone. +# +# * BUG-02 -- **open**, being fixed separately. `procmon.verify` reports *any* +# cmdline change as `pid_reuse_detected`, and `SessionManager.teardown` +# treats that name as "do not signal, and do not sweep either", so a session +# whose application exec-replaced its own argv -- a wrapper script, most of +# them -- is tombstoned `killed` while the process keeps running. The kill +# and reaper subtests below assert that the pid, its named children, its +# process group and its session id are all gone, and they stay that way: if +# BUG-02 reaches this check's victim, the right outcome is a red test, not a +# softer assertion. (The victim here is `${foot}/bin/foot`, a plain ELF in +# nixpkgs rather than a wrapper, so the trigger may not fire through it -- +# which is a fact about foot's packaging and not a reason to trust the path.) +# +# * The `/proc` session-id sweep cannot reach a PTY child -- **found by this +# check, open**. DESIGN.md §7 #7 says a child that called `setsid()` once is +# still caught, because it keeps the session id, and only a double +# `setsid()` escapes. Measured in this guest, that is not so: foot is +# pid/pgid/sid 1042 and the shell it runs is pid/pgid/sid **1056**. A +# terminal emulator must `setsid()` to give its child a controlling +# terminal, and `setsid()` changes the session id -- the very key the sweep +# searches on. So one `setsid()` is enough to leave both the process group +# `killpg` signals and the session the sweep walks, and any app that opens a +# PTY (a terminal, `script`, `tmux`, `ssh`) leaks its child by construction. +# +# In practice foot's shell still dies, because closing the PTY master sends +# it SIGHUP -- but that is the kernel's tty semantics, not this daemon's +# containment, and a child that ignores SIGHUP or holds no tty would +# survive. That is why the subtest below walks the **process tree** and +# names the pids it expects to be gone, rather than trusting an empty +# process group to mean "nothing survived". +# +# * A broker restart kills every session it was managing -- **found by this +# check, open, and it is a one-line module fix**. `systemctl restart +# hhstream-sessions` tombstones every live session as `exited` +# (`exit_detected_by: "proc_check"`, `last_error: "gone"`), and the new +# daemon logs `adopted 0, tombstoned 1`. The application is not gone because +# the daemon let go of it; it is gone because the *unit* killed it. +# `systemd.services.hhstream-sessions` sets no `KillMode=`, so it gets the +# default `control-group`: on stop systemd signals every process still in +# the unit's cgroup, and a launched app is a child of the daemon and so +# lives in that cgroup. +# +# This defeats DESIGN.md §2.4 and the whole adopt-on-startup path. +# `hhstreamd/launcher.py` explains at length why it uses a plain `Popen` +# rather than asyncio's subprocess transport -- precisely so that a daemon +# restart is not destructive -- and notes that "no unit file setting can fix +# it because the kill comes from inside this process". The converse is what +# bites here: the daemon's own care is undone from outside by the unit's +# default kill mode. `KillMode = "process"` on that unit is the fix. +# systemd.kill(5) warns that `process` lets children escape the service +# manager's lifecycle, which is exactly the trade this design already made: +# the registry, `killpg` and the `/proc` sweep are the lifecycle here. +# +# The restart subtests below are left asserting survival, and therefore red, +# until that lands. +# ───────────────────────────────────────────────────────────────────────────── +{ + testers, + hhstream, + testTools, + hhsModule, + hyprland, + foot, + jq, + procps, + coreutils, + dejavu_fonts, + width ? 1280, + height ? 720, + fps ? 30, + # The account the broker and every application it launches run as. The module + # refuses to create it (launched applications run as a real account), so the + # guest below declares it. + sessionUser ? "hermes", + # Long enough that nothing in this test is reaped by surprise, short enough + # that the number is visibly this test's and not the module's 3 h default. + idleTimeout ? 600, + controlSocket ? "/run/hhstream/control.sock", +}: +testers.runNixOSTest { + name = "hhstream-vm-sessions"; + + # Boot plus compositor startup plus ~30 s of real idle-clock waiting. Capped + # so a hang is a failure rather than a wedged builder. + globalTimeout = 1800; + + nodes.machine = { + imports = [ hhsModule ./lib/gpu-session.nix ]; + + services.hyprland-headless-stream = { + enable = true; + package = hhstream; + hyprlandPackage = hyprland; + # No `name`: the wildcard rule applies to whatever connector the virtio + # GPU gives this guest (see vm-hyprland.nix for why the check must not + # know that name). + outputs = [ + { + inherit width height; + refresh = fps; + } + ]; + + sessions = { + enable = true; + user = sessionUser; + inherit idleTimeout; + apps.foot = { + exec = "${foot}/bin/foot"; + # The daemon refuses unlisted arguments, and this check never passes + # any: `foot` with no argv opens a window running the account's shell, + # which is all the victim has to do. + argsAllow = [ ]; + }; + }; + }; + + # The module deliberately does not create this user. `video` and `render` + # are what any client of this session needs to reach the GPU; the broker's + # unit adds the compositor's own group on top (SupplementaryGroups=), which + # is what lets a launched client open the Wayland socket. + users.users.${sessionUser} = { + isNormalUser = true; + extraGroups = [ + "video" + "render" + ]; + }; + + # foot resolves "monospace" through fontconfig and refuses to start with no + # usable font. A NixOS test machine has `fonts.enableDefaultPackages = + # false`, so without this the victim application fails for a reason that has + # nothing to do with the broker. One font, not the default set. + fonts.packages = [ dejavu_fonts ]; + + environment.systemPackages = [ + testTools # hhs-hyprland-diagnostics + hhstream # the CLI under test + hyprland # hyprctl: the compositor is the source of truth here + foot + jq # the in-guest predicates the bounded waits poll + procps # ps, for "the process group and the session id are gone" + ]; + + virtualisation = { + memorySize = 2048; + cores = 2; + diskSize = 4096; + graphics = false; + }; + }; + + testScript = '' + import json + + USER = "${sessionUser}" + CONTROL = "${controlSocket}" + CONTROL_DIR = "/run/hhstream" + IDLE_TIMEOUT = ${toString idleTimeout}.0 + COMPOSITOR_RUNTIME = "/run/hyprland-headless-stream" + + # The module pins the compositor's XDG_RUNTIME_DIR; the instance signature + # under it is the only part not known ahead of time. Root may connect to + # the IPC socket even though it belongs to `hhstream`. Same shape as + # vm-hyprland.nix, which asks this for monitors. + HYPRCTL = ( + "set -eu; " + f"sig=$(ls -1 {COMPOSITOR_RUNTIME}/hypr | head -n1); " + f"XDG_RUNTIME_DIR={COMPOSITOR_RUNTIME}" + " HYPRLAND_INSTANCE_SIGNATURE=$sig hyprctl -j" + ) + HHSTREAM = "${hhstream}/bin/hhstream" + TRUE = "${coreutils}/bin/true" + FALSE = "${coreutils}/bin/false" + ID = "${coreutils}/bin/id" + + + def as_user(command): + """`command` (absolute path plus argv, never a shell) run as USER. + + A transient unit rather than `su`, because that is what the existing + checks already do for the compositor's account, and because it gives a + clean argv with no login shell in the middle. `--pipe --wait` + propagates the command's own exit status, which the first subtest + proves before anything depends on it. + """ + + return ( + "systemd-run --quiet --collect --pipe --wait" + f" --uid={USER} --setenv=HOME=/home/{USER} -- {command}" + ) + + + def cli(args): + """`hhstream session …` as USER, against the control socket.""" + + return as_user(f"{HHSTREAM} session --socket {CONTROL} {args}") + + + def gone(pid, pgid, sid, children=()): + """A shell predicate: this pid, each pid in `children`, the process + group and the session id are all absent from /proc. + + `children` is named explicitly rather than left to the process-group + check because "kill really kills, including children" is the assertion, + and a predicate that only looked at pgid/sid would also pass against a + teardown that never signalled anything if the group happened to be + empty. Built by concatenation so awk's braces do not have to be escaped + through an f-string. + """ + + awk = "awk '$2 == " + str(pgid) + " || $3 == " + str(sid) + "'" + parts = [ + "! kill -0 " + str(victim) + " 2>/dev/null" + for victim in (pid, *children) + ] + parts.append('[ -z "$(ps -eo pid=,pgid=,sid= | ' + awk + ')" ]') + return " && ".join(parts) + + + def dump(label, session_id=None): + print(f"########## diagnostics: {label} ##########") + status, out = machine.execute("hhs-hyprland-diagnostics", timeout=300) + print(out) + print(f"----- hhs-hyprland-diagnostics exit {status} -----") + commands = [ + "systemctl --no-pager --full status hhstream-sessions.service", + "journalctl --no-pager --boot --lines=200 --unit hhstream-sessions.service", + "systemctl show -p ExecStart --value hhstream-sessions.service", + f"ls -la {CONTROL_DIR} {CONTROL_DIR}/sessions /var/lib/hhstream" + " /var/lib/hhstream/sessions /var/lib/hhstream/logs", + "cat /var/lib/hhstream/sessions/*.json", + "ps -eo pid,ppid,pgid,sid,user,stat,comm,args --sort=pid", + cli("list --all"), + ] + if session_id: + commands += [ + cli(f"status {session_id}"), + # The application's own captured output: the only place a + # failed launch explains itself. + cli(f"logs {session_id} --lines 200"), + ] + for command in commands: + status, out = machine.execute(f"{command} 2>&1", timeout=180) + print(f"----- {command} (exit {status}) -----") + print(out) + status, out = machine.execute(f"{HYPRCTL} clients 2>&1", timeout=180) + print(f"----- hyprctl clients (exit {status}) -----") + print(out) + print("########## end diagnostics ##########") + + + start_all() + + with subtest("the as-user wrapper propagates exit status"): + # Everything below reads `machine.succeed`/`machine.fail` through + # `as_user`. If the wrapper swallowed the exit status, every one of + # those assertions would be vacuous, so prove it here first -- the same + # reason checks/lib/test-tools.nix self-tests its helpers at build time. + machine.succeed(as_user(TRUE), timeout=120) + machine.fail(as_user(FALSE), timeout=120) + print(machine.succeed(as_user(ID), timeout=120)) + + with subtest("the compositor comes up"): + # Not the thing under test, but every assertion below needs a session + # for the applications to be launched into. + try: + machine.wait_for_unit("hyprland-headless.service", timeout=300) + machine.wait_for_file(f"{COMPOSITOR_RUNTIME}/hypr", timeout=120) + except Exception: + dump("the compositor never started") + raise + + with subtest("the broker's unit comes up and listens"): + # `wait_for_unit` on its own is not enough here, and this is measured + # rather than assumed: the unit is `Type=simple` with no readiness + # protocol, so systemd calls it active the instant it has forked. A + # daemon that exits two milliseconds later and is restarted every + # second therefore passes `wait_for_unit` -- which is exactly what the + # ExecStart below does today. The honest test of "it came up" is the + # socket it exists to listen on, plus a restart count of zero. + try: + machine.wait_for_unit("hhstream-sessions.service", timeout=180) + machine.wait_for_file(CONTROL, timeout=120) + machine.succeed("systemctl is-active hhstream-sessions.service") + restarts = machine.succeed( + "systemctl show -p NRestarts --value hhstream-sessions.service" + ).strip() + assert restarts == "0", ( + f"the broker has restarted {restarts} time(s) already: it is " + "crash-looping, not running" + ) + except Exception: + dump("hhstream-sessions.service did not come up and listen") + raise + + with subtest("the control socket has the expected owner and mode"): + try: + print(machine.succeed(f"stat -c 'owner=%U group=%G mode=%a type=%F' {CONTROL}")) + print(machine.succeed(f"stat -c 'owner=%U group=%G mode=%a' {CONTROL_DIR}")) + machine.succeed(f'[ "$(stat -c %F {CONTROL})" = socket ]') + machine.succeed(f'[ "$(stat -c %U {CONTROL})" = {USER} ]') + # The unit sets no Group=, so the socket's group is the account's + # own primary group. Asked of the guest rather than hardcoded: the + # module's contract is "the account that drives the CLI owns it", + # not "the group is called users". + machine.succeed(f'[ "$(stat -c %G {CONTROL})" = "$(id -gn {USER})" ]') + machine.succeed(f'[ "$(stat -c %a {CONTROL})" = 660 ]') + machine.succeed(f'[ "$(stat -c %a {CONTROL_DIR})" = 750 ]') + machine.succeed(f'[ "$(stat -c %U {CONTROL_DIR})" = {USER} ]') + except Exception: + dump("the control socket is missing or not as specified") + raise + + with subtest("start prints a bare session id on stdout"): + # The contract: stdout is the id and nothing else, so $(...) is usable. + # Human detail goes to stderr, which the driver sends to the test log. + try: + out = machine.succeed(cli("start foot"), timeout=180) + assert out.endswith("\n"), f"start's stdout is not one line: {out!r}" + session_id = out.strip() + assert session_id.startswith("foot-"), ( + f"stdout is not a session id for the app that was started: {out!r}" + ) + assert len(session_id.split()) == 1, ( + f"stdout carries more than the bare id: {out!r}" + ) + print(f"session id: {session_id}") + except Exception: + dump("start did not print a session id") + raise + + with subtest("the session reports ready, with a live pid"): + try: + reply = json.loads(machine.succeed(cli(f"status --json {session_id}"), timeout=120)) + session = reply["session"] + print(json.dumps(session, indent=2, sort_keys=True)) + assert session["state"] == "ready", f"state is {session['state']!r}, not ready" + pid, pgid, sid = session["pid"], session["pgid"], session["sid"] + assert isinstance(pid, int) and pid > 1, f"implausible pid {pid!r}" + # start_new_session(): the kill handle is sid == pgid == pid. + assert pgid == pid and sid == pid, f"pid {pid}, pgid {pgid}, sid {sid} disagree" + assert session["idle_timeout_s"] == IDLE_TIMEOUT, ( + f"idle timeout is {session['idle_timeout_s']!r}, not the module's " + f"sessions.idleTimeout ({IDLE_TIMEOUT})" + ) + machine.succeed(f"kill -0 {pid}") + except Exception: + dump("the session did not report ready", locals().get("session_id")) + raise + + with subtest("the compositor reports a client whose pid is the session's"): + # THE assertion of this check: the compositor, over its own IPC, is the + # only thing that can say an application is really on this screen. The + # frame publisher is not consulted, and neither class nor title is + # asserted on -- only the pid, which is the one fact that ties the + # client on the screen to the session the broker handed back. + # + # One bounded wait, for the compositor to map a client that has only + # just connected: `ready` means "the process is alive", never "a window + # exists". Everything after it is a single assertion on a session that + # has finished coming up. + try: + machine.wait_until_succeeds( + f"{HYPRCTL} clients | jq -e --argjson pid {pid} 'any(.pid == $pid)' >/dev/null", + timeout=120, + ) + clients = json.loads(machine.succeed(f"{HYPRCTL} clients", timeout=120)) + print(f"compositor clients by pid: {[c.get('pid') for c in clients]}") + assert [c.get("pid") for c in clients].count(pid) == 1, ( + f"the compositor does not report exactly one client with pid {pid}" + ) + except Exception: + dump("the compositor never saw the launched application", session_id) + raise + + with subtest("list reports the session with the right pid and state"): + try: + table = machine.succeed(cli("list"), timeout=120) + print(table) + rows = [line.split() for line in table.splitlines()[1:] if line.strip()] + mine = [row for row in rows if row[0] == session_id] + assert len(mine) == 1, f"list does not show {session_id} exactly once" + app, state, listed_pid = mine[0][1], mine[0][2], mine[0][3] + assert app == "foot", f"list calls the app {app!r}" + assert state == "ready", f"list calls the state {state!r}" + assert listed_pid == str(pid), f"list reports pid {listed_pid}, not {pid}" + except Exception: + dump("list did not report the session", session_id) + raise + + with subtest("status --json reports the same pid and state"): + try: + reply = json.loads(machine.succeed(cli(f"status --json {session_id}"), timeout=120)) + assert reply["ok"] is True, reply + assert reply["id"] == session_id, reply + assert reply["state"] == "ready", reply + assert reply["session"]["pid"] == pid, reply["session"] + assert reply["session"]["app"] == "foot", reply["session"] + assert reply["session"]["live"] is True, reply["session"] + assert reply["session"]["ready_signal"] == "spawned", reply["session"] + except Exception: + dump("status --json did not report the session", session_id) + raise + + with subtest("the application really has a child of its own"): + # Captured before the kill, so "including children" is an assertion + # about named pids afterwards and not an inference from an empty + # process group. The window being mapped (above) means the child + # already exists, so this needs no wait. + # + # The walk is over **ppid**, not over the session id, and that is the + # whole point. Measured in this guest: foot is pid/pgid/sid 1042 and + # the shell it runs is pid/pgid/sid 1056 -- a terminal emulator must + # call setsid() to get a controlling terminal for its child, so that + # child leaves both the process group the daemon signals *and* the + # session id the daemon sweeps. So a pgid/sid-only check would pass + # with the child still running -- it is absent from both keys whether + # it is alive or dead -- and capturing "children" by session id finds + # nothing to name. The process tree is the only honest source. + try: + table = machine.succeed("ps -eo pid=,ppid=", timeout=120) + by_parent: dict[int, list[int]] = {} + for line in table.splitlines(): + bits = line.split() + if len(bits) == 2: + by_parent.setdefault(int(bits[1]), []).append(int(bits[0])) + children: list[int] = [] + frontier = [pid] + while frontier: + for child in by_parent.get(frontier.pop(), []): + if child not in children: + children.append(child) + frontier.append(child) + print(f"descendants of {pid}: {children}") + assert children, ( + f"{pid} has no descendant at all: the victim never started its " + "child, so this check cannot say anything about killing children" + ) + print( + machine.succeed( + "ps -o pid,ppid,pgid,sid,comm " + + " ".join(f"-p {p}" for p in (pid, *children)), + timeout=120, + ) + ) + except Exception: + dump("the launched application never had a child", session_id) + raise + + with subtest("kill ends the session"): + try: + reply = json.loads(machine.succeed(cli(f"kill --json {session_id}"), timeout=180)) + print(json.dumps(reply, indent=2, sort_keys=True)) + assert reply["ok"] is True, reply + assert reply["session"]["state"] == "killed", reply["session"] + # Not asserted: `stragglers`. It counts what the /proc sweep had to + # SIGKILL after the process group died, which is the sweep working + # rather than the kill failing. The next subtest is the assertion. + print(f"stragglers swept by session id: {reply['session'].get('stragglers')}") + except Exception: + dump("kill did not end the session", session_id) + raise + + with subtest("the pid, its children, its process group and its session id are gone"): + try: + # Bounded, and only for the kernel to finish a teardown the daemon + # has already performed: `kill` returns after the process group was + # signalled, the grace spent and the session id swept. It is not a + # retry of the assertion -- if anything is still there after this, + # something escaped. + machine.wait_until_succeeds(gone(pid, pgid, sid, children), timeout=60) + print(machine.succeed("ps -eo pid,pgid,sid,stat,comm --sort=pid")) + except Exception: + dump("something survived the kill", session_id) + raise + + with subtest("the compositor no longer lists the client"): + try: + machine.wait_until_succeeds( + f"{HYPRCTL} clients | jq -e --argjson pid {pid} 'all(.pid != $pid)' >/dev/null", + timeout=60, + ) + clients = json.loads(machine.succeed(f"{HYPRCTL} clients", timeout=120)) + print(f"compositor clients by pid: {[c.get('pid') for c in clients]}") + assert pid not in [c.get("pid") for c in clients] + except Exception: + dump("the compositor still lists the killed client", session_id) + raise + + with subtest("the idle reaper fires for real"): + # No injected clock anywhere: the daemon's own CLOCK_BOOTTIME deadline, + # a five-second timeout, and real time passing in the guest. + # + # `start --json` rather than start-then-status, so the pid is captured + # in the same call that created the session: with a five-second window + # a second round trip could land after the reaper had already fired. + try: + reaped = json.loads(machine.succeed(cli("start --json --idle-timeout 5s foot"), timeout=180)) + reaped_id, reaped_pid = reaped["id"], reaped["pid"] + reaped_pgid, reaped_sid = reaped["pgid"], reaped["sid"] + print(f"short-lived session {reaped_id}: pid {reaped_pid}, timeout " + f"{reaped['idle_timeout_s']}s") + assert reaped["idle_timeout_s"] == 5.0, reaped["idle_timeout_s"] + assert reaped["state"] == "ready", reaped["state"] + # Nothing touches it. The only wait is for the deadline to arrive. + machine.wait_until_succeeds( + cli(f"status --json {reaped_id}") + + " | jq -e '.session.state == \"reaped\"' >/dev/null", + timeout=90, + ) + record = json.loads(machine.succeed(cli(f"status --json {reaped_id}"), timeout=120))["session"] + assert record["state"] == "reaped", record["state"] + assert record["live"] is False, record + except Exception: + dump("the idle reaper never fired", locals().get("reaped_id")) + raise + + with subtest("the reaped session's application is gone"): + try: + machine.wait_until_succeeds(gone(reaped_pid, reaped_pgid, reaped_sid), timeout=60) + except Exception: + dump("the reaper left the application running", reaped_id) + raise + + with subtest("a session touched inside the window is not reaped"): + # The other half of the clock. Without this the subtest above would be + # satisfied by a daemon that killed everything after five seconds + # whatever the caller did, which proves nothing about `touch`. + # + # Six seconds of idle window, a touch every two seconds, for fourteen + # seconds -- more than twice the window, so a `touch` that did not + # reset the clock would have let the reaper fire at t=6. The assertion + # itself runs once, after the loop. + try: + kept = json.loads(machine.succeed(cli("start --json --idle-timeout 6s foot"), timeout=180)) + kept_id, kept_pid = kept["id"], kept["pid"] + print(f"touched session {kept_id}: pid {kept_pid}, timeout {kept['idle_timeout_s']}s") + assert kept["idle_timeout_s"] == 6.0, kept["idle_timeout_s"] + machine.succeed( + "for i in 1 2 3 4 5 6 7; do " + + cli(f"touch {kept_id}") + + " >/dev/null; sleep 2; done", + timeout=180, + ) + record = json.loads(machine.succeed(cli(f"status --json {kept_id}"), timeout=120))["session"] + print(json.dumps(record, indent=2, sort_keys=True)) + assert record["state"] == "ready", ( + f"a session touched every 2s inside a 6s window is {record['state']!r}" + ) + assert record["live"] is True, record + machine.succeed(f"kill -0 {kept_pid}") + # Leave nothing behind for the restart subtest to trip over. + machine.succeed(cli(f"kill {kept_id}"), timeout=180) + except Exception: + dump("a touched session was reaped anyway", locals().get("kept_id")) + raise + + with subtest("a session survives a restart of the broker"): + try: + survivor = json.loads(machine.succeed(cli("start --json foot"), timeout=180)) + survivor_id, survivor_pid = survivor["id"], survivor["pid"] + print(f"survivor {survivor_id}: pid {survivor_pid}") + machine.succeed("systemctl restart hhstream-sessions.service", timeout=180) + machine.wait_for_unit("hhstream-sessions.service", timeout=180) + # The new daemon rebinds the socket and adopts the live records + # before it answers; one bounded wait for it to answer at all, + # rather than for the answer we want. + machine.wait_until_succeeds(cli("list") + " >/dev/null", timeout=120) + record = json.loads( + machine.succeed(cli(f"status --json {survivor_id}"), timeout=120) + )["session"] + print(json.dumps(record, indent=2, sort_keys=True)) + assert record["pid"] == survivor_pid, ( + f"re-adopted as pid {record['pid']}, not {survivor_pid}" + ) + assert record["state"] == "ready", f"re-adopted as {record['state']!r}" + assert record["adopted"] is True, "the record does not say it was adopted" + assert record["pgid"] == survivor["pgid"], record + assert record["sid"] == survivor["sid"], record + machine.succeed(f"kill -0 {survivor_pid}") + except Exception: + dump("the session did not survive the restart", locals().get("survivor_id")) + raise + + with subtest("the re-adopted session is still killable"): + try: + reply = json.loads(machine.succeed(cli(f"kill --json {survivor_id}"), timeout=180)) + assert reply["ok"] is True, reply + assert reply["session"]["state"] == "killed", reply["session"] + machine.wait_until_succeeds( + gone(survivor_pid, survivor["pgid"], survivor["sid"]), timeout=60 + ) + machine.succeed("systemctl is-active hhstream-sessions.service") + except Exception: + dump("the re-adopted session could not be killed", locals().get("survivor_id")) + raise + ''; +} diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 8dd103e..ec0c37c 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -70,6 +70,7 @@ So the requirements are: | `tests/unit` | the framing, the capture wrapper and the server's client handling, with no compositor and no GPU | | `checks.vm-basic` | the module actually starts both units, the socket appears with the right owner/mode, the Hello parses and two frames arrive — with a fake capture program | | `checks.vm-hyprland` | the real thing: headless Hyprland comes up in the VM and `grim` captures a frame of the configured size | +| `checks.vm-sessions` | the session broker side: a real application runs as a tracked session on the compositor, the compositor's IPC sees its window, the idle reaper fires for real (and does not fire when the session is touched), and a broker restart adopts its sessions back | `vm-hyprland` is the only check that can fail for reasons outside this repo, so it is kept separate from `vm-basic` on purpose: when it fails, the compositor's diff --git a/examples/hhstream-sessions.config.example.toml b/examples/hhstream-sessions.config.example.toml new file mode 100644 index 0000000..2fe13ec --- /dev/null +++ b/examples/hhstream-sessions.config.example.toml @@ -0,0 +1,51 @@ +# hhstreamd configuration — the app allowlist. +# +# This is the main security control (DESIGN.md §8 item 1). Without it, +# `hhstream session start /bin/sh` would make every other control decorative. +# +# The daemon reads this at startup from --config / $HHSTREAM_CONFIG, defaulting +# to /etc/hhstream/config.toml. A missing file is not an error: the allowlist is +# then empty and every `start` is refused with exit 6, naming the file it looked +# for. A misconfigured deployment must not look like a crash. + +[defaults] +# The maximum number of live sessions. With no cgroup caps available (see +# DESIGN.md §3.3), this is the primary containment control against a looping +# agent spawning browsers, so it is a real setting and not a tuning knob. +max_sessions = 4 + +# Default idle timeout, in seconds. A session with no `touch` for this long is +# reaped. `touch` is the only thing that resets the clock. +idle_timeout_s = 10800 # 3h + +# The largest idle timeout a caller may ask for. +max_idle_timeout_s = 86400 # 24h + +# How long `kill` waits between SIGTERM and SIGKILL, by default. +grace_s = 10 + +# How long `start` will wait for readiness before returning exit 7. The session +# is left alive either way. +wait_ready_s = 15 + +# --------------------------------------------------------------------------- +# Apps. The key is the name a caller passes to `start`; it is never a path. +# --------------------------------------------------------------------------- + +[apps.chromium] +# Absolute path, always. Resolution against PATH is refused. +exec = "/run/current-system/sw/bin/chromium" +# Caller-supplied arguments must each match one of these fnmatch patterns. +# An app with no `args_allow` accepts no caller arguments at all. +args_allow = ["--new-window", "--app=*", "--user-data-dir=*"] + +[apps.foot] +exec = "/run/current-system/sw/bin/foot" + +[apps.blender] +exec = "/run/current-system/sw/bin/blender" +# Fixed arguments, always prepended, never supplied by the caller. +args = ["--factory-startup"] +args_allow = ["*.blend"] +# A per-app default idle timeout, overridden by --idle-timeout. +idle_timeout_s = 7200 diff --git a/nix/module.nix b/nix/module.nix index 331431b..d2857dc 100644 --- a/nix/module.nix +++ b/nix/module.nix @@ -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 + ]; + }; + }; }; } diff --git a/pyproject.toml b/pyproject.toml index 92f2bca..8532cae 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -12,6 +12,10 @@ dependencies = [] [project.scripts] hhstream-server = "hhstream.server:main" hhstream-client = "hhstream.client:main" +# The one front door: frames/launch/record verbs plus the `session` namespace. +hhstream = "hhstream.cli:main" +# The session daemon. A separate process on purpose: it outlives every CLI call. +hhstreamd = "hhstreamd.__main__:main" [tool.setuptools.packages.find] where = ["src"] \ No newline at end of file diff --git a/src/hhstream/cli.py b/src/hhstream/cli.py new file mode 100644 index 0000000..fd7b12a --- /dev/null +++ b/src/hhstream/cli.py @@ -0,0 +1,345 @@ +"""``hhstream`` — the one front door to this machine's headless Hyprland session. + +Four verbs that work whether or not the session daemon is running, and one +namespace that needs it: + + hhstream status is the session up, and can I reach it? + hhstream shot one frame of the screen + hhstream run -- CMD... launch a GUI app into the session (unmanaged) + hhstream record film the screen for N seconds + hhstream session ... managed application sessions (start/list/touch/kill) + +``run`` and ``session start`` both put an application on the screen; they are +deliberately different. ``run`` is the primitive: it execs and forgets, nothing +tracks the process, and stopping it is the caller's problem. ``session start`` +registers it, reports its pid, keeps its own clock, can be killed by name, and is +reaped if it goes quiet for too long. + +Access: the frame socket lives in a directory owned by the compositor's group +(mode 0750). If this process cannot read it, the CLI re-execs itself through the +*setuid* ``sg`` wrapper — deliberately, because a non-setuid ``sg`` earlier on +PATH fails with "setgroups: Operation not permitted", which looks like every +other failure. +""" + +from __future__ import annotations + +import argparse +import os +import pathlib +import shlex +import shutil +import subprocess +import sys +import time +from typing import Iterator + +from . import client as frames +from . import protocol + +#: The frame socket the compositor's publisher serves. +DEFAULT_FRAME_SOCKET = frames.DEFAULT_SOCKET +ENV_FRAME_SOCKET = "HHSTREAM_FRAME_SOCKET" +#: The group that owns the session's runtime directory. +DEFAULT_GROUP = "hhstream" +ENV_GROUP = "HHSTREAM_GROUP" +#: The units `status` reports on. Overridable so the CLI is not welded to this +#: machine's naming, but the defaults are the ones the module ships. +DEFAULT_UNITS = ("hyprland-headless.service", "hyprland-headless-stream.service") +ENV_UNITS = "HHSTREAM_UNITS" + +FFMPEG = "ffmpeg" + + +# ── access ───────────────────────────────────────────────────────────────── + + +def setuid_sg() -> str | None: + """The ``sg`` that can actually switch groups. + + Two exist on a NixOS box: the setuid wrapper in /run/wrappers/bin and a + plain symlink to shadow's copy in the system profile. Only the wrapper + works; a login shell happens to find it first, a cron job does not. + """ + + candidates = ["/run/wrappers/bin/sg", shutil.which("sg")] + for path in candidates: + if not path or not os.path.isfile(path) or not os.access(path, os.X_OK): + continue + if os.stat(path).st_mode & 0o4000: + return path + return None + + +def have_access(socket_path: str) -> bool: + directory = pathlib.Path(socket_path).parent + return os.access(directory, os.X_OK) and os.access(socket_path, os.R_OK) + + +def ensure_access(socket_path: str, group: str, argv: list[str]) -> None: + """Re-exec through ``sg`` when the socket is out of reach. Returns if fine.""" + + if have_access(socket_path): + return + sg = setuid_sg() + if sg is None: + sys.exit( + f"hhstream: cannot reach {socket_path} and no setuid 'sg' was found " + f"(looked in /run/wrappers/bin) to join group {group!r}" + ) + os.execv(sg, [sg, group, "-c", " ".join(shlex.quote(a) for a in argv)]) + + +def wayland_socket(runtime_dir: str) -> pathlib.Path | None: + """Whichever ``wayland-N`` the compositor bound — never assume ``-0``.""" + + root = pathlib.Path(runtime_dir) + for candidate in sorted(root.glob("wayland-*")): + if candidate.name.endswith(".lock"): + continue + if candidate.is_socket(): + return candidate + return None + + +# ── helpers ──────────────────────────────────────────────────────────────── + + +def read_frames(socket_path: str, *, count: int, timeout: float) -> tuple[dict, list[bytes]]: + return frames.read_stream(socket_path, count=count, timeout=timeout) + + +def frame_extension(hello: dict) -> str: + return "jpg" if str(hello.get("format", "")).endswith("jpeg") else "png" + + +def stream_frames(socket_path: str, seconds: float, timeout: float = 10.0) -> Iterator[bytes]: + """Yield frames off one connection until `seconds` of wall time have passed. + + One connection on purpose: the publisher drops frames for a slow reader + rather than queueing them, and reconnecting per frame would make us the slow + reader. + """ + + import socket as _socket + + conn = _socket.socket(_socket.AF_UNIX, _socket.SOCK_STREAM) + conn.settimeout(timeout) + try: + conn.connect(socket_path) + with conn.makefile("rb") as stream: + protocol.read_hello(stream) + started = time.monotonic() + while time.monotonic() - started < seconds: + payload = protocol.read_frame(stream) + if payload is None: + return + yield payload + finally: + conn.close() + + +def env_for_session(runtime_dir: str) -> dict[str, str]: + """The environment a GUI client needs to attach to the running compositor.""" + + wayland = wayland_socket(runtime_dir) + if wayland is None: + sys.exit(f"hhstream: no wayland socket in {runtime_dir} — is the compositor up?") + return { + "XDG_RUNTIME_DIR": runtime_dir, + "WAYLAND_DISPLAY": wayland.name, + "XDG_SESSION_TYPE": "wayland", + } + + +# ── verbs ────────────────────────────────────────────────────────────────── + + +def cmd_status(args: argparse.Namespace) -> int: + units = [u for u in (os.environ.get(ENV_UNITS) or "").split(",") if u] or list(DEFAULT_UNITS) + print("services:") + for unit in units: + state = subprocess.run( + ["systemctl", "is-active", unit], capture_output=True, text=True + ).stdout.strip() or "unknown" + print(f" {unit:<34} {state}") + print(f"frame: {args.frame_socket}") + print(f"access: {'readable' if have_access(args.frame_socket) else 'DENIED'}") + runtime_dir = str(pathlib.Path(args.frame_socket).parent) + wayland = wayland_socket(runtime_dir) + print(f"wayland: {wayland if wayland else 'none found'}") + print("probe: ", end="") + try: + hello, payloads = read_frames(args.frame_socket, count=1, timeout=args.timeout) + except OSError as exc: + print(f"no frame — {exc}") + return 1 + if not payloads: + print("no frame — the publisher closed without sending one") + return 1 + print(f"{len(payloads[0])} bytes, {hello['width']}x{hello['height']} {hello['format']}") + return 0 + + +def cmd_shot(args: argparse.Namespace) -> int: + hello, payloads = read_frames(args.frame_socket, count=1, timeout=args.timeout) + if not payloads: + print("hhstream: the publisher sent no frame", file=sys.stderr) + return 1 + out = pathlib.Path(args.out or f"hhstream-frame.{frame_extension(hello)}") + out.parent.mkdir(parents=True, exist_ok=True) + out.write_bytes(payloads[0]) + print(out) + return 0 + + +def cmd_run(args: argparse.Namespace) -> int: + argv = list(args.argv or []) + if not argv: + print("hhstream: run needs a command, e.g. hhstream run -- myapp", file=sys.stderr) + return 2 + env = dict(os.environ) + env.update(env_for_session(str(pathlib.Path(args.frame_socket).parent))) + os.execvpe(argv[0], argv, env) + return 0 # unreachable with execvpe + + +def cmd_record(args: argparse.Namespace) -> int: + if shutil.which(FFMPEG) is None: + print(f"hhstream: {FFMPEG} is not on PATH", file=sys.stderr) + return 1 + + out = pathlib.Path(args.out or "hhstream-recording.mp4") + work = pathlib.Path(args.work_dir) if args.work_dir else pathlib.Path( + os.environ.get("TMPDIR", "/tmp") + ) / f"hhstream-rec-{os.getpid()}" + work.mkdir(parents=True, exist_ok=True) + + hello, first = read_frames(args.frame_socket, count=1, timeout=args.timeout) + ext = frame_extension(hello) + if first: + (work / f"frame-{1:05d}.{ext}").write_bytes(first[0]) + + count = len(first) + started = time.monotonic() + for payload in stream_frames(args.frame_socket, max(0.0, args.seconds - 0.05)): + count += 1 + (work / f"frame-{count:05d}.{ext}").write_bytes(payload) + elapsed = max(time.monotonic() - started, 0.001) + + if count == 0: + print(f"hhstream: read no frames in {args.seconds}s", file=sys.stderr) + return 1 + + # Encode at the *measured* rate: a software-rendered VM tops out well under + # the advertised fps, so anything else would play back at the wrong speed. + fps = max(1, round(count / elapsed)) + subprocess.run( + [ + FFMPEG, "-hide_banner", "-loglevel", "error", "-y", + "-framerate", str(fps), + "-i", str(work / f"frame-%05d.{ext}"), + "-c:v", "libx264", "-pix_fmt", "yuv420p", + "-vf", "scale=trunc(iw/2)*2:trunc(ih/2)*2", + # Media stores reject files carrying metadata; strip it here so a + # recording is uploadable without a second pass. + "-map_metadata", "-1", "-fflags", "+bitexact", "-flags:v", "+bitexact", + str(out), + ] + ) + print(f"{out} ({count} frames in {elapsed:.2f}s -> {fps} fps)") + if not args.keep: + shutil.rmtree(work, ignore_errors=True) + return 0 + + +# ── parser ───────────────────────────────────────────────────────────────── + + +def build_parser() -> argparse.ArgumentParser: + parser = argparse.ArgumentParser( + prog="hhstream", + description=( + "Work this machine's headless Hyprland session: look at it, put an " + "application on it, manage that application as a session." + ), + epilog=( + "'run' launches and forgets. 'session start' launches and tracks — " + "use it when something must be found, kept alive and killed later." + ), + formatter_class=argparse.RawDescriptionHelpFormatter, + ) + parser.add_argument( + "--frame-socket", + default=os.environ.get(ENV_FRAME_SOCKET, DEFAULT_FRAME_SOCKET), + metavar="PATH", + help=f"the compositor's frame socket (default: ${ENV_FRAME_SOCKET} or " + f"{DEFAULT_FRAME_SOCKET})", + ) + parser.add_argument( + "--timeout", type=float, default=10.0, metavar="SECONDS", help="per-read socket timeout" + ) + parser.add_argument( + "--group", + default=os.environ.get(ENV_GROUP, DEFAULT_GROUP), + metavar="NAME", + help=f"group that owns the session's runtime directory (default: {DEFAULT_GROUP})", + ) + + verbs = parser.add_subparsers(dest="command", metavar="COMMAND") + + verbs.add_parser("status", help="are the units up, and can this process reach the socket?") + + shot = verbs.add_parser("shot", help="write one frame of the screen") + shot.add_argument("--out", metavar="FILE", help="where to write it (default: ./hhstream-frame.*)") + + run = verbs.add_parser("run", help="launch a GUI app into the session (unmanaged)") + run.add_argument("argv", nargs="*", metavar="-- CMD...", help="the command, after a literal --") + + record = verbs.add_parser("record", help="film the screen for N seconds") + record.add_argument("--seconds", type=float, default=10.0, metavar="N") + record.add_argument("--out", metavar="FILE", help="output mp4 (default: ./hhstream-recording.mp4)") + record.add_argument("--work-dir", metavar="DIR", help="where frames go (default: a temp dir)") + record.add_argument("--keep", action="store_true", help="keep the frames after encoding") + + # The managed namespace. It brings its own --socket (the *control* socket, + # which is a different socket from the frame one) and its own exit codes. + from hhstream_session import register as register_session + + register_session(verbs) + + return parser + + +def main(argv: list[str] | None = None) -> int: + parser = build_parser() + args = parser.parse_args(argv) + + if args.command is None: + parser.print_help(sys.stderr) + return 2 + + # Every verb except the session namespace speaks to the frame socket, so the + # group check happens here, once. The session handlers do their own. + if args.command in ("status", "shot", "run", "record"): + # Re-exec the ORIGINAL command line, not a reconstruction: `sys.executable` + # plus the arguments would drop this script's own path and hand Python a + # verb as a filename ("can't open file 'status'"). + argv = list(getattr(sys, "orig_argv", None) or [sys.executable, *sys.argv]) + ensure_access(args.frame_socket, args.group, argv) + + handler = { + "status": cmd_status, + "shot": cmd_shot, + "run": cmd_run, + "record": cmd_record, + }.get(args.command) + if handler is not None: + return handler(args) + + # session … — argparse already selected the handler when it parsed + return int(getattr(args, "func")(args)) + + +if __name__ == "__main__": # pragma: no cover + raise SystemExit(main()) diff --git a/src/hhstream_session/__init__.py b/src/hhstream_session/__init__.py new file mode 100644 index 0000000..e8f8296 --- /dev/null +++ b/src/hhstream_session/__init__.py @@ -0,0 +1,508 @@ +"""``hhstream session …`` — the CLI handlers, as a drop-in for someone else's CLI. + +The integration contract is one function:: + + from hhstream_session import register + register(subparsers) # subparsers from argparse's add_subparsers() + ... + args = parser.parse_args() + raise SystemExit(args.func(args)) + +``register`` adds a single ``session`` subcommand with its own verb tree, sets +``func`` (and ``hhstream_session_handler``, for hosts that dispatch on their own +attribute) to a callable taking the parsed namespace and returning an **exit +code from the frozen table** in ``DESIGN.md`` §1.6. The registrant needs to +know nothing about the daemon beyond the socket path, which comes from +``--socket`` or ``$HHSTREAM_SOCKET``. + +Nothing here is imported until a ``session`` verb actually runs: the module +imports only :mod:`hhstreamd.protocol` (framing and exit codes) and the +standard library, so a host CLI pays no startup cost and gains no new failure +mode by registering it. + +**The one thing to read before using this:** ``touch`` is the only mark of +activity that exists. ``list``, ``status``, ``logs`` and ``gc`` deliberately do +not reset a session's idle clock, so an agent watching a long-running app must +call ``touch`` or the session will be reaped on schedule. +""" + +from __future__ import annotations + +import argparse +import sys +import time +from typing import Any, Callable + +from hhstreamd.clock import format_duration, parse_duration +from hhstreamd.protocol import ExitCode + +from . import format as fmt +from .client import DEFAULT_SOCKET, ENV_SOCKET, ClientError, call, reply_exit_code + +__all__ = ["register", "build_parser", "dispatch", "main", "ExitCode"] + +#: Printed under `session --help` and under `start --help`. It is here, in two +#: places, because it is the single fact an agent gets wrong. +ACTIVITY_NOTE = ( + "ACTIVITY: 'touch' is the ONLY thing that resets a session's idle clock. " + "'list', 'status', 'logs' and 'gc' do NOT count — if polling kept sessions " + "alive, an abandoned session would never be reaped. An agent that leaves an " + "app running must call 'hhstream session touch ' before the idle timeout " + "expires." +) + +_FOLLOW_INTERVAL_S = 0.5 + + +# -------------------------------------------------------------------------- +# registration +# -------------------------------------------------------------------------- + + +def register(subparsers: Any, *, name: str = "session") -> argparse.ArgumentParser: + """Add the ``session`` namespace to an existing argparse subparser set. + + Returns the namespace's parser, so a host that wants to add to it can. + """ + + parser = subparsers.add_parser( + name, + help="manage tracked application sessions (needs the hhstream session daemon)", + description="Start, inspect, keep alive and kill tracked application sessions.", + epilog=ACTIVITY_NOTE, + formatter_class=argparse.RawDescriptionHelpFormatter, + ) + _build_namespace(parser) + return parser + + +def _socket_parent() -> argparse.ArgumentParser: + """Shared ``--socket`` so it may be given before *or* after the verb. + + ``SUPPRESS`` matters: without it the verb-level default would overwrite a + value given at the namespace level. + """ + + common = argparse.ArgumentParser(add_help=False) + common.add_argument( + "--socket", + default=argparse.SUPPRESS, + metavar="PATH", + help=f"control socket (default: ${ENV_SOCKET} or {DEFAULT_SOCKET})", + ) + return common + + +def _build_namespace(parser: argparse.ArgumentParser) -> None: + common = _socket_parent() + parser.add_argument( + "--socket", + default=None, + metavar="PATH", + help=f"control socket (default: ${ENV_SOCKET} or {DEFAULT_SOCKET})", + ) + # `hhstream session` with no verb lists, because that is what everyone + # types first. + parser.set_defaults(func=_cmd_list, hhstream_session_handler=_cmd_list, all=False, json=False) + + verbs = parser.add_subparsers(dest="session_verb", metavar="VERB") + + def add(name: str, handler: Callable[[argparse.Namespace], int], **kwargs: Any): + sub = verbs.add_parser(name, parents=[common], **kwargs) + sub.set_defaults(func=handler, hhstream_session_handler=handler) + sub.add_argument("--json", action="store_true", help="emit the protocol object on stdout") + return sub + + # ---- start ------------------------------------------------------- + start = add( + "start", + _cmd_start, + help="launch an allowlisted application as a tracked session", + description=( + "Launch an allowlisted application. Prints the bare session id on " + "stdout and human-readable detail on stderr, so $(hhstream session " + "start foo) is the id and nothing else.\n\n" + "Everything after a literal -- is passed to the application as an " + "argv list: 'session start chromium -- --new-window URL'." + ), + epilog=ACTIVITY_NOTE, + formatter_class=argparse.RawDescriptionHelpFormatter, + ) + start.add_argument("app", help="an app name from the daemon's allowlist, never a path") + start.add_argument( + "argv", + nargs="*", + metavar="-- ARGV...", + help="arguments for the application, after a literal --. Passed as an " + "argv list; there is never a shell.", + ) + start.add_argument( + "--idle-timeout", + type=_duration, + metavar="DURATION", + help="reap the session after this long with no 'touch' (e.g. 30s, 5m, 3h)", + ) + start.add_argument( + "--wait-ready", + type=_duration, + metavar="DURATION", + help="how long to wait for the app to signal readiness", + ) + home = start.add_mutually_exclusive_group() + home.add_argument( + "--home", metavar="PATH", help="run the app with this HOME instead of the inherited one" + ) + home.add_argument( + "--ephemeral-home", + action="store_true", + help="give the session a private HOME and delete it when the session ends " + "(opt-in; by default the app inherits the real home directory)", + ) + start.add_argument( + "--request-id", + metavar="ID", + help="deduplication token: retrying a start with the same id returns the " + "original reply instead of launching a second application", + ) + + # ---- list -------------------------------------------------------- + lst = add("list", _cmd_list, help="list sessions (does NOT count as activity)") + lst.add_argument("--all", action="store_true", help="include tombstones of ended sessions") + + # ---- status ------------------------------------------------------ + status = add("status", _cmd_status, help="show one session (does NOT count as activity)") + status.add_argument("id", help="session id") + status.add_argument( + "--events", type=int, default=20, metavar="N", help="recent audit events to include" + ) + + # ---- touch ------------------------------------------------------- + add( + "touch", + _cmd_touch, + help="reset the idle clock — THE ONLY MARK OF ACTIVITY", + description=( + "Reset the session's idle clock. Injects nothing, changes nothing " + "else, and is the only verb that counts as activity: an agent " + "observing a long-running application has no other way to say " + "'still working'." + ), + epilog=ACTIVITY_NOTE, + formatter_class=argparse.RawDescriptionHelpFormatter, + ).add_argument("id", help="session id") + + # ---- kill -------------------------------------------------------- + kill = add("kill", _cmd_kill, help="terminate a session and everything it spawned") + kill.add_argument("id", help="session id") + kill.add_argument( + "--grace", + type=_duration, + metavar="DURATION", + help="how long to wait after the first signal before SIGKILL (default: the daemon's)", + ) + kill.add_argument( + "--signal", default="TERM", metavar="SIG", help="first signal to send (default: TERM)" + ) + kill.add_argument("--request-id", metavar="ID", help="deduplication token") + + # ---- gc ---------------------------------------------------------- + add( + "gc", + _cmd_gc, + help="prune tombstones and reconcile the registry with /proc " + "(does NOT count as activity)", + ).add_argument("--request-id", metavar="ID", help="deduplication token") + + # ---- adopt ------------------------------------------------------- + adopt = add("adopt", _cmd_adopt, help="bring an already-running process under management") + adopt.add_argument("--pid", type=int, required=True, help="pid to adopt") + adopt.add_argument("--app", help="name to record (default: the executable's basename)") + adopt.add_argument("--idle-timeout", type=_duration, metavar="DURATION") + adopt.add_argument("--request-id", metavar="ID", help="deduplication token") + + # ---- logs -------------------------------------------------------- + logs = add( + "logs", + _cmd_logs, + help="the application's captured stdout/stderr (does NOT count as activity)", + ) + logs.add_argument("id", help="session id") + logs.add_argument("--lines", type=int, default=100, metavar="N", help="tail this many lines") + logs.add_argument( + "--follow", "-f", action="store_true", help="keep printing new output until interrupted" + ) + + +def _duration(text: str) -> float: + try: + return parse_duration(text) + except ValueError as exc: + raise argparse.ArgumentTypeError(str(exc)) from exc + + +# -------------------------------------------------------------------------- +# handlers +# -------------------------------------------------------------------------- + + +def _socket_of(args: argparse.Namespace) -> str | None: + return getattr(args, "socket", None) + + +def _request(args: argparse.Namespace, op: str, **fields: Any) -> dict[str, Any]: + return call(op, socket_path=_socket_of(args), **fields) + + +def _finish(args: argparse.Namespace, reply: dict[str, Any], render) -> int: + """Print a reply and return its exit code. + + Errors always go to stderr and always carry the machine field, whatever the + output mode, because that is what an agent branches on. + """ + + code = reply_exit_code(reply) + if getattr(args, "json", False): + fmt.dump_json(reply, stream=sys.stdout if reply.get("ok") else sys.stderr) + elif reply.get("ok"): + text = render(reply) + if text: + print(text) + else: + print(fmt.render_error(reply), file=sys.stderr) + return int(code) + + +def _guard(handler: Callable[[argparse.Namespace], int]) -> Callable[[argparse.Namespace], int]: + def wrapper(args: argparse.Namespace) -> int: + try: + return handler(args) + except ClientError as exc: + if getattr(args, "json", False): + fmt.dump_json( + {"ok": False, "error": exc.error, "reason": exc.reason, "hint": exc.hint}, + stream=sys.stderr, + ) + else: + print(f"error: {exc.reason}", file=sys.stderr) + if exc.hint: + print(f"hint: {exc.hint}", file=sys.stderr) + return int(exc.exit_code) + except KeyboardInterrupt: + return int(ExitCode.USAGE) + + wrapper.__name__ = handler.__name__ + wrapper.__doc__ = handler.__doc__ + return wrapper + + +@_guard +def _cmd_start(args: argparse.Namespace) -> int: + # argparse has already removed the separating `--`, so what is left is the + # application's own argv, as a list. It is never joined into a string. + argv = list(args.argv or []) + reply = _request( + args, + "start", + app=args.app, + argv=argv, + idle_timeout_s=args.idle_timeout, + wait_ready_s=args.wait_ready, + home=args.home, + ephemeral_home=args.ephemeral_home or None, + request_id=args.request_id, + ) + if not reply.get("ok"): + # A failed start may still have created a session (it exited at once, or + # it is slow to become ready). Print the id so it can be inspected. + if reply.get("id") and not args.json: + print(reply["id"]) + return _finish(args, reply, lambda r: "") + session = reply.get("session") or {} + if args.json: + fmt.dump_json(session) + return int(ExitCode.OK) + session_id = reply.get("id") or session.get("id") or "" + # stdout is the bare id and nothing else; detail goes to stderr. + print(session_id) + print( + f"started {session.get('app')} → {session_id} " + f"(pid {session.get('pid')}, pgid {session.get('pgid')}, sid {session.get('sid')})", + file=sys.stderr, + ) + print( + f"state {session.get('state')} via {session.get('ready_signal')}; " + f"idle timeout {_fmt_timeout(session.get('idle_timeout_s'))}", + file=sys.stderr, + ) + print( + f"keep it alive with: hhstream session touch {session_id} " + "(the only mark of activity; list/status/logs/gc do not count)", + file=sys.stderr, + ) + return int(ExitCode.OK) + + +def _fmt_timeout(seconds: Any) -> str: + return "disabled" if not seconds else format_duration(seconds) + + +@_guard +def _cmd_list(args: argparse.Namespace) -> int: + reply = _request(args, "list", all=bool(getattr(args, "all", False)) or None) + return _finish(args, reply, lambda r: fmt.render_list(r.get("sessions") or [])) + + +@_guard +def _cmd_status(args: argparse.Namespace) -> int: + reply = _request(args, "status", id=args.id, events=args.events) + return _finish(args, reply, lambda r: fmt.render_status(r.get("session") or {})) + + +@_guard +def _cmd_touch(args: argparse.Namespace) -> int: + reply = _request(args, "touch", id=args.id) + + def render(r: dict[str, Any]) -> str: + session = r.get("session") or {} + return ( + f"{session.get('id')}: idle clock reset; " + f"expires in {format_duration(session.get('expires_in_s'))}" + ) + + return _finish(args, reply, render) + + +@_guard +def _cmd_kill(args: argparse.Namespace) -> int: + reply = _request( + args, + "kill", + id=args.id, + grace_s=args.grace, + signal=args.signal, + request_id=args.request_id, + ) + + def render(r: dict[str, Any]) -> str: + """Say what the daemon actually did, not merely that it finished. + + The old rendering could only distinguish "signalled" from "not + signalled", and printed *the process was already gone* for both the + routine case and the case where the daemon refused to signal a live + application (BUG-02). A refusal is now an error reply and never reaches + here; what is left is reported with the signal and the process group it + went to, so "killed" cannot be read as more than it says. + """ + + session = r.get("session") or {} + bits = [f"{session.get('id')}: {session.get('state')}"] + sent = session.get("signal_sent") + if sent: + bits.append(f"sent {sent} to process group {session.get('pgid')}") + if session.get("escalated_to_sigkill"): + bits.append("escalated to SIGKILL") + stragglers = session.get("stragglers") or 0 + if stragglers: + bits.append(f"{stragglers} straggler(s) swept by session id") + if session.get("signalled") is False and not sent: + bits.append("nothing signalled (the process was already gone)") + survivors = session.get("survivors") or [] + if survivors: + # The loudest thing this command can say: the kill did not work. + bits.append( + f"WARNING: {len(survivors)} process(es) SURVIVED " + f"({', '.join(str(p) for p in survivors)})" + ) + return "; ".join(bits) + + return _finish(args, reply, render) + + +@_guard +def _cmd_gc(args: argparse.Namespace) -> int: + reply = _request(args, "gc", request_id=args.request_id) + return _finish(args, reply, fmt.render_gc) + + +@_guard +def _cmd_adopt(args: argparse.Namespace) -> int: + reply = _request( + args, + "adopt", + pid=args.pid, + app=args.app, + idle_timeout_s=args.idle_timeout, + request_id=args.request_id, + ) + if reply.get("ok") and not args.json: + print(reply.get("id", "")) + session = reply.get("session") or {} + print( + f"adopted pid {session.get('pid')} as {reply['id']}; " + "exit code will be unavailable (not a child of the daemon)", + file=sys.stderr, + ) + return int(ExitCode.OK) + return _finish(args, reply, lambda r: "") + + +@_guard +def _cmd_logs(args: argparse.Namespace) -> int: + reply = _request(args, "logs", id=args.id, lines=args.lines) + if not reply.get("ok") or not args.follow: + return _finish(args, reply, lambda r: "\n".join(r.get("lines") or [])) + # --follow polls from the returned offset. The daemon holds no streaming + # connection open, so a follower that dies costs the daemon nothing. + for line in reply.get("lines") or []: + print(line) + offset = reply.get("offset", 0) + try: + while True: + if reply.get("eof"): + break + time.sleep(_FOLLOW_INTERVAL_S) + reply = _request(args, "logs", id=args.id, offset=offset) + if not reply.get("ok"): + return _finish(args, reply, lambda r: "") + for line in reply.get("lines") or []: + print(line) + offset = reply.get("offset", offset) + except KeyboardInterrupt: + pass + return int(ExitCode.OK) + + +# -------------------------------------------------------------------------- +# standalone use +# -------------------------------------------------------------------------- + + +def build_parser(prog: str = "hhstream") -> argparse.ArgumentParser: + """A host CLI stand-in, so the handlers can be driven without one.""" + + parser = argparse.ArgumentParser(prog=prog) + subparsers = parser.add_subparsers(dest="command", metavar="COMMAND") + register(subparsers) + return parser + + +def dispatch(args: argparse.Namespace) -> int: + """Run the handler argparse selected. The host may call this or ``args.func``.""" + + handler = getattr(args, "func", None) + if handler is None: + return int(ExitCode.USAGE) + return int(handler(args)) + + +def main(argv: list[str] | None = None) -> int: + parser = build_parser() + args = parser.parse_args(argv) + if getattr(args, "command", None) is None: + parser.print_help(sys.stderr) + return int(ExitCode.USAGE) + return dispatch(args) + + +if __name__ == "__main__": # pragma: no cover + raise SystemExit(main()) diff --git a/src/hhstream_session/__main__.py b/src/hhstream_session/__main__.py new file mode 100644 index 0000000..ec933a7 --- /dev/null +++ b/src/hhstream_session/__main__.py @@ -0,0 +1,9 @@ +"""``python -m hhstream_session`` — drive the handlers without a host CLI. + +The real integration is :func:`hhstream_session.register`; this exists so the +verbs can be exercised (and tested) standalone. +""" + +from . import main + +raise SystemExit(main()) diff --git a/src/hhstream_session/client.py b/src/hhstream_session/client.py new file mode 100644 index 0000000..4f495fc --- /dev/null +++ b/src/hhstream_session/client.py @@ -0,0 +1,109 @@ +"""The control-socket client (DESIGN.md §1.6, §10). + +Blocking, stdlib sockets, one request per connection. **One connect attempt, +then exit 5** — a CLI that silently retries hides a down daemon, and the hint +tells the operator where to look. +""" + +from __future__ import annotations + +import os +import socket +from typing import Any + +from hhstreamd import protocol +from hhstreamd.protocol import ExitCode, exit_code_for + +DEFAULT_SOCKET = "/run/hhstream/control.sock" +ENV_SOCKET = "HHSTREAM_SOCKET" + +#: How long to wait for the daemon to answer. The daemon's own per-request +#: deadline is shorter for every verb except `kill` and `start`, which are +#: allowed their grace and readiness budgets, so this is a backstop. +DEFAULT_TIMEOUT_S = 60.0 + + +class ClientError(Exception): + """A failure that never reached the daemon's dispatch.""" + + def __init__(self, error: str, reason: str, hint: str | None = None) -> None: + super().__init__(reason) + self.error = error + self.reason = reason + self.hint = hint + + @property + def exit_code(self) -> ExitCode: + return exit_code_for(self.error) + + +def default_socket_path() -> str: + return os.environ.get(ENV_SOCKET, DEFAULT_SOCKET) + + +def call( + op: str, + *, + socket_path: str | None = None, + timeout: float = DEFAULT_TIMEOUT_S, + **fields: Any, +) -> dict[str, Any]: + """Send one request, return the decoded reply. + + Raises :class:`ClientError` with ``daemon_unreachable`` (exit 5) if the + socket cannot be reached, and ``timeout`` (exit 7) if the daemon accepts the + request but never answers. + """ + + path = socket_path or default_socket_path() + message = protocol.request(op, **fields) + sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) + sock.settimeout(timeout) + try: + try: + sock.connect(path) + except (FileNotFoundError, ConnectionRefusedError, PermissionError, OSError) as exc: + raise ClientError( + "daemon_unreachable", + f"cannot reach the hhstream session daemon at {path}: {exc}", + hint="is hhstreamd running? (it is an ordinary process; check " + "however you supervise it)", + ) from exc + try: + sock.sendall(protocol.encode(message)) + buffer = bytearray() + while b"\n" not in buffer: + chunk = sock.recv(65536) + if not chunk: + break + buffer.extend(chunk) + if len(buffer) > protocol.MAX_LINE_BYTES: + raise ClientError("bad_request", "reply exceeds the frame limit") + except TimeoutError as exc: + raise ClientError( + "timeout", f"the daemon did not answer {op!r} within {timeout:g}s" + ) from exc + except OSError as exc: + raise ClientError("daemon_unreachable", f"control socket error: {exc}") from exc + finally: + sock.close() + + if not buffer.strip(): + raise ClientError("daemon_unreachable", "the daemon closed the connection without replying") + try: + return protocol.decode(bytes(buffer)) + except protocol.ProtocolError as exc: + raise ClientError(exc.error, f"malformed reply from the daemon: {exc.reason}") from exc + + +def reply_exit_code(reply: dict[str, Any]) -> ExitCode: + """The frozen exit code for a decoded reply. + + A reply that is not ``ok`` never yields 0, even if it carries no error name + the table knows: reporting success for an unexplained failure is the one + mistake an agent cannot recover from. + """ + + if reply.get("ok"): + return ExitCode.OK + return exit_code_for(reply.get("error") or "bad_state") diff --git a/src/hhstream_session/format.py b/src/hhstream_session/format.py new file mode 100644 index 0000000..0008a31 --- /dev/null +++ b/src/hhstream_session/format.py @@ -0,0 +1,155 @@ +"""Rendering for the human views. + +``--json`` output is the protocol's own objects, unmodified: a flag that +reshapes the data would mean two contracts to keep in step. The tables below +are for people. +""" + +from __future__ import annotations + +import json +import sys +from typing import Any + +from hhstreamd.clock import format_duration + +DASH = "—" + + +def dump_json(obj: Any, stream=None) -> None: + print(json.dumps(obj, indent=2, sort_keys=True), file=stream or sys.stdout) + + +def _cell(value: Any) -> str: + return DASH if value is None else str(value) + + +def render_table(rows: list[list[str]], headers: list[str]) -> str: + widths = [len(h) for h in headers] + for row in rows: + for i, cell in enumerate(row): + widths[i] = max(widths[i], len(cell)) + out = [" ".join(h.ljust(widths[i]) for i, h in enumerate(headers)).rstrip()] + for row in rows: + out.append(" ".join(cell.ljust(widths[i]) for i, cell in enumerate(row)).rstrip()) + return "\n".join(out) + + +def render_list(sessions: list[dict[str, Any]]) -> str: + """The default view. + + ``EXPIRES IN`` is on it rather than behind a flag because it is the number + an agent actually needs. + + There is **no ``FG`` column** (DESIGN.md §1.4, amended): foreground-ness + needs compositor IPC, which this milestone does not have, so the column was + ``?`` on every row of every listing — a header and six columns of width + paying for no information, and a reader who has to learn that ``?`` means + *unknown* rather than *no*. ``foreground`` stays in the record and in + ``status``, where it is one line among many and can become real without + changing the shape of this table. + """ + + if not sessions: + return "no sessions" + rows = [] + for s in sessions: + live = s.get("live") + if live: + idle = format_duration(s.get("idle_s")) + expires = format_duration(s.get("expires_in_s")) + if s.get("expires_in_s") is None: + expires = "never" + else: + idle = DASH + left = s.get("tombstone_expires_in_s") + expires = f"(tombstone, {format_duration(left)} left)" if left is not None else DASH + rows.append( + [ + _cell(s.get("id")), + _cell(s.get("app")), + _cell(s.get("state")), + _cell(s.get("pid")) if live else DASH, + idle, + expires, + ] + ) + return render_table(rows, ["ID", "APP", "STATE", "PID", "IDLE", "EXPIRES IN"]) + + +def render_status(session: dict[str, Any]) -> str: + live = session.get("live") + lines = [ + f"{session.get('id')} ({session.get('app')})", + f" state {session.get('state')}" + + (f" [{session.get('last_error')}]" if session.get("last_error") else ""), + f" pid {_cell(session.get('pid'))} pgid {_cell(session.get('pgid'))}" + f" sid {_cell(session.get('sid'))}", + f" argv {' '.join(session.get('argv') or []) or DASH}", + f" home {_cell(session.get('home'))}", + f" created {_cell(session.get('created_at'))}", + f" last activity {_cell(session.get('last_activity_at'))}" + f" ({session.get('command_count', 0)} command(s) counted)", + f" idle {format_duration(session.get('idle_s'))}" + f" of {format_duration(session.get('idle_timeout_s'))}", + f" expires in {format_duration(session.get('expires_in_s'))}" + if session.get("expires_in_s") is not None + else " expires in never (idle timeout disabled)", + f" ready signal {_cell(session.get('ready_signal'))}", + f" adopted {session.get('adopted')}", + ] + if not live: + lines.append( + f" exit code {_cell(session.get('exit_code'))}" + f" detected by {_cell(session.get('exit_detected_by'))}" + ) + if session.get("exit_detected_by") in ("pidfd", "proc_poll", "proc_check"): + lines.append(" exit code unavailable (adopted process)") + compositor = session.get("compositor") or {} + lines.append( + f" window {_cell(compositor.get('window'))}" + f" workspace {_cell(compositor.get('workspace'))}" + f" foreground {_cell(compositor.get('foreground'))}" + ) + if compositor.get("note"): + lines.append(f" {compositor['note']}") + events = session.get("events") or [] + if events: + lines.append(" recent events") + for event in events[-20:]: + lines.append(f" {event.get('ts')} {event.get('event')}") + return "\n".join(lines) + + +def render_gc(result: dict[str, Any]) -> str: + lines = [ + f"pruned {result.get('pruned', 0)} tombstone(s), " + f"reconciled {len(result.get('reconciled') or [])} session(s)", + f"{result.get('live', 0)} live, {result.get('tombstones', 0)} tombstone(s) remain", + ] + for item in result.get("reconciled") or []: + lines.append(f" {item['id']}: {item['why']}") + unresolved = result.get("unresolved") or [] + if unresolved: + # Not a routine exit: the daemon could not establish whether these pids + # are still their sessions', so it signalled nothing. Said loudly + # because the application may well still be running (BUG-02 item 5). + lines.append( + "UNRESOLVED — identity could not be established, nothing was signalled:" + ) + for item in unresolved: + mismatched = ", ".join(item.get("mismatched") or []) or "no usable evidence" + lines.append(f" {item['id']}: {item['why']} ({mismatched})") + orphans = result.get("orphans") or [] + if orphans: + lines.append("orphaned processes (escaped the process group AND the session id):") + for item in orphans: + lines.append(f" {item['id']} sid {item['sid']}: pids {item['pids']}") + return "\n".join(lines) + + +def render_error(reply: dict[str, Any]) -> str: + parts = [f"error: {reply.get('reason') or reply.get('error')}"] + if reply.get("hint"): + parts.append(f"hint: {reply['hint']}") + return "\n".join(parts) diff --git a/src/hhstreamd/__init__.py b/src/hhstreamd/__init__.py new file mode 100644 index 0000000..5edda31 --- /dev/null +++ b/src/hhstreamd/__init__.py @@ -0,0 +1,8 @@ +"""hhstreamd — the hhstream session daemon (M0). + +Deliberately import-light: the CLI handler package imports +:mod:`hhstreamd.protocol` for the wire format and the exit-code table, and +must not pay for the daemon's dependencies to do it. +""" + +__version__ = "0.1.0" diff --git a/src/hhstreamd/__main__.py b/src/hhstreamd/__main__.py new file mode 100644 index 0000000..2d13b42 --- /dev/null +++ b/src/hhstreamd/__main__.py @@ -0,0 +1,253 @@ +"""``python -m hhstreamd`` — the session daemon. + +An ordinary long-running process. It is deliberately **agnostic about how it +is supervised**: no unit file, no ``sd_notify``, no ``systemctl``. It creates +the directories it needs if they are not already there, so it runs the same +under systemd, under a shell, or under a test harness. +""" + +from __future__ import annotations + +import argparse +import asyncio +import contextlib +import logging +import os +import signal +import sys +from pathlib import Path + +from . import __version__ +from .audit import AuditLog +from .clock import Clock, parse_duration +from .compositor import CompositorError, CompositorTarget +from .launcher import Launcher +from .manager import DEFAULT_SETTLE_S, ManagerConfig, SessionManager +from .policy import Policy, PolicyError, load_policy +from .registry import Registry +from .server import ControlServer + +log = logging.getLogger("hhstreamd") + +DEFAULT_SOCKET = "/run/hhstream/control.sock" +DEFAULT_RUNTIME_DIR = "/run/hhstream" +DEFAULT_STATE_DIR = "/var/lib/hhstream" +DEFAULT_CONFIG = "/etc/hhstream/config.toml" + +ENV_SOCKET = "HHSTREAM_SOCKET" +ENV_RUNTIME_DIR = "HHSTREAM_RUNTIME_DIR" +ENV_STATE_DIR = "HHSTREAM_STATE_DIR" +ENV_CONFIG = "HHSTREAM_CONFIG" +ENV_COMPOSITOR_RUNTIME_DIR = "HHSTREAM_COMPOSITOR_RUNTIME_DIR" + +#: Printed at startup when no compositor runtime directory was given. It is a +#: warning and not an error because the daemon is useful without a compositor — +#: a console app, a test harness — but on a desktop machine this is BUG-01 +#: waiting to happen, and the operator should see it before the first `start`. +NO_COMPOSITOR_WARNING = ( + "no --compositor-runtime-dir (or $%s): launched applications will inherit " + "this daemon's environment (XDG_RUNTIME_DIR=%s, WAYLAND_DISPLAY=%s) and may " + "not be able to reach a compositor — a GUI app will then exit immediately " + "with 'Failed to connect to Wayland display'" +) + + +def build_parser() -> argparse.ArgumentParser: + parser = argparse.ArgumentParser( + prog="hhstreamd", + description=( + "The hhstream session daemon. Owns managed application sessions, " + "their process groups and the idle clock." + ), + epilog=( + "Every flag below may also be set from the environment: " + f"{ENV_SOCKET}, {ENV_RUNTIME_DIR}, {ENV_STATE_DIR}, {ENV_CONFIG}, " + f"{ENV_COMPOSITOR_RUNTIME_DIR}. " + "The flag wins. The daemon never speaks the Wayland protocol (it only " + "locates the compositor's socket so a launched app can) and never " + "integrates with systemd; supervise it however you like." + ), + ) + parser.add_argument("--version", action="version", version=f"hhstreamd {__version__}") + parser.add_argument( + "--socket", + default=os.environ.get(ENV_SOCKET, DEFAULT_SOCKET), + help="control socket path (default: %(default)s)", + ) + parser.add_argument( + "--state-dir", + default=os.environ.get(ENV_STATE_DIR, DEFAULT_STATE_DIR), + help="session records, logs and the audit log (default: %(default)s)", + ) + parser.add_argument( + "--runtime-dir", + default=os.environ.get(ENV_RUNTIME_DIR, DEFAULT_RUNTIME_DIR), + help="per-session XDG_RUNTIME_DIR parent (default: %(default)s)", + ) + parser.add_argument( + "--compositor-runtime-dir", + default=os.environ.get(ENV_COMPOSITOR_RUNTIME_DIR), + metavar="PATH", + help="the COMPOSITOR's runtime directory — the one holding its wayland-N " + "socket. This is not --runtime-dir (that is where this daemon's own " + "control socket and per-session scratch directories live). Given, the " + "socket is discovered by name and exported to every launched " + "application as XDG_RUNTIME_DIR/WAYLAND_DISPLAY/XDG_SESSION_TYPE, and " + "the daemon refuses to start if the directory holds no usable socket. " + "Omitted, applications inherit this daemon's environment and may not " + "reach a compositor at all.", + ) + parser.add_argument( + "--config", + default=os.environ.get(ENV_CONFIG, DEFAULT_CONFIG), + help="TOML app allowlist (default: %(default)s). A missing file means " + "an empty allowlist and every start refused.", + ) + parser.add_argument( + "--settle", + type=parse_duration, + default=DEFAULT_SETTLE_S, + metavar="DURATION", + help="how long after spawn to wait before calling a session ready, so an " + "app that exits instantly is reported as exited rather than ready " + "(default: %(default)ss)", + ) + parser.add_argument( + "--socket-mode", + type=lambda v: int(v, 8), + default=0o660, + metavar="OCTAL", + help="mode for the control socket (default: 0660)", + ) + parser.add_argument( + "--log-level", + default=os.environ.get("HHSTREAM_LOG_LEVEL", "info"), + choices=["debug", "info", "warning", "error"], + ) + parser.add_argument( + "--check", + action="store_true", + help="validate the configuration and exit without listening", + ) + return parser + + +def resolve_compositor(args: argparse.Namespace) -> CompositorTarget | None: + """Validate ``--compositor-runtime-dir``, or warn that there is none. + + Raises :class:`CompositorError` so the caller can refuse to start: a daemon + that accepts work and then kills every application that arrives is worse + than one that refuses while the operator is still watching. + """ + + if not args.compositor_runtime_dir: + log.warning( + NO_COMPOSITOR_WARNING, + ENV_COMPOSITOR_RUNTIME_DIR, + os.environ.get("XDG_RUNTIME_DIR", ""), + os.environ.get("WAYLAND_DISPLAY", ""), + ) + return None + target = CompositorTarget.from_runtime_dir(args.compositor_runtime_dir) + log.info( + "compositor: %s (WAYLAND_DISPLAY=%s)", + target.session.runtime_dir, + target.session.wayland_display, + ) + return target + + +async def serve( + args: argparse.Namespace, policy: Policy, compositor: CompositorTarget | None +) -> int: + clock = Clock() + # Absolute, because these end up in a session record and in a launched + # app's environment: a relative HOME or XDG_RUNTIME_DIR would be resolved + # against whatever directory the app happens to be started in. + state_dir = Path(args.state_dir).resolve() + runtime_dir = Path(args.runtime_dir).resolve() + config = ManagerConfig( + state_dir=state_dir, + runtime_dir=runtime_dir, + policy=policy, + settle_s=args.settle, + compositor=compositor, + ) + manager = SessionManager( + config, + clock=clock, + registry=Registry(state_dir, clock), + launcher=Launcher(runtime_dir, state_dir, compositor=compositor), + audit=AuditLog(state_dir / "events.jsonl", clock), + ) + server = ControlServer( + manager, Path(args.socket).absolute(), socket_mode=args.socket_mode + ) + + summary = await manager.startup() + log.info( + "adopted %(adopted)s, tombstoned %(tombstoned)s, quarantined %(quarantined)s, " + "pruned %(pruned)s", + summary, + ) + log.info( + "allowlist: %s", + ", ".join(sorted(policy.apps)) or f"(empty — {policy.source or 'no config'})", + ) + await server.start() + + stop = asyncio.Event() + loop = asyncio.get_running_loop() + for sig in (signal.SIGINT, signal.SIGTERM): + with contextlib.suppress(NotImplementedError): + loop.add_signal_handler(sig, stop.set) + try: + await stop.wait() + finally: + log.info("shutting down; sessions are left running for the next daemon to adopt") + await server.stop() + await manager.shutdown() + return 0 + + +def main(argv: list[str] | None = None) -> int: + args = build_parser().parse_args(argv) + logging.basicConfig( + level=getattr(logging, args.log_level.upper()), + format="%(asctime)s %(levelname)-7s %(name)s: %(message)s", + stream=sys.stderr, + ) + try: + policy = load_policy(args.config) + except (PolicyError, OSError, ValueError) as exc: + print(f"hhstreamd: bad config {args.config}: {exc}", file=sys.stderr) + return 2 + try: + compositor = resolve_compositor(args) + except CompositorError as exc: + # Refuse, naming the directory: every application launched from here + # would die on startup, and "state exited" one command later is a much + # worse place to find that out. + print(f"hhstreamd: {exc}", file=sys.stderr) + return 2 + if args.check: + print(f"config {args.config}: {len(policy.apps)} app(s) allowlisted") + for name, rule in sorted(policy.apps.items()): + print(f" {name} -> {rule.exec}") + if compositor is None: + print("compositor: none configured; apps inherit the daemon's environment") + else: + print( + f"compositor: {compositor.session.runtime_dir} " + f"(WAYLAND_DISPLAY={compositor.session.wayland_display})" + ) + return 0 + try: + return asyncio.run(serve(args, policy, compositor)) + except OSError as exc: + print(f"hhstreamd: {exc}", file=sys.stderr) + return 1 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/src/hhstreamd/audit.py b/src/hhstreamd/audit.py new file mode 100644 index 0000000..73fae35 --- /dev/null +++ b/src/hhstreamd/audit.py @@ -0,0 +1,116 @@ +"""The append-only event log (DESIGN.md §2.3, §8 item 5). + +One JSON object per line in ``/events.jsonl``, size-rotated. Every +lifecycle event and every accepted command, with **both** timestamps: wall time +for a human reading it at 09:00 to find out why Blender died at 03:00, and +boottime so the entry can be lined up with the deadline arithmetic that +actually drove the daemon. + +A write failure is logged and dropped. Refusing a command because a log line +could not be written is the wrong trade (DESIGN.md §7 #15). +""" + +from __future__ import annotations + +import json +import logging +import os +from pathlib import Path +from typing import Any + +from .clock import Clock, iso +from .textio import tail_lines + +log = logging.getLogger("hhstreamd.audit") + +DEFAULT_MAX_BYTES = 16 * 1024 * 1024 +DEFAULT_KEEP = 3 + +#: Arguments are bounded in the audit record so one pathological request cannot +#: dominate the log. +MAX_FIELD_CHARS = 2048 + + +class AuditLog: + def __init__( + self, + path: Path | str, + clock: Clock | None = None, + *, + max_bytes: int = DEFAULT_MAX_BYTES, + keep: int = DEFAULT_KEEP, + ) -> None: + self.path = Path(path) + self.clock = clock or Clock() + self.max_bytes = max_bytes + self.keep = keep + + def emit(self, event: str, **fields: Any) -> None: + record = { + "ts": iso(self.clock.wall()), + "boottime": round(self.clock.boottime(), 3), + "event": event, + } + record.update({k: _bound(v) for k, v in fields.items() if v is not None}) + try: + self._rotate_if_needed() + self.path.parent.mkdir(parents=True, exist_ok=True) + line = json.dumps(record, ensure_ascii=True, sort_keys=True) + "\n" + with open(self.path, "a", encoding="utf-8") as fh: + fh.write(line) + except OSError as exc: + log.error("audit write failed (%s): dropping event %s", exc, event) + + def _rotate_if_needed(self) -> None: + try: + size = self.path.stat().st_size + except FileNotFoundError: + return + if size < self.max_bytes: + return + for index in range(self.keep - 1, 0, -1): + src = self.path.with_suffix(self.path.suffix + f".{index}") + dst = self.path.with_suffix(self.path.suffix + f".{index + 1}") + if src.exists(): + os.replace(src, dst) + os.replace(self.path, self.path.with_suffix(self.path.suffix + ".1")) + + #: How far back `tail` will look. Filtering by session means the window + #: may hold far fewer than `limit` matching events; a wider window costs + #: one read of a file that is already on the page cache. + TAIL_BYTES = 1 << 20 + + def tail(self, limit: int = 20, *, session: str | None = None) -> list[dict[str, Any]]: + """The most recent events, newest last. Used by ``status``. + + Bounded in bytes, not just in lines: the audit log rotates at 16 MiB and + reading all of it to show twenty entries would be absurd. + """ + + if limit <= 0: + return [] + lines, _, _ = tail_lines(self.path, limit=10_000, max_bytes=self.TAIL_BYTES) + out: list[dict[str, Any]] = [] + for line in reversed(lines): + line = line.strip() + if not line: + continue + try: + record = json.loads(line) + except json.JSONDecodeError: + continue + if session is not None and record.get("session") != session: + continue + out.append(record) + if len(out) >= limit: + break + out.reverse() + return out + + +def _bound(value: Any) -> Any: + if isinstance(value, str) and len(value) > MAX_FIELD_CHARS: + return value[:MAX_FIELD_CHARS] + "…" + if isinstance(value, list): + return [_bound(v) for v in value[:64]] + return value diff --git a/src/hhstreamd/clock.py b/src/hhstreamd/clock.py new file mode 100644 index 0000000..aa32b9f --- /dev/null +++ b/src/hhstreamd/clock.py @@ -0,0 +1,101 @@ +"""Clocks (DESIGN.md §6.1). + +Every deadline in the daemon is computed on ``CLOCK_BOOTTIME``: + +* wall time is wrong — an NTP step or a DST change would silently extend or + collapse an idle window; +* ``CLOCK_MONOTONIC`` is wrong — it stops across system suspend, so a host + suspended for four hours would wake believing a session had been idle for + seconds; +* ``CLOCK_BOOTTIME`` includes suspend, which is what an operator means by + "no commands for more than three hours". + +A wall-clock ISO timestamp is recorded alongside, for humans and logs only. +Nothing computes with it. + +The clock is an object so it can be injected: :class:`ManualClock` is what the +reaper's unit tests advance by three hours without sleeping. +""" + +from __future__ import annotations + +import datetime as _dt +import time + + +class Clock: + """The real clock: ``CLOCK_BOOTTIME`` for arithmetic, wall time for display.""" + + def boottime(self) -> float: + return time.clock_gettime(time.CLOCK_BOOTTIME) + + def wall(self) -> float: + return time.time() + + def wall_iso(self) -> str: + return iso(self.wall()) + + +class ManualClock(Clock): + """A clock under the test's control. Never used by the shipped daemon.""" + + def __init__(self, boottime: float = 1000.0, wall: float | None = None) -> None: + self._boottime = float(boottime) + self._wall = float(wall) if wall is not None else 1_700_000_000.0 + + def boottime(self) -> float: + return self._boottime + + def wall(self) -> float: + return self._wall + + def advance(self, seconds: float) -> None: + """Move both clocks forward. Suspend is indistinguishable from this.""" + + self._boottime += float(seconds) + self._wall += float(seconds) + + +def iso(epoch: float) -> str: + """Format a wall-clock epoch as a UTC ISO-8601 timestamp, second precision.""" + + return ( + _dt.datetime.fromtimestamp(epoch, _dt.UTC) + .replace(microsecond=0) + .isoformat() + .replace("+00:00", "Z") + ) + + +def parse_duration(text: str) -> float: + """Parse ``30s`` / ``5m`` / ``3h`` / ``2d`` / a bare number of seconds. + + Raises :class:`ValueError` with a message fit for an argparse error. + """ + + s = text.strip().lower() + if not s: + raise ValueError("empty duration") + units = {"s": 1.0, "m": 60.0, "h": 3600.0, "d": 86400.0} + multiplier = 1.0 + if s[-1] in units: + multiplier = units[s[-1]] + s = s[:-1] + try: + value = float(s) + except ValueError: + raise ValueError(f"not a duration: {text!r} (expected e.g. 30s, 5m, 3h)") from None + if value < 0: + raise ValueError(f"negative duration: {text!r}") + return value * multiplier + + +def format_duration(seconds: float | None) -> str: + """Render a duration as ``H:MM:SS`` for the human table. ``None`` is an em dash.""" + + if seconds is None: + return "—" + seconds = int(max(0.0, seconds)) + hours, rest = divmod(seconds, 3600) + minutes, secs = divmod(rest, 60) + return f"{hours}:{minutes:02d}:{secs:02d}" diff --git a/src/hhstreamd/compositor.py b/src/hhstreamd/compositor.py new file mode 100644 index 0000000..42477e8 --- /dev/null +++ b/src/hhstreamd/compositor.py @@ -0,0 +1,240 @@ +"""Finding the compositor's Wayland socket, and the environment that reaches it. + +This module exists because of BUG-01: the daemon spawned children with its own +inherited environment, and on the target machine that environment names the +*login* session (``XDG_RUNTIME_DIR=/run/user/1000``, no ``WAYLAND_DISPLAY``), +where no compositor is listening. Every GUI application therefore died inside a +second with ``Failed to connect to Wayland display``, and the only symptom one +command later was ``state exited``. + +Three facts shape what is here. + +**The compositor's runtime directory is not the daemon's.** ``--runtime-dir`` +is where the daemon's control socket and the per-session scratch directories +live; ``--compositor-runtime-dir`` is where the compositor's ``wayland-N`` +lives, owned by a *different* user (DESIGN.md §3.1, user A). Conflating them is +the bug, so they are separate options and this module only ever reads the +latter. + +**The socket's name is not knowable in advance.** It is ``wayland-1`` on the +target machine, not ``wayland-0``, because a crashed compositor had already +taken the first name; libwayland itself picks the first free one. So the socket +is *discovered*, never assumed, and a stale leftover must not win over the live +one — hence the connect probe in :func:`discover`. + +**A daemon that cannot reach a compositor should refuse to start.** Accepting +work and then killing every application that arrives is worse than refusing at +the point where the operator is still looking at the terminal. So discovery +raises :class:`CompositorError` and the caller exits; it never degrades quietly. +""" + +from __future__ import annotations + +import errno +import logging +import os +import socket +import stat +from dataclasses import dataclass +from pathlib import Path + +log = logging.getLogger("hhstreamd.compositor") + +#: Wayland sockets are ``wayland-``; libwayland also writes a ``wayland-.lock`` +#: beside each one, which is an ordinary file and never a candidate. +SOCKET_PREFIX = "wayland-" + +#: How long to wait for ``connect()`` on a candidate socket. The compositor is +#: local and accepting, or it is not; this only bounds a pathological case. +PROBE_TIMEOUT_S = 0.5 + + +class CompositorError(Exception): + """The configured compositor runtime directory holds no usable socket.""" + + +@dataclass(frozen=True, slots=True) +class CompositorSession: + """Where the compositor is, and the environment that attaches to it.""" + + runtime_dir: Path + wayland_display: str + + @property + def socket_path(self) -> Path: + return self.runtime_dir / self.wayland_display + + def env(self) -> dict[str, str]: + """The variables a child needs, laid *on top of* its inherited ones. + + ``XDG_RUNTIME_DIR`` is the compositor's, not the daemon's and not the + session's private scratch directory: a toolkit resolves + ``WAYLAND_DISPLAY`` relative to it, and the daemon's own value names a + login session with nothing listening in it. ``WAYLAND_DISPLAY`` is the + bare socket name rather than an absolute path, which is what every + toolkit expects to see. ``XDG_SESSION_TYPE`` is what GTK, Qt and + Chromium read to choose their Wayland backend over X11. + """ + + return { + "XDG_RUNTIME_DIR": str(self.runtime_dir), + "WAYLAND_DISPLAY": self.wayland_display, + "XDG_SESSION_TYPE": "wayland", + } + + +@dataclass(slots=True) +class _Candidate: + name: str + connectable: bool + refused: bool # nobody is listening: a leftover from a crashed compositor + detail: str + + @property + def rank(self) -> tuple[int, int, str]: + # Live sockets first; among equals, the highest ``wayland-N`` wins, + # because a compositor takes the first free name and so the survivor of + # a crash-and-restart is the *later* one. + return (0 if self.connectable else 1, -_suffix_order(self.name), self.name) + + +def _suffix_order(name: str) -> int: + suffix = name[len(SOCKET_PREFIX) :] + return int(suffix) if suffix.isdigit() else -1 + + +def _probe(path: Path) -> _Candidate: + """Try to connect, to tell a live socket from a crashed compositor's leftover.""" + + sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) + try: + sock.settimeout(PROBE_TIMEOUT_S) + sock.connect(str(path)) + except OSError as exc: + # ECONNREFUSED is definitive: the inode is there and no process is + # behind it. Anything else (EACCES, EPERM, a timeout) is a reason to + # warn, not to discard the candidate — it may still be the live socket, + # and refusing to start over an ambiguous probe is its own outage. + refused = exc.errno in (errno.ECONNREFUSED, errno.ENOENT) + return _Candidate(path.name, False, refused, f"{type(exc).__name__}: {exc}") + finally: + sock.close() + return _Candidate(path.name, True, False, "connectable") + + +def candidates(runtime_dir: Path) -> list[str]: + """Names in ``runtime_dir`` that are Wayland sockets, unordered. + + Only ``S_ISSOCK`` entries count, so the ``.lock`` file beside each socket + and any directory named like one are never picked. + """ + + found = [] + with os.scandir(runtime_dir) as entries: + for entry in sorted(entries, key=lambda e: e.name): + if not entry.name.startswith(SOCKET_PREFIX): + continue + try: + mode = entry.stat(follow_symlinks=True).st_mode + except OSError: # vanished, or a dangling symlink + continue + if stat.S_ISSOCK(mode): + found.append(entry.name) + return found + + +def discover(runtime_dir: Path | str) -> CompositorSession: + """Resolve the compositor's session from its runtime directory. + + Raises :class:`CompositorError`, naming the directory, if it cannot be read, + holds no Wayland socket, or holds only sockets that nothing is listening on. + """ + + path = Path(runtime_dir).expanduser() + try: + resolved = path.resolve(strict=True) + except OSError as exc: + raise CompositorError(f"compositor runtime dir {path}: {exc.strerror or exc}") from exc + if not resolved.is_dir(): + raise CompositorError(f"compositor runtime dir {resolved} is not a directory") + try: + names = candidates(resolved) + except OSError as exc: + raise CompositorError( + f"compositor runtime dir {resolved}: cannot be listed ({exc.strerror or exc})" + ) from exc + if not names: + raise CompositorError( + f"compositor runtime dir {resolved} holds no Wayland socket " + f"({SOCKET_PREFIX}N); is the compositor running, and is this the " + "right directory? It is the compositor's XDG_RUNTIME_DIR, not the " + "daemon's --runtime-dir." + ) + + probed = sorted((_probe(resolved / name) for name in names), key=lambda c: c.rank) + best = probed[0] + if not best.connectable and all(c.refused for c in probed): + detail = ", ".join(f"{c.name} ({c.detail})" for c in probed) + raise CompositorError( + f"compositor runtime dir {resolved} holds no usable Wayland socket: " + f"{detail}. These look like leftovers from a compositor that is no " + "longer running." + ) + if not best.connectable: + log.warning( + "compositor socket %s did not accept a probe connection (%s); using it anyway", + best.name, + best.detail, + ) + if len(probed) > 1: + log.info( + "compositor runtime dir %s holds %d Wayland sockets (%s); chose %s", + resolved, + len(probed), + ", ".join(f"{c.name} [{c.detail}]" for c in probed), + best.name, + ) + return CompositorSession(runtime_dir=resolved, wayland_display=best.name) + + +class CompositorTarget: + """The configured compositor, re-resolved at every spawn. + + Re-resolving matters because the compositor can restart under a running + daemon and come back on a different socket name (that is exactly how the + target machine ended up on ``wayland-1``). If re-resolution fails, the last + known-good session is reused and the failure is logged: a transient listing + error must not turn into every subsequent application being launched with no + compositor at all. + """ + + def __init__(self, session: CompositorSession) -> None: + self.session = session + + @classmethod + def from_runtime_dir(cls, runtime_dir: Path | str) -> "CompositorTarget": + """Validate at startup. Raises :class:`CompositorError` if unusable.""" + + return cls(discover(runtime_dir)) + + def resolve(self) -> CompositorSession: + try: + session = discover(self.session.runtime_dir) + except CompositorError as exc: + log.warning( + "re-resolving the compositor socket failed (%s); keeping %s", + exc, + self.session.wayland_display, + ) + return self.session + if session != self.session: + log.info( + "compositor socket changed: %s -> %s", + self.session.wayland_display, + session.wayland_display, + ) + self.session = session + return session + + def env(self) -> dict[str, str]: + return self.resolve().env() diff --git a/src/hhstreamd/launcher.py b/src/hhstreamd/launcher.py new file mode 100644 index 0000000..220ef89 --- /dev/null +++ b/src/hhstreamd/launcher.py @@ -0,0 +1,237 @@ +"""Spawning session applications (DESIGN.md §3.1, §3.3; brief boundaries). + +Every app is spawned with ``start_new_session=True``, which gives it a fresh +session id *and* process group with ``sid == pgid == pid``. That pair is the +kill handle: there is no cgroup here, so the process group is what a teardown +signals and the session id is what the sweep searches for. + +**Never a shell.** ``argv`` is a list, built by :mod:`hhstreamd.policy` from an +absolute path in the config plus caller arguments that matched an allowlist +pattern. There is no ``shell=True`` and no string interpolation into a command +line anywhere in this package. + +**Why :class:`subprocess.Popen` and not ``asyncio.create_subprocess_exec``.** +asyncio's subprocess transport kills the child when it is closed — which +happens when the daemon's event loop shuts down, and again via the transport's +``__del__``. Using it here would mean every session application was SIGKILLed +the moment the daemon stopped, so no session would ever survive a daemon +restart and ``adopt`` would have nothing to adopt. That is the opposite of +what DESIGN.md §2.4 requires, and no unit file setting can fix it because the +kill comes from inside this process. A plain ``Popen`` has no such behaviour: +it never signals the child, and the daemon watches for exit through a pidfd +instead (see :mod:`hhstreamd.manager`). The fork/exec briefly blocks the event +loop, which is a few milliseconds and the right trade. + +**The compositor environment (BUG-01).** A child does *not* get a usable +Wayland connection from the daemon's inherited environment: on the target machine +the daemon runs in the login session (``XDG_RUNTIME_DIR=/run/user/1000``, no +``WAYLAND_DISPLAY``) and the compositor listens somewhere else entirely. So when +``--compositor-runtime-dir`` names the compositor's runtime directory, the +discovered session (:mod:`hhstreamd.compositor`) is laid over the inherited +environment at spawn. Without that option the old inherited-environment +behaviour stands, and the daemon warns at startup that applications may not +reach a compositor. + +The app runs as **the same unprivileged user as the daemon** and inherits the +real home directory. M0 invents no service account and forces no throwaway +``HOME``; ``--home`` pins a different one and ``--ephemeral-home`` opts in to a +per-session one that is deleted on teardown. +""" + +from __future__ import annotations + +import logging +import os +import shutil +import subprocess +from dataclasses import dataclass +from pathlib import Path + +from .compositor import CompositorTarget +from .registry import Session + +log = logging.getLogger("hhstreamd.launcher") + +#: Environment variables the daemon's own plumbing must not leak into an app. +_STRIPPED = ( + "HHSTREAM_SOCKET", + "HHSTREAM_STATE_DIR", + "HHSTREAM_RUNTIME_DIR", + "HHSTREAM_CONFIG", + "HHSTREAM_COMPOSITOR_RUNTIME_DIR", +) + + +@dataclass(slots=True) +class Spawned: + process: subprocess.Popen + pid: int + pgid: int + sid: int + home: str + #: The **daemon-owned** per-session runtime directory, which is what goes in + #: the record and what ``discard_runtime_dir`` may delete. It is not + #: necessarily the child's ``XDG_RUNTIME_DIR``: with a compositor + #: configured, that is the compositor's directory, owned by another user. + runtime_dir: str + log_path: str + + +class Launcher: + def __init__( + self, + runtime_dir: Path | str, + state_dir: Path | str, + *, + compositor: CompositorTarget | None = None, + ) -> None: + self.runtime_dir = Path(runtime_dir) + self.state_dir = Path(state_dir) + #: The compositor to attach children to, or ``None`` to leave the + #: inherited environment alone (``--compositor-runtime-dir`` unset). + self.compositor = compositor + + # ---- per-session directories ------------------------------------- + + def session_runtime_dir(self, session_id: str) -> Path: + return self.runtime_dir / "sessions" / session_id + + def session_home(self, session_id: str) -> Path: + return self.state_dir / "homes" / session_id + + def log_path(self, session_id: str) -> Path: + return self.state_dir / "logs" / f"{session_id}.log" + + # ---- environment ------------------------------------------------- + + def build_env(self, session_id: str, home: Path) -> dict[str, str]: + """The app's environment. + + It inherits the daemon's, minus the daemon's own configuration, plus a + private ``XDG_RUNTIME_DIR`` for the app's own locks and sockets. + + When a compositor is configured, its session is laid **on top** of that: + ``XDG_RUNTIME_DIR`` becomes the compositor's (a toolkit resolves + ``WAYLAND_DISPLAY`` against it), ``WAYLAND_DISPLAY`` the discovered + socket name, ``XDG_SESSION_TYPE`` ``wayland``. This is BUG-01: without + it a child inherits the daemon's login-session environment, finds no + compositor there, and dies within a second — and the only symptom is + ``state exited`` one command later. The private directory is still + created and still recorded, because the daemon owns and cleans it up; + it is simply not what the app sees as ``XDG_RUNTIME_DIR`` any more. + + With no compositor configured, ``WAYLAND_DISPLAY`` is passed through + untouched when the daemon has one: the daemon still never speaks the + Wayland protocol itself, but it must not *prevent* an app from doing so. + """ + + env = {k: v for k, v in os.environ.items() if k not in _STRIPPED} + runtime = self.session_runtime_dir(session_id) + runtime.mkdir(parents=True, exist_ok=True, mode=0o700) + env["HOME"] = str(home) + env["XDG_RUNTIME_DIR"] = str(runtime) + env["HHSTREAM_SESSION_ID"] = session_id + if self.compositor is not None: + env.update(self.compositor.env()) + return env + + def resolve_home(self, session_id: str, home: str | None, ephemeral: bool) -> tuple[Path, bool]: + """Decide the app's ``HOME``. Returns ``(path, is_ephemeral)``.""" + + if home is not None and ephemeral: + raise ValueError("--home and --ephemeral-home are mutually exclusive") + if ephemeral: + path = self.session_home(session_id) + path.mkdir(parents=True, exist_ok=True, mode=0o700) + return path, True + if home is not None: + return Path(home), False + inherited = os.environ.get("HOME") or str(Path.home()) + return Path(inherited), False + + def discard_home(self, session: Session) -> None: + """Delete an ephemeral home on teardown. Best effort, never fatal.""" + + if not session.ephemeral_home or not session.home: + return + expected = self.session_home(session.id) + if Path(session.home) != expected: # never remove a directory we did not create + log.warning("refusing to delete %s: not the session's ephemeral home", session.home) + return + shutil.rmtree(session.home, ignore_errors=True) + + def discard_runtime_dir(self, session: Session) -> None: + """Remove the session's private ``XDG_RUNTIME_DIR`` once it is pruned. + + Kept until the tombstone is pruned rather than removed at teardown, so + a post-mortem can still look at what the app left behind. + """ + + if not session.runtime_dir: + return + expected = self.session_runtime_dir(session.id) + if Path(session.runtime_dir) != expected: + log.warning("refusing to delete %s: not the session's runtime dir", session.runtime_dir) + return + shutil.rmtree(session.runtime_dir, ignore_errors=True) + + # ---- spawn ------------------------------------------------------- + + def spawn( + self, + session_id: str, + argv: list[str], + *, + home: str | None = None, + ephemeral_home: bool = False, + ) -> Spawned: + """Start the application. Raises ``OSError`` if it cannot be executed.""" + + if not argv: + raise ValueError("argv is empty") + if not os.path.isabs(argv[0]): + # Policy already guarantees this; asserting it here means a future + # caller cannot bypass the allowlist by handing in a bare name that + # would be resolved against PATH. + raise ValueError(f"argv[0] must be an absolute path, got {argv[0]!r}") + + home_path, is_ephemeral = self.resolve_home(session_id, home, ephemeral_home) + env = self.build_env(session_id, home_path) + log_file = self.log_path(session_id) + log_file.parent.mkdir(parents=True, exist_ok=True, mode=0o750) + + # stdout and stderr are captured to a file the daemon owns, because + # `session logs` is served from here rather than from the journal. + fh = open(log_file, "ab", buffering=0) + try: + process = subprocess.Popen( + argv, + stdin=subprocess.DEVNULL, + stdout=fh, + stderr=subprocess.STDOUT, + cwd=str(home_path) if home_path.is_dir() else "/", + env=env, + start_new_session=True, # sid == pgid == pid; the kill handle + close_fds=True, + ) + finally: + fh.close() + + pid = process.pid + # A process spawned with start_new_session has sid == pgid == pid by + # construction. Read them back anyway: if the app has already exited, + # /proc is gone and the recorded values must still be the right ones to + # signal, which they are. + pgid = sid = pid + return Spawned( + process=process, + pid=pid, + pgid=pgid, + sid=sid, + home=str(home_path), + # The daemon-owned per-session directory, which is what + # `discard_runtime_dir` is allowed to delete — *not* the compositor's + # XDG_RUNTIME_DIR, which belongs to another user entirely. + runtime_dir=str(self.session_runtime_dir(session_id)), + log_path=str(log_file), + ) diff --git a/src/hhstreamd/manager.py b/src/hhstreamd/manager.py new file mode 100644 index 0000000..1822e49 --- /dev/null +++ b/src/hhstreamd/manager.py @@ -0,0 +1,1000 @@ +"""The session manager: every verb's implementation, and the one kill path. + +This module owns the state machine. :mod:`hhstreamd.server` is only framing +and dispatch; everything that decides anything lives here. + +Two things are worth finding quickly: + +* :meth:`SessionManager.teardown` is **the** teardown — ``killpg(SIGTERM)``, + grace, ``killpg(SIGKILL)``, then the ``/proc`` session-id sweep (DESIGN.md + §3.3). ``kill`` and the reaper both call it with a different ``reason``, so + there is one kill path and not two. +* :meth:`SessionManager.touch` is the **only** mark of activity in M0. There is + no input verb and no session-scoped frame verb, so an agent observing a + long-running app has no other way to say "still working". ``list``, + ``status``, ``logs`` and ``gc`` deliberately do not stamp it: if monitoring + refreshed the clock, a supervisor polling every 60 s would keep every + abandoned session alive forever and the reaper would never fire. +""" + +from __future__ import annotations + +import asyncio +import contextlib +import logging +import os +import signal +import subprocess +import time +from dataclasses import dataclass +from pathlib import Path +from typing import Any + +from . import procmon +from .audit import AuditLog +from .clock import Clock, iso +from .compositor import CompositorTarget +from .launcher import Launcher +from .policy import Policy, PolicyError, check_app_name +from .reaper import Reaper +from .registry import ( + TERMINAL_ERROR, + Registry, + Session, + State, +) +from .textio import tail_lines + +log = logging.getLogger("hhstreamd.manager") + +#: How long after spawn the daemon waits before calling a session ready. +#: It exists for one real failure mode: an app that hands off to an existing +#: instance and exits immediately (DESIGN.md §7 #3). Without the settle, +#: `start` would return a healthy-looking id for a process that is already +#: gone. It is deliberately short. +DEFAULT_SETTLE_S = 0.1 + +#: How long a teardown waits for SIGKILL to take effect before it calls a pid a +#: survivor. SIGKILL is not synchronous: the task is woken and torn down by the +#: kernel, which takes microseconds normally but can block on uninterruptible +#: I/O. Short enough not to stall a verb, long enough that a healthy process is +#: never libelled as unkillable. +SURVIVOR_GRACE_S = 0.5 + +#: A single `logs` reply never carries more than this, so one request cannot +#: exceed the protocol's frame limit however much the app has written. +MAX_LOG_CHUNK_BYTES = 256 * 1024 + +SIGNALS_BY_NAME = { + "TERM": signal.SIGTERM, + "SIGTERM": signal.SIGTERM, + "KILL": signal.SIGKILL, + "SIGKILL": signal.SIGKILL, + "INT": signal.SIGINT, + "SIGINT": signal.SIGINT, + "HUP": signal.SIGHUP, + "SIGHUP": signal.SIGHUP, + "QUIT": signal.SIGQUIT, + "SIGQUIT": signal.SIGQUIT, +} + + +class ManagerError(Exception): + """A verb that failed for a reason the protocol has a name for.""" + + def __init__(self, error: str, reason: str, hint: str | None = None, **fields: Any) -> None: + super().__init__(reason) + self.error = error + self.reason = reason + self.hint = hint + self.fields = fields + + +@dataclass(slots=True) +class ManagerConfig: + state_dir: Path + runtime_dir: Path + policy: Policy + settle_s: float = DEFAULT_SETTLE_S + #: The compositor launched applications attach to, or ``None`` for the + #: inherited environment (``--compositor-runtime-dir`` unset). + compositor: CompositorTarget | None = None + + +class SessionManager: + def __init__( + self, + config: ManagerConfig, + *, + clock: Clock | None = None, + registry: Registry | None = None, + launcher: Launcher | None = None, + audit: AuditLog | None = None, + ) -> None: + self.config = config + self.clock = clock or Clock() + self.registry = registry or Registry(config.state_dir, self.clock) + self.launcher = launcher or Launcher( + config.runtime_dir, config.state_dir, compositor=config.compositor + ) + self.audit = audit or AuditLog(Path(config.state_dir) / "events.jsonl", self.clock) + self.reaper = Reaper( + now=self.clock.boottime, + sessions=self.registry.live, + on_expire=self._reap, + ) + # Per-session asyncio plumbing, never persisted. + self._exited: dict[str, asyncio.Event] = {} + self._watchers: dict[str, asyncio.Task] = {} + self._busy: set[str] = set() + + # ------------------------------------------------------------------ + # startup / shutdown + # ------------------------------------------------------------------ + + async def startup(self) -> dict[str, Any]: + """Load the mirror and adopt what is still alive (DESIGN.md §2.4).""" + + self.registry.ensure_dirs() + records, quarantined = self.registry.load_records() + summary = { + "adopted": 0, + "tombstoned": 0, + "quarantined": len(quarantined), + "pruned": 0, + # Records whose pid could be neither confirmed nor ruled out. + # Never silent: each one is logged at ERROR as it happens. + "unresolved": 0, + } + for record in records: + if not record.live: + self.registry.insert_loaded(record) + continue + self.registry.insert_loaded(record) + if self.registry.stale_boot(record): + # The record predates this boot. Its processes cannot exist: + # pids restart from zero, so /proc would lie if we asked it. + self.registry.terminate( + record, State.EXITED, exit_detected_by="stale_boot", last_error="stale_boot" + ) + summary["tombstoned"] += 1 + self.audit.emit("adopt_stale_boot", session=record.id, app=record.app) + continue + verdict = self._identity_of(record) + if not verdict.ok: + # A wrapper-launched app used to land here, because its argv had + # changed since launch; it is now adopted like any other + # (BUG-02 item 4). What reaches this branch is a process that + # really is gone, or a pid the daemon cannot claim — and in the + # latter case `_identity_of` has already said so at ERROR, and + # `gc` will report any process left sharing the session id. + self.registry.terminate( + record, + State.EXITED, + exit_detected_by="proc_check", + last_error=verdict.reason, + ) + summary["tombstoned"] += 1 + if verdict.unresolved: + summary["unresolved"] += 1 + self.audit.emit( + "adopt_failed", + session=record.id, + app=record.app, + why=verdict.reason, + checked=list(verdict.checked), + mismatched=list(verdict.mismatched), + ) + continue + record.adopted = True + record.exit_detected_by = None + self.registry.persist(record, force=True) + self._watch(record) + summary["adopted"] += 1 + self.audit.emit("adopted", session=record.id, app=record.app, pid=record.pid) + summary["pruned"] = self._prune_tombstones() + self.audit.emit("daemon_started", pid=os.getpid(), **summary) + # Expired deadlines are reaped on the reaper's first pass, which runs + # before its first sleep. + self.reaper.start() + return summary + + async def shutdown(self) -> None: + """Stop watching, flush the mirror. **Sessions are left running.** + + The daemon is supervised by someone else and may be restarted at any + time; killing every app on the way out would make a restart destructive. + ``startup`` adopts them back. + """ + + await self.reaper.stop() + for task in list(self._watchers.values()): + task.cancel() + for task in list(self._watchers.values()): + with contextlib.suppress(asyncio.CancelledError, Exception): + await task + self._watchers.clear() + self.registry.flush_all() + self.audit.emit("daemon_stopping", pid=os.getpid(), live=len(self.registry.live())) + + # ------------------------------------------------------------------ + # helpers + # ------------------------------------------------------------------ + + def now(self) -> float: + return self.clock.boottime() + + def _require(self, session_id: Any) -> Session: + if not isinstance(session_id, str) or not session_id: + raise ManagerError("invalid_argument", "a session id is required") + session = self.registry.get(session_id) + if session is None: + raise ManagerError("no_such_session", f"no session {session_id!r}") + return session + + def _require_live(self, session_id: Any) -> Session: + session = self._require(session_id) + if not session.live: + if session.last_error in procmon.UNRESOLVED: + # BUG-02 item 5. This session was not observed to exit — the + # daemon gave up on it because it could not prove the pid was + # still ours, and signalled nothing. Answering a later `kill` + # with the same "is exited" as a routine exit would hide exactly + # the fact the caller needs: an application may still be running. + raise ManagerError( + session.last_error, + f"session {session.id} was given up on: pid {session.pid} could not " + f"be identified as this session ({session.last_error}), so nothing " + f"was ever signalled", + hint="if the application is still running, `hhstream session gc` " + "lists it under orphaned processes; kill it by hand", + id=session.id, + state=session.state, + ) + raise ManagerError( + TERMINAL_ERROR.get(session.state, "bad_state"), + f"session {session.id} is {session.state}", + id=session.id, + state=session.state, + ) + return session + + def _event(self, session_id: str) -> asyncio.Event: + return self._exited.setdefault(session_id, asyncio.Event()) + + def _identity_of(self, session: Session) -> procmon.Verdict: + """The one identity gate. **Every** caller goes through here (BUG-02). + + ``kill``, the reaper, ``gc`` and restart adoption all have to answer the + same question — "is the pid in this record still the process we + recorded?" — and before BUG-02 they each asked it with their own call to + a check that was wrong in the same way. Routing them through one method + means the evidence, the logging and the drift reporting cannot drift + apart between callers. + """ + + verdict = procmon.check( + session.pid, + starttime=session.pid_starttime, + sid=session.sid, + pgid=session.pgid, + cmdline_sha256=session.cmdline_sha256, + ) + if verdict.ok and verdict.cmdline_drifted: + # Entirely normal: a wrapper script `exec`ed the real binary, or the + # app rewrote its own argv. Worth one line in the log and nothing + # more — it is not evidence of anything (BUG-02). + log.debug( + "%s (pid %s): argv changed since launch; identity confirmed by %s", + session.id, + session.pid, + "+".join(verdict.checked), + ) + elif verdict.unresolved: + log.error( + "%s: refusing to treat pid %s as this session — %s (checked %s, mismatched %s)", + session.id, + session.pid, + verdict.reason, + "+".join(verdict.checked) or "nothing", + "+".join(verdict.mismatched) or "nothing", + ) + return verdict + + # ------------------------------------------------------------------ + # exit watching + # ------------------------------------------------------------------ + + def _watch(self, session: Session, process: subprocess.Popen | None = None) -> None: + """Watch one session for exit. One path for own children and adopted ones. + + ``os.pidfd_open`` (Linux >= 5.3) notifies on exit for a process that is + **not** our child, which is the adopted case, and works just as well for + one that is. The pidfd becomes readable when the process terminates, so + there is no polling and no latency. + + **The documented fallback** for a kernel without ``pidfd_open``, or a + pidfd this event loop cannot poll, is a one-second ``/proc`` liveness + poll (``procmon.POLL_INTERVAL_S``). It costs one ``stat`` per session + per second and detects an exit up to a second late; nothing else + changes, because both paths converge on :meth:`_on_exit`. + + **The exit status** comes from ``waitpid`` and is therefore available + only for the daemon's own children. For an adopted process the record + says ``exit_code: null`` with ``exit_detected_by`` naming the mechanism, + rather than inventing a zero. + """ + + def reap() -> int | None: + if process is None: + return None + # The pidfd fired, so the child is a zombie and waitpid will not + # block. poll() is subprocess's waitpid(WNOHANG). + for _ in range(50): + code = process.poll() + if code is not None: + return code + time.sleep(0.002) + return None # pragma: no cover - the kernel would have to lie + + async def watch_pidfd(fd: int) -> None: + loop = asyncio.get_running_loop() + done = asyncio.Event() + try: + loop.add_reader(fd, done.set) + except (OSError, NotImplementedError): # pragma: no cover + os.close(fd) + log.warning("pidfd is not pollable here; falling back to /proc polling") + await watch_poll() + return + try: + await done.wait() + finally: + with contextlib.suppress(OSError, ValueError): + loop.remove_reader(fd) + os.close(fd) + self._on_exit(session.id, exit_code=reap(), detected_by="pidfd") + + async def watch_poll() -> None: + while True: + await asyncio.sleep(procmon.POLL_INTERVAL_S) + if not procmon.is_alive(session.pid): + self._on_exit(session.id, exit_code=reap(), detected_by="proc_poll") + return + + fd = procmon.pidfd_open(session.pid) + if fd is None and not procmon.is_alive(session.pid): + # Already gone between spawn/adopt and here. + self._on_exit(session.id, exit_code=reap(), detected_by="proc_check") + return + coro = watch_pidfd(fd) if fd is not None else watch_poll() + self._watchers[session.id] = asyncio.create_task(coro, name=f"hhstreamd.watch:{session.id}") + + def _on_exit(self, session_id: str, *, exit_code: int | None, detected_by: str) -> None: + self._event(session_id).set() + session = self.registry.get(session_id) + if session is None or not session.live: + return + self.registry.terminate( + session, State.EXITED, exit_code=exit_code, exit_detected_by=detected_by + ) + self.audit.emit( + "session_exited", + session=session.id, + app=session.app, + pid=session.pid, + exit_code=exit_code, + detected_by=detected_by, + ) + self.reaper.wake() + + # ------------------------------------------------------------------ + # verbs + # ------------------------------------------------------------------ + + async def start( + self, + app: str, + argv: list[str] | None = None, + *, + idle_timeout_s: float | None = None, + wait_ready_s: float | None = None, + home: str | None = None, + ephemeral_home: bool = False, + ) -> dict[str, Any]: + policy = self.config.policy + policy.check_capacity(len(self.registry.live())) + rule, full_argv = policy.resolve(app, argv) + if idle_timeout_s is None and rule.idle_timeout_s is not None: + idle_timeout_s = rule.idle_timeout_s + timeout = policy.check_idle_timeout(idle_timeout_s) + wait_ready = policy.wait_ready_s if wait_ready_s is None else float(wait_ready_s) + + session_id = self.registry.new_id(app) + try: + spawned = self.launcher.spawn( + session_id, full_argv, home=home, ephemeral_home=ephemeral_home + ) + except (OSError, ValueError) as exc: + self.audit.emit("start_failed", app=app, argv=full_argv, reason=str(exc)) + raise ManagerError( + "refused", f"could not execute {full_argv[0]!r}: {exc}" + ) from exc + + identity = procmon.identity(spawned.pid) + now = self.now() + session = Session( + id=session_id, + app=app, + argv=full_argv, + pid=spawned.pid, + pgid=identity.pgid if identity else spawned.pgid, + sid=identity.sid if identity else spawned.sid, + pid_starttime=identity.starttime if identity else 0, + cmdline_sha256=identity.cmdline_sha256 if identity else "", + home=spawned.home, + runtime_dir=spawned.runtime_dir, + log_path=spawned.log_path, + created_at=iso(self.clock.wall()), + created_boottime=now, + last_activity_at=iso(self.clock.wall()), + last_activity_boottime=now, # `start` stamps activity implicitly + idle_timeout_s=timeout, + state=State.STARTING, + ephemeral_home=ephemeral_home, + command_count=1, + ) + self.registry.add(session) + self._exited.pop(session_id, None) + self._watch(session, spawned.process) + self.audit.emit( + "session_started", + session=session.id, + app=app, + pid=session.pid, + pgid=session.pgid, + sid=session.sid, + argv=full_argv, + idle_timeout_s=timeout, + ) + + ready = await self._settle(session, wait_ready) + self.reaper.wake() + record = session.public(self.now()) + if session.state == State.EXITED: + # The app exited during the settle: surface it rather than handing + # back a healthy-looking id (DESIGN.md §7 #3). + raise ManagerError( + "session_exited", + f"{app} exited immediately (exit code {session.exit_code})", + hint="the app may have handed off to an existing instance; " + "try --ephemeral-home to force a fresh one", + id=session.id, + session=record, + ) + if not ready: + # DESIGN.md §7 #4: the session is left alive and the id is printed; + # killing an app that took 20 s to start is worse than a slow + # success. Unreachable in M0, where readiness is "still running". + raise ManagerError( + "readiness_timeout", + f"{app} did not signal readiness within {wait_ready:g}s", + id=session.id, + session=record, + ) + return record + + async def _settle(self, session: Session, wait_ready: float) -> bool: + """Wait briefly for the process to prove it is still there. + + M0 has no compositor, so the design's ``wayland-fd`` readiness probe + degrades to **absent**: the only honest signal available here is that + the process is alive and is still the process we spawned. That is + recorded as ``ready_signal: "spawned"`` so nothing downstream mistakes + it for evidence that a window was mapped. + """ + + settle = min(self.config.settle_s, wait_ready) if wait_ready > 0 else 0.0 + if settle > 0: + with contextlib.suppress(TimeoutError): + await asyncio.wait_for(self._event(session.id).wait(), timeout=settle) + if not session.live: + return False + session.state = State.READY + session.ready_signal = "spawned" + self.registry.persist(session, force=True) + return True + + def list(self, *, include_tombstones: bool = False) -> dict[str, Any]: + """Read-only. **Does not** count as activity.""" + + now = self.now() + sessions = self.registry.all() if include_tombstones else self.registry.live() + return { + "sessions": [s.public(now) for s in sessions], + "live": len(self.registry.live()), + "tombstones": len(self.registry.tombstones()), + "boottime": now, + } + + def status(self, session_id: str, *, events: int = 20) -> dict[str, Any]: + """Read-only. **Does not** count as activity.""" + + session = self._require(session_id) + record = session.public(self.now()) + record["events"] = self.audit.tail(events, session=session.id) + record["compositor"] = { + # Enrichment the design calls optional, absent by construction in + # M0: the daemon never speaks the Wayland protocol and never talks + # to Hyprland's IPC. Locating the compositor's socket so a child + # can attach to it (see hhstreamd.compositor) tells us nothing + # about windows, so none of this becomes knowable. + "ipc": "absent", + "window": None, + "workspace": None, + "foreground": None, + "note": "M0 does not talk to the compositor; these are never guessed", + } + return record + + def touch(self, session_id: str) -> dict[str, Any]: + """**The only mark of activity in M0.** Resets the idle clock, injects nothing.""" + + session = self._require_live(session_id) + self.registry.touch(session, force_flush=True) + self.audit.emit( + "touch", + session=session.id, + app=session.app, + expires_in_s=round(session.expires_in(self.now()) or 0.0, 3), + ) + self.reaper.wake() + return session.public(self.now()) + + async def kill( + self, + session_id: str, + *, + grace_s: float | None = None, + sig: str | int = signal.SIGTERM, + ) -> dict[str, Any]: + session = self._require_live(session_id) + signum = _signal_number(sig) + grace = self.config.policy.grace_s if grace_s is None else float(grace_s) + if grace < 0: + raise ManagerError("invalid_argument", "grace may not be negative") + result = await self.teardown(session, reason="killed", grace_s=grace, sig=signum) + record = {**session.public(self.now()), **result} + if result["refused"]: + # BUG-02 item 5: the caller asked for a kill that did not happen, so + # they get an error and exit 4, not a success line that reads like + # the process was already gone. + raise ManagerError( + result["refused"], + f"refused to signal session {session.id}: pid {session.pid} can no longer " + f"be identified as this session " + f"({', '.join(result['identity_mismatched']) or 'no usable evidence'} " + f"of {', '.join(result['identity_checked']) or 'nothing'})", + hint="nothing was signalled; if an application is still running, " + "find it with `hhstream session gc` and kill it by hand", + id=session.id, + session=record, + ) + return record + + async def _survivors(self, session: Session) -> list[int]: + """Pids of the session still alive after the teardown has finished. + + The leader plus anything still carrying the session id. This is the + honest answer to "did the kill work", and it is what stops ``kill`` from + reporting success over a process that is still on the screen (BUG-02). + """ + + # Real time, not the injected clock: this waits on the kernel, not on + # session bookkeeping, and a test that freezes the clock must not turn + # it into an infinite loop. + deadline = time.monotonic() + SURVIVOR_GRACE_S + while True: + alive = set(procmon.session_members(session.sid, exclude={os.getpid()})) + if procmon.is_alive(session.pid): + alive.add(session.pid) + if not alive or time.monotonic() >= deadline: + return sorted(alive) + await asyncio.sleep(0.02) + + async def _reap(self, session_id: str) -> None: + session = self.registry.get(session_id) + if session is None or not session.live: + return + result = await self.teardown(session, reason="reaped", grace_s=self.config.policy.grace_s) + if result["refused"] or result["survivors"]: + # There is no caller to raise at here, so the loudness has to be in + # the log and the audit trail. The session is tombstoned either + # way, which is what keeps the reaper from spinning on it. + log.error( + "reaping %s did not complete: refused=%s survivors=%s", + session_id, + result["refused"], + result["survivors"], + ) + + async def teardown( + self, + session: Session, + *, + reason: str, + grace_s: float, + sig: int = signal.SIGTERM, + ) -> dict[str, Any]: + """The one kill path (DESIGN.md §3.3, §6.3). + + ``killpg(TERM)`` → grace → ``killpg(KILL)`` → sweep ``/proc`` for the + session id. The sweep is the substitute for a cgroup kill: a child that + called ``setsid()`` once has left the process group but kept the session + id, so it is caught here. A child that called ``setsid()`` twice escapes + even this; ``gc`` reports it. + + **It reports what it actually did** (BUG-02 item 1): the signal that was + sent and to which process group, whether it escalated, how many + stragglers the sweep took, and — the one that matters — whether anything + is *still alive* afterwards. Before BUG-02 the only thing a caller got + when the gate refused was ``signalled: false``, which the CLI rendered as + "the process was already gone"; an application that cannot be killed + while the tool reports success is the failure mode this exists to + prevent. A refusal is now carried back in ``refused`` and turned into an + error by :meth:`kill`. + """ + + if session.id in self._busy: + raise ManagerError("busy", f"session {session.id} is already being torn down") + self._busy.add(session.id) + state = State.REAPED if reason == "reaped" else State.KILLED + idle_s = session.idle_for(self.now()) + self.audit.emit( + f"{reason}_started", + session=session.id, + app=session.app, + pid=session.pid, + pgid=session.pgid, + signal=signal.Signals(sig).name, + grace_s=grace_s, + idle_s=None if idle_s is None else round(idle_s, 3), + ) + try: + exited = self._event(session.id) + # Only signal a process group we can still prove is ours. + verdict = self._identity_of(session) + escalated = False + sent: str | None = None + refused: str | None = None + if verdict.ok: + # The wrapper case lands here now: `argv` changed when the + # wrapper `exec`ed the real binary, and that is not evidence of + # anything, so the application is signalled like any other. + procmon.killpg(session.pgid, sig) + sent = signal.Signals(sig).name + if grace_s > 0: + with contextlib.suppress(TimeoutError): + await asyncio.wait_for(exited.wait(), timeout=grace_s) + if procmon.is_alive(session.pid) or procmon.session_members( + session.sid, exclude={os.getpid()} + ): + escalated = True + procmon.killpg(session.pgid, signal.SIGKILL) + # `sent` stays the signal the caller asked for; the + # escalation is reported on its own, so the two are not + # confused for one another. + # Give the kernel a moment to deliver SIGKILL before the + # sweep decides what is left. + with contextlib.suppress(TimeoutError): + await asyncio.wait_for(exited.wait(), timeout=1.0) + elif verdict.unresolved: + # Nothing is signalled, and the caller is *told* so: the pid + # cannot be claimed as this session's, so a kill aimed at it + # would be aimed at a stranger. `kill` raises on this. + refused = verdict.reason + session.last_error = verdict.reason + + if refused is not None: + # The recorded session id may now belong to something else + # entirely, so the sweep would be aiming at strangers. Skip it. + stragglers: list[int] = [] + else: + stragglers = procmon.sweep_session(session.sid, exclude={os.getpid()}) + + # What is left standing. The sweep has just sent SIGKILL, so give + # the kernel a bounded moment to act on it before calling anything a + # survivor: a pid that is still here after this is a real failure to + # kill, and the caller has to hear about it rather than read + # "killed" and assume. On a refusal nothing was signalled and the + # pids involved may not be ours at all, so there is nothing to call + # a survivor: `refused` is the thing the caller has to hear. + survivors = [] if refused else await self._survivors(session) + + if refused is None: + state_now = state + else: + # Not killed — the daemon never signalled anything. Recording + # KILLED here would be the same lie in the registry that the CLI + # was telling on stdout. + state_now = State.EXITED + self.registry.terminate( + session, + state_now, + exit_detected_by=session.exit_detected_by + or ("identity_refused" if refused else "killpg"), + last_error=session.last_error, + ) + self.launcher.discard_home(session) + self.audit.emit( + f"{reason}_completed", + session=session.id, + app=session.app, + escalated_to_sigkill=escalated, + stragglers=len(stragglers), + straggler_pids=stragglers, + signalled=verdict.ok, + signal_sent=sent, + pgid=session.pgid, + refused=refused, + survivors=survivors, + identity=verdict.reason or "verified", + cmdline_drifted=verdict.cmdline_drifted, + idle_s=None if idle_s is None else round(idle_s, 3), + ) + if survivors: + log.error( + "%s: %d process(es) survived the teardown: %s", + session.id, + len(survivors), + survivors, + ) + self.reaper.wake() + return { + "reason": reason, + "signalled": verdict.ok, + #: The signal actually delivered, or ``None`` if none was. + "signal_sent": sent, + "pgid": session.pgid, + "escalated_to_sigkill": escalated, + "stragglers": len(stragglers), + "straggler_pids": stragglers, + #: Still alive after everything. Non-empty means the teardown + #: did not do what it was asked to do. + "survivors": survivors, + #: ``"verified"``, or the reason the gate refused. + "identity": verdict.reason or "verified", + "identity_checked": list(verdict.checked), + "identity_mismatched": list(verdict.mismatched), + #: The recorded argv no longer matches the live one. Normal for + #: an app behind a wrapper script; never a reason to refuse. + "cmdline_drifted": verdict.cmdline_drifted, + #: Set when the daemon refused to signal at all (BUG-02 item 5). + "refused": refused, + } + finally: + self._busy.discard(session.id) + + async def adopt( + self, + pid: int, + *, + app: str | None = None, + idle_timeout_s: float | None = None, + ) -> dict[str, Any]: + """Bring an already-running process under management. + + The same machinery the daemon uses to re-adopt its own sessions after a + restart, exposed as a verb — and the bridge from an unmanaged launch + into management. + """ + + try: + pid = int(pid) + except (TypeError, ValueError): + raise ManagerError("invalid_argument", f"not a pid: {pid!r}") from None + if pid <= 1: + raise ManagerError("refused", f"refusing to adopt pid {pid}") + if pid == os.getpid(): + raise ManagerError("refused", "refusing to adopt the daemon itself") + for existing in self.registry.live(): + if existing.pid == pid: + raise ManagerError( + "already_managed", + f"pid {pid} is already session {existing.id}", + id=existing.id, + ) + identity = procmon.identity(pid) + if identity is None: + raise ManagerError("no_such_process", f"no process with pid {pid}") + argv = procmon.cmdline_argv(pid) or [] + if app is None: + app = Path(argv[0]).name if argv else f"pid{pid}" + try: + check_app_name(app) + except PolicyError as exc: + raise ManagerError(exc.error, exc.reason, exc.hint) from exc + self.config.policy.check_capacity(len(self.registry.live())) + timeout = self.config.policy.check_idle_timeout(idle_timeout_s) + + now = self.now() + session_id = self.registry.new_id(app) + session = Session( + id=session_id, + app=app, + argv=argv, + pid=pid, + pgid=identity.pgid, + sid=identity.sid, + pid_starttime=identity.starttime, + cmdline_sha256=identity.cmdline_sha256, + home=os.environ.get("HOME", "/"), + runtime_dir=str(self.launcher.session_runtime_dir(session_id)), + log_path=None, # the daemon did not spawn it, so it captured no output + created_at=iso(self.clock.wall()), + created_boottime=now, + last_activity_at=iso(self.clock.wall()), + last_activity_boottime=now, + idle_timeout_s=timeout, + state=State.READY, + ready_signal="adopted", + adopted=True, + command_count=1, + ) + self.registry.add(session) + self._exited.pop(session_id, None) + self._watch(session) + self.audit.emit( + "session_adopted", session=session.id, app=app, pid=pid, idle_timeout_s=timeout + ) + self.reaper.wake() + return session.public(self.now()) + + def gc(self) -> dict[str, Any]: + """Prune tombstones and reconcile the table with ``/proc``. + + Read-only with respect to the idle clock: **``gc`` does not count as + activity.** + """ + + now = self.now() + reconciled: list[dict[str, Any]] = [] + #: Reconciled sessions whose pid could not be resolved either way. + #: Reported separately so a caller can tell "it exited" (routine) + #: from "the daemon has lost track of a running application". + unresolved: list[dict[str, Any]] = [] + for session in self.registry.live(): + verdict = self._identity_of(session) + if verdict.ok: + # Including the wrapper case: a session whose argv changed after + # launch is healthy, and `gc` used to tombstone it while its + # application kept running (BUG-02 item 4). + continue + why = verdict.reason + self.registry.terminate( + session, + State.EXITED, + exit_detected_by="gc_proc_scan", + last_error=None if why == procmon.GONE else why, + ) + entry = {"id": session.id, "why": why} + if verdict.unresolved: + entry["mismatched"] = list(verdict.mismatched) + unresolved.append(entry) + reconciled.append(entry) + self.audit.emit( + "gc_reconciled", + session=session.id, + why=why, + mismatched=list(verdict.mismatched), + ) + + orphans: list[dict[str, Any]] = [] + for session in self.registry.tombstones(): + survivors = procmon.session_members(session.sid, exclude={os.getpid()}) + if survivors: + # Processes still sharing a dead session's session id: the + # double-`setsid()` leak the design admits to (§7 #7). + orphans.append({"id": session.id, "sid": session.sid, "pids": survivors}) + pruned = self._prune_tombstones() + self.reaper.wake() + self.audit.emit( + "gc", + pruned=pruned, + reconciled=len(reconciled), + unresolved=len(unresolved), + orphans=len(orphans), + ) + return { + "pruned": pruned, + "reconciled": reconciled, + "unresolved": unresolved, + "orphans": orphans, + "live": len(self.registry.live()), + "tombstones": len(self.registry.tombstones()), + "boottime": now, + } + + def _prune_tombstones(self) -> int: + now = self.now() + pruned = 0 + for session in self.registry.tombstones(): + expires = session.tombstone_expires() + if expires is None or expires > now: + continue + self.launcher.discard_home(session) + self.launcher.discard_runtime_dir(session) + self.registry.drop(session.id) + self._exited.pop(session.id, None) + self._watchers.pop(session.id, None) + pruned += 1 + return pruned + + def logs(self, session_id: str, *, lines: int = 100, offset: int | None = None) -> dict[str, Any]: + """The daemon's capture of the app's stdout/stderr. + + Served from ``/logs/.log`` rather than the journal, because + apps are ordinary child processes here. Read-only: **does not** count + as activity. ``offset`` supports ``--follow`` without the daemon + holding a streaming connection open. + """ + + session = self._require(session_id) + if not session.log_path: + return { + "id": session.id, + "path": None, + "lines": [], + "offset": 0, + "eof": True, + "note": "adopted sessions have no captured output", + } + path = Path(session.log_path) + try: + size = path.stat().st_size + except OSError: + return {"id": session.id, "path": str(path), "lines": [], "offset": 0, "eof": True} + if offset is None: + tail, truncated, size = tail_lines(path, max(0, int(lines))) + return { + "id": session.id, + "path": str(path), + "lines": tail, + "offset": size, + "truncated": truncated, + # `eof` means "no more output will ever arrive", which is true + # exactly when the session has ended. A follower polls until it. + "eof": not session.live, + } + offset = max(0, min(int(offset), size)) + try: + with open(path, "rb") as fh: + fh.seek(offset) + chunk = fh.read(MAX_LOG_CHUNK_BYTES) + new_offset = fh.tell() + except OSError as exc: + raise ManagerError("refused", f"could not read logs: {exc}") from exc + return { + "id": session.id, + "path": str(path), + "lines": chunk.decode("utf-8", "replace").splitlines(), + "offset": new_offset, + "truncated": new_offset < size, + "eof": not session.live and new_offset >= size, + } + + +def _signal_number(sig: str | int) -> int: + if isinstance(sig, int): + try: + return signal.Signals(sig).value + except ValueError: + raise ManagerError("invalid_argument", f"unknown signal: {sig!r}") from None + name = str(sig).upper() + if name in SIGNALS_BY_NAME: + return SIGNALS_BY_NAME[name] + raise ManagerError( + "invalid_argument", + f"unknown signal: {sig!r}", + hint=f"one of {', '.join(sorted(set(SIGNALS_BY_NAME)))}", + ) diff --git a/src/hhstreamd/policy.py b/src/hhstreamd/policy.py new file mode 100644 index 0000000..738fe22 --- /dev/null +++ b/src/hhstreamd/policy.py @@ -0,0 +1,237 @@ +"""The app allowlist and the input bounds on ``start`` (DESIGN.md §8 item 1). + +This is the main control, and the only part of §8 that is in M0: + +* ``start`` resolves an app *name* against the config file to an **absolute + path**. An arbitrary binary is refused with exit 6. Without this, + ``hhstream session start /bin/sh`` makes every other control decorative. +* ``argv`` is a **list**. There is never a shell: no ``shell=True``, no string + interpolation into a command line, anywhere in this package. +* Caller-supplied arguments are matched against ``args_allow`` patterns. An + app with no ``args_allow`` accepts no caller arguments at all. + +Deliberately **not** in M0 (brief: "nothing else from §8"): the ``SO_PEERCRED`` +uid/gid authorisation, per-session ``HOME`` by default, ``nice``, +``oom_score_adj``, rlimits, the RSS watchdog and the keybinding denylist. +``max_sessions`` is kept, because exit code 6 in the frozen table names it. +""" + +from __future__ import annotations + +import fnmatch +import logging +import os +import tomllib +from dataclasses import dataclass, field +from pathlib import Path +from typing import Any + +log = logging.getLogger("hhstreamd.policy") + +DEFAULT_IDLE_TIMEOUT_S = 3 * 3600.0 +DEFAULT_MAX_IDLE_TIMEOUT_S = 24 * 3600.0 +DEFAULT_MAX_SESSIONS = 4 +DEFAULT_GRACE_S = 10.0 +DEFAULT_WAIT_READY_S = 15.0 + +# Input bounds that apply to `start`. They exist so a malformed or hostile +# request is refused cheaply, before anything is spawned. +MAX_APP_NAME = 64 +MAX_ARGV_ITEMS = 64 +MAX_ARG_BYTES = 4096 +MAX_ARGV_BYTES = 64 * 1024 +APP_NAME_CHARS = set("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789._-+") + + +class PolicyError(Exception): + """A request refused by policy. ``error`` maps to an exit code.""" + + def __init__(self, error: str, reason: str, hint: str | None = None) -> None: + super().__init__(reason) + self.error = error + self.reason = reason + self.hint = hint + + +@dataclass(frozen=True, slots=True) +class AppRule: + name: str + exec: str + args: list[str] = field(default_factory=list) + args_allow: list[str] = field(default_factory=list) + idle_timeout_s: float | None = None + + def check_args(self, argv: list[str]) -> None: + for arg in argv: + if not any(fnmatch.fnmatchcase(arg, pattern) for pattern in self.args_allow): + raise PolicyError( + "argument_refused", + f"argument {arg!r} is not permitted for app {self.name!r}", + hint="args_allow in the hhstream config controls this", + ) + + +@dataclass(frozen=True, slots=True) +class Policy: + apps: dict[str, AppRule] = field(default_factory=dict) + max_sessions: int = DEFAULT_MAX_SESSIONS + idle_timeout_s: float = DEFAULT_IDLE_TIMEOUT_S + max_idle_timeout_s: float = DEFAULT_MAX_IDLE_TIMEOUT_S + grace_s: float = DEFAULT_GRACE_S + wait_ready_s: float = DEFAULT_WAIT_READY_S + source: str | None = None + + # ---- resolution -------------------------------------------------- + + def resolve(self, app: str, argv: list[str] | None) -> tuple[AppRule, list[str]]: + """Resolve an app name and caller argv to the full argv to execute. + + Returns ``(rule, argv)`` where ``argv[0]`` is the rule's absolute exec + path. Raises :class:`PolicyError` for anything not allowlisted. + """ + + check_app_name(app) + argv = list(argv or []) + check_argv(argv) + rule = self.apps.get(app) + if rule is None: + known = ", ".join(sorted(self.apps)) or "(the allowlist is empty)" + raise PolicyError( + "not_allowlisted", + f"app {app!r} is not in the allowlist", + hint=f"allowlisted apps: {known}; see {self.source or 'the hhstream config'}", + ) + rule.check_args(argv) + return rule, [rule.exec, *rule.args, *argv] + + def check_idle_timeout(self, seconds: float | None) -> float: + if seconds is None: + return self.idle_timeout_s + try: + value = float(seconds) + except (TypeError, ValueError): + raise PolicyError("invalid_argument", f"idle timeout is not a number: {seconds!r}") from None + if value < 0: + raise PolicyError("invalid_argument", "idle timeout may not be negative") + if value > self.max_idle_timeout_s: + raise PolicyError( + "refused", + f"idle timeout {value:g}s exceeds the configured maximum " + f"{self.max_idle_timeout_s:g}s", + ) + return value + + def check_capacity(self, live_count: int) -> None: + if self.max_sessions and live_count >= self.max_sessions: + raise PolicyError( + "session_cap_reached", + f"{live_count} live sessions, max_sessions is {self.max_sessions}", + hint="kill or gc a session, or raise max_sessions in the config", + ) + + +def check_app_name(app: Any) -> None: + if not isinstance(app, str) or not app: + raise PolicyError("invalid_argument", "app name must be a non-empty string") + if len(app) > MAX_APP_NAME: + raise PolicyError("invalid_argument", f"app name longer than {MAX_APP_NAME} characters") + bad = set(app) - APP_NAME_CHARS + if bad: + raise PolicyError( + "invalid_argument", + f"app name contains disallowed characters: {''.join(sorted(bad))!r}", + ) + + +def check_argv(argv: Any) -> None: + """Bounds on the caller-supplied argv. A list of strings, and not a large one.""" + + if not isinstance(argv, list): + raise PolicyError("invalid_argument", "argv must be a list of strings") + if len(argv) > MAX_ARGV_ITEMS: + raise PolicyError("invalid_argument", f"argv has more than {MAX_ARGV_ITEMS} items") + total = 0 + for arg in argv: + if not isinstance(arg, str): + raise PolicyError("invalid_argument", f"argv item is not a string: {arg!r}") + if "\0" in arg: + raise PolicyError("invalid_argument", "argv item contains a NUL byte") + encoded = len(arg.encode("utf-8")) + if encoded > MAX_ARG_BYTES: + raise PolicyError("invalid_argument", f"argv item longer than {MAX_ARG_BYTES} bytes") + total += encoded + if total > MAX_ARGV_BYTES: + raise PolicyError("invalid_argument", f"argv longer than {MAX_ARGV_BYTES} bytes in total") + + +# -------------------------------------------------------------------------- +# Config loading +# -------------------------------------------------------------------------- + + +def load_policy(path: Path | str | None) -> Policy: + """Read the allowlist from a TOML file. + + A missing file is not an error: it yields an empty allowlist, so the daemon + starts and every ``start`` is refused with exit 6 and a hint naming the file + it looked for. Refusing to start would make a misconfigured deployment look + like a crash. + """ + + if path is None: + return Policy(source=None) + path = Path(path) + if not path.exists(): + log.warning("no config at %s: the app allowlist is empty, every start will be refused", path) + return Policy(source=str(path)) + with open(path, "rb") as fh: + data = tomllib.load(fh) + return policy_from_dict(data, source=str(path)) + + +def policy_from_dict(data: dict[str, Any], *, source: str | None = None) -> Policy: + defaults = data.get("defaults", {}) + if not isinstance(defaults, dict): + raise PolicyError("invalid_argument", "[defaults] must be a table") + apps: dict[str, AppRule] = {} + raw_apps = data.get("apps", {}) + if not isinstance(raw_apps, dict): + raise PolicyError("invalid_argument", "[apps] must be a table") + for name, spec in raw_apps.items(): + apps[name] = _app_rule(name, spec) + return Policy( + apps=apps, + max_sessions=int(defaults.get("max_sessions", DEFAULT_MAX_SESSIONS)), + idle_timeout_s=float(defaults.get("idle_timeout_s", DEFAULT_IDLE_TIMEOUT_S)), + max_idle_timeout_s=float(defaults.get("max_idle_timeout_s", DEFAULT_MAX_IDLE_TIMEOUT_S)), + grace_s=float(defaults.get("grace_s", DEFAULT_GRACE_S)), + wait_ready_s=float(defaults.get("wait_ready_s", DEFAULT_WAIT_READY_S)), + source=source, + ) + + +def _app_rule(name: str, spec: Any) -> AppRule: + if not isinstance(spec, dict): + raise PolicyError("invalid_argument", f"[apps.{name}] must be a table") + check_app_name(name) + exec_path = spec.get("exec") + if not isinstance(exec_path, str) or not exec_path: + raise PolicyError("invalid_argument", f"[apps.{name}] needs an 'exec' string") + if not os.path.isabs(exec_path): + raise PolicyError( + "invalid_argument", + f"[apps.{name}].exec must be an absolute path, got {exec_path!r}", + ) + args = spec.get("args", []) + args_allow = spec.get("args_allow", []) + for key, value in (("args", args), ("args_allow", args_allow)): + if not isinstance(value, list) or not all(isinstance(v, str) for v in value): + raise PolicyError("invalid_argument", f"[apps.{name}].{key} must be a list of strings") + idle = spec.get("idle_timeout_s") + return AppRule( + name=name, + exec=exec_path, + args=list(args), + args_allow=list(args_allow), + idle_timeout_s=None if idle is None else float(idle), + ) diff --git a/src/hhstreamd/procmon.py b/src/hhstreamd/procmon.py new file mode 100644 index 0000000..e14d15e --- /dev/null +++ b/src/hhstreamd/procmon.py @@ -0,0 +1,406 @@ +"""``/proc`` inspection: liveness, identity, and the session-id sweep. + +This is the substitute for the cgroup membership the design lost when the +daemon stopped being a systemd *user* service (DESIGN.md §2.4, §3.3): + +* **Liveness** is ``/proc/`` existing. +* **Identity** is the evidence that makes it safe to signal a pid the daemon + did not spawn — see :func:`check` and the note below. +* **The sweep** finds processes whose session id matches a recorded session, + which catches a child that called ``setsid()`` once and so escaped the + process group. A child that calls ``setsid()`` twice escapes even this; that + is the honest cost of having no cgroup, and ``gc`` reports it. + +**Why the command line is not identity evidence (BUG-02).** The original +triple-check hashed ``/proc//cmdline`` and refused to signal when the hash +moved. ``/proc//cmdline`` is not a property of the *process*; it is a +window onto the current image's argument vector, and it is replaced wholesale by +every ``execve()``. On the target platform ``/run/current-system/sw/bin/`` +is almost always a wrapper script that ``exec``s the real binary, which arrives +with an argv of its own; Chromium then rewrites argv in place for its zygote and +renderer processes on top of that. So a perfectly healthy session was being +classified as a recycled pid, and ``kill``, ``gc`` and restart adoption all +quietly did the wrong thing. The hash is still recorded and still reported — +as *drift*, which is useful in a post-mortem — but it never gates a signal. + +**What is left, and why it is sound.** + +* ``starttime`` (``stat`` field 22) is written once by the kernel when the task + is created and is never writable afterwards, by the process or by anyone + else. ``execve()`` replaces the address space, not the task, so it survives + an arbitrarily long chain of wrappers. Two processes holding the same pid are + necessarily created at different times, so a difference here is proof of + reuse. The one residual window is the clock-tick granularity of the field + (``USER_HZ``, 10 ms on this kernel): a pid could in principle be recycled + within the same tick, which would require the kernel to wrap the whole pid + space — ``/proc/sys/kernel/pid_max``, four million by default — in under 10 ms. + ``boot_id`` (see :mod:`hhstreamd.registry`) closes the across-reboot case + separately, so this is the entire remaining exposure and it is accepted + knowingly. **This field is mandatory**: without it there is no identity, and + the caller is refused rather than silently obliged. +* ``sid`` and ``pgid`` are inherited across ``execve()`` and survive a wrapper + just as well, but they are only *immutable* for a session/group leader: a + leader's ``setsid()`` and ``setpgid()`` both fail with ``EPERM``, whereas an + ordinary process may lawfully leave at any moment. Every session the daemon + spawns is a leader by construction (``start_new_session=True`` gives + ``sid == pgid == pid``), so the check is applied exactly when the recorded + value equals the recorded pid and skipped otherwise — an *adopted* mid-session + process that later calls ``setsid()`` must not be mistaken for a stranger. + They corroborate ``starttime``; they are never trusted alone, because a + recycled pid that calls ``setsid()`` acquires ``sid == pgid == pid`` too. +""" + +from __future__ import annotations + +import errno +import hashlib +import os +import signal +from dataclasses import dataclass + +PROC = "/proc" + + +@dataclass(frozen=True, slots=True) +class ProcStat: + """The fields of ``/proc//stat`` this daemon cares about.""" + + pid: int + comm: str + state: str + ppid: int + pgid: int + sid: int + starttime: int + + +def read_stat(pid: int, *, proc: str = PROC) -> ProcStat | None: + """Parse ``/proc//stat``. ``None`` if the process is gone. + + ``comm`` may contain spaces and parentheses, so the fields after it are + located from the *last* ``)`` rather than by splitting the whole line. + """ + + try: + with open(f"{proc}/{pid}/stat", "rb") as fh: + raw = fh.read() + except (FileNotFoundError, ProcessLookupError, NotADirectoryError): + return None + except OSError as exc: # ESRCH racing with exit, EACCES on a hardened /proc + if exc.errno in (errno.ESRCH, errno.EACCES, errno.EPERM): + return None + raise + open_paren = raw.find(b"(") + close = raw.rfind(b")") + if open_paren == -1 or close < open_paren: + return None + comm = raw[open_paren + 1 : close].decode("utf-8", "replace") + rest = raw[close + 2 :].split() + # `rest` begins at field 3 (state), so field N lives at index N - 3. + if len(rest) < 20: + return None + try: + return ProcStat( + pid=int(raw[:open_paren].strip()), + comm=comm, + state=rest[0].decode(), + ppid=int(rest[1]), + pgid=int(rest[2]), + sid=int(rest[3]), + starttime=int(rest[19]), + ) + except (ValueError, IndexError): + return None + + +def read_cmdline(pid: int, *, proc: str = PROC) -> bytes | None: + """Raw NUL-separated ``/proc//cmdline``. ``None`` if the process is gone.""" + + try: + with open(f"{proc}/{pid}/cmdline", "rb") as fh: + return fh.read() + except (FileNotFoundError, ProcessLookupError, NotADirectoryError): + return None + except OSError as exc: + if exc.errno in (errno.ESRCH, errno.EACCES, errno.EPERM): + return None + raise + + +def cmdline_argv(pid: int, *, proc: str = PROC) -> list[str] | None: + """``/proc//cmdline`` split into an argv list.""" + + raw = read_cmdline(pid, proc=proc) + if raw is None: + return None + parts = raw.split(b"\0") + if parts and parts[-1] == b"": + parts.pop() + return [p.decode("utf-8", "replace") for p in parts] + + +def hash_cmdline(raw: bytes) -> str: + """The ``cmdline_sha256`` of DESIGN.md §2.1.""" + + return hashlib.sha256(raw).hexdigest() + + +def cmdline_hash(pid: int, *, proc: str = PROC) -> str | None: + raw = read_cmdline(pid, proc=proc) + return None if raw is None else hash_cmdline(raw) + + +#: `/proc//stat` states for a process that has already terminated. A +#: zombie still has a `/proc` entry — it holds its pid until its real parent +#: reaps it — but it will never run again and cannot be signalled into doing +#: anything. Treating it as alive would make the daemon escalate to SIGKILL +#: against a corpse and report sessions as running after they ended, which is +#: the common case for an *adopted* process whose real parent is slow to wait(). +DEAD_STATES = frozenset("ZX") + + +def is_alive(pid: int, *, proc: str = PROC) -> bool: + """True if the process exists and has not already terminated.""" + + stat = read_stat(pid, proc=proc) + return stat is not None and stat.state not in DEAD_STATES + + +@dataclass(frozen=True, slots=True) +class Identity: + """The evidence recorded at spawn and re-checked after a daemon restart.""" + + pid: int + pgid: int + sid: int + starttime: int + cmdline_sha256: str + + +def identity(pid: int, *, proc: str = PROC) -> Identity | None: + """Capture the anti-pid-reuse evidence for a live process.""" + + stat = read_stat(pid, proc=proc) + if stat is None: + return None + raw = read_cmdline(pid, proc=proc) + if raw is None: + return None + return Identity( + pid=pid, + pgid=stat.pgid, + sid=stat.sid, + starttime=stat.starttime, + cmdline_sha256=hash_cmdline(raw), + ) + + +#: Reasons :func:`check` can refuse. ``gone`` is routine — the process simply +#: exited. The other two are not: ``pid_reuse_detected`` means a *different* +#: process now holds the pid, and ``identity_unknown`` means the record carries +#: no usable evidence either way. A caller may never signal on any of them, and +#: must never report the latter two as a quiet success (BUG-02). +GONE = "gone" +PID_REUSE = "pid_reuse_detected" +IDENTITY_UNKNOWN = "identity_unknown" + +#: Refusals the caller has to be *loud* about: both mean the daemon could not +#: establish that the pid is still the session's, so an operation the caller +#: asked for did not happen. +UNRESOLVED = frozenset({PID_REUSE, IDENTITY_UNKNOWN}) + + +@dataclass(frozen=True, slots=True) +class Verdict: + """The outcome of an identity check, with the evidence that produced it. + + ``checked`` and ``mismatched`` are what makes this falsifiable in a log or a + test: they name the fields that actually gated the decision, so weakening + the gate cannot be done silently. + """ + + ok: bool + reason: str | None + #: Fields that were in a position to refuse, in the order they were tried. + checked: tuple[str, ...] = () + #: The subset of ``checked`` that did not match. + mismatched: tuple[str, ...] = () + #: The recorded ``cmdline_sha256`` no longer matches the live one. This is + #: *reported*, never acted on: see the module docstring. + cmdline_drifted: bool = False + + @property + def unresolved(self) -> bool: + """True when the identity could be neither confirmed nor ruled out.""" + + return self.reason in UNRESOLVED + + +def check( + pid: int, + *, + starttime: int | None, + sid: int | None = None, + pgid: int | None = None, + cmdline_sha256: str | None = None, + proc: str = PROC, +) -> Verdict: + """Decide whether ``pid`` is still the process whose identity was recorded. + + The gate is ``starttime``, corroborated by ``sid`` and ``pgid`` when the + recorded process was its own session/group leader — which every session the + daemon spawns is. ``cmdline_sha256`` is accepted and compared, but a + difference only sets :attr:`Verdict.cmdline_drifted`; it never refuses, + because an ``exec``ing wrapper script changes it as a matter of routine + (BUG-02). The reasoning for each field is in the module docstring. + """ + + stat = read_stat(pid, proc=proc) + if stat is None or stat.state in DEAD_STATES: + return Verdict(False, GONE) + + drifted = False + if cmdline_sha256: + live_hash = cmdline_hash(pid, proc=proc) + drifted = live_hash is not None and live_hash != cmdline_sha256 + + if not starttime or starttime <= 0: + # No evidence at all. Refusing is the only safe answer, and the caller + # is required to say so rather than skip whatever it was asked to do. + return Verdict(False, IDENTITY_UNKNOWN, cmdline_drifted=drifted) + + checked = ["starttime"] + mismatched = [] if stat.starttime == starttime else ["starttime"] + # `sid`/`pgid` are immutable only for a leader; see the module docstring. + if sid is not None and sid == pid: + checked.append("sid") + if stat.sid != sid: + mismatched.append("sid") + if pgid is not None and pgid == pid: + checked.append("pgid") + if stat.pgid != pgid: + mismatched.append("pgid") + + if mismatched: + return Verdict( + False, PID_REUSE, tuple(checked), tuple(mismatched), cmdline_drifted=drifted + ) + return Verdict(True, None, tuple(checked), (), cmdline_drifted=drifted) + + +def verify( + pid: int, + *, + starttime: int | None, + sid: int | None = None, + pgid: int | None = None, + cmdline_sha256: str | None = None, + proc: str = PROC, +) -> tuple[bool, str | None]: + """:func:`check` reduced to ``(ok, reason)`` for callers that want no detail.""" + + verdict = check( + pid, + starttime=starttime, + sid=sid, + pgid=pgid, + cmdline_sha256=cmdline_sha256, + proc=proc, + ) + return verdict.ok, verdict.reason + + +def iter_pids(*, proc: str = PROC) -> list[int]: + try: + entries = os.listdir(proc) + except OSError: + return [] + return sorted(int(e) for e in entries if e.isdigit()) + + +def session_members(sid: int, *, proc: str = PROC, exclude: set[int] | None = None) -> list[int]: + """Every live pid whose ``/proc//stat`` session id equals ``sid``. + + Refuses ``sid <= 1``: sweeping session 0 or 1 would select init and most of + the machine. + """ + + if sid is None or sid <= 1: + return [] + exclude = exclude or set() + found = [] + for pid in iter_pids(proc=proc): + if pid in exclude: + continue + stat = read_stat(pid, proc=proc) + if stat is not None and stat.sid == sid and stat.state not in DEAD_STATES: + found.append(pid) + return found + + +def kill_pid(pid: int, sig: int = signal.SIGKILL) -> bool: + """Signal one pid, tolerating the race where it has already exited.""" + + try: + os.kill(pid, sig) + return True + except ProcessLookupError: + return False + except PermissionError: + return False + + +def killpg(pgid: int, sig: int) -> bool: + """Signal a whole process group, refusing the dangerous group ids. + + ``pgid <= 1`` would mean "every process we may signal" or init's group; + neither is ever a session's group, because every session is spawned with + ``start_new_session=True`` and so has ``pgid == pid``. + """ + + if pgid is None or pgid <= 1: + return False + try: + os.killpg(pgid, sig) + return True + except ProcessLookupError: + return False + except PermissionError: + return False + + +def sweep_session( + sid: int, *, proc: str = PROC, exclude: set[int] | None = None, sig: int = signal.SIGKILL +) -> list[int]: + """Kill every straggler sharing the session id. Returns the pids signalled.""" + + victims = session_members(sid, proc=proc, exclude=exclude) + killed = [pid for pid in victims if kill_pid(pid, sig)] + return killed + + +# -------------------------------------------------------------------------- +# Exit notification +# -------------------------------------------------------------------------- + +#: ``os.pidfd_open`` needs Linux >= 5.3 and gives exit notification for +#: processes that are *not* our children — which is exactly the adopted case. +#: Where it is unavailable the daemon falls back to a 1 s ``/proc`` liveness +#: poll, which costs one ``stat`` per adopted session per second and detects an +#: exit up to a second late. Own children never need either path: asyncio's +#: child watcher gives both notification and the exit status. +HAVE_PIDFD = hasattr(os, "pidfd_open") + +#: How often the fallback polls, in seconds. +POLL_INTERVAL_S = 1.0 + + +def pidfd_open(pid: int) -> int | None: + """Open a pidfd, or ``None`` if unsupported or the process is already gone.""" + + if not HAVE_PIDFD: + return None + try: + return os.pidfd_open(pid) + except (ProcessLookupError, PermissionError, OSError): + return None diff --git a/src/hhstreamd/protocol.py b/src/hhstreamd/protocol.py new file mode 100644 index 0000000..f6ba66a --- /dev/null +++ b/src/hhstreamd/protocol.py @@ -0,0 +1,186 @@ +"""Wire format and the exit-code table (DESIGN.md §1.6, §3.4). + +Newline-delimited JSON over a unix ``SOCK_STREAM`` socket: one request object, +one response object, connection closed. This module is shared by the daemon +and by the CLI handlers, so the framing and the exit-code mapping exist exactly +once. It imports nothing outside the standard library and nothing from the +rest of ``hhstreamd``. +""" + +from __future__ import annotations + +import enum +import json +from typing import Any + +PROTOCOL_VERSION = 1 + +#: A single request or response line may not exceed this many bytes, including +#: the terminating newline. A peer that sends more is answered with +#: ``message_too_large`` and disconnected rather than being allowed to grow the +#: daemon's read buffer without bound. +MAX_LINE_BYTES = 1 << 20 # 1 MiB + + +class ProtocolError(Exception): + """A frame could not be read or decoded. + + ``error`` is the machine-readable name reported to the peer. + """ + + def __init__(self, error: str, reason: str) -> None: + super().__init__(reason) + self.error = error + self.reason = reason + + +# -------------------------------------------------------------------------- +# Exit codes (DESIGN.md §1.6). Frozen: agents branch on these. +# -------------------------------------------------------------------------- + + +class ExitCode(enum.IntEnum): + OK = 0 + USAGE = 2 + NO_SUCH_SESSION = 3 + BAD_STATE = 4 + DAEMON_UNREACHABLE = 5 + POLICY = 6 + TIMEOUT = 7 + BUSY = 8 + + +#: Machine-readable error names, grouped by the exit code they map to. Every +#: ``{"ok": false, "error": ...}`` the daemon can emit appears here; anything +#: unknown falls back to :data:`ExitCode.BAD_STATE` (see :func:`exit_code_for`). +EXIT_CODE_FOR_ERROR: dict[str, ExitCode] = { + # 2 — usage + "bad_request": ExitCode.USAGE, + "unknown_op": ExitCode.USAGE, + "unsupported_version": ExitCode.USAGE, + "message_too_large": ExitCode.USAGE, + "invalid_argument": ExitCode.USAGE, + # 3 — no such session + "no_such_session": ExitCode.NO_SUCH_SESSION, + "no_such_process": ExitCode.NO_SUCH_SESSION, + # 4 — not in a usable state + "session_exited": ExitCode.BAD_STATE, + "session_killed": ExitCode.BAD_STATE, + "session_reaped": ExitCode.BAD_STATE, + "session_starting": ExitCode.BAD_STATE, + "compositor_lost": ExitCode.BAD_STATE, + "bad_state": ExitCode.BAD_STATE, + "pid_reuse_detected": ExitCode.BAD_STATE, + # The session's identity could not be established either way, so the + # daemon refused rather than signalling blind (BUG-02 item 5). + "identity_unknown": ExitCode.BAD_STATE, + # 5 — daemon unreachable (produced by the client, never by the daemon) + "daemon_unreachable": ExitCode.DAEMON_UNREACHABLE, + # 6 — refused by policy + "not_allowlisted": ExitCode.POLICY, + "argument_refused": ExitCode.POLICY, + "session_cap_reached": ExitCode.POLICY, + "refused": ExitCode.POLICY, + # 7 — timed out + "timeout": ExitCode.TIMEOUT, + "readiness_timeout": ExitCode.TIMEOUT, + # 8 — busy + "busy": ExitCode.BUSY, + "already_managed": ExitCode.BUSY, +} + + +def exit_code_for(error: str | None) -> ExitCode: + """Map a machine-readable error name to its frozen exit code. + + An unrecognised name maps to :data:`ExitCode.BAD_STATE`: a caller that does + not know what went wrong should still be told the session is not usable, + which is strictly safer than reporting success. + """ + + if not error: + return ExitCode.OK + return EXIT_CODE_FOR_ERROR.get(error, ExitCode.BAD_STATE) + + +# -------------------------------------------------------------------------- +# Message construction +# -------------------------------------------------------------------------- + + +def request(op: str, **fields: Any) -> dict[str, Any]: + """Build a request object with the protocol version attached.""" + + msg: dict[str, Any] = {"v": PROTOCOL_VERSION, "op": op} + msg.update({k: v for k, v in fields.items() if v is not None}) + return msg + + +def ok(**fields: Any) -> dict[str, Any]: + return {"ok": True, **fields} + + +def error(err: str, reason: str, *, hint: str | None = None, **fields: Any) -> dict[str, Any]: + """Build an error reply. + + ``error`` is the machine field agents branch on, ``reason`` the human one + (DESIGN.md §1.6). + """ + + msg: dict[str, Any] = {"ok": False, "error": err, "reason": reason} + if hint is not None: + msg["hint"] = hint + msg.update(fields) + return msg + + +# -------------------------------------------------------------------------- +# Framing +# -------------------------------------------------------------------------- + + +def encode(message: dict[str, Any]) -> bytes: + """Serialise one message to a single newline-terminated line. + + ``ensure_ascii`` keeps the line free of raw newlines inside strings by + construction, so the framing cannot be broken by a session id, an argv + element or an error message. + """ + + line = json.dumps(message, ensure_ascii=True, separators=(",", ":")).encode("ascii") + if len(line) + 1 > MAX_LINE_BYTES: + raise ProtocolError("message_too_large", f"message is {len(line)} bytes") + return line + b"\n" + + +def decode(line: bytes) -> dict[str, Any]: + """Parse one frame (with or without its trailing newline) into a dict.""" + + if len(line) > MAX_LINE_BYTES: + raise ProtocolError("message_too_large", f"frame is {len(line)} bytes") + text = line.rstrip(b"\n") + if not text.strip(): + raise ProtocolError("bad_request", "empty frame") + try: + obj = json.loads(text) + except (UnicodeDecodeError, json.JSONDecodeError) as exc: + raise ProtocolError("bad_request", f"malformed JSON: {exc}") from exc + if not isinstance(obj, dict): + raise ProtocolError("bad_request", f"expected a JSON object, got {type(obj).__name__}") + return obj + + +def decode_request(line: bytes) -> dict[str, Any]: + """Parse and validate a request frame: an object with a known ``v`` and ``op``.""" + + obj = decode(line) + version = obj.get("v", PROTOCOL_VERSION) + if version != PROTOCOL_VERSION: + raise ProtocolError( + "unsupported_version", + f"protocol version {version!r} is not supported (daemon speaks {PROTOCOL_VERSION})", + ) + op = obj.get("op") + if not isinstance(op, str) or not op: + raise ProtocolError("bad_request", "request has no 'op' field") + return obj diff --git a/src/hhstreamd/reaper.py b/src/hhstreamd/reaper.py new file mode 100644 index 0000000..31a2d79 --- /dev/null +++ b/src/hhstreamd/reaper.py @@ -0,0 +1,187 @@ +"""The idle reaper (DESIGN.md §6). + +Deadline-scheduled, not polled: the reaper computes +``min(last_activity_boottime + idle_timeout_s)`` across live sessions and +sleeps until that instant or until a state change wakes it. Zero wakeups while +idle; no one-second tick burning a core on an otherwise quiet server. + +**The clock is injected at construction** — ``now()`` returns a +``CLOCK_BOOTTIME`` reading in production and whatever a test says otherwise. +The selection arithmetic below is therefore pure and covered by unit tests that +never sleep and never spawn anything. +""" + +from __future__ import annotations + +import asyncio +import logging +from typing import Awaitable, Callable, Iterable, Protocol + +log = logging.getLogger("hhstreamd.reaper") + + +class Expirable(Protocol): + """What the reaper needs of a session. ``Session`` satisfies it.""" + + id: str + + @property + def live(self) -> bool: ... + + def deadline(self) -> float | None: ... + + +def deadlines(sessions: Iterable[Expirable]) -> dict[str, float]: + """Every live session's deadline, keyed by id. + + Sessions in a terminal state and sessions with the idle timeout disabled + (``idle_timeout_s == 0``) have no deadline and do not appear. + """ + + out: dict[str, float] = {} + for session in sessions: + deadline = session.deadline() + if deadline is not None: + out[session.id] = deadline + return out + + +def next_deadline(sessions: Iterable[Expirable]) -> float | None: + """The earliest deadline, or ``None`` when nothing can expire. + + ``None`` is the empty-set case and means "sleep until woken". + """ + + found = deadlines(sessions) + return min(found.values()) if found else None + + +def select_expired(sessions: Iterable[Expirable], now: float) -> list[str]: + """Ids whose deadline has arrived, oldest deadline first. + + The comparison is ``deadline <= now`` so a session adopted after a daemon + restart with an already-expired deadline is selected on the first pass + rather than waiting another full timeout (DESIGN.md §2.4 item 6). + """ + + expired = [(deadline, sid) for sid, deadline in deadlines(sessions).items() if deadline <= now] + expired.sort() + return [sid for _, sid in expired] + + +def sleep_for(sessions: Iterable[Expirable], now: float) -> float | None: + """How long to sleep before the next deadline. + + ``None`` means "indefinitely"; ``0.0`` means something is already expired. + """ + + deadline = next_deadline(sessions) + if deadline is None: + return None + return max(0.0, deadline - now) + + +class Reaper: + """The deadline-scheduled task. + + ``sessions`` is a callable returning the current live set — the registry is + authoritative, and the reaper never holds its own copy of it. + ``on_expire(session_id)`` performs the teardown; it is exactly ``kill`` with + a different reason, so there is one kill path, not two (DESIGN.md §6.3). + """ + + def __init__( + self, + now: Callable[[], float], + sessions: Callable[[], Iterable[Expirable]], + on_expire: Callable[[str], Awaitable[None]], + *, + max_sleep: float = 3600.0, + retry_delay: float = 1.0, + ) -> None: + self._now = now + self._sessions = sessions + self._on_expire = on_expire + self._max_sleep = max_sleep + self._retry_delay = retry_delay + self._wake = asyncio.Event() + self._task: asyncio.Task | None = None + self.reaped: list[str] = [] + + # ---- pure helpers, exposed for tests and for `status` ------------- + + def next_deadline(self) -> float | None: + return next_deadline(self._sessions()) + + def expired(self) -> list[str]: + return select_expired(self._sessions(), self._now()) + + def sleep_for(self) -> float | None: + return sleep_for(self._sessions(), self._now()) + + # ---- lifecycle --------------------------------------------------- + + def wake(self) -> None: + """Re-evaluate the schedule now. Called on every state change.""" + + self._wake.set() + + def start(self) -> asyncio.Task: + if self._task is None: + self._task = asyncio.create_task(self.run(), name="hhstreamd.reaper") + return self._task + + async def stop(self) -> None: + if self._task is not None: + self._task.cancel() + try: + await self._task + except asyncio.CancelledError: + pass + self._task = None + + async def tick(self) -> list[str]: + """Reap everything currently expired. Returns the ids reaped.""" + + reaped: list[str] = [] + for session_id in self.expired(): + try: + await self._on_expire(session_id) + except Exception: # pragma: no cover - teardown must not kill the task + log.exception("reaping %s failed", session_id) + else: + reaped.append(session_id) + self.reaped.extend(reaped) + return reaped + + async def run(self) -> None: + while True: + # Cleared *before* the tick, so a state change that lands while we + # are tearing a session down still forces a re-evaluation instead + # of being swallowed. + self._wake.clear() + reaped = await self.tick() + delay = self.sleep_for() + # Nothing can expire: sleep until something wakes us. Zero + # wakeups on a quiet server, which is the point of scheduling on a + # deadline rather than ticking. + # + # With a deadline, the wait is additionally capped at `max_sleep`. + # That is not belt-and-braces: deadlines are on CLOCK_BOOTTIME but + # asyncio's timers run on CLOCK_MONOTONIC, which *stops* across + # system suspend. A host suspended for four hours would otherwise + # wake and keep waiting. Re-evaluating at most an hour of + # monotonic time later bounds that error to an hour, per daemon, + # not per session. + timeout: float | None = None if delay is None else min(delay, self._max_sleep) + if timeout == 0: + if reaped: + continue + # Still expired but nothing was reaped: the teardown failed. + # Back off rather than spinning on it. + log.warning("session(s) past their deadline could not be reaped; retrying") + timeout = self._retry_delay + try: + await asyncio.wait_for(self._wake.wait(), timeout=timeout) + except TimeoutError: + pass diff --git a/src/hhstreamd/registry.py b/src/hhstreamd/registry.py new file mode 100644 index 0000000..92198a0 --- /dev/null +++ b/src/hhstreamd/registry.py @@ -0,0 +1,394 @@ +"""The session record and its persistence (DESIGN.md §2.1, §2.3, §2.4). + +Authoritative state is in daemon memory; the files under ``/sessions/`` +are a mirror, written ``tmp`` + :func:`os.replace` so a reader never sees a +half-written record. **A mirror write failure never fails a command** — it is +logged, and memory stays truthful. +""" + +from __future__ import annotations + +import base64 +import json +import logging +import os +import secrets +import time +from dataclasses import asdict, dataclass, replace +from pathlib import Path +from typing import Any, Iterator + +from .clock import Clock, iso + +log = logging.getLogger("hhstreamd.registry") + +SCHEMA = 2 + +#: Tombstones survive this long so a ``status`` after an unexplained failure +#: still answers the question. ``gc`` prunes them. +DEFAULT_TOMBSTONE_TTL_S = 3600.0 + +#: ``last_activity`` is hot, so the mirror is flushed at most this often for a +#: touch-only change — losing 15 s of an idle clock across a crash is +#: irrelevant against a three-hour timeout. State transitions always flush. +ACTIVITY_FLUSH_INTERVAL_S = 15.0 + + +class State: + STARTING = "starting" + READY = "ready" + EXITED = "exited" + KILLED = "killed" + REAPED = "reaped" + COMPOSITOR_LOST = "compositor_lost" + + +#: States a session can never leave. Reaching one writes a tombstone. +TERMINAL = frozenset({State.EXITED, State.KILLED, State.REAPED, State.COMPOSITOR_LOST}) + +#: The error name a verb should be answered with when it arrives at a session +#: in a terminal state (all map to exit 4). +TERMINAL_ERROR = { + State.EXITED: "session_exited", + State.KILLED: "session_killed", + State.REAPED: "session_reaped", + State.COMPOSITOR_LOST: "compositor_lost", +} + + +def boot_id() -> str: + """The kernel's boot id, or ``""`` if it cannot be read. + + Sessions cannot outlive a reboot — the compositor does not — so a record + whose ``boot_id`` differs from the running kernel's describes processes + that are certainly gone, whatever ``/proc`` says about the pid today. This + is cheaper and far safer than hoping ``CLOCK_BOOTTIME`` values from a + previous boot happen not to collide. + """ + + try: + return Path("/proc/sys/kernel/random/boot_id").read_text().strip() + except OSError: # pragma: no cover - /proc always has it on Linux + return "" + + +@dataclass(slots=True) +class Session: + """DESIGN.md §2.1, minus the fields M0 cannot honestly fill. + + ``window``, ``workspace`` and ``foreground`` exist in the record and are + always ``None`` in M0: the compositor is not reachable from here, and the + design is explicit that nothing may be guessed. + """ + + id: str + app: str + argv: list[str] + pid: int + pgid: int + sid: int + pid_starttime: int + cmdline_sha256: str + home: str + runtime_dir: str + created_at: str + created_boottime: float + last_activity_at: str + last_activity_boottime: float + idle_timeout_s: float + state: str = State.STARTING + adopted: bool = False + ready_signal: str | None = None + workspace: int | None = None + window: Any = None + foreground: bool | None = None + command_count: int = 0 + exit_code: int | None = None + exit_detected_by: str | None = None + last_error: str | None = None + log_path: str | None = None + ephemeral_home: bool = False + tombstoned_boottime: float | None = None + tombstone_ttl_s: float = DEFAULT_TOMBSTONE_TTL_S + boot_id: str = "" + schema: int = SCHEMA + + # ---- derived ----------------------------------------------------- + + @property + def live(self) -> bool: + return self.state not in TERMINAL + + def deadline(self) -> float | None: + """The boottime instant at which this session becomes idle-expired. + + ``None`` for a session that can never expire: one in a terminal state, + or one whose idle timeout is zero (disabled). + """ + + if not self.live or not self.idle_timeout_s: + return None + return self.last_activity_boottime + self.idle_timeout_s + + def expires_in(self, now: float) -> float | None: + deadline = self.deadline() + return None if deadline is None else deadline - now + + def idle_for(self, now: float) -> float | None: + return None if not self.live else now - self.last_activity_boottime + + def tombstone_expires(self) -> float | None: + if self.tombstoned_boottime is None: + return None + return self.tombstoned_boottime + self.tombstone_ttl_s + + def to_dict(self) -> dict[str, Any]: + return asdict(self) + + @classmethod + def from_dict(cls, data: dict[str, Any]) -> "Session": + known = {f for f in cls.__dataclass_fields__} + unknown = set(data) - known + if unknown: + # Forward compatibility: a newer daemon's extra fields are dropped + # rather than crashing the adopt path. + log.warning("dropping unknown record fields %s", sorted(unknown)) + return cls(**{k: v for k, v in data.items() if k in known}) + + def public(self, now: float) -> dict[str, Any]: + """The record as the protocol reports it, with the derived numbers.""" + + data = self.to_dict() + data["idle_s"] = self.idle_for(now) + data["expires_in_s"] = self.expires_in(now) + data["live"] = self.live + data["tombstone_expires_in_s"] = ( + None if self.tombstone_expires() is None else self.tombstone_expires() - now + ) + return data + + +def mint_id(app: str, taken: set[str], *, rng: Any = secrets) -> str: + """``-<6 base32 chars>`` (DESIGN.md §2.2). + + Handles are never reused: an id present in the live *or* tombstone set is + refused and another drawn. Nothing parses the slug; it is a readability + affordance. + """ + + slug = "".join(c if c.isalnum() else "-" for c in app.lower()).strip("-") or "app" + slug = slug[:24] + for _ in range(1000): + raw = rng.token_bytes(5) + suffix = base64.b32encode(raw).decode("ascii").rstrip("=").lower()[:6] + candidate = f"{slug}-{suffix}" + if candidate not in taken: + return candidate + raise RuntimeError("could not mint an unused session id") # pragma: no cover + + +def atomic_write_json(path: Path, data: dict[str, Any]) -> None: + """Write ``data`` to ``path`` atomically: temp file in the same directory, + fsync, then :func:`os.replace`. + + Same directory matters — ``os.replace`` is only atomic within a filesystem. + """ + + path.parent.mkdir(parents=True, exist_ok=True) + tmp = path.parent / f".{path.name}.{os.getpid()}.{secrets.token_hex(4)}.tmp" + try: + with open(tmp, "w", encoding="utf-8") as fh: + json.dump(data, fh, ensure_ascii=True, sort_keys=True) + fh.write("\n") + fh.flush() + os.fsync(fh.fileno()) + os.replace(tmp, path) + except BaseException: + try: + tmp.unlink() + except OSError: + pass + raise + + +class Registry: + """The in-memory session table and its on-disk mirror.""" + + def __init__(self, state_dir: Path | str, clock: Clock | None = None) -> None: + self.state_dir = Path(state_dir) + self.sessions_dir = self.state_dir / "sessions" + self.quarantine_dir = self.sessions_dir / "bad" + self.clock = clock or Clock() + self._sessions: dict[str, Session] = {} + self._last_flush: dict[str, float] = {} + self._boot_id = boot_id() + + # ---- directories ------------------------------------------------- + + def ensure_dirs(self) -> None: + """Create the state directories if the supervisor has not. + + In production these come from the unit's ``StateDirectory=``; M0 ships + as an ordinary process, so the daemon creates what is missing rather + than depending on how it is supervised. + """ + + self.sessions_dir.mkdir(parents=True, exist_ok=True, mode=0o750) + + # ---- table ------------------------------------------------------- + + def __contains__(self, session_id: object) -> bool: + return session_id in self._sessions + + def __len__(self) -> int: + return len(self._sessions) + + def __iter__(self) -> Iterator[Session]: + return iter(list(self._sessions.values())) + + def get(self, session_id: str) -> Session | None: + return self._sessions.get(session_id) + + def all(self) -> list[Session]: + return sorted(self._sessions.values(), key=lambda s: s.created_boottime) + + def live(self) -> list[Session]: + return [s for s in self.all() if s.live] + + def tombstones(self) -> list[Session]: + return [s for s in self.all() if not s.live] + + def taken_ids(self) -> set[str]: + """Live *and* tombstoned ids, so handles are never reused.""" + + return set(self._sessions) + + def new_id(self, app: str) -> str: + return mint_id(app, self.taken_ids()) + + def add(self, session: Session) -> Session: + if session.id in self._sessions: + raise KeyError(f"session id already in use: {session.id}") + if not session.boot_id: + session.boot_id = self._boot_id + self._sessions[session.id] = session + self.persist(session, force=True) + return session + + def record_path(self, session_id: str) -> Path: + return self.sessions_dir / f"{session_id}.json" + + def persist(self, session: Session, *, force: bool = False) -> None: + """Mirror one record. Never raises: a mirror failure is not a command failure.""" + + now = self.clock.boottime() + if not force and now - self._last_flush.get(session.id, 0.0) < ACTIVITY_FLUSH_INTERVAL_S: + return + try: + self.ensure_dirs() + atomic_write_json(self.record_path(session.id), session.to_dict()) + self._last_flush[session.id] = now + except OSError as exc: + log.error("mirror write failed for %s: %s (memory is authoritative)", session.id, exc) + + def flush_all(self) -> None: + for session in self.all(): + self.persist(session, force=True) + + def drop(self, session_id: str) -> None: + """Forget a record entirely and remove its mirror (used by ``gc``).""" + + self._sessions.pop(session_id, None) + self._last_flush.pop(session_id, None) + try: + self.record_path(session_id).unlink() + except FileNotFoundError: + pass + except OSError as exc: + log.error("could not remove mirror for %s: %s", session_id, exc) + + # ---- transitions ------------------------------------------------- + + def touch(self, session: Session, *, force_flush: bool = False) -> None: + """Stamp activity. Callers stamp *after* a command is accepted.""" + + session.last_activity_boottime = self.clock.boottime() + session.last_activity_at = iso(self.clock.wall()) + session.command_count += 1 + self.persist(session, force=force_flush) + + def terminate( + self, + session: Session, + state: str, + *, + exit_code: int | None = None, + exit_detected_by: str | None = None, + last_error: str | None = None, + ) -> None: + """Move a session to a terminal state and write its tombstone.""" + + session.state = state + if exit_code is not None: + session.exit_code = exit_code + if exit_detected_by is not None: + session.exit_detected_by = exit_detected_by + if last_error is not None: + session.last_error = last_error + session.tombstoned_boottime = self.clock.boottime() + self.persist(session, force=True) + + # ---- startup adoption ------------------------------------------- + + def load_records(self) -> tuple[list[Session], list[tuple[Path, str]]]: + """Read the mirror. Returns ``(records, quarantined)``. + + A record that will not parse is moved to ``sessions/bad/`` and logged + loudly; its processes are left running and reported by ``gc`` rather + than killed on the basis of unreadable state (DESIGN.md §7 #13). + """ + + records: list[Session] = [] + quarantined: list[tuple[Path, str]] = [] + if not self.sessions_dir.is_dir(): + return records, quarantined + for path in sorted(self.sessions_dir.glob("*.json")): + try: + data = json.loads(path.read_text(encoding="utf-8")) + if not isinstance(data, dict): + raise ValueError("record is not an object") + session = Session.from_dict(data) + except (OSError, ValueError, TypeError) as exc: + reason = f"{type(exc).__name__}: {exc}" + log.error("quarantining unreadable record %s: %s", path, reason) + quarantined.append((path, reason)) + self._quarantine(path) + continue + records.append(session) + return records, quarantined + + def _quarantine(self, path: Path) -> None: + try: + self.quarantine_dir.mkdir(parents=True, exist_ok=True, mode=0o750) + os.replace(path, self.quarantine_dir / f"{path.name}.{int(time.time())}") + except OSError as exc: # pragma: no cover - best effort + log.error("could not quarantine %s: %s", path, exc) + + def insert_loaded(self, session: Session) -> Session: + """Put a record read from disk back into the table without re-persisting.""" + + self._sessions[session.id] = session + return session + + def stale_boot(self, session: Session) -> bool: + """True if the record was written before the current boot. + + Its processes are gone whatever ``/proc`` says, because pids are + recycled from zero at boot. + """ + + return bool(session.boot_id) and bool(self._boot_id) and session.boot_id != self._boot_id + + +def clone(session: Session, **changes: Any) -> Session: + return replace(session, **changes) diff --git a/src/hhstreamd/server.py b/src/hhstreamd/server.py new file mode 100644 index 0000000..acaf348 --- /dev/null +++ b/src/hhstreamd/server.py @@ -0,0 +1,335 @@ +"""The control socket (DESIGN.md §3.4). + +An asyncio unix ``SOCK_STREAM`` server speaking newline-delimited JSON: one +request object, one response object, connection closed. Chosen over HTTP +(framing and a server for no benefit on a local socket), D-Bus (no stdlib +client) and a bespoke binary protocol (unreadable at 3am). It is debuggable +with ``socat - UNIX-CONNECT:/run/hhstream/control.sock`` and costs nothing. + +This module is framing and dispatch only. Every decision lives in +:mod:`hhstreamd.manager`. +""" + +from __future__ import annotations + +import asyncio +import collections +import contextlib +import logging +import os +import socket +import struct +from pathlib import Path +from typing import Any, Awaitable, Callable + +from . import protocol +from .manager import ManagerError, SessionManager +from .policy import PolicyError + +log = logging.getLogger("hhstreamd.server") + +#: A request that has not produced a reply in this long is abandoned and the +#: caller told so, rather than holding the connection open indefinitely. +DEFAULT_REQUEST_TIMEOUT_S = 5.0 + +#: A `kill` may legitimately take `grace` seconds, so it gets its own budget. +KILL_TIMEOUT_MARGIN_S = 5.0 + +#: Replies to mutating verbs are remembered so a CLI that died before reading +#: the reply can retry without launching a second application. +DEDUP_ENTRIES = 64 + +#: Verbs whose replies are cached by `request_id`. The read verbs are absent +#: deliberately: they are idempotent, so a retry costs nothing and a cached +#: `list` would be a stale one. +MUTATING_VERBS = frozenset({"start", "touch", "kill", "adopt", "gc"}) + + +class ControlServer: + def __init__( + self, + manager: SessionManager, + socket_path: Path | str, + *, + request_timeout_s: float = DEFAULT_REQUEST_TIMEOUT_S, + socket_mode: int = 0o660, + ) -> None: + self.manager = manager + self.socket_path = Path(socket_path) + self.request_timeout_s = request_timeout_s + self.socket_mode = socket_mode + self._server: asyncio.AbstractServer | None = None + self._dedup: collections.OrderedDict[str, dict[str, Any]] = collections.OrderedDict() + self._ops: dict[str, Callable[[dict[str, Any], dict[str, Any]], Awaitable[dict[str, Any]]]] = { + "ping": self._op_ping, + "start": self._op_start, + "list": self._op_list, + "status": self._op_status, + "touch": self._op_touch, + "kill": self._op_kill, + "gc": self._op_gc, + "adopt": self._op_adopt, + "logs": self._op_logs, + } + + # ------------------------------------------------------------------ + # lifecycle + # ------------------------------------------------------------------ + + async def start(self) -> None: + self._prepare_socket_path() + self._server = await asyncio.start_unix_server( + self._handle, + path=str(self.socket_path), + # The stream limit is the frame limit: a peer cannot grow the + # daemon's read buffer past one message. + limit=protocol.MAX_LINE_BYTES, + ) + with contextlib.suppress(OSError): + os.chmod(self.socket_path, self.socket_mode) + log.info("listening on %s", self.socket_path) + + async def stop(self) -> None: + if self._server is not None: + self._server.close() + with contextlib.suppress(Exception): + await self._server.wait_closed() + self._server = None + with contextlib.suppress(FileNotFoundError, OSError): + self.socket_path.unlink() + + def _prepare_socket_path(self) -> None: + """Create the parent directory and clear a stale socket. + + A socket file left by a crashed daemon is unlinked only after proving + nobody is listening on it: connecting and being refused is the proof. + Unlinking a *live* socket would silently steal another daemon's clients. + """ + + self.socket_path.parent.mkdir(parents=True, exist_ok=True, mode=0o750) + if not self.socket_path.exists(): + return + probe = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) + try: + probe.settimeout(0.5) + probe.connect(str(self.socket_path)) + except (ConnectionRefusedError, FileNotFoundError): + log.warning("removing stale socket %s", self.socket_path) + with contextlib.suppress(OSError): + self.socket_path.unlink() + except OSError as exc: + raise OSError( + f"{self.socket_path} exists and could not be probed: {exc}" + ) from exc + else: + raise OSError(f"another daemon is already listening on {self.socket_path}") + finally: + probe.close() + + # ------------------------------------------------------------------ + # connection handling + # ------------------------------------------------------------------ + + async def _handle(self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None: + caller = _peer_credentials(writer) + try: + try: + line = await reader.readuntil(b"\n") + except asyncio.IncompleteReadError as exc: + if not exc.partial: + return # a peer that connected and went away; not an error + line = exc.partial + except asyncio.LimitOverrunError: + await self._send( + writer, + protocol.error("message_too_large", "request exceeds the frame limit"), + ) + return + if len(line) > protocol.MAX_LINE_BYTES: + await self._send( + writer, + protocol.error("message_too_large", "request exceeds the frame limit"), + ) + return + response = await self._dispatch(line, caller) + await self._send(writer, response) + except (ConnectionResetError, BrokenPipeError): + pass + except Exception: + log.exception("unhandled error serving a request") + with contextlib.suppress(Exception): + await self._send( + writer, protocol.error("refused", "internal error; see the daemon log") + ) + finally: + with contextlib.suppress(Exception): + writer.close() + await writer.wait_closed() + + async def _send(self, writer: asyncio.StreamWriter, message: dict[str, Any]) -> None: + writer.write(protocol.encode(message)) + await writer.drain() + + async def _dispatch(self, line: bytes, caller: dict[str, Any]) -> dict[str, Any]: + started = self.manager.clock.boottime() + try: + request = protocol.decode_request(line) + except protocol.ProtocolError as exc: + self.manager.audit.emit( + "request_rejected", error=exc.error, reason=exc.reason, caller=caller + ) + return protocol.error(exc.error, exc.reason) + + op = request["op"] + request_id = request.get("request_id") + handler = self._ops.get(op) + if handler is None: + return protocol.error( + "unknown_op", f"unknown op {op!r}", hint=f"known: {', '.join(sorted(self._ops))}" + ) + + if isinstance(request_id, str) and op in MUTATING_VERBS and request_id in self._dedup: + cached = dict(self._dedup[request_id]) + cached["deduplicated"] = True + return cached + + timeout = self.request_timeout_s + if op == "kill": + # A kill is allowed to take its grace period plus the SIGKILL step. + grace = request.get("grace_s") + grace = self.manager.config.policy.grace_s if grace is None else float(grace or 0) + timeout = max(timeout, grace + KILL_TIMEOUT_MARGIN_S) + elif op == "start": + wait_ready = request.get("wait_ready_s") + wait_ready = ( + self.manager.config.policy.wait_ready_s if wait_ready is None else float(wait_ready or 0) + ) + timeout = max(timeout, wait_ready + 1.0) + + try: + response = await asyncio.wait_for(handler(request, caller), timeout=timeout) + except TimeoutError: + response = protocol.error("timeout", f"{op} did not complete within {timeout:g}s") + except ManagerError as exc: + response = protocol.error(exc.error, exc.reason, hint=exc.hint, **exc.fields) + except PolicyError as exc: + response = protocol.error(exc.error, exc.reason, hint=exc.hint) + except (TypeError, ValueError) as exc: + response = protocol.error("invalid_argument", str(exc)) + except Exception as exc: + log.exception("op %s failed", op) + response = protocol.error("refused", f"internal error: {type(exc).__name__}") + + elapsed_ms = round((self.manager.clock.boottime() - started) * 1000, 3) + response.setdefault("elapsed_ms", elapsed_ms) + if isinstance(request_id, str): + response["request_id"] = request_id + if op in MUTATING_VERBS: + self._remember(request_id, response) + + self.manager.audit.emit( + "request", + verb=op, + session=request.get("id") or response.get("id"), + caller=caller, + ok=bool(response.get("ok")), + error=response.get("error"), + duration_ms=elapsed_ms, + request_id=request_id if isinstance(request_id, str) else None, + ) + return response + + def _remember(self, request_id: str, response: dict[str, Any]) -> None: + self._dedup[request_id] = dict(response) + self._dedup.move_to_end(request_id) + while len(self._dedup) > DEDUP_ENTRIES: + self._dedup.popitem(last=False) + + # ------------------------------------------------------------------ + # ops + # ------------------------------------------------------------------ + + async def _op_ping(self, request: dict[str, Any], caller: dict[str, Any]) -> dict[str, Any]: + from . import __version__ + + return protocol.ok( + version=__version__, + pid=os.getpid(), + boottime=self.manager.now(), + live=len(self.manager.registry.live()), + ) + + async def _op_start(self, request: dict[str, Any], caller: dict[str, Any]) -> dict[str, Any]: + record = await self.manager.start( + request.get("app"), + request.get("argv"), + idle_timeout_s=request.get("idle_timeout_s"), + wait_ready_s=request.get("wait_ready_s"), + home=request.get("home"), + ephemeral_home=bool(request.get("ephemeral_home", False)), + ) + return protocol.ok(id=record["id"], state=record["state"], session=record) + + async def _op_list(self, request: dict[str, Any], caller: dict[str, Any]) -> dict[str, Any]: + return protocol.ok(**self.manager.list(include_tombstones=bool(request.get("all", False)))) + + async def _op_status(self, request: dict[str, Any], caller: dict[str, Any]) -> dict[str, Any]: + record = self.manager.status(request.get("id"), events=int(request.get("events", 20))) + return protocol.ok(id=record["id"], state=record["state"], session=record) + + async def _op_touch(self, request: dict[str, Any], caller: dict[str, Any]) -> dict[str, Any]: + record = self.manager.touch(request.get("id")) + return protocol.ok(id=record["id"], state=record["state"], session=record) + + async def _op_kill(self, request: dict[str, Any], caller: dict[str, Any]) -> dict[str, Any]: + record = await self.manager.kill( + request.get("id"), + grace_s=request.get("grace_s"), + sig=request.get("signal", "TERM"), + ) + return protocol.ok(id=record["id"], state=record["state"], session=record) + + async def _op_gc(self, request: dict[str, Any], caller: dict[str, Any]) -> dict[str, Any]: + return protocol.ok(**self.manager.gc()) + + async def _op_adopt(self, request: dict[str, Any], caller: dict[str, Any]) -> dict[str, Any]: + record = await self.manager.adopt( + request.get("pid"), + app=request.get("app"), + idle_timeout_s=request.get("idle_timeout_s"), + ) + return protocol.ok(id=record["id"], state=record["state"], session=record) + + async def _op_logs(self, request: dict[str, Any], caller: dict[str, Any]) -> dict[str, Any]: + return protocol.ok( + **self.manager.logs( + request.get("id"), + lines=int(request.get("lines", 100)), + offset=request.get("offset"), + ) + ) + + +def _peer_credentials(writer: asyncio.StreamWriter) -> dict[str, Any]: + """``SO_PEERCRED`` of the connecting process, for the audit log. + + M0 records who asked but does **not** authorise on it: the uid/gid + allowlist is §8 item 2, which the brief holds out of this milestone. The + socket's own mode and its directory are the access control here. + """ + + sock = writer.get_extra_info("socket") + if sock is None: + return {} + try: + raw = sock.getsockopt(socket.SOL_SOCKET, socket.SO_PEERCRED, struct.calcsize("3i")) + pid, uid, gid = struct.unpack("3i", raw) + except OSError: + return {} + caller: dict[str, Any] = {"pid": pid, "uid": uid, "gid": gid} + try: + with open(f"/proc/{pid}/comm", encoding="utf-8") as fh: + caller["comm"] = fh.read().strip() + except OSError: + pass + return caller diff --git a/src/hhstreamd/textio.py b/src/hhstreamd/textio.py new file mode 100644 index 0000000..7eb3b21 --- /dev/null +++ b/src/hhstreamd/textio.py @@ -0,0 +1,51 @@ +"""Reading the tail of a file that may be arbitrarily large. + +Both the audit log and an application's captured output are append-only files +with no upper bound in M0, and both are read by verbs that must stay cheap. +Reading either whole — ``readlines()`` on a gigabyte of Chromium stderr — would +turn a ``status`` into an out-of-memory event on a machine that already has no +resource caps (DESIGN.md §3.3). So every tail read is bounded in bytes, and +says when it truncated. +""" + +from __future__ import annotations + +import os +from pathlib import Path + +#: The most any single tail read will pull into memory. +DEFAULT_TAIL_BYTES = 1 << 20 # 1 MiB + + +def tail_lines( + path: Path | str, limit: int, *, max_bytes: int = DEFAULT_TAIL_BYTES +) -> tuple[list[str], bool, int]: + """The last ``limit`` lines of ``path``. + + Returns ``(lines, truncated, size)``. ``truncated`` is true when the window + did not reach the start of the file, so a caller can say so rather than + implying it showed everything. + """ + + if limit <= 0: + try: + return [], False, os.stat(path).st_size + except OSError: + return [], False, 0 + try: + with open(path, "rb") as fh: + size = fh.seek(0, os.SEEK_END) + window = min(size, max_bytes) + fh.seek(size - window) + data = fh.read(window) + except OSError: + return [], False, 0 + partial = window < size + if partial: + # The window almost certainly starts mid-line; drop that fragment + # rather than reporting a half line as if it were whole. + newline = data.find(b"\n") + data = data[newline + 1 :] if newline != -1 else b"" + lines = data.decode("utf-8", "replace").splitlines() + truncated = partial or len(lines) > limit + return lines[-limit:], truncated, size diff --git a/tests/sessions/conftest.py b/tests/sessions/conftest.py new file mode 100644 index 0000000..8bc02e0 --- /dev/null +++ b/tests/sessions/conftest.py @@ -0,0 +1,80 @@ +"""Shared fixtures. + +Two things are worth knowing: + +* **Nothing here sleeps for real time** except where the brief requires it: the + one integration test that proves a real three-second idle reap. Everything + else either injects a clock or polls with a deadline. +* **Unix socket paths are short by force.** ``AF_UNIX`` caps a path at 108 + bytes and ``pytest``'s ``tmp_path`` can exceed that on a deep ``TMPDIR``, so + sockets live in a shallow ``mkdtemp`` of their own rather than under + ``tmp_path``. +""" + +from __future__ import annotations + +import os +import shutil +import socket +import sys +import tempfile +import time +from pathlib import Path + +import pytest + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) + +#: Linux's sun_path is 108 bytes including the NUL. +SUN_PATH_MAX = 107 + + +@pytest.fixture +def short_tmpdir() -> Path: + """A temp directory shallow enough to hold a unix socket path.""" + + path = Path(tempfile.mkdtemp(prefix="hh")) + try: + yield path + finally: + shutil.rmtree(path, ignore_errors=True) + + +def socket_path(directory: Path, name: str = "c.sock") -> str: + path = str(directory / name) + if len(path.encode()) > SUN_PATH_MAX: + pytest.skip(f"socket path too long for AF_UNIX ({len(path)} bytes): {path}") + return path + + +def wait_until(predicate, timeout: float, interval: float = 0.02, what: str = "condition"): + """Poll ``predicate`` until it is truthy. Returns its value, or fails. + + This is how the integration tests wait: a deadline and a tight poll, never + a fixed sleep sized by guesswork. + """ + + deadline = time.monotonic() + timeout + while True: + value = predicate() + if value: + return value + if time.monotonic() > deadline: + pytest.fail(f"timed out after {timeout}s waiting for {what}") + time.sleep(interval) + + +def pid_alive(pid: int) -> bool: + return os.path.isdir(f"/proc/{pid}") + + +def socket_is_live(path: str) -> bool: + sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) + try: + sock.settimeout(0.5) + sock.connect(path) + return True + except OSError: + return False + finally: + sock.close() diff --git a/tests/sessions/integration/test_lifecycle.py b/tests/sessions/integration/test_lifecycle.py new file mode 100644 index 0000000..6c51569 --- /dev/null +++ b/tests/sessions/integration/test_lifecycle.py @@ -0,0 +1,1125 @@ +"""Integration: a real daemon, a real socket, real processes, real reaps. + +No compositor, no network. The only thing that waits for wall-clock time is +the three-second idle timeout the brief asks to see fire for real; everything +else polls against a deadline. + +The dummy app is the brief's: ``python3 -c 'import time; time.sleep(600)'``. +Two variants exist alongside it, because they are the cases the design's +teardown is actually about — a grandchild inside the process group, and a child +that called ``setsid()`` and so escaped it. +""" + +from __future__ import annotations + +import io +import json +import os +import shlex +import signal +import socket +import subprocess +import sys +import time +from contextlib import redirect_stderr, redirect_stdout +from pathlib import Path + +import pytest + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) + +import hhstream_session +from conftest import pid_alive, socket_is_live, socket_path, wait_until +from hhstream_session.client import call +from hhstreamd.protocol import ExitCode + +PY = sys.executable + + +def _repo_root() -> Path: + """The repository root, found rather than counted. + + This file was written in a flat scratch layout and harvested into the real + repository one directory deeper. Counting `.parents[n]` broke the moment that + happened, so look for the marker instead. + """ + + for parent in Path(__file__).resolve().parents: + if (parent / "pyproject.toml").is_file(): + return parent + raise RuntimeError("no pyproject.toml above this test file") + + +REPO_ROOT = _repo_root() +#: The package lives under `src/` here. Keep the root too, so a flat checkout works. +IMPORT_PATH = os.pathsep.join([str(REPO_ROOT / "src"), str(REPO_ROOT)]) + +# The brief's dummy app, verbatim. +SLEEP_600 = "import time; time.sleep(600)" + +# Same, but it first spawns a grandchild inside the same process group. The +# grandchild's pid is printed so the test can assert it dies with the session. +WITH_GRANDCHILD = ( + "import subprocess, sys, time; " + "p = subprocess.Popen([sys.executable, '-c', 'import time; time.sleep(600)']); " + "print('grandchild', p.pid, flush=True); " + "time.sleep(600)" +) + +# A child that calls setsid() itself: it leaves the process group, so killpg +# misses it, but it keeps the session id, so the /proc sweep catches it. +# This is the fixture DESIGN.md §6.5 names for proving the sweep works. +WITH_ESCAPEE = ( + "import subprocess, sys, time; " + "p = subprocess.Popen([sys.executable, '-c', 'import time; time.sleep(600)'], " + "start_new_session=False, preexec_fn=None); " + "import os; " + "q = subprocess.Popen([sys.executable, '-c', " + "'import os, time; os.setpgid(0, 0); time.sleep(600)']); " + "print('child', p.pid, flush=True); " + "print('escapee', q.pid, flush=True); " + "time.sleep(600)" +) + +INSTANT_EXIT = "import sys; sys.exit(7)" + +# BUG-02's victim. On the target platform `/run/current-system/sw/bin/` is +# almost always a wrapper script that `exec`s the real binary, which arrives with +# an argv of its own — so the argv the daemon recorded at launch is not the argv +# `/proc` reports a moment later. That is a healthy application, and the daemon +# used to classify it as a recycled pid. +# +# The `go` file is what makes the test deterministic rather than a race: the +# wrapper blocks until the test says so, which guarantees the daemon recorded +# *this* shell's argv before the real binary replaced it. Without it the test +# would depend on the daemon reading /proc faster than `sh` can start. +WRAPPER_SH = """#!/bin/sh +# An `exec`ing wrapper script, as /run/current-system/sw/bin/ is. +while [ ! -e {go} ]; do sleep 0.02; done +exec {py} -c {code} +""" + +# BUG-01's victim: an app that reports the session environment it was handed and +# then stays alive, so the test can read it back through `session logs`. +ENV_DUMP = ( + "import json, os, sys, time; " + "print(json.dumps({k: os.environ.get(k) for k in " + "('XDG_RUNTIME_DIR', 'WAYLAND_DISPLAY', 'XDG_SESSION_TYPE')}), flush=True); " + "time.sleep(600)" +) + +#: How the daemon may report having noticed an exit: a pidfd, or the documented +#: /proc fallback where pidfd is unavailable. +EXIT_MECHANISMS = {"pidfd", "proc_poll", "proc_check"} + + +def config_text(wrapper: Path | None = None) -> str: + def app(name: str, code: str) -> str: + return f'\n[apps.{name}]\nexec = {json.dumps(PY)}\nargs = ["-c", {json.dumps(code)}]\n' + + wrapped = ( + f'\n[apps.wrapped]\nexec = {json.dumps(str(wrapper))}\nargs = []\n' + if wrapper is not None + else "" + ) + + return (wrapped + + "[defaults]\n" + "max_sessions = 8\n" + "idle_timeout_s = 3600\n" + "max_idle_timeout_s = 86400\n" + "grace_s = 2\n" + + app("sleeper", SLEEP_600) + + app("nested", WITH_GRANDCHILD) + + app("escapee", WITH_ESCAPEE) + + app("instant", INSTANT_EXIT) + + app("echoer", "import time; print('hello', flush=True); time.sleep(600)") + + app("chatty", "import time\nfor i in range(3):\n print(f'line {i}', flush=True)\n time.sleep(0.2)") + + app("envdump", ENV_DUMP) + ) + + +class Daemon: + """A real ``python -m hhstreamd`` in a subprocess, on a temp socket.""" + + def __init__(self, root: Path, *extra_args: str): + self.extra_args = list(extra_args) + self.root = root + self.socket = socket_path(root) + self.state_dir = root / "state" + self.runtime_dir = root / "run" + self.config = root / "config.toml" + # BUG-02: the `wrapped` app is reached through this five-line script, + # which `exec`s the real binary and so replaces the launched argv. + self.wrapper_go = root / "wrapper-go" + self.wrapper = root / "wrapper.sh" + self.wrapper.write_text( + WRAPPER_SH.format( + go=shlex.quote(str(self.wrapper_go)), + py=shlex.quote(PY), + code=shlex.quote(WITH_GRANDCHILD), + ) + ) + self.wrapper.chmod(0o755) + self.config.write_text(config_text(self.wrapper)) + self.log = root / "daemon.log" + self.process: subprocess.Popen | None = None + + def release_wrapper(self) -> None: + """Let the wrapper reach its `exec`. The argv changes from here.""" + + self.wrapper_go.write_text("go") + + def start(self) -> None: + self.process = subprocess.Popen( + [ + PY, "-m", "hhstreamd", + "--socket", self.socket, + "--state-dir", str(self.state_dir), + "--runtime-dir", str(self.runtime_dir), + "--config", str(self.config), + "--log-level", "debug", + *self.extra_args, + ], + stdout=open(self.log, "ab"), + stderr=subprocess.STDOUT, + cwd=str(REPO_ROOT), + env={**os.environ, "PYTHONPATH": IMPORT_PATH}, + ) + wait_until( + lambda: socket_is_live(self.socket) or self.process.poll() is not None, + timeout=15.0, + what="the daemon to listen", + ) + if self.process.poll() is not None: + pytest.fail(f"daemon exited at startup:\n{self.log.read_text()}") + + def stop(self, sig: int = signal.SIGTERM) -> None: + if self.process is None or self.process.poll() is not None: + return + self.process.send_signal(sig) + try: + self.process.wait(timeout=10) + except subprocess.TimeoutExpired: # pragma: no cover + self.process.kill() + self.process.wait(timeout=5) + + # ---- driving it --------------------------------------------------- + + def call(self, op: str, **fields): + return call(op, socket_path=self.socket, **fields) + + def cli(self, *argv: str) -> tuple[int, str, str]: + """Run a verb through the *registered CLI handlers*, in process. + + This is the integration contract the brief asks for: argparse + registration, the handler, the socket client and the exit-code mapping, + all of it. + """ + + out, err = io.StringIO(), io.StringIO() + with redirect_stdout(out), redirect_stderr(err): + code = hhstream_session.main(["session", "--socket", self.socket, *argv]) + return code, out.getvalue(), err.getvalue() + + def session(self, session_id: str) -> dict: + reply = self.call("status", id=session_id) + assert reply.get("ok"), reply + return reply["session"] + + def state_of(self, session_id: str) -> str: + return self.session(session_id)["state"] + + +@pytest.fixture +def daemon(short_tmpdir: Path): + d = Daemon(short_tmpdir) + d.start() + try: + yield d + finally: + # Kill anything still running before the daemon goes away, so a failing + # test cannot leak a 600-second sleeper. + try: + for session in d.call("list", all=True).get("sessions", []): + if session.get("live"): + with_suppressed(lambda: d.call("kill", id=session["id"], grace_s=0)) + except Exception: + pass + d.stop() + + +def compositor_dir(root: Path, name: str = "wayland-1") -> tuple[Path, socket.socket]: + """A stand-in for the compositor's runtime directory: one *listening* socket. + + A bound-and-listening ``AF_UNIX`` socket is indistinguishable from a live + compositor as far as discovery is concerned, and needs no compositor. + """ + + directory = root / "comp" + directory.mkdir(exist_ok=True) + (directory / f"{name}.lock").write_text("") # as libwayland leaves it + sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) + path = directory / name + if len(str(path).encode()) > 107: # pragma: no cover - SUN_PATH_MAX + pytest.skip(f"socket path too long for AF_UNIX: {path}") + sock.bind(str(path)) + sock.listen(4) + return directory, sock + + +def with_suppressed(fn): + try: + return fn() + except Exception: + return None + + +def start(daemon: Daemon, app: str, **fields) -> str: + reply = daemon.call("start", app=app, **fields) + assert reply.get("ok"), reply + return reply["id"] + + +# =========================================================================== +# the lifecycle the brief asks for: start -> status -> touch -> kill +# =========================================================================== + + +def test_real_lifecycle_start_status_touch_kill(daemon: Daemon): + # --- start, through the registered CLI handler ------------------- + code, out, err = daemon.cli("start", "nested") + assert code == ExitCode.OK, err + session_id = out.strip() + assert session_id and "\n" not in session_id, "stdout must be the bare id and nothing else" + assert session_id in err and "touch" in err, "the start output must name the keepalive verb" + + record = daemon.session(session_id) + pid = record["pid"] + assert record["state"] == "ready" + assert record["pgid"] == pid == record["sid"], "start_new_session must give sid == pgid == pid" + assert pid_alive(pid) + assert os.getsid(pid) == pid + + # The app really was spawned from the allowlist's absolute path, as a list. + assert record["argv"][0] == PY + assert record["argv"][1] == "-c" + + # --- the grandchild is inside the session ------------------------ + grandchild = wait_until( + lambda: _grandchild_pid(daemon, session_id), timeout=10.0, what="the grandchild's pid" + ) + assert pid_alive(grandchild) + assert os.getsid(grandchild) == pid, "the grandchild shares the session id" + + # --- status ------------------------------------------------------ + code, out, _ = daemon.cli("status", session_id, "--json") + assert code == ExitCode.OK + status = json.loads(out)["session"] + assert status["id"] == session_id + assert status["ready_signal"] == "spawned" + # Compositor enrichment degrades to absent in M0 and is never guessed. + assert status["window"] is None + assert status["workspace"] is None + assert status["compositor"]["ipc"] == "absent" + + # --- touch is the only thing that moves the clock ---------------- + before = daemon.session(session_id) + time.sleep(0.05) + daemon.cli("list") + daemon.cli("status", session_id) + daemon.cli("logs", session_id) + daemon.cli("gc") + after_reads = daemon.session(session_id) + assert after_reads["last_activity_boottime"] == before["last_activity_boottime"], ( + "list/status/logs/gc must not count as activity" + ) + + code, out, _ = daemon.cli("touch", session_id) + assert code == ExitCode.OK + after_touch = daemon.session(session_id) + assert after_touch["last_activity_boottime"] > before["last_activity_boottime"] + assert after_touch["command_count"] > before["command_count"] + + # --- kill -------------------------------------------------------- + code, out, err = daemon.cli("kill", session_id, "--grace", "2s") + assert code == ExitCode.OK, err + + record = daemon.session(session_id) + assert record["state"] == "killed" + assert record["live"] is False + + # The process AND the grandchild are gone. + wait_until(lambda: not pid_alive(pid), timeout=10.0, what="the session leader to exit") + wait_until(lambda: not pid_alive(grandchild), timeout=10.0, what="the grandchild to exit") + + # And nothing is left sharing the session id. + assert _session_members(record["sid"]) == [] + + # --- a verb against a dead session is exit 4 --------------------- + code, _, err = daemon.cli("touch", session_id) + assert code == ExitCode.BAD_STATE + assert "killed" in err + + +def test_a_three_second_idle_timeout_reaps_a_session_for_real(daemon: Daemon): + """The reaper, end to end: no injected clock, no debug hooks, real signals.""" + + started = time.monotonic() + session_id = start(daemon, "sleeper", idle_timeout_s=3) + pid = daemon.session(session_id)["pid"] + assert pid_alive(pid) + + # Reads must not keep it alive — this is the production failure the + # activity/non-activity split exists to prevent. + for _ in range(4): + time.sleep(0.5) + daemon.cli("list") + daemon.cli("status", session_id) + + wait_until( + lambda: daemon.state_of(session_id) == "reaped", + timeout=15.0, + interval=0.1, + what="the idle reaper to fire", + ) + elapsed = time.monotonic() - started + assert 3.0 <= elapsed < 15.0, f"reaped after {elapsed:.1f}s" + + wait_until(lambda: not pid_alive(pid), timeout=10.0, what="the reaped process to exit") + record = daemon.session(session_id) + assert record["state"] == "reaped" + assert record["tombstone_expires_in_s"] > 0 + + events = [e["event"] for e in record["events"]] + assert "reaped_started" in events and "reaped_completed" in events + + +def test_touching_a_session_keeps_it_past_its_idle_timeout(daemon: Daemon): + """The other half of the same contract: `touch` really does push the deadline.""" + + session_id = start(daemon, "sleeper", idle_timeout_s=3) + pid = daemon.session(session_id)["pid"] + for _ in range(6): # ~3s of touching, well past one timeout + time.sleep(0.5) + code, _, _ = daemon.cli("touch", session_id) + assert code == ExitCode.OK + assert daemon.state_of(session_id) == "ready" + assert pid_alive(pid) + + +# =========================================================================== +# teardown details +# =========================================================================== + + +def test_a_child_that_escapes_the_process_group_is_caught_by_the_session_sweep(daemon: Daemon): + """DESIGN.md §3.3 step 4, the substitute for a cgroup kill.""" + + session_id = start(daemon, "escapee") + record = daemon.session(session_id) + escapee = wait_until( + lambda: _logged_pid(daemon, session_id, "escapee"), timeout=10.0, what="the escapee's pid" + ) + wait_until(lambda: pid_alive(escapee), timeout=5.0, what="the escapee to exist") + assert os.getpgid(escapee) != record["pgid"], "the fixture must really leave the group" + assert os.getsid(escapee) == record["sid"], "but it keeps the session id" + + reply = daemon.call("kill", id=session_id, grace_s=1) + assert reply["ok"], reply + wait_until(lambda: not pid_alive(escapee), timeout=10.0, what="the escapee to be swept") + assert _session_members(record["sid"]) == [] + + +def test_an_app_that_exits_immediately_is_reported_as_exited_not_as_ready(daemon: Daemon): + """DESIGN.md §7 #3: never hand back a healthy-looking id for a dead process.""" + + reply = daemon.call("start", app="instant") + assert reply["ok"] is False + assert reply["error"] == "session_exited" + session_id = reply["id"] + record = daemon.session(session_id) + assert record["state"] == "exited" + assert record["exit_code"] == 7 + assert record["exit_detected_by"] in EXIT_MECHANISMS + + code, _, err = daemon.cli("status", session_id) + assert code == ExitCode.OK # status of a tombstone is a success + code, _, _ = daemon.cli("touch", session_id) + assert code == ExitCode.BAD_STATE + + +def test_an_app_that_exits_on_its_own_becomes_a_tombstone_with_its_exit_code(daemon: Daemon): + session_id = start(daemon, "sleeper") + pid = daemon.session(session_id)["pid"] + os.kill(pid, signal.SIGKILL) + wait_until( + lambda: daemon.state_of(session_id) == "exited", + timeout=10.0, + what="the daemon to notice the exit", + ) + record = daemon.session(session_id) + assert record["exit_code"] == -int(signal.SIGKILL) + assert record["exit_detected_by"] in EXIT_MECHANISMS + + +# =========================================================================== +# the rest of the verb surface +# =========================================================================== + + +def test_list_shows_live_sessions_and_all_shows_tombstones(daemon: Daemon): + a = start(daemon, "sleeper") + b = start(daemon, "sleeper") + daemon.call("kill", id=b, grace_s=0) + + code, out, _ = daemon.cli("list", "--json") + ids = {s["id"] for s in json.loads(out)["sessions"]} + assert ids == {a} + + code, out, _ = daemon.cli("list", "--all", "--json") + ids = {s["id"] for s in json.loads(out)["sessions"]} + assert ids == {a, b} + + code, out, _ = daemon.cli("list") + assert "EXPIRES IN" in out and a in out + + +def test_logs_serve_the_apps_output(daemon: Daemon): + session_id = start(daemon, "echoer") + lines = wait_until( + lambda: daemon.call("logs", id=session_id).get("lines"), + timeout=10.0, + what="the app's output", + ) + assert lines == ["hello"] + + code, out, _ = daemon.cli("logs", session_id) + assert code == ExitCode.OK and out.strip() == "hello" + + # The offset form is what --follow uses: nothing new yet. + reply = daemon.call("logs", id=session_id, offset=len("hello\n")) + assert reply["lines"] == [] + + +def test_logs_follow_streams_until_the_session_ends(daemon: Daemon): + """--follow polls from a byte offset; the daemon holds nothing open.""" + + session_id = start(daemon, "chatty") + code, out, _ = daemon.cli("logs", session_id, "--follow") + assert code == ExitCode.OK + assert out.splitlines() == ["line 0", "line 1", "line 2"] + assert daemon.state_of(session_id) == "exited" + + +def test_adopt_brings_an_unmanaged_process_under_management(daemon: Daemon): + victim = subprocess.Popen([PY, "-c", SLEEP_600], start_new_session=True) + try: + reply = daemon.call("adopt", pid=victim.pid, app="adopted-sleeper", idle_timeout_s=3600) + assert reply["ok"], reply + record = daemon.session(reply["id"]) + assert record["adopted"] is True + assert record["pid"] == victim.pid + assert record["ready_signal"] == "adopted" + + # Adopting it twice is refused rather than creating a second record. + again = daemon.call("adopt", pid=victim.pid) + assert again["ok"] is False and again["error"] == "already_managed" + + # Killing an adopted session works, and its exit code is honestly null: + # the daemon is not its parent, so no status is recoverable. + kill = daemon.call("kill", id=reply["id"], grace_s=1) + assert kill["ok"], kill + assert victim.wait(timeout=10) == -int(signal.SIGTERM) + wait_until(lambda: not pid_alive(victim.pid), timeout=10.0, what="the adopted process") + final = daemon.session(reply["id"]) + assert final["live"] is False + assert final["exit_code"] is None + assert final["exit_detected_by"] in EXIT_MECHANISMS | {"killpg"} + finally: + if victim.poll() is None: # pragma: no cover + victim.kill() + victim.wait(timeout=5) + + +def test_adopting_a_pid_that_does_not_exist_is_exit_three(daemon: Daemon): + code, _, err = daemon.cli("adopt", "--pid", "4194303") + assert code == ExitCode.NO_SUCH_SESSION + assert "no process" in err + + +@pytest.mark.parametrize("pid", ["1", "0"]) +def test_adopting_init_or_the_whole_group_is_refused(daemon: Daemon, pid: str): + code, _, _ = daemon.cli("adopt", "--pid", pid) + assert code == ExitCode.POLICY + + +def test_gc_reconciles_a_session_whose_process_vanished_without_notice(daemon: Daemon): + session_id = start(daemon, "sleeper") + record = daemon.session(session_id) + assert record["state"] == "ready" + + # Kill it and let the daemon notice via SIGCHLD; gc then prunes nothing but + # must report a consistent picture. + os.kill(record["pid"], signal.SIGKILL) + wait_until(lambda: daemon.state_of(session_id) == "exited", timeout=10.0, what="the exit") + + reply = daemon.call("gc") + assert reply["ok"], reply + assert reply["live"] == 0 + assert reply["tombstones"] >= 1 + assert reply["orphans"] == [] + + +def test_the_session_cap_is_enforced_against_a_looping_caller(daemon: Daemon): + ids = [start(daemon, "sleeper") for _ in range(8)] + reply = daemon.call("start", app="sleeper") + assert reply["ok"] is False + assert reply["error"] == "session_cap_reached" + for session_id in ids: + daemon.call("kill", id=session_id, grace_s=0) + + +def test_a_non_allowlisted_app_is_refused_with_exit_six(daemon: Daemon): + code, _, err = daemon.cli("start", "sh") + assert code == ExitCode.POLICY + assert "not in the allowlist" in err + + +def test_a_retried_start_with_the_same_request_id_does_not_launch_a_second_app(daemon: Daemon): + first = daemon.call("start", app="sleeper", request_id="abc-123") + second = daemon.call("start", app="sleeper", request_id="abc-123") + assert first["ok"] and second["ok"] + assert second["id"] == first["id"] + assert second.get("deduplicated") is True + assert len(daemon.call("list")["sessions"]) == 1 + daemon.call("kill", id=first["id"], grace_s=0) + + +def test_an_unknown_verb_and_a_malformed_frame_are_usage_errors(daemon: Daemon): + assert daemon.call("frobnicate")["error"] == "unknown_op" + + import socket as _socket + + sock = _socket.socket(_socket.AF_UNIX, _socket.SOCK_STREAM) + sock.settimeout(5) + sock.connect(daemon.socket) + sock.sendall(b"{not json at all\n") + reply = json.loads(sock.recv(65536)) + sock.close() + assert reply["ok"] is False and reply["error"] == "bad_request" + + +def test_the_client_reports_exit_five_when_the_daemon_is_not_there(short_tmpdir: Path): + missing = socket_path(short_tmpdir, "absent.sock") + out, err = io.StringIO(), io.StringIO() + with redirect_stdout(out), redirect_stderr(err): + code = hhstream_session.main(["session", "--socket", missing, "list"]) + assert code == ExitCode.DAEMON_UNREACHABLE + assert "cannot reach" in err.getvalue() + + +# =========================================================================== +# restart and adoption +# =========================================================================== + + +def test_sessions_survive_a_daemon_restart_and_are_adopted_back(daemon: Daemon): + session_id = start(daemon, "sleeper") + pid = daemon.session(session_id)["pid"] + + daemon.stop() + assert pid_alive(pid), "stopping the daemon must not kill its sessions" + + daemon.start() + record = daemon.session(session_id) + assert record["state"] == "ready" + assert record["adopted"] is True + assert record["pid"] == pid + + # And the adopted session is still killable, by the same one kill path. + assert daemon.call("kill", id=session_id, grace_s=1)["ok"] + wait_until(lambda: not pid_alive(pid), timeout=10.0, what="the adopted session to die") + + +def test_a_record_whose_pid_was_recycled_is_tombstoned_and_nothing_is_signalled( + daemon: Daemon, short_tmpdir: Path +): + """DESIGN.md §7 #6 — the check that makes adoption safe on a shared machine.""" + + session_id = start(daemon, "sleeper") + pid = daemon.session(session_id)["pid"] + daemon.stop() + + # Rewrite the mirror so the recorded identity no longer matches the live + # process: that is exactly what pid reuse looks like to the daemon. + record_path = daemon.state_dir / "sessions" / f"{session_id}.json" + record = json.loads(record_path.read_text()) + record["pid_starttime"] += 1 + record_path.write_text(json.dumps(record)) + + daemon.start() + adopted = daemon.session(session_id) + assert adopted["state"] == "exited" + assert adopted["last_error"] == "pid_reuse_detected" + assert pid_alive(pid), "a mismatched record must never be signalled" + + os.kill(pid, signal.SIGKILL) # the test owns the cleanup now + + +def test_a_session_whose_deadline_expired_while_the_daemon_was_down_is_reaped_at_once( + daemon: Daemon, +): + session_id = start(daemon, "sleeper", idle_timeout_s=3600) + pid = daemon.session(session_id)["pid"] + daemon.stop() + + # Backdate the last activity past the timeout: the same arithmetic as a + # daemon that was down for four hours. + record_path = daemon.state_dir / "sessions" / f"{session_id}.json" + record = json.loads(record_path.read_text()) + record["last_activity_boottime"] -= 7200.0 + record_path.write_text(json.dumps(record)) + + daemon.start() + wait_until( + lambda: daemon.state_of(session_id) == "reaped", + timeout=10.0, + what="the expired session to be reaped on adopt", + ) + wait_until(lambda: not pid_alive(pid), timeout=10.0, what="the process to be torn down") + + +def test_a_corrupt_record_is_quarantined_and_its_process_left_alone(daemon: Daemon): + session_id = start(daemon, "sleeper") + pid = daemon.session(session_id)["pid"] + daemon.stop() + + (daemon.state_dir / "sessions" / f"{session_id}.json").write_text("{ broken") + daemon.start() + + assert daemon.call("status", id=session_id)["error"] == "no_such_session" + assert pid_alive(pid), "unreadable state must not be grounds for killing" + quarantined = list((daemon.state_dir / "sessions" / "bad").iterdir()) + assert len(quarantined) == 1 + + os.kill(pid, signal.SIGKILL) + + +# =========================================================================== +# helpers +# =========================================================================== + + +def _logged_pid(daemon: Daemon, session_id: str, label: str) -> int | None: + reply = daemon.call("logs", id=session_id) + for line in reply.get("lines") or []: + parts = line.split() + if len(parts) == 2 and parts[0] == label: + return int(parts[1]) + return None + + +def _grandchild_pid(daemon: Daemon, session_id: str) -> int | None: + return _logged_pid(daemon, session_id, "grandchild") + + +def _session_members(sid: int) -> list[int]: + from hhstreamd.procmon import session_members + + return session_members(sid) + + +# =========================================================================== +# BUG-01: the environment a launched application is actually given +# =========================================================================== + + +def test_a_real_session_is_given_the_compositor_environment(short_tmpdir: Path): + """End to end: daemon, allowlist, spawn, and what the process sees after exec. + + Against the pre-fix daemon the app saw its own private XDG_RUNTIME_DIR and no + WAYLAND_DISPLAY at all, which is why every GUI app died within a second. + """ + + comp, listener = compositor_dir(short_tmpdir) + daemon = Daemon(short_tmpdir, "--compositor-runtime-dir", str(comp)) + daemon.start() + try: + session_id = start(daemon, "envdump") + record = daemon.session(session_id) + assert record["state"] == "ready" + + lines = wait_until( + lambda: daemon.call("logs", id=session_id).get("lines"), + timeout=10.0, + what="the app to report its environment", + ) + seen = json.loads(lines[0]) + assert seen == { + "XDG_RUNTIME_DIR": str(comp.resolve()), + "WAYLAND_DISPLAY": "wayland-1", + "XDG_SESSION_TYPE": "wayland", + } + # The private per-session directory is still the one the daemon records + # and is allowed to delete; the app's XDG_RUNTIME_DIR is not it. + assert record["runtime_dir"] != seen["XDG_RUNTIME_DIR"] + assert Path(record["runtime_dir"]).is_dir() + + daemon.call("kill", id=session_id, grace_s=0) + finally: + daemon.stop() + listener.close() + + +def test_the_daemon_refuses_to_start_without_a_usable_compositor_socket(short_tmpdir: Path): + """It must never listen: a daemon that accepts work it cannot do is worse.""" + + empty = short_tmpdir / "empty" + empty.mkdir() + daemon = Daemon(short_tmpdir, "--compositor-runtime-dir", str(empty)) + daemon.process = subprocess.Popen( + [ + PY, "-m", "hhstreamd", + "--socket", daemon.socket, + "--state-dir", str(daemon.state_dir), + "--runtime-dir", str(daemon.runtime_dir), + "--config", str(daemon.config), + "--compositor-runtime-dir", str(empty), + ], + stdout=subprocess.PIPE, + stderr=subprocess.PIPE, + text=True, + cwd=str(REPO_ROOT), + env={**os.environ, "PYTHONPATH": IMPORT_PATH}, + ) + _, err = daemon.process.communicate(timeout=30) + assert daemon.process.returncode == 2, err + assert str(empty.resolve()) in err + assert not socket_is_live(daemon.socket) + assert not Path(daemon.socket).exists() + + +def test_the_daemon_warns_when_it_has_no_compositor(daemon: Daemon): + """The inherited-environment path still works, and says that it may not.""" + + session_id = start(daemon, "envdump") + lines = wait_until( + lambda: daemon.call("logs", id=session_id).get("lines"), + timeout=10.0, + what="the app to report its environment", + ) + seen = json.loads(lines[0]) + # Unchanged behaviour: the app's own private runtime dir, nothing invented. + assert seen["XDG_RUNTIME_DIR"] == daemon.session(session_id)["runtime_dir"] + assert seen["XDG_SESSION_TYPE"] == os.environ.get("XDG_SESSION_TYPE") + assert seen["WAYLAND_DISPLAY"] == os.environ.get("WAYLAND_DISPLAY") + + log = daemon.log.read_text() + assert "may not be able to reach a compositor" in log + assert "--compositor-runtime-dir" in log + + daemon.call("kill", id=session_id, grace_s=0) + + +# =========================================================================== +# BUG-02 — an application behind an `exec`ing wrapper script +# +# The daemon's identity gate used to include a hash of /proc//cmdline. A +# wrapper script replaces that the moment it `exec`s the real binary, so every +# wrapper-launched application was classified as a recycled pid and `kill`, `gc` +# and restart adoption all quietly refused to touch it — while reporting +# success. Every caller of the gate gets its own test here. +# =========================================================================== + + +def start_wrapped(daemon: Daemon) -> tuple[str, int, int, str]: + """Start the wrapped app, let it `exec`, and return it once the argv has moved. + + Returns ``(session_id, pid, grandchild_pid, recorded_cmdline_sha256)``. The + wait is what gives the test its teeth: it does not proceed until ``/proc`` + disagrees with what the daemon recorded, which is the exact condition that + used to disable the kill path. + """ + + session_id = start(daemon, "wrapped") + record = daemon.session(session_id) + pid = record["pid"] + recorded = record["cmdline_sha256"] + + # The daemon recorded the *wrapper's* argv, because the wrapper has not + # reached its `exec` yet. + assert record["argv"] == [str(daemon.wrapper)] + assert _cmdline_hash(pid) == recorded, "the wrapper has exec'd too early to test anything" + + daemon.release_wrapper() + wait_until( + lambda: _cmdline_hash(pid) not in (None, recorded), + timeout=15.0, + what="the wrapper to exec the real binary", + ) + + # Same process, new argv: this is the whole bug in three assertions. + assert pid_alive(pid) + assert os.getsid(pid) == pid, "exec does not change the session id" + assert daemon.session(session_id)["state"] == "ready" + + grandchild = wait_until( + lambda: _grandchild_pid(daemon, session_id), timeout=15.0, what="the grandchild's pid" + ) + return session_id, pid, grandchild, recorded + + +def test_kill_kills_an_application_launched_through_an_execing_wrapper(daemon: Daemon): + """BUG-02's definition of done: the regression test that fails without the fix. + + The leader, its process group and its session-id stragglers all die, and the + caller is told which signal was sent rather than "nothing signalled". + """ + + session_id, pid, grandchild, recorded = start_wrapped(daemon) + assert _cmdline_hash(pid) != recorded, "the argv really did change" + + code, out, err = daemon.cli("kill", session_id, "--grace", "2s") + assert code == ExitCode.OK, err + + # 1. It reports what it actually did. + assert "SIGTERM" in out or "SIGKILL" in out, f"kill must name the signal it sent: {out!r}" + assert "nothing signalled" not in out, "the application was there; saying otherwise is the bug" + assert "SURVIVED" not in out, out + + # 2. It actually killed it: the leader and the grandchild. + wait_until(lambda: not pid_alive(pid), timeout=10.0, what="the session leader to die") + wait_until(lambda: not pid_alive(grandchild), timeout=10.0, what="the grandchild to die") + + record = daemon.session(session_id) + assert record["state"] == "killed" + + # 3. The audit trail says the same thing the caller was told. + completed = [e for e in record["events"] if e.get("event") == "killed_completed"][-1] + assert completed["signalled"] is True + assert completed["signal_sent"] in ("SIGTERM", "SIGKILL") + assert completed["pgid"] == pid + assert completed["survivors"] == [] + assert completed["identity"] == "verified" + # The drift is still observed and reported — it is simply not evidence. + assert completed["cmdline_drifted"] is True + + # 4. Nothing is left sharing the session id. + assert _session_members(record["sid"]) == [] + + +def test_gc_leaves_a_wrapper_launched_session_alone(daemon: Daemon): + """BUG-02 item 4: `gc` used to tombstone a healthy wrapper-launched session. + + A session reconciled away by `gc` is unkillable afterwards — every verb + answers "session exited" — while its application is still on the screen. + """ + + session_id, pid, grandchild, _ = start_wrapped(daemon) + + result = daemon.call("gc") + assert result["ok"], result + assert result["reconciled"] == [], "a wrapper-launched session is not a dead one" + assert result["unresolved"] == [] + assert daemon.state_of(session_id) == "ready" + assert pid_alive(pid) + + # And it is still killable afterwards, which is what `gc` used to cost. + assert daemon.call("kill", id=session_id, grace_s=1)["ok"] + wait_until(lambda: not pid_alive(pid), timeout=10.0, what="the session to die after gc") + wait_until(lambda: not pid_alive(grandchild), timeout=10.0, what="the grandchild to die") + + +def test_a_wrapper_launched_session_is_re_adopted_across_a_daemon_restart(daemon: Daemon): + """BUG-02 item 4: restart adoption used the same gate and failed the same way.""" + + session_id, pid, grandchild, _ = start_wrapped(daemon) + + daemon.stop() + assert pid_alive(pid), "stopping the daemon must not kill its sessions" + daemon.start() + + record = daemon.session(session_id) + assert record["state"] == "ready", "a wrapper-launched session must survive a restart" + assert record["adopted"] is True + assert record["pid"] == pid + assert "pid reuse" not in daemon.log.read_text().lower() + + # Still killable through the one kill path, after adoption. + code, out, err = daemon.cli("kill", session_id, "--grace", "2s") + assert code == ExitCode.OK, err + assert "nothing signalled" not in out + wait_until(lambda: not pid_alive(pid), timeout=10.0, what="the adopted session to die") + wait_until(lambda: not pid_alive(grandchild), timeout=10.0, what="the grandchild to die") + + +def test_the_adopt_verb_handles_a_process_that_execs_after_adoption(daemon: Daemon): + """The fourth caller of the gate: `adopt`, then an `exec`, then `kill`. + + The daemon records the identity of a process it did not spawn, and that + process then replaces its own argv. Nothing about it stopped being the + process that was adopted. + """ + + go = daemon.root / "adopt-go" + script = ( + "import os, sys, time\n" + "while not os.path.exists(sys.argv[1]): time.sleep(0.02)\n" + "os.execv(sys.executable, [sys.executable, '-c', 'import time; time.sleep(600)'])\n" + ) + victim = subprocess.Popen([PY, "-c", script, str(go)], start_new_session=True) + try: + pid = victim.pid + wait_until(lambda: _cmdline_hash(pid) is not None, timeout=10.0, what="the victim to start") + before = _cmdline_hash(pid) + + reply = daemon.call("adopt", pid=pid, app="victim") + assert reply["ok"], reply + session_id = reply["id"] + + go.write_text("go") + wait_until( + lambda: _cmdline_hash(pid) not in (None, before), + timeout=15.0, + what="the adopted process to exec", + ) + + code, out, err = daemon.cli("kill", session_id, "--grace", "2s") + assert code == ExitCode.OK, err + assert "nothing signalled" not in out + assert "SIGTERM" in out or "SIGKILL" in out, out + # This test is the victim's parent, so it must `wait()` rather than look + # for /proc/ to disappear: a killed process it has not reaped is a + # zombie and keeps its pid entry. + assert victim.wait(timeout=10) is not None, "the adopted process must be killed" + finally: + with_suppressed(lambda: victim.kill()) + with_suppressed(lambda: victim.wait(timeout=5)) + + +# --------------------------------------------------------------------------- +# ...and the protection that had to survive the fix +# --------------------------------------------------------------------------- + + +def test_kill_refuses_loudly_and_signals_nothing_when_the_pid_is_not_ours(daemon: Daemon): + """BUG-02 items 2, 3 and 5, against a live daemon. + + A pid cannot be forced to be recycled, so the record is made to describe an + identity that *cannot* match while the process is alive — a `starttime` one + tick earlier than the one the kernel wrote. The daemon must refuse, must + not signal, and must say so instead of reporting a successful kill. + """ + + session_id = start(daemon, "sleeper") + pid = daemon.session(session_id)["pid"] + daemon.stop() + + record_path = daemon.state_dir / "sessions" / f"{session_id}.json" + record = json.loads(record_path.read_text()) + record["pid_starttime"] -= 1 + record["state"] = "ready" # as if the daemon were still watching it + record_path.write_text(json.dumps(record)) + daemon.start() + + try: + # Adoption refuses it first, so `kill` meets a tombstoned session: that + # is itself the refusal, and it is exit 4, not a quiet success. + code, out, err = daemon.cli("kill", session_id) + assert code == ExitCode.BAD_STATE, (code, out, err) + assert pid_alive(pid), "a mismatched record must never be signalled" + + # Loud, and distinguishable from a routine exit: a caller who is told + # "is exited" would reasonably conclude the application is gone. + assert "could not be identified" in err, err + assert "nothing" in err and "signalled" in err, err + assert "pid_reuse_detected" in err, err + assert str(pid) in err, err + assert "gc" in err, "the caller is told how to find what is still running" + + adopted = daemon.session(session_id) + assert adopted["state"] == "exited" + assert adopted["last_error"] == "pid_reuse_detected" + finally: + os.kill(pid, signal.SIGKILL) # the test owns the cleanup now + + +def test_kill_refuses_loudly_when_a_live_sessions_identity_cannot_be_confirmed(daemon: Daemon): + """The same refusal reached through `kill` itself rather than through adoption. + + `gc` is used to confirm the daemon reports the session as unresolved rather + than as a routine exit: "it is gone" and "I cannot tell" are different + answers and the caller is entitled to both. + """ + + session_id = start(daemon, "sleeper") + pid = daemon.session(session_id)["pid"] + + # Rewrite the in-memory record through the mirror-free path: stop, edit, + # restart is what the adoption test does, so instead corrupt the identity in + # a way the live daemon will meet on its next check — an impossible + # starttime. The record is reloaded on restart, and the session is left + # live by marking it so. + daemon.stop() + record_path = daemon.state_dir / "sessions" / f"{session_id}.json" + record = json.loads(record_path.read_text()) + record["pid_starttime"] = 0 # no evidence at all + record_path.write_text(json.dumps(record)) + daemon.start() + + try: + adopted = daemon.session(session_id) + assert adopted["state"] == "exited" + assert adopted["last_error"] == "identity_unknown", ( + "a record with no evidence must be refused, not waved through" + ) + assert pid_alive(pid), "nothing may be signalled on no evidence" + assert "identity_unknown" in daemon.log.read_text() + finally: + os.kill(pid, signal.SIGKILL) + + +def test_the_daemon_reports_a_session_it_cannot_claim_rather_than_hiding_it(daemon: Daemon): + """BUG-02 item 5: never a silent skip. + + The audit log and the daemon log both carry the refusal, with the evidence + that produced it, so an operator can tell the difference between "the app + exited" and "the daemon has lost track of a running application". + """ + + session_id = start(daemon, "sleeper") + pid = daemon.session(session_id)["pid"] + daemon.stop() + + record_path = daemon.state_dir / "sessions" / f"{session_id}.json" + record = json.loads(record_path.read_text()) + record["pid_starttime"] += 7 + record_path.write_text(json.dumps(record)) + daemon.start() + + try: + events = daemon.call("status", id=session_id)["session"]["events"] + failed = [e for e in events if e.get("event") == "adopt_failed"] + assert failed, events + assert failed[-1]["why"] == "pid_reuse_detected" + assert failed[-1]["mismatched"] == ["starttime"], "the evidence is named, not implied" + + log = daemon.log.read_text() + assert "refusing to treat pid" in log + assert str(pid) in log + finally: + os.kill(pid, signal.SIGKILL) + + +def _cmdline_hash(pid: int) -> str | None: + """The live `cmdline_sha256`, read the same way the daemon reads it.""" + + try: + with open(f"/proc/{pid}/cmdline", "rb") as fh: + raw = fh.read() + except OSError: + return None + import hashlib + + return hashlib.sha256(raw).hexdigest() diff --git a/tests/sessions/unit/test_cli_registration.py b/tests/sessions/unit/test_cli_registration.py new file mode 100644 index 0000000..d9df716 --- /dev/null +++ b/tests/sessions/unit/test_cli_registration.py @@ -0,0 +1,306 @@ +"""The integration contract: ``register(subparsers)`` into someone else's CLI. + +The registrant is assumed to know nothing about the daemon beyond the socket +path, so these tests drive the handlers through a host parser they build +themselves and stub out the transport. +""" + +from __future__ import annotations + +import argparse +import io +import json +from contextlib import redirect_stderr, redirect_stdout + +import pytest + +import hhstream_session +from hhstream_session import register +from hhstream_session.client import ClientError +from hhstreamd.protocol import ExitCode + + +@pytest.fixture +def host_cli(): + """A stand-in for the pre-existing ``hhstream`` CLI.""" + + parser = argparse.ArgumentParser(prog="hhstream") + sub = parser.add_subparsers(dest="command") + + existing = sub.add_parser("frame", help="an existing subcommand") + existing.set_defaults(func=lambda args: 0) + + register(sub) + return parser + + +@pytest.fixture +def sent(monkeypatch): + """Capture what the handlers would send, and reply with what the test wants.""" + + class Transport(list): + """The captured requests, plus the canned replies to hand back.""" + + replies = [ + { + "ok": True, + "id": "stub-aaaaaa", + "session": {"id": "stub-aaaaaa", "state": "ready"}, + "sessions": [], + "lines": [], + } + ] + + calls = Transport() + + def fake_call(op, *, socket_path=None, timeout=None, **fields): + # Mirror protocol.request(): unset fields are not put on the wire, so + # the tests below can assert on what is actually sent. + wire = {k: v for k, v in fields.items() if v is not None} + calls.append({"op": op, "socket_path": socket_path, **wire}) + return calls.replies[min(len(calls) - 1, len(calls.replies) - 1)] + + monkeypatch.setattr(hhstream_session, "call", fake_call) + return calls + + +def run(parser: argparse.ArgumentParser, argv: list[str]) -> tuple[int, str, str]: + args = parser.parse_args(argv) + out, err = io.StringIO(), io.StringIO() + with redirect_stdout(out), redirect_stderr(err): + code = hhstream_session.dispatch(args) + return code, out.getvalue(), err.getvalue() + + +# --------------------------------------------------------------------------- +# registration +# --------------------------------------------------------------------------- + + +def test_registration_adds_exactly_one_subcommand_and_leaves_the_host_alone(host_cli): + args = host_cli.parse_args(["frame"]) + assert args.func(args) == 0 # the pre-existing subcommand still works + + args = host_cli.parse_args(["session", "list"]) + assert callable(args.func) + + +def test_the_handler_is_exposed_under_both_the_common_name_and_a_namespaced_one(host_cli): + args = host_cli.parse_args(["session", "status", "foo-aaaaaa"]) + assert args.func is args.hhstream_session_handler + + +def test_every_v1_verb_is_registered(host_cli): + for verb in ["start", "list", "status", "touch", "kill", "gc", "adopt", "logs"]: + argv = ["session", verb] + if verb in ("status", "touch", "kill", "logs"): + argv.append("foo-aaaaaa") + if verb == "start": + argv.append("foot") + if verb == "adopt": + argv += ["--pid", "1234"] + args = host_cli.parse_args(argv) + assert callable(args.func), verb + + +def test_session_with_no_verb_lists(host_cli, sent): + code, _, _ = run(host_cli, ["session"]) + assert code == ExitCode.OK + assert sent[0]["op"] == "list" + + +def test_the_socket_may_be_given_before_or_after_the_verb(host_cli, sent): + run(host_cli, ["session", "--socket", "/a.sock", "list"]) + run(host_cli, ["session", "list", "--socket", "/b.sock"]) + assert sent[0]["socket_path"] == "/a.sock" + assert sent[1]["socket_path"] == "/b.sock" + + +def test_the_socket_falls_back_to_the_environment(host_cli, sent, monkeypatch): + """The registrant's only piece of daemon knowledge.""" + + monkeypatch.setenv("HHSTREAM_SOCKET", "/env.sock") + run(host_cli, ["session", "list"]) + # The handler passes None through; the client resolves the default. + assert sent[0]["socket_path"] is None + from hhstream_session.client import default_socket_path + + assert default_socket_path() == "/env.sock" + + +# --------------------------------------------------------------------------- +# request shapes +# --------------------------------------------------------------------------- + + +def test_start_sends_the_app_and_an_argv_list_never_a_command_string(host_cli, sent): + run(host_cli, ["session", "start", "chromium", "--", "--new-window", "https://example.com"]) + assert sent[0]["op"] == "start" + assert sent[0]["app"] == "chromium" + assert sent[0]["argv"] == ["--new-window", "https://example.com"] + + +def test_this_commands_own_flags_still_parse_after_the_app_name(host_cli, sent): + """The separator divides the two argvs; it does not divide the parsers.""" + + run(host_cli, ["session", "start", "chromium", "--idle-timeout", "5m", "--", "--new-window"]) + assert sent[0]["idle_timeout_s"] == 300.0 + assert sent[0]["argv"] == ["--new-window"] + + +def test_an_application_flag_after_the_separator_is_never_read_as_ours(host_cli, sent): + run(host_cli, ["session", "start", "chromium", "--", "--idle-timeout", "5m"]) + assert "idle_timeout_s" not in sent[0] + assert sent[0]["argv"] == ["--idle-timeout", "5m"] + + +def test_durations_are_parsed_on_the_way_in(host_cli, sent): + run(host_cli, ["session", "start", "foot", "--idle-timeout", "3h"]) + assert sent[0]["idle_timeout_s"] == 10800.0 + run(host_cli, ["session", "kill", "foo-aaaaaa", "--grace", "30s"]) + assert sent[1]["grace_s"] == 30.0 + + +def test_a_bad_duration_is_rejected_by_argparse(host_cli): + with pytest.raises(SystemExit): + host_cli.parse_args(["session", "start", "foot", "--idle-timeout", "soon"]) + + +def test_home_and_ephemeral_home_are_mutually_exclusive(host_cli): + with pytest.raises(SystemExit): + host_cli.parse_args(["session", "start", "foot", "--home", "/x", "--ephemeral-home"]) + + +def test_ephemeral_home_is_opt_in_and_absent_by_default(host_cli, sent): + run(host_cli, ["session", "start", "foot"]) + assert "ephemeral_home" not in sent[0] + run(host_cli, ["session", "start", "foot", "--ephemeral-home"]) + assert sent[1]["ephemeral_home"] is True + + +def test_list_all_is_only_sent_when_asked(host_cli, sent): + run(host_cli, ["session", "list"]) + assert "all" not in sent[0] + run(host_cli, ["session", "list", "--all"]) + assert sent[1]["all"] is True + + +def test_request_ids_are_forwarded_on_mutating_verbs(host_cli, sent): + run(host_cli, ["session", "start", "foot", "--request-id", "abc"]) + assert sent[0]["request_id"] == "abc" + + +# --------------------------------------------------------------------------- +# output and exit codes +# --------------------------------------------------------------------------- + + +def test_start_prints_the_bare_id_on_stdout_and_detail_on_stderr(host_cli, sent): + sent.replies[:] = [ + { + "ok": True, + "id": "foot-k3f9qx", + "session": { + "id": "foot-k3f9qx", + "app": "foot", + "pid": 48812, + "pgid": 48812, + "sid": 48812, + "state": "ready", + "ready_signal": "spawned", + "idle_timeout_s": 10800, + }, + } + ] + code, out, err = run(host_cli, ["session", "start", "foot"]) + assert code == ExitCode.OK + assert out == "foot-k3f9qx\n" # exactly the id, so $(...) works + assert "pid 48812" in err + assert "touch foot-k3f9qx" in err # the keepalive is named where it is needed + + +def test_start_json_puts_one_object_on_stdout_and_nothing_on_stderr(host_cli, sent): + sent.replies[:] = [{"ok": True, "id": "foot-k3f9qx", "session": {"id": "foot-k3f9qx"}}] + code, out, err = run(host_cli, ["session", "start", "--json", "foot"]) + assert code == ExitCode.OK + assert json.loads(out) == {"id": "foot-k3f9qx"} + assert err == "" + + +def test_json_is_available_on_every_read_verb(host_cli, sent): + sent.replies[:] = [{"ok": True, "sessions": []}] + code, out, _ = run(host_cli, ["session", "list", "--json"]) + assert json.loads(out)["ok"] is True + + sent.replies[:] = [{"ok": True, "session": {"id": "a"}, "id": "a"}] + code, out, _ = run(host_cli, ["session", "status", "--json", "a"]) + assert json.loads(out)["session"] == {"id": "a"} + + sent.replies[:] = [{"ok": True, "lines": ["hello"], "offset": 6, "eof": True}] + code, out, _ = run(host_cli, ["session", "logs", "--json", "a"]) + assert json.loads(out)["lines"] == ["hello"] + + +def test_errors_go_to_stderr_with_the_machine_field_in_json_mode(host_cli, sent): + sent.replies[:] = [ + {"ok": False, "error": "not_allowlisted", "reason": "app 'sh' is not in the allowlist"} + ] + code, out, err = run(host_cli, ["session", "start", "--json", "sh"]) + assert code == ExitCode.POLICY + assert out == "" + assert json.loads(err)["error"] == "not_allowlisted" + + +def test_errors_are_human_readable_without_json(host_cli, sent): + sent.replies[:] = [ + {"ok": False, "error": "no_such_session", "reason": "no session 'x'", "hint": "try list"} + ] + code, out, err = run(host_cli, ["session", "status", "x"]) + assert code == ExitCode.NO_SUCH_SESSION + assert "no session 'x'" in err and "try list" in err + + +def test_a_transport_failure_becomes_exit_five_not_a_traceback(host_cli, monkeypatch): + def boom(*args, **kwargs): + raise ClientError("daemon_unreachable", "nothing is listening", hint="start it") + + monkeypatch.setattr(hhstream_session, "call", boom) + code, _, err = run(host_cli, ["session", "list"]) + assert code == ExitCode.DAEMON_UNREACHABLE + assert "nothing is listening" in err and "start it" in err + + +# --------------------------------------------------------------------------- +# the activity contract, as documented to the user +# --------------------------------------------------------------------------- + + +def test_the_help_text_says_touch_is_the_only_mark_of_activity(host_cli): + out = io.StringIO() + with redirect_stdout(out): + with pytest.raises(SystemExit): + host_cli.parse_args(["session", "--help"]) + text = out.getvalue() + assert "touch" in text + assert "ONLY" in text + for verb in ["list", "status", "logs", "gc"]: + assert verb in text + + +@pytest.mark.parametrize("verb", ["list", "status", "logs", "gc"]) +def test_each_read_verbs_help_says_it_does_not_count(host_cli, verb): + out = io.StringIO() + with redirect_stdout(out): + with pytest.raises(SystemExit): + host_cli.parse_args(["session", "--help"]) + line = [l for l in out.getvalue().splitlines() if l.strip().startswith(verb)] + assert line, verb + assert "does NOT count" in " ".join(out.getvalue().split()) + + +def test_touchs_help_calls_itself_the_only_mark_of_activity(host_cli): + out = io.StringIO() + with redirect_stdout(out): + with pytest.raises(SystemExit): + host_cli.parse_args(["session", "touch", "--help"]) + assert "only verb that counts as activity" in " ".join(out.getvalue().split()) diff --git a/tests/sessions/unit/test_compositor.py b/tests/sessions/unit/test_compositor.py new file mode 100644 index 0000000..a18f5bf --- /dev/null +++ b/tests/sessions/unit/test_compositor.py @@ -0,0 +1,414 @@ +"""BUG-01: a launched application must be able to reach the compositor. + +Every test here fails against the pre-fix daemon, which spawned children with +its own inherited environment — on the target machine the *login* session, with +no compositor listening in it — so every GUI application died within a second of +``start`` and the only symptom was ``state exited`` one command later. + +A note on the fixtures: a Wayland socket that is **bound but not listening** +gives ``ECONNREFUSED`` on connect, which is exactly what a socket left behind by +a crashed compositor looks like. A bound *and listening* socket is what a live +one looks like. That is the whole difference between the two helpers below, and +it is why the tests need no compositor. +""" + +from __future__ import annotations + +import json +import logging +import os +import socket +import stat +import sys +from pathlib import Path + +import pytest + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) + +from conftest import SUN_PATH_MAX +from hhstreamd import compositor +from hhstreamd.__main__ import ( + ENV_COMPOSITOR_RUNTIME_DIR, + build_parser, + main, + resolve_compositor, +) +from hhstreamd.compositor import CompositorError, CompositorSession, CompositorTarget, discover +from hhstreamd.launcher import Launcher + + +def _bind(directory: Path, name: str, *, listening: bool) -> socket.socket: + path = directory / name + if len(str(path).encode()) > SUN_PATH_MAX: + pytest.skip(f"socket path too long for AF_UNIX: {path}") + sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) + sock.bind(str(path)) + if listening: + sock.listen(4) + return sock + + +@pytest.fixture +def sockets(): + """Open sockets closed at teardown, so no test leaks a listener.""" + + opened: list[socket.socket] = [] + + def make(directory: Path, name: str, *, listening: bool = True) -> Path: + sock = _bind(directory, name, listening=listening) + opened.append(sock) + return directory / name + + try: + yield make + finally: + for sock in opened: + sock.close() + + +# --------------------------------------------------------------------------- +# discovery: the socket's name is found, never assumed +# --------------------------------------------------------------------------- + + +def test_discovers_wayland_1_not_wayland_0(short_tmpdir, sockets): + """The target machine's compositor is on ``wayland-1``. Nothing may assume ``-0``.""" + + sockets(short_tmpdir, "wayland-1") + session = discover(short_tmpdir) + assert session.wayland_display == "wayland-1" + assert session.runtime_dir == short_tmpdir.resolve() + assert session.socket_path == short_tmpdir.resolve() / "wayland-1" + + +def test_ignores_lock_files_and_other_non_sockets(short_tmpdir, sockets): + """``wayland-1.lock`` is a regular file libwayland writes beside the socket.""" + + (short_tmpdir / "wayland-1.lock").write_text("") + (short_tmpdir / "wayland-0").write_text("not a socket") # a leftover regular file + (short_tmpdir / "wayland-9").mkdir() # and a directory named like one + sockets(short_tmpdir, "wayland-1") + assert discover(short_tmpdir).wayland_display == "wayland-1" + + +def test_candidates_lists_only_sockets(short_tmpdir, sockets): + sockets(short_tmpdir, "wayland-0") + (short_tmpdir / "wayland-0.lock").write_text("") + (short_tmpdir / "bus").write_text("") + assert compositor.candidates(short_tmpdir.resolve()) == ["wayland-0"] + + +def test_a_live_socket_beats_a_crashed_compositors_leftover(short_tmpdir, sockets): + """Both are sockets; only one has anything behind it.""" + + sockets(short_tmpdir, "wayland-1", listening=False) # refuses connections + sockets(short_tmpdir, "wayland-0", listening=True) + assert discover(short_tmpdir).wayland_display == "wayland-0" + + +def test_among_live_sockets_the_later_name_wins(short_tmpdir, sockets): + """A compositor takes the first free name, so the survivor of a restart is later.""" + + sockets(short_tmpdir, "wayland-0") + sockets(short_tmpdir, "wayland-1") + assert discover(short_tmpdir).wayland_display == "wayland-1" + + +def test_non_numeric_suffix_is_usable_but_ranks_last(short_tmpdir, sockets): + sockets(short_tmpdir, "wayland-hyprland") + assert discover(short_tmpdir).wayland_display == "wayland-hyprland" + + +# --------------------------------------------------------------------------- +# fail loudly, early, and correctly +# --------------------------------------------------------------------------- + + +def test_empty_runtime_dir_is_refused_and_named(short_tmpdir): + with pytest.raises(CompositorError) as exc: + discover(short_tmpdir) + message = str(exc.value) + assert str(short_tmpdir.resolve()) in message + assert "no Wayland socket" in message + # It must not be mistaken for the daemon's own --runtime-dir. + assert "--runtime-dir" in message + + +def test_missing_runtime_dir_is_refused_and_named(short_tmpdir): + missing = short_tmpdir / "nope" + with pytest.raises(CompositorError) as exc: + discover(missing) + assert str(missing) in str(exc.value) + + +def test_a_file_in_place_of_the_runtime_dir_is_refused(short_tmpdir): + path = short_tmpdir / "file" + path.write_text("") + with pytest.raises(CompositorError) as exc: + discover(path) + assert str(path) in str(exc.value) + + +def test_only_stale_sockets_is_refused(short_tmpdir, sockets): + """Accepting work here would kill every application that arrived.""" + + sockets(short_tmpdir, "wayland-0", listening=False) + sockets(short_tmpdir, "wayland-1", listening=False) + with pytest.raises(CompositorError) as exc: + discover(short_tmpdir) + message = str(exc.value) + assert str(short_tmpdir.resolve()) in message + assert "no usable Wayland socket" in message + assert "wayland-0" in message and "wayland-1" in message + + +def test_an_unconnectable_but_not_refused_socket_is_used_with_a_warning( + short_tmpdir, sockets, caplog, monkeypatch +): + """An ambiguous probe (EACCES, a timeout) is a warning, not an outage.""" + + sockets(short_tmpdir, "wayland-1", listening=False) + + def refuse_with_eacces(path): + return compositor._Candidate(Path(path).name, False, False, "PermissionError: denied") + + monkeypatch.setattr(compositor, "_probe", refuse_with_eacces) + with caplog.at_level(logging.WARNING, logger="hhstreamd.compositor"): + assert discover(short_tmpdir).wayland_display == "wayland-1" + assert "did not accept a probe connection" in caplog.text + + +# --------------------------------------------------------------------------- +# the environment a child is given +# --------------------------------------------------------------------------- + + +def test_session_env_is_the_three_variables(): + session = CompositorSession(runtime_dir=Path("/run/user/1001"), wayland_display="wayland-1") + assert session.env() == { + "XDG_RUNTIME_DIR": "/run/user/1001", + "WAYLAND_DISPLAY": "wayland-1", + "XDG_SESSION_TYPE": "wayland", + } + + +def test_child_env_is_built_from_the_compositor_runtime_dir(short_tmpdir, sockets, tmp_path): + sockets(short_tmpdir, "wayland-1") + launcher = Launcher( + tmp_path / "runtime", + tmp_path / "state", + compositor=CompositorTarget.from_runtime_dir(short_tmpdir), + ) + env = launcher.build_env("chromium-uynn6w", tmp_path / "home") + + assert env["XDG_RUNTIME_DIR"] == str(short_tmpdir.resolve()) + assert env["WAYLAND_DISPLAY"] == "wayland-1" + assert env["XDG_SESSION_TYPE"] == "wayland" + # Not the daemon's own runtime dir, and not the session's private one. + assert env["XDG_RUNTIME_DIR"] != str(launcher.session_runtime_dir("chromium-uynn6w")) + # The private directory is still created: the daemon owns and cleans it up. + assert launcher.session_runtime_dir("chromium-uynn6w").is_dir() + + +def test_child_env_keeps_the_inherited_environment_underneath( + short_tmpdir, sockets, tmp_path, monkeypatch +): + sockets(short_tmpdir, "wayland-1") + monkeypatch.setenv("PATH", "/usr/bin") + monkeypatch.setenv("DBUS_SESSION_BUS_ADDRESS", "unix:path=/run/user/1000/bus") + launcher = Launcher( + tmp_path / "runtime", + tmp_path / "state", + compositor=CompositorTarget.from_runtime_dir(short_tmpdir), + ) + env = launcher.build_env("s", tmp_path / "home") + assert env["PATH"] == "/usr/bin" + assert env["DBUS_SESSION_BUS_ADDRESS"] == "unix:path=/run/user/1000/bus" + assert env["HOME"] == str(tmp_path / "home") + assert env["HHSTREAM_SESSION_ID"] == "s" + + +def test_the_daemons_own_configuration_never_leaks_to_a_child(tmp_path, monkeypatch): + monkeypatch.setenv(ENV_COMPOSITOR_RUNTIME_DIR, "/run/user/1001") + env = Launcher(tmp_path / "runtime", tmp_path / "state").build_env("s", tmp_path) + assert ENV_COMPOSITOR_RUNTIME_DIR not in env + + +def test_without_a_compositor_the_inherited_environment_still_stands(tmp_path, monkeypatch): + """Point 4 of the brief: the old behaviour is kept, not broken.""" + + monkeypatch.setenv("WAYLAND_DISPLAY", "wayland-7") + monkeypatch.delenv("XDG_SESSION_TYPE", raising=False) + launcher = Launcher(tmp_path / "runtime", tmp_path / "state") + env = launcher.build_env("s", tmp_path / "home") + assert env["XDG_RUNTIME_DIR"] == str(launcher.session_runtime_dir("s")) + assert env["WAYLAND_DISPLAY"] == "wayland-7" # passed through, not invented + assert "XDG_SESSION_TYPE" not in env + + +def test_the_recorded_runtime_dir_stays_the_one_the_daemon_may_delete( + short_tmpdir, sockets, tmp_path +): + """``discard_runtime_dir`` must never be pointed at another user's directory.""" + + sockets(short_tmpdir, "wayland-1") + launcher = Launcher( + tmp_path / "runtime", + tmp_path / "state", + compositor=CompositorTarget.from_runtime_dir(short_tmpdir), + ) + spawned = launcher.spawn("s", [sys.executable, "-c", "pass"]) + spawned.process.wait(timeout=10) + assert spawned.runtime_dir == str(launcher.session_runtime_dir("s")) + assert spawned.runtime_dir != str(short_tmpdir.resolve()) + + +def test_a_real_child_sees_the_compositor_environment(short_tmpdir, sockets, tmp_path): + """The end of the chain: what the process actually gets after exec.""" + + sockets(short_tmpdir, "wayland-1") + launcher = Launcher( + tmp_path / "runtime", + tmp_path / "state", + compositor=CompositorTarget.from_runtime_dir(short_tmpdir), + ) + code = ( + "import json, os, sys; " + "sys.stdout.write(json.dumps({k: os.environ.get(k) for k in " + "('XDG_RUNTIME_DIR', 'WAYLAND_DISPLAY', 'XDG_SESSION_TYPE')}))" + ) + spawned = launcher.spawn("s", [sys.executable, "-c", code]) + assert spawned.process.wait(timeout=30) == 0 + seen = json.loads(Path(spawned.log_path).read_text()) + assert seen == { + "XDG_RUNTIME_DIR": str(short_tmpdir.resolve()), + "WAYLAND_DISPLAY": "wayland-1", + "XDG_SESSION_TYPE": "wayland", + } + # And the socket it was pointed at is really there. + assert stat.S_ISSOCK(os.stat(short_tmpdir / seen["WAYLAND_DISPLAY"]).st_mode) + + +# --------------------------------------------------------------------------- +# re-resolution: the compositor can restart under a running daemon +# --------------------------------------------------------------------------- + + +def test_target_follows_a_compositor_that_came_back_on_another_socket(short_tmpdir, sockets): + first = sockets(short_tmpdir, "wayland-0") + target = CompositorTarget.from_runtime_dir(short_tmpdir) + assert target.session.wayland_display == "wayland-0" + + sockets(short_tmpdir, "wayland-1") # restarted compositor, new name + first.unlink() # the old socket file went with the old compositor + + assert target.env()["WAYLAND_DISPLAY"] == "wayland-1" + assert target.session.wayland_display == "wayland-1" + + +def test_target_keeps_the_last_known_good_when_re_resolution_fails(short_tmpdir, sockets, caplog): + sockets(short_tmpdir, "wayland-1") + target = CompositorTarget.from_runtime_dir(short_tmpdir) + (short_tmpdir / "wayland-1").unlink() # compositor gone, mid-flight + + with caplog.at_level(logging.WARNING, logger="hhstreamd.compositor"): + env = target.env() + assert env["WAYLAND_DISPLAY"] == "wayland-1" + assert "re-resolving the compositor socket failed" in caplog.text + + +# --------------------------------------------------------------------------- +# the daemon's startup contract +# --------------------------------------------------------------------------- + + +def _args(argv: list[str]): + return build_parser().parse_args(argv) + + +def test_the_option_and_the_environment_variable_are_both_accepted(monkeypatch): + monkeypatch.setenv(ENV_COMPOSITOR_RUNTIME_DIR, "/from/env") + assert _args([]).compositor_runtime_dir == "/from/env" + assert _args(["--compositor-runtime-dir", "/from/flag"]).compositor_runtime_dir == "/from/flag" + + +def test_no_option_means_no_compositor_and_a_startup_warning(monkeypatch, caplog): + monkeypatch.delenv(ENV_COMPOSITOR_RUNTIME_DIR, raising=False) + with caplog.at_level(logging.WARNING, logger="hhstreamd"): + assert resolve_compositor(_args([])) is None + assert "may not be able to reach a compositor" in caplog.text + assert "--compositor-runtime-dir" in caplog.text + + +def test_resolve_compositor_returns_a_target_when_the_socket_is_there(short_tmpdir, sockets): + sockets(short_tmpdir, "wayland-1") + target = resolve_compositor(_args(["--compositor-runtime-dir", str(short_tmpdir)])) + assert target is not None + assert target.session.wayland_display == "wayland-1" + + +def test_daemon_refuses_to_start_on_an_unusable_compositor_dir(short_tmpdir, capsys, monkeypatch): + """Exit before listening, with the directory in the message.""" + + monkeypatch.delenv(ENV_COMPOSITOR_RUNTIME_DIR, raising=False) + code = main( + [ + "--check", + "--socket", + str(short_tmpdir / "c.sock"), + "--state-dir", + str(short_tmpdir / "state"), + "--runtime-dir", + str(short_tmpdir / "runtime"), + "--config", + str(short_tmpdir / "missing.toml"), + "--compositor-runtime-dir", + str(short_tmpdir), + ] + ) + assert code == 2 + err = capsys.readouterr().err + assert str(short_tmpdir.resolve()) in err + assert "no Wayland socket" in err + + +def test_check_reports_the_discovered_compositor(short_tmpdir, sockets, capsys, monkeypatch): + monkeypatch.delenv(ENV_COMPOSITOR_RUNTIME_DIR, raising=False) + runtime = short_tmpdir / "comp" + runtime.mkdir() + sockets(runtime, "wayland-1") + code = main( + [ + "--check", + "--state-dir", + str(short_tmpdir / "state"), + "--runtime-dir", + str(short_tmpdir / "runtime"), + "--config", + str(short_tmpdir / "missing.toml"), + "--compositor-runtime-dir", + str(runtime), + ] + ) + assert code == 0 + out = capsys.readouterr().out + assert f"compositor: {runtime.resolve()}" in out + assert "WAYLAND_DISPLAY=wayland-1" in out + + +def test_check_says_so_when_no_compositor_is_configured(short_tmpdir, capsys, monkeypatch): + monkeypatch.delenv(ENV_COMPOSITOR_RUNTIME_DIR, raising=False) + code = main( + [ + "--check", + "--state-dir", + str(short_tmpdir / "state"), + "--runtime-dir", + str(short_tmpdir / "runtime"), + "--config", + str(short_tmpdir / "missing.toml"), + ] + ) + assert code == 0 + assert "compositor: none configured" in capsys.readouterr().out diff --git a/tests/sessions/unit/test_exit_codes.py b/tests/sessions/unit/test_exit_codes.py new file mode 100644 index 0000000..13fd676 --- /dev/null +++ b/tests/sessions/unit/test_exit_codes.py @@ -0,0 +1,104 @@ +"""The exit-code table of DESIGN.md §1.6. + +These are frozen: agents branch on them. The test states the table in full so +a change to it is a change to this file. +""" + +from __future__ import annotations + +import pytest + +from hhstream_session.client import ClientError, reply_exit_code +from hhstreamd.protocol import EXIT_CODE_FOR_ERROR, ExitCode, exit_code_for + + +def test_the_frozen_numbers(): + assert ExitCode.OK == 0 + assert ExitCode.USAGE == 2 + assert ExitCode.NO_SUCH_SESSION == 3 + assert ExitCode.BAD_STATE == 4 + assert ExitCode.DAEMON_UNREACHABLE == 5 + assert ExitCode.POLICY == 6 + assert ExitCode.TIMEOUT == 7 + assert ExitCode.BUSY == 8 + # 1 is deliberately absent: it is the shell's "something went wrong", and + # reusing it would make an unhandled crash indistinguishable from a + # documented outcome. + assert 1 not in set(ExitCode) + + +@pytest.mark.parametrize( + "error,code", + [ + # 2 — usage + ("bad_request", 2), + ("unknown_op", 2), + ("unsupported_version", 2), + ("message_too_large", 2), + ("invalid_argument", 2), + # 3 — no such session + ("no_such_session", 3), + ("no_such_process", 3), + # 4 — not in a usable state + ("session_exited", 4), + ("session_killed", 4), + ("session_reaped", 4), + ("session_starting", 4), + ("compositor_lost", 4), + ("bad_state", 4), + ("pid_reuse_detected", 4), + ("identity_unknown", 4), + # 5 — daemon unreachable + ("daemon_unreachable", 5), + # 6 — refused by policy + ("not_allowlisted", 6), + ("argument_refused", 6), + ("session_cap_reached", 6), + ("refused", 6), + # 7 — timed out + ("timeout", 7), + ("readiness_timeout", 7), + # 8 — busy + ("busy", 8), + ("already_managed", 8), + ], +) +def test_every_error_name_maps_to_its_documented_code(error, code): + assert exit_code_for(error) == code + + +def test_the_table_has_no_entries_this_test_does_not_know_about(): + """Adding an error name must mean adding it to the test above.""" + + documented = { + "bad_request", "unknown_op", "unsupported_version", "message_too_large", + "invalid_argument", "no_such_session", "no_such_process", "session_exited", + "session_killed", "session_reaped", "session_starting", "compositor_lost", + "bad_state", "pid_reuse_detected", "identity_unknown", + "daemon_unreachable", "not_allowlisted", + "argument_refused", "session_cap_reached", "refused", "timeout", + "readiness_timeout", "busy", "already_managed", + } + assert set(EXIT_CODE_FOR_ERROR) == documented + + +def test_success_is_zero(): + assert exit_code_for(None) == 0 + assert exit_code_for("") == 0 + + +def test_an_unknown_error_degrades_to_not_usable_rather_than_to_success(): + """A caller that does not recognise the failure must still not see a 0.""" + + assert exit_code_for("something_invented_next_year") == ExitCode.BAD_STATE + + +def test_reply_exit_code_reads_a_decoded_reply(): + assert reply_exit_code({"ok": True, "id": "a"}) == 0 + assert reply_exit_code({"ok": False, "error": "no_such_session"}) == 3 + assert reply_exit_code({"ok": False}) == ExitCode.BAD_STATE + + +def test_client_errors_carry_their_own_code(): + assert ClientError("daemon_unreachable", "no socket").exit_code == 5 + assert ClientError("timeout", "no reply").exit_code == 7 diff --git a/tests/sessions/unit/test_policy.py b/tests/sessions/unit/test_policy.py new file mode 100644 index 0000000..96259a1 --- /dev/null +++ b/tests/sessions/unit/test_policy.py @@ -0,0 +1,240 @@ +"""Allowlist and input-bound tests (DESIGN.md §8 item 1). + +The allowlist is the main control: without it, `start /bin/sh` makes every +other control decorative. +""" + +from __future__ import annotations + +import tomllib +from pathlib import Path + +import pytest + +from hhstreamd.policy import ( + MAX_ARG_BYTES, + MAX_ARGV_BYTES, + MAX_ARGV_ITEMS, + Policy, + PolicyError, + check_app_name, + check_argv, + load_policy, + policy_from_dict, +) + +CONFIG = """ +[defaults] +max_sessions = 2 +idle_timeout_s = 10800 +max_idle_timeout_s = 86400 + +[apps.chromium] +exec = "/run/current-system/sw/bin/chromium" +args_allow = ["--new-window", "--app=*", "--user-data-dir=*"] + +[apps.foot] +exec = "/usr/bin/foot" + +[apps.blender] +exec = "/usr/bin/blender" +args = ["--background"] +args_allow = ["*.blend"] +idle_timeout_s = 60 +""" + + +@pytest.fixture +def policy() -> Policy: + return policy_from_dict(tomllib.loads(CONFIG), source="test-config") + + +# --------------------------------------------------------------------------- +# the allowlist itself +# --------------------------------------------------------------------------- + + +def test_an_allowlisted_app_resolves_to_its_absolute_path(policy: Policy): + rule, argv = policy.resolve("chromium", ["--new-window"]) + assert rule.name == "chromium" + assert argv == ["/run/current-system/sw/bin/chromium", "--new-window"] + + +def test_an_app_that_is_not_in_the_allowlist_is_refused_with_a_policy_error(policy: Policy): + with pytest.raises(PolicyError) as exc: + policy.resolve("sh", []) + assert exc.value.error == "not_allowlisted" + assert "sh" in exc.value.reason + assert "blender, chromium, foot" in exc.value.hint + + +@pytest.mark.parametrize("name", ["/bin/sh", "./sh", "../../bin/sh", "sh;rm -rf /", "a b"]) +def test_a_path_or_a_shell_fragment_is_not_even_a_valid_app_name(policy: Policy, name: str): + """The caller names an app; it never names a binary.""" + + with pytest.raises(PolicyError) as exc: + policy.resolve(name, []) + assert exc.value.error == "invalid_argument" + + +def test_an_empty_allowlist_refuses_everything_and_says_so(): + empty = Policy(source="/etc/hhstream/config.toml") + with pytest.raises(PolicyError) as exc: + empty.resolve("foot", []) + assert exc.value.error == "not_allowlisted" + assert "the allowlist is empty" in exc.value.hint + + +def test_fixed_args_from_the_config_precede_the_callers(policy: Policy): + _, argv = policy.resolve("blender", ["scene.blend"]) + assert argv == ["/usr/bin/blender", "--background", "scene.blend"] + + +def test_an_app_rule_may_set_its_own_default_idle_timeout(policy: Policy): + assert policy.apps["blender"].idle_timeout_s == 60 + assert policy.apps["foot"].idle_timeout_s is None + + +# --------------------------------------------------------------------------- +# argument allowlisting +# --------------------------------------------------------------------------- + + +def test_arguments_are_matched_against_patterns(policy: Policy): + policy.resolve("chromium", ["--app=https://example.com", "--user-data-dir=/tmp/x"]) + + +def test_an_argument_that_matches_no_pattern_is_refused(policy: Policy): + with pytest.raises(PolicyError) as exc: + policy.resolve("chromium", ["--no-sandbox"]) + assert exc.value.error == "argument_refused" + assert "--no-sandbox" in exc.value.reason + + +def test_an_app_with_no_args_allow_accepts_no_caller_arguments(policy: Policy): + policy.resolve("foot", []) # fine + with pytest.raises(PolicyError) as exc: + policy.resolve("foot", ["-e", "sh"]) + assert exc.value.error == "argument_refused" + + +# --------------------------------------------------------------------------- +# config validation +# --------------------------------------------------------------------------- + + +def test_a_relative_exec_path_is_rejected_at_load_time(): + with pytest.raises(PolicyError) as exc: + policy_from_dict({"apps": {"foot": {"exec": "foot"}}}) + assert "absolute path" in exc.value.reason + + +def test_an_app_with_no_exec_is_rejected(): + with pytest.raises(PolicyError): + policy_from_dict({"apps": {"foot": {}}}) + + +@pytest.mark.parametrize("field", ["args", "args_allow"]) +def test_args_fields_must_be_lists_of_strings(field): + with pytest.raises(PolicyError): + policy_from_dict({"apps": {"foot": {"exec": "/usr/bin/foot", field: "oops"}}}) + + +def test_a_missing_config_file_yields_an_empty_allowlist_rather_than_a_crash(tmp_path: Path): + """A misconfigured deployment must not look like a daemon crash.""" + + policy = load_policy(tmp_path / "absent.toml") + assert policy.apps == {} + assert policy.source.endswith("absent.toml") + + +def test_a_config_file_is_read_from_disk(tmp_path: Path): + path = tmp_path / "config.toml" + path.write_text(CONFIG) + policy = load_policy(path) + assert set(policy.apps) == {"chromium", "foot", "blender"} + assert policy.max_sessions == 2 + + +# --------------------------------------------------------------------------- +# input bounds on `start` +# --------------------------------------------------------------------------- + + +def test_argv_must_be_a_list_not_a_string(): + """A string here would be the beginning of a shell command line.""" + + with pytest.raises(PolicyError) as exc: + check_argv("--new-window https://example.com") + assert exc.value.error == "invalid_argument" + + +def test_argv_items_must_be_strings(): + with pytest.raises(PolicyError): + check_argv(["--a", 7]) + + +def test_argv_length_is_bounded(): + check_argv(["x"] * MAX_ARGV_ITEMS) + with pytest.raises(PolicyError) as exc: + check_argv(["x"] * (MAX_ARGV_ITEMS + 1)) + assert "more than" in exc.value.reason + + +def test_a_single_argument_is_bounded(): + with pytest.raises(PolicyError): + check_argv(["x" * (MAX_ARG_BYTES + 1)]) + + +def test_the_total_argv_size_is_bounded(): + item = "x" * (MAX_ARG_BYTES - 1) + count = MAX_ARGV_BYTES // len(item) + 2 + with pytest.raises(PolicyError) as exc: + check_argv([item] * count) + assert "in total" in exc.value.reason + + +def test_a_nul_byte_in_an_argument_is_refused(): + """execve would truncate at the NUL; refusing is the honest answer.""" + + with pytest.raises(PolicyError) as exc: + check_argv(["--url=http://x\0--no-sandbox"]) + assert "NUL" in exc.value.reason + + +def test_app_names_are_bounded_and_charset_checked(): + check_app_name("chromium") + check_app_name("my-app_2.0+x") + with pytest.raises(PolicyError): + check_app_name("") + with pytest.raises(PolicyError): + check_app_name("a" * 65) + with pytest.raises(PolicyError): + check_app_name(None) + + +def test_an_idle_timeout_above_the_configured_maximum_is_refused(policy: Policy): + assert policy.check_idle_timeout(None) == 10800.0 + assert policy.check_idle_timeout(60) == 60.0 + with pytest.raises(PolicyError) as exc: + policy.check_idle_timeout(86401) + assert exc.value.error == "refused" + + +def test_a_negative_or_non_numeric_idle_timeout_is_refused(policy: Policy): + with pytest.raises(PolicyError): + policy.check_idle_timeout(-1) + with pytest.raises(PolicyError): + policy.check_idle_timeout("soon") + + +def test_a_zero_idle_timeout_is_accepted_and_means_never_expire(policy: Policy): + assert policy.check_idle_timeout(0) == 0.0 + + +def test_the_session_cap_is_enforced(policy: Policy): + policy.check_capacity(1) + with pytest.raises(PolicyError) as exc: + policy.check_capacity(2) + assert exc.value.error == "session_cap_reached" + assert "max_sessions is 2" in exc.value.reason diff --git a/tests/sessions/unit/test_procmon.py b/tests/sessions/unit/test_procmon.py new file mode 100644 index 0000000..c5ab821 --- /dev/null +++ b/tests/sessions/unit/test_procmon.py @@ -0,0 +1,383 @@ +"""`/proc` parsing and the safety guards on signalling. + +The identity check is what makes it safe to signal a pid the daemon did not +spawn, so it gets tests against a synthetic `/proc` as well as the real one. + +BUG-02 removed one of its three conditions, so these tests have two jobs rather +than one: they pin down that an `exec`ing wrapper no longer trips the gate, and +they pin down — in the same file, from the same synthetic `/proc` — that a +genuinely recycled pid is still refused. Dropping a condition without the +second half would leave a check that cannot fail, which is worse than the bug. +""" + +from __future__ import annotations + +import hashlib +import os +import signal +import subprocess +import sys +import time +from pathlib import Path + +import pytest + +from hhstreamd import procmon + + +def fake_proc(root: Path, pid: int, *, comm: str, sid: int, pgid: int, starttime: int, cmdline: bytes): + """Write a plausible `/proc/` for the parser to read.""" + + directory = root / str(pid) + directory.mkdir(parents=True, exist_ok=True) + fields = ["0"] * 50 + fields[0] = "S" # field 3: state + fields[1] = "1" # field 4: ppid + fields[2] = str(pgid) # field 5 + fields[3] = str(sid) # field 6 + fields[19] = str(starttime) # field 22 + (directory / "stat").write_text(f"{pid} ({comm}) " + " ".join(fields) + "\n") + (directory / "cmdline").write_bytes(cmdline) + return directory + + +def test_stat_parsing_survives_a_comm_containing_spaces_and_parentheses(tmp_path: Path): + """`comm` is attacker-adjacent: a process can rename itself to ") 1 2 3 (". + + Splitting the whole line on whitespace would read the wrong fields and the + daemon would then signal the wrong process group. + """ + + fake_proc( + tmp_path, + 42, + comm="evil (name) with ) spaces", + sid=7, + pgid=9, + starttime=12345, + cmdline=b"/bin/x\0", + ) + stat = procmon.read_stat(42, proc=str(tmp_path)) + assert stat.comm == "evil (name) with ) spaces" + assert stat.pgid == 9 + assert stat.sid == 7 + assert stat.starttime == 12345 + + +def test_a_missing_process_reads_as_none(tmp_path: Path): + assert procmon.read_stat(999, proc=str(tmp_path)) is None + assert procmon.read_cmdline(999, proc=str(tmp_path)) is None + assert procmon.identity(999, proc=str(tmp_path)) is None + assert procmon.is_alive(999, proc=str(tmp_path)) is False + + +def test_a_truncated_stat_line_is_rejected_rather_than_misparsed(tmp_path: Path): + directory = tmp_path / "7" + directory.mkdir() + (directory / "stat").write_text("7 (short) S 1 2\n") + assert procmon.read_stat(7, proc=str(tmp_path)) is None + + +def test_cmdline_is_split_on_nul_without_a_trailing_empty_item(tmp_path: Path): + fake_proc(tmp_path, 8, comm="x", sid=8, pgid=8, starttime=1, cmdline=b"/bin/x\0-a\0-b\0") + assert procmon.cmdline_argv(8, proc=str(tmp_path)) == ["/bin/x", "-a", "-b"] + + +def test_the_cmdline_hash_is_of_the_raw_bytes(tmp_path: Path): + raw = b"/bin/x\0-a\0" + fake_proc(tmp_path, 9, comm="x", sid=9, pgid=9, starttime=1, cmdline=raw) + assert procmon.cmdline_hash(9, proc=str(tmp_path)) == hashlib.sha256(raw).hexdigest() + + +# --------------------------------------------------------------------------- +# the identity check (BUG-02) +# --------------------------------------------------------------------------- + + +def leader(root: Path, pid: int, *, starttime: int, cmdline: bytes, comm: str = "x"): + """A session leader, as `start_new_session=True` produces: sid == pgid == pid.""" + + return fake_proc( + root, pid, comm=comm, sid=pid, pgid=pid, starttime=starttime, cmdline=cmdline + ) + + +def test_the_gate_is_starttime_corroborated_by_a_leaders_sid_and_pgid(tmp_path: Path): + """What is checked is stated explicitly, so weakening it cannot be silent.""" + + raw = b"/bin/x\0" + leader(tmp_path, 10, starttime=999, cmdline=raw) + verdict = procmon.check( + 10, + proc=str(tmp_path), + starttime=999, + sid=10, + pgid=10, + cmdline_sha256=hashlib.sha256(raw).hexdigest(), + ) + assert verdict.ok is True + assert verdict.reason is None + assert verdict.checked == ("starttime", "sid", "pgid") + assert verdict.mismatched == () + assert verdict.cmdline_drifted is False + + +@pytest.mark.parametrize( + "live,mismatched", + [ + # A different process was created on this pid: it cannot share the + # creation instant of the one that is recorded. + (dict(sid=10, pgid=10, starttime=1000), "starttime"), + # ...and if the clocks did collide, it is not in our session either. + (dict(sid=77, pgid=77, starttime=999), "sid"), + (dict(sid=10, pgid=77, starttime=999), "pgid"), + ], +) +def test_a_recycled_pid_is_still_refused(tmp_path: Path, live: dict, mismatched: str): + """The protection BUG-02 had to keep: a pid that is not ours is not signalled. + + The brief's construction: a pid cannot be forced to be recycled on demand, + so the record is held fixed — a session leader on pid 10, created at tick + 999 — and `/proc` is made to describe a process that **cannot** be that one + while it is alive. Each surviving condition is shown to refuse on its own. + """ + + fake_proc(tmp_path, 10, comm="stranger", cmdline=b"/bin/other\0", **live) + verdict = procmon.check(10, proc=str(tmp_path), starttime=999, sid=10, pgid=10) + assert verdict.ok is False, "a pid that is not ours must never be signalled" + assert verdict.reason == "pid_reuse_detected" + assert verdict.unresolved is True + assert mismatched in verdict.mismatched + + +def test_the_gate_cannot_be_satisfied_by_the_cmdline_alone(tmp_path: Path): + """A recycled pid is refused *even when the command line matches exactly*. + + The converse of dropping the condition: it was never what made the check + safe, and removing it takes nothing away. + """ + + raw = b"/bin/x\0" + fake_proc(tmp_path, 10, comm="x", sid=10, pgid=10, starttime=1000, cmdline=raw) + verdict = procmon.check( + 10, proc=str(tmp_path), starttime=999, sid=10, pgid=10, + cmdline_sha256=hashlib.sha256(raw).hexdigest(), + ) + assert verdict.ok is False + assert verdict.reason == "pid_reuse_detected" + assert verdict.cmdline_drifted is False, "identical argv, and still refused" + + +def test_a_wrapper_script_exec_does_not_look_like_pid_reuse(tmp_path: Path): + """BUG-02 itself, at the level of the check. + + The recorded argv is the wrapper's, the live argv is the real binary's, and + everything the kernel owns is unchanged. This is a healthy process. + """ + + launched = b"/run/current-system/sw/bin/chromium\0--ozone-platform=wayland\0" + live = b"/nix/store/abc-chromium-unwrapped/libexec/chromium/chromium\0" + leader(tmp_path, 2661433, starttime=15780209, cmdline=live, comm="chromium") + + verdict = procmon.check( + 2661433, + proc=str(tmp_path), + starttime=15780209, + sid=2661433, + pgid=2661433, + cmdline_sha256=hashlib.sha256(launched).hexdigest(), + ) + assert verdict.ok is True, "an exec'ing wrapper is not evidence of pid reuse" + assert verdict.cmdline_drifted is True, "the drift is still reported, just not acted on" + + +def test_the_cmdline_can_never_refuse_on_its_own(tmp_path: Path): + """The condition that was dropped is dropped: no value of it refuses.""" + + raw = b"/bin/real\0" + leader(tmp_path, 10, starttime=999, cmdline=raw) + for recorded_hash in ["0" * 64, hashlib.sha256(b"/bin/wrapper\0").hexdigest(), ""]: + verdict = procmon.check( + 10, proc=str(tmp_path), starttime=999, sid=10, pgid=10, + cmdline_sha256=recorded_hash, + ) + assert verdict.ok is True + assert "cmdline_sha256" not in verdict.checked + + +def test_sid_and_pgid_are_only_checked_for_a_leader(tmp_path: Path): + """An adopted non-leader may lawfully `setsid()`; that is not pid reuse. + + `setsid()` and `setpgid()` both fail with EPERM for a session/group leader, + so the recorded values are immutable exactly when they equal the recorded + pid — and are checked exactly then. + """ + + # Recorded as a member of someone else's session, then it calls setsid(). + fake_proc(tmp_path, 10, comm="x", sid=5, pgid=5, starttime=999, cmdline=b"/bin/x\0") + verdict = procmon.check(10, proc=str(tmp_path), starttime=999, sid=5, pgid=5) + assert verdict.ok is True + assert verdict.checked == ("starttime",), "a non-leader's sid/pgid are not evidence" + + +def test_a_record_with_no_starttime_is_refused_rather_than_waved_through(tmp_path: Path): + """BUG-02 item 5: no evidence means refuse loudly, never "probably fine".""" + + leader(tmp_path, 10, starttime=999, cmdline=b"/bin/x\0") + for missing in (None, 0, -1): + verdict = procmon.check(10, proc=str(tmp_path), starttime=missing, sid=10, pgid=10) + assert verdict.ok is False + assert verdict.reason == "identity_unknown" + assert verdict.unresolved is True + + +def test_a_vanished_process_reports_gone_not_pid_reuse(tmp_path: Path): + """The difference matters: one is routine, the other is alarming.""" + + verdict = procmon.check(404, proc=str(tmp_path), starttime=1, sid=404, pgid=404) + assert (verdict.ok, verdict.reason) == (False, "gone") + assert verdict.unresolved is False, "an exit is not something to shout about" + + +def test_a_zombie_is_gone_not_alive(tmp_path: Path): + """A zombie holds its pid but can never be signalled into doing anything.""" + + directory = leader(tmp_path, 10, starttime=999, cmdline=b"/bin/x\0") + stat = (directory / "stat").read_text().replace(") S ", ") Z ", 1) + (directory / "stat").write_text(stat) + verdict = procmon.check(10, proc=str(tmp_path), starttime=999, sid=10, pgid=10) + assert (verdict.ok, verdict.reason) == (False, "gone") + + +def test_verify_still_answers_ok_and_reason_for_callers_that_want_no_detail(tmp_path: Path): + leader(tmp_path, 10, starttime=999, cmdline=b"/bin/x\0") + assert procmon.verify(10, proc=str(tmp_path), starttime=999, sid=10, pgid=10) == (True, None) + assert procmon.verify(10, proc=str(tmp_path), starttime=998, sid=10, pgid=10) == ( + False, + "pid_reuse_detected", + ) + + +def test_the_real_process_verifies_against_itself(): + me = os.getpid() + identity = procmon.identity(me) + assert identity is not None + assert identity.sid == os.getsid(me) + assert identity.pgid == os.getpgid(me) + verdict = procmon.check( + me, + starttime=identity.starttime, + sid=identity.sid, + pgid=identity.pgid, + cmdline_sha256=identity.cmdline_sha256, + ) + assert verdict.ok is True + assert "starttime" in verdict.checked + + +def test_a_real_exec_does_not_change_starttime_but_does_change_the_cmdline(): + """The claim the whole fix rests on, measured on a real process. + + A process that `exec`s something else keeps its pid, its session id, its + process group and its `starttime`; only its command line is replaced. The + handshake over stdin is what makes it deterministic — the child is blocked + in `readline()` while the "before" identity is taken, so there is no race + with the `exec` and no sleep sized by guesswork. If this ever stops being + true, the gate is unsound and this test says so. + """ + + child = ( + "import os, sys\n" + "sys.stdout.write(str(os.getpid()) + chr(10)); sys.stdout.flush()\n" + "sys.stdin.readline()\n" # held here while the parent looks at us + "os.execv(sys.executable, [sys.executable, '-c', 'import time; time.sleep(30)'])\n" + ) + process = subprocess.Popen( + [sys.executable, "-c", child], + stdin=subprocess.PIPE, + stdout=subprocess.PIPE, + start_new_session=True, + ) + try: + pid = int(process.stdout.readline()) + before = procmon.identity(pid) + assert before is not None + assert before.sid == before.pgid == pid, "start_new_session gives a leader" + + process.stdin.write(b"go\n") + process.stdin.flush() + + deadline = time.monotonic() + 10.0 + while True: + after = procmon.identity(pid) + assert after is not None, "the process exec'd into nothing" + if after.cmdline_sha256 != before.cmdline_sha256: + break + assert time.monotonic() < deadline, "the exec never happened" + time.sleep(0.01) + + assert after.starttime == before.starttime, "starttime must survive exec" + assert after.sid == before.sid == pid, "the session id must survive exec" + assert after.pgid == before.pgid == pid, "the process group must survive exec" + + # And the gate agrees: the identity recorded before the exec still + # verifies afterwards, with the drift reported but not acted on. + verdict = procmon.check( + pid, + starttime=before.starttime, + sid=before.sid, + pgid=before.pgid, + cmdline_sha256=before.cmdline_sha256, + ) + assert verdict.ok is True + assert verdict.cmdline_drifted is True + finally: + process.kill() + process.wait(timeout=5) + + +# --------------------------------------------------------------------------- +# signalling guards +# --------------------------------------------------------------------------- + + +@pytest.mark.parametrize("sid", [0, 1, -1, None]) +def test_the_sweep_refuses_session_ids_that_would_select_the_machine(sid): + """sid 0 or 1 would match init and most of everything else.""" + + assert procmon.session_members(sid) == [] + assert procmon.sweep_session(sid) == [] + + +@pytest.mark.parametrize("pgid", [0, 1, -1, None]) +def test_killpg_refuses_the_dangerous_process_groups(pgid): + """killpg(0) means "every process in my own group" — including the daemon.""" + + assert procmon.killpg(pgid, signal.SIGTERM) is False + + +def test_the_sweep_finds_processes_by_session_id(tmp_path: Path): + for pid, sid in [(100, 55), (101, 55), (102, 66)]: + fake_proc(tmp_path, pid, comm="x", sid=sid, pgid=pid, starttime=1, cmdline=b"/bin/x\0") + assert procmon.session_members(55, proc=str(tmp_path)) == [100, 101] + assert procmon.session_members(66, proc=str(tmp_path)) == [102] + assert procmon.session_members(55, proc=str(tmp_path), exclude={100}) == [101] + + +def test_signalling_a_dead_pid_is_not_an_error(): + assert procmon.kill_pid(2**22 - 1, signal.SIGKILL) in (False, True) + + +def test_pidfd_open_yields_none_rather_than_raising_when_it_cannot_be_used(): + """The caller falls back to a /proc poll on None, so it must never raise. + + This covers both reasons for None: the kernel lacking the syscall, and the + process being gone between the liveness check and the open. + """ + + assert procmon.pidfd_open(2**22 - 1) is None + fd = procmon.pidfd_open(os.getpid()) + if fd is None: + assert not procmon.HAVE_PIDFD + else: + os.close(fd) diff --git a/tests/sessions/unit/test_protocol.py b/tests/sessions/unit/test_protocol.py new file mode 100644 index 0000000..ff2af78 --- /dev/null +++ b/tests/sessions/unit/test_protocol.py @@ -0,0 +1,110 @@ +"""Protocol framing tests (DESIGN.md §3.4).""" + +from __future__ import annotations + +import json + +import pytest + +from hhstreamd import protocol +from hhstreamd.protocol import MAX_LINE_BYTES, PROTOCOL_VERSION, ProtocolError + + +def test_a_message_is_exactly_one_newline_terminated_line(): + frame = protocol.encode({"ok": True, "id": "foot-aaaaaa"}) + assert frame.endswith(b"\n") + assert frame.count(b"\n") == 1 + assert json.loads(frame) == {"ok": True, "id": "foot-aaaaaa"} + + +def test_round_trip(): + message = {"v": 1, "op": "start", "app": "foot", "argv": ["--a", "--b"]} + assert protocol.decode(protocol.encode(message)) == message + + +def test_embedded_newlines_cannot_break_the_framing(): + """A session id or an argv element must never be able to split a frame.""" + + message = {"ok": False, "reason": "line one\nline two\r\nline three"} + frame = protocol.encode(message) + assert frame.count(b"\n") == 1 + assert protocol.decode(frame) == message + + +def test_non_ascii_is_escaped_so_the_frame_stays_ascii(): + frame = protocol.encode({"reason": "café — ✓"}) + frame.decode("ascii") # must not raise + assert protocol.decode(frame)["reason"] == "café — ✓" + + +def test_decode_tolerates_a_missing_trailing_newline(): + assert protocol.decode(b'{"ok":true}') == {"ok": True} + + +@pytest.mark.parametrize("line", [b"", b"\n", b" \n"]) +def test_an_empty_frame_is_a_bad_request(line): + with pytest.raises(ProtocolError) as exc: + protocol.decode(line) + assert exc.value.error == "bad_request" + + +def test_malformed_json_is_a_bad_request(): + with pytest.raises(ProtocolError) as exc: + protocol.decode(b"{not json\n") + assert exc.value.error == "bad_request" + assert "malformed JSON" in exc.value.reason + + +@pytest.mark.parametrize("payload", [b"[1,2,3]", b'"a string"', b"42", b"null"]) +def test_a_frame_that_is_not_an_object_is_rejected(payload): + with pytest.raises(ProtocolError) as exc: + protocol.decode(payload) + assert exc.value.error == "bad_request" + + +def test_an_oversized_frame_is_refused_on_both_sides(): + with pytest.raises(ProtocolError) as exc: + protocol.decode(b"x" * (MAX_LINE_BYTES + 1)) + assert exc.value.error == "message_too_large" + + with pytest.raises(ProtocolError) as exc: + protocol.encode({"argv": ["x" * MAX_LINE_BYTES]}) + assert exc.value.error == "message_too_large" + + +def test_decode_request_requires_an_op(): + with pytest.raises(ProtocolError) as exc: + protocol.decode_request(b'{"v":1}') + assert exc.value.error == "bad_request" + assert "no 'op'" in exc.value.reason + + +def test_decode_request_rejects_an_unknown_protocol_version(): + with pytest.raises(ProtocolError) as exc: + protocol.decode_request(b'{"v":99,"op":"list"}') + assert exc.value.error == "unsupported_version" + + +def test_a_request_without_a_version_is_assumed_to_be_current(): + assert protocol.decode_request(b'{"op":"list"}')["op"] == "list" + + +def test_request_attaches_the_version_and_drops_unset_fields(): + message = protocol.request("start", app="foot", argv=None, idle_timeout_s=30.0) + assert message == {"v": PROTOCOL_VERSION, "op": "start", "app": "foot", "idle_timeout_s": 30.0} + + +def test_error_replies_carry_both_a_machine_field_and_a_human_field(): + reply = protocol.error( + "not_allowlisted", "app 'sh' is not in the allowlist", hint="see the config" + ) + assert reply == { + "ok": False, + "error": "not_allowlisted", + "reason": "app 'sh' is not in the allowlist", + "hint": "see the config", + } + + +def test_ok_replies_are_flagged(): + assert protocol.ok(id="a")["ok"] is True diff --git a/tests/sessions/unit/test_reaper.py b/tests/sessions/unit/test_reaper.py new file mode 100644 index 0000000..bd7d949 --- /dev/null +++ b/tests/sessions/unit/test_reaper.py @@ -0,0 +1,215 @@ +"""Reaper unit tests — injected clock, no processes, no sleeping. + +DESIGN.md §6.5 layer 1: "tests pass a fake clock and assert which session is +selected and when". This is where nearly all of the reaping logic is covered. +""" + +from __future__ import annotations + +import asyncio + + +from hhstreamd.clock import ManualClock +from hhstreamd.reaper import Reaper, deadlines, next_deadline, select_expired, sleep_for +from hhstreamd.registry import State + + +class FakeSession: + """The minimum the reaper needs: an id, liveness and a deadline.""" + + def __init__(self, sid: str, last_activity: float, timeout: float, state: str = State.READY): + self.id = sid + self.last_activity_boottime = last_activity + self.idle_timeout_s = timeout + self.state = state + + @property + def live(self) -> bool: + return self.state not in {State.EXITED, State.KILLED, State.REAPED} + + def deadline(self): + if not self.live or not self.idle_timeout_s: + return None + return self.last_activity_boottime + self.idle_timeout_s + + +# --------------------------------------------------------------------------- +# selection +# --------------------------------------------------------------------------- + + +def test_empty_set_has_no_deadline_and_sleeps_indefinitely(): + assert deadlines([]) == {} + assert next_deadline([]) is None + assert select_expired([], now=10_000.0) == [] + # None means "sleep until woken" — zero wakeups on a quiet server. + assert sleep_for([], now=10_000.0) is None + + +def test_next_deadline_is_the_earliest_across_sessions(): + sessions = [ + FakeSession("a", last_activity=1000.0, timeout=10800.0), # 11800 + FakeSession("b", last_activity=5000.0, timeout=60.0), # 5060 <- earliest + FakeSession("c", last_activity=2000.0, timeout=3600.0), # 5600 + ] + assert next_deadline(sessions) == 5060.0 + assert sleep_for(sessions, now=5000.0) == 60.0 + + +def test_select_expired_returns_only_the_passed_deadlines_oldest_first(): + sessions = [ + FakeSession("late", last_activity=100.0, timeout=10.0), # 110 + FakeSession("later", last_activity=100.0, timeout=5.0), # 105 + FakeSession("future", last_activity=100.0, timeout=1000.0), # 1100 + ] + assert select_expired(sessions, now=120.0) == ["later", "late"] + assert select_expired(sessions, now=104.0) == [] + + +def test_deadline_is_inclusive_so_an_exactly_due_session_is_reaped(): + session = FakeSession("a", last_activity=100.0, timeout=10.0) + assert select_expired([session], now=110.0) == ["a"] + assert sleep_for([session], now=110.0) == 0.0 + + +def test_a_terminal_session_has_no_deadline(): + for state in (State.EXITED, State.KILLED, State.REAPED): + session = FakeSession("a", last_activity=0.0, timeout=1.0, state=state) + assert session.deadline() is None + assert select_expired([session], now=1e9) == [] + + +def test_a_zero_timeout_disables_expiry_rather_than_expiring_immediately(): + session = FakeSession("a", last_activity=0.0, timeout=0.0) + assert next_deadline([session]) is None + assert select_expired([session], now=1e9) == [] + + +def test_sleep_for_never_goes_negative(): + session = FakeSession("a", last_activity=0.0, timeout=10.0) + assert sleep_for([session], now=1_000_000.0) == 0.0 + + +# --------------------------------------------------------------------------- +# the Reaper object, with the clock injected at construction +# --------------------------------------------------------------------------- + + +def make_reaper(clock: ManualClock, sessions: list[FakeSession]): + reaped: list[str] = [] + + async def on_expire(session_id: str) -> None: + reaped.append(session_id) + for session in sessions: + if session.id == session_id: + session.state = State.REAPED + + return Reaper(now=clock.boottime, sessions=lambda: sessions, on_expire=on_expire), reaped + + +def test_clock_is_injected_and_nothing_expires_until_it_moves(): + clock = ManualClock(boottime=1000.0) + sessions = [FakeSession("a", last_activity=1000.0, timeout=10800.0)] + reaper, reaped = make_reaper(clock, sessions) + + assert reaper.next_deadline() == 11800.0 + assert reaper.sleep_for() == 10800.0 + assert reaper.expired() == [] + + clock.advance(10799.0) + assert reaper.expired() == [] + clock.advance(1.0) # exactly three hours of idleness + assert reaper.expired() == ["a"] + assert reaped == [] # selection alone does not tear anything down + + +def test_tick_reaps_the_expired_and_leaves_the_rest(): + clock = ManualClock(boottime=0.0) + sessions = [ + FakeSession("doomed", last_activity=0.0, timeout=60.0), + FakeSession("safe", last_activity=0.0, timeout=3600.0), + ] + reaper, reaped = make_reaper(clock, sessions) + clock.advance(61.0) + + assert asyncio.run(reaper.tick()) == ["doomed"] + assert reaped == ["doomed"] + assert sessions[1].state == State.READY + # The reaped session now has no deadline, so the next one is the survivor's. + assert reaper.next_deadline() == 3600.0 + + +def test_adopt_with_an_already_expired_deadline_is_reaped_on_the_first_pass(): + """DESIGN.md §2.4 item 6: the arithmetic survives a daemon restart. + + A record adopted at boottime 50000 whose last activity was at 1000 with a + one-hour timeout is already 13 hours overdue. It must be selected + immediately, not scheduled another hour out. + """ + + clock = ManualClock(boottime=50_000.0) + sessions = [FakeSession("adopted", last_activity=1000.0, timeout=3600.0)] + reaper, reaped = make_reaper(clock, sessions) + + assert reaper.sleep_for() == 0.0 + assert asyncio.run(reaper.tick()) == ["adopted"] + assert reaped == ["adopted"] + + +def test_a_touch_pushes_the_deadline_out(): + clock = ManualClock(boottime=0.0) + session = FakeSession("a", last_activity=0.0, timeout=100.0) + reaper, _ = make_reaper(clock, [session]) + + clock.advance(99.0) + assert reaper.expired() == [] + session.last_activity_boottime = clock.boottime() # what `touch` does + clock.advance(99.0) + assert reaper.expired() == [] + clock.advance(2.0) + assert reaper.expired() == ["a"] + + +def test_run_reaps_when_the_deadline_arrives_and_then_sleeps_indefinitely(): + """Exercise the real asyncio task without waiting for a real timeout.""" + + async def scenario(): + clock = ManualClock(boottime=0.0) + sessions = [FakeSession("a", last_activity=0.0, timeout=10_000.0)] + reaper, reaped = make_reaper(clock, sessions) + task = reaper.start() + await asyncio.sleep(0) # let the first pass run + assert reaped == [] + + clock.advance(10_001.0) # three hours pass in a nanosecond + reaper.wake() + for _ in range(20): + await asyncio.sleep(0) + if reaped: + break + assert reaped == ["a"] + # Nothing left to expire: the task is parked, not spinning. + assert reaper.sleep_for() is None + await reaper.stop() + assert task.done() + + asyncio.run(scenario()) + + +def test_a_failing_teardown_does_not_kill_the_reaper_task(): + async def scenario(): + clock = ManualClock(boottime=0.0) + sessions = [FakeSession("a", last_activity=0.0, timeout=1.0)] + calls = [] + + async def on_expire(session_id: str) -> None: + calls.append(session_id) + raise RuntimeError("teardown exploded") + + reaper = Reaper(now=clock.boottime, sessions=lambda: sessions, on_expire=on_expire) + clock.advance(2.0) + assert await reaper.tick() == [] # the failure is swallowed and logged + assert calls == ["a"] + assert reaper.expired() == ["a"] # still expired; it will be retried + + asyncio.run(scenario()) diff --git a/tests/sessions/unit/test_registry.py b/tests/sessions/unit/test_registry.py new file mode 100644 index 0000000..27a2adb --- /dev/null +++ b/tests/sessions/unit/test_registry.py @@ -0,0 +1,270 @@ +"""Registry unit tests: atomic persistence, adoption, tombstones.""" + +from __future__ import annotations + +import base64 +import json +import os +from pathlib import Path + +import pytest + +from hhstreamd.clock import ManualClock +from hhstreamd.registry import ( + Registry, + Session, + State, + atomic_write_json, + mint_id, +) + + +def make_session(sid: str = "foot-aaaaaa", **overrides) -> Session: + base = dict( + id=sid, + app="foot", + argv=["/usr/bin/foot"], + pid=4242, + pgid=4242, + sid=4242, + pid_starttime=918342, + cmdline_sha256="9f2c", + home="/home/someone", + runtime_dir="/run/hhstream/sessions/" + sid, + created_at="2026-10-01T09:14:02Z", + created_boottime=1000.0, + last_activity_at="2026-10-01T09:14:02Z", + last_activity_boottime=1000.0, + idle_timeout_s=10800.0, + state=State.READY, + ) + base.update(overrides) + return Session(**base) + + +@pytest.fixture +def registry(tmp_path: Path) -> Registry: + reg = Registry(tmp_path, ManualClock(boottime=1000.0)) + reg.ensure_dirs() + return reg + + +# --------------------------------------------------------------------------- +# atomic persistence +# --------------------------------------------------------------------------- + + +def test_atomic_write_leaves_no_temporary_files_behind(tmp_path: Path): + target = tmp_path / "rec.json" + atomic_write_json(target, {"hello": "world"}) + assert json.loads(target.read_text()) == {"hello": "world"} + assert [p.name for p in tmp_path.iterdir()] == ["rec.json"] + + +def test_a_failed_write_leaves_the_previous_record_intact(tmp_path: Path, monkeypatch): + """The point of tmp + os.replace: a reader never sees a half-written record.""" + + target = tmp_path / "rec.json" + atomic_write_json(target, {"generation": 1}) + + def explode(*args, **kwargs): + raise OSError("disk full") + + monkeypatch.setattr(json, "dump", explode) + with pytest.raises(OSError): + atomic_write_json(target, {"generation": 2}) + + assert json.loads(target.read_text()) == {"generation": 1} + assert [p.name for p in tmp_path.iterdir()] == ["rec.json"] # temp cleaned up + + +def test_the_temp_file_is_written_in_the_target_directory(tmp_path: Path, monkeypatch): + """os.replace is only atomic within one filesystem, so the temp must be adjacent.""" + + seen: list[str] = [] + real_replace = os.replace + + def spy(src, dst, *args, **kwargs): + seen.append(str(src)) + return real_replace(src, dst, *args, **kwargs) + + monkeypatch.setattr(os, "replace", spy) + target = tmp_path / "deep" / "rec.json" + atomic_write_json(target, {"a": 1}) + assert Path(seen[0]).parent == target.parent + + +def test_persist_writes_the_record_and_it_round_trips(registry: Registry): + session = registry.add(make_session()) + path = registry.record_path(session.id) + assert path.exists() + restored = Session.from_dict(json.loads(path.read_text())) + assert restored == session + + +def test_a_mirror_write_failure_never_fails_the_command(registry: Registry, monkeypatch, caplog): + session = registry.add(make_session()) + monkeypatch.setattr( + "hhstreamd.registry.atomic_write_json", + lambda *a, **k: (_ for _ in ()).throw(OSError("read-only filesystem")), + ) + registry.touch(session, force_flush=True) # must not raise + assert session.command_count == 1 + assert "mirror write failed" in caplog.text + + +def test_activity_flushes_are_rate_limited_but_transitions_are_not(registry: Registry): + clock: ManualClock = registry.clock # type: ignore[assignment] + session = registry.add(make_session()) + + registry.touch(session) # within the 15 s window: memory only + on_disk = Session.from_dict(json.loads(registry.record_path(session.id).read_text())) + assert session.command_count == 1 + assert on_disk.command_count == 0 + + clock.advance(16.0) + registry.touch(session) + on_disk = Session.from_dict(json.loads(registry.record_path(session.id).read_text())) + assert on_disk.command_count == 2 + + +# --------------------------------------------------------------------------- +# handles +# --------------------------------------------------------------------------- + + +def test_a_colliding_draw_is_discarded_and_another_taken(): + """Handles are never reused: a draw already in the set is refused.""" + + class TwoDraws: + def __init__(self): + self.calls = 0 + + def token_bytes(self, n): + self.calls += 1 + return b"\x00" * n if self.calls == 1 else b"\xff" * n + + rng = TwoDraws() + collision = f"foot-{base64.b32encode(b'\x00' * 5).decode().rstrip('=').lower()[:6]}" + minted = mint_id("foot", {collision}, rng=rng) + assert rng.calls == 2 + assert minted != collision + assert minted.startswith("foot-") + + +def test_a_tombstoned_id_still_blocks_reuse(registry: Registry): + session = registry.add(make_session()) + registry.terminate(session, State.KILLED) + assert session.id in registry.taken_ids() + assert registry.new_id("foot") != session.id + + +def test_the_slug_is_sanitised_but_never_parsed(): + assert mint_id("Chromium", set()).startswith("chromium-") + assert mint_id("/bin/odd name", set()).startswith("bin-odd-name-") + assert mint_id("!!!", set()).startswith("app-") + + +# --------------------------------------------------------------------------- +# tombstones +# --------------------------------------------------------------------------- + + +def test_terminate_writes_a_tombstone_with_an_expiry(registry: Registry): + clock: ManualClock = registry.clock # type: ignore[assignment] + session = registry.add(make_session()) + registry.terminate(session, State.EXITED, exit_code=0, exit_detected_by="sigchld") + + assert not session.live + assert session.exit_code == 0 + assert session.tombstoned_boottime == clock.boottime() + assert session.tombstone_expires() == clock.boottime() + 3600.0 + assert session.deadline() is None # a tombstone can never be idle-reaped + assert registry.tombstones() == [session] + assert registry.live() == [] + + +def test_an_adopted_exit_records_no_exit_code_rather_than_inventing_a_zero(registry: Registry): + session = registry.add(make_session(adopted=True)) + registry.terminate(session, State.EXITED, exit_detected_by="pidfd") + assert session.exit_code is None + assert session.exit_detected_by == "pidfd" + + +def test_drop_removes_the_record_and_its_mirror(registry: Registry): + session = registry.add(make_session()) + path = registry.record_path(session.id) + registry.drop(session.id) + assert not path.exists() + assert registry.get(session.id) is None + + +# --------------------------------------------------------------------------- +# loading / adoption +# --------------------------------------------------------------------------- + + +def test_load_records_reads_back_what_was_persisted(tmp_path: Path): + writer = Registry(tmp_path, ManualClock()) + writer.ensure_dirs() + writer.add(make_session("foot-aaaaaa")) + writer.add(make_session("foot-bbbbbb", pid=99)) + + reader = Registry(tmp_path, ManualClock()) + records, quarantined = reader.load_records() + assert quarantined == [] + assert sorted(r.id for r in records) == ["foot-aaaaaa", "foot-bbbbbb"] + + +def test_a_corrupt_record_is_quarantined_not_deleted_and_not_acted_on(tmp_path: Path, caplog): + registry = Registry(tmp_path, ManualClock()) + registry.ensure_dirs() + bad = registry.sessions_dir / "foot-broken.json" + bad.write_text("{this is not json") + + records, quarantined = registry.load_records() + assert records == [] + assert len(quarantined) == 1 + assert not bad.exists() + moved = list(registry.quarantine_dir.iterdir()) + assert len(moved) == 1 + assert moved[0].read_text() == "{this is not json" + assert "quarantining unreadable record" in caplog.text + + +def test_a_record_that_is_not_an_object_is_quarantined(tmp_path: Path): + registry = Registry(tmp_path, ManualClock()) + registry.ensure_dirs() + (registry.sessions_dir / "x.json").write_text("[1, 2, 3]") + records, quarantined = registry.load_records() + assert records == [] and len(quarantined) == 1 + + +def test_unknown_fields_from_a_newer_schema_are_dropped_not_fatal(caplog): + data = make_session().to_dict() + data["invented_by_a_later_version"] = True + session = Session.from_dict(data) + assert session.id == "foot-aaaaaa" + assert "dropping unknown record fields" in caplog.text + + +def test_a_record_from_a_previous_boot_is_recognised_as_stale(tmp_path: Path): + """Pids restart from zero at boot, so /proc cannot be trusted about them.""" + + registry = Registry(tmp_path, ManualClock()) + this_boot = make_session("foot-aaaaaa") + this_boot.boot_id = registry._boot_id + previous_boot = make_session("foot-bbbbbb") + previous_boot.boot_id = "00000000-0000-0000-0000-000000000000" + + assert registry.stale_boot(this_boot) is False + assert registry.stale_boot(previous_boot) is True + + +def test_derived_fields_reported_to_callers(registry: Registry): + session = registry.add(make_session()) + public = session.public(now=1000.0 + 600.0) + assert public["idle_s"] == 600.0 + assert public["expires_in_s"] == 10800.0 - 600.0 + assert public["live"] is True + assert public["schema"] == 2 diff --git a/tests/sessions/unit/test_textio.py b/tests/sessions/unit/test_textio.py new file mode 100644 index 0000000..29ef56c --- /dev/null +++ b/tests/sessions/unit/test_textio.py @@ -0,0 +1,67 @@ +"""Bounded tail reads. + +Both the audit log and an application's captured output are unbounded in M0, and +both are read by verbs that must stay cheap. +""" + +from __future__ import annotations + +from pathlib import Path + +from hhstreamd.textio import tail_lines + + +def test_the_last_n_lines_are_returned(tmp_path: Path): + path = tmp_path / "f.log" + path.write_text("".join(f"line {i}\n" for i in range(100))) + lines, truncated, size = tail_lines(path, 3) + assert lines == ["line 97", "line 98", "line 99"] + assert truncated is True # there was more above the window + assert size == path.stat().st_size + + +def test_a_short_file_is_returned_whole_and_not_marked_truncated(tmp_path: Path): + path = tmp_path / "f.log" + path.write_text("a\nb\n") + assert tail_lines(path, 10) == (["a", "b"], False, 4) + + +def test_a_large_file_is_never_read_whole(tmp_path: Path): + """A gigabyte of Chromium stderr must not become a daemon-sized allocation.""" + + path = tmp_path / "big.log" + path.write_text("".join(f"{i:07d} padding padding padding\n" for i in range(40_000))) + assert path.stat().st_size > 1_000_000 + + lines, truncated, size = tail_lines(path, 5, max_bytes=4096) + assert len(lines) == 5 + assert lines[-1] == "0039999 padding padding padding" + assert truncated is True + assert size == path.stat().st_size + + +def test_a_partial_first_line_in_the_window_is_dropped_not_reported_as_whole(tmp_path: Path): + path = tmp_path / "f.log" + path.write_text("aaaaaaaaaaaaaaaaaaaa\nbbbb\ncccc\n") + lines, truncated, _ = tail_lines(path, 10, max_bytes=12) + assert "aaaa" not in "".join(lines) + assert lines == ["cccc"] or lines == ["bbbb", "cccc"] + assert truncated is True + + +def test_a_missing_file_is_empty_rather_than_an_error(tmp_path: Path): + assert tail_lines(tmp_path / "absent.log", 10) == ([], False, 0) + + +def test_asking_for_no_lines_still_reports_the_size(tmp_path: Path): + path = tmp_path / "f.log" + path.write_text("hello\n") + assert tail_lines(path, 0) == ([], False, 6) + + +def test_invalid_utf8_is_replaced_not_fatal(tmp_path: Path): + path = tmp_path / "f.log" + path.write_bytes(b"ok\n\xff\xfe bad\n") + lines, _, _ = tail_lines(path, 10) + assert lines[0] == "ok" + assert "bad" in lines[1]