stygian_browser/
lib.rs

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

stygian_browser/
lib.rs
