centinel_analytica_fastly/

lib.rs

//! Centinel Analytica bot-protection SDK for Fastly Compute.
//!
//! # Quick start
//!
//! ```ignore
//! use centinel_analytica_fastly::Centinel;
//! use fastly::{Error, Request, Response};
//!
//! #[fastly::main]
//! fn main(req: Request) -> Result<Response, Error> {
//!     Centinel::protect(req, |r| r.send("origin"))
//! }
//! ```
//!
//! # Observability & extensibility
//!
//! - [`CentinelObserver`] + [`CentinelEvent`]: subscribe to lifecycle
//!   events (path excluded, validator call start/end/error, decision,
//!   script injected). Ship [`JsonLogObserver`] for Fastly log endpoints
//!   or implement your own.
//! - [`Hooks`]: mutate the outbound validator request, override the
//!   decision, or decorate the block/redirect response.
//! - [`TraceContext`]: incoming W3C `traceparent` / `tracestate` are
//!   forwarded to the validator so its span chains under the caller's
//!   trace.
//!
//! Every block/redirect response carries `Server-Timing`,
//! `x-centinel-decision`, and `x-centinel-request-id` headers for
//! correlation.

#![warn(missing_docs)]

pub mod client;
pub mod config;
pub mod decision;
pub mod exclusions;
pub mod hooks;
pub mod observer;
pub mod request;
pub mod script_injection;

use std::time::Instant;

use fastly::{Error, Request, Response};
use regex::Regex;

pub use config::{CentinelConfig, ConfigError, DEFAULT_EXCLUSION_PATTERN};
pub use decision::{CookieData, CrawlerInfo, Decision, ValidationResponse, MAX_REDIRECT_HTML_SIZE};
pub use hooks::Hooks;
pub use observer::{
    CentinelEvent, CentinelObserver, JsonLogObserver, NoopObserver, RecorderObserver, TraceContext,
};

const BASE64_DECODE_TABLE: [u8; 256] = {
    let mut table = [255u8; 256];
    let alphabet = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
    let mut i = 0;
    while i < 64 {
        table[alphabet[i] as usize] = i as u8;
        i += 1;
    }
    table[b'=' as usize] = 64;
    table
};

fn base64_decode(encoded: &str) -> Result<String, String> {
    let bytes = base64_decode_bytes(encoded)?;
    std::str::from_utf8(&bytes)
        .map(|s| s.to_string())
        .map_err(|e| format!("UTF-8 decode error: {}", e))
}

fn base64_decode_bytes(encoded: &str) -> Result<Vec<u8>, String> {
    let input: Vec<u8> = encoded
        .bytes()
        .filter(|b| !b.is_ascii_whitespace())
        .collect();
    let mut result = Vec::with_capacity(input.len() * 3 / 4);

    for chunk in input.chunks(4) {
        if chunk.is_empty() {
            break;
        }

        let mut buf = [0u8; 4];
        for (i, &b) in chunk.iter().enumerate() {
            let val = BASE64_DECODE_TABLE[b as usize];
            if val == 255 {
                return Err(format!("Invalid base64 character: {}", b as char));
            }
            buf[i] = val;
        }

        result.push((buf[0] << 2) | (buf[1] >> 4));
        if buf[2] != 64 {
            result.push((buf[1] << 4) | (buf[2] >> 2));
        }
        if buf[3] != 64 {
            result.push((buf[2] << 6) | buf[3]);
        }
    }

    Ok(result)
}

fn apply_cookies(response: &mut Response, cookies: &[CookieData]) {
    for cookie in cookies {
        let mut val = format!("{}={}", cookie.name, cookie.value);
        if let Some(ref path) = cookie.path {
            if !path.is_empty() {
                val.push_str("; Path=");
                val.push_str(path);
            }
        }
        if let Some(ref domain) = cookie.domain {
            if !domain.is_empty() {
                val.push_str("; Domain=");
                val.push_str(domain);
            }
        }
        val.push_str("; SameSite=Lax; Secure");
        response.append_header("Set-Cookie", val);
    }
}

fn apply_response_headers(
    response: &mut Response,
    headers: &Option<std::collections::HashMap<String, String>>,
) {
    if let Some(ref headers) = headers {
        for (name, value) in headers {
            if !decision::is_blocked_header(name) {
                response.set_header(name, value);
            }
        }
    }
}

