@rushstack/playwright-browser-tunnel 0.1.0

package/lib/tunneledBrowserConnection.d.ts

@@ -0,0 +1,48 @@
+import type { Browser, LaunchOptions } from 'playwright-core';
+import { type ITerminal } from '@rushstack/terminal';
+import type { BrowserName } from './PlaywrightBrowserTunnel';
+/**
+ * Disposable handle returned by {@link tunneledBrowserConnection}.
+ * @beta
+ */
+export interface IDisposableTunneledBrowserConnection {
+    /**
+     * The WebSocket endpoint URL that the local Playwright client should connect to.
+     */
+    remoteEndpoint: string;
+    /**
+     * Dispose method that closes the WebSocket servers.
+     * Called automatically when using `using` syntax.
+     */
+    [Symbol.dispose]: () => void;
+    /**
+     * Promise that resolves when the remote WebSocket server closes.
+     */
+    closePromise: Promise<void>;
+}
+/**
+ * Creates a tunneled WebSocket endpoint that a local Playwright client can connect to.
+ * @beta
+ */
+export declare function tunneledBrowserConnection(logger: ITerminal, port?: number): Promise<IDisposableTunneledBrowserConnection>;
+/**
+ * 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>;
+}
+/**
+ * Creates a Playwright Browser instance connected via a tunneled WebSocket connection.
+ * @beta
+ */
+export declare function createTunneledBrowserAsync(browserName: BrowserName, launchOptions: LaunchOptions, logger?: ITerminal, port?: number): Promise<IDisposableTunneledBrowser>;
+//# sourceMappingURL=tunneledBrowserConnection.d.ts.map

package/lib/tunneledBrowserConnection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunneledBrowserConnection.d.ts","sourceRoot":"","sources":["../src/tunneledBrowserConnection.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAI9D,OAAO,EAAE,KAAK,SAAS,EAAqC,MAAM,qBAAqB,CAAC;AAExF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAoB7D;;;GAGG;AACH,MAAM,WAAW,oCAAoC;IACnD;;OAEG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IAC7B;;OAEG;IACH,YAAY,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B;AAED;;;GAGG;AACH,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,SAAS,EACjB,IAAI,GAAE,MAA4B,GACjC,OAAO,CAAC,oCAAoC,CAAC,CA4K/C;AAED;;;GAGG;AACH,MAAM,WAAW,0BAA0B;IACzC;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,CAAC,MAAM,CAAC,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5C;AAED;;;GAGG;AACH,wBAAsB,0BAA0B,CAC9C,WAAW,EAAE,WAAW,EACxB,aAAa,EAAE,aAAa,EAC5B,MAAM,CAAC,EAAE,SAAS,EAClB,IAAI,GAAE,MAA4B,GACjC,OAAO,CAAC,0BAA0B,CAAC,CA2BrC"}

package/lib/tunneledBrowserConnection.js

