plugins_cadence.py 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338
  1. """The plugin update-check cadence: read-only, receipt-surfaced.
  2. Runs at gateway start + the periodic tick when
  3. ``plugins.auto_update_check_hours`` (default 24, 0 disables) says it's
  4. due, writes a plugin-check receipt (pm.receipt, kind 'plugin-check'),
  5. and logs ONE actionable line when updates exist. Applying updates
  6. stays explicit — ``plugins.auto_apply: true`` (default false) opts into
  7. unattended apply for catalog and tracked git plugins, scan-gated like cmd_update.
  8. Pure, injectable clock/check/update seams for hermetic tests.
  9. """
  10. from __future__ import annotations
  11. import threading
  12. import time
  13. from pathlib import Path
  14. from typing import Callable, Optional
  15. _MARKERS_DIR = "plugin-update-checks"
  16. _DEFAULT_INTERVAL_HOURS = 24
  17. def _marker_path() -> Path:
  18. """The last-run marker, resolved per call (tests monkeypatch
  19. get_hermes_home). Derivation only — NO mkdir: a due-check or any
  20. read path must not create user state."""
  21. from hermes_constants import get_hermes_home
  22. return get_hermes_home() / _MARKERS_DIR / "last-run"
  23. def _results_path() -> Path:
  24. """The last check's per-plugin results, next to the marker (derivation only)."""
  25. return _marker_path().parent / "results.json"
  26. def snapshot_installs(plugins_dir: Path) -> dict:
  27. """The install records an update check is about to compare against. Take it BEFORE the check runs:
  28. a record read afterwards may already include an update that finished during the check."""
  29. from hermes_cli.plugins_provenance import read_sidecar_rows
  30. return read_sidecar_rows(plugins_dir)
  31. def record_check_results(results: list, checked_installs: dict) -> None:
  32. """Persist a completed check so surfaces that list plugins (the Desktop Plugins tab) can show an
  33. update without a network call per listing. Each row carries the install record it was checked
  34. against (*checked_installs*, from :func:`snapshot_installs` before the check), so a later reader
  35. can tell whether the result still applies. Never raises."""
  36. import json
  37. from utils import atomic_write_text
  38. try:
  39. rows = []
  40. for r in results:
  41. row = r.to_json() if hasattr(r, "to_json") else dict(r)
  42. rows.append({**row, "checked_install": _install_fingerprint(checked_installs.get(row.get("name")))})
  43. atomic_write_text(_markers_dir() / "results.json", json.dumps(rows, indent=2) + "\n")
  44. except (OSError, TypeError, ValueError):
  45. pass
  46. def _install_fingerprint(record) -> dict | None:
  47. """The parts of an install record an update check depends on."""
  48. if not isinstance(record, dict):
  49. return None
  50. return {"source": record.get("source"), "revision": record.get("revision"), "pinned": record.get("pinned") is True}
  51. def cached_git_updates(install_metadata: dict) -> dict[str, str]:
  52. """``{plugin name: what the update moves to}`` (a commit or a feed version) for git installs the last
  53. check found behind. A result is dropped once the install it was checked against changed (updated,
  54. reinstalled from another source, or pinned with ``--ref``), so Desktop never offers an update that
  55. already landed or one ``update`` would refuse."""
  56. import json
  57. try:
  58. rows = json.loads(_results_path().read_text(encoding="utf-8-sig"))
  59. except (OSError, ValueError):
  60. return {}
  61. out: dict[str, str] = {}
  62. for row in rows if isinstance(rows, list) else ():
  63. if not isinstance(row, dict) or row.get("class") != "git" or row.get("update_available") is not True:
  64. continue
  65. current = _install_fingerprint(install_metadata.get(row.get("name")))
  66. if current and not current["pinned"] and current == row.get("checked_install") and row.get("latest"):
  67. out[str(row["name"])] = str(row["latest"])
  68. return out
  69. def _markers_dir() -> Path:
  70. """The markers dir, created on demand — WRITE paths only."""
  71. d = _marker_path().parent
  72. d.mkdir(parents=True, exist_ok=True)
  73. return d
  74. def check_interval_hours(config_get: Callable | None = None) -> float:
  75. """plugins.auto_update_check_hours; 0 disables; default 24."""
  76. if config_get is None:
  77. config_get = _default_config_get
  78. try:
  79. value = config_get("plugins", "auto_update_check_hours")
  80. except Exception:
  81. return _DEFAULT_INTERVAL_HOURS
  82. if value is None:
  83. return _DEFAULT_INTERVAL_HOURS
  84. try:
  85. hours = float(value)
  86. except (TypeError, ValueError):
  87. return _DEFAULT_INTERVAL_HOURS
  88. return max(0.0, hours)
  89. def auto_apply_enabled(config_get: Callable | None = None) -> bool:
  90. if config_get is None:
  91. config_get = _default_config_get
  92. try:
  93. return bool(config_get("plugins", "auto_apply"))
  94. except Exception:
  95. return False
  96. def _default_config_get(section: str, key: str):
  97. try:
  98. from hermes_cli.config import cfg_get, load_config_readonly
  99. return cfg_get(load_config_readonly(), section, key, default=None)
  100. except Exception:
  101. return None
  102. def check_due(now: Optional[float] = None, interval_hours: Optional[float] = None,
  103. config_get: Callable | None = None) -> bool:
  104. """The clock gate: last-run marker vs the interval."""
  105. if interval_hours is None:
  106. interval_hours = check_interval_hours(config_get)
  107. if interval_hours <= 0:
  108. return False
  109. now = time.time() if now is None else now
  110. marker = _marker_path()
  111. try:
  112. last = marker.stat().st_mtime
  113. except OSError:
  114. return True
  115. return (now - last) >= interval_hours * 3600
  116. #: Minimal singleflight for one home: two gateway ticks overlapping in
  117. #: this process (boot pass + periodic tick) must not double-fetch or
  118. #: double-write receipts. A plain non-blocking lock — not a manager.
  119. _tick_lock = threading.Lock()
  120. def run_scheduled_check(
  121. *,
  122. run_checks_fn: Callable[..., list],
  123. plugins_dir: Path,
  124. apply_updates_fn: Optional[Callable[[str], None]] = None,
  125. log=None,
  126. config_get: Callable | None = None,
  127. now: Optional[float] = None,
  128. ) -> Optional[list]:
  129. """One cadence tick: gate → check → receipt → (opt-in) apply.
  130. Returns the check results, or None when not due / disabled / another
  131. tick is already in flight. NEVER raises — a cadence failure is
  132. logged, never fatal.
  133. """
  134. import logging
  135. if log is None:
  136. log = logging.getLogger(__name__)
  137. if not check_due(now=now, config_get=config_get):
  138. return None
  139. if not _tick_lock.acquire(blocking=False):
  140. log.debug("plugin update check already in flight — skipping tick")
  141. return None
  142. try:
  143. return _run_check_locked(
  144. run_checks_fn=run_checks_fn,
  145. plugins_dir=plugins_dir,
  146. apply_updates_fn=apply_updates_fn,
  147. log=log,
  148. config_get=config_get,
  149. )
  150. finally:
  151. _tick_lock.release()
  152. def _auto_apply(updates: list, checked_installs: dict, apply_updates_fn: Callable[[str], None], log) -> None:
  153. """Apply each update row the opt-in tick may move. A catalog install held with ``--ref`` is left
  154. where the user put it. A widened catalog pin is a pending review, not a failure: one line naming
  155. the command that walks it, no traceback every tick; other refusals are one line too."""
  156. from hermes_cli.plugins_auto_update import HELD_WITH_REF, HeldWithRef, held_with_ref
  157. from hermes_cli.plugins_cmd import PluginOperationError
  158. from hermes_cli.plugins_cmd_catalog import RepinConsentRequired
  159. for r in updates:
  160. if getattr(r, "klass", "") not in ("git", "catalog"):
  161. continue
  162. if held_with_ref(checked_installs.get(r.name)):
  163. log.info("plugin %s not auto-updated: %s", r.name, HELD_WITH_REF.format(name=r.name))
  164. continue
  165. try:
  166. apply_updates_fn(r.name)
  167. except HeldWithRef as exc: # held with --ref while the check ran
  168. log.info("plugin %s not auto-updated: %s", r.name, exc)
  169. except RepinConsentRequired:
  170. log.info("plugin %s has an update that needs your review: run `hermes plugins update %s`",
  171. r.name, r.name)
  172. except PluginOperationError as exc:
  173. log.warning("auto-apply of %s not applied: %s", r.name, exc)
  174. except (Exception, SystemExit):
  175. log.warning("auto-apply of %s failed", r.name, exc_info=True)
  176. def _run_check_locked(
  177. *,
  178. run_checks_fn: Callable[..., list],
  179. plugins_dir: Path,
  180. apply_updates_fn: Optional[Callable[[str], None]],
  181. log,
  182. config_get: Callable | None = None,
  183. ) -> list:
  184. check_ok = True
  185. warning = ""
  186. checked_installs: dict = {}
  187. try:
  188. checked_installs = snapshot_installs(plugins_dir)
  189. results = run_checks_fn(plugins_dir)
  190. except Exception:
  191. warning = "plugin update check failed"
  192. log.warning(warning, exc_info=True)
  193. results = []
  194. check_ok = False
  195. if check_ok:
  196. record_check_results(results, checked_installs)
  197. try:
  198. from pm import receipt
  199. token = receipt.begin("plugin-check")
  200. receipt.record_plugin_checks(results)
  201. if warning:
  202. receipt.record_warning(warning)
  203. updates = [r for r in results if getattr(r, "update_available", None) is True]
  204. receipt.finalize("failed" if not check_ok else "updates-available" if updates else "ok",
  205. exit_code=0 if check_ok else 1, token=token)
  206. except Exception:
  207. log.debug("plugin-check receipt write failed", exc_info=True)
  208. # ONE actionable line (a log, not a system-prompt mutation — cache safe)
  209. updates = [r for r in results if getattr(r, "update_available", None) is True]
  210. needs_fixing = [r for r in results if getattr(r, "needs_fixing", None)]
  211. if updates:
  212. names = ", ".join(r.name for r in updates)
  213. log.info(
  214. "plugin updates available: %s — run `hermes plugins check-updates` "
  215. "and `hermes plugins update <name>`",
  216. names,
  217. )
  218. if needs_fixing:
  219. names = ", ".join(r.name for r in needs_fixing)
  220. log.warning(
  221. "plugin update_url mismatches need attention: %s — run "
  222. "`hermes plugins trust-update-url <name>` after review",
  223. names,
  224. )
  225. # Opt-in unattended apply: the classes `hermes plugins update` can move (catalog re-pins to the
  226. # reviewed sha, tracked git pulls), scan-gated by the update path itself, which also refuses a
  227. # widened catalog pin or a too-new requires_hermes without a terminal. Pinned/manual/drift/pip
  228. # are never auto-applied (their update_available is False/None or their class excludes it).
  229. if apply_updates_fn and updates and auto_apply_enabled(config_get):
  230. _auto_apply(updates, checked_installs, apply_updates_fn, log)
  231. # stamp the marker AFTER a completed run (even a failed one — a
  232. # failing check retrying every tick would hammer the network)
  233. try:
  234. marker = _markers_dir() / "last-run"
  235. marker.write_text(str(int(time.time())), encoding="utf-8")
  236. except OSError:
  237. pass
  238. return results
  239. # ---------------------------------------------------------------------------
  240. # the production caller: real seams for the gateway boot/housekeeping tick
  241. # ---------------------------------------------------------------------------
  242. def maybe_run_gateway_check(
  243. *,
  244. run_checks_fn: Optional[Callable[..., list]] = None,
  245. apply_updates_fn: Optional[Callable[[str], None]] = None,
  246. plugins_dir: Optional[Path] = None,
  247. log=None,
  248. now: Optional[float] = None,
  249. ) -> Optional[list]:
  250. """The tick every gateway boot / housekeeping pass calls.
  251. Fills in the REAL seams ``run_scheduled_check`` leaves injectable:
  252. the same read-only ``plugins_updates.run_checks`` the manual
  253. ``hermes plugins check-updates`` uses (urllib feed fetch, git
  254. ls-remote, PyPI latest), the real plugins dir, and the manual
  255. ``hermes plugins update <name>`` flow as the opt-in apply path —
  256. auto-apply rides the identical security/consent/scan pipeline.
  257. Returns the check results, or None when not due / disabled. Due-gated
  258. by ``plugins.auto_update_check_hours`` (0 disables); a network error
  259. costs one warning and a stamped marker — never an apply.
  260. """
  261. if plugins_dir is None:
  262. from hermes_cli import plugins_cmd
  263. plugins_dir = plugins_cmd._plugins_dir()
  264. if run_checks_fn is None:
  265. # ONE shared network-default implementation — plugins_updates
  266. # owns default_fetch / default_ls_remote / _default_pypi_latest;
  267. # the manual `hermes plugins check-updates` passes the same
  268. # defaults. No boilerplate re-derivation here.
  269. from hermes_cli.plugins_updates import run_checks
  270. run_checks_fn = run_checks
  271. if apply_updates_fn is None:
  272. # update_one with no terminal, refusals raised (cmd_update would turn them into an exit)
  273. from hermes_cli import plugins_auto_update
  274. apply_updates_fn = plugins_auto_update.apply_unattended
  275. return run_scheduled_check(
  276. run_checks_fn=run_checks_fn,
  277. plugins_dir=plugins_dir,
  278. apply_updates_fn=apply_updates_fn,
  279. log=log,
  280. now=now,
  281. )