GitHub

API reference for message.

Envelopes on their way (Effect's Message).

An Outgoing message is what a sender holds: an OutgoingRequest (its decoded envelope, the services its schemas need, and how to answer the caller) or an OutgoingEnvelope. An Incoming message is what an entity receives: an IncomingRequest whose payload is still encoded (from another runner or from storage), an IncomingRequestLocal decoded on this runner, or an IncomingEnvelope.

Re-exports

Types

TypeDefinitionDescription
Incomingtype Incoming = IncomingRequest | IncomingEnvelope
IncomingLocaltype IncomingLocal = IncomingRequestLocal | IncomingEnvelope
Outgoingtype Outgoing = OutgoingRequest | OutgoingEnvelope

Classes

Functions

codec_for_json

codec_for_json(schema) -> S.Codec[Any, Any, Any, Any]

Effect's Schema.toCodecJson as a CodecFor: storage encodes with it.

ParameterTypeDescription
schemaS.Top

Returns S.Codec[Any, Any, Any, Any]

def codec_for_json(schema: S.Top) -> S.Codec[Any, Any, Any, Any]:
    """Effect's ``Schema.toCodecJson`` as a ``CodecFor``: storage encodes
    with it."""
    return S.to_codec_json(schema)

dynamic_annotations

dynamic_annotations(rpc, request) -> Context[Any]

rpc's annotations for request (ClusterSchema.Dynamic).

ParameterTypeDescription
rpcAnyRpc
requestRequest[Any]

Returns Context[Any]

def dynamic_annotations(rpc: AnyRpc, request: Request[Any]) -> Context[Any]:
    """``rpc``'s annotations for ``request`` (``ClusterSchema.Dynamic``)."""
    return rpc.annotations.get(Dynamic)(rpc.annotations, request)

incoming_local_from_outgoing

incoming_local_from_outgoing(message) -> IncomingLocal

The message as its entity on this runner receives it.

ParameterTypeDescription
messageOutgoing

Returns IncomingLocal

def incoming_local_from_outgoing(message: Outgoing) -> IncomingLocal:
    """The message as its entity on this runner receives it."""
    if isinstance(message, OutgoingEnvelope):
        return IncomingEnvelope(envelope=message.envelope)
    return IncomingRequestLocal(
        envelope=message.envelope,
        last_sent_reply=None,
        respond=message.respond,
        annotations=dynamic_annotations(message.rpc, message.envelope),
    )

serialize_request

serialize_request(message, codec_for) -> Effect[PartialRequest, MalformedMessage]

The request with its payload encoded by codec_for.

ParameterTypeDescription
messageOutgoingRequest
codec_forCodecFor

Returns Effect[PartialRequest, MalformedMessage]

def serialize_request(
    message: OutgoingRequest, codec_for: CodecFor
) -> Effect[PartialRequest, MalformedMessage]:
    """The request with its payload encoded by ``codec_for``."""
    request = message.envelope
    encode = S.encode_unknown_effect(codec_for(message.rpc.payload_schema))
    return MalformedMessage.refail(
        encode(request.payload).pipe(provide_context(message.context))
    ).map(lambda payload: _with_payload(request, payload))

serialize

serialize(message, codec_for) -> Effect[Partial, MalformedMessage]

The partial envelope of message (a request's encoding is cached per codec_for).

ParameterTypeDescription
messageOutgoing
codec_forCodecFor

Returns Effect[Partial, MalformedMessage]

def serialize(message: Outgoing, codec_for: CodecFor) -> Effect[Partial, MalformedMessage]:
    """The partial envelope of ``message`` (a request's encoding is cached
    per ``codec_for``)."""
    if isinstance(message, OutgoingEnvelope):
        return succeed(message.envelope)

    def run() -> Effect[Partial, MalformedMessage]:
        cached = message.encoded_cache
        if cached is not None and cached.codec_for is codec_for:
            return succeed(cached.envelope)

        def remember(envelope: PartialRequest) -> PartialRequest:
            message.encoded_cache = _EncodedCache(codec_for, envelope)
            return envelope

        return serialize_request(message, codec_for).map(remember)

    return suspend(run)

serialize_envelope

serialize_envelope(message) -> Effect[Encoded, MalformedMessage]

message as Effect's JSON.

ParameterTypeDescription
messageOutgoing

Returns Effect[Encoded, MalformedMessage]

def serialize_envelope(message: Outgoing) -> Effect[Encoded, MalformedMessage]:
    """``message`` as Effect's JSON."""
    return serialize(message, codec_for_json).flat_map(
        lambda partial: MalformedMessage.refail(S.encode_effect(envelope_.PartialJson)(partial))
    )  # pyright: ignore[reportReturnType]

deserialize_local

deserialize_local(message, encoded, codec_for) -> Effect[IncomingLocal, MalformedMessage]

encoded decoded again with message's schemas, as an entity on this runner receives it (what a remote runner would see).

ParameterTypeDescription
messageOutgoing
encodedPartial
codec_forCodecFor

Returns Effect[IncomingLocal, MalformedMessage]

def deserialize_local(
    message: Outgoing, encoded: Partial, codec_for: CodecFor
) -> Effect[IncomingLocal, MalformedMessage]:
    """``encoded`` decoded again with ``message``'s schemas, as an entity on
    this runner receives it (what a remote runner would see)."""
    if not isinstance(encoded, Request):
        return succeed(IncomingEnvelope(envelope=encoded))
    if not isinstance(message, OutgoingRequest):
        return fail(
            MalformedMessage(
                cause=ValueError("Can only deserialize a Request with an OutgoingRequest message")
            )
        )
    rpc = message.rpc
    decode = S.decode_unknown_effect(codec_for(rpc.payload_schema))

    def received(payload: object) -> IncomingLocal:
        request = _with_payload(encoded, payload)
        return IncomingRequestLocal(
            envelope=request,
            last_sent_reply=None,
            respond=message.respond,
            annotations=dynamic_annotations(rpc, request),
        )

    return MalformedMessage.refail(
        decode(encoded.payload).pipe(provide_context(message.context))
    ).map(received)