@@ -0,0 +1,216 @@
+"use strict";
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tunneledBrowserConnection = tunneledBrowserConnection;
+exports.createTunneledBrowserAsync = createTunneledBrowserAsync;
+const playwright_core_1 = __importDefault(require("playwright-core"));
+const ws_1 = require("ws");
+const package_json_1 = __importDefault(require("playwright-core/package.json"));
+const terminal_1 = require("@rushstack/terminal");
+const HttpServer_1 = require("./HttpServer");
+const { version: playwrightVersion } = package_json_1.default;
+const SUPPORTED_BROWSER_NAMES = new Set(['chromium', 'firefox', 'webkit']);
+const DEFAULT_LISTEN_PORT = 3000;
+/**
+ * Creates a tunneled WebSocket endpoint that a local Playwright client can connect to.
+ * @beta
+ */
+async function tunneledBrowserConnection(logger, port = DEFAULT_LISTEN_PORT) {
+    // Server that remote peer (actual browser host) connects to
+    const remoteWsServer = new ws_1.WebSocketServer({ port });
+    // Local HTTP + WebSocket server where the playwright client will connect providing params
+    const httpServer = new HttpServer_1.HttpServer(logger);
+    await httpServer.listenAsync();
+    logger.writeLine(`Remote WebSocket server listening on ws://localhost:${port}`);
+    const localProxyWs = httpServer.wsServer;
+    const localProxyWsEndpoint = httpServer.endpoint;
+    let browserName;
+    let launchOptions;
+    let remoteSocket;
+    let handshakeAck = false;
+    let handshakeSent = false;
+    function maybeSendHandshake() {
+        if (!handshakeSent && remoteSocket && browserName && launchOptions) {
+            const handshake = {
+                action: 'handshake',
+                browserName,
+                launchOptions,
+                playwrightVersion
+            };
+            // Log handshake without 'headless' to avoid confusion (tunnel enforces headless: false)
+            // eslint-disable-next-line @typescript-eslint/no-unused-vars
+            const { headless, ...logOptions } = launchOptions;
+            const logHandshake = {
+                ...handshake,
+                launchOptions: logOptions
+            };
+            logger.writeLine(`Sending handshake to remote: ${JSON.stringify(logHandshake)}`);
+            handshakeSent = true;
+            remoteSocket.send(JSON.stringify(handshake));
+        }
+    }
+    return await new Promise((resolve) => {
+        remoteWsServer.on('error', (error) => {
+            logger.writeErrorLine(`Remote WebSocket server error: ${error}`);
+        });
+        remoteWsServer.on('close', () => {
+            logger.writeLine('Remote WebSocket server closed');
+        });
+        const bufferedLocalMessages = [];
+        remoteWsServer.on('connection', (ws) => {
+            logger.writeLine('Remote websocket connected');
+            remoteSocket = ws;
+            handshakeAck = false;
+            maybeSendHandshake();
+            ws.on('message', (message) => {
+                if (!handshakeAck) {
+                    try {
+                        const receivedHandshake = JSON.parse(message.toString());
+                        if (receivedHandshake.action === 'handshakeAck') {
+                            handshakeAck = true;
+                            logger.writeLine('Received handshakeAck from remote');
+                        }
+                        else {
+                            logger.writeErrorLine('Invalid handshake ack message');
+                            ws.close();
+                            return;
+                        }
+                    }
+                    catch (e) {
+                        logger.writeErrorLine(`Failed parsing handshake ack: ${e}`);
+                        ws.close();
+                        return;
+                    }
+                    // Resolve only once local proxy available and handshake acknowledged
+                    if (handshakeAck) {
+                        // Flush any buffered local messages now that tunnel is active
+                        const activeRemote = remoteSocket;
+                        if (activeRemote && activeRemote.readyState === ws_1.WebSocket.OPEN) {
+                            while (bufferedLocalMessages.length > 0) {
+                                const m = bufferedLocalMessages.shift();
+                                if (m !== undefined) {
+                                    logger.writeLine(`Flushing buffered local message to remote: ${m}`);
+                                    activeRemote.send(m);
+                                }
+                            }
+                        }
+                    }
+                }
+                else {
+                    // Forward from remote to all local clients
+                    localProxyWs.clients.forEach((client) => {
+                        if (client.readyState === ws_1.WebSocket.OPEN) {
+                            client.send(message);
+                        }
+                    });
+                }
+            });
+            ws.on('close', () => logger.writeLine('Remote websocket closed'));
+            ws.on('error', (err) => logger.writeErrorLine(`Remote websocket error: ${err}`));
+        });
+        localProxyWs.on('connection', (localWs, request) => {
+            try {
+                const urlString = request === null || request === void 0 ? void 0 : request.url;
+                if (urlString) {
+                    const parsed = new URL(urlString, 'http://localhost');
+                    logger.writeLine(`Local client connected with query params: ${parsed.searchParams.toString()}`);
+                    const bName = parsed.searchParams.get('browser');
+                    if (bName && SUPPORTED_BROWSER_NAMES.has(bName)) {
+                        browserName = bName;
+                    }
+                    const launchOptionsParam = parsed.searchParams.get('launchOptions');
+                    if (launchOptionsParam) {
+                        try {
+                            launchOptions = JSON.parse(launchOptionsParam);
+                        }
+                        catch (e) {
+                            logger.writeErrorLine('Invalid launchOptions JSON provided');
+                        }
+                    }
+                }
+            }
+            catch (e) {
+                logger.writeErrorLine(`Error parsing local connection query params: ${e}`);
+            }
+            if (!browserName) {
+                const supportedBrowsersString = Array.from(SUPPORTED_BROWSER_NAMES).join('|');
+                logger.writeErrorLine(`browser query param required (${supportedBrowsersString})`);
+                localWs.close();
+                return;
+            }
+            if (!launchOptions) {
+                launchOptions = {}; // default empty if not provided
+            }
+            maybeSendHandshake();
+            localWs.on('message', (message) => {
+                if (handshakeAck && (remoteSocket === null || remoteSocket === void 0 ? void 0 : remoteSocket.readyState) === ws_1.WebSocket.OPEN) {
+                    remoteSocket.send(message);
+                }
+                else {
+                    // Buffer until handshakeAck to avoid losing early protocol messages from Playwright
+                    bufferedLocalMessages.push(message);
+                }
+            });
+            localWs.on('close', () => logger.writeLine('Local client websocket closed'));
+            localWs.on('error', (err) => logger.writeErrorLine(`Local client websocket error: ${err}`));
+        });
+        // Resolve immediately so caller can initiate local connection with query params (handshake completes later)
+        resolve({
+            remoteEndpoint: localProxyWsEndpoint,
+            [Symbol.dispose]() {
+                try {
+                    remoteWsServer.close();
+                }
+                catch (_a) {
+                    // ignore errors during remote WebSocket server shutdown
+                }
+                try {
+                    httpServer[Symbol.dispose]();
+                }
+                catch (_b) {
+                    // ignore errors during HTTP/WebSocket server shutdown
+                }
+            },
+            // eslint-disable-next-line promise/param-names
+            closePromise: new Promise((resolve2) => {
+                remoteWsServer.once('close', () => {
+                    resolve2();
+                });
+            })
+        });
+    });
+}
+/**
+ * Creates a Playwright Browser instance connected via a tunneled WebSocket connection.
+ * @beta
+ */
+async function createTunneledBrowserAsync(browserName, launchOptions, logger, port = DEFAULT_LISTEN_PORT) {
+    // Establish the tunnel first (remoteEndpoint here refers to local proxy endpoint for connect())
+    if (!logger) {
+        const terminalProvider = new terminal_1.ConsoleTerminalProvider();
+        logger = new terminal_1.Terminal(terminalProvider);
+    }
+    const connection = await tunneledBrowserConnection(logger, port);
+    const { remoteEndpoint } = connection;
+    // Append query params for browser and launchOptions
+    const urlObj = new URL(remoteEndpoint);
+    urlObj.searchParams.set('browser', browserName);
+    urlObj.searchParams.set('launchOptions', JSON.stringify(launchOptions || {}));
+    const connectEndpoint = urlObj.toString();
+    const browser = await playwright_core_1.default[browserName].connect(connectEndpoint);
+    logger.writeLine(`Connected to remote browser at ${connectEndpoint}`);
+    return {
+        browser,
+        async [Symbol.asyncDispose]() {
+            logger.writeLine('Disposing browser');
+            await browser.close();
+            // Dispose the tunnel connection after browser is closed
+            connection[Symbol.dispose]();
+        }
+    };
+}
+//# sourceMappingURL=tunneledBrowserConnection.js.map

