cache-kit 0.9.0

//! Postcard-based cache serialization with versioned envelopes.
//!
//! This module provides the canonical serialization format for all cache storage
//! in cache-kit. It uses Postcard for performance and wraps all cache entries in
//! versioned envelopes for schema evolution safety.
//!
//! # Architecture
//!
//! Every cache entry follows this format:
//! ```text
//! ┌─────────────────┬─────────────────┬──────────────────────────┐
//! │  MAGIC (4 bytes)│VERSION (4 bytes)│POSTCARD PAYLOAD (N bytes)│
//! └─────────────────┴─────────────────┴──────────────────────────┘
//!   "CKIT"              u32 (LE)           postcard::to_allocvec(T)
//! ```
//!
//! # Safety Guarantees
//!
//! - **Deterministic:** Same value always produces identical bytes
//! - **Validated:** Magic and version checked on every deserialization
//! - **Versioned:** Schema changes force cache eviction, not silent migration
//! - **Type-safe:** Postcard preserves exact Rust types
//!
//! # Example
//!
//! ```rust
//! use cache_kit::serialization::{serialize_for_cache, deserialize_from_cache};
//! use serde::{Serialize, Deserialize};
//!
//! #[derive(Serialize, Deserialize, PartialEq, Debug)]
//! struct User {
//!     id: u64,
//!     name: String,
//! }
//!
//! # fn main() -> cache_kit::Result<()> {
//! let user = User { id: 1, name: "Alice".to_string() };
//!
//! // Serialize with envelope
//! let bytes = serialize_for_cache(&user)?;
//!
//! // Deserialize with validation
//! let deserialized: User = deserialize_from_cache(&bytes)?;
//! assert_eq!(user, deserialized);
//! # Ok(())
//! # }
//! ```

use crate::error::{Error, Result};
use serde::{Deserialize, Serialize};

/// Magic header for cache-kit entries: b"CKIT"
///
/// This 4-byte signature identifies valid cache-kit cache entries.
/// Any entry without this magic is rejected during deserialization.
pub const CACHE_MAGIC: [u8; 4] = *b"CKIT";

/// Current schema version.
///
/// **CRITICAL:** Increment this constant when making breaking changes to cached types:
/// - Adding/removing struct fields
/// - Changing field types
/// - Reordering fields
/// - Changing enum variants
///
/// When deployed with a new version, old cache entries will be automatically
/// evicted and recomputed from the source of truth.
pub const CURRENT_SCHEMA_VERSION: u32 = 1;

/// Versioned envelope for cache entries.
///
/// Every cache entry is wrapped in this envelope to enable:
/// - **Corruption detection:** Invalid magic → reject entry
/// - **Schema evolution:** Version mismatch → evict and recompute
/// - **Observability:** Track version mismatches in metrics
///
/// # Format
///
/// ```text
/// ┌─────────────────┬─────────────────┬──────────────────────────┐
/// │  magic: [u8; 4] │ version: u32    │  payload: T              │
/// └─────────────────┴─────────────────┴──────────────────────────┘
/// ```
///
/// # Example
///
/// ```rust
/// use cache_kit::serialization::CacheEnvelope;
///
/// let envelope = CacheEnvelope::new("data");
/// assert_eq!(envelope.magic, *b"CKIT");
/// ```
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
pub struct CacheEnvelope<T> {
    /// Magic header: must be b"CKIT"
    pub magic: [u8; 4],
    /// Schema version: must match CURRENT_SCHEMA_VERSION
    pub version: u32,
    /// The actual cached data
    pub payload: T,
}

impl<T> CacheEnvelope<T> {
    /// Create a new envelope with current magic and version.
    ///
    /// # Example
    ///
    /// ```rust
    /// use cache_kit::serialization::CacheEnvelope;
    ///
    /// let envelope = CacheEnvelope::new(42);
    /// assert_eq!(envelope.payload, 42);
    /// ```
    pub fn new(payload: T) -> Self {
        Self {
            magic: CACHE_MAGIC,
            version: CURRENT_SCHEMA_VERSION,
            payload,
        }
    }
}

