Struct CloudScraper 

pub struct CloudScraper {
    pub profile: BrowserProfile,
    pub proxy: Option<Arc<TlsSpoofingProxy>>,
    /* private fields */
}

The main entry point for managing a stealthy browser instance.

CloudScraper wraps a headless_chrome::Browser and injects stealth configurations (via BrowserProfile and stealth JavaScript scripts) to make scraping tasks highly undetectable by modern bot-protection systems.

Fields

profile: BrowserProfile

The browser profile (fingerprint) being used.

proxy: Option<Arc<TlsSpoofingProxy>>

The local TLS MITM proxy instance (kept alive with the scraper)

Implementations

impl CloudScraper

pub fn builder() -> CloudScraperBuilder

Start building a CloudScraper instance.

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

Creates a new stealthy tab ready for navigation.

Injects the stealth script (with navigator.languages matching the active locale) and applies the locale’s Accept-Language/timezone/locale via CDP so the browser’s geo signals stay coherent with the egress proxy’s country.

pub fn detect_challenge(&self, tab: &Arc<Tab>) -> Result<ChallengeSignal, Error>

Classifies the challenge (if any) currently rendered in tab.

Detection runs over the tab’s rendered DOM. HTTP status/headers are not available from the DOM, so they are left unset — body markers are sufficient to recognise Cloudflare’s interstitial and Turnstile pages.

pub fn solve_challenge(&self, tab: &Arc<Tab>) -> Result<ChallengeSignal, Error>

Detects and attempts to clear any bot-protection challenge on tab.

Loops according to the configured MitigationPolicy: it waits for non-interactive challenges to auto-resolve in the real browser, and for an interactive Turnstile it makes a best-effort click via GenericSolver before waiting. Returns the final ChallengeSignal once the page is clear, or Error::Challenge if the budget is exhausted or the page is hard-blocked.

Blocking

Like the rest of this CDP-driven API, this is a synchronous, blocking call: it uses std::thread::sleep for back-off and blocks on CDP I/O. On an async runtime, call it from a blocking context (tokio::task::spawn_blocking), and run the TlsSpoofingProxy on a multi-threaded runtime — otherwise a back-off can starve the executor that serves the proxy the page is loading through.

pub fn domain_state(&self, host: &str) -> Result<Option<DomainState>, Error>

Reads the persisted DomainState for host, if a store is configured and a record exists.

pub fn record_outcome(&self, host: &str, outcome: Outcome) -> Result<(), Error>

Records outcome for host in the configured state store (no-op if none).

The current egress proxy is captured, and a Outcome::RateLimited sets a cooldown so callers can back off via Self::cooldown_remaining.

pub fn cooldown_remaining(&self, host: &str) -> Result<Option<Duration>, Error>

Remaining rate-limit cooldown for host, if any.

pub fn rotate_profile(self) -> Result<CloudScraper, Error>

Rotates the browser fingerprint by relaunching Chrome under a fresh random BrowserProfile. See Self::rotate_profile_with.

pub fn rotate_profile_with( self, profile: BrowserProfile, ) -> Result<CloudScraper, Error>

Rotates the browser fingerprint to profile, keeping the same egress IP.

Profile rotation cannot be done in place — the User-Agent and other launch flags are fixed at process start — so this relaunches Chrome and returns a fresh scraper, discarding the old browser and all its tabs/session state. The MITM proxy (and its port) and the current upstream proxy are preserved; only the impersonation client and browser are rebuilt for the new identity.

Because it consumes self, it is necessarily caller-driven (it cannot run inside the tab-scoped Self::solve_challenge). Use it when a site has blocked the browser identity rather than the IP; for a burned IP the automatic proxy rotation inside Self::solve_challenge handles it without a relaunch.

pub fn human_type_str(tab: &Arc<Tab>, text: &str) -> Result<(), Error>

Types a string into the current focused element with human-like delays

pub fn human_move_mouse( tab: &Arc<Tab>, end_x: f64, end_y: f64, ) -> Result<(), Error>

Moves the mouse to a target x,y using Bezier curves to evade bot detection