"""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
[docs]class MdnsError(ValueError):
pass
# ----------------------------------------------------------------- names ----
[docs]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)
[docs]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 ----
[docs]class Record:
__slots__ = ('name', 'rtype', 'ttl', 'data')
[docs] 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)
[docs]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'
[docs]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)
[docs]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)
[docs]class Message:
__slots__ = ('questions', 'answers', 'is_response')
[docs] 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
[docs]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 ----
[docs]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
[docs]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))
[docs]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
[docs]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()