ferripfs_blockstore/

caching.rs

// Ported from: kubo/boxo/blockstore/caching.go
// Kubo version: v0.39.0
// Original: https://github.com/ipfs/kubo/blob/v0.39.0/boxo/blockstore/caching.go
//
// Original work: Copyright (c) Protocol Labs, Inc.
// Port: Copyright (c) 2026 ferripfs contributors
// SPDX-License-Identifier: MIT OR Apache-2.0

//! Caching blockstore wrapper.
//!
//! This provides a caching layer on top of any blockstore,
//! reducing disk reads for frequently accessed blocks.

use crate::{Block, Blockstore, BlockstoreResult};
use cid::Cid;
use lru::LruCache;
use parking_lot::Mutex;
use std::num::NonZeroUsize;

/// Default cache size in number of blocks
pub const DEFAULT_CACHE_SIZE: usize = 256;

/// Caching blockstore that wraps another blockstore with an LRU cache.
pub struct CachingBlockstore<B: Blockstore> {
    inner: B,
    cache: Mutex<LruCache<String, Block>>,
    has_cache: Mutex<LruCache<String, bool>>,
}

impl<B: Blockstore> CachingBlockstore<B> {
    /// Create a new caching blockstore with the given cache size.
    pub fn new(inner: B, cache_size: usize) -> Self {
        let cache_size = NonZeroUsize::new(cache_size.max(1)).unwrap();
        Self {
            inner,
            cache: Mutex::new(LruCache::new(cache_size)),
            has_cache: Mutex::new(LruCache::new(cache_size)),
        }
    }

    /// Create a new caching blockstore with the default cache size.
    pub fn with_default_cache(inner: B) -> Self {
        Self::new(inner, DEFAULT_CACHE_SIZE)
    }

    /// Get the underlying blockstore.
    pub fn inner(&self) -> &B {
        &self.inner
    }

    /// Get the underlying blockstore mutably.
    pub fn inner_mut(&mut self) -> &mut B {
        &mut self.inner
    }

    /// Get the current cache size (number of blocks).
    pub fn cache_len(&self) -> usize {
        self.cache.lock().len()
    }

    /// Clear the cache.
    pub fn clear_cache(&self) {
        self.cache.lock().clear();
        self.has_cache.lock().clear();
    }

    /// Get cache statistics.
    pub fn cache_stats(&self) -> CacheStats {
        let cache = self.cache.lock();
        let has_cache = self.has_cache.lock();
        CacheStats {
            block_cache_len: cache.len(),
            block_cache_cap: cache.cap().get(),
            has_cache_len: has_cache.len(),
            has_cache_cap: has_cache.cap().get(),
        }
    }
}

/// Cache statistics
#[derive(Debug, Clone)]
pub struct CacheStats {
    pub block_cache_len: usize,
    pub block_cache_cap: usize,
    pub has_cache_len: usize,
    pub has_cache_cap: usize,
}

impl<B: Blockstore> Blockstore for CachingBlockstore<B> {
    fn get(&self, cid: &Cid) -> BlockstoreResult<Option<Block>> {
        let key = cid.to_string();

        // Check cache first
        {
            let mut cache = self.cache.lock();
            if let Some(block) = cache.get(&key) {
                return Ok(Some(block.clone()));
            }
        }

        // Cache miss - read from inner store
        let result = self.inner.get(cid)?;

        // Cache the result
        if let Some(ref block) = result {
            let mut cache = self.cache.lock();
            cache.put(key.clone(), block.clone());
            let mut has_cache = self.has_cache.lock();
            has_cache.put(key, true);
        }

        Ok(result)
    }

    fn put(&mut self, block: Block) -> BlockstoreResult<()> {
        let key = block.cid().to_string();

        // Write to inner store first
        self.inner.put(block.clone())?;

        // Update caches
        {
            let mut cache = self.cache.lock();
            cache.put(key.clone(), block);
        }
        {
            let mut has_cache = self.has_cache.lock();
            has_cache.put(key, true);
        }

        Ok(())
    }

    fn has(&self, cid: &Cid) -> BlockstoreResult<bool> {
        let key = cid.to_string();

        // Check has_cache first
        {
            let mut has_cache = self.has_cache.lock();
            if let Some(&exists) = has_cache.get(&key) {
                return Ok(exists);
            }
        }

        // Also check block cache
        {
            let cache = self.cache.lock();
            if cache.contains(&key) {
                let mut has_cache = self.has_cache.lock();
                has_cache.put(key, true);
                return Ok(true);
            }
        }

        // Cache miss - check inner store
        let exists = self.inner.has(cid)?;

        // Cache the result
        {
            let mut has_cache = self.has_cache.lock();
            has_cache.put(key, exists);
        }

        Ok(exists)
    }

