GitHub

API reference for client.

RPC clients (Effect's RpcClient).

make(Group) is a client of the group over the ClientProtocol in the context: an instance of the group whose RPC attributes call them. layer_protocol_http(url) and layer_protocol_socket() give the protocol; the serialization (RpcSerialization) comes from the context. layer_protocol_worker(size=) calls a pool of workers instead (their messages are values, so it needs no serialization).

Types

TypeDefinitionDescription
TransformClienttype TransformClient = Callable[[HttpClientService[Any, Any]], HttpClientService[Any, Any]]

Classes

Functions

layer_protocol_http

layer_protocol_http(url, *, transform_client=None, batch=None) -> Layer[ClientProtocol, Never, RpcSerialization | HttpClient]

A client protocol POSTing to url with the HttpClient; with batch, the requests a client makes together go in one POST.

ParameterTypeDescription
urlstr
transform_clientTransformClient | None = None
batchBatch | None = None

Returns Layer[ClientProtocol, Never, RpcSerialization | HttpClient]

def layer_protocol_http(
    url: str, *, transform_client: TransformClient | None = None, batch: Batch | None = None
) -> Layer[ClientProtocol, Never, RpcSerialization | HttpClient]:
    """A client protocol POSTing to ``url`` with the ``HttpClient``; with
    ``batch``, the requests a client makes together go in one POST."""
    from pyfect.effect import gen

    @gen
    def make_():
        client = yield from HttpClient()
        bound: HttpClientService[Any, Any] = client.map_request(
            lambda request: request.prepend_url(url)
        )
        if transform_client is not None:
            bound = transform_client(bound)
        return (yield from make_protocol_http(bound, batch=batch))

    return layer_effect(ClientProtocol, make_)

layer_protocol_socket

layer_protocol_socket(options=None) -> Layer[ClientProtocol, Never, RpcSerialization | Socket]

A client protocol over the Socket in the context.

ParameterTypeDescription
optionsSocketOptions | None = None

Returns Layer[ClientProtocol, Never, RpcSerialization | Socket]

def layer_protocol_socket(
    options: SocketOptions | None = None,
) -> Layer[ClientProtocol, Never, RpcSerialization | Socket]:
    """A client protocol over the ``Socket`` in the context."""
    return layer_effect(ClientProtocol, make_protocol_socket(options))

make_no_serialization

make_no_serialization[G: RpcGroup](group, on_from_client, options=None) -> Effect[tuple[G, ClientCore], Never, Scope]

A client of group sending its requests with on_from_client; hand it the responses with the core's write. Closing the scope interrupts the calls waiting.

ParameterTypeDescription
grouptype[G]
on_from_clientSendFn
optionsClientOptions | None = None

Returns Effect[tuple[G, ClientCore], Never, Scope]

def make_no_serialization[G: RpcGroup](
    group: type[G], on_from_client: SendFn, options: ClientOptions | None = None
) -> Effect[tuple[G, ClientCore], Never, Scope]:
    """A client of ``group`` sending its requests with ``on_from_client``;
    hand it the responses with the core's ``write``. Closing the scope
    interrupts the calls waiting."""

    @gen
    def make():
        services = yield from context()
        scope = yield from Scope()
        core = ClientCore(on_from_client, options or ClientOptions(), services)
        yield from scope.add_finalizer(lambda _: core.close())
        client = group()
        client._rpc_methods = core.methods(group)
        return client, core

    return make

with_headers

with_headers(headers) -> _WithHeaders

Send headers with the requests made inside: eff.pipe(with_headers({"authorization": token})).

ParameterTypeDescription
headersMapping[str, str] | Headers

Returns _WithHeaders

def with_headers(headers: Mapping[str, str] | Headers) -> _WithHeaders:
    """Send ``headers`` with the requests made inside:
    ``eff.pipe(with_headers({"authorization": token}))``."""
    return _WithHeaders(from_input(headers))

make_protocol_http

make_protocol_http(client, *, batch=None) -> Effect[ClientProtocolService, Never, RpcSerialization]

A client protocol POSTing to client (whose base URL is the server's): each request on its own, or with batch the requests a client makes together in one HTTP request.

ParameterTypeDescription
clientHttpClientService[Any, Any]
batchBatch | None = None

Returns Effect[ClientProtocolService, Never, RpcSerialization]

def make_protocol_http(
    client: HttpClientService[Any, Any], *, batch: Batch | None = None
) -> Effect[ClientProtocolService, Never, RpcSerialization]:
    """A client protocol POSTing to ``client`` (whose base URL is the
    server's): each request on its own, or with ``batch`` the requests a
    client makes together in one HTTP request."""

    def make() -> Effect[ClientProtocolService, Never, RpcSerialization]:
        batchers: list[_Batcher] = []

        def parts(
            write: WriteTo, _ids: set[int]
        ) -> Effect[ClientProtocolParts, Never, RpcSerialization]:
            def build(serialization: RpcSerializationService) -> ClientProtocolParts:
                exchange = _HttpExchange(client, serialization, write)
                if batch is None:
                    send = _unbatched(exchange)
                else:
                    batcher = _Batcher(exchange, batch)
                    batchers.append(batcher)
                    send = batcher.send

                def send_request(client_id: int, message: Message) -> Effect[None, RpcClientError]:
                    return send(client_id, message) if message.get("_tag") == "Request" else _VOID

                return ClientProtocolParts(send_request, False, serialization.codec_for)

            return RpcSerialization().map(build)

        def with_batches(protocol: ClientProtocolService) -> ClientProtocolService:
            if not batchers:
                return protocol
            batcher = batchers[0]

            def run(client_id: int, f: WriteResponse) -> Effect[Never]:
                return protocol.run(client_id, f).on_exit(lambda _: batcher.close(client_id))

            return ClientProtocolService(run, protocol.send, False, protocol.codec_for)

        return with_run_client(parts).map(with_batches)

    return suspend(make)

with_run_client

with_run_client[EX, RX](make) -> Effect[ClientProtocolService, EX, RX]

A client protocol from its parts, made with the function writing a response to a client and the set of running clients (Effect's Utils.withRunClient). Responses for a client that sent a request but is not running yet are kept until it runs; responses for any other client (one that stopped running) are dropped, so nothing is kept for a client that never runs again (Effect keeps them).

When the Scope the protocol is made in closes, the calls waiting and every later call fail with an RpcClientError saying the protocol is closed (in Effect they wait forever): a client made with make(Group).pipe(provide(protocol)) outlives its protocol.

Each run of the effect makes its own state, so a layer over it serves every run it is provided to.

ParameterTypeDescription
makeCallable[[WriteTo, set[int]], Effect[ClientProtocolParts, EX, RX]]

Returns Effect[ClientProtocolService, EX, RX]

def with_run_client[EX, RX](
    make: Callable[[WriteTo, set[int]], Effect[ClientProtocolParts, EX, RX]],
) -> Effect[ClientProtocolService, EX, RX]:
    """A client protocol from its parts, made with the function writing a
    response to a client and the set of running clients (Effect's
    ``Utils.withRunClient``). Responses for a client that sent a request
    but is not running yet are kept until it runs; responses for any other
    client (one that stopped running) are dropped, so nothing is kept for
    a client that never runs again (Effect keeps them).

    When the ``Scope`` the protocol is made in closes, the calls waiting
    and every later call fail with an ``RpcClientError`` saying the
    protocol is closed (in Effect they wait forever): a client made with
    ``make(Group).pipe(provide(protocol))`` outlives its protocol.

    Each run of the effect makes its own state, so a layer over it
    serves every run it is provided to."""

    def per_run() -> Effect[ClientProtocolService, EX, RX]:
        client_ids: set[int] = set()
        buffers: dict[int, list[tuple[Message, Context[Any]]]] = {}
        writes: dict[int, WriteResponse] = {}
        awaited: set[int] = set()
        """The clients that sent a request and have not stopped running."""
        released: list[RpcClientError] = []

        def write(client_id: int, response: Message) -> Effect[None]:
            def body() -> Effect[None]:
                found = writes.get(client_id)
                if found is not None:
                    return found(response)
                if client_id not in awaited:
                    return _VOID

                def keep(services: Context[Any]) -> None:
                    buffers.setdefault(client_id, []).append((response, services))

                return context().map(keep)

            return suspend(body)

        def build(parts: ClientProtocolParts) -> ClientProtocolService:
            def send(client_id: int, message: Message) -> Effect[None, RpcClientError]:
                def body() -> Effect[None, RpcClientError]:
                    if released:
                        return fail(released[0])
                    if message.get("_tag") == "Request":
                        awaited.add(client_id)
                    return parts.send(client_id, message)

                return suspend(body)

            def run(client_id: int, f: WriteResponse) -> Effect[Never]:
                @gen
                def running():
                    client_ids.add(client_id)
                    writes[client_id] = f
                    for response, services in buffers.pop(client_id, []):
                        yield from suspend(lambda r=response: f(r)).pipe(provide_context(services))

                    def leave(_: object) -> Effect[None]:
                        client_ids.discard(client_id)
                        awaited.discard(client_id)
                        writes.pop(client_id, None)
                        buffers.pop(client_id, None)
                        return _VOID

                    return (yield from never.on_exit(leave))

                return running

            return ClientProtocolService(run, send, parts.supports_ack, parts.codec_for)

        def release(_: object) -> Effect[None]:
            error = protocol_closed()
            released.append(error)
            failure: Message = {"_tag": "ClientProtocolError", "error": error}

            @gen
            def fail_waiting():
                for f in list(writes.values()):
                    yield from f(failure)

            return fail_waiting.uninterruptible()

        @gen
        def made():
            service = yield from make(write, client_ids).map(build)
            scope = yield from service_option(Scope)
            if scope is not None:
                # Added last, so it runs first: the waiting calls fail before
                # the transport is torn down.
                yield from scope.value.add_finalizer(release)
            return service

        return made

    return suspend(per_run)

make

make[G: RpcGroup](group: type[G], options: ClientOptions | None = None) -> Effect[G, Never, Scope | ClientProtocol]
make[G: RpcGroup, E, R](group: type[G], options: ClientOptions | None = None, *, layer: Layer[ClientProtocol, E, R]) -> Effect[G, E, R | Scope]

A client of group over the ClientProtocol in the context (Effect's RpcClient.make), or over layer, built into the caller's Scope. The client is valid until that scope closes; a protocol provided to make(...) alone is released once the client is made, and its calls then fail with an RpcClientError. Client middleware comes from the context too (middleware.layer_client).

ParameterTypeDescription
group
options= None
layer= None
@overload
def make[G: RpcGroup](
    group: type[G], options: ClientOptions | None = None
) -> Effect[G, Never, Scope | ClientProtocol]: ...
@overload
def make[G: RpcGroup, E, R](
    group: type[G], options: ClientOptions | None = None, *, layer: Layer[ClientProtocol, E, R]
) -> Effect[G, E, R | Scope]: ...
def make(
    group: type[RpcGroup],
    options: ClientOptions | None = None,
    *,
    layer: Layer[ClientProtocol, Any, Any] | None = None,
) -> Effect[Any, Any, Any]:
    """A client of ``group`` over the ``ClientProtocol`` in the context
    (Effect's ``RpcClient.make``), or over ``layer``, built into the
    caller's ``Scope``. The client is valid until that scope closes; a
    protocol provided to ``make(...)`` alone is released once the client
    is made, and its calls then fail with an ``RpcClientError``. Client
    middleware comes from the context too (``middleware.layer_client``)."""
    return with_layer(lambda: _make(group, options), layer)

default_retry_policy

default_retry_policy() -> Schedule[Any, Any, Never, Never]

Exponential from 0.5s by 1.5, at most 5s apart.

Returns Schedule[Any, Any, Never, Never]

def default_retry_policy() -> Schedule[Any, Any, Never, Never]:
    """Exponential from 0.5s by 1.5, at most 5s apart."""
    return cast(
        "Schedule[Any, Any, Never, Never]",
        schedule.min(schedule.exponential("500 millis", 1.5), schedule.spaced("5 seconds")),
    )

make_protocol_socket

make_protocol_socket(options=None) -> Effect[ClientProtocolService, Never, Scope | RpcSerialization | Socket]

A client protocol over the Socket in the context, reconnecting when it drops.

ParameterTypeDescription
optionsSocketOptions | None = None

Returns Effect[ClientProtocolService, Never, Scope | RpcSerialization | Socket]

def make_protocol_socket(
    options: SocketOptions | None = None,
) -> Effect[ClientProtocolService, Never, Scope | RpcSerialization | Socket]:
    """A client protocol over the ``Socket`` in the context, reconnecting
    when it drops."""
    resolved = options or SocketOptions()

    def parts(write: WriteTo, ids: set[int]) -> Effect[ClientProtocolParts, Never, Any]:
        @gen
        def make():
            socket = yield from Socket()
            serialization = yield from RpcSerialization()
            hooks = yield from ConnectionHooks()
            clock = yield from Clock()
            writer = yield from socket.writer
            interval = from_input_unsafe(resolved.ping_interval)
            timeout = (
                interval
                if resolved.ping_timeout is None
                else from_input_unsafe(resolved.ping_timeout)
            )
            pinger = _Pinger(clock, timeout)
            client = _SocketClient(
                serialization, write=write, ids=ids, writer=writer, pinger=pinger, options=resolved
            )
            yield from fork_scoped(
                pinger.tick(client.write_ping()).delay(interval).ignore().forever().interruptible()
            )
            policy = resolved.retry_policy or default_retry_policy()
            connection = client.connection(socket, hooks).tap_cause(client.on_cause)
            yield from fork_scoped(
                connection.retry(policy).catch_all(
                    lambda error: client.broadcast_error(RpcClientError(reason=error.reason))
                )
            )
            return ClientProtocolParts(client.send, True, serialization.codec_for)

        return make

    return cast(
        "Effect[ClientProtocolService, Never, Scope | RpcSerialization | Socket]",
        with_run_client(parts),
    )

layer_protocol_worker

layer_protocol_worker(*, size: int, concurrency: int = 1, target_utilization: float = 1.0) -> Layer[ClientProtocol, WorkerError, WorkerPlatform | Spawner]
layer_protocol_worker(*, min_size: int, max_size: int, time_to_live: DurationInput, concurrency: int = 1, target_utilization: float = 1.0) -> Layer[ClientProtocol, WorkerError, WorkerPlatform | Spawner]

make_protocol_worker as a layer.

ParameterTypeDescription
options= {}
@overload
def layer_protocol_worker(
    *, size: int, concurrency: int = 1, target_utilization: float = 1.0
) -> Layer[ClientProtocol, WorkerError, WorkerPlatform | Spawner]: ...
@overload
def layer_protocol_worker(
    *,
    min_size: int,
    max_size: int,
    time_to_live: DurationInput,
    concurrency: int = 1,
    target_utilization: float = 1.0,
) -> Layer[ClientProtocol, WorkerError, WorkerPlatform | Spawner]: ...
def layer_protocol_worker(
    **options: Any,
) -> Layer[ClientProtocol, WorkerError, WorkerPlatform | Spawner]:
    """``make_protocol_worker`` as a layer."""
    return layer_effect(ClientProtocol, make_protocol_worker(**options))

make_protocol_worker

make_protocol_worker(*, size: int, concurrency: int = 1, target_utilization: float = 1.0) -> Effect[ClientProtocolService, WorkerError, _Requirements]
make_protocol_worker(*, min_size: int, max_size: int, time_to_live: DurationInput, concurrency: int = 1, target_utilization: float = 1.0) -> Effect[ClientProtocolService, WorkerError, _Requirements]

A client protocol over a pool of workers from the WorkerPlatform: size of them, or between min_size and max_size with idle ones above min_size released after time_to_live. Each worker serves concurrency requests at a time; a worker that fails is respawned a second later, and its requests get a ClientProtocolError. An InitialMessage in the context is sent to each worker first.

ParameterTypeDescription
size= None
min_size= None
max_size= None
time_to_live= None
concurrency= 1
target_utilization= 1.0
@overload
def make_protocol_worker(
    *, size: int, concurrency: int = 1, target_utilization: float = 1.0
) -> Effect[ClientProtocolService, WorkerError, _Requirements]: ...
@overload
def make_protocol_worker(
    *,
    min_size: int,
    max_size: int,
    time_to_live: DurationInput,
    concurrency: int = 1,
    target_utilization: float = 1.0,
) -> Effect[ClientProtocolService, WorkerError, _Requirements]: ...
def make_protocol_worker(
    *,
    size: int | None = None,
    min_size: int | None = None,
    max_size: int | None = None,
    time_to_live: DurationInput | None = None,
    concurrency: int = 1,
    target_utilization: float = 1.0,
) -> Effect[ClientProtocolService, WorkerError, _Requirements]:
    """A client protocol over a pool of workers from the ``WorkerPlatform``:
    ``size`` of them, or between ``min_size`` and ``max_size`` with idle
    ones above ``min_size`` released after ``time_to_live``. Each worker
    serves ``concurrency`` requests at a time; a worker that fails is
    respawned a second later, and its requests get a
    ``ClientProtocolError``. An ``InitialMessage`` in the context is sent
    to each worker first."""
    ranged = (min_size, max_size, time_to_live)
    sized = size is not None and all(option is None for option in ranged)
    bounded = size is None and all(option is not None for option in ranged)
    if not (sized or bounded):
        raise TypeError(
            "make_protocol_worker takes size=, or min_size=, max_size= and time_to_live="
        )

    def parts(
        write: WriteTo, client_ids: set[int]
    ) -> Effect[ClientProtocolParts, WorkerError, Any]:
        @gen
        def make():
            platform = yield from WorkerPlatform()
            initial = yield from service_option(InitialMessage)
            hooks = yield from ConnectionHooks()
            client = _WorkerClient(
                write, client_ids, platform, None if initial is None else initial.value
            )
            acquire = client.acquire()
            if size is not None:
                pool = yield from Pool.make(
                    acquire,
                    size=size,
                    concurrency=concurrency,
                    target_utilization=target_utilization,
                )
            else:
                pool = yield from Pool.make_with_ttl(
                    acquire,
                    min=cast("int", min_size),
                    max=cast("int", max_size),
                    time_to_live=cast("DurationInput", time_to_live),
                    concurrency=concurrency,
                    target_utilization=target_utilization,
                )
            yield from add_finalizer(lambda _: sync(client.close))
            yield from scoped(pool.get())
            if hooks is not None:
                yield from hooks.on_connect
            return ClientProtocolParts(client.send_with(pool), True, cast("CodecFor", _codec_for))

        return make

    return cast("Effect[ClientProtocolService, WorkerError, _Requirements]", with_run_client(parts))