fn decode_decision_html(encoded: Option<&str>, fallback: &str) -> String {
    match encoded {
        Some(b64) if !b64.is_empty() && b64.len() <= MAX_REDIRECT_HTML_SIZE => {
            base64_decode(b64).unwrap_or_else(|_| fallback.to_string())
        }
        _ => fallback.to_string(),
    }
}

fn append_server_timing(response: &mut Response, duration_ms: u128) {
    let entry = format!("validator;dur={}", duration_ms);
    let existing = response
        .get_header("Server-Timing")
        .and_then(|v| std::str::from_utf8(v.as_bytes()).ok())
        .filter(|s| !s.is_empty());
    let merged = match existing {
        Some(existing) => format!("{}, {}", existing, entry),
        None => entry,
    };
    response.set_header("Server-Timing", merged);
}

fn add_correlation_headers(
    response: &mut Response,
    decision: &Decision,
    request_id: Option<&str>,
    duration_ms: u128,
) {
    append_server_timing(response, duration_ms);
    response.set_header("x-centinel-decision", decision.as_str());
    if let Some(rid) = request_id {
        response.set_header("x-centinel-request-id", rid);
    }
}

fn build_decision_response(
    status: u16,
    body: impl Into<fastly::Body>,
    api_response: &ValidationResponse,
    duration_ms: u128,
) -> Response {
    let mut response = Response::from_status(status).with_body(body);
    apply_response_headers(&mut response, &api_response.headers);
    apply_cookies(&mut response, &api_response.cookies);
    add_correlation_headers(
        &mut response,
        &api_response.decision,
        api_response.request_id.as_deref(),
        duration_ms,
    );
    response
}

/// Entry point for Centinel bot protection.
///
/// Construct via [`Centinel::new`] (reads the `centinel` Config Store)
/// or [`Centinel::with_config`] (explicit configuration). Attach an
/// observer with [`Centinel::with_observer`] and/or hooks with
/// [`Centinel::with_hooks`] before handling traffic.
///
/// The typical shape in a Fastly Compute `main` is:
///
/// ```ignore
/// let centinel = Centinel::new()?;
/// centinel.handle_request(req, |r| r.send("origin"))
/// ```
pub struct Centinel {
    config: CentinelConfig,
    exclusion_regex: Option<Regex>,
    inclusion_regex: Option<Regex>,
    observer: Box<dyn CentinelObserver>,
    hooks: Hooks,
}

struct CheckOutcome {
    response: Option<Response>,
    validator_duration_ms: Option<u128>,
}

impl Centinel {
    /// Load configuration from the Fastly Config Store named `centinel`
    /// and construct a [`Centinel`].
    pub fn new() -> Result<Self, ConfigError> {
        let config = CentinelConfig::from_config_store()?;
        Self::with_config(config)
    }

    /// Construct a [`Centinel`] from an explicit [`CentinelConfig`].
    ///
    /// Regex patterns in the config are compiled eagerly; invalid
    /// patterns return [`ConfigError::InvalidPattern`].
    pub fn with_config(config: CentinelConfig) -> Result<Self, ConfigError> {
        let exclusion_regex = config
            .url_exclusion_pattern
            .as_ref()
            .map(|p| Regex::new(p).map_err(|e| ConfigError::InvalidPattern(e.to_string())))
            .transpose()?;

        let inclusion_regex = config
            .url_inclusion_pattern
            .as_ref()
            .map(|p| Regex::new(p).map_err(|e| ConfigError::InvalidPattern(e.to_string())))
            .transpose()?;

        Ok(Self {
            config,
            exclusion_regex,
            inclusion_regex,
            observer: Box::new(NoopObserver),
            hooks: Hooks::default(),
        })
    }

