@rushstack/playwright-browser-tunnel 0.2.3 → 0.3.0

package/lib-esm/HttpServer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HttpServer.js","sourceRoot":"","sources":["../src/HttpServer.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,2DAA2D;AAE3D,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAE/B,OAAO,EAAE,eAAe,EAAkB,MAAM,IAAI,CAAC;AAIrD,MAAM,SAAS,GAAW,WAAW,CAAC;AAEtC;;;;GAIG;AACH,SAAS,aAAa,CAAC,WAAwB;IAC7C,OAAO,WAAW,CAAC,MAAM,KAAK,MAAM;QAClC,CAAC,CAAC,IAAI,WAAW,CAAC,OAAO,KAAK,WAAW,CAAC,IAAI,EAAE;QAChD,CAAC,CAAC,GAAG,WAAW,CAAC,OAAO,IAAI,WAAW,CAAC,IAAI,EAAE,CAAC;AACnD,CAAC;AAED;;;;GAIG;AACH,MAAM,OAAO,UAAU;IAMrB,YAAmB,MAAiB;QAClC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;QACtB,sFAAsF;QACtF,wEAAwE;QACxE,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC;QACnC,IAAI,CAAC,SAAS,GAAG,IAAI,eAAe,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;QAEzD,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE;YACnD,+FAA+F;YAC/F,IAAI,CAAC,SAAS,CAAC,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAa,EAAE,EAAE;gBACpE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,YAAY,EAAE,EAAE,EAAE,OAAO,CAAC,CAAC;YACjD,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC;IAEM,KAAK,CAAC,WAAW;QACtB,OAAO,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;YACnC,uEAAuE;YACvE,uDAAuD;YACvD,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,SAAS,EAAE,GAAG,EAAE;gBACrC,MAAM,WAAW,GAAgC,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;gBACxE,IAAI,CAAC,WAAW,EAAE,CAAC;oBACjB,MAAM,IAAI,KAAK,CAAC,2DAA2D,CAAC,CAAC;gBAC/E,CAAC;gBACD,IAAI,OAAO,WAAW,KAAK,QAAQ,EAAE,CAAC;oBACpC,MAAM,IAAI,KAAK,CAAC,yCAAyC,WAAW,2BAA2B,CAAC,CAAC;gBACnG,CAAC;gBACD,MAAM,gBAAgB,GAAW,aAAa,CAAC,WAAW,CAAC,CAAC;gBAC5D,IAAI,CAAC,iBAAiB,GAAG,gBAAgB,CAAC;gBAC1C,oEAAoE;gBACpE,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,4CAA4C,gBAAgB,EAAE,CAAC,CAAC;gBACvF,OAAO,CAAC,IAAI,GAAG,CAAC,QAAQ,gBAAgB,EAAE,CAAC,CAAC,CAAC;YAC/C,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC;IAED,IAAW,QAAQ;QACjB,IAAI,IAAI,CAAC,iBAAiB,KAAK,SAAS,EAAE,CAAC;YACzC,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;QAClD,CAAC;QACD,OAAO,QAAQ,IAAI,CAAC,iBAAiB,EAAE,CAAC;IAC1C,CAAC;IAED,IAAW,QAAQ;QACjB,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAEM,CAAC,MAAM,CAAC,OAAO,CAAC;QACrB,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;QACvB,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;CACF","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\nimport http from 'node:http';\nimport type { AddressInfo } from 'node:net';\nimport { URL } from 'node:url';\n\nimport { WebSocketServer, type WebSocket } from 'ws';\n\nimport type { ITerminal } from '@rushstack/terminal';\n\nconst LOCALHOST: string = 'localhost';\n\n/**\n * Formats an address info object into a WebSocket-compatible address string.\n * IPv6 addresses are formatted with brackets: [address]:port\n * IPv4 addresses are formatted as: address:port\n */\nfunction formatAddress(addressInfo: AddressInfo): string {\n  return addressInfo.family === 'IPv6'\n    ? `[${addressInfo.address}]:${addressInfo.port}`\n    : `${addressInfo.address}:${addressInfo.port}`;\n}\n\n/**\n * This HttpServer is used for the localProxyWs WebSocketServer.\n * The purpose is to parse the query params and path for the websocket url to get the\n * browserName and launchOptions.\n */\nexport class HttpServer {\n  private readonly _server: http.Server;\n  private readonly _wsServer: WebSocketServer; // local proxy websocket server accepting browser clients\n  private _listeningAddress: string | undefined;\n  private _logger: ITerminal;\n\n  public constructor(logger: ITerminal) {\n    this._logger = logger;\n    // We'll create an HTTP server and attach a WebSocketServer in noServer mode so we can\n    // manually parse the URL and extract query parameters before upgrading.\n    this._server = http.createServer();\n    this._wsServer = new WebSocketServer({ noServer: true });\n\n    this._server.on('upgrade', (request, socket, head) => {\n      // Accept all upgrades on the root path. We parse query string for browserName + launchOptions.\n      this._wsServer.handleUpgrade(request, socket, head, (ws: WebSocket) => {\n        this._wsServer.emit('connection', ws, request);\n      });\n    });\n  }\n\n  public async listenAsync(): Promise<URL> {\n    return await new Promise((resolve) => {\n      // Bind to 'localhost' which resolves to IPv4 (127.0.0.1) or IPv6 (::1)\n      // depending on system configuration and DNS resolution\n      this._server.listen(0, LOCALHOST, () => {\n        const addressInfo: AddressInfo | string | null = this._server.address();\n        if (!addressInfo) {\n          throw new Error('Server address is null - server may not be bound properly');\n        }\n        if (typeof addressInfo === 'string') {\n          throw new Error(`Server address is a pipe/socket path (${addressInfo}), expected an IP address`);\n        }\n        const formattedAddress: string = formatAddress(addressInfo);\n        this._listeningAddress = formattedAddress;\n        // This MUST be printed to terminal so VS Code can auto-port forward\n        this._logger.writeLine(`Local proxy HttpServer listening at ws://${formattedAddress}`);\n        resolve(new URL(`ws://${formattedAddress}`));\n      });\n    });\n  }\n\n  public get endpoint(): string {\n    if (this._listeningAddress === undefined) {\n      throw new Error('HttpServer not listening yet');\n    }\n    return `ws://${this._listeningAddress}`;\n  }\n\n  public get wsServer(): WebSocketServer {\n    return this._wsServer;\n  }\n\n  public [Symbol.dispose](): void {\n    this._wsServer.close();\n    this._server.close();\n  }\n}\n"]}

package/lib-esm/LaunchOptionsValidator.js

@@ -0,0 +1,156 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+import os from 'node:os';
+import path from 'node:path';
+import { FileSystem } from '@rushstack/node-core-library';
+/**
+ * The filename used to store the launch options allowlist.
+ * Stored in the user's home directory/.playwright-browser-tunnel folder.
+ * @beta
+ */
+export const LAUNCH_OPTIONS_ALLOWLIST_FILENAME = '.playwright-launch-options-allowlist.json';
+/**
+ * Validates Playwright launch options against security allowlists.
+ * Provides utilities for managing client-side allowlist configuration.
+ * @beta
+ */
+export class LaunchOptionsValidator {
+    /**
+     * Gets the path to the allowlist file in the user's local preferences folder.
+     * This follows the pattern of playwright-browser-installed.txt but stores in user's home directory.
+     */
+    static getAllowlistFilePath() {
+        // Store in user's home directory under .playwright-browser-tunnel
+        const homeDir = os.homedir();
+        const configDir = path.join(homeDir, '.playwright-browser-tunnel');
+        return path.join(configDir, LAUNCH_OPTIONS_ALLOWLIST_FILENAME);
+    }
+    /**
+     * Reads the allowlist from the user's local file system.
+     * Returns an empty allowlist if the file doesn't exist or is invalid.
+     */
+    static async readAllowlistAsync() {
+        const allowlistPath = this.getAllowlistFilePath();
+        try {
+            if (!FileSystem.exists(allowlistPath)) {
+                return {
+                    allowedOptions: [],
+                    version: this._allowlistVersion
+                };
+            }
+            const content = await FileSystem.readFileAsync(allowlistPath);
+            const parsed = JSON.parse(content);
+            if (typeof parsed === 'object' &&
+                parsed !== null &&
+                'allowedOptions' in parsed &&
+                Array.isArray(parsed.allowedOptions) &&
+                'version' in parsed &&
+                typeof parsed.version === 'number') {
+                return parsed;
+            }
+            // Invalid format, return empty allowlist
+            return {
+                allowedOptions: [],
+                version: this._allowlistVersion
+            };
+        }
+        catch (error) {
+            // If we can't read the file, return empty allowlist
+            return {
+                allowedOptions: [],
+                version: this._allowlistVersion
+            };
+        }
+    }
+    /**
+     * Writes the allowlist to the user's local file system.
+     */
+    static async writeAllowlistAsync(allowlist) {
+        const allowlistPath = this.getAllowlistFilePath();
+        const configDir = path.dirname(allowlistPath);
+        // Ensure the config directory exists
+        await FileSystem.ensureFolderAsync(configDir);
+        const content = JSON.stringify(allowlist, null, 2);
+        await FileSystem.writeFileAsync(allowlistPath, content, { ensureFolderExists: true });
+    }
+    /**
+     * Validates launch options against the security allowlist.
+     * All launch options are denied by default unless explicitly allowed by the user.
+     *
+     * @param launchOptions - The launch options to validate
+     * @param terminal - Optional terminal for logging warnings
+     * @returns Validation result with filtered options and warnings
+     */
+    static async validateLaunchOptionsAsync(launchOptions, terminal) {
+        const allowlist = await this.readAllowlistAsync();
+        const allowedOptionsSet = new Set(allowlist.allowedOptions);
+        const deniedOptions = [];
+        const warnings = [];
+        const filteredOptions = {};
+        // Check each provided launch option - deny all unless explicitly allowed
+        for (const key of Object.keys(launchOptions)) {
+            if (allowedOptionsSet.has(key)) {
+                // Option is in the user's allowlist - permit it
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                filteredOptions[key] = launchOptions[key];
+                if (terminal) {
+                    terminal.writeWarningLine(`Launch option '${key}' is allowed by user allowlist. ` +
+                        `Value: ${JSON.stringify(launchOptions[key])}`);
+                }
+            }
+            else {
+                // Option is not in allowlist - deny it
+                deniedOptions.push(key);
+                const warning = `Launch option '${key}' was denied (not in allowlist). ` +
+                    `To allow this option, add it to your local allowlist at: ${this.getAllowlistFilePath()}`;
+                warnings.push(warning);
+                if (terminal) {
+                    terminal.writeWarningLine(warning);
+                }
+            }
+        }
+        return {
+            isValid: deniedOptions.length === 0,
+            deniedOptions,
+            filteredOptions,
+            warnings
+        };
+    }
+    /**
+     * Adds an option to the allowlist.
+     */
+    static async addToAllowlistAsync(option) {
+        const allowlist = await this.readAllowlistAsync();
+        if (!allowlist.allowedOptions.includes(option)) {
+            allowlist.allowedOptions.push(option);
+            await this.writeAllowlistAsync(allowlist);
+        }
+    }
+    /**
+     * Removes an option from the allowlist.
+     */
+    static async removeFromAllowlistAsync(option) {
+        const allowlist = await this.readAllowlistAsync();
+        allowlist.allowedOptions = allowlist.allowedOptions.filter((opt) => opt !== option);
+        await this.writeAllowlistAsync(allowlist);
+    }
+    /**
+     * Clears the entire allowlist.
+     */
+    static async clearAllowlistAsync() {
+        await this.writeAllowlistAsync({
+            allowedOptions: [],
+            version: this._allowlistVersion
+        });
+    }
+    /**
+     * Gets a human-readable description of the allowlist security model.
+     */
+    static getAllowlistDescription() {
+        return (`All launch options are denied by default for security.\n` +
+            `Only options explicitly added to your allowlist will be permitted.\n\n` +
+            `Allowlist location: ${this.getAllowlistFilePath()}`);
+    }
+}
+LaunchOptionsValidator._allowlistVersion = 1;
+//# sourceMappingURL=LaunchOptionsValidator.js.map

package/lib-esm/LaunchOptionsValidator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LaunchOptionsValidator.js","sourceRoot":"","sources":["../src/LaunchOptionsValidator.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\nimport os from 'node:os';\nimport path from 'node:path';\n\nimport type { LaunchOptions } from 'playwright-core';\n\nimport { FileSystem } from '@rushstack/node-core-library';\nimport type { ITerminal } from '@rushstack/terminal';\n\n/**\n * The filename used to store the launch options allowlist.\n * Stored in the user's home directory/.playwright-browser-tunnel folder.\n * @beta\n */\nexport const LAUNCH_OPTIONS_ALLOWLIST_FILENAME: string = '.playwright-launch-options-allowlist.json';\n\n/**\n * Interface for the allowlist configuration stored in the user's local file system.\n * @beta\n */\nexport interface ILaunchOptionsAllowlist {\n  /**\n   * Set of launch option keys that the user has explicitly allowed.\n   * These bypass the default security restrictions.\n   */\n  allowedOptions: string[];\n\n  /**\n   * Version of the allowlist format, for future compatibility.\n   */\n  version: number;\n}\n\n/**\n * Result of validating launch options against the allowlist.\n * @beta\n */\nexport interface ILaunchOptionsValidationResult {\n  /**\n   * Whether the launch options are valid and allowed.\n   */\n  isValid: boolean;\n\n  /**\n   * Launch options that were denied due to security restrictions.\n   */\n  deniedOptions: Array<keyof LaunchOptions>;\n\n  /**\n   * Filtered launch options with denied properties removed.\n   */\n  filteredOptions: LaunchOptions;\n\n  /**\n   * Warning messages about denied options.\n   */\n  warnings: string[];\n}\n\n/**\n * Validates Playwright launch options against security allowlists.\n * Provides utilities for managing client-side allowlist configuration.\n * @beta\n */\nexport class LaunchOptionsValidator {\n  private static readonly _allowlistVersion: number = 1;\n\n  /**\n   * Gets the path to the allowlist file in the user's local preferences folder.\n   * This follows the pattern of playwright-browser-installed.txt but stores in user's home directory.\n   */\n  public static getAllowlistFilePath(): string {\n    // Store in user's home directory under .playwright-browser-tunnel\n    const homeDir: string = os.homedir();\n    const configDir: string = path.join(homeDir, '.playwright-browser-tunnel');\n    return path.join(configDir, LAUNCH_OPTIONS_ALLOWLIST_FILENAME);\n  }\n\n  /**\n   * Reads the allowlist from the user's local file system.\n   * Returns an empty allowlist if the file doesn't exist or is invalid.\n   */\n  public static async readAllowlistAsync(): Promise<ILaunchOptionsAllowlist> {\n    const allowlistPath: string = this.getAllowlistFilePath();\n\n    try {\n      if (!FileSystem.exists(allowlistPath)) {\n        return {\n          allowedOptions: [],\n          version: this._allowlistVersion\n        };\n      }\n\n      const content: string = await FileSystem.readFileAsync(allowlistPath);\n      const parsed: unknown = JSON.parse(content);\n\n      if (\n        typeof parsed === 'object' &&\n        parsed !== null &&\n        'allowedOptions' in parsed &&\n        Array.isArray(parsed.allowedOptions) &&\n        'version' in parsed &&\n        typeof parsed.version === 'number'\n      ) {\n        return parsed as ILaunchOptionsAllowlist;\n      }\n\n      // Invalid format, return empty allowlist\n      return {\n        allowedOptions: [],\n        version: this._allowlistVersion\n      };\n    } catch (error) {\n      // If we can't read the file, return empty allowlist\n      return {\n        allowedOptions: [],\n        version: this._allowlistVersion\n      };\n    }\n  }\n\n  /**\n   * Writes the allowlist to the user's local file system.\n   */\n  public static async writeAllowlistAsync(allowlist: ILaunchOptionsAllowlist): Promise<void> {\n    const allowlistPath: string = this.getAllowlistFilePath();\n    const configDir: string = path.dirname(allowlistPath);\n\n    // Ensure the config directory exists\n    await FileSystem.ensureFolderAsync(configDir);\n\n    const content: string = JSON.stringify(allowlist, null, 2);\n    await FileSystem.writeFileAsync(allowlistPath, content, { ensureFolderExists: true });\n  }\n\n  /**\n   * Validates launch options against the security allowlist.\n   * All launch options are denied by default unless explicitly allowed by the user.\n   *\n   * @param launchOptions - The launch options to validate\n   * @param terminal - Optional terminal for logging warnings\n   * @returns Validation result with filtered options and warnings\n   */\n  public static async validateLaunchOptionsAsync(\n    launchOptions: LaunchOptions,\n    terminal?: ITerminal\n  ): Promise<ILaunchOptionsValidationResult> {\n    const allowlist: ILaunchOptionsAllowlist = await this.readAllowlistAsync();\n    const allowedOptionsSet: Set<string> = new Set(allowlist.allowedOptions);\n\n    const deniedOptions: Array<keyof LaunchOptions> = [];\n    const warnings: string[] = [];\n    const filteredOptions: LaunchOptions = {};\n\n    // Check each provided launch option - deny all unless explicitly allowed\n    for (const key of Object.keys(launchOptions) as Array<keyof LaunchOptions>) {\n      if (allowedOptionsSet.has(key)) {\n        // Option is in the user's allowlist - permit it\n        // eslint-disable-next-line @typescript-eslint/no-explicit-any\n        (filteredOptions as any)[key] = launchOptions[key];\n\n        if (terminal) {\n          terminal.writeWarningLine(\n            `Launch option '${key}' is allowed by user allowlist. ` +\n              `Value: ${JSON.stringify(launchOptions[key])}`\n          );\n        }\n      } else {\n        // Option is not in allowlist - deny it\n        deniedOptions.push(key);\n\n        const warning: string =\n          `Launch option '${key}' was denied (not in allowlist). ` +\n          `To allow this option, add it to your local allowlist at: ${this.getAllowlistFilePath()}`;\n        warnings.push(warning);\n\n        if (terminal) {\n          terminal.writeWarningLine(warning);\n        }\n      }\n    }\n\n    return {\n      isValid: deniedOptions.length === 0,\n      deniedOptions,\n      filteredOptions,\n      warnings\n    };\n  }\n\n  /**\n   * Adds an option to the allowlist.\n   */\n  public static async addToAllowlistAsync(option: keyof LaunchOptions): Promise<void> {\n    const allowlist: ILaunchOptionsAllowlist = await this.readAllowlistAsync();\n\n    if (!allowlist.allowedOptions.includes(option)) {\n      allowlist.allowedOptions.push(option);\n      await this.writeAllowlistAsync(allowlist);\n    }\n  }\n\n  /**\n   * Removes an option from the allowlist.\n   */\n  public static async removeFromAllowlistAsync(option: keyof LaunchOptions): Promise<void> {\n    const allowlist: ILaunchOptionsAllowlist = await this.readAllowlistAsync();\n    allowlist.allowedOptions = allowlist.allowedOptions.filter((opt) => opt !== option);\n    await this.writeAllowlistAsync(allowlist);\n  }\n\n  /**\n   * Clears the entire allowlist.\n   */\n  public static async clearAllowlistAsync(): Promise<void> {\n    await this.writeAllowlistAsync({\n      allowedOptions: [],\n      version: this._allowlistVersion\n    });\n  }\n\n  /**\n   * Gets a human-readable description of the allowlist security model.\n   */\n  public static getAllowlistDescription(): string {\n    return (\n      `All launch options are denied by default for security.\\n` +\n      `Only options explicitly added to your allowlist will be permitted.\\n\\n` +\n      `Allowlist location: ${this.getAllowlistFilePath()}`\n    );\n  }\n}\n"]}

package/lib-esm/PlaywrightBrowserTunnel.js

@@ -0,0 +1,467 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+import { once } from 'node:events';
+import { WebSocket } from 'ws';
+import semver from 'semver';
+import { TerminalProviderSeverity, TerminalStreamWritable } from '@rushstack/terminal';
+import { Executable, FileSystem, Async } from '@rushstack/node-core-library';
+import { getNormalizedErrorString, getWebSocketCloseReason, getWebSocketReadyStateString, WebSocketCloseCode } from './utilities';
+import { LaunchOptionsValidator } from './LaunchOptionsValidator';
+const validBrowserNames = new Set(['chromium', 'firefox', 'webkit']);
+function isValidBrowserName(browserName) {
+    return validBrowserNames.has(browserName);
+}
+/**
+ * Hosts a Playwright browser server and forwards traffic over a WebSocket tunnel.
+ * @beta
+ */
+export class PlaywrightTunnel {
+    constructor(options) {
+        this._playwrightBrowsersInstalled = new Set();
+        this._status = 'stopped';
+        this._keepRunning = false;
+        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;
+    }
+    get status() {
+        return this._status;
+    }
+    // eslint-disable-next-line @typescript-eslint/naming-convention
+    set status(newStatus) {
+        this._status = newStatus;
+        this._onStatusChange(newStatus);
+    }
+    async waitForCloseAsync() {
+        const terminal = this._terminal;
+        const initWsPromise = this._initWsPromise;
+        if (initWsPromise) {
+            const ws = await initWsPromise;
+            await once(ws, 'close');
+            terminal.writeDebugLine('WebSocket connection closed. resolving init promise.');
+            this._initWsPromise = undefined;
+        }
+    }
+    async startAsync(options = {}) {
+        var _a;
+        this._keepRunning = (_a = options.keepRunning) !== null && _a !== void 0 ? _a : true;
+        const terminal = 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();
+        }
+    }
+    async stopAsync() {
+        var _a;
+        this._keepRunning = false;
+        if (this._pollInterval) {
+            clearInterval(this._pollInterval);
+            this._pollInterval = undefined;
+        }
+        await ((_a = this._initWsPromise) === null || _a === void 0 ? void 0 : _a.finally(() => {
+            var _a;
+            (_a = this._ws) === null || _a === void 0 ? void 0 : _a.close(WebSocketCloseCode.NORMAL_CLOSURE, 'Tunnel stopped');
+        }));
+    }
+    async [Symbol.asyncDispose]() {
+        this._terminal.writeLine('Disposing WebSocket connection.');
+        await this.stopAsync();
+    }
+    async cleanTempFilesAsync() {
+        const tmpPath = 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> {}
+    async _runCommandAsync(command, args) {
+        var _a, _b;
+        const tmpPath = this._playwrightInstallPath;
+        await FileSystem.ensureFolderAsync(tmpPath);
+        this._terminal.writeLine(`Running command: ${command} ${args.join(' ')} in ${tmpPath}`);
+        const cp = Executable.spawn(command, args, {
+            stdio: [
+                'ignore', // stdin
+                'pipe', // stdout
+                'pipe' // stderr
+            ],
+            currentWorkingDirectory: tmpPath
+        });
+        (_a = cp.stdout) === null || _a === void 0 ? void 0 : _a.pipe(new TerminalStreamWritable({
+            terminal: this._terminal,
+            severity: TerminalProviderSeverity.log
+        }));
+        (_b = cp.stderr) === null || _b === void 0 ? void 0 : _b.pipe(new TerminalStreamWritable({
+            terminal: this._terminal,
+            severity: TerminalProviderSeverity.error
+        }));
+        await Executable.waitForExitAsync(cp, { throwOnNonZeroExitCode: true, throwOnSignal: true });
+    }
+    async _installPlaywrightCoreAsync({ playwrightVersion }) {
+        this._terminal.writeLine(`Installing playwright-core version ${playwrightVersion}`);
+        await this._runCommandAsync('npm', [
+            'install',
+            `playwright-core-${playwrightVersion}@npm:playwright-core@${playwrightVersion}`
+        ]);
+    }
+    async _installPlaywrightBrowsersAsync({ playwrightVersion, browserName }) {
+        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
+        ]);
+    }
+    async _tryConnectAsync() {
+        const wsEndpoint = this._wsEndpoint;
+        if (!wsEndpoint) {
+            throw new Error('WebSocket endpoint is not defined');
+        }
+        return await new Promise((resolve, reject) => {
+            const ws = 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.
+    async _pollConnectionAsync() {
+        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 = this._tryConnectAsync();
+                this._pendingConnectionAttempt = connectionPromise;
+                connectionPromise
+                    .then((ws) => {
+                    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);
+        });
+    }
+    async _waitForIncomingConnectionAsync() {
+        this._terminal.writeLine('Waiting for incoming WebSocket connection');
+        return await new Promise((resolve, reject) => {
+            const server = new WebSocket.Server({ port: this._listenPort });
+            const cleanup = () => {
+                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) => {
+                    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?
+    async _setupPlaywrightAsync({ playwrightVersion, browserName }) {
+        const browserKey = `${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}`);
+    }
+    async _getPlaywrightBrowserServerProxyAsync({ browserName, playwrightVersion, launchOptions }) {
+        const terminal = this._terminal;
+        // Validate launch options against security allowlist
+        terminal.writeLine('Validating launch options against security allowlist...');
+        const validationResult = 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 = {
+            ...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 = await this._setupPlaywrightAsync({
+            playwrightVersion,
+            browserName
+        });
+        const { chromium, firefox, webkit } = playwright;
+        const browsers = { chromium, firefox, webkit };
+        const 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 = new WebSocket(browserServer.wsEndpoint());
+        return {
+            browserServer,
+            client
+        };
+    }
+    _validateHandshake(rawHandshake) {
+        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.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,
+            playwrightVersion: playwrightVersionSemver,
+            browserName
+        };
+    }
+    // ws1 is the tunnel websocket, ws2 is the browser server websocket
+    async _setupForwardingAsync(ws1, ws2) {
+        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: 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, reason) => {
+            const reasonStr = reason.toString() || 'no reason provided';
+            const codeDescription = 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, reason) => {
+            const reasonStr = reason.toString() || 'no reason provided';
+            const codeDescription = 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.
+     */
+    async _initPlaywrightBrowserTunnelAsync() {
+        let handshake = undefined;
+        let client = undefined;
+        let browserServer = undefined;
+        this.status = 'waiting-for-connection';
+        const ws = 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, reason) => {
+            const reasonStr = reason.toString() || 'no reason provided';
+            const codeDescription = 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((resolve, reject) => {
+            const onMessageHandler = async (data) => {
+                const terminal = this._terminal;
+                if (!handshake) {
+                    try {
+                        const rawHandshakeString = data.toString();
+                        const rawHandshake = 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 = 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 = await this._getPlaywrightBrowserServerProxyAsync(handshake);
+                        client = browserServerProxy.client;
+                        browserServer = browserServerProxy.browserServer;
+                        // Monitor browser server process for crashes
+                        const browserProcess = browserServer.process();
+                        if (browserProcess) {
+                            browserProcess.on('exit', (code, signal) => {
+                                terminal.writeErrorLine(`Browser server process exited - code: ${code}, signal: ${signal}`);
+                            });
+                            browserProcess.on('error', (err) => {
+                                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);
+        });
+    }
+}
+//# sourceMappingURL=PlaywrightBrowserTunnel.js.map