Skip to main content

A fast and durable bidirectional JSON RPC channel over Websockets and FastApi.

Project description

RPC

⚡ FASTAPI Websocket RPC

RPC over Websockets made easy, robust, and production ready

Tests Package Downloads

A fast and durable bidirectional JSON RPC channel over Websockets. The easiest way to create a live async channel between two nodes via Python (or other clients).

  • Both server and clients can easily expose Python methods that can be called by the other side. Method return values are sent back as RPC responses, which the other side can wait on.

  • Remote methods are easily called via the .other.method() wrapper

  • Connections are kept alive with a configurable retry mechanism (using Tenacity)

  • As seen at PyCon IL 2021 and EuroPython 2021

Supports and tested on Python >= 3.9

Installation 🛠️

pip install fastapi_websocket_rpc

RPC call example:

Say the server exposes an "add" method, e.g. :

class RpcCalculator(RpcMethodsBase):
    async def add(self, a, b):
        return a + b

Calling it is as easy as calling the method under the client's "other" property:

response = await client.other.add(a=1,b=2)
print(response.result) # 3

getting the response with the return value.

Usage example:

Server:

import uvicorn
from fastapi import FastAPI
from fastapi_websocket_rpc import RpcMethodsBase, WebsocketRPCEndpoint

# Methods to expose to the clients
class ConcatServer(RpcMethodsBase):
    async def concat(self, a="", b=""):
        return a + b
    
# Init the FAST-API app
app =  FastAPI()
# Create an endpoint and load it with the methods to expose
endpoint = WebsocketRPCEndpoint(ConcatServer())
# add the endpoint to the app
endpoint.register_route(app, "/ws")

# Start the server itself
uvicorn.run(app, host="0.0.0.0", port=9000)

Client

import asyncio
from fastapi_websocket_rpc import RpcMethodsBase, WebSocketRpcClient

async def run_client(uri):
    async with WebSocketRpcClient(uri, RpcMethodsBase()) as client:
        # call concat on the other side
        response = await client.other.concat(a="hello", b=" world")
        # print result
        print(response.result)  # will print "hello world"

# run the client until it completes interaction with server
asyncio.get_event_loop().run_until_complete(
    run_client("ws://localhost:9000/ws")
)

See the examples and tests folders for more server and client examples

Server calling client example:

  • Clients can call client.other.method()
    • which is a shortcut for channel.other.method()
  • Servers also get the channel object and can call remote methods via channel.other.method()
  • See the bidirectional call example for calling client from server and server events (e.g. on_connect).

What can I do with this?

Websockets are ideal to create bi-directional realtime connections over the web.

  • Push updates
  • Remote control mechanism
  • Pub / Sub (see fastapi_websocket_pubsub)
  • Trigger events (see "tests/trigger_flow_test.py")
  • Node negotiations (see "tests/advanced_rpc_test.py :: test_recursive_rpc_calls")

Concepts

  • RpcChannel - implements the RPC-protocol over the websocket

    • Sending RpcRequests per method call
    • Creating promises to track them (via unique call ids), and allow waiting for responses
    • Executing methods on the remote side and serializing return values as
    • Receiving RpcResponses and delivering them to waiting callers
  • RpcMethods - classes passed to both client and server-endpoint inits to expose callable methods to the other side.

    • Simply derive from RpcMethodsBase and add your own async methods
    • Note currently only key-word arguments are supported
    • Checkout RpcUtilityMethods for example methods, which are also useful debugging utilities
  • Foundations:

    • Based on asyncio for the power of Python coroutines

    • Server Endpoint:

      • Based on FAST-API: enjoy all the benefits of a full ASGI platform, including Async-io and dependency injections (for example to authenticate connections)

      • Based on Pydantic: easily serialize structured data as part of RPC requests and responses (see 'tests/basic_rpc_test.py :: test_structured_response' for an example)

    • Client :

      • Based on Tenacity: allowing configurable retries to keep to connection alive
        • see WebSocketRpcClient.init's retry_config
      • Based on python websockets - a more comprehensive client than the one offered by Fast-api

Logging

fastapi-websocket-rpc provides a helper logging module to control how it produces logs for you. See fastapi_websocket_rpc/logger.py. Use logging_config.set_mode or the 'WS_RPC_LOGGING' environment variable to choose the logging method you prefer or override completely via default logging config.

example:

# set RPC to log like UVICORN
from fastapi_websocket_rpc.logger import logging_config, LoggingModes
logging_config.set_mode(LoggingModes.UVICORN)

HTTP(S) Proxy

By default, fastapi-websocket-rpc uses websockets module as websocket client handler. This does not support HTTP(S) Proxy, see https://github.com/python-websockets/websockets/issues/364 . If the ability to use a proxy is important to, another websocket client implementation can be used, e.g. websocket-client (https://websocket-client.readthedocs.io). Here is how to use it. Installation:

pip install fastapi_websocket_rpc[websocket-client]

Then use websocket_client_handler_cls parameter:

import asyncio
from fastapi_websocket_rpc import RpcMethodsBase, WebSocketRpcClient, ProxyEnabledWebSocketClientHandler

async def run_client(uri):
    async with WebSocketRpcClient(uri, RpcMethodsBase(), websocket_client_handler_cls = ProxyEnabledWebSocketClientHandler) as client:

Just set standard environment variables (lowercase and uppercase works): http_proxy, https_proxy, and no_proxy before running python script.

Pull requests - welcome!

  • Please include tests for new features

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

fastapi_websocket_rpc-0.1.28.tar.gz (21.1 kB view details)

Uploaded Source

Built Distribution

fastapi_websocket_rpc-0.1.28-py3-none-any.whl (21.7 kB view details)

Uploaded Python 3

File details

Details for the file fastapi_websocket_rpc-0.1.28.tar.gz.

File metadata

File hashes

Hashes for fastapi_websocket_rpc-0.1.28.tar.gz
Algorithm Hash digest
SHA256 62259fc51db13027410c61a025918a618cd1a8ef1cf294eadde62ef48780d049
MD5 c9750c10950e013dabc7884a0d1adb6a
BLAKE2b-256 d0bbd8f917f37c488cc041c257238cd5f20a56f16a39ff95f2d8f96d2b614588

See more details on using hashes here.

File details

Details for the file fastapi_websocket_rpc-0.1.28-py3-none-any.whl.

File metadata

File hashes

Hashes for fastapi_websocket_rpc-0.1.28-py3-none-any.whl
Algorithm Hash digest
SHA256 0e7a31fdd6c6f732fe6ce2d7c98c7712e4bed34a107827007085b506716d3bd7
MD5 7201cab494fc28461937745ddae2b15b
BLAKE2b-256 be314f524c1cbc9f067b0829e93e6b8efb805186afb61ea24af4dbb3e7c2b728

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page