stygian-browser 0.10.0

//! Opinionated acquisition runner with deterministic escalation.
//!
//! The runner executes a mode-specific strategy ladder and returns a terminal
//! [`AcquisitionResult`] for every request, including setup-failure and timeout
//! paths.

use std::sync::Arc;
use std::time::{Duration, Instant};

use serde::{Deserialize, Serialize};
use serde_json::Value;

use crate::BrowserPool;
use crate::error::BrowserError;
use crate::page::WaitUntil;

/// Opinionated acquisition mode for the escalation ladder.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum AcquisitionMode {
    /// Prioritize lowest-latency paths.
    Fast,
    /// Favor reliability with broader escalation.
    Resilient,
    /// Start from stronger anti-bot paths.
    Hostile,
    /// Enter from a policy-guided start point.
    Investigate,
}

/// Strategy stage attempted by the acquisition runner.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum StrategyUsed {
    /// Plain HTTP fetch.
    DirectHttp,
    /// HTTP fetch using a TLS-profiled client.
    TlsProfiledHttp,
    /// Browser session with opinionated light-stealth defaults.
    BrowserLightStealth,
    /// Browser session scoped to a sticky context id.
    StickyProxyBrowserSession,
    /// Policy-guided entry marker for investigation mode.
    InvestigateEntry,
}

/// One acquisition request.
#[derive(Debug, Clone)]
pub struct AcquisitionRequest {
    /// Target URL.
    pub url: String,
    /// Acquisition mode.
    pub mode: AcquisitionMode,
    /// Optional selector that must be present for browser-stage success.
    pub wait_for_selector: Option<String>,
    /// Optional JavaScript extraction expression evaluated in browser stages.
    pub extraction_js: Option<String>,
    /// Hard wall-clock timeout for the whole acquisition attempt.
    pub total_timeout: Duration,
    /// Per-navigation timeout for browser stages.
    pub navigation_timeout: Duration,
    /// Per-request timeout for HTTP stages.
    pub request_timeout: Duration,
    /// Maximum HTML bytes captured into `html_excerpt`.
    pub html_excerpt_bytes: usize,
    /// Optional policy-guided stage that `Investigate` mode starts from.
    pub investigate_start: Option<StrategyUsed>,
}

impl Default for AcquisitionRequest {
    fn default() -> Self {
        Self {
            url: String::new(),
            mode: AcquisitionMode::Resilient,
            wait_for_selector: None,
            extraction_js: None,
            total_timeout: Duration::from_secs(45),
            navigation_timeout: Duration::from_secs(30),
            request_timeout: Duration::from_secs(15),
            html_excerpt_bytes: 4_096,
            investigate_start: None,
        }
    }
}

/// Failure class recorded per strategy stage.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum StageFailureKind {
    /// Stage initialization/setup failed.
    Setup,
    /// Stage hit a timeout.
    Timeout,
    /// Stage reached a known anti-bot block class.
    Blocked,
    /// Transport/runtime failure.
    Transport,
    /// Extraction/validation failure.
    Extraction,
}

/// Captured failure record for one stage.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct StageFailure {
    /// Stage where the failure happened.
    pub strategy: StrategyUsed,
    /// Coarse failure kind.
    pub kind: StageFailureKind,
    /// Compact diagnostic message.
    pub message: String,
}

/// Terminal acquisition result.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AcquisitionResult {
    /// `true` when any stage satisfied success criteria.
    pub success: bool,
    /// Stage that produced the terminal success, if any.
    pub strategy_used: Option<StrategyUsed>,
    /// Ordered stage attempts.
    pub attempted: Vec<StrategyUsed>,
    /// Final URL observed from the successful stage.
    pub final_url: Option<String>,
    /// HTTP status code observed from the successful stage.
    pub status_code: Option<u16>,
    /// Best-effort HTML excerpt from the successful stage.
    pub html_excerpt: Option<String>,
    /// Optional extraction payload.
    pub extracted: Option<Value>,
    /// Failure bundle collected across stages.
    pub failures: Vec<StageFailure>,
    /// `true` when the wall-clock timeout fired before completion.
    pub timed_out: bool,
}