/// Serialize a value with envelope for cache storage.
///
/// This is the canonical way to serialize data for cache storage in cache-kit.
/// All cache backends (InMemory, Redis, Memcached) use this function.
///
/// # Format
///
/// ```text
/// [MAGIC: 4 bytes] [VERSION: 4 bytes] [POSTCARD PAYLOAD: N bytes]
/// ```
///
/// # Performance
///
/// Postcard serialization is approximately:
/// - **8-12x faster** than JSON serialization
/// - **50-70% smaller** than JSON payloads
///
/// # Example
///
/// ```rust
/// use cache_kit::serialization::serialize_for_cache;
/// use serde::Serialize;
///
/// #[derive(Serialize)]
/// struct User { id: u64, name: String }
///
/// # fn main() -> cache_kit::Result<()> {
/// let user = User { id: 1, name: "Alice".to_string() };
/// let bytes = serialize_for_cache(&user)?;
///
/// // Verify envelope structure
/// assert_eq!(&bytes[0..4], b"CKIT");
/// # Ok(())
/// # }
/// ```
///
/// # Errors
///
/// Returns `Error::SerializationError` if Postcard serialization fails.
pub fn serialize_for_cache<T: Serialize>(value: &T) -> Result<Vec<u8>> {
    let envelope = CacheEnvelope::new(value);
    postcard::to_allocvec(&envelope).map_err(|e| {
        log::error!("Cache serialization failed: {}", e);
        Error::SerializationError(e.to_string())
    })
}

