captchaforge 0.2.28

//! Solver telemetry — structured event hooks for external analytics.
//!
//! The solver chain already logs to `tracing` and updates the
//! [`crate::solver::PatternStore`] for routing decisions, but
//! neither is suitable for durable metrics: tracing output is
//! operator-facing text, and the pattern store is a learned-routing
//! cache that prunes old entries. Production users want to know
//! per-solver success rates, p50/p95 solve times, fallback rates
//! per domain, and time-series trends.
//!
//! [`SolverTelemetry`] is a tiny trait the chain calls at every
//! solver-attempt outcome. The default implementation is a no-op, so
//! adding telemetry is opt-in: pass an `Arc<dyn SolverTelemetry>` via
//! [`crate::solver::CaptchaSolverChain::with_telemetry`] and your
//! impl receives every event.
//!
//! Implementations are free to: write to Prometheus, push to a
//! statsd/OTel collector, batch into SQLite, post to Sentry, mirror
//! into the pattern store, or ignore the events entirely. The trait
//! is intentionally allocation-light — events borrow strings where
//! possible — so a high-throughput impl can avoid heap churn.
use crate::captcha_detect::DetectedCaptcha;
use crate::solver::{CaptchaType, SolveMethod};

/// What happened during a single solver attempt.
///
/// `Success`/`Failure` correspond to the solver returning
/// `Ok(result)` with `result.success = true`/`false`. `Error` means
/// the solver returned `Err`. `Timeout` means the chain's per-solver
/// deadline elapsed before the solver returned anything.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum SolveOutcome {
    Success,
    Failure,
    Error,
    Timeout,
}

/// One solver attempt's telemetry event. Borrowed where possible so
/// hot-path implementations can avoid allocation.
///
/// `confidence` is only present on `Success` outcomes — the other
/// outcomes have no meaningful confidence value.
#[derive(Debug, Clone)]
#[non_exhaustive]
pub struct SolveEvent<'a> {
    /// Stable solver identifier (e.g. `"VlmCaptchaSolver"`).
    pub solver: &'static str,
    /// Captcha type the chain mapped from the detection.
    pub captcha_type: &'a CaptchaType,
    /// Original detected captcha kind from the detector.
    pub kind: &'a DetectedCaptcha,
    /// Domain the solve targeted, parsed from `CaptchaInfo.page_url`.
    pub domain: &'a str,
    /// What happened.
    pub outcome: SolveOutcome,
    /// Wall-clock duration of the attempt, in milliseconds.
    pub time_ms: u64,
    /// Solve confidence in 0.0–1.0; `None` for non-Success outcomes.
    pub confidence: Option<f32>,
    /// Which solver strategy the attempt used.
    pub method: &'a SolveMethod,
}

impl<'a> SolveEvent<'a> {
    /// Construct a `SolveEvent`. Required for external callers because
    /// the struct is `#[non_exhaustive]` (so the crate can add fields
    /// without a SemVer break) — direct struct-literal construction is
    /// not allowed across crate boundaries.
    #[allow(clippy::too_many_arguments)]
    pub fn new(
        solver: &'static str,
        captcha_type: &'a CaptchaType,
        kind: &'a DetectedCaptcha,
        domain: &'a str,
        outcome: SolveOutcome,
        time_ms: u64,
        confidence: Option<f32>,
        method: &'a SolveMethod,
    ) -> Self {
        Self {
            solver,
            captcha_type,
            kind,
            domain,
            outcome,
            time_ms,
            confidence,
            method,
        }
    }
}

