Skip to main content

fetchium_core/browser/
pool.rs

1//! Browser pool manager — manages headless Chromium instances (PRD §8.3).
2//!
3//! Resource tier controls pool size:
4//! - Minimal:     1 browser, 2 tabs  (~200 MB)
5//! - Standard:    1 browser, 4 tabs  (~500 MB)
6//! - Performance: 2 browsers, 8 tabs (~1 GB)
7//!
8//! ## Chrome binary detection (Ubuntu 24.04 snap)
9//! **Snap Chromium (Ubuntu 24.04)**: Uses `.user_data_dir()` per-instance to avoid
10//! Chrome's `SingletonLock` error (without it, only the 1st instance can launch).
11//!
12//! ## Graceful init
13//! `init()` logs individual browser failures but only errors if ALL instances fail.
14//! This lets snap Chromium work even when only 1 of N instances launches.
15//!
16//! Only compiled when the `headless` feature is enabled.
17
18#[cfg(not(feature = "headless"))]
19/// Stub pool for non-headless builds.
20pub struct BrowserPool;
21
22#[cfg(not(feature = "headless"))]
23impl BrowserPool {
24    pub fn new_stub() -> Self {
25        Self
26    }
27}
28
29#[cfg(feature = "headless")]
30pub use headless_impl::{BrowserPool, BrowserTier};
31
32#[cfg(feature = "headless")]
33mod headless_impl {
34    use crate::browser::tab::ManagedTab;
35    use chromiumoxide::{Browser, BrowserConfig};
36    use parking_lot::Mutex;
37    use std::path::PathBuf;
38    use std::sync::Arc;
39    use tokio::sync::Semaphore;
40    use tracing::{debug, info};
41
42    /// Resource tier controlling pool capacity.
43    #[derive(Debug, Clone, Copy, PartialEq, Eq)]
44    pub enum BrowserTier {
45        /// 1 browser, 2 tabs (~200 MB)
46        Minimal,
47        /// 1 browser, 4 tabs (~500 MB)
48        Standard,
49        /// 2 browsers, 8 tabs (~1 GB)
50        Performance,
51    }
52
53    impl BrowserTier {
54        pub fn tab_limit(&self) -> usize {
55            match self {
56                Self::Minimal => 2,
57                Self::Standard => 4,
58                Self::Performance => 8,
59            }
60        }
61
62        pub fn browser_count(&self) -> usize {
63            match self {
64                Self::Performance => 2,
65                _ => 1,
66            }
67        }
68    }
69
70    /// Managed pool of headless Chromium browser instances.
71    pub struct BrowserPool {
72        browsers: Mutex<Vec<Arc<Browser>>>,
73        tab_semaphore: Arc<Semaphore>,
74        tier: BrowserTier,
75        /// Optional Chrome binary path override. When `None`, auto-detection is used.
76        chrome_path: Option<PathBuf>,
77    }
78
79    impl BrowserPool {
80        /// Create a new pool (does not launch browsers yet — call `init()`).
81        /// Uses automatic Chrome binary detection at init time.
82        pub fn new(tier: BrowserTier) -> Self {
83            Self::new_with_path(tier, None)
84        }
85
86        /// Create a pool with an explicit Chrome binary path.
87        pub fn new_with_path(tier: BrowserTier, chrome_path: Option<PathBuf>) -> Self {
88            Self {
89                browsers: Mutex::new(Vec::new()),
90                tab_semaphore: Arc::new(Semaphore::new(tier.tab_limit())),
91                tier,
92                chrome_path,
93            }
94        }
95
96        /// Create a pool from `FetchiumConfig`, using the full priority-chain Chrome resolution.
97        ///
98        /// This is the preferred constructor — it honours `fetchium setup --headless` downloads,
99        /// env var overrides, and config file paths automatically.
100        pub fn from_config(tier: BrowserTier, config: &crate::config::FetchiumConfig) -> Self {
101            let chrome_path = crate::setup::chromium::resolve_chrome_path(config);
102            Self::new_with_path(tier, chrome_path)
103        }
104
105        /// Launch headless Chromium instances according to the resource tier.
106        pub async fn init(&self) -> anyhow::Result<()> {
107            let count = self.tier.browser_count();
108            info!("BrowserPool: launching {} Chromium instance(s)", count);
109
110            // Locate Chrome binary: use explicit override or fall back to system detection
111            let chrome_path: std::path::PathBuf = match &self.chrome_path {
112                Some(p) => {
113                    info!("BrowserPool: using configured Chrome at {}", p.display());
114                    p.clone()
115                }
116                None => [
117                    "/usr/bin/chromium-browser",
118                    "/usr/bin/chromium",
119                    "/usr/bin/google-chrome",
120                    "/usr/bin/google-chrome-stable",
121                    "/snap/bin/chromium",
122                ]
123                .iter()
124                .map(std::path::Path::new)
125                .find(|p| p.exists())
126                .map(|p| p.to_path_buf())
127                .ok_or_else(|| {
128                    anyhow::anyhow!(
129                        "No Chrome/Chromium binary found. \
130                         Run `fetchium setup --headless` to download Chrome for Testing, \
131                         or install with: sudo apt-get install chromium-browser"
132                    )
133                })?,
134            };
135            info!("BrowserPool: using Chrome at {}", chrome_path.display());
136
137            for i in 0..count {
138                // Each browser instance needs its own user-data-dir to avoid
139                // Chrome's SingletonLock preventing multiple simultaneous instances.
140                let user_data_dir = std::env::temp_dir().join(format!(
141                    "fetchium-chrome-{}-{}",
142                    std::process::id(),
143                    i
144                ));
145
146                let config = BrowserConfig::builder()
147                    .chrome_executable(&chrome_path)
148                    .user_data_dir(&user_data_dir)
149                    .arg("--no-sandbox")
150                    .arg("--disable-gpu")
151                    .arg("--disable-dev-shm-usage")
152                    .arg("--disable-extensions")
153                    .arg("--disable-background-networking")
154                    .arg("--disable-sync")
155                    .arg("--headless=new")
156                    .arg("--disable-blink-features=AutomationControlled")
157                    .arg("--user-agent=Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36")
158                    .build()
159                    .map_err(|e| anyhow::anyhow!("BrowserConfig error: {e}"))?;
160
161                match Browser::launch(config).await {
162                    Ok((browser, handler)) => {
163                        // Spawn the event handler loop in the background
164                        tokio::spawn(async move {
165                            use tokio_stream::StreamExt;
166                            let mut handler = handler;
167                            while handler.next().await.is_some() {}
168                        });
169                        self.browsers.lock().push(Arc::new(browser));
170                        debug!("BrowserPool: browser {} launched", i);
171                    }
172                    Err(e) => {
173                        // Log but keep going — if at least one browser launched, pool is usable
174                        tracing::warn!("BrowserPool: browser {} failed to launch: {e}", i);
175                    }
176                }
177            }
178
179            let launched = self.browsers.lock().len();
180            if launched == 0 {
181                return Err(anyhow::anyhow!(
182                    "BrowserPool: all {} browser instance(s) failed to launch",
183                    count
184                ));
185            }
186
187            info!(
188                "BrowserPool: ready ({}/{} browsers, {} tab slots)",
189                launched,
190                count,
191                self.tier.tab_limit()
192            );
193            Ok(())
194        }
195
196        /// Acquire a tab from the pool. Blocks if at capacity until one is released.
197        pub async fn acquire_tab(&self) -> anyhow::Result<ManagedTab> {
198            // Acquire a permit (blocks if tab_limit reached)
199            let permit = Arc::clone(&self.tab_semaphore)
200                .acquire_owned()
201                .await
202                .map_err(|e| anyhow::anyhow!("Semaphore closed: {e}"))?;
203
204            // Pick a browser (round-robin)
205            let browser = {
206                let browsers = self.browsers.lock();
207                if browsers.is_empty() {
208                    return Err(anyhow::anyhow!(
209                        "BrowserPool not initialized — call init() first"
210                    ));
211                }
212                Arc::clone(&browsers[0]) // Simple: always use first browser
213            };
214
215            let page = browser
216                .new_page("about:blank")
217                .await
218                .map_err(|e| anyhow::anyhow!("Failed to open new tab: {e}"))?;
219
220            debug!(
221                "BrowserPool: tab acquired ({} permits remaining)",
222                self.tab_semaphore.available_permits()
223            );
224
225            Ok(ManagedTab::new(page, permit))
226        }
227
228        /// Gracefully shut down all browser instances.
229        pub async fn shutdown(&self) {
230            let mut browsers = self.browsers.lock();
231            info!("BrowserPool: shutting down {} browser(s)", browsers.len());
232            browsers.clear(); // Drops all Arc<Browser>, triggering cleanup
233        }
234    }
235
236    #[cfg(test)]
237    mod tests {
238        use super::*;
239
240        #[test]
241        fn tier_limits() {
242            assert_eq!(BrowserTier::Minimal.tab_limit(), 2);
243            assert_eq!(BrowserTier::Standard.tab_limit(), 4);
244            assert_eq!(BrowserTier::Performance.tab_limit(), 8);
245            assert_eq!(BrowserTier::Performance.browser_count(), 2);
246            assert_eq!(BrowserTier::Minimal.browser_count(), 1);
247        }
248
249        #[test]
250        fn pool_semaphore_capacity() {
251            let pool = BrowserPool::new(BrowserTier::Standard);
252            assert_eq!(pool.tab_semaphore.available_permits(), 4);
253        }
254    }
255}