Skip to main content

yang_base/plugin/
manager.rs

1//! 插件管理器:运行期可变的插件注册、查找、配置加载与关闭。
2
3use serde_json::Value as JsonValue;
4use std::collections::HashMap;
5use std::sync::Arc;
6use tokio::sync::RwLock;
7
8use super::traits::{Plugin, PluginError, PluginLifecycleStage};
9use super::{normalize_plugin_lookup_name, normalize_plugin_name};
10use crate::error::BaseError;
11
12/// 插件管理器
13///
14/// 负责插件的注册、查找和生命周期管理
15///
16/// # 示例
17///
18/// ```rust,ignore
19/// use yang_base::plugin::{Plugin, PluginManager};
20///
21/// #[tokio::main]
22/// async fn main() -> Result<(), Box<dyn std::error::Error>> {
23///     let manager = PluginManager::new();
24///     
25///     // 注册插件
26///     manager.register(MyPlugin).await?;
27///     
28///     // 查找插件
29///     if let Some(plugin) = manager.get("my_plugin").await {
30///         println!("找到插件: {}", plugin.name());
31///     }
32///     
33///     // 获取所有插件(按依赖顺序)
34///     let plugins = manager.get_all().await;
35///     
36///     // 关闭所有插件
37///     manager.shutdown().await?;
38///     
39///     Ok(())
40/// }
41/// ```
42pub struct PluginManager {
43    /// 已注册的插件
44    /// Key: 插件名称, Value: 插件实例
45    plugins: Arc<RwLock<HashMap<String, Arc<dyn Plugin>>>>,
46
47    /// 插件配置
48    /// Key: 插件名称, Value: 配置 JSON
49    configs: Arc<RwLock<HashMap<String, JsonValue>>>,
50}
51
52impl PluginManager {
53    /// 创建新的插件管理器
54    ///
55    /// # 返回
56    /// - 新的 PluginManager 实例
57    ///
58    /// # 示例
59    ///
60    /// ```rust
61    /// use yang_base::plugin::PluginManager;
62    ///
63    /// let manager = PluginManager::new();
64    /// ```
65    pub fn new() -> Self {
66        Self {
67            plugins: Arc::new(RwLock::new(HashMap::new())),
68            configs: Arc::new(RwLock::new(HashMap::new())),
69        }
70    }
71
72    /// 注册插件
73    ///
74    /// # 参数
75    /// - plugin: 插件实例
76    ///
77    /// # 返回
78    /// - Ok(()): 注册成功
79    /// - Err(BaseError): 注册失败(如插件名称重复)
80    ///
81    /// # 示例
82    ///
83    /// ```rust,ignore
84    /// use yang_base::plugin::{Plugin, PluginManager};
85    ///
86    /// let manager = PluginManager::new();
87    /// manager.register(MyPlugin).await?;
88    /// ```
89    pub async fn register<P: Plugin + 'static>(&self, plugin: P) -> Result<(), BaseError> {
90        let name = normalize_plugin_name(plugin.name())?.to_string();
91        let plugin = Arc::new(plugin);
92
93        // 第一阶段:读锁检查(快速路径,避免持写锁跨 await)
94        {
95            let plugins = self.plugins.read().await;
96            if plugins.contains_key(&name) {
97                return Err(BaseError::PluginAlreadyRegistered(name));
98            }
99        } // 尽早释放读锁
100
101        // 调用注册回调(不持任何锁)
102        plugin
103            .on_register()
104            .await
105            .map_err(|source| BaseError::PluginLifecycleFailed {
106                plugin: name.clone(),
107                stage: PluginLifecycleStage::Register,
108                source,
109            })?;
110
111        // 第二阶段:写锁 + 二次校验(防止 TOCTOU 竞态)
112        {
113            let mut plugins = self.plugins.write().await;
114            if plugins.contains_key(&name) {
115                return Err(BaseError::PluginAlreadyRegistered(name));
116            }
117            plugins.insert(name.clone(), plugin);
118        }
119
120        log::info!("插件已注册: {}", name);
121        Ok(())
122    }
123
124    /// 查找插件
125    ///
126    /// # 参数
127    /// - name: 插件名称
128    ///
129    /// # 返回
130    /// - `Some(Arc<dyn Plugin>)`: 找到插件
131    /// - None: 插件不存在
132    ///
133    /// # 示例
134    ///
135    /// ```rust,ignore
136    /// use yang_base::plugin::PluginManager;
137    ///
138    /// let manager = PluginManager::new();
139    /// if let Some(plugin) = manager.get("my_plugin").await {
140    ///     println!("找到插件: {}", plugin.name());
141    /// }
142    /// ```
143    pub async fn get(&self, name: &str) -> Option<Arc<dyn Plugin>> {
144        let name = normalize_plugin_lookup_name(name)?;
145        let plugins = self.plugins.read().await;
146        plugins.get(name).cloned()
147    }
148
149    /// 获取所有已注册插件
150    ///
151    /// # 返回
152    /// - 插件列表(按依赖关系排序)
153    ///
154    /// # 示例
155    ///
156    /// ```rust,ignore
157    /// use yang_base::plugin::PluginManager;
158    ///
159    /// let manager = PluginManager::new();
160    /// let plugins = manager.get_all().await;
161    /// for plugin in plugins {
162    ///     println!("插件: {} v{}", plugin.name(), plugin.version());
163    /// }
164    /// ```
165    pub async fn get_all(&self) -> Vec<Arc<dyn Plugin>> {
166        let plugins = self.plugins.read().await;
167        let mut plugin_list: Vec<(String, Arc<dyn Plugin>)> = plugins
168            .iter()
169            .map(|(k, v)| (k.clone(), v.clone()))
170            .collect();
171
172        // 按依赖关系排序(节点名使用注册时归一化后的 key,见 topological_sort)
173        self.topological_sort(&mut plugin_list);
174
175        plugin_list.into_iter().map(|(_, p)| p).collect()
176    }
177
178    /// 加载插件配置
179    ///
180    /// # 参数
181    /// - name: 插件名称
182    /// - config: 配置 JSON
183    ///
184    /// # 返回
185    /// - Ok(()): 加载成功
186    /// - Err(BaseError): 加载失败(如配置验证失败)
187    ///
188    /// # 示例
189    ///
190    /// ```rust,ignore
191    /// use yang_base::plugin::PluginManager;
192    /// use serde_json::json;
193    ///
194    /// let manager = PluginManager::new();
195    /// let config = json!({"key": "value"});
196    /// manager.load_config("my_plugin", config).await?;
197    /// ```
198    pub async fn load_config(&self, name: &str, config: JsonValue) -> Result<(), BaseError> {
199        let normalized_name = normalize_plugin_lookup_name(name)
200            .ok_or_else(|| BaseError::PluginNotFound(name.to_string()))?;
201
202        // 获取插件
203        let plugin = self
204            .get(normalized_name)
205            .await
206            .ok_or_else(|| BaseError::PluginNotFound(normalized_name.to_string()))?;
207
208        // 验证配置(插件未定义 config_schema 时跳过验证)
209        if let Some(schema) = plugin.config_schema() {
210            self.validate_config(normalized_name, &config, &schema)?;
211        }
212
213        // 存储配置
214        {
215            let mut configs = self.configs.write().await;
216            configs.insert(normalized_name.to_string(), config);
217        }
218
219        Ok(())
220    }
221
222    /// 获取插件配置
223    ///
224    /// # 参数
225    /// - name: 插件名称
226    ///
227    /// # 返回
228    /// - Some(JsonValue): 插件配置
229    /// - None: 配置不存在
230    ///
231    /// # 示例
232    ///
233    /// ```rust,ignore
234    /// use yang_base::plugin::PluginManager;
235    ///
236    /// let manager = PluginManager::new();
237    /// if let Some(config) = manager.get_config("my_plugin").await {
238    ///     println!("配置: {:?}", config);
239    /// }
240    /// ```
241    pub async fn get_config(&self, name: &str) -> Option<JsonValue> {
242        let name = normalize_plugin_lookup_name(name)?;
243        let configs = self.configs.read().await;
244        configs.get(name).cloned()
245    }
246
247    /// 拓扑排序(按依赖关系排序)
248    ///
249    /// # 参数
250    /// - plugins: `(注册 key, 插件)` 列表,key 为注册时经 `normalize_plugin_name` 归一化后的名称
251    ///
252    /// # 说明
253    /// 使用 Kahn 算法进行拓扑排序,确保依赖插件先于当前插件。
254    ///
255    /// 节点名一律使用注册 key、依赖名一律经 `normalize_plugin_name` 归一化后再建边,
256    /// 与 [`super::registry::PluginRegistry`] 的 `compute_topological_sort` 同口径:
257    /// 避免插件对象 `name()` 返回带边界空格时与内部 key 失配,造成断边或误报循环依赖。
258    fn topological_sort(&self, plugins: &mut Vec<(String, Arc<dyn Plugin>)>) {
259        // 构建依赖图
260        let mut in_degree: HashMap<String, usize> = HashMap::new();
261        let mut graph: HashMap<String, Vec<String>> = HashMap::new();
262
263        for (name, plugin) in plugins.iter() {
264            in_degree.entry(name.clone()).or_insert(0);
265
266            for dep in plugin.dependencies() {
267                // 与 registry 同口径:trim 后再建边
268                let Ok(dep) = normalize_plugin_name(dep) else {
269                    continue;
270                };
271                if !plugins.iter().any(|(n, _)| n == dep) {
272                    log::warn!("插件 {} 声明的依赖 {:?} 未注册,无法建立依赖边", name, dep);
273                }
274                graph.entry(dep.to_string()).or_default().push(name.clone());
275                *in_degree.entry(name.clone()).or_insert(0) += 1;
276            }
277        }
278
279        // Kahn 算法
280        let mut queue: Vec<String> = in_degree
281            .iter()
282            .filter(|(_, &degree)| degree == 0)
283            .map(|(name, _)| name.clone())
284            .collect();
285
286        let mut sorted: Vec<String> = Vec::new();
287
288        while let Some(node) = queue.pop() {
289            sorted.push(node.clone());
290
291            if let Some(neighbors) = graph.get(&node) {
292                for neighbor in neighbors {
293                    if let Some(degree) = in_degree.get_mut(neighbor) {
294                        *degree -= 1;
295                        if *degree == 0 {
296                            queue.push(neighbor.clone());
297                        }
298                    }
299                }
300            }
301        }
302
303        // 检测循环依赖或断边:Kahn 算法结束后,未被排序的节点降级到最后
304        if sorted.len() < plugins.len() {
305            let circular: Vec<String> = plugins
306                .iter()
307                .map(|(n, _)| n.clone())
308                .filter(|n| !sorted.contains(n))
309                .collect();
310            log::error!(
311                "插件依赖图无法排序(存在环或断边),以下插件降级到最后: {}",
312                circular.join(", ")
313            );
314            // 将无法排序的插件追加到排序末尾,保证所有插件都出现在结果中
315            sorted.extend(circular);
316        }
317
318        // 重新排序插件列表(比较器同样用归一化 key,避免二次失配)
319        plugins.sort_by_key(|(n, _)| sorted.iter().position(|s| s == n).unwrap_or(usize::MAX));
320    }
321
322    /// 验证配置
323    ///
324    /// 使用 jsonschema crate 对配置进行 JSON Schema 验证。
325    /// 未启用 `plugin-schema` feature 时跳过验证。
326    ///
327    /// # 参数
328    /// - `plugin_name`: 插件名称(用于错误信息)
329    /// - `config`: 配置 JSON
330    /// - `schema`: JSON Schema
331    ///
332    /// # 返回
333    /// - `Ok(())`: 验证通过
334    /// - `Err(BaseError::PluginConfigInvalid)`: 配置不符合 Schema
335    fn validate_config(
336        &self,
337        plugin_name: &str,
338        config: &JsonValue,
339        schema: &JsonValue,
340    ) -> Result<(), BaseError> {
341        // 使用 jsonschema crate 进行 JSON Schema 验证
342        #[cfg(feature = "plugin-schema")]
343        {
344            // 构建可复用的验证器
345            let validator = jsonschema::validator_for(schema).map_err(|e| {
346                BaseError::PluginConfigInvalid(
347                    plugin_name.to_string(),
348                    format!("Schema 编译失败: {}", e),
349                )
350            })?;
351
352            // 收集所有验证错误信息
353            let error_msgs: Vec<String> = validator
354                .iter_errors(config)
355                .map(|e| e.to_string())
356                .collect();
357
358            if !error_msgs.is_empty() {
359                return Err(BaseError::PluginConfigInvalid(
360                    plugin_name.to_string(),
361                    error_msgs.join("; "),
362                ));
363            }
364        }
365
366        // 未启用 plugin-schema feature 时,跳过验证直接返回成功
367        #[cfg(not(feature = "plugin-schema"))]
368        {
369            let _ = (plugin_name, config, schema);
370        }
371
372        Ok(())
373    }
374
375    /// 关闭所有插件
376    ///
377    /// 按照依赖关系的逆序调用插件的 on_shutdown 方法
378    ///
379    /// # 返回
380    /// - Ok(()): 关闭成功
381    /// - Err(BaseError): 关闭失败
382    ///
383    /// # 示例
384    ///
385    /// ```rust,ignore
386    /// use yang_base::plugin::PluginManager;
387    ///
388    /// let manager = PluginManager::new();
389    /// // ... 注册插件 ...
390    /// manager.shutdown().await?;
391    /// ```
392    pub async fn shutdown(&self) -> Result<(), BaseError> {
393        let mut plugins = self.get_all().await;
394        plugins.reverse(); // 逆序关闭
395
396        let mut errors: Vec<(String, PluginError)> = Vec::new();
397
398        for plugin in plugins {
399            let name = plugin.name();
400            if let Err(e) = plugin.on_shutdown().await {
401                log::error!("插件 {} 关闭失败: {}", name, e);
402                errors.push((name.to_string(), e));
403            } else {
404                log::info!("插件已关闭: {}", name);
405            }
406        }
407
408        if let Some((plugin, source)) = errors.into_iter().next() {
409            Err(BaseError::PluginLifecycleFailed {
410                plugin,
411                stage: PluginLifecycleStage::Shutdown,
412                source,
413            })
414        } else {
415            Ok(())
416        }
417    }
418}
419
420impl Default for PluginManager {
421    fn default() -> Self {
422        Self::new()
423    }
424}