What is sent to an entity (Effect's Envelope): a Request of one
of its RPCs, an AckChunk acknowledging a streamed reply, or an
Interrupt cancelling a request.
A request whose payload is already encoded is a partial request; it
crosses runners and is written to message storage. PartialSchema
reads and writes partial envelopes as Effect's JSON (camelCase keys,
snowflakes as decimal strings), the Encoded shapes below.
Values#
| Attribute | Type | Description |
|---|---|---|
HeadersSchema | S.Bottom[Headers, Mapping[str, str]] | Headers as a record of strings. |
AddressSchema | S.Bottom[EntityAddress, Mapping[str, object]] | An entity address with Effect's keys. |
OpaqueHole | S.Bottom[Any] | A value the protocol's own codec already encoded: JSON under the text
serializations, bytes under |
PartialRequestSchema | S.Bottom[PartialRequest, Mapping[str, object]] | |
AckChunkSchema | S.Bottom[AckChunk, Mapping[str, object]] | |
InterruptSchema | S.Bottom[Interrupt, Mapping[str, object]] | |
PartialSchema | S.Bottom[Partial, Mapping[str, object]] | A partial envelope (Effect's |
PartialJson | S.Codec[Partial, object] | A partial envelope as Effect's JSON: ids as strings. |
Types#
| Type | Definition | Description |
|---|---|---|
PartialRequest | type PartialRequest = Request[object] | A request whose payload is encoded. |
Envelope | type Envelope[P] = Request[P] | AckChunk | Interrupt | |
Partial | type Partial = PartialRequest | AckChunk | Interrupt | |
Encoded | type Encoded = PartialRequestEncoded | AckChunkEncoded | InterruptEncoded |
Classes#
Functions#
is_envelope#
is_envelope(u) -> TypeIs[Envelope[Any]]| Parameter | Type | Description |
|---|---|---|
u | object |
Returns TypeIs[Envelope[Any]]
def is_envelope(u: object) -> TypeIs[Envelope[Any]]:
return isinstance(u, (Request, AckChunk, Interrupt))make_request#
make_request[P](*, request_id, address, tag, payload, headers=EMPTY, trace_id=None, span_id=None, sampled=None) -> Request[P]A request; the span ids are kept only with a trace_id.
| Parameter | Type | Description |
|---|---|---|
request_id | Snowflake | |
address | EntityAddress | |
tag | str | |
payload | P | |
headers | Headers = EMPTY | |
trace_id | str | None = None | |
span_id | str | None = None | |
sampled | bool | None = None |
Returns Request[P]
def make_request[P](
*,
request_id: Snowflake,
address: EntityAddress,
tag: str,
payload: P,
headers: Headers = EMPTY,
trace_id: str | None = None,
span_id: str | None = None,
sampled: bool | None = None,
) -> Request[P]:
"""A request; the span ids are kept only with a ``trace_id``."""
if trace_id is None:
return Request(
request_id=request_id, address=address, tag=tag, payload=payload, headers=headers
)
return Request(
request_id=request_id,
address=address,
tag=tag,
payload=payload,
headers=headers,
trace_id=trace_id,
span_id=span_id,
sampled=sampled,
)primary_key#
primary_key(envelope) -> str | NoneThe storage key of a request whose payload is a PrimaryKey.
| Parameter | Type | Description |
|---|---|---|
envelope | Envelope[Any] |
Returns str | None
def primary_key(envelope: Envelope[Any]) -> str | None:
"""The storage key of a request whose payload is a ``PrimaryKey``."""
if not isinstance(envelope, Request) or not primary_key_.is_primary_key(envelope.payload):
return None
return primary_key_by_address(
address=envelope.address, tag=envelope.tag, id=primary_key_.value(envelope.payload)
)primary_key_by_address#
primary_key_by_address(*, address, tag, id) -> str<entity type>/<entity id>/<tag>/<id>; storages with fixed-width
key columns hash it at their own boundary.
| Parameter | Type | Description |
|---|---|---|
address | EntityAddress | |
tag | str | |
id | str |
Returns str
def primary_key_by_address(*, address: EntityAddress, tag: str, id: str) -> str:
"""``<entity type>/<entity id>/<tag>/<id>``; storages with fixed-width
key columns hash it at their own boundary."""
return f"{address.entity_type}/{address.entity_id}/{tag}/{id}"encode#
encode(envelope) -> Encodedenvelope as Effect's JSON; raises SchemaError for a payload
that is not.
| Parameter | Type | Description |
|---|---|---|
envelope | Partial |
Returns Encoded
def encode(envelope: Partial) -> Encoded:
"""``envelope`` as Effect's JSON; raises ``SchemaError`` for a payload
that is not."""
return _encode_partial(envelope) # pyright: ignore[reportReturnType]decode#
decode(encoded) -> PartialA partial envelope from Effect's JSON; raises SchemaError.
| Parameter | Type | Description |
|---|---|---|
encoded | object |
Returns Partial
def decode(encoded: object) -> Partial:
"""A partial envelope from Effect's JSON; raises ``SchemaError``."""
return _decode_partial(encoded)encode_address#
encode_address(address) -> AddressEncoded| Parameter | Type | Description |
|---|---|---|
address | EntityAddress |
Returns AddressEncoded
def encode_address(address: EntityAddress) -> AddressEncoded:
return {
"shardId": {"group": address.shard_id.group, "id": address.shard_id.id},
"entityType": address.entity_type,
"entityId": address.entity_id,
}