RPC servers (Effect's RpcServer).
layer(Group) runs a server of the group over the ServerProtocol
in the context; layer_http(Group, path=...) serves it on an
HttpRouter route, over WebSockets (the default) or HTTP POSTs;
layer_protocol_socket_server over the connections of a
SocketServer; layer_protocol_stdio over standard input and output;
layer_protocol_worker_runner inside a worker,
serving its parent. The serialization (RpcSerialization) and the
group's handlers come from the context.
Values#
| Attribute | Type | Description |
|---|---|---|
layer_protocol_socket_server | Layer[ServerProtocol, Never, RpcSerialization | SocketServer] | A |
layer_protocol_stdio | Layer[ServerProtocol, Never, Stdio | RpcSerialization] | A server protocol over the current |
layer_protocol_worker_runner | Layer[ServerProtocol, WorkerError, WorkerRunnerPlatform] | A server protocol over the current |
Types#
| Type | Definition | Description |
|---|---|---|
WriteRequest | type WriteRequest = Callable[[int, Message], Effect[None]] | |
HttpEffect | type HttpEffect = Effect[HttpServerResponse, Never, Scope | HttpServerRequest] |
Classes#
Functions#
make_protocol_http#
make_protocol_http(path, *, stream_buffer_size=16) -> Effect[ServerProtocolService, Never, RpcSerialization | HttpRouter]A server protocol over HTTP POSTs to path of the router.
| Parameter | Type | Description |
|---|---|---|
path | str | |
stream_buffer_size | BufferSize = 16 |
Returns Effect[ServerProtocolService, Never, RpcSerialization | HttpRouter]
def make_protocol_http(
path: str, *, stream_buffer_size: BufferSize = 16
) -> Effect[ServerProtocolService, Never, RpcSerialization | HttpRouter]:
"""A server protocol over HTTP POSTs to ``path`` of the router."""
@gen
def make_():
made = yield from make_protocol_with_http_effect(stream_buffer_size=stream_buffer_size)
router = yield from HttpRouter()
yield from router.add("POST", path, made.http_effect)
return made.protocol
return make_make_protocol_websocket#
make_protocol_websocket(path) -> Effect[ServerProtocolService, Never, RpcSerialization | HttpRouter]A server protocol over WebSockets upgraded from GETs of path.
| Parameter | Type | Description |
|---|---|---|
path | str |
Returns Effect[ServerProtocolService, Never, RpcSerialization | HttpRouter]
def make_protocol_websocket(
path: str,
) -> Effect[ServerProtocolService, Never, RpcSerialization | HttpRouter]:
"""A server protocol over WebSockets upgraded from GETs of ``path``."""
@gen
def make_():
made = yield from make_protocol_with_http_effect_websocket()
router = yield from HttpRouter()
yield from router.add("GET", path, made.http_effect)
return made.protocol
return make_layer_protocol_http#
layer_protocol_http(path, *, stream_buffer_size=16) -> Layer[ServerProtocol, Never, RpcSerialization | HttpRouter]| Parameter | Type | Description |
|---|---|---|
path | str | |
stream_buffer_size | BufferSize = 16 |
Returns Layer[ServerProtocol, Never, RpcSerialization | HttpRouter]
def layer_protocol_http(
path: str, *, stream_buffer_size: BufferSize = 16
) -> Layer[ServerProtocol, Never, RpcSerialization | HttpRouter]:
return layer_effect(
ServerProtocol, make_protocol_http(path, stream_buffer_size=stream_buffer_size)
)layer_protocol_websocket#
layer_protocol_websocket(path) -> Layer[ServerProtocol, Never, RpcSerialization | HttpRouter]| Parameter | Type | Description |
|---|---|---|
path | str |
Returns Layer[ServerProtocol, Never, RpcSerialization | HttpRouter]
def layer_protocol_websocket(
path: str,
) -> Layer[ServerProtocol, Never, RpcSerialization | HttpRouter]:
return layer_effect(ServerProtocol, make_protocol_websocket(path))layer_http#
layer_http[G: RpcGroup](group, *, path, protocol='websocket', options=None, stream_buffer_size=16) -> Layer[Never, Never, RpcSerialization | HttpRouter | HandlersFor[G]]A server of group on the route path of the router (Effect's
RpcServer.layerHttp).
| Parameter | Type | Description |
|---|---|---|
group | type[G] | |
path | str | |
protocol | Literal['http', 'websocket'] = 'websocket' | |
options | ServerOptions | None = None | |
stream_buffer_size | BufferSize = 16 |
Returns Layer[Never, Never, RpcSerialization | HttpRouter | HandlersFor[G]]
def layer_http[G: RpcGroup](
group: type[G],
*,
path: str,
protocol: Literal["http", "websocket"] = "websocket",
options: ServerOptions | None = None,
stream_buffer_size: BufferSize = 16,
) -> Layer[Never, Never, RpcSerialization | HttpRouter | HandlersFor[G]]:
"""A server of ``group`` on the route ``path`` of the router (Effect's
``RpcServer.layerHttp``)."""
transport = (
layer_protocol_http(path, stream_buffer_size=stream_buffer_size)
if protocol == "http"
else layer_protocol_websocket(path)
)
return layer(group, options).pipe(layer_provide(transport))to_http_effect#
to_http_effect[G: RpcGroup](group, *, options=None, stream_buffer_size=16) -> Effect[HttpEffect, Never, Scope | RpcSerialization | HandlersFor[G]]A server of group running in the current scope, and the HTTP
handler of its POSTs (Effect's RpcServer.toHttpEffect).
| Parameter | Type | Description |
|---|---|---|
group | type[G] | |
options | ServerOptions | None = None | |
stream_buffer_size | BufferSize = 16 |
Returns Effect[HttpEffect, Never, Scope | RpcSerialization | HandlersFor[G]]
def to_http_effect[G: RpcGroup](
group: type[G], *, options: ServerOptions | None = None, stream_buffer_size: BufferSize = 16
) -> Effect[HttpEffect, Never, Scope | RpcSerialization | HandlersFor[G]]:
"""A server of ``group`` running in the current scope, and the HTTP
handler of its POSTs (Effect's ``RpcServer.toHttpEffect``)."""
made = make_protocol_with_http_effect(stream_buffer_size=stream_buffer_size)
return _to_http_effect(group, made, options)to_http_effect_websocket#
to_http_effect_websocket[G: RpcGroup](group, *, options=None) -> Effect[HttpEffect, Never, Scope | RpcSerialization | HandlersFor[G]]to_http_effect over WebSockets.
| Parameter | Type | Description |
|---|---|---|
group | type[G] | |
options | ServerOptions | None = None |
Returns Effect[HttpEffect, Never, Scope | RpcSerialization | HandlersFor[G]]
def to_http_effect_websocket[G: RpcGroup](
group: type[G], *, options: ServerOptions | None = None
) -> Effect[HttpEffect, Never, Scope | RpcSerialization | HandlersFor[G]]:
"""``to_http_effect`` over WebSockets."""
return _to_http_effect(group, make_protocol_with_http_effect_websocket(), options)make_no_serialization#
make_no_serialization[G: RpcGroup](group, on_from_server, options=None) -> Effect[RpcServer, Never, Scope | HandlersFor[G]]A server of group writing its responses with on_from_server.
It shuts down with the current scope: running requests are interrupted
and it waits until each client is told it ended.
| Parameter | Type | Description |
|---|---|---|
group | type[G] | |
on_from_server | OnFromServer | |
options | ServerOptions | None = None |
Returns Effect[RpcServer, Never, Scope | HandlersFor[G]]
def make_no_serialization[G: RpcGroup](
group: type[G],
on_from_server: OnFromServer,
options: ServerOptions | None = None,
) -> Effect[RpcServer, Never, Scope | HandlersFor[G]]:
"""A server of ``group`` writing its responses with ``on_from_server``.
It shuts down with the current scope: running requests are interrupted
and it waits until each client is told it ended."""
resolved = options or ServerOptions()
@gen
def make():
services = yield from context()
scope = yield from Scope()
track = yield from scope.fork("parallel")
semaphore = None
if resolved.concurrency != "unbounded":
semaphore = yield from Semaphore.make(resolved.concurrency)
server = RpcServer(
group,
on_from_server=on_from_server,
options=resolved,
services=services,
track=track,
semaphore=semaphore,
)
yield from scope.add_finalizer(lambda _: server._close())
return server
return cast("Effect[RpcServer, Never, Scope | HandlersFor[G]]", make)with_run#
with_run[EX, RX](make) -> Effect[ServerProtocolService, EX, RX]A protocol from its parts, made with the function writing requests
to the server (Effect's Utils.withRun). Requests written before the
server runs are kept, and handed to it (with their services) when it
does. Each run of the effect makes its own buffer, so a layer over it
serves every run (and every worker) it is built for.
| Parameter | Type | Description |
|---|---|---|
make | Callable[[WriteRequest], Effect[ProtocolParts, EX, RX]] |
Returns Effect[ServerProtocolService, EX, RX]
def with_run[EX, RX](
make: Callable[[WriteRequest], Effect[ProtocolParts, EX, RX]],
) -> Effect[ServerProtocolService, EX, RX]:
"""A protocol from its parts, made with the function writing requests
to the server (Effect's ``Utils.withRun``). Requests written before the
server runs are kept, and handed to it (with their services) when it
does. Each run of the effect makes its own buffer, so a layer over it
serves every run (and every worker) it is built for."""
def per_run() -> Effect[ServerProtocolService, EX, RX]:
buffer: list[tuple[int, Message, Context[Any]]] = []
current: list[WriteRequest] = []
semaphore = Semaphore(1)
def buffered(client_id: int, message: Message) -> Effect[None]:
def keep(services: Context[Any]) -> None:
buffer.append((client_id, message, services))
return context().map(keep)
def write(client_id: int, message: Message) -> Effect[None]:
return suspend(lambda: (current[-1] if current else buffered)(client_id, message))
def build(parts: ProtocolParts) -> ServerProtocolService:
def run(f: WriteRequest) -> Effect[Never]:
@gen
def running():
# What these requests' startup writes joins the buffer, and is run too.
# Each runs on its own: a message that fails ends only itself, as a
# live write's failure ends only its own client's reader.
for client_id, message, services in buffer:
yield from (
suspend(lambda c=client_id, m=message: f(c, m))
.pipe(provide_context(services))
.ignore_cause(log=LogLevel.DEBUG, message=_REPLAY_FAILED)
)
buffer.clear()
current.append(f)
return (yield from never.on_exit(lambda _: succeed(current.remove(f))))
return semaphore.with_permits(running)
return ServerProtocolService(
run,
parts.disconnects,
parts.send,
parts.end,
parts.supports_ack,
parts.supports_span_propagation,
parts.codec_for,
parts.initial_message,
parts.supports_notifications,
parts.client_ids,
)
return make(write).map(build)
return suspend(per_run)layer#
layer[G: RpcGroup](group, options=None) -> Layer[Never, Never, ServerProtocol | HandlersFor[G]]A server of group running while the layer is built (Effect's
RpcServer.layer).
| Parameter | Type | Description |
|---|---|---|
group | type[G] | |
options | ServerOptions | None = None |
Returns Layer[Never, Never, ServerProtocol | HandlersFor[G]]
def layer[G: RpcGroup](
group: type[G], options: ServerOptions | None = None
) -> Layer[Never, Never, ServerProtocol | HandlersFor[G]]:
"""A server of ``group`` running while the layer is built (Effect's
``RpcServer.layer``)."""
return effect_discard(fork_scoped(scoped(make(group, options))))make#
make[G: RpcGroup](group, options=None) -> Effect[Never, Never, Scope | ServerProtocol | HandlersFor[G]]Run a server of group over the ServerProtocol in the
context, until interrupted (Effect's RpcServer.make).
| Parameter | Type | Description |
|---|---|---|
group | type[G] | |
options | ServerOptions | None = None |
Returns Effect[Never, Never, Scope | ServerProtocol | HandlersFor[G]]
def make[G: RpcGroup](
group: type[G], options: ServerOptions | None = None
) -> Effect[Never, Never, Scope | ServerProtocol | HandlersFor[G]]:
"""Run a server of ``group`` over the ``ServerProtocol`` in the
context, until interrupted (Effect's ``RpcServer.make``)."""
resolved = options or ServerOptions()
@gen
def run():
protocol = yield from ServerProtocol()
services = yield from context()
state = _Serialized(group, protocol, services)
server_options = ServerOptions(
disable_tracing=resolved.disable_tracing,
disable_span_propagation=not protocol.supports_span_propagation,
span_prefix=resolved.span_prefix,
span_attributes=resolved.span_attributes,
concurrency=resolved.concurrency,
disable_fatal_defects=resolved.disable_fatal_defects,
disable_client_acks=not protocol.supports_ack,
)
state.server = yield from make_no_serialization(group, state.on_from_server, server_options)
on_disconnect = resolved.on_disconnect
def handle_disconnect(client_id: int) -> Effect[None, Never, Scope]:
disconnected = state.disconnect(client_id)
hook_of = on_disconnect
if hook_of is None:
return disconnected
hook = suspend(lambda: hook_of(client_id)).ignore_cause(
log="Unhandled", message="RpcServer onDisconnect hook failed"
)
# In the server's scope: a slow hook delays no other cleanup, and
# pending hooks are interrupted when the server stops.
return disconnected.flat_map(lambda _: fork_scoped(hook).as_void())
@gen
def disconnects():
while True:
client_id = yield from protocol.disconnects.take()
yield from handle_disconnect(client_id)
yield from fork_scoped(disconnects)
return (yield from protocol.run(state.on_request))
return runmake_protocol_stdio#
make_protocol_stdio() -> Effect[ServerProtocolService, Never, Stdio | RpcSerialization | Scope]A server protocol over Stdio, for the current scope.
Returns Effect[ServerProtocolService, Never, Stdio | RpcSerialization | Scope]
def make_protocol_stdio() -> Effect[ServerProtocolService, Never, Stdio | RpcSerialization | Scope]:
"""A server protocol over ``Stdio``, for the current scope."""
@gen
def make():
stdio = yield from Stdio()
fiber = yield from current_fiber()
serialization = yield from RpcSerialization()
def parts(write: WriteRequest) -> Effect[ProtocolParts, Never, Any]:
@gen
def build():
output = yield from Queue[Frame, Done].bounded(_OUTPUT_BUFFER)
parser = serialization.make_unsafe()
def on_input(data: bytes) -> Effect[None]:
@gen
def each():
for message in parser.decode(data):
yield from write(_CLIENT, cast("Message", message))
return each
yield from fork_scoped(
stdio.stdin.run_for_each(on_input)
.sandbox()
.tap_error(log_error)
.retry(spaced(_RETRY_EVERY))
.flat_map(lambda _: write(_CLIENT, cast("Message", _EOF)))
)
yield from fork_scoped(
from_queue(output)
.run(stdio.stdout())
.retry(spaced(_RETRY_EVERY))
.on_exit(lambda exit: _end_server(fiber, exit))
)
def send(_client: int, response: Message) -> Effect[None]:
encoded = parser.encode(response)
return succeed(None) if encoded is None else output.offer(encoded).as_void()
return ProtocolParts(
disconnects=(yield from Queue[int].unbounded()),
send=send,
end=lambda _client: output.end().as_void(),
supports_ack=True,
supports_span_propagation=True,
codec_for=serialization.codec_for,
client_ids=succeed(frozenset({_CLIENT})),
)
return build
return (yield from with_run(parts))
return makemake_protocol_socket_server#
make_protocol_socket_server() -> Effect[ServerProtocolService, Never, RpcSerialization | SocketServer | Scope]A server protocol over the connections of the SocketServer.
Returns Effect[ServerProtocolService, Never, RpcSerialization | SocketServer | Scope]
def make_protocol_socket_server() -> Effect[
ServerProtocolService, Never, RpcSerialization | SocketServer | Scope
]:
"""A server protocol over the connections of the ``SocketServer``."""
@gen
def make():
server = yield from SocketServer()
made = yield from make_socket_protocol()
yield from fork_scoped(server.run(lambda socket: scoped(made.on_socket(socket, ()))))
return made.protocol
return makemake_protocol_with_http_effect#
make_protocol_with_http_effect(*, stream_buffer_size=16) -> Effect[HttpProtocol, Never, RpcSerialization]A server protocol over HTTP POSTs: each request body is a client's messages; the response holds its responses (streamed as they come for a framed serialization).
| Parameter | Type | Description |
|---|---|---|
stream_buffer_size | BufferSize = 16 |
Returns Effect[HttpProtocol, Never, RpcSerialization]
def make_protocol_with_http_effect(
*, stream_buffer_size: BufferSize = 16
) -> Effect[HttpProtocol, Never, RpcSerialization]:
"""A server protocol over HTTP POSTs: each request body is a client's
messages; the response holds its responses (streamed as they come for
a framed serialization)."""
@gen
def make():
serialization = yield from RpcSerialization()
encode_defect = encode_defect_for(serialization.codec_for)
disconnects = yield from Queue[int, Never].unbounded()
clients: dict[int, _HttpClient] = {}
ids = iter(range(1 << 62))
writes: list[WriteRequest] = []
def parts(write: WriteRequest) -> Effect[ProtocolParts]:
writes.append(write)
def send(client_id: int, response: Message) -> Effect[None]:
client = clients.get(client_id)
return _VOID if client is None else client.write(response)
def end(client_id: int) -> Effect[None]:
client = clients.get(client_id)
return _VOID if client is None else client.end
return succeed(
ProtocolParts(
disconnects=disconnects,
send=send,
end=end,
supports_ack=False,
supports_span_propagation=False,
codec_for=serialization.codec_for,
supports_notifications=serialization.includes_framing,
client_ids=sync(lambda: frozenset(clients)),
)
)
protocol = yield from with_run(parts)
handler = _HttpHandler(
serialization,
encode_defect=encode_defect,
disconnects=disconnects,
clients=clients,
ids=ids,
writes=writes,
buffer=stream_buffer_size,
)
return HttpProtocol(protocol, handler.handle())
return makemake_protocol_with_http_effect_websocket#
make_protocol_with_http_effect_websocket() -> Effect[HttpProtocol, Never, RpcSerialization]A server protocol over WebSockets, upgraded by its HTTP handler.
Returns Effect[HttpProtocol, Never, RpcSerialization]
def make_protocol_with_http_effect_websocket() -> Effect[HttpProtocol, Never, RpcSerialization]:
"""A server protocol over WebSockets, upgraded by its HTTP handler."""
@gen
def make():
made = yield from make_socket_protocol()
@gen
def handle():
request = yield from HttpServerRequest()
if not (yield from origin_allowed(request)):
return empty(status=403)
socket = yield from request.upgrade.or_die()
yield from made.on_socket(socket, _request_headers(request))
return empty()
return HttpProtocol(made.protocol, handle)
return makemake_socket_protocol#
make_socket_protocol() -> Effect[SocketProtocol, Never, RpcSerialization]Returns Effect[SocketProtocol, Never, RpcSerialization]
def make_socket_protocol() -> Effect[SocketProtocol, Never, RpcSerialization]:
@gen
def make():
serialization = yield from RpcSerialization()
encode_defect = encode_defect_for(serialization.codec_for)
disconnects = yield from Queue[int, Never].unbounded()
clients: dict[int, Callable[[Message], Effect[None]]] = {}
ids = iter(range(1 << 62))
writes: list[WriteRequest] = []
def on_socket(socket: SocketService, headers: RequestHeaders) -> Effect[None, Never, Scope]:
@gen
def serve():
scope = yield from Scope()
parser = serialization.make_unsafe()
client_id = next(ids)
def leave(_: object) -> Effect[None]:
clients.pop(client_id, None)
return disconnects.offer(client_id).as_void()
yield from scope.add_finalizer(leave)
writer = yield from socket.writer
clients[client_id] = lambda response: _socket_write(
writer, parser, encode_defect, response
)
def process(data: Frame) -> Effect[None, SocketError]:
try:
decoded = parser.decode(data)
except MaxBufferSizeExceeded as cause:
return writer.write(CloseEvent(1009, str(cause)))
except Exception as cause:
defect = parser.encode(response_defect_encoded(encode_defect(cause)))
return _VOID if defect is None else writer.write(defect)
@gen
def each():
for message in decoded:
yield from writes[0](
client_id, _with_headers(cast("Message", message), headers)
)
return each
@gen
def read():
reader = yield from socket.reader
while True:
frames = yield from reader.pull
for frame in frames:
yield from process(frame)
def closed(error: SocketError) -> Effect[None, SocketError]:
return _VOID if isinstance(error.reason, SocketCloseError) else fail(error)
yield from read.catch_all(closed).or_die()
return serve
def send(client_id: int, response: Message) -> Effect[None]:
write = clients.get(client_id)
return _VOID if write is None else write(response)
def parts(write: WriteRequest) -> Effect[ProtocolParts]:
writes.append(write)
return succeed(
ProtocolParts(
disconnects=disconnects,
send=send,
end=lambda _: _VOID,
supports_ack=True,
supports_span_propagation=True,
codec_for=serialization.codec_for,
client_ids=sync(lambda: frozenset(clients)),
)
)
protocol = yield from with_run(parts)
return SocketProtocol(protocol, on_socket)
return makemake_protocol_worker_runner#
make_protocol_worker_runner() -> Effect[ServerProtocolService, WorkerError, WorkerRunnerPlatform | Scope]A server protocol over the WorkerRunner of the worker this runs
in. When the parent closes the worker, the fiber that made the
protocol (a layer.launch) is interrupted, so the worker's program
ends.
Returns Effect[ServerProtocolService, WorkerError, WorkerRunnerPlatform | Scope]
def make_protocol_worker_runner() -> Effect[
ServerProtocolService, WorkerError, WorkerRunnerPlatform | Scope
]:
"""A server protocol over the ``WorkerRunner`` of the worker this runs
in. When the parent closes the worker, the fiber that made the
protocol (a ``layer.launch``) is interrupted, so the worker's program
ends."""
def parts(write: WriteRequest) -> Effect[ProtocolParts, WorkerError, Any]:
@gen
def make():
fiber = yield from current_fiber()
scheduler = yield from CurrentScheduler()
platform = yield from WorkerRunnerPlatform()
backing = yield from platform.start()
initial = Deferred[object]()
client_ids: set[int] = set()
disconnects = yield from Queue[int].unbounded()
def on_message(client_id: int, message: Message) -> Effect[Any]:
client_ids.add(client_id)
if message.get("_tag") == "InitialMessage":
return initial.succeed(message.get("value"))
return write(client_id, message)
def end_program(_: object) -> Effect[None]:
return sync(lambda: scheduler.schedule(lambda: fiber.interrupt_as_unsafe(fiber.id)))
yield from fork_scoped(
backing.run(on_message).tap_cause(log_error).on_exit(end_program)
)
if backing.disconnects is not None:
dequeue = backing.disconnects
def left(client_id: int) -> Effect[None]:
client_ids.discard(client_id)
return disconnects.offer(client_id).as_void()
yield from fork_scoped(dequeue.take().flat_map(left).forever())
def send(client_id: int, response: Message) -> Effect[None]:
return backing.send(client_id, response)
return ProtocolParts(
disconnects=disconnects,
send=send,
end=lambda _: sync(lambda: None),
supports_ack=True,
supports_span_propagation=True,
codec_for=cast("CodecFor", _codec_for),
initial_message=initial.wait().map(_some),
client_ids=sync(lambda: frozenset(client_ids)),
)
return make
return cast(
"Effect[ServerProtocolService, WorkerError, WorkerRunnerPlatform | Scope]",
with_run(parts),
)On This Page
ValuesTypesClassesFunctionsmake_protocol_httpmake_protocol_websocketlayer_protocol_httplayer_protocol_websocketlayer_httpto_http_effectto_http_effect_websocketmake_no_serializationwith_runlayermakemake_protocol_stdiomake_protocol_socket_servermake_protocol_with_http_effectmake_protocol_with_http_effect_websocketmake_socket_protocolmake_protocol_worker_runner