fleetmesh-node 0.2.0__py3-none-any.whl

node/planes/transport/bridge/ratelimit.py

@@ -0,0 +1,44 @@
+"""A sliding one-minute rate limiter, shared by both relay bridges.
+
+The node's bridge compartment and the strfry plugin (`fleetmesh_strfry`) each
+carried this class, line for line (audit 2026-10-15, D4). It lives here, in a
+module that imports nothing of the node but its default, so the plugin - which
+already runs against the meshnode checkout - can take it without importing the
+bridge compartment.
+"""
+from __future__ import annotations
+
+import collections
+import threading
+import time
+from typing import Deque, Optional
+
+from node.config.compartments import DEFAULT_RATE_LIMIT_PER_MIN
+
+
+class RateLimiter:
+    """Sliding-window rate limiter tracking event timestamps within a 60-second interval."""
+
+    def __init__(self, limit_per_minute: int = DEFAULT_RATE_LIMIT_PER_MIN) -> None:
+        self.limit: int = max(1, int(limit_per_minute))
+        self._timestamps: Deque[float] = collections.deque()
+        self._lock: threading.Lock = threading.Lock()
+
+    def allow(self, now: Optional[float] = None) -> bool:
+        t = now if now is not None else time.time()
+        window_start = t - 60.0
+        with self._lock:
+            while self._timestamps and self._timestamps[0] < window_start:
+                self._timestamps.popleft()
+            if len(self._timestamps) >= self.limit:
+                return False
+            self._timestamps.append(t)
+            return True
+
+    def count(self, now: Optional[float] = None) -> int:
+        t = now if now is not None else time.time()
+        window_start = t - 60.0
+        with self._lock:
+            while self._timestamps and self._timestamps[0] < window_start:
+                self._timestamps.popleft()
+            return len(self._timestamps)

node/planes/transport/bridge/types.py

@@ -0,0 +1,43 @@
+"""Types and records for the Bridge compartment."""
+from __future__ import annotations
+
+from typing import Optional, TypedDict
+
+
+class IngressStats(TypedDict):
+    enabled: bool
+    stored: int
+    duplicates: int
+    p2p_forward_failures: int
+    refused: int
+    last_event_at: Optional[int]
+
+
+class EgressStats(TypedDict):
+    enabled: bool
+    sent: int
+    failed: int
+    pending: int
+    last_event_at: Optional[int]
+
+
+class RelayWorkerStats(TypedDict):
+    url: str
+    connected: bool
+    last_connected_at: Optional[int]
+    ingress_count: int
+    egress_count: int
+    errors_count: int
+    last_error: Optional[str]
+    handler_errors: int
+    last_handler_error: Optional[str]
+    last_event_at: Optional[int]
+
+
+class BridgeStateReport(TypedDict):
+    enabled: bool
+    relays_configured: int
+    relays_connected: int
+    ingress: IngressStats
+    egress: EgressStats
+    relays: dict[str, RelayWorkerStats]

node/planes/transport/lan/__init__.py

@@ -0,0 +1,9 @@
+"""Finding a node on the same link, with no relay and nothing configured.
+
+One-module compartment: everything is in compartment.py.
+"""
+from .compartment import Lan
+from .types import LanPeerRecord, LanStateReport
+
+__all__ = ['Lan', 'LanPeerRecord', 'LanStateReport']
+

node/planes/transport/lan/compartment.py

