hedl_mcp/

cache.rs

// Dweve HEDL - Hierarchical Entity Data Language
//
// Copyright (c) 2025 Dweve IP B.V. and individual contributors.
//
// SPDX-License-Identifier: Apache-2.0
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License in the LICENSE file at the
// root of this repository or at: http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

//! Request-level caching for immutable MCP operations.
//!
//! Provides true LRU caching for expensive operations like validation, linting,
//! and schema analysis. Caches are keyed by operation + input hash for
//! deterministic results.
//!
//! # True LRU Behavior
//!
//! Both `insert()` and `get()` operations update the access timestamp, ensuring
//! that frequently accessed entries are retained while least-recently-used
//! entries are evicted when the cache reaches capacity.
//!
//! # Performance
//!
//! Benchmarks show 2-5x speedup on repeated requests for the same content.
//!
//! # Thread Safety
//!
//! Uses `DashMap` for lock-free concurrent access with minimal contention.

use dashmap::DashMap;
use serde_json::Value as JsonValue;
use std::hash::{Hash, Hasher};
use std::sync::atomic::{AtomicU64, Ordering};

/// Maximum number of cache entries (configurable).
const DEFAULT_CACHE_SIZE: usize = 1000;

/// Hash a string using the default hasher (fast, non-cryptographic).
fn hash_string(s: &str) -> u64 {
    let mut hasher = std::collections::hash_map::DefaultHasher::new();
    s.hash(&mut hasher);
    hasher.finish()
}

/// Cache key combining operation name and input hash.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
struct CacheKey {
    operation: String,
    input_hash: u64,
}

impl CacheKey {
    fn new(operation: impl Into<String>, input: &str) -> Self {
        Self {
            operation: operation.into(),
            input_hash: hash_string(input),
        }
    }
}

/// Cached result with LRU metadata.
#[derive(Debug, Clone)]
struct CacheEntry {
    /// Cached JSON result.
    result: JsonValue,
    /// Access timestamp for LRU ordering (higher = more recent).
    access_time: u64,
}

/// Cache statistics for monitoring.
#[derive(Debug, Clone, Default)]
pub struct CacheStats {
    /// Total cache hits.
    pub hits: u64,
    /// Total cache misses.
    pub misses: u64,
    /// Total cache evictions (LRU).
    pub evictions: u64,
    /// Current cache size (entries).
    pub size: usize,
    /// Maximum cache size.
    pub max_size: usize,
}

impl CacheStats {
    /// Calculate cache hit rate (0.0 to 1.0).
    #[must_use]
    pub fn hit_rate(&self) -> f64 {
        let total = self.hits + self.misses;
        if total == 0 {
            0.0
        } else {
            self.hits as f64 / total as f64
        }
    }

    /// Calculate cache hit rate as percentage.
    #[must_use]
    pub fn hit_rate_percent(&self) -> f64 {
        self.hit_rate() * 100.0
    }
}

/// True LRU cache for immutable MCP operations.
///
/// Thread-safe cache using `DashMap` for concurrent access with true LRU eviction.
/// Both `get()` and `insert()` update the access timestamp, ensuring frequently
/// accessed entries are retained.
///
/// # Example
///
/// ```
/// use hedl_mcp::cache::OperationCache;
/// use serde_json::json;
///
/// let cache = OperationCache::new(1000);
///
/// // Cache a validation result
/// let result = json!({"valid": true});
/// cache.insert("validate", "my hedl content", result.clone());
///
/// // Retrieve from cache (updates LRU position)
/// if let Some(cached) = cache.get("validate", "my hedl content") {
///     assert_eq!(cached, result);
/// }
/// ```
pub struct OperationCache {
    /// Cache storage (operation+hash -> entry with result and access time).
    cache: DashMap<CacheKey, CacheEntry>,
    /// Maximum number of entries.
    max_size: usize,
    /// Monotonic timestamp counter for LRU ordering.
    timestamp_counter: AtomicU64,
    /// Cache hit counter.
    hits: AtomicU64,
    /// Cache miss counter.
    misses: AtomicU64,
    /// Cache eviction counter.
    evictions: AtomicU64,
}

