stygian_browser/
lib.rs

1//! # stygian-browser
2//!
3#![allow(clippy::multiple_crate_versions)]
4//! High-performance, anti-detection browser automation library for Rust.
5//!
6//! Built on Chrome `DevTools` Protocol (CDP) via [`chromiumoxide`](https://github.com/mattsse/chromiumoxide)
7//! with comprehensive stealth features to bypass modern anti-bot systems:
8//! Cloudflare, `DataDome`, `PerimeterX`, and Akamai Bot Manager.
9//!
10//! ## Features
11//!
12//! - **Browser pooling** — warm pool with min/max sizing, LRU eviction, and backpressure;
13//!   sub-100 ms acquire from the warm queue
14//! - **Anti-detection** — `navigator` spoofing, canvas noise, WebGL randomisation,
15//!   User-Agent patching, and plugin population
16//! - **Human behaviour** — Bézier-curve mouse paths, human-paced typing with typos,
17//!   random scroll and micro-interactions
18//! - **CDP leak protection** — hides `Runtime.enable` side-effects that expose automation
19//! - **WebRTC control** — block, proxy-route, or allow WebRTC to prevent IP leaks
20//! - **Fingerprint generation** — statistically-weighted device profiles matching
21//!   real-world browser market share distributions
22//! - **Stealth levels** — `None` / `Basic` / `Advanced` for tuning evasion vs performance
23//!
24//! ## Quick Start
25//!
26//! ```rust,no_run
27//! use stygian_browser::{BrowserPool, BrowserConfig, WaitUntil};
28//! use std::time::Duration;
29//!
30//! #[tokio::main]
31//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
32//!     // Default config: headless, Advanced stealth, pool of 2–10 browsers
33//!     let config = BrowserConfig::default();
34//!     let pool = BrowserPool::new(config).await?;
35//!
36//!     // Acquire a browser from the warm pool (< 100 ms)
37//!     let handle = pool.acquire().await?;
38//!
39//!     // Open a tab and navigate
40//!     let mut page = handle.browser().expect("valid browser").new_page().await?;
41//!     page.navigate(
42//!         "https://example.com",
43//!         WaitUntil::Selector("body".to_string()),
44//!         Duration::from_secs(30),
45//!     ).await?;
46//!
47//!     println!("Title: {}", page.title().await?);
48//!
49//!     // Return the browser to the pool
50//!     handle.release().await;
51//!     Ok(())
52//! }
53//! ```
54//!
55//! ## Stealth Levels
56//!
57//! | Level | `navigator` | Canvas | WebGL | CDP protect | Human behavior |
58//! |-------|:-----------:|:------:|:-----:|:-----------:|:--------------:|
59//! | `None` | — | — | — | — | — |
60//! | `Basic` | ✓ | — | — | ✓ | — |
61//! | `Advanced` | ✓ | ✓ | ✓ | ✓ | ✓ |
62//!
63//! ## Module Overview
64//!
65//! | Module | Description |
66//! |--------|-------------|
67//! | [`browser`] | [`BrowserInstance`] — launch, health-check, shutdown |
68//! | [`pool`] | [`BrowserPool`] + [`BrowserHandle`] — warm pool management |
69//! | [`page`] | [`PageHandle`] — navigate, eval, content, cookies |
70//! | [`config`] | [`BrowserConfig`] + builder pattern |
71//! | [`error`] | [`BrowserError`] and [`Result`] alias |
72//! | [`stealth`] | [`StealthProfile`], [`NavigatorProfile`] |
73//! | [`fingerprint`] | [`DeviceProfile`], [`BrowserKind`] |
74//! | [`behavior`] | [`behavior::MouseSimulator`], [`behavior::TypingSimulator`] |
75//! | [`webrtc`] | [`WebRtcConfig`], [`WebRtcPolicy`], [`ProxyLocation`] |
76//! | [`cdp_protection`] | CDP leak protection modes |
77
78pub mod browser;
79pub mod cdp_protection;
80pub mod config;
81pub mod error;
82pub mod page;
83pub mod pool;
84
85#[cfg(feature = "stealth")]
86pub mod stealth;
87
88#[cfg(feature = "stealth")]
89pub mod behavior;
90
91#[cfg(feature = "stealth")]
92pub mod fingerprint;
93
94#[cfg(feature = "stealth")]
95pub mod webrtc;
96
97#[cfg(feature = "mcp")]
98pub mod mcp;
99
100#[cfg(feature = "metrics")]
101pub mod metrics;
102
103pub mod session;
104
105pub mod recorder;
106
107// Re-exports for convenience
108pub use browser::BrowserInstance;
109pub use config::BrowserConfig;
110pub use error::{BrowserError, Result};
111pub use page::{PageHandle, ResourceFilter, WaitUntil};
112pub use pool::{BrowserHandle, BrowserPool, PoolStats};
113
114#[cfg(feature = "stealth")]
115pub use stealth::{NavigatorProfile, StealthConfig, StealthProfile};
116
117#[cfg(feature = "stealth")]
118pub use behavior::InteractionLevel;
119pub use fingerprint::{BrowserKind, DeviceProfile};
120
121#[cfg(feature = "stealth")]
122pub use webrtc::{ProxyLocation, WebRtcConfig, WebRtcPolicy};
123
124/// Prelude module for convenient imports
125pub mod prelude {
126    pub use crate::config::BrowserConfig;
127    pub use crate::error::{BrowserError, Result};
128    pub use crate::pool::{BrowserHandle, BrowserPool, PoolStats};
129
130    #[cfg(feature = "stealth")]
131    pub use crate::stealth::{NavigatorProfile, StealthConfig, StealthProfile};
132}
stygian_browser/lib.rs

stygian_browser/
lib.rs
