rustial_engine/io/

disk_cache.rs

//! Optional on-disk tile cache using a flat-file directory layout.
//!
//! Stores tiles as individual files under `{base_dir}/{z}/{x}/{y}.bin`.
//! Feature-gated behind the `disk-cache` feature flag.
//!
//! # On-disk format
//!
//! Each file is a minimal binary envelope:
//!
//! ```text
//! [u8 magic 'R']['M'][u8 version][u8 kind][u32 width LE][u32 height LE][RGBA8 data...]
//! ```
//!
//! - **Magic** (`RM`) guards against reading arbitrary files.
//! - **Version** (`1`) allows future format changes without silent corruption.
//! - **Kind** (`0` = Raster RGBA8) supports future tile data variants.
//! - Width / height / pixel data are identical to [`DecodedImage`](crate::tile_source::DecodedImage).
//!
//! # Thread safety
//!
//! All methods use only local `std::fs` calls with no interior mutability,
//! so `&DiskCache` is safe to share across threads. File-system atomicity
//! is achieved by writing to a temporary file and renaming, which is
//! atomic on all major platforms.
//!
//! # Eviction
//!
//! This cache is **write-only** -- it does not enforce a maximum size.
//! Call [`evict_older_than`](DiskCache::evict_older_than) periodically
//! (e.g. at startup) to prune stale entries, or use
//! [`clear`](DiskCache::clear) to wipe everything.

use crate::tile_source::TileData;
use rustial_math::TileId;
use std::io;
use std::path::{Path, PathBuf};
use std::time::SystemTime;
use thiserror::Error;

// ---------------------------------------------------------------------------
// Binary format constants
// ---------------------------------------------------------------------------

/// Two-byte magic header identifying a rustial cache file.
const MAGIC: [u8; 2] = [b'R', b'M'];

/// Current format version.  Bump when the on-disk layout changes.
const VERSION: u8 = 1;

/// Kind tag for [`TileData::Raster`].
const KIND_RASTER: u8 = 0;

/// Total header size: magic (2) + version (1) + kind (1) + width (4) + height (4).
const HEADER_LEN: usize = 12;

// ---------------------------------------------------------------------------
// Error type
// ---------------------------------------------------------------------------

/// Errors from disk cache operations.
#[derive(Debug, Error)]
pub enum DiskCacheError {
    /// An I/O error occurred reading or writing a cache file.
    #[error("disk cache I/O error: {0}")]
    Io(#[from] io::Error),
    /// The cached data could not be decoded (corrupt file, wrong version, etc.).
    #[error("disk cache decode error: {0}")]
    Decode(String),
}

// ---------------------------------------------------------------------------
// Internal helper types
// ---------------------------------------------------------------------------

/// Metadata for a single cache file, used by [`DiskCache::evict_to_size`].
struct CacheFileInfo {
    path: PathBuf,
    size: u64,
    modified: SystemTime,
}

// ---------------------------------------------------------------------------
// DiskCache
// ---------------------------------------------------------------------------

/// A flat-file on-disk tile cache.
///
/// Directory layout: `{base_dir}/{z}/{x}/{y}.bin`.
///
/// # Example
///
/// ```rust,no_run
/// use rustial_engine::DiskCache;
/// use rustial_math::TileId;
///
/// let cache = DiskCache::new("./tile_cache").unwrap();
/// let tile = TileId::new(10, 512, 340);
/// if let Some(data) = cache.get(&tile).unwrap() {
///     // use cached tile
/// }
/// ```
#[derive(Debug)]
pub struct DiskCache {
    base_dir: PathBuf,
}

impl DiskCache {
    /// Create (or open) a disk cache rooted at `base_dir`.
    ///
    /// The directory tree is created on demand; this call only ensures
    /// the root directory exists.
    pub fn new(base_dir: impl Into<PathBuf>) -> Result<Self, DiskCacheError> {
        let base_dir = base_dir.into();
        std::fs::create_dir_all(&base_dir)?;
        Ok(Self { base_dir })
    }

