Skip to content
Python
10.9 KB
Raw Blame
"""The reverse channel: a small RPC framing over the box's dialed-out WebSocket.

This is a TRANSPORT ADAPTER, not a protocol of its own. Controller → box
frames carry an ordinary HTTP request shape (`method`, `path`, `body`); the
box dispatches them into its OWN ASGI app in-process and answers with the
response. Every existing /v1 endpoint therefore works remotely with zero
handler changes. Box → controller `event` frames are reserved for the live
session stream (P1c).

Frame vocabulary (JSON text frames):
  handshake   box → ctrl   {"type": "hello", "protocol_version", "app_version",
                            "pubkey", "name", "token"?}
              ctrl → box   {"type": "challenge", "nonce"}
              box → ctrl   {"type": "auth", "signature"}
              ctrl → box   {"type": "welcome", "machine_id", "name"}
                         | {"type": "reject", "reason", "detail"?}
  steady      ctrl → box   {"type": "rpc", "id", "method", "path",
                            "body_b64"?, "content_type"?}
              box → ctrl   {"type": "rpc_result", "id", "status",
                            "body_b64", "content_type"}
  wallet      ctrl → box   {"type": "secret_deploy", "id", "sealed_b64"}
  (sealed)    ctrl → box   {"type": "secret_revoke", "id", "profiles"}
              box → ctrl   rpc_result for both (status 200/400)
  websocket   ctrl → box   {"type": "ws_open", "stream", "path"}
  (bridged)   ctrl → box   {"type": "ws_msg", "stream", "text"}
              ctrl → box   {"type": "ws_close", "stream"}
              box → ctrl   {"type": "ws_msg", "stream", "text"}
              box → ctrl   {"type": "ws_close", "stream"}

PROTOCOL_VERSION is checked with STRICT EQUALITY in P1 (owner ruling
2026-08-24); the field existing in the very first version is the
un-retrofittable escape hatch that lets later versions negotiate a window.
"""

from __future__ import annotations

import asyncio
import base64
import json
from typing import Any, Awaitable, Callable, Optional

# v2: hello carries seal_sig — the sealing key attested by the identity key.
PROTOCOL_VERSION = 2

# One in-flight RPC must never wedge the channel; the controller-side proxy
# turns a timeout into a 504 while the socket stays healthy.
RPC_TIMEOUT_SECONDS = 60.0


def app_version() -> str:
    from importlib.metadata import PackageNotFoundError, version

    # "coworker" = the distribution's name before it was published as "openworker".
    for dist in ("openworker", "coworker"):
        try:
            return version(dist)
        except PackageNotFoundError:
            continue
        except Exception:
            break
    return "0.0.0"


def encode_body(body: bytes | None) -> str:
    return base64.b64encode(body or b"").decode("ascii")


def decode_body(body_b64: str | None) -> bytes:
    return base64.b64decode((body_b64 or "").encode("ascii"))


ACTOR_HEADER = "x-openworker-actor"


class RpcClient:
    """Controller side: pending-future bookkeeping over an arbitrary send callable.

    The owning WebSocket handler runs the receive loop and feeds every
    `rpc_result` frame to `resolve()`; `request()` is what the proxy route
    awaits. Sends are serialized — concurrent proxy calls share one socket.
    """

    def __init__(self, send_text: Callable[[str], Awaitable[None]]) -> None:
        self._send_text = send_text
        self._send_lock = asyncio.Lock()
        self._pending: dict[str, asyncio.Future] = {}
        self._counter = 0
        self._closed = False

    async def send_frame(self, frame: dict[str, Any]) -> None:
        """Send an arbitrary channel frame (ws_open/ws_msg/ws_close) on the
        same socket, serialized with in-flight RPC sends."""
        if self._closed:
            raise ConnectionError("machine channel is closed")
        async with self._send_lock:
            await self._send_text(json.dumps(frame))

    async def request_frame(
        self, frame: dict[str, Any], timeout: float = RPC_TIMEOUT_SECONDS
    ) -> tuple[int, bytes, str]:
        """Send any id-carrying frame and await its rpc_result (allocates the id)."""
        if self._closed:
            raise ConnectionError("machine channel is closed")
        self._counter += 1
        rpc_id = f"r{self._counter}"
        frame = {**frame, "id": rpc_id}
        fut: asyncio.Future = asyncio.get_running_loop().create_future()
        self._pending[rpc_id] = fut
        try:
            async with self._send_lock:
                await self._send_text(json.dumps(frame))
            result = await asyncio.wait_for(fut, timeout=timeout)
        finally:
            self._pending.pop(rpc_id, None)
        return result

    async def request(
        self,
        method: str,
        path: str,
        body: bytes | None = None,
        content_type: str | None = None,
        timeout: float = RPC_TIMEOUT_SECONDS,
        actor: str = "",
    ) -> tuple[int, bytes, str]:
        frame: dict[str, Any] = {
            "type": "rpc",
            "method": method.upper(),
            "path": path,
            **({"actor": actor} if actor else {}),
        }
        if body:
            frame["body_b64"] = encode_body(body)
            frame["content_type"] = content_type or "application/json"
        return await self.request_frame(frame, timeout=timeout)

    def resolve(self, frame: dict[str, Any]) -> None:
        fut = self._pending.get(str(frame.get("id")))
        if fut is not None and not fut.done():
            fut.set_result(
                (
                    int(frame.get("status", 502)),
                    decode_body(frame.get("body_b64")),
                    str(frame.get("content_type") or "application/json"),
                )
            )

    def close(self, reason: str = "machine disconnected") -> None:
        self._closed = True
        for fut in self._pending.values():
            if not fut.done():
                fut.set_exception(ConnectionError(reason))
        self._pending.clear()


