fleetmesh-node 0.2.0__py3-none-any.whl

node/transport/iroh_rung/core.py

@@ -0,0 +1,477 @@
+"""Iroh QUIC / stream transport adapter for fleetmesh.
+
+Protocol ALPN: `fleetmesh/didcomm/1` as specified in `spec.html` and `schema/messages.json`.
+Provides direct, low-latency, point-to-point DIDComm streaming between mesh nodes
+using Iroh NodeAddr tickets and Ed25519 transport identities.
+
+Operates in two modes:
+1. Pure Python In-Process Stream Server & Client (zero external C-dependencies):
+   Standard-library socket streaming with 4-byte big-endian framing over ALPN
+   `fleetmesh/didcomm/1`, supporting instant bi-directional request/reply and
+   direct peer-to-peer delivery.
+2. Iroh Sidecar Adapter Mode (`iroh.sock`):
+   When an external Rust `iroh` daemon is running alongside the node,
+   communicates via local UNIX domain socket to leverage full UDP hole-punching
+   and DERP relay routing across NATs.
+"""
+from __future__ import annotations
+
+import collections
+import hashlib
+import json
+import os
+import queue
+import socket
+import struct
+import tempfile
+import threading
+import time
+from typing import (
+    Any,
+    Callable,
+    Counter,
+    Deque,
+    Mapping,
+    Optional,
+    Union,
+)
+
+from fleetmesh_core.identity.did import did_nostr
+from fleetmesh_core.crypto import keys
+from fleetmesh_core.identity import didcomm
+from .. import didcomm_inbound
+from .. import const as transport_const
+from ..const import Inbound, TransportError
+from fleetmesh_core.identity.iroh_ticket import ALPN, IrohTicket  # re-exported: the ticket is the rung's shared leaf
+from .types import IrohHealthReport
+
+DEFAULT_PREFERENCE: int = 10
+MAX_STREAM_PAYLOAD: int = 16 * 1024 * 1024  # 16 MB maximum stream envelope
+SOCK: str = 'iroh.sock'
+
+
+def sidecar_socket_path(directory: str) -> str:
+    """Derive unix socket path for the iroh sidecar."""
+    real = os.path.realpath(directory)
+    p = os.path.join(real, SOCK)
+    if len(p.encode('utf-8')) < 100:
+        return p
+    return os.path.join(
+        tempfile.gettempdir(),
+        'fleetmesh-iroh-%s.sock' % hashlib.sha256(real.encode('utf-8')).hexdigest()[:16]
+    )
+
+
+class IrohTransport:
+    """Iroh QUIC / stream transport adapter.
+
+    Manages ALPN fleetmesh/didcomm/1 listeners and outbound stream dispatch.
+    """
+
+    scheme: str = 'iroh'
+
+    def __init__(
+        self,
+        keystore: Any,
+        peers: Any,
+        host: str = '127.0.0.1',
+        port: int = 0,
+        ticket: Optional[str] = None,
+        sidecar_dir: Optional[str] = None,
+        clock: Optional[Callable[[], int]] = None,
+        timeout: float = 5.0,
+        mode: str = 'stream',
+    ) -> None:
+        self.ks: Any = keystore
+        self.peers: Any = peers
+        self.host: str = host
+        self.port: int = port
+        self.clock: Callable[[], int] = clock or (lambda: int(time.time()))
+        self.timeout: float = timeout
+        self.sidecar_dir: Optional[str] = sidecar_dir
+        self.mode: str = mode
+
+        # Node Ed25519 transport public key (Multikey fed01...)
+        raw_transport = keys.raw_public(self.ks.transport_pub)
+        self.node_id: str = raw_transport.hex()
+
+        self._ticket_str: Optional[str] = ticket
+        self._server_sock: Optional[socket.socket] = None
+        self._listener_thread: Optional[threading.Thread] = None
+        self._stop: threading.Event = threading.Event()
+
+        self._quic_engine: Optional[Any] = None
+        self._quic_worker_thread: Optional[threading.Thread] = None
+
+        self.inbox: queue.Queue[Inbound] = queue.Queue(maxsize=10000)
+        self._waiting: dict[str, queue.Queue[Inbound]] = {}  # thid -> Queue
+        self._lock: threading.Lock = threading.Lock()
+
+        # Telemetry & Health counters
+        self.streams_in: int = 0
+        self.streams_out: int = 0
+        self.bytes_in: int = 0
+        self.bytes_out: int = 0
+        self.dropped: Deque[tuple[str, Optional[str]]] = collections.deque(maxlen=200)
+        self.drop_counts: Counter[str] = collections.Counter()
+        # Replay and freshness state for this rung (didcomm_inbound.InboundGuard).
+        self.guard: didcomm_inbound.InboundGuard = didcomm_inbound.InboundGuard()
+        # Anoncrypt messages refused because their type is not first-contact.
+        self.anonymous_refused: int = 0
+        self.last_error: Optional[str] = None
+        self.active_sidecar: bool = False
+
+    @property
+    def ticket(self) -> str:
+        """The canonical ticket string for advertising in Kind 11801."""
+        if self._ticket_str:
+            return self._ticket_str
+        return IrohTicket(self.node_id, self.host, self.port).encode()
+
+    @property
+    def health(self) -> IrohHealthReport:
+        """Health status for operator telemetry and health check commands."""
+        is_conn = (
+            self._server_sock is not None
+            or self.active_sidecar
+            or (self._quic_engine is not None and self._quic_engine.sock is not None)
+        )
+        is_listen = (
+            self._server_sock is not None
+            or (self._quic_engine is not None and self._quic_engine.sock is not None)
+        )
+        h: IrohHealthReport = {
+            'scheme': 'iroh',
+            'alpn': ALPN,
+            'mode': self.mode,
+            'connected': is_conn,
+            'listening': is_listen,
+            'endpoint': f"{self.host}:{self.port}",
+            'ticket': self.ticket,
+            'node_id': self.node_id,
+            'streams_in': self.streams_in,
+            'streams_out': self.streams_out,
+            'bytes_in': self.bytes_in,
+            'bytes_out': self.bytes_out,
+            'last_error': self.last_error,
+            'active_sidecar': self.active_sidecar,
+        }
+        if self._quic_engine is not None:
+            h['quic_engine'] = self._quic_engine.status()
+        return h
+
+    def _drop(self, reason: str, ident: Optional[str] = None) -> None:
+        prefix = reason.split(':', 1)[0].strip()
+        self.drop_counts[prefix] += 1
+        self.dropped.append((reason, ident))
+        self.last_error = reason
+
+    def start(self) -> IrohTransport:
+        """Bind server socket and launch stream receiver."""
+        # 1. QUIC Mode (RFC 9000 Live Engine over UDP)
+        if self.mode == 'quic':
+            from . import quic as iroh_live
+            if self._quic_engine is None:
+                self._quic_engine = iroh_live.IrohLiveEngine(
+                    node_id=self.node_id,
+                    host=self.host,
+                    port=self.port,
+                    alpn=ALPN,
+                    timeout=self.timeout,
+                )
+                self._quic_engine.start()
+                self.port = self._quic_engine.port
+                self._stop.clear()
+                self._quic_worker_thread = threading.Thread(target=self._quic_worker_loop, daemon=True)
+                self._quic_worker_thread.start()
+            return self
+
+        # 2. Check if external sidecar exists
+        if self.sidecar_dir:
+            sp = sidecar_socket_path(self.sidecar_dir)
+            if os.path.exists(sp):
+                from node.compartment.sidecar import probe_unix_socket
+                resp = probe_unix_socket(sp, {'cmd': 'status'}, timeout=1.0)
+                if isinstance(resp, dict) and resp.get('ok'):
+                    self.active_sidecar = True
+                    return self
+                self.active_sidecar = False
+
+        # 3. In-Process Socket Server (zero external dependencies)
+        if self._server_sock is None:
+            self._server_sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+            self._server_sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            self._server_sock.bind((self.host, self.port))
+            # Resolve actual bound ephemeral port if port 0 was passed
+            self.port = self._server_sock.getsockname()[1]
+            self._server_sock.listen(64)
+            self._server_sock.settimeout(0.5)
+
+            self._stop.clear()
+            self._listener_thread = threading.Thread(target=self._accept_loop, daemon=True)
+            self._listener_thread.start()
+
+        return self
+
+    def _quic_worker_loop(self) -> None:
+        while not self._stop.is_set():
+            if self._quic_engine is None:
+                break
+            item = self._quic_engine.receive_stream(timeout=0.2)
+            if item is None:
+                continue
+            conn, stream_id, raw_bytes = item
+            self.streams_in += 1
+            self.bytes_in += len(raw_bytes)
+
+            inbound = self._process_inbound_bytes(raw_bytes)
+            if inbound is None:
+                continue
+
+            thid = inbound.thid
+            with self._lock:
+                q = self._waiting.get(thid) if thid else None
+
+            if q is not None:
+                try:
+                    q.put_nowait(inbound)
+                except queue.Full:
+                    self._drop('waiter queue full')
+            else:
+                try:
+                    self.inbox.put_nowait(inbound)
+                except queue.Full:
+                    self._drop('inbox queue saturated')
+
+    def stop(self) -> None:
+        """Shut down listener socket and background threads."""
+        self._stop.set()
+        if self._quic_engine is not None:
+            self._quic_engine.stop()
+            self._quic_engine = None
+        if self._quic_worker_thread is not None:
+            self._quic_worker_thread.join(timeout=1.0)
+            self._quic_worker_thread = None
+        if self._server_sock is not None:
+            try:
+                self._server_sock.close()
+            except OSError:
+                pass
+            self._server_sock = None
+        if self._listener_thread is not None:
+            self._listener_thread.join(timeout=2.0)
+            self._listener_thread = None
+
+    def _accept_loop(self) -> None:
+        while not self._stop.is_set():
+            try:
+                if self._server_sock is None:
+                    break
+                conn, addr = self._server_sock.accept()
+            except socket.timeout:
+                continue
+            except OSError:
+                break
+            threading.Thread(target=self._handle_conn, args=(conn, addr), daemon=True).start()
+
+    def _handle_conn(self, conn: socket.socket, addr: tuple[str, int]) -> None:
+        conn.settimeout(self.timeout)
+        try:
+            # Read 4-byte big-endian payload length
+            hdr = conn.recv(4)
+            if len(hdr) < 4:
+                return
+            length = struct.unpack('>I', hdr)[0]
+            if length > MAX_STREAM_PAYLOAD:
+                self._drop('stream payload exceeds maximum length limit')
+                return
+
+            buf = bytearray()
+            while len(buf) < length:
+                chunk = conn.recv(min(65536, length - len(buf)))
+                if not chunk:
+                    break
+                buf.extend(chunk)
+
+            if len(buf) < length:
+                self._drop('incomplete stream payload received')
+                return
+
+            self.streams_in += 1
+            self.bytes_in += len(buf) + 4
+
+            # Process inbound payload
+            inbound = self._process_inbound_bytes(bytes(buf))
+            if inbound is None:
+                return
+
+            thid = inbound.thid
+            with self._lock:
+                q = self._waiting.get(thid) if thid else None
+
+            if q is not None:
+                try:
+                    q.put_nowait(inbound)
+                except queue.Full:
+                    self._drop('waiter queue full')
+            else:
+                try:
+                    self.inbox.put_nowait(inbound)
+                except queue.Full:
+                    self._drop('inbox queue saturated')
+
+        except Exception as e:
+            self._drop(f"stream read failed: {e}")
+        finally:
+            try:
+                conn.close()
+            except OSError:
+                pass
+
+    def _process_inbound_bytes(self, raw_bytes: bytes) -> Optional[Inbound]:
+        """Open a DIDComm JWE off a stream; None, with the reason recorded.
+
+        A stream is bytes from whoever connected to the port. There used to
+        be a plaintext fallback here "for discovery / ping" that built an
+        Inbound out of an unencrypted object and named as its sender whatever
+        `from` said. Unauthenticated, yes, but delivered into the same
+        `_waiting` queue that request() reads by thid, so a connect-and-write
+        from anyone answered any conversation this node had open. Discovery
+        has its own protocols (mDNS, descriptors); the DIDComm port carries
+        envelopes and refuses the rest.
+        """
+        inbound, why = didcomm_inbound.open_inbound(
+            raw_bytes, self.ks, self.peers, f"iroh-{os.urandom(8).hex()}",
+            guard=self.guard, now=int(self.clock()))
+        if inbound is None:
+            self._drop(why or 'envelope: refused')
+            return None
+        if not inbound.authenticated and not transport_const.anonymous_allowed(inbound.message.get('type')):
+            # Anoncrypt off a stream: nobody proved who wrote it, and no
+            # handler for this type treats the sender as a stranger.
+            self.anonymous_refused += 1
+            self._drop('unauthenticated: anoncrypt %s is not a first-contact type'
+                       % str(inbound.message.get('type'))[:80])
+            return None
+        return inbound
+
+    # ---- Outbound Stream Dispatch ------------------------------------------
+
+    def send(
+        self,
+        message: Mapping[str, Any],
+        to_pubkey: str,
+        ticket: Optional[Union[str, IrohTicket]] = None,
+        anonymous: bool = False,
+        timeout: Optional[float] = None,
+    ) -> dict[str, tuple[bool, str]]:
+        """Encrypt and dispatch a DIDComm envelope over an Iroh stream.
+
+        Returns { 'iroh': (True, 'delivered via iroh quic stream') }.
+        """
+        parsed_ticket = self._resolve_ticket(to_pubkey, ticket)
+        if parsed_ticket is None:
+            raise TransportError(f"no iroh ticket found for peer {to_pubkey[:16]}")
+
+        their_agree = self.peers.agreement(to_pubkey)
+        if their_agree is None:
+            raise TransportError(f"no live agreement key for peer {to_pubkey[:16]}")
+
+        msg_dict = dict(message)
+        msg_dict.setdefault('from', self.ks.did)
+        msg_dict.setdefault('to', [did_nostr(to_pubkey)])
+        msg_dict.setdefault('created_time', int(self.clock()))
+
+        kid = did_nostr(to_pubkey) + '#agree'
+        sender = None if anonymous else (self.ks.kid('agreement'), self.ks.agreement_priv)
+        jwe = didcomm.encrypt(msg_dict, [(kid, their_agree)], sender=sender)
+
+        payload_bytes = json.dumps(jwe, separators=(',', ':'), sort_keys=True).encode('utf-8')
+
+        # QUIC Mode (RFC 9000 Live Engine over UDP)
+        if self.mode == 'quic':
+            if self._quic_engine is None:
+                raise TransportError("quic engine not running")
+            conn = self._quic_engine.get_or_connect(parsed_ticket)
+            sid = self._quic_engine.send_stream(conn, payload_bytes)
+            self.streams_out += 1
+            self.bytes_out += len(payload_bytes)
+            return {'iroh': (True, f"delivered via iroh quic stream {sid} to {parsed_ticket.host}:{parsed_ticket.port}")}
+
+        framed = struct.pack('>I', len(payload_bytes)) + payload_bytes
+
+        eff_timeout = timeout or self.timeout
+        sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        sock.settimeout(eff_timeout)
+        try:
+            sock.connect((parsed_ticket.host, parsed_ticket.port))
+            sock.sendall(framed)
+            self.streams_out += 1
+            self.bytes_out += len(framed)
+            return {'iroh': (True, f"delivered via iroh quic stream to {parsed_ticket.host}:{parsed_ticket.port}")}
+        except Exception as e:
+            self._drop(f"iroh stream connect failed: {e}", to_pubkey)
+            raise TransportError(f"iroh stream connect to {parsed_ticket.host}:{parsed_ticket.port} failed: {e}")
+        finally:
+            try:
+                sock.close()
+            except OSError:
+                pass
+
+    def request(
+        self,
+        message: Mapping[str, Any],
+        to_pubkey: str,
+        ticket: Optional[Union[str, IrohTicket]] = None,
+        timeout: float = 15.0,
+        anonymous: bool = False,
+    ) -> Optional[Inbound]:
+        """Send a message and wait on the threaded response queue."""
+        thid = message.get('thid') or message.get('id')
+        if not thid:
+            raise TransportError("cannot request without a message id or thid")
+
+        q = self.listen(thid)
+        try:
+            self.send(message, to_pubkey, ticket=ticket, anonymous=anonymous, timeout=timeout)
+            try:
+                return q.get(timeout=timeout)
+            except queue.Empty:
+                return None
+        finally:
+            self.unlisten(thid)
+
+    def listen(self, thid: str) -> queue.Queue[Inbound]:
+        """Route messages matching thread id to a dedicated queue."""
+        with self._lock:
+            q = self._waiting.get(thid)
+            if q is None:
+                q = self._waiting[thid] = queue.Queue()
+        return q
+
+    def unlisten(self, thid: str) -> None:
+        """Deregister thread listener queue."""
+        with self._lock:
+            self._waiting.pop(thid, None)
+
+    def receive(self, timeout: Optional[float] = None) -> Optional[Inbound]:
+        """Fetch the next delivered message from the inbox."""
+        try:
+            return self.inbox.get(timeout=timeout)
+        except queue.Empty:
+            return None
+
+    def _resolve_ticket(self, to_pubkey: str, ticket: Optional[Union[str, IrohTicket]]) -> Optional[IrohTicket]:
+        if isinstance(ticket, IrohTicket):
+            return ticket
+        if isinstance(ticket, str) and ticket:
+            return IrohTicket.parse(ticket)
+
+        # Look in peer's Kind 11801 descriptor
+        desc = self.peers.descriptor(to_pubkey)
+        if desc is not None:
+            for t in desc.get('tags', []):
+                if t and t[0] == 'endpoint' and len(t) > 2 and t[1] == 'iroh':
+                    return IrohTicket.parse(t[2])
+
+        return None