fleetmesh-node 0.2.0__py3-none-any.whl

node/transport/iroh_rung/types.py

@@ -0,0 +1,22 @@
+"""Types and report structures for the Iroh transport rung."""
+from __future__ import annotations
+
+from typing import Any, Optional, TypedDict
+
+
+class IrohHealthReport(TypedDict, total=False):
+    scheme: str
+    alpn: str
+    mode: str
+    connected: bool
+    listening: bool
+    endpoint: str
+    ticket: str
+    node_id: str
+    streams_in: int
+    streams_out: int
+    bytes_in: int
+    bytes_out: int
+    last_error: Optional[str]
+    active_sidecar: bool
+    quic_engine: Any

node/transport/ladder.py

@@ -0,0 +1,145 @@
+"""Per-rung circuit breaker and the rung base class for the transport ladder.
+
+The ladder itself - which rung is tried first for a peer, and in what order
+the rest follow - lives in router.py (TransportRouter); the order is
+fips-native, iroh, libp2p, nostr and is not decided here. This module holds
+the pieces every rung shares: a CircuitBreaker that stops the router from
+hanging on a target that keeps failing, a FaultLog so that what a rung
+dropped and why is readable rather than only countable. The rung contract
+itself (RungProtocol, Rung) is in rung.py. Standard library only.
+"""
+from __future__ import annotations
+
+import collections
+import threading
+import time
+from typing import Any, Counter, Deque, Dict, Iterable, Optional, TypedDict
+
+
+class Fault(TypedDict):
+    """One thing a rung refused or lost, kept so an operator can read it."""
+    at: int                      # the node clock when it happened
+    rung: str                    # 'nostr', 'fips-native', 'iroh', 'libp2p', or 'router'
+    reason: str                  # 'publish refused: wss://... invalid: ...'; the prefix before ':' is the family
+    ident: Optional[str]         # the wrap, stream or message id it concerned, when there was one
+
+
+class FaultLog:
+    """The most recent faults of one rung and a count per family, ever.
+
+    A count alone said '0 faults' while every wrap was being refused; the
+    reasons are what tell an operator the relay said 'ephemeral event
+    expired'. Thread-safe; readers get copies.
+    """
+
+    def __init__(self, rung: str, clock: Any = None, keep: int = 200) -> None:
+        self.rung: str = rung
+        self.clock: Any = clock or (lambda: int(time.time()))
+        self._recent: Deque[Fault] = collections.deque(maxlen=keep)
+        self.counts: Counter[str] = collections.Counter()
+        self._lock: threading.Lock = threading.Lock()
+
+    def record(self, reason: str, ident: Optional[str] = None) -> Fault:
+        f = Fault(at=int(self.clock()), rung=self.rung, reason=reason, ident=ident)
+        with self._lock:
+            self._recent.append(f)
+            self.counts[reason.split(':', 1)[0].strip()] += 1
+        return f
+
+    def recent(self, since: Optional[int] = None, family: Optional[str] = None) -> list[Fault]:
+        """Newest last. `since` keeps faults at or after that clock reading;
+        `family` keeps the reason prefix ('publish refused')."""
+        with self._lock:
+            rows = list(self._recent)
+        return [f for f in rows
+                if (since is None or f['at'] >= since)
+                and (family is None or f['reason'].split(':', 1)[0].strip() == family)]
+
+    @property
+    def maxlen(self) -> Optional[int]:
+        return self._recent.maxlen
+
+    def __len__(self) -> int:
+        return len(self._recent)
+
+    def __iter__(self) -> Iterable[Fault]:
+        with self._lock:
+            return iter(list(self._recent))
+
+
+def merge_faults(logs: Iterable[FaultLog], since: Optional[int] = None) -> list[Fault]:
+    """Faults across rungs in time order, for the ladder's aggregate view."""
+    out: list[Fault] = []
+    for lg in logs:
+        out.extend(lg.recent(since))
+    out.sort(key=lambda f: f['at'])
+    return out
+
+
+class CircuitBreaker:
+    """Per-target circuit breaker to avoid hanging on repeatedly failing transports."""
+
+    STATE_CLOSED: str = 'closed'
+    STATE_OPEN: str = 'open'
+    STATE_HALF_OPEN: str = 'half_open'
+
+    def __init__(self, failure_threshold: int = 3, recovery_timeout: float = 30.0) -> None:
+        self.failure_threshold: int = failure_threshold
+        self.recovery_timeout: float = recovery_timeout
+        self._lock: threading.RLock = threading.RLock()
+        self._failures: collections.Counter[str] = collections.Counter()
+        self._last_failure: Dict[str, float] = {}
+        self._states: Dict[str, str] = {}
+
+    def allow_attempt(self, target: str, now: Optional[float] = None) -> bool:
+        """Return True if an attempt to reach target is permitted."""
+        with self._lock:
+            t_now = time.time() if now is None else now
+            state = self._states.get(target, self.STATE_CLOSED)
+            if state == self.STATE_CLOSED:
+                return True
+            last = self._last_failure.get(target, 0.0)
+            if t_now - last >= self.recovery_timeout:
+                self._states[target] = self.STATE_HALF_OPEN
+                return True
+            return False
+
+    def record_success(self, target: str) -> None:
+        """Record successful transmission, resetting circuit to CLOSED."""
+        with self._lock:
+            self._failures[target] = 0
+            self._states[target] = self.STATE_CLOSED
+
+    def record_failure(self, target: str, now: Optional[float] = None) -> None:
+        """Record transmission failure, potentially tripping circuit to OPEN."""
+        with self._lock:
+            t_now = time.time() if now is None else now
+            self._last_failure[target] = t_now
+            self._failures[target] += 1
+            if self._failures[target] >= self.failure_threshold:
+                self._states[target] = self.STATE_OPEN
+
+    def state(self, target: str) -> str:
+        """Current state for target."""
+        with self._lock:
+            return self._states.get(target, self.STATE_CLOSED)
+
+    def failures(self, target: str) -> int:
+        """Return current consecutive failure count for target."""
+        with self._lock:
+            return self._failures[target]
+
+    def reset(self, target: Optional[str] = None) -> None:
+        """Reset circuit breaker for a target or all targets."""
+        with self._lock:
+            if target is None:
+                self._failures.clear()
+                self._last_failure.clear()
+                self._states.clear()
+            else:
+                self._failures.pop(target, None)
+                self._last_failure.pop(target, None)
+                self._states.pop(target, None)
+
+
+__all__ = ['CircuitBreaker', 'Fault', 'FaultLog', 'merge_faults']