    /// Load a tile from cache.
    ///
    /// Returns `Ok(None)` if the tile is not cached.
    pub fn get(&self, id: &TileId) -> Result<Option<TileData>, DiskCacheError> {
        let path = self.tile_path(id);
        match std::fs::read(&path) {
            Ok(bytes) => decode_tile_data(&bytes).map(Some),
            Err(e) if e.kind() == io::ErrorKind::NotFound => Ok(None),
            Err(e) => Err(DiskCacheError::Io(e)),
        }
    }

    /// Store a tile in the cache.
    ///
    /// Writes to a temporary file first, then renames atomically to
    /// prevent readers from seeing a partial write.
    pub fn put(&self, id: &TileId, data: &TileData) -> Result<(), DiskCacheError> {
        let bytes = encode_tile_data(data);
        if bytes.is_empty() {
            // Encoding not supported for this tile variant (e.g. Vector).
            return Err(DiskCacheError::Decode(
                "disk-cache serialisation not supported for this tile data kind".into(),
            ));
        }

        let path = self.tile_path(id);
        if let Some(parent) = path.parent() {
            std::fs::create_dir_all(parent)?;
        }

        // Write to a sibling temp file, then rename.
        let tmp = path.with_extension("tmp");
        std::fs::write(&tmp, bytes)?;
        std::fs::rename(&tmp, &path)?;
        Ok(())
    }

    /// Check whether a tile is present in the cache.
    pub fn contains(&self, id: &TileId) -> bool {
        self.tile_path(id).exists()
    }

    /// Remove a single tile from the cache.
    ///
    /// Returns `true` if the file was deleted, `false` if it was not cached.
    pub fn remove(&self, id: &TileId) -> Result<bool, DiskCacheError> {
        let path = self.tile_path(id);
        match std::fs::remove_file(&path) {
            Ok(()) => Ok(true),
            Err(e) if e.kind() == io::ErrorKind::NotFound => Ok(false),
            Err(e) => Err(DiskCacheError::Io(e)),
        }
    }

    /// Delete **all** cached tiles.
    ///
    /// Removes the entire directory tree under [`base_dir`](Self::base_dir)
    /// and recreates the root.
    pub fn clear(&self) -> Result<(), DiskCacheError> {
        if self.base_dir.exists() {
            std::fs::remove_dir_all(&self.base_dir)?;
        }
        std::fs::create_dir_all(&self.base_dir)?;
        Ok(())
    }

    /// Remove cached tiles whose last-modified time is older than `max_age`.
    ///
    /// Walks the directory tree, deletes matching `.bin` files, and
    /// removes any empty parent directories left behind.
    ///
    /// Returns the number of files deleted.
    pub fn evict_older_than(
        &self,
        max_age: std::time::Duration,
    ) -> Result<usize, DiskCacheError> {
        let cutoff = SystemTime::now()
            .checked_sub(max_age)
            .unwrap_or(SystemTime::UNIX_EPOCH);

        let mut removed = 0usize;
        self.walk_and_evict(&self.base_dir, cutoff, &mut removed)?;
        Ok(removed)
    }

    /// Remove cached tiles until the total on-disk size is at or below
    /// `max_bytes`.
    ///
    /// Files are sorted oldest-first (by last-modified time) and deleted
    /// in that order until the total size drops below the limit.
    ///
    /// Returns the number of files deleted.
    pub fn evict_to_size(&self, max_bytes: u64) -> Result<usize, DiskCacheError> {
        let mut entries = Vec::new();
        self.walk_file_info(&self.base_dir, &mut entries)?;

        // Sort oldest-first (smallest modified time first).
        entries.sort_by_key(|e| e.modified);

        let total: u64 = entries.iter().map(|e| e.size).sum();
        if total <= max_bytes {
            return Ok(0);
        }

        let mut current = total;
        let mut removed = 0usize;
        for entry in &entries {
            if current <= max_bytes {
                break;
            }
            if std::fs::remove_file(&entry.path).is_ok() {
                current = current.saturating_sub(entry.size);
                removed += 1;
                // Try to remove empty parent directories.
                if let Some(parent) = entry.path.parent() {
                    let _ = std::fs::remove_dir(parent);
                }
            }
        }
        Ok(removed)
    }

