captchaforge 0.2.39

//! 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<'_>) {}
}

/// Compose multiple telemetry sinks. Each `record` call fans out to
/// every wrapped sink in registration order. Use this when an
/// operator wants both in-process `MetricsTelemetry` (for `/metrics`)
/// AND a `JsonTelemetry` log stream AND a custom exporter pointed at
/// Datadog / Sentry / Honeycomb / etc.
///
/// All sinks share the same event; if one is slow it will block the
/// solve hot path, wrap slow sinks in their own buffering layer
/// before adding here.
///
/// # Example
///
/// ```rust,ignore
/// use std::sync::Arc;
/// use captchaforge::telemetry::{FanoutTelemetry, JsonTelemetry, MetricsTelemetry};
///
/// let metrics = Arc::new(MetricsTelemetry::new());
/// let fanout = Arc::new(
///     FanoutTelemetry::new()
///         .with_sink(metrics.clone())
///         .with_sink(Arc::new(JsonTelemetry))
/// );
/// let chain = captchaforge::solver::CaptchaSolverChain::default_chain()
///     .with_telemetry(fanout);
/// ```
pub struct FanoutTelemetry {
    sinks: Vec<std::sync::Arc<dyn SolverTelemetry>>,
}

impl FanoutTelemetry {
    pub fn new() -> Self {
        Self { sinks: Vec::new() }
    }

    /// Append a sink. Fanout calls record on every sink in
    /// registration order.
    #[must_use = "FanoutTelemetry::with_sink returns Self; assign or chain it"]
    pub fn with_sink(mut self, sink: std::sync::Arc<dyn SolverTelemetry>) -> Self {
        self.sinks.push(sink);
        self
    }

    pub fn len(&self) -> usize {
        self.sinks.len()
    }

    pub fn is_empty(&self) -> bool {
        self.sinks.is_empty()
    }
}

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

impl SolverTelemetry for FanoutTelemetry {
    fn record(&self, evt: &SolveEvent<'_>) {
        for sink in &self.sinks {
            sink.record(evt);
        }
    }
}

/// 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).
        //
        // `kind` is rendered through [`safe_kind_label`] so the
        // operator's custom rule names from `DetectedCaptcha::Custom`
        // don't get logged verbatim, those strings come from
        // user-supplied TOML and can encode sensitive info (vendor
        // names, internal product codenames, customer identifiers).
        // Built-in variants log their canonical name; Custom logs
        // `custom:<8-hex-chars-of-sha256>` so cardinality is bounded
        // and the operator's secret label is not in the log stream.
        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 = %safe_kind_label(evt.kind),
            method = ?evt.method,
            time_ms = evt.time_ms,
            confidence = evt.confidence.unwrap_or(f32::NAN),
        );
    }
}

/// Render a `DetectedCaptcha` for telemetry without leaking the
/// operator's `Custom(name)` label verbatim. Built-in variants
/// produce their `Debug` form; `Custom` produces `custom:<hex8>` so
/// cardinality stays bounded.
fn safe_kind_label(kind: &crate::detect::DetectedCaptcha) -> String {
    use crate::detect::DetectedCaptcha;
    match kind {
        DetectedCaptcha::Custom(name) => {
            use sha2::{Digest, Sha256};
            let mut h = Sha256::new();
            h.update(name.as_bytes());
            let d = h.finalize();
            format!("custom:{:02x}{:02x}{:02x}{:02x}", d[0], d[1], d[2], d[3])
        }
        other => format!("{other:?}"),
    }
}

/// 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)]
#[path = "telemetry/tests.rs"]
mod tests;