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.
395 lines
14 KiB
Python
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)
|