impl AcquisitionResult {
    const fn empty() -> Self {
        Self {
            success: false,
            strategy_used: None,
            attempted: Vec::new(),
            final_url: None,
            status_code: None,
            html_excerpt: None,
            extracted: None,
            failures: Vec::new(),
            timed_out: false,
        }
    }
}

#[derive(Debug, Clone)]
struct StageSuccess {
    final_url: Option<String>,
    status_code: Option<u16>,
    html_excerpt: Option<String>,
    extracted: Option<Value>,
}

#[derive(Debug, Clone)]
enum StageOutcome {
    Marker,
    Success(StageSuccess),
    Failure(StageFailure),
}

/// Runner facade for opinionated acquisition.
#[derive(Clone)]
pub struct AcquisitionRunner {
    pool: Arc<BrowserPool>,
}

impl AcquisitionRunner {
    /// Create a new acquisition runner.
    ///
    /// # Example
    ///
    /// ```no_run
    /// use stygian_browser::{AcquisitionRunner, BrowserConfig, BrowserPool};
    ///
    /// # async fn run() -> stygian_browser::Result<()> {
    /// let pool = BrowserPool::new(BrowserConfig::default()).await?;
    /// let _runner = AcquisitionRunner::new(pool);
    /// # Ok(())
    /// # }
    /// ```
    #[must_use]
    pub const fn new(pool: Arc<BrowserPool>) -> Self {
        Self { pool }
    }

    /// Return the deterministic stage ladder for a mode.
    ///
    /// Investigation mode starts at `investigate_start` when provided.
    #[must_use]
    pub fn strategy_ladder(
        mode: AcquisitionMode,
        investigate_start: Option<StrategyUsed>,
    ) -> Vec<StrategyUsed> {
        let mut stages = match mode {
            AcquisitionMode::Fast => vec![
                StrategyUsed::DirectHttp,
                StrategyUsed::TlsProfiledHttp,
                StrategyUsed::BrowserLightStealth,
            ],
            AcquisitionMode::Resilient => vec![
                StrategyUsed::DirectHttp,
                StrategyUsed::TlsProfiledHttp,
                StrategyUsed::BrowserLightStealth,
                StrategyUsed::StickyProxyBrowserSession,
            ],
            AcquisitionMode::Hostile => vec![
                StrategyUsed::BrowserLightStealth,
                StrategyUsed::StickyProxyBrowserSession,
                StrategyUsed::TlsProfiledHttp,
                StrategyUsed::DirectHttp,
            ],
            AcquisitionMode::Investigate => {
                let start = investigate_start.unwrap_or(StrategyUsed::BrowserLightStealth);
                vec![
                    StrategyUsed::InvestigateEntry,
                    start,
                    StrategyUsed::StickyProxyBrowserSession,
                    StrategyUsed::TlsProfiledHttp,
                ]
            }
        };

        dedupe_preserve_order(&mut stages);
        stages
    }

    /// Execute the acquisition ladder and return a terminal result.
    ///
    /// This method never panics and always returns an [`AcquisitionResult`],
    /// including timeout and setup-failure paths.
    ///
    /// # Example
    ///
    /// ```no_run
    /// use stygian_browser::{AcquisitionMode, AcquisitionRequest, AcquisitionRunner, BrowserConfig, BrowserPool};
    ///
    /// # async fn run() -> stygian_browser::Result<()> {
    /// let pool = BrowserPool::new(BrowserConfig::default()).await?;
    /// let runner = AcquisitionRunner::new(pool);
    /// let request = AcquisitionRequest {
    ///     url: "https://example.com".to_string(),
    ///     mode: AcquisitionMode::Resilient,
    ///     ..AcquisitionRequest::default()
    /// };
    /// let _result = runner.run(request).await;
    /// # Ok(())
    /// # }
    /// ```
    pub async fn run(&self, request: AcquisitionRequest) -> AcquisitionResult {
        let timeout = request.total_timeout;
        let timeout_strategy = Self::strategy_ladder(request.mode, request.investigate_start)
            .into_iter()
            .find(|strategy| *strategy != StrategyUsed::InvestigateEntry)
            .unwrap_or(StrategyUsed::DirectHttp);
        let mut result = tokio::time::timeout(timeout, self.run_inner(&request))
            .await
            .unwrap_or_else(|_| {
                let mut timed_out = AcquisitionResult::empty();
                timed_out.timed_out = true;
                timed_out.failures.push(StageFailure {
                    strategy: timeout_strategy,
                    kind: StageFailureKind::Timeout,
                    message: format!("acquisition timed out after {}ms", timeout.as_millis()),
                });
                timed_out
            });

        if !result.success {
            // Guarantee deterministic terminal output for all unsuccessful runs.
            if result.failures.is_empty() {
                result.failures.push(StageFailure {
                    strategy: timeout_strategy,
                    kind: StageFailureKind::Transport,
                    message: "acquisition ended without stage output".to_string(),
                });
            }
        }

        result
    }

