An RpcGroup declares procedures: each has a tag, and the schemas of its payload, success
and error. The server runs a handler per procedure; the client is an instance of the group
whose attributes call them, typed by the same schemas. Calls are messages, so one connection
carries many at once, and a procedure can answer with a stream of values.
Define, serve and call a group#
rpc.make(tag, payload=..., success=..., error=...) declares a procedure; a success of
rpc_schema.Stream(values, error) makes it a stream. Group.handlers().handle(Group.rpc)(f)
adds a handler, which takes an RpcRequest with the decoded payload and gives the success
value (or a Stream of them) or fails with the declared error. Group.to_layer(handlers) is
their layer, and raises ValueError naming each procedure left without a handler.
A group can list its tags, class Users(RpcGroup[Literal["GetUser", "Users"]]), so pyright
checks its handlers as TypeScript checks Effect's toLayer: to_layer rejects them while a
procedure has none, and a second handler for one is an error. Python has no way to gather a
class's attributes into a type, so the list repeats the tags; the class is checked against it
when it is defined, and a TypeError names any tag missing from either side. A tag must be a
string literal at rpc.make for its procedure to be checked (prefix makes it a plain
str).
rpc_server.layer_http(Group, path=...) serves the group on a route of the
router, over WebSockets by default or HTTP POSTs with
protocol="http". A call or handshake from a browser page of another origin is refused
with 403; layer.succeed(AllowedOrigins, origin.allow("https://app.example")) (from
pyfect.http.origin) lists the origins to accept too. Messages are encoded by the
RpcSerialization in the context:
serialization.layer_ndjson or layer_json, JSON-RPC 2.0 with layer_json_rpc() and
layer_nd_json_rpc(), or layer_schema_binary(), the
binary format, whose frames read and write the same bytes as
Effect's (max_frame_size= limits a frame, 16 MiB by default; fingerprint_payloads=True
fails on a payload whose layout differs). router.serve passes the layer's needs through, so the handlers
(HandlersFor[Group]) and the serialization can be provided to the served layer.
rpc_server.layer_protocol_stdio serves a group over standard input and output, for a
program another one starts: rpc_server.layer(Group) over it, launched, ends once input has
ended and the last response is written. As in Effect, the end interrupts the fiber that built
the layer, so under run_main the program exits with status 130, not 0.
rpc_client.make(Group) is the client, over the ClientProtocol in the context:
layer_protocol_http(url) sends calls as POSTs, and layer_protocol_socket() over the
Socket in the context. A call fails with the procedure's error or an RpcClientError,
whose reason is the socket's or worker's error, an HttpClientErrorSchema for an HTTP
failure, or an RpcClientDefect; it is a schema class, so it encodes as Effect's does;
a stream procedure gives a Stream. client.rpc.discard(payload) completes once the
server acknowledges the call as its handler starts, after the middleware ran: the handler's
result is not returned, but a middleware error or a failure before the handler starts still
fails it (over HTTP and workers it completes when the handler is done).
A JSON-RPC notification (a request without an id) runs like any call but gets no reply; one
for an unknown method or with an invalid payload is dropped and logged at debug level.
layer_json_rpc(control_messages=False) reads @effect/rpc/* methods as ordinary
notifications, for plain JSON-RPC peers. ServerOptions(on_disconnect=...) is called with
each client id the transport reports disconnected, after its requests were interrupted.
The client is valid while the protocol is. Provide the protocol around the code that uses
the client, or pass it as rpc_client.make(Group, layer=protocol), which builds it into the
caller's scope. rpc_client.make(Group).pipe(fx.provide(protocol)) releases the protocol
(and its WebSocket) as soon as the client is made; every call on that client then fails
with an RpcClientError saying the protocol is closed.
import pyfect as fx
from pyfect import layer, stream
from pyfect import schema as S
from pyfect.http import httpx_client, router, server, uvicorn_server
from pyfect.rpc import RpcGroup, RpcRequest, make, rpc_schema, serialization
from pyfect.rpc import client as rpc_client
from pyfect.rpc import server as rpc_server
class Todo(S.Class, identifier="Todo"):
id: int
title: str
class TodoNotFound(S.TaggedError):
id: int
# The group: each RPC's payload, success and error are schemas.
class Todos(RpcGroup):
get_todo = make("GetTodo", payload=S.Int, success=Todo, error=TodoNotFound)
# A stream RPC: the client gets the values as the handler produces them.
countdown = make("Countdown", payload=S.Int, success=rpc_schema.Stream(S.Int, S.Never))
todos = {1: Todo(id=1, title="Write docs")}
@fx.fn
def get_todo(request: RpcRequest[int]):
todo = todos.get(request.payload)
if todo is None:
return (yield from TodoNotFound(id=request.payload))
return todo
def countdown(request: RpcRequest[int]):
return stream.iterate(request.payload, lambda n: n - 1).take(request.payload + 1)
TodosLive = Todos.to_layer(
Todos.handlers().handle(Todos.get_todo)(get_todo).handle(Todos.countdown)(countdown)
)
# Serve the group on POST /rpc of the router. It needs the handlers and a serialization.
RpcLive = rpc_server.layer_http(Todos, path="/rpc", protocol="http")
def client_protocol(url: str):
return rpc_client.layer_protocol_http(url).pipe(layer.provide(serialization.layer_ndjson))
# The client: an instance of the group whose attributes call the server. `layer=` builds
# the protocol into this scope, so it lives as long as the client.
@fx.fn
def program():
url = yield from server.address_formatted_with(lambda origin: fx.succeed(f"{origin}/rpc"))
todos_client = yield from rpc_client.make(Todos, layer=client_protocol(url))
print((yield from todos_client.get_todo(1)))
print(repr((yield from todos_client.get_todo(2).flip())))
print((yield from todos_client.countdown(3).run_collect()))
# serve passes what the routes need through: provide the handlers and newline-delimited
# JSON to the served layer.
served = (
router.serve(RpcLive, disable_logger=True, disable_listen_log=True)
.pipe(layer.provide(TodosLive))
.pipe(layer.provide(serialization.layer_ndjson))
)
fx.run_main(
fx.scoped(program())
.pipe(fx.provide(served))
.pipe(fx.provide(uvicorn_server.layer(host="127.0.0.1"))) # any free port
.pipe(fx.provide(httpx_client.layer))
)Over a WebSocket#
pyfect.socket.ws.layer_web_socket(url) is a client Socket on the websockets library,
installed with the extra: pip install "pyfect-dev[websockets]". Under
layer_protocol_socket() it gives a protocol that sends every call over one connection,
reconnecting when it drops.
import pyfect as fx
from pyfect import layer
from pyfect import schema as S
from pyfect.http import router, server, uvicorn_server
from pyfect.rpc import RpcGroup, RpcRequest, make, serialization
from pyfect.rpc import client as rpc_client
from pyfect.rpc import server as rpc_server
from pyfect.socket import ws # needs the websockets extra: pip install "pyfect-dev[websockets]"
class Greeter(RpcGroup):
greet = make("Greet", payload=S.String, success=S.String)
def greet(request: RpcRequest[str]):
return fx.succeed(f"Hello, {request.payload}!")
# rpc_server.layer_http serves over WebSockets unless protocol="http" is given.
GreeterLive = (
rpc_server.layer_http(Greeter, path="/rpc")
.pipe(layer.provide(Greeter.to_layer(Greeter.handlers().handle(Greeter.greet)(greet))))
.pipe(layer.provide(serialization.layer_json))
)
def socket_protocol(url: str):
"""The protocol over one WebSocket, opened when the layer is built and closed with it."""
return (
rpc_client.layer_protocol_socket()
.pipe(layer.provide(ws.layer_web_socket(url)))
.pipe(layer.provide(serialization.layer_json))
)
@fx.fn
def calls():
"""Every call here goes over the same WebSocket."""
greeter = yield from rpc_client.make(Greeter)
print((yield from greeter.greet("Ada")))
print((yield from greeter.greet("Grace")))
@fx.fn
def program():
url = yield from server.address_formatted_with(
lambda origin: fx.succeed(origin.replace("http://", "ws://") + "/rpc")
)
# Provided around the code that uses the client: the socket stays open until it ends.
yield from fx.scoped(calls()).pipe(fx.provide(socket_protocol(url)))
served = router.serve(GreeterLive, disable_logger=True, disable_listen_log=True)
fx.run_main(
fx.scoped(program())
.pipe(fx.provide(served))
.pipe(fx.provide(uvicorn_server.layer(host="127.0.0.1")))
)RpcMiddleware runs around the handlers of the procedures that name it with
.middleware(...), for authentication say, and can provide them a service such as the
current user.
Security defaults#
- A WebSocket handshake or HTTP call from a browser page of another origin gets a 403 unless
AllowedOriginslists it. - Headers the transport carries, such as those of the HTTP request or the WebSocket upgrade, win over headers of the same name inside a message, so a client cannot claim a header that a proxy or gateway set. A message's headers must be string pairs; any other shape fails only that request. An object of strings is read only on a transport that carries no headers of its own (standard input and output, workers): over HTTP or a WebSocket the transport's pairs come first, as in Effect, and an object can't follow them.
- The client checks every message from the server before routing it, so a frame that isn't
a message fails the waiting call with an
RpcClientErrorand the connection keeps working. AnExitthat doesn't decode with the procedure's schemas is a defect of the call holding theSchemaError, as in Effect. Closing a client's scope sends an Interrupt for each call still running and drops late replies for it. - An NDJSON frame (
serialization.layer_ndjson,layer_nd_json_rpc()) holds at most 16 MiB of an unfinished line; a peer sending more fails its connection withMaxBufferSizeExceeded.layer_ndjson_with(max_buffer_size=...)sets another limit, in characters, andmax_buffer_size="unbounded"removes it. A line trickled in small frames costs time linear in its length.
Testing handlers#
pyfect.rpc.test.make_client(Group, layer=GroupLive) calls the handlers in memory,
without a server or serialization. The layer is built into the test's scope, so a database
or forked workers in it stay open while the client is used; provided to make_client(...)
alone, it would be released once the client is made.
import pyfect as fx
from pyfect import layer, scope, stream, testing
from pyfect import schema as S
from pyfect.rpc import RpcGroup, RpcRequest, make, rpc_schema
from pyfect.rpc import test as rpc_test
class Todo(S.Class, identifier="Todo"):
id: int
title: str
class TodoNotFound(S.TaggedError):
id: int
class Todos(RpcGroup):
get_todo = make("GetTodo", payload=S.Int, success=Todo, error=TodoNotFound)
countdown = make("Countdown", payload=S.Int, success=rpc_schema.Stream(S.Int, S.Never))
class Store(fx.Tag[dict[int, Todo]]): ...
@fx.fn
def get_todo(request: RpcRequest[int]):
todo = (yield from Store()).get(request.payload)
if todo is None:
return (yield from TodoNotFound(id=request.payload))
return todo
def countdown(request: RpcRequest[int]):
return stream.iterate(request.payload, lambda n: n - 1).take(request.payload + 1)
TodosLive = Todos.to_layer(
Todos.handlers().handle(Todos.get_todo)(get_todo).handle(Todos.countdown)(countdown)
)
def open_store():
"""A store that is cleared when its scope closes, like a database connection."""
def close(store: dict[int, Todo], _exit: object):
return fx.sync(store.clear)
return scope.acquire_release(fx.sync(lambda: {1: Todo(id=1, title="Test")}), close)
# The handlers' services come from the test; the store is a scoped resource.
TestTodos = TodosLive.pipe(layer.provide(layer.effect(Store, open_store())))
def todos_client():
"""A client calling the handlers in memory: no server, no serialization. `layer=`
builds TestTodos into the test's scope, so the store stays open while the client is
used. (`make_client(Todos).pipe(fx.provide(TestTodos))` would close it at once.)"""
return rpc_test.make_client(Todos, layer=TestTodos)
@testing.effect
def test_gets_a_todo():
client = yield from todos_client()
assert (yield from client.get_todo(1)) == Todo(id=1, title="Test")
@testing.effect
def test_a_missing_todo_is_a_typed_error():
client = yield from todos_client()
assert (yield from client.get_todo(7).flip()) == TodoNotFound(id=7)
@testing.effect
def test_streams_the_countdown():
client = yield from todos_client()
assert (yield from client.countdown(2).run_collect()) == [2, 1, 0]To test over real HTTP against uvicorn_server.layer_test(), give
rpc_client.layer_protocol_http a real client and the absolute URL from
server.address_formatted_with. The test server's own HttpClient doesn't work here, in
Effect either: it prefixes every URL with the server's origin, then the protocol prefixes
its URL on top. A relative URL fails with InvalidUrl (POST /rpc/http://127.0.0.1:PORT/)
and an absolute one with Error decoding HTTP response.
import pyfect as fx
from pyfect import layer
from pyfect import schema as S
from pyfect.http import httpx_client, router, server, uvicorn_server
from pyfect.rpc import RpcGroup, RpcRequest, make, serialization
from pyfect.rpc import client as rpc_client
from pyfect.rpc import server as rpc_server
class Greeter(RpcGroup):
greet = make("Greet", payload=S.String, success=S.String)
def greet(request: RpcRequest[str]) -> fx.Effect[str]:
return fx.succeed(f"hi {request.payload}")
Served = (
rpc_server.layer_http(Greeter, path="/rpc", protocol="http")
.pipe(layer.provide(Greeter.to_layer(Greeter.handlers().handle(Greeter.greet)(greet))))
.pipe(layer.provide(serialization.layer_json))
)
@fx.fn
def call():
greeter = yield from rpc_client.make(Greeter)
return (yield from greeter.greet("ada"))
@fx.fn
def program():
# The address the test server got, and a real client: not the test server's own.
url = yield from server.address_formatted_with(lambda origin: fx.succeed(f"{origin}/rpc"))
protocol = rpc_client.layer_protocol_http(url).pipe(
layer.provide(layer.merge(serialization.layer_json, httpx_client.layer))
)
print((yield from fx.scoped(call()).pipe(fx.provide(protocol))))
served = router.serve(Served, disable_logger=True, disable_listen_log=True)
fx.run_main(
fx.scoped(program()).pipe(fx.provide(served)).pipe(fx.provide(uvicorn_server.layer_test()))
)Reference: pyfect.rpc, pyfect.rpc.group,
pyfect.rpc.server,
pyfect.rpc.client,
pyfect.rpc.serialization.