browser-debugger-cli 0.5.1 → 0.6.1

package/dist/connection/__tests__/portReservation.contract.test.js

@@ -0,0 +1,250 @@
+/**
+ * Contract tests for port reservation
+ *
+ * Tests the contract: reserve port atomically OR throw ChromeLaunchError
+ *
+ * Philosophy: Test with real network sockets to validate actual behavior.
+ * Port reservation is an I/O operation that must work correctly in production,
+ * so we use real sockets rather than mocks.
+ *
+ * These are contract tests (not unit tests) because they test the contract
+ * between reservePort() and the Node.js net module.
+ */
+import * as net from 'net';
+import assert from 'node:assert/strict';
+import { describe, test } from 'node:test';
+import { ChromeLaunchError } from '../../connection/errors.js';
+import { reservePort } from '../../connection/portReservation.js';
+describe('Port Reservation - Success Cases', () => {
+    test('successfully reserves an available port', async () => {
+        const port = await findAvailablePort();
+        const reservation = await reservePort(port);
+        try {
+            // Contract: reservation should have release function
+            assert.ok(typeof reservation.release === 'function', 'Should return reservation with release()');
+        }
+        finally {
+            reservation.release();
+        }
+    });
+    test('release() frees the port for reuse', async () => {
+        const port = await findAvailablePort();
+        const reservation1 = await reservePort(port);
+        reservation1.release();
+        // Contract: after release, port should be available again
+        const reservation2 = await reservePort(port);
+        reservation2.release();
+        // If we got here without error, port was successfully reused
+        assert.ok(true, 'Port should be available after release');
+    });
+    test('can reserve multiple different ports simultaneously', async () => {
+        const port1 = await findAvailablePort();
+        const port2 = await findAvailablePort(port1 + 1);
+        const reservation1 = await reservePort(port1);
+        const reservation2 = await reservePort(port2);
+        try {
+            assert.ok(reservation1, 'First reservation should succeed');
+            assert.ok(reservation2, 'Second reservation should succeed');
+        }
+        finally {
+            reservation1.release();
+            reservation2.release();
+        }
+    });
+    test('release() can be called immediately after reservation', async () => {
+        const port = await findAvailablePort();
+        const reservation = await reservePort(port);
+        reservation.release(); // Immediate release
+        // Should not throw
+        assert.ok(true, 'Immediate release should be safe');
+    });
+});
+describe('Port Reservation - Failure Cases', () => {
+    test('throws ChromeLaunchError when port is already in use', async () => {
+        const port = await findAvailablePort();
+        // Occupy the port with a real server
+        const server = await createTestServer(port);
+        try {
+            // Contract: should throw ChromeLaunchError (not generic Error)
+            await assert.rejects(async () => {
+                await reservePort(port);
+            }, (error) => {
+                assert.ok(error instanceof ChromeLaunchError, 'Should throw ChromeLaunchError');
+                assert.ok(error.message.includes(`${port}`), 'Error message should mention port number');
+                assert.ok(error.message.includes('already in use'), 'Error message should indicate port is in use');
+                return true;
+            }, 'Should throw ChromeLaunchError when port is in use');
+        }
+        finally {
+            await closeServer(server);
+        }
+    });
+    test('fails when attempting to reserve same port twice', async () => {
+        const port = await findAvailablePort();
+        const reservation = await reservePort(port);
+        try {
+            // Contract: second reservation should fail with ChromeLaunchError
+            await assert.rejects(async () => {
+                await reservePort(port);
+            }, ChromeLaunchError, 'Should fail when port already reserved');
+        }
+        finally {
+            reservation.release();
+        }
+    });
+    test('error message includes helpful troubleshooting steps', async () => {
+        const port = await findAvailablePort();
+        const server = await createTestServer(port);
+        try {
+            await assert.rejects(async () => {
+                await reservePort(port);
+            }, (error) => {
+                // Contract: error message should help user troubleshoot
+                assert.ok(error.message.includes('bdg cleanup'), 'Should suggest cleanup command');
+                assert.ok(error.message.includes('lsof'), 'Should suggest checking processes');
+                assert.ok(error.message.includes(`--port ${port + 1}`), 'Should suggest alternative port');
+                return true;
+            }, 'Error message should include troubleshooting steps');
+        }
+        finally {
+            await closeServer(server);
+        }
+    });
+});
+describe('Port Reservation - Release Behavior', () => {
+    test('release() closes the server immediately', async () => {
+        const port = await findAvailablePort();
+        const reservation = await reservePort(port);
+        reservation.release();
+        // Port should be immediately available (not waiting for async cleanup)
+        const testServer = net.createServer();
+        const canBind = await new Promise((resolve) => {
+            testServer.once('error', () => resolve(false));
+            testServer.listen(port, '127.0.0.1', () => {
+                testServer.close();
+                resolve(true);
+            });
+        });
+        assert.ok(canBind, 'Port should be immediately available after release');
+    });
+    test('release() can be called multiple times safely', async () => {
+        const port = await findAvailablePort();
+        const reservation = await reservePort(port);
+        // Multiple releases should not throw
+        reservation.release();
+        reservation.release();
+        reservation.release();
+        assert.ok(true, 'Multiple release() calls should be safe');
+    });
+});
+describe('Port Reservation - Edge Cases', () => {
+    test('handles port number at lower boundary (1024)', async () => {
+        // Ports < 1024 require root, so we test 1024 (first non-privileged port)
+        // This may fail in environments where 1024 is in use - that's expected
+        try {
+            const reservation = await reservePort(1024);
+            reservation.release();
+            assert.ok(true, 'Should handle port 1024');
+        }
+        catch (error) {
+            // If port is in use, verify it's the expected error type
+            assert.ok(error instanceof ChromeLaunchError, 'Should throw ChromeLaunchError for in-use port 1024');
+        }
+    });
+    test('handles port number at upper boundary (65535)', async () => {
+        try {
+            const reservation = await reservePort(65535);
+            reservation.release();
+            assert.ok(true, 'Should handle port 65535');
+        }
+        catch (error) {
+            // If port is in use, verify it's the expected error type
+            assert.ok(error instanceof ChromeLaunchError, 'Should throw ChromeLaunchError for in-use port 65535');
+        }
+    });
+    test('binds to localhost (127.0.0.1) only, not all interfaces', async () => {
+        const port = await findAvailablePort();
+        const reservation = await reservePort(port);
+        try {
+            // Contract: should bind to 127.0.0.1, not 0.0.0.0
+            // This means we can still bind to the same port on other interfaces
+            // We verify by checking we can't bind to 127.0.0.1 but this is implicit
+            // in the reservation working at all
+            assert.ok(true, 'Reservation binds to localhost interface');
+        }
+        finally {
+            reservation.release();
+        }
+    });
+});
+describe('Port Reservation - Atomicity', () => {
+    test('reservation is atomic (prevents race conditions)', async () => {
+        const port = await findAvailablePort();
+        // Attempt two simultaneous reservations
+        const results = await Promise.allSettled([reservePort(port), reservePort(port)]);
+        // Contract: exactly one should succeed, one should fail
+        const successes = results.filter((r) => r.status === 'fulfilled');
+        const failures = results.filter((r) => r.status === 'rejected');
+        assert.equal(successes.length, 1, 'Exactly one reservation should succeed');
+        assert.equal(failures.length, 1, 'Exactly one reservation should fail');
+        // Cleanup successful reservation
+        const success = successes[0];
+        if (success?.status === 'fulfilled') {
+            success.value.release();
+        }
+        // Verify failure is ChromeLaunchError
+        const failure = failures[0];
+        if (failure?.status === 'rejected') {
+            assert.ok(failure.reason instanceof ChromeLaunchError, 'Failed reservation should throw ChromeLaunchError');
+        }
+    });
+});
+// Test Helpers
+/**
+ * Find an available port starting from a base port
+ *
+ * @param startPort - Port to start searching from (default: 9000)
+ * @returns Available port number
+ */
+async function findAvailablePort(startPort = 9000) {
+    for (let port = startPort; port < 65535; port++) {
+        const server = net.createServer();
+        const available = await new Promise((resolve) => {
+            server.once('error', () => resolve(false));
+            server.listen(port, '127.0.0.1', () => {
+                server.close();
+                resolve(true);
+            });
+        });
+        if (available) {
+            return port;
+        }
+    }
+    throw new Error('No available ports found');
+}
+/**
+ * Create a test server on a specific port
+ *
+ * @param port - Port to bind to
+ * @returns Server instance
+ */
+async function createTestServer(port) {
+    const server = net.createServer();
+    return new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(port, '127.0.0.1', () => {
+            resolve(server);
+        });
+    });
+}
+/**
+ * Close a server gracefully
+ *
+ * @param server - Server to close
+ */
+async function closeServer(server) {
+    return new Promise((resolve) => {
+        server.close(() => resolve());
+    });
+}
+//# sourceMappingURL=portReservation.contract.test.js.map

