Skip to main content

fetchium_core/browser/
tab.rs

1//! Managed browser tab with auto-cleanup via semaphore permit (PRD §8.3).
2//!
3//! `navigate_and_wait(url, selector, timeout)` is the preferred navigation method
4//! for JS-rendered SERPs — it waits for `selector` to appear in the DOM (using
5//! chromiumoxide's `find_element`) rather than just sleeping, giving reliable HTML.
6//!
7//! When the `headless` feature is disabled, this module compiles as stubs.
8
9#[cfg(feature = "headless")]
10pub use headless_impl::ManagedTab;
11
12#[cfg(not(feature = "headless"))]
13/// Stub type when headless feature is disabled.
14pub struct ManagedTab;
15
16#[cfg(feature = "headless")]
17mod headless_impl {
18    use anyhow::Context as _;
19    use chromiumoxide::Page;
20    use std::time::Duration;
21
22    /// A managed browser tab that returns its semaphore permit on drop.
23    ///
24    /// The permit is held for the lifetime of the tab; dropping the tab
25    /// automatically releases capacity in the pool.
26    pub struct ManagedTab {
27        pub(crate) page: Page,
28        _permit: tokio::sync::OwnedSemaphorePermit,
29    }
30
31    impl ManagedTab {
32        pub(crate) fn new(page: Page, permit: tokio::sync::OwnedSemaphorePermit) -> Self {
33            Self {
34                page,
35                _permit: permit,
36            }
37        }
38
39        /// Navigate to a URL, waiting up to `timeout_ms` milliseconds for load.
40        pub async fn navigate(&self, url: &str, timeout_ms: u64) -> anyhow::Result<()> {
41            tokio::time::timeout(Duration::from_millis(timeout_ms), self.page.goto(url))
42                .await
43                .context("Navigation timed out")?
44                .context("Navigation failed")?;
45            Ok(())
46        }
47
48        /// Navigate and wait until `selector` is present in the DOM (JS-rendered),
49        /// timing out after `timeout_ms`. Returns Ok even if selector never appears
50        /// so callers can still extract partial content.
51        pub async fn navigate_and_wait(
52            &self,
53            url: &str,
54            selector: &str,
55            timeout_ms: u64,
56        ) -> anyhow::Result<()> {
57            tokio::time::timeout(Duration::from_millis(timeout_ms), self.page.goto(url))
58                .await
59                .context("Navigation timed out")?
60                .context("Navigation failed")?;
61
62            // Poll for the results selector to confirm JS has rendered
63            let wait_result = tokio::time::timeout(
64                Duration::from_millis(timeout_ms / 2),
65                self.page.find_element(selector),
66            )
67            .await;
68
69            if wait_result.is_err() {
70                tracing::debug!(
71                    "navigate_and_wait: selector {selector:?} not found within timeout"
72                );
73            }
74            Ok(())
75        }
76
77        /// Get the fully rendered HTML content of the current page.
78        pub async fn content(&self) -> anyhow::Result<String> {
79            self.page
80                .content()
81                .await
82                .context("Failed to get page content")
83        }
84
85        /// Evaluate JavaScript in the page context.
86        pub async fn evaluate(&self, expression: &str) -> anyhow::Result<String> {
87            let result = self
88                .page
89                .evaluate(expression)
90                .await
91                .context("JS evaluation failed")?;
92            Ok(format!("{:?}", result.value()))
93        }
94
95        /// Access the underlying chromiumoxide Page.
96        pub fn page(&self) -> &Page {
97            &self.page
98        }
99    }
100}