Merge pull request #14 from J-Hoplin/feat/2.0.4

2.0.6

Author: J-Hoplin

.gitignore

@@ -6,4 +6,5 @@ dist/
 
 .idea
 src/**/*.js
+test.js
 

Readme.md

@@ -23,7 +23,11 @@
 
 ## Fully changed from 2.0.0
 
-The internal implementation is event-based, which significantly improves the stability. In addition, instead of relying on generic-pools to manage the pool, we have solved the problem of third-party dependency and features that were incompatible with generic-pools through our own pooling. However, there are many API changes and some features are currently disabled. If you update to 2.0.0, please be aware of the migration progress and disabled features for the changes.
+The internal implementation is event-based, which significantly improves the stability. In addition, instead of relying
+on generic-pools to manage the pool, we have solved the problem of third-party dependency and features that were
+incompatible with generic-pools through our own pooling. However, there are many API changes and some features are
+currently disabled. If you update to 2.0.0, please be aware of the migration progress and disabled features for the
+changes.
 Also cluster mode client will be provided in near future.
 
 ### API Changes
@@ -33,82 +37,79 @@ After that you can use dispatcher to control pool manager.
 
 **[ Client API ]**
 
-- StartPuppeteerPool
-
+- PuppeteePool
+  - `PuppeteerPool` is singleton class. You can use `PuppeteerPool.start` to initialize pool manager.
+- PuppeteerPool.start
+  - Static Method
+  - Description: Initialize pool manager. You need to call this function to start puppeteer pool. Even if you invoke
+    this function multiple times with differenct arguments, it will return the first initialized instance.
   - Args
-    - concurrencyLevel: number
-      - Number of context level to run tasks concurrently.
+    - concurrencyLevel
+      - Required
+      - number
     - contextMode: ContextMode
