"""Gateway control socket — the gateway-owned local coordination surface. Instead of process-table scans or ``gateway_state.json`` (which can outlive its writer), the gateway serves a local-only socket answering versioned JSON verbs (``identify``, ``status``). A connectable socket with a well-formed ``identify`` answer IS liveness — no PID-reuse heuristics. Transport — never a TCP port; filesystem/pipe ACLs are the auth boundary. POSIX: ``$HERMES_HOME/gateway.sock``, or a temp-dir socket plus a ``gateway.sock.path`` pointer file when the home path exceeds ``sun_path``. Windows: named pipe ``\\\\.\\pipe\\hermes-gateway-``. Wire contract: ONE request per connection — one JSON line in, one out, then the server closes (no keep-alive/pipelining). Consumers PREFER the socket and fall back to the state-file/scan layer when it doesn't answer. """ from __future__ import annotations import asyncio import contextlib import hashlib import json import logging import os import socket import sys import tempfile import time from pathlib import Path from typing import Any, Callable, Optional logger = logging.getLogger(__name__) CONTROL_PROTOCOL_VERSION = 1 _SOCKET_FILENAME = "gateway.sock" _POINTER_FILENAME = "gateway.sock.path" _IS_WINDOWS = sys.platform == "win32" # sun_path limit is 104 on macOS/BSD, 108 on Linux; leave margin for the NUL. _MAX_UNIX_PATH = 100 # Single-line JSON in/out; bounded so a misbehaving peer can't balloon memory. _MAX_REQUEST_BYTES = 64 * 1024 _MAX_RESPONSE_BYTES = 512 * 1024 _DEFAULT_CLIENT_TIMEOUT = 2.0 # --------------------------------------------------------------------------- # Path resolution (shared by server and client) # --------------------------------------------------------------------------- def _home_hash(home: Path) -> str: canonical = os.path.normcase(str(Path(home).expanduser().resolve(strict=False))) return hashlib.sha256(canonical.encode("utf-8")).hexdigest()[:16] def windows_pipe_name(home: Path) -> str: """Per-HERMES_HOME named pipe path (Windows transport).""" return rf"\\.\pipe\hermes-gateway-{_home_hash(home)}" def _fits_sun_path(path: Path) -> bool: return len(str(path).encode("utf-8")) <= _MAX_UNIX_PATH def _fallback_socket_path(home: Path) -> Path: """Short temp-dir path for homes whose direct socket path exceeds sun_path. Tries ``tempfile.gettempdir()`` then ``/tmp`` (POSIX). If nothing fits the tempdir candidate is returned anyway — bind fails non-fatally and consumers use the scan layer. """ name = f"hermes-gw-{_home_hash(home)}.sock" candidates = [Path(tempfile.gettempdir()) / name] if not _IS_WINDOWS: candidates.append(Path("/tmp") / name) for candidate in candidates: if _fits_sun_path(candidate): return candidate return candidates[0] def resolve_server_socket_path(home: Path) -> tuple[Path, Optional[Path]]: """Return ``(bind_path, pointer_file)``; pointer_file is non-None only when the temp-dir fallback is in use and the server must record it.""" direct = Path(home) / _SOCKET_FILENAME if _fits_sun_path(direct): return direct, None return _fallback_socket_path(home), Path(home) / _POINTER_FILENAME def resolve_client_socket_path(home: Path) -> Optional[Path]: """Where a client should connect for ``home``, or None when nothing exists.""" direct = Path(home) / _SOCKET_FILENAME if direct.exists(): return direct pointer = Path(home) / _POINTER_FILENAME try: if pointer.is_file(): target = pointer.read_text(encoding="utf-8").strip() if target and Path(target).exists(): return Path(target) except OSError: pass return None # --------------------------------------------------------------------------- # Default payload builders (import-light; overridable at wiring time) # --------------------------------------------------------------------------- def _detect_supervisor() -> str: """Supervisor kind for THIS process, declared from its own launch env (not inferred outside-in like ``_detect_supervisor_for_pid``).""" env = os.environ if env.get("INVOCATION_ID"): return "systemd" if sys.platform == "darwin" and ( env.get("XPC_SERVICE_NAME", "").startswith("ai.hermes") or env.get("LAUNCHD_SOCKET") ): return "launchd" if env.get("HERMES_DESKTOP_MANAGED"): return "desktop" if "--external-supervisor" in sys.argv: return "external" return "manual" def build_identify_payload() -> dict[str, Any]: """Default ``identify`` answer, built from gateway.status primitives.""" from gateway.status import ( _build_pid_record, _get_code_identity_fields, _profile_label_for_home, read_runtime_status, ) record = _build_pid_record() payload: dict[str, Any] = { "protocol": CONTROL_PROTOCOL_VERSION, **{k: record.get(k) for k in ("kind", "pid", "start_time", "hermes_home")}, "profile": _profile_label_for_home(record.get("hermes_home") or ""), "supervisor": _detect_supervisor(), } payload.update(_get_code_identity_fields()) # served_profiles (multiplex mode) is stamped into runtime status by the runner. try: served = (read_runtime_status() or {}).get("served_profiles") if isinstance(served, list) and served: payload["served_profiles"] = served except Exception: pass return payload def build_status_payload() -> dict[str, Any]: """Default ``status`` answer — current runtime status, answered live.""" from gateway.status import read_runtime_status payload = dict(read_runtime_status() or {}) payload["protocol"] = CONTROL_PROTOCOL_VERSION payload["answered_at"] = time.time() payload["answering_pid"] = os.getpid() return payload # --------------------------------------------------------------------------- # Server # --------------------------------------------------------------------------- class GatewayControlServer: """Gateway-owned control socket server (identify/status, v1). ``start()`` after the PID-file claim, ``stop()`` on shutdown. All failures are non-fatal — the gateway never refuses to serve messaging because its control socket couldn't bind; consumers fall back to the scan layer. """ def __init__( self, home: Optional[Path] = None, *, verb_handlers: Optional[dict[str, Callable[[], dict[str, Any]]]] = None, ) -> None: if home is None: from gateway.status import _get_process_hermes_home home = _get_process_hermes_home() self._home = Path(home) self._server: Optional[asyncio.AbstractServer] = None self._pipe_server: Any = None # Windows proactor pipe server self._bind_path: Optional[Path] = None self._pointer_file: Optional[Path] = None self._handlers: dict[str, Callable[[], dict[str, Any]]] = { "identify": build_identify_payload, "status": build_status_payload, } if verb_handlers: self._handlers.update(verb_handlers) # -- lifecycle --------------------------------------------------------- async def start(self) -> bool: """Bind and start serving. Returns True on success, False otherwise.""" try: if _IS_WINDOWS: return await self._start_windows() return await self._start_posix() except Exception as exc: logger.warning("Gateway control socket failed to start (non-fatal): %s", exc) return False async def _start_posix(self) -> bool: bind_path, pointer_file = resolve_server_socket_path(self._home) # We only get here after winning the PID-file O_EXCL race, so any # existing file is stale or a collision — never a live sibling. with contextlib.suppress(OSError): if bind_path.exists(): bind_path.unlink() # Restrictive umask so the socket is never world-connectable, even # for the instant before chmod. old_umask = os.umask(0o177) try: self._server = await asyncio.start_unix_server(self._handle_connection, path=str(bind_path)) finally: os.umask(old_umask) with contextlib.suppress(OSError): os.chmod(bind_path, 0o600) self._bind_path = bind_path if pointer_file is not None: pointer_file.write_text(str(bind_path), encoding="utf-8") self._pointer_file = pointer_file logger.info("Gateway control socket listening at %s", bind_path) return True async def _start_windows(self) -> bool: loop = asyncio.get_running_loop() start_serving_pipe = getattr(loop, "start_serving_pipe", None) if start_serving_pipe is None: logger.debug( "Event loop %s has no start_serving_pipe — control socket " "disabled (selector loop on Windows).", type(loop).__name__, ) return False pipe_name = windows_pipe_name(self._home) servers = await start_serving_pipe(lambda: _PipeControlProtocol(self), pipe_name) self._pipe_server = servers[0] if servers else None logger.info("Gateway control pipe listening at %s", pipe_name) return self._pipe_server is not None async def stop(self) -> None: """Stop serving and remove the socket/pointer files.""" if self._server is not None: self._server.close() with contextlib.suppress(Exception): await self._server.wait_closed() self._server = None if self._pipe_server is not None: with contextlib.suppress(Exception): self._pipe_server.close() self._pipe_server = None self.cleanup_files() def cleanup_files(self) -> None: """Best-effort removal of socket + pointer files (atexit-safe).""" for path in (self._bind_path, self._pointer_file): if path is not None: with contextlib.suppress(OSError): path.unlink(missing_ok=True) # -- request handling ---------------------------------------------------- def handle_request_line(self, raw: bytes) -> bytes: """One JSON request line -> one JSON response line. Never raises. Shared by the POSIX stream handler and the Windows pipe protocol. """ request_id: Any = None try: request = json.loads(raw.decode("utf-8")) if not isinstance(request, dict): raise ValueError("request must be a JSON object") request_id = request.get("id") verb = request.get("verb") handler = self._handlers.get(verb) if isinstance(verb, str) else None if handler is None: response: dict[str, Any] = { "ok": False, "error": f"unknown verb: {verb!r}", "protocol": CONTROL_PROTOCOL_VERSION, "supported_verbs": sorted(self._handlers), } else: response = {"ok": True, "protocol": CONTROL_PROTOCOL_VERSION, "result": handler()} except Exception as exc: response = { "ok": False, "error": f"{type(exc).__name__}: {exc}", "protocol": CONTROL_PROTOCOL_VERSION, } if request_id is not None: response["id"] = request_id try: encoded = json.dumps(response, default=str).encode("utf-8") except Exception: encoded = b'{"ok": false, "error": "response serialization failed"}' if len(encoded) > _MAX_RESPONSE_BYTES: encoded = b'{"ok": false, "error": "response too large"}' return encoded + b"\n" async def _handle_connection(self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None: try: raw = await asyncio.wait_for(reader.readline(), timeout=_DEFAULT_CLIENT_TIMEOUT) if not raw or len(raw) > _MAX_REQUEST_BYTES: return # Handlers read disk; keep that off the loop that drives every # platform adapter so a fast-polling consumer can't stall heartbeats. loop = asyncio.get_running_loop() response = await loop.run_in_executor(None, self.handle_request_line, raw.rstrip(b"\n")) writer.write(response) await writer.drain() except (asyncio.TimeoutError, ConnectionError, OSError): pass except Exception: logger.debug("Control socket connection handler error", exc_info=True) finally: with contextlib.suppress(Exception): writer.close() class _PipeControlProtocol(asyncio.Protocol): """One-shot request/response protocol for the Windows named pipe.""" def __init__(self, server: GatewayControlServer) -> None: self._server = server self._transport: Any = None self._buffer = bytearray() def connection_made(self, transport) -> None: # pragma: no cover - windows self._transport = transport def data_received(self, data: bytes) -> None: # pragma: no cover - windows self._buffer.extend(data) if len(self._buffer) > _MAX_REQUEST_BYTES: self._transport.close() return if b"\n" in self._buffer: line, _, _ = bytes(self._buffer).partition(b"\n") try: self._transport.write(self._server.handle_request_line(line)) finally: self._transport.close() # --------------------------------------------------------------------------- # Client (synchronous — used by CLI/updater consumers) # --------------------------------------------------------------------------- def query_gateway_control( home: Path, verb: str, *, timeout: float = _DEFAULT_CLIENT_TIMEOUT ) -> Optional[dict[str, Any]]: """Ask the gateway serving ``home`` a control verb; None when unanswered. Returns the verb's ``result`` payload. Any failure (no/stale socket, timeout, malformed answer, ``ok: false``) returns None so callers fall back to the scan layer. Never raises. """ request = json.dumps({"verb": verb, "id": 1, "protocol": CONTROL_PROTOCOL_VERSION}).encode("utf-8") + b"\n" query = _query_windows_pipe if _IS_WINDOWS else _query_unix_socket try: raw = query(Path(home), request, timeout) except Exception: return None if not raw: return None try: response = json.loads(raw.decode("utf-8")) except (ValueError, UnicodeDecodeError): return None if not isinstance(response, dict) or response.get("ok") is not True: return None result = response.get("result") return result if isinstance(result, dict) else None def _read_response_line(read: Callable[[], bytes], deadline: float) -> Optional[bytes]: """Read chunks until a newline, EOF, deadline, or the size cap (-> None).""" chunks: list[bytes] = [] while time.monotonic() < deadline: chunk = read() if not chunk: break chunks.append(chunk) if b"\n" in chunk: break if sum(len(c) for c in chunks) > _MAX_RESPONSE_BYTES: return None line, _, _ = b"".join(chunks).partition(b"\n") return line or None def _query_unix_socket(home: Path, request: bytes, timeout: float) -> Optional[bytes]: path = resolve_client_socket_path(home) if path is None: return None with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as sock: sock.settimeout(timeout) try: sock.connect(str(path)) except (ConnectionRefusedError, FileNotFoundError, OSError): return None sock.sendall(request) try: return _read_response_line(lambda: sock.recv(65536), time.monotonic() + timeout) except socket.timeout: return None def _query_windows_pipe(home: Path, request: bytes, timeout: float) -> Optional[bytes]: # pragma: no cover - wine2e lane pipe_name = windows_pipe_name(home) deadline = time.monotonic() + timeout handle = None while handle is None: try: handle = open(pipe_name, "r+b", buffering=0) except FileNotFoundError: return None except OSError: # Pipe busy (another client mid-handshake) — brief retry window. if time.monotonic() >= deadline: return None time.sleep(0.05) try: handle.write(request) return _read_response_line(lambda: handle.read(65536), deadline) finally: with contextlib.suppress(Exception): handle.close() def identify_gateway(home: Path, *, timeout: float = _DEFAULT_CLIENT_TIMEOUT) -> Optional[dict[str, Any]]: """Convenience wrapper: ``identify`` the gateway serving ``home``.""" return query_gateway_control(home, "identify", timeout=timeout) def pause_gateway_for_update(home: Path, *, timeout: float = _DEFAULT_CLIENT_TIMEOUT) -> Optional[dict[str, Any]]: """Ask the gateway serving ``home`` to drain and exit for an update. Returns the ACK ``{"pausing", "already_stopping", "pid", "drain_timeout"}`` or None when no gateway answers (old gateway without the verb, no/dead socket) — the caller then uses the legacy signal/tree-kill pause path. """ return query_gateway_control(home, "pause-for-update", timeout=timeout)