synapse_pingora/profiler/

endpoint_profile.rs

//! Per-endpoint statistical profile.
//!
//! Tracks baseline behavior for individual API endpoints including:
//! - Payload size distribution
//! - Expected parameters and their frequencies
//! - Content types observed
//! - Response status code distribution
//! - Request rate patterns
//!
//! ## Memory Budget
//! ~2KB per endpoint profile

use std::collections::HashMap;

use serde::{Deserialize, Serialize};

use crate::profiler::distribution::Distribution;
use crate::profiler::rate_tracker::RateTracker;

// ============================================================================
// Constants
// ============================================================================

/// Maximum number of content types to track per endpoint.
/// Prevents memory exhaustion from attackers sending many unique Content-Type headers.
const MAX_CONTENT_TYPES: usize = 20;

/// Maximum number of parameters to track per endpoint.
const MAX_PARAMS: usize = 50;

/// Maximum number of type categories per parameter (prevents memory exhaustion).
/// Type categories include: "numeric", "string", "email", "uuid"
const DEFAULT_MAX_TYPE_COUNTS: usize = 10;

// ============================================================================
// EndpointProfile - Per-endpoint baseline
// ============================================================================

/// Detailed statistics for a parameter value.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ParamStats {
    /// Frequency count
    pub count: u32,

    /// String length distribution
    pub length_dist: Distribution,

    /// Numeric value distribution (if applicable)
    pub numeric_dist: Distribution,

    /// Type counts
    pub type_counts: HashMap<String, u32>,
}

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

impl ParamStats {
    pub fn new() -> Self {
        Self {
            count: 0,
            length_dist: Distribution::new(),
            numeric_dist: Distribution::new(),
            type_counts: HashMap::with_capacity(4), // Pre-allocate for common types
        }
    }

    /// Update statistics with a new value.
    ///
    /// Type categories are bounded to prevent memory exhaustion attacks where
    /// an attacker sends many values designed to create unique type categories.
    pub fn update(&mut self, value: &str) {
        self.update_with_limit(value, DEFAULT_MAX_TYPE_COUNTS);
    }

    /// Update with configurable type count limit.
    pub fn update_with_limit(&mut self, value: &str, max_type_counts: usize) {
        self.count += 1;
        self.length_dist.update(value.len() as f64);

        // Helper to safely increment type count with bounds checking
        let mut increment_type = |type_name: &str| {
            // Only add if already tracked OR under limit
            if self.type_counts.contains_key(type_name) || self.type_counts.len() < max_type_counts
            {
                *self.type_counts.entry(type_name.to_string()).or_insert(0) += 1;
            }
        };

        // Try to parse as number
        if let Ok(num) = value.parse::<f64>() {
            self.numeric_dist.update(num);
            increment_type("numeric");
        } else {
            increment_type("string");
        }

        // Detect specific types (PII patterns)
        if value.contains('@') && value.contains('.') {
            increment_type("email");
        }
        if value.len() == 36 && value.chars().filter(|&c| c == '-').count() == 4 {
            increment_type("uuid");
        }
    }
}

// ============================================================================
// PII Redaction Helpers
// ============================================================================

/// Redact potentially sensitive parameter values for logging/display.
///
/// Masks middle portion of values to prevent PII leakage while preserving
/// enough information for debugging.
pub fn redact_value(value: &str) -> String {
    let len = value.len();
    if len <= 4 {
        // Too short to meaningfully redact
        return "*".repeat(len);
    }

    // Show first 2 and last 2 characters, mask the rest
    let visible_chars = 2;
    let start: String = value.chars().take(visible_chars).collect();
    let end: String = value.chars().skip(len - visible_chars).collect();
    let mask_len = len.saturating_sub(visible_chars * 2);

    format!("{}{}{}", start, "*".repeat(mask_len.max(1)), end)
}