-      - ContextMode.SHARED(Default): Each session will share local storage, cookies, etc.
-      - ContextMode.ISOLATED: Each session will have its own local storage, cookies, etc.
-    - options: [Puppeteer LaunchOptions](https://pptr.dev/api/puppeteer.launchoptions)
-    - customConfigPath: string
-      - Optional. If you want to use custom config file, you can pass path to config file.
-  - Returns
-    - dispatcher: TaskDispatcher
-      - Dispatcher instance to control pool manager.
-
-- StopPuppeteerPool
-  - Args
-    - dispatcher: TaskDispatcher
-      - Dispatcher instance returned from StartPuppeteerPool
-
-**[ TaskDispatcher API ]**
-
-- dispatchTask<T>
-
+      - Required
+      - ContextMode.ISOLATED | ContextMode.SHARED
+    - options
+      - Optional
+      - [puppeteer.LaunchOptions](https://pptr.dev/api/puppeteer.launchoptions)
+    - customConfigPath
+      - Optional
+      - string (Default: `puppeteer-pool-config.json` in project root)
+  - Return
+    - `Promise<PuppeteerPool>`
+    - Returns PuppeteerPool Instance.
+- Instance<PuppeteerPool>.stop
+  - Description: Stop pool manager. It will close all sessions and terminate pool manager.
+  - Return
+    - `Promise<void>`
+- Instance<PuppeteerPool>.runTask
+  - Description: Run task in pool manager. It will return result of task.
   - Args
-    - task: RequestedTask<T>
-  - Returns
-    ```typescript
-    {
-      event: EventEmitter,
-      resultListener: Promise<unknown>
-    }
-    ```
-    - event: Check given task's state. You can listen to two event(Node.js Event) task state
-      - RUNNING: Emits when task is running
-      - DONE: Emits when task is done
-    - resultListener: Promise Object for result. resultListener is not callable. You should just await Promise to be resolve.(Same as when 'DONE' event emits)
-
-- getPoolMetrics
-  - Returns
-    ```typescript
-    {
-      memoryUsageValue: number, // Memory Usage
-      memoryUsagePercentage: number, // Memory usage percentage
-      cpuUsage: number, // CPU Usage Percentage
-    };
+    - task
+      - Required
+      - Function
+  - Return
+    - `Promise<any>`
+    - Returns result of task(Same return type with task callback return type)
+- Instance<PuppeteerPool>.getPoolMetrics
+  - Description: Get pool metrics. It will return metrics of pool manager.
+  - Return
+    ```json
+        {
+            memoryUsageValue: (Memory Usage in MegaBytes),
+            memoryUsagePercentage: (Memory Usage with percentage),
+            cpuUsage: (CPU Usage with percentage)
+        }
     ```
 
 ## Simple Demo
 
 ```typescript
-import { ContextMode, StartPuppeteerPool } from '@hoplin/puppeteer-pool';
+import { ContextMode, PuppeteerPool } from '@hoplin/puppeteer-pool';
 
 async function main() {
-  const instance = await StartPuppeteerPool(3, ContextMode.ISOLATED);
+  const poolInstance = await PuppeteerPool.start(5, ContextMode.ISOLATED);
+
   const urls = [
     'https://www.google.com',
     'https://www.bing.com',
     'https://www.yahoo.com',
-    'https://www.duckduckgo.com',
-    'https://www.ask.com',
   ];
-  let taskCounter = 0;
-  for (const url of urls) {
-    const taskId = `TASK_${String(++taskCounter).padStart(3, '0')}`;
-    const { event, resultListener } = await instance.dispatchTask(
-      async (page) => {
-        await page.goto(url);
-        return await page.title();
-      },
-    );
-    const result = await resultListener;
-    console.log(`[${taskId}] Result:`, result);
-    console.log('-'.repeat(50));
-  }
+
+  console.log(await poolInstance.getPoolMetrics());
+
+  const promises = urls.map((url) =>
+    poolInstance.runTask(async (page) => {
+      await page.goto(url);
+      return await page.title();
+    }),
+  );
+
+  const titles = await Promise.all(promises);
+  titles.forEach((title) => console.log(title));
 }
+
 main();
 ```
 
@@ -133,20 +134,21 @@ Default config should be `puppeteer-pool-config.json` in root directory path.
 
 ### Default config setting
 
-If config file are not given or invalid path, manager will use default defined configurations. Or if you want to pass config path, you can pass path to `bootPoolManager` function as parameter.
+If config file are not given or invalid path, manager will use default defined configurations. Or if you want to pass
+config path, you can pass path to `bootPoolManager` function as parameter.
 
-```typescript
+```json
 {
-  session_pool: {
-    width: 1080,
-    height: 1024,
-  },
-  threshold: {
-    activate: true,
-    interval: 5,
-    cpu: 80,
-    memory: 2048,
+  "session_pool": {
+    "width": 1080,
+    "height": 1024
   },
+  "threshold": {
+    "activate": true,
+    "interval": 5,
+    "cpu": 80,
+    "memory": 2048
+  }
 }
 ```
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hoplin/puppeteer-pool",
-  "version": "2.0.3",
+  "version": "2.0.6",
   "main": "dist/index.js",
   "description": "Puppeteer Pool Manager for worker server, process daemon, commands etc...",
   "repository": "https://github.com/J-Hoplin/Puppeteer-Pool.git",

src/client/rest.ts

@@ -1,28 +1,81 @@
 /**
  * APIs for RESTful API mode
  */
-import { ContextMode, TaskDispatcher } from '../pool';
+import { PoolNotInitializedException } from '../error';
+import { TaskDispatcher } from '../pool/dispatcher';
+import { ContextMode } from '../pool/enum';
+import { RequestedTask } from '../types';
 import * as puppeteer from 'puppeteer';
 
-/**
- * Invoke this function to start a new Puppeteer Pool
- */
-export async function StartPuppeteerPool(
-  concurrencyLevel: number,
-  contextMode: ContextMode,
-  options?: puppeteer.LaunchOptions,
-  customConfigPath?: string,
-): Promise<TaskDispatcher> {
-  const instance = new TaskDispatcher();
-  await instance.init(concurrencyLevel, contextMode, options, customConfigPath);
-  return instance;
-}
+export class PuppeteerPool {
+  private static isInitialized = false;
+  private static dispatcherInstance: TaskDispatcher;
+  private static instance: PuppeteerPool;
 
-/**
- * Invoke this function to stop a Puppeteer Pool
- *
- * Please enroll this function in your graceful shutdown process
- */
-export async function StopPuppeteerPool(instance: TaskDispatcher) {
-  await instance.close();
+  /**
+   * Check if the instance is initialized
+   * Throw an error if the instance is not initialized
+   */
+  private checkInstanceInitalized() {
+    if (!PuppeteerPool.isInitialized) {
+      throw new PoolNotInitializedException();
+    }
+  }
+
+  /**
+   * Private constructor to make sure this class is a singleton
+   */
+  private constructor() {}
+
+  /**
+   * Invoke this function to start a new Puppeteer Pool
+   */
+  public static async start(
+    concurrencyLevel: number,
+    contextMode: ContextMode,
+    options?: puppeteer.LaunchOptions,
+    customConfigPath?: string,
+  ) {
+    if (!PuppeteerPool.isInitialized) {
+      // Initialize Task Dispatcher
+      PuppeteerPool.dispatcherInstance = new TaskDispatcher();
+      await PuppeteerPool.dispatcherInstance.init(
+        concurrencyLevel,
+        contextMode,
+        options,
+        customConfigPath,
+      );
+      // Initialize REST Client Instance
+      PuppeteerPool.instance = new PuppeteerPool();
+      // Change state to initialized
+      PuppeteerPool.isInitialized = true;
+    }
+    return PuppeteerPool.instance;
+  }
+
+  /**
+   * Invoke this function to stop a Puppeteer Pool
+   *
+   * Please enroll this function in your graceful shutdown process
+   */
+  public async stop() {
+    this.checkInstanceInitalized();
+    await PuppeteerPool.dispatcherInstance.close();
+  }
+
+  /**
+   * Invoke this function to run a task
+   */
+  public async runTask<T>(task: RequestedTask<T>) {
+    this.checkInstanceInitalized();
+    return await PuppeteerPool.dispatcherInstance.dispatchTask(task);
+  }
+
+  /**
+   * Invoke this function to get pool metrics
+   */
+  public async getPoolMetrics() {
+    this.checkInstanceInitalized();
+    return await PuppeteerPool.dispatcherInstance.getPoolMetrics();
+  }
 }

src/pool/context/context.ts

@@ -36,6 +36,7 @@ export abstract class TaskContext {
     if (this.page) {
       if (this.page.url() !== 'about:blank') {
         // 'about:blank' can't access to local storage
+        // It'll lead to chronium security error if try to access local storage in 'about:blank'
         await this.page.evaluate(() => {
           localStorage.clear();
           sessionStorage.clear();
@@ -73,6 +74,8 @@ export abstract class TaskContext {
           error: e as Error,
         };
       } finally {
+        // Clear resource after task is done
+        // This is to prevent memory leak and to prevent waste of resource
         await this.clearResource();
       }
     }