Struct BrowserPool 

pub struct BrowserPool { /* private fields */ }

Main browser pool with lifecycle management.

This is the public-facing API for the browser pool. It wraps the internal state and manages the keep-alive thread.

Overview

BrowserPool provides:

• Browser checkout via get()
• Pool warmup via warmup()
• Statistics via stats()
• Graceful shutdown via shutdown_async()

Example

use html2pdf_api::{BrowserPool, BrowserPoolConfigBuilder, ChromeBrowserFactory};
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create pool
    let mut pool = BrowserPool::builder()
        .config(
            BrowserPoolConfigBuilder::new()
                .max_pool_size(5)
                .warmup_count(3)
                .build()?
        )
        .factory(Box::new(ChromeBrowserFactory::with_defaults()))
        .build()?;

    // Warmup
    pool.warmup().await?;

    // Use browsers
    {
        let browser = pool.get()?;
        let tab = browser.new_tab()?;
        // ... do work ...
    } // browser returned to pool automatically

    // Shutdown
    pool.shutdown_async().await;

    Ok(())
}

Thread Safety

BrowserPool is Send and can be wrapped in Arc<Mutex<>> for sharing across threads. Use into_shared() for convenience.

Implementations

impl BrowserPool

pub fn into_shared(self) -> Arc<Mutex<BrowserPool>>

Convert pool into a shared Arc<Mutex<>> for use in web handlers.

This is convenient for web frameworks that need shared state.

Example

let pool = BrowserPool::builder()
    .factory(Box::new(ChromeBrowserFactory::with_defaults()))
    .build()?
    .into_shared();

// Can now be cloned and shared across handlers
let pool_clone = Arc::clone(&pool);

pub fn builder() -> BrowserPoolBuilder

Create a new builder for constructing a BrowserPool.

This is the recommended way to create a pool.

Example

let pool = BrowserPool::builder()
    .factory(Box::new(ChromeBrowserFactory::with_defaults()))
    .build()?;

pub fn get(&self) -> Result<BrowserHandle>

Get a browser from the pool (or create one if empty).

Returns a BrowserHandle that implements Deref<Target=Browser>, allowing transparent access to browser methods.

Automatic Return

The browser is automatically returned to the pool when the handle is dropped, even if your code panics (RAII pattern).

Errors

• Returns BrowserPoolError::ShuttingDown if pool is shutting down.
• Returns BrowserPoolError::BrowserCreation if new browser creation fails.
• Returns BrowserPoolError::HealthCheckFailed if all pooled browsers are unhealthy.

Example

let browser = pool.get()?;
let tab = browser.new_tab()?;
tab.navigate_to("https://example.com")?;
// browser returned automatically when it goes out of scope

pub fn stats(&self) -> PoolStats

Get pool statistics snapshot.

Returns

PoolStats containing:

• available: Browsers in pool ready for checkout
• active: All browsers (pooled + checked out)
• total: Currently same as active (for future expansion)

Example

let stats = pool.stats();
println!("Available: {}, Active: {}", stats.available, stats.active);

pub fn config(&self) -> &BrowserPoolConfig

Get a reference to the pool configuration.

Returns the configuration that was used to create this pool. The configuration is immutable after pool creation.

Example

let pool = BrowserPool::builder()
    .config(
        BrowserPoolConfigBuilder::new()
            .max_pool_size(10)
            .build()?
    )
    .factory(Box::new(ChromeBrowserFactory::with_defaults()))
    .build()?;

println!("Max pool size: {}", pool.config().max_pool_size);
println!("Browser TTL: {:?}", pool.config().browser_ttl);

Use Cases

• Logging configuration at startup
• Monitoring/metrics collection
• Readiness checks (comparing active count vs max_pool_size)
• Debugging pool behavior

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

Warmup the pool by pre-creating browsers.

This is highly recommended to reduce first-request latency. Should be called during application startup.

Process

1. Creates warmup_count browsers sequentially with staggered timing
2. Tests each browser with navigation
3. Returns all browsers to pool
4. Entire process has timeout (configurable via warmup_timeout)

Staggered Creation

Browsers are created with a 30-second delay between them to ensure their TTLs are offset. This prevents all browsers from expiring at the same time.

Errors

• Returns error if warmup times out.
• Returns error if browser creation fails.

Example

let pool = BrowserPool::builder()
    .factory(Box::new(ChromeBrowserFactory::with_defaults()))
    .build()?;

// Warmup during startup
pool.warmup().await?;

pub async fn shutdown_async(&mut self)

Asynchronously shutdown the pool (recommended method).

This is the preferred shutdown method as it can properly await async task cancellation. Should be called during application shutdown.

Shutdown Process

1. Set atomic shutdown flag (stops new operations)
2. Signal condvar to wake keep-alive thread immediately
3. Wait for keep-alive thread to exit (with timeout)
4. Abort all replacement creation tasks
5. Wait briefly for cleanup
6. Log final statistics

Timeout

Keep-alive thread is given 5 seconds to exit gracefully. If it doesn’t exit, we log an error but continue shutdown.

Example

let mut pool = /* ... */;

// During application shutdown
pool.shutdown_async().await;

pub fn shutdown(&mut self)

Synchronously shutdown the pool (fallback method).

This is a simplified shutdown for use in Drop or non-async contexts. Prefer shutdown_async() when possible for cleaner task cancellation.

Note

This method doesn’t wait for replacement tasks to finish since there’s no async runtime available. Tasks are aborted but may not have cleaned up yet.

Trait Implementations

impl BrowserPoolActixExt for BrowserPool

fn into_actix_data(self) -> BrowserPoolData

Convert the pool into Actix-web Data wrapper.

impl BrowserPoolAxumExt for BrowserPool

fn into_axum_state(self) -> SharedBrowserPool

Convert the pool into a form suitable for Axum’s with_state().

fn into_axum_extension(self) -> Extension<SharedBrowserPool>

Convert the pool into an Extension layer.

impl BrowserPoolRocketExt for BrowserPool

fn into_rocket_data(self) -> SharedBrowserPool

Convert the pool into a shared reference suitable for Rocket’s managed state.

impl Drop for BrowserPool

fn drop(&mut self)

Automatic cleanup when pool is dropped.

This ensures resources are released even if shutdown wasn’t called explicitly. Uses sync shutdown since Drop can’t be async.