GitHub

envelope

API reference for envelope.

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

AttributeTypeDescription
HeadersSchemaS.Bottom[Headers, Mapping[str, str]]

Headers as a record of strings.

AddressSchemaS.Bottom[EntityAddress, Mapping[str, object]]

An entity address with Effect's keys.

OpaqueHoleS.Bottom[Any]

A value the protocol's own codec already encoded: JSON under the text serializations, bytes under SchemaBinary (Effect's OpaqueHole).

PartialRequestSchemaS.Bottom[PartialRequest, Mapping[str, object]]
AckChunkSchemaS.Bottom[AckChunk, Mapping[str, object]]
InterruptSchemaS.Bottom[Interrupt, Mapping[str, object]]
PartialSchemaS.Bottom[Partial, Mapping[str, object]]

A partial envelope (Effect's Envelope.Partial): ids are bigints on its encoded side, so SchemaBinary writes them as Effect does.

PartialJsonS.Codec[Partial, object]

A partial envelope as Effect's JSON: ids as strings.

Types

TypeDefinitionDescription
PartialRequesttype PartialRequest = Request[object]

A request whose payload is encoded.

Envelopetype Envelope[P] = Request[P] | AckChunk | Interrupt
Partialtype Partial = PartialRequest | AckChunk | Interrupt
Encodedtype Encoded = PartialRequestEncoded | AckChunkEncoded | InterruptEncoded

Classes

Functions

is_envelope

is_envelope(u) -> TypeIs[Envelope[Any]]
ParameterTypeDescription
uobject

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.

ParameterTypeDescription
request_idSnowflake
addressEntityAddress
tagstr
payloadP
headersHeaders = EMPTY
trace_idstr | None = None
span_idstr | None = None
sampledbool | 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 | None

The storage key of a request whose payload is a PrimaryKey.

ParameterTypeDescription
envelopeEnvelope[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.

ParameterTypeDescription
addressEntityAddress
tagstr
idstr

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) -> Encoded

envelope as Effect's JSON; raises SchemaError for a payload that is not.

ParameterTypeDescription
envelopePartial

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) -> Partial

A partial envelope from Effect's JSON; raises SchemaError.

ParameterTypeDescription
encodedobject

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
ParameterTypeDescription
addressEntityAddress

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,
    }