GitHub

atom_rpc

API reference for atom_rpc.

Atoms over an RPC client (Effect's effect/reactivity/AtomRpc).

make(tag, group=Users, protocol=...) gives an AtomRpcClient: a runtime whose layer provides tag with a client of group over the protocol, query atoms calling an RPC (a pull atom for a streaming one) and mutation function atoms::

class UsersClient(Tag[Users], key="UsersClient"): ...

client = atom_rpc.make(UsersClient, group=Users, protocol=protocol_layer)
user = client.query(Users.get_user, {"id": 1}, reactivity_keys=["users"])
rename = client.mutation(Users.rename)
registry.set(rename, {"payload": {"id": 1, "name": "x"}, "reactivity_keys": ["users"]})

A query with a serialization_key is serializable (hydration), as AtomRpc:<tag>:<key>; a mutation is, as AtomRpc:mutation:[id,tag]. Equal arguments give the same atom.

Types

TypeDefinitionDescription
ProtocolLayertype ProtocolLayer = Layer[Any, Any, Any]

The layer a client needs: its ClientProtocol and the client side of its RPCs' middleware (failures become defects).

Classes

Functions

make

make[G: RpcGroup, T](tag, *, group, protocol, make_effect=None, span_prefix=None, span_attributes=None, generate_request_id=None, disable_tracing=False, runtime=runtime) -> AtomRpcClient[G, T]

Atoms over a client of group provided as tag (Effect's AtomRpc.Service): the client is make_effect, by default RpcClient.make(group, ...) with the tracing options, over protocol (a layer, or a function of the atom context giving one). runtime is the runtime factory.

ParameterTypeDescription
tagProvides[G, T]
grouptype[G]
protocolProtocolLayer | Callable[[AtomContext], ProtocolLayer]
make_effectEffect[G, Never, Any] | None = None
span_prefixstr | None = None
span_attributesMapping[str, object] | None = None
generate_request_idCallable[[], RequestId] | None = None
disable_tracingbool = False
runtimeRuntimeFactory = runtime

Returns AtomRpcClient[G, T]

def make[G: RpcGroup, T](
    tag: Provides[G, T],
    *,
    group: type[G],
    protocol: ProtocolLayer | Callable[[AtomContext], ProtocolLayer],
    make_effect: Effect[G, Never, Any] | None = None,
    span_prefix: str | None = None,
    span_attributes: Mapping[str, object] | None = None,
    generate_request_id: Callable[[], RequestId] | None = None,
    disable_tracing: bool = False,
    runtime: RuntimeFactory = runtime,
) -> AtomRpcClient[G, T]:
    """Atoms over a client of ``group`` provided as ``tag`` (Effect's
    ``AtomRpc.Service``): the client is ``make_effect``, by default
    ``RpcClient.make(group, ...)`` with the tracing options, over
    ``protocol`` (a layer, or a function of the atom context giving
    one). ``runtime`` is the runtime factory."""
    options = rpc_client.ClientOptions(
        span_prefix=span_prefix,
        span_attributes=dict(span_attributes or {}),
        disable_tracing=disable_tracing,
        generate_request_id=generate_request_id,
    )
    if make_effect is not None:
        require_effect(make_effect, "make_effect")
    made = make_effect if make_effect is not None else rpc_client.make(group, options)
    client_layer: Layer[T, Never, Any] = layer_effect(tag, made)

    def with_protocol(layer: ProtocolLayer) -> Layer[T]:
        return client_layer.pipe(provide(layer.or_die()))

    if isinstance(protocol, Layer):
        atom_runtime = runtime(with_protocol(cast("ProtocolLayer", protocol)))
    else:
        make_protocol = protocol
        atom_runtime = runtime(lambda get: with_protocol(make_protocol(get)))
    return AtomRpcClient(tag, group, atom_runtime)