Struct BrowserPool 

pub struct BrowserPool { /* private fields */ }

A pool of reusable browser tabs spread across one or more Chrome sessions.

Tabs are created lazily on first acquire(). Call warmup() to optionally pre-create tabs for faster first acquires.

Usage

use void_crawl_core::pool::BrowserPool;

let pool = BrowserPool::from_env().await?;
// warmup() is optional — tabs are created on demand

let tab = pool.acquire().await?;
tab.page.navigate("https://example.com").await?;
let html = tab.page.content().await?;
pool.release(tab).await;

pool.close().await?;

Implementations

impl BrowserPool

pub fn new(config: PoolConfig, sessions: Vec<BrowserSession>) -> Self

Create a new pool from pre-built sessions and config.

The pool starts with no tabs — they are created lazily on acquire() or optionally pre-created via warmup().

pub async fn from_env() -> Result<Self>

Build a pool from environment variables.

Variable	Description	Default
CHROME_WS_URLS	Comma-separated ws:// or http:// URLs (connect mode)	—
BROWSER_COUNT	Number of Chrome processes to launch	1
TABS_PER_BROWSER	Max concurrent tabs per browser	4
TAB_MAX_USES	Hard recycle threshold	50
TAB_MAX_IDLE_SECS	Idle eviction timeout	60
CHROME_NO_SANDBOX	Set to "1" to pass --no-sandbox	—
CHROME_HEADLESS	Set to "0" for headful mode	1
ACQUIRE_TIMEOUT_SECS	Max seconds to wait in acquire()	30
VIEWPORT_WIDTH	Stealth viewport width	1920
VIEWPORT_HEIGHT	Stealth viewport height	1080
CDP_PORT_BASE	Pin Chrome’s --remote-debugging-port for launched browsers. Browser i uses base + i. Unset = OS-assigned (recommended; can’t conflict).	—

pub async fn warmup(&self) -> Result<()>

Optionally pre-open tabs across all sessions and fill the ready queue.

Tabs are created in parallel across sessions, then inserted into the ready queue. Successful tabs are kept even when some fail; the first error (if any) is returned after all successful tabs are stored.

This is optional — if not called, tabs are created lazily on first acquire().

pub async fn acquire(&self) -> Result<PooledTab>

Check out a tab from the pool.

If an idle tab is available, it is returned immediately. Otherwise, a new tab is created on demand (up to tabs_per_browser * browsers total). Blocks only when all tabs are currently in use.

Tabs that have exceeded tab_max_uses are silently hard-recycled.

The semaphore permit is returned on every error path so that failures never permanently shrink pool concurrency.

pub async fn acquire_timed(&self) -> Result<(PooledTab, u64)>

Like acquire, but also returns the milliseconds spent blocked on the concurrency semaphore — the pure queueing wait, excluding any lazy tab-creation latency that happens after a permit is granted. A near-zero value means a slot was free immediately; a non-trivial value means the caller queued behind other in-flight work. Surfaced to MCP clients so an agent can tell when it has oversubscribed the pool and should throttle or cap a batch at max_tabs.

pub async fn release(&self, tab: PooledTab)

Return a tab to the pool after use.

Instant return — no CDP round-trip on the common path. The next caller’s navigate(url) overwrites prior page content; stealth scripts persist across navigations.

The one exception: if a download was armed on this tab and never completed (arm_download without a matching wait), we reset the CDP download behavior before recycling so the next caller doesn’t inherit an allowAndName pointing at a since-deleted quarantine dir. This costs one CDP call only on the rare armed-but-abandoned path.

pub async fn evict_idle(&self) -> Result<()>

Close idle tabs that have exceeded tab_max_idle_secs and open fresh replacements.

Intended to be called periodically from a background tokio task.

pub fn config(&self) -> &PoolConfig

Access the pool configuration.

pub fn available_permits(&self) -> usize

Free concurrency permits right now — how many more tabs could be acquired without queueing. max_tabs - available_permits() is the count currently checked out (in-flight fetches plus any held session tabs). A live snapshot an agent can read via pool_status to size a fan-out before submitting it.

pub fn start_eviction_task(self: Arc<Self>)

Start a background Tokio task that periodically calls evict_idle.

Idempotent — if an eviction task is already running, this is a no-op. The handle is stored inside the pool and cancelled automatically by close. Call stop_eviction_task to cancel early.

Panics

Must be called from within a Tokio runtime context.

pub fn stop_eviction_task(&self)

Stop the background eviction task (if running).

Called automatically by close.

pub async fn close(&self) -> Result<()>

Drain all tabs and close all browser sessions.

Returns the first error encountered during tab or session teardown, but always attempts to close everything regardless of individual failures.

Trait Implementations

impl Debug for BrowserPool

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.