@quenty/studio-bridge 0.7.1 → 0.8.0

package/src/bridge/index.ts

@@ -0,0 +1,42 @@
+/**
+ * Public API surface for the bridge module.
+ *
+ * Re-exports ONLY public types — nothing from internal/ leaks out.
+ * Consumers import from '@quenty/studio-bridge/bridge' (or this index)
+ * and get BridgeConnection, BridgeSession, typed results, and errors.
+ */
+
+// Classes
+export { BridgeConnection } from './bridge-connection.js';
+export type { BridgeConnectionOptions } from './bridge-connection.js';
+export { BridgeSession } from './bridge-session.js';
+
+// Types
+export type {
+  SessionInfo,
+  InstanceInfo,
+  SessionContext,
+  SessionOrigin,
+  ExecResult,
+  StateResult,
+  ScreenshotResult,
+  LogsResult,
+  DataModelResult,
+  LogEntry,
+  LogOptions,
+  QueryDataModelOptions,
+  LogFollowOptions,
+  StudioState,
+  DataModelInstance,
+  OutputLevel,
+} from './types.js';
+
+// Error classes
+export {
+  SessionNotFoundError,
+  ActionTimeoutError,
+  SessionDisconnectedError,
+  CapabilityNotSupportedError,
+  ContextNotFoundError,
+  HostUnreachableError,
+} from './types.js';

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

