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#
| Attribute | Type | Description |
|---|---|---|
KeepAliveRpc | Rpc[None, None, Never, Never, Never, Literal['Cluster/Entity/keepAlive']] | The persisted, uninterruptible RPC an entity sends itself to stay alive. |
Types#
| Type | Definition | Description |
|---|---|---|
ClusterClientError | type ClusterClientError = MailboxFull | AlreadyProcessingMessage | PersistenceError | EntityNotAssignedToRunner | What an entity client's calls fail with besides the RPC's own errors. |
Concurrency | type Concurrency = int | Literal['unbounded'] | |
EntityHandlerFn | type EntityHandlerFn = Callable[[Request[Any]], Any] | |
Behaviour | type 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.
| Parameter | Type | Description |
|---|---|---|
enabled | bool |
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.
| Parameter | Type | Description |
|---|---|---|
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