Files
hyprland-headless-stream-pl…/src/hhstreamd/reaper.py
T
Hermenix 30f456c07e integrate the session broker: one CLI, a module unit, and a VM check
M0 of the sessions design, wired into the flake and gated by a real check.

What is here now:

- `src/hhstreamd/` — the broker: session registry, lifecycle verbs, process-group
  teardown, app allowlist, audit log, idle reaper on CLOCK_BOOTTIME.
- `src/hhstream_session/` — the CLI handlers, registered into the one front door.
- `src/hhstream/cli.py` — `hhstream status|shot|run|record|session …`, so the
  frame verbs and the session namespace are one binary.
- `nix/module.nix` — `sessions.*` options and the `hhstream-sessions.service`
  unit: the operator's own account (never a service account, because launched
  applications should see that account's home), the compositor's group as a
  supplementary group (without it a launched GUI client cannot open the Wayland
  socket), the generated app allowlist, and `--compositor-runtime-dir` so
  applications are handed the compositor's session rather than the broker's.
- `checks/vm-sessions.nix` — 18 subtests on a real compositor in a VM.

Two bugs found by driving it, both fixed:

- BUG-01: launched applications could not reach the compositor at all — the
  broker spawned them with its own inherited environment, which names the login
  session. `hhstreamd/compositor.py` discovers the socket and builds the child
  environment; a directory with no usable socket is a startup refusal, not a
  warning.
- BUG-02: `kill` refused to signal a live application and said nothing was
  wrong. The identity gate hashed `/proc/<pid>/cmdline`, which every `execve`
  replaces — and on NixOS applications are reached through wrapper scripts that
  do exactly that. The gate now rests on `starttime` (+ boot id, + session id
  where it is immutable) and records command-line drift as evidence of nothing.

KillMode=process is set on the unit on purpose: the default control-group kill
would take the applications down with the broker, which would make adoption and
a broker restart pointless.
2026-10-01 12:23:16 +00:00

188 lines
6.5 KiB
Python

"""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