rpc-router 0.3.0__tar.gz

rpc_router-0.3.0/PKG-INFO

@@ -0,0 +1,3 @@
+Metadata-Version: 2.4
+Name: rpc-router
+Version: 0.3.0

rpc_router-0.3.0/pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "rpc-router"
+dependencies = []
+dynamic = ["version"]
+
+[dependency-groups]
+fastapi = ["fastapi"]
+websockets = ["websockets"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.uv]
+package = true
+
+[build-system]
+build-backend = "setuptools.build_meta"
+requires = [
+  "setuptools>=45",
+  "git-semantic-version"
+]

rpc_router-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

rpc_router-0.3.0/src/rpc_router/backends/fastapi/__init__.py

@@ -0,0 +1 @@
+from .transport import FastAPIServer as FastAPIServer

rpc_router-0.3.0/src/rpc_router/backends/fastapi/transport.py

@@ -0,0 +1,69 @@
+from fastapi import WebSocket, WebSocketDisconnect
+
+from ...exceptions import ConnectionBrokenException
+from ...lifecycle import AbstractServer
+from ...protocol import AbstractDuplexConnection, ConnectionManager, DuplexRouter
+
+
+class FastAPIDuplexConnection(AbstractDuplexConnection):
+    """
+    Concrete transport mapping abstract string hooks directly to
+    FastAPI's native WebSocket object structure.
+    """
+
+    def __init__(
+        self,
+        websocket: WebSocket,
+        *,
+        router: DuplexRouter,
+        client_id: str | None = None,
+        manager: ConnectionManager | None = None,
+    ):
+        super().__init__(router, client_id=client_id, manager=manager)
+        self.ws = websocket
+
+    async def _raw_send(self, payload_str: str) -> None:
+        """Pushes raw text data straight through the FastAPI client pipe."""
+        try:
+            await self.ws.send_text(payload_str)
+        except WebSocketDisconnect:
+            raise ConnectionBrokenException
+
+    async def _raw_recv(self) -> str | None:
+        """Reads raw text out of FastAPI's incoming stream, catching disconnects safely."""
+        try:
+            return await self.ws.receive_text()
+        except WebSocketDisconnect:
+            return None
+
+    async def _raw_close(self) -> None:
+        """FastAPI automatically closes dropped socket tasks cleanly via context."""
+
+
+class FastAPIServer(AbstractServer):
+    """
+    Concrete FastAPI Server Wrapper.
+    Inherits the full abstract lifecycle context and handles connecting pipes cleanly.
+    """
+
+    async def _raw_start(self) -> None:
+        """Agnostic server hook. FastAPI starts via its own ASGI server launcher (e.g., uvicorn)."""
+        print(
+            "🚀 FastAPIServer context initialized. Ready to route WebSocket pipelines."
+        )
+
+    async def _raw_stop(self) -> None:
+        """Agnostic cleanup hook. Runs automatically when the server context exits."""
+        print("🛑 FastAPIServer context torn down cleanly.")
+
+    async def handle_websocket(self, websocket: WebSocket) -> None:
+        """
+        Public execution gateway route method.
+        Accepts raw incoming websockets and couples them directly to the abstract engine.
+        """
+        conn = FastAPIDuplexConnection(
+            websocket, router=self.router, manager=self.manager
+        )
+
+        async with conn:
+            await conn.wait_forever()

rpc_router-0.3.0/src/rpc_router/backends/websockets/__init__.py

@@ -0,0 +1 @@
+from .transport import WebsocketClient as WebsocketClient, WebsocketServer as WebsocketServer

rpc_router-0.3.0/src/rpc_router/backends/websockets/transport.py

