web_server_surface.py 5.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100
  1. """What each launch surface of the one web-server stack may do.
  2. The host serving the app records its surface once on ``app.state.ui_surface``; unset, it reads
  3. as ``gateway`` on the gateway's own listener for native clients (the app has a
  4. ``gateway_runner``, as the lifespan choice reads) and ``dashboard`` elsewhere (the standalone
  5. ``hermes dashboard`` and ``hermes serve``). Every surface-dependent decision reads this table
  6. instead of re-deriving it, and :func:`route_on` keeps a route off the surfaces that do not use
  7. it. ``auth_required`` is decided at runtime by the auth gate, so the private-launch predicate is
  8. a function over state, not a table field.
  9. """
  10. from __future__ import annotations
  11. from dataclasses import dataclass
  12. from typing import Any, Callable
  13. from fastapi import HTTPException, Request
  14. @dataclass(frozen=True)
  15. class SurfacePolicy:
  16. #: Mounts a browser UI; ``serve`` is JSON-RPC/WS only.
  17. serves_spa: bool
  18. #: Public HTML may carry the session token. Where it may not, every HTML entry
  19. #: (``/index.html`` included) gets the token-free bootstrap instead of the raw file.
  20. html_token: bool
  21. #: ``/api/host-terminal`` may open host shells (still gated per request).
  22. host_terminal: bool
  23. #: An unauthenticated start hands the operator a private launch link.
  24. launch_link: bool
  25. #: ``/api/webapp/socket-ticket`` mints the browser's one-use tickets for ``/api/ws`` and the voice
  26. #: streams on this same origin (accepted by the loopback and gated upgrade gates alike).
  27. gateway_ticket: bool
  28. #: Behind the sign-in gate, a write that carries the session cookie (``/auth/logout`` included)
  29. #: must come from this listener's own origin. Elsewhere the gate keeps main's rule.
  30. own_origin_cookie_writes: bool
  31. #: ``/api/webapp-access/*`` serves: native Desktop's Web Access pane calls the gateway's own
  32. #: listener (the private one, or the Webapp's when it is on).
  33. web_access: bool
  34. #: The browser's file routes serve: ``/api/chat/file-upload`` stages a picked file,
  35. #: ``/api/files/ticket`` mints the path-bound tickets for downloads and media links, and chat
  36. #: upload bodies are capped before they are parsed (``web_upload_limit``).
  37. browser_files: bool
  38. #: ``/api/desktop-plugins/*`` serves this host's desktop plugins to the browser's plugin loader;
  39. #: native Desktop reads its own disk.
  40. desktop_plugins: bool
  41. #: ``/api/ui-preferences`` serves: the browser's door to this machine's UI preferences store
  42. #: (native Desktop reaches the same file through its preload capability, not over HTTP).
  43. ui_preferences: bool
  44. #: ``/api/audio/voice-config`` may hand the client provider keys to call STT/TTS itself. A
  45. #: browser tab cannot: a provider without CORS (the Nous tool gateway) refuses its fetch, and the
  46. #: keys would sit in the page. It relays through the host's /api/audio/* endpoints instead.
  47. client_direct_voice: bool
  48. POLICIES: dict[str, SurfacePolicy] = {
  49. "serve": SurfacePolicy(
  50. serves_spa=False, html_token=True, host_terminal=False, launch_link=False, gateway_ticket=False,
  51. own_origin_cookie_writes=False, web_access=False, browser_files=False,
  52. desktop_plugins=False, ui_preferences=False, client_direct_voice=True),
  53. "dashboard": SurfacePolicy(
  54. serves_spa=True, html_token=True, host_terminal=False, launch_link=False, gateway_ticket=False,
  55. own_origin_cookie_writes=False, web_access=False, browser_files=False,
  56. desktop_plugins=False, ui_preferences=False, client_direct_voice=True),
  57. "gateway": SurfacePolicy(
  58. serves_spa=True, html_token=True, host_terminal=False, launch_link=False, gateway_ticket=False,
  59. own_origin_cookie_writes=False, web_access=True, browser_files=False,
  60. desktop_plugins=False, ui_preferences=False, client_direct_voice=True),
  61. "webapp": SurfacePolicy(
  62. serves_spa=True, html_token=False, host_terminal=True, launch_link=True, gateway_ticket=True,
  63. own_origin_cookie_writes=True, web_access=True, browser_files=True,
  64. desktop_plugins=True, ui_preferences=True, client_direct_voice=False),
  65. }
  66. def surface(state: Any) -> str:
  67. """The surface *state*'s app serves (see the module docstring)."""
  68. recorded = getattr(state, "ui_surface", None)
  69. if recorded:
  70. return recorded
  71. return "gateway" if getattr(state, "gateway_runner", None) is not None else "dashboard"
  72. def policy(state: Any) -> SurfacePolicy:
  73. return POLICIES[surface(state)]
  74. def route_on(field: str) -> Callable[[Request], None]:
  75. """A route dependency answering 404 where the serving surface's policy leaves *field* off, so
  76. the route does not exist there for any caller."""
  77. def surface_serves(request: Request) -> None:
  78. if not getattr(policy(request.app.state), field):
  79. raise HTTPException(status_code=404, detail="Not Found")
  80. return surface_serves
  81. def private_launch(state: Any) -> bool:
  82. """Webapp on an unauthenticated bind: the launch link is the only way in."""
  83. return policy(state).launch_link and not getattr(state, "auth_required", False)