node/transport/lineproto.py

@@ -0,0 +1,49 @@
+"""Newline-delimited JSON over a stream socket.
+
+A reply on a stream socket arrives in as many pieces as the kernel and the
+writer choose. One `recv(65536)` sees whatever happens to be in the buffer:
+half a line when the writer paused, or a line and a half when it did not.
+Readers of a line protocol loop until the delimiter, with a cap so a peer
+that never sends one cannot grow this process without bound.
+"""
+from __future__ import annotations
+
+import json
+import socket
+from typing import Any
+
+DEFAULT_CAP: int = 1 << 20
+
+
+def read_line(sock: socket.socket, cap: int = DEFAULT_CAP) -> bytes:
+    """Read from `sock` until a newline and return the line without it.
+
+    Bytes after the newline in the same recv are discarded: this is for a
+    one-shot request/reply exchange, not for a long-lived multiplexed stream.
+    Raises ValueError if the peer closes before a newline (EOF) or sends
+    `cap` bytes without one. Socket timeouts propagate as the caller set
+    them (socket.timeout / TimeoutError).
+    """
+    if cap <= 0:
+        raise ValueError('cap must be positive')
+    buf = bytearray()
+    while True:
+        chunk = sock.recv(min(65536, cap - len(buf) + 1))
+        if not chunk:
+            raise ValueError('line: connection closed before a newline (%d bytes buffered)' % len(buf))
+        buf.extend(chunk)
+        nl = buf.find(b'\n')
+        if nl >= 0:
+            return bytes(buf[:nl])
+        if len(buf) > cap:
+            raise ValueError('line: %d bytes without a newline exceeds the %d-byte cap' % (len(buf), cap))
+
+
+def read_json_line(sock: socket.socket, cap: int = DEFAULT_CAP) -> Any:
+    """Read one newline-terminated JSON value from `sock`.
+
+    Raises ValueError on EOF before the newline, on a line past `cap` bytes,
+    and on a line that is not JSON (json.JSONDecodeError is a ValueError).
+    """
+    line = read_line(sock, cap=cap)
+    return json.loads(line.decode('utf-8'))