    async fn run_inner(&self, request: &AcquisitionRequest) -> AcquisitionResult {
        let mut result = AcquisitionResult::empty();
        let ladder = Self::strategy_ladder(request.mode, request.investigate_start);
        let started = Instant::now();

        for strategy in ladder {
            if started.elapsed() >= request.total_timeout {
                result.timed_out = true;
                result.failures.push(StageFailure {
                    strategy,
                    kind: StageFailureKind::Timeout,
                    message: "wall-clock timeout reached before stage execution".to_string(),
                });
                break;
            }

            result.attempted.push(strategy);
            match self.execute_stage(strategy, request).await {
                StageOutcome::Marker => {}
                StageOutcome::Success(success) => {
                    result.success = true;
                    result.strategy_used = Some(strategy);
                    result.final_url = success.final_url;
                    result.status_code = success.status_code;
                    result.html_excerpt = success.html_excerpt;
                    result.extracted = success.extracted;
                    break;
                }
                StageOutcome::Failure(failure) => result.failures.push(failure),
            }
        }

        result
    }

    async fn execute_stage(
        &self,
        strategy: StrategyUsed,
        request: &AcquisitionRequest,
    ) -> StageOutcome {
        match strategy {
            StrategyUsed::DirectHttp => self.run_http_stage(request, false).await,
            StrategyUsed::TlsProfiledHttp => self.run_http_stage(request, true).await,
            StrategyUsed::BrowserLightStealth => self.run_browser_stage(request, false).await,
            StrategyUsed::StickyProxyBrowserSession => self.run_browser_stage(request, true).await,
            StrategyUsed::InvestigateEntry => StageOutcome::Marker,
        }
    }

    async fn run_browser_stage(&self, request: &AcquisitionRequest, sticky: bool) -> StageOutcome {
        let strategy = if sticky {
            StrategyUsed::StickyProxyBrowserSession
        } else {
            StrategyUsed::BrowserLightStealth
        };

        let handle_result = if sticky {
            let context = host_hint(&request.url).unwrap_or_else(|| "default".to_string());
            self.pool.acquire_for(&context).await
        } else {
            self.pool.acquire().await
        };

        let handle = match handle_result {
            Ok(handle) => handle,
            Err(err) => {
                return StageOutcome::Failure(StageFailure {
                    strategy,
                    kind: StageFailureKind::Setup,
                    message: format!("browser acquire failed: {err}"),
                });
            }
        };

        let page_result = async {
            let browser = handle.browser().ok_or_else(|| {
                BrowserError::ConfigError("browser handle already released".to_string())
            })?;
            let mut page = browser.new_page().await?;
            page.navigate(
                &request.url,
                WaitUntil::DomContentLoaded,
                request.navigation_timeout,
            )
            .await?;

            if let Some(selector) = &request.wait_for_selector {
                page.wait_for_selector(selector, request.navigation_timeout)
                    .await?;
            }

            let extracted = match request.extraction_js.as_deref() {
                Some(script) => Some(page.eval::<Value>(script).await.map_err(|err| {
                    BrowserError::ScriptExecutionFailed {
                        script: script.to_string(),
                        reason: err.to_string(),
                    }
                })?),
                None => None,
            };

            let html = page.content().await?;
            let final_url = page.url().await.ok();
            let status_code = page.status_code().ok().flatten();
            let html_excerpt = truncate_html(&html, request.html_excerpt_bytes);

            drop(page);

            Ok::<StageSuccess, BrowserError>(StageSuccess {
                final_url,
                status_code,
                html_excerpt: Some(html_excerpt),
                extracted,
            })
        }
        .await;

        handle.release().await;

        match page_result {
            Ok(success) => {
                if is_block_status(success.status_code) {
                    StageOutcome::Failure(StageFailure {
                        strategy,
                        kind: StageFailureKind::Blocked,
                        message: format!(
                            "blocked status during browser stage: {:?}",
                            success.status_code
                        ),
                    })
                } else {
                    StageOutcome::Success(success)
                }
            }
            Err(err) => StageOutcome::Failure(StageFailure {
                strategy,
                kind: classify_browser_error(&err),
                message: err.to_string(),
            }),
        }
    }

