@quenty/studio-bridge 0.7.1 → 0.9.0

package/src/bridge/internal/__tests__/failover-inflight.test.ts

@@ -0,0 +1,329 @@
+/**
+ * Integration tests for inflight request handling during failover. Verifies
+ * that pending requests are properly rejected when the client is disconnected,
+ * and that old sessions throw SessionDisconnectedError after failover.
+ *
+ * Uses real BridgeClient connected to a mock host (WebSocketServer).
+ */
+
+import { describe, it, expect, afterEach, vi } from 'vitest';
+import { WebSocketServer, WebSocket } from 'ws';
+import { BridgeClient } from '../bridge-client.js';
+
+// Mock loadActionSourcesAsync so _ensureActionsAsync is a no-op in tests
+vi.mock('../../../commands/framework/action-loader.js', () => ({
+  loadActionSourcesAsync: vi.fn(async () => []),
+}));
+import {
+  encodeHostMessage,
+  decodeHostMessage,
+  type HostProtocolMessage,
+} from '../host-protocol.js';
+import { SessionDisconnectedError } from '../../types.js';
+import type { SessionInfo } from '../../types.js';
+
+function createSessionInfo(overrides: Partial<SessionInfo> = {}): SessionInfo {
+  return {
+    sessionId: 'session-1',
+    placeName: 'TestPlace',
+    state: 'Edit',
+    pluginVersion: '1.0.0',
+    capabilities: ['execute', 'queryState'],
+    connectedAt: new Date('2024-01-01'),
+    origin: 'user',
+    context: 'edit',
+    instanceId: 'inst-1',
+    placeId: 100,
+    gameId: 200,
+    ...overrides,
+  };
+}
+
+interface MockHost {
+  wss: WebSocketServer;
+  port: number;
+  clients: WebSocket[];
+  receivedMessages: HostProtocolMessage[];
+}
+
+async function createMockHostWithSessions(
+  sessions: SessionInfo[]
+): Promise<MockHost> {
+  const clients: WebSocket[] = [];
+  const receivedMessages: HostProtocolMessage[] = [];
+
+  const wss = new WebSocketServer({ port: 0, path: '/client' });
+
+  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) => {
+    clients.push(ws);
+
+    ws.on('message', (raw) => {
+      const data = typeof raw === 'string' ? raw : raw.toString('utf-8');
+      const msg = decodeHostMessage(data);
+      if (msg) {
+        receivedMessages.push(msg);
+
+        if (msg.type === 'list-sessions') {
+          ws.send(
+            encodeHostMessage({
+              type: 'list-sessions-response',
+              requestId: msg.requestId,
+              sessions,
+            })
+          );
+        }
+        // Do NOT respond to host-envelope — leave them pending
+      }
+    });
+  });
+
+  return { wss, port, clients, receivedMessages };
+}
+
+async function closeHost(host: MockHost): Promise<void> {
+  for (const client of host.wss.clients) {
+    client.terminate();
+  }
+  await new Promise<void>((resolve) => {
+    host.wss.close(() => resolve());
+  });
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise<void>((resolve) => setTimeout(resolve, ms));
+}
+
+describe('Inflight request handling during failover', () => {
+  let host: MockHost | undefined;
+  let client: BridgeClient | undefined;
+
+  afterEach(async () => {
+    if (client) {
+      try {
+        await client.disconnectAsync();
+      } catch {
+        /* ignore */
+      }
+      client = undefined;
+    }
+    if (host) {
+      try {
+        await closeHost(host);
+      } catch {
+        /* ignore */
+      }
+      host = undefined;
+    }
+  });
+
+  it('pending request rejects with error when client disconnects', async () => {
+    const sessions = [createSessionInfo({ sessionId: 'session-1' })];
+    host = await createMockHostWithSessions(sessions);
+
+    client = new BridgeClient();
+    await client.connectAsync(host.port);
+
+    const session = client.getSession('session-1');
+    expect(session).toBeDefined();
+
+    // Send an action that will never get a response (mock host doesn't
+    // respond to host-envelope messages)
+    const execPromise = session!.execAsync('print("hello")', 30_000);
+
+    // Wait for the envelope to be sent
+    await delay(50);
+
+    // Simulate failover cleanup by explicitly disconnecting
+    await client.disconnectAsync();
+    client = undefined;
+
+    // The pending request should reject with 'Client disconnected'
+    await expect(execPromise).rejects.toThrow('Client disconnected');
+  });
+
+  it('ALL pending requests are rejected, not just the first', async () => {
+    const sessions = [createSessionInfo({ sessionId: 'session-1' })];
+    host = await createMockHostWithSessions(sessions);
+
+    client = new BridgeClient();
+    await client.connectAsync(host.port);
+
+    const session = client.getSession('session-1');
+    expect(session).toBeDefined();
+
+    // Send multiple actions that will never get responses
+    const promises = [
+      session!.execAsync('print("a")', 30_000),
+      session!.execAsync('print("b")', 30_000),
+      session!.execAsync('print("c")', 30_000),
+    ];
+
+    // Wait for envelopes to be sent
+    await delay(50);
+
+    // Simulate failover cleanup
+    await client.disconnectAsync();
+    client = undefined;
+
+    // ALL promises should reject
+    const results = await Promise.allSettled(promises);
+    for (const result of results) {
+      expect(result.status).toBe('rejected');
+    }
+    // All should reject with 'Client disconnected'
+    for (const result of results) {
+      if (result.status === 'rejected') {
+        expect(result.reason.message).toContain('Client disconnected');
+      }
+    }
+  });
+
+  it('requests reject before takeover would complete', async () => {
+    const sessions = [createSessionInfo({ sessionId: 'session-1' })];
+    host = await createMockHostWithSessions(sessions);
+
+    client = new BridgeClient();
+    await client.connectAsync(host.port);
+
+    const session = client.getSession('session-1');
+    expect(session).toBeDefined();
+
+    // Track ordering
+    const events: string[] = [];
+
+    // Start a pending request
+    const execPromise = session!
+      .execAsync('print("hello")', 30_000)
+      .catch((err) => {
+        events.push('request-rejected');
+        throw err;
+      });
+
+    await delay(50);
+
+    // Disconnect (which immediately rejects pending requests)
+    await client.disconnectAsync();
+    client = undefined;
+
+    // Verify the promise rejected
+    await expect(execPromise).rejects.toThrow();
+
+    // Request rejection should have been recorded
+    expect(events).toContain('request-rejected');
+  });
+
+  it('after failover, old BridgeSession throws SessionDisconnectedError', async () => {
+    const sessions = [createSessionInfo({ sessionId: 'session-1' })];
+    host = await createMockHostWithSessions(sessions);
+
+    client = new BridgeClient();
+    await client.connectAsync(host.port);
+
+    const session = client.getSession('session-1');
+    expect(session).toBeDefined();
+
+    // Disconnect the client (simulates failover cleanup)
+    await client.disconnectAsync();
+    client = undefined;
+
+    // The old session should now throw SessionDisconnectedError
+    expect(session!.isConnected).toBe(false);
+    await expect(session!.execAsync('print("hello")')).rejects.toThrow(
+      SessionDisconnectedError
+    );
+    await expect(session!.queryStateAsync()).rejects.toThrow(
+      SessionDisconnectedError
+    );
+    await expect(session!.captureScreenshotAsync()).rejects.toThrow(
+      SessionDisconnectedError
+    );
+    await expect(session!.queryLogsAsync()).rejects.toThrow(
+      SessionDisconnectedError
+    );
+    await expect(
+      session!.queryDataModelAsync({ path: 'game' })
+    ).rejects.toThrow(SessionDisconnectedError);
+  });
+
+  it('client emits disconnected event when host dies', async () => {
+    host = await createMockHostWithSessions([]);
+
+    client = new BridgeClient();
+    await client.connectAsync(host.port);
+
+    const disconnectedPromise = new Promise<void>((resolve) => {
+      client!.on('disconnected', resolve);
+    });
+
+    // Kill the host (force close)
+    await closeHost(host);
+    host = undefined;
+
+    // Should emit disconnected
+    await disconnectedPromise;
+    expect(client.isConnected).toBe(false);
+  });
+
+  it('multiple pending requests from different sessions all reject', async () => {
+    const sessions = [
+      createSessionInfo({ sessionId: 'session-a', instanceId: 'inst-a' }),
+      createSessionInfo({ sessionId: 'session-b', instanceId: 'inst-b' }),
+    ];
+    host = await createMockHostWithSessions(sessions);
+
+    client = new BridgeClient();
+    await client.connectAsync(host.port);
+
+    const sessionA = client.getSession('session-a');
+    const sessionB = client.getSession('session-b');
+    expect(sessionA).toBeDefined();
+    expect(sessionB).toBeDefined();
+
+    // Send actions on both sessions
+    const promiseA = sessionA!.execAsync('print("a")', 30_000);
+    const promiseB = sessionB!.execAsync('print("b")', 30_000);
+
+    await delay(50);
+
+    // Disconnect (simulating failover cleanup)
+    await client.disconnectAsync();
+    client = undefined;
+
+    // Both should reject
+    const results = await Promise.allSettled([promiseA, promiseB]);
+    expect(results[0].status).toBe('rejected');
+    expect(results[1].status).toBe('rejected');
+  });
+
+  it('session disconnected event fires when handles are marked disconnected', async () => {
+    const sessions = [createSessionInfo({ sessionId: 'session-1' })];
+    host = await createMockHostWithSessions(sessions);
+
+    client = new BridgeClient();
+    await client.connectAsync(host.port);
+
+    const session = client.getSession('session-1');
+    expect(session).toBeDefined();
+
+    const disconnectedPromise = new Promise<void>((resolve) => {
+      session!.on('disconnected', resolve);
+    });
+
+    // Disconnect the client
+    await client.disconnectAsync();
+    client = undefined;
+
+    // Session should have emitted disconnected
+    await disconnectedPromise;
+    expect(session!.isConnected).toBe(false);
+  });
+});

