fleetmesh-node 0.2.0__py3-none-any.whl

node/protocols/ssb/muxrpc.py

@@ -0,0 +1,256 @@
+"""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
+
+
+class MuxRPCError(FleetmeshError):
+    """Base error for MuxRPC operations."""
+
+
+MAX_MUXRPC_BODY_LEN = 16 * 1024 * 1024  # 16 MB
+
+
+class MuxRPCMessage:
+    """A single MuxRPC packet with a 9-byte binary header and body."""
+
+    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""
+
+    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
+
+    @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}>"
+        )
+
+
+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,
+    )
+
+
+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,
+    )
+
+
+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,
+    )
+
+
+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,
+    )
+
+
+class MuxRPCRouter:
+    """Dispatches MuxRPC procedure calls to registered handlers."""
+
+    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()
+
+    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)
+
+    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))]

node/protocols/ssb/package.py

@@ -0,0 +1,267 @@
+"""fleetmesh-protocol-ssb: Secure Scuttlebutt (SSB) protocol package.
+
+Conforms to ProtocolPackage (fleetmesh_core.wire.interfaces.ProtocolPackage).
+Integrates the SSB sidecar daemon, client, MuxRPC routing, and SSBRung
+into the Fleetmesh protocol host and transport ladder.
+"""
+from __future__ import annotations
+
+from fleetmesh_core.wire import spelling  # noqa: E402
+
+import json
+import os
+from typing import Any, Mapping, Optional
+
+from fleetmesh_core.crypto.ssb import (
+    SSB_MAINNET_NETWORK_KEY,
+    SSBCryptoError,
+    format_ssb_feed_id,
+    parse_ssb_feed_id,
+)
+from fleetmesh_core.wire.interfaces import (
+    ProtocolHealth,
+    ProtocolHostRouter,
+    ProtocolIdentityAdapter,
+)
+from node.protocols.base import Ed25519IdentityAdapter
+from node.transport.ssb_rung import SSBRung
+from sidecar.fleetmesh_ssb import SSBSidecarClient, SSBSidecarDaemon
+
+__all__ = [
+    'SSBIdentityAdapter',
+    'SSBProtocolPackage',
+]
+
+
+class SSBIdentityAdapter(Ed25519IdentityAdapter):
+    """Identity and assertion adapter for Secure Scuttlebutt (@pubkey.ed25519)."""
+
+    def __init__(self, private_key: Any = None, feed_id: Optional[str] = None):
+        super().__init__(private_key=private_key)
+        self._feed_id = feed_id
+        if self.private_key is not None and not self._feed_id and hasattr(self.private_key, 'public_key'):
+            pk_raw = self.private_key.public_key().public_bytes_raw()
+            self._feed_id = format_ssb_feed_id(pk_raw)
+
+    def resolve_id(self, uri: str) -> Optional[str]:
+        """Resolves SSB feed ID from raw feed ID or ssb: URI."""
+        clean = uri.strip()
+        if clean.startswith("ssb:"):
+            clean = clean[4:]
+        if clean.startswith("@") and clean.endswith(".ed25519"):
+            try:
+                parse_ssb_feed_id(clean)
+                return clean
+            except (SSBCryptoError, ValueError):
+                return None
+        return None
+
+    def verify_assertion(self, payload: bytes, signature: bytes, pubkey: str) -> bool:
+        try:
+            if pubkey.startswith("@") and pubkey.endswith(".ed25519"):
+                pk_bytes = parse_ssb_feed_id(pubkey)
+            elif spelling.is_hex(pubkey, 64, upper=True):
+                pk_bytes = bytes.fromhex(pubkey)
+            else:
+                pk_bytes = pubkey.encode('utf-8')
+        except (SSBCryptoError, ValueError):
+            return False
+        return self._verify_ed25519_bytes(payload, signature, pk_bytes)
+
+
+class SSBProtocolPackage:
+    """The Secure Scuttlebutt (SSB) protocol suite for Fleetmesh."""
+
+    name: str = 'ssb'
+    version: str = '1.0.0'
+    standards: tuple[str, ...] = (
+        'ssb',
+        'SSB-SHS',
+        'SSB-BoxStream',
+        'SSB-MuxRPC',
+        'secret-handshake',
+        'boxstream',
+        'muxrpc',
+    )
+
+    def __init__(
+        self,
+        node_dir: Optional[str] = None,
+        socket_path: Optional[str] = None,
+        tcp_host: str = "127.0.0.1",
+        tcp_port: int = 8008,
+        network_key: bytes = SSB_MAINNET_NETWORK_KEY,
+        secret_key_bytes: Optional[bytes] = None,
+        sidecar_client: Optional[SSBSidecarClient] = None,
+        auto_start_sidecar: bool = False,
+        private_key: Optional[Any] = None,
+    ):
+        self.node_dir = node_dir or "/tmp/fleetmesh-ssb"
+        self.socket_path = socket_path or os.path.join(self.node_dir, "ssb.sock")
+        self.tcp_host = tcp_host
+        self.tcp_port = tcp_port
+        self.network_key = network_key
+        self.secret_key_bytes = secret_key_bytes
+        self.private_key = private_key
+        self.auto_start_sidecar = auto_start_sidecar
+
+        if self.private_key is not None and not self.secret_key_bytes:
+            try:
+                self.secret_key_bytes = self.private_key.private_bytes_raw()
+            except Exception:
+                pass
+
+        self._client = sidecar_client
+        self._daemon: Optional[SSBSidecarDaemon] = None
+        self._host: Optional[ProtocolHostRouter] = None
+        self._enabled: bool = True
+        self.config: Mapping[str, Any] = {}
+
+    def configure(self, config: Mapping[str, Any]) -> None:
+        self.config = dict(config)
+        self._enabled = self.config.get('enabled', True)
+        if 'socket_path' in self.config:
+            self.socket_path = self.config['socket_path']
+        if 'tcp_host' in self.config:
+            self.tcp_host = self.config['tcp_host']
+        if 'tcp_port' in self.config:
+            self.tcp_port = self.config['tcp_port']
+        if 'auto_start_sidecar' in self.config:
+            self.auto_start_sidecar = self.config['auto_start_sidecar']
+        if 'network_key' in self.config:
+            nk = self.config['network_key']
+            self.network_key = bytes.fromhex(nk) if isinstance(nk, str) else nk
+
+    @property
+    def client(self) -> Optional[SSBSidecarClient]:
+        if self._client is not None:
+            return self._client
+        if os.path.exists(self.socket_path):
+            self._client = SSBSidecarClient(self.socket_path)
+        return self._client
+
+    def identity_adapter(self, keystore: Any = None) -> Optional[ProtocolIdentityAdapter]:
+        priv = self.private_key
+        if priv is None and keystore is not None:
+            # Check if keystore has ed25519 key
+            priv = getattr(keystore, 'ed25519_sk', None)
+        return SSBIdentityAdapter(private_key=priv)
+
+    def mount_ingress(self, host: ProtocolHostRouter) -> None:
+        if not self._enabled:
+            return
+        self._host = host
+
+        # Register status inspection route for HTTP multiplexer
+        def _handle_ssb_status(conn: Any, req: Any = None) -> Any:
+            st = self.health()
+            payload = {
+                "healthy": st.healthy,
+                "status": st.status,
+                "connections_active": st.connections_active,
+                "messages_in": st.messages_in,
+                "messages_out": st.messages_out,
+                "errors": list(st.errors),
+                "socket_path": self.socket_path,
+                "tcp_port": self.tcp_port,
+            }
+            body = json.dumps(payload, indent=2).encode('utf-8')
+            if conn is not None and hasattr(conn, 'sendall'):
+                from node.transport import ws
+                ws.http_response(conn, "200 OK", body, "application/json")
+                return True
+            return 200, {"Content-Type": "application/json"}, body
+
+        if hasattr(host, 'mount_route'):
+            host.mount_route('/ssb/status', _handle_ssb_status, methods=('GET',), owner=self.name)
+        elif hasattr(host, 'register_route'):
+            host.register_route("GET", "/ssb/status", _handle_ssb_status, owner=self.name)
+
+    def transport_rung(self, context: Any = None) -> Optional[Any]:
+        if not self._enabled:
+            return None
+        router = getattr(context, 'router', None) or context
+        return SSBRung(
+            router=router,
+            sidecar_client=self.client,
+            socket_path=self.socket_path,
+        )
+
+    def compartments(self) -> tuple[type[Any], ...]:
+        return ()
+
+    def start(self) -> None:
+        if not self._enabled:
+            return
+        if self.auto_start_sidecar and self._daemon is None:
+            self._daemon = SSBSidecarDaemon(
+                node_dir=self.node_dir,
+                tcp_port=self.tcp_port,
+                bind_host=self.tcp_host,
+                uds_path=self.socket_path,
+                network_key=self.network_key,
+                secret_key_bytes=self.secret_key_bytes,
+            )
+            self._daemon.start()
+            self.tcp_port = self._daemon.tcp_port
+            self._client = SSBSidecarClient(self.socket_path)
+
+    def stop(self) -> None:
+        if self._client is not None:
+            self._client.close()
+            self._client = None
+        if self._daemon is not None:
+            self._daemon.stop()
+            self._daemon = None
+
+    def health(self) -> ProtocolHealth:
+        if not self._enabled:
+            return ProtocolHealth(
+                healthy=True,
+                status="disabled",
+                connections_active=0,
+                messages_in=0,
+                messages_out=0,
+                errors=(),
+            )
+
+        client = self.client
+        if client is not None and os.path.exists(self.socket_path):
+            try:
+                st = client.status()
+                if st.get('ok'):
+                    return ProtocolHealth(
+                        healthy=True,
+                        status="serving",
+                        connections_active=st.get('peers_connected', 0),
+                        messages_in=st.get('messages_count', 0),
+                        messages_out=0,
+                        errors=(),
+                    )
+            except Exception as e:
+                return ProtocolHealth(
+                    healthy=False,
+                    status="unreachable",
+                    connections_active=0,
+                    messages_in=0,
+                    messages_out=0,
+                    errors=(str(e),),
+                )
+
+        return ProtocolHealth(
+            healthy=True,
+            status="configured",
+            connections_active=0,
+            messages_in=0,
+            messages_out=0,
+            errors=(),
+        )
+
+    def descriptor_capabilities(self) -> tuple[tuple[str, str], ...]:
+        if not self._enabled:
+            return ()
+        return (
+            ('c', 'ssb'),
+            ('c', 'shs'),
+            ('c', 'muxrpc'),
+        )

node/protocols/textile/__init__.py

@@ -0,0 +1,111 @@
+"""FleetMesh Node Textile Protocol Package (`node.protocols.textile`)."""
+from __future__ import annotations
+
+# The stores and route handlers live in the fleetmesh-protocols package
+# (fleetmesh_protocols.textile); this package re-exports them so node code and
+# the protocol router keep their import paths.
+
+from fleetmesh_protocols.textile.fiber_routes import HttpResult, JSON_CT, binary_http_response, handle_fiber_http, is_fiber_route
+from fleetmesh_protocols.textile.fiber_store import (
+    FIBER_KINDS,
+    INTERACTION_KINDS,
+    MAX_FIBER_BYTES,
+    MAX_OWNER_BYTES,
+    MAX_UPLOAD_BODY_BYTES,
+    PAYLOAD_KINDS,
+    VISIBILITIES,
+    StandaloneFiberStore,
+)
+from fleetmesh_protocols.textile.hosted_relay import PROTOCOL_DIGEST, PROTOCOL_VERSION, HostedLeafRelay
+from fleetmesh_protocols.textile.leaf_relay import (
+    KIND_FABRIC,
+    KIND_FIBER,
+    KIND_QUILT,
+    KIND_STRAND,
+    NEG_BUCKETS,
+    NEG_FINGERPRINT,
+    NEG_ID_LIST,
+    NEG_INFINITY,
+    NEG_LIST_THRESHOLD,
+    NEG_SKIP,
+    NEG_VERSION,
+    WS_GUID,
+    NegBound,
+    NegentropyServer,
+    build_engine_textile_inventory,
+    canonical_bao_hex,
+    decode_neg_message,
+    decode_varint,
+    det_hex,
+    encode_neg_message,
+    encode_varint,
+    neg_fingerprint,
+    serve_relay_websocket,
+)
+from fleetmesh_protocols.textile.quilt_routes import handle_quilt_http, is_quilt_route
+from fleetmesh_protocols.textile.quilt_store import (
+    AUDIENCE_RANK,
+    AUDIENCES,
+    MAX_VIEW_JSON_BYTES,
+    StandaloneQuiltStore,
+    compute_fabric_root,
+    compute_quilt_root,
+    group_owner_id,
+    validate_quilt_view,
+)
+from .transducers import PROTOCOL_FAMILIES, PythonProtocolRouter, default_python_protocol_router
+
+__all__ = [
+    "HttpResult",
+    "JSON_CT",
+    "binary_http_response",
+    "handle_fiber_http",
+    "is_fiber_route",
+    "FIBER_KINDS",
+    "INTERACTION_KINDS",
+    "MAX_FIBER_BYTES",
+    "MAX_OWNER_BYTES",
+    "MAX_UPLOAD_BODY_BYTES",
+    "PAYLOAD_KINDS",
+    "VISIBILITIES",
+    "StandaloneFiberStore",
+    "PROTOCOL_DIGEST",
+    "PROTOCOL_VERSION",
+    "HostedLeafRelay",
+    "KIND_FABRIC",
+    "KIND_FIBER",
+    "KIND_QUILT",
+    "KIND_STRAND",
+    "NEG_BUCKETS",
+    "NEG_FINGERPRINT",
+    "NEG_ID_LIST",
+    "NEG_INFINITY",
+    "NEG_LIST_THRESHOLD",
+    "NEG_SKIP",
+    "NEG_VERSION",
+    "WS_GUID",
+    "NegBound",
+    "NegentropyServer",
+    "build_engine_textile_inventory",
+    "canonical_bao_hex",
+    "det_hex",
+    "decode_neg_message",
+    "decode_varint",
+    "encode_neg_message",
+    "encode_varint",
+    "neg_fingerprint",
+    "serve_relay_websocket",
+    "handle_quilt_http",
+    "is_quilt_route",
+    "AUDIENCE_RANK",
+    "AUDIENCES",
+    "MAX_VIEW_JSON_BYTES",
+    "StandaloneQuiltStore",
+    "compute_fabric_root",
+    "compute_quilt_root",
+    "group_owner_id",
+    "validate_quilt_view",
+    "PROTOCOL_FAMILIES",
+    "PythonProtocolRouter",
+    "default_python_protocol_router",
+]