@@ -0,0 +1,84 @@
+import logging
+
+import websockets
+from websockets.protocol import State
+
+from ...exceptions import ConnectionBrokenException, ConnectionRefusedException
+from ...lifecycle import AbstractClient, AbstractServer
+from ...protocol import AbstractDuplexConnection, ConnectionManager, DuplexRouter
+
+logger = logging.getLogger(__name__)
+
+
+class WebsocketsDuplexConnection(AbstractDuplexConnection):
+    """Framework specific pipe translation layer handling raw string frames."""
+
+    def __init__(
+        self,
+        websocket,
+        router: DuplexRouter,
+        client_id: str | None = None,
+        manager: ConnectionManager | None = None,
+    ):
+        super().__init__(router, client_id=client_id, manager=manager)
+        self.ws = websocket
+
+    async def _raw_send(self, payload_str: str) -> None:
+        try:
+            await self.ws.send(payload_str)
+        except websockets.exceptions.ConnectionClosed as e:
+            raise ConnectionBrokenException from e
+
+    async def _raw_recv(self) -> str | None:
+        try:
+            return await self.ws.recv()
+        except websockets.exceptions.ConnectionClosed:
+            return None
+
+    async def _raw_close(self) -> None:
+        await self.ws.close()
+
+
+class WebsocketServer(AbstractServer):
+    """Concrete WebSocket Server mapping lifecycle hooks directly to the websockets library."""
+
+    def __init__(self, router: DuplexRouter, host: str, port: int):
+        super().__init__(router)
+        self.host = host
+        self.port = port
+        self._server = None
+
+    async def _raw_start(self) -> None:
+        """Concrete implementation bootstrapping the websockets loop server handle."""
+
+        async def handler(websocket):
+            # Context entry handles manager tracking and listener loop tasks automatically
+            async with WebsocketsDuplexConnection(
+                websocket, self.router, manager=self.manager
+            ) as conn:
+                # Abstract helper blocks the function handle until the client disconnects
+                await conn.wait_forever()
+
+        self._server = await websockets.serve(handler, self.host, self.port)
+        logger.info(f"WebSocket Server active on ws://{self.host}:{self.port}")
+
+    async def _raw_stop(self) -> None:
+        """Concrete implementation shutting down the web socket network listener descriptor."""
+        if self._server:
+            self._server.close()
+            await self._server.wait_closed()
+            logger.info("WebSocket Server shut down cleanly")
+
+
+class WebsocketClient(AbstractClient):
+    """Concrete WebSocket Client mapping connection handshakes directly to the websockets library."""
+
+    def __init__(self, router: DuplexRouter, target_url: str):
+        super().__init__(router)
+        self.target_url = target_url
+
+    async def _create_connection(self) -> WebsocketsDuplexConnection:
+        websocket = await websockets.connect(self.target_url)
+        if not websocket.state == State.OPEN:
+            raise ConnectionRefusedException
+        return WebsocketsDuplexConnection(websocket, self.router)

rpc_router-0.3.0/src/rpc_router/exceptions.py

@@ -0,0 +1,10 @@
+class BaseException(Exception):
+    pass
+
+
+class ConnectionBrokenException(BaseException):
+    pass
+
+
+class ConnectionRefusedException(BaseException):
+    pass

rpc_router-0.3.0/src/rpc_router/lifecycle.py

@@ -0,0 +1,69 @@
+from abc import ABC, abstractmethod
+
+from .protocol import AbstractDuplexConnection, ConnectionManager, DuplexRouter
+
+
+class AbstractEndpoint(ABC):
+    def __init__(self, router: DuplexRouter):
+        self.router = router
+        self.on_connect = router.on_connect
+        self.before_receive = router.before_receive
+        self.before_send = router.before_send
+
+
+class AbstractServer(AbstractEndpoint):
+    """
+    Abstract Lifecycle Context Manager for Servers.
+    Manages global registries. Subclasses only implement raw boot hooks.
+    """
+
+    def __init__(self, router: DuplexRouter):
+        super().__init__(router=router)
+        self.manager = ConnectionManager()
+
+    @abstractmethod
+    async def _raw_start(self) -> None:
+        """Low-level server startup primitive (e.g., websockets.serve, fastapi boot)."""
+
+    @abstractmethod
+    async def _raw_stop(self) -> None:
+        """Low-level server shutdown primitive (e.g., closing server listeners)."""
+
+    async def __aenter__(self):
+        """Entering the server context automatically triggers the low-level infrastructure boot."""
+        await self._raw_start()
+        return self.manager
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """Exiting the server context guarantees infrastructure teardown and client purging."""
+        # 1. Cleanly disconnect all remaining active connections tracked by the server
+        for client_id, conn in list(self.manager.active_connections.items()):
+            if conn.is_alive:
+                await conn.__aexit__(None, None, None)
+
+        # 2. Trigger transport shutdown
+        await self._raw_stop()
+
+
+class AbstractClient(AbstractEndpoint):
+    """
+    Abstract Lifecycle Context Manager for Clients.
+    Subclasses only implement raw socket creation hooks.
+    """
+
+    def __init__(self, router: DuplexRouter):
+        super().__init__(router=router)
+        self._conn: AbstractDuplexConnection | None = None
+
+    @abstractmethod
+    async def _create_connection(self) -> AbstractDuplexConnection:
+        """Subclasses override this to open a raw network stream pipe."""
+
+    async def __aenter__(self) -> AbstractDuplexConnection:
+        self._conn = await self._create_connection()
+        # Simply enter the connection's context. The connection ABC starts the background loop natively!
+        return await self._conn.__aenter__()
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        if self._conn:
+            return await self._conn.__aexit__(exc_type, exc_val, exc_tb)

