@shaykec/bridge 0.1.0

package/src/protocol.test.js

@@ -0,0 +1,373 @@
+/**
+ * Tests for ClaudeTeach bridge protocol — TierManager, generateClientId, validateHandshake.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { TierManager, generateClientId, validateHandshake } from './protocol.js';
+import {
+  TIER_FULL,
+  TIER_CANVAS,
+  TIER_TERMINAL,
+  CLIENT_EXTENSION,
+  CLIENT_CANVAS,
+  PROTOCOL_VERSION,
+} from '@shaykec/shared';
+
+// ---------------------------------------------------------------------------
+// generateClientId
+// ---------------------------------------------------------------------------
+
+describe('generateClientId', () => {
+  it('returns a string starting with "client-"', () => {
+    const id = generateClientId();
+    expect(typeof id).toBe('string');
+    expect(id.startsWith('client-')).toBe(true);
+  });
+
+  it('generates unique IDs across multiple calls', () => {
+    const ids = new Set(Array.from({ length: 50 }, () => generateClientId()));
+    expect(ids.size).toBe(50);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// validateHandshake
+// ---------------------------------------------------------------------------
+
+describe('validateHandshake', () => {
+  it('accepts a valid extension handshake', () => {
+    const result = validateHandshake({ clientType: 'extension', protocolVersion: 1 });
+    expect(result).toEqual({ valid: true, error: null });
+  });
+
+  it('accepts a valid canvas handshake', () => {
+    const result = validateHandshake({ clientType: 'canvas', protocolVersion: 1 });
+    expect(result).toEqual({ valid: true, error: null });
+  });
+
+  it('rejects missing clientType', () => {
+    const result = validateHandshake({ protocolVersion: 1 });
+    expect(result.valid).toBe(false);
+    expect(result.error).toMatch(/clientType/i);
+  });
+
+  it('rejects invalid clientType', () => {
+    const result = validateHandshake({ clientType: 'unknown', protocolVersion: 1 });
+    expect(result.valid).toBe(false);
+    expect(result.error).toMatch(/clientType/i);
+  });
+
+  it('rejects missing protocolVersion', () => {
+    const result = validateHandshake({ clientType: 'extension' });
+    expect(result.valid).toBe(false);
+    expect(result.error).toMatch(/protocolVersion/i);
+  });
+
+  it('rejects protocolVersion higher than the server supports', () => {
+    const result = validateHandshake({ clientType: 'extension', protocolVersion: PROTOCOL_VERSION + 1 });
+    expect(result.valid).toBe(false);
+    expect(result.error).toMatch(/version/i);
+  });
+
+  it('accepts protocolVersion equal to current version', () => {
+    const result = validateHandshake({ clientType: 'canvas', protocolVersion: PROTOCOL_VERSION });
+    expect(result).toEqual({ valid: true, error: null });
+  });
+
+  it('rejects null payload', () => {
+    const result = validateHandshake(null);
+    expect(result.valid).toBe(false);
+    expect(result.error).toBeDefined();
+  });
+
+  it('rejects undefined payload', () => {
+    const result = validateHandshake(undefined);
+    expect(result.valid).toBe(false);
+    expect(result.error).toBeDefined();
+  });
+
+  it('rejects a string payload', () => {
+    const result = validateHandshake('not an object');
+    expect(result.valid).toBe(false);
+    expect(result.error).toMatch(/object/i);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// TierManager
+// ---------------------------------------------------------------------------
+
+describe('TierManager', () => {
+  /** @type {TierManager} */
+  let tm;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    tm = new TierManager();
+  });
+
+  afterEach(() => {
+    tm.stopHeartbeat();
+    vi.useRealTimers();
+  });
+
+  // --- Helper to create a fake WebSocket ---
+  function fakeWs() {
+    return { readyState: 1, send: vi.fn() };
+  }
+
+  // --- Helper to create a fake SSE response ---
+  function fakeSseRes() {
+    return { write: vi.fn() };
+  }
+
+  // --- Tier detection ---
+
+  it('starts at TIER_TERMINAL', () => {
+    expect(tm.getTier()).toBe(TIER_TERMINAL);
+  });
+
+  it('becomes TIER_CANVAS when a canvas WS client connects', () => {
+    tm.addWsClient('c1', fakeWs(), CLIENT_CANVAS);
+    expect(tm.getTier()).toBe(TIER_CANVAS);
+  });
+
+  it('becomes TIER_FULL when both extension and canvas WS clients connect', () => {
+    tm.addWsClient('e1', fakeWs(), CLIENT_EXTENSION);
+    tm.addWsClient('c1', fakeWs(), CLIENT_CANVAS);
+    expect(tm.getTier()).toBe(TIER_FULL);
+  });
+
+  it('stays TIER_TERMINAL when only extension connects (no canvas)', () => {
+    tm.addWsClient('e1', fakeWs(), CLIENT_EXTENSION);
+    expect(tm.getTier()).toBe(TIER_TERMINAL);
+  });
+
+  it('recalculates tier downward when a client disconnects', () => {
+    tm.addWsClient('e1', fakeWs(), CLIENT_EXTENSION);
+    tm.addWsClient('c1', fakeWs(), CLIENT_CANVAS);
+    expect(tm.getTier()).toBe(TIER_FULL);
+
+    tm.removeWsClient('e1');
+    expect(tm.getTier()).toBe(TIER_CANVAS);
+
+    tm.removeWsClient('c1');
+    expect(tm.getTier()).toBe(TIER_TERMINAL);
+  });
+
+  it('becomes TIER_CANVAS when a canvas SSE client connects', () => {
+    tm.addSseClient('s1', fakeSseRes(), CLIENT_CANVAS);
+    expect(tm.getTier()).toBe(TIER_CANVAS);
+  });
+
+  it('becomes TIER_FULL with WS extension + SSE canvas', () => {
+    tm.addWsClient('e1', fakeWs(), CLIENT_EXTENSION);
+    tm.addSseClient('s1', fakeSseRes(), CLIENT_CANVAS);
+    expect(tm.getTier()).toBe(TIER_FULL);
+  });
+
+  it('recalculates when SSE client removed', () => {
+    tm.addSseClient('s1', fakeSseRes(), CLIENT_CANVAS);
+    expect(tm.getTier()).toBe(TIER_CANVAS);
+
+    tm.removeSseClient('s1');
+    expect(tm.getTier()).toBe(TIER_TERMINAL);
+  });
+
+  // --- getTierInfo ---
+
+  it('getTierInfo returns correct structure', () => {
+    tm.addWsClient('e1', fakeWs(), CLIENT_EXTENSION);
+    tm.addSseClient('s1', fakeSseRes(), CLIENT_CANVAS);
+
+    const info = tm.getTierInfo();
+    expect(info.tier).toBe(TIER_FULL);
+    expect(info.label).toBe('Full (Extension + Canvas)');
+    expect(info.clients.websocket).toEqual([CLIENT_EXTENSION]);
+    expect(info.clients.sse).toEqual([CLIENT_CANVAS]);
+    expect(info.clients.total).toBe(2);
+  });
+
+  it('getTierInfo returns empty clients when none connected', () => {
+    const info = tm.getTierInfo();
+    expect(info.tier).toBe(TIER_TERMINAL);
+    expect(info.clients.total).toBe(0);
+    expect(info.clients.websocket).toEqual([]);
+    expect(info.clients.sse).toEqual([]);
+  });
+
+  // --- hasExtension / hasCanvas ---
+
+  it('hasExtension returns false initially', () => {
+    expect(tm.hasExtension()).toBe(false);
+  });
+
+  it('hasExtension returns true after extension WS connects', () => {
+    tm.addWsClient('e1', fakeWs(), CLIENT_EXTENSION);
+    expect(tm.hasExtension()).toBe(true);
+  });
+
+  it('hasCanvas returns false initially', () => {
+    expect(tm.hasCanvas()).toBe(false);
+  });
+
+  it('hasCanvas returns true after canvas WS connects', () => {
+    tm.addWsClient('c1', fakeWs(), CLIENT_CANVAS);
+    expect(tm.hasCanvas()).toBe(true);
+  });
+
+  it('hasCanvas returns true after canvas SSE connects', () => {
+    tm.addSseClient('s1', fakeSseRes(), CLIENT_CANVAS);
+    expect(tm.hasCanvas()).toBe(true);
+  });
+
+  // --- onTierChange ---
+
+  it('onTierChange fires when tier changes', () => {
+    const listener = vi.fn();
+    tm.onTierChange(listener);
+
+    tm.addWsClient('c1', fakeWs(), CLIENT_CANVAS);
+    expect(listener).toHaveBeenCalledWith(TIER_TERMINAL, TIER_CANVAS);
+  });
+
+  it('onTierChange does not fire when tier stays the same', () => {
+    tm.addWsClient('c1', fakeWs(), CLIENT_CANVAS);
+
+    const listener = vi.fn();
+    tm.onTierChange(listener);
+
+    // Adding a second canvas client should not change the tier
+    tm.addWsClient('c2', fakeWs(), CLIENT_CANVAS);
+    expect(listener).not.toHaveBeenCalled();
+  });
+
+  it('onTierChange fires multiple times across tier transitions', () => {
+    const listener = vi.fn();
+    tm.onTierChange(listener);
+
+    // TERMINAL -> CANVAS
+    tm.addWsClient('c1', fakeWs(), CLIENT_CANVAS);
+    // CANVAS -> FULL
+    tm.addWsClient('e1', fakeWs(), CLIENT_EXTENSION);
+    // FULL -> CANVAS
+    tm.removeWsClient('e1');
+
+    expect(listener).toHaveBeenCalledTimes(3);
+    expect(listener).toHaveBeenNthCalledWith(1, TIER_TERMINAL, TIER_CANVAS);
+    expect(listener).toHaveBeenNthCalledWith(2, TIER_CANVAS, TIER_FULL);
+    expect(listener).toHaveBeenNthCalledWith(3, TIER_FULL, TIER_CANVAS);
+  });
+
+  it('tier change broadcasts to WS and SSE clients', () => {
+    const ws = fakeWs();
+    const sseRes = fakeSseRes();
+    tm.addSseClient('s1', sseRes, CLIENT_CANVAS);
+
+    // Clear calls from the initial addSseClient tier change broadcast
+    ws.send.mockClear();
+    sseRes.write.mockClear();
+
+    // Now add an extension WS client, which triggers another tier change
+    tm.addWsClient('e1', ws, CLIENT_EXTENSION);
+
+    // The WS client should have received the tier change message
+    expect(ws.send).toHaveBeenCalled();
+    // The SSE client should also have received the tier change message
+    expect(sseRes.write).toHaveBeenCalled();
+  });
+
+  // --- broadcastWs / broadcastSse with no clients ---
+
+  it('broadcastWs does not throw with no clients', () => {
+    expect(() => tm.broadcastWs('test')).not.toThrow();
+  });
+
+  it('broadcastSse does not throw with no clients', () => {
+    expect(() => tm.broadcastSse('test')).not.toThrow();
+  });
+
+  it('broadcastWs sends to all connected WS clients', () => {
+    const ws1 = fakeWs();
+    const ws2 = fakeWs();
+    tm.addWsClient('c1', ws1, CLIENT_CANVAS);
+    tm.addWsClient('c2', ws2, CLIENT_CANVAS);
+
+    tm.broadcastWs('hello');
+    expect(ws1.send).toHaveBeenCalledWith('hello');
+    expect(ws2.send).toHaveBeenCalledWith('hello');
+  });
+
+  it('broadcastWs skips clients that are not OPEN (readyState !== 1)', () => {
+    const ws1 = { readyState: 1, send: vi.fn() };
+    const ws2 = { readyState: 3, send: vi.fn() }; // CLOSED
+    tm.addWsClient('c1', ws1, CLIENT_CANVAS);
+    tm.addWsClient('c2', ws2, CLIENT_CANVAS);
+
+    tm.broadcastWs('hello');
+    expect(ws1.send).toHaveBeenCalledWith('hello');
+    expect(ws2.send).not.toHaveBeenCalled();
+  });
+
+  it('broadcastSse sends to all SSE clients', () => {
+    const r1 = fakeSseRes();
+    const r2 = fakeSseRes();
+    tm.addSseClient('s1', r1, CLIENT_CANVAS);
+    tm.addSseClient('s2', r2, CLIENT_CANVAS);
+
+    tm.broadcastSse('hello');
+    expect(r1.write).toHaveBeenCalledWith('data: hello\n\n');
+    expect(r2.write).toHaveBeenCalledWith('data: hello\n\n');
+  });
+
+  it('broadcastWs swallows send errors', () => {
+    const ws = { readyState: 1, send: vi.fn(() => { throw new Error('broken'); }) };
+    tm.addWsClient('c1', ws, CLIENT_CANVAS);
+    expect(() => tm.broadcastWs('data')).not.toThrow();
+  });
+
+  it('broadcastSse swallows write errors', () => {
+    const res = { write: vi.fn(() => { throw new Error('broken'); }) };
+    tm.addSseClient('s1', res, CLIENT_CANVAS);
+    expect(() => tm.broadcastSse('data')).not.toThrow();
+  });
+
+  // --- Heartbeat ---
+
+  it('startHeartbeat / stopHeartbeat do not throw', () => {
+    expect(() => tm.startHeartbeat()).not.toThrow();
+    expect(() => tm.stopHeartbeat()).not.toThrow();
+  });
+
+  it('heartbeat broadcasts to connected clients at interval', () => {
+    const ws = fakeWs();
+    tm.addWsClient('c1', ws, CLIENT_CANVAS);
+    ws.send.mockClear();
+
+    tm.startHeartbeat();
+
+    // Advance past one heartbeat interval (30 000 ms)
+    vi.advanceTimersByTime(30_000);
+    expect(ws.send).toHaveBeenCalled();
+
+    const msg = JSON.parse(ws.send.mock.calls[0][0]);
+    expect(msg.type).toBe('sys:heartbeat');
+  });
+
+  it('stopHeartbeat stops broadcasting', () => {
+    const ws = fakeWs();
+    tm.addWsClient('c1', ws, CLIENT_CANVAS);
+    ws.send.mockClear();
+
+    tm.startHeartbeat();
+    tm.stopHeartbeat();
+
+    vi.advanceTimersByTime(60_000);
+    // No heartbeat should have been sent after stopping
+    expect(ws.send).not.toHaveBeenCalled();
+  });
+
+  it('calling stopHeartbeat without start does not throw', () => {
+    expect(() => tm.stopHeartbeat()).not.toThrow();
+  });
+});

