stygian_proxy/
lib.rs

1//! # stygian-proxy
2#![allow(clippy::multiple_crate_versions)]
3//!
4//! High-performance, resilient proxy rotation for the Stygian scraping ecosystem.
5//!
6//! ## Features
7//!
8//! - Pluggable rotation strategies: round-robin, random, weighted, least-used
9//! - `bayesian-rotation` feature: Thompson-sampling bandit strategy that
10//!   learns per-proxy health online. Cites 76 % success vs 36 % round-robin
11//!   on identical proxies in the `ProxyOps` benchmark (549 114 requests / 7 days).
12//!   See `crate::strategy::ThompsonStrategy` and the strategy module
13//!   docs for the 76 % / 36 % citation.
14//! - Per-proxy latency and success-rate tracking via atomics
15//! - Async health checker with configurable intervals
16//! - Per-proxy circuit breaker (`Closed -> Open -> HalfOpen`)
17//! - In-memory proxy pool (no external DB required)
18//! - `graph` feature: `ProxyManagerPort` trait for stygian-graph HTTP adapters
19//!   (see `crate::graph`; only compiled with `--features graph`)
20//! - `browser` feature: per-context proxy binding for stygian-browser
21//! - `vendor-stickiness` feature: per-vendor session stickiness policy.
22//!   Encodes the 2026 guide anti-bot stickiness matrix
23//!   (`Akamai` → 30min sticky, `Cloudflare` → 5min sticky,
24//!   `Imperva` → 15min sticky, `PerimeterX` / `Kasada` → fresh per
25//!   domain, `DataDome` → fresh per request, everything else → fresh
26//!   per request) into a typed [`VendorStickinessMap`] consulted by
27//!   [`SessionMap::acquire_session`](crate::session::SessionMap::acquire_session)
28//!   and
29//!   [`ProxyManager::acquire_for_domain_with_vendor`](crate::manager::ProxyManager::acquire_for_domain_with_vendor).
30//!
31//! ## Quick start
32//!
33//! ```rust,no_run
34//! use stygian_proxy::error::ProxyResult;
35//!
36//! fn main() -> ProxyResult<()> {
37//!     // ProxyManager construction added in T12 (proxy-manager task)
38//!     Ok(())
39//! }
40//! ```
41
42pub mod circuit_breaker;
43pub mod error;
44pub mod fetcher;
45pub mod health;
46pub mod manager;
47pub mod ports;
48pub mod session;
49pub mod stickiness;
50pub mod storage;
51pub mod strategy;
52pub mod types;
53pub mod vendor_quirks;
54
55#[cfg(feature = "graph")]
56pub mod graph;
57
58#[cfg(feature = "browser")]
59pub mod browser;
60
61#[cfg(feature = "tls-profiled")]
62pub mod http_client;
63
64pub mod routing;
65
66#[cfg(feature = "coherence-validation")]
67pub mod adapters;
68
69/// MCP (Model Context Protocol) server — exposes proxy pool tools
70#[cfg(feature = "mcp")]
71pub mod mcp;
72
73// Top-level re-exports
74pub use circuit_breaker::{CircuitBreaker, STATE_CLOSED, STATE_HALF_OPEN, STATE_OPEN};
75pub use error::{ProxyError, ProxyResult};
76#[cfg(feature = "dns-fetcher")]
77pub use fetcher::DnsTxtFetcher;
78pub use fetcher::{
79    FreeApiProxiesFetcher, FreeListFetcher, FreeListSource, ProxyFetcher, load_from_fetcher,
80};
81pub use health::{HealthChecker, HealthMap};
82pub use manager::{PoolStats, ProxyHandle, ProxyManager, ProxyManagerBuilder};
83pub use session::{SessionDecision, SessionMap, StickyPolicy};
84pub use stickiness::{StickinessPolicy, VendorStickinessMap};
85pub use storage::MemoryProxyStore;
86pub use strategy::{
87    BayesianObserver, BoxedBayesianObserver, BoxedRotationStrategy, LeastUsedStrategy,
88    NoopBayesianObserver, ProxyCandidate, RandomStrategy, RotationStrategy, RoundRobinStrategy,
89    WeightedStrategy, capable_healthy_candidates,
90};
91
92#[cfg(feature = "bayesian-rotation")]
93pub use strategy::ThompsonStrategy;
94pub use types::{
95    CapabilityRequirement, IpClass, IpClassRequirement, ProfiledRequestMode, Proxy,
96    ProxyCapabilities, ProxyConfig, ProxyMetrics, ProxyRecord, ProxyType, RoutingPath,
97    TargetVendorCompatibility, TrustTier, VendorId, validate_asn, validate_city,
98    validate_postal_code, well_known,
99};
100pub use vendor_quirks::{
101    BRD_SUPERPROXY_QUIRK, CRAWLERA_8011_QUIRK, IPROYAL_QUIRK, ParseError, ProxyUrl, QuirkMatch,
102    QuirkSeverity, Scheme, VENDOR_QUIRKS, VendorQuirk, ZYTE_8011_QUIRK, check,
103};
104
105#[cfg(feature = "graph")]
106pub use graph::{BoxedProxyManager, NoopProxyManager, ProxyManagerPort};
107
108#[cfg(feature = "browser")]
109pub use browser::{BrowserProxySource, ProxyManagerBridge};
110
111#[cfg(feature = "tls-profiled")]
112pub use http_client::{ProfiledRequester, ProfiledRequesterError};
113
114// Coherence port + adapter re-exports. The trait and supporting types are
115// always compiled (so external adapters can implement `CoherencePort` even
116// when the default `DefaultCoherenceValidator` is off); the adapter itself
117// is feature-gated, mirroring the `BayesianObserver` / `ThompsonStrategy`
118// pattern.
119pub use ports::coherence::{
120    AcceptLanguage, BoxedCoherencePort, CoherenceContext, CoherencePolicy, CoherencePort,
121    CoherenceVerdict, IsoCountry, Locale, MismatchField, MismatchSeverity, Tz,
122};
123
124#[cfg(feature = "coherence-validation")]
125pub use adapters::coherence::DefaultCoherenceValidator;
stygian_proxy/lib.rs

stygian_proxy/
lib.rs
