secra_plugins 0.1.32

//! 插件管理器错误类型
//!
//! 定义插件管理系统的所有错误类型

use thiserror::Error;

/// 插件管理器错误类型
#[derive(Debug, Error)]
pub enum PluginManagerError {
    /// 插件未找到
    #[error("插件未找到: {0}")]
    NotFound(String),

    /// 插件已存在
    #[error("插件已存在: {0}")]
    AlreadyExists(String),

    /// 插件验证失败
    #[error("插件验证失败: {0}")]
    ValidationFailed(String),

    /// 插件加载失败
    #[error("插件加载失败: {0}")]
    LoadFailed(String),

    /// 插件初始化失败
    #[error("插件初始化失败: {0}")]
    InitializationFailed(String),

    /// 插件启动失败
    #[error("插件启动失败: {0}")]
    StartFailed(String),

    /// 插件停止失败
    #[error("插件停止失败: {0}")]
    StopFailed(String),

    /// 插件卸载失败
    #[error("插件卸载失败: {0}")]
    UninstallFailed(String),

    /// 插件升级失败
    #[error("插件升级失败: {0}")]
    UpgradeFailed(String),

    /// 插件包解析失败
    #[error("插件包解析失败: {0}")]
    ParseFailed(String),

    /// 完整性验证失败
    #[error("插件包完整性验证失败: {0}")]
    IntegrityCheckFailed(String),

    /// 签名验证失败
    #[error("插件包签名验证失败: {0}")]
    SignatureCheckFailed(String),

    /// 依赖错误
    #[error("插件依赖错误: {0}")]
    DependencyError(String),

    /// 状态错误
    #[error("插件状态错误: {0}")]
    StateError(String),
    
    /// 配置错误
    #[error("插件配置错误: {0}")]
    ConfigError(String),
    
    /// 执行错误
    #[error("插件执行错误: {0}")]
    ExecutionError(String),