package/lib/tunneledBrowserConnection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunneledBrowserConnection.js","sourceRoot":"","sources":["../src/tunneledBrowserConnection.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 playwright from 'playwright-core';\nimport type { Browser, LaunchOptions } from 'playwright-core';\nimport { WebSocketServer, WebSocket, type RawData } from 'ws';\nimport playwrightPackageJson from 'playwright-core/package.json';\n\nimport { type ITerminal, Terminal, ConsoleTerminalProvider } from '@rushstack/terminal';\n\nimport type { BrowserName } from './PlaywrightBrowserTunnel';\nimport { HttpServer } from './HttpServer';\n\nconst { version: playwrightVersion } = playwrightPackageJson;\n\nconst SUPPORTED_BROWSER_NAMES: Set<string> = new Set(['chromium', 'firefox', 'webkit']);\n\ninterface IHandshake {\n  action: 'handshake';\n  browserName: BrowserName;\n  launchOptions: LaunchOptions;\n  playwrightVersion: string;\n}\n\ninterface IHandshakeAck {\n  action: 'handshakeAck';\n}\n\nconst DEFAULT_LISTEN_PORT: number = 3000;\n\n/**\n * Disposable handle returned by {@link tunneledBrowserConnection}.\n * @beta\n */\nexport interface IDisposableTunneledBrowserConnection {\n  /**\n   * The WebSocket endpoint URL that the local Playwright client should connect to.\n   */\n  remoteEndpoint: string;\n  /**\n   * Dispose method that closes the WebSocket servers.\n   * Called automatically when using `using` syntax.\n   */\n  [Symbol.dispose]: () => void;\n  /**\n   * Promise that resolves when the remote WebSocket server closes.\n   */\n  closePromise: Promise<void>;\n}\n\n/**\n * Creates a tunneled WebSocket endpoint that a local Playwright client can connect to.\n * @beta\n */\nexport async function tunneledBrowserConnection(\n  logger: ITerminal,\n  port: number = DEFAULT_LISTEN_PORT\n): Promise<IDisposableTunneledBrowserConnection> {\n  // Server that remote peer (actual browser host) connects to\n  const remoteWsServer: WebSocketServer = new WebSocketServer({ port });\n  // Local HTTP + WebSocket server where the playwright client will connect providing params\n  const httpServer: HttpServer = new HttpServer(logger);\n  await httpServer.listenAsync();\n  logger.writeLine(`Remote WebSocket server listening on ws://localhost:${port}`);\n\n  const localProxyWs: WebSocketServer = httpServer.wsServer;\n  const localProxyWsEndpoint: string = httpServer.endpoint;\n\n  let browserName: BrowserName | undefined;\n  let launchOptions: LaunchOptions | undefined;\n  let remoteSocket: WebSocket | undefined;\n  let handshakeAck: boolean = false;\n  let handshakeSent: boolean = false;\n\n  function maybeSendHandshake(): void {\n    if (!handshakeSent && remoteSocket && browserName && launchOptions) {\n      const handshake: IHandshake = {\n        action: 'handshake',\n        browserName,\n        launchOptions,\n        playwrightVersion\n      };\n      // Log handshake without 'headless' to avoid confusion (tunnel enforces headless: false)\n      // eslint-disable-next-line @typescript-eslint/no-unused-vars\n      const { headless, ...logOptions } = launchOptions;\n      const logHandshake: Omit<IHandshake, 'launchOptions'> & {\n        launchOptions: Omit<LaunchOptions, 'headless'>;\n      } = {\n        ...handshake,\n        launchOptions: logOptions\n      };\n      logger.writeLine(`Sending handshake to remote: ${JSON.stringify(logHandshake)}`);\n      handshakeSent = true;\n      remoteSocket.send(JSON.stringify(handshake));\n    }\n  }\n\n  return await new Promise((resolve) => {\n    remoteWsServer.on('error', (error) => {\n      logger.writeErrorLine(`Remote WebSocket server error: ${error}`);\n    });\n\n    remoteWsServer.on('close', () => {\n      logger.writeLine('Remote WebSocket server closed');\n    });\n\n    const bufferedLocalMessages: Array<RawData> = [];\n\n    remoteWsServer.on('connection', (ws) => {\n      logger.writeLine('Remote websocket connected');\n      remoteSocket = ws;\n      handshakeAck = false;\n      maybeSendHandshake();\n\n      ws.on('message', (message) => {\n        if (!handshakeAck) {\n          try {\n            const receivedHandshake: IHandshakeAck = JSON.parse(message.toString());\n            if (receivedHandshake.action === 'handshakeAck') {\n              handshakeAck = true;\n              logger.writeLine('Received handshakeAck from remote');\n            } else {\n              logger.writeErrorLine('Invalid handshake ack message');\n              ws.close();\n              return;\n            }\n          } catch (e) {\n            logger.writeErrorLine(`Failed parsing handshake ack: ${e}`);\n            ws.close();\n            return;\n          }\n          // Resolve only once local proxy available and handshake acknowledged\n          if (handshakeAck) {\n            // Flush any buffered local messages now that tunnel is active\n            const activeRemote: WebSocket | undefined = remoteSocket;\n            if (activeRemote && activeRemote.readyState === WebSocket.OPEN) {\n              while (bufferedLocalMessages.length > 0) {\n                const m: Buffer | ArrayBuffer | Buffer[] | string | undefined = bufferedLocalMessages.shift();\n                if (m !== undefined) {\n                  logger.writeLine(`Flushing buffered local message to remote: ${m}`);\n                  activeRemote.send(m);\n                }\n              }\n            }\n          }\n        } else {\n          // Forward from remote to all local clients\n          localProxyWs.clients.forEach((client) => {\n            if (client.readyState === WebSocket.OPEN) {\n              client.send(message);\n            }\n          });\n        }\n      });\n\n      ws.on('close', () => logger.writeLine('Remote websocket closed'));\n      ws.on('error', (err) => logger.writeErrorLine(`Remote websocket error: ${err}`));\n    });\n\n    localProxyWs.on('connection', (localWs, request) => {\n      try {\n        const urlString: string | undefined = request?.url;\n        if (urlString) {\n          const parsed: URL = new URL(urlString, 'http://localhost');\n          logger.writeLine(`Local client connected with query params: ${parsed.searchParams.toString()}`);\n          const bName: string | null = parsed.searchParams.get('browser');\n          if (bName && SUPPORTED_BROWSER_NAMES.has(bName)) {\n            browserName = bName as BrowserName;\n          }\n          const launchOptionsParam: string | null = parsed.searchParams.get('launchOptions');\n          if (launchOptionsParam) {\n            try {\n              launchOptions = JSON.parse(launchOptionsParam);\n            } catch (e) {\n              logger.writeErrorLine('Invalid launchOptions JSON provided');\n            }\n          }\n        }\n      } catch (e) {\n        logger.writeErrorLine(`Error parsing local connection query params: ${e}`);\n      }\n\n      if (!browserName) {\n        const supportedBrowsersString: string = Array.from(SUPPORTED_BROWSER_NAMES).join('|');\n        logger.writeErrorLine(`browser query param required (${supportedBrowsersString})`);\n        localWs.close();\n        return;\n      }\n      if (!launchOptions) {\n        launchOptions = {} as LaunchOptions; // default empty if not provided\n      }\n\n      maybeSendHandshake();\n\n      localWs.on('message', (message) => {\n        if (handshakeAck && remoteSocket?.readyState === WebSocket.OPEN) {\n          remoteSocket.send(message);\n        } else {\n          // Buffer until handshakeAck to avoid losing early protocol messages from Playwright\n          bufferedLocalMessages.push(message);\n        }\n      });\n      localWs.on('close', () => logger.writeLine('Local client websocket closed'));\n      localWs.on('error', (err) => logger.writeErrorLine(`Local client websocket error: ${err}`));\n    });\n\n    // Resolve immediately so caller can initiate local connection with query params (handshake completes later)\n    resolve({\n      remoteEndpoint: localProxyWsEndpoint,\n      [Symbol.dispose]() {\n        try {\n          remoteWsServer.close();\n        } catch {\n          // ignore errors during remote WebSocket server shutdown\n        }\n        try {\n          httpServer[Symbol.dispose]();\n        } catch {\n          // ignore errors during HTTP/WebSocket server shutdown\n        }\n      },\n      // eslint-disable-next-line promise/param-names\n      closePromise: new Promise<void>((resolve2) => {\n        remoteWsServer.once('close', () => {\n          resolve2();\n        });\n      })\n    });\n  });\n}\n\n/**\n * Disposable handle returned by {@link createTunneledBrowserAsync}.\n * @beta\n */\nexport interface IDisposableTunneledBrowser {\n  /**\n   * The connected Playwright Browser instance.\n   */\n  browser: Browser;\n  /**\n   * Async dispose method that closes the browser connection.\n   * Called automatically when using `await using` syntax.\n   */\n  [Symbol.asyncDispose]: () => Promise<void>;\n}\n\n/**\n * Creates a Playwright Browser instance connected via a tunneled WebSocket connection.\n * @beta\n */\nexport async function createTunneledBrowserAsync(\n  browserName: BrowserName,\n  launchOptions: LaunchOptions,\n  logger?: ITerminal,\n  port: number = DEFAULT_LISTEN_PORT\n): Promise<IDisposableTunneledBrowser> {\n  // Establish the tunnel first (remoteEndpoint here refers to local proxy endpoint for connect())\n\n  if (!logger) {\n    const terminalProvider: ConsoleTerminalProvider = new ConsoleTerminalProvider();\n    logger = new Terminal(terminalProvider);\n  }\n\n  const connection: IDisposableTunneledBrowserConnection = await tunneledBrowserConnection(logger, port);\n  const { remoteEndpoint } = connection;\n  // Append query params for browser and launchOptions\n  const urlObj: URL = new URL(remoteEndpoint);\n  urlObj.searchParams.set('browser', browserName);\n  urlObj.searchParams.set('launchOptions', JSON.stringify(launchOptions || {}));\n  const connectEndpoint: string = urlObj.toString();\n  const browser: Browser = await playwright[browserName].connect(connectEndpoint);\n  logger.writeLine(`Connected to remote browser at ${connectEndpoint}`);\n\n  return {\n    browser,\n    async [Symbol.asyncDispose]() {\n      logger.writeLine('Disposing browser');\n      await browser.close();\n      // Dispose the tunnel connection after browser is closed\n      connection[Symbol.dispose]();\n    }\n  };\n}\n"]}

package/lib/utilities.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The filename used to indicate that the Playwright on Codespaces extension is installed.
+ * @beta
+ */
+export declare const EXTENSION_INSTALLED_FILENAME: string;
+/**
+ * Helper to determine if the Playwright on Codespaces extension is installed. This check's for the
+ * existence of a well-known file in the OS temp directory.
+ * @beta
+ */
+export declare function isExtensionInstalledAsync(): Promise<boolean>;
+/**
+ * Normalizes an error to a string for logging purposes.
+ * @beta
+ */
+export declare function getNormalizedErrorString(error: unknown): string;
+//# sourceMappingURL=utilities.d.ts.map

package/lib/utilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utilities.d.ts","sourceRoot":"","sources":["../src/utilities.ts"],"names":[],"mappings":"AAOA;;;GAGG;AACH,eAAO,MAAM,4BAA4B,EAAE,MAAyD,CAAC;AAErG;;;;GAIG;AACH,wBAAsB,yBAAyB,IAAI,OAAO,CAAC,OAAO,CAAC,CASlE;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAQ/D"}

package/lib/utilities.js

@@ -0,0 +1,41 @@
+"use strict";
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXTENSION_INSTALLED_FILENAME = void 0;
+exports.isExtensionInstalledAsync = isExtensionInstalledAsync;
+exports.getNormalizedErrorString = getNormalizedErrorString;
+const node_os_1 = require("node:os");
+const node_core_library_1 = require("@rushstack/node-core-library");
+/**
+ * The filename used to indicate that the Playwright on Codespaces extension is installed.
+ * @beta
+ */
+exports.EXTENSION_INSTALLED_FILENAME = '.playwright-codespaces-extension-installed.txt';
+/**
+ * Helper to determine if the Playwright on Codespaces extension is installed. This check's for the
+ * existence of a well-known file in the OS temp directory.
+ * @beta
+ */
+async function isExtensionInstalledAsync() {
+    // Read file from os.tempdir() + '/.playwright-codespaces-extension-installed'
+    const tempDir = (0, node_os_1.tmpdir)();
+    const extensionInstalledFilePath = `${tempDir}/${exports.EXTENSION_INSTALLED_FILENAME}`;
+    const doesExist = node_core_library_1.FileSystem.exists(extensionInstalledFilePath);
+    // check if file exists
+    return doesExist;
+}
+/**
+ * Normalizes an error to a string for logging purposes.
+ * @beta
+ */
+function getNormalizedErrorString(error) {
+    if (error instanceof Error) {
+        if (error.stack) {
+            return error.stack;
+        }
+        return error.message;
+    }
+    return String(error);
+}
+//# sourceMappingURL=utilities.js.map

package/lib/utilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utilities.js","sourceRoot":"","sources":["../src/utilities.ts"],"names":[],"mappings":";AAAA,4FAA4F;AAC5F,2DAA2D;;;AAiB3D,8DASC;AAMD,4DAQC;AAtCD,qCAAiC;AAEjC,oEAA0D;AAE1D;;;GAGG;AACU,QAAA,4BAA4B,GAAW,gDAAgD,CAAC;AAErG;;;;GAIG;AACI,KAAK,UAAU,yBAAyB;IAC7C,8EAA8E;IAC9E,MAAM,OAAO,GAAW,IAAA,gBAAM,GAAE,CAAC;IAEjC,MAAM,0BAA0B,GAAW,GAAG,OAAO,IAAI,oCAA4B,EAAE,CAAC;IACxF,MAAM,SAAS,GAAY,8BAAU,CAAC,MAAM,CAAC,0BAA0B,CAAC,CAAC;IAEzE,uBAAuB;IACvB,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,SAAgB,wBAAwB,CAAC,KAAc;IACrD,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;YAChB,OAAO,KAAK,CAAC,KAAK,CAAC;QACrB,CAAC;QACD,OAAO,KAAK,CAAC,OAAO,CAAC;IACvB,CAAC;IACD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;AACvB,CAAC","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 { tmpdir } from 'node:os';\n\nimport { FileSystem } from '@rushstack/node-core-library';\n\n/**\n * The filename used to indicate that the Playwright on Codespaces extension is installed.\n * @beta\n */\nexport const EXTENSION_INSTALLED_FILENAME: string = '.playwright-codespaces-extension-installed.txt';\n\n/**\n * Helper to determine if the Playwright on Codespaces extension is installed. This check's for the\n * existence of a well-known file in the OS temp directory.\n * @beta\n */\nexport async function isExtensionInstalledAsync(): Promise<boolean> {\n  // Read file from os.tempdir() + '/.playwright-codespaces-extension-installed'\n  const tempDir: string = tmpdir();\n\n  const extensionInstalledFilePath: string = `${tempDir}/${EXTENSION_INSTALLED_FILENAME}`;\n  const doesExist: boolean = FileSystem.exists(extensionInstalledFilePath);\n\n  // check if file exists\n  return doesExist;\n}\n\n/**\n * Normalizes an error to a string for logging purposes.\n * @beta\n */\nexport function getNormalizedErrorString(error: unknown): string {\n  if (error instanceof Error) {\n    if (error.stack) {\n      return error.stack;\n    }\n    return error.message;\n  }\n  return String(error);\n}\n"]}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@rushstack/playwright-browser-tunnel",
+  "version": "0.1.0",
+  "description": "Run a remote Playwright Browser Tunnel. Useful in remote development environments.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/microsoft/rushstack.git",
+    "directory": "apps/playwright-browser-tunnel"
+  },
+  "main": "lib/index.js",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "engineStrict": true,
+  "homepage": "https://rushstack.io",
+  "dependencies": {
+    "string-argv": "~0.3.1",
+    "semver": "~7.5.4",
+    "ws": "~8.14.1",
+    "playwright": "1.56.1",
+    "@rushstack/node-core-library": "5.19.1",
+    "@rushstack/terminal": "0.21.0",
+    "@rushstack/ts-command-line": "5.1.7"
+  },
+  "devDependencies": {
+    "eslint": "~9.37.0",
+    "@types/semver": "7.5.0",
+    "@types/ws": "8.5.5",
+    "playwright-core": "~1.56.1",
+    "@playwright/test": "~1.56.1",
+    "@types/node": "20.17.19",
+    "@rushstack/heft": "1.1.10",
+    "local-node-rig": "1.0.0"
+  },
+  "peerDependencies": {
+    "playwright-core": "~1.56.1"
+  },
+  "scripts": {
+    "build": "heft build --clean",
+    "_phase:build": "heft run --only build -- --clean",
+    "demo": "playwright test --config=playwright.config.ts"
+  }
+}

