secra_plugins 0.1.32

//! 插件查询相关操作

use crate::error::{PluginManagerError, PluginManagerResult};
use crate::manager::types::{PluginInfo, PluginMap};
use crate::manager::validation::sanitize_plugin_name;
use tracing::{debug, error, info, trace};

/// 查询所有插件信息
///
/// 获取插件管理器中所有已加载插件的详细信息，包括元数据、状态、指纹和子插件列表。
/// 返回的信息是只读的，不包含插件实例的内部实现细节。
///
/// # 参数
/// * `plugins` - 插件实例的共享映射表，使用 `Arc<RwLock<>>` 保证线程安全
///
/// # 返回值
/// * `PluginManagerResult<Vec<PluginInfo>>` - 成功时返回所有插件的 `PluginInfo` 列表
///
/// # 错误
/// * 通常不会返回错误，除非发生内部系统错误
///
/// # 示例
/// ```no_run
/// use std::sync::Arc;
/// use tokio::sync::RwLock;
/// use std::collections::HashMap;
/// 
/// # async fn example() {
/// let plugins = Arc::new(RwLock::new(HashMap::new()));
/// let plugin_infos = get_all_plugins(plugins).await?;
/// for info in plugin_infos {
///     println!("插件: {}, 状态: {:?}", info.metadata.name, info.status);
/// }
/// # }
/// ```
pub async fn get_all_plugins(
    plugins: PluginMap,
) -> PluginManagerResult<Vec<PluginInfo>> {
    trace!("查询所有插件信息");
    
    let plugin_infos: Vec<PluginInfo> = {
        let plugins = plugins.read().await;
        let count = plugins.len();
        debug!("当前有 {} 个插件", count);

        plugins
            .values()
            .map(|instance| PluginInfo {
                metadata: instance.metadata.clone(),
                status: instance.status.clone(),
                fingerprint: instance.fingerprint.clone(),
                child_plugins: instance.child_plugins.clone(),
            })
            .collect()
    };

    info!("查询到 {} 个插件", plugin_infos.len());
    trace!("插件信息查询完成");
    Ok(plugin_infos)
}

/// 查询单个插件信息
///
/// 根据插件ID获取指定插件的详细信息，包括元数据、状态、指纹和子插件列表。
/// 插件ID会被自动清理和验证，防止注入攻击。
///
/// # 参数
/// * `plugins` - 插件实例的共享映射表，使用 `Arc<RwLock<>>` 保证线程安全
/// * `plugin_id` - 要查询的插件ID
///
/// # 返回值
/// * `PluginManagerResult<PluginInfo>` - 成功时返回插件的 `PluginInfo`
///
/// # 错误
/// * `PluginManagerError::NotFound` - 如果指定的插件不存在
/// * `PluginManagerError::ValidationFailed` - 如果插件ID验证失败
///
/// # 示例
/// ```no_run
/// use std::sync::Arc;
/// use tokio::sync::RwLock;
/// use std::collections::HashMap;
/// 
/// # async fn example() {
/// let plugins = Arc::new(RwLock::new(HashMap::new()));
/// let plugin_info = get_plugin(plugins, "my-plugin").await?;
/// println!("插件名称: {}", plugin_info.metadata.name);
/// println!("插件状态: {:?}", plugin_info.status);
/// # }
/// ```
pub async fn get_plugin(
    plugins: PluginMap,
    plugin_id: &str,
) -> PluginManagerResult<PluginInfo> {
    trace!("查询单个插件信息: {}", plugin_id);
    
    let sanitized_plugin_id = sanitize_plugin_name(plugin_id)?;
    debug!("插件ID清理: {} -> {}", plugin_id, sanitized_plugin_id);

    let plugin_info = {
        let plugins = plugins.read().await;

        let plugin_instance = plugins.get(&sanitized_plugin_id)
            .ok_or_else(|| {
                error!("插件不存在: {}", plugin_id);
                PluginManagerError::not_found(plugin_id)
            })?;

        debug!("找到插件: {} (状态: {:?})", 
               plugin_instance.metadata.name, plugin_instance.status);

        PluginInfo {
            metadata: plugin_instance.metadata.clone(),
            status: plugin_instance.status.clone(),
            fingerprint: plugin_instance.fingerprint.clone(),
            child_plugins: plugin_instance.child_plugins.clone(),
        }
    };

    trace!("插件信息查询完成");
    Ok(plugin_info)
}