@quenty/studio-bridge 0.7.1 → 0.9.0

package/dist/src/bridge/internal/environment-detection.test.js

@@ -0,0 +1,150 @@
+/**
+ * Unit tests for environment-detection -- validates role detection logic
+ * including host election on free port, client detection when host exists,
+ * remoteHost override, and devcontainer detection.
+ */
+import { existsSync } from 'node:fs';
+import { describe, it, expect, afterEach, beforeEach } from 'vitest';
+import { detectRoleAsync, isDevcontainer, getDefaultRemoteHost, } from './environment-detection.js';
+import { BridgeHost } from './bridge-host.js';
+describe('detectRoleAsync', () => {
+    let bridgeHost;
+    afterEach(async () => {
+        if (bridgeHost) {
+            await bridgeHost.stopAsync();
+            bridgeHost = undefined;
+        }
+    });
+    it('returns host role on a free ephemeral port', async () => {
+        const result = await detectRoleAsync({ port: 0 });
+        expect(result.role).toBe('host');
+        expect(result.port).toBeGreaterThan(0);
+    });
+    it('returns client role when remoteHost is specified', async () => {
+        const result = await detectRoleAsync({
+            port: 38741,
+            remoteHost: 'some-remote-host:38741',
+        });
+        expect(result.role).toBe('client');
+        expect(result.port).toBe(38741);
+    });
+    it('returns client role when a bridge host is already running', async () => {
+        // Start a real bridge host on an ephemeral port
+        bridgeHost = new BridgeHost();
+        const port = await bridgeHost.startAsync({ port: 0 });
+        const result = await detectRoleAsync({ port });
+        expect(result.role).toBe('client');
+        expect(result.port).toBe(port);
+    });
+    it('preserves the port from options in the result', async () => {
+        const result = await detectRoleAsync({
+            port: 12345,
+            remoteHost: 'localhost:12345',
+        });
+        expect(result.port).toBe(12345);
+    });
+    it('returns host role with the bound port when port is 0', async () => {
+        const result = await detectRoleAsync({ port: 0 });
+        // Ephemeral port should be assigned by the OS
+        expect(result.role).toBe('host');
+        expect(result.port).not.toBe(0);
+        expect(result.port).toBeGreaterThan(0);
+    });
+});
+const DEVCONTAINER_ENV_KEYS = [
+    'REMOTE_CONTAINERS',
+    'CODESPACES',
+    'CONTAINER',
+];
+const dockerenvExists = existsSync('/.dockerenv');
+describe('isDevcontainer', () => {
+    const savedEnv = {};
+    beforeEach(() => {
+        // Save current values so we can restore after each test
+        for (const key of DEVCONTAINER_ENV_KEYS) {
+            savedEnv[key] = process.env[key];
+        }
+    });
+    afterEach(() => {
+        // Restore original env values
+        for (const key of DEVCONTAINER_ENV_KEYS) {
+            if (savedEnv[key] === undefined) {
+                delete process.env[key];
+            }
+            else {
+                process.env[key] = savedEnv[key];
+            }
+        }
+    });
+    function clearDevcontainerEnv() {
+        for (const key of DEVCONTAINER_ENV_KEYS) {
+            delete process.env[key];
+        }
+    }
+    it('returns true when REMOTE_CONTAINERS is set', () => {
+        clearDevcontainerEnv();
+        process.env.REMOTE_CONTAINERS = 'true';
+        expect(isDevcontainer()).toBe(true);
+    });
+    it('returns true when CODESPACES is set', () => {
+        clearDevcontainerEnv();
+        process.env.CODESPACES = 'true';
+        expect(isDevcontainer()).toBe(true);
+    });
+    it('returns true when CONTAINER is set', () => {
+        clearDevcontainerEnv();
+        process.env.CONTAINER = 'true';
+        expect(isDevcontainer()).toBe(true);
+    });
+    it('returns false when no env vars set and no /.dockerenv', () => {
+        clearDevcontainerEnv();
+        // If /.dockerenv exists on this machine, the function should still return true
+        expect(isDevcontainer()).toBe(dockerenvExists);
+    });
+    it('treats empty string as falsy', () => {
+        clearDevcontainerEnv();
+        process.env.REMOTE_CONTAINERS = '';
+        // Empty string is falsy -- result depends only on /.dockerenv
+        expect(isDevcontainer()).toBe(dockerenvExists);
+    });
+});
+describe('getDefaultRemoteHost', () => {
+    const savedEnv = {};
+    beforeEach(() => {
+        for (const key of DEVCONTAINER_ENV_KEYS) {
+            savedEnv[key] = process.env[key];
+        }
+    });
+    afterEach(() => {
+        for (const key of DEVCONTAINER_ENV_KEYS) {
+            if (savedEnv[key] === undefined) {
+                delete process.env[key];
+            }
+            else {
+                process.env[key] = savedEnv[key];
+            }
+        }
+    });
+    function clearDevcontainerEnv() {
+        for (const key of DEVCONTAINER_ENV_KEYS) {
+            delete process.env[key];
+        }
+    }
+    it('returns localhost:38741 in devcontainer', () => {
+        clearDevcontainerEnv();
+        process.env.REMOTE_CONTAINERS = 'true';
+        expect(getDefaultRemoteHost()).toBe('localhost:38741');
+    });
+    it('returns null outside devcontainer', () => {
+        clearDevcontainerEnv();
+        // Only null if /.dockerenv doesn't exist
+        if (!dockerenvExists) {
+            expect(getDefaultRemoteHost()).toBeNull();
+        }
+        else {
+            // If /.dockerenv exists, we're in a container, so it returns the host
+            expect(getDefaultRemoteHost()).toBe('localhost:38741');
+        }
+    });
+});
+//# sourceMappingURL=environment-detection.test.js.map

