use crate::engines::browser_downloader::{BrowserDownloadConfig, BrowserDownloadManager};
use crate::engines::client::tab_pool::TabPool;
use crate::engines::engine_client::EngineError;
use crate::infrastructure::services::config_service::BrowserConfigTrait;
use chromiumoxide::cdp::browser_protocol::browser::BrowserContextId;
use chromiumoxide::cdp::browser_protocol::target::{
CreateBrowserContextParams, CreateTargetParams,
};
use chromiumoxide::{Browser, BrowserConfig, Page};
use futures::StreamExt;
use log::{debug, error, info, warn};
use std::collections::HashMap;
use std::path::PathBuf;
use std::sync::atomic::{AtomicBool, AtomicU64, AtomicUsize, Ordering};
use std::sync::Arc;
use std::time::{Duration, Instant};
use tokio::sync::{mpsc, Mutex, OnceCell, RwLock, Semaphore};
use tokio::task::JoinHandle;
mod launch;
mod pool;
pub use pool::{BrowserInstance, BrowserPool, PooledPage};
#[derive(Debug, Clone)]
pub struct BrowserPoolConfig {
pub max_instances: usize,
pub idle_timeout_secs: u64,
pub health_check_interval_secs: u64,
pub create_timeout_secs: u64,
pub enable_reuse: bool,
pub browser_args: Vec<String>,
pub tab_pool_max_size: usize,
pub context_isolation: bool,
}
impl Default for BrowserPoolConfig {
fn default() -> Self {
Self {
max_instances: 5,
idle_timeout_secs: 300, health_check_interval_secs: 60, create_timeout_secs: 30,
enable_reuse: true,
browser_args: vec![
"--disable-gpu".to_string(),
"--disable-dev-shm-usage".to_string(),
],
tab_pool_max_size: 10,
context_isolation: true,
}
}
}
impl BrowserPoolConfig {
#[must_use]
pub fn docker_safe_args() -> Self {
let mut config = Self::default();
if is_container_environment() {
config.browser_args.push("--no-sandbox".to_string());
info!("Container environment detected, adding --no-sandbox to browser args");
}
config
}
}
fn is_container_environment() -> bool {
if std::path::Path::new("/.dockerenv").exists() {
return true;
}
if let Ok(cgroup) = std::fs::read_to_string("/proc/1/cgroup") {
if cgroup.contains("docker") || cgroup.contains("kubepods") || cgroup.contains("containerd")
{
return true;
}
}
false
}
#[derive(Debug, Clone)]
pub struct BrowserPoolStats {
pub total_instances: usize,
pub available_instances: usize,
pub in_use_instances: usize,
pub max_instances: usize,
}
struct PooledBrowser {
browser: Arc<Browser>,
created_at: Instant,
last_used_at_millis: AtomicU64,
use_count: AtomicU64,
is_healthy: AtomicBool,
instance_id: u64,
tab_pool: Arc<TabPool>,
_permit: tokio::sync::OwnedSemaphorePermit,
}
impl PooledBrowser {
fn new(
browser: Arc<Browser>,
instance_id: u64,
tab_pool_max_size: usize,
permit: tokio::sync::OwnedSemaphorePermit,
) -> Self {
let now = Instant::now();
Self {
browser,
created_at: now,
last_used_at_millis: AtomicU64::new(0),
use_count: AtomicU64::new(0),
is_healthy: AtomicBool::new(true),
instance_id,
tab_pool: Arc::new(TabPool::new(tab_pool_max_size)),
_permit: permit,
}
}
fn touch(&self) {
let elapsed = self.created_at.elapsed();
self.last_used_at_millis
.store(elapsed.as_millis() as u64, Ordering::Release);
self.use_count.fetch_add(1, Ordering::Relaxed);
}
fn last_used(&self) -> Instant {
let millis = self.last_used_at_millis.load(Ordering::Acquire);
self.created_at + Duration::from_millis(millis)
}
fn mark_unhealthy(&self) {
self.is_healthy.store(false, Ordering::Release);
}
fn is_healthy(&self) -> bool {
self.is_healthy.load(Ordering::Acquire)
}
}
impl std::fmt::Debug for PooledBrowser {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("PooledBrowser")
.field("instance_id", &self.instance_id)
.field("created_at", &self.created_at)
.field("use_count", &self.use_count)
.field("is_healthy", &self.is_healthy)
.finish()
}
}
struct ReturnMessage {
instance_id: u64,
browser: Arc<Browser>,
}
struct BrowserPoolState {
config: BrowserPoolConfig,
browser_config: Arc<dyn BrowserConfigTrait>,
available: RwLock<HashMap<u64, Arc<PooledBrowser>>>,
in_use: RwLock<HashMap<u64, Arc<PooledBrowser>>>,
instance_counter: AtomicU64,
total_instances: AtomicUsize,
semaphore: Arc<Semaphore>,
download_manager: Arc<BrowserDownloadManager>,
cleanup_task: Mutex<Option<JoinHandle<()>>>,
return_task: Mutex<Option<JoinHandle<()>>>,
return_sender: Arc<mpsc::Sender<ReturnMessage>>,
return_receiver: Mutex<Option<mpsc::Receiver<ReturnMessage>>>,
shutdown: AtomicBool,
browser_path: OnceCell<PathBuf>,
profile_dir_counter: AtomicU64,
profile_dirs: std::sync::Mutex<Vec<std::path::PathBuf>>,
#[cfg(feature = "engine-moli")]
memory: parking_lot::RwLock<Option<Arc<crate::engines::memory_watermark::MemoryWatermark>>>,
#[cfg(feature = "engine-moli")]
critical_reclaim_done: AtomicBool,
}
fn validate_pool_proxy(proxy: &str) -> Result<String, EngineError> {
const ALLOWED_PROXY_SCHEMES: &[&str] = &["http", "https", "socks5", "socks4"];
crate::utils::proxy::validate_proxy_url(proxy, ALLOWED_PROXY_SCHEMES)
.map_err(|e| EngineError::Other(format!("Invalid proxy URL: {}", e)))
}
impl BrowserPoolState {
fn new(
config: BrowserPoolConfig,
browser_config: Arc<dyn BrowserConfigTrait>,
download_manager: Arc<BrowserDownloadManager>,
) -> Self {
#[cfg(feature = "engine-moli")]
let global_watermark = crate::engines::memory_watermark::get_global();
let max_instances = config.max_instances;
let (return_tx, return_rx) = mpsc::channel(32);
Self {
config,
browser_config,
available: RwLock::new(HashMap::new()),
in_use: RwLock::new(HashMap::new()),
instance_counter: AtomicU64::new(0),
total_instances: AtomicUsize::new(0),
semaphore: Arc::new(Semaphore::new(max_instances)),
download_manager,
cleanup_task: Mutex::new(None),
return_task: Mutex::new(None),
return_sender: Arc::new(return_tx),
return_receiver: Mutex::new(Some(return_rx)),
#[cfg(feature = "engine-moli")]
memory: parking_lot::RwLock::new(global_watermark),
#[cfg(feature = "engine-moli")]
critical_reclaim_done: AtomicBool::new(false),
shutdown: AtomicBool::new(false),
browser_path: OnceCell::new(),
profile_dir_counter: AtomicU64::new(0),
profile_dirs: std::sync::Mutex::new(Vec::new()),
}
}
fn register_profile_dir(&self, dir: std::path::PathBuf) {
self.profile_dirs
.lock()
.expect("profile_dirs poisoned")
.push(dir);
}
async fn acquire(&self) -> Result<(u64, Arc<Browser>), EngineError> {
if self.shutdown.load(Ordering::Acquire) {
return Err(EngineError::Other(
"Browser pool is shutting down".to_string(),
));
}
#[cfg(feature = "engine-moli")]
if let Some(gated) = self.gate_by_memory_watermark().await {
return gated;
}
let permit = self
.semaphore
.clone()
.acquire_owned()
.await
.map_err(|_| EngineError::Other("Failed to acquire semaphore".to_string()))?;
if self.config.enable_reuse {
if let Some((id, browser)) = self.try_get_available().await {
return Ok((id, browser));
}
}
self.create_new_instance(permit).await
}
#[cfg(feature = "engine-moli")]
async fn gate_by_memory_watermark(&self) -> Option<Result<(u64, Arc<Browser>), EngineError>> {
use crate::engines::memory_watermark::MemoryLevel;
let watermark = self.memory.read().clone();
let watermark = watermark?;
match watermark.level() {
MemoryLevel::Critical => {
if !self.critical_reclaim_done.swap(true, Ordering::AcqRel) {
self.reclaim_idle_instances_now().await;
}
Some(Err(EngineError::MemoryConstrained(
"browser pool acquire rejected under Critical memory watermark".to_string(),
)))
}
MemoryLevel::Tight => {
if self.config.enable_reuse {
if let Some((id, browser)) = self.try_get_available().await {
return Some(Ok((id, browser)));
}
}
if self.total_instances.load(Ordering::Relaxed) > 0 {
return Some(Err(EngineError::MemoryConstrained(
"no reusable browser instance under Tight memory watermark".to_string(),
)));
}
None
}
MemoryLevel::Abundant => {
if self.critical_reclaim_done.load(Ordering::Relaxed) {
self.critical_reclaim_done.store(false, Ordering::Relaxed);
}
None
}
}
}
async fn acquire_with_tab_pool(
&self,
) -> Result<(u64, Arc<Browser>, Arc<TabPool>), EngineError> {
let (instance_id, browser) = self.acquire().await?;
let tab_pool = {
let in_use = self.in_use.read().await;
in_use
.get(&instance_id)
.map(|p| p.tab_pool.clone())
.ok_or_else(|| {
EngineError::Other(format!(
"instance {instance_id} not found in_use after acquire"
))
})?
};
Ok((instance_id, browser, tab_pool))
}
async fn try_get_available(&self) -> Option<(u64, Arc<Browser>)> {
let mut available = self.available.write().await;
let healthy_entry = available
.iter()
.find(|(_, p)| p.is_healthy())
.map(|(id, _)| *id);
if let Some(id) = healthy_entry {
if let Some(pooled) = available.remove(&id) {
pooled.touch();
let mut in_use = self.in_use.write().await;
in_use.insert(id, pooled.clone());
debug!(
"Reusing browser instance {} (used {} times)",
id,
pooled.use_count.load(Ordering::Relaxed)
);
return Some((id, pooled.browser.clone()));
}
}
None
}
async fn create_new_instance(
&self,
permit: tokio::sync::OwnedSemaphorePermit,
) -> Result<(u64, Arc<Browser>), EngineError> {
let instance_id = self.instance_counter.fetch_add(1, Ordering::Relaxed);
info!("Creating new browser instance {}", instance_id);
let browser = self.launch_browser().await?;
let pooled = Arc::new(PooledBrowser::new(
browser.clone(),
instance_id,
self.config.tab_pool_max_size,
permit,
));
pooled.touch();
{
let mut in_use = self.in_use.write().await;
in_use.insert(instance_id, pooled);
}
self.total_instances.fetch_add(1, Ordering::Relaxed);
info!(
"Browser instance {} created successfully (total: {})",
instance_id,
self.total_instances.load(Ordering::Relaxed)
);
Ok((instance_id, browser))
}
async fn return_instance(&self, instance_id: u64, browser: Arc<Browser>) {
if self.shutdown.load(Ordering::Acquire) {
debug!(
"Pool is shutting down, closing browser instance {}",
instance_id
);
return;
}
let pooled = {
let mut in_use = self.in_use.write().await;
in_use.remove(&instance_id)
};
if let Some(pooled) = pooled {
let is_healthy = self.check_browser_health(&browser).await;
if is_healthy && self.config.enable_reuse && !self.shutdown.load(Ordering::Acquire) {
let mut available = self.available.write().await;
available.insert(instance_id, pooled);
debug!("Browser instance {} returned to pool", instance_id);
} else {
self.total_instances.fetch_sub(1, Ordering::Relaxed);
debug!(
"Browser instance {} closed (unhealthy or reuse disabled)",
instance_id
);
}
} else {
warn!(
"Browser instance {} not found in use, ignoring return",
instance_id
);
}
}
fn try_reclaim_in_use_slot(&self, instance_id: u64) -> bool {
match self.in_use.try_write() {
Ok(mut in_use) => {
if in_use.remove(&instance_id).is_some() {
self.total_instances.fetch_sub(1, Ordering::Relaxed);
true
} else {
false
}
}
Err(_) => false,
}
}
async fn launch_browser(&self) -> Result<Arc<Browser>, EngineError> {
let remote_debugging_url = self.browser_config.get_remote_debugging_url();
let proxy_url = self.browser_config.get_proxy_url();
let validated_proxy = proxy_url.as_deref().map(validate_pool_proxy).transpose()?;
let (browser, mut handler) = if let Some(ref url) = remote_debugging_url {
Self::connect_remote_browser(url).await?
} else {
self.launch_local_browser(validated_proxy).await?
};
tokio::spawn(async move {
while let Some(h) = handler.next().await {
if let Err(e) = h {
debug!("Browser handler event error (continuing): {:?}", e);
}
}
});
Ok(Arc::new(browser))
}
}
static GLOBAL_BROWSER_POOL: std::sync::OnceLock<BrowserPool> = std::sync::OnceLock::new();
pub fn get_global_pool() -> Option<&'static BrowserPool> {
GLOBAL_BROWSER_POOL.get()
}
pub fn init_global_pool(config: BrowserPoolConfig, browser_config: Arc<dyn BrowserConfigTrait>) {
let pool = BrowserPool::new(config, browser_config);
let _ = GLOBAL_BROWSER_POOL.set(pool);
info!("Global browser pool initialized");
}
pub async fn shutdown_global_pool() {
if let Some(pool) = GLOBAL_BROWSER_POOL.get() {
pool.shutdown().await;
info!("Global browser pool shut down");
}
}
#[cfg(test)]
mod tests {
#[cfg(feature = "engine-moli")]
mod memory_gate {
use super::*;
use crate::engines::memory_watermark::{MemoryLevel, MemoryWatermark};
fn pool() -> BrowserPool {
BrowserPool::new(
BrowserPoolConfig::default(),
Arc::new(BrowserConfigComponent::default()),
)
}
fn watermark(_available_mib: u64) -> Arc<MemoryWatermark> {
MemoryWatermark::new(512, 2048)
}
#[tokio::test]
async fn critical_rejects_acquire_without_launching() {
let pool = pool();
let wm = watermark(100);
assert_eq!(wm.apply_sample(Some(100)), MemoryLevel::Critical);
pool.set_memory_watermark(Some(wm));
let result = pool.acquire_page().await;
match result {
Err(EngineError::MemoryConstrained(msg)) => {
assert!(msg.contains("Critical"), "错误文案应指明 Critical:{}", msg);
}
other => panic!("期望 MemoryConstrained,实际: {:?}", other.err()),
}
}
#[tokio::test]
async fn tight_cold_pool_passes_gate_but_running_pool_rejects_new_instance() {
let pool = pool();
let wm = watermark(1500);
assert_eq!(wm.apply_sample(Some(1500)), MemoryLevel::Tight);
pool.set_memory_watermark(Some(wm));
let result = pool.acquire_page().await;
assert!(
!matches!(result, Err(EngineError::MemoryConstrained(_))),
"冷池 Tight 应放行首实例,实际被水位拒绝: {:?}",
result.err()
);
pool.state_for_test()
.total_instances
.store(1, Ordering::Relaxed);
let result = pool.acquire_page().await;
match result {
Err(EngineError::MemoryConstrained(msg)) => {
assert!(msg.contains("Tight"), "错误文案应指明 Tight:{}", msg);
}
other => panic!("期望 MemoryConstrained,实际: {:?}", other.err()),
}
assert_eq!(
pool.state_for_test()
.total_instances
.load(Ordering::Relaxed),
1,
"Tight 下不得创建新实例"
);
}
#[tokio::test]
async fn pool_shares_global_watermark_instance_with_router() {
let wm = MemoryWatermark::new(512, 2048);
assert_eq!(wm.apply_sample(Some(1500)), MemoryLevel::Tight);
crate::engines::memory_watermark::set_global(wm.clone());
let pool = pool();
let pool_wm = pool
.state_for_test()
.memory
.read()
.clone()
.expect("池构造期应自取全局水位镜像");
assert!(
Arc::ptr_eq(&wm, &pool_wm),
"池与 router 必须共享同一水位 Arc 实例"
);
assert_eq!(pool_wm.level(), MemoryLevel::Tight);
}
#[tokio::test]
async fn no_watermark_keeps_legacy_behavior() {
let pool = pool();
pool.shutdown().await;
let result = pool.acquire_page().await;
assert!(
!matches!(result, Err(EngineError::MemoryConstrained(_))),
"无水位装配时不得出现水位错误"
);
}
}
use super::*;
use crate::infrastructure::services::config_service::BrowserConfigComponent;
#[test]
fn test_browser_pool_config_default() {
let config = BrowserPoolConfig::default();
assert_eq!(config.max_instances, 5);
assert_eq!(config.idle_timeout_secs, 300);
assert_eq!(config.health_check_interval_secs, 60);
assert!(config.enable_reuse);
assert_eq!(config.tab_pool_max_size, 10);
assert!(
config.context_isolation,
"context_isolation must default to true"
);
assert!(
!config.browser_args.iter().any(|a| a == "--no-sandbox"),
"default browser_args should not contain --no-sandbox"
);
}
#[test]
fn test_context_isolation_branch_selection() {
let isolation_on = BrowserPoolConfig::default();
assert!(isolation_on.context_isolation);
let isolation_off = BrowserPoolConfig {
context_isolation: false,
..BrowserPoolConfig::default()
};
assert!(!isolation_off.context_isolation);
assert_eq!(isolation_off.max_instances, 5);
assert_eq!(isolation_off.tab_pool_max_size, 10);
assert!(isolation_off.enable_reuse);
assert!(BrowserPoolConfig::docker_safe_args().context_isolation);
}
#[tokio::test]
async fn test_acquire_page_tab_pool_escape_hatch_shutdown_fails() {
let config = BrowserPoolConfig {
context_isolation: false,
..BrowserPoolConfig::default()
};
let browser_config = Arc::new(BrowserConfigComponent::default());
let pool = BrowserPool::new(config, browser_config);
pool.shutdown().await;
let result = pool.acquire_page().await;
assert!(result.is_err());
}
#[test]
fn test_browser_pool_config_docker_safe_args() {
let config = BrowserPoolConfig::docker_safe_args();
assert_eq!(config.max_instances, 5);
assert!(config.browser_args.contains(&"--disable-gpu".to_string()));
}
#[test]
fn test_browser_pool_config_tab_pool_disabled() {
let config = BrowserPoolConfig {
tab_pool_max_size: 0,
..BrowserPoolConfig::default()
};
assert_eq!(config.tab_pool_max_size, 0);
}
#[tokio::test]
async fn test_browser_pool_acquire_page_shutdown_fails() {
let config = BrowserPoolConfig::default();
let browser_config = Arc::new(BrowserConfigComponent::default());
let pool = BrowserPool::new(config, browser_config);
pool.shutdown().await;
let result = pool.acquire_page().await;
assert!(result.is_err());
}
#[tokio::test]
async fn test_try_reclaim_in_use_slot_absent_id_is_noop() {
let config = BrowserPoolConfig::default();
let browser_config = Arc::new(BrowserConfigComponent::default());
let state = Arc::new(BrowserPoolState::new(
config,
browser_config,
Arc::new(BrowserDownloadManager::new(BrowserDownloadConfig::default())),
));
state.total_instances.store(3, Ordering::Relaxed);
assert!(
!state.try_reclaim_in_use_slot(999),
"reclaiming an absent instance must return false"
);
assert_eq!(
state.total_instances.load(Ordering::Relaxed),
3,
"absent-id reclaim must not decrement total_instances"
);
assert_eq!(state.in_use.read().await.len(), 0);
}
#[test]
fn test_browser_pool_stats() {
let config = BrowserPoolConfig::default();
let browser_config = Arc::new(BrowserConfigComponent::default());
let pool = BrowserPool::new(config, browser_config);
let stats = tokio_test::block_on(pool.stats());
assert_eq!(stats.total_instances, 0);
assert_eq!(stats.available_instances, 0);
assert_eq!(stats.in_use_instances, 0);
}
#[tokio::test]
async fn test_browser_pool_shutdown() {
let config = BrowserPoolConfig::default();
let browser_config = Arc::new(BrowserConfigComponent::default());
let pool = BrowserPool::new(config, browser_config);
pool.shutdown().await;
let result = pool.acquire().await;
assert!(result.is_err());
}
#[tokio::test]
async fn test_browser_pool_clone() {
let config = BrowserPoolConfig::default();
let browser_config = Arc::new(BrowserConfigComponent::default());
let pool = BrowserPool::new(config, browser_config);
let pool2 = pool.clone();
let stats1 = pool.stats().await;
let stats2 = pool2.stats().await;
assert_eq!(stats1.total_instances, stats2.total_instances);
}
#[tokio::test]
async fn test_concurrent_shutdown_acquire() {
let config = BrowserPoolConfig::default();
let browser_config = Arc::new(BrowserConfigComponent::default());
let pool = Arc::new(BrowserPool::new(config, browser_config));
let mut handles = Vec::new();
for _ in 0..20 {
let pool_clone = pool.clone();
handles.push(tokio::spawn(async move { pool_clone.acquire().await }));
}
pool.shutdown().await;
let mut error_count = 0;
for handle in handles {
if handle.await.unwrap().is_err() {
error_count += 1;
}
}
assert!(
error_count > 0,
"expected some errors in test env without browser"
);
}
#[tokio::test]
async fn test_semaphore_permit_consistency() {
let config = BrowserPoolConfig {
max_instances: 3,
..BrowserPoolConfig::default()
};
let browser_config = Arc::new(BrowserConfigComponent::default());
let pool = BrowserPool::new(config, browser_config);
let stats = pool.stats().await;
assert_eq!(stats.total_instances, 0);
assert_eq!(stats.in_use_instances, 0);
assert_eq!(stats.available_instances, 0);
let permit = pool
.state_for_test()
.semaphore
.clone()
.acquire_owned()
.await;
assert!(
permit.is_ok(),
"should be able to acquire permit when pool is empty"
);
drop(permit);
pool.shutdown().await;
}
#[tokio::test]
async fn test_return_sender_arc_clone_no_block() {
let config = BrowserPoolConfig::default();
let browser_config = Arc::new(BrowserConfigComponent::default());
let pool = BrowserPool::new(config, browser_config);
let mut handles = Vec::new();
for _ in 0..100 {
let state = pool.state_for_test().clone();
handles.push(tokio::spawn(async move {
let _sender = state.clone_return_sender();
}));
}
for handle in handles {
handle.await.unwrap();
}
pool.shutdown().await;
}
#[test]
fn test_pooled_browser_last_used_atomic() {
let atomic = AtomicU64::new(0);
let base = Instant::now();
let elapsed = base.elapsed();
atomic.store(elapsed.as_millis() as u64, Ordering::Release);
let millis = atomic.load(Ordering::Acquire);
let reconstructed = base + Duration::from_millis(millis);
let diff = Instant::now().duration_since(reconstructed);
assert!(diff < Duration::from_millis(100));
}
#[test]
fn test_validate_pool_proxy_rejects_whitespace_injection() {
assert!(validate_pool_proxy("http://bad proxy --flag").is_err());
assert!(validate_pool_proxy("ftp://not-allowed").is_err());
assert!(validate_pool_proxy("http://proxy.example.com:8080").is_ok());
assert!(validate_pool_proxy("socks5://user:pass@proxy:1080").is_ok()); }
}