/// Check if a value appears to contain PII.
pub fn is_likely_pii(value: &str) -> bool {
    // Email pattern
    if value.contains('@') && value.contains('.') {
        return true;
    }
    // UUID pattern
    if value.len() == 36 && value.chars().filter(|&c| c == '-').count() == 4 {
        return true;
    }
    // Long alphanumeric (tokens, API keys)
    if value.len() > 20
        && value
            .chars()
            .all(|c| c.is_alphanumeric() || c == '-' || c == '_')
    {
        return true;
    }
    false
}

/// Statistical profile for a single API endpoint.
///
/// Memory budget: ~2KB per endpoint
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct EndpointProfile {
    /// Path template (e.g., "/api/users/{id}")
    pub template: String,

    /// Payload size distribution (bytes)
    pub payload_size: Distribution,

    /// Response size distribution (bytes)
    pub response_size: Distribution,

    /// Expected query parameters (name -> stats)
    /// Capped at MAX_PARAMS parameters
    pub expected_params: HashMap<String, ParamStats>,

    /// Expected content types (type -> frequency count)
    pub content_types: HashMap<String, u32>,

    /// Expected response content types (type -> frequency count)
    pub response_content_types: HashMap<String, u32>,

    /// HTTP status codes (code -> count)
    pub status_codes: HashMap<u16, u32>,

    /// Request rate tracker (60-second window)
    pub request_rate: RateTracker,

    /// Aggregate endpoint risk score (0.0-100.0)
    /// Computed from attack density and vulnerability indicators
    pub endpoint_risk: f32,

    /// Total sample count
    pub sample_count: u32,

    /// First seen timestamp (ms)
    pub first_seen_ms: u64,

    /// Last updated timestamp (ms)
    pub last_updated_ms: u64,
}

impl EndpointProfile {
    /// Create a new profile for an endpoint template.
    pub fn new(template: String, now_ms: u64) -> Self {
        Self {
            template,
            payload_size: Distribution::new(),
            response_size: Distribution::new(),
            expected_params: HashMap::with_capacity(16),
            content_types: HashMap::with_capacity(4),
            response_content_types: HashMap::with_capacity(4),
            status_codes: HashMap::with_capacity(8),
            request_rate: RateTracker::new(),
            endpoint_risk: 0.0,
            sample_count: 0,
            first_seen_ms: now_ms,
            last_updated_ms: now_ms,
        }
    }

    /// Update profile with request data.
    ///
    /// Uses `&[(&str, &str)]` to pass param name and value.
    pub fn update(
        &mut self,
        payload_size: usize,
        params: &[(&str, &str)], // Changed from &[&str] to include values
        content_type: Option<&str>,
        now_ms: u64,
    ) {
        // Update payload size distribution
        self.payload_size.update(payload_size as f64);

        // Update request rate
        self.request_rate.record(now_ms);

        // Update parameter statistics
        for &(param_name, param_value) in params {
            if let Some(stats) = self.expected_params.get_mut(param_name) {
                stats.update(param_value);
            } else if self.expected_params.len() < MAX_PARAMS {
                let mut stats = ParamStats::new();
                stats.update(param_value);
                self.expected_params.insert(param_name.to_string(), stats);
            }
        }

        // Cap params at MAX_PARAMS (memory protection)
        if self.expected_params.len() > MAX_PARAMS {
            Self::evict_least_frequent(&mut self.expected_params, MAX_PARAMS);
        }

        // Update content type (bounded to prevent memory exhaustion)
        if let Some(ct) = content_type {
            // Only track if we haven't hit the limit, or if this type is already tracked
            if self.content_types.len() < MAX_CONTENT_TYPES || self.content_types.contains_key(ct) {
                *self.content_types.entry(ct.to_string()).or_insert(0) += 1;
            }
            // If at limit and new type, just ignore (don't pollute with attacker-generated types)
        }

        self.sample_count += 1;
        self.last_updated_ms = now_ms;
    }

