Both ends can call.

WSRPC makes one WebSocket symmetric. The browser calls your Python handlers, and a handler calls back into the browser and waits for the answer.

pip install wsrpc-aiohttp

pip install wsrpc-asgi

Read the documentation Quick start

browser server connecting

This page

The wire

No frames yet.

Every line here was drawn by a call from the server into this page. This page runs the JavaScript client that ships with the package, and these frames are the ones a Python server exchanges.

The same call from every side

A handler on aiohttp or ASGI, and a caller in Python, in TypeScript or on a plain page.

server.py

import random

from aiohttp import web
from wsrpc_aiohttp import STATIC_DIR, Route, WebSocketAsync, decorators

QUOTES = [
    ("HAL 9000", "I'm sorry, Dave. I'm afraid I can't do that."),
    ("The Oracle", "There is no spoon."),
    ("T-800", "I'll be back."),
]


class Socket(WebSocketAsync):
    pass


class Chat(Route[Socket]):
    @decorators.proxy
    async def send(self, *, text: str) -> dict:
        # Draw the line in the page that called, and wait for its answer.
        await self.socket.proxy.chat.append(text=text, mine=True)

        sender, reply = random.choice(QUOTES)
        await self.socket.proxy.chat.append(sender=sender, text=reply)
        return {"delivered": True}


def create_app() -> web.Application:
    Socket.add_route("chat", Chat)
    app = web.Application()
    app.router.add_get("/ws/", Socket)
    app.router.add_static("/js/", STATIC_DIR)
    return app


if __name__ == "__main__":
    web.run_app(create_app(), host="127.0.0.1", port=8000)

app.py

import random

from fastapi import FastAPI, WebSocket
from wsrpc_asgi import Route, WebSocketAsync, decorators

QUOTES = [
    ("HAL 9000", "I'm sorry, Dave. I'm afraid I can't do that."),
    ("The Oracle", "There is no spoon."),
    ("T-800", "I'll be back."),
]


class RPC(WebSocketAsync):
    pass


class Chat(Route[RPC]):
    @decorators.proxy
    async def send(self, *, text: str) -> dict:
        # Draw the line in the page that called, and wait for its answer.
        await self.socket.proxy.chat.append(text=text, mine=True)

        sender, reply = random.choice(QUOTES)
        await self.socket.proxy.chat.append(sender=sender, text=reply)
        return {"delivered": True}


RPC.add_route("chat", Chat)
app = FastAPI()


@app.websocket("/ws/")
async def rpc(websocket: WebSocket) -> None:
    await RPC.serve(websocket)

client.py

import asyncio

from wsrpc_aiohttp import Route, WSRPCClient, decorators


class Chat(Route):
    @decorators.proxy
    def append(self, *, text: str, sender: str = "you", mine: bool = False) -> dict:
        # The server calls this method. Draw the line and confirm it.
        print(f"{sender}: {text}")
        return {"seen": True}


async def main() -> None:
    client = WSRPCClient("http://127.0.0.1:8000/ws/")

    # Register the route before the connection opens.
    client.add_route("chat", Chat)

    async with client:
        print(await client.proxy.chat.send(text="Hello"))
        await asyncio.sleep(1)


if __name__ == "__main__":
    asyncio.run(main())

chat.ts

import WSRPC from "@wsrpc/client";

interface Line {
  sender?: string;
  text: string;
  mine?: boolean;
}

const chat = document.getElementById("chat") as HTMLElement;
const rpc = new WSRPC("/ws/");

// The server calls this route. The page draws what it gets.
rpc.addRoute("chat.append", (line: Line) => {
  const row = document.createElement("p");
  row.textContent = `${line.sender ?? "you"}: ${line.text}`;
  chat.append(row);
  return { seen: true };
});

rpc.connect();

export async function say(text: string): Promise<void> {
  await rpc.call<{ delivered: boolean }>("chat.send", { text });
}

wsrpc-client.d.ts

// The package ships wsrpc.d.ts. Map it onto the module name once.
declare module "@wsrpc/client" {
  export default class WSRPC {
    constructor(url: string, reconnectTimeout?: number);
    connect(): void;
    destroy(): void;
    state(): "CONNECTING" | "OPEN" | "CLOSING" | "CLOSED";
    call<T>(method: string, params?: object): Promise<T>;
    addRoute(
      route: string,
      handler: (params: never) => unknown,
      isAsync?: boolean,
    ): void;
  }
}

index.html

<form id="say"><input name="text" autocomplete="off"></form>
<div id="chat"></div>

<script src="/js/wsrpc.min.js"></script>
<script>
  const rpc = new WSRPC("/ws/");

  // The server calls this route. The page draws what it gets.
  rpc.addRoute("chat.append", function (line) {
    const row = document.createElement("p");
    row.textContent = (line.sender || "you") + ": " + line.text;
    document.getElementById("chat").append(row);
    return {seen: true};
  });

  rpc.connect();

  document.getElementById("say").addEventListener("submit", function (event) {
    event.preventDefault();
    rpc.proxy.chat.send({text: event.target.text.value});
    event.target.reset();
  });
</script>

What the connection gives you

Calls in both directions

A handler calls a route that the browser registered, and awaits its result on the same socket.

Routes or plain functions

Expose a function, or a route class whose instance lives as long as the connection it serves.

Many calls at once

Every call carries its own id, so results return to their own callers in any order.

Remote errors raise locally

A failure on the far side arrives with its type and message, and raises where you made the call.

Signals for the lifecycle

Watch connect, disconnect and each call without wrapping a single handler.

Blocking code stays off the loop

Asynchronous handlers run on the event loop. Synchronous handlers run in a thread pool.

How a call travels

Every frame is one JSON object. A call carries an id, a method and params; the answer comes back with the same id. Both peers send calls, so a handler can ask the browser a question while it serves one.

The browser calls the server.

The server calls the browser inside the call it is serving.

Which package?

Two implementations, one wire protocol. A Python peer, a browser peer and a server can be mixed freely.

	`wsrpc-aiohttp`	`wsrpc-asgi`
Server	aiohttp web handler	ASGI route, middleware or standalone application
Frameworks	aiohttp	FastAPI, Starlette, Django, Litestar, Quart, Sanic, Falcon, BlackSheep
Install	pip install wsrpc-aiohttp	pip install 'wsrpc-asgi[fastapi,client]'
Python client	built on aiohttp	built on websockets
JavaScript client	included	the same client
JSON codec	loads and dumps are replaceable	the same