    /// Count the number of cached tiles (walks the directory tree).
    pub fn len(&self) -> Result<usize, DiskCacheError> {
        let mut count = 0usize;
        self.walk_count(&self.base_dir, &mut count)?;
        Ok(count)
    }

    /// Whether the cache directory is empty (no `.bin` files).
    pub fn is_empty(&self) -> Result<bool, DiskCacheError> {
        Ok(self.len()? == 0)
    }

    /// The root directory of this cache.
    pub fn base_dir(&self) -> &Path {
        &self.base_dir
    }

    // -- private helpers --------------------------------------------------

    fn tile_path(&self, id: &TileId) -> PathBuf {
        self.base_dir
            .join(id.zoom.to_string())
            .join(id.x.to_string())
            .join(format!("{}.bin", id.y))
    }

    fn walk_and_evict(
        &self,
        dir: &Path,
        cutoff: SystemTime,
        removed: &mut usize,
    ) -> Result<(), DiskCacheError> {
        let entries = match std::fs::read_dir(dir) {
            Ok(e) => e,
            Err(e) if e.kind() == io::ErrorKind::NotFound => return Ok(()),
            Err(e) => return Err(DiskCacheError::Io(e)),
        };

        for entry in entries {
            let entry = entry?;
            let ft = entry.file_type()?;

            if ft.is_dir() {
                self.walk_and_evict(&entry.path(), cutoff, removed)?;
                // Remove the directory if it is now empty.
                let _ = std::fs::remove_dir(entry.path());
            } else if ft.is_file() {
                if let Some(ext) = entry.path().extension() {
                    if ext == "bin" {
                        let modified = entry
                            .metadata()
                            .and_then(|m| m.modified())
                            .unwrap_or(SystemTime::UNIX_EPOCH);
                        if modified < cutoff {
                            std::fs::remove_file(entry.path())?;
                            *removed += 1;
                        }
                    }
                }
            }
        }
        Ok(())
    }

    fn walk_file_info(
        &self,
        dir: &Path,
        out: &mut Vec<CacheFileInfo>,
    ) -> Result<(), DiskCacheError> {
        let entries = match std::fs::read_dir(dir) {
            Ok(e) => e,
            Err(e) if e.kind() == io::ErrorKind::NotFound => return Ok(()),
            Err(e) => return Err(DiskCacheError::Io(e)),
        };

        for entry in entries {
            let entry = entry?;
            let ft = entry.file_type()?;
            if ft.is_dir() {
                self.walk_file_info(&entry.path(), out)?;
            } else if ft.is_file() {
                if let Some(ext) = entry.path().extension() {
                    if ext == "bin" {
                        let meta = entry.metadata()?;
                        out.push(CacheFileInfo {
                            path: entry.path(),
                            size: meta.len(),
                            modified: meta.modified().unwrap_or(SystemTime::UNIX_EPOCH),
                        });
                    }
                }
            }
        }
        Ok(())
    }