    /// Update profile with response data.
    pub fn update_response(
        &mut self,
        response_size: usize,
        status_code: u16,
        content_type: Option<&str>,
        now_ms: u64,
    ) {
        self.response_size.update(response_size as f64);
        self.record_status(status_code);

        if let Some(ct) = content_type {
            if self.response_content_types.len() < MAX_CONTENT_TYPES
                || self.response_content_types.contains_key(ct)
            {
                *self
                    .response_content_types
                    .entry(ct.to_string())
                    .or_insert(0) += 1;
            }
        }

        self.last_updated_ms = now_ms;
    }

    /// Record response status code.
    pub fn record_status(&mut self, status_code: u16) {
        *self.status_codes.entry(status_code).or_insert(0) += 1;
    }

    /// Get the dominant content type (most frequent).
    pub fn dominant_content_type(&self) -> Option<&str> {
        self.content_types
            .iter()
            .max_by_key(|(_, count)| *count)
            .map(|(ct, _)| ct.as_str())
    }

    /// Get the dominant response content type.
    pub fn dominant_response_content_type(&self) -> Option<&str> {
        self.response_content_types
            .iter()
            .max_by_key(|(_, count)| *count)
            .map(|(ct, _)| ct.as_str())
    }

    /// Get parameter frequency (0.0-1.0).
    pub fn param_frequency(&self, param: &str) -> f64 {
        if self.sample_count == 0 {
            return 0.0;
        }
        self.expected_params
            .get(param)
            .map(|stats| stats.count as f64 / self.sample_count as f64)
            .unwrap_or(0.0)
    }

    /// Check if a parameter is "expected" (seen in > threshold of requests).
    pub fn is_expected_param(&self, param: &str, threshold: f64) -> bool {
        self.param_frequency(param) >= threshold
    }

    /// Get status code frequency (0.0-1.0).
    pub fn status_frequency(&self, status_code: u16) -> f64 {
        let total: u32 = self.status_codes.values().sum();
        if total == 0 {
            return 0.0;
        }
        self.status_codes
            .get(&status_code)
            .map(|&count| count as f64 / total as f64)
            .unwrap_or(0.0)
    }

    /// Get the error rate (4xx + 5xx responses).
    pub fn error_rate(&self) -> f64 {
        let total: u32 = self.status_codes.values().sum();
        if total == 0 {
            return 0.0;
        }
        let errors: u32 = self
            .status_codes
            .iter()
            .filter(|(&code, _)| code >= 400)
            .map(|(_, &count)| count)
            .sum();
        errors as f64 / total as f64
    }

    /// Calculate baseline request rate (requests per minute over lifetime).
    pub fn baseline_rate(&self, now_ms: u64) -> f64 {
        let lifetime_ms = now_ms.saturating_sub(self.first_seen_ms).max(1);
        let lifetime_minutes = lifetime_ms as f64 / 60_000.0;
        self.sample_count as f64 / lifetime_minutes.max(1.0)
    }

    /// Evict least frequent entries from a HashMap.
    fn evict_least_frequent(map: &mut HashMap<String, ParamStats>, target_size: usize) {
        if map.len() <= target_size {
            return;
        }

        // Find minimum frequency to keep
        let mut frequencies: Vec<u32> = map.values().map(|s| s.count).collect();
        frequencies.sort_unstable();
        let to_remove = map.len() - target_size;
        let min_keep = frequencies.get(to_remove).copied().unwrap_or(0);

        // Remove entries below threshold
        map.retain(|_, stats| stats.count >= min_keep);
    }

    /// Check if profile has enough samples for anomaly detection.
    pub fn is_mature(&self, min_samples: u32) -> bool {
        self.sample_count >= min_samples
    }

    /// Get the age of this profile in milliseconds.
    pub fn age_ms(&self, now_ms: u64) -> u64 {
        now_ms.saturating_sub(self.first_seen_ms)
    }

    /// Get time since last update in milliseconds.
    pub fn idle_ms(&self, now_ms: u64) -> u64 {
        now_ms.saturating_sub(self.last_updated_ms)
    }
}

