@rushstack/playwright-browser-tunnel 0.2.4 → 0.3.1

package/src/PlaywrightBrowserTunnel.ts

@@ -1,650 +0,0 @@
-// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
-// See LICENSE in the project root for license information.
-
-import type { ChildProcess } from 'node:child_process';
-import { once } from 'node:events';
-
-import type { BrowserServer, BrowserType, LaunchOptions } from 'playwright-core';
-import { type RawData, WebSocket, type WebSocketServer } from 'ws';
-import semver from 'semver';
-
-import { TerminalProviderSeverity, TerminalStreamWritable, type ITerminal } from '@rushstack/terminal';
-import { Executable, FileSystem, Async } from '@rushstack/node-core-library';
-
-import {
-  getNormalizedErrorString,
-  getWebSocketCloseReason,
-  getWebSocketReadyStateString,
-  WebSocketCloseCode
-} from './utilities';
-import { LaunchOptionsValidator, type ILaunchOptionsValidationResult } from './LaunchOptionsValidator';
-
-/**
- * Allowed Playwright browser names.
- * @beta
- */
-export type BrowserName = 'chromium' | 'firefox' | 'webkit';
-const validBrowserNames: Set<string> = new Set(['chromium', 'firefox', 'webkit'] satisfies BrowserName[]);
-function isValidBrowserName(browserName: string): browserName is BrowserName {
-  return validBrowserNames.has(browserName);
-}
-
-/**
- * Status values reported by {@link PlaywrightTunnel}.
- * @beta
- */
-export type TunnelStatus =
-  | 'waiting-for-connection'
-  | 'browser-server-running'
-  | 'stopped'
-  | 'setting-up-browser-server'
-  | 'error';
-
-/**
- * Handshake data exchanged during the initial WebSocket connection.
- * @beta
- */
-export interface IHandshake {
-  action: 'handshake';
-  browserName: BrowserName;
-  launchOptions: LaunchOptions;
-  playwrightVersion: semver.SemVer;
-}
-
-type TunnelMode = 'poll-connection' | 'wait-for-incoming-connection';
-
-/**
- * Options for configuring a {@link PlaywrightTunnel} instance.
- * @beta
- */
-export type IPlaywrightTunnelOptions = {
-  terminal: ITerminal;
-  onStatusChange: (status: TunnelStatus) => void;
-  playwrightInstallPath: string;
-  /**
-   * Optional callback invoked before launching the browser server.
-   * Receives the handshake data including launch options.
-   * If the callback returns false, the browser server launch will be aborted.
-   * This allows the client to prompt the user for approval before starting.
-   */
-  onBeforeLaunch?: (handshake: IHandshake) => Promise<boolean> | boolean;
-} & (
-  | {
-      mode: 'poll-connection';
-      wsEndpoint: string;
-    }
-  | {
-      mode: 'wait-for-incoming-connection';
-      listenPort: number;
-    }
-);
-
-interface IBrowserServerProxy {
-  browserServer: BrowserServer;
-  client: WebSocket;
-}
-
-/**
- * Hosts a Playwright browser server and forwards traffic over a WebSocket tunnel.
- * @beta
- */
-export class PlaywrightTunnel {
-  private readonly _terminal: ITerminal;
-  private readonly _onStatusChange: (status: TunnelStatus) => void;
-  private readonly _onBeforeLaunch?: (handshake: IHandshake) => Promise<boolean> | boolean;
-  private readonly _playwrightBrowsersInstalled: Set<string> = new Set();
-  private readonly _wsEndpoint: string | undefined;
-  private readonly _listenPort: number | undefined;
-  private readonly _playwrightInstallPath: string;
-  private _status: TunnelStatus = 'stopped';
-  private _initWsPromise?: Promise<WebSocket>;
-  private _keepRunning: boolean = false;
-  private _ws?: WebSocket;
-  private _mode: TunnelMode;
-  private _pendingConnectionAttempt?: Promise<WebSocket>;
-  private _pollInterval?: NodeJS.Timeout;
-
-  public constructor(options: IPlaywrightTunnelOptions) {
-    const { mode, terminal, onStatusChange, playwrightInstallPath, onBeforeLaunch } = options;
-
-    switch (mode) {
-      case 'poll-connection':
-        if (!options.wsEndpoint) {
-          throw new Error('wsEndpoint is required for poll-connection mode');
-        }
-        this._wsEndpoint = options.wsEndpoint;
-        this._listenPort = undefined;
-        break;
-      case 'wait-for-incoming-connection':
-        if (options.listenPort === undefined) {
-          throw new Error('listenPort is required for wait-for-incoming-connection mode');
-        }
-        this._wsEndpoint = undefined;
-        this._listenPort = options.listenPort;
-        break;
-      default:
-        throw new Error(`Invalid mode: ${mode}`);
-    }
-
-    this._mode = mode;
-    this._terminal = terminal;
-    this._onStatusChange = onStatusChange;
-    this._onBeforeLaunch = onBeforeLaunch;
-    this._playwrightInstallPath = playwrightInstallPath;
-  }
-
-  public get status(): TunnelStatus {
-    return this._status;
-  }
-
-  // eslint-disable-next-line @typescript-eslint/naming-convention
-  private set status(newStatus: TunnelStatus) {
-    this._status = newStatus;
-    this._onStatusChange(newStatus);
-  }
-
-  public async waitForCloseAsync(): Promise<void> {
-    const terminal: ITerminal = this._terminal;
-    const initWsPromise: Promise<WebSocket> | undefined = this._initWsPromise;
-    if (initWsPromise) {
-      const ws: WebSocket = await initWsPromise;
-      await once(ws, 'close');
-      terminal.writeDebugLine('WebSocket connection closed. resolving init promise.');
-      this._initWsPromise = undefined;
-    }
-  }
-
-  public async startAsync(options: { keepRunning?: boolean } = {}): Promise<void> {
-    this._keepRunning = options.keepRunning ?? true;
-    const terminal: ITerminal = this._terminal;
-    terminal.writeLine(`keepRunning: ${this._keepRunning}`);
-    while (this._keepRunning) {
-      if (!this._initWsPromise) {
-        this._initWsPromise = this._initPlaywrightBrowserTunnelAsync();
-      } else {
-        terminal.writeLine(`Tunnel is already running with status: ${this.status}`);
-      }
-      await this.waitForCloseAsync();
-    }
-  }
-
-  public async stopAsync(): Promise<void> {
-    this._keepRunning = false;
-    if (this._pollInterval) {
-      clearInterval(this._pollInterval);
-      this._pollInterval = undefined;
-    }
-    await this._initWsPromise?.finally(() => {
-      this._ws?.close(WebSocketCloseCode.NORMAL_CLOSURE, 'Tunnel stopped');
-    });
-  }
-
-  public async [Symbol.asyncDispose](): Promise<void> {
-    this._terminal.writeLine('Disposing WebSocket connection.');
-    await this.stopAsync();
-  }
-
-  public async cleanTempFilesAsync(): Promise<void> {
-    const tmpPath: string = this._playwrightInstallPath;
-    this._terminal.writeLine(`Cleaning up temporary files in ${tmpPath}`);
-    try {
-      await FileSystem.ensureEmptyFolderAsync(tmpPath);
-      this._terminal.writeLine(`Temporary files cleaned up.`);
-    } catch (error) {
-      this._terminal.writeLine(`Failed to clean up temporary files: ${getNormalizedErrorString(error)}`);
-    }
-  }
-
-  // TODO: We should implement an uninstall command to remove installed Playwright browsers
-  // public async uninstallPlaywrightBrowsersAsync(): Promise<void> {}
-
-  private async _runCommandAsync(command: string, args: string[]): Promise<void> {
-    const tmpPath: string = this._playwrightInstallPath;
-    await FileSystem.ensureFolderAsync(tmpPath);
-    this._terminal.writeLine(`Running command: ${command} ${args.join(' ')} in ${tmpPath}`);
-
-    const cp: ChildProcess = Executable.spawn(command, args, {
-      stdio: [
-        'ignore', // stdin
-        'pipe', // stdout
-        'pipe' // stderr
-      ],
-      currentWorkingDirectory: tmpPath
-    });
-
-    cp.stdout?.pipe(
-      new TerminalStreamWritable({
-        terminal: this._terminal,
-        severity: TerminalProviderSeverity.log
-      })
-    );
-    cp.stderr?.pipe(
-      new TerminalStreamWritable({
-        terminal: this._terminal,
-        severity: TerminalProviderSeverity.error
-      })
-    );
-
-    await Executable.waitForExitAsync(cp, { throwOnNonZeroExitCode: true, throwOnSignal: true });
-  }
-
-  private async _installPlaywrightCoreAsync({
-    playwrightVersion
-  }: Pick<IHandshake, 'playwrightVersion'>): Promise<void> {
-    this._terminal.writeLine(`Installing playwright-core version ${playwrightVersion}`);
-    await this._runCommandAsync('npm', [
-      'install',
-      `playwright-core-${playwrightVersion}@npm:playwright-core@${playwrightVersion}`
-    ]);
-  }
-
-  private async _installPlaywrightBrowsersAsync({
-    playwrightVersion,
-    browserName
-  }: Pick<IHandshake, 'playwrightVersion' | 'browserName'>): Promise<void> {
-    await this._installPlaywrightCoreAsync({ playwrightVersion });
-    this._terminal.writeLine(`Executing playwright-core version ${playwrightVersion}`);
-    await this._runCommandAsync('node', [
-      `node_modules/playwright-core-${playwrightVersion}/cli.js`,
-      'install',
-      browserName
-    ]);
-  }
-
-  private async _tryConnectAsync(): Promise<WebSocket> {
-    const wsEndpoint: string | undefined = this._wsEndpoint;
-    if (!wsEndpoint) {
-      throw new Error('WebSocket endpoint is not defined');
-    }
-    return await new Promise<WebSocket>((resolve, reject) => {
-      const ws: WebSocket = new WebSocket(wsEndpoint);
-      ws.on('open', () => {
-        this._terminal.writeLine(`WebSocket connection opened`);
-        resolve(ws);
-      });
-      ws.once('error', (error) => {
-        reject(error);
-      });
-    });
-  }
-
-  // TODO: Only supporting one test at a time.
-  // Need to support multiple simultaneous connections for parallel tests.
-  private async _pollConnectionAsync(): Promise<WebSocket> {
-    this._terminal.writeLine(`Waiting for WebSocket connection`);
-    return await new Promise((resolve, reject) => {
-      this._pollInterval = setInterval(() => {
-        if (this._pendingConnectionAttempt) {
-          return; // Skip if a connection attempt is already in progress
-        }
-        const connectionPromise: Promise<WebSocket> = this._tryConnectAsync();
-        this._pendingConnectionAttempt = connectionPromise;
-        connectionPromise
-          .then((ws: WebSocket) => {
-            clearInterval(this._pollInterval);
-            this._pollInterval = undefined;
-            ws.removeAllListeners();
-            this._pendingConnectionAttempt = undefined;
-            resolve(ws);
-          })
-          .catch(() => {
-            // no-op - will retry on next interval
-            this._pendingConnectionAttempt = undefined;
-          });
-      }, 500);
-    });
-  }
-
-  private async _waitForIncomingConnectionAsync(): Promise<WebSocket> {
-    this._terminal.writeLine('Waiting for incoming WebSocket connection');
-
-    return await new Promise<WebSocket>((resolve, reject) => {
-      const server: WebSocketServer = new WebSocket.Server({ port: this._listenPort });
-
-      const cleanup = (): void => {
-        server.removeAllListeners();
-      };
-
-      server.once('connection', (ws) => {
-        this._terminal.writeLine('Incoming WebSocket connection established');
-
-        // Stop listening immediately so the port is released
-        cleanup();
-        server.close((closeError?: Error) => {
-          if (closeError) {
-            this._terminal.writeLine(
-              `Failed to close WebSocket server: ${
-                closeError instanceof Error ? closeError.message : closeError
-              }`
-            );
-          }
-          resolve(ws);
-        });
-      });
-
-      server.once('error', (error) => {
-        this._terminal.writeLine(`WebSocket server error: ${getNormalizedErrorString(error)}`);
-
-        cleanup();
-        // Try to close (best-effort), then reject
-        server.close(() => reject(error));
-      });
-    });
-  }
-
-  // TODO: If a user runs this for the first time, `this._playwrightBrowsersInstalled` will be empty
-  // and it will try to install the browsers every time. We should persist this information. Maybe a cache file with text per
-  // machine instance?
-  private async _setupPlaywrightAsync({
-    playwrightVersion,
-    browserName
-  }: Pick<IHandshake, 'playwrightVersion' | 'browserName'>): Promise<typeof import('playwright-core')> {
-    const browserKey: string = `${playwrightVersion}-${browserName}`;
-    this._terminal.writeLine(`Checking for installed playwright browsers. Installed browsers: ${browserKey}`);
-    if (!this._playwrightBrowsersInstalled.has(browserKey)) {
-      this._terminal.writeLine(
-        `Playwright browser not found. Installing playwright-core version ${playwrightVersion}`
-      );
-      await this._installPlaywrightBrowsersAsync({ playwrightVersion, browserName });
-      this._playwrightBrowsersInstalled.add(browserKey);
-    }
-
-    this._terminal.writeLine(`Using playwright-core version ${playwrightVersion} for browser server`);
-    return await import(`${this._playwrightInstallPath}/node_modules/playwright-core-${playwrightVersion}`);
-  }
-
-  private async _getPlaywrightBrowserServerProxyAsync({
-    browserName,
-    playwrightVersion,
-    launchOptions
-  }: Pick<IHandshake, 'playwrightVersion' | 'browserName' | 'launchOptions'>): Promise<IBrowserServerProxy> {
-    const terminal: ITerminal = this._terminal;
-
-    // Validate launch options against security allowlist
-    terminal.writeLine('Validating launch options against security allowlist...');
-    const validationResult: ILaunchOptionsValidationResult =
-      await LaunchOptionsValidator.validateLaunchOptionsAsync(launchOptions, terminal);
-
-    if (!validationResult.isValid) {
-      terminal.writeWarningLine(
-        `Some launch options were denied: ${validationResult.deniedOptions.join(', ')}`
-      );
-      terminal.writeWarningLine(`Using filtered launch options. Denied options have been removed.`);
-    }
-
-    // Use filtered options and ensure headless: false for headed tests in codespaces
-    // This is critical for the extension's purpose - enabling headed Playwright tests remotely
-    const safeOptions: LaunchOptions = {
-      ...validationResult.filteredOptions,
-      headless: false
-    };
-
-    // Log the validated options, excluding 'headless' since it's always false for this extension
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    const { headless, ...logOptions } = safeOptions;
-    terminal.writeLine(
-      `Launch options after validation: ${JSON.stringify(logOptions)} (headless: false enforced)`
-    );
-
-    const playwright: typeof import('playwright-core') = await this._setupPlaywrightAsync({
-      playwrightVersion,
-      browserName
-    });
-
-    const { chromium, firefox, webkit } = playwright;
-    const browsers: Record<BrowserName, BrowserType> = { chromium, firefox, webkit };
-
-    const browserServer: BrowserServer = await browsers[browserName].launchServer(safeOptions);
-
-    if (!browserServer) {
-      throw new Error(
-        `Failed to launch browser server for ${browserName} with options: ${JSON.stringify(safeOptions)}`
-      );
-    }
-
-    terminal.writeLine(`Launched ${browserName} browser server`);
-    const client: WebSocket = new WebSocket(browserServer.wsEndpoint());
-
-    return {
-      browserServer,
-      client
-    };
-  }
-
-  private _validateHandshake(rawHandshake: unknown): IHandshake {
-    if (
-      typeof rawHandshake !== 'object' ||
-      rawHandshake === null ||
-      'action' in rawHandshake === false ||
-      'browserName' in rawHandshake === false ||
-      'playwrightVersion' in rawHandshake === false ||
-      'launchOptions' in rawHandshake === false ||
-      typeof rawHandshake.action !== 'string' ||
-      typeof rawHandshake.browserName !== 'string' ||
-      typeof rawHandshake.playwrightVersion !== 'string' ||
-      typeof rawHandshake.launchOptions !== 'object'
-    ) {
-      throw new Error(`Invalid handshake: ${JSON.stringify(rawHandshake)}. Must be an object.`);
-    }
-
-    const { action, browserName, playwrightVersion, launchOptions } = rawHandshake;
-
-    if (action !== 'handshake') {
-      throw new Error(`Invalid action: ${action}. Expected 'handshake'.`);
-    }
-    const playwrightVersionSemver: semver.SemVer | null = semver.coerce(playwrightVersion);
-    if (!playwrightVersionSemver) {
-      throw new Error(`Invalid Playwright version: ${playwrightVersion}. Must be a valid semver version.`);
-    }
-    if (!isValidBrowserName(browserName)) {
-      throw new Error(
-        `Invalid browser name: ${browserName}. Must be one of ${Array.from(validBrowserNames).join(', ')}.`
-      );
-    }
-
-    return {
-      action,
-      launchOptions: launchOptions as LaunchOptions,
-      playwrightVersion: playwrightVersionSemver,
-      browserName
-    };
-  }
-
-  // ws1 is the tunnel websocket, ws2 is the browser server websocket
-  private async _setupForwardingAsync(ws1: WebSocket, ws2: WebSocket): Promise<void> {
-    this._terminal.writeLine('Setting up message forwarding between ws1 and ws2');
-    this._terminal.writeLine(`  ws1 (tunnel) readyState: ${getWebSocketReadyStateString(ws1.readyState)}`);
-    this._terminal.writeLine(`  ws2 (browser) readyState: ${getWebSocketReadyStateString(ws2.readyState)}`);
-
-    const messageCount: { ws1ToWs2: number; ws2ToWs1: number } = { ws1ToWs2: 0, ws2ToWs1: 0 };
-
-    ws1.on('message', (data) => {
-      messageCount.ws1ToWs2++;
-      if (ws2.readyState === WebSocket.OPEN) {
-        ws2.send(data);
-      } else {
-        this._terminal.writeLine(
-          `ws2 not open (state: ${getWebSocketReadyStateString(ws2.readyState)}). Dropping message #${messageCount.ws1ToWs2}`
-        );
-      }
-    });
-    ws2.on('message', (data) => {
-      messageCount.ws2ToWs1++;
-      if (ws1.readyState === WebSocket.OPEN) {
-        ws1.send(data);
-      } else {
-        this._terminal.writeLine(
-          `ws1 not open (state: ${getWebSocketReadyStateString(ws1.readyState)}). Dropping message #${messageCount.ws2ToWs1}`
-        );
-      }
-    });
-
-    ws1.once('close', (code: number, reason: Buffer) => {
-      const reasonStr: string = reason.toString() || 'no reason provided';
-      const codeDescription: string = getWebSocketCloseReason(code);
-      this._terminal.writeLine(
-        `ws1 (tunnel) closed - code: ${code} (${codeDescription}), reason: ${reasonStr}`
-      );
-      this._terminal.writeLine(
-        `  Messages forwarded: ws1->ws2: ${messageCount.ws1ToWs2}, ws2->ws1: ${messageCount.ws2ToWs1}`
-      );
-      if (ws2.readyState === WebSocket.OPEN) {
-        this._terminal.writeLine('  Closing ws2 (browser) in response');
-        ws2.close(WebSocketCloseCode.NORMAL_CLOSURE, 'Tunnel closed');
-      }
-    });
-    ws2.once('close', (code: number, reason: Buffer) => {
-      const reasonStr: string = reason.toString() || 'no reason provided';
-      const codeDescription: string = getWebSocketCloseReason(code);
-      this._terminal.writeLine(
-        `ws2 (browser) closed - code: ${code} (${codeDescription}), reason: ${reasonStr}`
-      );
-      this._terminal.writeLine(
-        `  Messages forwarded: ws1->ws2: ${messageCount.ws1ToWs2}, ws2->ws1: ${messageCount.ws2ToWs1}`
-      );
-      if (ws1.readyState === WebSocket.OPEN) {
-        this._terminal.writeLine('  Closing ws1 (tunnel) in response');
-        ws1.close(WebSocketCloseCode.NORMAL_CLOSURE, 'Browser closed');
-      }
-    });
-
-    ws1.once('error', (error) => {
-      this._terminal.writeErrorLine(`ws1 (tunnel) WebSocket error: ${getNormalizedErrorString(error)}`);
-      this._terminal.writeErrorLine(`  ws1 readyState: ${getWebSocketReadyStateString(ws1.readyState)}`);
-    });
-    ws2.once('error', (error) => {
-      this._terminal.writeErrorLine(`ws2 (browser) WebSocket error: ${getNormalizedErrorString(error)}`);
-      this._terminal.writeErrorLine(`  ws2 readyState: ${getWebSocketReadyStateString(ws2.readyState)}`);
-    });
-  }
-
-  /**
-   * Initializes the Playwright browser tunnel by establishing a WebSocket connection
-   * and setting up the browser server.
-   * Returns when the handshake is complete and the browser server is running.
-   */
-  private async _initPlaywrightBrowserTunnelAsync(): Promise<WebSocket> {
-    let handshake: IHandshake | undefined = undefined;
-    let client: WebSocket | undefined = undefined;
-    let browserServer: BrowserServer | undefined = undefined;
-
-    this.status = 'waiting-for-connection';
-    const ws: WebSocket =
-      this._mode === 'poll-connection'
-        ? await this._pollConnectionAsync()
-        : await this._waitForIncomingConnectionAsync();
-
-    ws.on('open', () => {
-      this._terminal.writeLine(`WebSocket connection established`);
-      handshake = undefined;
-    });
-
-    ws.on('error', (error) => {
-      this._terminal.writeLine(`WebSocket error occurred: ${getNormalizedErrorString(error)}`);
-    });
-
-    ws.on('close', async (code: number, reason: Buffer) => {
-      const reasonStr: string = reason.toString() || 'no reason provided';
-      const codeDescription: string = getWebSocketCloseReason(code);
-      this._initWsPromise = undefined;
-      this.status = 'stopped';
-      this._terminal.writeLine(
-        `WebSocket connection closed - code: ${code} (${codeDescription}), reason: ${reasonStr}`
-      );
-      this._terminal.writeLine(`  handshake received: ${handshake !== undefined}`);
-      this._terminal.writeLine(`  browserServer active: ${browserServer !== undefined}`);
-      if (browserServer) {
-        this._terminal.writeLine('  Closing browser server...');
-        await browserServer.close();
-        this._terminal.writeLine('  Browser server closed');
-      }
-    });
-
-    return await new Promise<WebSocket>((resolve, reject) => {
-      const onMessageHandler = async (data: RawData): Promise<void> => {
-        const terminal: ITerminal = this._terminal;
-        if (!handshake) {
-          try {
-            const rawHandshakeString: string = data.toString();
-            const rawHandshake: unknown = JSON.parse(rawHandshakeString);
-            terminal.writeLine(`Received handshake: ${rawHandshakeString}`);
-            handshake = this._validateHandshake(rawHandshake);
-
-            // Call the onBeforeLaunch callback if provided
-            if (this._onBeforeLaunch) {
-              terminal.writeLine('Requesting user approval before launching browser server...');
-              const shouldProceed: boolean = await this._onBeforeLaunch(handshake);
-              if (!shouldProceed) {
-                terminal.writeLine('Browser server launch cancelled by user.');
-                ws.off('message', onMessageHandler);
-                ws.close(WebSocketCloseCode.NORMAL_CLOSURE, 'Launch cancelled by user');
-                reject(new Error('Browser server launch cancelled by user'));
-                return;
-              }
-              terminal.writeLine('User approved browser server launch.');
-            }
-
-            this.status = 'setting-up-browser-server';
-            const browserServerProxy: IBrowserServerProxy =
-              await this._getPlaywrightBrowserServerProxyAsync(handshake);
-            client = browserServerProxy.client;
-            browserServer = browserServerProxy.browserServer;
-
-            // Monitor browser server process for crashes
-            const browserProcess: ChildProcess | null = browserServer.process();
-            if (browserProcess) {
-              browserProcess.on('exit', (code: number | null, signal: string | null) => {
-                terminal.writeErrorLine(`Browser server process exited - code: ${code}, signal: ${signal}`);
-              });
-              browserProcess.on('error', (err: Error) => {
-                terminal.writeErrorLine(`Browser server process error: ${getNormalizedErrorString(err)}`);
-              });
-              terminal.writeDebugLine(`Browser server process started with PID: ${browserProcess.pid}`);
-            } else {
-              terminal.writeDebugLine('Warning: Browser server process handle not available for monitoring');
-            }
-
-            this.status = 'browser-server-running';
-
-            // Send ack so that the counterpart also knows to start forwarding messages.
-            // NOTE: The 1-second delay is an intentional workaround. In the current
-            // protocol, the remote tunnel endpoint does not expose an explicit "ready"
-            // signal for when it has finished initializing its own forwarding logic
-            // after receiving the initial handshake. This
-            // delay avoids races where early messages could be dropped or mishandled
-            // if they arrive before the remote side is fully ready.
-            //
-            // TODO: A future improvement would be to replace this delay with a deterministic
-            // synchronization mechanism (e.g. an explicit "ready" message or event)
-            // instead of relying on a fixed timeout.
-            await Async.sleepAsync(2000);
-
-            ws.send(JSON.stringify({ action: 'handshakeAck' }));
-            await this._setupForwardingAsync(ws, client);
-
-            // Clean up message handler after successful handshake
-            ws.off('message', onMessageHandler);
-            resolve(ws);
-          } catch (error) {
-            terminal.writeLine(`Error processing handshake: ${error}`);
-            this.status = 'error';
-
-            // Cleanup and close connection on error
-            ws.off('message', onMessageHandler);
-            ws.close(WebSocketCloseCode.INTERNAL_ERROR, 'Handshake error');
-            reject(error);
-            return;
-          }
-        } else {
-          if (!client) {
-            terminal.writeLine('Browser WebSocket client is not initialized.');
-            ws.off('message', onMessageHandler);
-            ws.close(WebSocketCloseCode.INTERNAL_ERROR, 'Browser client not initialized');
-            return;
-          }
-        }
-      };
-      ws.on('message', onMessageHandler);
-    });
-  }
-}

package/src/tunneledBrowserConnection/ITunneledBrowser.ts

@@ -1,20 +0,0 @@
-// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
-// See LICENSE in the project root for license information.
-
-import type { Browser } from 'playwright-core';
-
-/**
- * Disposable handle returned by {@link createTunneledBrowserAsync}.
- * @beta
- */
-export interface IDisposableTunneledBrowser {
-  /**
-   * The connected Playwright Browser instance.
-   */
-  browser: Browser;
-  /**
-   * Async dispose method that closes the browser connection.
-   * Called automatically when using `await using` syntax.
-   */
-  [Symbol.asyncDispose]: () => Promise<void>;
-}