impl OperationCache {
    /// Create a new cache with the specified maximum size.
    ///
    /// # Arguments
    ///
    /// * `max_size` - Maximum number of cache entries (0 = disabled)
    ///
    /// # Examples
    ///
    /// ```
    /// use hedl_mcp::cache::OperationCache;
    ///
    /// let cache = OperationCache::new(1000);
    /// ```
    #[must_use]
    pub fn new(max_size: usize) -> Self {
        Self {
            cache: DashMap::with_capacity(max_size),
            max_size,
            timestamp_counter: AtomicU64::new(0),
            hits: AtomicU64::new(0),
            misses: AtomicU64::new(0),
            evictions: AtomicU64::new(0),
        }
    }

    /// Get a cached result if available, updating its LRU position.
    ///
    /// # Arguments
    ///
    /// * `operation` - Operation name (e.g., "validate", "lint")
    /// * `input` - Input content (used for cache key hash)
    ///
    /// # Returns
    ///
    /// Cached result if available, `None` otherwise.
    ///
    /// # Examples
    ///
    /// ```
    /// use hedl_mcp::cache::OperationCache;
    ///
    /// let cache = OperationCache::new(1000);
    /// let result = cache.get("validate", "%VERSION 1.0\n---");
    /// assert!(result.is_none()); // Cache miss on first access
    /// ```
    pub fn get(&self, operation: &str, input: &str) -> Option<JsonValue> {
        let key = CacheKey::new(operation, input);

        if let Some(mut entry) = self.cache.get_mut(&key) {
            // Update access time for true LRU behavior
            entry.access_time = self.timestamp_counter.fetch_add(1, Ordering::Relaxed);
            self.hits.fetch_add(1, Ordering::Relaxed);
            Some(entry.result.clone())
        } else {
            self.misses.fetch_add(1, Ordering::Relaxed);
            None
        }
    }

    /// Insert a result into the cache.
    ///
    /// If the cache is full, evicts the least recently used entry.
    /// If `max_size` is 0, this is a no-op (cache disabled).
    ///
    /// # Arguments
    ///
    /// * `operation` - Operation name (e.g., "validate", "lint")
    /// * `input` - Input content (used for cache key hash)
    /// * `result` - Result to cache
    ///
    /// # Examples
    ///
    /// ```
    /// use hedl_mcp::cache::OperationCache;
    /// use serde_json::json;
    ///
    /// let cache = OperationCache::new(1000);
    /// cache.insert("validate", "%VERSION 1.0\n---", json!({"valid": true}));
    /// ```
    pub fn insert(&self, operation: &str, input: &str, result: JsonValue) {
        // Cache disabled when max_size is 0
        if self.max_size == 0 {
            return;
        }

        let key = CacheKey::new(operation, input);
        let access_time = self.timestamp_counter.fetch_add(1, Ordering::Relaxed);

        // Evict LRU entry if at capacity (and not updating existing key)
        if self.cache.len() >= self.max_size && !self.cache.contains_key(&key) {
            self.evict_lru();
        }

        let entry = CacheEntry {
            result,
            access_time,
        };
        self.cache.insert(key, entry);
    }

    /// Evict the least recently used entry (lowest `access_time`).
    fn evict_lru(&self) {
        // Find the entry with the lowest access_time
        let mut lru_key: Option<CacheKey> = None;
        let mut lru_time = u64::MAX;

        for entry in &self.cache {
            if entry.value().access_time < lru_time {
                lru_time = entry.value().access_time;
                lru_key = Some(entry.key().clone());
            }
        }

        // Remove the LRU entry
        if let Some(key) = lru_key {
            if self.cache.remove(&key).is_some() {
                self.evictions.fetch_add(1, Ordering::Relaxed);
            }
        }
    }