    async fn run_http_stage(
        &self,
        request: &AcquisitionRequest,
        tls_profiled: bool,
    ) -> StageOutcome {
        if request.wait_for_selector.is_some() || request.extraction_js.is_some() {
            return StageOutcome::Failure(StageFailure {
                strategy: if tls_profiled {
                    StrategyUsed::TlsProfiledHttp
                } else {
                    StrategyUsed::DirectHttp
                },
                kind: StageFailureKind::Extraction,
                message: "HTTP stages cannot satisfy selector/extraction requirements".to_string(),
            });
        }

        self.run_http_stage_impl(request, tls_profiled).await
    }

    #[cfg(feature = "tls-config")]
    async fn run_http_stage_impl(
        &self,
        request: &AcquisitionRequest,
        tls_profiled: bool,
    ) -> StageOutcome {
        use crate::tls::{CHROME_131, build_profiled_client_preset};

        let strategy = if tls_profiled {
            StrategyUsed::TlsProfiledHttp
        } else {
            StrategyUsed::DirectHttp
        };

        let client = if tls_profiled {
            match build_profiled_client_preset(&CHROME_131, None) {
                Ok(client) => client,
                Err(err) => {
                    return StageOutcome::Failure(StageFailure {
                        strategy,
                        kind: StageFailureKind::Setup,
                        message: format!("tls-profiled client setup failed: {err}"),
                    });
                }
            }
        } else {
            match reqwest::Client::builder()
                .timeout(request.request_timeout)
                .cookie_store(true)
                .build()
            {
                Ok(client) => client,
                Err(err) => {
                    return StageOutcome::Failure(StageFailure {
                        strategy,
                        kind: StageFailureKind::Setup,
                        message: format!("http client setup failed: {err}"),
                    });
                }
            }
        };

        let response = match client
            .get(&request.url)
            .timeout(request.request_timeout)
            .send()
            .await
        {
            Ok(response) => response,
            Err(err) => {
                return StageOutcome::Failure(StageFailure {
                    strategy,
                    kind: if err.is_timeout() {
                        StageFailureKind::Timeout
                    } else {
                        StageFailureKind::Transport
                    },
                    message: err.to_string(),
                });
            }
        };

        let status_code = Some(response.status().as_u16());
        let final_url = Some(response.url().to_string());
        let html = match response.text().await {
            Ok(text) => text,
            Err(err) => {
                return StageOutcome::Failure(StageFailure {
                    strategy,
                    kind: StageFailureKind::Transport,
                    message: format!("response body read failed: {err}"),
                });
            }
        };

        if is_block_status(status_code) {
            return StageOutcome::Failure(StageFailure {
                strategy,
                kind: StageFailureKind::Blocked,
                message: format!("blocked status from HTTP stage: {status_code:?}"),
            });
        }

        StageOutcome::Success(StageSuccess {
            final_url,
            status_code,
            html_excerpt: Some(truncate_html(&html, request.html_excerpt_bytes)),
            extracted: None,
        })
    }