/// Hook the solver chain calls at every attempt outcome.
///
/// Implementations MUST be cheap — the chain calls `record` from the
/// hot solve path. Slow implementations (network writes, blocking
/// I/O) should buffer or spawn so they don't extend solve latency.
pub trait SolverTelemetry: Send + Sync {
    /// Called once per solver attempt. The reference is short-lived;
    /// implementations that need to persist must clone.
    fn record(&self, evt: &SolveEvent<'_>);
}

/// Default zero-overhead implementation — drops every event.
///
/// Used as the chain's telemetry until a real implementation is
/// installed via [`crate::solver::CaptchaSolverChain::with_telemetry`].
pub struct NoopTelemetry;

impl SolverTelemetry for NoopTelemetry {
    fn record(&self, _evt: &SolveEvent<'_>) {}
}

/// Telemetry that emits each event as a `tracing::info!` with
/// structured fields — pairs naturally with `tracing-subscriber`'s
/// JSON layer for routing into ELK / Loki / Datadog without any
/// extra integration code on the operator side.
///
/// Each event becomes one log line tagged with target
/// `"captchaforge.solve"`; consumer queries:
///
/// - `target == "captchaforge.solve" && outcome == "success"` →
///   per-solver success rate.
/// - `histogram(time_ms)` over `target == "captchaforge.solve"` →
///   p50/p95/p99 solve latency by `solver` + `domain`.
/// - `outcome == "timeout"` → per-vendor timeout rate.
///
/// Use [`MetricsTelemetry`] when you want in-process aggregation
/// (Prometheus-style); use this when you want raw events flowing
/// through your existing log pipeline.
pub struct JsonTelemetry;

impl SolverTelemetry for JsonTelemetry {
    fn record(&self, evt: &SolveEvent<'_>) {
        // `tracing::info!` macro doesn't accept dynamic `target`,
        // so emit via `event!` with explicit target. Field names
        // are stable — consumers join on them.
        tracing::event!(
            target: "captchaforge.solve",
            tracing::Level::INFO,
            solver = %evt.solver,
            outcome = %outcome_label(evt.outcome),
            domain = %evt.domain,
            captcha_type = ?evt.captcha_type,
            kind = ?evt.kind,
            method = ?evt.method,
            time_ms = evt.time_ms,
            confidence = evt.confidence.unwrap_or(f32::NAN),
        );
    }
}

/// Stable string label for an outcome. Used by both
/// [`JsonTelemetry`]'s log fields and [`MetricsTelemetry`]'s
/// counter keys so a Prometheus query and a log query see the same
/// label values.
fn outcome_label(o: SolveOutcome) -> &'static str {
    match o {
        SolveOutcome::Success => "success",
        SolveOutcome::Failure => "failure",
        SolveOutcome::Error => "error",
        SolveOutcome::Timeout => "timeout",
    }
}

/// In-process metrics aggregator for solver telemetry.
///
/// Maintains per-`(solver, outcome)` event counts plus
/// per-`(solver, outcome)` time-histogram buckets. Cheap enough to
/// be the default in production: each `record` call takes a brief
/// mutex + 2 small map lookups + a counter increment.
///
/// Read with [`MetricsTelemetry::snapshot`]; that returns a flat
/// [`MetricsSnapshot`] you can serialise to Prometheus / OpenMetrics
/// / JSON / your dashboard format of choice. The snapshot is a
/// point-in-time copy — concurrent `record` calls don't block the
/// reader, and the reader doesn't reset counters.
///
/// Histogram buckets are fixed at `[10ms, 50ms, 100ms, 500ms, 1s,
/// 5s, 10s, 30s, +inf]` — covers the typical captcha-solve latency
/// envelope (10ms cache hit → 30s VLM + retry).
pub struct MetricsTelemetry {
    inner: std::sync::Mutex<MetricsState>,
}

/// Mutex-protected aggregation state for [`MetricsTelemetry`].
#[derive(Default)]
struct MetricsState {
    counts: std::collections::HashMap<(String, &'static str), u64>,
    histograms: std::collections::HashMap<(String, &'static str), [u64; 9]>,
}

impl MetricsTelemetry {
    pub fn new() -> Self {
        Self {
            inner: std::sync::Mutex::new(MetricsState::default()),
        }
    }

    /// Take a point-in-time snapshot of every metric this telemetry
    /// has accumulated. Cheap to call repeatedly; doesn't reset.
    pub fn snapshot(&self) -> MetricsSnapshot {
        let inner = self.inner.lock().expect("metrics mutex poisoned");
        let counts = inner
            .counts
            .iter()
            .map(|((solver, outcome), n)| MetricCount {
                solver: solver.clone(),
                outcome,
                count: *n,
            })
            .collect();
        let histograms = inner
            .histograms
            .iter()
            .map(|((solver, outcome), buckets)| MetricHistogram {
                solver: solver.clone(),
                outcome,
                bucket_upper_bounds_ms: HISTOGRAM_BUCKETS_MS.to_vec(),
                bucket_counts: buckets.to_vec(),
            })
            .collect();
        MetricsSnapshot { counts, histograms }
    }
}

impl Default for MetricsTelemetry {
    fn default() -> Self {
        Self::new()
    }
}

impl SolverTelemetry for MetricsTelemetry {
    fn record(&self, evt: &SolveEvent<'_>) {
        let mut inner = self.inner.lock().expect("metrics mutex poisoned");
        let key = (evt.solver.to_string(), outcome_label(evt.outcome));
        *inner.counts.entry(key.clone()).or_insert(0) += 1;
        let buckets = inner.histograms.entry(key).or_insert([0u64; 9]);
        let bucket_idx = histogram_bucket_index(evt.time_ms);
        buckets[bucket_idx] += 1;
    }
}

/// Histogram bucket upper bounds in milliseconds. The final
/// `u64::MAX` is the +inf bucket (everything slower than 30s).
const HISTOGRAM_BUCKETS_MS: [u64; 9] = [10, 50, 100, 500, 1_000, 5_000, 10_000, 30_000, u64::MAX];

/// Index of the smallest bucket whose upper bound is ≥ `time_ms`.
/// Branch-light so the hot record path stays cheap.
fn histogram_bucket_index(time_ms: u64) -> usize {
    for (i, upper) in HISTOGRAM_BUCKETS_MS.iter().enumerate() {
        if time_ms <= *upper {
            return i;
        }
    }
    HISTOGRAM_BUCKETS_MS.len() - 1
}

/// Point-in-time snapshot of every metric a [`MetricsTelemetry`]
/// has accumulated. Implements `Serialize` so callers can hand it
/// straight to a JSON / Prometheus exposition layer.
#[derive(Debug, Clone, serde::Serialize)]
pub struct MetricsSnapshot {
    pub counts: Vec<MetricCount>,
    pub histograms: Vec<MetricHistogram>,
}

/// One `(solver, outcome) → count` entry.
#[derive(Debug, Clone, serde::Serialize)]
pub struct MetricCount {
    pub solver: String,
    pub outcome: &'static str,
    pub count: u64,
}

/// One `(solver, outcome) → bucketed time-histogram` entry.
///
/// `bucket_upper_bounds_ms` and `bucket_counts` are parallel: the
/// nth count belongs to the bucket with the nth upper bound. The
/// final `u64::MAX` bucket is the catch-all for events slower than
/// every other bound.
#[derive(Debug, Clone, serde::Serialize)]
pub struct MetricHistogram {
    pub solver: String,
    pub outcome: &'static str,
    pub bucket_upper_bounds_ms: Vec<u64>,
    pub bucket_counts: Vec<u64>,
}

impl MetricsSnapshot {
    /// Render every metric in Prometheus exposition-format text.
    /// Callers can serve this directly from a `/metrics` HTTP
    /// endpoint without any extra exporter library.
    ///
    /// Format reference:
    /// <https://prometheus.io/docs/instrumenting/exposition_formats/>
    pub fn to_prometheus(&self) -> String {
        use std::fmt::Write;
        let mut out = String::with_capacity(self.counts.len() * 64 + self.histograms.len() * 256);
        // Counter family
        out.push_str("# HELP captchaforge_solve_total Total solver attempts by solver + outcome.\n");
        out.push_str("# TYPE captchaforge_solve_total counter\n");
        for c in &self.counts {
            let _ = writeln!(
                out,
                r#"captchaforge_solve_total{{solver="{}",outcome="{}"}} {}"#,
                escape_label(&c.solver),
                c.outcome,
                c.count
            );
        }
        // Histogram family
        out.push_str(
            "# HELP captchaforge_solve_duration_ms Solve duration in milliseconds.\n",
        );
        out.push_str("# TYPE captchaforge_solve_duration_ms histogram\n");
        for h in &self.histograms {
            let mut cumulative = 0u64;
            for (upper, count) in h.bucket_upper_bounds_ms.iter().zip(h.bucket_counts.iter()) {
                cumulative += count;
                let upper_label = if *upper == u64::MAX {
                    "+Inf".to_string()
                } else {
                    upper.to_string()
                };
                let _ = writeln!(
                    out,
                    r#"captchaforge_solve_duration_ms_bucket{{solver="{}",outcome="{}",le="{}"}} {}"#,
                    escape_label(&h.solver),
                    h.outcome,
                    upper_label,
                    cumulative
                );
            }
            let total: u64 = h.bucket_counts.iter().sum();
            let _ = writeln!(
                out,
                r#"captchaforge_solve_duration_ms_count{{solver="{}",outcome="{}"}} {}"#,
                escape_label(&h.solver),
                h.outcome,
                total
            );
        }
        out
    }
}

/// Escape a Prometheus label value per the exposition format —
/// backslash + quote + newline. Conservative; never strips chars
/// (would mask real solver-name typos).
fn escape_label(value: &str) -> String {
    let mut out = String::with_capacity(value.len());
    for c in value.chars() {
        match c {
            '\\' => out.push_str(r"\\"),
            '"' => out.push_str(r#"\""#),
            '\n' => out.push_str(r"\n"),
            other => out.push(other),
        }
    }
    out
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::sync::{Arc, Mutex};

    /// In-memory telemetry sink for assertion in tests / examples.
    struct CapturingTelemetry {
        events: Mutex<Vec<(SolveOutcome, String, u64)>>,
    }

    impl SolverTelemetry for CapturingTelemetry {
        fn record(&self, evt: &SolveEvent<'_>) {
            self.events
                .lock()
                .unwrap()
                .push((evt.outcome, evt.domain.to_owned(), evt.time_ms));
        }
    }

    #[test]
    fn noop_telemetry_drops_events() {
        let t = NoopTelemetry;
        let kind = DetectedCaptcha::Turnstile;
        let captcha_type = CaptchaType::CloudflareTurnstile;
        let method = SolveMethod::BehavioralBypass;
        let evt = SolveEvent {
            solver: "TestSolver",
            captcha_type: &captcha_type,
            kind: &kind,
            domain: "example.com",
            outcome: SolveOutcome::Success,
            time_ms: 1234,
            confidence: Some(0.95),
            method: &method,
        };
        t.record(&evt);
        // No assertion needed; we're verifying it doesn't panic.
    }

    #[test]
    fn metrics_telemetry_aggregates_per_solver_outcome_counts() {
        let m = MetricsTelemetry::new();
        let kind = DetectedCaptcha::Turnstile;
        let captcha_type = CaptchaType::CloudflareTurnstile;
        let method = SolveMethod::BehavioralBypass;

        for (solver, outcome) in [
            ("BehavioralCaptchaSolver", SolveOutcome::Success),
            ("BehavioralCaptchaSolver", SolveOutcome::Success),
            ("BehavioralCaptchaSolver", SolveOutcome::Failure),
            ("VlmCaptchaSolver", SolveOutcome::Success),
        ] {
            m.record(&SolveEvent {
                solver,
                captcha_type: &captcha_type,
                kind: &kind,
                domain: "ex.com",
                outcome,
                time_ms: 100,
                confidence: None,
                method: &method,
            });
        }
        let snap = m.snapshot();
        let beh_succ = snap
            .counts
            .iter()
            .find(|c| c.solver == "BehavioralCaptchaSolver" && c.outcome == "success");
        assert_eq!(beh_succ.map(|c| c.count), Some(2));
        let beh_fail = snap
            .counts
            .iter()
            .find(|c| c.solver == "BehavioralCaptchaSolver" && c.outcome == "failure");
        assert_eq!(beh_fail.map(|c| c.count), Some(1));
    }

    #[test]
    fn metrics_histogram_bucket_index_partitions_correctly() {
        // Boundary values land in the bucket whose upper bound
        // they exactly equal, not the next one up.
        assert_eq!(histogram_bucket_index(0), 0);
        assert_eq!(histogram_bucket_index(10), 0);
        assert_eq!(histogram_bucket_index(11), 1);
        assert_eq!(histogram_bucket_index(50), 1);
        assert_eq!(histogram_bucket_index(100), 2);
        assert_eq!(histogram_bucket_index(500), 3);
        assert_eq!(histogram_bucket_index(1_000), 4);
        assert_eq!(histogram_bucket_index(5_000), 5);
        assert_eq!(histogram_bucket_index(10_000), 6);
        assert_eq!(histogram_bucket_index(30_000), 7);
        // Anything past 30s lands in the +inf bucket.
        assert_eq!(histogram_bucket_index(31_000), 8);
        assert_eq!(histogram_bucket_index(u64::MAX), 8);
    }

    #[test]
    fn metrics_to_prometheus_renders_valid_exposition_format() {
        let m = MetricsTelemetry::new();
        let kind = DetectedCaptcha::Turnstile;
        let captcha_type = CaptchaType::CloudflareTurnstile;
        let method = SolveMethod::BehavioralBypass;
        m.record(&SolveEvent {
            solver: "TestSolver",
            captcha_type: &captcha_type,
            kind: &kind,
            domain: "ex.com",
            outcome: SolveOutcome::Success,
            time_ms: 250,
            confidence: Some(0.9),
            method: &method,
        });
        let prom = m.snapshot().to_prometheus();
        // Must contain the documented metric names + label format.
        assert!(prom.contains("# HELP captchaforge_solve_total"));
        assert!(prom.contains("# TYPE captchaforge_solve_total counter"));
        assert!(prom.contains(r#"captchaforge_solve_total{solver="TestSolver",outcome="success"} 1"#));
        assert!(prom.contains("# HELP captchaforge_solve_duration_ms"));
        assert!(prom.contains("# TYPE captchaforge_solve_duration_ms histogram"));
        // Cumulative bucket count: a single 250ms event lands in
        // bucket 3 (le=500), so every bucket from le=500 onward
        // should report cumulative >=1.
        assert!(prom.contains(r#"captchaforge_solve_duration_ms_bucket{solver="TestSolver",outcome="success",le="500"} 1"#));
        assert!(prom.contains(r#"captchaforge_solve_duration_ms_bucket{solver="TestSolver",outcome="success",le="+Inf"} 1"#));
        // Smaller buckets should report 0.
        assert!(prom.contains(r#"captchaforge_solve_duration_ms_bucket{solver="TestSolver",outcome="success",le="10"} 0"#));
    }

    #[test]
    fn metrics_to_prometheus_escapes_problematic_label_chars() {
        let m = MetricsTelemetry::new();
        let kind = DetectedCaptcha::Turnstile;
        let captcha_type = CaptchaType::CloudflareTurnstile;
        let method = SolveMethod::BehavioralBypass;
        // Solver name with backslash + quote — must escape so the
        // exposition format stays parseable.
        m.record(&SolveEvent {
            solver: "Solver\"with\\quotes",
            captcha_type: &captcha_type,
            kind: &kind,
            domain: "ex.com",
            outcome: SolveOutcome::Success,
            time_ms: 10,
            confidence: None,
            method: &method,
        });
        let prom = m.snapshot().to_prometheus();
        // Quote → \", backslash → \\.
        assert!(prom.contains(r#"solver="Solver\"with\\quotes""#));
    }

    #[test]
    fn outcome_label_returns_stable_strings() {
        // Stability matters: Prometheus / log queries join on these
        // exact strings. A typo here breaks every dashboard.
        assert_eq!(outcome_label(SolveOutcome::Success), "success");
        assert_eq!(outcome_label(SolveOutcome::Failure), "failure");
        assert_eq!(outcome_label(SolveOutcome::Error), "error");
        assert_eq!(outcome_label(SolveOutcome::Timeout), "timeout");
    }

    #[test]
    fn json_telemetry_does_not_panic_on_record() {
        // We can't easily intercept the tracing output here without
        // a subscriber; the lightest assertion is just "doesn't
        // panic + doesn't allocate-bomb".
        let t = JsonTelemetry;
        let kind = DetectedCaptcha::Turnstile;
        let captcha_type = CaptchaType::CloudflareTurnstile;
        let method = SolveMethod::BehavioralBypass;
        for outcome in [
            SolveOutcome::Success,
            SolveOutcome::Failure,
            SolveOutcome::Error,
            SolveOutcome::Timeout,
        ] {
            t.record(&SolveEvent {
                solver: "TestSolver",
                captcha_type: &captcha_type,
                kind: &kind,
                domain: "x.test",
                outcome,
                time_ms: 100,
                confidence: None,
                method: &method,
            });
        }
    }

    #[test]
    fn capturing_telemetry_round_trips_event_fields() {
        let cap = Arc::new(CapturingTelemetry {
            events: Mutex::new(Vec::new()),
        });
        let kind = DetectedCaptcha::HCaptcha;
        let captcha_type = CaptchaType::HCaptcha;
        let method = SolveMethod::VisionLLM;

        for (outcome, ms) in [
            (SolveOutcome::Success, 1000_u64),
            (SolveOutcome::Failure, 2000),
            (SolveOutcome::Error, 50),
            (SolveOutcome::Timeout, 30000),
        ] {
            let evt = SolveEvent {
                solver: "TestSolver",
                captcha_type: &captcha_type,
                kind: &kind,
                domain: "x.test",
                outcome,
                time_ms: ms,
                confidence: None,
                method: &method,
            };
            cap.record(&evt);
        }
        let events = cap.events.lock().unwrap();
        assert_eq!(events.len(), 4);
        assert_eq!(events[0].0, SolveOutcome::Success);
        assert_eq!(events[3].2, 30000);
    }
}