@crawlee/browser-pool 4.0.0-beta.7 → 4.0.0-beta.71

package/puppeteer/puppeteer-plugin.js

@@ -1,11 +1,18 @@
 import { readFile } from 'node:fs/promises';
 import { BrowserPlugin } from '../abstract-classes/browser-plugin.js';
 import { anonymizeProxySugar } from '../anonymize-proxy.js';
-import { log } from '../logger.js';
 import { noop } from '../utils.js';
 import { PuppeteerController } from './puppeteer-controller.js';
 const PROXY_SERVER_ARG = '--proxy-server=';
 export class PuppeteerPlugin extends BrowserPlugin {
+    /** Pages share cookies/storage on the remote browser (Puppeteer defaults to non-incognito). */
+    useRemoteConnection(connection, parameters = {}) {
+        super.useRemoteConnection(connection, parameters);
+        if (!this.useIncognitoPages) {
+            this.log.info('Remote Puppeteer connection — pages will share cookies and storage on the remote ' +
+                'browser instance (useIncognitoPages defaults to false).');
+        }
+    }
     async _launch(launchContext) {
         let oldPuppeteerVersion = false;
         try {
@@ -17,58 +24,80 @@ export class PuppeteerPlugin extends BrowserPlugin {
         catch {
             // ignore
         }
-        const { launchOptions, userDataDir, useIncognitoPages, proxyUrl } = launchContext;
-        launchOptions.userDataDir = launchOptions.userDataDir ?? userDataDir;
-        if (launchOptions.headless === false) {
-            if (Array.isArray(launchOptions.args)) {
-                launchOptions.args.push('--disable-site-isolation-trials');
-            }
-            else {
-                launchOptions.args = ['--disable-site-isolation-trials'];
-            }
-        }
-        if (launchOptions.headless === true && oldPuppeteerVersion) {
-            launchOptions.headless = 'new';
-        }
+        const { useIncognitoPages, proxyUrl, ignoreProxyCertificate } = launchContext;
         let browser;
-        {
-            const [anonymizedProxyUrl, close] = await anonymizeProxySugar(proxyUrl);
-            if (proxyUrl) {
-                const proxyArg = `${PROXY_SERVER_ARG}${anonymizedProxyUrl ?? proxyUrl}`;
+        if (this.remoteConnection) {
+            browser = await this._connectToRemoteBrowser(launchContext, async (url) => {
+                const connectOptions = this.remoteConnectionParameters?.connectOptions ?? {};
+                this.log.info('Connecting to remote browser via connect (CDP).');
+                return this.library.connect({ ...connectOptions, browserWSEndpoint: url });
+            });
+        }
+        else {
+            const { launchOptions, userDataDir, experimentalContainers } = launchContext;
+            if (experimentalContainers) {
+                throw new Error('Experimental containers are only available with Playwright');
+            }
+            launchOptions.userDataDir = launchOptions.userDataDir ?? userDataDir;
+            if (launchOptions.headless === false) {
                 if (Array.isArray(launchOptions.args)) {
-                    launchOptions.args.push(proxyArg);
+                    launchOptions.args.push('--disable-site-isolation-trials');
                 }
                 else {
-                    launchOptions.args = [proxyArg];
+                    launchOptions.args = ['--disable-site-isolation-trials'];
                 }
             }
-            try {
-                browser = await this.library.launch(launchOptions);
-                if (anonymizedProxyUrl) {
-                    browser.on('disconnected', async () => {
-                        await close();
-                    });
-                }
+            if (launchOptions.headless === true && oldPuppeteerVersion) {
+                launchOptions.headless = 'new';
             }
-            catch (error) {
-                await close();
-                this._throwAugmentedLaunchError(error, launchContext.launchOptions?.executablePath, '`apify/actor-node-puppeteer-chrome`', "Try installing a browser, if it's missing, by running `npx @puppeteer/browsers install chromium --path [path]` and pointing `executablePath` to the downloaded executable (https://pptr.dev/browsers-api)");
+            {
+                const [anonymizedProxyUrl, close] = await anonymizeProxySugar(proxyUrl, undefined, undefined, {
+                    ignoreProxyCertificate: launchContext.ignoreProxyCertificate,
+                });
+                if (proxyUrl) {
+                    const proxyArg = `${PROXY_SERVER_ARG}${anonymizedProxyUrl ?? proxyUrl}`;
+                    if (Array.isArray(launchOptions.args)) {
+                        launchOptions.args.push(proxyArg);
+                    }
+                    else {
+                        launchOptions.args = [proxyArg];
+                    }
+                }
+                try {
+                    browser = await this.library.launch(launchOptions);
+                    if (anonymizedProxyUrl) {
+                        browser.on('disconnected', async () => {
+                            await close();
+                        });
+                    }
+                }
+                catch (error) {
+                    await close();
+                    this._throwAugmentedLaunchError(error, launchContext.launchOptions?.executablePath, '`apify/actor-node-puppeteer-chrome`', "Try installing a browser, if it's missing, by running `npx @puppeteer/browsers install chromium --path [path]` and pointing `executablePath` to the downloaded executable (https://pptr.dev/browsers-api)");
+                }
             }
         }
-        browser.on('targetcreated', async (target) => {
+        const targetCreatedHandler = async (target) => {
             try {
                 const page = await target.page();
                 if (page) {
                     page.on('error', (error) => {
-                        log.exception(error, 'Page crashed.');
+                        this.log.exception(error, 'Page crashed.');
                         page.close().catch(noop);
                     });
                 }
             }
             catch (error) {
-                log.exception(error, 'Failed to retrieve page from target.');
+                this.log.exception(error, 'Failed to retrieve page from target.');
             }
-        });
+        };
+        browser.on('targetcreated', targetCreatedHandler);
+        // Clean up the listener when a remote browser disconnects to prevent leaks
+        if (this.remoteConnection) {
+            browser.once('disconnected', () => {
+                browser.off('targetcreated', targetCreatedHandler);
+            });
+        }
         const boundMethods = [
             'newPage',
             'close',
@@ -78,6 +107,7 @@ export class PuppeteerPlugin extends BrowserPlugin {
             'version',
             'on',
             'process',
+            'pages',
         ].reduce((map, method) => {
             map[method] = browser[method]?.bind(browser);
             return map;
@@ -89,22 +119,30 @@ export class PuppeteerPlugin extends BrowserPlugin {
                     return async (...args) => {
                         let page;
                         if (useIncognitoPages) {
-                            const [anonymizedProxyUrl, close] = await anonymizeProxySugar(proxyUrl);
+                            // Skip proxy setup for remote connections — proxy is managed by the remote service.
+                            const effectiveProxyUrl = this.remoteConnection ? undefined : proxyUrl;
+                            const [anonymizedProxyUrl, close] = effectiveProxyUrl
+                                ? await anonymizeProxySugar(effectiveProxyUrl, undefined, undefined, {
+                                    ignoreProxyCertificate,
+                                })
+                                : [undefined, noop];
+                            const proxyServer = anonymizedProxyUrl ?? effectiveProxyUrl;
+                            const contextOptions = proxyServer ? { proxyServer } : {};
+                            const context = (await browser[method](contextOptions));
                             try {
-                                const context = (await browser[method]({
-                                    proxyServer: anonymizedProxyUrl ?? proxyUrl,
-                                }));
                                 page = await context.newPage(...args);
-                                if (anonymizedProxyUrl) {
-                                    page.on('close', async () => {
-                                        await close();
-                                    });
-                                }
                             }
                             catch (error) {
+                                await context.close().catch(noop);
                                 await close();
                                 throw error;
                             }
+                            page.once('close', async () => {
+                                if (anonymizedProxyUrl) {
+                                    await close();
+                                }
+                                await context.close().catch(noop);
+                            });
                         }
                         else {
                             page = await boundMethods.newPage(...args);

package/puppeteer/puppeteer-plugin.js.map

@@ -1 +1 @@
-{"version":3,"file":"puppeteer-plugin.js","sourceRoot":"","sources":["../../src/puppeteer/puppeteer-plugin.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"puppeteer-plugin.js","sourceRoot":"","sources":["../../src/puppeteer/puppeteer-plugin.ts"],"names":[],"mappings":"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"}

package/remote-browser-pool.d.ts

@@ -0,0 +1,173 @@
+import type { IBrowserPool, NewPageOptions, PageState } from '@crawlee/types';
+import type { BrowserPlugin } from './abstract-classes/browser-plugin.js';
+import { BrowserPool } from './browser-pool.js';
+import type { BrowserPoolHooks, BrowserPoolOptions } from './browser-pool.js';
+import { RemoteBrowserProvider } from './remote-browser-provider.js';
+/**
+ * The result of resolving a remote browser endpoint: the URL to connect to plus an optional opaque
+ * `context` object that is handed back to `release`.
+ */
+export interface ResolvedRemoteEndpoint {
+    /** The browser endpoint URL to connect to. */
+    url: string;
+    /** Opaque metadata passed back to `release()` — e.g. session IDs, API tokens. */
+    context?: Record<string, unknown>;
+}
+/**
+ * A remote browser endpoint: either a static URL string, or a function called once per browser launch
+ * that returns a URL (optionally with a `context` for `release`).
+ *
+ * The function receives the `proxyUrl` resolved by Crawlee's proxy configuration for the launch, so it
+ * can forward it to the remote service's proxy API.
+ */
+export type RemoteBrowserEndpoint = string | ((options?: {
+    proxyUrl?: string;
+}) => string | ResolvedRemoteEndpoint | Promise<string | ResolvedRemoteEndpoint>);
+/**
+ * The bridge a {@link RemoteBrowserPool} injects into a {@link BrowserPlugin} so the plugin can
+ * connect to a remote browser without owning any remote-session policy.
+ *
+ * The plugin only knows how to make the library-specific `connect()` call; everything else — resolving
+ * the endpoint, calling the user's `release()`, and guaranteeing release fires at most once — lives in
+ * the pool. The plugin calls {@link RemoteConnection.resolve|resolve} before connecting, stores the
+ * returned `token` on its launch context, and the controller later calls
+ * {@link RemoteConnection.release|release} with that token when the browser closes.
+ *
+ * @internal
+ */
+export interface RemoteConnection {
+    /** Resolves the endpoint for a single browser launch. The `token` identifies the session for release. */
+    resolve(options?: {
+        proxyUrl?: string;
+    }): Promise<{
+        url: string;
+        token: number;
+    }>;
+    /** Releases the remote session for `token`. Idempotent — safe to call from both `close()` and `kill()`. */
+    release(token: number): Promise<void>;
+}
+/**
+ * Per-plugin remote connection parameters, passed to {@link BrowserPlugin.useRemoteConnection}.
+ * The endpoint is supplied per-launch via {@link RemoteConnection}; these are the static connect()
+ * parameters (protocol, headers, timeouts, …).
+ */
+export interface RemoteConnectionParameters {
+    /**
+     * Playwright only: which protocol to connect with. `'cdp'` uses `connectOverCDP()` (the default),
+// @ts-ignore optional peer dependency or compatibility with es2022
+     * `'playwright'` uses `connect()` (Playwright's own WebSocket protocol). Ignored by Puppeteer.
+     */
+    protocol?: 'cdp' | 'playwright';
+    /** Extra options forwarded to the library `connect()` / `connectOverCDP()` call (endpoint excluded). */
+    connectOptions?: Record<string, unknown>;
+}
+export interface RemoteBrowserPoolOptions {
+    /**
+     * The browser plugin(s) used to connect to the remote service — e.g. `new PlaywrightPlugin(playwright.chromium)`
+     * or `new PuppeteerPlugin(puppeteer)`. The pool configures them for remote connection; do not set a local
+     * `launchOptions` on them.
+     */
+    browserPlugins: BrowserPlugin[];
+    /**
+     * The remote browser endpoint: a static URL, a function returning one per launch, or a
+     * {@link RemoteBrowserProvider} instance encapsulating a session create/release lifecycle.
+     */
+    endpoint: RemoteBrowserEndpoint | RemoteBrowserProvider<any>;
+    /**
+     * Cleanup callback invoked when a browser closes, crashes, or the pool is destroyed. Receives the
+     * `context` returned by a function endpoint. Errors are caught and logged. Ignored when `endpoint`
+     * is a {@link RemoteBrowserProvider} (its own `release()` is used instead).
+     */
+    release?: (info: {
+        endpoint: string;
+        context?: Record<string, unknown>;
+    }) => unknown;
+    /**
+     * Maximum number of remote browsers open at once. When reached, {@link RemoteBrowserPool.newPage|newPage}
+     * waits for a browser to close before connecting a new one. Set it to your service's concurrent-session limit
+     * to avoid `429` errors. Defaults to the {@link RemoteBrowserProvider.maxOpenBrowsers|provider's value}, or
+     * `Infinity`.
+     */
+    maxOpenBrowsers?: number;
+    /** Static connect() parameters (Playwright protocol selection, headers, timeouts, …). */
+    connection?: RemoteConnectionParameters;
+    /** Extra {@link BrowserPool} options (lifecycle hooks, page limits, fingerprinting, …). */
+    browserPoolOptions?: Omit<BrowserPoolOptions, 'browserPlugins'> & BrowserPoolHooks<any, any, any>;
+    /** Fallback poll interval (ms) while waiting for a free browser slot. The wait is event-driven; this only bounds it. @default 500 */
+    slotPollIntervalMillis?: number;
+}
+/**
+ * The remote-connection configuration a browser crawler accepts on its `remoteBrowser` option. It is the
+ * {@link RemoteBrowserPoolOptions} a user supplies *minus* the parts the crawler provides itself — the
+ * `browserPlugins` (the crawler builds the correct one for its browser) and `browserPoolOptions` (taken from
+ * the crawler's own `browserPoolOptions`). This is what makes the crawler path both terse and mismatch-proof.
+ */
+export type CrawlerRemoteBrowserOptions = Omit<RemoteBrowserPoolOptions, 'browserPlugins' | 'browserPoolOptions'>;
+/**
+ * An {@link IBrowserPool} implementation for remote browser services.
+ *
+ * Unlike configuring a remote browser through a crawler's `launchContext`, this pool is the single owner
+ * of all remote-session concerns:
+ * - **endpoint resolution** — static URL, per-launch function, or {@link RemoteBrowserProvider};
+ * - **release lifecycle** — `release()` fires exactly once per session on close/crash/teardown (no leaks,
+ *   no double-release);
+ * - **concurrency** — {@link RemoteBrowserPoolOptions.maxOpenBrowsers|maxOpenBrowsers} is enforced inside
+ *   {@link RemoteBrowserPool.newPage|newPage}, which waits for a free slot rather than overshooting.
+ *
+ * The wrapped {@link BrowserPool} and its plugin only perform the library-specific `connect()` call.
+ *
+ * Pass an instance as the crawler's `browserPool` option:
+ *
+ * ```typescript
+ * import { PlaywrightPlugin, RemoteBrowserPool } from '@crawlee/browser-pool';
+ * import { PlaywrightCrawler } from 'crawlee';
+// @ts-ignore optional peer dependency or compatibility with es2022
+ * import playwright from 'playwright';
+ *
+ * const browserPool = new RemoteBrowserPool({
+ *     browserPlugins: [new PlaywrightPlugin(playwright.chromium)],
+ *     endpoint: 'wss://production-sfo.browserless.io?token=xxx',
+ *     maxOpenBrowsers: 2,
+ * });
+ *
+ * const crawler = new PlaywrightCrawler({ browserPool });
+ * ```
+ *
+ * @category Browser management
+ */
+export declare class RemoteBrowserPool<Page = unknown> implements IBrowserPool<Page> {
+    /** The wrapped pool that performs the remote connections and serves pages. */
+    readonly browserPool: BrowserPool;
+    /** The wrapped pool viewed through the {@link IBrowserPool} contract (the bare type widens pages to `never`). */
+    private readonly pool;
+    private readonly registry;
+    private readonly slotPollIntervalMillis;
+    private readonly log;
+    /** Shared by all `newPage` callers waiting for a free slot, so they don't each register their own listeners. */
+    private _capacityChange?;
+    constructor(options: RemoteBrowserPoolOptions);
+    /** Maximum number of remote browsers that may be open at the same time. */
+    get maxOpenBrowsers(): number;
+    set maxOpenBrowsers(value: number);
+    /**
+     * Opens a new page, waiting first until {@link RemoteBrowserPoolOptions.maxOpenBrowsers|maxOpenBrowsers}
+     * allows it (either a new browser slot is free, or an active browser still has page capacity).
+     */
+    newPage(options?: NewPageOptions): Promise<Page>;
+    closePage(page: Page, options?: {
+        error?: Error;
+    }): Promise<void>;
+    extractPageState(page: Page): Promise<PageState>;
+    injectPageState(page: Page, state: PageState): Promise<void>;
+    /** Closes all browsers, releases any still-open remote sessions, and tears down the wrapped pool. */
+    destroy(): Promise<void>;
+    /** Resolves once the wrapped pool can serve another page without exceeding `maxOpenBrowsers`. */
+    private _waitForFreeSlot;
+    /**
+     * Resolves on the next browser-retired / page-closed event, or after `slotPollIntervalMillis`. All
+     * concurrently-waiting `newPage` calls share a single promise (and a single pair of event listeners)
+     * per tick, so a fleet of saturated callers doesn't fan out into N listener pairs on the pool.
+     */
+    private _nextCapacityChange;
+}
+//# sourceMappingURL=remote-browser-pool.d.ts.map

package/remote-browser-pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-browser-pool.d.ts","sourceRoot":"","sources":["../src/remote-browser-pool.ts"],"names":[],"mappings":"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"}

package/remote-browser-pool.js

@@ -0,0 +1,192 @@
+import { serviceLocator } from '@crawlee/core';
+import { BrowserPool } from './browser-pool.js';
+import { RemoteBrowserProvider } from './remote-browser-provider.js';
+/**
+ * Owns the lifecycle of remote browser sessions for a single {@link RemoteBrowserPool}: endpoint
+ * resolution, the user's `release()` callback, and a release-at-most-once guarantee. Implements
+ * {@link RemoteConnection} so it can be injected into a plugin.
+ */
+class RemoteSessionRegistry {
+    endpoint;
+    onRelease;
+    log;
+    sessions = new Map();
+    nextToken = 0;
+    constructor(endpoint, onRelease, log) {
+        this.endpoint = endpoint;
+        this.onRelease = onRelease;
+        this.log = log;
+    }
+    async resolve(options) {
+        const resolved = typeof this.endpoint === 'function' ? await this.endpoint(options) : this.endpoint;
+        let result;
+        if (typeof resolved === 'string') {
+            if (!resolved)
+                throw new Error('Remote browser endpoint resolved to an empty string.');
+            result = { url: resolved };
+        }
+        else if (!resolved?.url) {
+            throw new Error("Remote browser endpoint() must return a URL string or an object with a non-empty 'url'.");
+        }
+        else {
+            result = resolved;
+        }
+        const token = this.nextToken++;
+        this.sessions.set(token, { url: result.url, context: result.context, released: false });
+        return { url: result.url, token };
+    }
+    async release(token) {
+        const session = this.sessions.get(token);
+        // Release at most once per session — guards a close()/teardown race (the `released` flag is set
+        // synchronously before the awaited onRelease, so releaseAll() can't double-fire an in-flight release).
+        if (!session || session.released)
+            return;
+        session.released = true;
+        try {
+            await this.onRelease?.({ endpoint: session.url, context: session.context });
+        }
+        catch (err) {
+            this.log.warning('Remote browser release() failed.', { error: err?.message });
+        }
+        finally {
+            this.sessions.delete(token);
+        }
+    }
+    /** Releases every session that is still open. Called on pool teardown so no remote session leaks. */
+    async releaseAll() {
+        await Promise.all([...this.sessions.keys()].map(async (token) => this.release(token)));
+    }
+}
+/**
+ * An {@link IBrowserPool} implementation for remote browser services.
+ *
+ * Unlike configuring a remote browser through a crawler's `launchContext`, this pool is the single owner
+ * of all remote-session concerns:
+ * - **endpoint resolution** — static URL, per-launch function, or {@link RemoteBrowserProvider};
+ * - **release lifecycle** — `release()` fires exactly once per session on close/crash/teardown (no leaks,
+ *   no double-release);
+ * - **concurrency** — {@link RemoteBrowserPoolOptions.maxOpenBrowsers|maxOpenBrowsers} is enforced inside
+ *   {@link RemoteBrowserPool.newPage|newPage}, which waits for a free slot rather than overshooting.
+ *
+ * The wrapped {@link BrowserPool} and its plugin only perform the library-specific `connect()` call.
+ *
+ * Pass an instance as the crawler's `browserPool` option:
+ *
+ * ```typescript
+ * import { PlaywrightPlugin, RemoteBrowserPool } from '@crawlee/browser-pool';
+ * import { PlaywrightCrawler } from 'crawlee';
+ * import playwright from 'playwright';
+ *
+ * const browserPool = new RemoteBrowserPool({
+ *     browserPlugins: [new PlaywrightPlugin(playwright.chromium)],
+ *     endpoint: 'wss://production-sfo.browserless.io?token=xxx',
+ *     maxOpenBrowsers: 2,
+ * });
+ *
+ * const crawler = new PlaywrightCrawler({ browserPool });
+ * ```
+ *
+ * @category Browser management
+ */
+export class RemoteBrowserPool {
+    /** The wrapped pool that performs the remote connections and serves pages. */
+    browserPool;
+    /** The wrapped pool viewed through the {@link IBrowserPool} contract (the bare type widens pages to `never`). */
+    pool;
+    registry;
+    slotPollIntervalMillis;
+    log;
+    /** Shared by all `newPage` callers waiting for a free slot, so they don't each register their own listeners. */
+    _capacityChange;
+    constructor(options) {
+        const { browserPlugins, endpoint, release, maxOpenBrowsers, connection = {}, browserPoolOptions = {}, slotPollIntervalMillis = 500, } = options;
+        this.log = serviceLocator.getLogger().child({ prefix: 'RemoteBrowserPool' });
+        this.slotPollIntervalMillis = slotPollIntervalMillis;
+        // A RemoteBrowserProvider carries its own endpoint, release, and maxOpenBrowsers.
+        const provider = endpoint instanceof RemoteBrowserProvider ? endpoint : undefined;
+        const resolvedEndpoint = provider
+            ? (opts) => provider.connect(opts)
+            : endpoint;
+        const resolvedRelease = provider
+            ? ({ context }) => provider.release(context)
+            : release;
+        const resolvedMax = maxOpenBrowsers ?? provider?.maxOpenBrowsers;
+        this.registry = new RemoteSessionRegistry(resolvedEndpoint, resolvedRelease, this.log);
+        // Wire every plugin for remote connection.
+        for (const plugin of browserPlugins) {
+            plugin.useRemoteConnection(this.registry, connection);
+        }
+        this.browserPool = new BrowserPool({ ...browserPoolOptions, browserPlugins });
+        this.pool = this.browserPool;
+        // Release a browser's remote session once it closes. The registry dedupes (close() schedules a delayed
+        // kill(), so BROWSER_CLOSED can fire twice), and destroy()'s releaseAll() backstops any that never close.
+        this.browserPool.on("browserLaunched" /* BROWSER_POOL_EVENTS.BROWSER_LAUNCHED */, (controller) => {
+            controller.once("browserClosed" /* BROWSER_CONTROLLER_EVENTS.BROWSER_CLOSED */, () => {
+                const token = controller.launchContext._remoteToken;
+                if (token !== undefined)
+                    void this.registry.release(token);
+            });
+        });
+        if (resolvedMax !== undefined) {
+            this.browserPool.maxOpenBrowsers = resolvedMax;
+        }
+    }
+    /** Maximum number of remote browsers that may be open at the same time. */
+    get maxOpenBrowsers() {
+        return this.browserPool.maxOpenBrowsers;
+    }
+    set maxOpenBrowsers(value) {
+        this.browserPool.maxOpenBrowsers = value;
+    }
+    /**
+     * Opens a new page, waiting first until {@link RemoteBrowserPoolOptions.maxOpenBrowsers|maxOpenBrowsers}
+     * allows it (either a new browser slot is free, or an active browser still has page capacity).
+     */
+    async newPage(options) {
+        await this._waitForFreeSlot();
+        return this.pool.newPage(options);
+    }
+    async closePage(page, options) {
+        return this.pool.closePage(page, options);
+    }
+    async extractPageState(page) {
+        return this.pool.extractPageState(page);
+    }
+    async injectPageState(page, state) {
+        return this.pool.injectPageState(page, state);
+    }
+    /** Closes all browsers, releases any still-open remote sessions, and tears down the wrapped pool. */
+    async destroy() {
+        await this.browserPool.destroy();
+        // Backstop: release any sessions whose browser never emitted a close (e.g. dropped on teardown).
+        await this.registry.releaseAll();
+    }
+    /** Resolves once the wrapped pool can serve another page without exceeding `maxOpenBrowsers`. */
+    async _waitForFreeSlot() {
+        while (!this.browserPool.hasFreeBrowserSlot() && !this.browserPool.hasActiveBrowserWithFreeCapacity()) {
+            await this._nextCapacityChange();
+        }
+    }
+    /**
+     * Resolves on the next browser-retired / page-closed event, or after `slotPollIntervalMillis`. All
+     * concurrently-waiting `newPage` calls share a single promise (and a single pair of event listeners)
+     * per tick, so a fleet of saturated callers doesn't fan out into N listener pairs on the pool.
+     */
+    _nextCapacityChange() {
+        this._capacityChange ??= new Promise((resolve) => {
+            const done = () => {
+                clearTimeout(timer);
+                this.browserPool.off("browserRetired" /* BROWSER_POOL_EVENTS.BROWSER_RETIRED */, done);
+                this.browserPool.off("pageClosed" /* BROWSER_POOL_EVENTS.PAGE_CLOSED */, done);
+                this._capacityChange = undefined;
+                resolve();
+            };
+            const timer = setTimeout(done, this.slotPollIntervalMillis);
+            timer.unref?.();
+            this.browserPool.once("browserRetired" /* BROWSER_POOL_EVENTS.BROWSER_RETIRED */, done);
+            this.browserPool.once("pageClosed" /* BROWSER_POOL_EVENTS.PAGE_CLOSED */, done);
+        });
+        return this._capacityChange;
+    }
+}
+//# sourceMappingURL=remote-browser-pool.js.map

package/remote-browser-pool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-browser-pool.js","sourceRoot":"","sources":["../src/remote-browser-pool.ts"],"names":[],"mappings":"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"}