@quenty/studio-bridge 0.7.0 → 0.8.0

package/src/bridge/internal/session-tracker.ts

@@ -0,0 +1,198 @@
+/**
+ * In-memory session map with instance-level grouping. Tracks connected
+ * plugin sessions by sessionId and groups them by instanceId for
+ * multi-context support (edit, client, server in Play mode).
+ *
+ * Used exclusively by bridge-host.ts. Emits events when sessions and
+ * instance groups are added, removed, or updated.
+ */
+
+import { EventEmitter } from 'events';
+import type {
+  SessionInfo,
+  SessionContext,
+  InstanceInfo,
+  StudioState,
+} from '../types.js';
+import type {
+  PluginMessage,
+  ServerMessage,
+} from '../../server/web-socket-protocol.js';
+
+export interface TransportHandle {
+  sendActionAsync<TResponse>(
+    message: ServerMessage,
+    timeoutMs: number
+  ): Promise<TResponse>;
+  sendMessage(message: ServerMessage): void;
+  readonly isConnected: boolean;
+  on(event: 'message', listener: (msg: PluginMessage) => void): this;
+  on(event: 'disconnected', listener: () => void): this;
+}
+
+export interface TrackedSession {
+  info: SessionInfo;
+  handle: TransportHandle;
+  lastHeartbeat: Date;
+}
+
+export class SessionTracker extends EventEmitter {
+  private _sessions = new Map<string, TrackedSession>();
+  private _instanceSessions = new Map<string, Set<string>>();
+
+  /**
+   * Add a session to the tracker. Groups by instanceId and emits events.
+   * If this is the first session for the instanceId, emits 'instance-added'.
+   */
+  addSession(
+    sessionId: string,
+    info: SessionInfo,
+    handle: TransportHandle
+  ): void {
+    const tracked: TrackedSession = {
+      info,
+      handle,
+      lastHeartbeat: new Date(),
+    };
+
+    this._sessions.set(sessionId, tracked);
+
+    // Instance grouping
+    const instanceId = info.instanceId;
+    let sessionSet = this._instanceSessions.get(instanceId);
+    const isNewInstance = !sessionSet;
+
+    if (!sessionSet) {
+      sessionSet = new Set();
+      this._instanceSessions.set(instanceId, sessionSet);
+    }
+
+    sessionSet.add(sessionId);
+
+    this.emit('session-added', tracked);
+
+    if (isNewInstance) {
+      this.emit('instance-added', this._buildInstanceInfo(instanceId));
+    }
+  }
+
+  /**
+   * Remove a session from the tracker. If this was the last session for
+   * the instanceId, removes the instance group and emits 'instance-removed'.
+   */
+  removeSession(sessionId: string): void {
+    const tracked = this._sessions.get(sessionId);
+    if (!tracked) {
+      return;
+    }
+
+    const instanceId = tracked.info.instanceId;
+    this._sessions.delete(sessionId);
+
+    // Update instance grouping
+    const sessionSet = this._instanceSessions.get(instanceId);
+    if (sessionSet) {
+      sessionSet.delete(sessionId);
+
+      if (sessionSet.size === 0) {
+        this._instanceSessions.delete(instanceId);
+        this.emit('session-removed', sessionId);
+        this.emit('instance-removed', instanceId);
+        return;
+      }
+    }
+
+    this.emit('session-removed', sessionId);
+  }
+
+  /**
+   * Get a tracked session by sessionId.
+   */
+  getSession(sessionId: string): TrackedSession | undefined {
+    return this._sessions.get(sessionId);
+  }
+
+  /**
+   * List all session infos.
+   */
+  listSessions(): SessionInfo[] {
+    return Array.from(this._sessions.values()).map((t) => t.info);
+  }
+
+  /**
+   * Update a session's state and emit 'session-updated'.
+   */
+  updateSessionState(sessionId: string, state: StudioState): void {
+    const tracked = this._sessions.get(sessionId);
+    if (!tracked) {
+      return;
+    }
+
+    tracked.info = { ...tracked.info, state };
+    this.emit('session-updated', tracked);
+  }
+
+  /**
+   * List unique instances. Each instance groups 1-3 context sessions
+   * that share the same instanceId.
+   */
+  listInstances(): InstanceInfo[] {
+    const instances: InstanceInfo[] = [];
+
+    for (const instanceId of this._instanceSessions.keys()) {
+      instances.push(this._buildInstanceInfo(instanceId));
+    }
+
+    return instances;
+  }
+
+  /**
+   * Get all tracked sessions for a given instanceId.
+   */
+  getSessionsByInstance(instanceId: string): TrackedSession[] {
+    const sessionIds = this._instanceSessions.get(instanceId);
+    if (!sessionIds) {
+      return [];
+    }
+
+    const result: TrackedSession[] = [];
+    for (const sessionId of sessionIds) {
+      const tracked = this._sessions.get(sessionId);
+      if (tracked) {
+        result.push(tracked);
+      }
+    }
+    return result;
+  }
+
+  /**
+   * Get a specific context session for an instance.
+   * Returns undefined if the context is not connected.
+   */
+  getSessionByContext(
+    instanceId: string,
+    context: SessionContext
+  ): TrackedSession | undefined {
+    const sessions = this.getSessionsByInstance(instanceId);
+    return sessions.find((s) => s.info.context === context);
+  }
+
+  /** Number of currently tracked sessions. */
+  get sessionCount(): number {
+    return this._sessions.size;
+  }
+
+  private _buildInstanceInfo(instanceId: string): InstanceInfo {
+    const sessions = this.getSessionsByInstance(instanceId);
+    const first = sessions[0];
+
+    return {
+      instanceId,
+      placeName: first?.info.placeName ?? '',
+      placeId: first?.info.placeId ?? 0,
+      gameId: first?.info.gameId ?? 0,
+      contexts: sessions.map((s) => s.info.context),
+      origin: first?.info.origin ?? 'user',
+    };
+  }
+}