    #[cfg(not(feature = "tls-config"))]
    async fn run_http_stage_impl(
        &self,
        _request: &AcquisitionRequest,
        tls_profiled: bool,
    ) -> StageOutcome {
        let strategy = if tls_profiled {
            StrategyUsed::TlsProfiledHttp
        } else {
            StrategyUsed::DirectHttp
        };
        StageOutcome::Failure(StageFailure {
            strategy,
            kind: StageFailureKind::Setup,
            message: "HTTP acquisition requires the `tls-config` feature".to_string(),
        })
    }
}

fn dedupe_preserve_order(stages: &mut Vec<StrategyUsed>) {
    let mut seen = Vec::new();
    stages.retain(|stage| {
        if seen.contains(stage) {
            false
        } else {
            seen.push(*stage);
            true
        }
    });
}

fn classify_browser_error(error: &BrowserError) -> StageFailureKind {
    match error {
        BrowserError::Timeout { .. } => StageFailureKind::Timeout,
        BrowserError::NavigationFailed { reason, .. } if reason.contains("selector") => {
            StageFailureKind::Blocked
        }
        BrowserError::ScriptExecutionFailed { .. } => StageFailureKind::Extraction,
        BrowserError::ConfigError(_) | BrowserError::PoolExhausted { .. } => {
            StageFailureKind::Setup
        }
        BrowserError::ProxyUnavailable { .. }
        | BrowserError::ConnectionError { .. }
        | BrowserError::CdpError { .. }
        | BrowserError::LaunchFailed { .. }
        | BrowserError::NavigationFailed { .. }
        | BrowserError::Io(_)
        | BrowserError::StaleNode { .. } => StageFailureKind::Transport,
        #[cfg(feature = "extract")]
        BrowserError::ExtractionFailed(_) => StageFailureKind::Extraction,
    }
}

const fn is_block_status(status: Option<u16>) -> bool {
    matches!(status, Some(401 | 403 | 407 | 429 | 503))
}

fn truncate_html(html: &str, max_bytes: usize) -> String {
    if html.len() <= max_bytes {
        return html.to_string();
    }

    let mut out = String::new();
    for ch in html.chars() {
        if out.len() + ch.len_utf8() > max_bytes {
            break;
        }
        out.push(ch);
    }
    out
}

fn host_hint(url: &str) -> Option<String> {
    let without_scheme = url.split_once("://")?.1;
    let authority = without_scheme.split('/').next()?;
    let host = authority.rsplit('@').next()?.split(':').next()?;
    if host.is_empty() {
        None
    } else {
        Some(host.to_ascii_lowercase())
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn ladder_is_deterministic_for_modes() {
        assert_eq!(
            AcquisitionRunner::strategy_ladder(AcquisitionMode::Fast, None),
            vec![
                StrategyUsed::DirectHttp,
                StrategyUsed::TlsProfiledHttp,
                StrategyUsed::BrowserLightStealth,
            ]
        );

        assert_eq!(
            AcquisitionRunner::strategy_ladder(
                AcquisitionMode::Investigate,
                Some(StrategyUsed::StickyProxyBrowserSession)
            ),
            vec![
                StrategyUsed::InvestigateEntry,
                StrategyUsed::StickyProxyBrowserSession,
                StrategyUsed::TlsProfiledHttp,
            ]
        );
    }

    #[test]
    fn block_statuses_are_classified() {
        assert!(is_block_status(Some(403)));
        assert!(is_block_status(Some(429)));
        assert!(!is_block_status(Some(200)));
        assert!(!is_block_status(None));
    }

    #[test]
    fn host_hint_extracts_authority() {
        assert_eq!(
            host_hint("https://user:pass@example.com:8443/path"),
            Some("example.com".to_string())
        );
    }

    #[test]
    fn truncate_html_respects_utf8_boundaries() {
        let src = "abc😀def";
        let out = truncate_html(src, 5);
        assert_eq!(out, "abc");
    }
}