browserless 13.12.5 → 13.13.0

package/index.d.ts

@@ -31,7 +31,7 @@ export interface Context {
   respawn: () => void
   context: () => Promise<BrowserContext>
   browser: () => Promise<Browser>
-  evaluate: <T>(fn: (page: Page, response?: HTTPResponse | undefined, error?: Error) => T | Promise<T>, gotoOpts?: GotoOptions) => Promise<T>
+  evaluate: <T>(fn: (page: Page, response?: HTTPResponse | undefined, error?: Error) => T | Promise<T>, gotoOpts?: GotoOptions & { keepPage?: boolean, preserveContext?: boolean }) => Promise<T>
   goto: (page: Page, opts: GotoOptions & { url: string }) => Promise<GotoResult>
   html: (url: string, opts?: GotoOptions) => Promise<string>
   page: (name?: string) => Promise<Page>
@@ -41,7 +41,7 @@ export interface Context {
   getDevice: (deviceName: string) => Viewport | undefined
   report: (opts?: { benchmark?: boolean }) => Promise<HardwareInfo>
   destroyContext: (opts?: { force?: boolean }) => Promise<void>
-  withPage: <T>(fn: (page: Page, goto: unknown) => Promise<T>, opts?: { timeout?: number }) => Promise<T>
+  withPage: <T>(fn: (page: Page, goto: unknown) => Promise<T>, opts?: { timeout?: number, keepPage?: boolean, preserveContext?: boolean }) => Promise<T>
 }
 
 export interface GotoOptions {

package/package.json

@@ -2,7 +2,7 @@
   "name": "browserless",
   "description": "The headless Chrome/Chromium driver on top of Puppeteer. Take screenshots, generate PDFs, extract text and HTML with a production-ready API.",
   "homepage": "https://browserless.js.org",
-  "version": "13.12.5",
+  "version": "13.13.0",
   "types": "index.d.ts",
   "main": "src/index.js",
   "author": {
@@ -69,5 +69,5 @@
     "timeout": "2m",
     "workerThreads": false
   },
-  "gitHead": "0e35854cf760df379112c723c75376e9b25e98fc"
+  "gitHead": "e118824d6fc40a4d930b58bbe7d449731b5df2aa"
 }

package/src/index.js

@@ -110,7 +110,10 @@ module.exports = ({ timeout: globalTimeout = 30000, ...launchOpts } = {}) => {
       }
     }
 
-    const withPage = (fn, { timeout: evaluateTimeout } = {}) => {
+    const withPage = (
+      fn,
+      { timeout: evaluateTimeout, keepPage = false, preserveContext = false } = {}
+    ) => {
       const name = fn.name || 'anonymous'
 
       return async (...args) => {
@@ -119,24 +122,39 @@ module.exports = ({ timeout: globalTimeout = 30000, ...launchOpts } = {}) => {
         async function run () {
           let page
           let closePageTimeout
+          let isRetained = false
 
-          try {
-            page = await createPage(name)
-            closePageTimeout = setTimeout(() => {
+          const startCloseTimeout = () => {
+            const timer = setTimeout(() => {
               closePage(page, name).catch(error => {
                 const { message, code, name } = ensureError(error)
                 debug('closePage:timeout:error', { message, code, name })
               })
             }, timeout)
-            if (typeof closePageTimeout.unref === 'function') closePageTimeout.unref()
+            if (typeof timer.unref === 'function') timer.unref()
+            return timer
+          }
+
+          try {
+            page = await createPage(name)
+            closePageTimeout = startCloseTimeout()
             const value = await fn(page, goto)(...args)
-            await closePage(page, `${name}:success`)
+            // A timeout already rejected the caller, who never received this
+            // page. Retaining it would clear the in-call watchdog and arm a
+            // new one with nobody holding the page.
+            if (keepPage && !isRejected) isRetained = true
+            else await closePage(page, `${name}:success`)
             return value
           } catch (error) {
             await closePage(page, `${name}:error`)
             if (!isRejected) throw ensureError(error)
           } finally {
+            // The in-call watchdog ends with the call. A retained page gets a
+            // fresh window of this same timeout, measured from handover.
+            // The owner has to finish or close the page inside that window.
+            // Failed attempts already closed their page, so only the last one retains.
             if (closePageTimeout) clearTimeout(closePageTimeout)
+            if (isRetained) startCloseTimeout()
           }
         }
 
@@ -150,10 +168,20 @@ module.exports = ({ timeout: globalTimeout = 30000, ...launchOpts } = {}) => {
               const isRetryable =
                 error.code === 'EBRWSRCONTEXTCONNRESET' || error.code === 'EPROTOCOL'
               if (!isRetryable) throw error
+              const { message, attemptNumber, retriesLeft } = error
+              // Every attempt builds its own page, so both codes are retryable
+              // inside the existing context: `EBRWSRCONTEXTCONNRESET` covers a
+              // closed page, a detached frame and a destroyed execution context,
+              // which a fresh page recovers from. Replacing the context is the
+              // only part a caller that owns it cannot afford, since that closes
+              // the pages it still holds. Skip that, not the retry.
+              if (preserveContext) {
+                debug('retry', { attemptNumber, retriesLeft, message, preserveContext })
+                return
+              }
               const previousContextPromise = _contextPromise
               _contextPromise = createBrowserContext(contextOpts)
               await pReflect(previousContextPromise.then(ctx => ctx.close()))
-              const { message, attemptNumber, retriesLeft } = error
               debug('retry', { attemptNumber, retriesLeft, message })
             }
           })
@@ -167,11 +195,15 @@ module.exports = ({ timeout: globalTimeout = 30000, ...launchOpts } = {}) => {
       }
     }
 
-    const evaluate = (fn, gotoOpts) =>
-      withPage(
+    const evaluate = (fn, gotoOpts) => {
+      // Both belong to withPage, so they are pulled out rather than spread into
+      // the navigation options.
+      const { keepPage, preserveContext, ...navigateOpts } = gotoOpts ?? {}
+
+      return withPage(
         Object.defineProperty(
           (page, goto) => async (url, opts) => {
-            const { response, error } = await goto(page, { url, ...gotoOpts, ...opts })
+            const { response, error } = await goto(page, { url, ...navigateOpts, ...opts })
             return fn(page, response, error)
           },
           'name',
@@ -180,8 +212,9 @@ module.exports = ({ timeout: globalTimeout = 30000, ...launchOpts } = {}) => {
             writable: false
           }
         ),
-        gotoOpts
+        { ...navigateOpts, keepPage, preserveContext }
       )
+    }
 
     const destroyContext = async ({ force = false } = {}) => {
       if (force) isDestroyedForced = true