    /// Attach an observer that receives lifecycle [`CentinelEvent`]s.
    /// Default is [`NoopObserver`].
    pub fn with_observer<O: CentinelObserver + 'static>(mut self, observer: O) -> Self {
        self.observer = Box::new(observer);
        self
    }

    /// Attach a set of consumer-supplied mutation [`Hooks`].
    pub fn with_hooks(mut self, hooks: Hooks) -> Self {
        self.hooks = hooks;
        self
    }

    /// One-shot helper: construct a [`Centinel`] from the Config Store
    /// and run [`Centinel::handle_request`]. Fails open (runs
    /// `on_allowed` directly) when configuration is missing.
    ///
    /// Does not support observers or hooks — build the instance
    /// manually when you need those.
    pub fn protect<F>(req: Request, on_allowed: F) -> Result<Response, Error>
    where
        F: FnOnce(Request) -> Result<Response, Error>,
    {
        match Self::new() {
            Ok(centinel) => centinel.handle_request(req, on_allowed),
            Err(_) => on_allowed(req),
        }
    }

    /// Inspect a request and return a block/redirect response when the
    /// validator says so; `Ok(None)` means the caller should forward.
    ///
    /// For full integration use [`Centinel::handle_request`], which also
    /// handles script injection and `Server-Timing` on allow responses.
    pub fn check_request(&self, req: &Request) -> Result<Option<Response>, Error> {
        Ok(self.check_internal(req)?.response)
    }

    fn check_internal(&self, req: &Request) -> Result<CheckOutcome, Error> {
        let path = req.get_path();

        if exclusions::should_exclude_path(
            path,
            self.exclusion_regex.as_ref(),
            self.inclusion_regex.as_ref(),
        ) {
            self.observer
                .on_event(&CentinelEvent::PathExcluded { path });
            return Ok(CheckOutcome {
                response: None,
                validator_duration_ms: None,
            });
        }

        let mut validation_req = request::ValidationRequest::from_fastly_request(req);
        if let Some(hook) = &self.hooks.before_validate {
            hook(&mut validation_req);
        }

        let trace = TraceContext::from_request(req);
        let validator_url = format!("{}/validate", self.config.api_endpoint);
        self.observer.on_event(&CentinelEvent::ValidatorCallStart {
            url: &validator_url,
            trace_ctx: trace,
        });

        let client = client::CentinelClient::new(&self.config);
        let call_started = Instant::now();

        match client.validate(&validation_req, trace) {
            Ok((mut api_response, latency)) => {
                let duration_ms = latency.as_millis();
                self.observer.on_event(&CentinelEvent::ValidatorCallEnd {
                    status: 200,
                    duration_ms,
                    request_id: api_response.request_id.as_deref(),
                });

                if let Some(hook) = &self.hooks.after_validate {
                    hook(&mut api_response);
                }

                // success=false means the validator reported its own error;
                // treat as fail-open and skip the Decision event (no real
                // decision was made). Duration is still propagated so
                // Server-Timing reflects the round-trip.
                if !api_response.success {
                    return Ok(CheckOutcome {
                        response: None,
                        validator_duration_ms: Some(duration_ms),
                    });
                }

                let status_code = match api_response.decision {
                    Decision::Block => api_response.validated_status_code(403),
                    _ => api_response.validated_status_code(200),
                };

                self.observer.on_event(&CentinelEvent::Decision {
                    decision: &api_response.decision,
                    status_code,
                    request_id: api_response.request_id.as_deref(),
                    crawler: api_response.crawler.as_ref(),
                    validator_duration_ms: duration_ms,
                });

                let response = match api_response.decision {
                    Decision::Allow | Decision::NotMatched | Decision::Unknown => None,
                    Decision::Block => {
                        let body = decode_decision_html(
                            api_response.response_html.as_deref(),
                            "Access Denied",
                        );
                        let mut resp =
                            build_decision_response(status_code, body, &api_response, duration_ms);
                        if let Some(hook) = &self.hooks.decorate_response {
                            hook(&mut resp, &Decision::Block);
                        }
                        Some(resp)
                    }
                    Decision::Redirect => {
                        let html_b64 = match api_response.response_html {
                            Some(ref h) => h,
                            None => {
                                return Ok(CheckOutcome {
                                    response: None,
                                    validator_duration_ms: Some(duration_ms),
                                })
                            }
                        };
                        if html_b64.len() > MAX_REDIRECT_HTML_SIZE {
                            return Ok(CheckOutcome {
                                response: None,
                                validator_duration_ms: Some(duration_ms),
                            });
                        }
                        match base64_decode(html_b64) {
                            Ok(html) => {
                                let mut resp = build_decision_response(
                                    status_code,
                                    html,
                                    &api_response,
                                    duration_ms,
                                );
                                if let Some(hook) = &self.hooks.decorate_response {
                                    hook(&mut resp, &Decision::Redirect);
                                }
                                Some(resp)
                            }
                            Err(_) => None,
                        }
                    }
                };

                Ok(CheckOutcome {
                    response,
                    validator_duration_ms: Some(duration_ms),
                })
            }
            Err(e) => {
                let duration_ms = call_started.elapsed().as_millis();
                self.observer.on_event(&CentinelEvent::ValidatorError {
                    error: &e,
                    duration_ms,
                });
                Ok(CheckOutcome {
                    response: None,
                    validator_duration_ms: Some(duration_ms),
                })
            }
        }
    }

    /// Inject the collector `<script>` tag into an HTML response when a
    /// site key is configured. No-op otherwise or for non-HTML bodies.
    pub fn inject_script(&self, response: Response) -> Response {
        if let Some(ref site_key) = self.config.site_key {
            let (injected, bytes_added) = script_injection::inject_script(response, site_key);
            if bytes_added > 0 {
                self.observer
                    .on_event(&CentinelEvent::ScriptInjected { bytes_added });
            }
            injected
        } else {
            response
        }
    }

    /// `true` when a site key is configured (script injection enabled).
    pub fn has_site_key(&self) -> bool {
        self.config.site_key.is_some()
    }

    /// Full integration: validate, forward to origin via `on_allowed`,
    /// inject the collector script, and stamp `Server-Timing`.
    ///
    /// Fails open on any validator error.
    pub fn handle_request<F>(&self, req: Request, on_allowed: F) -> Result<Response, Error>
    where
        F: FnOnce(Request) -> Result<Response, Error>,
    {
        let outcome = self.check_internal(&req)?;
        if let Some(resp) = outcome.response {
            return Ok(resp);
        }

        let mut resp = on_allowed(req)?;

        if let Some(dur) = outcome.validator_duration_ms {
            append_server_timing(&mut resp, dur);
        }

        if self.has_site_key() {
            resp = self.inject_script(resp);
        }

        Ok(resp)
    }
}

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

    // --- Base64 correctness ---

    #[test]
    fn test_base64_lookup_table_correctness() {
        let alphabet = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
        for (i, &byte) in alphabet.iter().enumerate() {
            assert_eq!(
                BASE64_DECODE_TABLE[byte as usize], i as u8,
                "Lookup table wrong for '{}' at index {}",
                byte as char, i
            );
        }
        assert_eq!(BASE64_DECODE_TABLE[b'=' as usize], 64);
        for b in [b'!', b'@', b'#', b'$', b'%', b'^', b'&', b'*'] {
            assert_eq!(BASE64_DECODE_TABLE[b as usize], 255);
        }
    }

    #[test]
    fn test_base64_known_values() {
        assert_eq!(base64_decode("SGVsbG8=").unwrap(), "Hello");
        assert_eq!(base64_decode("SGVsbG8gV29ybGQ=").unwrap(), "Hello World");
        assert_eq!(base64_decode("").unwrap(), "");
        assert_eq!(base64_decode("YQ==").unwrap(), "a");
        assert_eq!(base64_decode("YWI=").unwrap(), "ab");
        assert_eq!(base64_decode("YWJj").unwrap(), "abc");
    }

    #[test]
    fn test_base64_html_payload() {
        let html = "<html><body><h1>Challenge</h1></body></html>";
        let encoded = "PGh0bWw+PGJvZHk+PGgxPkNoYWxsZW5nZTwvaDE+PC9ib2R5PjwvaHRtbD4=";
        assert_eq!(base64_decode(encoded).unwrap(), html);
    }

    #[test]
    fn test_base64_with_whitespace() {
        // Base64 with line breaks (common in PEM-style encodings)
        let encoded = "SGVs\nbG8g\nV29y\nbGQ=";
        assert_eq!(base64_decode(encoded).unwrap(), "Hello World");
    }

    #[test]
    fn test_base64_invalid_character() {
        assert!(base64_decode("SGVs!G8=").is_err());
        assert!(base64_decode("@@@").is_err());
    }

    #[test]
    fn test_base64_non_utf8_returns_error() {
        // /w== decodes to [0xFF] which is invalid UTF-8
        let result = base64_decode("/w==");
        assert!(
            result.is_err(),
            "Expected UTF-8 error for non-UTF8 bytes, got: {:?}",
            result
        );

        // But raw byte decoding should succeed
        let bytes = base64_decode_bytes("/w==").unwrap();
        assert_eq!(bytes, vec![0xFF]);
    }

    // --- Config validation ---

    #[test]
    fn test_with_config_valid_regex() {
        let config = CentinelConfig {
            url_exclusion_pattern: Some(r"\.(js|css)$".to_string()),
            url_inclusion_pattern: Some(r"^/api/".to_string()),
            ..CentinelConfig::default()
        };
        assert!(Centinel::with_config(config).is_ok());
    }

    #[test]
    fn test_with_config_invalid_exclusion_regex() {
        let config = CentinelConfig {
            url_exclusion_pattern: Some(r"[invalid".to_string()),
            ..CentinelConfig::default()
        };
        let result = Centinel::with_config(config);
        assert!(result.is_err());
        let err = result.err().unwrap();
        assert!(matches!(err, ConfigError::InvalidPattern(_)));
    }

    #[test]
    fn test_with_config_invalid_inclusion_regex() {
        let config = CentinelConfig {
            url_inclusion_pattern: Some(r"(unclosed".to_string()),
            ..CentinelConfig::default()
        };
        let result = Centinel::with_config(config);
        assert!(result.is_err());
        let err = result.err().unwrap();
        assert!(matches!(err, ConfigError::InvalidPattern(_)));
    }

    #[test]
    fn test_with_config_no_patterns() {
        let config = CentinelConfig {
            url_exclusion_pattern: None,
            url_inclusion_pattern: None,
            ..CentinelConfig::default()
        };
        let centinel = Centinel::with_config(config).unwrap();
        assert!(centinel.exclusion_regex.is_none());
        assert!(centinel.inclusion_regex.is_none());
    }

    // --- decode_decision_html ---

    #[test]
    fn test_decode_decision_html_decodes_valid_base64() {
        assert_eq!(
            decode_decision_html(Some("PGgxPkJsb2NrZWQ8L2gxPg=="), "fallback"),
            "<h1>Blocked</h1>"
        );
    }

    #[test]
    fn test_decode_decision_html_none_returns_fallback() {
        assert_eq!(decode_decision_html(None, "Access Denied"), "Access Denied");
    }

    #[test]
    fn test_decode_decision_html_empty_returns_fallback() {
        assert_eq!(
            decode_decision_html(Some(""), "Access Denied"),
            "Access Denied"
        );
    }

    #[test]
    fn test_decode_decision_html_invalid_base64_returns_fallback() {
        assert_eq!(
            decode_decision_html(Some("!!!not-base64!!!"), "Access Denied"),
            "Access Denied"
        );
    }

    #[test]
    fn test_decode_decision_html_oversize_returns_fallback() {
        let huge = "A".repeat(MAX_REDIRECT_HTML_SIZE + 1);
        assert_eq!(
            decode_decision_html(Some(&huge), "Access Denied"),
            "Access Denied"
        );
    }

    // --- apply_cookies ---

    #[test]
    fn test_apply_cookies_full() {
        let cookies = vec![CookieData {
            name: "_centinel".to_string(),
            value: "abc123".to_string(),
            path: Some("/".to_string()),
            domain: Some(".example.com".to_string()),
        }];
        let mut response = Response::from_status(200);
        apply_cookies(&mut response, &cookies);
        let cookie_header = response.get_header_str("Set-Cookie").unwrap().to_string();
        assert!(cookie_header.contains("_centinel=abc123"));
        assert!(cookie_header.contains("; Path=/"));
        assert!(cookie_header.contains("; Domain=.example.com"));
    }

    #[test]
    fn test_apply_cookies_no_optional_fields() {
        let cookies = vec![CookieData {
            name: "simple".to_string(),
            value: "val".to_string(),
            path: None,
            domain: None,
        }];
        let mut response = Response::from_status(200);
        apply_cookies(&mut response, &cookies);
        let cookie_header = response.get_header_str("Set-Cookie").unwrap().to_string();
        assert_eq!(cookie_header, "simple=val; SameSite=Lax; Secure");
    }

    #[test]
    fn test_apply_cookies_empty() {
        let mut response = Response::from_status(200);
        apply_cookies(&mut response, &[]);
        assert!(response.get_header_str("Set-Cookie").is_none());
    }

    // --- apply_response_headers ---

    #[test]
    fn test_apply_response_headers_filters_blocked() {
        let mut headers = std::collections::HashMap::new();
        headers.insert("Content-Type".to_string(), "text/html".to_string());
        headers.insert("Transfer-Encoding".to_string(), "chunked".to_string());
        headers.insert("Connection".to_string(), "keep-alive".to_string());
        headers.insert("X-Custom".to_string(), "allowed".to_string());

        let mut response = Response::from_status(200);
        apply_response_headers(&mut response, &Some(headers));

        assert_eq!(
            response.get_header_str("Content-Type").unwrap(),
            "text/html"
        );
        assert_eq!(response.get_header_str("X-Custom").unwrap(), "allowed");
        assert!(response.get_header_str("Transfer-Encoding").is_none());
        assert!(response.get_header_str("Connection").is_none());
    }

    #[test]
    fn test_apply_response_headers_none() {
        let mut response = Response::from_status(200);
        apply_response_headers(&mut response, &None);
        // Should not panic, no headers added
    }

    // --- build_decision_response ---

    #[test]
    fn test_build_decision_response_block() {
        let api_response = ValidationResponse {
            success: true,
            status_code: Some(403),
            request_id: Some("req-123".to_string()),
            decision: Decision::Block,
            response_html: None,
            cookies: vec![CookieData {
                name: "_c".to_string(),
                value: "v1".to_string(),
                path: Some("/".to_string()),
                domain: None,
            }],
            headers: Some({
                let mut h = std::collections::HashMap::new();
                h.insert("Cache-Control".to_string(), "no-store".to_string());
                h
            }),
            crawler: None,
        };

        let resp = build_decision_response(403, "Blocked", &api_response, 42);
        assert_eq!(resp.get_status().as_u16(), 403);
        assert_eq!(
            resp.get_header_str("Server-Timing").unwrap(),
            "validator;dur=42"
        );
        assert_eq!(resp.get_header_str("x-centinel-decision").unwrap(), "block");
        assert_eq!(
            resp.get_header_str("x-centinel-request-id").unwrap(),
            "req-123"
        );
        assert_eq!(resp.get_header_str("Cache-Control").unwrap(), "no-store");
        assert!(resp.get_header_str("Set-Cookie").unwrap().contains("_c=v1"));
    }

    #[test]
    fn test_append_server_timing_merges_existing() {
        let mut resp = Response::from_status(200);
        resp.set_header("Server-Timing", "origin;dur=10");
        append_server_timing(&mut resp, 42);
        assert_eq!(
            resp.get_header_str("Server-Timing").unwrap(),
            "origin;dur=10, validator;dur=42"
        );
    }

    #[test]
    fn test_append_server_timing_sets_when_missing() {
        let mut resp = Response::from_status(200);
        append_server_timing(&mut resp, 7);
        assert_eq!(
            resp.get_header_str("Server-Timing").unwrap(),
            "validator;dur=7"
        );
    }

    // --- observer wiring ---

    #[test]
    fn test_inject_script_emits_event_for_html() {
        let config = CentinelConfig {
            site_key: Some("test-key".to_string()),
            ..CentinelConfig::default()
        };
        let recorder = RecorderObserver::new();
        let centinel = Centinel::with_config(config).unwrap();
        let centinel = centinel.with_observer(recorder);
        let html = Response::new().with_body_text_html("<html><body>x</body></html>");
        let _out = centinel.inject_script(html);
        // The RecorderObserver was moved into Centinel; we can't read back
        // its events without Rc/RefCell plumbing. This test just exercises
        // the code path and ensures no panic.
    }

    #[test]
    fn test_inject_script_no_event_for_non_html() {
        use std::cell::RefCell;
        use std::rc::Rc;

        struct RcRecorder(Rc<RefCell<usize>>);
        impl CentinelObserver for RcRecorder {
            fn on_event(&self, _e: &CentinelEvent<'_>) {
                *self.0.borrow_mut() += 1;
            }
        }

        let counter = Rc::new(RefCell::new(0usize));
        let config = CentinelConfig {
            site_key: Some("k".to_string()),
            ..CentinelConfig::default()
        };
        let centinel = Centinel::with_config(config)
            .unwrap()
            .with_observer(RcRecorder(counter.clone()));

        let json = Response::new()
            .with_body_text_plain(r#"{"x":1}"#)
            .with_header("Content-Type", "application/json");
        let _ = centinel.inject_script(json);
        assert_eq!(*counter.borrow(), 0, "no event for non-HTML");

        let html = Response::new().with_body_text_html("<p>hi</p>");
        let _ = centinel.inject_script(html);
        assert_eq!(*counter.borrow(), 1, "one event for HTML injection");
    }

    // --- has_site_key ---

    #[test]
    fn test_has_site_key() {
        let config_with = CentinelConfig {
            site_key: Some("key".to_string()),
            ..CentinelConfig::default()
        };
        let centinel = Centinel::with_config(config_with).unwrap();
        assert!(centinel.has_site_key());

        let config_without = CentinelConfig {
            site_key: None,
            ..CentinelConfig::default()
        };
        let centinel = Centinel::with_config(config_without).unwrap();
        assert!(!centinel.has_site_key());
    }
}

