y-reticulum 0.1.0

package/src/room.js

@@ -0,0 +1,403 @@
+/**
+ * @file room.js
+ * @description The per-room mesh for a {@link ReticulumProvider}.
+ *
+ * A Room owns the local Reticulum destination for a Yjs room, announces it for
+ * discovery, learns peers from their announces, and maintains a pairwise
+ * {@link PeerConn} (Link) to each one. Over each link it runs the Yjs sync
+ * protocol (y-protocols/sync) and awareness protocol, broadcasting local Doc
+ * and Awareness updates and applying inbound ones.
+ *
+ * To avoid the two peers both trying to open a Link to each other (WebRTC
+ * "glare"), exactly one side initiates: the peer whose destination hash is
+ * lexicographically smaller. The other simply accepts.
+ */
+
+import { Destination, DestType, toHex } from "@reticulum/core";
+import * as encoding from "lib0/encoding";
+import * as awarenessProtocol from "y-protocols/awareness";
+import * as syncProtocol from "y-protocols/sync";
+import * as Y from "yjs";
+import { getCompressionProvider } from "./compression.js";
+import { messageAwareness, messageSync, readMessage } from "./messages.js";
+import { PeerConn } from "./peer-conn.js";
+
+/**
+ * Delay after a peer Link drops before the initiator re-requests the peer's
+ * path, accelerating re-discovery beyond the periodic announce cadence. Small
+ * enough to beat the default announce interval, large enough to skip transient
+ * blips and to no-op if the peer comes back via the next announce first.
+ */
+const RECONNECT_PATH_REQUEST_DELAY_MS = 1500;
+
+/** Constant-time-ish equality for two equal-length byte arrays. */
+function bytesEqual(/** @type {Uint8Array} */ a, /** @type {Uint8Array} */ b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a[i] ^ b[i];
+  return diff === 0;
+}
+
+/**
+ * @typedef {Object} RoomCallbacks
+ * @property {(added: string[], removed: string[]) => void} onPeers
+ *   Fired whenever peers are discovered or drop off. Ids are hex link_ids.
+ * @property {(synced: boolean) => void} onSynced
+ *   Fired when the room's overall sync state changes.
+ */
+
+/**
+ * One Yjs room: a local destination that announces for discovery, plus the set
+ * of pairwise {@link PeerConn} links to discovered peers, with the Yjs sync
+ * and awareness protocols running over each link.
+ */
+export class Room {
+  /**
+   * @param {object} options
+   * @param {Y.Doc} options.doc
+   * @param {awarenessProtocol.Awareness} options.awareness
+   * @param {import("@reticulum/core").Reticulum} options.reticulum
+   * @param {import("@reticulum/core").Identity} options.identity
+   * @param {string} options.appName - Deterministic destination app-name for the room.
+   * @param {number} options.maxConns
+   * @param {number} options.announceIntervalMs
+   * @param {RoomCallbacks} options.callbacks
+   */
+  constructor({
+    doc,
+    awareness,
+    reticulum,
+    identity,
+    appName,
+    maxConns,
+    announceIntervalMs,
+    callbacks,
+  }) {
+    this.doc = doc;
+    this.awareness = awareness;
+    this.rns = reticulum;
+    this.identity = identity;
+    this.appName = appName;
+    this.maxConns = maxConns;
+    this.announceIntervalMs = announceIntervalMs;
+    this.callbacks = callbacks;
+
+    /** @type {import("@reticulum/core").Destination|null} */
+    this.dest = null;
+    /** Hex of this room destination's hash; set once connected. */
+    this.myHex = "";
+    this.connected = false;
+    /** Whether the Doc is synced with the current peer mesh. */
+    this.synced = false;
+    /** Shared bzip2 provider for Resource compression; set on connect(). */
+    this.bz2 = null;
+
+    /** @type {Map<string, PeerConn>} hex link_id → conn */
+    this.peerConns = new Map();
+    /** Destination hashes we currently have an outgoing link to (initiator side). */
+    this.linkedDestHexes = new Set();
+    /** Destination hashes with an in-flight createLink() (de-bounces announces). */
+    this.pendingInitiates = new Set();
+    /** Destination hex → scheduled reconnect path-request timer (initiator side). */
+    this.pendingPathRequests = new Map();
+
+    this._onAnnounce = this._onAnnounce.bind(this);
+    this._onLinkRequest = this._onLinkRequest.bind(this);
+    this._docUpdateHandler = this._docUpdateHandler.bind(this);
+    this._awarenessUpdateHandler = this._awarenessUpdateHandler.bind(this);
+  }
+
+  /** Creates + binds the room destination, announces, and starts discovery. */
+  async connect() {
+    if (this.connected) return;
+    this.bz2 = await getCompressionProvider();
+    this.dest = await Destination.IN(
+      this.appName,
+      DestType.SINGLE,
+      this.identity,
+      this.rns,
+    );
+    this.myHex = toHex(/** @type {Uint8Array} */ (this.dest.destinationHash));
+    // registerDestination() has bindLocalDestination commented out upstream, so
+    // bind explicitly — otherwise inbound LINKREQUEST/DATA for this destination
+    // is dropped by the transport.
+    this.rns.transport.bindLocalDestination(this.dest);
+
+    this.rns.transport.addEventListener("announce", this._onAnnounce);
+    this.dest.addEventListener("link_request", this._onLinkRequest);
+    this.doc.on("update", this._docUpdateHandler);
+    this.awareness.on("update", this._awarenessUpdateHandler);
+
+    // Delegate the periodic re-announce loop — and its §9.7 60 s floor — to
+    // @reticulum/core. startAnnouncing() fires the first announce immediately
+    // (so the destination is reachable as soon as connect() returns), then
+    // repeats at the interval to keep cached mesh paths fresh against
+    // transit-relay TTLs.
+    this.dest.startAnnouncing({ intervalMs: this.announceIntervalMs });
+
+    this.connected = true;
+  }
+
+  /** Stops announcing, tears down all peer links, and unbinds the destination. */
+  async disconnect() {
+    if (!this.connected) return;
+    this.connected = false;
+
+    this.dest?.stopAnnouncing();
+    for (const timer of this.pendingPathRequests.values()) clearTimeout(timer);
+    this.pendingPathRequests.clear();
+    this.rns.transport.removeEventListener("announce", this._onAnnounce);
+    this.dest?.removeEventListener("link_request", this._onLinkRequest);
+    this.doc.off("update", this._docUpdateHandler);
+    this.awareness.off("update", this._awarenessUpdateHandler);
+
+    // Tell peers to drop our awareness state before the links come down.
+    awarenessProtocol.removeAwarenessStates(
+      this.awareness,
+      [this.doc.clientID],
+      "disconnect",
+    );
+
+    const removed = [...this.peerConns.keys()];
+    for (const conn of this.peerConns.values()) conn.destroy();
+    this.peerConns.clear();
+    this.linkedDestHexes.clear();
+    this.pendingInitiates.clear();
+    this.synced = false;
+    if (removed.length) this.callbacks.onPeers([], removed);
+
+    if (this.dest) {
+      this.rns.transport.unbindLocalDestination(this.dest);
+      this.dest = null;
+    }
+    this.myHex = "";
+  }
+
+  /**
+   * Initiator path: a peer in our room announced. Open a Link to it unless we
+   * already have one, we're at capacity, or the glare rule says the peer should
+   * initiate instead.
+   * @param {Event} event
+   */
+  async _onAnnounce(event) {
+    if (!this.connected || !this.dest) return;
+    const detail = /** @type {any} */ (event).detail;
+    if (
+      !bytesEqual(
+        /** @type {Uint8Array} */ (detail.nameHash),
+        /** @type {Uint8Array} */ (this.dest.nameHash),
+      )
+    ) {
+      return; // different room
+    }
+    const remoteHex = toHex(/** @type {Uint8Array} */ (detail.destinationHash));
+    if (remoteHex === this.myHex) return; // self (transport filters this, but be safe)
+    if (this.peerConns.size >= this.maxConns) return;
+    if (
+      this.linkedDestHexes.has(remoteHex) ||
+      this.pendingInitiates.has(remoteHex)
+    ) {
+      return;
+    }
+    // Glare avoidance: only the lexicographically smaller destination initiates.
+    if (this.myHex > remoteHex) return;
+
+    this.pendingInitiates.add(remoteHex);
+    try {
+      const out = await Destination.OUT(
+        this.appName,
+        DestType.SINGLE,
+        detail.identity,
+        this.rns,
+      );
+      const link = await out.createLink();
+      if (!this.connected) {
+        await link.teardown();
+        return;
+      }
+      this.linkedDestHexes.add(remoteHex);
+      this._registerPeer(link, detail.destinationHash);
+    } catch {
+      // Peer vanished mid-handshake, transport error, etc. — the announce loop
+      // will retry on the next announce if the peer is still around.
+    } finally {
+      this.pendingInitiates.delete(remoteHex);
+    }
+  }
+
+  /**
+   * Responder path: a peer is opening a Link to us. Accept it.
+   * @param {Event} event
+   */
+  async _onLinkRequest(event) {
+    if (!this.connected || !this.dest) return;
+    if (this.peerConns.size >= this.maxConns) return;
+    const packet = /** @type {any} */ (event).detail.packet;
+    try {
+      const link = await this.dest.acceptLink(packet);
+      if (!this.connected) {
+        await link.teardown();
+        return;
+      }
+      this._registerPeer(link, null);
+    } catch {
+      // Handshake failed; nothing to clean up.
+    }
+  }
+
+  /**
+   * Registers a newly active peer and kicks off the Yjs sync handshake
+   * (syncStep1 + local awareness), mirroring y-webrtc's peer-on-connect path.
+   * @param {import("@reticulum/core").Link} link
+   * @param {Uint8Array|null} remoteDestHash
+   */
+  _registerPeer(link, remoteDestHash) {
+    const peer = new PeerConn({
+      link,
+      remoteDestHash,
+      bz2: this.bz2,
+      onData: (payload, p) => this._onPeerData(payload, p),
+      onClose: (p) => this._onPeerClose(p),
+    });
+    this.peerConns.set(peer.peerId, peer);
+    this.callbacks.onPeers([peer.peerId], []);
+    this._sendInitialSync(peer);
+  }
+
+  /** @param {PeerConn} peer */
+  _onPeerClose(peer) {
+    if (!this.peerConns.delete(peer.peerId)) return;
+    if (peer.remoteDestHash) {
+      const remoteHex = toHex(peer.remoteDestHash);
+      this.linkedDestHexes.delete(remoteHex);
+      // Initiator side only: the responder (remoteDestHash === null) must not
+      // re-initiate per the glare rule, so it has nothing to path-request.
+      this._scheduleReconnectPathRequest(remoteHex, peer.remoteDestHash);
+    }
+    this.callbacks.onPeers([], [peer.peerId]);
+    this._checkSynced();
+  }
+
+  /**
+   * Schedules a one-shot path request for a dropped peer so the mesh answers
+   * with a fresh path-response announce, beating the periodic announce
+   * cadence. Coalesces flaps to one in-flight request per peer and is a no-op
+   * if the peer already came back (via a normal announce) by the time it fires.
+   *
+   * @param {string} remoteHex
+   * @param {Uint8Array} remoteDestHash
+   */
+  _scheduleReconnectPathRequest(remoteHex, remoteDestHash) {
+    if (!this.connected || this.pendingPathRequests.has(remoteHex)) return;
+    const timer = setTimeout(() => {
+      this.pendingPathRequests.delete(remoteHex);
+      if (!this.connected || !this.dest) return;
+      if (this.linkedDestHexes.has(remoteHex)) return; // already re-linked
+      this.rns.transport.requestPath(remoteDestHash).catch(() => {});
+    }, RECONNECT_PATH_REQUEST_DELAY_MS);
+    this.pendingPathRequests.set(remoteHex, timer);
+  }
+
+  /**
+   * Inbound raw bytes from a peer: decode and apply, send back any reply, and
+   * mark the peer (and possibly the room) synced.
+   * @param {Uint8Array} payload
+   * @param {PeerConn} peer
+   */
+  _onPeerData(payload, peer) {
+    const reply = readMessage(
+      this.doc,
+      this.awareness,
+      payload,
+      peer,
+      this.synced,
+      () => {
+        peer.synced = true;
+        this._checkSynced();
+      },
+    );
+    if (reply) this._send(peer, reply);
+  }
+
+  /**
+   * Local Doc update → broadcast a sync `update` to every peer.
+   * @param {Uint8Array} update
+   * @param {any} _origin
+   */
+  _docUpdateHandler(update, _origin) {
+    const encoder = encoding.createEncoder();
+    encoding.writeVarUint(encoder, messageSync);
+    syncProtocol.writeUpdate(encoder, update);
+    this._broadcast(encoding.toUint8Array(encoder));
+  }
+
+  /**
+   * Local Awareness update → broadcast an awareness update to every peer.
+   * @param {{added: number[], updated: number[], removed: number[]}} changes
+   * @param {any} _origin
+   */
+  _awarenessUpdateHandler({ added, updated, removed }, _origin) {
+    const changedClients = added.concat(updated, removed);
+    const encoder = encoding.createEncoder();
+    encoding.writeVarUint(encoder, messageAwareness);
+    encoding.writeVarUint8Array(
+      encoder,
+      awarenessProtocol.encodeAwarenessUpdate(this.awareness, changedClients),
+    );
+    this._broadcast(encoding.toUint8Array(encoder));
+  }
+
+  /**
+   * Sends the initial sync handshake to a freshly connected peer: a syncStep1
+   * (requesting their state) and, if we have any, our awareness state. Both
+   * sides do this, so state flows both ways.
+   * @param {PeerConn} peer
+   */
+  _sendInitialSync(peer) {
+    const step1 = encoding.createEncoder();
+    encoding.writeVarUint(step1, messageSync);
+    syncProtocol.writeSyncStep1(step1, this.doc);
+    this._send(peer, encoding.toUint8Array(step1));
+
+    const clients = Array.from(this.awareness.getStates().keys());
+    if (clients.length > 0) {
+      const aw = encoding.createEncoder();
+      encoding.writeVarUint(aw, messageAwareness);
+      encoding.writeVarUint8Array(
+        aw,
+        awarenessProtocol.encodeAwarenessUpdate(this.awareness, clients),
+      );
+      this._send(peer, encoding.toUint8Array(aw));
+    }
+  }
+
+  /** @param {Uint8Array} bytes */
+  _broadcast(bytes) {
+    for (const peer of this.peerConns.values()) this._send(peer, bytes);
+  }
+
+  /** @param {PeerConn} peer @param {Uint8Array} bytes */
+  _send(peer, bytes) {
+    peer.send(bytes).catch(() => {});
+  }
+
+  /**
+   * Recomputes room-level sync state and emits on change. A room with no peers
+   * is *not* synced — an empty mesh carries no sync guarantee — so this flips
+   * back to `synced: false` when the last peer drops, rather than vacuously
+   * `true`.
+   */
+  _checkSynced() {
+    let synced = this.peerConns.size > 0;
+    for (const peer of this.peerConns.values()) {
+      if (!peer.synced) {
+        synced = false;
+        break;
+      }
+    }
+    if (synced !== this.synced) {
+      this.synced = synced;
+      this.callbacks.onSynced(synced);
+    }
+  }
+}

