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.
This commit is contained in:
1 parent
9dc9e0da9a
commit
30f456c07e
37 files changed
+9118
-1
No files matched your search
@@ -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 ``<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)
|
||||
Reference in new issue
Block a user