class AsgiDispatcher:
    """Box side: dispatch an `rpc` frame into the box's own ASGI app in-process."""

    def __init__(self, app: Any) -> None:
        import httpx

        self._client = httpx.AsyncClient(
            transport=httpx.ASGITransport(app=app),
            base_url="http://joined-box",
            timeout=RPC_TIMEOUT_SECONDS,
        )

    async def dispatch(self, frame: dict[str, Any]) -> dict[str, Any]:
        rpc_id = str(frame.get("id"))
        try:
            body = decode_body(frame.get("body_b64"))
            headers = {}
            if body:
                headers["content-type"] = str(
                    frame.get("content_type") or "application/json"
                )
            # The controller-verified actor becomes a header only HERE — the box
            # has no listener, so nothing else can present one.
            if frame.get("actor"):
                headers[ACTOR_HEADER] = str(frame["actor"])
            response = await self._client.request(
                str(frame.get("method", "GET")),
                str(frame.get("path", "/")),
                content=body or None,
                headers=headers,
            )
            return {
                "type": "rpc_result",
                "id": rpc_id,
                "status": response.status_code,
                "body_b64": encode_body(response.content),
                "content_type": response.headers.get(
                    "content-type", "application/json"
                ),
            }
        except Exception as exc:  # a broken dispatch must answer, not wedge the channel
            return {
                "type": "rpc_result",
                "id": rpc_id,
                "status": 502,
                "body_b64": encode_body(
                    json.dumps({"error": f"dispatch failed: {exc}"}).encode()
                ),
                "content_type": "application/json",
            }

    async def aclose(self) -> None:
        await self._client.aclose()


class AsgiWsBridge:
    """Box side: one bridged WebSocket stream into the box's own ASGI app.

    The controller's GUI-facing socket is spliced to this: `ws_msg` frames feed
    the app as `websocket.receive` events, and everything the app sends comes
    back as `ws_msg` frames. The session WebSocket protocol is JSON text both
    ways, so only text frames are bridged.
    """

    def __init__(
        self,
        app: Any,
        stream_id: str,
        path: str,
        send_frame: Callable[[dict[str, Any]], Awaitable[None]],
        actor: str = "",
    ) -> None:
        self._app = app
        self.stream_id = stream_id
        self._path = path
        self._send_frame = send_frame
        self._actor = actor
        self._incoming: asyncio.Queue = asyncio.Queue()
        self._closed = False

    async def run(self) -> None:
        path, _, query = self._path.partition("?")
        scope = {
            "type": "websocket",
            "asgi": {"version": "3.0", "spec_version": "2.3"},
            "scheme": "ws",
            "path": path,
            "raw_path": path.encode(),
            "query_string": query.encode(),
            "root_path": "",
            "headers": (
                [(ACTOR_HEADER.encode(), self._actor.encode())] if self._actor else []
            ),
            "client": ("channel", 0),
            "server": ("joined-box", 0),
            "subprotocols": [],
        }
        await self._incoming.put({"type": "websocket.connect"})
        try:
            await self._app(scope, self._incoming.get, self._send)
        except Exception:
            pass  # app-side failure closes the stream below, never the channel
        finally:
            await self._close_out()

    def feed_text(self, text: str) -> None:
        self._incoming.put_nowait({"type": "websocket.receive", "text": text})

    def feed_close(self) -> None:
        self._closed = True  # controller-initiated: no ws_close echo needed
        self._incoming.put_nowait({"type": "websocket.disconnect", "code": 1000})

    async def _send(self, message: dict[str, Any]) -> None:
        kind = message["type"]
        if kind == "websocket.send":
            text = message.get("text")
            if text is None and message.get("bytes") is not None:
                text = bytes(message["bytes"]).decode("utf-8", "replace")
            if text is not None and not self._closed:
                await self._send_frame(
                    {"type": "ws_msg", "stream": self.stream_id, "text": text}
                )
        elif kind == "websocket.close":
            await self._close_out()

    async def _close_out(self) -> None:
        if self._closed:
            return
        self._closed = True
        try:
            await self._send_frame({"type": "ws_close", "stream": self.stream_id})
        except Exception:
            pass


def reject_frame(reason: str, detail: Optional[str] = None) -> dict[str, Any]:
    frame: dict[str, Any] = {"type": "reject", "reason": reason}
    if detail:
        frame["detail"] = detail
    return frame