pixelweaver 0.1.0

package/src/lib/sync/ws-client.test.ts

@@ -0,0 +1,604 @@
+/**
+ * Unit tests for the WebSocket client.
+ *
+ * These test the unit-testable logic (ID generation, backoff calculation,
+ * message serialization, pending timeouts) without requiring an actual
+ * WebSocket server. Full integration tests are deferred to E2E.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { generateMessageId, calculateBackoff, WebSocketClient } from './ws-client.js';
+
+/**
+ * Structural shape for the messages produced by the WebSocket client.
+ * Used only to narrow JSON.parse results in these tests.
+ */
+interface ParsedCommand {
+  type: string;
+  plugin?: string;
+  params?: Record<string, unknown>;
+  id?: string;
+  timestamp?: number;
+}
+interface ParsedMessage {
+  type: string;
+  id: string;
+  command?: ParsedCommand;
+  error?: string;
+}
+function parseMessage(raw: string): ParsedMessage {
+  return JSON.parse(raw) as ParsedMessage;
+}
+
+// --- generateMessageId ---
+
+describe('generateMessageId', () => {
+  it('should return a non-empty string', () => {
+    const id = generateMessageId();
+    expect(typeof id).toBe('string');
+    expect(id.length).toBeGreaterThan(0);
+  });
+
+  it('should return unique IDs on successive calls', () => {
+    const ids = new Set(Array.from({ length: 100 }, () => generateMessageId()));
+    expect(ids.size).toBe(100);
+  });
+
+  it('should return valid UUID format', () => {
+    const id = generateMessageId();
+    // UUID v4 pattern: 8-4-4-4-12 hex digits
+    expect(id).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/);
+  });
+});
+
+// --- calculateBackoff ---
+
+describe('calculateBackoff', () => {
+  it('should return 1000ms for attempt 0', () => {
+    expect(calculateBackoff(0)).toBe(1000);
+  });
+
+  it('should return 2000ms for attempt 1', () => {
+    expect(calculateBackoff(1)).toBe(2000);
+  });
+
+  it('should return 4000ms for attempt 2', () => {
+    expect(calculateBackoff(2)).toBe(4000);
+  });
+
+  it('should return 8000ms for attempt 3', () => {
+    expect(calculateBackoff(3)).toBe(8000);
+  });
+
+  it('should return 16000ms for attempt 4', () => {
+    expect(calculateBackoff(4)).toBe(16000);
+  });
+
+  it('should cap at 30000ms (MAX_BACKOFF)', () => {
+    expect(calculateBackoff(5)).toBe(30000); // 1000 * 2^5 = 32000 -> capped at 30000
+    expect(calculateBackoff(10)).toBe(30000);
+    expect(calculateBackoff(100)).toBe(30000);
+  });
+
+  it('should produce strictly non-decreasing values', () => {
+    let prev = 0;
+    for (let i = 0; i < 20; i++) {
+      const current = calculateBackoff(i);
+      expect(current).toBeGreaterThanOrEqual(prev);
+      prev = current;
+    }
+  });
+});
+
+// --- Message serialization ---
+
+describe('message serialization', () => {
+  it('should produce correct JSON for a command message', () => {
+    // Simulate what sendCommand builds internally
+    const command = {
+      type: 'draw_pixel',
+      plugin: 'builtin/pencil',
+      version: '1.0.0',
+      params: { x: 10, y: 20, color: '#ff0000' },
+      id: 'cmd-id-123',
+      timestamp: 1700000000000,
+    };
+
+    const message = {
+      type: 'command' as const,
+      id: 'msg-id-456',
+      command,
+    };
+
+    const json = parseMessage(JSON.stringify(message));
+
+    expect(json.type).toBe('command');
+    expect(json.id).toBe('msg-id-456');
+    expect(json.command?.type).toBe('draw_pixel');
+    expect(json.command?.plugin).toBe('builtin/pencil');
+    expect(json.command?.params?.["x"]).toBe(10);
+    expect(json.command?.id).toBe('cmd-id-123');
+    expect(json.command?.timestamp).toBe(1700000000000);
+  });
+
+  it('should produce correct JSON for a sync_request message', () => {
+    const message = {
+      type: 'sync_request' as const,
+      id: 'msg-sync-1',
+    };
+
+    const json = parseMessage(JSON.stringify(message));
+    expect(json.type).toBe('sync_request');
+    expect(json.id).toBe('msg-sync-1');
+    expect(Object.keys(json)).toHaveLength(2);
+  });
+
+  it('should produce correct JSON for an undo message', () => {
+    const message = {
+      type: 'undo' as const,
+      id: 'msg-undo-1',
+    };
+
+    const json = parseMessage(JSON.stringify(message));
+    expect(json.type).toBe('undo');
+    expect(json.id).toBe('msg-undo-1');
+    expect(Object.keys(json)).toHaveLength(2);
+  });
+
+  it('should produce correct JSON for a redo message', () => {
+    const message = {
+      type: 'redo' as const,
+      id: 'msg-redo-1',
+    };
+
+    const json = parseMessage(JSON.stringify(message));
+    expect(json.type).toBe('redo');
+    expect(json.id).toBe('msg-redo-1');
+    expect(Object.keys(json)).toHaveLength(2);
+  });
+});
+
+// --- Pending message timeout ---
+
+describe('pending message timeout', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('should reject with timeout error after 10 seconds', async () => {
+    // Create a mock WebSocket that connects but never responds to messages
+    let mockOnOpen: ((ev: Event) => void) | null = null;
+    const mockWs = {
+      readyState: 1, // WebSocket.OPEN
+      send: vi.fn(),
+      close: vi.fn(),
+      set onopen(fn: ((ev: Event) => void) | null) { mockOnOpen = fn; },
+      get onopen() { return mockOnOpen; },
+      onclose: null as ((ev: CloseEvent) => void) | null,
+      onerror: null as ((ev: Event) => void) | null,
+      onmessage: null as ((ev: MessageEvent) => void) | null,
+    };
+
+    const OriginalWebSocket = globalThis.WebSocket;
+    // Replace global WebSocket with a constructor that returns our mock
+    globalThis.WebSocket = vi.fn().mockImplementation(() => mockWs) as unknown as typeof WebSocket;
+    // Preserve the OPEN constant for isConnected() check
+    (globalThis.WebSocket as unknown as Record<string, number>)["OPEN"] = 1;
+
+    try {
+      const client = new WebSocketClient('ws://localhost:9999/ws');
+
+      // Start connect and immediately fire onopen (synchronous mock)
+      const connectPromise = client.connect();
+      (mockOnOpen as ((ev: Event) => void) | null)?.(new Event('open'));
+      await connectPromise;
+
+      // Start an undo request -- server will never respond
+      const undoPromise = client.sendUndo();
+
+      // Advance time by 10 seconds to trigger the pending timeout
+      vi.advanceTimersByTime(10_000);
+
+      await expect(undoPromise).rejects.toThrow('timed out');
+    } finally {
+      globalThis.WebSocket = OriginalWebSocket;
+    }
+  });
+});
+
+// --- WebSocketClient construction ---
+
+describe('WebSocketClient', () => {
+  it('should report not connected before connect() is called', () => {
+    const client = new WebSocketClient('ws://localhost:9999/ws');
+    expect(client.isConnected()).toBe(false);
+  });
+
+  it('should allow setting URL via setUrl', () => {
+    const client = new WebSocketClient('ws://localhost:9999/ws');
+    // setUrl doesn't throw and the client can be used afterward
+    client.setUrl('ws://localhost:8888/ws');
+    expect(client.isConnected()).toBe(false);
+  });
+
+  it('should support subscribing and unsubscribing from events', () => {
+    const client = new WebSocketClient('ws://localhost:9999/ws');
+
+    const cb = vi.fn();
+    const unsub = client.onError(cb);
+    expect(typeof unsub).toBe('function');
+
+    // Unsubscribe should not throw
+    unsub();
+  });
+
+  it('should reject sendCommand when not connected', async () => {
+    const client = new WebSocketClient('ws://localhost:9999/ws');
+
+    await expect(
+      client.sendCommand({
+        type: 'draw_pixel',
+        plugin: 'builtin/pencil',
+        version: '1.0.0',
+        params: {},
+      }),
+    ).rejects.toThrow('Not connected');
+  });
+
+  it('should reject requestSync when not connected', async () => {
+    const client = new WebSocketClient('ws://localhost:9999/ws');
+    await expect(client.requestSync()).rejects.toThrow('Not connected');
+  });
+
+  it('should reject sendUndo when not connected', async () => {
+    const client = new WebSocketClient('ws://localhost:9999/ws');
+    await expect(client.sendUndo()).rejects.toThrow('Not connected');
+  });
+
+  it('should reject sendRedo when not connected', async () => {
+    const client = new WebSocketClient('ws://localhost:9999/ws');
+    await expect(client.sendRedo()).rejects.toThrow('Not connected');
+  });
+});
+
+// --- Forward-reject callback ---
+
+describe('forwardCommand reject handling', () => {
+  it('should invoke onForwardReject callback when server rejects a forwarded command', async () => {
+    let mockOnOpen: ((ev: Event) => void) | null = null;
+    let mockOnMessage: ((ev: MessageEvent) => void) | null = null;
+    const sentMessages: string[] = [];
+
+    const mockWs = {
+      readyState: 1,
+      send: vi.fn((data: string) => { sentMessages.push(data); }),
+      close: vi.fn(),
+      set onopen(fn: ((ev: Event) => void) | null) { mockOnOpen = fn; },
+      get onopen() { return mockOnOpen; },
+      onclose: null as ((ev: CloseEvent) => void) | null,
+      onerror: null as ((ev: Event) => void) | null,
+      set onmessage(fn: ((ev: MessageEvent) => void) | null) { mockOnMessage = fn; },
+      get onmessage() { return mockOnMessage; },
+    };
+
+    const OriginalWebSocket = globalThis.WebSocket;
+    globalThis.WebSocket = vi.fn().mockImplementation(() => mockWs) as unknown as typeof WebSocket;
+    (globalThis.WebSocket as unknown as Record<string, number>)["OPEN"] = 1;
+
+    try {
+      const client = new WebSocketClient('ws://localhost:9999/ws');
+      const connectPromise = client.connect();
+      (mockOnOpen as ((ev: Event) => void) | null)?.(new Event('open'));
+      await connectPromise;
+
+      const rejectCb = vi.fn();
+      client.setOnForwardReject(rejectCb);
+
+      // Forward a command
+      client.forwardCommand({
+        type: 'draw_pixel',
+        plugin: 'builtin/pencil',
+        version: '1.0.0',
+        params: { x: 1, y: 2 },
+        id: 'cmd-1',
+        timestamp: Date.now(),
+      });
+
+      // Extract the message ID that was sent
+      expect(sentMessages).toHaveLength(1);
+      const sentMsg = parseMessage(sentMessages[0] ?? "");
+      const msgId = sentMsg.id;
+
+      // Simulate server sending command_reject for that message ID
+      (mockOnMessage as ((ev: MessageEvent) => void) | null)?.(new MessageEvent('message', {
+        data: JSON.stringify({
+          type: 'command_reject',
+          id: msgId,
+          error: 'permission denied',
+        }),
+      }));
+
+      expect(rejectCb).toHaveBeenCalledOnce();
+      expect(rejectCb).toHaveBeenCalledWith(msgId, 'permission denied');
+    } finally {
+      globalThis.WebSocket = OriginalWebSocket;
+    }
+  });
+
+  it('should NOT invoke onForwardReject for acked forwarded commands', async () => {
+    let mockOnOpen: ((ev: Event) => void) | null = null;
+    let mockOnMessage: ((ev: MessageEvent) => void) | null = null;
+    const sentMessages: string[] = [];
+
+    const mockWs = {
+      readyState: 1,
+      send: vi.fn((data: string) => { sentMessages.push(data); }),
+      close: vi.fn(),
+      set onopen(fn: ((ev: Event) => void) | null) { mockOnOpen = fn; },
+      get onopen() { return mockOnOpen; },
+      onclose: null as ((ev: CloseEvent) => void) | null,
+      onerror: null as ((ev: Event) => void) | null,
+      set onmessage(fn: ((ev: MessageEvent) => void) | null) { mockOnMessage = fn; },
+      get onmessage() { return mockOnMessage; },
+    };
+
+    const OriginalWebSocket = globalThis.WebSocket;
+    globalThis.WebSocket = vi.fn().mockImplementation(() => mockWs) as unknown as typeof WebSocket;
+    (globalThis.WebSocket as unknown as Record<string, number>)["OPEN"] = 1;
+
+    try {
+      const client = new WebSocketClient('ws://localhost:9999/ws');
+      const connectPromise = client.connect();
+      (mockOnOpen as ((ev: Event) => void) | null)?.(new Event('open'));
+      await connectPromise;
+
+      const rejectCb = vi.fn();
+      client.setOnForwardReject(rejectCb);
+
+      // Forward a command
+      client.forwardCommand({
+        type: 'draw_pixel',
+        plugin: 'builtin/pencil',
+        version: '1.0.0',
+        params: {},
+        id: 'cmd-2',
+        timestamp: Date.now(),
+      });
+
+      const sentMsg = parseMessage(sentMessages[0] ?? "");
+      const msgId = sentMsg.id;
+
+      // Simulate server sending command_ack
+      (mockOnMessage as ((ev: MessageEvent) => void) | null)?.(new MessageEvent('message', {
+        data: JSON.stringify({ type: 'command_ack', id: msgId }),
+      }));
+
+      // Now simulate a reject for the same ID (should not trigger callback
+      // because the ID was already removed on ack)
+      (mockOnMessage as ((ev: MessageEvent) => void) | null)?.(new MessageEvent('message', {
+        data: JSON.stringify({
+          type: 'command_reject',
+          id: msgId,
+          error: 'too late',
+        }),
+      }));
+
+      expect(rejectCb).not.toHaveBeenCalled();
+    } finally {
+      globalThis.WebSocket = OriginalWebSocket;
+    }
+  });
+
+  it('should not invoke callback when not connected (forwardCommand is a no-op)', () => {
+    const client = new WebSocketClient('ws://localhost:9999/ws');
+    const rejectCb = vi.fn();
+    client.setOnForwardReject(rejectCb);
+
+    // forwardCommand on a disconnected client silently returns
+    client.forwardCommand({
+      type: 'draw_pixel',
+      plugin: 'builtin/pencil',
+      version: '1.0.0',
+      params: {},
+      id: 'cmd-3',
+      timestamp: Date.now(),
+    });
+
+    expect(rejectCb).not.toHaveBeenCalled();
+  });
+});
+
+// --- Post-double-socket hardening regression tests ---
+
+/**
+ * Shared mock WebSocket factory used by the hardening tests. Returns a
+ * mutable handle plus an installer that swaps globalThis.WebSocket with a
+ * constructor yielding the handle. Each test is responsible for calling
+ * the restore function in a finally block.
+ */
+interface MockHandle {
+  onopen: ((ev: Event) => void) | null;
+  onclose: ((ev: CloseEvent) => void) | null;
+  onerror: ((ev: Event) => void) | null;
+  onmessage: ((ev: MessageEvent) => void) | null;
+  close: ReturnType<typeof vi.fn>;
+  send: ReturnType<typeof vi.fn>;
+  readyState: number;
+}
+
+function installMockWebSocket(opts?: { throwOnConstruct?: Error }): {
+  handle: MockHandle;
+  restore: () => void;
+} {
+  const handle: MockHandle = {
+    onopen: null,
+    onclose: null,
+    onerror: null,
+    onmessage: null,
+    close: vi.fn(),
+    send: vi.fn(),
+    readyState: 0, // CONNECTING initially
+  };
+
+  const OriginalWebSocket = globalThis.WebSocket;
+  globalThis.WebSocket = vi.fn().mockImplementation(() => {
+    if (opts?.throwOnConstruct) throw opts.throwOnConstruct;
+    return handle;
+  }) as unknown as typeof WebSocket;
+  (globalThis.WebSocket as unknown as Record<string, number>)["OPEN"] = 1;
+  (globalThis.WebSocket as unknown as Record<string, number>)["CONNECTING"] = 0;
+
+  return {
+    handle,
+    restore: () => {
+      globalThis.WebSocket = OriginalWebSocket;
+    },
+  };
+}
+
+describe('disconnect() symmetric handler cleanup', () => {
+  it('should null all four handlers so stale events from the closing socket are ignored', async () => {
+    const { handle, restore } = installMockWebSocket();
+    try {
+      const client = new WebSocketClient('ws://localhost:9999/ws');
+      const errorCb = vi.fn();
+      client.onError(errorCb);
+
+      const connectPromise = client.connect();
+      handle.readyState = 1;
+      handle.onopen?.(new Event('open'));
+      await connectPromise;
+
+      // Grab the live handlers before disconnect so we can assert they're
+      // cleared (not just that the reference on the handle is null, but
+      // that the client actually stripped them off).
+      const openBefore = handle.onopen;
+      const messageBefore = handle.onmessage;
+      const errorBefore = handle.onerror;
+      const closeBefore = handle.onclose;
+      expect(openBefore).not.toBeNull();
+      expect(messageBefore).not.toBeNull();
+      expect(errorBefore).not.toBeNull();
+      expect(closeBefore).not.toBeNull();
+
+      client.disconnect();
+
+      // All four handlers must be nulled so stale events from the closing
+      // socket can't invoke handleMessage/notifyError post-disconnect.
+      expect(handle.onopen).toBeNull();
+      expect(handle.onmessage).toBeNull();
+      expect(handle.onerror).toBeNull();
+      expect(handle.onclose).toBeNull();
+
+      // Sanity: if we imagine the closing socket firing a stale error,
+      // the captured handler was nulled so there's nothing to call. The
+      // errorCb subscriber must not have received any post-disconnect
+      // notifications.
+      expect(errorCb).not.toHaveBeenCalled();
+    } finally {
+      restore();
+    }
+  });
+});
+
+describe('connect() promise is guarded by settled flag', () => {
+  it('should only reject once and notify error once when onerror multi-fires before open', async () => {
+    const { handle, restore } = installMockWebSocket();
+    try {
+      const client = new WebSocketClient('ws://localhost:9999/ws');
+      const errorCb = vi.fn();
+      client.onError(errorCb);
+
+      // Start connect and fire onerror multiple times before open.
+      const connectPromise = client.connect();
+      handle.readyState = 3; // CLOSED
+      handle.onerror?.(new Event('error'));
+      handle.onerror?.(new Event('error'));
+      handle.onerror?.(new Event('error'));
+
+      await expect(connectPromise).rejects.toThrow('WebSocket error');
+
+      // Exactly one notifyError despite three onerror events.
+      expect(errorCb).toHaveBeenCalledTimes(1);
+    } finally {
+      restore();
+    }
+  });
+
+  it('should swallow post-settle onerror events once open has resolved', async () => {
+    const { handle, restore } = installMockWebSocket();
+    try {
+      const client = new WebSocketClient('ws://localhost:9999/ws');
+      const errorCb = vi.fn();
+      client.onError(errorCb);
+
+      const connectPromise = client.connect();
+      handle.readyState = 1; // OPEN
+      handle.onopen?.(new Event('open'));
+      await connectPromise;
+
+      // Post-settle onerror events should NOT re-notify subscribers. The
+      // following onclose (which the server or network will send) still
+      // fires notifyConnectionChange(false) so subscribers still learn
+      // the socket died -- we're only deduping the error channel.
+      handle.onerror?.(new Event('error'));
+      handle.onerror?.(new Event('error'));
+      expect(errorCb).not.toHaveBeenCalled();
+    } finally {
+      restore();
+    }
+  });
+});
+
+describe('scheduleReconnect() survives synchronous WebSocket constructor throws', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('should schedule the next reconnect when new WebSocket() throws synchronously', async () => {
+    // Install a constructor that always throws. This simulates the case
+    // where the WebSocket URL is malformed or a security-policy denies
+    // construction -- no socket is created, no onclose will ever fire,
+    // so connect() must explicitly schedule the next reconnect.
+    const { restore } = installMockWebSocket({
+      throwOnConstruct: new Error('invalid URL'),
+    });
+    try {
+      const client = new WebSocketClient('ws://localhost:9999/ws');
+      const errorCb = vi.fn();
+      client.onError(errorCb);
+
+      // First connect attempt: throws synchronously. The promise rejects,
+      // but because we're not intentionalDisconnect and reconnectAttempts
+      // is still within limits, a reconnect should be scheduled.
+      await expect(client.connect()).rejects.toThrow('Failed to create WebSocket');
+
+      // At this point a reconnect timer should be pending. Advance time
+      // past the first backoff (1000ms for attempt 0) to fire it.
+      const WebSocketCtor = globalThis.WebSocket as unknown as ReturnType<typeof vi.fn>;
+      const constructCallsBefore = WebSocketCtor.mock.calls.length;
+      expect(constructCallsBefore).toBe(1);
+
+      vi.advanceTimersByTime(1_100);
+      // Yield so the async setTimeout callback gets a chance to run the
+      // nested connect(), which will also throw.
+      await Promise.resolve();
+      await Promise.resolve();
+
+      // The scheduled retry must have attempted to construct a new socket.
+      // If the sync-throw catch branch failed to schedule, this count
+      // would remain at 1 and the retry chain would be dead.
+      expect(WebSocketCtor.mock.calls.length).toBeGreaterThan(constructCallsBefore);
+    } finally {
+      restore();
+    }
+  });
+});