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