secra_plugins 0.1.32

//! 插件管理器类型定义

use crate::factory::PluginFactory;
use crate::metadata::PluginMetadata;
use crate::plugins::Plugin;
use crate::status::{ChildPluginInfo, PluginStatus};
use libloading::Library;
use serde::{Deserialize, Serialize};
use std::collections::HashMap;
use std::path::PathBuf;
use std::sync::Arc;
use tokio::sync::RwLock;

// 重新导出 CreatePluginFn，统一类型定义（避免在 factory.rs 和 types.rs 中重复定义）
pub use crate::factory::CreatePluginFn;

/// 插件实例映射表类型别名
///
/// 用于在插件管理器内部存储和管理所有插件实例的共享映射表。
/// 使用 `Arc<RwLock<>>` 保证线程安全，支持并发读写。
///
/// # 类型定义
/// `Arc<RwLock<HashMap<String, PluginInstance>>>`
///
/// # 使用场景
/// - 插件管理器的内部状态存储
/// - 所有插件操作的参数传递
/// - 线程间共享插件实例
///
/// # 示例
/// ```no_run
/// use crate::manager::types::PluginMap;
/// 
/// let plugins: PluginMap = Arc::new(RwLock::new(HashMap::new()));
/// ```
pub type PluginMap = Arc<RwLock<HashMap<String, PluginInstance>>>;

/// 插件实例包装器
///
/// 包含插件的完整信息，包括插件实例、元数据、状态、子插件列表等。
/// 这是插件管理器内部使用的核心数据结构。
///
/// # 字段
/// * `plugin`: 插件实例，实现了 `Plugin` trait
/// * `metadata`: 插件元数据，包含名称、版本、ID等信息
/// * `status`: 插件当前状态（Loaded, Initialized, Running, Stopped, Error）
/// * `child_plugins`: 子插件信息列表（如果此插件是父插件）
/// * `_library`: 动态库句柄，保持库的加载状态，防止库被卸载
/// * `fingerprint`: 插件指纹，来自插件包的签名信息
/// * `temp_library_path`: 临时库文件路径（可选）
/// * `plugin_temp_dir`: 插件临时目录路径
///
/// # 生命周期
/// 插件实例的生命周期与动态库绑定，`_library` 字段确保库在实例存在时保持加载。
pub struct PluginInstance {
    /// 插件实例
    pub plugin: Box<dyn Plugin>,
    /// 插件元数据
    pub metadata: PluginMetadata,
    /// 插件状态
    pub status: PluginStatus,
    /// 子插件信息列表
    pub child_plugins: Vec<ChildPluginInfo>,
    /// 动态库句柄（保持库加载状态）
    pub _library: Arc<Library>,
    /// 插件指纹（来自插件包）
    pub fingerprint: String,
    /// 临时库文件路径
    pub temp_library_path: Option<PathBuf>,
    /// 插件临时目录
    pub plugin_temp_dir: PathBuf,
}

/// 插件信息（用于查询返回，不包含内部实现细节）
///
/// 用于对外暴露的插件信息结构，不包含插件实例和动态库句柄等内部实现细节。
/// 可以安全地序列化和反序列化，用于 API 响应。
///
/// # 字段
/// * `metadata`: 插件元数据
/// * `status`: 插件当前状态
/// * `fingerprint`: 插件指纹
/// * `child_plugins`: 子插件信息列表
///
/// # 序列化
/// 实现了 `Serialize` 和 `Deserialize`，可以转换为 JSON 等格式。
///
/// # 使用场景
/// 用于插件查询 API 的返回结果，避免暴露内部实现细节。
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PluginInfo {
    /// 插件元数据
    pub metadata: PluginMetadata,
    /// 插件状态
    pub status: PluginStatus,
    /// 插件指纹（来自插件包）
    pub fingerprint: String,
    /// 子插件信息列表
    pub child_plugins: Vec<ChildPluginInfo>,
}