| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101 |
- """Relay transport protocol — the gateway<->connector wire contract. EXPERIMENTAL.
- The ``RelayAdapter`` delegates all wire I/O to a ``RelayTransport``. The gateway
- dials OUT to the connector, so production is a WebSocket client (``ws_transport.py``)
- and tests use an in-memory stub (``tests/gateway/relay/stub_connector.py``). This
- module defines the protocol surface only. May change without a deprecation cycle
- until >=2 Class-1 platforms validate it. See website/docs/developer-guide/relay-connector-contract.md.
- """
- from __future__ import annotations
- import asyncio
- from typing import Any, Awaitable, Callable, Dict, Optional, Protocol, runtime_checkable
- from gateway.platforms.event import MessageEvent
- from gateway.relay.descriptor import CapabilityDescriptor
- # Callback the transport invokes for each inbound normalized event: a task it returns is the
- # event's admission still running off the reader, and the frame is ACKed when that task succeeds.
- InboundHandler = Callable[[MessageEvent], Awaitable[Optional["asyncio.Task[None]"]]]
- # Callback for each forwarded passthrough request (§5.1): ``(forward, buffer_id)``.
- # ``forward`` is a ws_transport.PassthroughForward, typed Any here because
- # ws_transport imports FROM this module; ``buffer_id`` (§5.3 buffered flip) is
- # acked by the handler after durable handoff.
- PassthroughHandler = Callable[[Any, Optional[str]], Awaitable[None]]
- @runtime_checkable
- class RelayTransport(Protocol):
- """Full gateway<->connector transport contract."""
- async def connect(self) -> bool:
- """Open the connection to the connector; return True on success."""
- ...
- async def disconnect(self) -> None:
- ...
- async def handshake(self) -> CapabilityDescriptor:
- """Return the capability descriptor the connector advertises."""
- ...
- def set_inbound_handler(self, handler: InboundHandler) -> None:
- ...
- def set_passthrough_handler(self, handler: PassthroughHandler) -> None:
- """Register the callback for each forwarded passthrough request (§5.1).
- The connector answers the provider's edge ACK itself, then forwards the real
- request over this same outbound socket (a hosted gateway has no public
- inbound port). Optional on a transport (a stub may not implement it).
- """
- ...
- async def send_outbound(
- self, action: dict[str, Any], *, platform: Optional[str] = None
- ) -> dict[str, Any]:
- """Carry an outbound action (send/edit/typing) to the connector.
- Returns a result dict; for ``op == "send"`` it carries ``success`` and
- optionally ``message_id`` / ``error``. ``platform`` tags WHICH fronted
- platform this reply targets (the transport resolves the matching botId);
- omitted ⇒ the connector uses the session's default platform.
- """
- ...
- async def get_chat_info(self, chat_id: str) -> dict[str, Any]:
- """Proxy a chat-info lookup to the connector."""
- ...
- async def send_interrupt(self, session_key: str, reason: Optional[str] = None) -> None:
- """Route a mid-turn /stop to the connector for ``session_key`` (OUTBOUND
- direction; the actual cancellation happens when the connector echoes an
- interrupt inbound down the socket owning that session)."""
- ...
- async def go_idle(self, timeout_s: float = 10.0) -> bool:
- """Ask the connector to flip this instance to buffered-only (§5.3).
- Sends ``going_idle`` and awaits the connector-authoritative ``going_idle_ack``
- (live delivery stopped; inbound now buffers for replay on reconnect). True on
- ack, False on timeout / not-connected — the caller closes regardless.
- Optional on a transport; part of the gateway's EXISTING drain transition.
- """
- ...
- async def send_follow_up(
- self, action: dict[str, Any], *, platform: Optional[str] = None
- ) -> dict[str, Any]:
- """Act on a shared-identity capability bound to a session (A2 outbound).
- A credential acting on the SHARED bot identity (e.g. a Discord interaction
- follow-up token) NEVER reaches the gateway: the connector vaults it keyed by
- session and the gateway issues a SEMANTIC action (``op == "follow_up"``,
- ``session_key``, ``kind`` e.g. ``"discord.interaction_token"``, ``content``,
- optional ``metadata``). Returns ``{success, message_id?, error?}``; ``success``
- is False when the capability is absent/expired or the tenant mismatches —
- nothing to retry with (a leaked gateway holds zero capability material).
- """
- ...
|