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//!
7//! Browser automation and stealth tooling for sites protected by Cloudflare,
8//! `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** — User-Agent patching and plugin population
15//! - **Human behaviour** — Bézier-curve mouse paths, human-paced typing with typos,
16//!   random scroll and micro-interactions
17//! - **Fingerprint generation** — statistically-weighted device profiles matching
18//!   real-world browser market share distributions
19//!
20//! ## Quick Start
21//!
22//! ```rust,no_run
23//! use stygian_browser::{BrowserPool, BrowserConfig, WaitUntil};
24//! use std::time::Duration;
25//!
26//! # async fn run() -> Result<(), Box<dyn std::error::Error>> {
27//!     // Default config: headless, Advanced stealth, pool of 2–10 browsers
28//!     let config = BrowserConfig::default();
29//!     let pool = BrowserPool::new(config).await?;
30//!
31//!     // Acquire a browser from the warm pool (< 100 ms)
32//!     let handle = pool.acquire().await?;
33//!
34//!     // Open a tab and navigate
35//!     let mut page = handle.browser().expect("valid browser").new_page().await?;
36//!     page.navigate(
37//!         "https://example.com",
38//!         WaitUntil::DomContentLoaded,
39//!         Duration::from_secs(30),
40//!     ).await?;
41//!
42//!     println!("Title: {}", page.title().await?);
43//!
44//!     handle.release().await;
45//!     Ok(())
46//! # }
47//! ```
48//!
49//! ## Stealth Levels
50//!
51//! | Level | Navigator spoof | Canvas noise | WebGL random | CDP protection | Human behavior |
52//! | ----- | --------------- | ------------ | ------------ | -------------- | -------------- |
53//! | `None` | — | — | — | — | — |
54//! | `Basic` | ✓ | — | — | ✓ | — |
55//! | `Advanced` | ✓ | ✓ | ✓ | ✓ | ✓ |
56//!
57//! ## Module Overview
58//!
59//! | Module | Description |
60//! | -------- | ------------- |
61//! | [`browser`] | [`BrowserInstance`] — launch, health-check, shutdown |
62//! | [`pool`] | [`BrowserPool`] + [`BrowserHandle`] — warm pool management |
63//! | [`page`] | [`PageHandle`] — navigate, eval, content, cookies |
64//! | [`config`] | [`BrowserConfig`] + builder pattern |
65//! | [`error`] | [`BrowserError`] and [`Result`] alias |
66//! | [`fingerprint`] | [`DeviceProfile`], [`BrowserKind`] |
67//! | [`webrtc`] | [`WebRtcConfig`], [`WebRtcPolicy`], [`ProxyLocation`] |
68//! | [`cdp_protection`] | CDP leak protection modes |
69
70pub mod acquisition;
71pub mod behavior_adapter;
72pub mod browser;
73pub mod cdp_protection;
74pub mod config;
75pub mod error;
76pub mod page;
77pub mod pool;
78pub mod proxy;
79
80#[cfg(feature = "extract")]
81pub mod extract;
82
83#[cfg(feature = "extract")]
84pub use extract::Extractable;
85
86#[cfg(feature = "similarity")]
87pub mod similarity;
88
89#[cfg(feature = "similarity")]
90pub use similarity::{ElementFingerprint, SimilarMatch, SimilarityConfig};
91
92#[cfg(feature = "stealth")]
93pub mod stealth;
94
95#[cfg(feature = "stealth")]
96pub mod behavior;
97
98#[cfg(feature = "stealth")]
99pub mod fingerprint;
100
101#[cfg(feature = "stealth")]
102pub mod tls;
103
104#[cfg(feature = "stealth")]
105pub mod webrtc;
106
107#[cfg(feature = "stealth")]
108pub mod noise;
109
110#[cfg(feature = "stealth")]
111pub mod canvas_noise;
112
113#[cfg(feature = "stealth")]
114pub mod webgl_noise;
115
116#[cfg(feature = "stealth")]
117pub mod audio_noise;
118
119#[cfg(feature = "stealth")]
120pub mod rects_noise;
121
122#[cfg(feature = "stealth")]
123pub mod cdp_hardening;
124
125#[cfg(feature = "stealth")]
126pub mod peripheral_stealth;
127
128#[cfg(feature = "stealth")]
129pub mod validation;
130
131pub mod tls_validation;
132
133#[cfg(feature = "stealth")]
134pub mod profile;
135
136#[cfg(feature = "stealth")]
137pub mod navigator_coherence;
138
139#[cfg(feature = "stealth")]
140pub mod timing_noise;
141
142#[cfg(feature = "stealth")]
143pub mod diagnostic;
144
145#[cfg(feature = "mcp")]
146pub mod mcp;
147
148#[cfg(feature = "metrics")]
149pub mod metrics;
150
151pub mod session;
152
153pub mod recorder;
154
155pub use acquisition::{
156    AcquisitionMode, AcquisitionRequest, AcquisitionResult, AcquisitionRunner, StageFailure,
157    StageFailureKind, StrategyUsed,
158};
159pub use behavior_adapter::{
160    AdapterKind, AppliedBehaviorPlan, BehaviorInteractionLevel, BrowserBehaviorAdapter,
161    ExecutionMode, PolymorphicBehaviorAdapter, SessionMode, TelemetryLevel,
162};
163pub use browser::BrowserInstance;
164pub use config::{BrowserConfig, HeadlessMode, StealthLevel};
165pub use error::{BrowserError, Result};
166pub use page::{NodeHandle, PageHandle, ResourceFilter, WaitUntil};
167pub use pool::{BrowserHandle, BrowserPool, PoolStats};
168pub use proxy::{DirectLease, ProxyLease, ProxySource};
169
170#[cfg(feature = "stealth")]
171pub use stealth::{NavigatorProfile, StealthConfig, StealthProfile};
172
173#[cfg(feature = "stealth")]
174pub use behavior::InteractionLevel;
175#[cfg(feature = "stealth")]
176pub use behavior::RequestPacer;
177#[cfg(feature = "stealth")]
178pub use fingerprint::{BrowserKind, DeviceProfile};
179
180#[cfg(feature = "stealth")]
181pub use webrtc::{ProxyLocation, WebRtcConfig, WebRtcPolicy};
182
183pub mod prelude {
184    pub use crate::config::BrowserConfig;
185    pub use crate::error::{BrowserError, Result};
186    pub use crate::pool::{BrowserHandle, BrowserPool, PoolStats};
187
188    #[cfg(feature = "stealth")]
189    pub use crate::stealth::{NavigatorProfile, StealthConfig, StealthProfile};
190}
stygian_browser/lib.rs

stygian_browser/
lib.rs