package/src/bridge/internal/transport-client.test.ts

@@ -0,0 +1,241 @@
+/**
+ * Unit tests for TransportClient -- validates connection, message
+ * send/receive, disconnect handling, and reconnection with backoff.
+ */
+
+import { describe, it, expect, vi, afterEach, beforeEach } from 'vitest';
+import { WebSocketServer, WebSocket } from 'ws';
+import { TransportClient } from './transport-client.js';
+
+async function createTestServer(): Promise<{
+  wss: WebSocketServer;
+  port: number;
+  connections: WebSocket[];
+}> {
+  const connections: WebSocket[] = [];
+  const wss = new WebSocketServer({ port: 0 });
+
+  const port = await new Promise<number>((resolve) => {
+    wss.on('listening', () => {
+      const addr = wss.address();
+      if (typeof addr === 'object' && addr !== null) {
+        resolve(addr.port);
+      }
+    });
+  });
+
+  wss.on('connection', (ws) => {
+    connections.push(ws);
+  });
+
+  return { wss, port, connections };
+}
+
+async function closeServer(wss: WebSocketServer): Promise<void> {
+  for (const client of wss.clients) {
+    client.terminate();
+  }
+  await new Promise<void>((resolve) => {
+    wss.close(() => resolve());
+  });
+}
+
+describe('TransportClient', () => {
+  let server:
+    | { wss: WebSocketServer; port: number; connections: WebSocket[] }
+    | undefined;
+  let client: TransportClient | undefined;
+
+  afterEach(async () => {
+    if (client) {
+      client.disconnect();
+      client = undefined;
+    }
+    if (server) {
+      await closeServer(server.wss);
+      server = undefined;
+    }
+  });
+
+  describe('connectAsync', () => {
+    it('connects to a WebSocket server', async () => {
+      server = await createTestServer();
+      client = new TransportClient();
+
+      await client.connectAsync(`ws://localhost:${server.port}`);
+
+      expect(client.isConnected).toBe(true);
+    });
+
+    it('rejects when server is not available', async () => {
+      client = new TransportClient();
+
+      await expect(
+        client.connectAsync('ws://localhost:19999')
+      ).rejects.toThrow();
+    });
+
+    it('emits connected event', async () => {
+      server = await createTestServer();
+      client = new TransportClient();
+      const listener = vi.fn();
+
+      client.on('connected', listener);
+      await client.connectAsync(`ws://localhost:${server.port}`);
+
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('send and receive', () => {
+    it('sends a message to the server', async () => {
+      server = await createTestServer();
+      client = new TransportClient();
+      await client.connectAsync(`ws://localhost:${server.port}`);
+
+      // Wait for server to register the connection
+      await new Promise((r) => setTimeout(r, 50));
+
+      const received = new Promise<string>((resolve) => {
+        server!.connections[0].on('message', (raw) => {
+          resolve(typeof raw === 'string' ? raw : raw.toString('utf-8'));
+        });
+      });
+
+      client.send('hello-server');
+
+      expect(await received).toBe('hello-server');
+    });
+
+    it('receives messages from the server', async () => {
+      server = await createTestServer();
+      client = new TransportClient();
+      await client.connectAsync(`ws://localhost:${server.port}`);
+
+      await new Promise((r) => setTimeout(r, 50));
+
+      const received = new Promise<string>((resolve) => {
+        client!.on('message', resolve);
+      });
+
+      server.connections[0].send('hello-client');
+
+      expect(await received).toBe('hello-client');
+    });
+
+    it('throws when sending on a disconnected client', async () => {
+      client = new TransportClient();
+
+      expect(() => client!.send('test')).toThrow(
+        'TransportClient is not connected'
+      );
+    });
+  });
+
+  describe('disconnect', () => {
+    it('disconnects cleanly', async () => {
+      server = await createTestServer();
+      client = new TransportClient();
+      await client.connectAsync(`ws://localhost:${server.port}`);
+
+      client.disconnect();
+
+      expect(client.isConnected).toBe(false);
+    });
+
+    it('emits disconnected event', async () => {
+      server = await createTestServer();
+      client = new TransportClient();
+      await client.connectAsync(`ws://localhost:${server.port}`);
+
+      const listener = vi.fn();
+      client.on('disconnected', listener);
+
+      client.disconnect();
+
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it('emits disconnected when server closes connection', async () => {
+      server = await createTestServer();
+      client = new TransportClient();
+      await client.connectAsync(`ws://localhost:${server.port}`, {
+        maxReconnectAttempts: 0,
+      });
+
+      // Suppress the unhandled error event from reconnection failure
+      client.on('error', () => {});
+
+      await new Promise((r) => setTimeout(r, 50));
+
+      const disconnected = new Promise<void>((resolve) => {
+        client!.on('disconnected', resolve);
+      });
+
+      // Close from server side
+      server.connections[0].close();
+
+      await disconnected;
+      expect(client.isConnected).toBe(false);
+    });
+  });
+
+  describe('reconnection', () => {
+    beforeEach(() => {
+      vi.useFakeTimers();
+    });
+
+    afterEach(() => {
+      vi.useRealTimers();
+    });
+
+    it('attempts reconnection after server-initiated disconnect', async () => {
+      vi.useRealTimers(); // Need real timers for initial connect
+
+      server = await createTestServer();
+      client = new TransportClient();
+      await client.connectAsync(`ws://localhost:${server.port}`, {
+        maxReconnectAttempts: 3,
+        initialBackoffMs: 100,
+        maxBackoffMs: 1000,
+      });
+
+      await new Promise((r) => setTimeout(r, 50));
+
+      // Disconnect from server side
+      server.connections[0].close();
+
+      // Wait for disconnect to register
+      await new Promise((r) => setTimeout(r, 50));
+      expect(client.isConnected).toBe(false);
+
+      // Wait for first reconnection attempt (100ms backoff)
+      await new Promise((r) => setTimeout(r, 200));
+
+      // Client should reconnect
+      expect(client.isConnected).toBe(true);
+    });
+
+    it('does not reconnect after intentional disconnect', async () => {
+      vi.useRealTimers();
+
+      server = await createTestServer();
+      client = new TransportClient();
+      await client.connectAsync(`ws://localhost:${server.port}`, {
+        maxReconnectAttempts: 3,
+        initialBackoffMs: 50,
+      });
+
+      const errorListener = vi.fn();
+      client.on('error', errorListener);
+
+      client.disconnect();
+
+      // Wait well past the backoff
+      await new Promise((r) => setTimeout(r, 200));
+
+      // Should not have tried to reconnect (no error events from failed reconnects)
+      expect(client.isConnected).toBe(false);
+    });
+  });
+});

package/src/bridge/internal/transport-client.ts

@@ -0,0 +1,194 @@
+/**
+ * Low-level WebSocket client with automatic reconnection and exponential
+ * backoff. Handles connection, message send/receive, and reconnection
+ * on disconnect. No business logic -- it is a dumb pipe.
+ */
+
+import { EventEmitter } from 'events';
+import { WebSocket } from 'ws';
+
+export interface TransportClientOptions {
+  /** Maximum number of reconnection attempts. Default: 10. */
+  maxReconnectAttempts?: number;
+  /** Initial backoff delay in ms. Default: 1000. */
+  initialBackoffMs?: number;
+  /** Maximum backoff delay in ms. Default: 30000. */
+  maxBackoffMs?: number;
+}
+
+const DEFAULT_MAX_RECONNECT_ATTEMPTS = 10;
+const DEFAULT_INITIAL_BACKOFF_MS = 1_000;
+const DEFAULT_MAX_BACKOFF_MS = 30_000;
+
+export class TransportClient extends EventEmitter {
+  private _ws: WebSocket | undefined;
+  private _url: string = '';
+  private _isConnected = false;
+  private _reconnectAttempt = 0;
+  private _reconnectTimer: ReturnType<typeof setTimeout> | undefined;
+  private _options: Required<TransportClientOptions> = {
+    maxReconnectAttempts: DEFAULT_MAX_RECONNECT_ATTEMPTS,
+    initialBackoffMs: DEFAULT_INITIAL_BACKOFF_MS,
+    maxBackoffMs: DEFAULT_MAX_BACKOFF_MS,
+  };
+  private _intentionalClose = false;
+
+  /**
+   * Connect to the given WebSocket URL. Resolves when the connection is
+   * established. Rejects if the initial connection fails.
+   */
+  async connectAsync(
+    url: string,
+    options?: TransportClientOptions
+  ): Promise<void> {
+    this._url = url;
+    this._intentionalClose = false;
+
+    if (options) {
+      this._options = {
+        maxReconnectAttempts:
+          options.maxReconnectAttempts ?? DEFAULT_MAX_RECONNECT_ATTEMPTS,
+        initialBackoffMs:
+          options.initialBackoffMs ?? DEFAULT_INITIAL_BACKOFF_MS,
+        maxBackoffMs: options.maxBackoffMs ?? DEFAULT_MAX_BACKOFF_MS,
+      };
+    }
+
+    await this._connectInternalAsync();
+  }
+
+  /**
+   * Disconnect from the server. Does not attempt reconnection.
+   */
+  disconnect(): void {
+    this._intentionalClose = true;
+    this._clearReconnectTimer();
+
+    if (this._ws) {
+      this._ws.removeAllListeners();
+      if (
+        this._ws.readyState === WebSocket.OPEN ||
+        this._ws.readyState === WebSocket.CONNECTING
+      ) {
+        this._ws.close();
+      }
+      this._ws = undefined;
+    }
+
+    if (this._isConnected) {
+      this._isConnected = false;
+      this.emit('disconnected');
+    }
+  }
+
+  /**
+   * Send a string message over the WebSocket.
+   */
+  send(data: string): void {
+    if (!this._ws || this._ws.readyState !== WebSocket.OPEN) {
+      throw new Error('TransportClient is not connected');
+    }
+    this._ws.send(data);
+  }
+
+  /** Whether the client is currently connected. */
+  get isConnected(): boolean {
+    return this._isConnected;
+  }
+
+  private _connectInternalAsync(): Promise<void> {
+    return new Promise<void>((resolve, reject) => {
+      const ws = new WebSocket(this._url);
+      this._ws = ws;
+
+      const onOpen = () => {
+        cleanup();
+        this._isConnected = true;
+        this._reconnectAttempt = 0;
+        this._setupMessageHandler(ws);
+        this.emit('connected');
+        resolve();
+      };
+
+      const onError = (err: Error) => {
+        cleanup();
+        reject(err);
+      };
+
+      const onClose = () => {
+        cleanup();
+        reject(new Error(`WebSocket closed before connection to ${this._url}`));
+      };
+
+      const cleanup = () => {
+        ws.off('open', onOpen);
+        ws.off('error', onError);
+        ws.off('close', onClose);
+      };
+
+      ws.on('open', onOpen);
+      ws.on('error', onError);
+      ws.on('close', onClose);
+    });
+  }
+
+  private _setupMessageHandler(ws: WebSocket): void {
+    ws.on('message', (raw) => {
+      const data = typeof raw === 'string' ? raw : raw.toString('utf-8');
+      this.emit('message', data);
+    });
+
+    ws.on('close', () => {
+      this._isConnected = false;
+      this.emit('disconnected');
+
+      if (!this._intentionalClose) {
+        this._scheduleReconnect();
+      }
+    });
+
+    ws.on('error', (err) => {
+      this.emit('error', err);
+    });
+  }
+
+  private _scheduleReconnect(): void {
+    if (this._reconnectAttempt >= this._options.maxReconnectAttempts) {
+      this.emit(
+        'error',
+        new Error(
+          `Failed to reconnect after ${this._options.maxReconnectAttempts} attempts`
+        )
+      );
+      return;
+    }
+
+    const backoff = Math.min(
+      this._options.initialBackoffMs * Math.pow(2, this._reconnectAttempt),
+      this._options.maxBackoffMs
+    );
+
+    this._reconnectAttempt++;
+
+    this._reconnectTimer = setTimeout(async () => {
+      try {
+        await this._connectInternalAsync();
+      } catch {
+        // _connectInternalAsync rejected -- the close handler in
+        // _setupMessageHandler will fire and schedule the next retry
+        // IF the connection actually opened and then closed. But if
+        // the connection never opened, we need to schedule manually.
+        if (!this._isConnected && !this._intentionalClose) {
+          this._scheduleReconnect();
+        }
+      }
+    }, backoff);
+  }
+
+  private _clearReconnectTimer(): void {
+    if (this._reconnectTimer !== undefined) {
+      clearTimeout(this._reconnectTimer);
+      this._reconnectTimer = undefined;
+    }
+  }
+}