Source code for fleetmesh_node.protocols.ssb.muxrpc

"""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))]