webapp_access.py 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260
  1. """Web Access routes: Desktop's Web Access pane turns the gateway-served Webapp on and off here.
  2. Thin HTTP over :mod:`hermes_cli.webapp_access`. Every handler acts on the home of the gateway that
  3. serves the requested profile; start and stop write its ``webapp:`` config and restart that gateway,
  4. which reads the config only when it starts. Start, Stop and Restart run one at a time. Only native
  5. Desktop on this computer reaches them (:func:`owner_on_this_machine`), never a browser, and only on
  6. the gateway's own listener, where its pane calls them (``SurfacePolicy.web_access``; 404 elsewhere).
  7. """
  8. from __future__ import annotations
  9. import asyncio
  10. import threading
  11. import time
  12. from contextlib import asynccontextmanager, contextmanager
  13. from typing import Any, Callable, Optional
  14. from fastapi import APIRouter, Depends, HTTPException, Request
  15. from pydantic import BaseModel
  16. from hermes_cli import webapp_access
  17. from hermes_cli.web_deps import late
  18. from hermes_cli.web_routers._common import (
  19. _profile_scope,
  20. config_scoped_to_thread,
  21. config_write_scope,
  22. destructive_profile,
  23. )
  24. _restart_gateway_after = late("_restart_gateway_after", "hermes_cli.web_server_gateway")
  25. _gateway_restart_failure = late("gateway_restart_failure", "hermes_cli.web_server_gateway")
  26. # One Web Access change at a time in this backend (every Desktop window's pane talks to it): a
  27. # Start, Stop or Restart waits for the one in flight, from its build through the restart request,
  28. # so the Portal's callback, the config and the gateway all end on the last change asked for.
  29. _CHANGE_LOCK = threading.Lock()
  30. _CHANGE_POLL_SECONDS = 0.05
  31. # The Starts in flight, by the gateway they turn the Webapp on for, oldest first: each one's step and
  32. # when it was asked for. The status the pane polls carries one, because building the bundle can take
  33. # minutes: the pane says what is happening, and a pane opened meanwhile shows the Start running
  34. # instead of offering it. A record lives from the request's arrival (``preparing`` while another
  35. # change holds the lock) until the restart it asked for serves the new config, fails, is replaced
  36. # by a Stop, a Restart or a later Start's restart, or outlasts the pane's own wait for it. Mutated
  37. # on the event loop only.
  38. _STARTS: dict[Optional[str], list[dict]] = {}
  39. #: How long a Start's restart is followed after its request answers: as long as the pane waits.
  40. _RESTART_FOLLOW_SECONDS = 90.0
  41. def _start_in_flight(gateway: Optional[str]) -> Optional[dict]:
  42. """The Start the status reports for *gateway*: the newest one past ``preparing`` (a queued one
  43. only waits behind it), else the oldest still waiting. Drops restarts followed for too long."""
  44. now = time.monotonic()
  45. records = [r for r in _STARTS.get(gateway, ()) if r.get("follow_until", now) >= now]
  46. if not records:
  47. _STARTS.pop(gateway, None)
  48. return None
  49. _STARTS[gateway] = records
  50. running = [r for r in records if r["step"] != "preparing"]
  51. return running[-1] if running else records[0]
  52. def _reported(record: Optional[dict]) -> Optional[dict]:
  53. """``start_progress`` as the pane reads it: the step and when the Start was asked for."""
  54. return None if record is None else {"step": record["step"], "started_at": record["started_at"]}
  55. def _restart_settled(record: dict, status: dict, instance: Optional[tuple]) -> bool:
  56. """A Start whose request answered ends once a gateway other than the one its restart replaces
  57. (*instance* answers now) serves the config it wrote, or that restart exited without replacing
  58. it. The gateway it replaces may serve an earlier Start's config on the same port."""
  59. if "restart_pid" not in record:
  60. return False
  61. failure = status.get("restart_failure") or {}
  62. if failure.get("pid") == record["restart_pid"]:
  63. return True
  64. return instance not in (None, record["replaces"]) and webapp_access.serves_config(status)
  65. def _drop(gateway: Optional[str], record: dict) -> None:
  66. """Forget *record* and no other Start, so one Start ending never hides another."""
  67. remaining = [r for r in _STARTS.get(gateway, ()) if r is not record]
  68. if remaining:
  69. _STARTS[gateway] = remaining
  70. else:
  71. _STARTS.pop(gateway, None)
  72. def _drop_followed(gateway: Optional[str]) -> None:
  73. """A Stop, a Restart or a later Start's restart replaces the restart a finished Start is
  74. followed by."""
  75. for record in [r for r in _STARTS.get(gateway, ()) if "restart_pid" in r]:
  76. _drop(gateway, record)
  77. def owner_on_this_machine(request: Request) -> None:
  78. """Web Access decides what this machine exposes, so only native Desktop on this computer may use
  79. it: a request admitted with a native grant (``dashboard_auth.native_http``), a one-use ticket from
  80. the gateway's private control socket, which answers only this OS user, sent from loopback with no
  81. Origin. A browser tab can present neither. Every other credential is refused, the loopback session
  82. token included: on the Webapp it is the browser credential, which a tab holds even when it reaches
  83. the gateway from another machine (an SSH tunnel), and behind the sign-in gate a cookie or bearer
  84. login may come from another device."""
  85. if not getattr(request.state, "native_http_principal", None):
  86. raise HTTPException(status_code=403, detail="Web Access can only be changed from the Hermes app on this computer.")
  87. router = APIRouter(dependencies=[Depends(owner_on_this_machine)])
  88. class StartBody(BaseModel):
  89. mode: str
  90. public_url: Optional[str] = None
  91. @contextmanager
  92. def _gateway_scope(profile: Optional[str], *, config_write: bool):
  93. """Scope to the home of the gateway serving *profile*; yields that gateway's profile name."""
  94. from hermes_constants import profile_name_for_home
  95. with _profile_scope(profile):
  96. name = profile_name_for_home(webapp_access.gateway_home()) or profile
  97. with config_write_scope(name) if config_write else _profile_scope(name):
  98. yield name
  99. async def _scoped(profile: Optional[str], fn: Callable[[Optional[str]], Any], *, config_write: bool = False) -> Any:
  100. """Run ``fn(gateway profile)`` in the gateway's scope off the loop; access errors become 400s.
  101. Only a ``config.yaml`` write takes the config lock; registration waits on the portal outside it."""
  102. def _run():
  103. with _gateway_scope(profile, config_write=config_write) as gateway_profile:
  104. return fn(gateway_profile)
  105. try:
  106. return await asyncio.to_thread(_run)
  107. except webapp_access.WebappAccessError as exc:
  108. raise HTTPException(status_code=400, detail=str(exc)) from exc
  109. async def _in_gateway_home(gateway: Optional[str], fn: Callable[[], Any]) -> Any:
  110. """Run ``fn()`` off the loop in the home and secret scope of the *gateway* profile that
  111. ``_scoped`` resolved, without the skills lock ``_profile_scope`` holds, which every config,
  112. skills and tools request takes: for the slow steps (the bundle build, Portal registration),
  113. which never touch skills. Access errors become 400s."""
  114. try:
  115. return await config_scoped_to_thread(gateway, fn)
  116. except webapp_access.WebappAccessError as exc:
  117. raise HTTPException(status_code=400, detail=str(exc)) from exc
  118. @asynccontextmanager
  119. async def _one_change_at_a_time():
  120. """Hold :data:`_CHANGE_LOCK` for one change. Polled rather than awaited on a worker thread, so a
  121. request cancelled while it waits never takes the lock, and the steps run on any event loop."""
  122. while not _CHANGE_LOCK.acquire(blocking=False):
  123. await asyncio.sleep(_CHANGE_POLL_SECONDS)
  124. try:
  125. yield
  126. finally:
  127. _CHANGE_LOCK.release()
  128. async def _restart(gateway: Optional[str], what: str) -> dict:
  129. """The status after asking the *gateway* profile's gateway to restart onto the saved config. Runs
  130. after the config write released the config lock, as main's config routes do: the restart spawn
  131. and the status query (a control-socket round trip) hold up no config, skills or tools request.
  132. A refused restart (a live chat) keeps the saved config and reports ``restart_error``."""
  133. restart = await asyncio.to_thread(_restart_gateway_after, gateway, what=what, label="Web Access")
  134. return {**await _in_gateway_home(gateway, webapp_access.access_status), **restart}
  135. @router.get("/api/webapp-access/status")
  136. async def webapp_access_status(profile: Optional[str] = None):
  137. """``restart_failure``: the newest restart of this gateway exited without replacing it, and why;
  138. the pane waiting on that restart stops and says so instead of timing out. ``start_progress``:
  139. the Start for this gateway (``step``, ``started_at`` in epoch seconds) from its request's arrival
  140. until a gateway serves the config it wrote (or its restart failed), else None.
  141. The pane polls this, so the status (a control-socket round trip) runs outside the skills lock,
  142. as in ``_restart``."""
  143. gateway = await _scoped(profile, lambda gateway: gateway)
  144. # Before the status round trip: a Start that ends during it is still reported, so the pane polls
  145. # again rather than showing that config change undone until its next refetch.
  146. start = _start_in_flight(gateway)
  147. followed = any("restart_pid" in r for r in _STARTS.get(gateway, ()))
  148. def read():
  149. # The gateway's identity first: one replaced between the two reads then still counts as old.
  150. instance = webapp_access.gateway_instance() if followed else None
  151. return instance, {**webapp_access.access_status(), "restart_failure": _gateway_restart_failure(gateway)}
  152. instance, status = await _in_gateway_home(gateway, read)
  153. while start is not None and _restart_settled(start, status, instance):
  154. _drop(gateway, start)
  155. start = _start_in_flight(gateway)
  156. return {**status, "start_progress": _reported(start)}
  157. @router.post("/api/webapp-access/start")
  158. async def start_webapp_access(body: StartBody, profile: Optional[str] = None):
  159. profile = destructive_profile(profile, "POST /api/webapp-access/start")
  160. gateway = await _scoped(profile, lambda gateway: gateway)
  161. # Reported from its arrival: a Start waiting for another change shows as one being prepared, and
  162. # its clock counts from when it was asked for.
  163. record = {"step": "preparing", "started_at": time.time()}
  164. _STARTS.setdefault(gateway, []).append(record)
  165. try:
  166. async with _one_change_at_a_time():
  167. # Writes a standalone profile's first port claim, so it takes the config lock.
  168. host, port, public_url, callback = await _scoped(
  169. profile, lambda _gateway: webapp_access.plan(body.mode, body.public_url), config_write=True)
  170. # The bundle before anything else lasting: a failed build registers, restarts and writes
  171. # nothing but that port claim.
  172. record["step"] = "building"
  173. await _in_gateway_home(gateway, webapp_access.build_bundle)
  174. record["step"] = "registering"
  175. await _in_gateway_home(gateway, lambda: webapp_access.register(callback))
  176. record["step"] = "restarting"
  177. await _scoped(profile, lambda _gateway: webapp_access.serve(host, public_url, port), config_write=True)
  178. replaces = await _in_gateway_home(gateway, webapp_access.gateway_instance)
  179. result = await _restart(gateway, "turning on Web Access")
  180. if result.get("restart_started") and result.get("restart_pid") is not None:
  181. # Followed past the request: until the restarted gateway serves this config, a pane
  182. # opened now shows the Start restarting, not the saved change waiting for a restart.
  183. _drop_followed(gateway)
  184. record.update(restart_pid=result["restart_pid"], replaces=replaces,
  185. follow_until=time.monotonic() + _RESTART_FOLLOW_SECONDS)
  186. else:
  187. _drop(gateway, record)
  188. # The pane keeps this answer as the status it shows. Where the backend answering is the
  189. # gateway being restarted, no status read succeeds until its replacement is up, so the
  190. # answer itself must say the Start is still under way.
  191. return {**result, "start_progress": _reported(_start_in_flight(gateway))}
  192. finally:
  193. if "restart_pid" not in record:
  194. _drop(gateway, record)
  195. @router.post("/api/webapp-access/stop")
  196. async def stop_webapp_access(profile: Optional[str] = None):
  197. profile = destructive_profile(profile, "POST /api/webapp-access/stop")
  198. def _stop(gateway):
  199. webapp_access.turn_off()
  200. return gateway
  201. async with _one_change_at_a_time():
  202. gateway = await _scoped(profile, _stop, config_write=True)
  203. _drop_followed(gateway)
  204. return await _restart(gateway, "turning off Web Access")
  205. @router.post("/api/webapp-access/restart")
  206. async def restart_webapp_access(profile: Optional[str] = None):
  207. """Apply the saved config to a gateway that has not restarted onto it yet: restart that gateway
  208. and nothing else (no Portal registration, no build, no config write)."""
  209. profile = destructive_profile(profile, "POST /api/webapp-access/restart")
  210. async with _one_change_at_a_time():
  211. gateway = await _scoped(profile, lambda gateway: gateway)
  212. _drop_followed(gateway)
  213. return await _restart(gateway, "applying Web Access")