"""Secure Scuttlebutt (SSB) MuxRPC Protocol Framing and Method Dispatcher (SSB-MuxRPC).
Standard library only. Manages:
- 9-byte packet framing (flags, body length, request ID) for SSB-MuxRPC.
- Supported payload encodings: binary (00), UTF-8 text (01), JSON (10).
- Procedure calls: async, sync, source, duplex, sink.
- Feed history streaming (createHistoryStream) with stream termination.
- Error propagation and stream completion flags.
"""
from __future__ import annotations
import json
import struct
from typing import Any, Callable, Mapping, Optional, Sequence, Union
from fleetmesh_core.conformance.errors import FleetmeshError
__all__ = [
'MuxRPCError',
'PS_TYPE_BUFFER',
'PS_TYPE_TEXT',
'PS_TYPE_JSON',
'FLAG_STREAM',
'FLAG_END_ERR',
'MuxRPCMessage',
'build_request',
'build_response',
'build_error_response',
'build_stream_end',
'MuxRPCRouter',
]
PS_TYPE_BUFFER = 0
PS_TYPE_TEXT = 1
PS_TYPE_JSON = 2
FLAG_STREAM = 0x08
FLAG_END_ERR = 0x04
[docs]class MuxRPCError(FleetmeshError):
"""Base error for MuxRPC operations."""
MAX_MUXRPC_BODY_LEN = 16 * 1024 * 1024 # 16 MB
[docs]class MuxRPCMessage:
"""A single MuxRPC packet with a 9-byte binary header and body."""
[docs] def __init__(
self,
req: int,
body: Union[bytes, str, Mapping[str, Any], list[Any], bool, int, float, None],
body_type: int = PS_TYPE_JSON,
is_stream: bool = False,
is_end_err: bool = False,
):
self.req = req
self.body = body
self.body_type = body_type
self.is_stream = is_stream
self.is_end_err = is_end_err
@property
def flags(self) -> int:
f = self.body_type & 0x03
if self.is_stream:
f |= FLAG_STREAM
if self.is_end_err:
f |= FLAG_END_ERR
return f
@property
def raw_body_bytes(self) -> bytes:
if self.body_type == PS_TYPE_BUFFER:
return bytes(self.body) if isinstance(self.body, (bytes, bytearray)) else b""
elif self.body_type == PS_TYPE_TEXT:
return str(self.body).encode('utf-8')
elif self.body_type == PS_TYPE_JSON:
return json.dumps(self.body, separators=(',', ':')).encode('utf-8')
return b""
[docs] def encode(self) -> bytes:
"""Encode to 9-byte header followed by body bytes."""
body_bytes = self.raw_body_bytes
header = struct.pack('>BIi', self.flags, len(body_bytes), self.req)
return header + body_bytes
[docs] @classmethod
def from_bytes(cls, data: bytes) -> tuple[Optional[MuxRPCMessage], int]:
"""Decode message from wire bytes.
Returns (message, bytes_consumed) if a full message is available.
Returns (None, 0) if more bytes are needed.
"""
if len(data) < 9:
return None, 0
flags, length, req = struct.unpack('>BIi', data[:9])
if length > MAX_MUXRPC_BODY_LEN:
raise MuxRPCError(f"MuxRPC packet length exceeds maximum ({length} > {MAX_MUXRPC_BODY_LEN})")
total_len = 9 + length
if len(data) < total_len:
return None, 0
body_raw = data[9:total_len]
body_type = flags & 0x03
is_stream = bool(flags & FLAG_STREAM)
is_end_err = bool(flags & FLAG_END_ERR)
body: Any
if body_type == PS_TYPE_BUFFER:
body = body_raw
elif body_type == PS_TYPE_TEXT:
body = body_raw.decode('utf-8', errors='replace')
elif body_type == PS_TYPE_JSON:
if not body_raw:
body = None
else:
try:
body = json.loads(body_raw.decode('utf-8'))
except Exception as e:
raise MuxRPCError(f"invalid JSON payload in MuxRPC packet: {e}") from e
else:
body = body_raw
msg = cls(
req=req,
body=body,
body_type=body_type,
is_stream=is_stream,
is_end_err=is_end_err,
)
return msg, total_len
def __repr__(self) -> str:
return (
f"<MuxRPCMessage req={self.req} type={self.body_type} "
f"stream={self.is_stream} end_err={self.is_end_err} body={self.body!r}>"
)
[docs]def build_request(
req_id: int,
name: Sequence[str],
args: Sequence[Any],
rpc_type: str = "async",
) -> MuxRPCMessage:
"""Build an outbound MuxRPC request message."""
body = {
"name": list(name),
"args": list(args),
"type": rpc_type,
}
is_stream = rpc_type in ("source", "duplex", "sink")
return MuxRPCMessage(
req=req_id,
body=body,
body_type=PS_TYPE_JSON,
is_stream=is_stream,
is_end_err=False,
)
[docs]def build_response(
req_id: int,
payload: Any,
is_stream: bool = False,
is_end_err: bool = False,
body_type: int = PS_TYPE_JSON,
) -> MuxRPCMessage:
"""Build a standard response message (response req is negative)."""
return MuxRPCMessage(
req=-abs(req_id),
body=payload,
body_type=body_type,
is_stream=is_stream,
is_end_err=is_end_err,
)
[docs]def build_error_response(req_id: int, message: str, is_stream: bool = False) -> MuxRPCMessage:
"""Build an error response packet with end_err=True."""
return MuxRPCMessage(
req=-abs(req_id),
body={"name": "Error", "message": message},
body_type=PS_TYPE_JSON,
is_stream=is_stream,
is_end_err=True,
)
[docs]def build_stream_end(req_id: int) -> MuxRPCMessage:
"""Build an end-of-stream indicator (JSON true with stream and end_err set)."""
return MuxRPCMessage(
req=-abs(req_id),
body=True,
body_type=PS_TYPE_JSON,
is_stream=True,
is_end_err=True,
)
[docs]class MuxRPCRouter:
"""Dispatches MuxRPC procedure calls to registered handlers."""
[docs] def __init__(self, local_feed_id: str = "@AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=.ed25519"):
self.local_feed_id = local_feed_id
self._handlers: dict[str, Callable[[int, list[Any], str], list[MuxRPCMessage]]] = {}
self._register_default_handlers()
[docs] def register(
self,
name: str,
handler: Callable[[int, list[Any], str], list[MuxRPCMessage]],
) -> None:
"""Register a procedure handler."""
self._handlers[name] = handler
def _register_default_handlers(self) -> None:
# whoami
def _handle_whoami(req_id: int, args: list[Any], rpc_type: str) -> list[MuxRPCMessage]:
return [build_response(req_id, {"id": self.local_feed_id})]
self.register("whoami", _handle_whoami)
# blobs.has
def _handle_blobs_has(req_id: int, args: list[Any], rpc_type: str) -> list[MuxRPCMessage]:
# Expects list of blob hashes, returns list of booleans
return [build_response(req_id, [False] * len(args))]
self.register("blobs.has", _handle_blobs_has)
[docs] def handle_request(self, msg: MuxRPCMessage) -> list[MuxRPCMessage]:
"""Dispatch an incoming MuxRPC request and return zero or more response messages."""
if not isinstance(msg.body, dict):
return [build_error_response(msg.req, "Malformed RPC request: expected JSON object")]
name_list = msg.body.get("name")
if not name_list or not isinstance(name_list, list):
return [build_error_response(msg.req, "Malformed RPC request: missing or invalid 'name'")]
method_name = ".".join(name_list)
args = msg.body.get("args", [])
rpc_type = msg.body.get("type", "async")
handler = self._handlers.get(method_name)
if not handler:
return [build_error_response(msg.req, f"Method '{method_name}' not implemented")]
try:
return handler(msg.req, args, rpc_type)
except Exception as e:
return [build_error_response(msg.req, str(e))]