    fn walk_count(&self, dir: &Path, count: &mut usize) -> Result<(), DiskCacheError> {
        let entries = match std::fs::read_dir(dir) {
            Ok(e) => e,
            Err(e) if e.kind() == io::ErrorKind::NotFound => return Ok(()),
            Err(e) => return Err(DiskCacheError::Io(e)),
        };

        for entry in entries {
            let entry = entry?;
            let ft = entry.file_type()?;
            if ft.is_dir() {
                self.walk_count(&entry.path(), count)?;
            } else if ft.is_file() {
                if let Some(ext) = entry.path().extension() {
                    if ext == "bin" {
                        *count += 1;
                    }
                }
            }
        }
        Ok(())
    }
}

// ---------------------------------------------------------------------------
// Encode / Decode
// ---------------------------------------------------------------------------

fn encode_tile_data(data: &TileData) -> Vec<u8> {
    match data {
        TileData::Raster(img) => {
            let mut buf = Vec::with_capacity(HEADER_LEN + img.data.len());
            buf.extend_from_slice(&MAGIC);
            buf.push(VERSION);
            buf.push(KIND_RASTER);
            buf.extend_from_slice(&img.width.to_le_bytes());
            buf.extend_from_slice(&img.height.to_le_bytes());
            buf.extend_from_slice(&img.data);
            buf
        }
        TileData::Vector(_) | TileData::RawVector(_) => {
            // Vector tile disk-cache serialisation is not yet implemented.
            // Return a zero-length buffer; callers should check before writing.
            Vec::new()
        }
    }
}

fn decode_tile_data(bytes: &[u8]) -> Result<TileData, DiskCacheError> {
    if bytes.len() < HEADER_LEN {
        return Err(DiskCacheError::Decode(format![
            "file too short ({} bytes, need at least {HEADER_LEN})",
            bytes.len()
        ]));
    }

    // Validate magic bytes.
    if bytes[0..2] != MAGIC {
        return Err(DiskCacheError::Decode(format![
            "invalid magic: expected {:?}, got {:?}",
            MAGIC,
            &bytes[0..2]
        ]));
    }

    // Validate version.
    let version = bytes[2];
    if version != VERSION {
        return Err(DiskCacheError::Decode(format![
            "unsupported version {version} (expected {VERSION})"
        ]));
    }

    let kind = bytes[3];
    match kind {
        KIND_RASTER => {
            let width = u32::from_le_bytes([bytes[4], bytes[5], bytes[6], bytes[7]]);
            let height = u32::from_le_bytes([bytes[8], bytes[9], bytes[10], bytes[11]]);
            let pixel_data = &bytes[HEADER_LEN..];

            let expected_len = (width as usize)
                .checked_mul(height as usize)
                .and_then(|n| n.checked_mul(4))
                .ok_or_else(|| {
                    DiskCacheError::Decode(format![
                        "dimensions overflow: {width}x{height}"
                    ])
                })?;

            if pixel_data.len() != expected_len {
                return Err(DiskCacheError::Decode(format![
                    "expected {expected_len} bytes of pixel data for {width}x{height}, got {}",
                    pixel_data.len()
                ]));
            }

            Ok(TileData::Raster(crate::tile_source::DecodedImage {
                width,
                height,
                data: std::sync::Arc::new(pixel_data.to_vec()),
            }))
        }
        _ => Err(DiskCacheError::Decode(format![
            "unknown tile kind tag: {kind}"
        ])),
    }
}

// ---------------------------------------------------------------------------
// Tests
// ---------------------------------------------------------------------------

#[cfg(test)]
mod tests {
    use super::*;
    use crate::tile_source::DecodedImage;

    /// Create a unique temp directory for each test.
    fn temp_cache(name: &str) -> (DiskCache, PathBuf) {
        let dir = std::env::temp_dir()
            .join("rustial_disk_cache_test")
            .join(name);
        let _ = std::fs::remove_dir_all(&dir);
        let cache = DiskCache::new(&dir).expect("create cache");
        (cache, dir)
    }

    fn sample_tile() -> TileData {
        TileData::Raster(DecodedImage {
            width: 2,
            height: 2,
            data: vec![255u8; 16].into(), // 2x2 RGBA
        })
    }

    // -- roundtrip ---------------------------------------------------------

    #[test]
    fn roundtrip_raster_tile() {
        let (cache, dir) = temp_cache("roundtrip");
        let id = TileId::new(5, 10, 15);
        let data = sample_tile();

        assert!(!cache.contains(&id));
        cache.put(&id, &data).expect("put");
        assert!(cache.contains(&id));

        match cache.get(&id).expect("get").expect("some") {
            TileData::Raster(img) => {
                assert_eq!(img.width, 2);
                assert_eq!(img.height, 2);
                assert_eq!(img.data.len(), 16);
                assert!(img.data.iter().all(|&b| b == 255));
            }
            TileData::Vector(_) | TileData::RawVector(_) => panic!("expected Raster, got Vector"),
        }

        assert!(cache.remove(&id).expect("remove"));
        assert!(!cache.contains(&id));
        let _ = std::fs::remove_dir_all(&dir);
    }

