@quenty/studio-bridge 0.7.0 → 0.8.0

package/src/test/e2e/split-server.test.ts

@@ -0,0 +1,290 @@
+/**
+ * End-to-end tests for split-server mode. A BridgeHost accepts plugin
+ * connections on /plugin and CLI client connections on /client. Verifies
+ * that multiple clients can coexist with the host without interfering
+ * with plugin sessions.
+ *
+ * Note: The current BridgeHost does not implement full host-protocol
+ * message routing (list-sessions, host-envelope relay). These tests
+ * exercise the real transport layer and connection lifecycle, not the
+ * relay protocol. Split-server relay is tested via BridgeConnection
+ * with a mock host (see bridge-connection-remote.test.ts).
+ */
+
+import { describe, it, expect, afterEach } from 'vitest';
+import { WebSocket } from 'ws';
+import { BridgeHost } from '../../bridge/internal/bridge-host.js';
+import { MockPluginClient } from '../helpers/mock-plugin-client.js';
+import type { PluginSessionInfo } from '../../bridge/internal/bridge-host.js';
+
+function connectClient(port: number): Promise<WebSocket> {
+  return new Promise((resolve, reject) => {
+    const ws = new WebSocket(`ws://localhost:${port}/client`);
+    ws.on('open', () => resolve(ws));
+    ws.on('error', reject);
+  });
+}
+
+describe('split-server e2e', () => {
+  let host: BridgeHost | undefined;
+  const plugins: MockPluginClient[] = [];
+  const clients: WebSocket[] = [];
+
+  afterEach(async () => {
+    for (const plugin of plugins) {
+      await plugin.disconnectAsync();
+    }
+    plugins.length = 0;
+
+    for (const ws of clients) {
+      if (
+        ws.readyState === WebSocket.OPEN ||
+        ws.readyState === WebSocket.CONNECTING
+      ) {
+        ws.close();
+      }
+    }
+    clients.length = 0;
+
+    if (host) {
+      await host.stopAsync();
+      host = undefined;
+    }
+  });
+
+  it('client connects to existing host', async () => {
+    host = new BridgeHost();
+    const port = await host.startAsync({ port: 0 });
+    expect(port).toBeGreaterThan(0);
+
+    // Connect a plugin
+    const plugin = new MockPluginClient({
+      port,
+      instanceId: 'inst-split-1',
+      placeName: 'SplitPlace',
+    });
+    plugins.push(plugin);
+    await plugin.connectAndRegisterAsync();
+    await new Promise((r) => setTimeout(r, 50));
+
+    expect(host.pluginCount).toBe(1);
+
+    // Connect a client on /client path
+    const clientWs = await connectClient(port);
+    clients.push(clientWs);
+
+    expect(clientWs.readyState).toBe(WebSocket.OPEN);
+  });
+
+  it('client can list sessions from host via plugin-connected events', async () => {
+    host = new BridgeHost();
+    const port = await host.startAsync({ port: 0 });
+
+    // Track plugin-connected events
+    const connectedSessions: PluginSessionInfo[] = [];
+    host.on('plugin-connected', (info: PluginSessionInfo) => {
+      connectedSessions.push(info);
+    });
+
+    // Connect two plugins
+    const pluginA = new MockPluginClient({
+      port,
+      instanceId: 'inst-list-A',
+      placeName: 'PlaceA',
+    });
+    plugins.push(pluginA);
+    await pluginA.connectAndRegisterAsync();
+
+    const pluginB = new MockPluginClient({
+      port,
+      instanceId: 'inst-list-B',
+      placeName: 'PlaceB',
+    });
+    plugins.push(pluginB);
+    await pluginB.connectAndRegisterAsync();
+    await new Promise((r) => setTimeout(r, 50));
+
+    expect(host.pluginCount).toBe(2);
+    expect(connectedSessions).toHaveLength(2);
+
+    const sessionIds = connectedSessions.map((s) => s.sessionId).sort();
+    expect(sessionIds).toContain(pluginA.sessionId);
+    expect(sessionIds).toContain(pluginB.sessionId);
+
+    // Verify instance metadata
+    const sessionA = connectedSessions.find(
+      (s) => s.sessionId === pluginA.sessionId
+    );
+    expect(sessionA!.placeName).toBe('PlaceA');
+    expect(sessionA!.instanceId).toBe('inst-list-A');
+
+    const sessionB = connectedSessions.find(
+      (s) => s.sessionId === pluginB.sessionId
+    );
+    expect(sessionB!.placeName).toBe('PlaceB');
+    expect(sessionB!.instanceId).toBe('inst-list-B');
+  });
+
+  it('plugin and client coexist on the same host without interference', async () => {
+    host = new BridgeHost();
+    const port = await host.startAsync({ port: 0 });
+
+    // Connect plugin with execute capability
+    const plugin = new MockPluginClient({
+      port,
+      instanceId: 'inst-relay',
+      capabilities: ['execute', 'queryState'],
+    });
+    plugins.push(plugin);
+    await plugin.connectAndRegisterAsync();
+    await new Promise((r) => setTimeout(r, 50));
+
+    // Connect a client
+    const clientWs = await connectClient(port);
+    clients.push(clientWs);
+
+    // Both connections should be active
+    expect(host.pluginCount).toBe(1);
+    expect(plugin.isConnected).toBe(true);
+    expect(clientWs.readyState).toBe(WebSocket.OPEN);
+
+    // Plugin can send heartbeats without affecting the client
+    plugin.sendMessage({
+      type: 'heartbeat',
+      sessionId: plugin.sessionId,
+      payload: {
+        uptimeMs: 5000,
+        state: 'Edit',
+        pendingRequests: 0,
+      },
+    });
+
+    await new Promise((r) => setTimeout(r, 50));
+
+    // Client can send data without affecting the plugin
+    clientWs.send(JSON.stringify({ type: 'ping' }));
+
+    await new Promise((r) => setTimeout(r, 50));
+
+    // Both should still be connected
+    expect(plugin.isConnected).toBe(true);
+    expect(clientWs.readyState).toBe(WebSocket.OPEN);
+    expect(host.pluginCount).toBe(1);
+  });
+
+  it('client disconnect does not affect host or plugin', async () => {
+    host = new BridgeHost();
+    const port = await host.startAsync({ port: 0 });
+
+    const plugin = new MockPluginClient({
+      port,
+      instanceId: 'inst-client-dc',
+    });
+    plugins.push(plugin);
+    await plugin.connectAndRegisterAsync();
+    await new Promise((r) => setTimeout(r, 50));
+
+    // Connect client
+    const clientWs = await connectClient(port);
+    clients.push(clientWs);
+
+    expect(host.pluginCount).toBe(1);
+
+    // Disconnect the client
+    clientWs.close();
+    await new Promise((r) => setTimeout(r, 100));
+
+    // Host should still be running
+    expect(host.isRunning).toBe(true);
+    expect(host.pluginCount).toBe(1);
+
+    // Plugin should still be connected
+    expect(plugin.isConnected).toBe(true);
+  });
+
+  it('plugin disconnect does not affect connected clients', async () => {
+    host = new BridgeHost();
+    const port = await host.startAsync({ port: 0 });
+
+    const plugin = new MockPluginClient({
+      port,
+      instanceId: 'inst-plugin-dc',
+    });
+    plugins.push(plugin);
+    await plugin.connectAndRegisterAsync();
+    await new Promise((r) => setTimeout(r, 50));
+
+    // Connect a client
+    const clientWs = await connectClient(port);
+    clients.push(clientWs);
+
+    // Track plugin disconnect
+    const disconnectedPromise = new Promise<string>((resolve) => {
+      host!.on('plugin-disconnected', resolve);
+    });
+
+    // Disconnect the plugin
+    await plugin.disconnectAsync();
+
+    const disconnectedId = await disconnectedPromise;
+    expect(disconnectedId).toBe(plugin.sessionId);
+
+    // Host still running
+    expect(host.isRunning).toBe(true);
+    expect(host.pluginCount).toBe(0);
+
+    // Client still connected
+    expect(clientWs.readyState).toBe(WebSocket.OPEN);
+  });
+
+  it('health endpoint returns correct data with active connections', async () => {
+    host = new BridgeHost();
+    const port = await host.startAsync({ port: 0 });
+
+    // Connect a plugin
+    const plugin = new MockPluginClient({
+      port,
+      instanceId: 'inst-health',
+    });
+    plugins.push(plugin);
+    await plugin.connectAndRegisterAsync();
+    await new Promise((r) => setTimeout(r, 50));
+
+    // Check health endpoint
+    const res = await fetch(`http://localhost:${port}/health`);
+    expect(res.status).toBe(200);
+
+    const body = (await res.json()) as Record<string, unknown>;
+    expect(body.status).toBe('ok');
+    expect(body.port).toBe(port);
+    expect(body.sessions).toBe(1);
+  });
+
+  it('graceful shutdown sends host-transfer notice to clients', async () => {
+    host = new BridgeHost();
+    const port = await host.startAsync({ port: 0 });
+
+    // Connect a client
+    const clientWs = await connectClient(port);
+    clients.push(clientWs);
+
+    // Listen for host-transfer message
+    const transferPromise = new Promise<Record<string, unknown>>((resolve) => {
+      clientWs.on('message', (raw) => {
+        const data = JSON.parse(
+          typeof raw === 'string' ? raw : raw.toString('utf-8')
+        );
+        if (data.type === 'host-transfer') {
+          resolve(data);
+        }
+      });
+    });
+
+    // Graceful shutdown
+    await host.shutdownAsync();
+
+    // The client should have received the host-transfer notice
+    const transferMsg = await transferPromise;
+    expect(transferMsg.type).toBe('host-transfer');
+  });
+});