package/test/destination.test.js

@@ -0,0 +1,46 @@
+/**
+ * @file destination.test.js
+ * @description Unit tests for the room-name → destination aspect derivation.
+ *
+ * Locks the exact mapping so a refactor can't silently change room membership
+ * (two peers must derive the same aspect to find each other).
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+import { roomDestinationName } from "../src/destination.js";
+
+test("roomDestinationName is deterministic for the same input", async () => {
+  const a = await roomDestinationName("my-room");
+  const b = await roomDestinationName("my-room");
+  assert.equal(a, b);
+});
+
+test("roomDestinationName differs for different inputs", async () => {
+  const a = await roomDestinationName("room-one");
+  const b = await roomDestinationName("room-two");
+  assert.notEqual(a, b);
+});
+
+test("roomDestinationName has the expected shape", async () => {
+  const name = await roomDestinationName("anything");
+  assert.match(
+    name,
+    /^y-reticulum\.sync\.[0-9a-f]{16}$/,
+    "aspect must be y-reticulum.sync.<16 hex chars>",
+  );
+});
+
+test("roomDestinationName maps known inputs to a locked hash", async () => {
+  // First 8 bytes of SHA-256("hello") = 2cf24dba5fb0a30e. Pinning this catches
+  // accidental changes to the derivation that would fragment a room's peers.
+  assert.equal(
+    await roomDestinationName("hello"),
+    "y-reticulum.sync.2cf24dba5fb0a30e",
+  );
+  // SHA-256("y-reticulum") prefix = 2b3a1eacdb01545a
+  assert.equal(
+    await roomDestinationName("y-reticulum"),
+    "y-reticulum.sync.2b3a1eacdb01545a",
+  );
+});

package/test/large-sync.test.js

@@ -0,0 +1,67 @@
+/**
+ * @file large-sync.smoke.js
+ * @description Phase 4 smoketest — an initial Doc state larger than the link
+ * MDU syncs via a chunked, compressed Reticulum Resource.
+ *
+ * Provider A starts with a large payload already in its Doc, so the very first
+ * syncStep2 it sends (its full state) cannot fit in a single DATA packet and
+ * must travel as a Resource. Provider B receives, reassembles (decompressing if
+ * bz2 shrunk it) and ends up with identical state — exercising the oversized
+ * path end to end.
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+import { Identity } from "@reticulum/core";
+import * as Y from "yjs";
+import { ReticulumProvider } from "../src/index.js";
+import { makeLoopback, nudgeAnnounce, waitFor } from "./loopback.js";
+
+const ROOM = "y-reticulum-large-sync-smoke";
+// Comfortably larger than the default link MDU (~431 B).
+const LARGE = "x".repeat(3000);
+
+test("an initial state larger than the link MDU syncs via a Resource", {
+  timeout: 15000,
+}, async () => {
+  const { rnsA, rnsB, close } = await makeLoopback();
+  const docA = new Y.Doc();
+  const docB = new Y.Doc();
+
+  // Put the large payload in A *before* connecting, so the initial syncStep2
+  // (A's full state) must be chunked into a Resource.
+  docA.getText("t").insert(0, LARGE);
+  assert.ok(
+    Y.encodeStateAsUpdate(docA).length > 500,
+    "sanity: payload must exceed the link MDU",
+  );
+
+  const providerA = new ReticulumProvider(ROOM, docA, {
+    reticulum: rnsA,
+    identity: await Identity.generate(),
+  });
+  const providerB = new ReticulumProvider(ROOM, docB, {
+    reticulum: rnsB,
+    identity: await Identity.generate(),
+  });
+
+  /** @type {boolean} */ let bSynced = false;
+  providerB.on("synced", (/** @type {any} */ e) => {
+    if (e.synced) bSynced = true;
+  });
+
+  await providerA.connect();
+  await providerB.connect();
+  // The periodic re-announce cadence is now @reticulum/core's job (and clamped
+  // to ≥60 s), so nudge one explicit announce per side to mesh up fast.
+  await nudgeAnnounce(providerA, providerB);
+
+  // B becomes synced exactly when it receives + applies A's large step2.
+  await waitFor(() => bSynced, 10000);
+  await waitFor(() => docB.getText("t").toString() === LARGE, 5000);
+  assert.equal(docB.getText("t").toString(), LARGE);
+
+  await providerA.destroy();
+  await providerB.destroy();
+  await close();
+});

