RPCs and HTTP endpoints that reach an entity from outside the cluster
(Effect's EntityProxy): to_rpc_group derives an RPC group whose
requests carry the entity id and the entity RPC's payload;
to_http_api_group derives an HTTP API group with the entity id in the
path.
That group is built at run time, so a client reads its operations by name
(.method("<Tag>"), typed Any). To type a client, declare the operations
in your own group, one line per entity RPC (Effect types its group by the
entity's RPCs, which Python cannot)::
class Counters(HttpApiGroup, identifier="counters"):
increment, increment_discard = entity_proxy.http_endpoints(Counter.increment)entity_proxy_server.layer_http_api serves either group.
Values#
| Attribute | Type | Description |
|---|---|---|
CLIENT_ERRORS | tuple[Any, ...] | The errors a discarding call can fail with. |
REQUEST_ERRORS | tuple[Any, ...] | The cluster errors a call can fail with, besides the RPC's own. |
Types#
| Type | Definition | Description |
|---|---|---|
ClientError | type ClientError = MailboxFull | AlreadyProcessingMessage | PersistenceError | What |
RequestError | type RequestError = ClientError | EntityNotAssignedToRunner | What |
Classes#
Functions#
proxy_rpcs#
proxy_rpcs(entity) -> list[AnyRpc]For each entity RPC Tag: "<type>.<Tag>", answered with the
RPC's success, and "<type>.<Tag>Discard", answered once the message
is sent.
| Parameter | Type | Description |
|---|---|---|
entity | type[Entity] |
Returns list[AnyRpc]
def proxy_rpcs(entity: type[Entity]) -> list[AnyRpc]:
"""For each entity RPC ``Tag``: ``"<type>.<Tag>"``, answered with the
RPC's success, and ``"<type>.<Tag>Discard"``, answered once the message
is sent."""
rpcs: list[AnyRpc] = []
for parent in entity.rpcs.values():
payload = _payload(parent)
success: Any = parent.success_schema
error: Any = S.Union(parent.error_schema, *REQUEST_ERRORS)
make: Any = make_rpc
made: AnyRpc = make(
f"{entity.type}.{parent.tag}", payload=payload, success=success, error=error
)
rpc = made.annotate_merge(parent.annotations)
discard: AnyRpc = make_rpc(
f"{entity.type}.{parent.tag}Discard",
payload=payload,
error=S.Union(*CLIENT_ERRORS),
).annotate_merge(parent.annotations)
rpcs.extend((rpc, discard))
return rpcsto_rpc_group#
to_rpc_group(entity) -> type[RpcGroup]The RPC group of proxy_rpcs(entity) (Effect's
EntityProxy.toRpcGroup); its RPCs are looked up by tag in
rpcs.
| Parameter | Type | Description |
|---|---|---|
entity | type[Entity] |
Returns type[RpcGroup]
def to_rpc_group(entity: type[Entity]) -> type[RpcGroup]:
"""The RPC group of ``proxy_rpcs(entity)`` (Effect's
``EntityProxy.toRpcGroup``); its RPCs are looked up by tag in
``rpcs``."""
members = {f"rpc_{index}": rpc for index, rpc in enumerate(proxy_rpcs(entity))}
return type(f"{entity.__name__}Proxy", (RpcGroup,), members)http_endpoints#
http_endpoints[P, A, E](rpc) -> EntityEndpoints[P, A, E]POST /<tag lowercased>/:entityId (Tag), answered with the RPC's
success, and POST /<tag lowercased>/:entityId/discard (TagDiscard),
answered once the message is sent, typed, to declare in an
HttpApiGroup.
| Parameter | Type | Description |
|---|---|---|
rpc | Rpc[P, A, E, Any, Any] |
Returns EntityEndpoints[P, A, E]
def http_endpoints[P, A, E](rpc: Rpc[P, A, E, Any, Any]) -> EntityEndpoints[P, A, E]:
"""``POST /<tag lowercased>/:entityId`` (``Tag``), answered with the RPC's
success, and ``POST /<tag lowercased>/:entityId/discard`` (``TagDiscard``),
answered once the message is sent, typed, to declare in an
``HttpApiGroup``."""
path = f"/{rpc.tag.lower()}/:entityId"
post: Any = http_endpoint.post
call: Any = post(
rpc.tag,
path,
params=_ENTITY_ID_PARAMS,
payload=rpc.payload_schema,
success=rpc.success_schema,
error=(rpc.error_schema, *REQUEST_ERRORS),
)
discard: Any = post(
f"{rpc.tag}Discard",
f"{path}/discard",
params=_ENTITY_ID_PARAMS,
payload=rpc.payload_schema,
error=CLIENT_ERRORS,
)
return EntityEndpoints(
call.annotate_merge(rpc.annotations), discard.annotate_merge(rpc.annotations)
)to_http_api_group#
to_http_api_group(name, entity) -> type[HttpApiGroup[Any]]The HTTP API group name with, for each entity RPC Tag, a
POST /<tag lowercased>/:entityId endpoint Tag answered with the
RPC's success, and POST /<tag lowercased>/:entityId/discard
TagDiscard answered once the message is sent (Effect's
EntityProxy.toHttpApiGroup).
| Parameter | Type | Description |
|---|---|---|
name | str | |
entity | type[Entity] |
Returns type[HttpApiGroup[Any]]
def to_http_api_group(name: str, entity: type[Entity]) -> type[HttpApiGroup[Any]]:
"""The HTTP API group ``name`` with, for each entity RPC ``Tag``, a
``POST /<tag lowercased>/:entityId`` endpoint ``Tag`` answered with the
RPC's success, and ``POST /<tag lowercased>/:entityId/discard``
``TagDiscard`` answered once the message is sent (Effect's
``EntityProxy.toHttpApiGroup``)."""
group: type[HttpApiGroup[Any]] = HttpApiGroup.make(name)
for parent in entity.rpcs.values():
rpc: Any = parent
group = group.add(*http_endpoints(rpc))
return group