    /// Get cache statistics.
    ///
    /// # Returns
    ///
    /// Current cache statistics including hit/miss counts and hit rate.
    ///
    /// # Examples
    ///
    /// ```
    /// use hedl_mcp::cache::OperationCache;
    /// use serde_json::json;
    ///
    /// let cache = OperationCache::new(1000);
    /// cache.insert("validate", "input", json!({"valid": true}));
    /// cache.get("validate", "input"); // Hit
    /// cache.get("validate", "other"); // Miss
    ///
    /// let stats = cache.stats();
    /// assert_eq!(stats.hits, 1);
    /// assert_eq!(stats.misses, 1);
    /// assert_eq!(stats.size, 1);
    /// ```
    pub fn stats(&self) -> CacheStats {
        CacheStats {
            hits: self.hits.load(Ordering::Relaxed),
            misses: self.misses.load(Ordering::Relaxed),
            evictions: self.evictions.load(Ordering::Relaxed),
            size: self.cache.len(),
            max_size: self.max_size,
        }
    }

    /// Clear all cache entries.
    ///
    /// # Examples
    ///
    /// ```
    /// use hedl_mcp::cache::OperationCache;
    /// use serde_json::json;
    ///
    /// let cache = OperationCache::new(1000);
    /// cache.insert("validate", "input", json!({"valid": true}));
    /// assert_eq!(cache.stats().size, 1);
    ///
    /// cache.clear();
    /// assert_eq!(cache.stats().size, 0);
    /// ```
    pub fn clear(&self) {
        self.cache.clear();
    }

