use std::path::Path;
#[cfg(feature = "tier-b-toml")]
use std::path::PathBuf;
#[cfg(feature = "tier-b-toml")]
use std::time::SystemTime;
use serde::{Deserialize, Serialize};
use thiserror::Error;
#[cfg(feature = "pacing")]
use crate::pacing::{BoundedNormalDelay, RequestPacer};
#[cfg(feature = "rotation")]
use crate::rotation::RotationPolicy;
#[derive(Debug, Clone, Error, PartialEq, Eq)]
pub enum ConfigError {
#[error("failed to read config file: {0}")]
Read(String),
#[error("failed to parse config TOML: {0}")]
TomlParse(String),
#[error("invalid pacing bounds: min {min_ms} ms is greater than max {max_ms} ms")]
InvalidPacingBounds {
min_ms: u64,
max_ms: u64,
},
#[error("invalid Tier-B persona: {0}")]
Profile(String),
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
#[serde(default)]
pub struct GuiseConfig {
#[cfg(feature = "rotation")]
pub rotation: RotationConfig,
#[cfg(feature = "pacing")]
pub pacing: PacingConfig,
pub pool: PoolConfig,
}
impl GuiseConfig {
pub fn from_toml_file(path: impl AsRef<Path>) -> Result<Self, ConfigError> {
let raw = std::fs::read_to_string(path.as_ref())
.map_err(|e| ConfigError::Read(format!("{}: {e}", path.as_ref().display())))?;
Self::from_toml_str(&raw)
}
pub fn from_toml_str(s: &str) -> Result<Self, ConfigError> {
toml::from_str(s).map_err(|e| ConfigError::TomlParse(e.to_string()))
}
#[cfg(all(feature = "rotation", feature = "fingerprint"))]
#[must_use]
pub fn to_pool_config(self) -> crate::persona_pool::PoolConfig {
crate::persona_pool::PoolConfig {
rotation_policy: self.rotation.to_policy(),
max_concurrent_sessions: self.pool.max_concurrent_sessions,
}
}
#[cfg(feature = "pacing")]
#[must_use]
pub fn request_pacer(self) -> RequestPacer {
self.pacing.page_load_pacer()
}
#[cfg(feature = "rotation")]
#[must_use]
pub fn with_rotation_policy(mut self, policy: RotationPolicyName) -> Self {
self.rotation.policy = policy;
self
}
#[cfg(feature = "rotation")]
#[must_use]
pub fn with_per_requests_n(mut self, n: u64) -> Self {
self.rotation.per_requests_n = n;
self
}
#[must_use]
pub fn with_max_concurrent_sessions(mut self, limit: usize) -> Self {
self.pool.max_concurrent_sessions = limit;
self
}
#[cfg(feature = "pacing")]
pub fn with_pacing_page_load_ms(
mut self,
min_ms: u64,
max_ms: u64,
) -> Result<Self, ConfigError> {
self.pacing.page_load_ms = validate_bounds(min_ms, max_ms)?;
Ok(self)
}
#[cfg(feature = "pacing")]
pub fn with_pacing_sub_resource_ms(
mut self,
min_ms: u64,
max_ms: u64,
) -> Result<Self, ConfigError> {
self.pacing.sub_resource_ms = validate_bounds(min_ms, max_ms)?;
Ok(self)
}
#[cfg(feature = "pacing")]
pub fn with_pacing_api_call_ms(
mut self,
min_ms: u64,
max_ms: u64,
) -> Result<Self, ConfigError> {
self.pacing.api_call_ms = validate_bounds(min_ms, max_ms)?;
Ok(self)
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(default)]
pub struct RotationConfig {
pub policy: RotationPolicyName,
pub per_requests_n: u64,
}
impl Default for RotationConfig {
fn default() -> Self {
Self {
policy: RotationPolicyName::PerSession,
per_requests_n: 0,
}
}
}
impl RotationConfig {
#[cfg(feature = "rotation")]
#[must_use]
pub fn to_policy(self) -> RotationPolicy {
match self.policy {
RotationPolicyName::Never => RotationPolicy::Never,
RotationPolicyName::PerSession => RotationPolicy::PerSession,
RotationPolicyName::PerTarget => RotationPolicy::PerTarget,
RotationPolicyName::PerRequests => RotationPolicy::PerRequests(self.per_requests_n),
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
#[serde(rename_all = "snake_case")]
pub enum RotationPolicyName {
Never,
#[default]
PerSession,
PerTarget,
PerRequests,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(default)]
pub struct PacingConfig {
pub page_load_ms: (u64, u64),
pub sub_resource_ms: (u64, u64),
pub api_call_ms: (u64, u64),
}
impl Default for PacingConfig {
fn default() -> Self {
Self {
page_load_ms: (800, 3_000),
sub_resource_ms: (100, 400),
api_call_ms: (300, 1_200),
}
}
}
impl PacingConfig {
#[cfg(feature = "pacing")]
#[must_use]
pub fn page_load_pacer(self) -> RequestPacer {
RequestPacer::new(BoundedNormalDelay::from_unordered_bounds(
self.page_load_ms.0,
self.page_load_ms.1,
))
}
#[cfg(feature = "pacing")]
#[must_use]
pub fn sub_resource_pacer(self) -> RequestPacer {
RequestPacer::new(BoundedNormalDelay::from_unordered_bounds(
self.sub_resource_ms.0,
self.sub_resource_ms.1,
))
}
#[cfg(feature = "pacing")]
#[must_use]
pub fn api_call_pacer(self) -> RequestPacer {
RequestPacer::new(BoundedNormalDelay::from_unordered_bounds(
self.api_call_ms.0,
self.api_call_ms.1,
))
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
#[serde(default)]
pub struct PoolConfig {
pub max_concurrent_sessions: usize,
}
fn validate_bounds(min_ms: u64, max_ms: u64) -> Result<(u64, u64), ConfigError> {
if min_ms > max_ms {
return Err(ConfigError::InvalidPacingBounds { min_ms, max_ms });
}
Ok((min_ms, max_ms))
}
#[cfg(feature = "tier-b-toml")]
#[derive(Debug, Clone)]
pub struct TierBPersonaDir {
path: PathBuf,
last_mtime: Option<SystemTime>,
profiles: Vec<crate::fingerprint::ProfileBundle>,
}
#[cfg(feature = "tier-b-toml")]
impl TierBPersonaDir {
#[must_use]
pub fn new(path: impl Into<PathBuf>) -> Self {
Self {
path: path.into(),
last_mtime: None,
profiles: Vec::new(),
}
}
#[must_use]
pub fn profiles(&self) -> &[crate::fingerprint::ProfileBundle] {
&self.profiles
}
pub fn scan(&mut self) -> Result<&[crate::fingerprint::ProfileBundle], ConfigError> {
self.profiles.clear();
let mut latest: Option<SystemTime> = None;
let entries = std::fs::read_dir(&self.path)
.map_err(|e| ConfigError::Read(format!("{}: {e}", self.path.display())))?;
for entry in entries {
let entry = entry.map_err(|e| ConfigError::Read(e.to_string()))?;
let path = entry.path();
if path.extension().and_then(|e| e.to_str()) != Some("toml") {
continue;
}
let mtime = entry
.metadata()
.and_then(|m| m.modified())
.map_err(|e| ConfigError::Read(format!("{}: {e}", path.display())))?;
latest = Some(latest.map_or(mtime, |t| t.max(mtime)));
let bundle = crate::fingerprint::ProfileBundle::from_toml(&path)
.map_err(|e| ConfigError::Profile(format!("{}: {e}", path.display())))?;
self.profiles.push(bundle);
}
self.last_mtime = latest;
Ok(&self.profiles)
}
pub fn reload_if_changed(&mut self) -> Result<bool, ConfigError> {
let current = self.latest_mtime()?;
if current != self.last_mtime {
self.scan()?;
Ok(true)
} else {
Ok(false)
}
}
fn latest_mtime(&self) -> Result<Option<SystemTime>, ConfigError> {
let entries = std::fs::read_dir(&self.path)
.map_err(|e| ConfigError::Read(format!("{}: {e}", self.path.display())))?;
let mut latest: Option<SystemTime> = None;
for entry in entries {
let entry = entry.map_err(|e| ConfigError::Read(e.to_string()))?;
let path = entry.path();
if path.extension().and_then(|e| e.to_str()) != Some("toml") {
continue;
}
let mtime = entry
.metadata()
.and_then(|m| m.modified())
.map_err(|e| ConfigError::Read(format!("{}: {e}", path.display())))?;
latest = Some(latest.map_or(mtime, |t| t.max(mtime)));
}
Ok(latest)
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn defaults_match_expected() {
let cfg = GuiseConfig::default();
#[cfg(feature = "rotation")]
{
assert_eq!(cfg.rotation.policy, RotationPolicyName::PerSession);
assert_eq!(cfg.rotation.per_requests_n, 0);
}
#[cfg(feature = "pacing")]
{
assert_eq!(cfg.pacing.page_load_ms, (800, 3_000));
assert_eq!(cfg.pacing.sub_resource_ms, (100, 400));
assert_eq!(cfg.pacing.api_call_ms, (300, 1_200));
}
assert_eq!(cfg.pool.max_concurrent_sessions, 0);
}
#[test]
fn toml_round_trip_preserves_values() {
let cfg = GuiseConfig::default()
.with_rotation_policy(RotationPolicyName::PerRequests)
.with_per_requests_n(50)
.with_max_concurrent_sessions(4)
.with_pacing_page_load_ms(900, 2_800)
.unwrap()
.with_pacing_sub_resource_ms(150, 350)
.unwrap()
.with_pacing_api_call_ms(400, 1_000)
.unwrap();
let toml = toml::to_string(&cfg).expect("serializable");
let parsed = GuiseConfig::from_toml_str(&toml).expect("round-trippable");
assert_eq!(parsed, cfg);
}
#[test]
fn from_toml_str_parses_rotation_and_pacing() {
let s = r#"
[rotation]
policy = "per_requests"
per_requests_n = 100
[pacing]
page_load_ms = [700, 2500]
sub_resource_ms = [80, 300]
api_call_ms = [250, 900]
[pool]
max_concurrent_sessions = 16
"#;
let cfg = GuiseConfig::from_toml_str(s).unwrap();
#[cfg(feature = "rotation")]
{
assert_eq!(cfg.rotation.policy, RotationPolicyName::PerRequests);
assert_eq!(cfg.rotation.per_requests_n, 100);
assert_eq!(cfg.rotation.to_policy(), RotationPolicy::PerRequests(100));
}
#[cfg(feature = "pacing")]
{
assert_eq!(cfg.pacing.page_load_ms, (700, 2_500));
assert_eq!(cfg.pacing.sub_resource_ms, (80, 300));
assert_eq!(cfg.pacing.api_call_ms, (250, 900));
}
assert_eq!(cfg.pool.max_concurrent_sessions, 16);
}
#[test]
fn cli_overrides_take_precedence_over_defaults() {
let cfg = GuiseConfig::default()
.with_rotation_policy(RotationPolicyName::Never)
.with_per_requests_n(7)
.with_max_concurrent_sessions(12)
.with_pacing_page_load_ms(1_000, 2_000)
.unwrap();
#[cfg(feature = "rotation")]
{
assert_eq!(cfg.rotation.policy, RotationPolicyName::Never);
assert_eq!(cfg.rotation.per_requests_n, 7);
}
assert_eq!(cfg.pool.max_concurrent_sessions, 12);
#[cfg(feature = "pacing")]
{
assert_eq!(cfg.pacing.page_load_ms, (1_000, 2_000));
}
}
#[test]
fn precedence_default_then_file_then_cli() {
assert_eq!(GuiseConfig::default().pacing.page_load_ms, (800, 3_000));
let file = GuiseConfig::from_toml_str(
"[pacing]\npage_load_ms = [600, 2000]\n[rotation]\npolicy = \"per_target\"\n",
)
.unwrap();
#[cfg(feature = "pacing")]
assert_eq!(file.pacing.page_load_ms, (600, 2_000));
#[cfg(feature = "rotation")]
assert_eq!(file.rotation.policy, RotationPolicyName::PerTarget);
let cli = file
.with_rotation_policy(RotationPolicyName::Never)
.with_pacing_page_load_ms(500, 1_500)
.unwrap();
#[cfg(feature = "rotation")]
assert_eq!(cli.rotation.policy, RotationPolicyName::Never);
#[cfg(feature = "pacing")]
assert_eq!(cli.pacing.page_load_ms, (500, 1_500));
}
#[test]
fn invalid_pacing_bounds_are_rejected() {
let err = GuiseConfig::default()
.with_pacing_page_load_ms(3_000, 800)
.unwrap_err();
assert!(matches!(
err,
ConfigError::InvalidPacingBounds {
min_ms: 3_000,
max_ms: 800
}
));
}
#[cfg(all(feature = "rotation", feature = "fingerprint"))]
#[test]
fn to_pool_config_matches_rotation_policy() {
let cfg = GuiseConfig::default()
.with_rotation_policy(RotationPolicyName::PerTarget)
.with_max_concurrent_sessions(8);
let pool = cfg.to_pool_config();
assert_eq!(pool.rotation_policy, RotationPolicy::PerTarget);
assert_eq!(pool.max_concurrent_sessions, 8);
}
#[cfg(feature = "pacing")]
#[test]
fn request_pacer_uses_configured_page_load_bounds() {
let cfg = GuiseConfig::default()
.with_pacing_page_load_ms(900, 1_100)
.unwrap();
let pacer = cfg.request_pacer();
assert_eq!(pacer.challenge_multiplier(), 1);
}
#[cfg(all(feature = "tier-b-toml", feature = "rotation"))]
#[test]
fn tier_b_dir_scans_toml_files() {
let dir = std::env::temp_dir().join(format!("guise-tier-b-{}-a", std::process::id()));
let _ = std::fs::remove_dir_all(&dir);
std::fs::create_dir_all(&dir).unwrap();
std::fs::write(
dir.join("a.toml"),
"browser = \"chrome-win\"\ntls = \"chrome131\"\n",
)
.unwrap();
let mut watcher = TierBPersonaDir::new(&dir);
let profiles = watcher.scan().unwrap();
assert_eq!(profiles.len(), 1);
assert_eq!(
profiles[0].browser,
crate::fingerprint::StealthProfile::ChromeWindowsStable
);
let _ = std::fs::remove_dir_all(&dir);
}
#[cfg(all(feature = "tier-b-toml", feature = "rotation"))]
#[test]
fn tier_b_reload_detects_new_file() {
let dir = std::env::temp_dir().join(format!("guise-tier-b-{}-b", std::process::id()));
let _ = std::fs::remove_dir_all(&dir);
std::fs::create_dir_all(&dir).unwrap();
std::fs::write(
dir.join("a.toml"),
"browser = \"chrome-win\"\ntls = \"chrome131\"\n",
)
.unwrap();
let mut watcher = TierBPersonaDir::new(&dir);
watcher.scan().unwrap();
assert_eq!(watcher.profiles().len(), 1);
std::fs::write(
dir.join("b.toml"),
"browser = \"firefox\"\ntls = \"firefox133\"\n",
)
.unwrap();
let reloaded = watcher.reload_if_changed().unwrap();
assert!(reloaded, "new persona file should trigger a reload");
assert_eq!(watcher.profiles().len(), 2);
let _ = std::fs::remove_dir_all(&dir);
}
}