package/playwright.config.ts

@@ -0,0 +1,45 @@
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './tests',
+  /* Run tests in files in parallel */
+  fullyParallel: true,
+  /* Retry on CI only */
+  retries: 0,
+  /* Opt out of parallel tests on CI. */
+  workers: 1,
+  /* Reporter to use. See https://playwright.dev/docs/test-reporters */
+  reporter: 'html',
+  /* Shared settings for all the projects below. See https://playwright.dev/docs/api/class-testoptions. */
+  use: {
+    /* Base URL to use in actions like `await page.goto('/')`. */
+    // baseURL: 'http://localhost:3000',
+
+    /* Collect trace when retrying the failed test. See https://playwright.dev/docs/trace-viewer */
+    trace: 'on'
+  },
+
+  /* Configure projects for major browsers */
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] }
+    },
+    {
+      name: 'firefox',
+      use: { ...devices['Desktop Firefox'] }
+    },
+    {
+      name: 'webkit',
+      use: { ...devices['Desktop Safari'] }
+    },
+    {
+      name: 'Google Chrome',
+      use: { ...devices['Desktop Chrome'], channel: 'chrome' } // or 'chrome-beta'
+    },
+    {
+      name: 'Microsoft Edge',
+      use: { ...devices['Desktop Edge'], channel: 'msedge' } // or "msedge-beta" or 'msedge-dev'
+    }
+  ]
+});

