y-reticulum 0.1.0

package/test/messages.test.js

@@ -0,0 +1,167 @@
+/**
+ * @file messages.test.js
+ * @description Unit tests for the Yjs sync wire codec ({@link readMessage}).
+ *
+ * These exercise the protocol logic directly — no networking — so they're fast
+ * and pin the request/reply behaviour (syncStep1→step2, updates, awareness,
+ * queryAwareness) that the integration smoketests only cover end-to-end.
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+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 {
+  messageAwareness,
+  messageQueryAwareness,
+  messageSync,
+  readMessage,
+} from "../src/messages.js";
+
+/** Wraps `body` (written by `write`) in a tagged message frame. */
+function frame(tag, write) {
+  const enc = encoding.createEncoder();
+  encoding.writeVarUint(enc, tag);
+  write?.(enc);
+  return encoding.toUint8Array(enc);
+}
+
+test("message tags match the y-webrtc wire format", () => {
+  assert.equal(messageSync, 0);
+  assert.equal(messageAwareness, 1);
+  assert.equal(messageQueryAwareness, 3);
+});
+
+test("syncStep1 is answered with a syncStep2 carrying our state", () => {
+  // `doc` holds the state; an empty peer requests it via syncStep1.
+  const doc = new Y.Doc();
+  doc.getMap("m").set("k", "v");
+  const peer = new Y.Doc();
+
+  const step1 = frame(messageSync, (enc) =>
+    syncProtocol.writeSyncStep1(enc, peer),
+  );
+
+  let syncedCalls = 0;
+  const reply = readMessage(
+    doc,
+    new awarenessProtocol.Awareness(doc),
+    step1,
+    "origin",
+    false,
+    () => {
+      syncedCalls++;
+    },
+  );
+
+  // syncStep1 always produces a reply; it does not itself mark the room synced.
+  assert.ok(reply instanceof Uint8Array);
+  assert.equal(syncedCalls, 0);
+
+  // Applying the reply (a syncStep2) to the peer delivers the state and fires
+  // the one-shot synced callback.
+  const reply2 = readMessage(
+    peer,
+    new awarenessProtocol.Awareness(peer),
+    reply,
+    "origin",
+    false,
+    () => {
+      syncedCalls++;
+    },
+  );
+  assert.equal(reply2, null); // syncStep2 needs no reply
+  assert.equal(syncedCalls, 1);
+  assert.equal(peer.getMap("m").get("k"), "v");
+});
+
+test("the synced callback is suppressed once the room is synced", () => {
+  const doc = new Y.Doc();
+  doc.getMap("m").set("k", "v");
+  const sv = Y.encodeStateVector(new Y.Doc());
+  const step2 = frame(messageSync, (enc) =>
+    syncProtocol.writeSyncStep2(enc, doc, sv),
+  );
+
+  let syncedCalls = 0;
+  const receiver = new Y.Doc();
+  readMessage(
+    receiver,
+    new awarenessProtocol.Awareness(receiver),
+    step2,
+    "origin",
+    true, // room already synced
+    () => {
+      syncedCalls++;
+    },
+  );
+  assert.equal(syncedCalls, 0);
+});
+
+test("a sync update message applies to the doc and needs no reply", () => {
+  // Capture a real update from a doc.
+  const source = new Y.Doc();
+  /** @type {Uint8Array|undefined} */ let update;
+  source.on("update", (/** @type {Uint8Array} */ u) => {
+    update = u;
+  });
+  source.getMap("m").set("k", "v");
+  assert.ok(update);
+
+  const updateMsg = frame(messageSync, (enc) =>
+    syncProtocol.writeUpdate(enc, /** @type {Uint8Array} */ (update)),
+  );
+
+  const receiver = new Y.Doc();
+  const reply = readMessage(
+    receiver,
+    new awarenessProtocol.Awareness(receiver),
+    updateMsg,
+    "origin",
+    false,
+    () => {},
+  );
+  assert.equal(reply, null);
+  assert.equal(receiver.getMap("m").get("k"), "v");
+});
+
+test("queryAwareness is answered with an awareness update", () => {
+  const doc = new Y.Doc();
+  const awareness = new awarenessProtocol.Awareness(doc);
+  awareness.setLocalState({ user: "alice" });
+
+  const query = frame(messageQueryAwareness);
+  const reply = readMessage(doc, awareness, query, "origin", false, () => {});
+  assert.ok(reply instanceof Uint8Array);
+
+  // Applying the reply to a fresh awareness delivers the state.
+  const peerDoc = new Y.Doc();
+  const peerAwareness = new awarenessProtocol.Awareness(peerDoc);
+  const reply2 = readMessage(
+    peerDoc,
+    peerAwareness,
+    reply,
+    "origin",
+    false,
+    () => {},
+  );
+  assert.equal(reply2, null);
+  assert.deepEqual(peerAwareness.getStates().get(doc.clientID), {
+    user: "alice",
+  });
+});
+
+test("an unknown message tag yields no reply", () => {
+  const doc = new Y.Doc();
+  const reply = readMessage(
+    doc,
+    new awarenessProtocol.Awareness(doc),
+    frame(99),
+    "origin",
+    false,
+    () => {},
+  );
+  assert.equal(reply, null);
+});

