plugin_eviction.py 21 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421
  1. """Keep an update alive when an enabled plugin no longer fits the new core.
  2. Admission refuses a plugin that does not fit, because the user is choosing and can
  3. choose again. An update has nobody to ask and must never fail because of a plugin:
  4. core moved (a newer Python, a bumped pin, a newer manifest contract) under a plugin
  5. that was admitted against the old core. Such a plugin is disabled in every home that
  6. enables it, the reason reaches the operator and the receipt, and the update continues
  7. with the rest. Only a core that cannot build on its own still fails. The edit is recorded
  8. in the home's config. A resolver or build verdict carries a fingerprint of what was tried
  9. (core's dependency inputs plus the plugin's) and is retried once either side changed; a fetch
  10. failure is retried by the next update. A plugin that fits again gets the edit undone; a user who re-enables, disables or removes it takes the decision back.
  11. Retries are tried only on top of the enabled plugins that build, so a recorded plugin can never
  12. cost an enabled one its place.
  13. Disabling needs evidence about the plugin itself: its requires-python against the pinned
  14. interpreter, its manifest contract, a resolver proof, or its build failing. A fetch or
  15. tooling failure could be the moment, so the plugin gets one retry before it is disabled.
  16. requires_hermes and a plugin's own requirement on hermes-agent are judged against a version
  17. identity that can lag (a checkout without its release tags), so a misfit there only sits out:
  18. config is untouched, boot skips it the same way, and it rejoins when the verdict flips. A secondary profile whose config cannot be read
  19. sits out until its config is fixed.
  20. """
  21. from __future__ import annotations
  22. import base64
  23. import hashlib
  24. import io
  25. import json
  26. import subprocess
  27. import sys
  28. from pathlib import Path
  29. from pm.environment import BuildFailure, ResolutionConflict
  30. from pm.environments import install_state_dir, runtime_facts_path
  31. from pm.filesystem import durable_write_bytes, file_digest, native, read_bytes_or_none
  32. from pm.package import InstallError
  33. from pm.plugins_state import RECORD
  34. Entry = tuple[Path, str, Path] # (home plugins dir, selection key, plugin dir)
  35. def _interpreter_version() -> str:
  36. """The Python the generation is built for; a plugin's requires-python is judged against it."""
  37. from pm._uv import _toolchain
  38. tools = _toolchain(explicit=True)
  39. if tools is None:
  40. raise InstallError("venv", "PM's pinned toolchain is unavailable")
  41. probe = subprocess.run([native(tools[1]), "-I", "-c", "import platform; print(platform.python_version())"],
  42. capture_output=True, text=True, check=True, timeout=60)
  43. return probe.stdout.strip()
  44. def static_verdicts(entries: list[Entry], python_version: str,
  45. extras: list[str]) -> tuple[dict[Path, str], dict[Path, str]]:
  46. """``(disable, sit out)`` reasons found without a resolver, keyed by resolved dir."""
  47. from pm.plugin_declarations import manifest_version_error, read_python_declaration
  48. from pm.workspace import hermes_fit_error
  49. reasons: dict[Path, str] = {}
  50. waiting: dict[Path, str] = {}
  51. for _plugins_dir, _name, plugin_dir in entries:
  52. key = plugin_dir.resolve()
  53. if key in reasons or key in waiting:
  54. continue
  55. try:
  56. declaration = read_python_declaration(plugin_dir)
  57. except (OSError, ValueError, TypeError) as exc:
  58. reasons[key] = f"its dependency declaration is invalid: {exc}"
  59. continue
  60. # Mirrors build_member_dirs, so the recorded stamp is the one boot expects.
  61. hermes = hermes_fit_error(declaration, extras)
  62. if hermes:
  63. waiting[key] = hermes
  64. continue
  65. manifest = manifest_version_error(declaration.manifest, plugin_dir.name)
  66. reason = (manifest.removeprefix(f"Plugin '{plugin_dir.name}' ") if manifest
  67. else declaration.python_error(python_version))
  68. if reason:
  69. reasons[key] = reason
  70. return reasons, waiting
  71. def _discard(names: list, spellings: set[str]) -> None:
  72. """Remove *spellings* from a round-tripped list in place, so order and comments survive."""
  73. for index in reversed(range(len(names))):
  74. if names[index] in spellings:
  75. del names[index]
  76. def _list(plugins, key: str) -> list:
  77. if plugins.get(key) is None:
  78. plugins[key] = []
  79. return plugins[key]
  80. def _disable(plugins, name: str, plugin_dir: Path, reason: str, tried: str | None = None) -> None:
  81. """Park *name* in plugins.disabled, drop it from plugins.enabled and record what to undo."""
  82. from pm.plugins_state import plugin_spellings
  83. spellings = plugin_spellings(plugin_dir, name)
  84. disabled, enabled = _list(plugins, "disabled"), plugins.get("enabled")
  85. if not isinstance(plugins.get(RECORD), dict):
  86. plugins[RECORD] = {}
  87. earlier = plugins[RECORD].get(name)
  88. if name in disabled and isinstance(earlier, dict):
  89. was_enabled = bool(earlier.get("enabled")) # a retry that still fails keeps the first record
  90. else:
  91. was_enabled = isinstance(enabled, list) and bool(spellings & set(enabled))
  92. if name not in disabled:
  93. disabled.append(name)
  94. if isinstance(enabled, list):
  95. _discard(enabled, spellings)
  96. plugins[RECORD][name] = {"enabled": was_enabled, "reason": " ".join(reason.split())[:300]}
  97. if tried:
  98. plugins[RECORD][name]["tried"] = tried
  99. def _rejoin(plugins, name: str, plugin_dir: Path) -> None:
  100. """Undo an earlier update's _disable now that the plugin fits again."""
  101. from pm.plugins_state import plugin_spellings
  102. record = plugins.get(RECORD) if isinstance(plugins.get(RECORD), dict) else {}
  103. earlier = record.get(name)
  104. if not isinstance(earlier, dict):
  105. return # the user settled it since this update read the config: their choice stands
  106. _discard(_list(plugins, "disabled"), plugin_spellings(plugin_dir, name))
  107. if earlier.get("enabled") and name not in _list(plugins, "enabled"):
  108. plugins["enabled"].append(name)
  109. def settle_record(plugins, settled=()) -> None:
  110. """A user's own selection takes the decision back: forget the record of every plugin they just
  111. enabled, disabled or removed (*settled*), so no later update turns it back on."""
  112. record = plugins.get(RECORD)
  113. for name in settled if isinstance(record, dict) else ():
  114. record.pop(name, None)
  115. _prune_record(plugins)
  116. def _prune_record(plugins) -> None:
  117. """Forget records whose plugin left plugins.disabled (the user re-enabled or removed it)."""
  118. record = plugins.get(RECORD)
  119. if not isinstance(record, dict):
  120. plugins.pop(RECORD, None)
  121. return
  122. disabled = set(plugins.get("disabled") or ())
  123. for name in [name for name in record if name not in disabled]:
  124. del record[name]
  125. if not record:
  126. del plugins[RECORD]
  127. def recorded_evictions() -> dict[Entry, dict]:
  128. """Plugins an earlier update disabled that their home still has disabled, with their record.
  129. A provider-only record (never in plugins.enabled) is retried only while memory.provider still
  130. names it, so a rejoin never installs a provider the user has since switched away from."""
  131. from pm.plugins_state import dependency_homes, plugin_spellings, read_home_selection
  132. from pm.workspace import selected_plugin_dir
  133. entries: dict[Entry, dict] = {}
  134. for home in dependency_homes():
  135. try:
  136. selection = read_home_selection(home) or {}
  137. except ValueError:
  138. continue # sync_evicting already reports an unreadable profile
  139. plugins = selection.get("plugins") or {}
  140. provider = str((selection.get("memory") or {}).get("provider") or "").strip()
  141. record, disabled = plugins.get(RECORD), plugins.get("disabled") or []
  142. for name in record if isinstance(record, dict) else ():
  143. if not isinstance(name, str) or name not in disabled:
  144. continue
  145. try:
  146. plugin_dir = selected_plugin_dir(home / "plugins", name)
  147. except InstallError:
  148. continue # a hand-edited key that names no plugin tree
  149. earlier = record[name] if isinstance(record[name], dict) else {}
  150. if plugin_dir is not None and (earlier.get("enabled") or provider in plugin_spellings(plugin_dir, name)):
  151. entries[(home / "plugins", name, plugin_dir)] = earlier
  152. return entries
  153. class PluginEviction:
  154. """One update's config edits: disable the plugins in *reasons*, re-enable *rejoined* ones.
  155. A disabled plugin leaves plugins.enabled under every spelling and is recorded under
  156. plugins.disabled_by_update (was it enabled, and why), so a later update can retry it and undo
  157. exactly this edit. memory.provider is left alone: plugins.disabled keeps a parked provider out
  158. of the environment and the loader, and re-enabling the plugin brings the provider back with it.
  159. Published like a plugin selection.
  160. """
  161. def __init__(self, entries: list[Entry], reasons: dict[Path, str], rejoined: list[Entry] = (), *,
  162. tried: dict[Path, str] | None = None, configs=None):
  163. from hermes_yaml import roundtrip_yaml
  164. from pm.publication import selection_snapshot
  165. # The snapshot the update decided from: a user edit since then refuses publication.
  166. self.configs = selection_snapshot() if configs is None else configs
  167. tried = tried or {}
  168. by_home: dict[Path, list[tuple[str, Path, str | None]]] = {}
  169. for plugins_dir, name, plugin_dir in entries:
  170. if plugin_dir.resolve() in reasons:
  171. by_home.setdefault(plugins_dir.parent, []).append((name, plugin_dir, reasons[plugin_dir.resolve()]))
  172. for plugins_dir, name, plugin_dir in rejoined:
  173. by_home.setdefault(plugins_dir.parent, []).append((name, plugin_dir, None))
  174. self.edits: list[tuple[Path, bytes | None, bytes]] = []
  175. for home, changes in by_home.items():
  176. path = home / "config.yaml"
  177. previous = read_bytes_or_none(path) # config-reader: ok — pm publication: byte-level compare-and-swap rewrite of the local file
  178. yaml = roundtrip_yaml()
  179. config = (yaml.load(previous.decode("utf-8-sig")) if previous else None) or {}
  180. # read_home_selection already proved plugins is a mapping and the lists are lists.
  181. plugins = config.get("plugins")
  182. if plugins is None:
  183. plugins = config["plugins"] = {}
  184. for name, plugin_dir, reason in changes:
  185. if reason is None:
  186. _rejoin(plugins, name, plugin_dir)
  187. else:
  188. _disable(plugins, name, plugin_dir, reason, tried.get(plugin_dir.resolve()))
  189. _prune_record(plugins)
  190. output = io.StringIO()
  191. yaml.dump(config, output)
  192. self.edits.append((path, previous, output.getvalue().encode("utf-8")))
  193. def publish(self, project: Path) -> None:
  194. from pm.publication import selection_snapshot
  195. if selection_snapshot() != self.configs:
  196. raise ValueError("plugin configuration changed while preparing publication; retry")
  197. row = {"configs": [{"config": str(path),
  198. "previous": base64.b64encode(previous).decode() if previous is not None else None,
  199. "config_after": hashlib.sha256(proposed).hexdigest()}
  200. for path, previous, proposed in self.edits],
  201. "facts_before": file_digest(runtime_facts_path(project))}
  202. durable_write_bytes(install_state_dir(project) / "publication.json", json.dumps(row).encode())
  203. for path, _previous, proposed in self.edits:
  204. durable_write_bytes(path, proposed)
  205. def _trial(package, enabled, explicit: bool, plugin_dirs: list[Path]) -> tuple[str, bool] | None:
  206. """Why the last of *plugin_dirs* cannot join the build, and whether that is a verdict on the
  207. plugin (a resolver proof or its build failing) rather than the moment; None when it builds."""
  208. cause = ""
  209. # A fetch or tooling failure can be the moment rather than the plugin: one more try.
  210. for _attempt in range(2):
  211. try:
  212. package.apply(enabled, explicit=explicit, plugin_dirs=plugin_dirs, skip_invalid_secondary=True)
  213. return None
  214. except (ResolutionConflict, BuildFailure) as exc:
  215. return f"the dependency environment no longer builds with it: {exc.cause[-400:]}", True
  216. except InstallError as exc:
  217. cause = exc.cause
  218. return f"its dependencies could not be prepared, twice: {cause[-400:]}", False
  219. def sync_evicting(package, facts, fact: dict, *, extras, shipped, frozen, explicit: bool) -> None:
  220. """Build the discovered selection, disabling whatever plugin keeps it from building.
  221. Static misfits go first (no resolver needed). If the rest still fails, core alone is
  222. built to prove the plugins are the cause, then members are re-added in config order
  223. and each one that breaks the build is disabled too. Plugins an earlier update disabled
  224. are retried once their fingerprint changed, on top of the enabled plugins that build,
  225. and re-enabled when they fit.
  226. """
  227. from pm import receipt
  228. from pm.install import _target_selection
  229. from pm.plugins_state import dependency_homes, read_home_selection
  230. from pm.publication import selection_snapshot
  231. from pm.workspace import enabled_plugin_entries
  232. configs = selection_snapshot()
  233. notices: list[str] = []
  234. for home in dependency_homes()[1:]:
  235. try:
  236. read_home_selection(home)
  237. except ValueError as exc:
  238. notices.append(f"Skipped the plugins of profile {home}: {exc}; they rejoin once its config.yaml is fixed")
  239. entries = enabled_plugin_entries(skip_invalid_secondary=True)
  240. recorded = recorded_evictions()
  241. selection = dict(extras=extras, shipped=shipped, frozen=frozen)
  242. # Core's extras with no plugin: what every build of this update selects, so the static
  243. # verdicts judge plugin extras under the same selection boot's currency check reads.
  244. base = _target_selection(package, fact, inputs={"plugin_dirs": []}, repair=False, **selection)[0]
  245. reasons, waiting = static_verdicts([*entries, *recorded], _interpreter_version(), base)
  246. update = _EvictingUpdate(package, facts, fact, selection, base=base, explicit=explicit, configs=configs,
  247. entries=entries, recorded=recorded, reasons=reasons, waiting=waiting)
  248. update.run()
  249. notices += _outcome_notices(entries, recorded, reasons, waiting, update.joined)
  250. for message in notices:
  251. print(f"⚠ {message}", file=sys.stderr, flush=True)
  252. receipt.record_warning(message)
  253. class _EvictingUpdate:
  254. """One update's build: the enabled plugins first, then the recorded ones that are due."""
  255. def __init__(self, package, facts, fact: dict, selection: dict, *, base: list[str], explicit: bool, configs,
  256. entries: list[Entry], recorded: dict[Entry, dict], reasons: dict[Path, str],
  257. waiting: dict[Path, str]):
  258. from pm.workspace import _is_member_candidate
  259. self.package, self.facts, self.fact, self.selection = package, facts, fact, selection
  260. self.explicit, self.configs, self.entries, self.reasons = explicit, configs, entries, reasons
  261. self.retrying = list(recorded)
  262. self.tried: dict[Path, str] = {}
  263. self.verdicts: list[Path] = [] # disabled on a verdict about the plugin: fingerprinted at commit
  264. self.base = base
  265. def fits(plugin_dir: Path) -> bool:
  266. return plugin_dir.resolve() not in reasons and plugin_dir.resolve() not in waiting
  267. self.kept = list(dict.fromkeys(plugin_dir for _plugins_dir, _name, plugin_dir in entries
  268. if fits(plugin_dir) and _is_member_candidate(plugin_dir)))
  269. # A plugin with nothing to build rejoins on its static verdict; one with dependencies is
  270. # due only when core's inputs, its own or the enabled plugins beside it changed since the
  271. # attempt that failed.
  272. self.joined = [entry for entry in recorded if fits(entry[2]) and not _is_member_candidate(entry[2])]
  273. # Those whose last failure was no verdict on the plugin (a download failure, a static
  274. # misfit since fixed) go first: they fitted beside the rest before.
  275. self.due = sorted((entry for entry, record in recorded.items()
  276. if fits(entry[2]) and _is_member_candidate(entry[2])
  277. and record.get("tried") != self.fingerprint(entry[2], self.kept)),
  278. key=lambda entry: "tried" in recorded[entry])
  279. def fingerprint(self, plugin_dir: Path, beside: list[Path]) -> str:
  280. """What a retry of *plugin_dir* would build: core, the plugin and the enabled plugins."""
  281. return self.package.expected_stamp(self.base, plugin_dirs=[*beside, plugin_dir])
  282. def commit(self, members: list[Path]) -> None:
  283. from pm import receipt
  284. from pm.install import _commit_selection, _runtime_state_matches, _target_selection
  285. members = list(dict.fromkeys(members))
  286. # Fingerprinted against the members this update leaves enabled: the next update compares there.
  287. self.tried = {member.resolve(): self.fingerprint(member, members) for member in self.verdicts}
  288. enabled, stamp, inputs = _target_selection(self.package, self.fact, inputs={"plugin_dirs": members},
  289. repair=False, **self.selection)
  290. receipt.record_feature_list(enabled)
  291. edit = None
  292. if self.reasons or self.joined:
  293. edit = PluginEviction([*self.entries, *self.retrying], self.reasons, self.joined,
  294. tried=self.tried, configs=self.configs)
  295. _commit_selection(self.package, self.facts, edit, enabled=enabled, stamp=stamp, inputs=inputs,
  296. current=_runtime_state_matches(self.fact, stamp), repair=False, explicit=self.explicit,
  297. skip_invalid_secondary=True)
  298. def run(self) -> None:
  299. due = [entry[2] for entry in self.due]
  300. if due:
  301. try:
  302. self.joined += self.due
  303. self.commit([*self.kept, *due])
  304. return
  305. except InstallError:
  306. self.joined = self.joined[:-len(self.due)]
  307. try:
  308. if not due:
  309. self.commit(self.kept)
  310. return
  311. self.package.apply(self.base, explicit=self.explicit, plugin_dirs=self.kept, skip_invalid_secondary=True)
  312. except InstallError as failure:
  313. self.evict_enabled(failure)
  314. return
  315. fitting = list(self.kept)
  316. for entry in self.due:
  317. if self.try_member(fitting, entry[2]):
  318. self.joined.append(entry)
  319. self.commit(fitting)
  320. def try_member(self, fitting: list[Path], member: Path) -> bool:
  321. """Add *member* to *fitting* when it builds on top; else record why. Only a verdict on the
  322. plugin is fingerprinted: a fetch failure is the moment, so the next update retries it."""
  323. verdict = _trial(self.package, self.base, self.explicit, [*fitting, member])
  324. if verdict is None:
  325. fitting.append(member)
  326. return True
  327. self.reasons[member.resolve()] = verdict[0]
  328. if verdict[1]:
  329. self.verdicts.append(member)
  330. return False
  331. def evict_enabled(self, failure: InstallError) -> None:
  332. """Core alone must build; then each enabled member that breaks the build is disabled.
  333. Nothing rejoins in such an update: a retried plugin must never take an enabled one's place."""
  334. if not self.kept:
  335. raise failure
  336. try:
  337. self.package.apply(self.base, explicit=self.explicit, plugin_dirs=[], skip_invalid_secondary=True)
  338. except InstallError:
  339. raise failure from None
  340. self.joined = [entry for entry in self.joined if entry not in self.due]
  341. fitting: list[Path] = []
  342. for member in self.kept:
  343. self.try_member(fitting, member)
  344. self.commit(fitting)
  345. _RETRY = "a later update retries it"
  346. def _outcome_notices(entries: list[Entry], recorded: dict[Entry, dict], reasons: dict[Path, str],
  347. waiting: dict[Path, str], joined: list[Entry]) -> list[str]:
  348. notices = []
  349. for plugins_dir, name, plugin_dir in entries:
  350. key = plugin_dir.resolve()
  351. if key in reasons:
  352. notices.append(f"Disabled plugin '{name}' in {plugins_dir.parent}: {reasons[key]}; {_RETRY} and turns it "
  353. f"back on once it fits, or run `hermes plugins enable {name}` sooner")
  354. elif key in waiting:
  355. notices.append(f"Left plugin '{name}' in {plugins_dir.parent} out of this update: {waiting[key]}; "
  356. "it stays enabled and rejoins once Hermes reports a version it accepts")
  357. for entry, record in recorded.items():
  358. plugins_dir, name, plugin_dir = entry
  359. if entry in joined:
  360. notices.append(f"Turned plugin '{name}' in {plugins_dir.parent} back on: it fits this Hermes again")
  361. continue
  362. why = reasons.get(plugin_dir.resolve()) or waiting.get(plugin_dir.resolve()) or record.get("reason") or "unknown"
  363. notices.append(f"Plugin '{name}' in {plugins_dir.parent} is still disabled: {why}; {_RETRY}")
  364. return notices