receipt.py 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328
  1. """pm sync receipts: the machine-readable surface for venv operations.
  2. Every pm venv sync — startup, plugin install, update rebuild — writes a
  3. receipt with the SAME schema the updater's receipts use
  4. (hermes_cli.update_receipt), into the same
  5. ``<HERMES_HOME>/logs/update_receipts/`` dir with a ``kind`` field
  6. separating kinds. One reader (``hermes pm status``, desktop IPC) serves
  7. every surface: a failed venv rebuild is as reportable as a failed
  8. update.
  9. The in-flight receipt lives in a ContextVar, not a module global: the
  10. sync cadence and dependency preparation can overlap across threads, and a
  11. shared global lets one run's begin/finalize clobber another's record.
  12. Two hazards of ContextVar state are handled explicitly:
  13. - Copied contexts (``contextvars.copy_context()``, asyncio.to_thread)
  14. share the SAME dict object — so every record_* COPY-ON-WRITES: it
  15. deep-copies, mutates the copy, and re-sets it in the current context.
  16. A child task records into its own copy; the parent's receipt is
  17. untouched.
  18. - A nested ``begin`` in the same context would silently drop the outer
  19. receipt. ``begin`` therefore returns the ContextVar token; passing it
  20. to ``finalize(..., token=...)`` restores the OUTER receipt instead of
  21. discarding it. The ambient no-token begin→finalize stays as-is (the
  22. existing linear consumers — pm sync, the plugin-check cadence).
  23. Correlation: ``begin`` stamps the receipt with the ambient update
  24. correlation id (derived from the open update receipt's own identity in
  25. the same context). ``finalize`` files the finished receipt under that
  26. id in a per-context map, and the updater embeds only the entry carrying
  27. ITS OWN id (``last_for_update``), never latest.json — a sync that
  28. finished before the update began, a standalone sync, or one from a
  29. concurrent thread cannot be misattributed to it, and a nested update's
  30. sync never displaces the outer update's entry.
  31. """
  32. from __future__ import annotations
  33. import contextvars
  34. from contextlib import contextmanager
  35. import copy
  36. import json
  37. import os
  38. import time
  39. import uuid
  40. from datetime import datetime, timezone, UTC
  41. from pathlib import Path
  42. from typing import Any, Optional
  43. _RECEIPT_KEEP = 20
  44. # Scoped current receipt — per-context (threads get their own via
  45. # context isolation), same pattern as agent/context_compressor's pin.
  46. _current: contextvars.ContextVar[Optional[dict[str, Any]]] = contextvars.ContextVar(
  47. "pm_receipt_current", default=None
  48. )
  49. # Completed sync receipts, keyed by the update correlation id they were
  50. # begun under (copy-on-written per finalize — copied contexts never share
  51. # a mutated dict). The updater embeds ONLY the entry carrying ITS id, so
  52. # a nested update's sync can never displace the outer update's, and a
  53. # standalone sync (update_id None) is never embedded. Bounded: one entry
  54. # per distinct update id seen in this context (nesting depth).
  55. _completed_by_update: contextvars.ContextVar[Optional[dict[str, dict[str, Any]]]] = (
  56. contextvars.ContextVar("pm_receipt_completed_by_update", default=None)
  57. )
  58. _worker_update: contextvars.ContextVar[tuple[Optional[str]] | None] = contextvars.ContextVar(
  59. "pm_worker_update", default=None
  60. )
  61. _last_completed: contextvars.ContextVar[Optional[dict[str, Any]]] = contextvars.ContextVar(
  62. "pm_last_completed", default=None
  63. )
  64. @contextmanager
  65. def worker_context(update_id: Optional[str]):
  66. """Carry correlation across the worker seam without consulting disk state."""
  67. token = _worker_update.set((update_id,))
  68. completed = _last_completed.set(None)
  69. try:
  70. yield
  71. finally:
  72. _last_completed.reset(completed)
  73. _worker_update.reset(token)
  74. def last_completed() -> Optional[dict[str, Any]]:
  75. return copy.deepcopy(_last_completed.get())
  76. def accept_worker_receipt(data: Optional[dict[str, Any]], update_id: Optional[str]) -> None:
  77. if data is None:
  78. return
  79. if data.get("update_id") != update_id:
  80. raise ValueError("PM worker receipt correlation mismatch")
  81. if update_id:
  82. completed = dict(_completed_by_update.get() or {})
  83. completed[update_id] = copy.deepcopy(data)
  84. _completed_by_update.set(completed)
  85. def _ambient_update_id() -> Optional[str]:
  86. """The update correlation id in force in this context, or None.
  87. Lazy import: hermes_cli.update_receipt imports pm.receipt at embed
  88. time, so this direction must stay function-scoped. Never raises."""
  89. worker = _worker_update.get()
  90. if worker is not None:
  91. return worker[0]
  92. try:
  93. from hermes_cli.update_receipt import current_correlation_id
  94. return current_correlation_id()
  95. except Exception:
  96. return None
  97. def _utc_now_iso() -> str:
  98. return datetime.now(UTC).isoformat()
  99. def _receipt_dir() -> Path:
  100. """The receipts dir — a pure path computation, NO mkdir side
  101. effect: readers (latest()) must not create state."""
  102. from hermes_constants import get_hermes_home
  103. return get_hermes_home() / "logs" / "update_receipts"
  104. def begin(kind: str) -> contextvars.Token:
  105. """Start recording a sync. ``kind``: 'sync' | 'update' | 'plugin-check'.
  106. Returns the ContextVar token — pass it to ``finalize(token=...)`` when
  107. this begin nests inside an outer begin in the same context, so the
  108. outer receipt survives the inner finalize.
  109. The receipt is stamped with the ambient update correlation id (the
  110. ``hermes update`` this sync belongs to), or None for a standalone
  111. sync — the id is what makes the updater's embed selective."""
  112. return _current.set(
  113. {
  114. "schema": 1,
  115. "kind": kind,
  116. "update_id": _ambient_update_id(),
  117. "started_at": _utc_now_iso(),
  118. "steps": [],
  119. "venv_rebuild": None,
  120. "feature_list": None,
  121. "platform": None,
  122. "outcome": None,
  123. "warnings": [],
  124. "refusal": None,
  125. }
  126. )
  127. def _record(mutate) -> None:
  128. """Copy-on-write record: the ContextVar may be shared with copied
  129. contexts, so mutate a deep copy and re-set it in THIS context only."""
  130. current = _current.get()
  131. if current is None:
  132. return
  133. updated = dict(current)
  134. mutate(updated)
  135. _current.set(copy.deepcopy(updated))
  136. def record_step(name: str, ok: bool, detail: str = "") -> None:
  137. _record(lambda r: r.update(steps=[*r["steps"],
  138. {"name": name, "ok": ok, "detail": detail, "at": _utc_now_iso()}]))
  139. def record_venv_rebuild(ok: bool, reason: str = "") -> None:
  140. _record(lambda r: r.__setitem__("venv_rebuild", {"ok": ok, "reason": reason}))
  141. def record_feature_list(extras: Optional[list[str]]) -> None:
  142. _record(lambda r: r.__setitem__("feature_list", extras))
  143. def record_platform(platform_id: str) -> None:
  144. _record(lambda r: r.__setitem__("platform", platform_id))
  145. def record_plugin_checks(results: list) -> None:
  146. """Plugin update-check results (the cadence's receipt section).
  147. Each item is a plugins_updates.CheckResult.to_json() dict."""
  148. _record(
  149. lambda r: r.__setitem__(
  150. "plugin_checks", [r.to_json() if hasattr(r, "to_json") else r for r in results]
  151. )
  152. )
  153. def record_warning(message: str) -> None:
  154. """Record a warning surfaced to the user during this sync — a warning
  155. that reached the operator's eyes must reach the receipt too."""
  156. _record(
  157. lambda r: r.update(
  158. warnings=[*r.get("warnings", []),
  159. {"message": str(message), "at": _utc_now_iso()}]
  160. )
  161. )
  162. def record_refusal(code: str, detail: str = "") -> None:
  163. """Record WHY this sync refused to act (e.g. the lazy-install policy).
  164. ``outcome`` stays whatever ``finalize`` is given (refusals finalize as
  165. ``failed``/``refused``) — this names the refusal class."""
  166. _record(
  167. lambda r: r.__setitem__(
  168. "refusal", {"code": str(code), "detail": str(detail), "at": _utc_now_iso()}
  169. )
  170. )
  171. def snapshot() -> Optional[dict[str, Any]]:
  172. """The in-flight receipt data — for the updater to EMBED its sync
  173. sections into its own receipt (one schema, one directory). A deep
  174. COPY: the authoritative in-flight dict is never exposed for the
  175. caller to mutate."""
  176. current = _current.get()
  177. return copy.deepcopy(current) if current is not None else None
  178. def finalize(
  179. outcome: str, exit_code: int = 0, token: Optional[contextvars.Token] = None
  180. ) -> Optional[Path]:
  181. """Write the receipt (``outcome``: ok | refused | failed | bisected)
  182. and rotate. Returns its path; None when nothing was begun.
  183. With ``token`` (from the matching ``begin``): pops only this begin's
  184. receipt and restores the outer one. Without: pops whatever is
  185. current (the ambient linear-consumer form)."""
  186. current = snapshot()
  187. if current is None:
  188. return None
  189. if token is not None:
  190. _current.reset(token)
  191. else:
  192. _current.set(None)
  193. current["outcome"] = outcome
  194. current["exit_code"] = exit_code
  195. current["finished_at"] = _utc_now_iso()
  196. _last_completed.set(copy.deepcopy(current))
  197. # Correlation: file this completion under its update id (copy-on-write
  198. # — a deep-copied entry in a freshly copied map, never a shared dict).
  199. update_id = current.get("update_id")
  200. if update_id:
  201. completed = dict(_completed_by_update.get() or {})
  202. completed[update_id] = copy.deepcopy(current)
  203. _completed_by_update.set(completed)
  204. try:
  205. path = _write_rotated(current)
  206. except OSError:
  207. return None
  208. return path
  209. def last_for_update(update_id: Optional[str], *, consume: bool = False) -> Optional[dict[str, Any]]:
  210. """The last sync receipt completed in THIS context under ``update_id``
  211. — the correlation surface for an invoking update's embed. A sync from
  212. before this update, a standalone sync, or one from a concurrent
  213. context cannot be returned; a nested update's sync is filed under the
  214. nested id and never displaces the outer update's entry. Deep copy;
  215. None when no matching completion exists."""
  216. if not update_id:
  217. return None
  218. entries = dict(_completed_by_update.get() or {})
  219. completed = entries.get(update_id)
  220. if consume:
  221. entries.pop(update_id, None)
  222. _completed_by_update.set(entries)
  223. return copy.deepcopy(completed) if completed is not None else None
  224. def latest() -> Optional[dict[str, Any]]:
  225. """The newest receipt (any kind) — the reader surface for
  226. ``hermes pm status`` + the desktop. Pure read: never creates the
  227. receipts dir."""
  228. try:
  229. point = _receipt_dir() / "latest.json"
  230. if point.is_file():
  231. return json.loads(point.read_text(encoding="utf-8-sig"))
  232. except (OSError, ValueError):
  233. return None
  234. return None
  235. def _receipt_name(data: dict[str, Any]) -> str:
  236. """Unique name for concurrent writers: stamp + pid + full random
  237. uuid4 (same pid+random convention as the updater's receipts)."""
  238. stamp = time.strftime("%Y%m%dT%H%M%SZ", time.gmtime())
  239. kind = data.get("kind") or "sync"
  240. return f"pm_{stamp}-{kind}-{os.getpid()}-{uuid.uuid4().hex}.json"
  241. def _write_rotated(data: dict[str, Any]) -> Path:
  242. """Use the same stdlib-only atomic writer as PM's installed facts."""
  243. from pm.filesystem import lock_fd
  244. from pm.lock import _write
  245. d = _receipt_dir()
  246. d.mkdir(parents=True, exist_ok=True)
  247. path = d / _receipt_name(data)
  248. # Concurrent completions share latest.json; serialize its replacement.
  249. with (d / ".pm-write.lock").open("a+b") as lock:
  250. lock_fd(lock.fileno(), wait=True)
  251. _write(path, data)
  252. _write(d / "latest.json", data)
  253. _rotate(d)
  254. return path
  255. def _rotate(d: Path) -> None:
  256. """Keep the newest _RECEIPT_KEEP PM receipts. The dir also holds the
  257. updater's ``update_*.json`` receipts — this rotates ONLY pm's own
  258. (``pm_*.json``); the updater rotates its own."""
  259. receipts = sorted(
  260. (p for p in d.glob("pm_*.json") if p.is_file()),
  261. key=lambda p: p.name,
  262. )
  263. for stale in receipts[:-_RECEIPT_KEEP]:
  264. try:
  265. stale.unlink()
  266. except OSError:
  267. pass