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