Files
hyprland-headless-stream-pl…/src/hhstreamd/registry.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

395 lines
14 KiB
Python

"""The session record and its persistence (DESIGN.md §2.1, §2.3, §2.4).
Authoritative state is in daemon memory; the files under ``<state>/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:
"""``<app-slug>-<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)