    /// IO 错误
    #[error("IO 错误: {0}")]
    Io(#[from] std::io::Error),
    
    /// JSON 序列化/反序列化错误
    #[error("JSON 错误: {0}")]
    Json(#[from] serde_json::Error),

    /// 其他错误
    #[error("其他错误: {0}")]
    Other(String),
}

impl PluginManagerError {
    /// 创建未找到错误
    ///
    /// 当尝试访问不存在的插件时使用此方法创建错误。
    ///
    /// # 参数
    /// * `plugin_id` - 未找到的插件ID或标识符
    ///
    /// # 返回值
    /// * `Self` - `PluginManagerError::NotFound` 变体
    ///
    /// # 示例
    /// ```no_run
    /// let error = PluginManagerError::not_found("my-plugin");
    /// ```
    pub fn not_found(plugin_id: impl Into<String>) -> Self {
        Self::NotFound(plugin_id.into())
    }
    
    /// 创建已存在错误
    ///
    /// 当尝试加载已存在的插件时使用此方法创建错误。
    ///
    /// # 参数
    /// * `plugin_id` - 已存在的插件ID或标识符
    ///
    /// # 返回值
    /// * `Self` - `PluginManagerError::AlreadyExists` 变体
    ///
    /// # 示例
    /// ```no_run
    /// let error = PluginManagerError::already_exists("my-plugin");
    /// ```
    pub fn already_exists(plugin_id: impl Into<String>) -> Self {
        Self::AlreadyExists(plugin_id.into())
    }
    
    /// 创建验证失败错误
    ///
    /// 当插件验证过程失败时使用此方法创建错误。
    /// 验证失败可能包括元数据验证、签名验证、依赖检查等。
    ///
    /// # 参数
    /// * `msg` - 验证失败的错误消息
    ///
    /// # 返回值
    /// * `Self` - `PluginManagerError::ValidationFailed` 变体
    ///
    /// # 示例
    /// ```no_run
    /// let error = PluginManagerError::validation_failed("插件元数据无效");
    /// ```
    pub fn validation_failed(msg: impl Into<String>) -> Self {
        Self::ValidationFailed(msg.into())
    }
    
    /// 创建加载失败错误
    ///
    /// 当插件加载过程失败时使用此方法创建错误。
    /// 加载失败可能包括文件读取失败、动态库加载失败等。
    ///
    /// # 参数
    /// * `msg` - 加载失败的错误消息
    ///
    /// # 返回值
    /// * `Self` - `PluginManagerError::LoadFailed` 变体
    ///
    /// # 示例
    /// ```no_run
    /// let error = PluginManagerError::load_failed("动态库加载失败");
    /// ```
    pub fn load_failed(msg: impl Into<String>) -> Self {
        Self::LoadFailed(msg.into())
    }
    
    /// 创建初始化失败错误
    ///
    /// 当插件初始化过程失败时使用此方法创建错误。
    /// 初始化失败可能包括配置错误、资源分配失败等。
    ///
    /// # 参数
    /// * `msg` - 初始化失败的错误消息
    ///
    /// # 返回值
    /// * `Self` - `PluginManagerError::InitializationFailed` 变体
    ///
    /// # 示例
    /// ```no_run
    /// let error = PluginManagerError::initialization_failed("配置验证失败");
    /// ```
    pub fn initialization_failed(msg: impl Into<String>) -> Self {
        Self::InitializationFailed(msg.into())
    }
    
    /// 创建启动失败错误
    ///
    /// 当插件启动过程失败时使用此方法创建错误。
    /// 启动失败可能包括服务启动失败、资源初始化失败等。
    ///
    /// # 参数
    /// * `msg` - 启动失败的错误消息
    ///
    /// # 返回值
    /// * `Self` - `PluginManagerError::StartFailed` 变体
    ///
    /// # 示例
    /// ```no_run
    /// let error = PluginManagerError::start_failed("服务启动失败");
    /// ```
    pub fn start_failed(msg: impl Into<String>) -> Self {
        Self::StartFailed(msg.into())
    }
    
    /// 创建停止失败错误
    ///
    /// 当插件停止过程失败时使用此方法创建错误。
    /// 停止失败可能包括资源清理失败、服务关闭失败等。
    ///
    /// # 参数
    /// * `msg` - 停止失败的错误消息
    ///
    /// # 返回值
    /// * `Self` - `PluginManagerError::StopFailed` 变体
    ///
    /// # 示例
    /// ```no_run
    /// let error = PluginManagerError::stop_failed("资源清理失败");
    /// ```
    pub fn stop_failed(msg: impl Into<String>) -> Self {
        Self::StopFailed(msg.into())
    }
    
    /// 创建依赖错误
    ///
    /// 当插件依赖关系出现问题时使用此方法创建错误。
    /// 依赖错误可能包括依赖插件不存在、依赖版本不匹配等。
    ///
    /// # 参数
    /// * `msg` - 依赖错误的错误消息
    ///
    /// # 返回值
    /// * `Self` - `PluginManagerError::DependencyError` 变体
    ///
    /// # 示例
    /// ```no_run
    /// let error = PluginManagerError::dependency_error("依赖插件不存在");
    /// ```
    pub fn dependency_error(msg: impl Into<String>) -> Self {
        Self::DependencyError(msg.into())
    }
    
    /// 创建状态错误
    ///
    /// 当插件状态转换或状态检查失败时使用此方法创建错误。
    /// 状态错误可能包括无效的状态转换、状态不一致等。
    ///
    /// # 参数
    /// * `msg` - 状态错误的错误消息
    ///
    /// # 返回值
    /// * `Self` - `PluginManagerError::StateError` 变体
    ///
    /// # 示例
    /// ```no_run
    /// let error = PluginManagerError::state_error("无效的状态转换");
    /// ```
    pub fn state_error(msg: impl Into<String>) -> Self {
        Self::StateError(msg.into())
    }
    
    /// 创建配置错误
    ///
    /// 当插件配置相关操作失败时使用此方法创建错误。
    /// 配置错误可能包括配置格式错误、配置验证失败等。
    ///
    /// # 参数
    /// * `msg` - 配置错误的错误消息
    ///
    /// # 返回值
    /// * `Self` - `PluginManagerError::ConfigError` 变体
    ///
    /// # 示例
    /// ```no_run
    /// let error = PluginManagerError::config_error("配置格式无效");
    /// ```
    pub fn config_error(msg: impl Into<String>) -> Self {
        Self::ConfigError(msg.into())
    }
    
    /// 创建执行错误
    ///
    /// 当插件功能执行失败时使用此方法创建错误。
    /// 执行错误可能包括执行超时、执行逻辑错误等。
    ///
    /// # 参数
    /// * `msg` - 执行错误的错误消息
    ///
    /// # 返回值
    /// * `Self` - `PluginManagerError::ExecutionError` 变体
    ///
    /// # 示例
    /// ```no_run
    /// let error = PluginManagerError::execution_error("执行超时");
    /// ```
    pub fn execution_error(msg: impl Into<String>) -> Self {
        Self::ExecutionError(msg.into())
    }
}

/// 插件管理器结果类型
pub type PluginManagerResult<T> = Result<T, PluginManagerError>;