Source code for fleetmesh_node.transport.iroh_rung.core

"""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'


[docs]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] )
[docs]class IrohTransport: """Iroh QUIC / stream transport adapter. Manages ALPN fleetmesh/didcomm/1 listeners and outbound stream dispatch. """ scheme: str = 'iroh'
[docs] 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
[docs] 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 fleetmesh_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')
[docs] 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 ------------------------------------------
[docs] 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
[docs] 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)
[docs] 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
[docs] def unlisten(self, thid: str) -> None: """Deregister thread listener queue.""" with self._lock: self._waiting.pop(thid, None)
[docs] 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