gateway_runtime_replace.py 6.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141
  1. """Replace a gateway left running by an older Hermes on this install's own home.
  2. After an upgrade the old daemon keeps answering the home's control socket, but its ``identify`` has
  3. no ``runtime_protocol`` (it predates the session-authority runtime). Every client of this version
  4. ensures through :func:`hermes_cli.gateway_runtime.ensure_gateway_runtime` (the TUI bootstrap,
  5. Desktop's ``hermes gateway ensure``, ``hermes chat``), so ensure replaces that owner once, exactly as
  6. ``hermes gateway stop`` would stop it (a planned-stop marker in the owner's home, then SIGTERM; a
  7. bounded wait; a start-time-guarded force kill), and then starts the current one the normal way.
  8. Refused, never stopped:
  9. - a gateway that speaks a NEWER runtime protocol than this client (a downgrade must not kill it);
  10. - a gateway of another install: its home resolves outside this install's root (a profile symlinked
  11. into another HERMES root), or the process serves another home than the socket that answered;
  12. - anything whose ``identify`` cannot be pinned to one live process (pid/start time disagree, our
  13. own process, not a gateway).
  14. """
  15. from __future__ import annotations
  16. import os
  17. import time
  18. from pathlib import Path
  19. from typing import Any
  20. # Graceful drain before the guarded force kill; an idle old gateway exits in well under a second.
  21. _GRACEFUL_STOP_SECONDS = 10.0
  22. _FORCED_STOP_SECONDS = 5.0
  23. # One line each, short enough for the TUI's activity row after its "gateway incompatible: " prefix.
  24. REFUSAL_DETAIL = {
  25. "owner_newer": "a newer Hermes's gateway owns this profile; update Hermes or run: hermes gateway stop",
  26. "foreign_install": "another Hermes install's gateway owns this profile; stop it there: hermes gateway stop",
  27. "owner_unverified": "an older Hermes gateway owns this profile and was not verified; run: hermes gateway stop",
  28. "owner_did_not_exit": "an older Hermes gateway owns this profile and did not stop; run: hermes gateway stop",
  29. "owner_unreachable": "an older Hermes gateway owns this profile; run: hermes gateway stop",
  30. }
  31. def _install_root() -> Path:
  32. from hermes_constants import get_default_hermes_root
  33. return Path(get_default_hermes_root()).resolve()
  34. def _identify(home: Path, timeout: float) -> tuple[Path, dict] | None:
  35. """``(control_home, identify payload)`` of the process answering for *home*: its own socket, or
  36. the default multiplexer's for a served named profile (the same order discovery uses)."""
  37. from hermes_cli.gateway_runtime_discovery import query_identify
  38. from hermes_cli.gateway_runtime_multiplex import multiplexer_root_for
  39. for control in (home, multiplexer_root_for(home)):
  40. if control is None:
  41. continue
  42. try:
  43. return control, query_identify(control, timeout=timeout)
  44. except (FileNotFoundError, ConnectionRefusedError):
  45. continue
  46. return None
  47. def _same(a: Any, b: Path) -> bool:
  48. try:
  49. return os.path.normcase(str(Path(a).resolve())) == os.path.normcase(str(b.resolve()))
  50. except (OSError, TypeError, ValueError):
  51. return False
  52. def _within_install(home: Path, root: Path) -> bool:
  53. home = home.resolve()
  54. return home == root or (home.parent == root / "profiles")
  55. def _verified_owner(control: Path, payload: dict) -> tuple[int, Any] | str:
  56. from gateway.status import _GATEWAY_KIND, _pid_exists, get_process_start_time, start_time_fingerprints_match
  57. protocol = payload.get("runtime_protocol")
  58. if type(protocol) is int and protocol > 1:
  59. return "owner_newer"
  60. if not _within_install(control, _install_root()) or not _same(payload.get("hermes_home"), control):
  61. return "foreign_install"
  62. pid, recorded = payload.get("pid"), payload.get("start_time")
  63. if (payload.get("kind") != _GATEWAY_KIND or type(pid) is not int or pid <= 1
  64. or pid in {os.getpid(), os.getppid()} or recorded is None or not _pid_exists(pid)):
  65. return "owner_unverified"
  66. current = get_process_start_time(pid)
  67. try:
  68. if current is None or not start_time_fingerprints_match(recorded, current):
  69. return "owner_unverified"
  70. except (TypeError, ValueError):
  71. return "owner_unverified"
  72. return pid, current
  73. def _write_planned_stop(control: Path, pid: int, start_time: Any) -> None:
  74. """The marker ``hermes gateway stop`` writes, in the OWNER's home (it reads its own), so the old
  75. gateway exits as a planned stop: clean exit, ``stopped`` persisted, no supervisor revival."""
  76. from gateway.status import _PLANNED_STOP_MARKER_FILENAME, _utc_now_iso, _write_marker
  77. _write_marker(control / _PLANNED_STOP_MARKER_FILENAME, {
  78. "target_pid": pid, "target_start_time": start_time,
  79. "stopper_pid": os.getpid(), "written_at": _utc_now_iso(),
  80. })
  81. def _wait_gone(pid: int, seconds: float) -> bool:
  82. from gateway.status import _pid_exists
  83. end = time.monotonic() + max(seconds, 0.0)
  84. while _pid_exists(pid):
  85. if time.monotonic() >= end:
  86. return False
  87. time.sleep(0.1)
  88. return True
  89. def replace_incompatible_owner(home: Path, *, deadline: float) -> str | None:
  90. """Stop the older-Hermes gateway answering for *home*; None once it is gone, else a refusal code
  91. (see :data:`REFUSAL_DETAIL`). Never starts anything: the caller's ensure loop does that."""
  92. from gateway.status import terminate_pid
  93. budget = deadline - time.monotonic()
  94. if budget <= 0:
  95. return "owner_unreachable"
  96. try:
  97. found = _identify(home, timeout=min(2.0, budget))
  98. except (OSError, ValueError, TypeError): # timeout, refused/denied peer, malformed reply
  99. return "owner_unreachable"
  100. if found is None:
  101. return None # it is already gone: nothing to replace
  102. control, payload = found
  103. verdict = _verified_owner(control, payload)
  104. if isinstance(verdict, str):
  105. return verdict
  106. pid, start_time = verdict
  107. _write_planned_stop(control, pid, start_time)
  108. graceful = min(_GRACEFUL_STOP_SECONDS, max(deadline - time.monotonic() - _FORCED_STOP_SECONDS, 1.0))
  109. try:
  110. if os.name != "nt":
  111. # Windows has no SIGTERM for an asyncio loop: the marker watcher IS its graceful stop.
  112. terminate_pid(pid, expected_start_time=start_time)
  113. if _wait_gone(pid, graceful):
  114. return None
  115. terminate_pid(pid, force=True, expected_start_time=start_time)
  116. except ProcessLookupError:
  117. return None
  118. except (PermissionError, OSError):
  119. return "owner_did_not_exit" if not _wait_gone(pid, 0) else None
  120. return None if _wait_gone(pid, _FORCED_STOP_SECONDS) else "owner_did_not_exit"