package/dist/connection/__tests__/portReservation.contract.test.js.map

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

package/dist/connection/cdp.d.ts

@@ -1,5 +1,6 @@
 import WebSocket from 'ws';
-import type { ConnectionOptions } from '../types';
+import type { CDPEventSource, EventCleanup } from './events.js';
+import type { ConnectionOptions, CreateOptions, Logger } from './types.js';
 /**
  * Chrome DevTools Protocol WebSocket connection manager.
  *
@@ -20,7 +21,7 @@ import type { ConnectionOptions } from '../types';
  * @returns WebSocket instance
  */
 type WebSocketFactory = (url: string, options?: WebSocket.ClientOptions) => WebSocket;
-export declare class CDPConnection {
+export declare class CDPConnection implements CDPEventSource {
     private ws;
     private messageId;
     private pendingMessages;
@@ -37,7 +38,9 @@ export declare class CDPConnection {
     private onDisconnect?;
     private connectionOptions;
     private readonly createWebSocket;
-    constructor(createWebSocket?: WebSocketFactory);
+    private readonly logger;
+    private readonly config;
+    constructor(logger?: Logger, createWebSocket?: WebSocketFactory);
     /**
      * Create and connect a CDPConnection instance in one step.
      *
@@ -45,21 +48,28 @@ export declare class CDPConnection {
      * the connection is established before returning the instance.
      *
      * @param wsUrl - WebSocket debugger URL from CDP target
-     * @param options - Connection configuration options
+     * @param options - Connection and logger configuration options
      * @returns Fully connected CDPConnection instance
      * @throws Error if connection fails after all retries
      *
      * @example
      * ```typescript
-     * // Async factory pattern (recommended)
-     * const cdp = await CDPConnection.create(wsUrl, options);
+     * // Basic usage
+     * const cdp = await CDPConnection.create(wsUrl);
+     *
+     * // With options
+     * const cdp = await CDPConnection.create(wsUrl, {
+     *   timeout: 10000,
+     *   autoReconnect: true,
+     *   logger: customLogger
+     * });
      *
      * // Traditional pattern (still supported)
-     * const cdp = new CDPConnection();
+     * const cdp = new CDPConnection(logger);
      * await cdp.connect(wsUrl, options);
      * ```
      */
-    static create(wsUrl: string, options?: ConnectionOptions): Promise<CDPConnection>;
+    static create(wsUrl: string, options?: CreateOptions): Promise<CDPConnection>;
     /**
      * Connect to Chrome via WebSocket.
      *
@@ -231,12 +241,25 @@ export declare class CDPConnection {
      * and always invoke them with unknown parameters. The generic T is only for
      * caller convenience and type checking at the call site.
      *
+     * Implements CDPEventSource interface, returning a cleanup function
+     * instead of handler ID for easier resource management.
+     *
      * @param event - CDP event name (e.g., 'Network.requestWillBeSent')
      * @param handler - Callback function to handle the event
-     * @returns Handler ID for later removal with off()
+     * @returns Cleanup function to unregister the handler
      * @typeParam T - Type of event parameters for type safety at call site
+     *
+     * @example
+     * ```typescript
+     * const cleanup = cdp.on('Network.requestWillBeSent', (params) => {
+     *   console.log('Request:', params.request.url);
+     * });
+     *
+     * // Later, unregister
+     * cleanup();
+     * ```
      */
-    on<T = unknown>(event: string, handler: (params: T) => void): number;
+    on<T = unknown>(event: string, handler: (params: T) => void): EventCleanup;
     /**
      * Remove a specific event handler.
      *
@@ -262,7 +285,7 @@ export declare class CDPConnection {
      * @param code - WebSocket close code (default: 1000 for normal closure)
      * @param reason - Human-readable close reason
      */
-    close(code?: number, reason?: string): void;
+    close(code?: 1000, reason?: string): void;
     /**
      * Forcefully terminate the WebSocket connection immediately.
      *

package/dist/connection/cdp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cdp.d.ts","sourceRoot":"","sources":["../../src/connection/cdp.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cdp.d.ts","sourceRoot":"","sources":["../../src/connection/cdp.ts"],"names":[],"mappings":"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"}