@vuer-ai/vuer-rtc-server 0.1.1

package/tests/e2e/packet-loss.test.ts

@@ -0,0 +1,229 @@
+/**
+ * E2E: CRDT convergence with simulated packet loss and retries.
+ *
+ * Verifies that clients can recover from dropped messages by
+ * re-sending unacknowledged operations.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from '@jest/globals';
+import { createTestServer, type TestServer } from './helpers/createTestServer.js';
+import { waitFor, waitForConvergence, assertGraphsEqual } from './helpers/assertions.js';
+import type { GraphStore } from '@vuer-ai/vuer-rtc';
+
+// ── Helpers ───────────────────────────────────────────────────
+
+function seedGraph(store: GraphStore): void {
+  store.edit({
+    otype: 'node.insert',
+    key: '',
+    path: 'children',
+    value: { key: 'scene', tag: 'Scene', name: 'Scene' },
+  });
+  store.edit({
+    otype: 'node.insert',
+    key: 'scene',
+    path: 'children',
+    value: {
+      key: 'cube-1',
+      tag: 'Mesh',
+      name: 'Cube',
+      position: [0, 0, 0],
+      opacity: 1,
+    },
+  });
+  store.commit('seed scene');
+}
+
+// ── Tests ─────────────────────────────────────────────────────
+
+describe('packet-loss', () => {
+  let ts: TestServer;
+
+  beforeEach(() => {
+    ts = createTestServer();
+  });
+
+  afterEach(() => {
+    ts.close();
+  });
+
+  // ── 1. Retry recovers dropped message ───────────────────────
+
+  it('retry recovers a dropped message', async () => {
+    // Client A has 100% drop rate — all initial sends are lost
+    const clientA = ts.connectClient('room-1', 'session-a', { dropRate: 1.0 });
+    const clientB = ts.connectClient('room-1', 'session-b');
+
+    seedGraph(clientA.store);
+
+    // Give some time — B should NOT receive the seed
+    await new Promise((r) => setTimeout(r, 100));
+    expect(Object.keys(clientB.store.getState().graph.nodes).length).toBe(0);
+
+    // Disable drop and retry
+    clientA.disableDrop();
+    clientA.retryUnacked();
+
+    await waitForConvergence([clientA.store, clientB.store], 3000);
+
+    const graphA = clientA.store.getState().graph;
+    const graphB = clientB.store.getState().graph;
+    assertGraphsEqual(graphA, graphB);
+    expect(Object.keys(graphB.nodes).length).toBeGreaterThan(0);
+  });
+
+  // ── 2. Partial loss with retry ──────────────────────────────
+
+  it('recovers from partial packet loss with retry', async () => {
+    // 50% drop rate — some messages get through, some don't
+    const clientA = ts.connectClient('room-1', 'session-a', { dropRate: 0.5 });
+    const clientB = ts.connectClient('room-1', 'session-b', { dropRate: 0.5 });
+
+    // Seed with no drop so both clients have the base graph
+    clientA.disableDrop();
+    clientB.disableDrop();
+    seedGraph(clientA.store);
+    await waitForConvergence([clientA.store, clientB.store], 3000);
+
+    // Re-enable drop and make edits
+    clientA.disableDrop(); // A sends reliably
+    // B has 50% drop — acks from server may be lost
+
+    clientA.store.edit({
+      otype: 'vector3.set',
+      key: 'cube-1',
+      path: 'position',
+      value: [10, 20, 30],
+    });
+    clientA.store.commit('move cube');
+
+    clientB.store.edit({
+      otype: 'number.set',
+      key: 'cube-1',
+      path: 'opacity',
+      value: 0.7,
+    });
+    clientB.store.commit('set opacity');
+
+    // Wait a bit for any messages that got through
+    await new Promise((r) => setTimeout(r, 200));
+
+    // Disable drop and retry all unacked
+    clientA.disableDrop();
+    clientB.disableDrop();
+    clientA.retryUnacked();
+    clientB.retryUnacked();
+
+    await waitForConvergence([clientA.store, clientB.store], 3000);
+
+    const graphA = clientA.store.getState().graph;
+    const graphB = clientB.store.getState().graph;
+    assertGraphsEqual(graphA, graphB);
+  });
+
+  // ── 3. Multiple retries needed ──────────────────────────────
+
+  it('converges after multiple retry rounds', async () => {
+    const clientA = ts.connectClient('room-1', 'session-a', { dropRate: 0.8 });
+    const clientB = ts.connectClient('room-1', 'session-b');
+
+    seedGraph(clientA.store);
+
+    // Retry up to 5 times — with 80% drop, ~99.97% chance at least one gets through
+    for (let attempt = 0; attempt < 5; attempt++) {
+      clientA.retryUnacked();
+      await new Promise((r) => setTimeout(r, 50));
+    }
+
+    // Disable drop for final retry
+    clientA.disableDrop();
+    clientA.retryUnacked();
+
+    await waitForConvergence([clientA.store, clientB.store], 3000);
+
+    const graphB = clientB.store.getState().graph;
+    expect(Object.keys(graphB.nodes).length).toBeGreaterThan(0);
+  });
+
+  // ── 4. Lost ack — message delivered but ack dropped ─────────
+
+  it('handles lost ack gracefully', async () => {
+    const clientA = ts.connectClient('room-1', 'session-a');
+    const clientB = ts.connectClient('room-1', 'session-b');
+
+    seedGraph(clientA.store);
+    await waitForConvergence([clientA.store, clientB.store], 3000);
+
+    // Make an edit and commit
+    clientA.store.edit({
+      otype: 'vector3.set',
+      key: 'cube-1',
+      path: 'position',
+      value: [99, 99, 99],
+    });
+    const msg = clientA.store.commit('move cube');
+    expect(msg).not.toBeNull();
+
+    // Wait for B to receive the broadcast
+    await waitFor(() => {
+      const pos = clientB.store.getState().graph.nodes['cube-1']?.position;
+      return Array.isArray(pos) && pos[0] === 99;
+    });
+
+    // Simulate: the message was delivered but A never got the ack.
+    // A's journal entry is still unacked. Re-sending should be idempotent.
+    clientA.retryUnacked();
+    await new Promise((r) => setTimeout(r, 100));
+
+    // Both should still be converged — the duplicate was handled
+    const graphA = clientA.store.getState().graph;
+    const graphB = clientB.store.getState().graph;
+    assertGraphsEqual(graphA, graphB);
+    expect(graphA.nodes['cube-1'].position).toEqual([99, 99, 99]);
+  });
+
+  // ── 5. Packet loss + latency combined ──────────────────────
+
+  it('converges with combined latency and packet loss', async () => {
+    const clientA = ts.connectClient('room-1', 'session-a', { latencyMs: 50, dropRate: 0.3 });
+    const clientB = ts.connectClient('room-1', 'session-b', { latencyMs: 50, dropRate: 0.3 });
+
+    // Seed reliably first
+    clientA.disableDrop();
+    clientB.disableDrop();
+    seedGraph(clientA.store);
+    await waitForConvergence([clientA.store, clientB.store], 5000);
+
+    // Re-enable conditions
+    // Use a fixed seed approach: set dropRate back
+    // For deterministic behavior, we just retry until converged
+
+    clientA.store.edit({
+      otype: 'number.add',
+      key: 'cube-1',
+      path: 'opacity',
+      value: 5,
+    });
+    clientA.store.commit('add opacity');
+
+    // Retry loop until convergence or timeout
+    const start = Date.now();
+    let converged = false;
+    while (!converged && Date.now() - start < 5000) {
+      clientA.retryUnacked();
+      clientB.retryUnacked();
+      await new Promise((r) => setTimeout(r, 200));
+      try {
+        const gA = clientA.store.getState().graph;
+        const gB = clientB.store.getState().graph;
+        assertGraphsEqual(gA, gB);
+        converged = true;
+      } catch {
+        // Not yet converged, retry
+      }
+    }
+
+    expect(converged).toBe(true);
+    expect(clientA.store.getState().graph.nodes['cube-1'].opacity).toBe(6);
+  });
+});

package/tests/e2e/relay.test.ts

@@ -0,0 +1,255 @@
+/**
+ * E2E: Basic message relay through the server.
+ *
+ * Verifies that the RTCServer correctly relays CRDTMessages
+ * between clients, assigns sequence numbers, deduplicates
+ * retries, and fans out to all room members.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from '@jest/globals';
+import { createTestServer, type TestServer } from './helpers/createTestServer.js';
+import { waitFor, waitForConvergence, assertGraphsEqual } from './helpers/assertions.js';
+import type { GraphStore, CRDTMessage } from '@vuer-ai/vuer-rtc';
+
+// ── Helpers ───────────────────────────────────────────────────
+
+/** Insert a scene root + a mesh node so property ops have a target. */
+function seedGraph(store: GraphStore): void {
+  store.edit({
+    otype: 'node.insert',
+    key: '',
+    path: 'children',
+    value: { key: 'scene', tag: 'Scene', name: 'Scene' },
+  });
+  store.edit({
+    otype: 'node.insert',
+    key: 'scene',
+    path: 'children',
+    value: {
+      key: 'cube-1',
+      tag: 'Mesh',
+      name: 'Cube',
+      position: [0, 0, 0],
+      opacity: 1,
+    },
+  });
+  store.commit('seed scene');
+}
+
+// ── Tests ─────────────────────────────────────────────────────
+
+describe('relay', () => {
+  let ts: TestServer;
+
+  beforeEach(() => {
+    ts = createTestServer();
+  });
+
+  afterEach(() => {
+    ts.close();
+  });
+
+  // ── 1. Sequential edits ────────────────────────────────────
+
+  it('two clients: sequential edits', async () => {
+    const clientA = ts.connectClient('room-1', 'session-a');
+    const clientB = ts.connectClient('room-1', 'session-b');
+
+    // Client A seeds the graph
+    seedGraph(clientA.store);
+
+    // Wait for Client B to receive the seed
+    await waitForConvergence([clientA.store, clientB.store]);
+
+    // Client A edits position
+    clientA.store.edit({
+      otype: 'vector3.set',
+      key: 'cube-1',
+      path: 'position',
+      value: [1, 2, 3],
+    });
+    clientA.store.commit('move cube');
+
+    // Wait for convergence
+    await waitForConvergence([clientA.store, clientB.store]);
+
+    // Both graphs should be identical
+    const graphA = clientA.store.getState().graph;
+    const graphB = clientB.store.getState().graph;
+    assertGraphsEqual(graphA, graphB);
+
+    // Verify the position value is correct
+    expect(graphB.nodes['cube-1'].position).toEqual([1, 2, 3]);
+  });
+
+  // ── 2. Ack after commit ────────────────────────────────────
+
+  it('client receives ack after commit', async () => {
+    const clientA = ts.connectClient('room-1', 'session-a');
+
+    // Seed the graph
+    seedGraph(clientA.store);
+
+    // Wait for the seed commit to be acked
+    await waitFor(() => {
+      const journal = clientA.store.getState().journal;
+      return journal.length > 0 && journal.every((e) => e.ack);
+    });
+
+    // Now make an edit and commit
+    clientA.store.edit({
+      otype: 'vector3.set',
+      key: 'cube-1',
+      path: 'position',
+      value: [5, 5, 5],
+    });
+    const msg = clientA.store.commit('set position');
+    expect(msg).not.toBeNull();
+
+    // Wait for the ack to arrive
+    await waitFor(() => {
+      const journal = clientA.store.getState().journal;
+      const entry = journal.find((e) => e.msg.id === msg!.id);
+      return entry !== undefined && entry.ack === true;
+    });
+
+    // The entry should now be acked
+    const journal = clientA.store.getState().journal;
+    const entry = journal.find((e) => e.msg.id === msg!.id);
+    expect(entry).toBeDefined();
+    expect(entry!.ack).toBe(true);
+  });
+
+  // ── 3. Deduplication ───────────────────────────────────────
+
+  it('server deduplicates messages', async () => {
+    const clientA = ts.connectClient('room-1', 'session-a');
+    const clientB = ts.connectClient('room-1', 'session-b');
+
+    // Seed the graph from A
+    seedGraph(clientA.store);
+    await waitForConvergence([clientA.store, clientB.store]);
+
+    // Client A edits and commits
+    clientA.store.edit({
+      otype: 'vector3.set',
+      key: 'cube-1',
+      path: 'position',
+      value: [10, 20, 30],
+    });
+    const msg = clientA.store.commit('move cube');
+    expect(msg).not.toBeNull();
+
+    // Wait for Client B to receive the original broadcast
+    await waitFor(() => {
+      const pos = clientB.store.getState().graph.nodes['cube-1']?.position;
+      return Array.isArray(pos) && pos[0] === 10;
+    });
+
+    // Snapshot B's journal length after receiving the first copy
+    const journalLenBefore = clientB.store.getState().journal.length;
+
+    // Simulate a duplicate: rebroadcast the same message via the broker.
+    // The client-side CRDT layer should ignore it (journal dedup in onRemoteMessage).
+    await ts.broker.publish('room-1', { ...msg!, serverSeq: 999 });
+
+    // Give time for any duplicate delivery to settle
+    await new Promise((resolve) => setTimeout(resolve, 100));
+
+    // Client B's journal should not have grown — the duplicate was dropped
+    const journalLenAfter = clientB.store.getState().journal.length;
+    expect(journalLenAfter).toBe(journalLenBefore);
+  });
+
+  // ── 4. Monotonic server sequence numbers ───────────────────
+
+  it('messages have monotonic server sequence numbers', async () => {
+    const clientA = ts.connectClient('room-1', 'session-a');
+    const clientB = ts.connectClient('room-1', 'session-b');
+
+    // Seed the graph
+    seedGraph(clientA.store);
+    await waitForConvergence([clientA.store, clientB.store]);
+
+    // Collect serverSeq values from messages that Client B receives
+    const serverSeqs: number[] = [];
+    const originalReceive = clientB.store.receive.bind(clientB.store);
+    clientB.store.receive = (msg: CRDTMessage) => {
+      // The SequencedMessage carries serverSeq
+      if ((msg as any).serverSeq !== undefined) {
+        serverSeqs.push((msg as any).serverSeq);
+      }
+      originalReceive(msg);
+    };
+
+    // Client A sends multiple commits
+    clientA.store.edit({
+      otype: 'vector3.set',
+      key: 'cube-1',
+      path: 'position',
+      value: [1, 0, 0],
+    });
+    clientA.store.commit('move 1');
+
+    clientA.store.edit({
+      otype: 'vector3.set',
+      key: 'cube-1',
+      path: 'position',
+      value: [2, 0, 0],
+    });
+    clientA.store.commit('move 2');
+
+    clientA.store.edit({
+      otype: 'vector3.set',
+      key: 'cube-1',
+      path: 'position',
+      value: [3, 0, 0],
+    });
+    clientA.store.commit('move 3');
+
+    // Wait for all three to arrive at B
+    await waitFor(() => serverSeqs.length >= 3);
+
+    // Verify monotonically increasing
+    for (let i = 1; i < serverSeqs.length; i++) {
+      expect(serverSeqs[i]).toBeGreaterThan(serverSeqs[i - 1]);
+    }
+  });
+
+  // ── 5. Three clients in the same room ──────────────────────
+
+  it('three clients in the same room', async () => {
+    const clientA = ts.connectClient('room-1', 'session-a');
+    const clientB = ts.connectClient('room-1', 'session-b');
+    const clientC = ts.connectClient('room-1', 'session-c');
+
+    // Client A seeds the graph
+    seedGraph(clientA.store);
+
+    // Wait for all three to converge on the seed
+    await waitForConvergence([clientA.store, clientB.store, clientC.store]);
+
+    // Client A edits position
+    clientA.store.edit({
+      otype: 'vector3.set',
+      key: 'cube-1',
+      path: 'position',
+      value: [7, 8, 9],
+    });
+    clientA.store.commit('move cube');
+
+    // Wait for all three to converge
+    await waitForConvergence([clientA.store, clientB.store, clientC.store]);
+
+    // All three should have the same graph
+    const graphA = clientA.store.getState().graph;
+    const graphB = clientB.store.getState().graph;
+    const graphC = clientC.store.getState().graph;
+    assertGraphsEqual(graphA, graphB);
+    assertGraphsEqual(graphA, graphC);
+
+    // Verify the value
+    expect(graphB.nodes['cube-1'].position).toEqual([7, 8, 9]);
+    expect(graphC.nodes['cube-1'].position).toEqual([7, 8, 9]);
+  });
+});