boot_bootstrap.py 8.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247
  1. """Bounded home maintenance after an installed revision changes.
  2. A per-install, per-profile record and lock remain because config migrations
  3. must not retry a broken migration on every launch, and the full SQLite
  4. integrity guard is too expensive to run every time. Steps still own their
  5. idempotence and rollback; failure is recorded until the next revision (or
  6. an explicit post-update run). PM owns runtime diagnosis, not this record.
  7. """
  8. from __future__ import annotations
  9. from pm.environments import install_state_dir
  10. import json
  11. import logging
  12. import os
  13. import subprocess
  14. import time
  15. from pathlib import Path
  16. logger = logging.getLogger(__name__)
  17. RECORD_SCHEMA_VERSION = 1
  18. LOCK_STALE_SECONDS = 600
  19. # ---------------------------------------------------------------------------
  20. # current identity
  21. # ---------------------------------------------------------------------------
  22. def read_git_head(root: Path) -> str | None:
  23. """The commit SHA of the checkout at ``root``.
  24. Asks git, rather than reimplementing it: parsing ``.git`` by hand
  25. (worktree gitfiles, symbolic HEAD, packed-refs, commondir) is a
  26. reimplementation of ``git rev-parse HEAD`` that reftable breaks
  27. wholesale. The managed git comes first, a PATH git second; with
  28. neither, the answer is None and boot carries on — fail-open.
  29. Cost: one ~10ms subprocess. Only checkouts pay it — a sealed tree
  30. reads its stamp and never gets here — and it happens once per boot.
  31. """
  32. git = _git_binary()
  33. if git is None:
  34. return None
  35. try:
  36. out = subprocess.run(
  37. [git, "-C", str(root), "rev-parse", "HEAD"],
  38. capture_output=True,
  39. text=True, encoding="utf-8", errors="replace",
  40. timeout=10,
  41. check=False,
  42. )
  43. except (OSError, subprocess.SubprocessError):
  44. return None
  45. if out.returncode != 0:
  46. return None
  47. sha = out.stdout.strip()
  48. return sha if len(sha) >= 7 else None
  49. def _git_binary() -> str | None:
  50. """The git to run, or None when this machine has no usable one.
  51. pm's pinned git first (the win32 Git-for-Windows package — where it
  52. is installed, it is the one whose bash contract the rest of the tree
  53. already trusts), then a PATH git. The imports are local: this module
  54. is loaded early enough that a module-level import would widen the
  55. boot import graph for a lookup most platforms answer from PATH.
  56. """
  57. try:
  58. from pm import installed_package
  59. installed = installed_package("git")
  60. if installed is not None and installed.binary is not None:
  61. return str(installed.binary)
  62. except Exception as exc:
  63. logger.debug("pm git lookup failed: %s", exc)
  64. import shutil
  65. return shutil.which("git")
  66. def current_install_identity(project_root: Path) -> str | None:
  67. """What code this install is: stamp commit for sealed trees, git HEAD
  68. for checkouts, None for broken trees (never bootstrap, never write)."""
  69. from hermes_cli.steward import read_install_stamp
  70. root = Path(project_root)
  71. if (root / ".git").exists():
  72. return read_git_head(root)
  73. stamp = read_install_stamp(root)
  74. commit = stamp.get("commit")
  75. if isinstance(commit, str) and len(commit) >= 7:
  76. return commit
  77. # A tagless/commitless stamp is a broken artifact; the tag alone is
  78. # accepted as a weaker identity (bundled artifacts always carry one).
  79. tag = stamp.get("tag")
  80. return tag if isinstance(tag, str) and tag else None
  81. # ---------------------------------------------------------------------------
  82. # the per-install state folder: installs/<SHA16>/ under the DEFAULT home
  83. # ---------------------------------------------------------------------------
  84. def record_path(project_root: Path) -> Path:
  85. """Each profile completes its own home maintenance for this installation."""
  86. from hermes_cli.profiles import get_active_profile_name
  87. name = get_active_profile_name() or "default"
  88. return install_state_dir(project_root) / "bootstrap" / f"{name}.json"
  89. def read_last_known(path: Path) -> dict:
  90. try:
  91. data = json.loads(Path(path).read_text(encoding="utf-8-sig"))
  92. except (OSError, ValueError):
  93. return {}
  94. return data if isinstance(data, dict) else {}
  95. def _write_record(path: Path, identity: str, results: dict) -> None:
  96. payload = {
  97. "schemaVersion": RECORD_SCHEMA_VERSION,
  98. "identity": identity,
  99. "bootstrappedAt": time.strftime("%Y-%m-%dT%H:%M:%S%z"),
  100. "results": results,
  101. }
  102. path.parent.mkdir(parents=True, exist_ok=True)
  103. tmp = path.with_name(path.name + ".tmp")
  104. tmp.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
  105. os.replace(tmp, path)
  106. def needs_bootstrap(project_root: Path) -> str | None:
  107. """The new identity when this install changed since its last bootstrap,
  108. else None. None identity (broken tree) never bootstraps."""
  109. identity = current_install_identity(project_root)
  110. if not identity:
  111. return None
  112. known = read_last_known(record_path(project_root))
  113. if known.get("identity") == identity:
  114. return None
  115. return identity
  116. # ---------------------------------------------------------------------------
  117. # single-flight lock
  118. # ---------------------------------------------------------------------------
  119. class _RecordLock:
  120. """O_CREAT|O_EXCL existence-as-mutex next to a record file.
  121. Losers skip (boot never waits on another process's bootstrap; the steps
  122. are idempotent, so a botched winner only costs redundant work later).
  123. A stale lock — older than LOCK_STALE_SECONDS — is broken and re-tried
  124. once: a crashed winner died before its record write, so re-running is
  125. correct.
  126. """
  127. def __init__(self, record: Path):
  128. self.path = record.with_name(record.name + ".lock")
  129. self.acquired = False
  130. def _try_create(self) -> bool:
  131. try:
  132. self.path.parent.mkdir(parents=True, exist_ok=True)
  133. fd = os.open(self.path, os.O_CREAT | os.O_EXCL | os.O_WRONLY)
  134. except FileExistsError:
  135. return False
  136. except OSError:
  137. return False
  138. try:
  139. os.write(fd, json.dumps({"pid": os.getpid(), "startedAt": time.time()}).encode("utf-8"))
  140. finally:
  141. os.close(fd)
  142. return True
  143. def _is_stale(self) -> bool:
  144. try:
  145. body = json.loads(self.path.read_text(encoding="utf-8-sig"))
  146. started = float(body.get("startedAt", 0))
  147. except (OSError, ValueError):
  148. # Unreadable lock: age it by mtime instead.
  149. try:
  150. started = self.path.stat().st_mtime
  151. except OSError:
  152. return False
  153. return (time.time() - started) > LOCK_STALE_SECONDS
  154. def acquire(self) -> bool:
  155. if self._try_create():
  156. self.acquired = True
  157. return True
  158. if self._is_stale():
  159. try:
  160. self.path.unlink()
  161. except OSError:
  162. return False
  163. if self._try_create():
  164. self.acquired = True
  165. return True
  166. return False
  167. def release(self) -> None:
  168. if not self.acquired:
  169. return
  170. try:
  171. self.path.unlink()
  172. except OSError:
  173. pass
  174. self.acquired = False
  175. # ---------------------------------------------------------------------------
  176. # the boot entry point
  177. # ---------------------------------------------------------------------------
  178. def run_boot_bootstrap(project_root: Path) -> dict:
  179. """Bound home maintenance to one attempt per installed revision."""
  180. from hermes_cli import post_update
  181. identity = needs_bootstrap(project_root)
  182. if not identity:
  183. return {"home": "skipped"}
  184. record = record_path(project_root)
  185. lock = _RecordLock(record)
  186. if not lock.acquire():
  187. return {"home": "lost-race"}
  188. try:
  189. # A previous holder may have finished after our first read.
  190. if read_last_known(record).get("identity") == identity:
  191. return {"home": "done-by-other"}
  192. logger.info("home maintenance: code changed to %s, running steps", identity[:12])
  193. results = post_update.run_steps(post_update.BOOT_HOME_STEPS)
  194. _write_record(record, identity, results)
  195. return {"home": results}
  196. finally:
  197. lock.release()
  198. def maybe_run_boot_bootstrap(project_root: Path) -> None:
  199. """The one call boot paths use. Never raises: a bootstrap problem must
  200. not stop the gateway/serve/CLI from starting."""
  201. try:
  202. run_boot_bootstrap(Path(project_root))
  203. except Exception as exc:
  204. logger.warning("boot bootstrap failed (continuing boot): %s", exc)