kawa-storage 0.1.1

//! # Storage Error Types
//!
//! ストレージエンジンのエラー型定義。
//! 詳細なエラー情報とコンテキストを提供する。

use thiserror::Error;
use std::io;
use uuid::Uuid;

/// ストレージエンジンのエラー型
/// 
/// # エラーカテゴリ
/// - I/Oエラー: ファイルシステム関連
/// - データ整合性エラー: CRCチェック、フォーマット不正
/// - 設定エラー: 無効な設定値
/// - 容量エラー: ディスク容量不足
/// 
/// # @todo
/// - [ ] エラーメトリクスの追加
/// - [ ] リトライ可能エラーの分類
/// - [ ] 詳細なエラーコード体系
#[derive(Error, Debug)]
pub enum StorageError {
    /// I/Oエラー
    #[error("I/O error: {0}")]
    Io(#[from] io::Error),
    
    /// データ整合性エラー - CRCチェック失敗
    #[error("Data integrity error: CRC mismatch at offset {offset}, expected {expected:x}, got {actual:x}")]
    CrcMismatch {
        offset: u64,
        expected: u32,
        actual: u32,
    },
    
    /// データフォーマットエラー
    #[error("Invalid data format: {message}")]
    InvalidFormat { message: String },
    
    /// セグメントが見つからない
    #[error("Segment not found: {segment_id}")]
    SegmentNotFound { segment_id: Uuid },
    
    /// オフセット範囲外エラー
    #[error("Offset out of range: {offset} is beyond available data")]
    OffsetOutOfRange { offset: u64 },
    
    /// 設定エラー
    #[error("Configuration error: {message}")]
    Configuration { message: String },
    
    /// ディスク容量不足
    #[error("Insufficient disk space: need {required} bytes, available {available} bytes")]
    InsufficientSpace {
        required: u64,
        available: u64,
    },
    
    /// 同期エラー
    #[error("Synchronization error: {message}")]
    Synchronization { message: String },
    
    /// シリアライゼーションエラー
    #[error("Serialization error: {0}")]
    Serialization(#[from] bincode::Error),
    
    /// 内部エラー（予期しないエラー）
    #[error("Internal error: {message}")]
    Internal { message: String },
}

impl StorageError {
    /// 設定エラーを作成
    pub fn configuration(message: impl Into<String>) -> Self {
        Self::Configuration {
            message: message.into(),
        }
    }
    
    /// データフォーマットエラーを作成
    pub fn invalid_format(message: impl Into<String>) -> Self {
        Self::InvalidFormat {
            message: message.into(),
        }
    }
    
    /// 内部エラーを作成
    pub fn internal(message: impl Into<String>) -> Self {
        Self::Internal {
            message: message.into(),
        }
    }
    
    /// 同期エラーを作成
    pub fn synchronization(message: impl Into<String>) -> Self {
        Self::Synchronization {
            message: message.into(),
        }
    }
    
    /// このエラーがリトライ可能かどうかを判定
    /// 
    /// # Returns
    /// * `true` - リトライ可能なエラー
    /// * `false` - リトライ不可能なエラー
    /// 
    /// # @todo
    /// - [ ] より詳細なリトライ判定ロジック
    pub fn is_retryable(&self) -> bool {
        match self {
            Self::Io(_) => true,
            Self::InsufficientSpace { .. } => false,
            Self::CrcMismatch { .. } => false,
            Self::InvalidFormat { .. } => false,
            Self::SegmentNotFound { .. } => false,
            Self::OffsetOutOfRange { .. } => false,
            Self::Configuration { .. } => false,
            Self::Synchronization { .. } => true,
            Self::Serialization(_) => false,
            Self::Internal { .. } => false,
        }
    }
    
    /// エラーの重要度を取得
    /// 
    /// # Returns
    /// - `High`: 即座に対処が必要
    /// - `Medium`: 監視が必要
    /// - `Low`: 通常のエラー
    pub fn severity(&self) -> ErrorSeverity {
        match self {
            Self::CrcMismatch { .. } => ErrorSeverity::High,
            Self::InsufficientSpace { .. } => ErrorSeverity::High,
            Self::Internal { .. } => ErrorSeverity::High,
            Self::InvalidFormat { .. } => ErrorSeverity::Medium,
            Self::SegmentNotFound { .. } => ErrorSeverity::Medium,
            Self::Configuration { .. } => ErrorSeverity::Medium,
            Self::Io(_) => ErrorSeverity::Low,
            Self::OffsetOutOfRange { .. } => ErrorSeverity::Low,
            Self::Synchronization { .. } => ErrorSeverity::Low,
            Self::Serialization(_) => ErrorSeverity::Low,
        }
    }
}

/// エラーの重要度
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ErrorSeverity {
    /// 高: 即座に対処が必要
    High,
    /// 中: 監視が必要
    Medium,
    /// 低: 通常のエラー
    Low,
}

/// エラー結果型の型エイリアス
pub type StorageResult<T> = Result<T, StorageError>;