Files
HermenixandClaude Opus 5 129430bffd wire the broker to the compositor, containers and pointer
The four slices existed and nothing called them. Now the broker builds a
spatial container per session, reads back what the compositor actually did,
and aims the cursor into one container under a broker-wide lease.

Record schema 3 (registry.py): `container` {output, workspace, mode,
created_by, state}, `pointer` {bookmark, last_released_at, released_by} and
the compositor's `signature`. A v2 record is migrated on load, not refused —
its application is still running. Every field that could not be verified is
null; `container: null` means "no container", never "probably something".

Containers (new container_host.py, manager.py, launcher.py): `start`
allocates a slot from `WorkspaceAllocator`, runs `container_plan()`'s argv,
launches the app with the container stamp in its environment, then reads the
workspace, output and window back out of `clients -j`. Teardown removes the
output, releases the slot and reports survivors rather than claiming success
— and runs for an unprompted exit and for `gc` too, so no container is ever
left unattended. Broker start-up reconciles: adopt `hh-*` outputs a live
session claims, remove the rest, `contains_output()` being the only filter.
No IPC means `container: degraded` and lifecycle verbs unchanged.

The plans' argv are dispatched over the compositor's request socket rather
than by executing `hyprctl`, which is what hyprctl does with the same words;
the reply is checked, so a refused command is not recorded as a container.

Pointer (new driver.py, manager.py): a client for the driver's private
socket, and `pointer.acquire|move|button|click|release|state` on top of
`PointerLease`. The broker owns the lease, the driver executes. The bookmark
is marked on every move and before release and stored in the record, so it
survives a restart. On expiry `pressed()` is read before `expire()` and
`release_all` goes to the driver, because the lease cannot lift a button
itself; a sweep runs unprompted so the TTL is a promise.

containers.py to v2: `quarantine_plan()` -> `quarantine_argv()`, with the
before-any-per-session-rule ordering stated where the caller could get it
wrong. protocol.py: 9 NO_LEASE, 10 COMPOSITOR, the verb table, and the
`request_id` cache moved out of the server so the CLI agrees with it.

Tests: real AF_UNIX everywhere — a stateful fake compositor and the shipped
pointer driver behind a recording sink. No mocked sockets, no compositor, no
VM. 551 -> 693.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017mUq7QvQ9EZb2Wi35xj4cs
2026-10-02 19:47:33 +00:00

1152 lines
44 KiB
Python

"""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.
#:
#: These are PREPENDED to whatever PYTHONPATH we inherited rather than replacing
#: it. Clobbering it works in a checkout, where `src/` is the package, but under
#: a build (checks/unit.nix) the package under test is what the inherited path
#: points at -- so replacing it made `python -m hhstreamd` die at startup with an
#: ImportError, and every test in this file error out in its setup, which reads
#: as a daemon bug rather than a harness one.
_CHECKOUT_PATH = os.pathsep.join([str(REPO_ROOT / "src"), str(REPO_ROOT)])
IMPORT_PATH = os.pathsep.join(
p for p in (_CHECKOUT_PATH, os.environ.get("PYTHONPATH", "")) if p
)
# 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/<app>` 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/<app> 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)"
)
# The container stamp as the application actually receives it. A separate app
# from `envdump` because that one asserts on an exact three-key dict, and the
# question here is a different one: did the class the window rule matches
# reach the process.
APP_ID_DUMP = (
"import json, os, time; "
"print(json.dumps({k: os.environ.get(k) for k in "
"('HHSTREAM_APP_ID', 'SDL_VIDEO_WAYLAND_WMCLASS', 'RESOURCE_NAME')}), 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)
+ app("idump", APP_ID_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)
#: Extra environment for the daemon process, laid over the inherited
#: one. The container tests use it to pin the compositor instance
#: signature the way a real deployment's unit does.
self.env: dict[str, str] = {}
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, **self.env},
)
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/<pid>/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/<pid> 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()