#[cfg(test)]
mod perf_tests {
    use super::*;
    use std::time::Instant;

    fn make_base64_payload(decoded_size: usize) -> String {
        const ALPHABET: &[u8] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
        let encoded_len = decoded_size.div_ceil(3) * 4;
        (0..encoded_len).map(|i| ALPHABET[i % 64] as char).collect()
    }

    #[test]
    fn perf_base64_decode_1kb() {
        let payload = make_base64_payload(1024);
        let iterations = 1000;
        let start = Instant::now();
        for _ in 0..iterations {
            let _ = base64_decode_bytes(payload.as_str());
        }
        let per_op = start.elapsed() / iterations;
        assert!(
            per_op.as_micros() < 500,
            "base64 1KB: {:?}/op (limit: 500µs)",
            per_op
        );
    }

    #[test]
    fn perf_base64_decode_10kb() {
        let payload = make_base64_payload(10 * 1024);
        let iterations = 100;
        let start = Instant::now();
        for _ in 0..iterations {
            let _ = base64_decode_bytes(payload.as_str());
        }
        let per_op = start.elapsed() / iterations;
        assert!(
            per_op.as_micros() < 2000,
            "base64 10KB: {:?}/op (limit: 2ms)",
            per_op
        );
    }

    #[test]
    fn perf_base64_decode_100kb() {
        let payload = make_base64_payload(100 * 1024);
        let iterations = 10;
        let start = Instant::now();
        for _ in 0..iterations {
            let _ = base64_decode_bytes(payload.as_str());
        }
        let per_op = start.elapsed() / iterations;
        assert!(
            per_op.as_millis() < 20,
            "base64 100KB: {:?}/op (limit: 20ms)",
            per_op
        );
    }

