gateway_runtime_service.py 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296
  1. """Non-installing service-manager operations for an explicit canonical profile.
  2. The legacy start helpers refresh units, regenerate plists, or fall back to
  3. unmanaged processes. Client startup must not call those helpers.
  4. """
  5. from __future__ import annotations
  6. import csv
  7. from dataclasses import dataclass
  8. import hashlib
  9. import io
  10. import os
  11. from pathlib import Path
  12. import plistlib
  13. import subprocess
  14. import sys
  15. import time
  16. from xml.parsers.expat import ExpatError
  17. from gateway.runtime_contract import RuntimeState
  18. from hermes_cli._subprocess_compat import windows_hide_flags
  19. class RuntimeStartError(RuntimeError):
  20. def __init__(self, reason: str, state: RuntimeState = "inaccessible"):
  21. super().__init__(reason)
  22. self.reason, self.state = reason, state
  23. def remaining(deadline: float) -> float:
  24. budget = deadline - time.monotonic()
  25. if budget <= 0:
  26. raise TimeoutError
  27. return budget
  28. def service_suffix(home: Path) -> str:
  29. """Host-service suffix for the REQUESTED home, never the initiating client's env.
  30. Same rule as ``hermes_cli.gateway._profile_suffix``: only the platform-native
  31. default home owns the bare unit name; ``<root>/profiles/<name>`` yields the
  32. profile name; any other root (Docker, a temp harness) yields a path hash so a
  33. custom root can never resolve to the production ``hermes-gateway`` unit.
  34. """
  35. from hermes_constants import account_default_hermes_home
  36. from hermes_cli.gateway import _profile_name_from_home
  37. default = account_default_hermes_home().resolve()
  38. home = home.resolve()
  39. if home == default:
  40. return ""
  41. root = default
  42. if not home.is_relative_to(default):
  43. root = home.parent.parent if home.parent.name == "profiles" else home
  44. if home != root:
  45. name = _profile_name_from_home(home, root)
  46. if name:
  47. return name
  48. return hashlib.sha256(str(home).encode()).hexdigest()[:8]
  49. @dataclass(frozen=True)
  50. class ExistingService:
  51. backend: str
  52. start_argv: tuple[str, ...]
  53. running: bool = False
  54. def _run(argv: list[str] | tuple[str, ...], deadline: float, *, encoding: str | None = "utf-8"):
  55. return subprocess.run(argv, stdin=subprocess.DEVNULL, capture_output=True,
  56. text=encoding is not None, encoding=encoding, errors="strict" if encoding else None,
  57. creationflags=windows_hide_flags(), timeout=remaining(deadline), check=False)
  58. def _verify_binding(verify, *args, **kwargs):
  59. try:
  60. return verify(*args, **kwargs)
  61. except (ValueError, TypeError, KeyError, AttributeError, ExpatError) as exc:
  62. reason = str(exc)
  63. raise RuntimeStartError(reason if reason in {
  64. "profile_mismatch", "service_account_mismatch", "service_disabled"
  65. } else "service_identity_unverified") from None
  66. def _exists(path: Path) -> bool:
  67. try:
  68. path.lstat()
  69. return True
  70. except FileNotFoundError:
  71. return False
  72. def _systemd(home: Path, deadline: float) -> ExistingService | None:
  73. from hermes_cli import gateway as gw
  74. from hermes_cli.service_manager import _s6_running
  75. from hermes_cli.gateway_runtime_service_identity import ForeignRoot, SYSTEMD_IDENTITY_PROPERTIES, verify_systemd
  76. if _s6_running():
  77. raise RuntimeStartError("external_supervisor")
  78. suffix = service_suffix(home)
  79. unit = f"hermes-gateway{'-' + suffix if suffix else ''}.service"
  80. paths = (Path.home() / ".config/systemd/user" / unit, Path("/etc/systemd/system") / unit)
  81. # On non-systemd hosts there is no manager to own transient units. Installed
  82. # definitions still count: a broken manager is not permission to bypass one.
  83. # Every Hermes entrypoint ensures the gateway, so a host with no installed unit must not
  84. # touch the service manager at all (a headless runner has no user bus to answer it).
  85. # With a unit installed anywhere, both scopes are asked: two claiming the name is a conflict.
  86. installed = (*paths, Path("/usr/lib/systemd/system") / unit, Path("/lib/systemd/system") / unit)
  87. if not any(_exists(p) for p in installed):
  88. return None
  89. found = []
  90. for system in (False, True):
  91. command = gw._systemctl_cmd(system)
  92. result = _run([*command, "show", unit, "--no-pager", "--all",
  93. "--property=LoadState,ActiveState,SubState,UnitFileState," + ",".join(SYSTEMD_IDENTITY_PROPERTIES)], deadline)
  94. props = dict(line.split("=", 1) for line in result.stdout.splitlines() if "=" in line)
  95. if not _exists(paths[int(system)]) and (result.returncode or props.get("LoadState") == "not-found"):
  96. # Nothing installed in this scope: an unreachable or empty manager there has no
  97. # unit that could serve or block this home.
  98. continue
  99. if result.returncode or props.get("LoadState") != "loaded":
  100. raise RuntimeStartError("service_manager_unavailable")
  101. if props.get("UnitFileState") in {"masked", "masked-runtime"}:
  102. raise RuntimeStartError("service_masked")
  103. state = props.get("ActiveState")
  104. if state == "deactivating":
  105. raise RuntimeStartError("service_draining", "draining")
  106. if state not in {"inactive", "active", "activating", "reloading", "failed"}:
  107. raise RuntimeStartError("service_state_unknown")
  108. if state == "failed":
  109. raise RuntimeStartError("service_failed")
  110. environment = _run([*command, "show-environment"], deadline)
  111. if environment.returncode:
  112. raise RuntimeStartError("service_identity_unverified")
  113. try:
  114. verify_systemd(props, environment.stdout, home, system=system)
  115. except ForeignRoot:
  116. # A unit named like ours but pinned to another HOME root belongs to a
  117. # different install (a sandbox HOME beside a real one); it neither serves
  118. # nor blocks this home.
  119. continue
  120. except ValueError as exc:
  121. reason = str(exc)
  122. raise RuntimeStartError(reason if reason in {
  123. "profile_mismatch", "service_account_mismatch"
  124. } else "service_identity_unverified") from None
  125. found.append(ExistingService("systemd", tuple([*command, "--no-ask-password", "start", unit]),
  126. state != "inactive"))
  127. if len(found) > 1:
  128. raise RuntimeStartError("service_scope_conflict", "conflict")
  129. return found[0] if found else None
  130. def _s6(home: Path, deadline: float) -> ExistingService | None:
  131. """Find the container gateway slot that owns ``home``.
  132. TUI clients call ``ensure_gateway_runtime`` inside the Docker image too.
  133. They must request that s6 starts the registered slot, rather than falling
  134. through the Linux systemd probe and treating s6 as inaccessible.
  135. """
  136. from hermes_cli.service_manager import S6ServiceManager
  137. from hermes_cli.gateway_runtime_multiplex import implied_host_root
  138. # with-contenv is also the service run script's authority. The initiating
  139. # client may have selected a named profile or a different install root.
  140. try:
  141. container_home = Path("/run/s6/container_environment/HERMES_HOME").read_text(encoding="utf-8-sig").strip()
  142. except (OSError, UnicodeError):
  143. raise RuntimeStartError("service_identity_unverified") from None
  144. if not container_home:
  145. raise RuntimeStartError("service_identity_unverified")
  146. root = Path(container_home).resolve()
  147. home = home.resolve()
  148. if home != root and home.parent != root / "profiles":
  149. raise RuntimeStartError("profile_mismatch")
  150. # A normal named profile belongs to the root multiplexer. Returning None
  151. # lets ensure select its host, including a first boot with no saved verdict.
  152. if home != root and implied_host_root(home) == root:
  153. return None
  154. profile = "default" if home == root else home.name
  155. manager = S6ServiceManager()
  156. service_name = f"gateway-{profile}"
  157. if not (manager.scandir / service_name).is_dir():
  158. raise RuntimeStartError("service_manager_unavailable")
  159. return ExistingService("s6", (service_name,), manager.is_running(service_name))
  160. def _launchd(home: Path, deadline: float) -> ExistingService | None:
  161. import pwd
  162. suffix = service_suffix(home)
  163. label = f"ai.hermes.gateway{'-' + suffix if suffix else ''}"
  164. account = pwd.getpwuid(os.getuid()) # windows-footgun: ok — native launchd only
  165. account_home = Path(account.pw_dir)
  166. plist = account_home / "Library/LaunchAgents" / f"{label}.plist"
  167. from hermes_cli.gateway_runtime_service_identity import verify_launchd_loaded, verify_launchd_plist, read_definition
  168. installed = _exists(plist)
  169. domains = [f"gui/{os.getuid()}", f"user/{os.getuid()}"] # windows-footgun: ok — native launchd only
  170. found = []
  171. loaded = []
  172. for domain in domains:
  173. result = _run(["launchctl", "print", f"{domain}/{label}"], deadline)
  174. if result.returncode == 0:
  175. loaded.append(result.stdout)
  176. found.append(ExistingService("launchd", ("launchctl", "kickstart", f"{domain}/{label}"),
  177. "state = running" in result.stdout))
  178. continue
  179. # launchctl's native absent-service code; other errors retain uncertainty.
  180. if result.returncode != 113:
  181. raise RuntimeStartError("service_manager_unavailable")
  182. if len(found) > 1:
  183. raise RuntimeStartError("service_scope_conflict", "conflict")
  184. if found:
  185. _verify_binding(verify_launchd_loaded, loaded[0], home, uid=os.getuid(), username=account.pw_name) # windows-footgun: ok — native launchd only
  186. return found[0]
  187. if installed:
  188. definition = _verify_binding(plistlib.loads, read_definition(plist))
  189. _verify_binding(verify_launchd_plist, definition, label, home)
  190. # Load ONLY the existing file, never bootout/rewrite or kickstart -k.
  191. return ExistingService("launchd", ("launchctl", "bootstrap", domains[0], str(plist)))
  192. return None
  193. def _windows(home: Path, deadline: float) -> ExistingService | None:
  194. from hermes_cli.gateway_windows import _decode_schtasks_output
  195. suffix = service_suffix(home)
  196. name = f"Hermes_Gateway{'_' + suffix if suffix else ''}"
  197. def query(refusal: str, *argv: str) -> str:
  198. # schtasks/whoami write the console code page, and /XML declares UTF-16 over those bytes:
  199. # decode like the drift check does (#116193) instead of the locale codec or raw bytes (#139083).
  200. result = _run(list(argv), deadline, encoding=None)
  201. if result.returncode:
  202. raise RuntimeStartError(refusal)
  203. return _decode_schtasks_output(result.stdout or b"")
  204. rows = csv.reader(io.StringIO(query("service_manager_unavailable", "schtasks.exe", "/Query", "/FO", "CSV", "/NH")))
  205. # Orphaned TaskCache entries print localized one-field diagnostics among the rows (#142140). Only a
  206. # well-formed row can name our task, so skipping the rest can only fall through to the unmanaged path.
  207. if any(len(row) == 3 and row[0].lstrip("\\") == name for row in rows):
  208. from hermes_cli.gateway_runtime_service_identity import verify_windows_task
  209. unverified = "service_identity_unverified"
  210. definition = query(unverified, "schtasks.exe", "/Query", "/TN", name, "/XML")
  211. accounts = list(csv.reader(io.StringIO(query(unverified, "whoami.exe", "/USER", "/FO", "CSV", "/NH"))))
  212. if len(accounts) != 1 or len(accounts[0]) != 2:
  213. raise RuntimeStartError("service_identity_unverified")
  214. _verify_binding(verify_windows_task, definition, home, *accounts[0])
  215. return ExistingService("windows", ("schtasks.exe", "/Run", "/TN", name))
  216. # A Startup-folder entry (the fallback when Scheduled Task install was declined/blocked) is login
  217. # persistence only, with no start verb or identity to verify. Starting a stopped owner is the
  218. # same detached direct spawn manual `hermes gateway start` uses beside it; the unmanaged path
  219. # pins the explicit home and refuses a job-bound (no-breakaway) child, and the runtime lock
  220. # plus host attach arbitrate against the entry firing again at the next login.
  221. return None
  222. def _no_supervisor(home: Path, deadline: float) -> None:
  223. """Android/Termux has no service manager (main refuses `gateway install/start` there and says
  224. "Run manually: hermes gateway"): an unmanaged detached start is its only owner. Python 3.13+
  225. reports ``sys.platform == "android"``; older Termux interpreters report linux and reach the
  226. systemd probe, which finds no unit and lands on the same unmanaged start."""
  227. def discover_existing_gateway_service(home: Path, *, deadline: float) -> ExistingService | None:
  228. from hermes_cli.service_manager import _s6_running
  229. backend = _s6 if _s6_running() else {"linux": _systemd, "darwin": _launchd, "win32": _windows,
  230. "android": _no_supervisor}.get(sys.platform)
  231. if backend is None:
  232. raise RuntimeStartError("unsupported_supervisor_platform")
  233. try:
  234. return backend(home, deadline)
  235. except subprocess.TimeoutExpired:
  236. raise TimeoutError from None
  237. except (OSError, ValueError) as exc:
  238. raise RuntimeStartError("service_manager_unavailable") from exc
  239. def start_existing_gateway_service(service: ExistingService, *, deadline: float) -> None:
  240. """Request start once; only live control readiness can establish success."""
  241. if service.running:
  242. return
  243. if service.backend == "s6":
  244. from hermes_cli.service_manager import S6ServiceManager
  245. try:
  246. S6ServiceManager().start(service.start_argv[0])
  247. except subprocess.TimeoutExpired:
  248. raise TimeoutError from None
  249. except (OSError, RuntimeError, ValueError) as exc:
  250. raise RuntimeStartError("service_start_failed") from exc
  251. return
  252. try:
  253. result = _run(service.start_argv, deadline, encoding=None)
  254. except subprocess.TimeoutExpired:
  255. raise TimeoutError from None
  256. except OSError as exc:
  257. raise RuntimeStartError("service_start_failed") from exc
  258. if result.returncode:
  259. raise RuntimeStartError("service_start_failed")