stygian_browser/
lib.rs

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

stygian_browser/
lib.rs
