@browserless.io/browserless 2.3.0 → 2.4.0-beta-3

package/build/types.js

@@ -5,13 +5,15 @@ class Route {
     _debug;
     _metrics;
     _monitoring;
-    constructor(_browserManager, _config, _fileSystem, _debug, _metrics, _monitoring) {
+    _staticSDKDir;
+    constructor(_browserManager, _config, _fileSystem, _debug, _metrics, _monitoring, _staticSDKDir) {
         this._browserManager = _browserManager;
         this._config = _config;
         this._fileSystem = _fileSystem;
         this._debug = _debug;
         this._metrics = _metrics;
         this._monitoring = _monitoring;
+        this._staticSDKDir = _staticSDKDir;
     }
     /**
      * A boolean, or a function that returns a boolean, on
@@ -86,6 +88,13 @@ class Route {
      * @returns Monitor
      */
     monitoring = () => this._monitoring;
+    /**
+     * When running in an SDK environment, this returns the fully-qualified
+     * directory of that static directory. When "null" then no SDK directory
+     * has been set.
+     * @returns {string | null} The full path location of the SDK's static directory
+     */
+    staticSDKDir = () => this._staticSDKDir;
 }
 /**
  * A primitive HTTP-based route that doesn't require a

package/build/webhooks.d.ts

@@ -1,5 +1,7 @@
+/// <reference types="node" />
 import { Config } from '@browserless.io/browserless';
-export declare class WebHooks {
+import { EventEmitter } from 'events';
+export declare class WebHooks extends EventEmitter {
     protected config: Config;
     constructor(config: Config);
     protected callURL(url: string | null): Promise<void | Response> | undefined;
@@ -8,4 +10,13 @@ export declare class WebHooks {
     callRejectAlertURL(): Promise<void | Response> | undefined;
     callTimeoutAlertURL(): Promise<void | Response> | undefined;
     callErrorAlertURL(message: string): void | Promise<void | Response>;
+    /**
+     * Implement any browserless-core-specific shutdown logic here.
+     * Calls the empty-SDK stop method for downstream implementations.
+     */
+    shutdown: () => Promise<void>;
+    /**
+     * Left blank for downstream SDK modules to optionally implement.
+     */
+    stop: () => void;
 }

package/build/webhooks.js

@@ -1,7 +1,9 @@
 import { fetchTimeout, noop } from '@browserless.io/browserless';
