GitHub

API reference for message.

The messages between RPC clients and servers (Effect's RpcMessage).

The decoded messages (Request, Ack, Interrupt, Eof from a client; ResponseChunk, ResponseExit, ResponseDefect, ClientEnd from a server) are what the serialization-free client and server exchange. The encoded ones are the JSON shapes a protocol carries, TypedDicts with Effect's wire keys (requestId, isNotification), so a pyfect peer and an Effect peer understand each other.

Values

AttributeTypeDescription
EOFEof
PINGPing = {'_tag': 'Ping'}
PONGPong = {'_tag': 'Pong'}
EOF_ENCODEDEofEncoded = {'_tag': 'Eof'}
EncodedSchemaS.Codec[Any, Any]

Types

TypeDefinitionDescription
RequestIdtype RequestId = str | int

A request's id, unique per client (Effect's branded RequestId).

FromClienttype FromClient = Request | Ack | Interrupt | Eof
FromServertype FromServer = ResponseChunk | ResponseExit | ResponseDefect | ClientEnd
EncodedHeaderstype EncodedHeaders = Sequence[tuple[str, str]] | Sequence[Sequence[str]]
FromClientEncodedtype FromClientEncoded = RequestEncoded | AckEncoded | InterruptEncoded | Ping | EofEncoded
FromServerEncodedtype FromServerEncoded = ResponseChunkEncoded | ResponseExitEncoded | ResponseDefectEncoded | Pong | ClientProtocolError | RequestEncoded
ServerMessagetype ServerMessage = ResponseChunkEncoded | ResponseExitEncoded | ResponseDefectEncoded | Pong

A message a client reads from a server, checked by decode_from_server.

Classes

Functions

is_request_id

is_request_id(value) -> TypeIs[RequestId]

Whether value is a RequestId (a string or an int, not a bool).

ParameterTypeDescription
valueobject

Returns TypeIs[RequestId]

def is_request_id(value: object) -> TypeIs[RequestId]:
    """Whether ``value`` is a ``RequestId`` (a string or an int, not a bool)."""
    return isinstance(value, str) or (isinstance(value, int) and not isinstance(value, bool))

decode_control

decode_control(message) -> Eof | Ack | Interrupt | None

A client's control message (Eof, Ack, Interrupt), or None for another tag. An Ack or Interrupt without a valid requestId raises MalformedMessage. Every server reads them through this.

ParameterTypeDescription
messageMapping[str, object]

Returns Eof | Ack | Interrupt | None

def decode_control(message: Mapping[str, object]) -> Eof | Ack | Interrupt | None:
    """A client's control message (``Eof``, ``Ack``, ``Interrupt``), or
    ``None`` for another tag. An ``Ack`` or ``Interrupt`` without a valid
    ``requestId`` raises ``MalformedMessage``. Every server reads them
    through this."""
    match message:
        case {"_tag": "Eof"}:
            return EOF
        case {"_tag": "Ack", "requestId": request_id} if is_request_id(request_id):
            return Ack(request_id)
        case {"_tag": "Interrupt", "requestId": request_id} if is_request_id(request_id):
            return Interrupt(request_id)
        case {"_tag": "Ack" | "Interrupt" as tag}:
            raise MalformedMessage(f"a client's {tag} message has no valid requestId")
        case _:
            return None

decode_from_server

decode_from_server(messages) -> list[ServerMessage]

The messages a client reads among the parsed messages of a server, each with its keys and a valid requestId. A tag a client does not read is left out (Effect's clients ignore it); anything else raises MalformedMessage. Every client protocol reads through this.

ParameterTypeDescription
messagesIterable[object]

Returns list[ServerMessage]

def decode_from_server(messages: Iterable[object]) -> list[ServerMessage]:
    """The messages a client reads among the parsed ``messages`` of a
    server, each with its keys and a valid ``requestId``. A tag a client
    does not read is left out (Effect's clients ignore it); anything else
    raises ``MalformedMessage``. Every client protocol reads through this."""
    decoded: list[ServerMessage] = []
    for message in messages:
        if not isinstance(message, Mapping):
            raise MalformedMessage(f"a server message is an object, not {type(message).__name__}")
        fields = cast("Mapping[object, object]", message)
        tag = fields.get("_tag")
        if not isinstance(tag, str) or tag in _NEVER_SENT:
            raise MalformedMessage(f"a server does not send the tag {tag!r:.40}")
        required = _READ.get(tag)
        if required is None:
            continue
        missing = [key for key in required if key not in fields]
        if missing:
            raise MalformedMessage(f"a server's {tag} message has no {', '.join(missing)}")
        if "requestId" in required and not is_request_id(fields["requestId"]):
            raise MalformedMessage(f"a server's {tag} message has an invalid requestId")
        decoded.append(cast("ServerMessage", message))
    return decoded

response_defect_encoded

response_defect_encoded(defect) -> ResponseDefectEncoded
ParameterTypeDescription
defectobject

Returns ResponseDefectEncoded

def response_defect_encoded(defect: object) -> ResponseDefectEncoded:
    return {"_tag": "Defect", "defect": defect}

response_exit_die_encoded

response_exit_die_encoded(request_id, defect) -> ResponseExitEncoded
ParameterTypeDescription
request_idRequestId
defectobject

Returns ResponseExitEncoded

def response_exit_die_encoded(request_id: RequestId, defect: object) -> ResponseExitEncoded:
    return {
        "_tag": "Exit",
        "requestId": request_id,
        "exit": {"_tag": "Failure", "cause": [{"_tag": "Die", "defect": defect}]},
    }

is_terminal_response

is_terminal_response(response) -> bool

Whether response ends a request (an exit) or every request of the client (a defect or a protocol error).

ParameterTypeDescription
responseFromServerEncoded

Returns bool

def is_terminal_response(response: FromServerEncoded) -> bool:
    """Whether ``response`` ends a request (an exit) or every request of the
    client (a defect or a protocol error)."""
    return response["_tag"] in ("Exit", "Defect", "ClientProtocolError")