node/transport/mdns.py

@@ -0,0 +1,303 @@
+"""Enough of RFC 6762 and RFC 6763 for a node to find another on its own link.
+
+Standard library only, like `ws.py` and for the same reason: this is the one
+discovery path that must work when there is no relay, no DNS and no internet,
+so it cannot be the path that needs a package index to install.
+
+What is here is the DNS-SD subset a service advertisement uses and nothing
+else: PTR, SRV, TXT and A, a query for one service type, and the records that
+answer it. Name compression is decoded because other responders emit it, and
+never written, because a service advertisement is small and a pointer saves
+nothing worth the code.
+
+The wire is the ordinary DNS message format on multicast. What makes it mDNS
+rather than DNS is where it goes - 224.0.0.251:5353, TTL 255, joined by every
+participant - and that an answer may arrive unsolicited, which is how a node
+that has just started announces itself to a link that never asked.
+
+None of this authenticates anything and it is not supposed to. A TXT record is
+a routing hint: anyone on the link can claim any key. What proves a node is the
+descriptor fetched afterwards from the address the hint gave, which is signed.
+`lan.py` is where that happens.
+"""
+from __future__ import annotations
+
+import socket
+import struct
+from typing import Any, Iterator, Optional
+
+GROUP: str = '224.0.0.251'
+PORT: int = 5353
+# RFC 6762 section 11: every mDNS packet is sent with a TTL of 255, and a
+# receiver may check it. It is how the protocol keeps itself on one link.
+HOP: int = 255
+# Record types. The four a service advertisement needs.
+A: int = 1
+PTR: int = 12
+TXT: int = 16
+SRV: int = 33
+IN: int = 1
+# The cache-flush bit, the top bit of the class field in an answer. It tells a
+# receiver that this record replaces what it holds rather than joining it,
+# which is what a node that has changed address needs.
+FLUSH: int = 0x8000
+# What a record is good for. Short enough that a node which vanishes without a
+# goodbye is forgotten in minutes, long enough not to re-query constantly.
+TTL: int = 120
+MAX_PACKET: int = 9000
+
+
+class MdnsError(ValueError):
+    pass
+
+
+# ----------------------------------------------------------------- names ----
+def encode_name(name: str) -> bytes:
+    """A dotted name as length-prefixed labels, terminated by a zero byte."""
+    out = bytearray()
+    for label in name.rstrip('.').split('.'):
+        raw = label.encode('utf-8')
+        if not raw or len(raw) > 63:
+            raise MdnsError('a label is 1 to 63 bytes: %r' % label[:20])
+        out.append(len(raw))
+        out += raw
+    out.append(0)
+    if len(out) > 255:
+        raise MdnsError('a name is at most 255 bytes')
+    return bytes(out)
+
+
+def decode_name(buf: bytes, off: int) -> tuple[str, int]:
+    """(name, offset after it). Follows compression pointers, and refuses a
+    loop: a pointer must always point strictly backwards, so a packet that
+    points forward or to itself is malformed rather than an infinite read."""
+    labels: list[str] = []
+    here, jumped, hops = off, None, 0
+    while True:
+        if here >= len(buf):
+            raise MdnsError('name runs past the packet')
+        n = buf[here]
+        if n & 0xC0 == 0xC0:
+            if here + 1 >= len(buf):
+                raise MdnsError('a compression pointer runs past the packet')
+            target = ((n & 0x3F) << 8) | buf[here + 1]
+            if target >= here:
+                raise MdnsError('a compression pointer must point backwards')
+            hops += 1
+            if hops > 64:
+                raise MdnsError('too many compression pointers')
+            if jumped is None:
+                jumped = here + 2
+            here = target
+            continue
+        here += 1
+        if n == 0:
+            break
+        if here + n > len(buf):
+            raise MdnsError('a label runs past the packet')
+        labels.append(buf[here:here + n].decode('utf-8', 'replace'))
+        here += n
+    return '.'.join(labels), (jumped if jumped is not None else here)
+
+
+# --------------------------------------------------------------- records ----
+class Record:
+    __slots__ = ('name', 'rtype', 'ttl', 'data')
+
+    def __init__(self, name: str, rtype: int, data: Any, ttl: int = TTL) -> None:
+        self.name, self.rtype, self.ttl, self.data = name, rtype, ttl, data
+
+    def __repr__(self) -> str:
+        return 'Record(%r, %d, %r)' % (self.name, self.rtype, self.data)
+
+
+def encode_txt(pairs: dict[str, str]) -> bytes:
+    """DNS-SD TXT: one length-prefixed `key=value` string per entry, sorted so
+    the same map always encodes to the same bytes."""
+    out = bytearray()
+    for k in sorted(pairs):
+        item = ('%s=%s' % (k, pairs[k])).encode('utf-8')
+        if len(item) > 255:
+            raise MdnsError('a TXT entry is at most 255 bytes: %s' % k)
+        out.append(len(item))
+        out += item
+    return bytes(out) or b'\x00'
+
+
+def decode_txt(raw: bytes) -> dict[str, str]:
+    out: dict[str, str] = {}
+    i = 0
+    while i < len(raw):
+        n = raw[i]
+        i += 1
+        if n == 0:
+            continue
+        item = raw[i:i + n].decode('utf-8', 'replace')
+        i += n
+        key, _, value = item.partition('=')
+        if key:
+            out.setdefault(key, value)
+    return out
+
+
+def _rdata(rec: Record) -> bytes:
+    if rec.rtype == PTR:
+        return encode_name(rec.data)
+    if rec.rtype == TXT:
+        return encode_txt(rec.data) if isinstance(rec.data, dict) else bytes(rec.data)
+    if rec.rtype == SRV:
+        prio, weight, port, target = rec.data
+        return struct.pack('!HHH', prio, weight, port) + encode_name(target)
+    if rec.rtype == A:
+        return socket.inet_aton(rec.data)
+    raise MdnsError('this speaks PTR, TXT, SRV and A, not type %d' % rec.rtype)
+
+
+def build(
+    questions: list[tuple[str, int]] | None = None,
+    answers: list[Record] | None = None,
+    additionals: list[Record] | None = None,
+    flush: bool = True,
+) -> bytes:
+    """One mDNS message. A message with answers is a response (QR set); one
+    with only questions is a query. The id is zero: mDNS matches on content,
+    never on a transaction id, because an answer may be unsolicited."""
+    qs, ans, adds = questions or [], answers or [], additionals or []
+    flags = 0x8400 if ans else 0x0000          # QR + AA when answering
+    out = bytearray(struct.pack('!HHHHHH', 0, flags, len(qs), len(ans), 0, len(adds)))
+    for name, qtype in qs:
+        out += encode_name(name) + struct.pack('!HH', qtype, IN)
+    for rec in ans + adds:
+        body = _rdata(rec)
+        klass = IN | (FLUSH if flush and rec.rtype != PTR else 0)
+        out += encode_name(rec.name) + struct.pack('!HHIH', rec.rtype, klass, rec.ttl, len(body)) + body
+    if len(out) > MAX_PACKET:
+        raise MdnsError('packet of %d bytes is larger than this sends' % len(out))
+    return bytes(out)
+
+
+class Message:
+    __slots__ = ('questions', 'answers', 'is_response')
+
+    def __init__(self, questions: list[tuple[str, int]], answers: list[Record], is_response: bool) -> None:
+        self.questions, self.answers, self.is_response = questions, answers, is_response
+
+
+def parse(buf: bytes) -> Message:
+    """A message, with every record this speaks decoded and the rest skipped.
+
+    A packet from the link is whatever anyone put on it, so every length is
+    checked against the buffer before it is used and an unknown type is walked
+    over by its own length rather than guessed at.
+    """
+    if len(buf) < 12:
+        raise MdnsError('a DNS message is at least 12 bytes')
+    _, flags, qd, an, ns, ar = struct.unpack('!HHHHHH', buf[:12])
+    off = 12
+    questions: list[tuple[str, int]] = []
+    for _ in range(qd):
+        name, off = decode_name(buf, off)
+        if off + 4 > len(buf):
+            raise MdnsError('a question runs past the packet')
+        qtype, _qclass = struct.unpack('!HH', buf[off:off + 4])
+        off += 4
+        questions.append((name, qtype))
+    answers: list[Record] = []
+    for _ in range(an + ns + ar):
+        if off >= len(buf):
+            break                      # a truncated section is what it is
+        name, off = decode_name(buf, off)
+        if off + 10 > len(buf):
+            raise MdnsError('a record header runs past the packet')
+        rtype, _klass, ttl, rdlen = struct.unpack('!HHIH', buf[off:off + 10])
+        off += 10
+        if off + rdlen > len(buf):
+            raise MdnsError('rdata runs past the packet')
+        body, end = buf[off:off + rdlen], off + rdlen
+        try:
+            if rtype == PTR:
+                answers.append(Record(name, PTR, decode_name(buf, off)[0], ttl))
+            elif rtype == TXT:
+                answers.append(Record(name, TXT, decode_txt(body), ttl))
+            elif rtype == SRV and rdlen >= 7:
+                prio, weight, port = struct.unpack('!HHH', body[:6])
+                answers.append(Record(name, SRV, (prio, weight, port, decode_name(buf, off + 6)[0]), ttl))
+            elif rtype == A and rdlen == 4:
+                answers.append(Record(name, A, socket.inet_ntoa(body), ttl))
+        except MdnsError:
+            pass                       # one unreadable record is not a bad packet
+        off = end
+    return Message(questions, answers, bool(flags & 0x8000))
+
+
+# ---------------------------------------------------------------- socket ----
+def open_socket(bind_group: bool = True) -> socket.socket:
+    """A socket on the mDNS group, shareable with every other responder here.
+
+    SO_REUSEPORT as well as SO_REUSEADDR, because two nodes on one machine is
+    the arrangement this project already runs - lon1 has carried two since
+    2026-09-04 - and without it the second one cannot bind and the pair is
+    invisible to each other and to everyone else.
+    """
+    s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM, socket.IPPROTO_UDP)
+    s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+    if hasattr(socket, 'SO_REUSEPORT'):
+        try:
+            s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEPORT, 1)
+        except OSError:
+            pass                       # some kernels decline it; one node still works
+    s.setsockopt(socket.IPPROTO_IP, socket.IP_MULTICAST_TTL, HOP)
+    s.setsockopt(socket.IPPROTO_IP, socket.IP_MULTICAST_LOOP, 1)
+    s.bind(('', PORT if bind_group else 0))
+    if bind_group:
+        s.setsockopt(socket.IPPROTO_IP, socket.IP_ADD_MEMBERSHIP,
+                     struct.pack('4s4s', socket.inet_aton(GROUP), socket.inet_aton('0.0.0.0')))
+    s.settimeout(0.5)
+    return s
+
+
+def send(sock: socket.socket, packet: bytes) -> None:
+    """Put one packet on the group. Raises OSError if the link refuses it.
+
+    It used to swallow that, on the grounds that no route to the group is not
+    this node's fault. True, and the wrong layer to decide it: a joined socket
+    is not a link that forwards, and a host with no route for 224.0.0.0/4 or a
+    network that filters multicast - which is what a cloud private network
+    usually is - refuses the send itself. Swallowed here, such a node
+    advertised nothing, said nothing about it, and reported itself as
+    advertising. This layer says what happened; `Lan._say` decides what it
+    means and puts it where an operator reads it.
+    """
+    sock.sendto(packet, (GROUP, PORT))
+
+
+def receive(sock: socket.socket) -> Iterator[tuple[Message, str]]:
+    """Every message readable right now, with the address it came from."""
+    while True:
+        try:
+            data, addr = sock.recvfrom(MAX_PACKET)
+        except (socket.timeout, BlockingIOError):
+            return
+        except OSError:
+            return
+        try:
+            yield parse(data), addr[0]
+        except MdnsError:
+            continue                   # a malformed packet is a packet, not a fault
+
+
+def local_address() -> Optional[str]:
+    """This machine's address on the interface that reaches the link.
+
+    Asked of a disconnected UDP socket, which chooses a route without sending
+    anything: there is nothing to reach on a dead network, and this still
+    answers because the kernel already knows which interface it would use.
+    """
+    s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    try:
+        s.connect((GROUP, PORT))
+        return s.getsockname()[0]
+    except OSError:
+        return None
+    finally:
+        s.close()