// ============================================================================
// Tests
// ============================================================================

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

    #[test]
    fn test_endpoint_profile_new() {
        let profile = EndpointProfile::new("/api/users".to_string(), 1000);
        assert_eq!(profile.template, "/api/users");
        assert_eq!(profile.sample_count, 0);
        assert_eq!(profile.first_seen_ms, 1000);
        assert_eq!(profile.last_updated_ms, 1000);
    }

    #[test]
    fn test_endpoint_profile_update() {
        let mut profile = EndpointProfile::new("/api/users".to_string(), 1000);

        profile.update(
            100,
            &[("name", "alice"), ("email", "a@example.com")],
            Some("application/json"),
            2000,
        );

        assert_eq!(profile.sample_count, 1);
        assert_eq!(profile.last_updated_ms, 2000);
        assert!(profile.expected_params.contains_key("name"));
        assert!(profile.expected_params.contains_key("email"));
        assert!(profile.content_types.contains_key("application/json"));
    }

    #[test]
    fn test_endpoint_profile_param_frequency() {
        let mut profile = EndpointProfile::new("/api/users".to_string(), 1000);

        // Update with "name" in all requests, "email" in half
        for i in 0..10 {
            let params = if i % 2 == 0 {
                vec![("name", "val"), ("email", "val")]
            } else {
                vec![("name", "val")]
            };
            profile.update(100, &params, None, 1000 + i * 100);
        }

        assert!((profile.param_frequency("name") - 1.0).abs() < 0.01);
        assert!((profile.param_frequency("email") - 0.5).abs() < 0.01);
        assert_eq!(profile.param_frequency("unknown"), 0.0);
    }

    #[test]
    fn test_endpoint_profile_is_expected_param() {
        let mut profile = EndpointProfile::new("/api/users".to_string(), 1000);

        // "name" in 9/10 requests, "optional" in 2/10
        for i in 0..10 {
            let params = if i == 0 {
                vec![("optional", "val")]
            } else if i < 3 {
                vec![("name", "val"), ("optional", "val")]
            } else {
                vec![("name", "val")]
            };
            profile.update(100, &params, None, 1000 + i * 100);
        }

        assert!(profile.is_expected_param("name", 0.8)); // 90% > 80%
        assert!(!profile.is_expected_param("optional", 0.8)); // 20% < 80%
    }

    #[test]
    fn test_endpoint_profile_content_type_bounds() {
        let mut profile = EndpointProfile::new("/api/test".to_string(), 1000);

        // Add MAX_CONTENT_TYPES unique content types
        for i in 0..MAX_CONTENT_TYPES {
            profile.update(
                100,
                &[],
                Some(&format!("application/type-{}", i)),
                1000 + i as u64,
            );
        }
        assert_eq!(profile.content_types.len(), MAX_CONTENT_TYPES);

        // Try to add more unique content types - should be ignored
        for i in 0..10 {
            profile.update(
                100,
                &[],
                Some(&format!("application/extra-{}", i)),
                2000 + i as u64,
            );
        }
        // Should still be at MAX_CONTENT_TYPES, not growing
        assert_eq!(profile.content_types.len(), MAX_CONTENT_TYPES);

        // But existing content types should still be updated
        let initial_count = *profile.content_types.get("application/type-0").unwrap();
        profile.update(100, &[], Some("application/type-0"), 3000);
        let updated_count = *profile.content_types.get("application/type-0").unwrap();
        assert_eq!(updated_count, initial_count + 1);
    }

    #[test]
    fn test_endpoint_profile_dominant_content_type() {
        let mut profile = EndpointProfile::new("/api/test".to_string(), 1000);

        // JSON 5 times, XML 2 times
        for _ in 0..5 {
            profile.update(100, &[], Some("application/json"), 1000);
        }
        for _ in 0..2 {
            profile.update(100, &[], Some("application/xml"), 1000);
        }

        assert_eq!(profile.dominant_content_type(), Some("application/json"));
    }

    #[test]
    fn test_endpoint_profile_status_codes() {
        let mut profile = EndpointProfile::new("/api/test".to_string(), 1000);

        // 80% success, 20% errors
        for _ in 0..8 {
            profile.record_status(200);
        }
        for _ in 0..2 {
            profile.record_status(500);
        }

        assert!((profile.status_frequency(200) - 0.8).abs() < 0.01);
        assert!((profile.status_frequency(500) - 0.2).abs() < 0.01);
        assert!((profile.error_rate() - 0.2).abs() < 0.01);
    }

    #[test]
    fn test_endpoint_profile_baseline_rate() {
        let mut profile = EndpointProfile::new("/api/test".to_string(), 0);

        // 60 requests over 1 minute = 60 req/min
        for i in 0..60 {
            profile.update(100, &[], None, i * 1000);
        }

        let rate = profile.baseline_rate(60_000);
        assert!((rate - 60.0).abs() < 1.0);
    }

    #[test]
    fn test_endpoint_profile_is_mature() {
        let mut profile = EndpointProfile::new("/api/test".to_string(), 1000);

        assert!(!profile.is_mature(10));

        for i in 0..10 {
            profile.update(100, &[], None, 1000 + i * 100);
        }

        assert!(profile.is_mature(10));
        assert!(!profile.is_mature(20));
    }

    #[test]
    fn test_endpoint_profile_age_and_idle() {
        let profile = EndpointProfile::new("/api/test".to_string(), 1000);

        assert_eq!(profile.age_ms(2000), 1000);
        assert_eq!(profile.idle_ms(2000), 1000);
    }

    #[test]
    fn test_evict_least_frequent() {
        let mut map: HashMap<String, ParamStats> = HashMap::new();
        let mut s1 = ParamStats::new();
        s1.count = 10;
        let mut s2 = ParamStats::new();
        s2.count = 5;
        let mut s3 = ParamStats::new();
        s3.count = 1;
        let mut s4 = ParamStats::new();
        s4.count = 8;

        map.insert("a".to_string(), s1);
        map.insert("b".to_string(), s2);
        map.insert("c".to_string(), s3);
        map.insert("d".to_string(), s4);

        EndpointProfile::evict_least_frequent(&mut map, 2);

        // Should keep "a" (10) and "d" (8)
        assert!(map.len() <= 2);
        assert!(map.contains_key("a"));
    }

    // ========================================================================
    // ParamStats Type Count Bounds Tests
    // ========================================================================

    #[test]
    fn test_param_stats_type_count_limit() {
        let mut stats = ParamStats::new();

        // Update with values that would create multiple type categories
        for _ in 0..100 {
            stats.update("12345"); // numeric
            stats.update("hello"); // string
            stats.update("test@example.com"); // email
            stats.update("123e4567-e89b-12d3-a456-426614174000"); // uuid
        }

        // Standard types: numeric, string, email, uuid = 4 types
        // Should not exceed DEFAULT_MAX_TYPE_COUNTS (10)
        assert!(stats.type_counts.len() <= DEFAULT_MAX_TYPE_COUNTS);
    }

    #[test]
    fn test_param_stats_custom_type_limit() {
        let mut stats = ParamStats::new();

        // Use custom limit of 2
        for _ in 0..10 {
            stats.update_with_limit("12345", 2); // numeric
            stats.update_with_limit("hello", 2); // string
            stats.update_with_limit("test@example.com", 2); // would add email, but limit is 2
        }

        // Should have at most 2 type categories
        assert!(stats.type_counts.len() <= 2);
    }

    // ========================================================================
    // PII Redaction Helper Tests
    // ========================================================================

    #[test]
    fn test_redact_value() {
        // Test email redaction
        let email = "user@example.com";
        let redacted = redact_value(email);
        assert!(redacted.starts_with("us"));
        assert!(redacted.ends_with("om"));
        assert!(redacted.len() == email.len());

        // Test short value
        let short = "ab";
        let redacted_short = redact_value(short);
        assert_eq!(redacted_short, "**");

        // Test medium value
        let medium = "hello";
        let redacted_medium = redact_value(medium);
        assert!(redacted_medium.starts_with("he"));
        assert!(redacted_medium.ends_with("lo"));
    }

    #[test]
    fn test_is_likely_pii() {
        // Email patterns
        assert!(is_likely_pii("user@example.com"));
        assert!(is_likely_pii("admin@company.org"));
        assert!(!is_likely_pii("not-email-format"));

        // UUID patterns
        assert!(is_likely_pii("123e4567-e89b-12d3-a456-426614174000"));
        assert!(!is_likely_pii("not-a-uuid"));

        // Long alphanumeric (API keys, tokens)
        assert!(is_likely_pii("abcdefghijklmnopqrstuvwxyz12345"));
        assert!(!is_likely_pii("short"));
    }

    #[test]
    fn test_endpoint_profile_response_update() {
        let mut profile = EndpointProfile::new("/api/users".to_string(), 1000);

        profile.update_response(5000, 200, Some("application/json"), 2000);

        assert_eq!(profile.last_updated_ms, 2000);
        assert!((profile.response_size.mean() - 5000.0).abs() < 0.01);
        assert!((profile.status_frequency(200) - 1.0).abs() < 0.01);
        assert_eq!(
            profile.dominant_response_content_type(),
            Some("application/json")
        );
    }

    #[test]
    fn test_endpoint_profile_response_content_type_bounds() {
        let mut profile = EndpointProfile::new("/api/test".to_string(), 1000);

        // Add MAX_CONTENT_TYPES unique content types
        for i in 0..MAX_CONTENT_TYPES {
            profile.update_response(
                100,
                200,
                Some(&format!("application/type-{}", i)),
                1000 + i as u64,
            );
        }
        assert_eq!(profile.response_content_types.len(), MAX_CONTENT_TYPES);

        // Try to add more
        profile.update_response(100, 200, Some("application/extra"), 2000);
        assert_eq!(profile.response_content_types.len(), MAX_CONTENT_TYPES);
    }

    #[test]
    fn test_param_eviction_under_load() {
        let mut profile = EndpointProfile::new("/api/test".to_string(), 1000);

        // Add many parameters with different frequencies
        // p0..p49 will have 10 hits each
        // p50..p99 will have 1 hit each
        for i in 0..MAX_PARAMS {
            let name = format!("p{}", i);
            for _ in 0..10 {
                profile.update(100, &[(&name, "val")], None, 1000);
            }
        }
        for i in MAX_PARAMS..(MAX_PARAMS * 2) {
            let name = format!("p{}", i);
            profile.update(100, &[(&name, "val")], None, 1000);
        }

        assert!(profile.expected_params.len() <= MAX_PARAMS);
        // Frequent ones should be preserved
        assert!(profile.expected_params.contains_key("p0"));
        assert!(profile.expected_params.contains_key("p49"));
    }

    #[test]
    fn test_baseline_rate_zero_lifetime() {
        let mut profile = EndpointProfile::new("/api/test".to_string(), 1000);
        profile.update(100, &[], None, 1000);

        // now_ms == first_seen_ms
        let rate = profile.baseline_rate(1000);
        // lifetime_ms = 1 (max(1)), lifetime_minutes = 1/60000
        // rate = 1 / (1/60000) = 60000 req/min
        assert!(rate > 0.0);
        assert!(rate.is_finite());
    }

    #[test]
    fn test_param_stats_no_type_counts_but_count_positive() {
        let mut stats = ParamStats::new();
        // Update with 0 limit
        stats.update_with_limit("val", 0);

        assert_eq!(stats.count, 1);
        assert_eq!(stats.type_counts.len(), 0);
        // length_dist should still be updated
        assert_eq!(stats.length_dist.count(), 1);
    }
}