@blitzbrowser/blitzbrowser 1.0.0

package/docker-compose.yml

@@ -0,0 +1,23 @@
+services:
+  s3:
+    image: minio/minio:RELEASE.2025-04-22T22-12-26Z
+    ports:
+      - "8001:9001"
+      - "8000:9000"
+    environment:
+      MINIO_ROOT_USER: admin
+      MINIO_ROOT_PASSWORD: admin123
+    command: server --console-address ":9001" /data
+    restart: always
+  blitzbrowser:
+    image: sha256:75beb3e809758401bf3520576083f4a8d8094628cb0d61058be56de7cb1fbe32
+    command: node ./dist/main.js
+    ports:
+      - "9999:9999"
+    environment:
+      S3_ENDPOINT: http://s3:9000
+      S3_ACCESS_KEY_ID: xOyDpwtTUn5P7lkWpbSP
+      S3_SECRET_ACCESS_KEY: XbCcsDW7oAY8bC82ptPOLLny2up4eZjg6MIqCYxP
+      S3_USER_DATA_BUCKET: user-data
+    shm_size: "2gb"
+    restart: always

package/nest-cli.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json.schemastore.org/nest-cli",
+  "collection": "@nestjs/schematics",
+  "sourceRoot": "src",
+  "compilerOptions": {
+    "deleteOutDir": true
+  }
+}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@blitzbrowser/blitzbrowser",
+  "version": "1.0.0",
+  "description": "Deploying, scaling and managing browsers at scale.",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.911.0",
+    "@blitzbrowser/tunnel": "2.0.2",
+    "@nestjs/common": "^10.0.0",
+    "@nestjs/core": "^10.0.0",
+    "@nestjs/platform-express": "^10.0.0",
+    "axios": "^1.12.2",
+    "proxy-chain": "^2.5.9",
+    "puppeteer": "^24.6.0",
+    "reflect-metadata": "^0.2.0",
+    "rxjs": "^7.8.1",
+    "tar": "^7.5.1",
+    "ws": "^8.18.3",
+    "zod": "^4.3.5"
+  },
+  "devDependencies": {
+    "@nestjs/cli": "^10.0.0",
+    "@nestjs/schematics": "^10.0.0",
+    "@nestjs/testing": "^10.0.0",
+    "@types/express": "^4.17.17",
+    "@types/http-proxy": "^1.17.16",
+    "@types/jest": "^29.5.2",
+    "@types/node": "^20.3.1",
+    "@types/supertest": "^6.0.0",
+    "@types/ws": "^8.18.1",
+    "@typescript-eslint/eslint-plugin": "^6.0.0",
+    "@typescript-eslint/parser": "^6.0.0",
+    "eslint": "^8.42.0",
+    "eslint-config-prettier": "^9.0.0",
+    "eslint-plugin-prettier": "^5.0.0",
+    "jest": "^29.5.0",
+    "prettier": "^3.0.0",
+    "source-map-support": "^0.5.21",
+    "supertest": "^6.3.3",
+    "ts-jest": "^29.1.0",
+    "ts-loader": "^9.4.3",
+    "ts-node": "^10.9.1",
+    "tsconfig-paths": "^4.2.0",
+    "typescript": "^5.1.3"
+  },
+  "jest": {
+    "moduleFileExtensions": [
+      "js",
+      "json",
+      "ts"
+    ],
+    "rootDir": "src",
+    "testRegex": ".*\\.spec\\.ts$",
+    "transform": {
+      "^.+\\.(t|j)s$": "ts-jest"
+    },
+    "collectCoverageFrom": [
+      "**/*.(t|j)s"
+    ],
+    "coverageDirectory": "../coverage",
+    "testEnvironment": "node"
+  },
+  "scripts": {
+    "build": "rm -r ./dist && nest build",
+    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
+    "lint": "eslint \"{src,apps,libs,test}/**/*.ts\" --fix"
+  }
+}

package/src/app.module.ts