-export class WebHooks {
+import { EventEmitter } from 'events';
+export class WebHooks extends EventEmitter {
     config;
     constructor(config) {
+        super();
         this.config = config;
     }
     callURL(url) {
@@ -40,4 +42,15 @@ export class WebHooks {
             return console.error(`Issue calling error hook: "${err}". Did you set a working ERROR_ALERT_URL env variable?`);
         }
     }
+    /**
+     * Implement any browserless-core-specific shutdown logic here.
+     * Calls the empty-SDK stop method for downstream implementations.
+     */
+    shutdown = async () => {
+        await this.stop();
+    };
+    /**
+     * Left blank for downstream SDK modules to optionally implement.
+     */
+    stop = () => { };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserless.io/browserless",
-  "version": "2.3.0",
+  "version": "2.4.0-beta-3",
   "license": "SSPL",
   "description": "The browserless platform",
   "author": "browserless.io",
@@ -57,7 +57,7 @@
     "http-proxy": "^1.18.1",
     "lighthouse": "^11.1.0",
     "micromatch": "^4.0.4",
-    "playwright-core": "^1.42.0",
+    "playwright-core": "^1.42.1",
     "puppeteer-core": "^22.3.0",
     "puppeteer-extra": "^3.3.6",
     "puppeteer-extra-plugin-stealth": "^2.11.2",
@@ -71,10 +71,10 @@
     "@types/http-proxy": "^1.17.14",
     "@types/micromatch": "^4.0.6",
     "@types/mocha": "^10.0.6",
-    "@types/node": "^20.11.22",
+    "@types/node": "^20.11.24",
     "@types/sinon": "^17.0.3",
-    "@typescript-eslint/eslint-plugin": "^7.1.0",
-    "@typescript-eslint/parser": "^7.1.0",
+    "@typescript-eslint/eslint-plugin": "^7.1.1",
+    "@typescript-eslint/parser": "^7.1.1",
     "assert": "^2.0.0",
     "chai": "^5.1.0",
     "cross-env": "^7.0.3",

package/src/browserless.ts

@@ -27,6 +27,7 @@ import {
   printLogo,
   safeParse,
 } from '@browserless.io/browserless';
+import { EventEmitter } from 'events';
 import { readFile } from 'fs/promises';
 import { userInfo } from 'os';
 
@@ -42,7 +43,7 @@ type routeInstances =
   | WebSocketRoute
   | BrowserWebsocketRoute;
 
-export class Browserless {
+export class Browserless extends EventEmitter {
   protected debug: debug.Debugger = createLogger('index');
   protected browserManager: BrowserManager;
   protected config: Config;
@@ -53,6 +54,7 @@ export class Browserless {
   protected router: Router;
   protected token: Token;
   protected webhooks: WebHooks;
+  protected staticSDKDir: string | null = null;
 
   disabledRouteNames: string[] = [];
   webSocketRouteFiles: string[] = [];
@@ -82,6 +84,7 @@ export class Browserless {
     token?: Browserless['token'];
     webhooks?: Browserless['webhooks'];
   } = {}) {
+    super();
     this.config = config || new Config();
     this.metrics = metrics || new Metrics();
     this.token = token || new Token(this.config);
@@ -149,6 +152,10 @@ export class Browserless {
     return this.disabledRouteNames.some((name) => name === route.name);
   }
 
+  public setStaticSDKDir(dir: string) {
+    this.staticSDKDir = dir;
+  }
+
   public disableRoutes(...routeNames: string[]) {
     this.disabledRouteNames.push(...routeNames);
   }
@@ -172,7 +179,18 @@ export class Browserless {
 
   public async stop() {
     clearInterval(this.metricsSaveIntervalID as unknown as number);
-    return Promise.all([this.server?.stop()]);
+    return Promise.all([
+      this.server?.shutdown(),
+      this.browserManager.shutdown(),
+      this.config.shutdown(),
+      this.fileSystem.shutdown(),
+      this.limiter.shutdown(),
+      this.metrics.shutdown(),
+      this.monitoring.shutdown(),
+      this.router.shutdown(),
+      this.token.shutdown(),
+      this.webhooks.shutdown(),
+    ]);
   }
 
   public async start() {
@@ -226,6 +244,7 @@ export class Browserless {
           logger,
           this.metrics,
           this.monitoring,
+          this.staticSDKDir,
         );
 
         if (!this.routeIsDisabled(route)) {
@@ -236,6 +255,7 @@ export class Browserless {
           route.monitoring = () => this.monitoring;
           route.fileSystem = () => this.fileSystem;
           route.debug = () => logger;
+          route.staticSDKDir = () => this.staticSDKDir;
 
           httpRoutes.push(route);
         }
@@ -277,6 +297,7 @@ export class Browserless {
           logger,
           this.metrics,
           this.monitoring,
+          this.staticSDKDir,
         );
 
         if (!this.routeIsDisabled(route)) {
@@ -286,6 +307,7 @@ export class Browserless {
           route.monitoring = () => this.monitoring;
           route.fileSystem = () => this.fileSystem;
           route.debug = () => logger;
+          route.staticSDKDir = () => this.staticSDKDir;
 
           wsRoutes.push(route);
         }

package/src/browsers/chromium.cdp.ts

@@ -5,9 +5,6 @@ import {
   Request,
   ServerError,
   createLogger,
-  encrypt,
-  liveURLSep,
-  makeExternalURL,
   noop,
   once,
 } from '@browserless.io/browserless';
@@ -27,7 +24,6 @@ puppeteerStealth.use(StealthPlugin());
 export class ChromiumCDP extends EventEmitter {
   protected config: Config;
   protected userDataDir: string | null;
-  protected record: boolean;
   protected blockAds: boolean;
   protected running = false;
   protected browser: Browser | null = null;
@@ -38,21 +34,18 @@ export class ChromiumCDP extends EventEmitter {
   protected executablePath = playwright.chromium.executablePath();
 
   constructor({
-    userDataDir,
-    config,
-    record,
     blockAds,
+    config,
+    userDataDir,
   }: {
     blockAds: boolean;
     config: Config;
-    record: boolean;
     userDataDir: ChromiumCDP['userDataDir'];
   }) {
     super();
 
     this.userDataDir = userDataDir;
     this.config = config;
-    this.record = record;
     this.blockAds = blockAds;
     this.debug(`Starting new browser instance`);
   }
@@ -62,135 +55,11 @@ export class ChromiumCDP extends EventEmitter {
     this.removeAllListeners();
   }
 
-  protected setUpEmbeddedAPI = async (
-    page: Page,
-    id: string,
-    record: boolean,
-  ): Promise<void> => {
-    const pageId = this.getPageId(page);
-    const liveUrl = this.makeLiveURL(id, pageId);
-    const embeddedAPI = (pageId: string, liveUrl: string, record: boolean) => {
-      Object.defineProperty(window, 'browserless', {
-        configurable: false,
-        enumerable: false,
-        value: {},
-        writable: false,
-      });
-
-      Object.defineProperties(window.browserless, {
-        liveUrl: {
-          configurable: false,
-          enumerable: false,
-          value: () => liveUrl,
-          writable: false,
-        },
-        pageId: {
-          configurable: false,
-          enumerable: false,
-          value: () => pageId,
-          writable: false,
-        },
-        startRecording: {
-          configurable: false,
-          enumerable: false,
-          value: (params: object) =>
-            new Promise((resolve, reject) => {
-              if (!record) {
-                throw new Error(
-                  `Must connect with a record query-param set to "true" in order to use recording`,
-                );
-              }
-              const start = () =>
-                window.postMessage(
-                  { ...params, id: pageId, type: 'REC_START' },
-                  '*',
-                );
-              const onStart = (event: MessageEvent) => {
-                if (event.data.id !== pageId) return;
-                if (event.data.message === 'REC_STARTED') {
-                  window.removeEventListener('message', onStart);
-                  return resolve(undefined);
-                }
-                if (event.data.message === 'REC_START_FAIL') {
-                  window.removeEventListener('message', onStart);
-                  return reject(new Error(event.data.error));
-                }
-              };
-
-              window.addEventListener('message', onStart);
-
-              return document.readyState == 'complete'
-                ? start()
-                : window.addEventListener('load', start);
-            }),
-          writable: false,
-        },
-        stopRecording: {
-          configurable: false,
-          enumerable: false,
-          value: () =>
-            new Promise((resolve, reject) => {
-              if (!record) {
-                return reject(
-                  new Error(
-                    `Must connect with a record query-param set to "true" in order to use recording`,
-                  ),
-                );
-              }
-              const onStop = (event: MessageEvent) => {
-                if (event.data.id !== pageId) return;
-                if (event.data.message === 'REC_FILE') {
-                  window.removeEventListener('message', onStop);
-                  return resolve(event.data.file);
-                }
-
-                if (event.data.message === 'REC_STOP_FAIL') {
-                  window.removeEventListener('message', onStop);
-                  return reject(new Error(event.data.error));
-                }
-
-                if (event.data.message === 'REC_NOT_STARTED') {
-                  window.removeEventListener('message', onStop);
-                  return reject(
-                    new Error(
-                      `Recording hasn't started, did you forget to start it?`,
-                    ),
-                  );
-                }
-              };
-
-              window.addEventListener('message', onStop);
-              return window.postMessage({ id: pageId, type: 'REC_STOP' }, '*');
-            }),
-          writable: false,
-        },
-      });
-    };
-
-    // Setup the browserless embedded API
-    await Promise.all([
-      page.evaluate(embeddedAPI, pageId, liveUrl, record),
-      page.evaluateOnNewDocument(embeddedAPI, pageId, liveUrl, record),
-    ]).catch((err) =>
-      this.debug(`Error setting up embedded API:`, err.message),
-    );
-  };
-
   public getPageId = (page: Page): string => {
     // @ts-ignore
     return page.target()._targetId;
   };
 
-  public makeLiveURL = (browserId: string, pageId: string) => {
-    const serverAddress = this.config.getExternalAddress();
-    const key = this.config.getAESKey();
-    const path = `${browserId}${liveURLSep}${pageId}`;
-    const encoded = encrypt(path, key);
-    const query = `?id=${encoded}`;
-
-    return makeExternalURL(serverAddress, 'live', query);
-  };
-
   protected onTargetCreated = async (target: Target) => {
     if (target.type() === 'page') {
       const page = await target.page().catch((e) => {
@@ -219,8 +88,6 @@ export class ChromiumCDP extends EventEmitter {
             }
           });
         }
-        const browserId = this.wsEndpoint()?.split('/').pop() as string;
-        await this.setUpEmbeddedAPI(page, browserId, this.record);
         this.emit('newPage', page);
       }
     }
@@ -268,33 +135,19 @@ export class ChromiumCDP extends EventEmitter {
       executablePath: this.executablePath,
     };
 
-    if (this.record || this.blockAds) {
-      const requiredExtensionArgs: string[] = [];
+    if (this.blockAds) {
       // Necessary to load extensions
       finalOptions.headless = false;
 
-      if (this.record) {
-        finalOptions.ignoreDefaultArgs = ['--enable-automation'];
-        requiredExtensionArgs.push(
-          '--enable-usermedia-screen-capturing',
-          '--enable-blink-features=GetUserMedia',
-          '--allow-http-screen-capture',
-          '--auto-select-desktop-capture-source=browserless-screencast',
-          '--disable-infobars',
-        );
-      }
-
-      const loadExtensionPaths: string = [
-        ...(this.record
-          ? [path.join(__dirname, '..', '..', 'extensions', 'screencast')]
-          : []),
-        ...(this.blockAds
-          ? [path.join(__dirname, '..', '..', 'extensions', 'ublock')]
-          : []),
-      ].join(',');
+      const loadExtensionPaths: string = path.join(
+        __dirname,
+        '..',
+        '..',
+        'extensions',
+        'ublock',
+      );
 
       finalOptions.args.push(
-        ...requiredExtensionArgs,
         '--load-extension=' + loadExtensionPaths,
         '--disable-extensions-except=' + loadExtensionPaths,
       );

package/src/browsers/chromium.playwright.ts

@@ -13,7 +13,6 @@ import httpProxy from 'http-proxy';
 export class ChromiumPlaywright extends EventEmitter {
   protected config: Config;
   protected userDataDir: string | null;
-  protected record: boolean;
   protected running = false;
   protected proxy = httpProxy.createProxyServer();
   protected browser: playwright.BrowserServer | null = null;
@@ -24,17 +23,14 @@ export class ChromiumPlaywright extends EventEmitter {
   constructor({
     config,
     userDataDir,
-    record,
   }: {
     config: Config;
-    record: boolean;
     userDataDir: ChromiumPlaywright['userDataDir'];
   }) {
     super();
 
     this.userDataDir = userDataDir;
     this.config = config;
-    this.record = record;
 
     this.debug(`Starting new browser instance`);
   }
@@ -82,10 +78,6 @@ export class ChromiumPlaywright extends EventEmitter {
   ): Promise<playwright.BrowserServer> => {
     this.debug(`Launching Playwright Handler`);
 
-    if (this.record) {
-      throw new ServerError(`Recording is not yet available with this browser`);
-    }
-
     this.browser = await playwright.chromium.launchServer({
       ...options,
       args: [

package/src/browsers/firefox.playwright.ts

@@ -13,7 +13,6 @@ import httpProxy from 'http-proxy';
 export class FirefoxPlaywright extends EventEmitter {
   protected config: Config;
   protected userDataDir: string | null;
-  protected record: boolean;
   protected running = false;
   protected proxy = httpProxy.createProxyServer();
   protected browser: playwright.BrowserServer | null = null;
@@ -23,17 +22,14 @@ export class FirefoxPlaywright extends EventEmitter {
   constructor({
     config,
     userDataDir,
-    record,
   }: {
     config: Config;
-    record: boolean;
     userDataDir: FirefoxPlaywright['userDataDir'];
   }) {
     super();
 
     this.userDataDir = userDataDir;
     this.config = config;
-    this.record = record;
 
     this.debug(`Starting new browser instance`);
   }
@@ -73,10 +69,6 @@ export class FirefoxPlaywright extends EventEmitter {
   public launch = async (
     options: BrowserServerOptions = {},
   ): Promise<playwright.BrowserServer> => {
-    if (this.record) {
-      throw new ServerError(`Recording is not yet available with this browser`);
-    }
-
     this.debug(`Launching Playwright Handler`);
 
     this.browser = await playwright.firefox.launchServer({

package/src/browsers/index.ts

@@ -84,7 +84,6 @@ export class BrowserManager {
     const browser = new Browser({
       blockAds: false,
       config: this.config,
-      record: false,
       userDataDir: null,
     });
     await browser.launch();
@@ -122,7 +121,6 @@ export class BrowserManager {
     const browser = new Browser({
       blockAds: false,
       config: this.config,
-      record: false,
       userDataDir: null,
     });
     await browser.launch();
@@ -322,7 +320,6 @@ export class BrowserManager {
     router: BrowserHTTPRoute | BrowserWebsocketRoute,
   ): Promise<BrowserInstance> => {
     const { browser: Browser } = router;
-    const record = parseBooleanParam(req.parsed.searchParams, 'record', false);
     const blockAds = parseBooleanParam(
       req.parsed.searchParams,
       'blockAds',
@@ -446,7 +443,6 @@ export class BrowserManager {
     const browser = new Browser({
       blockAds,
       config: this.config,
-      record,
       userDataDir,
     });
 
@@ -477,7 +473,7 @@ export class BrowserManager {
     return browser;
   };
 
-  public stop = async (): Promise<void> => {
+  public shutdown = async (): Promise<void> => {
     this.debug(`Closing down browser instances`);
     const sessions = Array.from(this.browsers);
     await Promise.all(sessions.map(([b]) => b.close()));
@@ -486,7 +482,12 @@ export class BrowserManager {
     this.timers.forEach((t) => clearTimeout(t));
     this.browsers = new Map();
     this.timers = new Map();
-
+    await this.stop();
     this.debug(`Shutdown complete`);
   };
+
+  /**
+   * Left blank for downstream SDK modules to optionally implement.
+   */
+  public stop = () => {};
 }

package/src/browsers/webkit.playwright.ts

@@ -13,7 +13,6 @@ import httpProxy from 'http-proxy';
 export class WebkitPlaywright extends EventEmitter {
   protected config: Config;
   protected userDataDir: string | null;
-  protected record: boolean;
   protected running = false;
   protected proxy = httpProxy.createProxyServer();
   protected browser: playwright.BrowserServer | null = null;
@@ -23,17 +22,14 @@ export class WebkitPlaywright extends EventEmitter {
   constructor({
     config,
     userDataDir,
-    record,
   }: {
     config: Config;
-    record: boolean;
     userDataDir: WebkitPlaywright['userDataDir'];
   }) {
     super();
 
     this.userDataDir = userDataDir;
     this.config = config;
-    this.record = record;
 
     this.debug(`Starting new browser instance`);
   }
@@ -73,10 +69,6 @@ export class WebkitPlaywright extends EventEmitter {
   public launch = async (
     options: BrowserServerOptions = {},
   ): Promise<playwright.BrowserServer> => {
-    if (this.record) {
-      throw new ServerError(`Recording is not yet available with this browser`);
-    }
-
     this.debug(`Launching Playwright Handler`);
 
     this.browser = await playwright.webkit.launchServer({

package/src/config.ts

@@ -441,4 +441,17 @@ export class Config extends EventEmitter {
     'Access-Control-Allow-Origin': this.corsOrigin,
     'Access-Control-Max-Age': this.corsMaxAge,
   });
+
+  /**
+   * Implement any browserless-core-specific shutdown logic here.
+   * Calls the empty-SDK stop method for downstream implementations.
+   */
+  public shutdown = async () => {
+    await this.stop();
+  };
+
+  /**
+   * Left blank for downstream SDK modules to optionally implement.
+   */
+  public stop = () => {};
 }

package/src/constants.ts

@@ -1,5 +1,4 @@
 export const encryptionAlgo = 'aes-192-cbc';
 export const encryptionSep = '.';
-export const liveURLSep = ':';
 export const keyLength = 24;
 export const BLESS_PAGE_IDENTIFIER = 'BLESS';

package/src/file-system.ts

@@ -5,13 +5,15 @@ import {
   encrypt,
 } from '@browserless.io/browserless';
 import { readFile, writeFile } from 'fs/promises';
+import { EventEmitter } from 'events';
 
-export class FileSystem {
+export class FileSystem extends EventEmitter {
   protected fsMap: Map<string, string[]> = new Map();
   protected currentAESKey: Buffer;
   protected log = createLogger('file-system');
 
   constructor(protected config: Config) {
+    super();
     this.currentAESKey = config.getAESKey();
     this.config.on('token', this.handleTokenChange);
   }
@@ -79,4 +81,17 @@ export class FileSystem {
 
     return splitContents;
   };
+
+  /**
+   * Implement any browserless-core-specific shutdown logic here.
+   * Calls the empty-SDK stop method for downstream implementations.
+   */
+  public shutdown = async () => {
+    await this.stop();
+  };
+
+  /**
+   * Left blank for downstream SDK modules to optionally implement.
+   */
+  public stop = () => {};
 }

package/src/http.ts

@@ -161,14 +161,6 @@ export interface SystemQueryParameters {
    */
   launch?: CDPLaunchOptions | BrowserServerOptions | string;
 
-  /**
-   * Whether or nor to record the session. The browser will run
-   * in "head-full" mode, and recording is started and closed
-   * via the embedded browserless API. Please refer to the "Recording"
-   * section in the live documentation site for more details.
-   */
-  record?: boolean;
-
   /**
    * Override the system-level timeout for this request.
    * Accepts a value in milliseconds.