package/test/loopback.js

@@ -0,0 +1,100 @@
+/**
+ * @file loopback.js
+ * @description Shared TCP-loopback harness for smoketests: wires two
+ *   in-process Reticulum instances together (one listens, one dials) so a test
+ *   can build providers on them. Not a test file — just helpers.
+ */
+import net from "node:net";
+import { Reticulum } from "@reticulum/core";
+import { TCPClientInterface, TCPServerInterface } from "@reticulum/node";
+
+export const HOST = "127.0.0.1";
+
+/** Resolves with a free localhost TCP port (ephemeral, immediately released). */
+export function getFreePort() {
+  return new Promise((resolve, reject) => {
+    const probe = net.createServer();
+    probe.unref();
+    probe.on("error", reject);
+    probe.listen({ host: HOST, port: 0 }, () => {
+      const { port } = /** @type {net.AddressInfo} */ (probe.address());
+      probe.close(() => resolve(port));
+    });
+  });
+}
+
+/**
+ * Wires two in-process Reticulum instances over a TCP loopback (A listens, B
+ * dials) and returns them plus a `close()` that tears the link down.
+ *
+ * @returns {Promise<{
+ *   rnsA: Reticulum,
+ *   rnsB: Reticulum,
+ *   close: () => Promise<void>,
+ * }>}
+ */
+export async function makeLoopback() {
+  const port = await getFreePort();
+  const rnsA = new Reticulum();
+  const rnsB = new Reticulum();
+  // A listens. The TCPServerInterface has no writable stream itself, so do not
+  // addInterface() it — only its spawned children get wired in, marked default
+  // so the leaf can emit handshake packets via the default-interface fallback.
+  const server = new TCPServerInterface({ port });
+  await server.connect();
+  const spawned = new Promise((resolve) => {
+    server.addEventListener(
+      "connection",
+      (/** @type {any} */ event) => {
+        rnsA.addInterface(event.detail, true);
+        resolve();
+      },
+      { once: true },
+    );
+  });
+  const client = new TCPClientInterface({ host: HOST, port });
+  await client.connect();
+  rnsB.addInterface(client, true);
+  await spawned;
+  return {
+    rnsA,
+    rnsB,
+    async close() {
+      await client.disconnect().catch(() => {});
+      await server.disconnect().catch(() => {});
+    },
+  };
+}
+
+/** Polls `cond()` every 50ms until true, rejecting after `timeoutMs`. */
+export function waitFor(cond, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const deadline = Date.now() + timeoutMs;
+    const tick = () => {
+      if (cond()) return resolve(undefined);
+      if (Date.now() >= deadline) return reject(new Error("waitFor timed out"));
+      setTimeout(tick, 50);
+    };
+    tick();
+  });
+}
+
+/**
+ * Triggers one immediate re-announce from each provider's room destination.
+ *
+ * The periodic re-announce cadence is owned by @reticulum/core and clamped to
+ * the §9.7 60 s floor, so smoketests can't lean on a sub-minute tick for
+ * mutual discovery. Firing one explicit announce from each side once everyone
+ * is connected makes mesh-up fast and deterministic — covering the
+ * hash-ordering case where the second-connecting peer missed the first's
+ * immediate announce (its listener wasn't registered yet) and would otherwise
+ * have to wait for the next periodic tick.
+ *
+ * @param {...import("../src/provider.js").ReticulumProvider} providers
+ * @returns {Promise<void>}
+ */
+export async function nudgeAnnounce(...providers) {
+  for (const p of providers) {
+    await p.room?.dest?.announce();
+  }
+}