@quenty/studio-bridge 0.7.0 → 0.8.0

package/src/bridge/internal/environment-detection.ts

@@ -0,0 +1,119 @@
+/**
+ * Role detection utility for the bridge network. Determines whether the
+ * current process should act as a bridge host or bridge client by attempting
+ * to bind the port and probing the health endpoint.
+ *
+ * Algorithm:
+ * 1. If `remoteHost` specified -> client
+ * 2. Try to bind port -> host
+ * 3. EADDRINUSE -> check health endpoint
+ *    a. Health succeeds -> client (host is alive)
+ *    b. Health fails -> wait, retry bind (stale host)
+ */
+
+import { existsSync } from 'node:fs';
+import { TransportServer } from './transport-server.js';
+import { checkHealthAsync } from './health-endpoint.js';
+
+export type DetectedRole = 'host' | 'client';
+
+export interface DetectRoleResult {
+  role: DetectedRole;
+  server?: TransportServer;
+  port: number;
+}
+
+const STALE_RETRY_DELAY_MS = 1_000;
+const MAX_STALE_RETRIES = 3;
+const DEFAULT_BRIDGE_PORT = 38741;
+
+/**
+ * Detect whether this process should act as a bridge host or client.
+ *
+ * - If `remoteHost` is specified, always returns 'client'.
+ * - Otherwise, tries to bind the port. Success means 'host'.
+ * - If EADDRINUSE, probes the health endpoint:
+ *   - If healthy, returns 'client'.
+ *   - If unhealthy (stale port), waits and retries the bind.
+ */
+export async function detectRoleAsync(options: {
+  port: number;
+  remoteHost?: string;
+}): Promise<DetectRoleResult> {
+  // If remoteHost is specified, always connect as client
+  if (options.remoteHost) {
+    return { role: 'client', port: options.port };
+  }
+
+  // Try to bind the port, with retries for stale ports
+  for (let attempt = 0; attempt <= MAX_STALE_RETRIES; attempt++) {
+    const server = new TransportServer();
+
+    try {
+      const boundPort = await server.startAsync({ port: options.port });
+      // We successfully bound -- we are the host.
+      // Stop the server for now; the caller (BridgeConnection) will
+      // use this server instance to set up BridgeHost.
+      // Actually, we return the server still listening so the caller
+      // can reuse it. But BridgeHost creates its own TransportServer.
+      // So we stop it and let the caller know to create a BridgeHost.
+      await server.stopAsync();
+      return { role: 'host', port: boundPort };
+    } catch (err: unknown) {
+      const isAddressInUse =
+        err instanceof Error &&
+        (err.message.includes('already in use') ||
+          (err as NodeJS.ErrnoException).code === 'EADDRINUSE');
+
+      if (!isAddressInUse) {
+        throw err;
+      }
+
+      // Port is in use -- check if a healthy bridge host is there
+      const health = await checkHealthAsync(options.port);
+
+      if (health) {
+        // A live bridge host is running; become a client
+        return { role: 'client', port: options.port };
+      }
+
+      // Health check failed -- stale port. Wait and retry.
+      if (attempt < MAX_STALE_RETRIES) {
+        await new Promise((resolve) =>
+          setTimeout(resolve, STALE_RETRY_DELAY_MS)
+        );
+      }
+    }
+  }
+
+  // All retries exhausted
+  throw new Error(
+    `Port ${options.port} is held by another process and no bridge host responded on /health. ` +
+      `The port may be in use by a non-bridge process.`
+  );
+}
+
+/**
+ * Detect whether running inside a devcontainer.
+ * Checks: REMOTE_CONTAINERS, CODESPACES, CONTAINER env vars, /.dockerenv file.
+ * Wide net -- false positive = 3s delay then fallback. False negative = user uses --remote.
+ */
+export function isDevcontainer(): boolean {
+  return !!(
+    process.env.REMOTE_CONTAINERS ||
+    process.env.CODESPACES ||
+    process.env.CONTAINER ||
+    existsSync('/.dockerenv')
+  );
+}
+
+/**
+ * Get default remote host for devcontainer environments.
+ * Returns "localhost:38741" inside devcontainer, null otherwise.
+ */
+export function getDefaultRemoteHost(): string | null {
+  if (isDevcontainer()) {
+    return `localhost:${DEFAULT_BRIDGE_PORT}`;
+  }
+  return null;
+}

