oxigdal_cloud/cache/
mod.rs

1//! Advanced multi-level caching layer for cloud storage
2//!
3//! This module provides a comprehensive caching system with:
4//! - LRU cache with TTL (Time-To-Live)
5//! - LFU (Least Frequently Used) cache
6//! - ARC (Adaptive Replacement Cache)
7//! - Spatial-aware caching for geospatial data
8//! - Tile-based caching for COG/tile pyramids
9//! - Persistent disk cache with metadata
10//! - Cache warming strategies
11//! - Configurable eviction policies
12
13use std::path::PathBuf;
14use std::time::Duration;
15
16pub mod backends;
17pub mod eviction;
18pub mod metadata;
19pub mod multi;
20
21#[cfg(test)]
22mod tests;
23
24// Re-export main types
25pub use metadata::{
26    CacheEntry, CacheKey, CacheStats, DiskCacheMetadata, LevelStats, SpatialInfo, TileCoord,
27};
28
29#[cfg(feature = "cache")]
30pub use eviction::{ArcCache, LfuCache, LruTtlCache};
31
32#[cfg(feature = "cache")]
33pub use backends::{PersistentDiskCache, SpatialCache, TileCache};
34
35#[cfg(feature = "cache")]
36pub use multi::{CacheWarmer, DiskCache, MemoryCache, MultiLevelCache};
37
38/// Cache eviction strategy
39#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
40pub enum EvictionStrategy {
41    /// Least Recently Used
42    Lru,
43    /// Least Frequently Used
44    Lfu,
45    /// Adaptive (combines LRU and LFU using ARC algorithm)
46    #[default]
47    Adaptive,
48    /// Time-based eviction (oldest entries first)
49    TimeToLive,
50    /// Size-based eviction (largest entries first)
51    LargestFirst,
52    /// Random eviction
53    Random,
54}
55
56/// Cache warming strategy
57#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
58pub enum WarmingStrategy {
59    /// No pre-warming
60    #[default]
61    None,
62    /// Warm based on access patterns
63    AccessPattern,
64    /// Warm spatially adjacent tiles
65    SpatialAdjacent,
66    /// Warm pyramid levels (for tile caching)
67    PyramidLevels,
68    /// Custom warming function
69    Custom,
70}
71
72/// Cache configuration
73#[derive(Debug, Clone)]
74pub struct CacheConfig {
75    /// Maximum memory cache size in bytes
76    pub max_memory_size: usize,
77    /// Maximum disk cache size in bytes
78    pub max_disk_size: usize,
79    /// Whether to enable compression
80    pub compress: bool,
81    /// Compression threshold (compress if larger than this)
82    pub compress_threshold: usize,
83    /// Eviction strategy
84    pub eviction_strategy: EvictionStrategy,
85    /// Whether to enable persistent disk cache
86    pub persistent: bool,
87    /// Disk cache directory
88    pub cache_dir: Option<PathBuf>,
89    /// Default TTL for entries
90    pub default_ttl: Option<Duration>,
91    /// Maximum entry age before eviction
92    pub max_age: Option<Duration>,
93    /// Maximum number of entries
94    pub max_entries: usize,
95    /// Cache warming strategy
96    pub warming_strategy: WarmingStrategy,
97    /// Number of entries to warm at a time
98    pub warm_batch_size: usize,
99    /// Whether to track spatial metadata
100    pub spatial_aware: bool,
101    /// Target ARC adaptation rate (0.0-1.0)
102    pub arc_adaptation_rate: f64,
103}
104
105impl Default for CacheConfig {
106    fn default() -> Self {
107        Self {
108            max_memory_size: 100 * 1024 * 1024, // 100 MB
109            max_disk_size: 1024 * 1024 * 1024,  // 1 GB
110            compress: true,
111            compress_threshold: 4096, // 4 KB
112            eviction_strategy: EvictionStrategy::Adaptive,
113            persistent: true,
114            cache_dir: None,
115            default_ttl: Some(Duration::from_secs(3600)), // 1 hour
116            max_age: Some(Duration::from_secs(3600)),     // 1 hour
117            max_entries: 10000,
118            warming_strategy: WarmingStrategy::None,
119            warm_batch_size: 10,
120            spatial_aware: false,
121            arc_adaptation_rate: 0.5,
122        }
123    }
124}
125
126impl CacheConfig {
127    /// Creates a new cache configuration
128    #[must_use]
129    pub fn new() -> Self {
130        Self::default()
131    }
132
133    /// Sets the maximum memory cache size
134    #[must_use]
135    pub fn with_max_memory_size(mut self, size: usize) -> Self {
136        self.max_memory_size = size;
137        self
138    }
139
140    /// Sets the maximum disk cache size
141    #[must_use]
142    pub fn with_max_disk_size(mut self, size: usize) -> Self {
143        self.max_disk_size = size;
144        self
145    }
146
147    /// Enables or disables compression
148    #[must_use]
149    pub fn with_compress(mut self, compress: bool) -> Self {
150        self.compress = compress;
151        self
152    }
153
154    /// Sets the eviction strategy
155    #[must_use]
156    pub fn with_eviction_strategy(mut self, strategy: EvictionStrategy) -> Self {
157        self.eviction_strategy = strategy;
158        self
159    }
160
161    /// Sets the cache directory
162    #[must_use]
163    pub fn with_cache_dir(mut self, dir: impl Into<PathBuf>) -> Self {
164        self.cache_dir = Some(dir.into());
165        self
166    }
167
168    /// Sets the default TTL
169    #[must_use]
170    pub fn with_default_ttl(mut self, ttl: Duration) -> Self {
171        self.default_ttl = Some(ttl);
172        self
173    }
174
175    /// Sets the maximum entry age
176    #[must_use]
177    pub fn with_max_age(mut self, duration: Duration) -> Self {
178        self.max_age = Some(duration);
179        self
180    }
181
182    /// Sets the maximum number of entries
183    #[must_use]
184    pub fn with_max_entries(mut self, count: usize) -> Self {
185        self.max_entries = count;
186        self
187    }
188
189    /// Sets the warming strategy
190    #[must_use]
191    pub fn with_warming_strategy(mut self, strategy: WarmingStrategy) -> Self {
192        self.warming_strategy = strategy;
193        self
194    }
195
196    /// Enables spatial awareness
197    #[must_use]
198    pub fn with_spatial_aware(mut self, enabled: bool) -> Self {
199        self.spatial_aware = enabled;
200        self
201    }
202}
oxigdal_cloud/cache/mod.rs

oxigdal_cloud/cache/
mod.rs
