"""Shared-listener ingress for inbound-port platforms under ``gateway.multiplex_profiles``. The default profile owns the ONE HTTP listener (api_server, and the webhook adapter's port). A secondary profile's port-binding adapter (Twilio SMS, LINE, Teams, BlueBubbles, Microsoft Graph, WhatsApp Cloud, WeCom callback, Feishu webhook mode) therefore cannot bind its own port; instead the runner constructs it in *shared-listener mode*: ``bind_listener`` publishes the adapter's fully wired ``web.Application`` instead of starting a ``TCPSite``, and the default listener forwards ``/p//`` to it through ``dispatch_profile_ingress``. Invariants: the forwarded request runs under the NAMED profile's runtime scope and is verified by that profile's adapter with that profile's secret; the un-prefixed path keeps serving the default profile untouched; a profile with no adapter for the path gets a 404, never the default's adapter. """ from __future__ import annotations import logging from typing import TYPE_CHECKING, Any, Optional if TYPE_CHECKING: # aiohttp is an optional dependency of every adapter using this module from aiohttp import web logger = logging.getLogger(__name__) _WILDCARD_HOSTS = frozenset({"", "0.0.0.0", "::", "*"}) def is_wildcard_host(host: Any) -> bool: """True for the dual-stack default (None/"") and the per-family wildcards.""" return host is None or str(host).strip() in _WILDCARD_HOSTS def shared_ingress_profile(adapter: Any) -> Optional[str]: """Profile name when *adapter* was constructed in shared-listener mode, else None.""" return getattr(adapter, "_shared_listener_profile", None) or None def listener_base_url(host: Any, port: Any) -> str: """``http://host:port`` clients use to reach a listener bound on ``host`` (wildcards → loopback).""" host = "127.0.0.1" if is_wildcard_host(host) else str(host) if ":" in host and not host.startswith("["): host = f"[{host}]" return f"http://{host}:{port or 0}" def shared_listener_base(runner: Any) -> Optional[str]: """``http://host:port`` of the default profile's live listener (api_server first, then webhook).""" from gateway.config import Platform adapters = getattr(runner, "adapters", None) or {} for platform in (Platform.API_SERVER, Platform.WEBHOOK): adapter = adapters.get(platform) if adapter is None: continue return listener_base_url(getattr(adapter, "_host", None), getattr(adapter, "_port", 0)) return None async def bind_listener( adapter: Any, app: web.Application, host: Optional[str], port: int, ingress_path: str, *, reuse_address: Optional[bool] = None, access_log: Any = ..., ) -> Optional[web.AppRunner]: """Start *app* on ``host:port`` and return its ``AppRunner`` — or, in shared-listener mode, publish *app* for ``/p//`` forwarding and return None (nothing bound). ``ingress_path`` is the adapter's primary callback path, used for the log line and runtime status.""" from aiohttp import web profile = shared_ingress_profile(adapter) if profile: publish_shared_ingress(adapter, app, ingress_path) return None runner = web.AppRunner(app) if access_log is ... else web.AppRunner(app, access_log=access_log) await runner.setup() site = web.TCPSite(runner, host, port, reuse_address=reuse_address) try: await site.start() except BaseException: await runner.cleanup() raise return runner def publish_shared_ingress(adapter: Any, app: web.Application, ingress_path: str) -> None: """Freeze *app* and expose it to the default listener; records the ``/p//`` URL.""" profile = shared_ingress_profile(adapter) app.freeze() adapter._shared_ingress_app = app base = shared_listener_base(getattr(adapter, "gateway_runner", None)) prefix = f"/p/{profile}" adapter._shared_ingress_base = f"{base}{prefix}" if base else prefix adapter._shared_ingress_url = f"{adapter._shared_ingress_base}{ingress_path}" platform = getattr(getattr(adapter, "platform", None), "value", "adapter") if base: logger.info( "[%s] profile '%s' is served on the default profile's shared listener: %s " "(point the vendor's callback URL at this path behind your public host)", platform, profile, adapter._shared_ingress_url, ) else: logger.warning( "[%s] profile '%s' is in shared-listener mode but the default profile has no live api_server " "or webhook listener yet; it will be reachable at %s%s once one is up", platform, profile, prefix, ingress_path, ) write = getattr(adapter, "_write_runtime_status_safe", None) if callable(write): write("shared_ingress", ingress_url=adapter._shared_ingress_url) def shared_ingress_apps(runner: Any, profile: Optional[str]) -> list[tuple[Any, web.Application]]: """``(adapter, app)`` for every shared-listener adapter of a NAMED served profile. ``default`` and unknown profiles yield nothing: the default's port-binders own their own ports, and a profile without a live adapter must never fall back to another profile's.""" if not profile or profile == "default": return [] adapters = (getattr(runner, "_profile_adapters", None) or {}).get(profile) or {} return [ (adapter, app) for adapter in adapters.values() if (app := getattr(adapter, "_shared_ingress_app", None)) is not None ] async def dispatch_profile_ingress( runner: Any, profile: Optional[str], tail: str, request: web.Request, *, scoped: bool = False, ) -> web.StreamResponse: """Forward ``/p//`` to the served profile's adapter app that routes ``/``, under that profile's runtime scope (``scoped=True`` when the caller already entered it). 404 when no adapter of *profile* serves the path.""" from aiohttp import web from aiohttp.web_urldispatcher import MatchInfoError candidates = shared_ingress_apps(runner, profile) from gateway.run_runtime import profile_parked if not candidates and profile_parked(runner, profile): # Its adapters come back with it (a rescan or restart): the platform retries a 503. from gateway.parked_route_refusal import ParkedRouteRefused raise web.HTTPServiceUnavailable(text="Profile temporarily unavailable; retry", headers=ParkedRouteRefused.headers) if not profile or not candidates: raise web.HTTPNotFound(text="Unknown or unconfigured profile") rel_url = request.rel_url.with_path("/" + tail.lstrip("/"), keep_query=True, keep_fragment=True) forwarded = request.clone(rel_url=rel_url) chosen = None for _adapter, app in candidates: match = await app.router.resolve(forwarded) # A 404 means "not my path": try the profile's next adapter; 405 and real matches belong here. if isinstance(match, MatchInfoError) and match.http_exception.status == 404: continue chosen = app break if chosen is None: raise web.HTTPNotFound(text="No adapter serves this path for the profile") # Each adapter chose its own body cap when it built its Application; honour it for the forwarded read. forwarded = request.clone(rel_url=rel_url, client_max_size=chosen._client_max_size) if scoped: return await chosen._handle(forwarded) from gateway.run import _profile_runtime_scope from hermes_cli.profiles import get_profile_dir with _profile_runtime_scope(get_profile_dir(profile)): return await chosen._handle(forwarded)