rpc_router-0.3.0/src/rpc_router/protocol.py

@@ -0,0 +1,256 @@
+import asyncio
+import json
+import logging
+import uuid
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+from typing import Any, Optional, Protocol
+
+from .exceptions import ConnectionBrokenException
+
+logger = logging.getLogger(__name__)
+
+
+class SendReceiveHandler(Protocol):
+    def __call__(self, ctx: AbstractDuplexConnection, frame: any) -> any:
+        pass
+
+
+class DuplexRouter:
+    """Symmetrical routing registry using an intuitive event syntax."""
+
+    def __init__(self):
+        self.routes: dict[str, Callable] = {}
+        self.connect_handler: Callable | None = None
+        self.receive_handlers: list[SendReceiveHandler] = []
+        self.send_handlers: list[SendReceiveHandler] = []
+
+    def on(self, name_or_func: str | Callable | None = None):
+        if callable(name_or_func):
+            self.routes[name_or_func.__name__] = name_or_func
+            return name_or_func
+
+        def decorator(func):
+            method_name = (
+                name_or_func if isinstance(name_or_func, str) else func.__name__
+            )
+            self.routes[method_name] = func
+            return func
+
+        return decorator
+
+    def on_connect(self, func: Callable):
+        self.connect_handler = func
+        return func
+
+    def before_receive(self, func: SendReceiveHandler):
+        self.receive_handlers.append(func)
+        return func
+
+    def before_send(self, func: SendReceiveHandler):
+        self.send_handlers.append(func)
+        return func
+
+
+class ConnectionManager:
+    """Manages active connection lifetimes across an application topology."""
+
+    def __init__(self):
+        self.active_connections: dict[str, AbstractDuplexConnection] = {}
+
+    def register(self, client_id: str, connection: "AbstractDuplexConnection") -> None:
+        self.active_connections[client_id] = connection
+        logger.debug(f"Registered client: {client_id}")
+
+    def unregister(self, client_id: str) -> None:
+        if self.active_connections.pop(client_id, None):
+            logger.debug(f"Unregistered client: {client_id}")
+
+    def get(self, client_id: str) -> Optional["AbstractDuplexConnection"]:
+        conn = self.active_connections.get(client_id)
+        return conn if (conn and conn.is_alive) else None
+
+    async def broadcast(
+        self,
+        method: str,
+        payload: Any = None,
+        exclude: list[str] | None = None,
+    ):
+        if exclude is None:
+            exclude = []
+        logger.debug(f"Broadcasting {method}: {payload}")
+        count = 0
+        for client_id in self.active_connections:
+            if client_id in exclude:
+                continue
+            count += 1
+            await self.send_to(client_id=client_id, method=method, payload=payload)
+        logger.debug(f"Broadcasted {method}: {payload} to {count} clients")
+        return count
+
+    async def send_to(self, client_id: str, method: str, payload: Any = None):
+        logger.debug(f"Sending {method}: {payload} to {client_id}")
+        conn = self.active_connections.get(client_id)
+        if not conn:
+            raise RuntimeError("No client with id %s", client_id)
+        await conn.send(method=method, payload=payload)
+
+
+class AbstractDuplexConnection(ABC):
+    """
+    Symmetrical Protocol Engine & Self-Driving Context Manager.
+    Completely encapsulates background task loops and lifecycles.
+    """
+
+    def __init__(
+        self,
+        router: DuplexRouter,
+        client_id: str | None = None,
+        manager: ConnectionManager | None = None,
+    ):
+        self.router = router
+        self.client_id = client_id or f"rpc-{uuid.uuid4().hex[:8]}"
+        self.manager = manager
+        self.pending_calls: dict[str, asyncio.Future] = {}
+        self.is_alive = True
+        self._listener_task: asyncio.Task | None = None
+
+    @abstractmethod
+    async def _raw_send(self, payload_str: str) -> None:
+        pass
+
+    @abstractmethod
+    async def _raw_recv(self) -> str | None:
+        pass
+
+    @abstractmethod
+    async def _raw_close(self) -> None:
+        pass
+
+    async def send(self, method: str, payload: Any = None) -> None:
+        if not self.is_alive:
+            raise ConnectionBrokenException
+        frame = {"id": None, "type": "signal", "method": method, "payload": payload}
+        await self._dispatch_frame(frame)
+
+    async def _dispatch_frame(self, frame):
+        logger.debug("Sending %s", frame)
+        for handler in self.router.send_handlers:
+            handler(self, frame=frame)
+        await self._raw_send(json.dumps(frame))
+
+    async def call(self, method: str, payload: Any = None, timeout: float = 5.0) -> Any:
+        if not self.is_alive:
+            raise ConnectionBrokenException
+        call_id = f"rpc-{uuid.uuid4()}"
+        future = asyncio.get_running_loop().create_future()
+        self.pending_calls[call_id] = future
+        frame = {"id": call_id, "type": "request", "method": method, "payload": payload}
+        await self._dispatch_frame(frame)
+        try:
+            return await asyncio.wait_for(future, timeout=timeout)
+        except asyncio.TimeoutError:
+            self.pending_calls.pop(call_id, None)
+            raise TimeoutError(f"Call to '{method}' timed out")
+
+    async def wait_forever(self) -> None:
+        """
+        Abstract helper method to passively anchor any server-side or client-side context.
+        Blocks execution natively until the underlying network stream finishes or drops.
+        """
+        if self._listener_task:
+            try:
+                await self._listener_task
+            except (asyncio.CancelledError, Exception):
+                pass
+
+    async def __aenter__(self):
+        self.is_alive = True
+        if self.router.connect_handler:
+            try:
+                res = await self.router.connect_handler(self)
+                logger.debug(f"Connect handler returned {res}")
+            except Exception as e:
+                logger.error(f"Exception {e} occured during connection")
+                self.is_alive = False
+                await self._raw_close()
+        if self.is_alive:
+            if self.manager:
+                self.manager.register(self.client_id, self)
+            self._listener_task = asyncio.create_task(self._listen_loop())
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        self.is_alive = False
+        if self.manager:
+            self.manager.unregister(self.client_id)
+
+        if self._listener_task and not self._listener_task.done():
+            self._listener_task.cancel()
+            try:
+                await self._listener_task
+            except (asyncio.CancelledError, Exception):
+                pass
+
+        for fut in list(self.pending_calls.values()):
+            if not fut.done():
+                fut.cancel()
+        self.pending_calls.clear()
+        await self._raw_close()
+
+    async def _listen_loop(self) -> None:
+        try:
+            while self.is_alive:
+                message = await self._raw_recv()
+                if message is None:
+                    logger.debug("Connection terminated")
+                    break
+                if self.is_alive:
+                    asyncio.create_task(self._handle_frame(message))
+        finally:
+            self.is_alive = False
+
+    async def _handle_frame(self, raw_message: str) -> None:
+        try:
+            frame = json.loads(raw_message)
+            logger.debug("Handling %s", frame)
+            for handler in self.router.receive_handlers:
+                handler(self, frame=frame)
+            t, fid, m, p = (
+                frame.get("type"),
+                frame.get("id"),
+                frame.get("method"),
+                frame.get("payload"),
+            )
+            if t == "response" and fid in self.pending_calls:
+                future = self.pending_calls.pop(fid, None)
+                if future and not future.done():
+                    (
+                        future.set_exception(RuntimeError(frame["error"]))
+                        if frame.get("error")
+                        else future.set_result(p)
+                    )
+            elif t in ("request", "signal") and (handler := self.router.routes.get(m)):
+                if t == "signal":
+                    await handler(self, p)
+                elif t == "request" and fid:
+                    try:
+                        res = await handler(self, p)
+                        frame = {
+                            "id": fid,
+                            "type": "response",
+                            "method": m,
+                            "payload": res,
+                        }
+                        await self._dispatch_frame(frame)
+                    except Exception as e:
+                        frame = {
+                            "id": fid,
+                            "type": "response",
+                            "method": m,
+                            "payload": None,
+                            "error": str(e),
+                        }
+                        await self._dispatch_frame(frame)
+        except Exception:
+            pass

rpc_router-0.3.0/src/rpc_router.egg-info/PKG-INFO

@@ -0,0 +1,3 @@
+Metadata-Version: 2.4
+Name: rpc-router
+Version: 0.3.0

rpc_router-0.3.0/src/rpc_router.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+pyproject.toml
+src/rpc_router/__init__.py
+src/rpc_router/exceptions.py
+src/rpc_router/lifecycle.py
+src/rpc_router/protocol.py
+src/rpc_router.egg-info/PKG-INFO
+src/rpc_router.egg-info/SOURCES.txt
+src/rpc_router.egg-info/dependency_links.txt
+src/rpc_router.egg-info/top_level.txt
+src/rpc_router/backends/__init__.py
+src/rpc_router/backends/fastapi/__init__.py
+src/rpc_router/backends/fastapi/transport.py
+src/rpc_router/backends/websockets/__init__.py
+src/rpc_router/backends/websockets/transport.py

rpc_router-0.3.0/src/rpc_router.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

rpc_router-0.3.0/src/rpc_router.egg-info/top_level.txt

@@ -0,0 +1 @@
+rpc_router