@rushstack/playwright-browser-tunnel 0.3.0 → 0.3.2

package/src/tunneledBrowserConnection/ITunneledBrowser.ts

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

package/src/tunneledBrowserConnection/ITunneledBrowserConnection.ts

@@ -1,37 +0,0 @@
-// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
-// See LICENSE in the project root for license information.
-
-import type { LaunchOptions } from 'playwright-core';
-
-import type { BrowserName } from '../PlaywrightBrowserTunnel';
-
-export interface IHandshake {
-  action: 'handshake';
-  browserName: BrowserName;
-  launchOptions: LaunchOptions;
-  playwrightVersion: string;
-}
-
-export interface IHandshakeAck {
-  action: 'handshakeAck';
-}
-
-/**
- * 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>;
-}

package/src/tunneledBrowserConnection/TunneledBrowser.ts

@@ -1,52 +0,0 @@
-// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
-// See LICENSE in the project root for license information.
-
-import type { Browser, LaunchOptions } from 'playwright-core';
-import playwright from 'playwright-core';
-
-import type { ITerminal } from '@rushstack/terminal';
-import { ConsoleTerminalProvider, Terminal } from '@rushstack/terminal';
-
-import type { BrowserName } from '../PlaywrightBrowserTunnel';
-import { DEFAULT_LISTEN_PORT } from './constants';
-import type { IDisposableTunneledBrowser } from './ITunneledBrowser';
-import type { IDisposableTunneledBrowserConnection } from './ITunneledBrowserConnection';
-import { tunneledBrowserConnection } from './TunneledBrowserConnection';
-
-/**
- * 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/tunneledBrowserConnection/TunneledBrowserConnection.ts

@@ -1,232 +0,0 @@
-// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
-// See LICENSE in the project root for license information.
-
-import type { LaunchOptions } from 'playwright-core';
-import playwrightPackageJson from 'playwright-core/package.json';
-import type { RawData } from 'ws';
-import { WebSocket, WebSocketServer } from 'ws';
-
-import type { ITerminal } from '@rushstack/terminal';
-
-import { HttpServer } from '../HttpServer';
-import type { BrowserName } from '../PlaywrightBrowserTunnel';
-import {
-  getNormalizedErrorString,
-  getWebSocketCloseReason,
-  getWebSocketReadyStateString,
-  WebSocketCloseCode
-} from '../utilities';
-import type {
-  IDisposableTunneledBrowserConnection,
-  IHandshake,
-  IHandshakeAck
-} from './ITunneledBrowserConnection';
-import { DEFAULT_LISTEN_PORT, SUPPORTED_BROWSER_NAMES } from './constants';
-
-const { version: playwrightVersion } = playwrightPackageJson;
-
-/**
- * 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(WebSocketCloseCode.PROTOCOL_ERROR, 'Invalid handshake ack');
-              return;
-            }
-          } catch (e) {
-            logger.writeErrorLine(`Failed parsing handshake ack: ${e}`);
-            ws.close(WebSocketCloseCode.PROTOCOL_ERROR, 'Failed parsing handshake');
-            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', (code: number, reason: Buffer) => {
-        const reasonStr: string = reason.toString() || 'no reason provided';
-        const codeDescription: string = getWebSocketCloseReason(code);
-        logger.writeDebugLine(
-          `Remote websocket closed - code: ${code} (${codeDescription}), reason: ${reasonStr}`
-        );
-        logger.writeDebugLine(
-          `  Connection state at close: handshakeSent=${handshakeSent}, handshakeAck=${handshakeAck}`
-        );
-        logger.writeDebugLine(`  Buffered messages pending: ${bufferedLocalMessages.length}`);
-      });
-      ws.on('error', (err: Error) => {
-        logger.writeErrorLine(`Remote websocket error: ${getNormalizedErrorString(err)}`);
-        logger.writeErrorLine(`  Socket readyState: ${getWebSocketReadyStateString(ws.readyState)}`);
-      });
-    });
-
-    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(WebSocketCloseCode.PROTOCOL_ERROR, 'Missing browser param');
-        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', (code: number, reason: Buffer) => {
-        const reasonStr: string = reason.toString() || 'no reason provided';
-        const codeDescription: string = getWebSocketCloseReason(code);
-        logger.writeDebugLine(
-          `Local client websocket closed - code: ${code} (${codeDescription}), reason: ${reasonStr}`
-        );
-        logger.writeDebugLine(
-          `  Remote socket state: ${remoteSocket ? getWebSocketReadyStateString(remoteSocket.readyState) : 'undefined'}`
-        );
-        logger.writeDebugLine(`  handshakeAck: ${handshakeAck}`);
-      });
-      localWs.on('error', (err: Error) => {
-        logger.writeErrorLine(`Local client websocket error: ${getNormalizedErrorString(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();
-        });
-      })
-    });
-  });
-}

package/src/tunneledBrowserConnection/constants.ts

@@ -1,5 +0,0 @@
-// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
-// See LICENSE in the project root for license information.
-
-export const SUPPORTED_BROWSER_NAMES: Set<string> = new Set(['chromium', 'firefox', 'webkit']);
-export const DEFAULT_LISTEN_PORT: number = 56767;

package/src/tunneledBrowserConnection/index.ts

@@ -1,8 +0,0 @@
-// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
-// See LICENSE in the project root for license information.
-
-export { createTunneledBrowserAsync } from './TunneledBrowser';
-export { tunneledBrowserConnection } from './TunneledBrowserConnection';
-
-export type { IDisposableTunneledBrowser } from './ITunneledBrowser';
-export type { IDisposableTunneledBrowserConnection } from './ITunneledBrowserConnection';

package/src/utilities.ts

@@ -1,136 +0,0 @@
-// 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 Local Browser Server extension is installed.
- * @beta
- */
-export const EXTENSION_INSTALLED_FILENAME: string =
-  '.playwright-local-browser-server-extension-installed.txt';
-
-/**
- * Helper to determine if the Playwright Local Browser Server extension is installed. This checks 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-local-browser-server-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);
-}
-
-/**
- * WebSocket close codes as defined by RFC 6455.
- * @see {@link https://datatracker.ietf.org/doc/html/rfc6455#section-11.7}
- * @beta
- */
-export const WebSocketCloseCode: {
-  /** Normal closure; the connection successfully completed. */
-  readonly NORMAL_CLOSURE: 1000;
-  /** Endpoint is going away (e.g., server shutting down, browser navigating away). */
-  readonly GOING_AWAY: 1001;
-  /** Protocol error encountered. */
-  readonly PROTOCOL_ERROR: 1002;
-  /** Received data type that cannot be accepted (e.g., text-only endpoint received binary). */
-  readonly UNSUPPORTED_DATA: 1003;
-  /** No status code was provided even though one was expected. */
-  readonly NO_STATUS_RECEIVED: 1005;
-  /** Connection was closed abnormally (e.g., without sending a close frame). */
-  readonly ABNORMAL_CLOSURE: 1006;
-  /** Received message data inconsistent with the message type. */
-  readonly INVALID_PAYLOAD: 1007;
-  /** Received a message that violates policy. */
-  readonly POLICY_VIOLATION: 1008;
-  /** Received a message that is too big to process. */
-  readonly MESSAGE_TOO_BIG: 1009;
-  /** Server encountered an unexpected condition that prevented it from fulfilling the request. */
-  readonly INTERNAL_ERROR: 1011;
-  /** Connection was closed due to TLS handshake failure. */
-  readonly TLS_HANDSHAKE_FAILED: 1015;
-} = {
-  NORMAL_CLOSURE: 1000,
-  GOING_AWAY: 1001,
-  PROTOCOL_ERROR: 1002,
-  UNSUPPORTED_DATA: 1003,
-  NO_STATUS_RECEIVED: 1005,
-  ABNORMAL_CLOSURE: 1006,
-  INVALID_PAYLOAD: 1007,
-  POLICY_VIOLATION: 1008,
-  MESSAGE_TOO_BIG: 1009,
-  INTERNAL_ERROR: 1011,
-  TLS_HANDSHAKE_FAILED: 1015
-};
-
-/**
- * Type for WebSocket close code values.
- * @beta
- */
-export type WebSocketCloseCodeValue = (typeof WebSocketCloseCode)[keyof typeof WebSocketCloseCode];
-
-/**
- * Human-readable descriptions for WebSocket close codes.
- * @beta
- */
-export const WebSocketCloseCodeDescriptions: Record<WebSocketCloseCodeValue, string> = {
-  [WebSocketCloseCode.NORMAL_CLOSURE]: 'Normal Closure',
-  [WebSocketCloseCode.GOING_AWAY]: 'Going Away',
-  [WebSocketCloseCode.PROTOCOL_ERROR]: 'Protocol Error',
-  [WebSocketCloseCode.UNSUPPORTED_DATA]: 'Unsupported Data',
-  [WebSocketCloseCode.NO_STATUS_RECEIVED]: 'No Status Received',
-  [WebSocketCloseCode.ABNORMAL_CLOSURE]: 'Abnormal Closure (connection lost)',
-  [WebSocketCloseCode.INVALID_PAYLOAD]: 'Invalid Payload',
-  [WebSocketCloseCode.POLICY_VIOLATION]: 'Policy Violation',
-  [WebSocketCloseCode.MESSAGE_TOO_BIG]: 'Message Too Big',
-  [WebSocketCloseCode.INTERNAL_ERROR]: 'Internal Error',
-  [WebSocketCloseCode.TLS_HANDSHAKE_FAILED]: 'TLS Handshake Failed'
-};
-
-/**
- * Returns a human-readable description for a WebSocket close code.
- * @beta
- */
-export function getWebSocketCloseReason(code: number): string {
-  return WebSocketCloseCodeDescriptions[code as WebSocketCloseCodeValue] || 'Unknown';
-}
-
-/**
- * Returns a human-readable string for a WebSocket ready state.
- * @beta
- */
-export function getWebSocketReadyStateString(readyState: number): string {
-  switch (readyState) {
-    case 0:
-      return 'CONNECTING';
-    case 1:
-      return 'OPEN';
-    case 2:
-      return 'CLOSING';
-    case 3:
-      return 'CLOSED';
-    default:
-      return `UNKNOWN(${readyState})`;
-  }
-}

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

