"""The control socket (DESIGN.md §3.4). An asyncio unix ``SOCK_STREAM`` server speaking newline-delimited JSON: one request object, one response object, connection closed. Chosen over HTTP (framing and a server for no benefit on a local socket), D-Bus (no stdlib client) and a bespoke binary protocol (unreadable at 3am). It is debuggable with ``socat - UNIX-CONNECT:/run/hhstream/control.sock`` and costs nothing. This module is framing and dispatch only. Every decision lives in :mod:`hhstreamd.manager`. """ from __future__ import annotations import asyncio import collections import contextlib import logging import os import socket import struct from pathlib import Path from typing import Any, Awaitable, Callable from . import protocol from .manager import ManagerError, SessionManager from .policy import PolicyError log = logging.getLogger("hhstreamd.server") #: A request that has not produced a reply in this long is abandoned and the #: caller told so, rather than holding the connection open indefinitely. DEFAULT_REQUEST_TIMEOUT_S = 5.0 #: A `kill` may legitimately take `grace` seconds, so it gets its own budget. KILL_TIMEOUT_MARGIN_S = 5.0 #: Replies to mutating verbs are remembered so a CLI that died before reading #: the reply can retry without launching a second application. DEDUP_ENTRIES = 64 #: Verbs whose replies are cached by `request_id`. The read verbs are absent #: deliberately: they are idempotent, so a retry costs nothing and a cached #: `list` would be a stale one. MUTATING_VERBS = frozenset({"start", "touch", "kill", "adopt", "gc"}) class ControlServer: def __init__( self, manager: SessionManager, socket_path: Path | str, *, request_timeout_s: float = DEFAULT_REQUEST_TIMEOUT_S, socket_mode: int = 0o660, ) -> None: self.manager = manager self.socket_path = Path(socket_path) self.request_timeout_s = request_timeout_s self.socket_mode = socket_mode self._server: asyncio.AbstractServer | None = None self._dedup: collections.OrderedDict[str, dict[str, Any]] = collections.OrderedDict() self._ops: dict[str, Callable[[dict[str, Any], dict[str, Any]], Awaitable[dict[str, Any]]]] = { "ping": self._op_ping, "start": self._op_start, "list": self._op_list, "status": self._op_status, "touch": self._op_touch, "kill": self._op_kill, "gc": self._op_gc, "adopt": self._op_adopt, "logs": self._op_logs, } # ------------------------------------------------------------------ # lifecycle # ------------------------------------------------------------------ async def start(self) -> None: self._prepare_socket_path() self._server = await asyncio.start_unix_server( self._handle, path=str(self.socket_path), # The stream limit is the frame limit: a peer cannot grow the # daemon's read buffer past one message. limit=protocol.MAX_LINE_BYTES, ) with contextlib.suppress(OSError): os.chmod(self.socket_path, self.socket_mode) log.info("listening on %s", self.socket_path) async def stop(self) -> None: if self._server is not None: self._server.close() with contextlib.suppress(Exception): await self._server.wait_closed() self._server = None with contextlib.suppress(FileNotFoundError, OSError): self.socket_path.unlink() def _prepare_socket_path(self) -> None: """Create the parent directory and clear a stale socket. A socket file left by a crashed daemon is unlinked only after proving nobody is listening on it: connecting and being refused is the proof. Unlinking a *live* socket would silently steal another daemon's clients. """ self.socket_path.parent.mkdir(parents=True, exist_ok=True, mode=0o750) if not self.socket_path.exists(): return probe = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) try: probe.settimeout(0.5) probe.connect(str(self.socket_path)) except (ConnectionRefusedError, FileNotFoundError): log.warning("removing stale socket %s", self.socket_path) with contextlib.suppress(OSError): self.socket_path.unlink() except OSError as exc: raise OSError( f"{self.socket_path} exists and could not be probed: {exc}" ) from exc else: raise OSError(f"another daemon is already listening on {self.socket_path}") finally: probe.close() # ------------------------------------------------------------------ # connection handling # ------------------------------------------------------------------ async def _handle(self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None: caller = _peer_credentials(writer) try: try: line = await reader.readuntil(b"\n") except asyncio.IncompleteReadError as exc: if not exc.partial: return # a peer that connected and went away; not an error line = exc.partial except asyncio.LimitOverrunError: await self._send( writer, protocol.error("message_too_large", "request exceeds the frame limit"), ) return if len(line) > protocol.MAX_LINE_BYTES: await self._send( writer, protocol.error("message_too_large", "request exceeds the frame limit"), ) return response = await self._dispatch(line, caller) await self._send(writer, response) except (ConnectionResetError, BrokenPipeError): pass except Exception: log.exception("unhandled error serving a request") with contextlib.suppress(Exception): await self._send( writer, protocol.error("refused", "internal error; see the daemon log") ) finally: with contextlib.suppress(Exception): writer.close() await writer.wait_closed() async def _send(self, writer: asyncio.StreamWriter, message: dict[str, Any]) -> None: writer.write(protocol.encode(message)) await writer.drain() async def _dispatch(self, line: bytes, caller: dict[str, Any]) -> dict[str, Any]: started = self.manager.clock.boottime() try: request = protocol.decode_request(line) except protocol.ProtocolError as exc: self.manager.audit.emit( "request_rejected", error=exc.error, reason=exc.reason, caller=caller ) return protocol.error(exc.error, exc.reason) op = request["op"] request_id = request.get("request_id") handler = self._ops.get(op) if handler is None: return protocol.error( "unknown_op", f"unknown op {op!r}", hint=f"known: {', '.join(sorted(self._ops))}" ) if isinstance(request_id, str) and op in MUTATING_VERBS and request_id in self._dedup: cached = dict(self._dedup[request_id]) cached["deduplicated"] = True return cached timeout = self.request_timeout_s if op == "kill": # A kill is allowed to take its grace period plus the SIGKILL step. grace = request.get("grace_s") grace = self.manager.config.policy.grace_s if grace is None else float(grace or 0) timeout = max(timeout, grace + KILL_TIMEOUT_MARGIN_S) elif op == "start": wait_ready = request.get("wait_ready_s") wait_ready = ( self.manager.config.policy.wait_ready_s if wait_ready is None else float(wait_ready or 0) ) timeout = max(timeout, wait_ready + 1.0) try: response = await asyncio.wait_for(handler(request, caller), timeout=timeout) except TimeoutError: response = protocol.error("timeout", f"{op} did not complete within {timeout:g}s") except ManagerError as exc: response = protocol.error(exc.error, exc.reason, hint=exc.hint, **exc.fields) except PolicyError as exc: response = protocol.error(exc.error, exc.reason, hint=exc.hint) except (TypeError, ValueError) as exc: response = protocol.error("invalid_argument", str(exc)) except Exception as exc: log.exception("op %s failed", op) response = protocol.error("refused", f"internal error: {type(exc).__name__}") elapsed_ms = round((self.manager.clock.boottime() - started) * 1000, 3) response.setdefault("elapsed_ms", elapsed_ms) if isinstance(request_id, str): response["request_id"] = request_id if op in MUTATING_VERBS: self._remember(request_id, response) self.manager.audit.emit( "request", verb=op, session=request.get("id") or response.get("id"), caller=caller, ok=bool(response.get("ok")), error=response.get("error"), duration_ms=elapsed_ms, request_id=request_id if isinstance(request_id, str) else None, ) return response def _remember(self, request_id: str, response: dict[str, Any]) -> None: self._dedup[request_id] = dict(response) self._dedup.move_to_end(request_id) while len(self._dedup) > DEDUP_ENTRIES: self._dedup.popitem(last=False) # ------------------------------------------------------------------ # ops # ------------------------------------------------------------------ async def _op_ping(self, request: dict[str, Any], caller: dict[str, Any]) -> dict[str, Any]: from . import __version__ return protocol.ok( version=__version__, pid=os.getpid(), boottime=self.manager.now(), live=len(self.manager.registry.live()), ) async def _op_start(self, request: dict[str, Any], caller: dict[str, Any]) -> dict[str, Any]: record = await self.manager.start( request.get("app"), request.get("argv"), idle_timeout_s=request.get("idle_timeout_s"), wait_ready_s=request.get("wait_ready_s"), home=request.get("home"), ephemeral_home=bool(request.get("ephemeral_home", False)), ) return protocol.ok(id=record["id"], state=record["state"], session=record) async def _op_list(self, request: dict[str, Any], caller: dict[str, Any]) -> dict[str, Any]: return protocol.ok(**self.manager.list(include_tombstones=bool(request.get("all", False)))) async def _op_status(self, request: dict[str, Any], caller: dict[str, Any]) -> dict[str, Any]: record = self.manager.status(request.get("id"), events=int(request.get("events", 20))) return protocol.ok(id=record["id"], state=record["state"], session=record) async def _op_touch(self, request: dict[str, Any], caller: dict[str, Any]) -> dict[str, Any]: record = self.manager.touch(request.get("id")) return protocol.ok(id=record["id"], state=record["state"], session=record) async def _op_kill(self, request: dict[str, Any], caller: dict[str, Any]) -> dict[str, Any]: record = await self.manager.kill( request.get("id"), grace_s=request.get("grace_s"), sig=request.get("signal", "TERM"), ) return protocol.ok(id=record["id"], state=record["state"], session=record) async def _op_gc(self, request: dict[str, Any], caller: dict[str, Any]) -> dict[str, Any]: return protocol.ok(**self.manager.gc()) async def _op_adopt(self, request: dict[str, Any], caller: dict[str, Any]) -> dict[str, Any]: record = await self.manager.adopt( request.get("pid"), app=request.get("app"), idle_timeout_s=request.get("idle_timeout_s"), ) return protocol.ok(id=record["id"], state=record["state"], session=record) async def _op_logs(self, request: dict[str, Any], caller: dict[str, Any]) -> dict[str, Any]: return protocol.ok( **self.manager.logs( request.get("id"), lines=int(request.get("lines", 100)), offset=request.get("offset"), ) ) def _peer_credentials(writer: asyncio.StreamWriter) -> dict[str, Any]: """``SO_PEERCRED`` of the connecting process, for the audit log. M0 records who asked but does **not** authorise on it: the uid/gid allowlist is §8 item 2, which the brief holds out of this milestone. The socket's own mode and its directory are the access control here. """ sock = writer.get_extra_info("socket") if sock is None: return {} try: raw = sock.getsockopt(socket.SOL_SOCKET, socket.SO_PEERCRED, struct.calcsize("3i")) pid, uid, gid = struct.unpack("3i", raw) except OSError: return {} caller: dict[str, Any] = {"pid": pid, "uid": uid, "gid": gid} try: with open(f"/proc/{pid}/comm", encoding="utf-8") as fh: caller["comm"] = fh.read().strip() except OSError: pass return caller