Skip to main content

yang_base/plugin/
mod.rs

1//! 插件管理模块
2//!
3//! 提供插件注册、管理和生命周期控制功能。
4//!
5//! # 主要组件
6//!
7//! - `Plugin` trait:插件接口定义
8//! - `PluginManager`:插件管理器,负责插件的注册和查找
9//!
10//! # 示例
11//!
12//! ```rust,ignore
13//! use yang_base::plugin::{Plugin, PluginManager};
14//!
15//! // 定义插件
16//! struct MyPlugin;
17//!
18//! #[async_trait::async_trait]
19//! impl Plugin for MyPlugin {
20//!     fn name(&self) -> &str {
21//!         "my_plugin"
22//!     }
23//! }
24//!
25//! // 注册插件
26//! let manager = PluginManager::new();
27//! manager.register(MyPlugin).await?;
28//! ```
29
30use async_trait::async_trait;
31use serde_json::Value as JsonValue;
32use std::collections::HashMap;
33use std::fmt;
34use std::sync::Arc;
35use tokio::sync::RwLock;
36
37use crate::error::BaseError;
38
39/// 插件生命周期回调的结构化错误类型。
40pub type PluginError = Box<dyn std::error::Error + Send + Sync + 'static>;
41
42/// 插件生命周期阶段。
43#[derive(Debug, Clone, Copy, PartialEq, Eq)]
44#[non_exhaustive]
45pub enum PluginLifecycleStage {
46    /// 注册回调。
47    Register,
48    /// 初始化 SQL 或初始化回调。
49    Initialize,
50    /// 关闭回调。
51    Shutdown,
52}
53
54impl fmt::Display for PluginLifecycleStage {
55    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
56        formatter.write_str(match self {
57            Self::Register => "register",
58            Self::Initialize => "initialize",
59            Self::Shutdown => "shutdown",
60        })
61    }
62}
63
64fn normalize_plugin_name(name: &str) -> Result<&str, BaseError> {
65    let name = name.trim();
66    if name.is_empty() {
67        return Err(BaseError::PluginRegisterFailed(
68            "<empty>".to_string(),
69            "插件名称不能为空".to_string(),
70        ));
71    }
72
73    Ok(name)
74}
75
76fn normalize_plugin_lookup_name(name: &str) -> Option<&str> {
77    let name = name.trim();
78    (!name.is_empty()).then_some(name)
79}
80
81/// 插件接口
82///
83/// 所有插件必须实现此 trait
84///
85/// # 示例
86///
87/// ```rust,ignore
88/// use yang_base::plugin::Plugin;
89/// use async_trait::async_trait;
90///
91/// struct MyPlugin;
92///
93/// #[async_trait]
94/// impl Plugin for MyPlugin {
95///     fn name(&self) -> &str {
96///         "my_plugin"
97///     }
98///     
99///     fn version(&self) -> &str {
100///         "1.0.0"
101///     }
102///     
103///     fn init_sql(&self) -> Vec<String> {
104///         vec![
105///             "CREATE TABLE IF NOT EXISTS my_table (id INT PRIMARY KEY)".to_string()
106///         ]
107///     }
108/// }
109/// ```
110#[async_trait]
111pub trait Plugin: Send + Sync {
112    /// 获取插件名称
113    ///
114    /// 插件名称必须唯一,用于标识和查找插件
115    ///
116    /// # 返回
117    /// - 插件名称字符串
118    fn name(&self) -> &str;
119
120    /// 获取插件版本
121    ///
122    /// 使用语义化版本号,格式:major.minor.patch
123    ///
124    /// # 返回
125    /// - 版本号字符串,默认为 "0.1.0"
126    fn version(&self) -> &str {
127        "0.1.0"
128    }
129
130    /// 获取插件依赖列表
131    ///
132    /// 返回当前插件依赖的其他插件名称列表
133    /// 系统会确保依赖插件先于当前插件初始化
134    ///
135    /// # 返回
136    /// - 依赖插件名称列表,默认为空
137    fn dependencies(&self) -> &[&str] {
138        &[]
139    }
140
141    /// 获取数据库初始化 SQL 脚本
142    ///
143    /// 返回创建表的 SQL 语句列表
144    /// 建议使用 IF NOT EXISTS 确保幂等性
145    ///
146    /// # 返回
147    /// - SQL 语句列表,默认为空
148    fn init_sql(&self) -> Vec<String> {
149        Vec::new()
150    }
151
152    /// 获取数据库迁移脚本
153    ///
154    /// 返回 (版本号, SQL 脚本) 的列表
155    /// 版本号格式:YYYYMMDDHHMMSS
156    ///
157    /// # 返回
158    /// - (版本号, SQL 脚本) 元组列表,默认为空
159    fn migration_sql(&self) -> Vec<(String, String)> {
160        Vec::new()
161    }
162
163    /// 获取插件配置 Schema
164    ///
165    /// 返回 JSON Schema 格式的配置定义
166    ///
167    /// # 返回
168    /// - Some(JsonValue): 配置 Schema
169    /// - None: 无配置要求(默认)
170    fn config_schema(&self) -> Option<JsonValue> {
171        None
172    }
173
174    /// 插件注册时的回调
175    ///
176    /// 在插件被注册到 PluginManager 时调用
177    ///
178    /// # 返回
179    /// - Ok(()): 注册成功
180    /// - Err: 注册失败
181    async fn on_register(&self) -> Result<(), PluginError> {
182        Ok(())
183    }
184
185    /// 数据库初始化后的回调
186    ///
187    /// 在插件的数据库表创建完成后调用
188    /// 可用于插入初始数据或执行其他初始化逻辑
189    ///
190    /// # 返回
191    /// - Ok(()): 初始化成功
192    /// - Err: 初始化失败
193    async fn on_init(&self) -> Result<(), PluginError> {
194        Ok(())
195    }
196
197    /// 系统关闭时的回调
198    ///
199    /// 在系统关闭时调用,用于清理资源
200    ///
201    /// # 返回
202    /// - Ok(()): 关闭成功
203    /// - Err: 关闭失败
204    async fn on_shutdown(&self) -> Result<(), PluginError> {
205        Ok(())
206    }
207}
208
209/// 插件管理器
210///
211/// 负责插件的注册、查找和生命周期管理
212///
213/// # 示例
214///
215/// ```rust,ignore
216/// use yang_base::plugin::{Plugin, PluginManager};
217///
218/// #[tokio::main]
219/// async fn main() -> Result<(), Box<dyn std::error::Error>> {
220///     let manager = PluginManager::new();
221///     
222///     // 注册插件
223///     manager.register(MyPlugin).await?;
224///     
225///     // 查找插件
226///     if let Some(plugin) = manager.get("my_plugin").await {
227///         println!("找到插件: {}", plugin.name());
228///     }
229///     
230///     // 获取所有插件(按依赖顺序)
231///     let plugins = manager.get_all().await;
232///     
233///     // 关闭所有插件
234///     manager.shutdown().await?;
235///     
236///     Ok(())
237/// }
238/// ```
239pub struct PluginManager {
240    /// 已注册的插件
241    /// Key: 插件名称, Value: 插件实例
242    plugins: Arc<RwLock<HashMap<String, Arc<dyn Plugin>>>>,
243
244    /// 插件配置
245    /// Key: 插件名称, Value: 配置 JSON
246    configs: Arc<RwLock<HashMap<String, JsonValue>>>,
247}
248
249impl PluginManager {
250    /// 创建新的插件管理器
251    ///
252    /// # 返回
253    /// - 新的 PluginManager 实例
254    ///
255    /// # 示例
256    ///
257    /// ```rust
258    /// use yang_base::plugin::PluginManager;
259    ///
260    /// let manager = PluginManager::new();
261    /// ```
262    pub fn new() -> Self {
263        Self {
264            plugins: Arc::new(RwLock::new(HashMap::new())),
265            configs: Arc::new(RwLock::new(HashMap::new())),
266        }
267    }
268
269    /// 注册插件
270    ///
271    /// # 参数
272    /// - plugin: 插件实例
273    ///
274    /// # 返回
275    /// - Ok(()): 注册成功
276    /// - Err(BaseError): 注册失败(如插件名称重复)
277    ///
278    /// # 示例
279    ///
280    /// ```rust,ignore
281    /// use yang_base::plugin::{Plugin, PluginManager};
282    ///
283    /// let manager = PluginManager::new();
284    /// manager.register(MyPlugin).await?;
285    /// ```
286    pub async fn register<P: Plugin + 'static>(&self, plugin: P) -> Result<(), BaseError> {
287        let name = normalize_plugin_name(plugin.name())?.to_string();
288        let plugin = Arc::new(plugin);
289
290        // 第一阶段:读锁检查(快速路径,避免持写锁跨 await)
291        {
292            let plugins = self.plugins.read().await;
293            if plugins.contains_key(&name) {
294                return Err(BaseError::PluginAlreadyRegistered(name));
295            }
296        } // 尽早释放读锁
297
298        // 调用注册回调(不持任何锁)
299        plugin
300            .on_register()
301            .await
302            .map_err(|source| BaseError::PluginLifecycleFailed {
303                plugin: name.clone(),
304                stage: PluginLifecycleStage::Register,
305                source,
306            })?;
307
308        // 第二阶段:写锁 + 二次校验(防止 TOCTOU 竞态)
309        {
310            let mut plugins = self.plugins.write().await;
311            if plugins.contains_key(&name) {
312                return Err(BaseError::PluginAlreadyRegistered(name));
313            }
314            plugins.insert(name.clone(), plugin);
315        }
316
317        log::info!("插件已注册: {}", name);
318        Ok(())
319    }
320
321    /// 查找插件
322    ///
323    /// # 参数
324    /// - name: 插件名称
325    ///
326    /// # 返回
327    /// - `Some(Arc<dyn Plugin>)`: 找到插件
328    /// - None: 插件不存在
329    ///
330    /// # 示例
331    ///
332    /// ```rust,ignore
333    /// use yang_base::plugin::PluginManager;
334    ///
335    /// let manager = PluginManager::new();
336    /// if let Some(plugin) = manager.get("my_plugin").await {
337    ///     println!("找到插件: {}", plugin.name());
338    /// }
339    /// ```
340    pub async fn get(&self, name: &str) -> Option<Arc<dyn Plugin>> {
341        let name = normalize_plugin_lookup_name(name)?;
342        let plugins = self.plugins.read().await;
343        plugins.get(name).cloned()
344    }
345
346    /// 获取所有已注册插件
347    ///
348    /// # 返回
349    /// - 插件列表(按依赖关系排序)
350    ///
351    /// # 示例
352    ///
353    /// ```rust,ignore
354    /// use yang_base::plugin::PluginManager;
355    ///
356    /// let manager = PluginManager::new();
357    /// let plugins = manager.get_all().await;
358    /// for plugin in plugins {
359    ///     println!("插件: {} v{}", plugin.name(), plugin.version());
360    /// }
361    /// ```
362    pub async fn get_all(&self) -> Vec<Arc<dyn Plugin>> {
363        let plugins = self.plugins.read().await;
364        let mut plugin_list: Vec<_> = plugins.values().cloned().collect();
365
366        // 按依赖关系排序
367        self.topological_sort(&mut plugin_list);
368
369        plugin_list
370    }
371
372    /// 加载插件配置
373    ///
374    /// # 参数
375    /// - name: 插件名称
376    /// - config: 配置 JSON
377    ///
378    /// # 返回
379    /// - Ok(()): 加载成功
380    /// - Err(BaseError): 加载失败(如配置验证失败)
381    ///
382    /// # 示例
383    ///
384    /// ```rust,ignore
385    /// use yang_base::plugin::PluginManager;
386    /// use serde_json::json;
387    ///
388    /// let manager = PluginManager::new();
389    /// let config = json!({"key": "value"});
390    /// manager.load_config("my_plugin", config).await?;
391    /// ```
392    pub async fn load_config(&self, name: &str, config: JsonValue) -> Result<(), BaseError> {
393        let normalized_name = normalize_plugin_lookup_name(name)
394            .ok_or_else(|| BaseError::PluginNotFound(name.to_string()))?;
395
396        // 获取插件
397        let plugin = self
398            .get(normalized_name)
399            .await
400            .ok_or_else(|| BaseError::PluginNotFound(normalized_name.to_string()))?;
401
402        // 验证配置(插件未定义 config_schema 时跳过验证)
403        if let Some(schema) = plugin.config_schema() {
404            self.validate_config(normalized_name, &config, &schema)?;
405        }
406
407        // 存储配置
408        {
409            let mut configs = self.configs.write().await;
410            configs.insert(normalized_name.to_string(), config);
411        }
412
413        Ok(())
414    }
415
416    /// 获取插件配置
417    ///
418    /// # 参数
419    /// - name: 插件名称
420    ///
421    /// # 返回
422    /// - Some(JsonValue): 插件配置
423    /// - None: 配置不存在
424    ///
425    /// # 示例
426    ///
427    /// ```rust,ignore
428    /// use yang_base::plugin::PluginManager;
429    ///
430    /// let manager = PluginManager::new();
431    /// if let Some(config) = manager.get_config("my_plugin").await {
432    ///     println!("配置: {:?}", config);
433    /// }
434    /// ```
435    pub async fn get_config(&self, name: &str) -> Option<JsonValue> {
436        let name = normalize_plugin_lookup_name(name)?;
437        let configs = self.configs.read().await;
438        configs.get(name).cloned()
439    }
440
441    /// 拓扑排序(按依赖关系排序)
442    ///
443    /// # 参数
444    /// - plugins: 插件列表
445    ///
446    /// # 说明
447    /// 使用 Kahn 算法进行拓扑排序,确保依赖插件先于当前插件
448    fn topological_sort(&self, plugins: &mut Vec<Arc<dyn Plugin>>) {
449        // 构建依赖图
450        let mut in_degree: HashMap<String, usize> = HashMap::new();
451        let mut graph: HashMap<String, Vec<String>> = HashMap::new();
452
453        for plugin in plugins.iter() {
454            let name = plugin.name().to_string();
455            in_degree.entry(name.clone()).or_insert(0);
456
457            for dep in plugin.dependencies() {
458                graph.entry(dep.to_string()).or_default().push(name.clone());
459                *in_degree.entry(name.clone()).or_insert(0) += 1;
460            }
461        }
462
463        // Kahn 算法
464        let mut queue: Vec<String> = in_degree
465            .iter()
466            .filter(|(_, &degree)| degree == 0)
467            .map(|(name, _)| name.clone())
468            .collect();
469
470        let mut sorted = Vec::new();
471
472        while let Some(node) = queue.pop() {
473            sorted.push(node.clone());
474
475            if let Some(neighbors) = graph.get(&node) {
476                for neighbor in neighbors {
477                    if let Some(degree) = in_degree.get_mut(neighbor) {
478                        *degree -= 1;
479                        if *degree == 0 {
480                            queue.push(neighbor.clone());
481                        }
482                    }
483                }
484            }
485        }
486
487        // 检测循环依赖:Kahn 算法结束后,未被排序的节点构成环
488        if sorted.len() < plugins.len() {
489            let circular: Vec<String> = plugins
490                .iter()
491                .filter(|p| !sorted.iter().any(|n| n == p.name()))
492                .map(|p| p.name().to_string())
493                .collect();
494            log::error!(
495                "检测到循环依赖,以下插件将无法按依赖顺序加载: {}",
496                circular.join(", ")
497            );
498            // 将循环中的插件追加到排序末尾,保证所有插件都出现在结果中
499            sorted.extend(circular);
500        }
501
502        // 重新排序插件列表
503        plugins.sort_by_key(|p| {
504            sorted
505                .iter()
506                .position(|n| n == p.name())
507                .unwrap_or(usize::MAX)
508        });
509    }
510
511    /// 验证配置
512    ///
513    /// 使用 jsonschema crate 对配置进行 JSON Schema 验证。
514    /// 未启用 `plugin-schema` feature 时跳过验证。
515    ///
516    /// # 参数
517    /// - `plugin_name`: 插件名称(用于错误信息)
518    /// - `config`: 配置 JSON
519    /// - `schema`: JSON Schema
520    ///
521    /// # 返回
522    /// - `Ok(())`: 验证通过
523    /// - `Err(BaseError::PluginConfigInvalid)`: 配置不符合 Schema
524    fn validate_config(
525        &self,
526        plugin_name: &str,
527        config: &JsonValue,
528        schema: &JsonValue,
529    ) -> Result<(), BaseError> {
530        // 使用 jsonschema crate 进行 JSON Schema 验证
531        #[cfg(feature = "plugin-schema")]
532        {
533            // 构建可复用的验证器
534            let validator = jsonschema::validator_for(schema).map_err(|e| {
535                BaseError::PluginConfigInvalid(
536                    plugin_name.to_string(),
537                    format!("Schema 编译失败: {}", e),
538                )
539            })?;
540
541            // 收集所有验证错误信息
542            let error_msgs: Vec<String> = validator
543                .iter_errors(config)
544                .map(|e| e.to_string())
545                .collect();
546
547            if !error_msgs.is_empty() {
548                return Err(BaseError::PluginConfigInvalid(
549                    plugin_name.to_string(),
550                    error_msgs.join("; "),
551                ));
552            }
553        }
554
555        // 未启用 plugin-schema feature 时,跳过验证直接返回成功
556        #[cfg(not(feature = "plugin-schema"))]
557        {
558            let _ = (plugin_name, config, schema);
559        }
560
561        Ok(())
562    }
563
564    /// 关闭所有插件
565    ///
566    /// 按照依赖关系的逆序调用插件的 on_shutdown 方法
567    ///
568    /// # 返回
569    /// - Ok(()): 关闭成功
570    /// - Err(BaseError): 关闭失败
571    ///
572    /// # 示例
573    ///
574    /// ```rust,ignore
575    /// use yang_base::plugin::PluginManager;
576    ///
577    /// let manager = PluginManager::new();
578    /// // ... 注册插件 ...
579    /// manager.shutdown().await?;
580    /// ```
581    pub async fn shutdown(&self) -> Result<(), BaseError> {
582        let mut plugins = self.get_all().await;
583        plugins.reverse(); // 逆序关闭
584
585        let mut errors: Vec<(String, PluginError)> = Vec::new();
586
587        for plugin in plugins {
588            let name = plugin.name();
589            if let Err(e) = plugin.on_shutdown().await {
590                log::error!("插件 {} 关闭失败: {}", name, e);
591                errors.push((name.to_string(), e));
592            } else {
593                log::info!("插件已关闭: {}", name);
594            }
595        }
596
597        if let Some((plugin, source)) = errors.into_iter().next() {
598            Err(BaseError::PluginLifecycleFailed {
599                plugin,
600                stage: PluginLifecycleStage::Shutdown,
601                source,
602            })
603        } else {
604            Ok(())
605        }
606    }
607}
608
609impl Default for PluginManager {
610    fn default() -> Self {
611        Self::new()
612    }
613}
614
615/// 插件管理器构建器(构建阶段使用)
616///
617/// 在构建阶段负责插件的注册,构建完成后生成不可变的 `PluginRegistry`。
618/// 构建阶段可以进行可变操作,运行阶段通过 `PluginRegistry` 进行无锁查找。
619///
620/// # 示例
621///
622/// ```rust,ignore
623/// use yang_base::plugin::{Plugin, PluginManagerBuilder};
624///
625/// #[tokio::main]
626/// async fn main() -> Result<(), Box<dyn std::error::Error>> {
627///     let mut builder = PluginManagerBuilder::new();
628///
629///     // 注册插件
630///     builder.register(MyPlugin).await?;
631///
632///     // 构建不可变的 PluginRegistry
633///     let registry = builder.build();
634///
635///     // 无锁查找插件
636///     if let Some(plugin) = registry.get("my_plugin") {
637///         println!("找到插件: {}", plugin.name());
638///     }
639///
640///     Ok(())
641/// }
642/// ```
643pub struct PluginManagerBuilder {
644    /// 已注册的插件(构建阶段可变)
645    /// Key: 插件名称, Value: 插件实例
646    plugins: HashMap<String, Arc<dyn Plugin>>,
647
648    /// 插件配置
649    /// Key: 插件名称, Value: 配置 JSON
650    configs: HashMap<String, JsonValue>,
651}
652
653impl PluginManagerBuilder {
654    /// 创建新的插件管理器构建器
655    ///
656    /// # 返回
657    /// - 新的 PluginManagerBuilder 实例
658    ///
659    /// # 示例
660    ///
661    /// ```rust
662    /// use yang_base::plugin::PluginManagerBuilder;
663    ///
664    /// let builder = PluginManagerBuilder::new();
665    /// ```
666    pub fn new() -> Self {
667        Self {
668            plugins: HashMap::new(),
669            configs: HashMap::new(),
670        }
671    }
672
673    /// 注册插件(构建阶段使用)
674    ///
675    /// 检查插件名称是否重复,调用 `on_register()` 回调,然后插入 HashMap。
676    ///
677    /// # 参数
678    /// - `plugin`: 插件实例
679    ///
680    /// # 返回
681    /// - `Ok(())`: 注册成功
682    /// - `Err(BaseError)`: 注册失败(如插件名称重复或注册回调失败)
683    ///
684    /// # 示例
685    ///
686    /// ```rust,ignore
687    /// use yang_base::plugin::{Plugin, PluginManagerBuilder};
688    ///
689    /// let mut builder = PluginManagerBuilder::new();
690    /// builder.register(MyPlugin).await?;
691    /// ```
692    pub async fn register<P: Plugin + 'static>(&mut self, plugin: P) -> Result<(), BaseError> {
693        let name = normalize_plugin_name(plugin.name())?.to_string();
694
695        // 检查插件是否已注册(构建阶段直接访问 HashMap,无需加锁)
696        if self.plugins.contains_key(&name) {
697            return Err(BaseError::PluginAlreadyRegistered(name));
698        }
699
700        let plugin = Arc::new(plugin);
701
702        // 调用注册回调
703        plugin
704            .on_register()
705            .await
706            .map_err(|source| BaseError::PluginLifecycleFailed {
707                plugin: name.clone(),
708                stage: PluginLifecycleStage::Register,
709                source,
710            })?;
711
712        // 插入 HashMap
713        self.plugins.insert(name.clone(), plugin);
714
715        log::info!("插件已注册(构建阶段): {}", name);
716        Ok(())
717    }
718
719    /// 消费构建器,生成不可变的 PluginRegistry
720    ///
721    /// 调用此方法后,构建器被消费,返回运行阶段使用的 `PluginRegistry`。
722    /// `PluginRegistry` 在构建时执行一次拓扑排序并缓存结果。
723    ///
724    /// # 返回
725    /// - `Ok(PluginRegistry)`: 构建成功
726    /// - `Err(BaseError::PluginDependencyMissing)`: 某插件的依赖未注册
727    /// - `Err(BaseError::PluginCircularDependency)`: 插件之间存在循环依赖
728    ///
729    /// # 示例
730    ///
731    /// ```rust,ignore
732    /// use yang_base::plugin::PluginManagerBuilder;
733    ///
734    /// let mut builder = PluginManagerBuilder::new();
735    /// // ... 注册插件 ...
736    /// let registry = builder.build()?;
737    /// ```
738    pub fn build(self) -> Result<PluginRegistry, BaseError> {
739        // 检查每个插件的依赖是否都已注册
740        for (plugin_name, plugin) in &self.plugins {
741            for dep in plugin.dependencies() {
742                let dep = normalize_plugin_name(dep)?;
743                if !self.plugins.contains_key(dep) {
744                    // 依赖未注册,返回错误
745                    return Err(BaseError::PluginDependencyMissing(
746                        plugin_name.clone(),
747                        dep.to_string(),
748                    ));
749                }
750            }
751        }
752        // 依赖完整性检查通过,构建注册表(内部会检测循环依赖)
753        PluginRegistry::new(self.plugins, self.configs)
754    }
755}
756
757impl Default for PluginManagerBuilder {
758    fn default() -> Self {
759        Self::new()
760    }
761}
762
763/// 插件注册表(运行阶段使用,无锁)
764///
765/// 由 `PluginManagerBuilder::build()` 生成,存储不可变的插件集合。
766/// 运行阶段通过 HashMap 直接查找,无需获取任何锁,实现 O(1) 无锁查找。
767/// 拓扑排序结果在构建时计算一次并缓存,多次调用 `get_all()` 无需重新计算。
768///
769/// # 示例
770///
771/// ```rust,ignore
772/// use yang_base::plugin::{Plugin, PluginManagerBuilder};
773///
774/// #[tokio::main]
775/// async fn main() -> Result<(), Box<dyn std::error::Error>> {
776///     let mut builder = PluginManagerBuilder::new();
777///     builder.register(MyPlugin).await?;
778///     let registry = builder.build();
779///
780///     // 无锁 O(1) 查找
781///     if let Some(plugin) = registry.get("my_plugin") {
782///         println!("找到插件: {}", plugin.name());
783///     }
784///
785///     // 获取缓存的排序结果(无需重新计算)
786///     let all_plugins = registry.get_all();
787///
788///     // 关闭所有插件
789///     registry.shutdown().await?;
790///
791///     Ok(())
792/// }
793/// ```
794pub struct PluginRegistry {
795    /// 不可变插件映射(无 RwLock 包装,运行阶段无锁访问)
796    /// Key: 插件名称, Value: 插件实例
797    plugins: HashMap<String, Arc<dyn Plugin>>,
798
799    /// 拓扑排序缓存(构建时计算一次,运行阶段直接返回引用)
800    sorted_plugins: Vec<Arc<dyn Plugin>>,
801
802    /// 插件配置
803    /// Key: 插件名称, Value: 配置 JSON
804    configs: HashMap<String, JsonValue>,
805}
806
807impl PluginRegistry {
808    /// 创建新的插件注册表(私有构造方法)
809    ///
810    /// 接收 plugins 和 configs,调用 `compute_topological_sort` 并缓存排序结果。
811    /// 此方法仅由 `PluginManagerBuilder::build()` 调用。
812    ///
813    /// # 参数
814    /// - `plugins`: 插件 HashMap
815    /// - `configs`: 配置 HashMap
816    ///
817    /// # 返回
818    /// - `Ok(PluginRegistry)`: 构建成功
819    /// - `Err(BaseError::PluginCircularDependency)`: 存在循环依赖
820    fn new(
821        plugins: HashMap<String, Arc<dyn Plugin>>,
822        configs: HashMap<String, JsonValue>,
823    ) -> Result<Self, BaseError> {
824        // 构建时执行一次拓扑排序并缓存结果(内部检测循环依赖)
825        let sorted_plugins = Self::compute_topological_sort(&plugins)?;
826        Ok(Self {
827            plugins,
828            sorted_plugins,
829            configs,
830        })
831    }
832
833    /// 查找插件(无锁,O(1) HashMap 查找)
834    ///
835    /// 直接通过 HashMap 查找,无需获取任何锁。
836    ///
837    /// # 参数
838    /// - `name`: 插件名称
839    ///
840    /// # 返回
841    /// - `Some(&Arc<dyn Plugin>)`: 找到插件
842    /// - `None`: 插件不存在
843    ///
844    /// # 示例
845    ///
846    /// ```rust,ignore
847    /// use yang_base::plugin::PluginManagerBuilder;
848    ///
849    /// let registry = PluginManagerBuilder::new().build();
850    /// if let Some(plugin) = registry.get("my_plugin") {
851    ///     println!("找到插件: {}", plugin.name());
852    /// }
853    /// ```
854    pub fn get(&self, name: &str) -> Option<&Arc<dyn Plugin>> {
855        let name = normalize_plugin_lookup_name(name)?;
856        self.plugins.get(name)
857    }
858
859    /// 获取所有已注册插件(返回缓存的排序结果引用)
860    ///
861    /// 直接返回构建时缓存的拓扑排序结果,无需重新计算。
862    ///
863    /// # 返回
864    /// - 按依赖关系排序的插件切片引用
865    ///
866    /// # 示例
867    ///
868    /// ```rust,ignore
869    /// use yang_base::plugin::PluginManagerBuilder;
870    ///
871    /// let registry = PluginManagerBuilder::new().build();
872    /// let plugins = registry.get_all();
873    /// for plugin in plugins {
874    ///     println!("插件: {} v{}", plugin.name(), plugin.version());
875    /// }
876    /// ```
877    pub fn get_all(&self) -> &[Arc<dyn Plugin>] {
878        &self.sorted_plugins
879    }
880
881    /// 获取插件配置
882    ///
883    /// # 参数
884    /// - `name`: 插件名称
885    ///
886    /// # 返回
887    /// - `Some(&JsonValue)`: 插件配置
888    /// - `None`: 配置不存在
889    pub fn get_config(&self, name: &str) -> Option<&JsonValue> {
890        let name = normalize_plugin_lookup_name(name)?;
891        self.configs.get(name)
892    }
893
894    /// 关闭所有插件(逆序关闭)
895    ///
896    /// 按照拓扑排序的逆序调用每个插件的 `on_shutdown` 方法,
897    /// 确保依赖其他插件的插件先被关闭。
898    ///
899    /// # 返回
900    /// - `Ok(())`: 所有插件关闭成功
901    /// - `Err(BaseError)`: 某个插件关闭失败
902    ///
903    /// # 示例
904    ///
905    /// ```rust,ignore
906    /// use yang_base::plugin::PluginManagerBuilder;
907    ///
908    /// let registry = PluginManagerBuilder::new().build();
909    /// // ... 使用插件 ...
910    /// registry.shutdown().await?;
911    /// ```
912    pub async fn shutdown(&self) -> Result<(), BaseError> {
913        // 逆序遍历缓存的排序结果,确保依赖插件最后关闭
914        let mut errors: Vec<(String, PluginError)> = Vec::new();
915
916        for plugin in self.sorted_plugins.iter().rev() {
917            let name = plugin.name();
918            if let Err(e) = plugin.on_shutdown().await {
919                log::error!("插件 {} 关闭失败: {}", name, e);
920                errors.push((name.to_string(), e));
921            } else {
922                log::info!("插件已关闭: {}", name);
923            }
924        }
925
926        if let Some((plugin, source)) = errors.into_iter().next() {
927            Err(BaseError::PluginLifecycleFailed {
928                plugin,
929                stage: PluginLifecycleStage::Shutdown,
930                source,
931            })
932        } else {
933            Ok(())
934        }
935    }
936
937    /// 计算拓扑排序(私有方法,构建时调用一次)
938    ///
939    /// 使用 Kahn 算法对插件进行拓扑排序,确保依赖插件先于当前插件出现。
940    /// 当排序后的节点数小于插件总数时,说明存在循环依赖。
941    ///
942    /// # 参数
943    /// - `plugins`: 插件 HashMap 引用
944    ///
945    /// # 返回
946    /// - `Ok(Vec<Arc<dyn Plugin>>)`: 按依赖关系排序的插件列表
947    /// - `Err(BaseError::PluginCircularDependency)`: 存在循环依赖,错误信息含未排序节点
948    fn compute_topological_sort(
949        plugins: &HashMap<String, Arc<dyn Plugin>>,
950    ) -> Result<Vec<Arc<dyn Plugin>>, BaseError> {
951        // 构建入度表和邻接图
952        let mut in_degree: HashMap<String, usize> = HashMap::new();
953        let mut graph: HashMap<String, Vec<String>> = HashMap::new();
954
955        for (name, plugin) in plugins {
956            let name = name.clone();
957            in_degree.entry(name.clone()).or_insert(0);
958
959            for dep in plugin.dependencies() {
960                let dep = normalize_plugin_name(dep)?;
961                // dep -> name 的边:dep 是 name 的依赖,dep 先执行
962                graph.entry(dep.to_string()).or_default().push(name.clone());
963                *in_degree.entry(name.clone()).or_insert(0) += 1;
964            }
965        }
966
967        // Kahn 算法:从入度为 0 的节点开始
968        let mut queue: Vec<String> = in_degree
969            .iter()
970            .filter(|(_, &degree)| degree == 0)
971            .map(|(name, _)| name.clone())
972            .collect();
973
974        let mut sorted_names: Vec<String> = Vec::new();
975
976        while let Some(node) = queue.pop() {
977            sorted_names.push(node.clone());
978
979            if let Some(neighbors) = graph.get(&node) {
980                for neighbor in neighbors {
981                    if let Some(degree) = in_degree.get_mut(neighbor) {
982                        *degree -= 1;
983                        if *degree == 0 {
984                            queue.push(neighbor.clone());
985                        }
986                    }
987                }
988            }
989        }
990
991        // 检测循环依赖:若排序后的节点数小于插件总数,说明存在循环
992        if sorted_names.len() < plugins.len() {
993            // 找出未被排序的节点(即循环中的插件)
994            let unsorted: Vec<String> = plugins
995                .keys()
996                .filter(|name| !sorted_names.contains(name))
997                .cloned()
998                .collect();
999            let unsorted_str = unsorted.join(", ");
1000            return Err(BaseError::PluginCircularDependency(format!(
1001                "循环依赖涉及的插件: {}",
1002                unsorted_str
1003            )));
1004        }
1005
1006        // 按排序顺序构建插件列表。这里使用注册阶段规范化后的 HashMap key,
1007        // 避免插件对象 `name()` 返回带边界空格时与内部索引不一致。
1008        let sorted_plugins: Vec<Arc<dyn Plugin>> = sorted_names
1009            .iter()
1010            .filter_map(|name| plugins.get(name).cloned())
1011            .collect();
1012
1013        Ok(sorted_plugins)
1014    }
1015}
1016
1017#[cfg(test)]
1018mod tests {
1019    use super::*;
1020
1021    /// 测试用插件:无依赖
1022    struct PluginA;
1023
1024    #[async_trait]
1025    impl Plugin for PluginA {
1026        fn name(&self) -> &str {
1027            "plugin_a"
1028        }
1029    }
1030
1031    /// 测试用插件:依赖 plugin_a
1032    struct PluginB;
1033
1034    #[async_trait]
1035    impl Plugin for PluginB {
1036        fn name(&self) -> &str {
1037            "plugin_b"
1038        }
1039
1040        fn dependencies(&self) -> &[&str] {
1041            &["plugin_a"]
1042        }
1043    }
1044
1045    /// 测试用插件:依赖 plugin_b
1046    struct PluginC;
1047
1048    #[async_trait]
1049    impl Plugin for PluginC {
1050        fn name(&self) -> &str {
1051            "plugin_c"
1052        }
1053
1054        fn dependencies(&self) -> &[&str] {
1055            &["plugin_b"]
1056        }
1057    }
1058
1059    /// 测试用插件:注册时返回错误
1060    struct PluginFailing;
1061
1062    #[async_trait]
1063    impl Plugin for PluginFailing {
1064        fn name(&self) -> &str {
1065            "plugin_failing"
1066        }
1067
1068        async fn on_register(&self) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
1069            Err("注册失败".into())
1070        }
1071    }
1072
1073    /// 测试用插件:名称带边界空格
1074    struct PluginASpaced;
1075
1076    #[async_trait]
1077    impl Plugin for PluginASpaced {
1078        fn name(&self) -> &str {
1079            " plugin_a "
1080        }
1081    }
1082
1083    /// 测试用插件:空白名称
1084    struct PluginBlankName;
1085
1086    #[async_trait]
1087    impl Plugin for PluginBlankName {
1088        fn name(&self) -> &str {
1089            "   "
1090        }
1091    }
1092
1093    /// 验证需求: P4 - PluginRegistry::get(name) 的结果与构建前注册的插件一一对应
1094    #[tokio::test]
1095    async fn test_registry_get_matches_registered_plugins() {
1096        let mut builder = PluginManagerBuilder::new();
1097        builder.register(PluginA).await.unwrap();
1098        builder.register(PluginB).await.unwrap();
1099        builder.register(PluginC).await.unwrap();
1100
1101        let registry = builder.build().expect("构建注册表应成功");
1102
1103        // 验证每个注册的插件都能通过 get 找到,且名称一致
1104        let plugin_a = registry.get("plugin_a");
1105        assert!(plugin_a.is_some(), "应能找到 plugin_a");
1106        assert_eq!(plugin_a.unwrap().name(), "plugin_a");
1107
1108        let plugin_b = registry.get("plugin_b");
1109        assert!(plugin_b.is_some(), "应能找到 plugin_b");
1110        assert_eq!(plugin_b.unwrap().name(), "plugin_b");
1111
1112        let plugin_c = registry.get("plugin_c");
1113        assert!(plugin_c.is_some(), "应能找到 plugin_c");
1114        assert_eq!(plugin_c.unwrap().name(), "plugin_c");
1115
1116        // 验证不存在的插件返回 None
1117        assert!(
1118            registry.get("nonexistent").is_none(),
1119            "不存在的插件应返回 None"
1120        );
1121    }
1122
1123    /// 验证需求: P4 - get_all() 返回缓存结果,多次调用结果一致
1124    #[tokio::test]
1125    async fn test_registry_get_all_returns_cached_result() {
1126        let mut builder = PluginManagerBuilder::new();
1127        builder.register(PluginA).await.unwrap();
1128        builder.register(PluginB).await.unwrap();
1129        builder.register(PluginC).await.unwrap();
1130
1131        let registry = builder.build().expect("构建注册表应成功");
1132
1133        // 多次调用 get_all() 应返回相同的结果(缓存)
1134        let all_first = registry.get_all();
1135        let all_second = registry.get_all();
1136
1137        // 验证两次调用返回相同数量的插件
1138        assert_eq!(
1139            all_first.len(),
1140            all_second.len(),
1141            "多次调用 get_all() 应返回相同数量的插件"
1142        );
1143        assert_eq!(all_first.len(), 3, "应有 3 个插件");
1144
1145        // 验证两次调用返回相同的插件名称(顺序一致)
1146        let names_first: Vec<&str> = all_first.iter().map(|p| p.name()).collect();
1147        let names_second: Vec<&str> = all_second.iter().map(|p| p.name()).collect();
1148        assert_eq!(
1149            names_first, names_second,
1150            "多次调用 get_all() 应返回相同顺序的插件"
1151        );
1152    }
1153
1154    /// 验证需求: P4 - get_all() 返回的插件按拓扑顺序排列(依赖先于被依赖者)
1155    #[tokio::test]
1156    async fn test_registry_get_all_topological_order() {
1157        let mut builder = PluginManagerBuilder::new();
1158        // 故意以非依赖顺序注册
1159        builder.register(PluginC).await.unwrap();
1160        builder.register(PluginA).await.unwrap();
1161        builder.register(PluginB).await.unwrap();
1162
1163        let registry = builder.build().expect("构建注册表应成功");
1164        let all_plugins = registry.get_all();
1165
1166        // 找到各插件在排序结果中的位置
1167        let pos_a = all_plugins.iter().position(|p| p.name() == "plugin_a");
1168        let pos_b = all_plugins.iter().position(|p| p.name() == "plugin_b");
1169        let pos_c = all_plugins.iter().position(|p| p.name() == "plugin_c");
1170
1171        assert!(
1172            pos_a.is_some() && pos_b.is_some() && pos_c.is_some(),
1173            "所有插件应在排序结果中"
1174        );
1175
1176        // 验证拓扑顺序:plugin_a 在 plugin_b 之前,plugin_b 在 plugin_c 之前
1177        assert!(
1178            pos_a.unwrap() < pos_b.unwrap(),
1179            "plugin_a(被依赖)应在 plugin_b 之前"
1180        );
1181        assert!(
1182            pos_b.unwrap() < pos_c.unwrap(),
1183            "plugin_b(被依赖)应在 plugin_c 之前"
1184        );
1185    }
1186
1187    /// 验证需求: 9.3 - 注册重名插件应返回错误
1188    #[tokio::test]
1189    async fn test_builder_register_duplicate_returns_error() {
1190        let mut builder = PluginManagerBuilder::new();
1191        builder.register(PluginA).await.unwrap();
1192
1193        // 再次注册同名插件应返回错误
1194        struct PluginADuplicate;
1195        #[async_trait]
1196        impl Plugin for PluginADuplicate {
1197            fn name(&self) -> &str {
1198                "plugin_a"
1199            }
1200        }
1201
1202        let result = builder.register(PluginADuplicate).await;
1203        assert!(
1204            matches!(result, Err(BaseError::PluginAlreadyRegistered(_))),
1205            "注册重名插件应返回 PluginAlreadyRegistered 错误"
1206        );
1207    }
1208
1209    #[tokio::test]
1210    async fn test_builder_register_trims_plugin_names() {
1211        let mut builder = PluginManagerBuilder::new();
1212        builder
1213            .register(PluginASpaced)
1214            .await
1215            .expect("插件名应在构建期注册时 trim");
1216
1217        let result = builder.register(PluginA).await;
1218        assert!(
1219            matches!(result, Err(BaseError::PluginAlreadyRegistered(name)) if name == "plugin_a"),
1220            "trim 后的重复插件名应返回 PluginAlreadyRegistered"
1221        );
1222
1223        let registry = builder.build().expect("构建注册表应成功");
1224        assert!(registry.get("plugin_a").is_some());
1225        assert!(registry.get(" plugin_a ").is_some());
1226    }
1227
1228    #[tokio::test]
1229    async fn test_plugin_manager_register_trims_plugin_names_and_config_keys() {
1230        let manager = PluginManager::new();
1231        manager
1232            .register(PluginASpaced)
1233            .await
1234            .expect("插件名应在运行期注册时 trim");
1235
1236        assert!(manager.get("plugin_a").await.is_some());
1237        assert!(manager.get(" plugin_a ").await.is_some());
1238
1239        let result = manager.register(PluginA).await;
1240        assert!(
1241            matches!(result, Err(BaseError::PluginAlreadyRegistered(name)) if name == "plugin_a"),
1242            "trim 后的重复插件名应返回 PluginAlreadyRegistered"
1243        );
1244
1245        let config = serde_json::json!({"enabled": true});
1246        manager
1247            .load_config(" plugin_a ", config.clone())
1248            .await
1249            .expect("配置加载应使用 trim 后插件名");
1250
1251        assert_eq!(manager.get_config("plugin_a").await, Some(config.clone()));
1252        assert_eq!(manager.get_config(" plugin_a ").await, Some(config));
1253    }
1254
1255    #[tokio::test]
1256    async fn test_register_rejects_blank_plugin_names() {
1257        let mut builder = PluginManagerBuilder::new();
1258        let builder_result = builder.register(PluginBlankName).await;
1259        assert!(
1260            matches!(builder_result, Err(BaseError::PluginRegisterFailed(name, message)) if name == "<empty>" && message.contains("插件名称不能为空")),
1261            "构建期注册空白插件名应返回 PluginRegisterFailed"
1262        );
1263
1264        let manager = PluginManager::new();
1265        let manager_result = manager.register(PluginBlankName).await;
1266        assert!(
1267            matches!(manager_result, Err(BaseError::PluginRegisterFailed(name, message)) if name == "<empty>" && message.contains("插件名称不能为空")),
1268            "运行期注册空白插件名应返回 PluginRegisterFailed"
1269        );
1270    }
1271
1272    /// 验证需求: 9.3 - 注册回调失败时应返回错误
1273    #[tokio::test]
1274    async fn test_builder_register_callback_failure_returns_error() {
1275        use std::error::Error;
1276
1277        let mut builder = PluginManagerBuilder::new();
1278        let result = builder.register(PluginFailing).await;
1279        let error = match result {
1280            Err(error) => error,
1281            Ok(()) => panic!("注册回调失败时不应成功"),
1282        };
1283        assert!(matches!(
1284            &error,
1285            BaseError::PluginLifecycleFailed {
1286                plugin,
1287                stage: PluginLifecycleStage::Register,
1288                ..
1289            } if plugin == "plugin_failing"
1290        ));
1291        assert_eq!(error.code(), 100003);
1292        assert!(error.source().is_some(), "注册回调底层错误链不得丢失");
1293    }
1294
1295    /// 验证需求: 9.4 - build() 消费构建器并返回 PluginRegistry
1296    #[tokio::test]
1297    async fn test_builder_build_produces_registry() {
1298        let mut builder = PluginManagerBuilder::new();
1299        builder.register(PluginA).await.unwrap();
1300
1301        let registry = builder.build().expect("构建注册表应成功");
1302
1303        // 验证 registry 包含注册的插件
1304        assert!(
1305            registry.get("plugin_a").is_some(),
1306            "registry 应包含已注册的插件"
1307        );
1308        assert_eq!(registry.get_all().len(), 1, "registry 应有 1 个插件");
1309    }
1310
1311    /// 验证需求: 9.7 - get() 返回正确的插件引用
1312    #[tokio::test]
1313    async fn test_registry_get_returns_correct_plugin() {
1314        let mut builder = PluginManagerBuilder::new();
1315        builder.register(PluginA).await.unwrap();
1316        builder.register(PluginB).await.unwrap();
1317
1318        let registry = builder.build().expect("构建注册表应成功");
1319
1320        // 验证 get() 返回正确的插件
1321        let plugin = registry.get("plugin_a").unwrap();
1322        assert_eq!(plugin.name(), "plugin_a", "get() 应返回正确名称的插件");
1323        assert_eq!(plugin.version(), "0.1.0", "get() 应返回正确版本的插件");
1324    }
1325
1326    /// 验证需求: 9.9 - shutdown() 逆序关闭所有插件
1327    #[tokio::test]
1328    async fn test_registry_shutdown_succeeds() {
1329        let mut builder = PluginManagerBuilder::new();
1330        builder.register(PluginA).await.unwrap();
1331        builder.register(PluginB).await.unwrap();
1332
1333        let registry = builder.build().expect("构建注册表应成功");
1334
1335        // 验证 shutdown() 成功执行
1336        let result = registry.shutdown().await;
1337        assert!(result.is_ok(), "shutdown() 应成功执行");
1338    }
1339
1340    /// 验证需求: 9.9/TEST-6 - shutdown() 按逆拓扑顺序关闭(依赖者先关)
1341    ///
1342    /// 插件依赖关系: PluginA ← PluginB ← PluginC
1343    /// 拓扑排序结果: [plugin_a, plugin_b, plugin_c](依赖在前)
1344    /// 关闭顺序应为逆序: [plugin_c, plugin_b, plugin_a](依赖者先关)
1345    #[tokio::test]
1346    async fn test_shutdown_calls_in_reverse_topological_order() {
1347        use std::sync::Mutex;
1348
1349        static SHUTDOWN_ORDER: Mutex<Vec<String>> = Mutex::new(Vec::new());
1350        SHUTDOWN_ORDER.lock().unwrap().clear();
1351
1352        /// 无依赖插件 A
1353        struct PluginA;
1354        #[async_trait]
1355        impl Plugin for PluginA {
1356            fn name(&self) -> &str {
1357                "plugin_a"
1358            }
1359            async fn on_shutdown(&self) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
1360                SHUTDOWN_ORDER.lock().unwrap().push("plugin_a".to_string());
1361                Ok(())
1362            }
1363        }
1364
1365        /// 依赖 plugin_a 的插件 B
1366        struct PluginB;
1367        #[async_trait]
1368        impl Plugin for PluginB {
1369            fn name(&self) -> &str {
1370                "plugin_b"
1371            }
1372            fn dependencies(&self) -> &[&str] {
1373                &["plugin_a"]
1374            }
1375            async fn on_shutdown(&self) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
1376                SHUTDOWN_ORDER.lock().unwrap().push("plugin_b".to_string());
1377                Ok(())
1378            }
1379        }
1380
1381        /// 依赖 plugin_b 的插件 C(最顶层依赖者)
1382        struct PluginC;
1383        #[async_trait]
1384        impl Plugin for PluginC {
1385            fn name(&self) -> &str {
1386                "plugin_c"
1387            }
1388            fn dependencies(&self) -> &[&str] {
1389                &["plugin_b"]
1390            }
1391            async fn on_shutdown(&self) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
1392                SHUTDOWN_ORDER.lock().unwrap().push("plugin_c".to_string());
1393                Ok(())
1394            }
1395        }
1396
1397        let mut builder = PluginManagerBuilder::new();
1398        builder.register(PluginA).await.unwrap();
1399        builder.register(PluginB).await.unwrap();
1400        builder.register(PluginC).await.unwrap();
1401
1402        let registry = builder.build().expect("构建注册表应成功");
1403        let result = registry.shutdown().await;
1404        assert!(result.is_ok(), "shutdown() 应成功执行");
1405
1406        let order = SHUTDOWN_ORDER.lock().unwrap().clone();
1407        assert_eq!(
1408            order,
1409            vec!["plugin_c", "plugin_b", "plugin_a"],
1410            "shutdown 应按逆拓扑顺序关闭:C (依赖B) → B (依赖A) → A"
1411        );
1412    }
1413
1414    /// 验证需求: 9.1/9.2 - PluginManagerBuilder::new() 创建空构建器
1415    #[tokio::test]
1416    async fn test_builder_new_creates_empty_builder() {
1417        let builder = PluginManagerBuilder::new();
1418        let registry = builder.build().expect("空构建器构建应成功");
1419
1420        // 空构建器构建的 registry 应为空
1421        assert_eq!(registry.get_all().len(), 0, "空构建器应生成空 registry");
1422        assert!(
1423            registry.get("any").is_none(),
1424            "空 registry 不应包含任何插件"
1425        );
1426    }
1427
1428    /// 验证需求: 20.1, 20.2, 20.3 - build() 检查依赖完整性
1429    #[tokio::test]
1430    async fn test_build_detects_missing_dependency() {
1431        let mut builder = PluginManagerBuilder::new();
1432        // 只注册 plugin_b,但 plugin_b 依赖 plugin_a(未注册)
1433        builder
1434            .register(PluginB)
1435            .await
1436            .expect("注册 plugin_b 应成功");
1437
1438        let result = builder.build();
1439        assert!(
1440            matches!(result, Err(BaseError::PluginDependencyMissing(_, _))),
1441            "依赖未注册时应返回 PluginDependencyMissing 错误"
1442        );
1443
1444        // 验证错误信息包含插件名和依赖名
1445        if let Err(BaseError::PluginDependencyMissing(plugin, dep)) = result {
1446            assert_eq!(plugin, "plugin_b", "错误应指向 plugin_b");
1447            assert_eq!(dep, "plugin_a", "缺失的依赖应是 plugin_a");
1448        }
1449    }
1450
1451    /// 验证需求: 19.1, 19.2, 19.3, 19.4 - build() 检测循环依赖
1452    #[tokio::test]
1453    async fn test_build_detects_circular_dependency() {
1454        // 定义循环依赖的插件:X 依赖 Y,Y 依赖 X
1455        struct PluginX;
1456        #[async_trait]
1457        impl Plugin for PluginX {
1458            fn name(&self) -> &str {
1459                "plugin_x"
1460            }
1461            fn dependencies(&self) -> &[&str] {
1462                &["plugin_y"]
1463            }
1464        }
1465
1466        struct PluginY;
1467        #[async_trait]
1468        impl Plugin for PluginY {
1469            fn name(&self) -> &str {
1470                "plugin_y"
1471            }
1472            fn dependencies(&self) -> &[&str] {
1473                &["plugin_x"]
1474            }
1475        }
1476
1477        let mut builder = PluginManagerBuilder::new();
1478        builder
1479            .register(PluginX)
1480            .await
1481            .expect("注册 plugin_x 应成功");
1482        builder
1483            .register(PluginY)
1484            .await
1485            .expect("注册 plugin_y 应成功");
1486
1487        let result = builder.build();
1488        assert!(
1489            matches!(result, Err(BaseError::PluginCircularDependency(_))),
1490            "循环依赖时应返回 PluginCircularDependency 错误"
1491        );
1492
1493        // 验证错误信息包含未排序节点
1494        if let Err(BaseError::PluginCircularDependency(msg)) = result {
1495            assert!(
1496                msg.contains("plugin_x") || msg.contains("plugin_y"),
1497                "错误信息应包含循环中的插件名称"
1498            );
1499        }
1500    }
1501
1502    /// 验证需求: 7.1, 7.2, 7.3, 7.4 - validate_config 集成 jsonschema
1503    #[cfg(feature = "plugin-schema")]
1504    #[tokio::test]
1505    async fn test_validate_config_with_schema() {
1506        use serde_json::json;
1507
1508        // 定义带 Schema 的插件
1509        struct SchemaPlugin;
1510        #[async_trait]
1511        impl Plugin for SchemaPlugin {
1512            fn name(&self) -> &str {
1513                "schema_plugin"
1514            }
1515            fn config_schema(&self) -> Option<JsonValue> {
1516                Some(json!({
1517                    "type": "object",
1518                    "properties": {
1519                        "host": {"type": "string"},
1520                        "port": {"type": "integer"}
1521                    },
1522                    "required": ["host", "port"]
1523                }))
1524            }
1525        }
1526
1527        let manager = PluginManager::new();
1528        manager.register(SchemaPlugin).await.expect("注册应成功");
1529
1530        // 合法配置应通过验证
1531        let valid_config = json!({"host": "localhost", "port": 3306});
1532        let result = manager.load_config("schema_plugin", valid_config).await;
1533        assert!(result.is_ok(), "合法配置应通过验证");
1534    }
1535
1536    /// 验证需求: 7.1, 7.2 - 配置不符合 Schema 时返回错误
1537    #[cfg(feature = "plugin-schema")]
1538    #[tokio::test]
1539    async fn test_validate_config_invalid_returns_error() {
1540        use serde_json::json;
1541
1542        // 定义带 Schema 的插件
1543        struct StrictPlugin;
1544        #[async_trait]
1545        impl Plugin for StrictPlugin {
1546            fn name(&self) -> &str {
1547                "strict_plugin"
1548            }
1549            fn config_schema(&self) -> Option<JsonValue> {
1550                Some(json!({
1551                    "type": "object",
1552                    "properties": {
1553                        "port": {"type": "integer"}
1554                    },
1555                    "required": ["port"]
1556                }))
1557            }
1558        }
1559
1560        let manager = PluginManager::new();
1561        manager.register(StrictPlugin).await.expect("注册应成功");
1562
1563        // 配置缺少必填字段应返回错误
1564        let invalid_config = json!({"host": "localhost"});
1565        let result = manager.load_config("strict_plugin", invalid_config).await;
1566        assert!(
1567            matches!(result, Err(BaseError::PluginConfigInvalid(_, _))),
1568            "配置不符合 Schema 应返回 PluginConfigInvalid 错误"
1569        );
1570    }
1571
1572    // ==================== C6 并发回归:register TOCTOU ====================
1573
1574    /// 并发注册同名插件(TOCTOU 回归网,对应 I11)。
1575    ///
1576    /// `register` 的「read 检查 contains_key → on_register → write insert」是分离的
1577    /// 三段锁,存在 check-then-insert 竞态窗口:多个并发注册同名插件时,可能都越过
1578    /// 检查、最终多次 insert(后写覆盖)。本测试**锁定当前契约**:
1579    /// - 进程不 panic、不死锁,map 不被破坏
1580    /// - 并发结束后插件确实可查到且名称正确
1581    /// - 至少有一个 register 调用返回 Ok(拿到锁的胜出者)
1582    ///
1583    /// I11 修复(改单把 write 锁 check-and-insert)后,应能进一步断言「恰好一个
1584    /// Ok、其余 PluginAlreadyRegistered」——届时收紧本测试。
1585    #[tokio::test(flavor = "multi_thread", worker_threads = 4)]
1586    async fn concurrent_same_name_register_keeps_map_consistent() {
1587        struct DupPlugin;
1588        #[async_trait]
1589        impl Plugin for DupPlugin {
1590            fn name(&self) -> &str {
1591                "dup_plugin"
1592            }
1593        }
1594
1595        let manager = Arc::new(PluginManager::new());
1596
1597        let mut handles = Vec::new();
1598        for _ in 0..16 {
1599            let m = Arc::clone(&manager);
1600            handles.push(tokio::spawn(async move { m.register(DupPlugin).await }));
1601        }
1602
1603        let mut ok_count = 0usize;
1604        for h in handles {
1605            // 任务本身不应 panic
1606            let res = h.await.expect("注册任务不应 panic");
1607            if res.is_ok() {
1608                ok_count += 1;
1609            }
1610        }
1611
1612        // 当前契约:至少一个成功(窗口竞态下可能 >1)
1613        assert!(ok_count >= 1, "并发同名注册应至少有一个成功");
1614
1615        // map 未被破坏:插件可查到且名称正确
1616        let got = manager.get("dup_plugin").await;
1617        assert!(got.is_some(), "并发注册后应能查到 dup_plugin");
1618        assert_eq!(got.unwrap().name(), "dup_plugin");
1619    }
1620
1621    /// 并发注册不同名插件:全部成功,全部可查到,无丢失。
1622    #[tokio::test(flavor = "multi_thread", worker_threads = 4)]
1623    async fn concurrent_distinct_register_no_loss() {
1624        // 用宏生成固定数量的不同名插件,避免运行时动态 name 生命周期问题
1625        macro_rules! make_plugin {
1626            ($ty:ident, $name:literal) => {
1627                struct $ty;
1628                #[async_trait]
1629                impl Plugin for $ty {
1630                    fn name(&self) -> &str {
1631                        $name
1632                    }
1633                }
1634            };
1635        }
1636        make_plugin!(P0, "cn_p0");
1637        make_plugin!(P1, "cn_p1");
1638        make_plugin!(P2, "cn_p2");
1639        make_plugin!(P3, "cn_p3");
1640        make_plugin!(P4, "cn_p4");
1641        make_plugin!(P5, "cn_p5");
1642        make_plugin!(P6, "cn_p6");
1643        make_plugin!(P7, "cn_p7");
1644
1645        let manager = Arc::new(PluginManager::new());
1646        let m = Arc::clone(&manager);
1647
1648        // 并发注册 8 个不同名插件
1649        let (r0, r1, r2, r3, r4, r5, r6, r7) = tokio::join!(
1650            {
1651                let m = Arc::clone(&m);
1652                async move { m.register(P0).await }
1653            },
1654            {
1655                let m = Arc::clone(&m);
1656                async move { m.register(P1).await }
1657            },
1658            {
1659                let m = Arc::clone(&m);
1660                async move { m.register(P2).await }
1661            },
1662            {
1663                let m = Arc::clone(&m);
1664                async move { m.register(P3).await }
1665            },
1666            {
1667                let m = Arc::clone(&m);
1668                async move { m.register(P4).await }
1669            },
1670            {
1671                let m = Arc::clone(&m);
1672                async move { m.register(P5).await }
1673            },
1674            {
1675                let m = Arc::clone(&m);
1676                async move { m.register(P6).await }
1677            },
1678            {
1679                let m = Arc::clone(&m);
1680                async move { m.register(P7).await }
1681            },
1682        );
1683        for r in [r0, r1, r2, r3, r4, r5, r6, r7] {
1684            r.expect("不同名插件注册应全部成功");
1685        }
1686
1687        for i in 0..8 {
1688            let name = format!("cn_p{}", i);
1689            assert!(
1690                manager.get(&name).await.is_some(),
1691                "{} 应已注册且可查到",
1692                name
1693            );
1694        }
1695    }
1696}