@@ -0,0 +1,446 @@
+"""Finding a node on the same link, with no relay and nothing configured.
+
+Bridge 5, and the only one that needs nothing outside the room. The
+specification's four bootstrap paths all start somewhere else: a relay holds
+the descriptor, gossipsub needs a peer to reach the topic, and an operator
+typing an address has to know one. `fleetmesh_core/tests/test_unplug.py` passes with
+every relay gone, but only because the peers were already in the config - two
+nodes that had never met could not have found each other, which is the part of
+the unplug claim nothing was demonstrating.
+
+A node advertises `_fleetmesh._tcp.local.` over multicast DNS, carrying its
+pubkey, the protocol digest it speaks, and the port of its own relay face. It
+browses for the same, and for each answer it does the thing that makes the
+hint worth having: it asks that face for the advertiser's kind 11801.
+
+That is the whole trick. Every node already serves a relay face, a descriptor
+is an ordinary event on it, and `descriptor.resolve` takes any relay URL. So
+the peer's own face is the relay, the descriptor it serves is signed by the
+key the advert claimed, and `peers.learn` refuses it if the two disagree. A
+stranger on the link may advertise any pubkey it likes and gets nowhere: it
+cannot produce a descriptor signed by a key it does not hold.
+
+**The digest does not filter.** Since 0.3 two nodes built from different
+schemas peer on the protocols they share (fleetmesh_core/identity.shared_protocols), so an
+advert with a different digest is a candidate like any other. The advert still
+carries the digest: it is provenance, kept per node in `meshnode lan` so an
+operator can see a link drifting onto several schemas without dialling anyone.
+
+Discovery ends at a validated descriptor. Peering is the scheduler's business
+and an operator's decision, as it is for every other bridge.
+"""
+from __future__ import annotations
+
+from fleetmesh_core.wire import spelling  # noqa: E402
+
+import ipaddress
+import socket
+import threading
+from typing import Any, Callable, Mapping, Optional
+
+from node.protocols.nostr import descriptor as descriptor_mod
+from node.compartment import stores as st
+from node.channels import Channel, TROUBLE
+from node.metrics import COUNTER, Metric
+from node.transport import mdns
+from node.compartment import Command, Compartment, Every, Need
+from node.config import LanConfig
+
+
+from .types import LanPeerRecord, LanStateReport
+
+SERVICE: str = '_fleetmesh._tcp.local'
+# The TXT keys. Short because a TXT record is small and every advertisement
+# carries all of them; `pk` and `d` are what a reader acts on, `c` is a hint.
+KEY_PUBKEY: str = 'pk'
+KEY_DIGEST: str = 'd'
+KEY_CLASS: str = 'c'
+# How much of the digest travels. Sixteen hex is eight bytes of it, which is
+# far past any accident, and a full one would be most of the record.
+DIGEST_CHARS: int = 16
+# A node is re-announced this often even when nothing has changed, because a
+# record expires and a listener that joined late has heard nothing.
+ANNOUNCE_EVERY: int = 60
+# What one browse may bring back, and how long a peer stays known after its
+# last advert. A link is not a grant, so the bound is here.
+SEEN_MAX: int = 128
+FORGET_AFTER: int = 600
+
+
+def instance_name(pubkey: str) -> str:
+    """The DNS-SD instance: this node's key, short, under the service type.
+
+    Sixteen hex is enough to be unique on a link and short enough to read in
+    `dns-sd -B`. The full key travels in the TXT, which is what is acted on.
+    """
+    return '%s.%s' % (pubkey[:16], SERVICE)
+
+
+def _not_dialable(ip: str, src: Optional[str]) -> Optional[str]:
+    """Why this node will not open a socket to the address an advert names,
+    or None if it will. Two rules, in the order they are cheapest."""
+    try:
+        target = ipaddress.ip_address(ip)
+    except ValueError:
+        return 'the advertised address is not an IP address'
+    if not (target.is_private or target.is_link_local or target.is_loopback):
+        return 'the advertised address is not on a local network'
+    if src is not None:
+        try:
+            if ipaddress.ip_address(src) != target:
+                return 'the advertised address is not the one that sent the packet'
+        except ValueError:
+            return 'the advertised address is not the one that sent the packet'
+    return None
+
+
+class Lan(Compartment):
+
+    name: str = 'lan'
+    reads: tuple[str, ...] = ('lan',)
+    config_cls = LanConfig
+    NEEDS = (
+        Need('keystore', 'ks'),
+        Need('peers', 'peers'),
+        Need('face', 'face'),
+        Need('node_class', 'node_class'),
+        Need('timeout', 'timeout'),
+    )
+    EVERY = (Every(seconds=ANNOUNCE_EVERY, run='_announce'),)
+    COMMANDS = (
+        Command(
+            key='show',
+            name='Lan',
+            description='what this node advertises on its link and what it has heard there',
+            tags=('lan', 'status'),
+            permission='lan/show',
+            run='state',
+            reply='{enabled, service, advertising, address, port, seen, learned, refused}',
+        ),
+    )
+    STORES = (
+        st.Store(key='_seen', description='LAN peers seen via broadcast beacon',
+                 kind=st.TABLE, shape=dict, bound=1024, keyed_by='peer', evict=st.LRU),
+        st.Store(key='_resolved', description='when peer descriptor was last fetched over LAN',
+                 kind=st.TABLE, shape=int, bound=1024, keyed_by='peer', evict=st.LRU),
+    )
+    CHANNELS = (
+        Channel('socket_error', 'Cannot join mDNS multicast group', level=TROUBLE,
+                say='cannot join the mDNS group ({error}); the other bridges are unaffected'),
+        Channel('advertising', 'Local node mDNS service advertisement started',
+                say='advertising {instance} on port {port}'),
+        Channel('send_error', 'Multicast link cannot carry advertisement', level=TROUBLE,
+                say='the link will not carry an advertisement ({error}); nothing else is affected'),
+    )
+    METRICS = (
+        Metric(name='lan_advertisements', description='Times mDNS advertisement was started.',
+               kind=COUNTER, counts='advertising', tags=('lan', 'mdns')),
+        Metric(name='lan_socket_errors', description='Times mDNS socket join failed.',
+               kind=COUNTER, counts='socket_error', tags=('lan', 'mdns', 'error')),
+        Metric(name='lan_send_errors', description='Times mDNS packet send failed.',
+               kind=COUNTER, counts='send_error', tags=('lan', 'mdns', 'error')),
+    )
+
+    def __init__(
+        self,
+        keystore: Any,
+        peers: Any,
+        face: Any,
+        digest: Optional[str] = None,
+        node_class: str = 'edge',
+        clock: Optional[Callable[[], int]] = None,
+        timeout: float = 5.0,
+        node: Optional[Any] = None,
+    ) -> None:
+        super().__init__(node, clock)
+        self.ks: Any = keystore
+        self.peers: Any = peers
+        self.face: Any = face
+        self.digest: str = digest or getattr(node, 'digest', None) or descriptor_mod.DIGEST
+        self.node_class: str = node_class
+        self.timeout: float = timeout
+        self.sock: Optional[socket.socket] = None
+        self.address: Optional[str] = None
+        self._announced_at: int = 0
+        self._carried: Optional[bool] = None           # did the last packet leave the machine
+        self._seen: st.Table[str, LanPeerRecord]     # pubkey -> {host, port, at}
+        self._resolved: st.Table[str, int]            # pubkey -> when its descriptor was last fetched
+        self.learned: int = 0
+        self._up: Optional[bool] = None
+        self._lock: threading.Lock = threading.Lock()
+
+    # ---- configuration --------------------------------------------------------
+    def _cfg(self) -> Mapping[str, Any]:
+        c = self.config('lan')
+        return c if isinstance(c, dict) else {}
+
+    @property
+    def enabled(self) -> bool:
+        return bool(self.settings().enabled)
+
+    @property
+    def face_port(self) -> int:
+        try:
+            return int(getattr(self.face.server, 'port', 0) or 0)
+        except (AttributeError, TypeError, ValueError):
+            return 0
+
+    # ---- what this node says about itself -------------------------------------
+    def txt(self) -> dict[str, str]:
+        return {KEY_PUBKEY: self.ks.node_pk,
+                KEY_DIGEST: self.digest[:DIGEST_CHARS],
+                KEY_CLASS: self.node_class}
+
+    def records(self, ttl: int = mdns.TTL) -> list[mdns.Record]:
+        """The four records one advertisement is: what exists, where it is,
+        what it says about itself, and the address behind the name."""
+        inst = instance_name(self.ks.node_pk)
+        host = '%s.local' % self.ks.node_pk[:16]
+        out = [mdns.Record(SERVICE, mdns.PTR, inst, ttl),
+               mdns.Record(inst, mdns.SRV, (0, 0, self.face_port, host), ttl),
+               mdns.Record(inst, mdns.TXT, self.txt(), ttl)]
+        if self.address:
+            out.append(mdns.Record(host, mdns.A, self.address, ttl))
+        return out
+
+    # ---- lifecycle ------------------------------------------------------------
+    def start(self) -> None:
+        if not self.enabled:
+            return
+        self._open()
+
+    def _open(self) -> bool:
+        if self.sock is not None:
+            return True
+        try:
+            self.sock = mdns.open_socket()
+            self.address = mdns.local_address()
+        except OSError as e:
+            if self._up is not False:
+                self.say('socket_error', error=e)
+            self.refusals.refuse('socket', 'cannot join the group', detail={'error': str(e)}, at=self.clock())
+            self._up, self.sock = False, None
+            return False
+        if self._up is not True:
+            self.say('advertising', instance=instance_name(self.ks.node_pk), port=self.face_port)
+        self._up = True
+        return True
+
+    def stop(self) -> Any:
+        """Say goodbye before going, so a listener forgets this node at once
+        rather than holding a dead address until the record expires."""
+        if self.sock is None:
+            return None
+        self._say(mdns.build(answers=self.records(ttl=0)), 'goodbye')
+        try:
+            self.sock.close()
+        except OSError:
+            pass
+        self.sock = None
+        return [('lan', 'said goodbye')]
+
+    # ---- the tick -------------------------------------------------------------
+    _tick_runs_every = True
+
+    def tick(self, now: int) -> list[tuple[Any, ...]]:
+        if not self.enabled:
+            if self.sock is not None:
+                self.stop()
+            return []
+        if not self._open():
+            return []
+        did: list[tuple[Any, ...]] = []
+        did += self._serve(now)
+        did += self.run_every(now)
+        self._forget(now)
+        did += self._resolve(now)
+        return did
+
+    def _say(self, packet: bytes, what: str) -> bool:
+        """One packet on the group. A link that will not carry it is a
+        refusal, not a traceback.
+
+        A joined socket is not a link that forwards: a host with no route for
+        224.0.0.0/4, or a network that filters multicast, refuses the send
+        itself with ENETUNREACH or EPERM. Raised out of the tick, that would
+        cost this compartment the rest of its own work - forgetting expired
+        adverts and fetching the descriptors of peers it has already heard -
+        which is the shape of the bug where one peer that could not be
+        addressed ended the tick for every peer behind it.
+        """
+        assert self.sock is not None
+        try:
+            mdns.send(self.sock, packet)
+        except (OSError, mdns.MdnsError) as e:
+            if self._carried is not False:
+                self.say('send_error', error=e)
+            self._carried = False
+            self.refusals.refuse('send', 'the link would not carry it',
+                                 detail={'what': what, 'error': '%s: %s' % (type(e).__name__, e)},
+                                 at=self.clock())
+            return False
+        self._carried = True
+        return True
+
+    def _announce(self, now: Optional[int] = None) -> None:
+        """Say what this node is, unsolicited, and ask who else is here."""
+        if not self.enabled or not self._open() or self.sock is None:
+            return
+        now = now if now is not None else self.clock()
+        # Stamped before the sends rather than after them, which is the
+        # opposite of the handover's order and for the opposite reason: an
+        # advertisement repeats every ANNOUNCE_EVERY seconds by design, so one
+        # that did not go is picked up by the next one. Stamping after a
+        # failure would re-announce on every tick instead, which is a packet
+        # storm at a link that has already said no.
+        self._announced_at = now
+        if self.face_port:
+            self._say(mdns.build(answers=self.records()), 'announcement')
+        self._say(mdns.build(questions=[(SERVICE, mdns.PTR)]), 'browse')
+
+    def _serve(self, now: int) -> list[tuple[Any, ...]]:
+        """Answer what was asked, and note what was announced."""
+        assert self.sock is not None
+        did: list[tuple[Any, ...]] = []
+        for msg, _src in mdns.receive(self.sock):
+            if any(n.rstrip('.') == SERVICE and t in (mdns.PTR, 255) for n, t in msg.questions):
+                if self.face_port:
+                    self._say(mdns.build(answers=self.records()), 'answer')
+            if msg.is_response:
+                did += self._heard(msg, now, src=_src)
+        return did
+
+    def _heard(self, msg: mdns.Message, now: int, src: Optional[str] = None) -> list[tuple[Any, ...]]:
+        """Assemble SRV and TXT for one instance into a candidate.
+
+        src is the address the packet came from. An advert names the host
+        this node will open a WebSocket to, and until it was checked the
+        name could be anything: a multicast packet on the link could point
+        every listening node at an arbitrary address and port - a service on
+        the operator's own network that trusts its callers, or an address
+        on the internet - with this node making the connection. So the A
+        record must be the address that sent the packet (a node advertises
+        itself, from itself), and it must be one a LAN can hold: private,
+        link-local or loopback. The tests hand messages in without a source
+        and are held to the second rule alone.
+        """
+        srv: dict[str, tuple[int, str]] = {}
+        txt: dict[str, dict[str, str]] = {}
+        addr: dict[str, str] = {}
+        for rec in msg.answers:
+            if rec.rtype == mdns.SRV and isinstance(rec.data, tuple):
+                srv[rec.name.rstrip('.')] = (rec.data[2], rec.data[3].rstrip('.'))
+            elif rec.rtype == mdns.TXT and isinstance(rec.data, dict):
+                txt[rec.name.rstrip('.')] = rec.data
+            elif rec.rtype == mdns.A and isinstance(rec.data, str):
+                addr[rec.name.rstrip('.')] = rec.data
+        did: list[tuple[Any, ...]] = []
+        for inst, entries in txt.items():
+            pk = (entries.get(KEY_PUBKEY) or '').lower()
+            if not spelling.is_hex(pk, 64):
+                self.refusals.refuse('advert', 'no usable pubkey', subject=inst[:32], at=now)
+                continue
+            if pk == self.ks.node_pk:
+                continue                       # our own advert, looped back
+            theirs = entries.get(KEY_DIGEST) or ''
+            # A different digest is not a refusal (see the module note); it is
+            # recorded with the node below so the operator can see it.
+            port, host = srv.get(inst, (0, ''))
+            if not port:
+                continue                       # TXT without its SRV; the rest may follow
+            ip = addr.get(host) or self._seen.get(pk, {}).get('host')
+            if not ip:
+                continue                       # no address yet; the A record may follow
+            why = _not_dialable(ip, src)
+            if why is not None:
+                self.refusals.refuse('advert', why, subject=pk, detail={'host': ip, 'src': src}, at=now)
+                continue
+            with self._lock:
+                fresh = pk not in self._seen
+                if len(self._seen) >= SEEN_MAX and fresh:
+                    self.refusals.refuse('advert', 'more nodes on this link than it holds',
+                                         detail={'max': SEEN_MAX}, at=now)
+                    continue
+                self._seen[pk] = {'host': ip, 'port': port, 'at': now, 'digest': theirs[:DIGEST_CHARS],
+                                  'same_digest': theirs == self.digest[:DIGEST_CHARS]}
+            if fresh:
+                did.append(('lan', pk[:16], 'seen at %s:%d' % (ip, port)))
+        return did
+
+    def _resolve(self, now: int) -> list[tuple[Any, ...]]:
+        """Ask each new neighbour's own face for the descriptor it claims.
+
+        This is where an advert stops being a claim. The face serves a kind
+        11801 signed by the node key; `peers.learn` runs it through
+        `fleetmesh_core.identity.validate_descriptor` and a BIP-340 check, so a spoofed
+        advert yields either nothing or somebody else's valid descriptor, and
+        the pubkey comparison below refuses that too.
+        """
+        did: list[tuple[Any, ...]] = []
+        with self._lock:
+            todo: list[tuple[str, LanPeerRecord]] = [(pk, v) for pk, v in self._seen.items()
+                                                     if now - self._resolved.get(pk, 0) >= FORGET_AFTER]
+        for pk, where in todo[:8]:
+            self._resolved[pk] = now
+            url = 'ws://%s:%d' % (where['host'], int(where['port']))
+            try:
+                desc = descriptor_mod.resolve(pk, [url], now=now, timeout=self.timeout)
+            except Exception as e:
+                self.refusals.refuse('resolve', 'the face did not answer', subject=pk,
+                                     detail={'url': url, 'error': '%s: %s' % (type(e).__name__, e)}, at=now)
+                continue
+            if desc is None:
+                self.refusals.refuse('resolve', 'no descriptor on the advertised face',
+                                     subject=pk, detail={'url': url}, at=now)
+                continue
+            if desc.get('pubkey') != pk:
+                self.refusals.refuse('resolve', 'the face served another node\'s descriptor',
+                                     subject=pk, detail={'served': str(desc.get('pubkey'))[:16]}, at=now)
+                continue
+            if self.peers.learn(desc):
+                self.learned += 1
+                did.append(('lan', pk[:16], 'descriptor learned from its own face'))
+        return did
+
+    def _forget(self, now: int) -> None:
+        with self._lock:
+            for pk in [p for p, v in self._seen.items() if now - v['at'] > FORGET_AFTER]:
+                del self._seen[pk]
+                self._resolved.pop(pk, None)
+
+    # ---- being watched --------------------------------------------------------
+    def state(self) -> LanStateReport:
+        with self._lock:
+            seen: dict[str, LanPeerRecord] = dict(self._seen)
+        return {
+            'enabled': self.enabled,
+            'service': SERVICE,
+            # Not "the socket is open": a joined socket that cannot send is the
+            # case this compartment exists to survive, and reporting it as
+            # advertising was the lie that made the swallowed OSError invisible.
+            'advertising': self.sock is not None and bool(self.face_port) and self._carried is not False,
+            'address': self.address,
+            'port': self.face_port,
+            'digest': self.digest[:DIGEST_CHARS],
+            'seen': {pk[:16]: v for pk, v in seen.items()},
+            'learned': self.learned,
+        }
+
+    def trouble(self) -> list[str]:
+        if not self.enabled:
+            return []
+        out: list[str] = []
+        if self._up is False:
+            out.append('the mDNS group could not be joined; this node is not discoverable on its link')
+        elif self._carried is False:
+            out.append('the link will not carry a multicast packet, so nothing is advertised and '
+                       'nothing here is heard; the other bridges are unaffected')
+        elif self.sock is not None and not self.face_port:
+            out.append('no relay face port, so nothing is advertised: a neighbour would have '
+                       'nowhere to ask for the descriptor')
+        with self._lock:
+            drift = sorted(pk[:16] for pk, v in self._seen.items() if not v.get('same_digest', True))
+        if drift:
+            out.append('%d node(s) on this link were built from another schema and peer on what is '
+                       'shared: %s' % (len(drift), ', '.join(drift)))
+        return out

node/planes/transport/lan/types.py

@@ -0,0 +1,25 @@
+"""Types and records for the LAN compartment."""
+from __future__ import annotations
+
+from typing import Optional, TypedDict
+
+
+class LanPeerRecord(TypedDict, total=False):
+    """Metadata recorded for a peer seen on the LAN link."""
+    host: str
+    port: int
+    at: int
+    digest: str
+    same_digest: bool
+
+
+class LanStateReport(TypedDict, total=False):
+    """The report Lan.state() gives of itself."""
+    enabled: bool
+    service: str
+    advertising: bool
+    address: Optional[str]
+    port: int
+    digest: str
+    seen: dict[str, LanPeerRecord]
+    learned: int

node/planes/transport/link/__init__.py

@@ -0,0 +1,7 @@
+"""The relay links this node holds open, as a compartment.
+
+One-module compartment: everything is in compartment.py.
+"""
+from .compartment import Link
+
+__all__ = ['Link']