    /// Reset cache statistics (hit/miss/eviction counters).
    ///
    /// Does not clear the cache itself, only resets the counters.
    pub fn reset_stats(&self) {
        self.hits.store(0, Ordering::Relaxed);
        self.misses.store(0, Ordering::Relaxed);
        self.evictions.store(0, Ordering::Relaxed);
    }
}

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

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

    #[test]
    fn test_cache_hit_miss() {
        let cache = OperationCache::new(10);

        // Miss on first access
        assert!(cache.get("validate", "input1").is_none());
        assert_eq!(cache.stats().misses, 1);

        // Insert
        cache.insert("validate", "input1", json!({"valid": true}));

        // Hit on second access
        let result = cache.get("validate", "input1");
        assert!(result.is_some());
        assert_eq!(result.unwrap()["valid"], true);
        assert_eq!(cache.stats().hits, 1);
    }

    #[test]
    fn test_cache_different_operations() {
        let cache = OperationCache::new(10);

        cache.insert("validate", "input", json!({"valid": true}));
        cache.insert("lint", "input", json!({"diagnostics": []}));

        // Different operations with same input are cached separately
        let validate_result = cache.get("validate", "input");
        let lint_result = cache.get("lint", "input");

        assert!(validate_result.is_some());
        assert!(lint_result.is_some());
        assert_ne!(validate_result, lint_result);
    }

    #[test]
    fn test_cache_different_inputs() {
        let cache = OperationCache::new(10);

        cache.insert("validate", "input1", json!({"valid": true}));
        cache.insert("validate", "input2", json!({"valid": false}));

        // Different inputs are cached separately
        let result1 = cache.get("validate", "input1");
        let result2 = cache.get("validate", "input2");

        assert_eq!(result1.unwrap()["valid"], true);
        assert_eq!(result2.unwrap()["valid"], false);
    }

    #[test]
    fn test_cache_true_lru_eviction() {
        let cache = OperationCache::new(3);

        // Fill cache to capacity
        cache.insert("op", "input1", json!(1));
        cache.insert("op", "input2", json!(2));
        cache.insert("op", "input3", json!(3));

        assert_eq!(cache.stats().size, 3);
        assert_eq!(cache.stats().evictions, 0);

        // Access input1 to make it recently used
        cache.get("op", "input1");

        // Insert one more (should evict input2, the true LRU)
        cache.insert("op", "input4", json!(4));

        assert_eq!(cache.stats().size, 3);
        assert_eq!(cache.stats().evictions, 1);

        // input1 should still be present (was accessed recently)
        assert!(cache.get("op", "input1").is_some());

        // input2 should be evicted (true LRU)
        assert!(cache.get("op", "input2").is_none());

        // input3 and input4 should still be present
        assert!(cache.get("op", "input3").is_some());
        assert!(cache.get("op", "input4").is_some());
    }

    #[test]
    fn test_cache_fifo_eviction_without_access() {
        let cache = OperationCache::new(3);

        // Fill cache to capacity
        cache.insert("op", "input1", json!(1));
        cache.insert("op", "input2", json!(2));
        cache.insert("op", "input3", json!(3));

        // Insert one more without accessing any (should evict input1, oldest)
        cache.insert("op", "input4", json!(4));

        assert_eq!(cache.stats().evictions, 1);

        // input1 should be evicted (oldest insert, no access)
        assert!(cache.get("op", "input1").is_none());

        // Others should still be present
        assert!(cache.get("op", "input2").is_some());
        assert!(cache.get("op", "input3").is_some());
        assert!(cache.get("op", "input4").is_some());
    }

    #[test]
    fn test_cache_zero_capacity() {
        let cache = OperationCache::new(0);

        cache.insert("op", "key", json!("value"));

        // With zero capacity, nothing should be cached
        assert!(cache.get("op", "key").is_none());
        assert_eq!(cache.stats().size, 0);
    }

    #[test]
    fn test_cache_stats() {
        let cache = OperationCache::new(10);

        cache.insert("op", "input1", json!(1));

        cache.get("op", "input1"); // Hit
        cache.get("op", "input2"); // Miss
        cache.get("op", "input1"); // Hit
        cache.get("op", "input3"); // Miss

        let stats = cache.stats();
        assert_eq!(stats.hits, 2);
        assert_eq!(stats.misses, 2);
        assert_eq!(stats.size, 1);
        assert_eq!(stats.hit_rate(), 0.5);
        assert_eq!(stats.hit_rate_percent(), 50.0);
    }

    #[test]
    fn test_cache_clear() {
        let cache = OperationCache::new(10);

        cache.insert("op", "input1", json!(1));
        cache.insert("op", "input2", json!(2));

        assert_eq!(cache.stats().size, 2);

        cache.clear();

        assert_eq!(cache.stats().size, 0);
        assert!(cache.get("op", "input1").is_none());
        assert!(cache.get("op", "input2").is_none());
    }

    #[test]
    fn test_cache_reset_stats() {
        let cache = OperationCache::new(10);

        cache.insert("op", "input1", json!(1));
        cache.get("op", "input1"); // Hit
        cache.get("op", "input2"); // Miss

        assert_eq!(cache.stats().hits, 1);
        assert_eq!(cache.stats().misses, 1);

        cache.reset_stats();

        assert_eq!(cache.stats().hits, 0);
        assert_eq!(cache.stats().misses, 0);
        assert_eq!(cache.stats().size, 1); // Cache not cleared
    }

    #[test]
    fn test_cache_hash_collision_resistance() {
        let cache = OperationCache::new(10);

        // Very similar inputs (should have different hashes)
        cache.insert("op", "input", json!(1));
        cache.insert("op", "input ", json!(2)); // Trailing space

        let result1 = cache.get("op", "input");
        let result2 = cache.get("op", "input ");

        assert_eq!(result1.unwrap(), 1);
        assert_eq!(result2.unwrap(), 2);
    }

    #[test]
    fn test_cache_concurrent_access() {
        use std::sync::Arc;
        use std::thread;

        let cache = Arc::new(OperationCache::new(100));
        let mut handles = vec![];

        // Spawn multiple threads doing concurrent reads/writes
        for i in 0..10 {
            let cache_clone = cache.clone();
            let handle = thread::spawn(move || {
                for j in 0..100 {
                    let key = format!("input{}", j % 10);
                    cache_clone.insert("op", &key, json!(i));
                    cache_clone.get("op", &key);
                }
            });
            handles.push(handle);
        }

        // Wait for all threads
        for handle in handles {
            handle.join().unwrap();
        }

        // Cache should be consistent
        let stats = cache.stats();
        assert!(stats.size > 0);
        assert!(stats.size <= 100);
    }

    #[test]
    fn test_cache_update_existing_key() {
        let cache = OperationCache::new(3);

        cache.insert("op", "key1", json!(1));
        cache.insert("op", "key2", json!(2));
        cache.insert("op", "key3", json!(3));

        // Update existing key (should not trigger eviction)
        cache.insert("op", "key1", json!(10));

        assert_eq!(cache.stats().size, 3);
        assert_eq!(cache.stats().evictions, 0);
        assert_eq!(cache.get("op", "key1").unwrap(), json!(10));
    }
}