feat: better pool API (#77)

* feat: better pool API

* test: update

* docs: fix typo

Author: Kikobeats

README.md

@@ -475,42 +475,48 @@ const browserless = require('browserless')
 
 **browserless** uses internally a singleton browser instance.
 
-You can use a pool instances using [`@browserless/pool`](https://github.com/Kikobeats/browserless/tree/master/packages/pool) package.
+If you want to keep multiple browsers open, you can use [`@browserless/pool`](https://github.com/Kikobeats/browserless/tree/master/packages/pool) package.
 
 ```js
 const createBrowserless = require('@browserless/pool')
+
 const browserlessPool = createBrowserless({
-  poolOpts: {
-    max: 15,
-    min: 2
-  }
+  max: 2, // max browsers to keep open
+  timeout: 30000 // max time a browser is consiedered fresh
 })
 ```
 
-
-The API is the same than `browserless`. now the constructor is accepting an extra option called `poolOpts`.
-
-This setting is used for initializing the pool properly. You can see what you can specify there at [node-pool#opts](https://github.com/coopernurse/node-pool#createpool).
-
-Also, you can interact with a standalone `browserless` instance of your pool.
+You can still pass specific puppeteer options as second argument:
 
 ```js
-const createBrowserless = require('browserless')
-const browserlessPool = createBrowserless.pool()
+const createBrowserless = require('@browserless/pool')
 
-// get a browserless instance from the pool
-browserlessPool(async browserless => {
-  // get a page from the browser instance
-  const page = await browserless.page()
-  await browserless.goto(page, { url: url.toString() })
-  const html = await page.content()
-  console.log(html)
-  process.exit()
+const browserlessPool = createBrowserless({
+  max: 2, // max browsers to keep open
+  timeout: 30000 // max time a browser is consiedered fresh
+}, {
+  ignoreHTTPSErrors: true,
+  args: [
+    '--disable-gpu',
+    '--single-process',
+    '--no-zygote',
+    '--no-sandbox',
+    '--hide-scrollbars'
+  ]
 })
 ```
 
+After that, the API is the same than **browserless**:
+
+```js
+browserlessPool
+  .screenshot('http://example.com', { device: 'iPhone 6' })
+  .then(buffer => {
+    console.log(`your screenshot is here!`)
+  })
+```
 
-You don't need to think about the acquire/release step: It's done automagically ✨.
+Every time you call the pool, it handles acquire and release a new browser instance from the pool ✨.
 
 ## Packages
 

packages/pool/package.json

@@ -24,6 +24,7 @@
     "threads"
   ],
   "dependencies": {
+    "debug-logfmt": "~1.0.3",
     "generic-pool": "~3.7.1"
   },
   "devDependencies": {

packages/pool/src/create.js

@@ -1,32 +1,59 @@
 'use strict'
 
+const debug = require('debug-logfmt')('browserless:pool')
 const createBrowserless = require('browserless')
 const genericPool = require('generic-pool')
+const assert = require('assert')
 
-module.exports = (opts, launchOpts) => {
-  const factory = {
-    create: async () => ({
-      ...(await createBrowserless(launchOpts))
-    }),
-    destroy: browserless => browserless.browser.close()
-  }
+const poolInfo = pool => ({
+  size: pool.size,
+  available: pool.available,
+  borrowed: pool.borrowed,
+  pending: pool.pending
+})
 
-  const pool = genericPool.createPool(factory, opts)
+const POOL_OPTS = {
+  // should the pool start creating resources, initialize the evictor,
+  // etc once the constructor is called.
+  autostart: true,
+  // minimum number of resources to keep in pool at any given time.
+  // If this is set >= max, the pool will silently set the min to equal.
+  min: 0,
+  // Number of resources to check each eviction run
+  testOnBorrow: true
+}
 
-  return async fn => {
-    let error
-    let result
-    let browserless
+module.exports = (opts, launchOpts) => {
+  assert(opts.timeout, 'opts.timeout is required')
+  assert(opts.max, 'opts.max is required')
 
-    try {
-      browserless = await pool.acquire()
-      result = await fn(browserless)
-    } catch (err) {
-      error = err
+  const factory = {
+    create: () => {
+      const browserless = createBrowserless(launchOpts)
+      browserless.createdAt = Date.now()
+      browserless.lifespan = () => Date.now() - browserless.createdAt
+      debug('create', { createdAt: browserless.createdAt })
+      return browserless
+    },
+    destroy: browserless => {
+      debug('destroy', {
+        createdAt: browserless.createdAt,
+        lifespan: browserless.lifespan()
+      })
+      return browserless.destroy()
+    },
+    validate: browserless => {
+      const lifespan = browserless.lifespan()
+      const isValid = lifespan < opts.timeout
+      debug('validate', { createdAt: browserless.createdAt, lifespan, isValid })
+      return isValid
     }
+  }
+
+  const pool = genericPool.createPool(factory, { ...POOL_OPTS, ...opts })
 
-    if (browserless) await pool.release(browserless)
-    if (error) throw error
-    return result
+  return fn => {
+    debug('acquire browser', poolInfo(pool))
+    return pool.use(fn)
   }
 }

packages/pool/src/index.js

@@ -2,16 +2,10 @@
 
 const createPool = require('./create')
 
-const POOL_OPTS = {
-  max: 15,
-  min: 2
-}
-
-module.exports = ({ opts, ...launchOpts } = {}) => {
-  const poolOpts = { ...POOL_OPTS, ...opts }
-  const pool = createPool(poolOpts, launchOpts)
+module.exports = (opts, launchOpts) => {
+  const pool = createPool(opts, launchOpts)
   ;['html', 'text', 'pdf', 'screenshot'].forEach(key => {
-    pool[key] = (url, opts) => pool(browserless => browserless[key](url, opts))
+    pool[key] = (...args) => pool(browserless => browserless[key](...args))
   })
   return pool
 }

packages/pool/test/index.js

@@ -1 +1,2 @@
-require('@browserless/test')(require('../src'))
+const createPool = require('../src')
+require('@browserless/test')(() => createPool({ max: 2, timeout: 30000 }))