@quenty/studio-bridge 0.7.1 → 0.9.0

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

@@ -0,0 +1,275 @@
+/**
+ * Failover detection and host takeover state machine. When the bridge host
+ * process dies, surviving clients detect the disconnect and race to bind
+ * the port, promoting themselves to become the new host.
+ *
+ * Two paths:
+ * - Graceful: Host sends HostTransferNotice before shutting down. Clients
+ *   skip jitter and attempt takeover immediately.
+ * - Crash: No notification. Clients detect WebSocket disconnect, apply
+ *   random jitter [0, 500ms] to avoid thundering herd, then race to bind.
+ */
+
+import { createServer, type Server } from 'net';
+import { WebSocket } from 'ws';
+import { HostUnreachableError } from '../types.js';
+
+export type TakeoverState =
+  | 'connected'
+  | 'detecting-failure'
+  | 'taking-over'
+  | 'promoted'
+  | 'fell-back-to-client';
+
+export interface HandOffDependencies {
+  tryBindAsync: (port: number) => Promise<boolean>;
+  tryConnectAsClientAsync: (port: number) => Promise<boolean>;
+  delay: (ms: number) => Promise<void>;
+}
+
+const MAX_CRASH_JITTER_MS = 500;
+const MAX_RETRIES = 10;
+const RETRY_DELAY_MS = 1_000;
+
+/**
+ * Compute jitter delay before takeover attempt. Graceful shutdowns skip
+ * jitter entirely; crash-detected disconnects apply random [0, 500ms].
+ */
+export function computeTakeoverJitterMs(options: {
+  graceful: boolean;
+}): number {
+  if (options.graceful) {
+    return 0;
+  }
+  return Math.random() * MAX_CRASH_JITTER_MS;
+}
+
+/**
+ * Attempt to bind a TCP server to the given port. Resolves true if the
+ * bind succeeds (port is free), false if EADDRINUSE.
+ */
+function tryBindDefaultAsync(port: number): Promise<boolean> {
+  return new Promise<boolean>((resolve) => {
+    const server: Server = createServer();
+
+    server.once('error', (err: NodeJS.ErrnoException) => {
+      if (err.code === 'EADDRINUSE') {
+        resolve(false);
+      } else {
+        resolve(false);
+      }
+    });
+
+    server.once('listening', () => {
+      server.close(() => {
+        resolve(true);
+      });
+    });
+
+    server.listen(port, 'localhost');
+  });
+}
+
+/**
+ * Attempt a WebSocket connection to ws://localhost:{port}/client with a
+ * 2-second timeout. Resolves true if the connection succeeds (another
+ * host is running), false otherwise.
+ */
+function tryConnectAsClientDefaultAsync(port: number): Promise<boolean> {
+  const CONNECT_TIMEOUT_MS = 2_000;
+
+  return new Promise<boolean>((resolve) => {
+    const ws = new WebSocket(`ws://localhost:${port}/client`);
+
+    const timer = setTimeout(() => {
+      ws.removeAllListeners();
+      ws.terminate();
+      resolve(false);
+    }, CONNECT_TIMEOUT_MS);
+
+    ws.once('open', () => {
+      clearTimeout(timer);
+      ws.removeAllListeners();
+      ws.close();
+      resolve(true);
+    });
+
+    ws.once('error', () => {
+      clearTimeout(timer);
+      ws.removeAllListeners();
+      resolve(false);
+    });
+  });
+}
+
+function delayDefault(ms: number): Promise<void> {
+  return new Promise<void>((resolve) => setTimeout(resolve, ms));
+}
+
+export type HandOffLogEntry = {
+  message: string;
+  oldState: TakeoverState;
+  newState: TakeoverState;
+  timestamp: string;
+  reason: string;
+  data?: Record<string, unknown>;
+};
+
+export type HandOffLogger = (entry: HandOffLogEntry) => void;
+
+export class HandOffManager {
+  private _state: TakeoverState = 'connected';
+  private _takeoverPending = false;
+  private _port: number;
+  private _deps: HandOffDependencies;
+  private _logger: HandOffLogger | undefined;
+
+  constructor(options: {
+    port: number;
+    deps?: HandOffDependencies;
+    logger?: HandOffLogger;
+  }) {
+    this._port = options.port;
+    this._deps = options.deps ?? {
+      tryBindAsync: tryBindDefaultAsync,
+      tryConnectAsClientAsync: tryConnectAsClientDefaultAsync,
+      delay: delayDefault,
+    };
+    this._logger = options.logger;
+  }
+
+  /** Current state of the takeover state machine. */
+  get state(): TakeoverState {
+    return this._state;
+  }
+
+  /**
+   * Called when the client receives a HostTransferNotice from the host.
+   * Marks the pending transfer so the subsequent disconnect skips jitter.
+   */
+  onHostTransferNotice(): void {
+    const oldState = this._state;
+    this._takeoverPending = true;
+    this._state = 'detecting-failure';
+    this._log(
+      'Received host transfer notice',
+      oldState,
+      'detecting-failure',
+      'host-transfer-notice'
+    );
+  }
+
+  /**
+   * Called when the client detects that the host WebSocket has disconnected.
+   * Runs the takeover state machine:
+   *
+   * 1. Apply jitter (0 for graceful, random [0, 500ms] for crash)
+   * 2. Set state to 'taking-over'
+   * 3. Retry loop (max 10 attempts):
+   *    - Try to bind the port
+   *    - If bind succeeds: state='promoted', return 'promoted'
+   *    - If bind fails (EADDRINUSE): try connecting as client
+   *      - If client connects: state='fell-back-to-client', return
+   *      - If client fails: wait 1s and retry
+   * 4. After 10 retries: throw HostUnreachableError
+   */
+  async onHostDisconnectedAsync(): Promise<'promoted' | 'fell-back-to-client'> {
+    const graceful = this._takeoverPending;
+
+    // Step 1: Jitter
+    const jitterMs = computeTakeoverJitterMs({ graceful });
+    if (jitterMs > 0) {
+      this._log(
+        'Applying crash jitter',
+        this._state,
+        this._state,
+        'crash-jitter',
+        { jitterMs }
+      );
+      await this._deps.delay(jitterMs);
+    }
+
+    // Step 2: Transition to taking-over
+    const prevState = this._state;
+    this._state = 'taking-over';
+    this._log(
+      'Beginning takeover attempt',
+      prevState,
+      'taking-over',
+      graceful ? 'graceful-disconnect' : 'crash-detected'
+    );
+
+    // Step 3: Retry loop
+    for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+      const bindSuccess = await this._deps.tryBindAsync(this._port);
+
+      if (bindSuccess) {
+        this._log(
+          'Port bind succeeded — promoted to host',
+          'taking-over',
+          'promoted',
+          'bind-success',
+          { attempt }
+        );
+        this._state = 'promoted';
+        return 'promoted';
+      }
+
+      // Port is in use — check if another host is running
+      const clientConnected = await this._deps.tryConnectAsClientAsync(
+        this._port
+      );
+
+      if (clientConnected) {
+        this._log(
+          'Another host detected — falling back to client',
+          'taking-over',
+          'fell-back-to-client',
+          'new-host-found',
+          { attempt }
+        );
+        this._state = 'fell-back-to-client';
+        return 'fell-back-to-client';
+      }
+
+      // Neither bind nor connect worked — wait and retry
+      if (attempt < MAX_RETRIES - 1) {
+        this._log('Retry attempt', 'taking-over', 'taking-over', 'retry', {
+          attempt,
+          maxRetries: MAX_RETRIES,
+        });
+        await this._deps.delay(RETRY_DELAY_MS);
+      }
+    }
+
+    // Step 4: Exhausted retries
+    this._log(
+      'All retries exhausted',
+      'taking-over',
+      'taking-over',
+      'retries-exhausted'
+    );
+    throw new HostUnreachableError('localhost', this._port);
+  }
+
+  private _log(
+    message: string,
+    oldState: TakeoverState,
+    newState: TakeoverState,
+    reason: string,
+    data?: Record<string, unknown>
+  ): void {
+    if (!this._logger) {
+      return;
+    }
+
+    this._logger({
+      message,
+      oldState,
+      newState,
+      timestamp: new Date().toISOString(),
+      reason,
+      data,
+    });
+  }
+}

