@rushstack/playwright-browser-tunnel 0.1.0

package/src/tunneledBrowserConnection.ts

@@ -0,0 +1,284 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import playwright from 'playwright-core';
+import type { Browser, LaunchOptions } from 'playwright-core';
+import { WebSocketServer, WebSocket, type RawData } from 'ws';
+import playwrightPackageJson from 'playwright-core/package.json';
+
+import { type ITerminal, Terminal, ConsoleTerminalProvider } from '@rushstack/terminal';
+
+import type { BrowserName } from './PlaywrightBrowserTunnel';
+import { HttpServer } from './HttpServer';
+
+const { version: playwrightVersion } = playwrightPackageJson;
+
+const SUPPORTED_BROWSER_NAMES: Set<string> = new Set(['chromium', 'firefox', 'webkit']);
+
+interface IHandshake {
+  action: 'handshake';
+  browserName: BrowserName;
+  launchOptions: LaunchOptions;
+  playwrightVersion: string;
+}
+
+interface IHandshakeAck {
+  action: 'handshakeAck';
+}
+
+const DEFAULT_LISTEN_PORT: number = 3000;
+
+/**
+ * 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 async function tunneledBrowserConnection(
+  logger: ITerminal,
+  port: number = DEFAULT_LISTEN_PORT
+): Promise<IDisposableTunneledBrowserConnection> {
+  // Server that remote peer (actual browser host) connects to
+  const remoteWsServer: WebSocketServer = new WebSocketServer({ port });
+  // Local HTTP + WebSocket server where the playwright client will connect providing params
+  const httpServer: HttpServer = new HttpServer(logger);
+  await httpServer.listenAsync();
+  logger.writeLine(`Remote WebSocket server listening on ws://localhost:${port}`);
+
+  const localProxyWs: WebSocketServer = httpServer.wsServer;
+  const localProxyWsEndpoint: string = httpServer.endpoint;
+
+  let browserName: BrowserName | undefined;
+  let launchOptions: LaunchOptions | undefined;
+  let remoteSocket: WebSocket | undefined;
+  let handshakeAck: boolean = false;
+  let handshakeSent: boolean = false;
+
+  function maybeSendHandshake(): void {
+    if (!handshakeSent && remoteSocket && browserName && launchOptions) {
+      const handshake: IHandshake = {
+        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: Omit<IHandshake, 'launchOptions'> & {
+        launchOptions: Omit<LaunchOptions, 'headless'>;
+      } = {
+        ...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: Array<RawData> = [];
+
+    remoteWsServer.on('connection', (ws) => {
+      logger.writeLine('Remote websocket connected');
+      remoteSocket = ws;
+      handshakeAck = false;
+      maybeSendHandshake();
+
+      ws.on('message', (message) => {
+        if (!handshakeAck) {
+          try {
+            const receivedHandshake: IHandshakeAck = 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: WebSocket | undefined = remoteSocket;
+            if (activeRemote && activeRemote.readyState === WebSocket.OPEN) {
+              while (bufferedLocalMessages.length > 0) {
+                const m: Buffer | ArrayBuffer | Buffer[] | string | undefined = 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 === 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: string | undefined = request?.url;
+        if (urlString) {
+          const parsed: URL = new URL(urlString, 'http://localhost');
+          logger.writeLine(`Local client connected with query params: ${parsed.searchParams.toString()}`);
+          const bName: string | null = parsed.searchParams.get('browser');
+          if (bName && SUPPORTED_BROWSER_NAMES.has(bName)) {
+            browserName = bName as BrowserName;
+          }
+          const launchOptionsParam: string | null = 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: string = Array.from(SUPPORTED_BROWSER_NAMES).join('|');
+        logger.writeErrorLine(`browser query param required (${supportedBrowsersString})`);
+        localWs.close();
+        return;
+      }
+      if (!launchOptions) {
+        launchOptions = {} as LaunchOptions; // default empty if not provided
+      }
+
+      maybeSendHandshake();
+
+      localWs.on('message', (message) => {
+        if (handshakeAck && remoteSocket?.readyState === 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 {
+          // ignore errors during remote WebSocket server shutdown
+        }
+        try {
+          httpServer[Symbol.dispose]();
+        } catch {
+          // ignore errors during HTTP/WebSocket server shutdown
+        }
+      },
+      // eslint-disable-next-line promise/param-names
+      closePromise: new Promise<void>((resolve2) => {
+        remoteWsServer.once('close', () => {
+          resolve2();
+        });
+      })
+    });
+  });
+}
+
+/**
+ * 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 async function createTunneledBrowserAsync(
+  browserName: BrowserName,
+  launchOptions: LaunchOptions,
+  logger?: ITerminal,
+  port: number = DEFAULT_LISTEN_PORT
+): Promise<IDisposableTunneledBrowser> {
+  // Establish the tunnel first (remoteEndpoint here refers to local proxy endpoint for connect())
+
+  if (!logger) {
+    const terminalProvider: ConsoleTerminalProvider = new ConsoleTerminalProvider();
+    logger = new Terminal(terminalProvider);
+  }
+
+  const connection: IDisposableTunneledBrowserConnection = await tunneledBrowserConnection(logger, port);
+  const { remoteEndpoint } = connection;
+  // Append query params for browser and launchOptions
+  const urlObj: URL = new URL(remoteEndpoint);
+  urlObj.searchParams.set('browser', browserName);
+  urlObj.searchParams.set('launchOptions', JSON.stringify(launchOptions || {}));
+  const connectEndpoint: string = urlObj.toString();
+  const browser: Browser = await playwright[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]();
+    }
+  };
+}

package/src/utilities.ts

@@ -0,0 +1,42 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import { tmpdir } from 'node:os';
+
+import { FileSystem } from '@rushstack/node-core-library';
+
+/**
+ * The filename used to indicate that the Playwright on Codespaces extension is installed.
+ * @beta
+ */
+export const EXTENSION_INSTALLED_FILENAME: string = '.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
+ */
+export async function isExtensionInstalledAsync(): Promise<boolean> {
+  // Read file from os.tempdir() + '/.playwright-codespaces-extension-installed'
+  const tempDir: string = tmpdir();
+
+  const extensionInstalledFilePath: string = `${tempDir}/${EXTENSION_INSTALLED_FILENAME}`;
+  const doesExist: boolean = FileSystem.exists(extensionInstalledFilePath);
+
+  // check if file exists
+  return doesExist;
+}
+
+/**
+ * Normalizes an error to a string for logging purposes.
+ * @beta
+ */
+export function getNormalizedErrorString(error: unknown): string {
+  if (error instanceof Error) {
+    if (error.stack) {
+      return error.stack;
+    }
+    return error.message;
+  }
+  return String(error);
+}