    fn delete(&mut self, cid: &Cid) -> BlockstoreResult<()> {
        let key = cid.to_string();

        // Delete from inner store
        self.inner.delete(cid)?;

        // Remove from caches
        {
            let mut cache = self.cache.lock();
            cache.pop(&key);
        }
        {
            let mut has_cache = self.has_cache.lock();
            has_cache.pop(&key);
        }

        Ok(())
    }

    fn get_size(&self, cid: &Cid) -> BlockstoreResult<Option<usize>> {
        let key = cid.to_string();

        // Check cache first
        {
            let mut cache = self.cache.lock();
            if let Some(block) = cache.get(&key) {
                return Ok(Some(block.size()));
            }
        }

        // Cache miss - check inner store
        self.inner.get_size(cid)
    }

    fn all_keys_chan(&self) -> BlockstoreResult<Box<dyn Iterator<Item = Cid> + '_>> {
        // Delegate to inner store (caching doesn't help here)
        self.inner.all_keys_chan()
    }

    fn hash_on_read(&self) -> bool {
        self.inner.hash_on_read()
    }

    fn set_hash_on_read(&mut self, enabled: bool) {
        self.inner.set_hash_on_read(enabled);
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::FlatFsBlockstore;
    use tempfile::tempdir;

    #[test]
    fn test_caching_blockstore_get() {
        let dir = tempdir().unwrap();
        let inner = FlatFsBlockstore::new_default(dir.path().join("blocks")).unwrap();
        let mut bs = CachingBlockstore::new(inner, 10);

        // Store a block
        let block = Block::new_raw(b"cached data".to_vec()).unwrap();
        let cid = *block.cid();
        bs.put(block.clone()).unwrap();

        // First get (should populate cache)
        let retrieved = bs.get(&cid).unwrap().unwrap();
        assert_eq!(retrieved.data(), b"cached data");

        // Check cache is populated
        assert_eq!(bs.cache_len(), 1);

        // Second get (should come from cache)
        let retrieved2 = bs.get(&cid).unwrap().unwrap();
        assert_eq!(retrieved2.data(), b"cached data");
    }

    #[test]
    fn test_caching_blockstore_has() {
        let dir = tempdir().unwrap();
        let inner = FlatFsBlockstore::new_default(dir.path().join("blocks")).unwrap();
        let mut bs = CachingBlockstore::new(inner, 10);

        let block = Block::new_raw(b"test".to_vec()).unwrap();
        let cid = *block.cid();

        // Initially not present
        assert!(!bs.has(&cid).unwrap());

        // Store the block
        bs.put(block).unwrap();

        // Now it exists
        assert!(bs.has(&cid).unwrap());
    }

    #[test]
    fn test_caching_blockstore_delete() {
        let dir = tempdir().unwrap();
        let inner = FlatFsBlockstore::new_default(dir.path().join("blocks")).unwrap();
        let mut bs = CachingBlockstore::new(inner, 10);

        let block = Block::new_raw(b"delete me".to_vec()).unwrap();
        let cid = *block.cid();

        bs.put(block).unwrap();
        assert!(bs.has(&cid).unwrap());
        assert_eq!(bs.cache_len(), 1);

        bs.delete(&cid).unwrap();
        assert!(!bs.has(&cid).unwrap());
        assert_eq!(bs.cache_len(), 0);
    }

    #[test]
    fn test_caching_blockstore_stats() {
        let dir = tempdir().unwrap();
        let inner = FlatFsBlockstore::new_default(dir.path().join("blocks")).unwrap();
        let mut bs = CachingBlockstore::new(inner, 100);

        for i in 0..10 {
            let block = Block::new_raw(format!("block {}", i).into_bytes()).unwrap();
            bs.put(block).unwrap();
        }

        let stats = bs.cache_stats();
        assert_eq!(stats.block_cache_len, 10);
        assert_eq!(stats.block_cache_cap, 100);
    }

    #[test]
    fn test_caching_blockstore_clear() {
        let dir = tempdir().unwrap();
        let inner = FlatFsBlockstore::new_default(dir.path().join("blocks")).unwrap();
        let mut bs = CachingBlockstore::new(inner, 10);

        let block = Block::new_raw(b"clear test".to_vec()).unwrap();
        let cid = *block.cid();
        bs.put(block).unwrap();

        assert_eq!(bs.cache_len(), 1);

        bs.clear_cache();
        assert_eq!(bs.cache_len(), 0);

        // Block should still exist in underlying store
        assert!(bs.has(&cid).unwrap());
    }
}