package/src/bridge/internal/hand-off.test.ts

@@ -0,0 +1,408 @@
+/**
+ * Unit tests for HandOffManager — validates the takeover state machine
+ * transitions, jitter computation, and retry logic using injected
+ * dependencies (no real network).
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import {
+  HandOffManager,
+  computeTakeoverJitterMs,
+  type HandOffDependencies,
+  type HandOffLogEntry,
+} from './hand-off.js';
+import { HostUnreachableError } from '../types.js';
+import { createHealthHandler } from './health-endpoint.js';
+
+function createMockDeps(
+  overrides: Partial<HandOffDependencies> = {}
+): HandOffDependencies {
+  return {
+    tryBindAsync: overrides.tryBindAsync ?? vi.fn().mockResolvedValue(true),
+    tryConnectAsClientAsync:
+      overrides.tryConnectAsClientAsync ?? vi.fn().mockResolvedValue(false),
+    delay: overrides.delay ?? vi.fn().mockResolvedValue(undefined),
+  };
+}
+
+describe('HandOffManager', () => {
+  describe('state machine transitions', () => {
+    it('starts in connected state', () => {
+      const deps = createMockDeps();
+      const manager = new HandOffManager({ port: 38741, deps });
+
+      expect(manager.state).toBe('connected');
+    });
+
+    it('transitions to detecting-failure on HostTransferNotice', () => {
+      const deps = createMockDeps();
+      const manager = new HandOffManager({ port: 38741, deps });
+
+      manager.onHostTransferNotice();
+
+      expect(manager.state).toBe('detecting-failure');
+    });
+
+    it('graceful path: skips jitter, transitions to promoted on bind success', async () => {
+      const deps = createMockDeps({
+        tryBindAsync: vi.fn().mockResolvedValue(true),
+      });
+      const manager = new HandOffManager({ port: 38741, deps });
+
+      manager.onHostTransferNotice();
+      const result = await manager.onHostDisconnectedAsync();
+
+      expect(result).toBe('promoted');
+      expect(manager.state).toBe('promoted');
+      // Delay should not have been called with any jitter value > 0
+      expect(deps.delay).not.toHaveBeenCalled();
+    });
+
+    it('crash path: applies jitter before takeover attempt', async () => {
+      const deps = createMockDeps({
+        tryBindAsync: vi.fn().mockResolvedValue(true),
+        delay: vi.fn().mockResolvedValue(undefined),
+      });
+      const manager = new HandOffManager({ port: 38741, deps });
+
+      // Mock Math.random to return a known value
+      const randomSpy = vi.spyOn(Math, 'random').mockReturnValue(0.5);
+
+      // Do NOT call onHostTransferNotice — this simulates a crash
+      const result = await manager.onHostDisconnectedAsync();
+
+      expect(result).toBe('promoted');
+      expect(manager.state).toBe('promoted');
+      // Should have called delay with jitter (0.5 * 500 = 250ms)
+      expect(deps.delay).toHaveBeenCalledWith(250);
+
+      randomSpy.mockRestore();
+    });
+
+    it('falls back to client when bind fails and another host exists', async () => {
+      const deps = createMockDeps({
+        tryBindAsync: vi.fn().mockResolvedValue(false),
+        tryConnectAsClientAsync: vi.fn().mockResolvedValue(true),
+      });
+      const manager = new HandOffManager({ port: 38741, deps });
+
+      manager.onHostTransferNotice();
+      const result = await manager.onHostDisconnectedAsync();
+
+      expect(result).toBe('fell-back-to-client');
+      expect(manager.state).toBe('fell-back-to-client');
+    });
+
+    it('retries when bind fails and no host reachable', async () => {
+      let bindCallCount = 0;
+      const deps = createMockDeps({
+        tryBindAsync: vi.fn().mockImplementation(async () => {
+          bindCallCount++;
+          // Succeed on the 3rd attempt
+          return bindCallCount >= 3;
+        }),
+        tryConnectAsClientAsync: vi.fn().mockResolvedValue(false),
+        delay: vi.fn().mockResolvedValue(undefined),
+      });
+      const manager = new HandOffManager({ port: 38741, deps });
+
+      manager.onHostTransferNotice();
+      const result = await manager.onHostDisconnectedAsync();
+
+      expect(result).toBe('promoted');
+      expect(manager.state).toBe('promoted');
+      expect(deps.tryBindAsync).toHaveBeenCalledTimes(3);
+      // delay should have been called for retry waits (2 retries before success)
+      expect(deps.delay).toHaveBeenCalledTimes(2);
+      expect(deps.delay).toHaveBeenCalledWith(1_000);
+    });
+
+    it('throws HostUnreachableError after 10 failed retries', async () => {
+      const deps = createMockDeps({
+        tryBindAsync: vi.fn().mockResolvedValue(false),
+        tryConnectAsClientAsync: vi.fn().mockResolvedValue(false),
+        delay: vi.fn().mockResolvedValue(undefined),
+      });
+      const manager = new HandOffManager({ port: 38741, deps });
+
+      manager.onHostTransferNotice();
+
+      await expect(manager.onHostDisconnectedAsync()).rejects.toThrow(
+        HostUnreachableError
+      );
+      expect(deps.tryBindAsync).toHaveBeenCalledTimes(10);
+      expect(deps.tryConnectAsClientAsync).toHaveBeenCalledTimes(10);
+      // 9 retry delays (not called after the last failed attempt)
+      expect(deps.delay).toHaveBeenCalledTimes(9);
+    });
+
+    it('transitions through taking-over before reaching promoted', async () => {
+      const states: string[] = [];
+      const deps = createMockDeps({
+        tryBindAsync: vi.fn().mockImplementation(async () => {
+          states.push(manager.state);
+          return true;
+        }),
+      });
+      const manager = new HandOffManager({ port: 38741, deps });
+
+      manager.onHostTransferNotice();
+      await manager.onHostDisconnectedAsync();
+
+      expect(states).toContain('taking-over');
+      expect(manager.state).toBe('promoted');
+    });
+
+    it('transitions through taking-over before reaching fell-back-to-client', async () => {
+      const states: string[] = [];
+      const deps = createMockDeps({
+        tryBindAsync: vi.fn().mockImplementation(async () => {
+          states.push(manager.state);
+          return false;
+        }),
+        tryConnectAsClientAsync: vi.fn().mockResolvedValue(true),
+      });
+      const manager = new HandOffManager({ port: 38741, deps });
+
+      manager.onHostTransferNotice();
+      await manager.onHostDisconnectedAsync();
+
+      expect(states).toContain('taking-over');
+      expect(manager.state).toBe('fell-back-to-client');
+    });
+  });
+
+  describe('computeTakeoverJitterMs', () => {
+    it('returns 0 for graceful shutdown', () => {
+      expect(computeTakeoverJitterMs({ graceful: true })).toBe(0);
+    });
+
+    it('returns values in [0, 500] for crash', () => {
+      // Run multiple times to verify range
+      for (let i = 0; i < 100; i++) {
+        const jitter = computeTakeoverJitterMs({ graceful: false });
+        expect(jitter).toBeGreaterThanOrEqual(0);
+        expect(jitter).toBeLessThanOrEqual(500);
+      }
+    });
+
+    it('uses Math.random for crash jitter', () => {
+      const randomSpy = vi.spyOn(Math, 'random').mockReturnValue(0.8);
+
+      const jitter = computeTakeoverJitterMs({ graceful: false });
+      expect(jitter).toBe(400); // 0.8 * 500
+
+      randomSpy.mockRestore();
+    });
+  });
+
+  describe('port parameter', () => {
+    it('passes the configured port to tryBindAsync', async () => {
+      const tryBindAsync = vi.fn().mockResolvedValue(true);
+      const deps = createMockDeps({ tryBindAsync });
+      const manager = new HandOffManager({ port: 12345, deps });
+
+      manager.onHostTransferNotice();
+      await manager.onHostDisconnectedAsync();
+
+      expect(tryBindAsync).toHaveBeenCalledWith(12345);
+    });
+
+    it('passes the configured port to tryConnectAsClientAsync', async () => {
+      const tryConnectAsClientAsync = vi.fn().mockResolvedValue(true);
+      const deps = createMockDeps({
+        tryBindAsync: vi.fn().mockResolvedValue(false),
+        tryConnectAsClientAsync,
+      });
+      const manager = new HandOffManager({ port: 54321, deps });
+
+      manager.onHostTransferNotice();
+      await manager.onHostDisconnectedAsync();
+
+      expect(tryConnectAsClientAsync).toHaveBeenCalledWith(54321);
+    });
+  });
+
+  describe('structured debug logging', () => {
+    it('logs state transition on HostTransferNotice', () => {
+      const logger = vi.fn();
+      const deps = createMockDeps();
+      const manager = new HandOffManager({ port: 38741, deps, logger });
+
+      manager.onHostTransferNotice();
+
+      expect(logger).toHaveBeenCalledTimes(1);
+      const entry: HandOffLogEntry = logger.mock.calls[0][0];
+      expect(entry.oldState).toBe('connected');
+      expect(entry.newState).toBe('detecting-failure');
+      expect(entry.reason).toBe('host-transfer-notice');
+      expect(entry.timestamp).toBeDefined();
+    });
+
+    it('logs state transitions during graceful promotion', async () => {
+      const logger = vi.fn();
+      const deps = createMockDeps({
+        tryBindAsync: vi.fn().mockResolvedValue(true),
+      });
+      const manager = new HandOffManager({ port: 38741, deps, logger });
+
+      manager.onHostTransferNotice();
+      await manager.onHostDisconnectedAsync();
+
+      // Should have logs: host-transfer-notice, graceful-disconnect, bind-success
+      const reasons = logger.mock.calls.map((c: any[]) => c[0].reason);
+      expect(reasons).toContain('host-transfer-notice');
+      expect(reasons).toContain('graceful-disconnect');
+      expect(reasons).toContain('bind-success');
+    });
+
+    it('logs crash jitter when not graceful', async () => {
+      const logger = vi.fn();
+      const deps = createMockDeps({
+        tryBindAsync: vi.fn().mockResolvedValue(true),
+        delay: vi.fn().mockResolvedValue(undefined),
+      });
+      const manager = new HandOffManager({ port: 38741, deps, logger });
+
+      const randomSpy = vi.spyOn(Math, 'random').mockReturnValue(0.5);
+      await manager.onHostDisconnectedAsync();
+      randomSpy.mockRestore();
+
+      const reasons = logger.mock.calls.map((c: any[]) => c[0].reason);
+      expect(reasons).toContain('crash-jitter');
+      expect(reasons).toContain('crash-detected');
+    });
+
+    it('logs retry attempts when bind and connect fail', async () => {
+      const logger = vi.fn();
+      let bindCount = 0;
+      const deps = createMockDeps({
+        tryBindAsync: vi.fn().mockImplementation(async () => {
+          bindCount++;
+          return bindCount >= 3;
+        }),
+        tryConnectAsClientAsync: vi.fn().mockResolvedValue(false),
+        delay: vi.fn().mockResolvedValue(undefined),
+      });
+      const manager = new HandOffManager({ port: 38741, deps, logger });
+
+      manager.onHostTransferNotice();
+      await manager.onHostDisconnectedAsync();
+
+      const retryEntries = logger.mock.calls
+        .map((c: any[]) => c[0])
+        .filter((e: HandOffLogEntry) => e.reason === 'retry');
+      expect(retryEntries.length).toBe(2);
+      expect(retryEntries[0].data?.attempt).toBe(0);
+      expect(retryEntries[1].data?.attempt).toBe(1);
+    });
+
+    it('logs retries-exhausted when all attempts fail', async () => {
+      const logger = vi.fn();
+      const deps = createMockDeps({
+        tryBindAsync: vi.fn().mockResolvedValue(false),
+        tryConnectAsClientAsync: vi.fn().mockResolvedValue(false),
+        delay: vi.fn().mockResolvedValue(undefined),
+      });
+      const manager = new HandOffManager({ port: 38741, deps, logger });
+
+      manager.onHostTransferNotice();
+      await expect(manager.onHostDisconnectedAsync()).rejects.toThrow(
+        HostUnreachableError
+      );
+
+      const reasons = logger.mock.calls.map((c: any[]) => c[0].reason);
+      expect(reasons).toContain('retries-exhausted');
+    });
+
+    it('does not throw when no logger is provided', async () => {
+      const deps = createMockDeps({
+        tryBindAsync: vi.fn().mockResolvedValue(true),
+      });
+      const manager = new HandOffManager({ port: 38741, deps });
+
+      manager.onHostTransferNotice();
+      const result = await manager.onHostDisconnectedAsync();
+
+      expect(result).toBe('promoted');
+    });
+
+    it('includes ISO timestamp in every log entry', async () => {
+      const logger = vi.fn();
+      const deps = createMockDeps({
+        tryBindAsync: vi.fn().mockResolvedValue(true),
+      });
+      const manager = new HandOffManager({ port: 38741, deps, logger });
+
+      manager.onHostTransferNotice();
+      await manager.onHostDisconnectedAsync();
+
+      for (const call of logger.mock.calls) {
+        const entry: HandOffLogEntry = call[0];
+        expect(entry.timestamp).toMatch(/^\d{4}-\d{2}-\d{2}T/);
+      }
+    });
+  });
+});
+
+describe('Health endpoint observability fields', () => {
+  it('includes hostUptime and lastFailoverAt in response', () => {
+    const startTime = Date.now() - 10_000;
+    const hostStartTime = Date.now() - 5_000;
+    const lastFailoverAt = new Date(hostStartTime).toISOString();
+
+    const handler = createHealthHandler(() => ({
+      port: 38741,
+      sessions: 3,
+      startTime,
+      hostStartTime,
+      lastFailoverAt,
+    }));
+
+    // Simulate an HTTP response object
+    let statusCode = 0;
+    let body = '';
+    const res = {
+      writeHead(code: number, _hdrs: Record<string, string | number>) {
+        statusCode = code;
+      },
+      end(data: string) {
+        body = data;
+      },
+    } as any;
+
+    handler({} as any, res);
+
+    expect(statusCode).toBe(200);
+    const parsed = JSON.parse(body);
+    expect(parsed.status).toBe('ok');
+    expect(typeof parsed.hostUptime).toBe('number');
+    expect(parsed.hostUptime).toBeLessThanOrEqual(parsed.uptime);
+    expect(parsed.lastFailoverAt).toBe(lastFailoverAt);
+  });
+
+  it('defaults hostUptime to uptime when hostStartTime is not provided', () => {
+    const startTime = Date.now() - 10_000;
+
+    const handler = createHealthHandler(() => ({
+      port: 38741,
+      sessions: 0,
+      startTime,
+    }));
+
+    let body = '';
+    const res = {
+      writeHead() {},
+      end(data: string) {
+        body = data;
+      },
+    } as any;
+
+    handler({} as any, res);
+
+    const parsed = JSON.parse(body);
+    // hostUptime should equal uptime when no separate hostStartTime
+    expect(parsed.hostUptime).toBe(parsed.uptime);
+    expect(parsed.lastFailoverAt).toBeNull();
+  });
+});