GitHub

API reference for server.

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

AttributeTypeDescription
layer_protocol_socket_serverLayer[ServerProtocol, Never, RpcSerialization | SocketServer]

A ServerProtocol serving each connection of the SocketServer (make_protocol_socket_server).

layer_protocol_stdioLayer[ServerProtocol, Never, Stdio | RpcSerialization]

A server protocol over the current Stdio: requests are read from standard input and responses written to standard output. Once input has ended and the last response is written, it interrupts the fiber that built it, as Effect's layerProtocolStdio does, so a launched server under run_main exits 130.

layer_protocol_worker_runnerLayer[ServerProtocol, WorkerError, WorkerRunnerPlatform]

A server protocol over the current WorkerRunnerPlatform.

Types

TypeDefinitionDescription
WriteRequesttype WriteRequest = Callable[[int, Message], Effect[None]]
HttpEffecttype 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.

ParameterTypeDescription
pathstr
stream_buffer_sizeBufferSize = 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.

ParameterTypeDescription
pathstr

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]
ParameterTypeDescription
pathstr
stream_buffer_sizeBufferSize = 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]
ParameterTypeDescription
pathstr

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).

ParameterTypeDescription
grouptype[G]
pathstr
protocolLiteral['http', 'websocket'] = 'websocket'
optionsServerOptions | None = None
stream_buffer_sizeBufferSize = 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).

ParameterTypeDescription
grouptype[G]
optionsServerOptions | None = None
stream_buffer_sizeBufferSize = 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.

ParameterTypeDescription
grouptype[G]
optionsServerOptions | 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.

ParameterTypeDescription
grouptype[G]
on_from_serverOnFromServer
optionsServerOptions | 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.

ParameterTypeDescription
makeCallable[[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).

ParameterTypeDescription
grouptype[G]
optionsServerOptions | 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).

ParameterTypeDescription
grouptype[G]
optionsServerOptions | 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 run

make_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 make

make_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 make

make_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).

ParameterTypeDescription
stream_buffer_sizeBufferSize = 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 make

make_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 make

make_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 make

make_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),
    )