    // -- miss returns None -------------------------------------------------

    #[test]
    fn get_nonexistent_returns_none() {
        let (cache, dir) = temp_cache("miss");
        assert!(cache.get(&TileId::new(0, 0, 0)).expect("get").is_none());
        let _ = std::fs::remove_dir_all(&dir);
    }

    // -- remove nonexistent returns false ----------------------------------

    #[test]
    fn remove_nonexistent_returns_false() {
        let (cache, dir) = temp_cache("remove_miss");
        assert!(!cache.remove(&TileId::new(0, 0, 0)).expect("remove"));
        let _ = std::fs::remove_dir_all(&dir);
    }

    // -- decode validation -------------------------------------------------

    #[test]
    fn decode_too_short() {
        assert!(decode_tile_data(&[0, 1, 2]).is_err());
    }

    #[test]
    fn decode_bad_magic() {
        let mut data = vec![b'X', b'Y', VERSION, KIND_RASTER];
        data.extend_from_slice(&1u32.to_le_bytes()); // width
        data.extend_from_slice(&1u32.to_le_bytes()); // height
        data.extend_from_slice(&[0u8; 4]); // 1x1 RGBA
        assert!(decode_tile_data(&data).is_err());
    }

    #[test]
    fn decode_wrong_version() {
        let mut data = vec![b'R', b'M', 99, KIND_RASTER];
        data.extend_from_slice(&1u32.to_le_bytes());
        data.extend_from_slice(&1u32.to_le_bytes());
        data.extend_from_slice(&[0u8; 4]);
        assert!(decode_tile_data(&data).is_err());
    }

    #[test]
    fn decode_unknown_kind() {
        let mut data = vec![b'R', b'M', VERSION, 77];
        data.extend_from_slice(&1u32.to_le_bytes());
        data.extend_from_slice(&1u32.to_le_bytes());
        data.extend_from_slice(&[0u8; 4]);
        assert!(decode_tile_data(&data).is_err());
    }

    #[test]
    fn decode_wrong_pixel_length() {
        let mut data = vec![b'R', b'M', VERSION, KIND_RASTER];
        data.extend_from_slice(&2u32.to_le_bytes()); // width=2
        data.extend_from_slice(&2u32.to_le_bytes()); // height=2
        data.extend_from_slice(&[0u8; 4]); // only 4 bytes, need 16
        assert!(decode_tile_data(&data).is_err());
    }

    #[test]
    fn decode_overflow_dimensions() {
        let mut data = vec![b'R', b'M', VERSION, KIND_RASTER];
        data.extend_from_slice(&u32::MAX.to_le_bytes()); // width
        data.extend_from_slice(&u32::MAX.to_le_bytes()); // height
        // No pixel data -- the overflow check fires first.
        assert!(decode_tile_data(&data).is_err());
    }

    // -- clear -------------------------------------------------------------

    #[test]
    fn clear_removes_all_tiles() {
        let (cache, dir) = temp_cache("clear");
        let data = sample_tile();
        cache.put(&TileId::new(1, 0, 0), &data).expect("put");
        cache.put(&TileId::new(2, 1, 1), &data).expect("put");
        assert_eq!(cache.len().expect("len"), 2);

        cache.clear().expect("clear");
        assert!(cache.is_empty().expect("is_empty"));
        let _ = std::fs::remove_dir_all(&dir);
    }

    // -- len / is_empty ----------------------------------------------------

