bhandaar 0.1.0-alpha.1

On-disk LRU/TTL file cache for Rust with cross-process concurrency via flock(2)
Documentation
use crate::metadata::EntryMeta;
use crate::shard::Shard;
use crate::store;

/// Find the LRU entry in a shard (oldest last_accessed).
pub fn find_lru_entry(shard: &Shard) -> Option<(String, EntryMeta)> {
    let entries = shard.entries();
    let mut lru: Option<(String, EntryMeta)> = None;

    for (key, path) in entries {
        let meta_path = path.with_extension("dat.meta");
        match store::read_meta(&meta_path) {
            Ok(meta) => {
                if meta.is_expired() {
                    // Expired entries are优先 evicted
                    return Some((key, meta));
                }
                match &lru {
                    None => lru = Some((key, meta)),
                    Some((_, existing)) => {
                        if meta.last_accessed < existing.last_accessed {
                            lru = Some((key, meta));
                        }
                    }
                }
            }
            Err(_) => {
                // Corrupted metadata — evict this entry
                return Some((key.clone(), EntryMeta {
                    key,
                    size: 0,
                    created_at: 0,
                    last_accessed: 0,
                    expires_at: None,
                }));
            }
        }
    }

    lru
}

/// Evict expired entries from a shard.
pub fn evict_expired(shard: &Shard) -> u64 {
    let entries = shard.entries();
    let mut freed = 0u64;

    for (key, path) in entries {
        let meta_path = path.with_extension("dat.meta");
        if let Ok(meta) = store::read_meta(&meta_path) {
            if meta.is_expired() {
                let _ = store::delete_file(&path);
                let _ = store::delete_file(&meta_path);
                shard.remove(&key);
                freed += meta.size;
            }
        }
    }

    freed
}

/// Evict the LRU entry from a shard, returning the freed size.
pub fn evict_lru(shard: &Shard) -> Option<u64> {
    if let Some((key, meta)) = find_lru_entry(shard) {
        let path = shard.get_path(&key).unwrap_or_default();
        let meta_path = path.with_extension("dat.meta");

        let _ = store::delete_file(&path);
        let _ = store::delete_file(&meta_path);
        shard.remove(&key);

        Some(meta.size)
    } else {
        None
    }
}

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

    #[test]
    fn find_lru_returns_entry() {
        let dir = tempfile::tempdir().unwrap();
        let shard = Shard::new();

        // Create two entries with different timestamps
        let path1 = dir.path().join("a/dat1.dat");
        let path2 = dir.path().join("a/dat2.dat");

        let meta1 = EntryMeta::new("key1".to_string(), 100, None);
        std::thread::sleep(Duration::from_millis(10));
        let meta2 = EntryMeta::new("key2".to_string(), 200, None);

        store::write_data(&path1, b"data1").unwrap();
        store::write_meta(&path1.with_extension("dat.meta"), &meta1).unwrap();
        store::write_data(&path2, b"data2").unwrap();
        store::write_meta(&path2.with_extension("dat.meta"), &meta2).unwrap();

        shard.insert("key1".to_string(), path1);
        shard.insert("key2".to_string(), path2);

        let lru = find_lru_entry(&shard);
        assert!(lru.is_some());
        assert_eq!(lru.unwrap().0, "key1"); // key1 was created first
    }

    #[test]
    fn evict_lru_removes_entry() {
        let dir = tempfile::tempdir().unwrap();
        let shard = Shard::new();

        let path = dir.path().join("evict.dat");
        let meta = EntryMeta::new("evict-me".to_string(), 50, None);

        store::write_data(&path, b"data").unwrap();
        store::write_meta(&path.with_extension("dat.meta"), &meta).unwrap();

        shard.insert("evict-me".to_string(), path.clone());

        let freed = evict_lru(&shard);
        assert_eq!(freed, Some(50));
        assert!(!path.exists());
        assert!(!shard.contains("evict-me"));
    }
}