@@ -1,50 +0,0 @@
-{
-  "cacheVersion": "9.37.0_v22.21.1",
-  "fileVersions": [
-    [
-      "HttpServer.ts",
-      "eb5d3c70d2744adfbd44448fe2fae2b0a6413b15bb338fd31af7ecade290c973_Q57tkjZtaaMkmlD1DBUjScEtgSo="
-    ],
-    [
-      "LaunchOptionsValidator.ts",
-      "36f10ef5bba6f95e0f332c1aab5a344c6e1475f8d35abb30a74143cdfd42a537_Q57tkjZtaaMkmlD1DBUjScEtgSo="
-    ],
-    [
-      "utilities.ts",
-      "f24e93ae9da2ced3e3e5b3d4b7becddcf80ac8678775c673cc80a63045e9a246_Q57tkjZtaaMkmlD1DBUjScEtgSo="
-    ],
-    [
-      "PlaywrightBrowserTunnel.ts",
-      "1bbea2c477cd1510d00e14a14fbec331f491dd2f058e2146671cb08385da8e09_Q57tkjZtaaMkmlD1DBUjScEtgSo="
-    ],
-    [
-      "tunneledBrowserConnection/constants.ts",
-      "869309171fd2db0c9aaeb1003be41243d026b23c1715de8e53afe8b30edd1f39_Q57tkjZtaaMkmlD1DBUjScEtgSo="
-    ],
-    [
-      "tunneledBrowserConnection/ITunneledBrowser.ts",
-      "f69368b63d693a2c39804340262e6f4262c44a3cba1a73ee34084634d44fd4ef_Q57tkjZtaaMkmlD1DBUjScEtgSo="
-    ],
-    [
-      "tunneledBrowserConnection/ITunneledBrowserConnection.ts",
-      "0a38e3d400fbbaa2c2e46c7671791a21a6ca5f64c6e0179cb6763f66fd2be8d3_Q57tkjZtaaMkmlD1DBUjScEtgSo="
-    ],
-    [
-      "tunneledBrowserConnection/TunneledBrowserConnection.ts",
-      "9b61eeb3223a7e24a6cece972a31c4ec06cf8d517b5c686fe24a5708642306b6_Q57tkjZtaaMkmlD1DBUjScEtgSo="
-    ],
-    [
-      "tunneledBrowserConnection/TunneledBrowser.ts",
-      "2b1763d3a9069360f0eaf654d86c9a147e749f51a0622530606519472af1ed61_Q57tkjZtaaMkmlD1DBUjScEtgSo="
-    ],
-    [
-      "tunneledBrowserConnection/index.ts",
-      "7120be95e2c956b5b31ec8dc46a2824b0bf8058f36ea7a43ac60c1ccad23dca2_Q57tkjZtaaMkmlD1DBUjScEtgSo="
-    ],
-    [
-      "index.ts",
-      "24a883b07dbd0c309fa5f83653a48f3ac849200808fbe3872f34b11c99ea1668_Q57tkjZtaaMkmlD1DBUjScEtgSo="
-    ]
-  ],
-  "filesHash": "yJgnU3yxb7-XPq6SpVUP-w"
-}