"""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 fleetmesh_node.protocols.nostr import descriptor as descriptor_mod
from fleetmesh_node.compartment import stores as st
from fleetmesh_node.channels import Channel, TROUBLE
from fleetmesh_node.metrics import COUNTER, Metric
from fleetmesh_node.transport import mdns
from fleetmesh_node.compartment import Command, Compartment, Every, Need
from fleetmesh_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
[docs]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
[docs]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')),
)
[docs] 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 -------------------------------------
[docs] def txt(self) -> dict[str, str]:
return {KEY_PUBKEY: self.ks.node_pk,
KEY_DIGEST: self.digest[:DIGEST_CHARS],
KEY_CLASS: self.node_class}
[docs] 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 ------------------------------------------------------------
[docs] 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
[docs] 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
[docs] 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 --------------------------------------------------------
[docs] 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,
}
[docs] 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