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}