"""The session record and its persistence (DESIGN.md §2.1, §2.3, §2.4). Authoritative state is in daemon memory; the files under ``/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") #: 3 adds the container, the pointer bookmark and the compositor signature #: (PLAN §7). The number is read, never written by anyone but this module: a #: record carrying an older one is **migrated on load** (:func:`migrate`), not #: refused, because the processes it describes are still running and refusing #: the record would strand them. SCHEMA = 3 #: 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 ContainerState: """What the broker knows about a session's spatial container. These are the only four answers. ``container: null`` is a fifth and different thing — "this session has no container at all" — and nothing here means "probably something": a field the compositor did not confirm stays ``None`` (PLAN §7). """ #: Created by us, and the compositor still shows the output. OWNED = "owned" #: No IPC, so nothing was created and nothing can be verified. The session #: still starts, stops and is reaped by process identity (PLAN §4.4). DEGRADED = "degraded" #: Torn down on purpose: the output was removed and the slot released. REMOVED = "removed" #: The record and the compositor disagree — the output we recorded is not #: there, or an output of ours has no live session. Never deleted on a #: guess; reconciliation decides. ORPHAN = "orphan" 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 #: ``{output, workspace, mode, created_by, state}`` or ``None`` for "no #: container". A dict rather than a nested dataclass because #: :meth:`to_dict` is ``asdict`` and :meth:`from_dict` is ``cls(**data)``: #: a dataclass would serialise and come back as a dict anyway, and the #: asymmetry is where a half-migrated record would hide. container: dict[str, Any] | None = None #: ``{bookmark, last_released_at, released_by}``. Absent (``None``) means #: the pointer was never aimed here — not that its position is unknown. pointer: dict[str, Any] | None = None #: ``HYPRLAND_INSTANCE_SIGNATURE`` of the compositor this session's #: container lives in, so a restarted broker re-attaches to the same #: instance instead of picking whichever one is there now. signature: str | 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": data = migrate(data) 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 container_record( *, output: str | None, workspace: int | None, mode: tuple[int, int] | None, created_by: str, state: str, ) -> dict[str, Any]: """One ``container`` sub-record (PLAN §7). Every argument is explicit and may be ``None`` because the degraded case is the common one: there is a container *state* to report long before there is an output to name, and the alternative — leaving the key out — would read as "no container" when what we mean is "a container we could not verify". """ return { "output": output, "workspace": workspace, "mode": None if mode is None else {"width": mode[0], "height": mode[1]}, "created_by": created_by, "state": state, } def pointer_record( *, bookmark: dict[str, Any] | None, last_released_at: str | None, released_by: str | None, ) -> dict[str, Any]: """One ``pointer`` sub-record: where the cursor was left, and by what. Written on every move and on release. A session that has one has been aimed at; a session that has none never was. """ return { "bookmark": bookmark, "last_released_at": last_released_at, "released_by": released_by, } def migrate(data: dict[str, Any]) -> dict[str, Any]: """Bring a record read from disk up to :data:`SCHEMA`. A schema-2 record is **adopted, not rejected**: its application is very likely still running, and the daemon that wrote it knew nothing of containers, so the honest value for every field schema 3 added is ``None`` — "no container", "the pointer was never used here", "we do not know which compositor instance this was". Each of those is a defined value, which is the whole reason the migration can be this short. A record from a *newer* schema is left alone and loudly logged: the fields this daemon does not know are dropped by :meth:`Session.from_dict`, and guessing at what a future version meant would be worse than running with the subset we understand. """ schema = data.get("schema") if schema == SCHEMA: return data if isinstance(schema, int) and schema > SCHEMA: log.error( "record %s is schema %s, newer than this daemon's %s; reading the fields " "this version knows and leaving the rest", data.get("id"), schema, SCHEMA, ) return data upgraded = dict(data) # Only ever *adds* keys. A v2 record that somehow carries a container must # keep it: the field is new to the schema, not new to the session. for key in ("container", "pointer", "signature"): upgraded.setdefault(key, None) upgraded["schema"] = SCHEMA log.info("migrated record %s from schema %s to %s", data.get("id"), schema, SCHEMA) return upgraded def mint_id(app: str, taken: set[str], *, rng: Any = secrets) -> str: """``-<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)