package/src/bridge/internal/__tests__/host-client-integration.test.ts

@@ -0,0 +1,387 @@
+/**
+ * Integration tests for host<->client protocol. Verifies that a real
+ * BridgeHost correctly processes client WebSocket messages (list-sessions,
+ * list-instances) and broadcasts session events when plugins connect or
+ * disconnect. This covers Bug 1: host never processed client messages.
+ *
+ * Uses real BridgeHost and WebSocket connections — no mocks for the host side.
+ */
+
+import { describe, it, expect, afterEach } from 'vitest';
+import { EventEmitter } from 'events';
+import { WebSocket } from 'ws';
+import { BridgeHost } from '../bridge-host.js';
+import { SessionTracker } from '../session-tracker.js';
+import {
+  encodeHostMessage,
+  decodeHostMessage,
+  type HostProtocolMessage,
+  type ListSessionsRequest,
+  type ListInstancesRequest,
+} from '../host-protocol.js';
+import type { Capability } from '../../../server/web-socket-protocol.js';
+import type { SessionInfo, SessionContext } from '../../types.js';
+
+class StubTransportHandle extends EventEmitter {
+  get isConnected(): boolean {
+    return true;
+  }
+
+  async sendActionAsync(): Promise<never> {
+    throw new Error('stub');
+  }
+
+  sendMessage(): void {
+    // no-op
+  }
+}
+
+function connectClientWsAsync(port: number): Promise<WebSocket> {
+  return new Promise<WebSocket>((resolve, reject) => {
+    const ws = new WebSocket(`ws://localhost:${port}/client`);
+    ws.on('open', () => resolve(ws));
+    ws.on('error', reject);
+  });
+}
+
+function connectPluginWsAsync(port: number): Promise<WebSocket> {
+  return new Promise<WebSocket>((resolve, reject) => {
+    const ws = new WebSocket(`ws://localhost:${port}/plugin`);
+    ws.on('open', () => resolve(ws));
+    ws.on('error', reject);
+  });
+}
+
+async function waitForMessageAsync(
+  ws: WebSocket,
+  timeoutMs = 2_000
+): Promise<HostProtocolMessage> {
+  return new Promise<HostProtocolMessage>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new Error(`Timed out waiting for message (${timeoutMs}ms)`));
+    }, timeoutMs);
+
+    ws.once('message', (raw) => {
+      clearTimeout(timer);
+      const data = typeof raw === 'string' ? raw : raw.toString('utf-8');
+      const msg = decodeHostMessage(data);
+      if (!msg) {
+        reject(new Error(`Failed to decode host message: ${data}`));
+        return;
+      }
+      resolve(msg);
+    });
+  });
+}
+
+function deriveContext(state: string): SessionContext {
+  if (state === 'Server') return 'server';
+  if (state === 'Client') return 'client';
+  return 'edit';
+}
+
+/**
+ * Wire BridgeHost events to a SessionTracker, mirroring the pattern from
+ * BridgeConnection._initHostAsync. Returns the tracker for querying.
+ */
+function wireHostAndTracker(host: BridgeHost): SessionTracker {
+  const tracker = new SessionTracker();
+
+  // plugin-connected -> tracker.addSession
+  host.on('plugin-connected', (info) => {
+    const state = info.state ?? 'Edit';
+    const context = deriveContext(state);
+
+    const sessionInfo: SessionInfo = {
+      sessionId: info.sessionId,
+      placeName: info.placeName ?? '',
+      placeFile: info.placeFile,
+      state: state as SessionInfo['state'],
+      pluginVersion: info.pluginVersion ?? '',
+      capabilities: info.capabilities,
+      connectedAt: new Date(),
+      origin: 'user',
+      context,
+      instanceId: info.instanceId ?? info.sessionId,
+      placeId: 0,
+      gameId: 0,
+    };
+
+    const handle = new StubTransportHandle();
+    tracker.addSession(info.sessionId, sessionInfo, handle);
+  });
+
+  // plugin-disconnected -> tracker.removeSession
+  host.on('plugin-disconnected', (sessionId: string) => {
+    tracker.removeSession(sessionId);
+  });
+
+  // client-message -> respond to list-sessions, list-instances
+  host.on(
+    'client-message',
+    (msg: HostProtocolMessage, reply: (m: HostProtocolMessage) => void) => {
+      if (msg.type === 'list-sessions') {
+        const req = msg as ListSessionsRequest;
+        reply({
+          type: 'list-sessions-response',
+          requestId: req.requestId,
+          sessions: tracker.listSessions(),
+        });
+      } else if (msg.type === 'list-instances') {
+        const req = msg as ListInstancesRequest;
+        reply({
+          type: 'list-instances-response',
+          requestId: req.requestId,
+          instances: tracker.listInstances(),
+        });
+      }
+    }
+  );
+
+  // session-added -> broadcast session-event connected
+  tracker.on('session-added', (tracked: { info: SessionInfo }) => {
+    host.broadcastToClients({
+      type: 'session-event',
+      event: 'connected',
+      sessionId: tracked.info.sessionId,
+      session: tracked.info,
+      context: tracked.info.context,
+      instanceId: tracked.info.instanceId,
+    });
+  });
+
+  // session-removed -> broadcast session-event disconnected
+  tracker.on('session-removed', (sessionId: string) => {
+    host.broadcastToClients({
+      type: 'session-event',
+      event: 'disconnected',
+      sessionId,
+      context: 'edit',
+      instanceId: sessionId,
+    });
+  });
+
+  return tracker;
+}
+
+/**
+ * Send a register message on a plugin WebSocket.
+ */
+async function registerPluginAsync(
+  pluginWs: WebSocket,
+  options: {
+    sessionId: string;
+    instanceId: string;
+    placeName?: string;
+    pluginVersion?: string;
+    state?: string;
+    capabilities?: Capability[];
+  }
+): Promise<void> {
+  pluginWs.send(
+    JSON.stringify({
+      type: 'register',
+      sessionId: options.sessionId,
+      payload: {
+        pluginVersion: options.pluginVersion ?? '0.7.0',
+        instanceId: options.instanceId,
+        placeName: options.placeName ?? 'TestPlace',
+        state: options.state ?? 'Edit',
+        capabilities: options.capabilities ?? ['execute'],
+      },
+    })
+  );
+
+  // Yield to let the host process the register
+  await new Promise((r) => setTimeout(r, 20));
+}
+
+describe('Host-client integration', { timeout: 10_000 }, () => {
+  let host: BridgeHost | undefined;
+  const openSockets: WebSocket[] = [];
+
+  afterEach(async () => {
+    for (const ws of openSockets) {
+      if (
+        ws.readyState === WebSocket.OPEN ||
+        ws.readyState === WebSocket.CONNECTING
+      ) {
+        ws.terminate();
+      }
+    }
+    openSockets.length = 0;
+
+    if (host) {
+      try {
+        await host.stopAsync();
+      } catch {
+        /* ignore */
+      }
+      host = undefined;
+    }
+  });
+
+  it('host responds to list-sessions request from client WebSocket', async () => {
+    host = new BridgeHost();
+    const port = await host.startAsync({ port: 0 });
+    wireHostAndTracker(host);
+
+    const clientWs = await connectClientWsAsync(port);
+    openSockets.push(clientWs);
+
+    // Send list-sessions request
+    const responsePromise = waitForMessageAsync(clientWs);
+    clientWs.send(
+      encodeHostMessage({
+        type: 'list-sessions',
+        requestId: 'req-1',
+      })
+    );
+
+    const response = await responsePromise;
+
+    expect(response.type).toBe('list-sessions-response');
+    expect(response).toHaveProperty('requestId', 'req-1');
+    expect(response).toHaveProperty('sessions');
+    expect((response as { sessions: unknown[] }).sessions).toEqual([]);
+  });
+
+  it('host responds to list-instances request from client WebSocket', async () => {
+    host = new BridgeHost();
+    const port = await host.startAsync({ port: 0 });
+    wireHostAndTracker(host);
+
+    const clientWs = await connectClientWsAsync(port);
+    openSockets.push(clientWs);
+
+    // Send list-instances request
+    const responsePromise = waitForMessageAsync(clientWs);
+    clientWs.send(
+      encodeHostMessage({
+        type: 'list-instances',
+        requestId: 'req-2',
+      })
+    );
+
+    const response = await responsePromise;
+
+    expect(response.type).toBe('list-instances-response');
+    expect(response).toHaveProperty('requestId', 'req-2');
+    expect(response).toHaveProperty('instances');
+    expect((response as { instances: unknown[] }).instances).toEqual([]);
+  });
+
+  it('client WebSocket receives session-event when plugin connects', async () => {
+    host = new BridgeHost();
+    const port = await host.startAsync({ port: 0 });
+    wireHostAndTracker(host);
+
+    // Connect a client first so it can receive the broadcast
+    const clientWs = await connectClientWsAsync(port);
+    openSockets.push(clientWs);
+
+    // Set up listener before plugin connects
+    const eventPromise = waitForMessageAsync(clientWs);
+
+    // Connect a plugin and register
+    const pluginWs = await connectPluginWsAsync(port);
+    openSockets.push(pluginWs);
+
+    await registerPluginAsync(pluginWs, {
+      sessionId: 'test-session-1',
+      instanceId: 'game-123',
+      placeName: 'TestPlace',
+      pluginVersion: '0.7.0',
+      state: 'Edit',
+      capabilities: ['execute'],
+    });
+
+    const event = await eventPromise;
+
+    expect(event.type).toBe('session-event');
+    expect(event).toHaveProperty('event', 'connected');
+    expect(event).toHaveProperty('sessionId', 'test-session-1');
+  });
+
+  it('client WebSocket receives session-event when plugin disconnects', async () => {
+    host = new BridgeHost();
+    const port = await host.startAsync({ port: 0 });
+    wireHostAndTracker(host);
+
+    const clientWs = await connectClientWsAsync(port);
+    openSockets.push(clientWs);
+
+    // Connect and register a plugin
+    const pluginWs = await connectPluginWsAsync(port);
+    openSockets.push(pluginWs);
+
+    // Wait for the connected event first
+    const connectedPromise = waitForMessageAsync(clientWs);
+
+    await registerPluginAsync(pluginWs, {
+      sessionId: 'test-session-1',
+      instanceId: 'game-123',
+    });
+
+    await connectedPromise;
+
+    // Now set up listener for the disconnected event
+    const disconnectPromise = waitForMessageAsync(clientWs);
+
+    // Close the plugin WebSocket
+    pluginWs.close();
+
+    const event = await disconnectPromise;
+
+    expect(event.type).toBe('session-event');
+    expect(event).toHaveProperty('event', 'disconnected');
+    expect(event).toHaveProperty('sessionId', 'test-session-1');
+  });
+
+  it('list-sessions returns connected plugin after register', async () => {
+    host = new BridgeHost();
+    const port = await host.startAsync({ port: 0 });
+    wireHostAndTracker(host);
+
+    const clientWs = await connectClientWsAsync(port);
+    openSockets.push(clientWs);
+
+    // Connect and register a plugin
+    const pluginWs = await connectPluginWsAsync(port);
+    openSockets.push(pluginWs);
+
+    // Wait for the connected session-event so we know the tracker has the session
+    const connectedPromise = waitForMessageAsync(clientWs);
+
+    await registerPluginAsync(pluginWs, {
+      sessionId: 'test-session-1',
+      instanceId: 'game-123',
+      placeName: 'TestPlace',
+      pluginVersion: '0.7.0',
+      state: 'Edit',
+      capabilities: ['execute'],
+    });
+
+    await connectedPromise;
+
+    // Now send list-sessions
+    const responsePromise = waitForMessageAsync(clientWs);
+    clientWs.send(
+      encodeHostMessage({
+        type: 'list-sessions',
+        requestId: 'req-ls-1',
+      })
+    );
+
+    const response = await responsePromise;
+
+    expect(response.type).toBe('list-sessions-response');
+    expect(response).toHaveProperty('requestId', 'req-ls-1');
+
+    const sessions = (response as { sessions: SessionInfo[] }).sessions;
+    expect(sessions).toHaveLength(1);
+    expect(sessions[0].sessionId).toBe('test-session-1');
+    expect(sessions[0].instanceId).toBe('game-123');
+    expect(sessions[0].placeName).toBe('TestPlace');
+  });
+});