package/dist/src/bridge/internal/environment-detection.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment-detection.test.js","sourceRoot":"","sources":["../../../../src/bridge/internal/environment-detection.test.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,69 @@
+/**
+ * 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.
+ */
+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>;
+}
+/**
+ * Compute jitter delay before takeover attempt. Graceful shutdowns skip
+ * jitter entirely; crash-detected disconnects apply random [0, 500ms].
+ */
+export declare function computeTakeoverJitterMs(options: {
+    graceful: boolean;
+}): number;
+export type HandOffLogEntry = {
+    message: string;
+    oldState: TakeoverState;
+    newState: TakeoverState;
+    timestamp: string;
+    reason: string;
+    data?: Record<string, unknown>;
+};
+export type HandOffLogger = (entry: HandOffLogEntry) => void;
+export declare class HandOffManager {
+    private _state;
+    private _takeoverPending;
+    private _port;
+    private _deps;
+    private _logger;
+    constructor(options: {
+        port: number;
+        deps?: HandOffDependencies;
+        logger?: HandOffLogger;
+    });
+    /** Current state of the takeover state machine. */
+    get state(): TakeoverState;
+    /**
+     * Called when the client receives a HostTransferNotice from the host.
+     * Marks the pending transfer so the subsequent disconnect skips jitter.
+     */
+    onHostTransferNotice(): void;
+    /**
+     * 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
+     */
+    onHostDisconnectedAsync(): Promise<'promoted' | 'fell-back-to-client'>;
+    private _log;
+}
+//# sourceMappingURL=hand-off.d.ts.map

package/dist/src/bridge/internal/hand-off.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hand-off.d.ts","sourceRoot":"","sources":["../../../../src/bridge/internal/hand-off.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,MAAM,MAAM,aAAa,GACrB,WAAW,GACX,mBAAmB,GACnB,aAAa,GACb,UAAU,GACV,qBAAqB,CAAC;AAE1B,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACjD,uBAAuB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5D,KAAK,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACtC;AAMD;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE;IAC/C,QAAQ,EAAE,OAAO,CAAC;CACnB,GAAG,MAAM,CAKT;AAgED,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,aAAa,CAAC;IACxB,QAAQ,EAAE,aAAa,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC;AAE7D,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAA8B;IAC5C,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,KAAK,CAAsB;IACnC,OAAO,CAAC,OAAO,CAA4B;gBAE/B,OAAO,EAAE;QACnB,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,CAAC,EAAE,mBAAmB,CAAC;QAC3B,MAAM,CAAC,EAAE,aAAa,CAAC;KACxB;IAUD,mDAAmD;IACnD,IAAI,KAAK,IAAI,aAAa,CAEzB;IAED;;;OAGG;IACH,oBAAoB,IAAI,IAAI;IAY5B;;;;;;;;;;;;;OAaG;IACG,uBAAuB,IAAI,OAAO,CAAC,UAAU,GAAG,qBAAqB,CAAC;IA+E5E,OAAO,CAAC,IAAI;CAoBb"}

package/dist/src/bridge/internal/hand-off.js

@@ -0,0 +1,178 @@
+/**
+ * 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 } from 'net';
+import { WebSocket } from 'ws';
+import { HostUnreachableError } from '../types.js';
+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) {
+    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) {
+    return new Promise((resolve) => {
+        const server = createServer();
+        server.once('error', (err) => {
+            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) {
+    const CONNECT_TIMEOUT_MS = 2_000;
+    return new Promise((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) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export class HandOffManager {
+    _state = 'connected';
+    _takeoverPending = false;
+    _port;
+    _deps;
+    _logger;
+    constructor(options) {
+        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() {
+        return this._state;
+    }
+    /**
+     * Called when the client receives a HostTransferNotice from the host.
+     * Marks the pending transfer so the subsequent disconnect skips jitter.
+     */
+    onHostTransferNotice() {
+        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() {
+        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);
+    }
+    _log(message, oldState, newState, reason, data) {
+        if (!this._logger) {
+            return;
+        }
+        this._logger({
+            message,
+            oldState,
+            newState,
+            timestamp: new Date().toISOString(),
+            reason,
+            data,
+        });
+    }
+}
+//# sourceMappingURL=hand-off.js.map

package/dist/src/bridge/internal/hand-off.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hand-off.js","sourceRoot":"","sources":["../../../../src/bridge/internal/hand-off.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,7 @@
+/**
+ * Unit tests for HandOffManager — validates the takeover state machine
+ * transitions, jitter computation, and retry logic using injected
+ * dependencies (no real network).
+ */
+export {};
+//# sourceMappingURL=hand-off.test.d.ts.map

package/dist/src/bridge/internal/hand-off.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hand-off.test.d.ts","sourceRoot":"","sources":["../../../../src/bridge/internal/hand-off.test.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}