zombie_rs/

error.rs

//! Error types for zombie runtime operations.
//!
//! This module defines a comprehensive error hierarchy following Rust best practices.
//! The design prioritizes:
//! - Zero-cost when not used (no allocation until error occurs)
//! - Clear error messages for debugging
//! - Type safety via exhaustive matching
//!
//! # Error Handling Philosophy
//!
//! Internal invariant violations (logic bugs) should use `debug_assert!` or
//! `unreachable!()` - these are programming errors, not runtime errors.
//!
//! External failures (eviction during replay, type mismatches from user code)
//! should use `ZombieResult<T>` for graceful handling.

use std::fmt;
use crate::tock::Tock;

/// Main error type for zombie operations.
///
/// Each variant includes enough context to diagnose the issue.
/// Uses `Box<str>` instead of `String` for reasons to reduce size of error variants.
#[derive(Debug)]
pub enum ZombieError {
    /// No context found for a given tock during replay.
    /// This can happen if a context was incorrectly evicted while still needed.
    ContextNotFound {
        tock: Tock,
        /// Additional context about where this happened
        location: &'static str,
    },

    /// Context exists but has no replayer (should not happen in normal operation).
    NoReplayer {
        context_start: Tock,
        context_end: Tock,
    },

    /// Replay did not produce the expected result.
    ReplayFailed {
        target: Tock,
        reason: Box<str>,
    },

    /// Type mismatch during downcast (user stored wrong type or corruption).
    TypeMismatch {
        expected: &'static str,
        tock: Tock,
    },

    /// Runtime not initialized - must call `Runtime::init()` first.
    NotInitialized,

    /// Invalid record state transition (internal logic error).
    InvalidRecordState {
        from: &'static str,
        to: &'static str,
    },

    /// Eviction operation failed.
    EvictionFailed {
        reason: Box<str>,
    },

    /// Index out of bounds in context value array.
    IndexOutOfBounds {
        tock: Tock,
        context_start: Tock,
        context_end: Tock,
        index: usize,
        len: usize,
    },

    /// Replay loop exceeded maximum iterations (possible infinite loop).
    ReplayLoopExceeded {
        target: Tock,
        max_iterations: usize,
    },
}

impl fmt::Display for ZombieError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            ZombieError::ContextNotFound { tock, location } => {
                write!(f, "no context found for tock {} at {}", tock, location)
            }
            ZombieError::NoReplayer { context_start, context_end } => {
                write!(f, "context [{}, {}) has no replayer", context_start, context_end)
            }
            ZombieError::ReplayFailed { target, reason } => {
                write!(f, "replay to tock {} failed: {}", target, reason)
            }
            ZombieError::TypeMismatch { expected, tock } => {
                write!(f, "type mismatch at tock {}, expected {}", tock, expected)
            }
            ZombieError::NotInitialized => {
                write!(f, "Runtime not initialized, call Runtime::init() first")
            }
            ZombieError::InvalidRecordState { from, to } => {
                write!(f, "invalid record state transition from {} to {}", from, to)
            }
            ZombieError::EvictionFailed { reason } => {
                write!(f, "eviction failed: {}", reason)
            }
            ZombieError::IndexOutOfBounds { tock, context_start, context_end, index, len } => {
                write!(f, "index {} out of bounds (len {}) for tock {} in context [{}, {})",
                       index, len, tock, context_start, context_end)
            }
            ZombieError::ReplayLoopExceeded { target, max_iterations } => {
                write!(f, "replay loop exceeded {} iterations for tock {}", max_iterations, target)
            }
        }
    }
}

impl std::error::Error for ZombieError {}

/// Result type alias for zombie operations.
pub type ZombieResult<T> = Result<T, ZombieError>;

// ============================================================================
// Error Construction Helpers
// ============================================================================

impl ZombieError {
    /// Create a ContextNotFound error with location context.
    #[cold]
    #[inline(never)]
    pub fn context_not_found(tock: Tock, location: &'static str) -> Self {
        ZombieError::ContextNotFound { tock, location }
    }

    /// Create a TypeMismatch error.
    #[cold]
    #[inline(never)]
    pub fn type_mismatch<T>(tock: Tock) -> Self {
        ZombieError::TypeMismatch {
            expected: std::any::type_name::<T>(),
            tock,
        }
    }

    /// Create a ReplayFailed error.
    #[cold]
    #[inline(never)]
    pub fn replay_failed(target: Tock, reason: impl Into<Box<str>>) -> Self {
        ZombieError::ReplayFailed { target, reason: reason.into() }
    }
}

// ============================================================================
// Extension Traits for Ergonomic Error Handling
// ============================================================================

/// Extension trait for Option that converts to ZombieError.
pub trait OptionExt<T> {
    /// Convert None to ContextNotFound error.
    fn context_not_found(self, tock: Tock, location: &'static str) -> ZombieResult<T>;

    /// Convert None to NoReplayer error.
    fn no_replayer(self, context_start: Tock, context_end: Tock) -> ZombieResult<T>;

    /// Convert None to TypeMismatch error.
    fn type_mismatch<U>(self, tock: Tock) -> ZombieResult<T>;
}

impl<T> OptionExt<T> for Option<T> {
    fn context_not_found(self, tock: Tock, location: &'static str) -> ZombieResult<T> {
        self.ok_or_else(|| ZombieError::context_not_found(tock, location))
    }

    fn no_replayer(self, context_start: Tock, context_end: Tock) -> ZombieResult<T> {
        self.ok_or(ZombieError::NoReplayer { context_start, context_end })
    }

    fn type_mismatch<U>(self, tock: Tock) -> ZombieResult<T> {
        self.ok_or_else(|| ZombieError::type_mismatch::<U>(tock))
    }
}

/// Extension trait for Result to add context to errors.
pub trait ResultExt<T> {
    /// Add location context to errors.
    fn with_location(self, location: &'static str) -> ZombieResult<T>;
}

impl<T> ResultExt<T> for ZombieResult<T> {
    fn with_location(self, _location: &'static str) -> ZombieResult<T> {
        // For now, just pass through. Could enhance error with location later.
        self
    }
}

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

    #[test]
    fn test_error_display() {
        let err = ZombieError::context_not_found(Tock(42), "test_location");
        assert!(err.to_string().contains("42"));
        assert!(err.to_string().contains("test_location"));
    }

    #[test]
    fn test_type_mismatch_includes_type_name() {
        let err = ZombieError::type_mismatch::<Vec<i32>>(Tock(10));
        let msg = err.to_string();
        assert!(msg.contains("Vec"));
        assert!(msg.contains("10"));
    }

    #[test]
    fn test_option_ext() {
        let none: Option<i32> = None;
        let result = none.context_not_found(Tock(5), "test");
        assert!(result.is_err());
    }
}