package/test/peer-conn.test.js

@@ -0,0 +1,150 @@
+/**
+ * @file peer-conn.smoke.js
+ * @description Channel transport smoketest for {@link PeerConn}.
+ *
+ * Establishes a single Link between two in-process Reticulum instances (over a
+ * TCP loopback), wraps each end in a PeerConn, and verifies the two send paths:
+ *
+ *   - small payloads (≤ the channel MDU) round-trip as reliable Channel
+ *     messages, in both directions;
+ *   - a payload larger than the channel MDU is delivered via a chunked,
+ *     compressed Reticulum Resource.
+ *
+ * No Yjs machinery — this pins the PeerConn transport layer directly.
+ */
+import assert from "node:assert/strict";
+import test from "node:test";
+import { Destination, DestType, Identity } from "@reticulum/core";
+import {
+  getCompressionProvider,
+  PeerConn,
+  roomDestinationName,
+} from "../src/index.js";
+import { makeLoopback, waitFor } from "./loopback.js";
+
+const ROOM = "y-reticulum-peer-conn-smoke";
+
+/** Constant-time-ish equality for two Uint8Arrays of equal length. */
+function bytesEqual(a, 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;
+}
+
+/**
+ * Resolves with the first validated announce on `rns` whose `nameHash` matches
+ * `roomNameHash` (a peer in the same room).
+ * @param {import("@reticulum/core").Reticulum} rns
+ * @param {Uint8Array} roomNameHash
+ * @returns {Promise<{ destinationHash: Uint8Array, identity: Identity }>}
+ */
+function waitForPeer(rns, roomNameHash) {
+  return new Promise((resolve) => {
+    const listener = (/** @type {any} */ event) => {
+      const detail = event.detail;
+      if (
+        bytesEqual(/** @type {Uint8Array} */ (detail.nameHash), roomNameHash)
+      ) {
+        rns.transport.removeEventListener("announce", listener);
+        resolve({
+          destinationHash: detail.destinationHash,
+          identity: detail.identity,
+        });
+      }
+    };
+    rns.transport.addEventListener("announce", listener);
+  });
+}
+
+test("PeerConn exchanges small payloads over the Channel and large over a Resource", {
+  timeout: 15000,
+}, async () => {
+  const { rnsA, rnsB, close } = await makeLoopback();
+  const bz2 = await getCompressionProvider();
+  const appName = await roomDestinationName(ROOM);
+
+  const idA = await Identity.generate();
+  const idB = await Identity.generate();
+  const destA = await Destination.IN(appName, DestType.SINGLE, idA, rnsA);
+  rnsA.transport.bindLocalDestination(destA);
+  const destB = await Destination.IN(appName, DestType.SINGLE, idB, rnsB);
+  rnsB.transport.bindLocalDestination(destB);
+
+  // Discover each other before opening a link.
+  const aSeesB = waitForPeer(rnsA, destB.nameHash);
+  const bSeesA = waitForPeer(rnsB, destA.nameHash);
+  await destA.announce();
+  await destB.announce();
+  const peerBOnA = await aSeesB;
+  const peerAOnB = await bSeesA;
+
+  /** @type {PeerConn | null} */ let connA = null;
+  /** @type {Uint8Array[]} */ const aReceived = [];
+
+  // A is the responder: accept the link and wrap it.
+  destA.addEventListener("link_request", async (/** @type {any} */ event) => {
+    const link = await destA.acceptLink(event.detail.packet);
+    connA = new PeerConn({
+      link,
+      remoteDestHash: null,
+      bz2,
+      onData: (payload) => {
+        aReceived.push(payload);
+      },
+      onClose: () => {},
+    });
+  });
+
+  // B is the initiator: open the link and wrap it.
+  const outDest = await Destination.OUT(
+    appName,
+    DestType.SINGLE,
+    peerAOnB.identity,
+    rnsB,
+  );
+  const linkB = await outDest.createLink();
+  /** @type {Uint8Array[]} */ const bReceived = [];
+  const connB = new PeerConn({
+    link: linkB,
+    remoteDestHash: peerBOnA.destinationHash,
+    bz2,
+    onData: (payload) => {
+      bReceived.push(payload);
+    },
+    onClose: () => {},
+  });
+
+  await waitFor(() => connA != null, 5000);
+  const connALocal = /** @type {PeerConn} */ (connA);
+
+  // Sanity: the channel is wired up and its MDU is below the link MDU.
+  assert.ok(connB.channel.mdu > 0);
+  assert.ok(connB.channel.mdu < linkB.mdu);
+
+  // --- Small payloads round-trip over the Channel (both directions) -----
+  const small = new Uint8Array([1, 2, 3, 4, 5]);
+  await connB.send(small); // B → A
+  await waitFor(() => aReceived.length >= 1, 5000);
+  assert.deepEqual(aReceived[0], small);
+
+  await connALocal.send(small); // A → B
+  await waitFor(() => bReceived.length >= 1, 5000);
+  assert.deepEqual(bReceived[0], small);
+
+  // --- A payload larger than the channel MDU travels as a Resource ------
+  const large = new Uint8Array(2000);
+  for (let i = 0; i < large.length; i++) large[i] = i & 0xff;
+  assert.ok(
+    large.length > connB.channel.mdu,
+    "fixture must exceed channel MDU",
+  );
+  await connB.send(large); // B → A
+  await waitFor(() => aReceived.some((p) => p.length === large.length), 8000);
+  const gotLarge = aReceived.find((p) => p.length === large.length);
+  assert.deepEqual(gotLarge, large);
+
+  connALocal.destroy();
+  connB.destroy();
+  await close();
+});