package/src/router.js

@@ -0,0 +1,149 @@
+/**
+ * Event routing for ClaudeTeach bridge server.
+ * Visual commands from plugin fan out to the best connected client.
+ * User events from clients are stored for the plugin to poll.
+ */
+
+import {
+  parseEnvelope,
+  isTypeInCategory,
+  createEnvelope,
+  MSG_SYS_CONNECT,
+  MSG_SYS_DISCONNECT,
+  MSG_SYS_HEARTBEAT,
+} from '@shaykec/shared';
+
+/**
+ * Event router — manages message flow between plugin and clients.
+ */
+export class EventRouter {
+  /**
+   * @param {import('./protocol.js').TierManager} tierManager
+   */
+  constructor(tierManager) {
+    this.tierManager = tierManager;
+
+    /**
+     * Queue of user events waiting to be polled by the plugin.
+     * @type {Array<object>}
+     */
+    this.eventQueue = [];
+
+    /**
+     * Maximum event queue size before oldest events are dropped.
+     */
+    this.maxQueueSize = 1000;
+  }
+
+  /**
+   * Route a visual command from the plugin to connected clients.
+   * Fans out to all connected canvas/extension clients.
+   * @param {object} envelope - Parsed message envelope
+   */
+  routeVisualCommand(envelope) {
+    const data = JSON.stringify(envelope);
+
+    // Send to all WebSocket clients
+    this.tierManager.broadcastWs(data);
+
+    // Send to all SSE clients
+    this.tierManager.broadcastSse(data);
+  }
+
+  /**
+   * Handle an incoming message from a WebSocket client.
+   * System messages are handled internally; user events are queued.
+   * @param {string} rawData - Raw WebSocket message
+   * @param {string} clientId - Client ID
+   * @returns {{ handled: boolean, error: string|null }}
+   */
+  handleWsMessage(rawData, clientId) {
+    const { valid, envelope, error } = parseEnvelope(rawData);
+
+    if (!valid) {
+      return { handled: false, error };
+    }
+
+    // System messages are handled by the server, not queued
+    if (envelope.type === MSG_SYS_HEARTBEAT) {
+      return { handled: true, error: null };
+    }
+
+    if (envelope.type === MSG_SYS_CONNECT || envelope.type === MSG_SYS_DISCONNECT) {
+      // These are handled by the server's connection logic
+      return { handled: true, error: null };
+    }
+
+    // User events and capture events go to the queue
+    if (isTypeInCategory(envelope.type, 'event') ||
+        isTypeInCategory(envelope.type, 'capture') ||
+        isTypeInCategory(envelope.type, 'context')) {
+      this._enqueueEvent(envelope);
+      return { handled: true, error: null };
+    }
+
+    // Canvas commands from other sources — fan out
+    if (isTypeInCategory(envelope.type, 'canvas')) {
+      this.routeVisualCommand(envelope);
+      return { handled: true, error: null };
+    }
+
+    // Unknown type — silently accept but don't route
+    return { handled: true, error: null };
+  }
+
+  /**
+   * Handle an incoming event from the REST API (POST /api/event).
+   * @param {object} body - Parsed request body (should be an envelope)
+   * @returns {{ ok: boolean, error: string|null }}
+   */
+  handleRestEvent(body) {
+    const { valid, envelope, error } = parseEnvelope(body);
+
+    if (!valid) {
+      return { ok: false, error };
+    }
+
+    this._enqueueEvent(envelope);
+    return { ok: true, error: null };
+  }
+
+  /**
+   * Poll queued events. Returns and clears the queue.
+   * @returns {Array<object>}
+   */
+  pollEvents() {
+    const events = this.eventQueue.slice();
+    this.eventQueue = [];
+    return events;
+  }
+
+  /**
+   * Peek at queued events without clearing.
+   * @returns {Array<object>}
+   */
+  peekEvents() {
+    return this.eventQueue.slice();
+  }
+
+  /**
+   * Get the number of queued events.
+   * @returns {number}
+   */
+  getQueueSize() {
+    return this.eventQueue.length;
+  }
+
+  /**
+   * Add an event to the queue, trimming oldest if at capacity.
+   * @param {object} envelope
+   */
+  _enqueueEvent(envelope) {
+    if (this.eventQueue.length >= this.maxQueueSize) {
+      // Drop oldest 10% to avoid constant trimming
+      const dropCount = Math.floor(this.maxQueueSize * 0.1);
+      this.eventQueue = this.eventQueue.slice(dropCount);
+    }
+    this.eventQueue.push(envelope);
+  }
+}