package/rush-logs/playwright-browser-tunnel._phase_build.cache.log

@@ -0,0 +1,3 @@
+Caching build output folders: dist, lib, temp, .rush/temp/operation/_phase_build
+Successfully set cache entry.
+Cache key: rushstack+playwright-browser-tunnel-_phase_build-83a085f61cdc0a4bb81c20aa939830fc5b5cff2f

package/rush-logs/playwright-browser-tunnel._phase_build.log

@@ -0,0 +1,8 @@
+Invoking: heft run --only build -- --clean --production
+ ---- build started ---- 
+[build:typescript] Using TypeScript version 5.8.2
+[build:lint] Using ESLint version 9.37.0
+[build:api-extractor] Using API Extractor version 7.55.5
+[build:api-extractor] Analysis will use the bundled TypeScript version 5.8.2
+ ---- build finished (22.696s) ---- 
+-------------------- Finished (22.704s) --------------------

package/src/HttpServer.ts

@@ -0,0 +1,87 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import http from 'node:http';
+import type { AddressInfo } from 'node:net';
+import { URL } from 'node:url';
+
+import { WebSocketServer, type WebSocket } from 'ws';
+
+import type { ITerminal } from '@rushstack/terminal';
+
+const LOCALHOST: string = 'localhost';
+
+/**
+ * Formats an address info object into a WebSocket-compatible address string.
+ * IPv6 addresses are formatted with brackets: [address]:port
+ * IPv4 addresses are formatted as: address:port
+ */
+function formatAddress(addressInfo: AddressInfo): string {
+  return addressInfo.family === 'IPv6'
+    ? `[${addressInfo.address}]:${addressInfo.port}`
+    : `${addressInfo.address}:${addressInfo.port}`;
+}
+
+/**
+ * This HttpServer is used for the localProxyWs WebSocketServer.
+ * The purpose is to parse the query params and path for the websocket url to get the
+ * browserName and launchOptions.
+ */
+export class HttpServer {
+  private readonly _server: http.Server;
+  private readonly _wsServer: WebSocketServer; // local proxy websocket server accepting browser clients
+  private _listeningAddress: string | undefined;
+  private _logger: ITerminal;
+
+  public constructor(logger: ITerminal) {
+    this._logger = logger;
+    // We'll create an HTTP server and attach a WebSocketServer in noServer mode so we can
+    // manually parse the URL and extract query parameters before upgrading.
+    this._server = http.createServer();
+    this._wsServer = new WebSocketServer({ noServer: true });
+
+    this._server.on('upgrade', (request, socket, head) => {
+      // Accept all upgrades on the root path. We parse query string for browserName + launchOptions.
+      this._wsServer.handleUpgrade(request, socket, head, (ws: WebSocket) => {
+        this._wsServer.emit('connection', ws, request);
+      });
+    });
+  }
+
+  public async listenAsync(): Promise<URL> {
+    return await new Promise((resolve) => {
+      // Bind to 'localhost' which resolves to IPv4 (127.0.0.1) or IPv6 (::1)
+      // depending on system configuration and DNS resolution
+      this._server.listen(0, LOCALHOST, () => {
+        const addressInfo: AddressInfo | string | null = this._server.address();
+        if (!addressInfo) {
+          throw new Error('Server address is null - server may not be bound properly');
+        }
+        if (typeof addressInfo === 'string') {
+          throw new Error(`Server address is a pipe/socket path (${addressInfo}), expected an IP address`);
+        }
+        const formattedAddress: string = formatAddress(addressInfo);
+        this._listeningAddress = formattedAddress;
+        // This MUST be printed to terminal so VS Code can auto-port forward
+        this._logger.writeLine(`Local proxy HttpServer listening at ws://${formattedAddress}`);
+        resolve(new URL(`ws://${formattedAddress}`));
+      });
+    });
+  }
+
+  public get endpoint(): string {
+    if (this._listeningAddress === undefined) {
+      throw new Error('HttpServer not listening yet');
+    }
+    return `ws://${this._listeningAddress}`;
+  }
+
+  public get wsServer(): WebSocketServer {
+    return this._wsServer;
+  }
+
+  public [Symbol.dispose](): void {
+    this._wsServer.close();
+    this._server.close();
+  }
+}