@vuer-ai/vuer-rtc-server 0.2.0 → 0.2.2

package/tests/journal/journal-rle.test.ts

@@ -0,0 +1,511 @@
+/**
+ * Unit tests for RLE (Run-Length Encoding) journal compression
+ *
+ * Tests:
+ * 1. RLE encode/decode roundtrip
+ * 2. CRDT semantics preservation
+ * 3. Compression ratio measurement
+ * 4. Edge cases (empty, single message, all same agent, etc.)
+ */
+
+import { describe, it, expect } from '@jest/globals';
+import type { CRDTMessage } from '@vuer-ai/vuer-rtc';
+import {
+  encodeJournalRLE,
+  decodeJournalRLE,
+  verifyRLEIntegrity,
+  getCompressionStats,
+  type RLEEncodedJournal,
+} from '../../src/journal/JournalRLE.js';
+
+/**
+ * Helper: Create a test message
+ */
+function createTestMessage(
+  id: string,
+  sessionId: string,
+  lamportTime: number,
+  timestamp: number,
+  ops: any[] = []
+): CRDTMessage {
+  return {
+    id,
+    sessionId,
+    clock: { [sessionId]: lamportTime },
+    lamportTime,
+    timestamp,
+    ops: ops.length > 0 ? ops : [{
+      key: 'cube-1',
+      otype: 'vector3.set',
+      path: 'position',
+      value: [lamportTime, 0, 0],
+    }],
+  };
+}
+
+describe('JournalRLE - Run-Length Encoding', () => {
+  describe('Basic encode/decode roundtrip', () => {
+    it('should encode and decode empty journal', () => {
+      const messages: CRDTMessage[] = [];
+      const encoded = encodeJournalRLE(messages);
+      const decoded = decodeJournalRLE(encoded);
+
+      expect(decoded).toEqual([]);
+      expect(encoded.totalMessages).toBe(0);
+      expect(encoded.segments).toHaveLength(0);
+    });
+
+    it('should encode and decode single message', () => {
+      const messages = [
+        createTestMessage('msg-1', 'session-1', 1, 1000),
+      ];
+
+      const encoded = encodeJournalRLE(messages);
+      const decoded = decodeJournalRLE(encoded);
+
+      expect(decoded).toEqual(messages);
+      expect(encoded.totalMessages).toBe(1);
+      expect(encoded.segments).toHaveLength(1);
+      expect(encoded.segments[0].agentId).toBe('session-1');
+      expect(encoded.segments[0].count).toBe(1);
+    });
+
+    it('should encode consecutive messages from same agent', () => {
+      const messages = [
+        createTestMessage('msg-1', 'session-1', 1, 1000),
+        createTestMessage('msg-2', 'session-1', 2, 1001),
+        createTestMessage('msg-3', 'session-1', 3, 1002),
+      ];
+
+      const encoded = encodeJournalRLE(messages);
+      const decoded = decodeJournalRLE(encoded);
+
+      expect(decoded).toEqual(messages);
+      expect(encoded.totalMessages).toBe(3);
+      expect(encoded.segments).toHaveLength(1);
+      expect(encoded.segments[0].count).toBe(3);
+      expect(encoded.segments[0].messages).toHaveLength(3);
+    });
+
+    it('should segment messages from different agents', () => {
+      const messages = [
+        createTestMessage('msg-1', 'session-1', 1, 1000),
+        createTestMessage('msg-2', 'session-1', 2, 1001),
+        createTestMessage('msg-3', 'session-2', 3, 1002),
+        createTestMessage('msg-4', 'session-2', 4, 1003),
+        createTestMessage('msg-5', 'session-1', 5, 1004),
+      ];
+
+      const encoded = encodeJournalRLE(messages);
+      const decoded = decodeJournalRLE(encoded);
+
+      expect(decoded).toEqual(messages);
+      expect(encoded.totalMessages).toBe(5);
+      expect(encoded.segments).toHaveLength(3);
+
+      // First segment: session-1, 2 messages
+      expect(encoded.segments[0].agentId).toBe('session-1');
+      expect(encoded.segments[0].count).toBe(2);
+
+      // Second segment: session-2, 2 messages
+      expect(encoded.segments[1].agentId).toBe('session-2');
+      expect(encoded.segments[1].count).toBe(2);
+
+      // Third segment: session-1, 1 message
+      expect(encoded.segments[2].agentId).toBe('session-1');
+      expect(encoded.segments[2].count).toBe(1);
+    });
+
+    it('should handle many agents with alternating pattern', () => {
+      const messages = Array.from({ length: 10 }, (_, i) => {
+        const sessionId = i % 2 === 0 ? 'session-1' : 'session-2';
+        return createTestMessage(`msg-${i}`, sessionId, i, 1000 + i);
+      });
+
+      const encoded = encodeJournalRLE(messages);
+      const decoded = decodeJournalRLE(encoded);
+
+      expect(decoded).toEqual(messages);
+      expect(encoded.totalMessages).toBe(10);
+      expect(encoded.segments).toHaveLength(10); // Each alternates, so 10 segments
+    });
+  });
+
+  describe('CRDT semantics preservation', () => {
+    it('should preserve vector clocks', () => {
+      const messages = [
+        {
+          id: 'msg-1',
+          sessionId: 'session-1',
+          clock: { 'session-1': 5, 'session-2': 3 },
+          lamportTime: 8,
+          timestamp: 1000,
+          ops: [],
+        },
+        {
+          id: 'msg-2',
+          sessionId: 'session-1',
+          clock: { 'session-1': 6, 'session-2': 3 },
+          lamportTime: 9,
+          timestamp: 1001,
+          ops: [],
+        },
+      ] as CRDTMessage[];
+
+      const encoded = encodeJournalRLE(messages);
+      const decoded = decodeJournalRLE(encoded);
+
+      expect(decoded[0].clock).toEqual({ 'session-1': 5, 'session-2': 3 });
+      expect(decoded[1].clock).toEqual({ 'session-1': 6, 'session-2': 3 });
+    });
+
+    it('should preserve lamport timestamps', () => {
+      const messages = [
+        createTestMessage('msg-1', 'session-1', 1, 1000),
+        createTestMessage('msg-2', 'session-1', 2, 2000),
+        createTestMessage('msg-3', 'session-2', 3, 3000),
+      ];
+
+      const encoded = encodeJournalRLE(messages);
+      const decoded = decodeJournalRLE(encoded);
+
+      expect(decoded[0].lamportTime).toBe(1);
+      expect(decoded[1].lamportTime).toBe(2);
+      expect(decoded[2].lamportTime).toBe(3);
+    });
+
+    it('should preserve operation semantics', () => {
+      const ops = [
+        { key: 'cube-1', otype: 'vector3.set', path: 'position', value: [1, 2, 3] },
+        { key: 'cube-2', otype: 'vector3.add', path: 'position', value: [0.5, 0.5, 0.5] },
+      ];
+
+      const messages = [
+        createTestMessage('msg-1', 'session-1', 1, 1000, [ops[0]]),
+        createTestMessage('msg-2', 'session-1', 2, 1001, [ops[1]]),
+      ];
+
+      const encoded = encodeJournalRLE(messages);
+      const decoded = decodeJournalRLE(encoded);
+
+      expect(JSON.stringify(decoded[0].ops)).toBe(JSON.stringify([ops[0]]));
+      expect(JSON.stringify(decoded[1].ops)).toBe(JSON.stringify([ops[1]]));
+    });
+
+    it('should verify integrity after roundtrip', () => {
+      const messages = [
+        createTestMessage('msg-1', 'session-1', 1, 1000),
+        createTestMessage('msg-2', 'session-1', 2, 1001),
+        createTestMessage('msg-3', 'session-2', 3, 1002),
+      ];
+
+      const encoded = encodeJournalRLE(messages);
+      const verification = verifyRLEIntegrity(messages, encoded);
+
+      expect(verification.valid).toBe(true);
+      expect(verification.errors).toHaveLength(0);
+    });
+  });
+
+  describe('Compression ratio measurement', () => {
+    it('should compute compression ratio for small journal', () => {
+      const messages = [
+        createTestMessage('msg-1', 'session-1', 1, 1000),
+        createTestMessage('msg-2', 'session-1', 2, 1001),
+        createTestMessage('msg-3', 'session-1', 3, 1002),
+      ];
+
+      const encoded = encodeJournalRLE(messages);
+      const stats = getCompressionStats(encoded);
+
+      // Same-agent runs reduce redundancy, but JSON overhead is significant
+      // RLE is more effective with binary encoding or larger journals
+      expect(stats.segmentCount).toBe(1);
+      expect(stats.avgMessagesPerSegment).toBeCloseTo(3, 0);
+      expect(stats.originalBytes).toBeGreaterThan(0);
+      expect(stats.compressedBytes).toBeGreaterThan(0);
+    });
+
+    it('should compute compression ratio for large homogeneous journal', () => {
+      // 100 messages from same agent
+      const messages = Array.from({ length: 100 }, (_, i) =>
+        createTestMessage(`msg-${i}`, 'session-1', i, 1000 + i)
+      );
+
+      const encoded = encodeJournalRLE(messages);
+      const stats = getCompressionStats(encoded);
+
+      // RLE groups same-agent messages into single segment
+      expect(stats.segmentCount).toBe(1);
+      expect(stats.avgMessagesPerSegment).toBeCloseTo(100, 0);
+      // With JSON encoding, savings are modest; binary codecs would show better ratios
+      expect(stats.originalBytes).toBeGreaterThan(0);
+    });
+
+    it('should have low compression for heterogeneous journal', () => {
+      // 100 messages alternating between 10 agents
+      const messages = Array.from({ length: 100 }, (_, i) => {
+        const sessionId = `session-${i % 10}`;
+        return createTestMessage(`msg-${i}`, sessionId, i, 1000 + i);
+      });
+
+      const encoded = encodeJournalRLE(messages);
+      const stats = getCompressionStats(encoded);
+
+      // Many small segments = poor compression (but still valid)
+      expect(stats.ratio).toBeLessThan(1.5);
+      expect(stats.segmentCount).toBe(100); // Each message is own segment
+    });
+
+    it('should report accurate size metrics', () => {
+      const messages = [
+        createTestMessage('msg-1', 'session-1', 1, 1000),
+        createTestMessage('msg-2', 'session-1', 2, 1001),
+      ];
+
+      const encoded = encodeJournalRLE(messages);
+      const stats = getCompressionStats(encoded);
+
+      expect(stats.originalBytes).toBeGreaterThan(0);
+      expect(stats.compressedBytes).toBeGreaterThan(0);
+      expect(stats.savedBytes).toBe(stats.originalBytes - stats.compressedBytes);
+      expect(stats.percentSaved).toBeCloseTo(
+        (stats.savedBytes / stats.originalBytes) * 100,
+        1
+      );
+    });
+  });
+
+  describe('Error handling', () => {
+    it('should detect decode errors on corrupted data', () => {
+      const corrupted: RLEEncodedJournal = {
+        version: 1,
+        totalMessages: 5,
+        segments: [
+          {
+            agentId: 'session-1',
+            count: 5,
+            messages: [
+              createTestMessage('msg-1', 'session-2', 1, 1000), // Wrong sessionId!
+            ] as CRDTMessage[],
+          },
+        ],
+        metadata: { compressionRatio: 1, originalSize: 0, compressedSize: 0 },
+      };
+
+      expect(() => decodeJournalRLE(corrupted)).toThrow(
+        /sessionId mismatch/
+      );
+    });
+
+    it('should detect count mismatch', () => {
+      const corrupted: RLEEncodedJournal = {
+        version: 1,
+        totalMessages: 10, // Claim 10
+        segments: [
+          {
+            agentId: 'session-1',
+            count: 2,
+            messages: [
+              createTestMessage('msg-1', 'session-1', 1, 1000),
+              createTestMessage('msg-2', 'session-1', 2, 1001),
+            ] as CRDTMessage[],
+          },
+        ],
+        metadata: { compressionRatio: 1, originalSize: 0, compressedSize: 0 },
+      };
+
+      expect(() => decodeJournalRLE(corrupted)).toThrow(
+        /expected 10 messages.*got 2/
+      );
+    });
+
+    it('should report integrity errors', () => {
+      const original = [
+        createTestMessage('msg-1', 'session-1', 1, 1000),
+      ];
+
+      const corrupted: RLEEncodedJournal = {
+        version: 1,
+        totalMessages: 1,
+        segments: [
+          {
+            agentId: 'session-1',
+            count: 1,
+            messages: [
+              {
+                ...original[0],
+                id: 'msg-corrupted', // Wrong ID
+              },
+            ] as CRDTMessage[],
+          },
+        ],
+        metadata: { compressionRatio: 1, originalSize: 0, compressedSize: 0 },
+      };
+
+      const verification = verifyRLEIntegrity(original, corrupted);
+      expect(verification.valid).toBe(false);
+      expect(verification.errors.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe('Edge cases', () => {
+    it('should handle messages with complex operations', () => {
+      const complexOps = [
+        {
+          key: 'node-1',
+          otype: 'node.insert',
+          path: 'children',
+          value: {
+            key: 'child-1',
+            tag: 'Mesh',
+            name: 'Cube',
+            position: [0, 0, 0],
+          },
+        },
+        {
+          key: '_meta',
+          otype: 'meta.undo',
+          path: '_meta',
+          targetMsgId: 'msg-1',
+        },
+      ];
+
+      const messages = [
+        createTestMessage('msg-1', 'session-1', 1, 1000, [complexOps[0]]),
+        createTestMessage('msg-2', 'session-1', 2, 1001, [complexOps[1]]),
+      ];
+
+      const encoded = encodeJournalRLE(messages);
+      const decoded = decodeJournalRLE(encoded);
+      const verification = verifyRLEIntegrity(messages, encoded);
+
+      expect(decoded).toEqual(messages);
+      expect(verification.valid).toBe(true);
+    });
+
+    it('should handle multiple operations per message', () => {
+      const multiOpMsg: CRDTMessage = {
+        id: 'msg-1',
+        sessionId: 'session-1',
+        clock: { 'session-1': 1 },
+        lamportTime: 1,
+        timestamp: 1000,
+        ops: [
+          { key: 'node-1', otype: 'vector3.set', path: 'position', value: [1, 2, 3] },
+          { key: 'node-2', otype: 'vector3.set', path: 'position', value: [4, 5, 6] },
+          { key: 'node-3', otype: 'vector3.set', path: 'position', value: [7, 8, 9] },
+        ],
+      };
+
+      const messages = [multiOpMsg];
+      const encoded = encodeJournalRLE(messages);
+      const decoded = decodeJournalRLE(encoded);
+      const verification = verifyRLEIntegrity(messages, encoded);
+
+      expect(decoded[0].ops).toHaveLength(3);
+      expect(verification.valid).toBe(true);
+    });
+
+    it('should handle large timestamps', () => {
+      const largeTimestamp = Number.MAX_SAFE_INTEGER / 1000;
+      const messages = [
+        createTestMessage('msg-1', 'session-1', 1, largeTimestamp),
+      ];
+
+      const encoded = encodeJournalRLE(messages);
+      const decoded = decodeJournalRLE(encoded);
+
+      expect(decoded[0].timestamp).toBe(largeTimestamp);
+    });
+  });
+
+  describe('Real-world scenarios', () => {
+    it('should compress a realistic editing session', () => {
+      // Simulate: User A does 10 edits, then User B does 5, then A does 10 more
+      const messages: CRDTMessage[] = [];
+
+      // User A: 10 edits
+      for (let i = 0; i < 10; i++) {
+        messages.push(
+          createTestMessage(
+            `msg-a-${i}`,
+            'session-a',
+            i,
+            1000 + i,
+            [{ key: 'cube-1', otype: 'vector3.add', path: 'position', value: [0.1, 0, 0] }]
+          )
+        );
+      }
+
+      // User B: 5 edits
+      for (let i = 0; i < 5; i++) {
+        messages.push(
+          createTestMessage(
+            `msg-b-${i}`,
+            'session-b',
+            i,
+            1010 + i,
+            [{ key: 'cube-2', otype: 'vector3.add', path: 'position', value: [0, 0.1, 0] }]
+          )
+        );
+      }
+
+      // User A: 10 more edits
+      for (let i = 10; i < 20; i++) {
+        messages.push(
+          createTestMessage(
+            `msg-a-${i}`,
+            'session-a',
+            i,
+            1020 + i,
+            [{ key: 'cube-1', otype: 'vector3.add', path: 'position', value: [0.1, 0, 0] }]
+          )
+        );
+      }
+
+      const encoded = encodeJournalRLE(messages);
+      const stats = getCompressionStats(encoded);
+
+      expect(encoded.segments).toHaveLength(3);
+      // RLE reduces redundancy by grouping same-agent messages
+      // Real compression gains manifest with binary codecs or network serialization
+      expect(stats.segmentCount).toBe(3);
+
+      const verification = verifyRLEIntegrity(messages, encoded);
+      expect(verification.valid).toBe(true);
+    });
+
+    it('should compress collaborative session with concurrent edits', () => {
+      // Simulate: 5 users concurrently editing
+      const messages: CRDTMessage[] = [];
+      let msgId = 0;
+      let lamportTime = 0;
+
+      for (let round = 0; round < 10; round++) {
+        for (let user = 1; user <= 5; user++) {
+          messages.push(
+            createTestMessage(
+              `msg-${msgId++}`,
+              `session-${user}`,
+              lamportTime++,
+              1000 + round * 5 + user
+            )
+          );
+        }
+      }
+
+      const encoded = encodeJournalRLE(messages);
+      const stats = getCompressionStats(encoded);
+
+      // Many concurrent users = many segments (alternating pattern)
+      expect(encoded.segments.length).toBeGreaterThan(1);
+      // JSON overhead dominates with many small segments
+      // Real benefit appears with binary protocols or storage backends
+      expect(stats.segmentCount).toBeGreaterThan(1);
+
+      const verification = verifyRLEIntegrity(messages, encoded);
+      expect(verification.valid).toBe(true);
+    });
+  });
+});