package/src/bridge/internal/health-endpoint.test.ts

@@ -0,0 +1,147 @@
+/**
+ * Unit tests for the health endpoint — validates the HTTP health handler
+ * and the checkHealthAsync client function.
+ */
+
+import { describe, it, expect, afterEach } from 'vitest';
+import http from 'http';
+import {
+  checkHealthAsync,
+  createHealthHandler,
+  type HealthInfo,
+} from './health-endpoint.js';
+
+/**
+ * Start a tiny HTTP server that serves the health handler on /health.
+ * Returns the port and a cleanup function.
+ */
+async function startHealthServerAsync(
+  getInfo: () => HealthInfo
+): Promise<{ port: number; closeAsync: () => Promise<void> }> {
+  const handler = createHealthHandler(getInfo);
+  const server = http.createServer((req, res) => {
+    if (req.url === '/health') {
+      handler(req, res);
+    } else {
+      res.writeHead(404);
+      res.end();
+    }
+  });
+
+  return new Promise((resolve) => {
+    server.listen(0, 'localhost', () => {
+      const addr = server.address();
+      const port = typeof addr === 'object' && addr !== null ? addr.port : 0;
+      resolve({
+        port,
+        closeAsync: () => new Promise<void>((r) => server.close(() => r())),
+      });
+    });
+  });
+}
+
+describe('health-endpoint', () => {
+  let closeServer: (() => Promise<void>) | undefined;
+
+  afterEach(async () => {
+    if (closeServer) {
+      await closeServer();
+      closeServer = undefined;
+    }
+  });
+
+  describe('createHealthHandler', () => {
+    it('returns a JSON response with status ok', async () => {
+      const startTime = Date.now() - 5000;
+      const { port, closeAsync } = await startHealthServerAsync(() => ({
+        port: 38741,
+        sessions: 3,
+        startTime,
+      }));
+      closeServer = closeAsync;
+
+      const result = await checkHealthAsync(port);
+
+      expect(result).not.toBeNull();
+      expect(result!.status).toBe('ok');
+      expect(result!.port).toBe(38741);
+      expect(result!.sessions).toBe(3);
+      expect(result!.uptime).toBeGreaterThanOrEqual(4000);
+    });
+
+    it('returns fresh data on each request', async () => {
+      let sessionCount = 0;
+      const { port, closeAsync } = await startHealthServerAsync(() => ({
+        port: 38741,
+        sessions: ++sessionCount,
+        startTime: Date.now(),
+      }));
+      closeServer = closeAsync;
+
+      const r1 = await checkHealthAsync(port);
+      const r2 = await checkHealthAsync(port);
+
+      expect(r1!.sessions).toBe(1);
+      expect(r2!.sessions).toBe(2);
+    });
+  });
+
+  describe('checkHealthAsync', () => {
+    it('returns null when no server is running on the port', async () => {
+      // Use a port that's almost certainly not in use
+      const result = await checkHealthAsync(19999);
+      expect(result).toBeNull();
+    });
+
+    it('returns null when server returns invalid JSON', async () => {
+      const server = http.createServer((_req, res) => {
+        res.writeHead(200, { 'Content-Type': 'text/plain' });
+        res.end('not json');
+      });
+
+      const port = await new Promise<number>((resolve) => {
+        server.listen(0, 'localhost', () => {
+          const addr = server.address();
+          resolve(typeof addr === 'object' && addr !== null ? addr.port : 0);
+        });
+      });
+      closeServer = () => new Promise<void>((r) => server.close(() => r()));
+
+      const result = await checkHealthAsync(port);
+      expect(result).toBeNull();
+    });
+
+    it('returns null when server returns JSON without status field', async () => {
+      const server = http.createServer((_req, res) => {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ notStatus: true }));
+      });
+
+      const port = await new Promise<number>((resolve) => {
+        server.listen(0, 'localhost', () => {
+          const addr = server.address();
+          resolve(typeof addr === 'object' && addr !== null ? addr.port : 0);
+        });
+      });
+      closeServer = () => new Promise<void>((r) => server.close(() => r()));
+
+      const result = await checkHealthAsync(port);
+      expect(result).toBeNull();
+    });
+
+    it('returns valid health response from a running host', async () => {
+      const { port, closeAsync } = await startHealthServerAsync(() => ({
+        port: 38741,
+        sessions: 1,
+        startTime: Date.now() - 1000,
+      }));
+      closeServer = closeAsync;
+
+      const result = await checkHealthAsync(port);
+
+      expect(result).not.toBeNull();
+      expect(result!.status).toBe('ok');
+      expect(typeof result!.uptime).toBe('number');
+    });
+  });
+});