package/temp/build/lint/_eslint-5eVG3S6w.json

@@ -0,0 +1,30 @@
+{
+  "cacheVersion": "9.37.0_v22.21.1",
+  "fileVersions": [
+    [
+      "HttpServer.ts",
+      "eb5d3c70d2744adfbd44448fe2fae2b0a6413b15bb338fd31af7ecade290c973_Q57tkjZtaaMkmlD1DBUjScEtgSo="
+    ],
+    [
+      "LaunchOptionsValidator.ts",
+      "36f10ef5bba6f95e0f332c1aab5a344c6e1475f8d35abb30a74143cdfd42a537_Q57tkjZtaaMkmlD1DBUjScEtgSo="
+    ],
+    [
+      "utilities.ts",
+      "8e9d962306505f79f305b1c7b85af30fc535fbe1de3fc31b795ad0f0ffa16bb0_Q57tkjZtaaMkmlD1DBUjScEtgSo="
+    ],
+    [
+      "PlaywrightBrowserTunnel.ts",
+      "c012ad7961971e4397e70333754dbc3e42cfc40a0df2bbe12cb097dcfa9cc962_Q57tkjZtaaMkmlD1DBUjScEtgSo="
+    ],
+    [
+      "tunneledBrowserConnection.ts",
+      "de7c574ca049c6265814d6f14c63f30cfea09bb73f467e1dfaa0e5555f8b5302_Q57tkjZtaaMkmlD1DBUjScEtgSo="
+    ],
+    [
+      "index.ts",
+      "24a883b07dbd0c309fa5f83653a48f3ac849200808fbe3872f34b11c99ea1668_Q57tkjZtaaMkmlD1DBUjScEtgSo="
+    ]
+  ],
+  "filesHash": "veFIt5t1iWa1vWcPeyJW4Q"
+}

package/temp/build/lint/lint.sarif

