Struct BrowserHandle 

pub struct BrowserHandle { /* private fields */ }

RAII handle for browser instances.

Automatically returns the browser to the pool when dropped. This ensures browsers are always returned even if the code panics.

Thread Safety

BrowserHandle is Send but not Sync. This means:

• ✅ You can move it to another thread
• ❌ You cannot share it between threads simultaneously

This matches the typical usage pattern where a single request/task uses a browser exclusively.

Usage

let browser_handle = pool.get()?;

// Use browser via Deref
let tab = browser_handle.new_tab()?;
// ... do work ...

// Browser automatically returned to pool when handle goes out of scope

Explicit Drop

If you need to return the browser early (before end of scope), you can explicitly drop the handle:

let browser = pool.get()?;
let tab = browser.new_tab()?;
// ... do work ...

// Return browser early
drop(browser);

// Browser is now back in the pool and available for others
// Attempting to use `browser` here would be a compile error

Panic Safety

The RAII pattern ensures browsers are returned even during panics:

let browser = pool.get()?;

// Even if this panics...
some_function_that_might_panic();

// ...the browser is still returned to the pool during unwinding

Implementations

impl BrowserHandle

pub fn id(&self) -> u64

Get the browser’s unique ID.

Useful for logging and debugging.

Returns

The unique ID assigned to this browser instance.

Example

let browser = pool.get()?;
log::info!("Using browser {}", browser.id());

pub fn age(&self) -> Duration

Get the browser’s age (time since creation).

Useful for monitoring and debugging.

Returns

Duration since the browser was created.

Example

let browser = pool.get()?;
log::debug!("Browser age: {:?}", browser.age());

pub fn age_minutes(&self) -> u64

Get the browser’s age in minutes.

Convenience method for human-readable logging.

Example

let browser = pool.get()?;
log::info!("Browser {} is {} minutes old", browser.id(), browser.age_minutes());

Methods from Deref<Target = Browser>

pub fn get_process_id(&self) -> Option<u32>

pub fn get_ws_url(&self) -> String

pub fn get_tabs(&self) -> &Arc<Mutex<Vec<Arc<Tab>>>>

The tabs are behind an Arc and Mutex because they’re accessible from multiple threads (including the one that handles incoming protocol events about new or changed tabs).

pub fn wait_for_initial_tab(&self) -> Result<Arc<Tab>, Error>

👎Deprecated since 1.0.4: Use new_tab() instead.

Chrome always launches with at least one tab. The reason we have to ‘wait’ is because information about that tab isn’t available immediately after starting the process. Tabs are behind Arcs because they each have their own thread which handles events and method responses directed to them.

Wait timeout: 10 secs

pub fn new_tab(&self) -> Result<Arc<Tab>, Error>

Create a new tab and return a handle to it.

If you want to specify its starting options, see new_tab_with_options.

let first_tab = browser.new_tab()?;
let new_tab = browser.new_tab()?;
let num_tabs = browser.get_tabs().lock().unwrap().len();
assert_eq!(2, num_tabs);

pub fn new_tab_with_options( &self, create_target_params: CreateTarget, ) -> Result<Arc<Tab>, Error>

Create a new tab with a starting url, height / width, context ID and ‘frame control’

   let new_tab = browser.new_tab_with_options(CreateTarget {
   url: "chrome://version",
   width: Some(1024),
   height: Some(800),
   browser_context_id: None,
   enable_begin_frame_control: None,
   })?;

pub fn new_context(&self) -> Result<Context<'_>, Error>

Creates the equivalent of a new incognito window, AKA a browser context

pub fn register_missing_tabs(&self)

Adds tabs that have not been opened with new_tab to the list of tabs

pub fn get_version(&self) -> Result<GetVersionReturnObject, Error>

Get version information

let version_info = browser.get_version()?;
println!("User-Agent is `{}`", version_info.user_agent);

Trait Implementations

impl Debug for BrowserHandle

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

Formats the value using the given formatter.

impl Deref for BrowserHandle

fn deref(&self) -> &Self::Target

Transparently access the underlying Browser.

This allows using all Browser methods directly on the handle:

let browser = pool.get()?;

// new_tab() is a Browser method, but works on BrowserHandle
let tab = browser.new_tab()?;

Panics

Panics if called after the browser has been returned to the pool. This should never happen in normal usage since the handle owns the browser until it’s dropped.

type Target = Browser

The resulting type after dereferencing.

impl Drop for BrowserHandle

fn drop(&mut self)

Automatically return browser to pool when handle is dropped.

This is the critical RAII pattern that ensures browsers are always returned to the pool, even if the code using them panics.

Implementation Details

• Uses Option::take() to move the browser out of the handle
• Calls BrowserPoolInner::return_browser() to return it
• Safe to call multiple times (subsequent calls are no-ops)