@@ -0,0 +1,191 @@
+/**
+ * Integration tests for crash-recovery failover. Verifies that when a host
+ * process dies without sending a HostTransferNotice, clients detect the
+ * disconnect, apply random jitter, and race to bind the port.
+ *
+ * Uses real BridgeHost and HandOffManager instances with ephemeral ports.
+ */
+
+import { describe, it, expect, afterEach, vi } from 'vitest';
+import { WebSocket } from 'ws';
+import { BridgeHost } from '../bridge-host.js';
+import { HandOffManager, computeTakeoverJitterMs } from '../hand-off.js';
+
+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 waitForClose(ws: WebSocket, timeoutMs = 5_000): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    if (ws.readyState === WebSocket.CLOSED) {
+      resolve();
+      return;
+    }
+    const timer = setTimeout(() => {
+      reject(new Error('Timed out waiting for WebSocket close'));
+    }, timeoutMs);
+    ws.on('close', () => {
+      clearTimeout(timer);
+      resolve();
+    });
+  });
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise<void>((resolve) => setTimeout(resolve, ms));
+}
+
+describe('Crash recovery failover', () => {
+  let host: BridgeHost | undefined;
+  let clientWs: WebSocket | undefined;
+  let newHost: BridgeHost | undefined;
+
+  afterEach(async () => {
+    if (clientWs) {
+      if (
+        clientWs.readyState === WebSocket.OPEN ||
+        clientWs.readyState === WebSocket.CONNECTING
+      ) {
+        clientWs.terminate();
+      }
+      clientWs = undefined;
+    }
+    if (host) {
+      try {
+        await host.stopAsync();
+      } catch {
+        /* ignore */
+      }
+      host = undefined;
+    }
+    if (newHost) {
+      try {
+        await newHost.stopAsync();
+      } catch {
+        /* ignore */
+      }
+      newHost = undefined;
+    }
+  });
+
+  it('client detects crash and takes over after jitter', async () => {
+    host = new BridgeHost();
+    const port = await host.startAsync({ port: 0 });
+
+    clientWs = await connectClientWsAsync(port);
+
+    // Force-close the host (simulates crash — no HostTransferNotice sent)
+    await host.stopAsync();
+    host = undefined;
+
+    // Wait for the client WebSocket to detect the close
+    await waitForClose(clientWs);
+
+    // Client did NOT receive a transfer notice, so this is a crash path
+    const handOff = new HandOffManager({ port });
+    // Do NOT call onHostTransferNotice — this is a crash
+
+    const outcome = await handOff.onHostDisconnectedAsync();
+    expect(outcome).toBe('promoted');
+    expect(handOff.state).toBe('promoted');
+  });
+
+  it('crash jitter is in [0, 500ms] range', () => {
+    // Verify the jitter function produces values in the correct range
+    for (let i = 0; i < 200; i++) {
+      const jitter = computeTakeoverJitterMs({ graceful: false });
+      expect(jitter).toBeGreaterThanOrEqual(0);
+      expect(jitter).toBeLessThanOrEqual(500);
+    }
+  });
+
+  it('crash jitter is zero for graceful shutdowns', () => {
+    const jitter = computeTakeoverJitterMs({ graceful: true });
+    expect(jitter).toBe(0);
+  });
+
+  it('multiple clients after crash: exactly one wins the port bind race', async () => {
+    host = new BridgeHost();
+    const port = await host.startAsync({ port: 0 });
+
+    // Connect two clients
+    const ws1 = await connectClientWsAsync(port);
+    const ws2 = await connectClientWsAsync(port);
+
+    // Force-close the host (crash)
+    await host.stopAsync();
+    host = undefined;
+
+    // Wait for both clients to detect the close
+    await Promise.all([waitForClose(ws1), waitForClose(ws2)]);
+
+    // Both clients attempt takeover without transfer notice (crash path).
+    // We need to coordinate: the first one to bind starts a new host so the
+    // second can fall back.
+    const handOff1 = new HandOffManager({ port });
+    const handOff2 = new HandOffManager({ port });
+
+    // Zero-jitter for determinism: mock Math.random to return 0
+    const randomSpy = vi.spyOn(Math, 'random').mockReturnValue(0);
+
+    const results = await Promise.allSettled([
+      (async () => {
+        const result = await handOff1.onHostDisconnectedAsync();
+        if (result === 'promoted') {
+          // Bind the port so the other client can fall back
+          newHost = new BridgeHost();
+          await newHost.startAsync({ port });
+        }
+        return result;
+      })(),
+      (async () => {
+        // Small delay so the first client binds first
+        await delay(100);
+        return handOff2.onHostDisconnectedAsync();
+      })(),
+    ]);
+
+    randomSpy.mockRestore();
+
+    const fulfilled = results
+      .filter(
+        (r): r is PromiseFulfilledResult<'promoted' | 'fell-back-to-client'> =>
+          r.status === 'fulfilled'
+      )
+      .map((r) => r.value);
+
+    // At least one should be promoted
+    expect(fulfilled.filter((o) => o === 'promoted')).toHaveLength(1);
+
+    // Clean up
+    ws1.terminate();
+    ws2.terminate();
+    clientWs = undefined;
+  });
+
+  it('takeover succeeds even when host port is briefly in TIME_WAIT', async () => {
+    // This test verifies that after a host stops, the port becomes available
+    // quickly enough for takeover. Node's SO_REUSEADDR helps here.
+    host = new BridgeHost();
+    const port = await host.startAsync({ port: 0 });
+
+    await host.stopAsync();
+    host = undefined;
+
+    // Immediately try to bind
+    const handOff = new HandOffManager({ port });
+    handOff.onHostTransferNotice(); // skip jitter
+
+    const outcome = await handOff.onHostDisconnectedAsync();
+    expect(outcome).toBe('promoted');
+
+    // Verify the port is actually usable
+    newHost = new BridgeHost();
+    const newPort = await newHost.startAsync({ port });
+    expect(newPort).toBe(port);
+  });
+});

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