@@ -0,0 +1,233 @@
+{
+  "version": "2.1.0",
+  "$schema": "http://json.schemastore.org/sarif-2.1.0-rtm.5",
+  "runs": [
+    {
+      "tool": {
+        "driver": {
+          "name": "ESLint",
+          "informationUri": "https://eslint.org",
+          "version": "9.37.0",
+          "rules": [
+            {
+              "id": "@typescript-eslint/no-explicit-any",
+              "helpUri": "https://typescript-eslint.io/rules/no-explicit-any",
+              "properties": {},
+              "shortDescription": {
+                "text": "Disallow the `any` type"
+              }
+            },
+            {
+              "id": "@typescript-eslint/naming-convention",
+              "helpUri": "https://typescript-eslint.io/rules/naming-convention",
+              "properties": {},
+              "shortDescription": {
+                "text": "Enforce naming conventions for everything across a codebase"
+              }
+            },
+            {
+              "id": "@typescript-eslint/no-unused-vars",
+              "helpUri": "https://typescript-eslint.io/rules/no-unused-vars",
+              "properties": {},
+              "shortDescription": {
+                "text": "Disallow unused variables"
+              }
+            },
+            {
+              "id": "promise/param-names",
+              "helpUri": "https://github.com/eslint-community/eslint-plugin-promise/blob/main/docs/rules/param-names.md",
+              "properties": {},
+              "shortDescription": {
+                "text": "Enforce consistent param names and ordering when creating new promises."
+              }
+            }
+          ]
+        }
+      },
+      "artifacts": [
+        {
+          "location": {
+            "uri": "src/HttpServer.ts"
+          }
+        },
+        {
+          "location": {
+            "uri": "src/LaunchOptionsValidator.ts"
+          }
+        },
+        {
+          "location": {
+            "uri": "src/utilities.ts"
+          }
+        },
+        {
+          "location": {
+            "uri": "src/PlaywrightBrowserTunnel.ts"
+          }
+        },
+        {
+          "location": {
+            "uri": "src/tunneledBrowserConnection.ts"
+          }
+        },
+        {
+          "location": {
+            "uri": "src/index.ts"
+          }
+        }
+      ],
+      "results": [
+        {
+          "level": "warning",
+          "message": {
+            "text": "Unexpected any. Specify a different type."
+          },
+          "locations": [
+            {
+              "physicalLocation": {
+                "artifactLocation": {
+                  "uri": "src/LaunchOptionsValidator.ts",
+                  "index": 1
+                },
+                "region": {
+                  "startLine": 162,
+                  "startColumn": 29,
+                  "endLine": 162,
+                  "endColumn": 32
+                }
+              }
+            }
+          ],
+          "ruleId": "@typescript-eslint/no-explicit-any",
+          "ruleIndex": 0,
+          "suppressions": [
+            {
+              "kind": "inSource",
+              "justification": ""
+            }
+          ]
+        },
+        {
+          "level": "warning",
+          "message": {
+            "text": "Classic Accessor name `status` must have one leading underscore(s)."
+          },
+          "locations": [
+            {
+              "physicalLocation": {
+                "artifactLocation": {
+                  "uri": "src/PlaywrightBrowserTunnel.ts",
+                  "index": 3
+                },
+                "region": {
+                  "startLine": 136,
+                  "startColumn": 15,
+                  "endLine": 136,
+                  "endColumn": 21
+                }
+              }
+            }
+          ],
+          "ruleId": "@typescript-eslint/naming-convention",
+          "ruleIndex": 1,
+          "suppressions": [
+            {
+              "kind": "inSource",
+              "justification": ""
+            }
+          ]
+        },
+        {
+          "level": "warning",
+          "message": {
+            "text": "'headless' is assigned a value but never used."
+          },
+          "locations": [
+            {
+              "physicalLocation": {
+                "artifactLocation": {
+                  "uri": "src/PlaywrightBrowserTunnel.ts",
+                  "index": 3
+                },
+                "region": {
+                  "startLine": 379,
+                  "startColumn": 13,
+                  "endLine": 379,
+                  "endColumn": 21
+                }
+              }
+            }
+          ],
+          "ruleId": "@typescript-eslint/no-unused-vars",
+          "ruleIndex": 2,
+          "suppressions": [
+            {
+              "kind": "inSource",
+              "justification": ""
+            }
+          ]
+        },
+        {
+          "level": "warning",
+          "message": {
+            "text": "'headless' is assigned a value but never used."
+          },
+          "locations": [
+            {
+              "physicalLocation": {
+                "artifactLocation": {
+                  "uri": "src/tunneledBrowserConnection.ts",
+                  "index": 4
+                },
+                "region": {
+                  "startLine": 85,
+                  "startColumn": 15,
+                  "endLine": 85,
+                  "endColumn": 23
+                }
+              }
+            }
+          ],
+          "ruleId": "@typescript-eslint/no-unused-vars",
+          "ruleIndex": 2,
+          "suppressions": [
+            {
+              "kind": "inSource",
+              "justification": ""
+            }
+          ]
+        },
+        {
+          "level": "error",
+          "message": {
+            "text": "Promise constructor parameters must be named to match \"^_?resolve$\""
+          },
+          "locations": [
+            {
+              "physicalLocation": {
+                "artifactLocation": {
+                  "uri": "src/tunneledBrowserConnection.ts",
+                  "index": 4
+                },
+                "region": {
+                  "startLine": 223,
+                  "startColumn": 40,
+                  "endLine": 223,
+                  "endColumn": 48
+                }
+              }
+            }
+          ],
+          "ruleId": "promise/param-names",
+          "ruleIndex": 3,
+          "suppressions": [
+            {
+              "kind": "inSource",
+              "justification": ""
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}