    #[test]
    fn len_counts_tiles() {
        let (cache, dir) = temp_cache("len");
        assert!(cache.is_empty().expect("empty"));

        let data = sample_tile();
        cache.put(&TileId::new(0, 0, 0), &data).expect("put");
        cache.put(&TileId::new(1, 0, 0), &data).expect("put");
        assert_eq!(cache.len().expect("len"), 2);
        let _ = std::fs::remove_dir_all(&dir);
    }

    // -- eviction ----------------------------------------------------------

    #[test]
    fn evict_removes_old_tiles() {
        let (cache, dir) = temp_cache("evict");
        let data = sample_tile();
        cache.put(&TileId::new(0, 0, 0), &data).expect("put");

        // Evict tiles older than 0 seconds (i.e. everything).
        let removed = cache
            .evict_older_than(std::time::Duration::ZERO)
            .expect("evict");
        assert_eq!(removed, 1);
        assert!(cache.is_empty().expect("is_empty"));
        let _ = std::fs::remove_dir_all(&dir);
    }

    #[test]
    fn evict_keeps_recent_tiles() {
        let (cache, dir) = temp_cache("evict_keep");
        let data = sample_tile();
        cache.put(&TileId::new(0, 0, 0), &data).expect("put");

        // Evict tiles older than 1 hour -- the tile we just wrote stays.
        let removed = cache
            .evict_older_than(std::time::Duration::from_secs(3600))
            .expect("evict");
        assert_eq!(removed, 0);
        assert_eq!(cache.len().expect("len"), 1);
        let _ = std::fs::remove_dir_all(&dir);
    }

    #[test]
    fn evict_to_size_removes_excess_files() {
        let (cache, dir) = temp_cache("evict_to_size");
        let data = sample_tile();
        cache.put(&TileId::new(0, 0, 0), &data).expect("put");
        cache.put(&TileId::new(1, 0, 0), &data).expect("put");
        cache.put(&TileId::new(2, 0, 0), &data).expect("put");
        assert_eq!(cache.len().expect("len"), 3);

        // Evict to a size limit just above the current size -- no files removed.
        let removed = cache
            .evict_to_size(64)
            .expect("evict_to_size");
        assert_eq!(removed, 0);
        assert_eq!(cache.len().expect("len"), 3);

        // Evict to a size limit below the size of the largest single tile.
        let removed = cache
            .evict_to_size(15)
            .expect("evict_to_size");
        assert_eq!(removed, 1);
        assert_eq!(cache.len().expect("len"), 2);

        // Clean up the remaining tiles.
        let _ = std::fs::remove_dir_all(&dir);
    }

    #[test]
    fn evict_to_size_removes_oldest() {
        let (cache, dir) = temp_cache("evict_size");
        let data = sample_tile();

        // Each sample_tile is 2x2 RGBA = 16 bytes of pixel data + 12 byte header = 28 bytes on disk.
        cache.put(&TileId::new(0, 0, 0), &data).expect("put");
        // Brief sleep so modified times differ.
        std::thread::sleep(std::time::Duration::from_millis(50));
        cache.put(&TileId::new(1, 0, 0), &data).expect("put");

        assert_eq!(cache.len().expect("len"), 2);

        // Evict to a size that fits only one file.
        let removed = cache.evict_to_size(30).expect("evict");
        assert_eq!(removed, 1);
        assert_eq!(cache.len().expect("len"), 1);
        // The older tile (zoom 0) should have been evicted.
        assert!(!cache.contains(&TileId::new(0, 0, 0)));
        assert!(cache.contains(&TileId::new(1, 0, 0)));

        let _ = std::fs::remove_dir_all(&dir);
    }

    #[test]
    fn evict_to_size_noop_when_under_limit() {
        let (cache, dir) = temp_cache("evict_size_noop");
        let data = sample_tile();
        cache.put(&TileId::new(0, 0, 0), &data).expect("put");

        let removed = cache.evict_to_size(1_000_000).expect("evict");
        assert_eq!(removed, 0);
        assert_eq!(cache.len().expect("len"), 1);
        let _ = std::fs::remove_dir_all(&dir);
    }
}