plugins_state.py 8.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195
  1. """Plugin-owned durable state and namespaced settings helpers (split out of hermes_cli.plugins)."""
  2. from __future__ import annotations
  3. import json
  4. import os
  5. import re
  6. import threading
  7. from contextlib import contextmanager
  8. from pathlib import Path
  9. from typing import Any, Dict, Mapping
  10. from hermes_constants import get_hermes_home
  11. from hermes_cli.plugins_manifest import _portable_data_namespace
  12. _PLUGIN_SETTING_SEGMENT_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$")
  13. _PLUGIN_SETTING_RESERVED_ROOTS = frozenset({"model", "plugins", "security", "settings"})
  14. _PLUGIN_STATE_KEY_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$")
  15. _PLUGIN_STATE_QUOTA_BYTES = 10 * 1024 * 1024
  16. _PLUGIN_STATE_LOCKS: dict[str, threading.RLock] = {}
  17. _PLUGIN_STATE_LOCKS_GUARD = threading.Lock()
  18. def _plugin_relative_segments(key: str) -> tuple[str, ...]:
  19. """Validate/split a plugin-relative settings key; global paths, traversal, and core roots are rejected
  20. before any config read.
  21. The public API accepts only relative keys (``endpoint`` or ``retry.policy``). See #64227.
  22. """
  23. if not isinstance(key, str):
  24. raise ValueError("Expected a plugin-relative config key string")
  25. segments = tuple(key.split("."))
  26. invalid = not key or "/" in key or "\\" in key or segments[0].lower() in _PLUGIN_SETTING_RESERVED_ROOTS
  27. if invalid or not all(_PLUGIN_SETTING_SEGMENT_RE.fullmatch(segment) for segment in segments):
  28. raise ValueError(
  29. "Expected a plugin-relative config key such as 'endpoint' or "
  30. "'retry.policy'; global, cross-plugin, and traversal paths are forbidden"
  31. )
  32. return segments
  33. def _nested_plugin_value(root: object, segments: tuple[str, ...], default: Any) -> Any:
  34. """Walk ``segments`` through nested mappings; ``default`` on the first miss."""
  35. current = root
  36. for segment in segments:
  37. if not isinstance(current, Mapping) or segment not in current:
  38. return default
  39. current = current[segment]
  40. return current
  41. def _nested_plugin_mapping(segments: tuple[str, ...], value: Any) -> dict[str, Any]:
  42. """Wrap ``value`` in nested single-key dicts, outermost first."""
  43. nested: Any = value
  44. for segment in reversed(segments):
  45. nested = {segment: nested}
  46. return nested
  47. def _plugin_settings_entry(config: object, plugin_id: str) -> Mapping[str, Any] | None:
  48. """``plugins.entries.<plugin_id>`` as a mapping, else ``None``."""
  49. entry = _nested_plugin_value(config, ("plugins", "entries", plugin_id), None)
  50. return entry if isinstance(entry, Mapping) else None
  51. def save_plugin_setting(plugin_id: str, segments: tuple[str, ...], value: Any) -> None:
  52. """Atomically write one value under ``plugins.entries.<plugin_id>.settings``.
  53. THE writer for plugin settings: ``PluginContext.set_config`` (the plugin itself) and the
  54. Desktop/TUI ``plugins.manage settings`` action both land here so managed-install and
  55. administrator-managed-key refusals, the cross-process lock and the fail-closed raw read
  56. are enforced once. ``segments`` must already be validated by :func:`_plugin_relative_segments`.
  57. """
  58. from hermes_cli import config as config_mod
  59. from hermes_cli import managed_scope
  60. if config_mod.is_managed():
  61. raise PermissionError("Plugin settings cannot be changed in a managed install")
  62. full_path = ("plugins", "entries", plugin_id, "settings", *segments)
  63. dotted_path = ".".join(full_path)
  64. if managed_scope.is_key_managed(dotted_path):
  65. raise PermissionError(f"Plugin setting {dotted_path!r} is administrator-managed")
  66. partial = _nested_plugin_mapping(full_path[:4], _nested_plugin_mapping(segments, value))
  67. # The lock covers merge-read plus atomic save so sibling plugin writes (threads or
  68. # processes) cannot race between the two steps.
  69. with _locked_plugin_state(config_mod.get_config_path()), config_mod._CONFIG_LOCK:
  70. # Fail closed on malformed YAML: save_config degrades parse failures to {} — safe
  71. # for reads, destructive for read-modify-write.
  72. config_mod.read_user_config_raw()
  73. config_mod.save_config(partial, preserve_keys={full_path}, merge_existing=True)
  74. def _plugin_data_namespace(plugin_id: str, data_namespace: str) -> str:
  75. """Return one Windows-safe directory component for plugin-owned data. Portable Agent Plugins already
  76. receive this exact PLUGIN_DATA path; otherwise the fixed prefix avoids Windows reserved device names and
  77. the digest prevents fold collisions."""
  78. candidate = data_namespace or plugin_id
  79. portable = data_namespace and candidate.startswith("agent-plugin-")
  80. if portable and re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_-]{0,191}", candidate):
  81. return candidate
  82. return _portable_data_namespace(candidate)
  83. @contextmanager
  84. def _locked_plugin_state(path: Path):
  85. """Serialize state read-modify-write across threads/processes (fcntl / msvcrt). The lock lives in a
  86. sibling file because atomic replacement changes the target's inode."""
  87. lock_path = path.with_name(f".{path.name}.lock")
  88. with _PLUGIN_STATE_LOCKS_GUARD:
  89. thread_lock = _PLUGIN_STATE_LOCKS.setdefault(str(lock_path.resolve(strict=False)), threading.RLock())
  90. with thread_lock:
  91. lock_path.parent.mkdir(parents=True, exist_ok=True)
  92. with open(lock_path, "a+b") as handle:
  93. if os.name == "nt": # pragma: no cover - exercised on Windows CI
  94. import msvcrt
  95. if handle.seek(0, os.SEEK_END) == 0:
  96. handle.write(b"\0")
  97. handle.flush()
  98. handle.seek(0)
  99. msvcrt.locking(handle.fileno(), msvcrt.LK_LOCK, 1)
  100. else:
  101. import fcntl
  102. fcntl.flock(handle.fileno(), fcntl.LOCK_EX)
  103. try:
  104. yield
  105. finally:
  106. if os.name == "nt": # pragma: no cover - exercised on Windows CI
  107. handle.seek(0)
  108. msvcrt.locking(handle.fileno(), msvcrt.LK_UNLCK, 1)
  109. else:
  110. fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
  111. class PluginState:
  112. """Atomic, quota-bounded JSON key/value state owned by one plugin."""
  113. def __init__(self, plugin_id: str, data_namespace: str = "") -> None:
  114. self._data_namespace = _plugin_data_namespace(plugin_id, data_namespace)
  115. @property
  116. def data_dir(self) -> Path:
  117. """Profile-scoped directory matching portable plugins' PLUGIN_DATA."""
  118. return get_hermes_home() / "plugin-data" / self._data_namespace
  119. @property
  120. def path(self) -> Path:
  121. return self.data_dir / "state.json"
  122. @property
  123. def quota_bytes(self) -> int:
  124. return _PLUGIN_STATE_QUOTA_BYTES
  125. @staticmethod
  126. def _validate_key(key: str) -> None:
  127. if not isinstance(key, str) or not _PLUGIN_STATE_KEY_RE.fullmatch(key) or ".." in key:
  128. raise ValueError(
  129. "Plugin state keys must be 1-128 characters using letters, "
  130. "numbers, '_', '-', '.', or ':' (without '..')"
  131. )
  132. def _read_unlocked(self) -> dict[str, Any]:
  133. try:
  134. with open(self.path, encoding="utf-8-sig") as handle:
  135. data = json.load(handle)
  136. except FileNotFoundError:
  137. return {}
  138. except (OSError, ValueError) as exc:
  139. raise RuntimeError(f"Cannot parse plugin state {self.path}: {exc}") from exc
  140. if not isinstance(data, dict):
  141. raise RuntimeError(f"Cannot parse plugin state {self.path}: root must be an object")
  142. return data
  143. def get(self, key: str, default: Any = None) -> Any:
  144. """Read a JSON value, returning *default* when the key is absent."""
  145. self._validate_key(key)
  146. with _locked_plugin_state(self.path):
  147. return self._read_unlocked().get(key, default)
  148. def set(self, key: str, value: Any) -> None:
  149. """Atomically set one JSON value without dropping concurrent updates."""
  150. self._validate_key(key)
  151. with _locked_plugin_state(self.path):
  152. data = self._read_unlocked()
  153. data[key] = value
  154. try:
  155. encoded = json.dumps(data, ensure_ascii=False, indent=2).encode("utf-8")
  156. except (TypeError, ValueError) as exc:
  157. raise ValueError(f"Plugin state value for {key!r} is not JSON-serializable") from exc
  158. if len(encoded) > self.quota_bytes:
  159. raise ValueError(
  160. f"Plugin state quota exceeded: {len(encoded)} bytes is greater "
  161. f"than the {self.quota_bytes}-byte per-plugin quota"
  162. )
  163. from utils import atomic_json_write
  164. atomic_json_write(self.path, data, mode=0o600)