@@ -0,0 +1,39 @@
+import { Module } from '@nestjs/common';
+import { S3Client } from '@aws-sdk/client-s3';
+import { PoolStatusController } from './controllers/pool-status.controller';
+import { UserDataS3Service, UserDataService } from './services/user-data.service';
+import { BrowserPoolService } from './services/browser-pool.service';
+import { TimezoneService } from './services/timezone.service';
+import { CDPController } from './controllers/cdp.controller';
+
+@Module({
+  imports: [],
+  controllers: [
+    CDPController,
+    PoolStatusController,
+  ],
+  providers: [
+    {
+      provide: S3Client,
+      useFactory: async () => {
+        return new S3Client({
+          region: 'auto',
+          endpoint: process.env.S3_ENDPOINT,
+          credentials: {
+            accessKeyId: process.env.S3_ACCESS_KEY_ID,
+            secretAccessKey: process.env.S3_SECRET_ACCESS_KEY,
+          },
+          forcePathStyle: true,
+        });
+      }
+    },
+    {
+      provide: UserDataService,
+      useClass: UserDataS3Service,
+    },
+
+    BrowserPoolService,
+    TimezoneService
+  ],
+})
+export class AppModule { }

package/src/components/browser-instance.component.ts

@@ -0,0 +1,534 @@
+import { Logger } from '@nestjs/common';
+import { ChildProcess, spawn } from 'child_process';
+import * as ProxyChain from 'proxy-chain';
+import * as EventEmitter from 'events';
+import { WebSocket } from 'ws';
+import { Channel, Tunnel } from '@blitzbrowser/tunnel';
+import { ModuleRef } from '@nestjs/core';
+import { UserDataService } from 'src/services/user-data.service';
+import * as fsPromise from 'fs/promises';
+import { TimezoneService } from 'src/services/timezone.service';
+import { BrowserPoolService, BrowserPoolStatus } from 'src/services/browser-pool.service';
+
+interface Stats {
+  trgRxBytes: number;
+  trgTxBytes: number;
+}
+
+class PortPool {
+
+  #next_port_to_claim = 13000;
+
+  readonly #available_ports: number[] = [];
+
+  constructor(starting_port: number) {
+    this.#next_port_to_claim = starting_port;
+  }
+
+  getAvailablePort() {
+    if (this.#available_ports.length === 0) {
+      return this.#next_port_to_claim++;
+    }
+
+    return this.#available_ports.shift();
+  }
+
+  releasePort(port: number) {
+    if (typeof port !== 'number') {
+      return;
+    }
+
+    this.#available_ports.push(port);
+  }
+
+}
+
+export interface BrowserInstanceEvents {
+  cdp_terminated: [];
+  terminated: [];
+}
+
+interface ConnectionOptions {
+  timezone?: string;
+  proxy_url?: string;
+  user_data_id?: string;
+  user_data_read_only?: boolean;
+}
+
+/**
+ * Connection Options to use to launch the browser instance
+ */
+export interface ConnectionOptionsEvent {
+  type: 'CONNECTION_OPTIONS';
+  options: ConnectionOptions;
+}
+
+/**
+ * Request to terminate the CDP.
+ */
+interface CDPCloseEvent {
+  type: 'CDP_CLOSE';
+}
+
+/**
+ * CDP connection is terminated.
+ */
+interface CDPTerminatedEvent {
+  type: 'CDP_TERMINATED';
+  status: BrowserInstanceStatus;
+}
+
+/**
+ * Browser instance status update
+ */
+interface BrowserInstanceStatusEvent {
+  type: 'BROWSER_INSTANCE_STATUS';
+  status: BrowserInstanceStatus;
+}
+
+interface BrowserInstanceRequestEvent {
+  type: 'BROWSER_INSTANCE_REQUEST';
+  url: string;
+  bytes_downloaded: number;
+  bytes_uploaded: number;
+  created_at: string;
+}
+
+type BrowserInstanceEvent = ConnectionOptionsEvent | CDPCloseEvent | CDPTerminatedEvent | BrowserInstanceStatusEvent | BrowserInstanceRequestEvent;
+
+export interface BrowserInstanceStatus {
+  browser_pool: BrowserPoolStatus;
+
+  // Order of events that should happen in happy path
+  connected_at: string | undefined;
+  preparation_tasks_started_at: string | undefined;
+  browser_process_launching_at: string | undefined;
+  browser_process_launched_at: string | undefined;
+  browser_process_cdp_connected_at: string | undefined;
+  browser_process_cdp_terminated_at: string | undefined;
+  completion_tasks_started_at: string | undefined;
+
+  // Can happen anytime
+  cdp_close_event_at: string | undefined;
+}
+
+export class BrowserInstance extends EventEmitter<BrowserInstanceEvents> {
+
+  static readonly CDP_CHANNEL_ID = 2;
+  static readonly EVENT_CHANNEL_ID = 3;
+
+  static #CDP_PORT_POOL = new PortPool(13000);
+
+  readonly #logger: Logger;
+
+  readonly #browser_pool_service: BrowserPoolService;
+
+  #browser_instance_process: ChildProcess;
+
+  #proxy_server: ProxyChain.Server;
+
+  #cdp_websocket: WebSocket;
+
+  #connected_at: string | undefined;
+  #preparation_tasks_started_at: string | undefined;
+  #browser_process_launching_at: string | undefined;
+  #browser_process_launched_at: string | undefined;
+  #browser_process_cdp_connected_at: string | undefined;
+  #browser_process_cdp_terminated_at: string | undefined;
+  #completion_tasks_started_at: string | undefined;
+  #cdp_close_event_at: string | undefined;
+
+  readonly #user_data_folder: string;
+
+  #connection_options: ConnectionOptions | undefined;
+
+  #tunnel: Tunnel;
+  #event_channel: Channel;
+  #cdp_channel: Channel;
+
+  #timezone: string;
+  #cdp_port: number;
+
+  constructor(
+    readonly id: string,
+    readonly module_ref: ModuleRef
+  ) {
+    super();
+    this.#browser_pool_service = this.module_ref.get(BrowserPoolService);
+    this.#logger = new Logger(`${BrowserInstance.name}|${id}`);
+    this.#user_data_folder = `/home/pptruser/user-data/${id}`;
+  }
+
+  get in_use() {
+    return typeof this.#connected_at === 'string';
+  }
+
+  get cdp_terminated() {
+    return typeof this.#browser_process_cdp_terminated_at === 'string';
+  }
+
+  connectTunnel(tunnel: Tunnel) {
+    if (this.in_use) {
+      throw new Error(`Browser instance ${this.id} is already in use.`);
+    }
+
+    this.#connected_at = new Date().toISOString();
+    this.#tunnel = tunnel;
+
+    this.#tunnel.on('closed', () => {
+      this.#logger.log('Tunnel closed');
+      this.close();
+    })
+
+    this.#logger.log('Connecting tunnel.');
+
+    this.#event_channel = this.#tunnel.createChannel(BrowserInstance.EVENT_CHANNEL_ID, async (data) => {
+      const event: BrowserInstanceEvent = JSON.parse(data.toString('utf8'));
+
+      switch (event.type) {
+        case 'CONNECTION_OPTIONS':
+          this.#connection_options = event.options;
+          this.#startPreparationTasks();
+          break;
+        case 'CDP_CLOSE':
+          this.#cdp_close_event_at = new Date().toISOString();
+          this.#logger.log('Received CDP Close event');
+          this.close();
+          break;
+      }
+    });
+
+    this.#sendBrowserInstanceStatus();
+
+    this.once('cdp_terminated', () => {
+      this.#sendBrowserInstanceStatus();
+      this.#event_channel.send(JSON.stringify({ type: 'CDP_TERMINATED', status: this.status } satisfies CDPTerminatedEvent));
+      this.#logger.log('CDP terminated, will now close.')
+      this.close();
+    });
+
+    this.once('terminated', () => {
+      // Release after terminated. We need to make sure the browser process is killed before reusing the port. Preventing collision.
+      BrowserInstance.#CDP_PORT_POOL.releasePort(this.#cdp_port);
+      this.#logger.log('Released CDP port');
+
+      this.#sendBrowserInstanceStatus();
+      this.#tunnel.close();
+
+      this.#logger.log('Closed tunnel.');
+    });
+  }
+
+  async #startPreparationTasks() {
+    try {
+      this.#preparation_tasks_started_at = new Date().toISOString();
+
+      this.#logger.log('Starting preparation tasks');
+
+      await fsPromise.mkdir(this.#user_data_folder, { recursive: true });
+
+      this.#cdp_port = BrowserInstance.#CDP_PORT_POOL.getAvailablePort();
+
+      await Promise.all([
+        this.#startProxyServer(),
+        this.#updateTimezone(),
+        (async () => {
+          if (this.#connection_options?.user_data_id) {
+            await this.#downloadUserData();
+          }
+        })()
+      ]);
+
+      await this.#launchProcess();
+
+      this.#sendBrowserInstanceStatus();
+    } catch (e) {
+      this.#logger.error('Error while doing preparation tasks', e?.stack || e);
+      this.close();
+    }
+  }
+
+  async #downloadUserData() {
+    if (!this.#connection_options.user_data_id) {
+      return;
+    }
+
+    await this.module_ref.get(UserDataService).downloadUserData(
+      this.#connection_options.user_data_id,
+      this.#user_data_folder
+    );
+  }
+
+  readonly #proxy_connections: { [connection_id: number]: { url: string; } } = {};
+
+  async #startProxyServer() {
+    if (this.#proxy_server) {
+      return;
+    }
+
+    return new Promise((res, rej) => {
+      this.#proxy_server = new ProxyChain.Server({
+        port: 0,
+        host: '127.0.0.1',
+        verbose: false,
+        prepareRequestFunction: async ({ request, connectionId }) => {
+          this.#proxy_connections[connectionId] = { url: request.url };
+
+          if (!this.in_use || !this.#connection_options?.proxy_url) {
+            return {};
+          }
+
+          return {
+            upstreamProxyUrl: this.#connection_options.proxy_url
+          };
+        },
+      });
+
+      this.#proxy_server.listen((err) => {
+        if (err) {
+          rej(err);
+          return;
+        }
+
+        this.#proxy_server.on('connectionClosed', ({ connectionId, stats }: { connectionId: number; stats: Stats }) => {
+          if (this.#event_channel) {
+            const proxy_connection = this.#proxy_connections[connectionId];
+
+            if (proxy_connection) {
+              this.#event_channel.send(JSON.stringify({
+                type: 'BROWSER_INSTANCE_REQUEST',
+                url: proxy_connection.url,
+                bytes_downloaded: stats.trgRxBytes,
+                bytes_uploaded: stats.trgTxBytes,
+                created_at: new Date().toISOString()
+              } satisfies BrowserInstanceRequestEvent));
+            }
+          }
+
+          delete this.#proxy_connections[connectionId];
+        });
+
+        res(undefined);
+      });
+    });
+  }
+
+  async #updateTimezone() {
+    if (this.#connection_options?.timezone) {
+      this.#timezone = this.#connection_options.timezone;
+    } else if (this.#connection_options?.proxy_url) {
+      this.#timezone = await this.module_ref.get(TimezoneService).getProxyTimezone(this.#connection_options.proxy_url);
+    } else {
+      this.#timezone = await this.module_ref.get(TimezoneService).getDefaultTimezone();
+    }
+  }
+
+  async close() {
+    if (typeof this.#completion_tasks_started_at === 'string') {
+      return;
+    }
+
+    this.#completion_tasks_started_at = new Date().toISOString();
+
+    this.#sendBrowserInstanceStatus();
+
+    this.#logger.log('Starting completion tasks.');
+
+    if (this.#isBrowserProcessAlive()) {
+      this.#logger.log('Killing process');
+
+      try {
+        await new Promise((res) => {
+          this.#browser_instance_process.once('exit', () => {
+            res(undefined);
+          });
+
+          this.#browser_instance_process.kill();
+        });
+      } catch (e) {
+        this.#logger.error('Error while killing process', e?.stack);
+      }
+    } else {
+      this.#logger.log('Process already killed.');
+    }
+
+    if (this.#cdp_websocket) {
+      this.#logger.log('Closing cdp websocket.');
+      this.#cdp_websocket.close();
+    }
+
+    if (this.#proxy_server) {
+      this.#logger.log('Closing proxy server.');
+      try {
+        await this.#proxy_server.close(true);
+      } catch (e) {
+        this.#logger.error('Error while closing proxy server', e?.stack);
+      }
+    }
+
+    try {
+      await this.#uploadUserData();
+    } catch (e) {
+      this.#logger.error('Error while uploading user data', e?.stack || e);
+    }
+
+    try {
+      this.#logger.log('Deleting user data.');
+      await fsPromise.rm(this.#user_data_folder, { recursive: true, force: true, maxRetries: 3, retryDelay: 250 });
+    } catch (e) {
+      this.#logger.error('Error while deleting user data', e?.stack || e);
+    }
+
+    this.#logger.log('Completion tasks terminated.');
+    this.emit('terminated');
+  }
+
+  async #uploadUserData() {
+    if (!this.#connection_options?.user_data_id || this.#connection_options?.user_data_read_only === true) {
+      return;
+    }
+
+    this.#logger.log('Uploading user data.');
+
+    await this.module_ref.get(UserDataService).uploadUserData(
+      this.#connection_options.user_data_id,
+      this.#user_data_folder
+    );
+  }
+
+  async #launchProcess() {
+    this.#browser_process_launching_at = new Date().toISOString();
+
+    this.#browser_instance_process = spawn(
+      `tini`,
+      ['-s', `--`, `node`, `./dist/components/browser-instance.process.js`],
+      {
+        stdio: ['pipe', 'pipe', 'pipe', 'ipc'],
+        env: {
+          ...process.env,
+          CDP_PORT: `${this.#cdp_port}`,
+          PROXY_SERVER_PORT: `${this.#proxy_server.port}`,
+          USER_DATA_FOLDER: this.#user_data_folder,
+          TZ: this.#timezone
+        }
+      }
+    );
+
+    this.#browser_instance_process.stdout.on('data', (data) => {
+      (data.toString() as string).split('\n').map(s => s.trim()).filter(s => s !== '').forEach(log => {
+        this.#logger.log(`stdout: ${log}`);
+      })
+    });
+    this.#browser_instance_process.stderr.on('data', (data) => {
+      (data.toString() as string).split('\n').map(s => s.trim()).filter(s => s !== '').forEach(log => {
+        this.#logger.error(`stderr: ${log}`);
+      })
+    });
+
+    await new Promise((res, rej) => {
+      this.#browser_instance_process.on('spawn', () => {
+        this.#logger.log('Process spawned');
+        res(undefined);
+      });
+      this.#browser_instance_process.on('error', err => {
+        rej(err);
+      })
+    });
+
+    this.#browser_process_launched_at = new Date().toISOString();
+
+    this.#logger.log('Process launched');
+
+    this.#browser_instance_process.once('exit', (e, i) => {
+      this.#logger.log(`Process exited ${e} ${i}`);
+      this.close();
+    });
+
+    const start = Date.now();
+
+    do {
+      try {
+        const response = await fetch(`http://127.0.0.1:${this.#cdp_port}/json/version`, { signal: AbortSignal.timeout(350) });
+
+        if (response.status !== 200) {
+          continue;
+        }
+
+        const data = await response.json();
+
+        if (!data.webSocketDebuggerUrl) {
+          continue;
+        }
+
+        this.#cdp_websocket = new WebSocket(data.webSocketDebuggerUrl);
+
+        await new Promise((res, rej) => {
+          this.#cdp_websocket.on('error', err => {
+            this.#logger.error('Error with CDP websocket', err?.stack || err);
+            rej(err);
+          })
+
+          this.#cdp_websocket.on('open', () => {
+            this.#browser_process_cdp_connected_at = new Date().toISOString();
+            this.#logger.log('CDP websocket connected');
+            this.#cdp_websocket.on('close', (code, reason) => {
+              this.#browser_process_cdp_terminated_at = new Date().toISOString();
+              this.#logger.log(`CDP Terminated ${code} ${reason.toString()}`);
+              this.emit('cdp_terminated');
+            });
+
+            this.#cdp_channel = this.#tunnel.createChannel(BrowserInstance.CDP_CHANNEL_ID, data => {
+              this.#cdp_websocket.send(data.toString('utf8'), { binary: false });
+            });
+
+            this.#cdp_websocket.on('message', (data) => {
+              this.#cdp_channel.send(data.toString('utf8'));
+            });
+
+            res(undefined);
+          })
+        });
+
+        return;
+      } catch (e) {
+        await new Promise(r => setTimeout(r, 20));
+      }
+    } while (Date.now() - start < 8000); // 8 seconds
+
+    this.#logger.error('CDP websocket failed to connect. Closing.');
+  }
+
+  get status() {
+    return {
+      browser_pool: this.#browser_pool_service.status,
+      connected_at: this.#connected_at,
+      preparation_tasks_started_at: this.#preparation_tasks_started_at,
+      browser_process_launching_at: this.#browser_process_launching_at,
+      browser_process_launched_at: this.#browser_process_launched_at,
+      browser_process_cdp_connected_at: this.#browser_process_cdp_connected_at,
+      browser_process_cdp_terminated_at: this.#browser_process_cdp_terminated_at,
+      completion_tasks_started_at: this.#completion_tasks_started_at,
+      cdp_close_event_at: this.#cdp_close_event_at,
+    } satisfies BrowserInstanceStatus;
+  }
+
+  #sendBrowserInstanceStatus() {
+    if (this.#event_channel) {
+      this.#event_channel.send(JSON.stringify({ type: 'BROWSER_INSTANCE_STATUS', status: this.status } satisfies BrowserInstanceStatusEvent));
+    }
+  }
+
+  #isBrowserProcessAlive() {
+    if (!this.#browser_instance_process) {
+      return false;
+    }
+
+    try {
+      process.kill(this.#browser_instance_process.pid, 0);
+      return true;
+    } catch (e) {
+      return false;
+    }
+  }
+
+}