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#
| Type | Definition | Description |
|---|---|---|
TransformClient | type 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.
| Parameter | Type | Description |
|---|---|---|
url | str | |
transform_client | TransformClient | None = None | |
batch | Batch | 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.
| Parameter | Type | Description |
|---|---|---|
options | SocketOptions | 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.
| Parameter | Type | Description |
|---|---|---|
group | type[G] | |
on_from_client | SendFn | |
options | ClientOptions | 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 makewith_headers#
with_headers(headers) -> _WithHeadersSend headers with the requests made inside:
eff.pipe(with_headers({"authorization": token})).
| Parameter | Type | Description |
|---|---|---|
headers | Mapping[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.
| Parameter | Type | Description |
|---|---|---|
client | HttpClientService[Any, Any] | |
batch | Batch | 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.
| Parameter | Type | Description |
|---|---|---|
make | Callable[[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).
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
options | SocketOptions | 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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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))