/// Deserialize a value from cache storage with validation.
///
/// This function performs strict validation:
/// 1. Checks magic header matches b"CKIT"
/// 2. Checks version matches CURRENT_SCHEMA_VERSION
/// 3. Deserializes Postcard payload
///
/// # Validation Strategy
///
/// **On magic mismatch:** Returns `Error::InvalidCacheEntry`
/// - Indicates corrupted cache entry or non-cache-kit data
/// - Cache entry should be evicted
///
/// **On version mismatch:** Returns `Error::VersionMismatch`
/// - Indicates schema change between code versions
/// - Cache entry should be evicted and recomputed
///
/// **On Postcard error:** Returns `Error::DeserializationError`
/// - Indicates corrupted payload
/// - Cache entry should be evicted
///
/// # Example
///
/// ```rust
/// use cache_kit::serialization::{serialize_for_cache, deserialize_from_cache};
/// use serde::{Serialize, Deserialize};
///
/// #[derive(Serialize, Deserialize, PartialEq, Debug)]
/// struct User { id: u64, name: String }
///
/// # fn main() -> cache_kit::Result<()> {
/// let user = User { id: 1, name: "Alice".to_string() };
/// let bytes = serialize_for_cache(&user)?;
///
/// let deserialized: User = deserialize_from_cache(&bytes)?;
/// assert_eq!(user, deserialized);
/// # Ok(())
/// # }
/// ```
///
/// # Errors
///
/// - `Error::InvalidCacheEntry`: Invalid magic header
/// - `Error::VersionMismatch`: Schema version mismatch
/// - `Error::DeserializationError`: Corrupted Postcard payload
pub fn deserialize_from_cache<'de, T: Deserialize<'de>>(bytes: &'de [u8]) -> Result<T> {
    // Attempt to deserialize envelope
    let envelope: CacheEnvelope<T> = postcard::from_bytes(bytes).map_err(|e| {
        log::error!("Cache deserialization failed: {}", e);
        Error::DeserializationError(e.to_string())
    })?;

    // Validate magic header
    if envelope.magic != CACHE_MAGIC {
        log::warn!(
            "Invalid cache entry: expected magic {:?}, got {:?}",
            CACHE_MAGIC,
            envelope.magic
        );
        return Err(Error::InvalidCacheEntry(format!(
            "Invalid magic: expected {:?}, got {:?}",
            CACHE_MAGIC, envelope.magic
        )));
    }

    // Validate schema version
    if envelope.version != CURRENT_SCHEMA_VERSION {
        log::warn!(
            "Cache version mismatch: expected {}, got {}",
            CURRENT_SCHEMA_VERSION,
            envelope.version
        );
        return Err(Error::VersionMismatch {
            expected: CURRENT_SCHEMA_VERSION,
            found: envelope.version,
        });
    }

    Ok(envelope.payload)
}

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

    #[derive(Serialize, Deserialize, PartialEq, Debug, Clone)]
    struct TestData {
        id: u64,
        name: String,
        active: bool,
    }

    #[test]
    fn test_roundtrip() {
        let data = TestData {
            id: 123,
            name: "test".to_string(),
            active: true,
        };

        let bytes = serialize_for_cache(&data).unwrap();
        let deserialized: TestData = deserialize_from_cache(&bytes).unwrap();

        assert_eq!(data, deserialized);
    }

    #[test]
    fn test_envelope_structure() {
        let data = TestData {
            id: 123,
            name: "test".to_string(),
            active: true,
        };

        let bytes = serialize_for_cache(&data).unwrap();

        // Deserialize the envelope to verify its structure
        // (postcard uses variable-length encoding, so we can't rely on fixed byte positions)
        let envelope: CacheEnvelope<TestData> = postcard::from_bytes(&bytes).unwrap();

        // Verify envelope magic
        assert_eq!(envelope.magic, CACHE_MAGIC);

        // Verify envelope version
        assert_eq!(envelope.version, CURRENT_SCHEMA_VERSION);

        // Verify payload matches original data
        assert_eq!(envelope.payload, data);
    }

    #[test]
    fn test_envelope_new() {
        let envelope = CacheEnvelope::new(42);
        assert_eq!(envelope.magic, CACHE_MAGIC);
        assert_eq!(envelope.version, CURRENT_SCHEMA_VERSION);
        assert_eq!(envelope.payload, 42);
    }

    #[test]
    fn test_invalid_magic_rejected() {
        let mut bytes = vec![0u8; 100];
        bytes[0..4].copy_from_slice(b"XXXX"); // Wrong magic
        bytes[4..8].copy_from_slice(&1u32.to_le_bytes()); // Valid version

        let result: Result<TestData> = deserialize_from_cache(&bytes);
        assert!(result.is_err());
        match result.unwrap_err() {
            Error::InvalidCacheEntry(_) => {} // Expected
            e => panic!("Expected InvalidCacheEntry, got {:?}", e),
        }
    }

    #[test]
    fn test_version_mismatch_rejected() {
        let data = TestData {
            id: 123,
            name: "test".to_string(),
            active: true,
        };

        let mut envelope = CacheEnvelope::new(&data);
        envelope.version = 999; // Future version

        let bytes = postcard::to_allocvec(&envelope).unwrap();
        let result: Result<TestData> = deserialize_from_cache(&bytes);

        assert!(result.is_err());
        match result.unwrap_err() {
            Error::VersionMismatch { expected, found } => {
                assert_eq!(expected, CURRENT_SCHEMA_VERSION);
                assert_eq!(found, 999);
            }
            e => panic!("Expected VersionMismatch, got {:?}", e),
        }
    }

    #[test]
    fn test_deterministic_serialization() {
        let data1 = TestData {
            id: 123,
            name: "test".to_string(),
            active: true,
        };
        let data2 = data1.clone();

        let bytes1 = serialize_for_cache(&data1).unwrap();
        let bytes2 = serialize_for_cache(&data2).unwrap();

        // Must produce identical bytes
        assert_eq!(bytes1, bytes2);
    }

    #[test]
    fn test_corrupted_payload_rejected() {
        // Create a valid envelope first
        let data = TestData {
            id: 123,
            name: "test".to_string(),
            active: true,
        };
        let mut bytes = serialize_for_cache(&data).unwrap();

        // Corrupt the payload by truncating aggressively
        // With postcard's compact encoding, we need to truncate enough to ensure
        // the data structure is incomplete
        let original_len = bytes.len();
        bytes.truncate(original_len / 2); // Truncate to half the size

        let result: Result<TestData> = deserialize_from_cache(&bytes);
        assert!(result.is_err());
        match result.unwrap_err() {
            Error::DeserializationError(_) => {} // Expected
            e => panic!("Expected DeserializationError, got {:?}", e),
        }
    }

    #[test]
    fn test_empty_data_roundtrip() {
        let data = TestData {
            id: 0,
            name: String::new(),
            active: false,
        };

        let bytes = serialize_for_cache(&data).unwrap();
        let deserialized: TestData = deserialize_from_cache(&bytes).unwrap();

        assert_eq!(data, deserialized);
    }

    #[test]
    fn test_large_data_roundtrip() {
        let data = TestData {
            id: u64::MAX,
            name: "x".repeat(10000),
            active: true,
        };

        let bytes = serialize_for_cache(&data).unwrap();
        let deserialized: TestData = deserialize_from_cache(&bytes).unwrap();

        assert_eq!(data, deserialized);
    }

    #[test]
    fn test_postcard_smaller_than_json() {
        let data = TestData {
            id: 123,
            name: "test".to_string(),
            active: true,
        };

        let postcard_bytes = serialize_for_cache(&data).unwrap();
        let json_bytes = serde_json::to_vec(&data).unwrap();

        // Postcard should be smaller (including envelope overhead)
        assert!(
            postcard_bytes.len() < json_bytes.len(),
            "Postcard ({} bytes) should be smaller than JSON ({} bytes)",
            postcard_bytes.len(),
            json_bytes.len()
        );
    }
}