    #[test]
    fn perf_path_exclusion_default_pattern() {
        let regex = Regex::new(DEFAULT_EXCLUSION_PATTERN).unwrap();
        let paths = [
            "/static/app.js",
            "/images/logo.png",
            "/fonts/font.woff2",
            "/api/users",
            "/index.html",
            "/products/123",
            "/styles/main.css",
            "/video/stream.mp4",
        ];
        let iterations = 10_000;
        let start = Instant::now();
        for _ in 0..iterations {
            for path in &paths {
                let _ = exclusions::should_exclude_path(path, Some(&regex), None);
            }
        }
        let per_op = start.elapsed() / (iterations * paths.len() as u32);
        assert!(
            per_op.as_micros() < 50,
            "path exclusion: {:?}/op (limit: 50µs)",
            per_op
        );
    }

    #[test]
    fn perf_path_exclusion_combined_patterns() {
        let exclusion = Regex::new(DEFAULT_EXCLUSION_PATTERN).unwrap();
        let inclusion = Regex::new(r"^/(api|admin|protected)/").unwrap();
        let paths = [
            "/api/users",
            "/admin/dashboard",
            "/protected/data",
            "/public/page",
            "/api/data.json",
            "/static/app.js",
        ];
        let iterations = 10_000;
        let start = Instant::now();
        for _ in 0..iterations {
            for path in &paths {
                let _ = exclusions::should_exclude_path(path, Some(&exclusion), Some(&inclusion));
            }
        }
        let per_op = start.elapsed() / (iterations * paths.len() as u32);
        assert!(
            per_op.as_micros() < 50,
            "combined path exclusion: {:?}/op (limit: 50µs)",
            per_op
        );
    }

