publication.py 10 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196
  1. """Worker-local plugin selection and code publication. No application dependency imports.
  2. Requests carry proposed data; discovery, snapshots and publication happen only
  3. while the install lock is held. The stdlib boot journal owns crash recovery.
  4. """
  5. from __future__ import annotations
  6. import base64
  7. import hashlib
  8. import io
  9. import json
  10. import threading
  11. from pathlib import Path
  12. from pm.environments import dependency_home_root, install_state_dir, runtime_facts_path
  13. from pm.filesystem import durable_write_bytes, file_digest, read_bytes_or_none
  14. from pm.workspace import enabled_plugin_dirs, _is_member_candidate
  15. _METADATA_LOCK_HOLDER = threading.local()
  16. def _metadata_records(data: bytes | None) -> dict:
  17. if data is None:
  18. return {}
  19. try:
  20. records = json.loads(data)
  21. except (UnicodeDecodeError, json.JSONDecodeError) as exc:
  22. raise ValueError("Plugin install metadata changed while preparing the update; retry.") from exc
  23. if not isinstance(records, dict):
  24. raise ValueError("Plugin install metadata changed while preparing the update; retry.")
  25. return records
  26. def candidate_members(extra_dirs=(), **selection):
  27. selected = enabled_plugin_dirs(**selection)
  28. enabled = {path.resolve() for path in (enabled_plugin_dirs() if selection else selected)}
  29. members = [source for source in selected
  30. if _admitted(source, new=source.resolve() not in enabled) and _is_member_candidate(source)]
  31. for directory in extra_dirs:
  32. directory = Path(directory)
  33. if directory not in members and _is_member_candidate(directory):
  34. members.append(directory)
  35. return members
  36. def selection_snapshot() -> dict[Path, bytes | None]:
  37. from pm.plugins_state import dependency_homes
  38. return {home / "config.yaml": read_bytes_or_none(home / "config.yaml") # config-reader: ok — pm publication: byte-level compare-and-swap rewrite of the local file
  39. for home in dependency_homes()}
  40. def validate_manifest(source: Path) -> dict:
  41. from pm.plugin_declarations import read_python_declaration, manifest_version_error
  42. from pm.workspace import core_requirement_error
  43. declaration = read_python_declaration(source)
  44. reason = manifest_version_error(declaration.manifest, source.name)
  45. if not reason and (core := core_requirement_error(declaration)):
  46. reason = f"Plugin '{source.name}' {core}"
  47. if reason:
  48. raise ValueError(reason)
  49. return declaration.manifest
  50. def _admitted(source: Path, *, new: bool) -> bool:
  51. """Refuse a change that newly enables or stages a plugin which does not fit; one enabled
  52. before it whose ``hermes-agent`` requirement misses this Hermes sits out (False), as the
  53. build leaves it out, rather than refusing every other plugin's change."""
  54. from pm.plugin_declarations import read_python_declaration, manifest_version_error
  55. from pm.workspace import core_requirement_error
  56. if new:
  57. validate_manifest(source)
  58. return True
  59. declaration = read_python_declaration(source)
  60. if reason := manifest_version_error(declaration.manifest, source.name):
  61. raise ValueError(reason)
  62. return not core_requirement_error(declaration)
  63. class PluginSelection:
  64. def __init__(self, selection: dict):
  65. from hermes_yaml import roundtrip_yaml
  66. from pm.plugin_eviction import settle_record
  67. self.configs = selection_snapshot()
  68. self.home = Path(selection["home"]).resolve()
  69. if not self.home.is_relative_to(dependency_home_root().resolve()):
  70. raise ValueError("config path is outside Hermes state")
  71. self.path = self.home / "config.yaml"
  72. self.previous = read_bytes_or_none(self.path) # config-reader: ok — pm publication: byte-level compare-and-swap rewrite of the local file
  73. expected = selection.get("expected_config")
  74. actual = hashlib.sha256(self.previous).hexdigest() if self.previous is not None else "missing"
  75. if expected is not None and expected != actual:
  76. raise ValueError("Plugin configuration changed since this selection was read; retry.")
  77. yaml = roundtrip_yaml()
  78. config = yaml.load(self.previous.decode("utf-8-sig")) if self.previous else {}
  79. if config is None:
  80. config = {}
  81. if not isinstance(config, dict):
  82. raise ValueError(f"configuration must be a mapping: {self.path}")
  83. plugins = config.setdefault("plugins", {})
  84. if not isinstance(plugins, dict):
  85. raise ValueError(f"plugins must be a mapping in {self.path}")
  86. plugins["enabled"] = sorted(selection["enabled"])
  87. plugins["disabled"] = sorted(selection["disabled"])
  88. settle_record(plugins, selection.get("settled", ()))
  89. output = io.StringIO()
  90. yaml.dump(config, output)
  91. self.proposed = output.getvalue().encode("utf-8")
  92. self.members = candidate_members(selection.get("extra_dirs", ()), proposed_home=self.home,
  93. enabled=selection["enabled"], disabled=selection["disabled"])
  94. def publish(self, project: Path) -> None:
  95. if selection_snapshot() != self.configs or read_bytes_or_none(self.path) != self.previous: # config-reader: ok — pm publication: byte-level compare-and-swap rewrite of the local file
  96. raise ValueError("plugin configuration changed while preparing publication; retry")
  97. row = {"config": str(self.path),
  98. "previous": base64.b64encode(self.previous).decode() if self.previous is not None else None,
  99. "facts_before": file_digest(runtime_facts_path(project)),
  100. "config_after": hashlib.sha256(self.proposed).hexdigest()}
  101. durable_write_bytes(install_state_dir(project) / "publication.json", json.dumps(row).encode())
  102. durable_write_bytes(self.path, self.proposed)
  103. class StagedPlugin:
  104. def __init__(self, plugin: dict):
  105. from pm.store import tree_digest
  106. from pm.workspace import enabled_plugin_dirs, member_sources
  107. self.configs = selection_snapshot()
  108. self.target = Path(plugin["target"]).absolute()
  109. self.staged = Path(plugin["staged"]).resolve()
  110. if (not self.target.resolve().is_relative_to(dependency_home_root().resolve())
  111. or self.target.parent.name != "plugins" or self.target.is_symlink()
  112. or self.staged == self.target.resolve() or self.staged.is_relative_to(self.target.resolve())
  113. or self.target.resolve().is_relative_to(self.staged)):
  114. raise ValueError("plugin publication paths escape or overlap their home")
  115. manifest = validate_manifest(self.staged)
  116. if manifest.get("name", self.target.name) != self.target.name:
  117. raise ValueError("The updated plugin changed its installed name; reinstall it explicitly.")
  118. self.staged_digest = tree_digest(self.staged)
  119. self.metadata = self.target.parent / ".install-metadata.json"
  120. previous = read_bytes_or_none(self.metadata)
  121. current = _metadata_records(previous)
  122. self.old_record = plugin["old_metadata"].get(self.target.name)
  123. if current.get(self.target.name) != self.old_record:
  124. raise ValueError("Plugin install metadata changed while preparing the update; retry.")
  125. self.new_record = plugin["new_metadata"].get(self.target.name)
  126. if self.new_record is None:
  127. raise ValueError("Plugin publication omitted its install metadata record.")
  128. self.target_digest = tree_digest(self.target) if self.target.exists() else None
  129. if self.target_digest != plugin["target_digest"]:
  130. raise ValueError("Plugin files changed while preparing the update; retry.")
  131. sources = member_sources(enabled_plugin_dirs(installing=self.target))
  132. self.active = self.target.resolve() in sources
  133. self.members = {}
  134. if self.active:
  135. sources[self.target.resolve()] = self.staged
  136. self.members = {identity: source for identity, source in sources.items()
  137. if _admitted(source, new=source == self.staged) and _is_member_candidate(source)}
  138. def publish(self, project: Path) -> None:
  139. import os
  140. import uuid
  141. from hermes_cli.auth import _file_lock
  142. from pm.store import tree_digest
  143. if selection_snapshot() != self.configs:
  144. raise ValueError("Plugin enablement changed while preparing the update; retry.")
  145. if tree_digest(self.staged) != self.staged_digest:
  146. raise ValueError("Staged plugin files changed while preparing the update; retry.")
  147. lock = self.metadata.with_name(f"{self.metadata.name}.lock")
  148. with _file_lock(lock, _METADATA_LOCK_HOLDER, 10.0,
  149. "Timed out waiting for the plugin install metadata lock"):
  150. previous = read_bytes_or_none(self.metadata)
  151. metadata = _metadata_records(previous)
  152. if metadata.get(self.target.name) != self.old_record:
  153. raise ValueError("Plugin install metadata changed while preparing the update; retry.")
  154. metadata[self.target.name] = self.new_record
  155. proposed = (json.dumps(metadata, indent=2, sort_keys=True) + "\n").encode()
  156. current = tree_digest(self.target) if self.target.exists() else None
  157. if current != self.target_digest:
  158. raise ValueError("Plugin files changed while preparing the update; retry.")
  159. backup = self.target.parent / f".previous-{uuid.uuid4().hex}"
  160. row = {
  161. "kind": "plugin", "target": str(self.target), "backup": str(backup), "metadata": str(self.metadata),
  162. "target_existed": self.target.exists(), "facts_before": file_digest(runtime_facts_path(project)),
  163. "metadata_before": base64.b64encode(previous).decode() if previous is not None else None,
  164. "metadata_after": base64.b64encode(proposed).decode(),
  165. }
  166. durable_write_bytes(install_state_dir(project) / "publication.json", json.dumps(row).encode())
  167. if self.target.exists():
  168. os.replace(self.target, backup)
  169. os.replace(self.staged, self.target)
  170. durable_write_bytes(self.metadata, proposed)