Skip to main content

spec_stream_cache/
snapshot.rs

1use crate::allocator::BlockAllocator;
2use crate::error::CacheError;
3use crate::manager::PagedKvCacheManager;
4use serde::{Deserialize, Serialize};
5use spec_stream_core::TokenId;
6
7/// Represents a single warm prefix entry in a persistent snapshot.
8#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
9pub struct PrefixSnapshotEntry {
10    /// 64-bit cumulative hash of this prefix block.
11    pub hash: u64,
12    /// Token IDs stored in the block.
13    pub tokens: Vec<TokenId>,
14}
15
16/// A serialized snapshot of warm prefix cache blocks for instant cold-start loading across restarts.
17#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
18pub struct PrefixCacheSnapshot {
19    /// Size of each physical block in tokens.
20    pub block_size: usize,
21    /// Collection of cached prefix entries.
22    pub entries: Vec<PrefixSnapshotEntry>,
23}
24
25impl PrefixCacheSnapshot {
26    pub fn new(block_size: usize) -> Self {
27        Self {
28            block_size,
29            entries: Vec::new(),
30        }
31    }
32
33    /// Serializes the snapshot to a JSON string.
34    pub fn to_json(&self) -> Result<String, CacheError> {
35        serde_json::to_string_pretty(self)
36            .map_err(|e| CacheError::SerializationError(e.to_string()))
37    }
38
39    /// Deserializes a snapshot from a JSON string.
40    pub fn from_json(json_str: &str) -> Result<Self, CacheError> {
41        serde_json::from_str(json_str).map_err(|e| CacheError::SerializationError(e.to_string()))
42    }
43}
44
45impl BlockAllocator {
46    /// Exports all active prefix cache entries into a snapshot.
47    pub fn export_prefix_snapshot(&self) -> PrefixCacheSnapshot {
48        let mut snapshot = PrefixCacheSnapshot::new(self.block_size);
49
50        for (&hash, &block_id) in &self.prefix_cache {
51            if let Some(block) = self.blocks.get(block_id) {
52                snapshot.entries.push(PrefixSnapshotEntry {
53                    hash,
54                    tokens: block.tokens.clone(),
55                });
56            }
57        }
58
59        snapshot
60    }
61
62    /// Imports warm prefix entries from a snapshot into the allocator pool.
63    /// Returns the number of prefix blocks successfully restored.
64    pub fn import_prefix_snapshot(
65        &mut self,
66        snapshot: &PrefixCacheSnapshot,
67    ) -> Result<usize, CacheError> {
68        let mut imported = 0;
69
70        for entry in &snapshot.entries {
71            // Only import if not already present and we have free blocks
72            if !self.prefix_cache.contains_key(&entry.hash) && !self.free_list.is_empty() {
73                let block_id = self.allocate()?;
74                {
75                    let block = self.get_block_mut(block_id)?;
76                    block.tokens = entry.tokens.clone();
77                    block.num_tokens = entry.tokens.len();
78                    block.prefix_hash = Some(entry.hash);
79                    // Retain a baseline reference for persistent warm caching
80                    block.ref_count = 1;
81                }
82                self.prefix_cache.insert(entry.hash, block_id);
83                imported += 1;
84            }
85        }
86
87        Ok(imported)
88    }
89}
90
91impl PagedKvCacheManager {
92    /// Exports current warm prefix cache to a snapshot.
93    pub fn export_snapshot(&self) -> PrefixCacheSnapshot {
94        self.allocator.lock().export_prefix_snapshot()
95    }
96
97    /// Imports a prefix cache snapshot into the active pool.
98    pub fn import_snapshot(&self, snapshot: &PrefixCacheSnapshot) -> Result<usize, CacheError> {
99        self.allocator.lock().import_prefix_snapshot(snapshot)
100    }
101
102    /// Saves the warm prefix cache to a JSON string.
103    pub fn save_snapshot_json(&self) -> Result<String, CacheError> {
104        self.export_snapshot().to_json()
105    }
106
107    /// Loads and warms the cache from a JSON snapshot string.
108    pub fn load_snapshot_json(&self, json_str: &str) -> Result<usize, CacheError> {
109        let snapshot = PrefixCacheSnapshot::from_json(json_str)?;
110        self.import_snapshot(&snapshot)
111    }
112}
113
114#[cfg(test)]
115mod tests {
116    use super::*;
117
118    #[test]
119    fn test_prefix_cache_snapshot_roundtrip() {
120        let block_size = 4;
121        let mut allocator = BlockAllocator::new(10, block_size);
122
123        // Populate a block and register prefix
124        let block_id = allocator.allocate().unwrap();
125        let tokens = vec![11, 22, 33, 44];
126        {
127            let block = allocator.get_block_mut(block_id).unwrap();
128            block.tokens = tokens.clone();
129            block.num_tokens = 4;
130        }
131        let hash = 0xDEADBEEFCAFE;
132        allocator.register_prefix(hash, block_id);
133
134        // Export to JSON
135        let snapshot = allocator.export_prefix_snapshot();
136        assert_eq!(snapshot.entries.len(), 1);
137        let json = snapshot.to_json().unwrap();
138
139        // Create a new fresh allocator and import the snapshot
140        let mut new_allocator = BlockAllocator::new(10, block_size);
141        let loaded_snapshot = PrefixCacheSnapshot::from_json(&json).unwrap();
142        let imported = new_allocator
143            .import_prefix_snapshot(&loaded_snapshot)
144            .unwrap();
145
146        assert_eq!(imported, 1);
147        assert_eq!(new_allocator.num_prefix_entries(), 1);
148        assert!(new_allocator.find_prefix(hash).is_some());
149    }
150}