package/src/test/helpers/mock-plugin-client.ts

@@ -0,0 +1,276 @@
+/**
+ * Reusable mock plugin client for E2E tests. Connects to a bridge host
+ * on the /plugin WebSocket path, sends the register handshake, and
+ * supports receiving and responding to action requests from the host.
+ */
+
+import { randomUUID } from 'crypto';
+import { WebSocket } from 'ws';
+import type {
+  Capability,
+  StudioState,
+} from '../../server/web-socket-protocol.js';
+
+export interface MockPluginClientOptions {
+  port: number;
+  instanceId?: string;
+  context?: 'edit' | 'client' | 'server';
+  placeName?: string;
+  capabilities?: Capability[];
+}
+
+export class MockPluginClient {
+  private _ws: WebSocket | undefined;
+  private _options: Required<MockPluginClientOptions>;
+  private _sessionId: string;
+  private _isConnected = false;
+  private _messageHandlers = new Map<
+    string,
+    Array<(msg: Record<string, unknown>) => void>
+  >();
+  private _allMessageHandlers: Array<(msg: Record<string, unknown>) => void> =
+    [];
+
+  constructor(options: MockPluginClientOptions) {
+    this._sessionId = randomUUID();
+    this._options = {
+      port: options.port,
+      instanceId: options.instanceId ?? randomUUID(),
+      context: options.context ?? 'edit',
+      placeName: options.placeName ?? 'TestPlace',
+      capabilities: options.capabilities ?? ['execute', 'queryState'],
+    };
+  }
+
+  /**
+   * Connect to the bridge host WebSocket endpoint.
+   */
+  async connectAsync(): Promise<void> {
+    const url = `ws://localhost:${this._options.port}/plugin`;
+    this._ws = new WebSocket(url);
+
+    await new Promise<void>((resolve, reject) => {
+      this._ws!.on('open', () => {
+        this._isConnected = true;
+        resolve();
+      });
+      this._ws!.on('error', reject);
+    });
+
+    // Set up message routing
+    this._ws.on('message', (raw) => {
+      const data = typeof raw === 'string' ? raw : raw.toString('utf-8');
+      let msg: Record<string, unknown>;
+      try {
+        msg = JSON.parse(data) as Record<string, unknown>;
+      } catch {
+        return;
+      }
+
+      const type = msg.type as string;
+
+      // Dispatch to type-specific handlers
+      const handlers = this._messageHandlers.get(type);
+      if (handlers) {
+        for (const handler of [...handlers]) {
+          handler(msg);
+        }
+      }
+
+      // Dispatch to all-message handlers
+      for (const handler of [...this._allMessageHandlers]) {
+        handler(msg);
+      }
+    });
+
+    this._ws.on('close', () => {
+      this._isConnected = false;
+    });
+
+    this._ws.on('error', () => {
+      // Errors handled via close
+    });
+  }
+
+  /**
+   * Send a v2 register message to the bridge host.
+   */
+  async sendRegisterAsync(): Promise<void> {
+    if (!this._ws || !this._isConnected) {
+      throw new Error('MockPluginClient is not connected');
+    }
+
+    const stateMap: Record<string, StudioState> = {
+      edit: 'Edit',
+      client: 'Client',
+      server: 'Server',
+    };
+
+    this._ws.send(
+      JSON.stringify({
+        type: 'register',
+        sessionId: this._sessionId,
+        payload: {
+          pluginVersion: '2.0.0-test',
+          instanceId: this._options.instanceId,
+          placeName: this._options.placeName,
+          state: stateMap[this._options.context] ?? 'Edit',
+          capabilities: this._options.capabilities,
+        },
+      })
+    );
+  }
+
+  /**
+   * Wait for a specific message type from the host. Returns the full message.
+   */
+  async waitForMessageAsync(
+    type: string,
+    timeoutMs = 5_000
+  ): Promise<Record<string, unknown>> {
+    return new Promise<Record<string, unknown>>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        cleanup();
+        reject(
+          new Error(
+            `Timed out waiting for '${type}' message after ${timeoutMs}ms`
+          )
+        );
+      }, timeoutMs);
+
+      const handler = (msg: Record<string, unknown>) => {
+        clearTimeout(timer);
+        cleanup();
+        resolve(msg);
+      };
+
+      const cleanup = () => {
+        const handlers = this._messageHandlers.get(type);
+        if (handlers) {
+          const idx = handlers.indexOf(handler);
+          if (idx >= 0) handlers.splice(idx, 1);
+        }
+      };
+
+      this._addHandler(type, handler);
+    });
+  }
+
+  /**
+   * Send a raw JSON message to the host.
+   */
+  sendMessage(msg: Record<string, unknown>): void {
+    if (!this._ws || !this._isConnected) {
+      throw new Error('MockPluginClient is not connected');
+    }
+    this._ws.send(JSON.stringify(msg));
+  }
+
+  /**
+   * Register a one-time handler for a specific message type.
+   */
+  onMessage(
+    type: string,
+    handler: (msg: Record<string, unknown>) => void
+  ): void {
+    this._addHandler(type, handler);
+  }
+
+  /**
+   * Register a handler called for every incoming message.
+   */
+  onAnyMessage(handler: (msg: Record<string, unknown>) => void): void {
+    this._allMessageHandlers.push(handler);
+  }
+
+  /**
+   * Auto-respond to action requests from the host. Sets up a handler
+   * that replies with the given response when an action of the specified
+   * type is received. The requestId is automatically copied from the
+   * incoming request.
+   */
+  autoRespond(
+    actionType: string,
+    responseFactory: (
+      request: Record<string, unknown>
+    ) => Record<string, unknown>
+  ): void {
+    this.onAnyMessage((msg) => {
+      if (msg.type === actionType) {
+        const response = responseFactory(msg);
+        // Copy requestId from the incoming request
+        if (msg.requestId) {
+          response.requestId = msg.requestId;
+        }
+        if (!response.sessionId) {
+          response.sessionId = this._sessionId;
+        }
+        this.sendMessage(response);
+      }
+    });
+  }
+
+  /**
+   * Disconnect from the host.
+   */
+  async disconnectAsync(): Promise<void> {
+    if (this._ws) {
+      if (
+        this._ws.readyState === WebSocket.OPEN ||
+        this._ws.readyState === WebSocket.CONNECTING
+      ) {
+        this._ws.close();
+        // Wait for close to complete
+        await new Promise<void>((resolve) => {
+          this._ws!.on('close', resolve);
+          // If already closed, resolve immediately
+          if (this._ws!.readyState === WebSocket.CLOSED) {
+            resolve();
+          }
+        });
+      }
+      this._ws = undefined;
+    }
+    this._isConnected = false;
+    this._messageHandlers.clear();
+    this._allMessageHandlers = [];
+  }
+
+  /** Whether the client is currently connected. */
+  get isConnected(): boolean {
+    return this._isConnected;
+  }
+
+  /** The auto-generated session ID for this mock plugin. */
+  get sessionId(): string {
+    return this._sessionId;
+  }
+
+  /** The instance ID. */
+  get instanceId(): string {
+    return this._options.instanceId;
+  }
+
+  /**
+   * Connect and send register. Returns the session ID assigned to this client.
+   */
+  async connectAndRegisterAsync(): Promise<string> {
+    await this.connectAsync();
+    await this.sendRegisterAsync();
+    // Yield to let the host process the register before the test continues
+    await new Promise((r) => setTimeout(r, 20));
+    return this._sessionId;
+  }
+
+  private _addHandler(
+    type: string,
+    handler: (msg: Record<string, unknown>) => void
+  ): void {
+    let handlers = this._messageHandlers.get(type);
+    if (!handlers) {
+      handlers = [];
+      this._messageHandlers.set(type, handlers);
+    }
+    handlers.push(handler);
+  }
+}