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#
| Attribute | Type | Description |
|---|---|---|
EOF | Eof | |
PING | Ping = {'_tag': 'Ping'} | |
PONG | Pong = {'_tag': 'Pong'} | |
EOF_ENCODED | EofEncoded = {'_tag': 'Eof'} | |
EncodedSchema | S.Codec[Any, Any] |
Types#
| Type | Definition | Description |
|---|---|---|
RequestId | type RequestId = str | int | A request's id, unique per client (Effect's branded |
FromClient | type FromClient = Request | Ack | Interrupt | Eof | |
FromServer | type FromServer = ResponseChunk | ResponseExit | ResponseDefect | ClientEnd | |
EncodedHeaders | type EncodedHeaders = Sequence[tuple[str, str]] | Sequence[Sequence[str]] | |
FromClientEncoded | type FromClientEncoded = RequestEncoded | AckEncoded | InterruptEncoded | Ping | EofEncoded | |
FromServerEncoded | type FromServerEncoded = ResponseChunkEncoded | ResponseExitEncoded | ResponseDefectEncoded | Pong | ClientProtocolError | RequestEncoded | |
ServerMessage | type ServerMessage = ResponseChunkEncoded | ResponseExitEncoded | ResponseDefectEncoded | Pong | A message a client reads from a server, checked by |
Classes#
Functions#
is_request_id#
is_request_id(value) -> TypeIs[RequestId]Whether value is a RequestId (a string or an int, not a bool).
| Parameter | Type | Description |
|---|---|---|
value | object |
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 | NoneA 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.
| Parameter | Type | Description |
|---|---|---|
message | Mapping[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 Nonedecode_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.
| Parameter | Type | Description |
|---|---|---|
messages | Iterable[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 decodedresponse_defect_encoded#
response_defect_encoded(defect) -> ResponseDefectEncoded| Parameter | Type | Description |
|---|---|---|
defect | object |
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| Parameter | Type | Description |
|---|---|---|
request_id | RequestId | |
defect | object |
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) -> boolWhether response ends a request (an exit) or every request of the
client (a defect or a protocol error).
| Parameter | Type | Description |
|---|---|---|
response | FromServerEncoded |
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")