    #[test]
    fn perf_script_injection_small_html() {
        let html = "<html><head><title>Test</title></head><body><p>Hello</p></body></html>";
        let iterations = 1000;
        let start = Instant::now();
        for _ in 0..iterations {
            let response = Response::new().with_body_text_html(html);
            let (_resp, _bytes) = script_injection::inject_script(response, "test-site-key-abc123");
        }
        let per_op = start.elapsed() / iterations;
        assert!(
            per_op.as_micros() < 500,
            "script injection small: {:?}/op (limit: 500µs)",
            per_op
        );
    }

    #[test]
    fn perf_script_injection_large_html() {
        let body_content: String = "<p>Lorem ipsum dolor sit amet. </p>\n".repeat(1000);
        let html = format!(
            "<html><head><title>Large</title></head><body>{}</body></html>",
            body_content
        );
        let iterations = 100;
        let start = Instant::now();
        for _ in 0..iterations {
            let response = Response::new().with_body_text_html(&html);
            let (_resp, _bytes) = script_injection::inject_script(response, "test-site-key-abc123");
        }
        let per_op = start.elapsed() / iterations;
        assert!(
            per_op.as_millis() < 10,
            "script injection large: {:?}/op (limit: 10ms)",
            per_op
        );
    }

    #[test]
    fn perf_validation_response_deserialize() {
        let json = r#"{"success":true,"decision":"allow","status_code":200,"request_id":"req-abc",
            "cookies":[{"name":"_c","value":"v1","path":"/","domain":".example.com"}],
            "headers":{"Content-Type":"text/html","Cache-Control":"no-store"},
            "crawler":{"id":"b1","name":"Googlebot","category":"search","access_allowed":true}}"#;
        let iterations = 5000;
        let start = Instant::now();
        for _ in 0..iterations {
            let _: ValidationResponse = serde_json::from_str(json).unwrap();
        }
        let per_op = start.elapsed() / iterations;
        assert!(
            per_op.as_micros() < 200,
            "JSON deser: {:?}/op (limit: 200µs)",
            per_op
        );
    }

    #[test]
    fn perf_validation_request_serialize() {
        let mut headers = std::collections::HashMap::with_capacity(5);
        headers.insert("User-Agent".to_string(), "Mozilla/5.0".to_string());
        headers.insert("Accept".to_string(), "text/html".to_string());
        let req = request::ValidationRequest {
            url: "https://example.com/api/resource".to_string(),
            method: "GET".to_string(),
            ip: "203.0.113.42".to_string(),
            headers,
            referrer: "https://example.com/".to_string(),
            cookie: "abc123".to_string(),
        };
        let iterations = 5000;
        let start = Instant::now();
        for _ in 0..iterations {
            let _ = serde_json::to_string(&req).unwrap();
        }
        let per_op = start.elapsed() / iterations;
        assert!(
            per_op.as_micros() < 200,
            "JSON ser: {:?}/op (limit: 200µs)",
            per_op
        );
    }

    #[test]
    fn perf_apply_cookies() {
        let cookies = vec![
            CookieData {
                name: "_c".to_string(),
                value: "v1".to_string(),
                path: Some("/".to_string()),
                domain: Some(".example.com".to_string()),
            },
            CookieData {
                name: "_s".to_string(),
                value: "v2".to_string(),
                path: Some("/".to_string()),
                domain: None,
            },
            CookieData {
                name: "_t".to_string(),
                value: "v3".to_string(),
                path: None,
                domain: None,
            },
        ];
        let iterations = 5000;
        let start = Instant::now();
        for _ in 0..iterations {
            let mut response = Response::from_status(200);
            apply_cookies(&mut response, &cookies);
        }
        let per_op = start.elapsed() / iterations;
        assert!(
            per_op.as_micros() < 100,
            "apply_cookies: {:?}/op (limit: 100µs)",
            per_op
        );
    }

    #[test]
    fn perf_centinel_with_config() {
        let config = CentinelConfig {
            url_exclusion_pattern: Some(DEFAULT_EXCLUSION_PATTERN.to_string()),
            url_inclusion_pattern: Some(r"^/(api|admin)/".to_string()),
            ..CentinelConfig::default()
        };
        let iterations = 100;
        let start = Instant::now();
        for _ in 0..iterations {
            let _ = Centinel::with_config(config.clone()).unwrap();
        }
        let per_op = start.elapsed() / iterations;
        assert!(
            per_op.as_millis() < 50,
            "config init: {:?}/op (limit: 50ms)",
            per_op
        );
    }
}