@browserless/function 10.12.15 → 12.0.0

package/README.md

@@ -37,9 +37,21 @@ The `@browserless/function` package allows you to:
 
 ### Usage
 
+First, create a function instance by calling the factory:
+
+```js
+const createFunction = require('@browserless/function')()
+```
+
+You can optionally pass a `tmpdir` for the sandbox working directory:
+
 ```js
-const createFunction = require('@browserless/function')
+const createFunction = require('@browserless/function')({ tmpdir: '/tmp/functions' })
+```
+
+Then use it to run arbitrary JavaScript:
 
+```js
 // Simple function without page access
 const code = ({ query }) => query.value * 2
 
@@ -55,7 +67,7 @@ console.log(result)
 When your code references `page`, browserless automatically provides access to the Puppeteer page:
 
 ```js
-const createFunction = require('@browserless/function')
+const createFunction = require('@browserless/function')()
 
 // Function with page access
 const code = async ({ page }) => {
@@ -89,9 +101,34 @@ The function returns a structured result:
 |----------|-------------|
 | `isFulfilled` | `true` if execution succeeded, `false` if error |
 | `value` | Return value (success) or error object (failure) |
-| `profiling` | Execution timing and performance data |
+| `profiling` | Execution timing and resource usage (see below) |
 | `logging` | Captured console output (`log`, `warn`, `error`, etc.) |
 
+#### Profiling
+
+The `profiling` object contains phased timing and resource data:
+
+| Property | Description |
+|----------|-------------|
+| `phases.compile` | Time to compile the sandbox script (ms) |
+| `phases.spawn` | Time to spawn the child process (ms) |
+| `phases.run` | Time executing the user function (ms) |
+| `phases.total` | Total wall-clock time (ms) |
+| `cpu` | CPU time consumed (ms) |
+| `memory` | Peak memory usage (bytes) |
+
+### Teardown
+
+Call `.teardown()` on the factory instance to clean up sandbox resources:
+
+```js
+const createFunction = require('@browserless/function')({ tmpdir: '/tmp/functions' })
+
+// ... use createFunction ...
+
+await createFunction.teardown()
+```
+
 ### Options
 
 ```js
@@ -121,7 +158,7 @@ const myFn = createFunction(code, {
 #### Interact with page elements
 
 ```js
-const createFunction = require('@browserless/function')
+const createFunction = require('@browserless/function')()
 
 const code = async ({ page }) => {
   await page.waitForSelector('button.submit')
@@ -138,7 +175,7 @@ const result = await clickAndGetTitle('https://example.com')
 #### Inject external scripts
 
 ```js
-const createFunction = require('@browserless/function')
+const createFunction = require('@browserless/function')()
 
 const code = ({ page }) => page.evaluate('jQuery.fn.jquery')
 
@@ -155,7 +192,7 @@ const result = await getjQueryVersion('https://example.com')
 #### Use npm modules in sandbox
 
 ```js
-const createFunction = require('@browserless/function')
+const createFunction = require('@browserless/function')()
 
 const code = async ({ page }) => {
   const _ = require('lodash')
@@ -170,7 +207,7 @@ const result = await countWords('https://example.com')
 #### Handle errors
 
 ```js
-const createFunction = require('@browserless/function')
+const createFunction = require('@browserless/function')()
 
 const code = () => {
   throw new Error('Something went wrong')
@@ -192,7 +229,7 @@ This is an **extended functionality package** for advanced use cases. It makes t
 | Package | Purpose |
 |---------|---------|
 | `@browserless/errors` | Error normalization and typed errors |
-| `isolated-function` | Secure VM sandbox execution |
+| `isolated-function` | Secure sandboxed execution via child processes |
 | `require-one-of` | Auto-detects browserless installation |
 | `acorn` / `acorn-walk` | AST parsing to detect page usage in code |
 

package/package.json

@@ -2,7 +2,7 @@
   "name": "@browserless/function",
   "description": "Execute arbitrary JavaScript code in a secure browser sandbox with access to page DOM and network.",
   "homepage": "https://browserless.js.org",
-  "version": "10.12.15",
+  "version": "12.0.0",
   "main": "src/index.js",
   "author": {
     "email": "hello@microlink.io",
@@ -31,16 +31,16 @@
     "vm"
   ],
   "dependencies": {
-    "@browserless/errors": "^10.12.14",
+    "@browserless/errors": "^12.0.0",
     "acorn": "~8.16.0",
     "acorn-walk": "~8.3.5",
-    "isolated-function": "~0.1.51",
+    "isolated-function": "~0.1.55",
     "require-one-of": "~1.0.24"
   },
   "devDependencies": {
-    "@browserless/test": "^10.12.6",
     "ava": "5",
-    "lodash": "latest"
+    "lodash": "latest",
+    "@browserless/test": "12.0.0"
   },
   "engines": {
     "node": ">= 20"
@@ -48,14 +48,13 @@
   "files": [
     "src"
   ],
-  "scripts": {
-    "test": "ava"
-  },
   "license": "MIT",
   "ava": {
     "serial": true,
     "timeout": "2m",
     "workerThreads": false
   },
-  "gitHead": "f6663d9a8b3ac2fdb28d524d7a4e3365e47dc972"
-}
+  "scripts": {
+    "test": "ava"
+  }
+}

package/src/function.js

@@ -1,33 +1,32 @@
 'use strict'
 
-const isolatedFunction = require('isolated-function')
 const template = require('./template')
 
 const [nodeMajor] = process.version.slice(1).split('.').map(Number)
 
-module.exports = async ({
-  url,
-  code,
-  vmOpts,
-  browserWSEndpoint,
-  needsNetwork = template.isUsingPage(code),
-  source = template(code, needsNetwork),
-  ...opts
-}) => {
-  const permissions = needsNetwork && nodeMajor >= 25 ? ['net'] : []
-  const vmOptsAllow = vmOpts?.allow || {}
-  const [fn, teardown] = isolatedFunction(source, {
-    ...vmOpts,
-    allow: {
-      ...vmOptsAllow,
-      permissions: [...(vmOptsAllow.permissions || []), ...permissions]
-    },
-    throwError: false
-  })
-  const result = await fn(url, browserWSEndpoint, opts)
-  await teardown()
-  return result
-}
+module.exports =
+  isolatedFunction =>
+    async ({
+      url,
+      code,
+      vmOpts,
+      browserWSEndpoint,
+      needsNetwork = template.isUsingPage(code),
+      source = template(code, needsNetwork),
+      ...opts
+    }) => {
+      const permissions = needsNetwork && nodeMajor >= 25 ? ['net'] : []
+      const vmOptsAllow = vmOpts?.allow || {}
+      const fn = isolatedFunction(source, {
+        ...vmOpts,
+        allow: {
+          ...vmOptsAllow,
+          permissions: [...(vmOptsAllow.permissions || []), ...permissions]
+        },
+        throwError: false
+      })
+      return fn(url, browserWSEndpoint, opts)
+    }
 
 module.exports.isUsingPage = template.isUsingPage
 module.exports.buildTemplate = template

package/src/index.js

@@ -1,8 +1,9 @@
 'use strict'
 
 const { isBrowserlessError, ensureError } = require('@browserless/errors')
+const createIsolatedFunction = require('isolated-function')
 const requireOneOf = require('require-one-of')
-const runFunction = require('./function')
+const createRunFunction = require('./function')
 
 const stringify = fn => fn.toString().trim().replace(/;$/, '')
 
@@ -29,72 +30,81 @@ const serializeResponse = response => ({
   fromServiceWorker: response.fromServiceWorker()
 })
 
-module.exports = (
-  fn,
-  {
-    getBrowserless = requireOneOf(['browserless']),
-    retry = 2,
-    timeout = 30000,
-    gotoOpts,
-    ...opts
-  } = {}
-) => {
-  const code = stringify(fn)
-  const needsNetwork = runFunction.isUsingPage(code)
-  const source = runFunction.buildTemplate(code, needsNetwork)
-  let browserPromise
-
-  const getBrowser = async () => {
-    if (!browserPromise) {
-      browserPromise = Promise.resolve(getBrowserless()).catch(error => {
-        browserPromise = undefined
-        throw error
-      })
+module.exports = ({ tmpdir } = {}) => {
+  const isolatedFunction = createIsolatedFunction({ tmpdir })
+  const runFunction = createRunFunction(isolatedFunction)
+
+  const createFunction = (
+    fn,
+    {
+      getBrowserless = requireOneOf(['browserless']),
+      retry = 2,
+      timeout = 30000,
+      gotoOpts,
+      ...opts
+    } = {}
+  ) => {
+    const code = stringify(fn)
+    const needsNetwork = createRunFunction.isUsingPage(code)
+    const source = createRunFunction.buildTemplate(code, needsNetwork)
+    let browserPromise
+
+    const getBrowser = async () => {
+      if (!browserPromise) {
+        browserPromise = Promise.resolve(getBrowserless()).catch(error => {
+          browserPromise = undefined
+          throw error
+        })
+      }
+      return browserPromise
     }
-    return browserPromise
-  }
 
-  return async (url, fnOpts = {}) => {
-    const browser = await getBrowser()
-    const browserless = await browser.createContext()
+    return async (url, fnOpts = {}) => {
+      const browser = await getBrowser()
+      const browserless = await browser.createContext()
 
-    return browserless.withPage((page, goto) => async () => {
-      const { device, response } = await goto(page, { url, timeout, ...gotoOpts })
+      return browserless.withPage((page, goto) => async () => {
+        const { device, response } = await goto(page, { url, timeout, ...gotoOpts })
 
-      const targetId = await getTargetId(page)
+        const targetId = await getTargetId(page)
 
-      const runFunctionOpts = {
-        url,
-        code,
-        device,
-        ...opts,
-        ...fnOpts,
-        ...(response && { _response: serializeResponse(response) })
-      }
+        const runFunctionOpts = {
+          url,
+          code,
+          device,
+          ...opts,
+          ...fnOpts,
+          ...(response && { _response: serializeResponse(response) })
+        }
 
-      if (runFunctionOpts.code === code) {
-        runFunctionOpts.needsNetwork = needsNetwork
-        runFunctionOpts.source = source
-      }
+        if (runFunctionOpts.code === code) {
+          runFunctionOpts.needsNetwork = needsNetwork
+          runFunctionOpts.source = source
+        }
 
-      if (runFunctionOpts.needsNetwork !== false) {
-        const browserFromPage = typeof page.browser === 'function' ? page.browser() : undefined
-        const browserWSEndpoint =
-          browserFromPage && typeof browserFromPage.wsEndpoint === 'function'
-            ? browserFromPage.wsEndpoint()
-            : undefined
+        if (runFunctionOpts.needsNetwork !== false) {
+          const browserFromPage = typeof page.browser === 'function' ? page.browser() : undefined
+          const browserWSEndpoint =
+            browserFromPage && typeof browserFromPage.wsEndpoint === 'function'
+              ? browserFromPage.wsEndpoint()
+              : undefined
 
-        if (!browserWSEndpoint) throw new Error('Browser WebSocket endpoint not found')
-        runFunctionOpts.browserWSEndpoint = browserWSEndpoint
-        runFunctionOpts.targetId = targetId
-      }
+          if (!browserWSEndpoint) throw new Error('Browser WebSocket endpoint not found')
+          runFunctionOpts.browserWSEndpoint = browserWSEndpoint
+          runFunctionOpts.targetId = targetId
+        }
 
-      const result = await runFunction(runFunctionOpts)
+        const result = await runFunction(runFunctionOpts)
 
-      if (result.isFulfilled) return result
-      const error = ensureError(result.value)
-      if (isBrowserlessError(error)) throw error
-      return result
-    })()
+        if (result.isFulfilled) return result
+        const error = ensureError(result.value)
+        if (isBrowserlessError(error)) throw error
+        return result
+      })()
+    }
   }
+
+  createFunction.teardown = () => isolatedFunction.teardown()
+
+  return createFunction
 }