runtime_foxdriver/
lib.rs

1//! # runtime-foxdriver
2//!
3//! [![santh status](https://img.shields.io/badge/santh-beta-blue)](https://santh.dev/standard)
4//!
5//! Firefox browser automation via WebDriver BiDi (`rustenium`).
6//!
7//! This crate provides a spawn-capable Firefox runtime: launch, drive, evaluate,
8//! click, type, scroll, screenshot, cookies, dialogs, and cross-origin frame graphs.
9//! It is intentionally **independent** of `guise` (the stealth substrate) so the fleet's
10//! layering stays one-way: guise may depend on `foxdriver` for its browser feature,
11//! but `foxdriver` knows nothing about stealth profiles, fingerprint bundles, or TLS impersonation.
12//!
13//! ## Quick start
14//!
15//! ```rust,no_run
16//! use runtime_foxdriver::{drive_browser, BrowserDriveOptions};
17//!
18//! #[tokio::main]
19//! async fn main() -> anyhow::Result<()> {
20//!     drive_browser("https://example.com", BrowserDriveOptions::default(), |page| async move {
21//!         let res = page.evaluate("document.title").await?;
22//!         let title: String = res.into_value()?;
23//!         println!("Page title: {title}");
24//!         Ok(())
25//!     }).await
26//! }
27//! ```
28//!
29//! ## When to use / when not to use
30//!
31//! ### When to use
32//! - Driving Firefox browsers natively via WebDriver BiDi for automation or scanning.
33//! - Capturing passive network traffic, JS dialogs, page downloads, and DOM security signals.
34//! - Traversing cross-origin iframe hierarchies and translating frame coordinates to main viewport space.
35//!
36//! ### When not to use
37//! - You need stealth/fingerprint spoofing directly: use `guise::browser` (which wraps `foxdriver` with stealth profiles).
38//! - You need Chromium / Playwright / CDP-specific driver bindings: use the corresponding runtime driver crate.
39//!
40//! ## Compared to alternatives
41//!
42//! Unlike raw selenium or marionette drivers, `runtime-foxdriver` uses WebDriver BiDi event streams for async, non-blocking telemetry and robust readiness-polled browser launches.
43//!
44//! Compared to headless chromium drivers, Firefox via BiDi provides native gecko rendering, full cross-origin OOPIF frame graph traversal, and clean SIGTERM graceful profile persistence before shutdown.
45//!
46//! ## How it fits in Santh
47//!
48//! `runtime-foxdriver` lives in `libs/runtime` as the primary Firefox browser driver primitive in Santh. Higher-level automation tools and stealth engines (such as `guise`) build on top of `runtime-foxdriver`.
49//!
50//! ## License
51//!
52//! MIT OR Apache-2.0
53
54#![forbid(unsafe_code)]
55#![warn(missing_docs)]
56#![warn(clippy::pedantic)]
57#![cfg_attr(
58    not(test),
59    deny(
60        clippy::unwrap_used,
61        clippy::expect_used,
62        clippy::todo,
63        clippy::unimplemented,
64        clippy::panic
65    )
66)]
67#![allow(
68    clippy::module_name_repetitions,
69    clippy::must_use_candidate,
70    clippy::missing_errors_doc,
71)]
72
73pub mod browser;
74pub mod cookies;
75pub mod dialog;
76pub mod frame;
77pub mod frame_graph;
78pub mod network;
79pub mod runtime;
80pub mod sensors;
81
82// Re-export the most common types at the crate root for ergonomics.
83pub use browser::{
84    launch_firefox, launch_firefox_self_managed, proxy_prefs, Element, EvaluationResult,
85    FoxBrowserConfig, FrameId, FrameInfo, FrameTreeNode, Page, ProxyConfig, ProxyScheme,
86    ScrollDirection,
87};
88pub use cookies::CapturedCookie;
89pub use dialog::{CapturedDialog, CapturedDownload, DialogLog};
90pub use frame_graph::{FrameGraph, FrameNode};
91pub use network::{
92    CapturedHeader, CapturedRequest, CapturedResponse, Filter, NetworkEntry, NetworkLog,
93};
94pub use runtime::{drive_browser, BrowserDriveOptions};
runtime_foxdriver/lib.rs

runtime_foxdriver/
lib.rs
