plugins_cmd_inspect.py 9.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190
  1. """Read-only inspection of a plugin source before install: which halves (agent, desktop) it ships.
  2. The gateway's answer to the install dialog's repository check, for a client with no Git of its own
  3. (the browser-hosted app). Native Desktop runs the same check in Electron
  4. (``apps/desktop/electron/desktop-plugin-install.ts`` ``probePluginRepo``); the detection rules and the
  5. result shape match it. The source goes through the installer's own resolution, kill list and
  6. clone (non-interactive, credentials scrubbed, ``plugins.clone_timeout_seconds``) into a temporary
  7. directory outside every profile's ``plugins/``. Nothing is installed, imported or run: only the
  8. manifest files are read, as text.
  9. """
  10. from __future__ import annotations
  11. import json
  12. import tempfile
  13. import threading
  14. import time
  15. from concurrent.futures import Future
  16. from pathlib import Path
  17. from typing import Any, Optional
  18. import hermes_yaml as yaml
  19. #: A manifest is a few hundred bytes; never read a hostile multi-megabyte one into memory.
  20. _MANIFEST_MAX_BYTES = 256 * 1024
  21. #: How long a successful inspection answers a repeat of the same request (see ``inspect_plugin_source``).
  22. _RESULT_TTL_SECONDS = 600
  23. #: ``(home, catalog_name, identifier)`` -> ``[future, finished_at]``; ``finished_at`` is None while it runs.
  24. _inspections: dict[tuple[str, str, str], list] = {}
  25. _inspections_lock = threading.Lock()
  26. def _pc():
  27. """The facade, read at call time: tests patch ``plugins_cmd.<name>`` and sibling calls must see it."""
  28. from hermes_cli import plugins_cmd
  29. return plugins_cmd
  30. def _read_manifest(path: Optional[Path], loads) -> dict[str, Any]:
  31. """The manifest as a dict when the file is a small regular file that parses, else ``{}``."""
  32. if path is None:
  33. return {}
  34. try:
  35. if path.is_symlink() or not path.is_file() or path.stat().st_size > _MANIFEST_MAX_BYTES:
  36. return {}
  37. data = loads(path.read_text(encoding="utf-8-sig"))
  38. except (OSError, UnicodeDecodeError, ValueError, yaml.YAMLError):
  39. return {}
  40. return data if isinstance(data, dict) else {}
  41. def _manifest_name(data: dict[str, Any]) -> Optional[str]:
  42. name = data.get("name")
  43. return name.strip() if isinstance(name, str) and name.strip() else None
  44. #: Files beside a ``plugin.yaml`` that the agent side loads: a ``register(ctx)`` package, or a dashboard
  45. #: tab/backend (``dashboard/manifest.json``, often with a ``plugin_api.py``) the gateway mounts.
  46. _AGENT_PAYLOAD_FILES = ("__init__.py", "dashboard/manifest.json")
  47. def _yaml_ships_agent_payload(root: Path, manifest: dict[str, Any]) -> bool:
  48. """Whether a ``plugin.yaml`` folder has something for the agent side to load. A manifest alone is not
  49. enough: desktop-only plugins ship one beside ``desktop/plugin.js`` for metadata, and installing those
  50. into the backend's ``plugins/`` puts down a package that loads nothing."""
  51. if any((root / rel).is_file() for rel in _AGENT_PAYLOAD_FILES):
  52. return True
  53. # The loader's manifest-only language pack (``_is_manifest_only_language_pack``), judged the way
  54. # ``hermes plugins validate`` does: declared locales plus the folder that holds them.
  55. return bool(manifest.get("provides_locales")) and (root / "locales").is_dir()
  56. def detect_components(root: Path, fallback_name: str) -> dict[str, Any]:
  57. """Electron's ``detectPluginComponents``: an agent half is a portable ``plugin.json``, or a
  58. ``plugin.yaml``/``plugin.yml`` with an agent payload beside it (:func:`_yaml_ships_agent_payload`);
  59. a desktop half is ``plugin.js`` at the root or in ``desktop/``. ``__init__.py`` is one payload, not
  60. a requirement: a manifest-only package with a ``dashboard/plugin_api.py`` backend is installable."""
  61. yaml_path = next((root / n for n in ("plugin.yaml", "plugin.yml") if (root / n).is_file()), None)
  62. yaml_manifest = _read_manifest(yaml_path, yaml.safe_load)
  63. portable = root / "plugin.json"
  64. agent = (yaml_path is not None and _yaml_ships_agent_payload(root, yaml_manifest)) or portable.is_file()
  65. desktop = (root / "plugin.js").is_file() or (root / "desktop" / "plugin.js").is_file()
  66. agent_name = None
  67. if agent:
  68. agent_name = (_manifest_name(yaml_manifest) or _manifest_name(_read_manifest(portable, json.loads))
  69. or fallback_name)
  70. return {"agent": agent, "desktop": desktop, "agent_name": agent_name}
  71. def _desktop_folder_name(git_url: str, subdir: Optional[str]) -> str:
  72. """Electron's ``desktopPluginFolderName``: the subdirectory's last real segment, else the repo name."""
  73. parts = [p for p in (subdir or "").replace("\\", "/").split("/") if p and p not in (".", "desktop")]
  74. return parts[-1] if parts else _pc()._repo_name_from_url(git_url)
  75. def _failure(error: str, warnings: list[str], insecure: bool) -> dict[str, Any]:
  76. return {"ok": False, "agent": False, "desktop": False, "warnings": warnings, "insecure": insecure,
  77. "error": error}
  78. def inspect_plugin_source(identifier: str, *, catalog_name: Optional[str] = None) -> dict[str, Any]:
  79. """``{ok, agent, desktop, agent_name, desktop_name, sha, warnings, insecure}``, or ``ok: False`` with
  80. ``error``. *catalog_name* inspects the curated entry at its reviewed pin (its repo replaces
  81. *identifier*), so the dialog shows exactly what the catalog install will put down. ``sha`` is the
  82. commit that was read: a source that moves after review must not install a tree nobody inspected,
  83. so the install is held to it, as native Desktop's probe is.
  84. A repeat of a request (same profile home, catalog name and source) joins the clone still running
  85. for it, or reads a successful answer it produced within :data:`_RESULT_TTL_SECONDS`. The browser
  86. stops waiting before a slow clone can finish (``plugins.clone_timeout_seconds`` reaches an hour per
  87. Git step); its Retry must collect that clone's answer, not start another under the same deadline.
  88. A failed read is never kept, so a Retry after one inspects afresh."""
  89. from hermes_constants import get_hermes_home
  90. key = (str(get_hermes_home()), catalog_name or "", identifier)
  91. now = time.monotonic()
  92. with _inspections_lock:
  93. for stale in [k for k, (_, done) in _inspections.items()
  94. if done is not None and now - done > _RESULT_TTL_SECONDS]:
  95. del _inspections[stale]
  96. slot = _inspections.get(key)
  97. owner = slot is None
  98. if owner:
  99. slot = _inspections[key] = [Future(), None]
  100. future: Future = slot[0]
  101. if not owner:
  102. return _copy(future.result())
  103. try:
  104. result = _inspect(identifier, catalog_name)
  105. except BaseException as exc:
  106. with _inspections_lock:
  107. _inspections.pop(key, None)
  108. future.set_exception(exc)
  109. raise
  110. with _inspections_lock:
  111. if result["ok"]:
  112. slot[1] = time.monotonic()
  113. else:
  114. _inspections.pop(key, None)
  115. future.set_result(result)
  116. return _copy(result)
  117. def _copy(result: dict[str, Any]) -> dict[str, Any]:
  118. """Each caller gets its own answer: one shared by joined requests must not be edited through another."""
  119. return {**result, "warnings": list(result["warnings"])}
  120. def forget_inspection(identifier: str, *, catalog_name: Optional[str] = None) -> None:
  121. """Drop the kept answer for this source in the current profile home once an install consumed it: a
  122. source that moved since must be read afresh when the dialog re-opens, not served for the rest of
  123. :data:`_RESULT_TTL_SECONDS`. A read still running is left for the requests joined to it."""
  124. from hermes_constants import get_hermes_home
  125. key = (str(get_hermes_home()), catalog_name or "", identifier)
  126. with _inspections_lock:
  127. if _inspections.get(key, [None, None])[1] is not None:
  128. del _inspections[key]
  129. def _inspect(identifier: str, catalog_name: Optional[str]) -> dict[str, Any]:
  130. pc = _pc()
  131. revision = None
  132. names: tuple[str, ...] = ()
  133. if catalog_name:
  134. from hermes_cli import plugins_cmd_catalog as catalog
  135. entry = catalog.get_live_catalog_entry(catalog_name)
  136. if entry is None:
  137. return _failure(f"'{catalog_name}' is not in the Hermes plugin catalog.", [], False)
  138. identifier, revision, names = entry.install_identifier, entry.sha or None, (entry.name,)
  139. try:
  140. git_url, subdir = pc._resolve_git_url(identifier)
  141. except ValueError as exc:
  142. return _failure(str(exc), [], False)
  143. insecure = git_url.startswith(("http://", "file://"))
  144. warnings = ["This URL uses an insecure or local scheme. Prefer https:// or git@ for production installs."] \
  145. if insecure else []
  146. try:
  147. from hermes_cli.plugins_cmd_catalog import raise_if_removed
  148. raise_if_removed(identifier, git_url, *names)
  149. with tempfile.TemporaryDirectory(prefix="hermes-plugin-inspect-") as tmp:
  150. clone = Path(tmp) / "plugin"
  151. sha = pc._clone_plugin_repo(clone, git_url, revision, subdir)
  152. root = pc._resolve_subdir_within(clone, subdir) if subdir else clone
  153. fallback = subdir.rstrip("/").rsplit("/", 1)[-1] if subdir else pc._repo_name_from_url(git_url)
  154. found = detect_components(root, fallback)
  155. except pc.PluginOperationError as exc:
  156. return _failure(str(exc), warnings, insecure)
  157. if not found["agent"] and not found["desktop"]:
  158. return _failure("No agent or desktop plugin artifacts found in this repository.", warnings, insecure)
  159. return {"ok": True, **found, "desktop_name": _desktop_folder_name(git_url, subdir) if found["desktop"] else None,
  160. "sha": sha, "warnings": warnings, "insecure": insecure}