web_server_plugin_profiles.py 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283
  1. """Dashboard plugins of a secondary served profile (PLG-3, #134889).
  2. A gateway serving several profiles imports dashboard plugin code for its launch profile only. A
  3. request scoped to another served profile (its native grant, a ``?profile=`` selection) gets that
  4. profile's own plugins: discovered under its own home and the root, gated by its own ``plugins.enabled`` /
  5. ``plugins.disabled``, and run in its own plugin host (bound to its home and secret scope) whatever
  6. its ``plugins.isolation`` says, so another profile's plugin code never enters this process. Bundled
  7. plugins are Hermes code and stay in-process. The host protocol is request/response, so a secondary
  8. profile's plugin websockets are refused by name until it carries them.
  9. """
  10. from __future__ import annotations
  11. import asyncio
  12. import contextvars
  13. import logging
  14. import threading
  15. import time
  16. from concurrent.futures import ThreadPoolExecutor
  17. from contextlib import ExitStack, contextmanager
  18. from pathlib import Path
  19. from typing import Any, Callable, Iterator, Optional
  20. from urllib.parse import parse_qsl, urlencode
  21. from fastapi.responses import JSONResponse, Response
  22. from starlette import status
  23. from starlette._utils import get_route_path
  24. from starlette.websockets import WebSocket
  25. from hermes_cli.config import get_process_hermes_home
  26. _log = logging.getLogger("hermes_cli.web_server")
  27. # Valid for every served profile, so a profile's plugin code must never receive them.
  28. _GATEWAY_CREDENTIAL_HEADERS = frozenset({
  29. "authorization", "cookie", "host", "x-hermes-gateway-ticket", "x-hermes-session-token"})
  30. # Every query credential the gateway accepts (``web_server_chat._ws_auth_ok``, ``_has_valid_query_token``,
  31. # the display bridge, the PTY reattach key) and the profile selector; compared after URL-decoding.
  32. _GATEWAY_QUERY_KEYS = frozenset({"token", "ticket", "internal", "display_ticket", "attach", "profile"})
  33. _profile_plugins: dict[str, list] = {}
  34. # Bumped by each explicit rescan of a profile: a scan begun before it publishes neither its list nor a miss.
  35. _profile_rescans: dict[str, int] = {}
  36. # Guards these module dicts only; disk scans run without it, so a scan never blocks another caller.
  37. _profile_plugins_lock = threading.Lock()
  38. # Requests forwarded to a profile's plugin host wait on that profile's own threads, not the gateway's
  39. # shared ``asyncio.to_thread`` pool: a slow plugin queues behind its own profile's plugin requests
  40. # instead of stalling every route that offloads blocking work.
  41. _HOSTED_REQUEST_THREADS = 4
  42. # How long a forwarded request may take, queueing included, before it answers 504. The host protocol
  43. # has no cancel, so the host may still finish the abandoned handler; the gateway's thread is freed.
  44. HOSTED_REQUEST_TIMEOUT_SECS = 60.0
  45. _hosted_executors: dict[str, ThreadPoolExecutor] = {}
  46. # A name a secondary profile lacks rescans its plugin dirs (it may be newly installed), then not again
  47. # for this long, so 404 probes can't force a disk scan per request. An explicit rescan clears it.
  48. _UNKNOWN_PLUGIN_RESCAN_SECS = 10.0
  49. _unknown_plugins: dict[tuple[str, str], float] = {}
  50. def secondary_profile_home() -> Optional[Path]:
  51. """The active scope's home when it is a profile other than the launch profile, else None."""
  52. from hermes_constants import get_hermes_home, hermes_home_key
  53. home = get_hermes_home()
  54. return None if hermes_home_key(home) == hermes_home_key(get_process_hermes_home()) else Path(home)
  55. def _scan_profile_plugins(home: Path) -> list:
  56. """The profile at ``home``'s dashboard plugins, read from disk: its own ``plugins/``, then the
  57. root's (as a standalone ``hermes --profile <name> serve`` scanned them; the profile's own copy
  58. wins a same-name conflict), then the bundled ones."""
  59. from hermes_cli.plugins import get_bundled_plugins_dir
  60. from hermes_cli.profiles import _get_default_hermes_home
  61. from hermes_cli.web_server_dashboard import _discover_dashboard_plugins
  62. bundled, own = get_bundled_plugins_dir(), Path(home) / "plugins"
  63. dirs = [own] + [r for r in [_get_default_hermes_home() / "plugins"]
  64. if r.resolve(strict=False) != own.resolve(strict=False)]
  65. return _discover_dashboard_plugins(
  66. [(d, "user") for d in dirs] + [(bundled / "memory", "bundled"), (bundled, "bundled")])
  67. def _published(key: str, rescans: int, plugins: list) -> list:
  68. """Cache ``plugins`` for ``key`` unless an explicit rescan began after this scan did; return them."""
  69. with _profile_plugins_lock:
  70. if _profile_rescans.get(key, 0) == rescans:
  71. _profile_plugins[key] = plugins
  72. return plugins
  73. def profile_dashboard_plugins(home: Path, force_rescan: bool = False) -> list:
  74. """Dashboard plugins of the profile at ``home`` (:func:`_scan_profile_plugins`), cached per home
  75. like the launch profile's list. An explicit rescan also forgets the profile's cached misses."""
  76. from hermes_constants import hermes_home_key
  77. key = hermes_home_key(home)
  78. with _profile_plugins_lock:
  79. if force_rescan:
  80. _profile_rescans[key] = _profile_rescans.get(key, 0) + 1
  81. for unknown in [k for k in _unknown_plugins if k[0] == key]:
  82. del _unknown_plugins[unknown]
  83. cached, rescans = _profile_plugins.get(key), _profile_rescans.get(key, 0)
  84. if cached is None or force_rescan or any(not Path(p["_dir"]).is_dir() for p in cached):
  85. cached = _published(key, rescans, _scan_profile_plugins(home))
  86. return cached
  87. def _named(plugins: list, name: str) -> Optional[dict]:
  88. return next((p for p in plugins if p.get("name") == name), None)
  89. def rescanned_plugin(home: Path, name: str) -> Optional[dict]:
  90. """The profile at ``home``'s entry for ``name`` after a rescan, or None; a name found missing
  91. within the last :data:`_UNKNOWN_PLUGIN_RESCAN_SECS` is answered without one. Blocking: the
  92. request gate runs it on a worker thread."""
  93. from hermes_constants import hermes_home_key
  94. home_key, now = hermes_home_key(home), time.monotonic()
  95. key = (home_key, name)
  96. with _profile_plugins_lock:
  97. if _unknown_plugins.get(key, now) > now:
  98. return None
  99. rescans = _profile_rescans.get(home_key, 0)
  100. # Not an explicit rescan: other names' unexpired misses survive it, so probes alternating names
  101. # can't defeat them.
  102. plugin = _named(_published(home_key, rescans, _scan_profile_plugins(home)), name)
  103. with _profile_plugins_lock:
  104. for expired in [k for k, until in _unknown_plugins.items() if until <= now]:
  105. del _unknown_plugins[expired]
  106. if plugin is not None:
  107. _unknown_plugins.pop(key, None)
  108. elif _profile_rescans.get(home_key, 0) == rescans: # an explicit rescan since may have found it
  109. _unknown_plugins[key] = now + _UNKNOWN_PLUGIN_RESCAN_SECS
  110. return plugin
  111. def plugin_api_path(plugin: Optional[dict]) -> Optional[Path]:
  112. """The resolved backend file of a discovered plugin entry, or None."""
  113. if not plugin or not plugin.get("_api_file"):
  114. return None
  115. return (Path(plugin["_dir"]) / plugin["_api_file"]).resolve()
  116. def _in_process_api_file(name: str) -> Optional[Path]:
  117. """The file this process's ``/api/plugins/<name>/`` router runs: the imported module's when one is
  118. mounted (a hosted forward route has none here), else the copy the first request would mount,
  119. the launch profile's discovery entry."""
  120. import sys
  121. from hermes_cli.web_server import _get_dashboard_plugins, app
  122. from hermes_cli.web_server_dashboard import _launch_profile_scope, _plugin_api_mounted
  123. if _plugin_api_mounted(app, name):
  124. file = getattr(sys.modules.get(f"hermes_dashboard_plugin_{name}"), "__file__", None)
  125. return Path(file).resolve() if file else None
  126. with _launch_profile_scope():
  127. return plugin_api_path(_named(_get_dashboard_plugins(), name))
  128. def _runs_in_process(plugin: Optional[dict]) -> bool:
  129. """Whether a secondary profile's entry may use this process's router: only its bundled copy,
  130. and only when that router runs that very file (a launch-profile user plugin can shadow the
  131. bundled name, or a disabled one hide it)."""
  132. return (plugin is not None and plugin.get("source") == "bundled"
  133. and _in_process_api_file(plugin["name"]) == plugin_api_path(plugin))
  134. def secondary_plugin(name: str) -> Optional[dict]:
  135. """The active secondary profile's own entry for ``name``, or None (also in the launch scope)."""
  136. home = secondary_profile_home()
  137. return None if home is None else _named(profile_dashboard_plugins(home), name)
  138. def _secondary_hosted_plugin(name: str) -> Optional[dict]:
  139. """The active secondary profile's own entry for ``name`` when its plugin host serves it, or None:
  140. the launch profile's scope, an unknown name, or the bundled copy this process runs."""
  141. plugin = secondary_plugin(name)
  142. return None if plugin is None or _runs_in_process(plugin) else plugin
  143. def in_process_router_refused(name: str) -> bool:
  144. """Whether this process's ``/api/plugins/<name>/`` router (the launch profile's copy) must not
  145. serve the active scope: a secondary profile runs only its own bundled copy here."""
  146. return secondary_profile_home() is not None and not _runs_in_process(secondary_plugin(name))
  147. @contextmanager
  148. def plugin_request_scope(scope) -> Iterator[None]:
  149. """Bind a plugin request's ``?profile=`` selection for its routing decision (the route
  150. dependency binds it again for the handler). An unknown profile binds nothing: the route
  151. dependency answers it as for any other route."""
  152. from fastapi import HTTPException
  153. from hermes_cli.web_server_profiles import _config_profile_scope, _is_current_profile
  154. profile = dict(parse_qsl(scope.get("query_string", b"").decode("latin-1"))).get("profile")
  155. with ExitStack() as stack:
  156. if not _is_current_profile(profile):
  157. try:
  158. stack.enter_context(_config_profile_scope(profile))
  159. except HTTPException as exc:
  160. _log.debug("Plugin request for profile %r left unscoped: %s", profile, exc.detail)
  161. yield
  162. def hosted_response(result: dict[str, Any]) -> Response:
  163. """A plugin host's buffered ``asgi`` answer as a response."""
  164. response = Response(content=result["body"], status_code=int(result["status"]))
  165. for key, value in result["headers"]: # a list, so repeated headers (Set-Cookie) all survive
  166. if key.lower() not in {"content-length", "transfer-encoding", "connection"}:
  167. response.headers.append(key, value)
  168. return response
  169. def _hosted_executor(home: Path) -> ThreadPoolExecutor:
  170. from hermes_constants import hermes_home_key
  171. key = hermes_home_key(home)
  172. with _profile_plugins_lock:
  173. executor = _hosted_executors.get(key)
  174. if executor is None:
  175. executor = _hosted_executors[key] = ThreadPoolExecutor(
  176. _HOSTED_REQUEST_THREADS, thread_name_prefix=f"plugin-host-requests-{Path(home).name}")
  177. return executor
  178. async def run_hosted_request(home: Path, name: str, call: Callable[[float], dict[str, Any]]) -> Response:
  179. """Run ``call(timeout)``, one plugin host ``asgi`` round trip for plugin ``name`` of the profile at
  180. ``home``, on that profile's own threads in this request's context; its answer, or 504 after
  181. :data:`HOSTED_REQUEST_TIMEOUT_SECS`. Other failures propagate."""
  182. timeout = HOSTED_REQUEST_TIMEOUT_SECS
  183. deadline, context = time.monotonic() + timeout, contextvars.copy_context()
  184. job = asyncio.get_running_loop().run_in_executor(
  185. _hosted_executor(home), context.run, lambda: call(max(deadline - time.monotonic(), 0.01)))
  186. try:
  187. return hosted_response(await asyncio.wait_for(job, timeout))
  188. except TimeoutError:
  189. _log.warning("Plugin %s: its plugin host did not answer within %gs", name, timeout)
  190. return JSONResponse({"detail": f"plugin {name!r} did not answer within {timeout:g}s"}, status_code=504)
  191. async def forward_secondary_plugin_request(request, name: str) -> Optional[Response]:
  192. """Serve ``/api/plugins/<name>/`` for a secondary profile through its own plugin host, or None
  193. when the in-process router answers (the launch profile, or a bundled plugin). Consent has been
  194. checked in the request's scope already."""
  195. plugin, home = _secondary_hosted_plugin(name), secondary_profile_home()
  196. if plugin is None or home is None:
  197. return None
  198. if not plugin.get("_api_file"):
  199. return JSONResponse({"detail": "Not Found"}, status_code=404)
  200. rest = get_route_path(request.scope).split("/", 4)
  201. path = "/" + (rest[4] if len(rest) > 4 else "")
  202. query = urlencode([(k, v) for k, v in parse_qsl(request.url.query, keep_blank_values=True)
  203. if k not in _GATEWAY_QUERY_KEYS])
  204. headers = [(k, v) for k, v in request.headers.items() if k.lower() not in _GATEWAY_CREDENTIAL_HEADERS]
  205. body = await request.body()
  206. from hermes_cli.plugin_host_http_auth import admitted_for_sensitive_route
  207. authenticated = admitted_for_sensitive_route(request)
  208. def call(timeout: float) -> dict[str, Any]:
  209. from hermes_cli.plugins import get_plugin_manager
  210. host = get_plugin_manager()._plugin_host() # the active (secondary) profile's own host
  211. return host.asgi_request(name, str(plugin["_dir"]), str(plugin["_api_file"]), request.method, path,
  212. query, headers, body, timeout=timeout, authenticated=authenticated)
  213. try:
  214. return await run_hosted_request(home, name, call)
  215. except Exception as exc: # health: allow BLE001 -- the host runs third-party code; any failure is this request's 502
  216. _log.warning("Plugin %s: its profile's plugin host could not serve %s: %s", name, path, exc)
  217. return JSONResponse({"detail": f"plugin {name!r} could not run in this profile's plugin host"},
  218. status_code=502)
  219. async def refuse_secondary_plugin_socket(scope, receive, send, name: str) -> bool:
  220. """Answer a secondary profile's socket to a plugin its host serves, and return True; False when
  221. the in-process router takes it. An authenticated dial is refused by name (HTTP 501 before
  222. accept, so Desktop's reconnect budget counts it); any other gets the plain policy close."""
  223. if _secondary_hosted_plugin(name) is None:
  224. return False
  225. from hermes_cli.web_server_chat import _ws_auth_ok
  226. socket = WebSocket(scope, receive, send)
  227. if not ((scope.get("state") or {}).get("native_http_principal") or _ws_auth_ok(socket)):
  228. await send({"type": "websocket.close", "code": status.WS_1008_POLICY_VIOLATION})
  229. return True
  230. detail = f"plugin {name!r} runs in this profile's plugin host, which does not carry websockets yet"
  231. _log.info("Plugin %s: refused a websocket for %s: %s", name, secondary_profile_home(), detail)
  232. if "websocket.http.response" in (scope.get("extensions") or {}):
  233. await socket.send_denial_response(JSONResponse({"detail": detail}, status_code=501))
  234. else:
  235. await send({"type": "websocket.close", "code": status.WS_1008_POLICY_VIOLATION, "reason": detail[:120]})
  236. return True