shared_ingress.py 7.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156
  1. """Shared-listener ingress for inbound-port platforms under ``gateway.multiplex_profiles``.
  2. The default profile owns the ONE HTTP listener (api_server, and the webhook adapter's port). A
  3. secondary profile's port-binding adapter (Twilio SMS, LINE, Teams, BlueBubbles, Microsoft Graph,
  4. WhatsApp Cloud, WeCom callback, Feishu webhook mode) therefore cannot bind its own port; instead the
  5. runner constructs it in *shared-listener mode*: ``bind_listener`` publishes the adapter's fully wired
  6. ``web.Application`` instead of starting a ``TCPSite``, and the default listener forwards
  7. ``/p/<profile>/<path>`` to it through ``dispatch_profile_ingress``.
  8. Invariants: the forwarded request runs under the NAMED profile's runtime scope and is verified by
  9. that profile's adapter with that profile's secret; the un-prefixed path keeps serving the default
  10. profile untouched; a profile with no adapter for the path gets a 404, never the default's adapter.
  11. """
  12. from __future__ import annotations
  13. import logging
  14. from typing import TYPE_CHECKING, Any, Optional
  15. if TYPE_CHECKING: # aiohttp is an optional dependency of every adapter using this module
  16. from aiohttp import web
  17. logger = logging.getLogger(__name__)
  18. _WILDCARD_HOSTS = frozenset({"", "0.0.0.0", "::", "*"})
  19. def is_wildcard_host(host: Any) -> bool:
  20. """True for the dual-stack default (None/"") and the per-family wildcards."""
  21. return host is None or str(host).strip() in _WILDCARD_HOSTS
  22. def shared_ingress_profile(adapter: Any) -> Optional[str]:
  23. """Profile name when *adapter* was constructed in shared-listener mode, else None."""
  24. return getattr(adapter, "_shared_listener_profile", None) or None
  25. def listener_base_url(host: Any, port: Any) -> str:
  26. """``http://host:port`` clients use to reach a listener bound on ``host`` (wildcards → loopback)."""
  27. host = "127.0.0.1" if is_wildcard_host(host) else str(host)
  28. if ":" in host and not host.startswith("["):
  29. host = f"[{host}]"
  30. return f"http://{host}:{port or 0}"
  31. def shared_listener_base(runner: Any) -> Optional[str]:
  32. """``http://host:port`` of the default profile's live listener (api_server first, then webhook)."""
  33. from gateway.config import Platform
  34. adapters = getattr(runner, "adapters", None) or {}
  35. for platform in (Platform.API_SERVER, Platform.WEBHOOK):
  36. adapter = adapters.get(platform)
  37. if adapter is None:
  38. continue
  39. return listener_base_url(getattr(adapter, "_host", None), getattr(adapter, "_port", 0))
  40. return None
  41. async def bind_listener(
  42. adapter: Any, app: web.Application, host: Optional[str], port: int, ingress_path: str, *,
  43. reuse_address: Optional[bool] = None, access_log: Any = ...,
  44. ) -> Optional[web.AppRunner]:
  45. """Start *app* on ``host:port`` and return its ``AppRunner`` — or, in shared-listener mode,
  46. publish *app* for ``/p/<profile>/`` forwarding and return None (nothing bound). ``ingress_path``
  47. is the adapter's primary callback path, used for the log line and runtime status."""
  48. from aiohttp import web
  49. profile = shared_ingress_profile(adapter)
  50. if profile:
  51. publish_shared_ingress(adapter, app, ingress_path)
  52. return None
  53. runner = web.AppRunner(app) if access_log is ... else web.AppRunner(app, access_log=access_log)
  54. await runner.setup()
  55. site = web.TCPSite(runner, host, port, reuse_address=reuse_address)
  56. try:
  57. await site.start()
  58. except BaseException:
  59. await runner.cleanup()
  60. raise
  61. return runner
  62. def publish_shared_ingress(adapter: Any, app: web.Application, ingress_path: str) -> None:
  63. """Freeze *app* and expose it to the default listener; records the ``/p/<profile>/`` URL."""
  64. profile = shared_ingress_profile(adapter)
  65. app.freeze()
  66. adapter._shared_ingress_app = app
  67. base = shared_listener_base(getattr(adapter, "gateway_runner", None))
  68. prefix = f"/p/{profile}"
  69. adapter._shared_ingress_base = f"{base}{prefix}" if base else prefix
  70. adapter._shared_ingress_url = f"{adapter._shared_ingress_base}{ingress_path}"
  71. platform = getattr(getattr(adapter, "platform", None), "value", "adapter")
  72. if base:
  73. logger.info(
  74. "[%s] profile '%s' is served on the default profile's shared listener: %s "
  75. "(point the vendor's callback URL at this path behind your public host)",
  76. platform, profile, adapter._shared_ingress_url,
  77. )
  78. else:
  79. logger.warning(
  80. "[%s] profile '%s' is in shared-listener mode but the default profile has no live api_server "
  81. "or webhook listener yet; it will be reachable at <listener>%s%s once one is up",
  82. platform, profile, prefix, ingress_path,
  83. )
  84. write = getattr(adapter, "_write_runtime_status_safe", None)
  85. if callable(write):
  86. write("shared_ingress", ingress_url=adapter._shared_ingress_url)
  87. def shared_ingress_apps(runner: Any, profile: Optional[str]) -> list[tuple[Any, web.Application]]:
  88. """``(adapter, app)`` for every shared-listener adapter of a NAMED served profile. ``default`` and
  89. unknown profiles yield nothing: the default's port-binders own their own ports, and a profile
  90. without a live adapter must never fall back to another profile's."""
  91. if not profile or profile == "default":
  92. return []
  93. adapters = (getattr(runner, "_profile_adapters", None) or {}).get(profile) or {}
  94. return [
  95. (adapter, app) for adapter in adapters.values()
  96. if (app := getattr(adapter, "_shared_ingress_app", None)) is not None
  97. ]
  98. async def dispatch_profile_ingress(
  99. runner: Any, profile: Optional[str], tail: str, request: web.Request, *, scoped: bool = False,
  100. ) -> web.StreamResponse:
  101. """Forward ``/p/<profile>/<tail>`` to the served profile's adapter app that routes ``/<tail>``,
  102. under that profile's runtime scope (``scoped=True`` when the caller already entered it). 404 when
  103. no adapter of *profile* serves the path."""
  104. from aiohttp import web
  105. from aiohttp.web_urldispatcher import MatchInfoError
  106. candidates = shared_ingress_apps(runner, profile)
  107. from gateway.run_runtime import profile_parked
  108. if not candidates and profile_parked(runner, profile):
  109. # Its adapters come back with it (a rescan or restart): the platform retries a 503.
  110. from gateway.parked_route_refusal import ParkedRouteRefused
  111. raise web.HTTPServiceUnavailable(text="Profile temporarily unavailable; retry",
  112. headers=ParkedRouteRefused.headers)
  113. if not profile or not candidates:
  114. raise web.HTTPNotFound(text="Unknown or unconfigured profile")
  115. rel_url = request.rel_url.with_path("/" + tail.lstrip("/"), keep_query=True, keep_fragment=True)
  116. forwarded = request.clone(rel_url=rel_url)
  117. chosen = None
  118. for _adapter, app in candidates:
  119. match = await app.router.resolve(forwarded)
  120. # A 404 means "not my path": try the profile's next adapter; 405 and real matches belong here.
  121. if isinstance(match, MatchInfoError) and match.http_exception.status == 404:
  122. continue
  123. chosen = app
  124. break
  125. if chosen is None:
  126. raise web.HTTPNotFound(text="No adapter serves this path for the profile")
  127. # Each adapter chose its own body cap when it built its Application; honour it for the forwarded read.
  128. forwarded = request.clone(rel_url=rel_url, client_max_size=chosen._client_max_size)
  129. if scoped:
  130. return await chosen._handle(forwarded)
  131. from gateway.run import _profile_runtime_scope
  132. from hermes_cli.profiles import get_profile_dir
  133. with _profile_runtime_scope(get_profile_dir(profile)):
  134. return await chosen._handle(forwarded)