graphlite 0.0.1

GraphLite - A lightweight ISO GQL Graph Database
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109

// Copyright (c) 2024-2025 DeepGraph Inc.
// SPDX-License-Identifier: Apache-2.0
//
//! Comprehensive caching system
//!
//! This module provides multi-level caching for:
//! - Query results
//! - Compiled query plans
//! - Subquery results
//! - Metadata lookups
//! - Statistics and cardinality estimates

pub mod cache_config;
pub mod cache_manager;
pub mod invalidation;
pub mod plan_cache;
pub mod result_cache;
pub mod subquery_cache;

pub use cache_config::{CacheConfig, EvictionPolicy};
pub use cache_manager::CacheManager;
pub use invalidation::{InvalidationEvent, InvalidationManager};
pub use plan_cache::{PlanCache, PlanCacheEntry, PlanCacheKey};
pub use result_cache::ResultCache;
pub use subquery_cache::{
    SubqueryCache, SubqueryCacheHit, SubqueryCacheKey, SubqueryResult, SubqueryType,
};

use std::time::{Duration, Instant};

/// Cache levels for different types of data
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum CacheLevel {
    /// L1: Hot data, frequently accessed (in-memory, small, fast)
    L1,
    /// L2: Warm data, occasionally accessed (in-memory, larger, moderate speed)
    L2,
    /// L3: Cold data, infrequently accessed (disk-backed, large, slower)
    L3,
}

/// Cache entry metadata
#[derive(Debug, Clone)]
pub struct CacheEntryMetadata {
    pub created_at: Instant,
    pub last_accessed: Instant,
    pub access_count: u32,
    pub size_bytes: usize,
    pub ttl: Option<Duration>,
    pub level: CacheLevel,
    pub tags: Vec<String>, // For cache invalidation
}

impl CacheEntryMetadata {
    pub fn new(size_bytes: usize, level: CacheLevel) -> Self {
        let now = Instant::now();
        Self {
            created_at: now,
            last_accessed: now,
            access_count: 0,
            size_bytes,
            ttl: None,
            level,
            tags: Vec::new(),
        }
    }

    pub fn with_ttl(mut self, ttl: Duration) -> Self {
        self.ttl = Some(ttl);
        self
    }

    pub fn with_tags(mut self, tags: Vec<String>) -> Self {
        self.tags = tags;
        self
    }

    pub fn is_expired(&self) -> bool {
        if let Some(ttl) = self.ttl {
            self.created_at.elapsed() > ttl
        } else {
            false
        }
    }

    pub fn update_access(&mut self) {
        self.last_accessed = Instant::now();
        self.access_count += 1;
    }
}

/// Generic cache key trait
pub trait CacheKey:
    std::fmt::Debug + Clone + PartialEq + Eq + std::hash::Hash + Send + Sync
{
    #[allow(dead_code)] // ROADMAP v0.5.0 - Cache key generation for query caching (see ROADMAP.md ยง9)
    fn cache_key(&self) -> String;
    fn tags(&self) -> Vec<String> {
        Vec::new()
    }
}

/// Generic cached value trait
pub trait CacheValue: std::fmt::Debug + Clone + Send + Sync {
    fn size_bytes(&self) -> usize;
    fn is_valid(&self) -> bool {
        true
    }
}