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(|(_, °ree)| 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}