package/test/provider.smoke.js

@@ -0,0 +1,146 @@
+/**
+ * @file provider.smoke.js
+ * @description Phase 2 smoketest — the {@link ReticulumProvider} connection
+ * lifecycle and peer mesh, without any Yjs sync yet.
+ *
+ * Two providers, each on its own in-process Reticulum instance wired over a TCP
+ * loopback, connect to the same room. Both should announce, discover each
+ * other, establish exactly one Link between them (via the glare-avoidance
+ * rule), and each emit a `peers` event with the other added.
+ */
+
+import assert from "node:assert/strict";
+import net from "node:net";
+import test from "node:test";
+import { Identity, Reticulum } from "@reticulum/core";
+import { TCPClientInterface, TCPServerInterface } from "@reticulum/node";
+import * as Y from "yjs";
+import { ReticulumProvider } from "../src/index.js";
+import { nudgeAnnounce } from "./loopback.js";
+
+const ROOM = "y-reticulum-provider-smoke";
+const HOST = "127.0.0.1";
+
+/** Resolves with a free localhost TCP port (ephemeral, immediately released). */
+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.
+ */
+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`. */
+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();
+  });
+}
+
+test("two providers discover each other and form a single Link", {
+  timeout: 15000,
+}, async () => {
+  const { rnsA, rnsB, close } = await makeLoopback();
+  const idA = await Identity.generate();
+  const idB = await Identity.generate();
+
+  const providerA = new ReticulumProvider(ROOM, new Y.Doc(), {
+    reticulum: rnsA,
+    identity: idA,
+  });
+  const providerB = new ReticulumProvider(ROOM, new Y.Doc(), {
+    reticulum: rnsB,
+    identity: idB,
+  });
+
+  /** @type {string[]} */
+  const aPeers = [];
+  /** @type {string[]} */
+  const bPeers = [];
+  let aConnected = false;
+  let bConnected = false;
+  providerA.on("status", (/** @type {any} */ e) => {
+    aConnected = aConnected || e.connected;
+  });
+  providerB.on("status", (/** @type {any} */ e) => {
+    bConnected = bConnected || e.connected;
+  });
+  providerA.on("peers", (/** @type {any} */ e) => aPeers.push(...e.added));
+  providerB.on("peers", (/** @type {any} */ e) => bPeers.push(...e.added));
+
+  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);
+
+  // Both should connect, discover exactly one peer, and hold one Link.
+  await waitFor(() => aPeers.length >= 1 && bPeers.length >= 1, 10000);
+  assert.ok(aConnected, "provider A never reported connected");
+  assert.ok(bConnected, "provider B never reported connected");
+  assert.equal(
+    /** @type {any} */ (providerA).room.peerConns.size,
+    1,
+    "provider A should hold exactly one peer Link",
+  );
+  assert.equal(
+    /** @type {any} */ (providerB).room.peerConns.size,
+    1,
+    "provider B should hold exactly one peer Link",
+  );
+
+  await providerA.destroy();
+  await providerB.destroy();
+  await close();
+});

package/test/reannounce.test.js

@@ -0,0 +1,62 @@
+/**
+ * @file reannounce.smoke.js
+ * @description Smoketest for delegating the periodic re-announce loop to
+ * @reticulum/core's `Destination.startAnnouncing` / `stopAnnouncing`.
+ *
+ * The cadence (and its §9.7 60 s floor) is the library's responsibility now;
+ * this test just locks in that y-reticulum wires it up correctly: the loop is
+ * running while a room is connected, the requested interval is forwarded (and
+ * clamped to the floor), and the loop is stopped again on disconnect.
+ */
+
+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 } from "./loopback.js";
+
+const ROOM = "y-reticulum-reannounce-smoke";
+
+test("connect starts the periodic re-announce loop; disconnect stops it", async () => {
+  const { rnsA, close } = await makeLoopback();
+  const provider = new ReticulumProvider(ROOM, new Y.Doc(), {
+    reticulum: rnsA,
+    identity: await Identity.generate(),
+  });
+
+  await provider.connect();
+  // @ts-expect-error -- reaching into the room for a white-box check
+  const dest = provider.room.dest;
+  assert.equal(dest.isAnnouncing(), true, "loop should run while connected");
+
+  // disconnect() nulls Room.dest, so capture the reference first; the object
+  // outlives teardown and its timer must have been cleared.
+  await provider.disconnect();
+  assert.equal(dest.isAnnouncing(), false, "loop should stop on disconnect");
+
+  await provider.destroy();
+  await close();
+});
+
+test("announceIntervalMs is forwarded and clamped to the 60s floor", async () => {
+  const { rnsA, close } = await makeLoopback();
+  const provider = new ReticulumProvider(ROOM, new Y.Doc(), {
+    reticulum: rnsA,
+    identity: await Identity.generate(),
+    announceIntervalMs: 5_000, // below the §9.7 floor
+  });
+
+  await provider.connect();
+  // @ts-expect-error -- reaching into the room for a white-box check
+  const { dest } = provider.room;
+  assert.equal(dest.isAnnouncing(), true);
+  assert.equal(
+    dest.announceIntervalMs,
+    60_000,
+    "sub-floor interval must be clamped to 60s",
+  );
+
+  await provider.destroy();
+  await close();
+});

package/test/reconnect.test.js

@@ -0,0 +1,117 @@
+/**
+ * @file reconnect.smoke.js
+ * @description Phase 5 smoketest — a dropped peer Link is re-established.
+ *
+ * Two providers sync over a TCP loopback. We then tear down the underlying
+ * Link from one side (simulating a peer/link drop): each provider should emit
+ * `peers removed` and flip `synced` to false (it lost its last peer). The
+ * initiator — the peer with the lexicographically smaller destination hash, per
+ * the glare-avoidance rule — then re-discovers the responder (its scheduled
+ * path request beats the periodic announce) and opens a fresh Link, so both
+ * emit `peers added` again, re-run the sync handshake, and end up synced. An
+ * edit made after reconnect must still flow across — proving a live Link, not a
+ * stale one.
+ */
+
+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-reconnect-smoke";
+
+/**
+ * @param {ReticulumProvider} p
+ * @returns {Map<string, unknown>}
+ */
+function peerConns(p) {
+  return /** @type {any} */ (p).room.peerConns;
+}
+
+test("a dropped Link is re-established and re-synced", {
+  timeout: 20000,
+}, async () => {
+  const { rnsA, rnsB, close } = await makeLoopback();
+  const docA = new Y.Doc();
+  const docB = new Y.Doc();
+
+  const providerA = new ReticulumProvider(ROOM, docA, {
+    reticulum: rnsA,
+    identity: await Identity.generate(),
+    // Leave the announce cadence at the default (60 s floor, owned by
+    // @reticulum/core). Initial mesh-up is nudged explicitly below; the
+    // post-drop reconnect must therefore be driven by the scheduled path
+    // request (1.5 s), not the announce cadence — which is what this test
+    // exercises.
+  });
+  const providerB = new ReticulumProvider(ROOM, docB, {
+    reticulum: rnsB,
+    identity: await Identity.generate(),
+  });
+
+  /** @type {boolean[]} */ const syncedA = [];
+  /** @type {boolean[]} */ const syncedB = [];
+  providerA.on("synced", (/** @type {any} */ e) => syncedA.push(e.synced));
+  providerB.on("synced", (/** @type {any} */ e) => syncedB.push(e.synced));
+
+  /** @type {string[]} */ const aAdded = [];
+  /** @type {string[]} */ const aRemoved = [];
+  /** @type {string[]} */ const bAdded = [];
+  /** @type {string[]} */ const bRemoved = [];
+  providerA.on("peers", (/** @type {any} */ e) => {
+    aAdded.push(...e.added);
+    aRemoved.push(...e.removed);
+  });
+  providerB.on("peers", (/** @type {any} */ e) => {
+    bAdded.push(...e.added);
+    bRemoved.push(...e.removed);
+  });
+
+  await providerA.connect();
+  await providerB.connect();
+  // Nudge initial discovery (the periodic cadence is ≥60 s); the post-drop
+  // reconnect below is then driven by the scheduled path request.
+  await nudgeAnnounce(providerA, providerB);
+
+  // --- Initial mesh: each discovers exactly one peer and syncs -----------
+  await waitFor(() => aAdded.length >= 1 && bAdded.length >= 1, 10000);
+  await waitFor(() => peerConns(providerA).size === 1, 10000);
+  await waitFor(() => peerConns(providerB).size === 1, 10000);
+  await waitFor(() => syncedA.includes(true) && syncedB.includes(true), 10000);
+
+  // Sanity: an edit flows A → B before we break anything.
+  docA.getMap("m").set("first", "yes");
+  await waitFor(() => docB.getMap("m").get("first") === "yes", 5000);
+
+  // --- Drop the Link from A's side; both ends get `close` ---------------
+  const connA = [...peerConns(providerA).values()][0];
+  await /** @type {any} */ (connA).link.teardown();
+
+  // Both observe the peer leaving and drop to zero peers.
+  await waitFor(() => aRemoved.length >= 1 && bRemoved.length >= 1, 10000);
+  await waitFor(() => peerConns(providerA).size === 0, 10000);
+  await waitFor(() => peerConns(providerB).size === 0, 10000);
+
+  // Losing the last peer must flip synced to false (the zero-peer rule).
+  await waitFor(() => syncedA.includes(false) && syncedB.includes(false), 5000);
+
+  // --- The initiator re-establishes the Link ----------------------------
+  await waitFor(() => aAdded.length >= 2 && bAdded.length >= 2, 10000);
+  await waitFor(() => peerConns(providerA).size === 1, 10000);
+  await waitFor(() => peerConns(providerB).size === 1, 10000);
+
+  // Re-sync handshake completes; final synced state is true on both.
+  await waitFor(() => syncedA[syncedA.length - 1] === true, 10000);
+  await waitFor(() => syncedB[syncedB.length - 1] === true, 10000);
+
+  // An edit made *after* reconnect flows A → B — live sync, not a stale link.
+  docA.getMap("m").set("after", "reconnect");
+  await waitFor(() => docB.getMap("m").get("after") === "reconnect", 5000);
+  assert.equal(docB.getMap("m").get("after"), "reconnect");
+
+  await providerA.destroy();
+  await providerB.destroy();
+  await close();
+});