@robota-sdk/agent-transport-webrtc 3.0.0-beta.100

package/src/mesh-mdns.ts

@@ -0,0 +1,406 @@
+/**
+ * Finding peer devices on the local network with multicast DNS service discovery (RFC 6762/6763),
+ * without telling the network whose devices they are or how many.
+ *
+ * - The service type is generic and names no product.
+ * - Every instance name is a pairwise tag for `dir(self → peer)` in the current epoch, so only that
+ *   peer recognises it, and it changes every epoch. The host name the records point at is random per
+ *   epoch rather than the machine's name.
+ * - The instance count is padded with random tags to a fixed step, so the answer does not reveal
+ *   how many devices this one pairs with. The padding and host name hold for the whole epoch, so
+ *   comparing two answers from one epoch does not tell the real tags from the padding either.
+ *
+ * A lookup asks for the service, keeps the instances whose name is one of the peer's tags for the
+ * adjacent epochs, and yields the answering address with the advertised port. That is a candidate
+ * only: anyone on the network can answer too, and gains nothing, because the peer is admitted by the
+ * device handshake or not at all. Since anyone can answer, a lookup does not stop at the first match:
+ * it keeps listening a little longer, and takes only a few answers from any one address, so neither
+ * an early answer nor many answers from one host can stand in for the peer's own.
+ */
+import { createRequire } from 'node:module';
+import { networkInterfaces } from 'node:os';
+
+import { rendezvousEpoch, RENDEZVOUS_EPOCH_MS } from '@robota-sdk/agent-remote-pairing';
+
+import type { IMeshCandidate, IMeshCandidateSource, IMeshPeerRoute } from './mesh-discovery.js';
+
+/** The DNS-SD service type. Generic on purpose: it must not name the product. */
+export const MESH_MDNS_SERVICE = '_rdv._tcp.local';
+/** Instance counts are padded up to a multiple of this. */
+export const MESH_MDNS_PAD_STEP = 8;
+/** Bytes of a pairwise tag used as an instance name (hex-encoded). */
+const INSTANCE_TAG_BYTES = 16;
+const RECORD_TTL_S = 120;
+const DEFAULT_LOOKUP_TIMEOUT_MS = 1_000;
+/** After the first match, how much longer a lookup listens for more answers. */
+const DEFAULT_ANSWER_GRACE_MS = 200;
+/** Candidates one lookup yields. */
+const MAX_LOOKUP_CANDIDATES = 8;
+/** Candidates one lookup takes from one answering address. */
+const MAX_CANDIDATES_PER_ADDRESS = 2;
+/** Answers go out at most this often; queries in between share the next one (RFC 6762 §6). */
+const DEFAULT_MIN_ANSWER_INTERVAL_MS = 500;
+
+/** A DNS resource record, in the shape `multicast-dns` reads and writes. */
+export interface IMdnsRecord {
+  readonly name: string;
+  readonly type: string;
+  readonly ttl?: number;
+  readonly data?: unknown;
+}
+
+export interface IMdnsQuestion {
+  readonly name: string;
+  readonly type: string;
+}
+
+export interface IMdnsPacket {
+  readonly questions?: readonly IMdnsQuestion[];
+  readonly answers?: readonly IMdnsRecord[];
+  readonly additionals?: readonly IMdnsRecord[];
+}
+
+export interface IMdnsRemote {
+  readonly address: string;
+}
+
+/** The slice of a `multicast-dns` instance this module drives. */
+export interface IMdnsTransport {
+  on(
+    event: 'query' | 'response',
+    listener: (packet: IMdnsPacket, rinfo: IMdnsRemote) => void,
+  ): void;
+  on(event: 'error' | 'warning', listener: (error: Error) => void): void;
+  removeListener(
+    event: 'response',
+    listener: (packet: IMdnsPacket, rinfo: IMdnsRemote) => void,
+  ): void;
+  query(packet: { readonly questions: readonly IMdnsQuestion[] }): void;
+  respond(packet: {
+    readonly answers: readonly IMdnsRecord[];
+    readonly additionals?: readonly IMdnsRecord[];
+  }): void;
+  destroy(): void;
+}
+
+export interface IMeshMdnsOptions {
+  /** Default: a `multicast-dns` socket on the standard group and port. */
+  readonly createTransport?: () => IMdnsTransport;
+  /** This device's addresses for the A/AAAA records. Default: its non-internal interfaces. */
+  readonly addresses?: () => readonly string[];
+  readonly lookupTimeoutMs?: number;
+  /** After the first match, how much longer a lookup listens (within `lookupTimeoutMs`). */
+  readonly answerGraceMs?: number;
+  readonly minAnswerIntervalMs?: number;
+  /** mDNS cannot run (e.g. the port is unavailable): the other candidate sources still do. */
+  readonly onError?: (error: Error) => void;
+  readonly now?: () => number;
+}
+
+function defaultTransport(): IMdnsTransport {
+  const requireFrom = createRequire(import.meta.url);
+  // eslint-disable-next-line @typescript-eslint/no-require-imports -- resolved only when mDNS is used, so importing the package opens no socket
+  const create = requireFrom('multicast-dns') as () => IMdnsTransport;
+  return create();
+}
+
+/** This device's non-internal interface addresses (no IPv6 link-local). */
+export function localInterfaceAddresses(): string[] {
+  const out: string[] = [];
+  for (const entries of Object.values(networkInterfaces())) {
+    for (const entry of entries ?? []) {
+      if (entry.internal) continue;
+      if (
+        entry.family === 'IPv4' ||
+        (entry.family === 'IPv6' && !entry.address.startsWith('fe80'))
+      ) {
+        out.push(entry.address);
+      }
+    }
+  }
+  return out;
+}
+
+function randomHex(bytes: number): string {
+  const out = new Uint8Array(bytes);
+  globalThis.crypto.getRandomValues(out);
+  return Buffer.from(out).toString('hex');
+}
+
+function instanceLabel(tag: Uint8Array): string {
+  return Buffer.from(tag.subarray(0, INSTANCE_TAG_BYTES)).toString('hex');
+}
+
+/** How many instances `count` real ones are announced as. */
+export function paddedInstanceCount(count: number): number {
+  return Math.max(MESH_MDNS_PAD_STEP, Math.ceil(count / MESH_MDNS_PAD_STEP) * MESH_MDNS_PAD_STEP);
+}
+
+function sameName(a: string, b: string): boolean {
+  return a.toLowerCase() === b.toLowerCase();
+}
+
+export class MeshMdns implements IMeshCandidateSource {
+  private transport?: IMdnsTransport;
+  private routes: readonly IMeshPeerRoute[] = [];
+  private port?: number;
+  private records?: { readonly answers: IMdnsRecord[]; readonly additionals: IMdnsRecord[] };
+  private instances = new Set<string>();
+  private timer?: ReturnType<typeof setTimeout>;
+  private generation = 0;
+  private closed = false;
+  /** This epoch's padding labels and host name. */
+  private epochCover?: {
+    readonly epoch: number;
+    readonly padding: string[];
+    readonly target: string;
+  };
+  /** What was last announced, to announce again only when it changes. */
+  private announced?: string;
+  private lastAnswer?: number;
+  private answerTimer?: ReturnType<typeof setTimeout>;
+
+  public constructor(private readonly options: IMeshMdnsOptions = {}) {}
+
+  private now(): number {
+    return (this.options.now ?? Date.now)();
+  }
+
+  /** The transport, created on first use. `undefined` once it failed or the source is closed. */
+  private open(): IMdnsTransport | undefined {
+    if (this.closed) return undefined;
+    if (this.transport !== undefined) return this.transport;
+    try {
+      const transport = (this.options.createTransport ?? defaultTransport)();
+      transport.on('query', (packet: IMdnsPacket) => this.onQuery(packet));
+      transport.on('error', (error: Error) => this.options.onError?.(error));
+      this.transport = transport;
+      return transport;
+    } catch (error) {
+      this.closed = true;
+      this.options.onError?.(error instanceof Error ? error : new Error(String(error)));
+      return undefined;
+    }
+  }
+
+  /** Announce this device to `routes`' peers, as a signaling endpoint on `port`. */
+  public advertise(routes: readonly IMeshPeerRoute[], port: number): Promise<void> {
+    this.routes = routes;
+    this.port = port;
+    return this.rebuild();
+  }
+
+  private async rebuild(): Promise<void> {
+    const generation = ++this.generation;
+    const port = this.port;
+    if (this.closed || port === undefined) return;
+    const epoch = rendezvousEpoch(this.now());
+    const tags = await Promise.all(
+      this.routes.map((route) => route.rendezvous.tag('mdns', 'outbound', epoch)),
+    );
+    if (generation !== this.generation || this.closed) return;
+    if (this.epochCover?.epoch !== epoch) {
+      this.epochCover = { epoch, padding: [], target: `${randomHex(8)}.local` };
+    }
+    const { padding, target } = this.epochCover;
+    const needed = paddedInstanceCount(tags.length) - tags.length;
+    while (padding.length < needed) padding.push(randomHex(INSTANCE_TAG_BYTES));
+    const labels = [...tags.map(instanceLabel), ...padding.slice(0, needed)].sort();
+    const signature = JSON.stringify([epoch, port, labels]);
+    const answers: IMdnsRecord[] = labels.map((label) => ({
+      name: MESH_MDNS_SERVICE,
+      type: 'PTR',
+      ttl: RECORD_TTL_S,
+      data: `${label}.${MESH_MDNS_SERVICE}`,
+    }));
+    const additionals: IMdnsRecord[] = [];
+    for (const label of labels) {
+      const name = `${label}.${MESH_MDNS_SERVICE}`;
+      additionals.push(
+        { name, type: 'SRV', ttl: RECORD_TTL_S, data: { priority: 0, weight: 0, port, target } },
+        { name, type: 'TXT', ttl: RECORD_TTL_S, data: [] },
+      );
+    }
+    for (const address of (this.options.addresses ?? localInterfaceAddresses)()) {
+      additionals.push({
+        name: target,
+        type: address.includes(':') ? 'AAAA' : 'A',
+        ttl: RECORD_TTL_S,
+        data: address,
+      });
+    }
+    this.records = { answers, additionals };
+    this.instances = new Set(labels.map((label) => `${label}.${MESH_MDNS_SERVICE}`.toLowerCase()));
+    this.schedule(epoch);
+    if (signature === this.announced) return;
+    this.announced = signature;
+    // An unsolicited announcement, so peers already browsing hear of the new names at once.
+    this.open()?.respond(this.records);
+  }
+
+  private schedule(epoch: number): void {
+    if (this.timer !== undefined) clearTimeout(this.timer);
+    const delay = Math.max(0, (epoch + 1) * RENDEZVOUS_EPOCH_MS - this.now());
+    this.timer = setTimeout(() => {
+      // allow-fallback: a failed rebuild keeps the last epoch's names; lookups try adjacent epochs
+      this.rebuild().catch(() => undefined);
+    }, delay);
+    this.timer.unref?.();
+  }
+
+  private onQuery(packet: IMdnsPacket): void {
+    const records = this.records;
+    if (records === undefined || this.closed) return;
+    const asked = (packet.questions ?? []).some(
+      (q) =>
+        (sameName(q.name, MESH_MDNS_SERVICE) && (q.type === 'PTR' || q.type === 'ANY')) ||
+        this.instances.has(q.name.toLowerCase()),
+    );
+    if (asked) this.answer();
+  }
+
+  /** Answer now, or once the interval since the last answer has passed; queries meanwhile share it. */
+  private answer(): void {
+    if (this.answerTimer !== undefined) return;
+    const interval = this.options.minAnswerIntervalMs ?? DEFAULT_MIN_ANSWER_INTERVAL_MS;
+    const wait = this.lastAnswer === undefined ? 0 : this.lastAnswer + interval - this.now();
+    const send = (): void => {
+      this.answerTimer = undefined;
+      if (this.closed || this.records === undefined) return;
+      this.lastAnswer = this.now();
+      this.transport?.respond(this.records);
+    };
+    if (wait <= 0) {
+      send();
+      return;
+    }
+    this.answerTimer = setTimeout(send, wait);
+    this.answerTimer.unref?.();
+  }
+
+  public async candidates(
+    peer: IMeshPeerRoute,
+    signal: AbortSignal,
+  ): Promise<readonly IMeshCandidate[]> {
+    const transport = this.open();
+    if (transport === undefined || signal.aborted) return [];
+    const epoch = rendezvousEpoch(this.now());
+    const wanted = new Set(
+      (await peer.rendezvous.lookupTags('mdns', epoch)).map(
+        (tag) => `${instanceLabel(tag)}.${MESH_MDNS_SERVICE}`,
+      ),
+    );
+    if (signal.aborted || this.closed) return [];
+    return new Promise<readonly IMeshCandidate[]>((resolve) => {
+      const found: IMeshCandidate[] = [];
+      let grace: ReturnType<typeof setTimeout> | undefined;
+      const finish = (): void => {
+        clearTimeout(timer);
+        clearTimeout(grace);
+        signal.removeEventListener('abort', finish);
+        transport.removeListener('response', onResponse);
+        resolve(found);
+      };
+      const onResponse = (packet: IMdnsPacket, rinfo: IMdnsRemote): void => {
+        const records = [...(packet.answers ?? []), ...(packet.additionals ?? [])];
+        for (const ptr of records) {
+          if (ptr.type !== 'PTR' || !sameName(ptr.name, MESH_MDNS_SERVICE)) continue;
+          if (typeof ptr.data !== 'string' || !wanted.has(ptr.data.toLowerCase())) continue;
+          const srv = records.find((r) => r.type === 'SRV' && sameName(r.name, ptr.data as string));
+          const port = (srv?.data as { port?: unknown } | undefined)?.port;
+          if (typeof port !== 'number' || !Number.isInteger(port) || port <= 0 || port > 65_535) {
+            continue;
+          }
+          // The address the answer came from: the peer's own records could name any address.
+          // No one address takes more than a few of the places, so one host cannot fill them all.
+          const fromAddress = found.filter((c) => c.host === rinfo.address);
+          if (
+            found.length < MAX_LOOKUP_CANDIDATES &&
+            fromAddress.length < MAX_CANDIDATES_PER_ADDRESS &&
+            !fromAddress.some((c) => c.port === port)
+          ) {
+            found.push({ host: rinfo.address, port });
+          }
+        }
+        if (found.length === 0 || grace !== undefined) return;
+        grace = setTimeout(finish, this.options.answerGraceMs ?? DEFAULT_ANSWER_GRACE_MS);
+        grace.unref?.();
+      };
+      const timer = setTimeout(finish, this.options.lookupTimeoutMs ?? DEFAULT_LOOKUP_TIMEOUT_MS);
+      timer.unref?.();
+      signal.addEventListener('abort', finish, { once: true });
+      transport.on('response', onResponse);
+      transport.query({ questions: [{ name: MESH_MDNS_SERVICE, type: 'PTR' }] });
+    });
+  }
+
+  public close(): void {
+    this.closed = true;
+    this.generation += 1;
+    if (this.timer !== undefined) clearTimeout(this.timer);
+    if (this.answerTimer !== undefined) clearTimeout(this.answerTimer);
+    this.transport?.destroy();
+    this.transport = undefined;
+  }
+}
+
+export interface IInMemoryMdnsBus {
+  /** A transport on this bus whose answers come from `address`. */
+  transport(address: string): IMdnsTransport;
+  /** Every packet answered on the bus, in order. */
+  readonly responses: readonly IMdnsPacket[];
+}
+
+/**
+ * An in-process multicast group — for tests and loopback only. A query reaches every member,
+ * itself included, as multicast loops back; an answer reaches every member with the answering
+ * member's address. Packets cross as JSON and are delivered on a microtask, as a network would.
+ */
+export function createInMemoryMdnsBus(): IInMemoryMdnsBus {
+  type TListener = (packet: IMdnsPacket, rinfo: IMdnsRemote) => void;
+  interface IMember {
+    readonly address: string;
+    readonly queries: Set<TListener>;
+    readonly responses: Set<TListener>;
+  }
+  const members = new Set<IMember>();
+  const responses: IMdnsPacket[] = [];
+  const broadcast = (
+    from: IMember,
+    packet: IMdnsPacket,
+    pick: (member: IMember) => Set<TListener>,
+  ): void => {
+    const copy = JSON.parse(JSON.stringify(packet)) as IMdnsPacket;
+    queueMicrotask(() => {
+      for (const member of members) {
+        for (const listener of pick(member)) listener(copy, { address: from.address });
+      }
+    });
+  };
+  return {
+    responses,
+    transport(address) {
+      const self: IMember = { address, queries: new Set(), responses: new Set() };
+      members.add(self);
+      return {
+        on(event: string, listener: TListener) {
+          if (event === 'query') self.queries.add(listener);
+          if (event === 'response') self.responses.add(listener);
+        },
+        removeListener(_event, listener) {
+          self.responses.delete(listener);
+        },
+        query(packet) {
+          broadcast(self, packet, (m) => m.queries);
+        },
+        respond(packet) {
+          responses.push(JSON.parse(JSON.stringify(packet)) as IMdnsPacket);
+          broadcast(self, packet, (m) => m.responses);
+        },
+        destroy() {
+          members.delete(self);
+        },
+      } as IMdnsTransport;
+    },
+  };
+}