@@ -0,0 +1,268 @@
+/**
+ * Integration tests for graceful host shutdown failover. Verifies that when
+ * a host calls shutdownAsync(), clients receive the HostTransferNotice and
+ * one of them successfully takes over as the new host.
+ *
+ * Uses real BridgeHost and HandOffManager instances with ephemeral ports.
+ */
+
+import { describe, it, expect, afterEach } from 'vitest';
+import { WebSocket } from 'ws';
+import { BridgeHost } from '../bridge-host.js';
+import { HandOffManager } from '../hand-off.js';
+import { decodeHostMessage } from '../host-protocol.js';
+
+/** Wait for a WebSocket message matching a predicate. */
+function waitForMessageAsync(
+  ws: WebSocket,
+  predicate: (data: string) => boolean,
+  timeoutMs = 5_000
+): Promise<string> {
+  return new Promise<string>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      ws.off('message', onMessage);
+      reject(new Error('Timed out waiting for message'));
+    }, timeoutMs);
+
+    const onMessage = (raw: Buffer | string) => {
+      const data = typeof raw === 'string' ? raw : raw.toString('utf-8');
+      if (predicate(data)) {
+        clearTimeout(timer);
+        ws.off('message', onMessage);
+        resolve(data);
+      }
+    };
+
+    ws.on('message', onMessage);
+  });
+}
+
+/** Connect a raw WebSocket to the host's /client path. */
+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 delay(ms: number): Promise<void> {
+  return new Promise<void>((resolve) => setTimeout(resolve, ms));
+}
+
+describe('Graceful shutdown failover', () => {
+  let host: BridgeHost | undefined;
+  let clientWs: WebSocket | undefined;
+  let newHost: BridgeHost | undefined;
+
+  afterEach(async () => {
+    if (clientWs) {
+      if (
+        clientWs.readyState === WebSocket.OPEN ||
+        clientWs.readyState === WebSocket.CONNECTING
+      ) {
+        clientWs.terminate();
+      }
+      clientWs = undefined;
+    }
+    if (host) {
+      try {
+        await host.stopAsync();
+      } catch {
+        /* ignore */
+      }
+      host = undefined;
+    }
+    if (newHost) {
+      try {
+        await newHost.stopAsync();
+      } catch {
+        /* ignore */
+      }
+      newHost = undefined;
+    }
+  });
+
+  it('client receives host-transfer notice on graceful shutdown', async () => {
+    host = new BridgeHost();
+    const port = await host.startAsync({ port: 0 });
+
+    clientWs = await connectClientWsAsync(port);
+
+    // Start listening for the transfer notice BEFORE triggering shutdown
+    const noticePromise = waitForMessageAsync(clientWs, (data) => {
+      const msg = decodeHostMessage(data);
+      return msg?.type === 'host-transfer';
+    });
+
+    // Trigger graceful shutdown
+    await host.shutdownAsync();
+    host = undefined;
+
+    // Client should have received the notice
+    const noticeData = await noticePromise;
+    const msg = decodeHostMessage(noticeData);
+    expect(msg).not.toBeNull();
+    expect(msg!.type).toBe('host-transfer');
+  });
+
+  it('client takes over as host after graceful shutdown', async () => {
+    host = new BridgeHost();
+    const port = await host.startAsync({ port: 0 });
+
+    clientWs = await connectClientWsAsync(port);
+
+    // Set up HandOffManager for this client
+    const handOff = new HandOffManager({ port });
+
+    // Start listening for transfer notice
+    const noticePromise = waitForMessageAsync(clientWs, (data) => {
+      const msg = decodeHostMessage(data);
+      return msg?.type === 'host-transfer';
+    });
+
+    // Trigger graceful shutdown
+    await host.shutdownAsync();
+    host = undefined;
+
+    // Wait for the notice to arrive
+    await noticePromise;
+    handOff.onHostTransferNotice();
+
+    // Client detects disconnect and runs takeover
+    const outcome = await handOff.onHostDisconnectedAsync();
+    expect(outcome).toBe('promoted');
+    expect(handOff.state).toBe('promoted');
+
+    // Verify the port is actually free — new host can bind
+    newHost = new BridgeHost();
+    const newPort = await newHost.startAsync({ port });
+    expect(newPort).toBe(port);
+  });
+
+  it('multiple clients: exactly one becomes host, others fall back', async () => {
+    host = new BridgeHost();
+    const port = await host.startAsync({ port: 0 });
+
+    // Connect two clients
+    const ws1 = await connectClientWsAsync(port);
+    const ws2 = await connectClientWsAsync(port);
+
+    const notice1Promise = waitForMessageAsync(ws1, (data) => {
+      const msg = decodeHostMessage(data);
+      return msg?.type === 'host-transfer';
+    });
+    const notice2Promise = waitForMessageAsync(ws2, (data) => {
+      const msg = decodeHostMessage(data);
+      return msg?.type === 'host-transfer';
+    });
+
+    // Graceful shutdown
+    await host.shutdownAsync();
+    host = undefined;
+
+    // Both clients should receive the notice
+    await Promise.all([notice1Promise, notice2Promise]);
+
+    // Both run the takeover state machine (one must bind, other must fall back)
+    const handOff1 = new HandOffManager({ port });
+    handOff1.onHostTransferNotice();
+
+    const handOff2 = new HandOffManager({ port });
+    handOff2.onHostTransferNotice();
+
+    // Simulate both clients starting takeover.
+    // One will bind the port and succeed, the other will fail to bind.
+    // We need to actually bind a host for the fallback client to connect to.
+
+    // Race them: first one to bind starts a new host
+    const results = await Promise.allSettled([
+      (async () => {
+        const result = await handOff1.onHostDisconnectedAsync();
+        if (result === 'promoted') {
+          newHost = new BridgeHost();
+          await newHost.startAsync({ port });
+        }
+        return result;
+      })(),
+      (async () => {
+        // Small delay to avoid thundering herd in test
+        await delay(50);
+        return handOff2.onHostDisconnectedAsync();
+      })(),
+    ]);
+
+    const outcomes = results
+      .filter(
+        (r): r is PromiseFulfilledResult<'promoted' | 'fell-back-to-client'> =>
+          r.status === 'fulfilled'
+      )
+      .map((r) => r.value);
+
+    // Exactly one should be promoted
+    expect(outcomes.filter((o) => o === 'promoted')).toHaveLength(1);
+    // The other should fall back (or the second could also get promoted if the first
+    // hasn't bound yet, but with the delay this is deterministic)
+
+    // Clean up WebSockets
+    ws1.terminate();
+    ws2.terminate();
+    clientWs = undefined; // prevent double-cleanup
+  });
+
+  it('plugin reconnects to the new host after failover', async () => {
+    host = new BridgeHost();
+    const port = await host.startAsync({ port: 0 });
+
+    clientWs = await connectClientWsAsync(port);
+
+    const noticePromise = waitForMessageAsync(clientWs, (data) => {
+      const msg = decodeHostMessage(data);
+      return msg?.type === 'host-transfer';
+    });
+
+    // Shutdown the original host
+    await host.shutdownAsync();
+    host = undefined;
+    await noticePromise;
+
+    // Start a new host on the same port
+    newHost = new BridgeHost();
+    const newPort = await newHost.startAsync({ port });
+    expect(newPort).toBe(port);
+
+    // Verify a plugin can connect to the new host
+    const pluginConnectedPromise = new Promise<string>((resolve) => {
+      newHost!.on('plugin-connected', (info: { sessionId: string }) => {
+        resolve(info.sessionId);
+      });
+    });
+
+    // Simulate a plugin connecting
+    const pluginWs = new WebSocket(`ws://localhost:${port}/plugin`);
+    await new Promise<void>((resolve, reject) => {
+      pluginWs.on('open', () => {
+        pluginWs.send(
+          JSON.stringify({
+            type: 'register',
+            sessionId: 'plugin-session-1',
+            payload: {
+              pluginVersion: '1.0.0',
+              instanceId: 'inst-1',
+              placeName: 'TestPlace',
+              state: 'Edit',
+              capabilities: ['execute'],
+            },
+          })
+        );
+        resolve();
+      });
+      pluginWs.on('error', reject);
+    });
+
+    const connectedSessionId = await pluginConnectedPromise;
+    expect(connectedSessionId).toBe('plugin-session-1');
+
+    pluginWs.terminate();
+  });
+});