package/src/bridge/internal/health-endpoint.ts

@@ -0,0 +1,100 @@
+/**
+ * HTTP health check endpoint for the bridge host. The handler is registered
+ * on the TransportServer for the '/health' path. A standalone client function
+ * (`checkHealthAsync`) allows probing a running bridge host.
+ */
+
+import http from 'http';
+
+export interface HealthResponse {
+  status: 'ok';
+  port: number;
+  sessions: number;
+  uptime: number;
+  hostUptime: number;
+  lastFailoverAt: string | null;
+}
+
+export interface HealthInfo {
+  port: number;
+  sessions: number;
+  startTime: number;
+  hostStartTime?: number;
+  lastFailoverAt?: string | null;
+}
+
+const HEALTH_TIMEOUT_MS = 2_000;
+
+/**
+ * Check the health endpoint of a running bridge host.
+ * Returns the parsed HealthResponse, or null if the health check fails.
+ */
+export async function checkHealthAsync(
+  port: number,
+  host?: string
+): Promise<HealthResponse | null> {
+  const targetHost = host ?? 'localhost';
+  const url = `http://${targetHost}:${port}/health`;
+
+  return new Promise<HealthResponse | null>((resolve) => {
+    const req = http.get(url, { timeout: HEALTH_TIMEOUT_MS }, (res) => {
+      let body = '';
+      res.on('data', (chunk: Buffer | string) => {
+        body += chunk;
+      });
+      res.on('end', () => {
+        try {
+          const parsed = JSON.parse(body) as HealthResponse;
+          if (parsed.status === 'ok' && typeof parsed.port === 'number') {
+            resolve(parsed);
+          } else {
+            resolve(null);
+          }
+        } catch {
+          resolve(null);
+        }
+      });
+      res.on('error', () => {
+        resolve(null);
+      });
+    });
+
+    req.on('error', () => {
+      resolve(null);
+    });
+
+    req.on('timeout', () => {
+      req.destroy();
+      resolve(null);
+    });
+  });
+}
+
+/**
+ * Create an HTTP request handler that returns the health JSON.
+ * The `getInfo` callback is invoked on each request to gather fresh data.
+ */
+export function createHealthHandler(
+  getInfo: () => HealthInfo
+): (req: http.IncomingMessage, res: http.ServerResponse) => void {
+  return (_req, res) => {
+    const info = getInfo();
+    const now = Date.now();
+    const hostStartTime = info.hostStartTime ?? info.startTime;
+    const response: HealthResponse = {
+      status: 'ok',
+      port: info.port,
+      sessions: info.sessions,
+      uptime: now - info.startTime,
+      hostUptime: now - hostStartTime,
+      lastFailoverAt: info.lastFailoverAt ?? null,
+    };
+
+    const body = JSON.stringify(response);
+    res.writeHead(200, {
+      'Content-Type': 'application/json',
+      'Content-Length': Buffer.byteLength(body),
+    });
+    res.end(body);
+  };
+}