GitHub

API reference for entity.

Entities (Effect's Entity): addressable types whose instances answer RPCs across a cluster. Subclass Entity with the RPCs as attributes, register the handlers with to_layer (or a mailbox with to_layer_queue) and call them through client().

Values

AttributeTypeDescription
KeepAliveRpcRpc[None, None, Never, Never, Never, Literal['Cluster/Entity/keepAlive']]

The persisted, uninterruptible RPC an entity sends itself to stay alive.

Types

TypeDefinitionDescription
ClusterClientErrortype ClusterClientError = MailboxFull | AlreadyProcessingMessage | PersistenceError | EntityNotAssignedToRunner

What an entity client's calls fail with besides the RPC's own errors.

Concurrencytype Concurrency = int | Literal['unbounded']
EntityHandlerFntype EntityHandlerFn = Callable[[Request[Any]], Any]
Behaviourtype Behaviour[R] = Callable[[Dequeue[Request[Any], Never], Replier], Effect[Never, Never, R]]

Classes

Functions

keep_alive

keep_alive(enabled) -> Effect[None, Never, Sharding | CurrentAddress]

Keep the current entity alive (True) until called with False; outside an entity that can be kept alive it does nothing. A provided KeepAliveHandler is called instead.

ParameterTypeDescription
enabledbool

Returns Effect[None, Never, Sharding | CurrentAddress]

def keep_alive(enabled: bool) -> Effect[None, Never, Sharding | CurrentAddress]:
    """Keep the current entity alive (``True``) until called with
    ``False``; outside an entity that can be kept alive it does nothing. A
    provided ``KeepAliveHandler`` is called instead."""

    @gen
    def run():
        handler = yield from service_option(KeepAliveHandler)
        if handler is not None:
            yield from handler.value(enabled)
            return
        found = yield from service_option(KeepAliveLatch)
        if found is None:
            return
        latch = found.value
        if not enabled:
            yield from latch.open()
            return
        sharding = yield from Sharding()
        address = yield from CurrentAddress()
        request_id = yield from sharding.get_snowflake
        span = yield from current_span().or_die()
        latch.close_unsafe()
        message = OutgoingRequest(
            annotations=KeepAliveRpc.annotations,
            rpc=KeepAliveRpc,
            context=Context.empty(),
            envelope=make_request(
                request_id=request_id,
                address=address,
                tag=KeepAliveRpc.tag,
                payload=None,
                trace_id=span.trace_id,
                span_id=span.span_id,
                sampled=span.sampled,
            ),
            last_received_reply=None,
            respond=_ignore,
        )
        yield from sharding.send_outgoing(message, True).or_die()

    return run.with_span(
        "Entity/keepAlive", attributes={"enabled": enabled}, capture_stack_trace=False
    )

make_test_client

make_test_client[T: Entity, E](entity: type[T], layer: Layer[Any, E, Sharding], /) -> Effect[Callable[[str], Effect[T]], E, Scope | ShardingConfig]
make_test_client[T: Entity, E, R](entity: type[T], layer: Layer[Any, E, R | Sharding], /) -> Effect[Callable[[str], Effect[T]], E, Scope | ShardingConfig | R]

Build layer against a sharding that records the entity's registration, and give a function making the client of an entity id: each id gets its own entity, started on first use and stopped when the current scope closes.

ParameterTypeDescription
entity
layer
@overload
def make_test_client[T: Entity, E](
    entity: type[T], layer: Layer[Any, E, Sharding], /
) -> Effect[Callable[[str], Effect[T]], E, Scope | ShardingConfig]: ...
@overload
def make_test_client[T: Entity, E, R](
    entity: type[T], layer: Layer[Any, E, R | Sharding], /
) -> Effect[Callable[[str], Effect[T]], E, Scope | ShardingConfig | R]: ...
def make_test_client(entity: type[Entity], layer: Layer[Any, Any, Any], /) -> Effect[Any, Any, Any]:
    """Build ``layer`` against a sharding that records the entity's
    registration, and give a function making the client of an entity id:
    each id gets its own entity, started on first use and stopped when the
    current scope closes."""
    require_layer(layer, "layer")

    @gen
    def make():
        config = yield from ShardingConfig()
        snowflakes = yield from make_generator()
        sharding = _TestSharding()
        yield from layer.pipe(layer_.provide(layer_.succeed(Sharding, sharding))).build()
        entry = sharding.registered.get(entity.type)
        if entry is None:
            yield from die(
                RuntimeError(f"Entity.make_test_client: {entity.type} was not registered by layer")
            )
            return None
        registered = entry

        @fn_untraced
        def lookup(entity_id: str):
            id = EntityId(entity_id)
            address = EntityAddress(
                entity_type=entity.type,
                entity_id=id,
                shard_id=ShardId(
                    group=entity.get_shard_group(id),
                    id=shard_number(entity_id, config.shards_per_group),
                ),
            )
            scope = yield from Scope()
            handler_context = (
                registered.context.add(CurrentRunnerAddress, _RUNNER_ADDRESS)
                .add(CurrentAddress, address)
                .add(CurrentActivationScope, scope)
                .add(Scope, scope)
            )
            handlers = yield from _Locally(registered.build, lambda _: handler_context)
            cores: list[ClientCore] = []

            def on_from_server(response: FromServer) -> Effect[None]:
                return cores[0].write(response)

            server = yield from _Locally(
                make_server_core(
                    entity.protocol,
                    on_from_server,
                    ServerOptions(
                        concurrency=registered.concurrency,
                        disable_fatal_defects=registered.disable_fatal_defects,
                    ),
                ),
                lambda _: handler_context.merge(handlers),
            )

            def on_from_client(sent: OnFromClient) -> Effect[None, Any]:
                message = sent.message
                if isinstance(message, rpc_message.Request):
                    request = Request[Any](
                        request_id=Snowflake(int(message.id)),
                        address=address,
                        tag=message.tag,
                        payload=message.payload,
                        headers=message.headers,
                        trace_id=message.trace_id,
                        span_id=message.span_id,
                        sampled=message.sampled,
                    )
                    return server.write(0, replace(message, payload=request))
                return server.write(0, message)

            _, core = yield from make_client_core(
                entity.protocol,
                on_from_client,
                ClientOptions(supports_ack=True, generate_request_id=snowflakes.next_unsafe),
            )
            cores.append(core)
            client = entity()
            client._rpc_methods = core.methods(entity.protocol)
            return client

        clients = yield from ResourceMap.make(lookup)
        return clients.get

    return make