Skip to main content

wordval_core/
plugin.rs

1use crate::error::Result;
2use async_trait::async_trait;
3
4/// 插件生命周期:start/stop 对称
5///
6/// 极简设计——只定义 start / stop 两个生命周期方法。
7/// Rust 版增强:异步化 + 依赖声明 + 拓扑排序启动。
8///
9/// # 示例
10///
11/// ```ignore
12/// use wordval_core::plugin::Plugin;
13///
14/// struct DbPlugin { pool: PgPool }
15///
16/// #[async_trait]
17/// impl Plugin for DbPlugin {
18///     fn name(&self) -> &str { "pg" }
19///
20///     async fn start(&self) -> Result<()> {
21///         sqlx::query("SELECT 1").fetch_one(&self.pool).await?;
22///         Ok(())
23///     }
24///
25///     async fn stop(&self) -> Result<()> {
26///         self.pool.close().await;
27///         Ok(())
28///     }
29/// }
30/// ```
31#[async_trait]
32pub trait Plugin: Send + Sync {
33    /// 插件唯一名称(用于注册、日志、依赖解析)
34    fn name(&self) -> &str;
35
36    /// 启动插件:验证连接、初始化资源
37    ///
38    /// 在 `PluginManager::start_all()` 中被调用,按拓扑顺序依次执行。
39    /// 若返回 `Err`,则启动流程中止,后续插件不会执行。
40    async fn start(&self) -> Result<()>;
41
42    /// 关闭插件:释放资源
43    ///
44    /// 在 `PluginManager::stop_all()` 中被调用,按逆序执行。
45    /// 即使返回 `Err`,也会继续关闭其余插件(仅记录日志)。
46    async fn stop(&self) -> Result<()>;
47
48    /// 依赖的其他插件名称(用于拓扑排序,保证启动顺序)
49    ///
50    /// 默认返回空数组(无依赖)。
51    fn depends_on(&self) -> &[&str] {
52        &[]
53    }
54
55    /// 启动优先级(数值越小越先启动,默认 100)
56    ///
57    /// 在拓扑排序中,当多个插件的依赖都已满足时,优先级数值小的先启动。
58    /// 相同优先级时按注册顺序。
59    ///
60    /// 典型分段:
61    /// - `0 ~ 99`:框架基础插件(cache、db 等)
62    /// - `100`:默认值
63    /// - `> 100`:用户自定义插件(越晚启动)
64    fn priority(&self) -> i32 {
65        100
66    }
67
68    /// 降级钩子:主动退出重负载状态(如断开下游、停止接受新请求),保留受限服务
69    ///
70    /// 在 `PluginManager::degrade_all()` 中按启动**逆序**调用(依赖方先降级,
71    /// 停止向被依赖方施压后再降级被依赖方,与 stop_all 的逆序同理)。
72    /// 返回 `Err` 会触发该插件故障转移(标 Faulted 并调用 `on_fault`)。
73    async fn on_degrade(&self) -> Result<()> {
74        Ok(())
75    }
76
77    /// 恢复钩子:从降级状态恢复完整服务能力
78    ///
79    /// 在 `PluginManager::resume_all()` 中按启动顺序调用(被依赖方先就绪)。
80    /// 返回 `Err` 会触发该插件故障转移。
81    async fn on_resume(&self) -> Result<()> {
82        Ok(())
83    }
84
85    /// 故障钩子:进入不可用状态前的最后清理(尽力而为,异常仅记录日志)
86    ///
87    /// 在 `PluginManager::fault()` 手动触发、或降级/恢复失败自动转移时调用。
88    /// 状态在钩子执行**前**已标为 Faulted(故障插件不再接收新工作,钩子安心清理)。
89    async fn on_fault(&self) -> Result<()> {
90        Ok(())
91    }
92}
93
94/// `Arc<T>` 自动实现 [`Plugin`]:全部方法转发到内部实例。
95///
96/// 便于多个组件共享同一个插件引用(如装配插件先注入依赖、再注册插件本体),
97/// 或把插件包装进 `Arc` 统一管理生命周期。
98#[async_trait]
99impl<T: Plugin + ?Sized> Plugin for Arc<T> {
100    fn name(&self) -> &str {
101        (**self).name()
102    }
103
104    fn depends_on(&self) -> &[&str] {
105        (**self).depends_on()
106    }
107
108    fn priority(&self) -> i32 {
109        (**self).priority()
110    }
111
112    async fn start(&self) -> Result<()> {
113        (**self).start().await
114    }
115
116    async fn stop(&self) -> Result<()> {
117        (**self).stop().await
118    }
119
120    async fn on_degrade(&self) -> Result<()> {
121        (**self).on_degrade().await
122    }
123
124    async fn on_resume(&self) -> Result<()> {
125        (**self).on_resume().await
126    }
127
128    async fn on_fault(&self) -> Result<()> {
129        (**self).on_fault().await
130    }
131}
132
133use std::collections::{HashMap, HashSet};
134use std::sync::Arc;
135use tracing::{error, info, warn};
136
137use crate::state::{PluginState, PluginTrigger};
138
139/// `stop_all` 依据的启动记录(三态,区分「从未启动」与「已停止」)
140enum StartedRecord {
141    /// 从未调用 `start_all`:`stop_all` 回退到注册列表逆序(尽力清理)
142    NotStarted,
143    /// 实际成功启动的插件(拓扑顺序);`stop_all` 严格按此列表逆序关闭
144    Running(Vec<Arc<dyn Plugin>>),
145    /// 已停止(含启动失败回滚):`stop_all` 不再重复执行钩子
146    Stopped,
147}
148
149/// 插件管理器:负责注册、拓扑排序启动、严格逆序关闭(含启动失败回滚)
150///
151/// 内置生命周期状态机([`PluginState`]):跟踪每个插件的状态,
152/// 非法操作(重复启动、恢复未降级插件等)被状态机拒绝并记录日志;
153/// 额外提供 `degrade_all` / `resume_all` / `fault` / `reset` 生命周期管理。
154///
155/// # 示例
156///
157/// ```ignore
158/// let mgr = PluginManager::new()
159///     .add(db_plugin)
160///     .add(cache_plugin);
161/// mgr.start_all().await?;
162/// // ... 运行应用 ...
163/// mgr.stop_all().await;
164/// ```
165pub struct PluginManager {
166    plugins: Vec<Arc<dyn Plugin>>,
167    /// 启动记录(三态):重复 start_all 不会清空已启动列表,stop_all 后不再重复关闭
168    started: std::sync::Mutex<StartedRecord>,
169    /// 各插件生命周期状态(name → state;新注册插件补记为 Stopped)
170    states: std::sync::Mutex<HashMap<String, PluginState>>,
171}
172
173impl PluginManager {
174    /// 创建空的插件管理器
175    pub fn new() -> Self {
176        Self {
177            plugins: Vec::new(),
178            started: std::sync::Mutex::new(StartedRecord::NotStarted),
179            states: std::sync::Mutex::new(HashMap::new()),
180        }
181    }
182
183    /// 同步注册表到状态表(新注册插件用 entry API 补记为 Stopped),返回状态表锁
184    fn states_locked(&self) -> std::sync::MutexGuard<'_, HashMap<String, PluginState>> {
185        let mut map = self.states.lock().unwrap();
186        for p in &self.plugins {
187            map.entry(p.name().to_owned()).or_insert(PluginState::Stopped);
188        }
189        map
190    }
191
192    /// 对指定插件应用状态转移(非法转移返回 Err,不更新状态)
193    fn apply(
194        &self,
195        states: &mut HashMap<String, PluginState>,
196        name: &str,
197        trigger: PluginTrigger,
198    ) -> std::result::Result<(), String> {
199        let cur = states.get(name).copied().unwrap_or(PluginState::Stopped);
200        let next = cur.transition(trigger)?;
201        states.insert(name.to_owned(), next);
202        Ok(())
203    }
204
205    /// 手动注册插件(链式调用)
206    ///
207    /// # 示例
208    ///
209    /// ```ignore
210    /// PluginManager::new()
211    ///     .add(DbPlugin::new(db_config))
212    ///     .add(CachePlugin::new(cache_config))
213    /// ```
214    // 消费式 builder 命名 `add` 与 `Add::add` 形似触发 lint;公开 API 已发布(crates.io),
215    // 改名属破坏性变更,此处刻意保留。
216    #[allow(clippy::should_implement_trait)]
217    pub fn add<P: Plugin + 'static>(mut self, plugin: P) -> Self {
218        self.plugins.push(Arc::new(plugin));
219        self
220    }
221
222    /// 编译期自动发现的插件批量注册
223    ///
224    /// 与 `#[plugin]` 宏配合使用,将 linkme 收集到的插件批量加入管理器。
225    pub fn add_discovered(mut self, plugins: Vec<Arc<dyn Plugin>>) -> Self {
226        self.plugins.extend(plugins);
227        self
228    }
229
230    /// 拓扑排序后依次启动所有插件,并记录实际启动顺序
231    ///
232    /// 若任一插件启动失败,立即按逆序回滚**本轮**已成功启动的插件,避免系统停留在部分启动状态;
233    /// 启动失败的插件标记为 Faulted(`state()` 可查)。
234    /// 已在运行的插件被状态机拒绝(跳过并告警),不会重复执行 start 钩子,
235    /// 且其启动记录被保留——二次 `start_all` 不会让 `stop_all` 失去可关闭的插件。
236    pub async fn start_all(&self) -> Result<()> {
237        let ordered = self.topological_sort()?;
238        // 保留上一轮仍在运行的插件:二次 start_all 全部被状态门禁跳过时,
239        // 不能用空列表覆盖记录,否则 stop_all 将无插件可关
240        let previous: Vec<Arc<dyn Plugin>> = match &*self.started.lock().unwrap() {
241            StartedRecord::Running(list) => list.clone(),
242            _ => Vec::new(),
243        };
244        let mut started: Vec<Arc<dyn Plugin>> = Vec::new();
245
246        for plugin in ordered {
247            // 状态门禁:非 Stopped 的插件跳过启动(防双启动;Faulted 须先 reset)
248            {
249                let mut states = self.states_locked();
250                if let Err(reason) = self.apply(&mut states, plugin.name(), PluginTrigger::Start) {
251                    warn!("插件 {} 跳过启动: {}", plugin.name(), reason);
252                    continue;
253                }
254            }
255            info!("启动插件: {}", plugin.name());
256            if let Err(e) = plugin.start().await {
257                error!("插件 {} 启动失败: {}", plugin.name(), e);
258                {
259                    let mut states = self.states_locked();
260                    let _ = self.apply(&mut states, plugin.name(), PluginTrigger::StartFailed);
261                }
262                // 回滚:仅逆序停止本轮新启动的插件(上一轮运行中的不受影响;尽力而为,失败仅记录日志)
263                for p in started.iter().rev() {
264                    info!("回滚已启动插件: {}", p.name());
265                    {
266                        let mut states = self.states_locked();
267                        let _ = self.apply(&mut states, p.name(), PluginTrigger::Stop);
268                    }
269                    if let Err(e2) = p.stop().await {
270                        error!("插件 {} 回滚停止异常: {}", p.name(), e2);
271                    }
272                }
273                *self.started.lock().unwrap() = if previous.is_empty() {
274                    StartedRecord::Stopped
275                } else {
276                    StartedRecord::Running(previous)
277                };
278                return Err(e);
279            }
280            {
281                let mut states = self.states_locked();
282                let _ = self.apply(&mut states, plugin.name(), PluginTrigger::StartOk);
283            }
284            started.push(Arc::clone(&plugin));
285        }
286
287        // 合并去重:fault→reset→restart 的插件会同时出现在两轮记录中,只保留本轮位置
288        let mut merged = previous;
289        merged.retain(|p| !started.iter().any(|s| s.name() == p.name()));
290        merged.extend(started);
291        *self.started.lock().unwrap() = StartedRecord::Running(merged);
292        Ok(())
293    }
294
295    /// 严格按“实际成功启动顺序”的逆序关闭插件(后启动的先关闭)
296    ///
297    /// 只关闭记录已启动的插件;未调用过 `start_all` 时回退到注册列表逆序;
298    /// 已停止(含启动失败回滚)后重复调用为空操作,不会重复执行 stop 钩子。
299    /// 即使某个插件关闭失败,也会继续关闭其余插件(仅记录错误日志)。
300    pub async fn stop_all(&self) {
301        let list = {
302            let mut record = self.started.lock().unwrap();
303            match std::mem::replace(&mut *record, StartedRecord::Stopped) {
304                StartedRecord::Running(list) => list,
305                StartedRecord::Stopped => return,
306                StartedRecord::NotStarted => self.plugins.clone(),
307            }
308        };
309        for plugin in list.iter().rev() {
310            info!("停止插件: {}", plugin.name());
311            // 停机兜底:Degraded / Faulted / 未启动的 Stopped 也允许关闭;
312            // 转移被拒(如瞬态状态)仅告警,仍执行 stop 钩子保证清理
313            {
314                let mut states = self.states_locked();
315                if let Err(reason) = self.apply(&mut states, plugin.name(), PluginTrigger::Stop) {
316                    warn!("插件 {} 状态转移告警: {}", plugin.name(), reason);
317                }
318            }
319            if let Err(e) = plugin.stop().await {
320                error!("插件 {} 停止异常: {}", plugin.name(), e);
321            }
322        }
323    }
324
325    /// 查询插件当前生命周期状态(未知插件返回 `None`)
326    pub fn state(&self, name: &str) -> Option<PluginState> {
327        self.states_locked().get(name).copied()
328    }
329
330    /// 降级所有运行中的插件(按启动**逆序**:依赖方先降级,与 stop_all 同理)
331    ///
332    /// 非 Running 状态的插件跳过;降级钩子失败的插件自动故障转移(Faulted + `on_fault`)。
333    pub async fn degrade_all(&self) {
334        let list = match &*self.started.lock().unwrap() {
335            StartedRecord::Running(list) => list.clone(),
336            _ => return, // 未启动或已停止,无可降级
337        };
338        for plugin in list.iter().rev() {
339            let name = plugin.name();
340            {
341                let mut states = self.states_locked();
342                if let Err(reason) = self.apply(&mut states, name, PluginTrigger::Degrade) {
343                    warn!("插件 {} 跳过降级: {}", name, reason);
344                    continue;
345                }
346            }
347            info!("降级插件: {}", name);
348            if let Err(e) = plugin.on_degrade().await {
349                error!("插件 {} 降级异常: {}", name, e);
350                self.fault_plugin(plugin, &format!("降级失败: {e}")).await;
351                continue;
352            }
353            let mut states = self.states_locked();
354            let _ = self.apply(&mut states, name, PluginTrigger::DegradeOk);
355        }
356    }
357
358    /// 恢复所有已降级的插件(按启动顺序:被依赖方先就绪)
359    ///
360    /// 非 Degraded 状态的插件跳过;恢复钩子失败的插件自动故障转移。
361    pub async fn resume_all(&self) {
362        let list = match &*self.started.lock().unwrap() {
363            StartedRecord::Running(list) => list.clone(),
364            _ => return,
365        };
366        for plugin in list.iter() {
367            let name = plugin.name();
368            {
369                let mut states = self.states_locked();
370                if let Err(reason) = self.apply(&mut states, name, PluginTrigger::Resume) {
371                    warn!("插件 {} 跳过恢复: {}", name, reason);
372                    continue;
373                }
374            }
375            info!("恢复插件: {}", name);
376            if let Err(e) = plugin.on_resume().await {
377                error!("插件 {} 恢复异常: {}", name, e);
378                self.fault_plugin(plugin, &format!("恢复失败: {e}")).await;
379                continue;
380            }
381            let mut states = self.states_locked();
382            let _ = self.apply(&mut states, name, PluginTrigger::ResumeOk);
383        }
384    }
385
386    /// 手动将指定插件转入故障状态并执行 `on_fault` 清理钩子
387    ///
388    /// 返回 `false` 表示插件未知或当前状态不可故障转移(如未启动);
389    /// 对已 Faulted 的插件幂等返回 `true`。
390    pub async fn fault(&self, name: &str) -> bool {
391        let Some(plugin) = self.plugins.iter().find(|p| p.name() == name) else {
392            warn!("fault: 未知插件 {}", name);
393            return false;
394        };
395        match self.state(name) {
396            Some(PluginState::Faulted) => true, // 幂等
397            Some(PluginState::Stopped) => {
398                warn!("插件 {} 未启动,无可故障转移", name);
399                false
400            }
401            Some(_) => {
402                self.fault_plugin(plugin, "手动触发").await;
403                true
404            }
405            None => false,
406        }
407    }
408
409    /// 将故障插件重置为 Stopped,允许重新走启动流程
410    ///
411    /// 返回 `false` 表示插件未知或状态机拒绝(非 Faulted 不可重置)。
412    pub fn reset(&self, name: &str) -> bool {
413        if !self.plugins.iter().any(|p| p.name() == name) {
414            return false;
415        }
416        let mut states = self.states_locked();
417        self.apply(&mut states, name, PluginTrigger::Reset).is_ok()
418    }
419
420    /// 将单个插件转入 Faulted 并执行故障清理钩子(状态先行,钩子随后,均尽力而为)
421    async fn fault_plugin(&self, plugin: &Arc<dyn Plugin>, reason: &str) {
422        {
423            let mut states = self.states_locked();
424            if let Err(r) = self.apply(&mut states, plugin.name(), PluginTrigger::Fault) {
425                warn!("插件 {} 故障转移被拒绝: {}", plugin.name(), r);
426                return;
427            }
428        }
429        error!("插件 {} 进入故障状态: {}", plugin.name(), reason);
430        if let Err(e) = plugin.on_fault().await {
431            error!("插件 {} 故障清理钩子异常: {}", plugin.name(), e);
432        }
433    }
434
435    /// Kahn 算法拓扑排序,检测循环依赖
436    ///
437    /// 在依赖关系相同(入度均为 0)的插件中,按 `priority()` 升序选取,
438    /// 优先级相同时按注册顺序(稳定排序)。
439    fn topological_sort(&self) -> Result<Vec<Arc<dyn Plugin>>> {
440        // 先校验重名:重名会导致 name_to_idx 后者覆盖前者,破坏依赖解析
441        self.check_duplicate_names()
442            .map_err(crate::error::Error::Config)?;
443
444        let name_to_idx: HashMap<&str, usize> = self
445            .plugins
446            .iter()
447            .enumerate()
448            .map(|(i, p)| (p.name(), i))
449            .collect();
450
451        let count = self.plugins.len();
452        let mut in_degree = vec![0usize; count];
453        let mut adj = vec![Vec::new(); count];
454
455        for (i, plugin) in self.plugins.iter().enumerate() {
456            for dep in plugin.depends_on() {
457                match name_to_idx.get(dep) {
458                    Some(&j) => {
459                        adj[j].push(i);
460                        in_degree[i] += 1;
461                    }
462                    // 依赖未注册时明确报错
463                    None => {
464                        return Err(crate::error::Error::Config(format!(
465                            "插件 {} 依赖的插件 {} 未注册",
466                            plugin.name(),
467                            dep
468                        )));
469                    }
470                }
471            }
472        }
473
474        // 收集初始入度为 0 的插件
475        let mut ready: Vec<usize> = (0..count).filter(|&i| in_degree[i] == 0).collect();
476        // 升序排列:priority 数值小的在前,同优先级保持注册顺序(稳定排序)
477        ready.sort_by_key(|&idx| self.plugins[idx].priority());
478
479        let mut sorted = Vec::with_capacity(count);
480        while !ready.is_empty() {
481            // remove(0) 取优先级数值最小的就绪插件(最先启动)
482            let u = ready.remove(0);
483            sorted.push(Arc::clone(&self.plugins[u]));
484            let mut newly_ready = Vec::new();
485            for &v in &adj[u] {
486                in_degree[v] -= 1;
487                if in_degree[v] == 0 {
488                    newly_ready.push(v);
489                }
490            }
491            if !newly_ready.is_empty() {
492                ready.extend(newly_ready);
493                ready.sort_by_key(|&idx| self.plugins[idx].priority());
494            }
495        }
496
497        if sorted.len() != count {
498            // 检测循环依赖
499            let cycle: Vec<&str> = self
500                .plugins
501                .iter()
502                .enumerate()
503                .filter(|(i, _)| in_degree[*i] > 0)
504                .map(|(_, p)| p.name())
505                .collect();
506            return Err(crate::error::Error::Config(format!(
507                "插件循环依赖: {:?}",
508                cycle
509            )));
510        }
511
512        Ok(sorted)
513    }
514
515    /// 确保插件之间没有 name 冲突
516    pub fn check_duplicate_names(&self) -> std::result::Result<(), String> {
517        let mut seen = HashSet::new();
518        for p in &self.plugins {
519            if !seen.insert(p.name()) {
520                return Err(format!("插件名重复: {}", p.name()));
521            }
522        }
523        Ok(())
524    }
525}
526
527impl Default for PluginManager {
528    fn default() -> Self {
529        Self::new()
530    }
531}
532
533#[cfg(test)]
534mod tests {
535    use super::*;
536    use async_trait::async_trait;
537    use parking_lot::Mutex;
538    use std::sync::Arc;
539
540    struct TestPlugin {
541        name: &'static str,
542        deps: &'static [&'static str],
543        prio: i32,
544        order: Arc<Mutex<Vec<String>>>,
545    }
546
547    #[async_trait]
548    impl Plugin for TestPlugin {
549        fn name(&self) -> &str {
550            self.name
551        }
552        async fn start(&self) -> Result<()> {
553            self.order.lock().push(format!("start:{}", self.name));
554            Ok(())
555        }
556        async fn stop(&self) -> Result<()> {
557            self.order.lock().push(format!("stop:{}", self.name));
558            Ok(())
559        }
560        fn depends_on(&self) -> &[&str] {
561            self.deps
562        }
563        fn priority(&self) -> i32 {
564            self.prio
565        }
566    }
567
568    #[tokio::test]
569    async fn test_topological_start() {
570        let order = Arc::new(Mutex::new(Vec::new()));
571
572        let mgr = PluginManager::new()
573            .add(TestPlugin {
574                name: "c",
575                deps: &["a", "b"],
576                prio: 100,
577                order: order.clone(),
578            })
579            .add(TestPlugin {
580                name: "b",
581                deps: &["a"],
582                prio: 100,
583                order: order.clone(),
584            })
585            .add(TestPlugin {
586                name: "a",
587                deps: &[],
588                prio: 100,
589                order: order.clone(),
590            });
591
592        mgr.start_all().await.unwrap();
593
594        let log = order.lock();
595        assert_eq!(log[0], "start:a");
596        assert_eq!(log[1], "start:b");
597        assert_eq!(log[2], "start:c");
598    }
599
600    #[tokio::test]
601    async fn test_cycle_detection() {
602        let order = Arc::new(Mutex::new(Vec::new()));
603
604        let mgr = PluginManager::new()
605            .add(TestPlugin {
606                name: "x",
607                deps: &["y"],
608                prio: 100,
609                order: order.clone(),
610            })
611            .add(TestPlugin {
612                name: "y",
613                deps: &["x"],
614                prio: 100,
615                order: order.clone(),
616            });
617
618        let result = mgr.start_all().await;
619        assert!(result.is_err());
620    }
621
622    #[tokio::test]
623    async fn test_stop_reverses_topological_order() {
624        let order = Arc::new(Mutex::new(Vec::new()));
625
626        // 注册顺序与拓扑顺序不同:c → b → a,但拓扑启动顺序为 a → b → c
627        let mgr = PluginManager::new()
628            .add(TestPlugin {
629                name: "c",
630                deps: &["a", "b"],
631                prio: 100,
632                order: order.clone(),
633            })
634            .add(TestPlugin {
635                name: "b",
636                deps: &["a"],
637                prio: 100,
638                order: order.clone(),
639            })
640            .add(TestPlugin {
641                name: "a",
642                deps: &[],
643                prio: 100,
644                order: order.clone(),
645            });
646
647        mgr.start_all().await.unwrap();
648        mgr.stop_all().await;
649
650        let log = order.lock();
651        assert_eq!(log[0], "start:a");
652        assert_eq!(log[1], "start:b");
653        assert_eq!(log[2], "start:c");
654        // 关闭必须是启动顺序的严格逆序,而不是注册顺序的逆序(c、b、a)
655        assert_eq!(log[3], "stop:c");
656        assert_eq!(log[4], "stop:b");
657        assert_eq!(log[5], "stop:a");
658    }
659
660    struct FailOnStartPlugin {
661        name: &'static str,
662        fail: bool,
663        order: Arc<Mutex<Vec<String>>>,
664    }
665
666    #[async_trait]
667    impl Plugin for FailOnStartPlugin {
668        fn name(&self) -> &str {
669            self.name
670        }
671        async fn start(&self) -> Result<()> {
672            self.order.lock().push(format!("start:{}", self.name));
673            if self.fail {
674                Err(crate::error::Error::Config(format!(
675                    "{} 启动失败(测试)",
676                    self.name
677                )))
678            } else {
679                Ok(())
680            }
681        }
682        async fn stop(&self) -> Result<()> {
683            self.order.lock().push(format!("stop:{}", self.name));
684            Ok(())
685        }
686    }
687
688    #[tokio::test]
689    async fn test_partial_start_rolls_back() {
690        let order = Arc::new(Mutex::new(Vec::new()));
691
692        let mgr = PluginManager::new()
693            .add(FailOnStartPlugin {
694                name: "a",
695                fail: false,
696                order: order.clone(),
697            })
698            .add(FailOnStartPlugin {
699                name: "b",
700                fail: true,
701                order: order.clone(),
702            });
703
704        let result = mgr.start_all().await;
705        assert!(result.is_err());
706
707        // a 已启动,b 失败后必须回滚 a(stop:a)
708        {
709            let log = order.lock();
710            assert_eq!(log[0], "start:a");
711            assert_eq!(log[1], "start:b");
712            assert_eq!(log[2], "stop:a");
713            assert_eq!(log.len(), 3);
714        }
715
716        // 回滚后停机列表清空:再次 stop 不重复关闭
717        mgr.stop_all().await;
718        assert_eq!(order.lock().len(), 3);
719    }
720
721    #[tokio::test]
722    async fn test_repeated_start_stop() {
723        let order = Arc::new(Mutex::new(Vec::new()));
724
725        let mgr = PluginManager::new().add(TestPlugin {
726            name: "a",
727            deps: &[],
728            prio: 100,
729            order: order.clone(),
730        });
731
732        mgr.start_all().await.unwrap();
733        mgr.stop_all().await;
734        // 重复 start/stop 不 panic、不重复关闭
735        mgr.start_all().await.unwrap();
736        mgr.stop_all().await;
737
738        let log = order.lock();
739        assert_eq!(&*log, &["start:a", "stop:a", "start:a", "stop:a"]);
740    }
741
742    #[tokio::test]
743    async fn test_priority_ordering() {
744        let order = Arc::new(Mutex::new(Vec::new()));
745
746        // 三个插件无依赖关系,靠 priority 控制启动顺序:
747        // prio=10 先启动,prio=50 其次,prio=200 最后
748        let mgr = PluginManager::new()
749            .add(TestPlugin {
750                name: "late",
751                deps: &[],
752                prio: 200,
753                order: order.clone(),
754            })
755            .add(TestPlugin {
756                name: "early",
757                deps: &[],
758                prio: 10,
759                order: order.clone(),
760            })
761            .add(TestPlugin {
762                name: "mid",
763                deps: &[],
764                prio: 50,
765                order: order.clone(),
766            });
767
768        mgr.start_all().await.unwrap();
769
770        let log = order.lock();
771        assert_eq!(log[0], "start:early"); // prio=10 最小,最先启动
772        assert_eq!(log[1], "start:mid"); // prio=50
773        assert_eq!(log[2], "start:late"); // prio=200 最大,最后启动
774    }
775
776    #[test]
777    fn duplicate_names_rejected() {
778        let order = Arc::new(Mutex::new(Vec::new()));
779        let mgr = PluginManager::new()
780            .add(TestPlugin { name: "dup", deps: &[], prio: 0, order: order.clone() })
781            .add(TestPlugin { name: "dup", deps: &[], prio: 0, order: order.clone() });
782        assert!(mgr.check_duplicate_names().is_err());
783        // start_all 内部同样校验重名
784        assert!(futures_block(mgr.start_all()).is_err());
785    }
786
787    #[test]
788    fn missing_dependency_rejected() {
789        let order = Arc::new(Mutex::new(Vec::new()));
790        let mgr = PluginManager::new()
791            .add(TestPlugin { name: "a", deps: &["ghost"], prio: 0, order: order.clone() });
792        let err = futures_block(mgr.start_all()).unwrap_err();
793        assert!(err.to_string().contains("ghost"));
794    }
795
796    #[test]
797    fn stop_all_without_start_falls_back_to_registry_reverse() {
798        let order = Arc::new(Mutex::new(Vec::new()));
799        let mgr = PluginManager::new()
800            .add(TestPlugin { name: "a", deps: &[], prio: 0, order: order.clone() })
801            .add(TestPlugin { name: "b", deps: &[], prio: 0, order: order.clone() });
802        // 未 start 直接 stop:按注册列表逆序关闭
803        futures_block(mgr.stop_all());
804        assert_eq!(&*order.lock(), &["stop:b", "stop:a"]);
805    }
806
807    #[test]
808    fn add_discovered_collects_arc_plugins() {
809        let order = Arc::new(Mutex::new(Vec::new()));
810        let p: Arc<dyn Plugin> = Arc::new(TestPlugin {
811            name: "discovered",
812            deps: &[],
813            prio: 0,
814            order: order.clone(),
815        });
816        let mgr = PluginManager::new().add_discovered(vec![p]);
817        assert_eq!(mgr.check_duplicate_names(), Ok(()));
818        futures_block(mgr.start_all()).unwrap();
819        assert_eq!(&*order.lock(), &["start:discovered"]);
820    }
821
822    #[tokio::test]
823    async fn arc_plugin_forwards_methods() {
824        let order = Arc::new(Mutex::new(Vec::new()));
825        let inner = Arc::new(TestPlugin { name: "wrapped", deps: &[], prio: 7, order: order.clone() });
826        let arc: Arc<dyn Plugin> = inner.clone();
827        assert_eq!(arc.name(), "wrapped");
828        assert_eq!(arc.priority(), 7);
829        assert!(arc.depends_on().is_empty());
830        arc.start().await.unwrap();
831        arc.stop().await.unwrap();
832        assert_eq!(&*order.lock(), &["start:wrapped", "stop:wrapped"]);
833    }
834
835    #[test]
836    fn default_manager() {
837        let mgr = PluginManager::default();
838        assert!(mgr.check_duplicate_names().is_ok());
839    }
840
841    // ── 生命周期状态机集成测试 ────────────────────────────────
842
843    /// 带降级/恢复/故障钩子的测试插件
844    struct LifecyclePlugin {
845        name: &'static str,
846        fail_degrade: bool,
847        fail_resume: bool,
848        order: Arc<Mutex<Vec<String>>>,
849    }
850
851    #[async_trait]
852    impl Plugin for LifecyclePlugin {
853        fn name(&self) -> &str {
854            self.name
855        }
856        async fn start(&self) -> Result<()> {
857            self.order.lock().push(format!("start:{}", self.name));
858            Ok(())
859        }
860        async fn stop(&self) -> Result<()> {
861            self.order.lock().push(format!("stop:{}", self.name));
862            Ok(())
863        }
864        async fn on_degrade(&self) -> Result<()> {
865            self.order.lock().push(format!("degrade:{}", self.name));
866            if self.fail_degrade {
867                Err(crate::error::Error::Config("降级失败(测试)".into()))
868            } else {
869                Ok(())
870            }
871        }
872        async fn on_resume(&self) -> Result<()> {
873            self.order.lock().push(format!("resume:{}", self.name));
874            if self.fail_resume {
875                Err(crate::error::Error::Config("恢复失败(测试)".into()))
876            } else {
877                Ok(())
878            }
879        }
880        async fn on_fault(&self) -> Result<()> {
881            self.order.lock().push(format!("fault:{}", self.name));
882            Ok(())
883        }
884    }
885
886    #[tokio::test]
887    async fn degrade_resume_lifecycle_transitions() {
888        let order = Arc::new(Mutex::new(Vec::new()));
889        let mgr = PluginManager::new()
890            .add(LifecyclePlugin {
891                name: "a",
892                fail_degrade: false,
893                fail_resume: false,
894                order: order.clone(),
895            })
896            .add(LifecyclePlugin {
897                name: "b",
898                fail_degrade: false,
899                fail_resume: false,
900                order: order.clone(),
901            });
902
903        mgr.start_all().await.unwrap();
904        assert_eq!(mgr.state("a"), Some(PluginState::Running));
905        assert_eq!(mgr.state("unknown"), None, "未知插件返回 None");
906
907        mgr.degrade_all().await;
908        assert_eq!(mgr.state("a"), Some(PluginState::Degraded));
909        assert!(mgr.state("a").unwrap().is_available(), "降级仍可用");
910        assert!(!mgr.state("a").unwrap().is_running());
911
912        mgr.resume_all().await;
913        assert_eq!(mgr.state("a"), Some(PluginState::Running));
914
915        // 降级后 stop:Degraded + Stop 合法
916        mgr.degrade_all().await;
917        mgr.stop_all().await;
918        assert_eq!(mgr.state("a"), Some(PluginState::Stopped));
919
920        assert_eq!(
921            &*order.lock(),
922            &[
923                "start:a", "start:b",
924                // degrade 逆序(依赖方 b 先降级),resume 正序(被依赖方 a 先就绪)
925                "degrade:b", "degrade:a", "resume:a", "resume:b",
926                "degrade:b", "degrade:a",
927                // stop 逆序(后启动的先关闭)
928                "stop:b", "stop:a"
929            ]
930        );
931    }
932
933    #[tokio::test]
934    async fn degrade_order_is_reverse_of_start_order() {
935        struct DepPlugin {
936            name: &'static str,
937            deps: &'static [&'static str],
938            order: Arc<Mutex<Vec<String>>>,
939        }
940        #[async_trait]
941        impl Plugin for DepPlugin {
942            fn name(&self) -> &str {
943                self.name
944            }
945            fn depends_on(&self) -> &[&str] {
946                self.deps
947            }
948            async fn start(&self) -> Result<()> {
949                Ok(())
950            }
951            async fn stop(&self) -> Result<()> {
952                Ok(())
953            }
954            async fn on_degrade(&self) -> Result<()> {
955                self.order.lock().push(format!("degrade:{}", self.name));
956                Ok(())
957            }
958        }
959
960        let order = Arc::new(Mutex::new(Vec::new()));
961        let mgr = PluginManager::new()
962            .add(DepPlugin { name: "a", deps: &[], order: order.clone() })
963            .add(DepPlugin { name: "b", deps: &["a"], order: order.clone() });
964        mgr.start_all().await.unwrap();
965        mgr.degrade_all().await;
966        // b(依赖方)先降级,a(被依赖方)后降级
967        assert_eq!(&*order.lock(), &["degrade:b", "degrade:a"]);
968    }
969
970    #[tokio::test]
971    async fn degrade_failure_triggers_fault_transfer() {
972        let order = Arc::new(Mutex::new(Vec::new()));
973        let mgr = PluginManager::new().add(LifecyclePlugin {
974            name: "a",
975            fail_degrade: true,
976            fail_resume: false,
977            order: order.clone(),
978        });
979
980        mgr.start_all().await.unwrap();
981        mgr.degrade_all().await;
982
983        // 降级失败 → 自动故障转移:on_fault 被调用、状态 Faulted
984        assert_eq!(mgr.state("a"), Some(PluginState::Faulted));
985        assert!(order.lock().contains(&"fault:a".to_string()));
986
987        // 故障插件不可再降级/恢复,stop 兜底可关闭
988        mgr.resume_all().await;
989        assert_eq!(mgr.state("a"), Some(PluginState::Faulted));
990        mgr.stop_all().await;
991        assert_eq!(mgr.state("a"), Some(PluginState::Stopped));
992    }
993
994    #[tokio::test]
995    async fn resume_failure_triggers_fault_transfer() {
996        let order = Arc::new(Mutex::new(Vec::new()));
997        let mgr = PluginManager::new().add(LifecyclePlugin {
998            name: "a",
999            fail_degrade: false,
1000            fail_resume: true,
1001            order: order.clone(),
1002        });
1003
1004        mgr.start_all().await.unwrap();
1005        mgr.degrade_all().await;
1006        mgr.resume_all().await;
1007
1008        assert_eq!(mgr.state("a"), Some(PluginState::Faulted));
1009        assert!(order.lock().contains(&"fault:a".to_string()));
1010    }
1011
1012    #[tokio::test]
1013    async fn manual_fault_and_reset_allow_restart() {
1014        let order = Arc::new(Mutex::new(Vec::new()));
1015        let mgr = PluginManager::new().add(LifecyclePlugin {
1016            name: "a",
1017            fail_degrade: false,
1018            fail_resume: false,
1019            order: order.clone(),
1020        });
1021
1022        mgr.start_all().await.unwrap();
1023
1024        // 未启动插件不可 fault、未知插件返回 false
1025        assert!(!mgr.fault("ghost").await);
1026
1027        assert!(mgr.fault("a").await);
1028        assert_eq!(mgr.state("a"), Some(PluginState::Faulted));
1029        assert!(order.lock().contains(&"fault:a".to_string()));
1030        // 对已 Faulted 插件幂等
1031        assert!(mgr.fault("a").await);
1032
1033        // Faulted 直接 start 被拒;reset 后可重新启动
1034        mgr.start_all().await.unwrap();
1035        assert_eq!(mgr.state("a"), Some(PluginState::Faulted), "Faulted 跳过启动");
1036        assert!(mgr.reset("a"));
1037        assert_eq!(mgr.state("a"), Some(PluginState::Stopped));
1038        assert!(!mgr.reset("a"), "非 Faulted 不可重置");
1039
1040        mgr.start_all().await.unwrap();
1041        assert_eq!(mgr.state("a"), Some(PluginState::Running));
1042        let starts = order.lock().iter().filter(|e| e.as_str() == "start:a").count();
1043        assert_eq!(starts, 2, "reset 后重新执行了 start 钩子");
1044    }
1045
1046    #[tokio::test]
1047    async fn start_failure_marks_plugin_faulted() {
1048        let order = Arc::new(Mutex::new(Vec::new()));
1049        let mgr = PluginManager::new()
1050            .add(FailOnStartPlugin { name: "ok", fail: true, order: order.clone() });
1051        // fail=true:启动即失败 → Faulted(而非 Stopped)
1052        assert!(mgr.start_all().await.is_err());
1053        assert_eq!(mgr.state("ok"), Some(PluginState::Faulted));
1054        assert!(!mgr.state("ok").unwrap().is_available());
1055    }
1056
1057    #[tokio::test]
1058    async fn double_start_is_rejected_by_state_gate() {
1059        let order = Arc::new(Mutex::new(Vec::new()));
1060        let mgr = PluginManager::new().add(LifecyclePlugin {
1061            name: "a",
1062            fail_degrade: false,
1063            fail_resume: false,
1064            order: order.clone(),
1065        });
1066
1067        mgr.start_all().await.unwrap();
1068        // 二次 start_all:状态机拒绝,start 钩子不重复执行
1069        mgr.start_all().await.unwrap();
1070        assert_eq!(mgr.state("a"), Some(PluginState::Running));
1071        assert_eq!(order.lock().iter().filter(|e| e.as_str() == "start:a").count(), 1);
1072
1073        // 二次 start_all 不得清空启动记录:stop_all 仍能关闭插件(恰好一次)
1074        mgr.stop_all().await;
1075        assert_eq!(mgr.state("a"), Some(PluginState::Stopped));
1076        assert_eq!(order.lock().iter().filter(|e| e.as_str() == "stop:a").count(), 1);
1077    }
1078
1079    #[tokio::test]
1080    async fn double_stop_does_not_rerun_hooks() {
1081        let order = Arc::new(Mutex::new(Vec::new()));
1082        let mgr = PluginManager::new().add(TestPlugin {
1083            name: "a",
1084            deps: &[],
1085            prio: 100,
1086            order: order.clone(),
1087        });
1088        mgr.start_all().await.unwrap();
1089        mgr.stop_all().await;
1090        // 已停止后重复 stop_all 为空操作,不再执行 stop 钩子
1091        mgr.stop_all().await;
1092        assert_eq!(&*order.lock(), &["start:a", "stop:a"]);
1093    }
1094
1095    #[tokio::test]
1096    async fn restart_after_fault_keeps_stop_record_consistent() {
1097        let order = Arc::new(Mutex::new(Vec::new()));
1098        let mgr = PluginManager::new()
1099            .add(LifecyclePlugin { name: "a", fail_degrade: false, fail_resume: false, order: order.clone() })
1100            .add(LifecyclePlugin { name: "b", fail_degrade: false, fail_resume: false, order: order.clone() });
1101        mgr.start_all().await.unwrap();
1102        assert!(mgr.fault("a").await);
1103        assert!(mgr.reset("a"));
1104        // 仅 a 重新启动,b 保持运行;合并记录须去重,a 不得出现两次
1105        mgr.start_all().await.unwrap();
1106        mgr.stop_all().await;
1107        let stops: Vec<String> = order.lock().iter().filter(|e| e.starts_with("stop:")).cloned().collect();
1108        // a 重启后位于记录末尾,逆序先关 a 再关 b;每个插件恰好关闭一次
1109        assert_eq!(stops, vec!["stop:a".to_string(), "stop:b".to_string()]);
1110    }
1111
1112    /// 在无 async 测试中驱动一个 future(简化:用 tokio runtime 手工 block_on)
1113    fn futures_block<F: std::future::Future>(fut: F) -> F::Output {
1114        tokio::runtime::Builder::new_current_thread()
1115            .enable_all()
1116            .build()
1117            .unwrap()
1118            .block_on(fut)
1119    }
1120}