wordval-core 1.0.8

Wordval framework core: app lifecycle, plugin system, error handling, unified response types
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
use crate::error::Result;
use async_trait::async_trait;

/// 插件生命周期:start/stop 对称
///
/// 极简设计——只定义 start / stop 两个生命周期方法。
/// Rust 版增强:异步化 + 依赖声明 + 拓扑排序启动。
///
/// # 示例
///
/// ```ignore
/// use wordval_core::plugin::Plugin;
///
/// struct DbPlugin { pool: PgPool }
///
/// #[async_trait]
/// impl Plugin for DbPlugin {
///     fn name(&self) -> &str { "pg" }
///
///     async fn start(&self) -> Result<()> {
///         sqlx::query("SELECT 1").fetch_one(&self.pool).await?;
///         Ok(())
///     }
///
///     async fn stop(&self) -> Result<()> {
///         self.pool.close().await;
///         Ok(())
///     }
/// }
/// ```
#[async_trait]
pub trait Plugin: Send + Sync {
    /// 插件唯一名称(用于注册、日志、依赖解析)
    fn name(&self) -> &str;

    /// 启动插件:验证连接、初始化资源
    ///
    /// 在 `PluginManager::start_all()` 中被调用,按拓扑顺序依次执行。
    /// 若返回 `Err`,则启动流程中止,后续插件不会执行。
    async fn start(&self) -> Result<()>;

    /// 关闭插件:释放资源
    ///
    /// 在 `PluginManager::stop_all()` 中被调用,按逆序执行。
    /// 即使返回 `Err`,也会继续关闭其余插件(仅记录日志)。
    async fn stop(&self) -> Result<()>;

    /// 依赖的其他插件名称(用于拓扑排序,保证启动顺序)
    ///
    /// 默认返回空数组(无依赖)。
    fn depends_on(&self) -> &[&str] {
        &[]
    }

    /// 启动优先级(数值越小越先启动,默认 100)
    ///
    /// 在拓扑排序中,当多个插件的依赖都已满足时,优先级数值小的先启动。
    /// 相同优先级时按注册顺序。
    ///
    /// 典型分段:
    /// - `0 ~ 99`:框架基础插件(cache、db 等)
    /// - `100`:默认值
    /// - `> 100`:用户自定义插件(越晚启动)
    fn priority(&self) -> i32 {
        100
    }

    /// 降级钩子:主动退出重负载状态(如断开下游、停止接受新请求),保留受限服务
    ///
    /// 在 `PluginManager::degrade_all()` 中按启动**逆序**调用(依赖方先降级,
    /// 停止向被依赖方施压后再降级被依赖方,与 stop_all 的逆序同理)。
    /// 返回 `Err` 会触发该插件故障转移(标 Faulted 并调用 `on_fault`)。
    async fn on_degrade(&self) -> Result<()> {
        Ok(())
    }

    /// 恢复钩子:从降级状态恢复完整服务能力
    ///
    /// 在 `PluginManager::resume_all()` 中按启动顺序调用(被依赖方先就绪)。
    /// 返回 `Err` 会触发该插件故障转移。
    async fn on_resume(&self) -> Result<()> {
        Ok(())
    }

    /// 故障钩子:进入不可用状态前的最后清理(尽力而为,异常仅记录日志)
    ///
    /// 在 `PluginManager::fault()` 手动触发、或降级/恢复失败自动转移时调用。
    /// 状态在钩子执行**前**已标为 Faulted(故障插件不再接收新工作,钩子安心清理)。
    async fn on_fault(&self) -> Result<()> {
        Ok(())
    }
}

/// `Arc<T>` 自动实现 [`Plugin`]:全部方法转发到内部实例。
///
/// 便于多个组件共享同一个插件引用(如装配插件先注入依赖、再注册插件本体),
/// 或把插件包装进 `Arc` 统一管理生命周期。
#[async_trait]
impl<T: Plugin + ?Sized> Plugin for Arc<T> {
    fn name(&self) -> &str {
        (**self).name()
    }

    fn depends_on(&self) -> &[&str] {
        (**self).depends_on()
    }

    fn priority(&self) -> i32 {
        (**self).priority()
    }

    async fn start(&self) -> Result<()> {
        (**self).start().await
    }

    async fn stop(&self) -> Result<()> {
        (**self).stop().await
    }

    async fn on_degrade(&self) -> Result<()> {
        (**self).on_degrade().await
    }

    async fn on_resume(&self) -> Result<()> {
        (**self).on_resume().await
    }

    async fn on_fault(&self) -> Result<()> {
        (**self).on_fault().await
    }
}

use std::collections::{HashMap, HashSet};
use std::sync::Arc;
use tracing::{error, info, warn};

use crate::state::{PluginState, PluginTrigger};

/// `stop_all` 依据的启动记录(三态,区分「从未启动」与「已停止」)
enum StartedRecord {
    /// 从未调用 `start_all`:`stop_all` 回退到注册列表逆序(尽力清理)
    NotStarted,
    /// 实际成功启动的插件(拓扑顺序);`stop_all` 严格按此列表逆序关闭
    Running(Vec<Arc<dyn Plugin>>),
    /// 已停止(含启动失败回滚):`stop_all` 不再重复执行钩子
    Stopped,
}

/// 插件管理器:负责注册、拓扑排序启动、严格逆序关闭(含启动失败回滚)
///
/// 内置生命周期状态机([`PluginState`]):跟踪每个插件的状态,
/// 非法操作(重复启动、恢复未降级插件等)被状态机拒绝并记录日志;
/// 额外提供 `degrade_all` / `resume_all` / `fault` / `reset` 生命周期管理。
///
/// # 示例
///
/// ```ignore
/// let mgr = PluginManager::new()
///     .add(db_plugin)
///     .add(cache_plugin);
/// mgr.start_all().await?;
/// // ... 运行应用 ...
/// mgr.stop_all().await;
/// ```
pub struct PluginManager {
    plugins: Vec<Arc<dyn Plugin>>,
    /// 启动记录(三态):重复 start_all 不会清空已启动列表,stop_all 后不再重复关闭
    started: std::sync::Mutex<StartedRecord>,
    /// 各插件生命周期状态(name → state;新注册插件补记为 Stopped)
    states: std::sync::Mutex<HashMap<String, PluginState>>,
}

impl PluginManager {
    /// 创建空的插件管理器
    pub fn new() -> Self {
        Self {
            plugins: Vec::new(),
            started: std::sync::Mutex::new(StartedRecord::NotStarted),
            states: std::sync::Mutex::new(HashMap::new()),
        }
    }

    /// 同步注册表到状态表(新注册插件用 entry API 补记为 Stopped),返回状态表锁
    fn states_locked(&self) -> std::sync::MutexGuard<'_, HashMap<String, PluginState>> {
        let mut map = self.states.lock().unwrap();
        for p in &self.plugins {
            map.entry(p.name().to_owned()).or_insert(PluginState::Stopped);
        }
        map
    }

    /// 对指定插件应用状态转移(非法转移返回 Err,不更新状态)
    fn apply(
        &self,
        states: &mut HashMap<String, PluginState>,
        name: &str,
        trigger: PluginTrigger,
    ) -> std::result::Result<(), String> {
        let cur = states.get(name).copied().unwrap_or(PluginState::Stopped);
        let next = cur.transition(trigger)?;
        states.insert(name.to_owned(), next);
        Ok(())
    }

    /// 手动注册插件(链式调用)
    ///
    /// # 示例
    ///
    /// ```ignore
    /// PluginManager::new()
    ///     .add(DbPlugin::new(db_config))
    ///     .add(CachePlugin::new(cache_config))
    /// ```
    // 消费式 builder 命名 `add` 与 `Add::add` 形似触发 lint;公开 API 已发布(crates.io),
    // 改名属破坏性变更,此处刻意保留。
    #[allow(clippy::should_implement_trait)]
    pub fn add<P: Plugin + 'static>(mut self, plugin: P) -> Self {
        self.plugins.push(Arc::new(plugin));
        self
    }

    /// 编译期自动发现的插件批量注册
    ///
    /// 与 `#[plugin]` 宏配合使用,将 linkme 收集到的插件批量加入管理器。
    pub fn add_discovered(mut self, plugins: Vec<Arc<dyn Plugin>>) -> Self {
        self.plugins.extend(plugins);
        self
    }

    /// 拓扑排序后依次启动所有插件,并记录实际启动顺序
    ///
    /// 若任一插件启动失败,立即按逆序回滚**本轮**已成功启动的插件,避免系统停留在部分启动状态;
    /// 启动失败的插件标记为 Faulted(`state()` 可查)。
    /// 已在运行的插件被状态机拒绝(跳过并告警),不会重复执行 start 钩子,
    /// 且其启动记录被保留——二次 `start_all` 不会让 `stop_all` 失去可关闭的插件。
    pub async fn start_all(&self) -> Result<()> {
        let ordered = self.topological_sort()?;
        // 保留上一轮仍在运行的插件:二次 start_all 全部被状态门禁跳过时,
        // 不能用空列表覆盖记录,否则 stop_all 将无插件可关
        let previous: Vec<Arc<dyn Plugin>> = match &*self.started.lock().unwrap() {
            StartedRecord::Running(list) => list.clone(),
            _ => Vec::new(),
        };
        let mut started: Vec<Arc<dyn Plugin>> = Vec::new();

        for plugin in ordered {
            // 状态门禁:非 Stopped 的插件跳过启动(防双启动;Faulted 须先 reset)
            {
                let mut states = self.states_locked();
                if let Err(reason) = self.apply(&mut states, plugin.name(), PluginTrigger::Start) {
                    warn!("插件 {} 跳过启动: {}", plugin.name(), reason);
                    continue;
                }
            }
            info!("启动插件: {}", plugin.name());
            if let Err(e) = plugin.start().await {
                error!("插件 {} 启动失败: {}", plugin.name(), e);
                {
                    let mut states = self.states_locked();
                    let _ = self.apply(&mut states, plugin.name(), PluginTrigger::StartFailed);
                }
                // 回滚:仅逆序停止本轮新启动的插件(上一轮运行中的不受影响;尽力而为,失败仅记录日志)
                for p in started.iter().rev() {
                    info!("回滚已启动插件: {}", p.name());
                    {
                        let mut states = self.states_locked();
                        let _ = self.apply(&mut states, p.name(), PluginTrigger::Stop);
                    }
                    if let Err(e2) = p.stop().await {
                        error!("插件 {} 回滚停止异常: {}", p.name(), e2);
                    }
                }
                *self.started.lock().unwrap() = if previous.is_empty() {
                    StartedRecord::Stopped
                } else {
                    StartedRecord::Running(previous)
                };
                return Err(e);
            }
            {
                let mut states = self.states_locked();
                let _ = self.apply(&mut states, plugin.name(), PluginTrigger::StartOk);
            }
            started.push(Arc::clone(&plugin));
        }

        // 合并去重:fault→reset→restart 的插件会同时出现在两轮记录中,只保留本轮位置
        let mut merged = previous;
        merged.retain(|p| !started.iter().any(|s| s.name() == p.name()));
        merged.extend(started);
        *self.started.lock().unwrap() = StartedRecord::Running(merged);
        Ok(())
    }

    /// 严格按“实际成功启动顺序”的逆序关闭插件(后启动的先关闭)
    ///
    /// 只关闭记录已启动的插件;未调用过 `start_all` 时回退到注册列表逆序;
    /// 已停止(含启动失败回滚)后重复调用为空操作,不会重复执行 stop 钩子。
    /// 即使某个插件关闭失败,也会继续关闭其余插件(仅记录错误日志)。
    pub async fn stop_all(&self) {
        let list = {
            let mut record = self.started.lock().unwrap();
            match std::mem::replace(&mut *record, StartedRecord::Stopped) {
                StartedRecord::Running(list) => list,
                StartedRecord::Stopped => return,
                StartedRecord::NotStarted => self.plugins.clone(),
            }
        };
        for plugin in list.iter().rev() {
            info!("停止插件: {}", plugin.name());
            // 停机兜底:Degraded / Faulted / 未启动的 Stopped 也允许关闭;
            // 转移被拒(如瞬态状态)仅告警,仍执行 stop 钩子保证清理
            {
                let mut states = self.states_locked();
                if let Err(reason) = self.apply(&mut states, plugin.name(), PluginTrigger::Stop) {
                    warn!("插件 {} 状态转移告警: {}", plugin.name(), reason);
                }
            }
            if let Err(e) = plugin.stop().await {
                error!("插件 {} 停止异常: {}", plugin.name(), e);
            }
        }
    }

    /// 查询插件当前生命周期状态(未知插件返回 `None`)
    pub fn state(&self, name: &str) -> Option<PluginState> {
        self.states_locked().get(name).copied()
    }

    /// 降级所有运行中的插件(按启动**逆序**:依赖方先降级,与 stop_all 同理)
    ///
    /// 非 Running 状态的插件跳过;降级钩子失败的插件自动故障转移(Faulted + `on_fault`)。
    pub async fn degrade_all(&self) {
        let list = match &*self.started.lock().unwrap() {
            StartedRecord::Running(list) => list.clone(),
            _ => return, // 未启动或已停止,无可降级
        };
        for plugin in list.iter().rev() {
            let name = plugin.name();
            {
                let mut states = self.states_locked();
                if let Err(reason) = self.apply(&mut states, name, PluginTrigger::Degrade) {
                    warn!("插件 {} 跳过降级: {}", name, reason);
                    continue;
                }
            }
            info!("降级插件: {}", name);
            if let Err(e) = plugin.on_degrade().await {
                error!("插件 {} 降级异常: {}", name, e);
                self.fault_plugin(plugin, &format!("降级失败: {e}")).await;
                continue;
            }
            let mut states = self.states_locked();
            let _ = self.apply(&mut states, name, PluginTrigger::DegradeOk);
        }
    }

    /// 恢复所有已降级的插件(按启动顺序:被依赖方先就绪)
    ///
    /// 非 Degraded 状态的插件跳过;恢复钩子失败的插件自动故障转移。
    pub async fn resume_all(&self) {
        let list = match &*self.started.lock().unwrap() {
            StartedRecord::Running(list) => list.clone(),
            _ => return,
        };
        for plugin in list.iter() {
            let name = plugin.name();
            {
                let mut states = self.states_locked();
                if let Err(reason) = self.apply(&mut states, name, PluginTrigger::Resume) {
                    warn!("插件 {} 跳过恢复: {}", name, reason);
                    continue;
                }
            }
            info!("恢复插件: {}", name);
            if let Err(e) = plugin.on_resume().await {
                error!("插件 {} 恢复异常: {}", name, e);
                self.fault_plugin(plugin, &format!("恢复失败: {e}")).await;
                continue;
            }
            let mut states = self.states_locked();
            let _ = self.apply(&mut states, name, PluginTrigger::ResumeOk);
        }
    }

    /// 手动将指定插件转入故障状态并执行 `on_fault` 清理钩子
    ///
    /// 返回 `false` 表示插件未知或当前状态不可故障转移(如未启动);
    /// 对已 Faulted 的插件幂等返回 `true`。
    pub async fn fault(&self, name: &str) -> bool {
        let Some(plugin) = self.plugins.iter().find(|p| p.name() == name) else {
            warn!("fault: 未知插件 {}", name);
            return false;
        };
        match self.state(name) {
            Some(PluginState::Faulted) => true, // 幂等
            Some(PluginState::Stopped) => {
                warn!("插件 {} 未启动,无可故障转移", name);
                false
            }
            Some(_) => {
                self.fault_plugin(plugin, "手动触发").await;
                true
            }
            None => false,
        }
    }

    /// 将故障插件重置为 Stopped,允许重新走启动流程
    ///
    /// 返回 `false` 表示插件未知或状态机拒绝(非 Faulted 不可重置)。
    pub fn reset(&self, name: &str) -> bool {
        if !self.plugins.iter().any(|p| p.name() == name) {
            return false;
        }
        let mut states = self.states_locked();
        self.apply(&mut states, name, PluginTrigger::Reset).is_ok()
    }

    /// 将单个插件转入 Faulted 并执行故障清理钩子(状态先行,钩子随后,均尽力而为)
    async fn fault_plugin(&self, plugin: &Arc<dyn Plugin>, reason: &str) {
        {
            let mut states = self.states_locked();
            if let Err(r) = self.apply(&mut states, plugin.name(), PluginTrigger::Fault) {
                warn!("插件 {} 故障转移被拒绝: {}", plugin.name(), r);
                return;
            }
        }
        error!("插件 {} 进入故障状态: {}", plugin.name(), reason);
        if let Err(e) = plugin.on_fault().await {
            error!("插件 {} 故障清理钩子异常: {}", plugin.name(), e);
        }
    }

    /// Kahn 算法拓扑排序,检测循环依赖
    ///
    /// 在依赖关系相同(入度均为 0)的插件中,按 `priority()` 升序选取,
    /// 优先级相同时按注册顺序(稳定排序)。
    fn topological_sort(&self) -> Result<Vec<Arc<dyn Plugin>>> {
        // 先校验重名:重名会导致 name_to_idx 后者覆盖前者,破坏依赖解析
        self.check_duplicate_names()
            .map_err(crate::error::Error::Config)?;

        let name_to_idx: HashMap<&str, usize> = self
            .plugins
            .iter()
            .enumerate()
            .map(|(i, p)| (p.name(), i))
            .collect();

        let count = self.plugins.len();
        let mut in_degree = vec![0usize; count];
        let mut adj = vec![Vec::new(); count];

        for (i, plugin) in self.plugins.iter().enumerate() {
            for dep in plugin.depends_on() {
                match name_to_idx.get(dep) {
                    Some(&j) => {
                        adj[j].push(i);
                        in_degree[i] += 1;
                    }
                    // 依赖未注册时明确报错
                    None => {
                        return Err(crate::error::Error::Config(format!(
                            "插件 {} 依赖的插件 {} 未注册",
                            plugin.name(),
                            dep
                        )));
                    }
                }
            }
        }

        // 收集初始入度为 0 的插件
        let mut ready: Vec<usize> = (0..count).filter(|&i| in_degree[i] == 0).collect();
        // 升序排列:priority 数值小的在前,同优先级保持注册顺序(稳定排序)
        ready.sort_by_key(|&idx| self.plugins[idx].priority());

        let mut sorted = Vec::with_capacity(count);
        while !ready.is_empty() {
            // remove(0) 取优先级数值最小的就绪插件(最先启动)
            let u = ready.remove(0);
            sorted.push(Arc::clone(&self.plugins[u]));
            let mut newly_ready = Vec::new();
            for &v in &adj[u] {
                in_degree[v] -= 1;
                if in_degree[v] == 0 {
                    newly_ready.push(v);
                }
            }
            if !newly_ready.is_empty() {
                ready.extend(newly_ready);
                ready.sort_by_key(|&idx| self.plugins[idx].priority());
            }
        }

        if sorted.len() != count {
            // 检测循环依赖
            let cycle: Vec<&str> = self
                .plugins
                .iter()
                .enumerate()
                .filter(|(i, _)| in_degree[*i] > 0)
                .map(|(_, p)| p.name())
                .collect();
            return Err(crate::error::Error::Config(format!(
                "插件循环依赖: {:?}",
                cycle
            )));
        }

        Ok(sorted)
    }

    /// 确保插件之间没有 name 冲突
    pub fn check_duplicate_names(&self) -> std::result::Result<(), String> {
        let mut seen = HashSet::new();
        for p in &self.plugins {
            if !seen.insert(p.name()) {
                return Err(format!("插件名重复: {}", p.name()));
            }
        }
        Ok(())
    }
}

impl Default for PluginManager {
    fn default() -> Self {
        Self::new()
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use async_trait::async_trait;
    use parking_lot::Mutex;
    use std::sync::Arc;

    struct TestPlugin {
        name: &'static str,
        deps: &'static [&'static str],
        prio: i32,
        order: Arc<Mutex<Vec<String>>>,
    }

    #[async_trait]
    impl Plugin for TestPlugin {
        fn name(&self) -> &str {
            self.name
        }
        async fn start(&self) -> Result<()> {
            self.order.lock().push(format!("start:{}", self.name));
            Ok(())
        }
        async fn stop(&self) -> Result<()> {
            self.order.lock().push(format!("stop:{}", self.name));
            Ok(())
        }
        fn depends_on(&self) -> &[&str] {
            self.deps
        }
        fn priority(&self) -> i32 {
            self.prio
        }
    }

    #[tokio::test]
    async fn test_topological_start() {
        let order = Arc::new(Mutex::new(Vec::new()));

        let mgr = PluginManager::new()
            .add(TestPlugin {
                name: "c",
                deps: &["a", "b"],
                prio: 100,
                order: order.clone(),
            })
            .add(TestPlugin {
                name: "b",
                deps: &["a"],
                prio: 100,
                order: order.clone(),
            })
            .add(TestPlugin {
                name: "a",
                deps: &[],
                prio: 100,
                order: order.clone(),
            });

        mgr.start_all().await.unwrap();

        let log = order.lock();
        assert_eq!(log[0], "start:a");
        assert_eq!(log[1], "start:b");
        assert_eq!(log[2], "start:c");
    }

    #[tokio::test]
    async fn test_cycle_detection() {
        let order = Arc::new(Mutex::new(Vec::new()));

        let mgr = PluginManager::new()
            .add(TestPlugin {
                name: "x",
                deps: &["y"],
                prio: 100,
                order: order.clone(),
            })
            .add(TestPlugin {
                name: "y",
                deps: &["x"],
                prio: 100,
                order: order.clone(),
            });

        let result = mgr.start_all().await;
        assert!(result.is_err());
    }

    #[tokio::test]
    async fn test_stop_reverses_topological_order() {
        let order = Arc::new(Mutex::new(Vec::new()));

        // 注册顺序与拓扑顺序不同:c → b → a,但拓扑启动顺序为 a → b → c
        let mgr = PluginManager::new()
            .add(TestPlugin {
                name: "c",
                deps: &["a", "b"],
                prio: 100,
                order: order.clone(),
            })
            .add(TestPlugin {
                name: "b",
                deps: &["a"],
                prio: 100,
                order: order.clone(),
            })
            .add(TestPlugin {
                name: "a",
                deps: &[],
                prio: 100,
                order: order.clone(),
            });

        mgr.start_all().await.unwrap();
        mgr.stop_all().await;

        let log = order.lock();
        assert_eq!(log[0], "start:a");
        assert_eq!(log[1], "start:b");
        assert_eq!(log[2], "start:c");
        // 关闭必须是启动顺序的严格逆序,而不是注册顺序的逆序(c、b、a)
        assert_eq!(log[3], "stop:c");
        assert_eq!(log[4], "stop:b");
        assert_eq!(log[5], "stop:a");
    }

    struct FailOnStartPlugin {
        name: &'static str,
        fail: bool,
        order: Arc<Mutex<Vec<String>>>,
    }

    #[async_trait]
    impl Plugin for FailOnStartPlugin {
        fn name(&self) -> &str {
            self.name
        }
        async fn start(&self) -> Result<()> {
            self.order.lock().push(format!("start:{}", self.name));
            if self.fail {
                Err(crate::error::Error::Config(format!(
                    "{} 启动失败(测试)",
                    self.name
                )))
            } else {
                Ok(())
            }
        }
        async fn stop(&self) -> Result<()> {
            self.order.lock().push(format!("stop:{}", self.name));
            Ok(())
        }
    }

    #[tokio::test]
    async fn test_partial_start_rolls_back() {
        let order = Arc::new(Mutex::new(Vec::new()));

        let mgr = PluginManager::new()
            .add(FailOnStartPlugin {
                name: "a",
                fail: false,
                order: order.clone(),
            })
            .add(FailOnStartPlugin {
                name: "b",
                fail: true,
                order: order.clone(),
            });

        let result = mgr.start_all().await;
        assert!(result.is_err());

        // a 已启动,b 失败后必须回滚 a(stop:a)
        {
            let log = order.lock();
            assert_eq!(log[0], "start:a");
            assert_eq!(log[1], "start:b");
            assert_eq!(log[2], "stop:a");
            assert_eq!(log.len(), 3);
        }

        // 回滚后停机列表清空:再次 stop 不重复关闭
        mgr.stop_all().await;
        assert_eq!(order.lock().len(), 3);
    }

    #[tokio::test]
    async fn test_repeated_start_stop() {
        let order = Arc::new(Mutex::new(Vec::new()));

        let mgr = PluginManager::new().add(TestPlugin {
            name: "a",
            deps: &[],
            prio: 100,
            order: order.clone(),
        });

        mgr.start_all().await.unwrap();
        mgr.stop_all().await;
        // 重复 start/stop 不 panic、不重复关闭
        mgr.start_all().await.unwrap();
        mgr.stop_all().await;

        let log = order.lock();
        assert_eq!(&*log, &["start:a", "stop:a", "start:a", "stop:a"]);
    }

    #[tokio::test]
    async fn test_priority_ordering() {
        let order = Arc::new(Mutex::new(Vec::new()));

        // 三个插件无依赖关系,靠 priority 控制启动顺序:
        // prio=10 先启动,prio=50 其次,prio=200 最后
        let mgr = PluginManager::new()
            .add(TestPlugin {
                name: "late",
                deps: &[],
                prio: 200,
                order: order.clone(),
            })
            .add(TestPlugin {
                name: "early",
                deps: &[],
                prio: 10,
                order: order.clone(),
            })
            .add(TestPlugin {
                name: "mid",
                deps: &[],
                prio: 50,
                order: order.clone(),
            });

        mgr.start_all().await.unwrap();

        let log = order.lock();
        assert_eq!(log[0], "start:early"); // prio=10 最小,最先启动
        assert_eq!(log[1], "start:mid"); // prio=50
        assert_eq!(log[2], "start:late"); // prio=200 最大,最后启动
    }

    #[test]
    fn duplicate_names_rejected() {
        let order = Arc::new(Mutex::new(Vec::new()));
        let mgr = PluginManager::new()
            .add(TestPlugin { name: "dup", deps: &[], prio: 0, order: order.clone() })
            .add(TestPlugin { name: "dup", deps: &[], prio: 0, order: order.clone() });
        assert!(mgr.check_duplicate_names().is_err());
        // start_all 内部同样校验重名
        assert!(futures_block(mgr.start_all()).is_err());
    }

    #[test]
    fn missing_dependency_rejected() {
        let order = Arc::new(Mutex::new(Vec::new()));
        let mgr = PluginManager::new()
            .add(TestPlugin { name: "a", deps: &["ghost"], prio: 0, order: order.clone() });
        let err = futures_block(mgr.start_all()).unwrap_err();
        assert!(err.to_string().contains("ghost"));
    }

    #[test]
    fn stop_all_without_start_falls_back_to_registry_reverse() {
        let order = Arc::new(Mutex::new(Vec::new()));
        let mgr = PluginManager::new()
            .add(TestPlugin { name: "a", deps: &[], prio: 0, order: order.clone() })
            .add(TestPlugin { name: "b", deps: &[], prio: 0, order: order.clone() });
        // 未 start 直接 stop:按注册列表逆序关闭
        futures_block(mgr.stop_all());
        assert_eq!(&*order.lock(), &["stop:b", "stop:a"]);
    }

    #[test]
    fn add_discovered_collects_arc_plugins() {
        let order = Arc::new(Mutex::new(Vec::new()));
        let p: Arc<dyn Plugin> = Arc::new(TestPlugin {
            name: "discovered",
            deps: &[],
            prio: 0,
            order: order.clone(),
        });
        let mgr = PluginManager::new().add_discovered(vec![p]);
        assert_eq!(mgr.check_duplicate_names(), Ok(()));
        futures_block(mgr.start_all()).unwrap();
        assert_eq!(&*order.lock(), &["start:discovered"]);
    }

    #[tokio::test]
    async fn arc_plugin_forwards_methods() {
        let order = Arc::new(Mutex::new(Vec::new()));
        let inner = Arc::new(TestPlugin { name: "wrapped", deps: &[], prio: 7, order: order.clone() });
        let arc: Arc<dyn Plugin> = inner.clone();
        assert_eq!(arc.name(), "wrapped");
        assert_eq!(arc.priority(), 7);
        assert!(arc.depends_on().is_empty());
        arc.start().await.unwrap();
        arc.stop().await.unwrap();
        assert_eq!(&*order.lock(), &["start:wrapped", "stop:wrapped"]);
    }

    #[test]
    fn default_manager() {
        let mgr = PluginManager::default();
        assert!(mgr.check_duplicate_names().is_ok());
    }

    // ── 生命周期状态机集成测试 ────────────────────────────────

    /// 带降级/恢复/故障钩子的测试插件
    struct LifecyclePlugin {
        name: &'static str,
        fail_degrade: bool,
        fail_resume: bool,
        order: Arc<Mutex<Vec<String>>>,
    }

    #[async_trait]
    impl Plugin for LifecyclePlugin {
        fn name(&self) -> &str {
            self.name
        }
        async fn start(&self) -> Result<()> {
            self.order.lock().push(format!("start:{}", self.name));
            Ok(())
        }
        async fn stop(&self) -> Result<()> {
            self.order.lock().push(format!("stop:{}", self.name));
            Ok(())
        }
        async fn on_degrade(&self) -> Result<()> {
            self.order.lock().push(format!("degrade:{}", self.name));
            if self.fail_degrade {
                Err(crate::error::Error::Config("降级失败(测试)".into()))
            } else {
                Ok(())
            }
        }
        async fn on_resume(&self) -> Result<()> {
            self.order.lock().push(format!("resume:{}", self.name));
            if self.fail_resume {
                Err(crate::error::Error::Config("恢复失败(测试)".into()))
            } else {
                Ok(())
            }
        }
        async fn on_fault(&self) -> Result<()> {
            self.order.lock().push(format!("fault:{}", self.name));
            Ok(())
        }
    }

    #[tokio::test]
    async fn degrade_resume_lifecycle_transitions() {
        let order = Arc::new(Mutex::new(Vec::new()));
        let mgr = PluginManager::new()
            .add(LifecyclePlugin {
                name: "a",
                fail_degrade: false,
                fail_resume: false,
                order: order.clone(),
            })
            .add(LifecyclePlugin {
                name: "b",
                fail_degrade: false,
                fail_resume: false,
                order: order.clone(),
            });

        mgr.start_all().await.unwrap();
        assert_eq!(mgr.state("a"), Some(PluginState::Running));
        assert_eq!(mgr.state("unknown"), None, "未知插件返回 None");

        mgr.degrade_all().await;
        assert_eq!(mgr.state("a"), Some(PluginState::Degraded));
        assert!(mgr.state("a").unwrap().is_available(), "降级仍可用");
        assert!(!mgr.state("a").unwrap().is_running());

        mgr.resume_all().await;
        assert_eq!(mgr.state("a"), Some(PluginState::Running));

        // 降级后 stop:Degraded + Stop 合法
        mgr.degrade_all().await;
        mgr.stop_all().await;
        assert_eq!(mgr.state("a"), Some(PluginState::Stopped));

        assert_eq!(
            &*order.lock(),
            &[
                "start:a", "start:b",
                // degrade 逆序(依赖方 b 先降级),resume 正序(被依赖方 a 先就绪)
                "degrade:b", "degrade:a", "resume:a", "resume:b",
                "degrade:b", "degrade:a",
                // stop 逆序(后启动的先关闭)
                "stop:b", "stop:a"
            ]
        );
    }

    #[tokio::test]
    async fn degrade_order_is_reverse_of_start_order() {
        struct DepPlugin {
            name: &'static str,
            deps: &'static [&'static str],
            order: Arc<Mutex<Vec<String>>>,
        }
        #[async_trait]
        impl Plugin for DepPlugin {
            fn name(&self) -> &str {
                self.name
            }
            fn depends_on(&self) -> &[&str] {
                self.deps
            }
            async fn start(&self) -> Result<()> {
                Ok(())
            }
            async fn stop(&self) -> Result<()> {
                Ok(())
            }
            async fn on_degrade(&self) -> Result<()> {
                self.order.lock().push(format!("degrade:{}", self.name));
                Ok(())
            }
        }

        let order = Arc::new(Mutex::new(Vec::new()));
        let mgr = PluginManager::new()
            .add(DepPlugin { name: "a", deps: &[], order: order.clone() })
            .add(DepPlugin { name: "b", deps: &["a"], order: order.clone() });
        mgr.start_all().await.unwrap();
        mgr.degrade_all().await;
        // b(依赖方)先降级,a(被依赖方)后降级
        assert_eq!(&*order.lock(), &["degrade:b", "degrade:a"]);
    }

    #[tokio::test]
    async fn degrade_failure_triggers_fault_transfer() {
        let order = Arc::new(Mutex::new(Vec::new()));
        let mgr = PluginManager::new().add(LifecyclePlugin {
            name: "a",
            fail_degrade: true,
            fail_resume: false,
            order: order.clone(),
        });

        mgr.start_all().await.unwrap();
        mgr.degrade_all().await;

        // 降级失败 → 自动故障转移:on_fault 被调用、状态 Faulted
        assert_eq!(mgr.state("a"), Some(PluginState::Faulted));
        assert!(order.lock().contains(&"fault:a".to_string()));

        // 故障插件不可再降级/恢复,stop 兜底可关闭
        mgr.resume_all().await;
        assert_eq!(mgr.state("a"), Some(PluginState::Faulted));
        mgr.stop_all().await;
        assert_eq!(mgr.state("a"), Some(PluginState::Stopped));
    }

    #[tokio::test]
    async fn resume_failure_triggers_fault_transfer() {
        let order = Arc::new(Mutex::new(Vec::new()));
        let mgr = PluginManager::new().add(LifecyclePlugin {
            name: "a",
            fail_degrade: false,
            fail_resume: true,
            order: order.clone(),
        });

        mgr.start_all().await.unwrap();
        mgr.degrade_all().await;
        mgr.resume_all().await;

        assert_eq!(mgr.state("a"), Some(PluginState::Faulted));
        assert!(order.lock().contains(&"fault:a".to_string()));
    }

    #[tokio::test]
    async fn manual_fault_and_reset_allow_restart() {
        let order = Arc::new(Mutex::new(Vec::new()));
        let mgr = PluginManager::new().add(LifecyclePlugin {
            name: "a",
            fail_degrade: false,
            fail_resume: false,
            order: order.clone(),
        });

        mgr.start_all().await.unwrap();

        // 未启动插件不可 fault、未知插件返回 false
        assert!(!mgr.fault("ghost").await);

        assert!(mgr.fault("a").await);
        assert_eq!(mgr.state("a"), Some(PluginState::Faulted));
        assert!(order.lock().contains(&"fault:a".to_string()));
        // 对已 Faulted 插件幂等
        assert!(mgr.fault("a").await);

        // Faulted 直接 start 被拒;reset 后可重新启动
        mgr.start_all().await.unwrap();
        assert_eq!(mgr.state("a"), Some(PluginState::Faulted), "Faulted 跳过启动");
        assert!(mgr.reset("a"));
        assert_eq!(mgr.state("a"), Some(PluginState::Stopped));
        assert!(!mgr.reset("a"), "非 Faulted 不可重置");

        mgr.start_all().await.unwrap();
        assert_eq!(mgr.state("a"), Some(PluginState::Running));
        let starts = order.lock().iter().filter(|e| e.as_str() == "start:a").count();
        assert_eq!(starts, 2, "reset 后重新执行了 start 钩子");
    }

    #[tokio::test]
    async fn start_failure_marks_plugin_faulted() {
        let order = Arc::new(Mutex::new(Vec::new()));
        let mgr = PluginManager::new()
            .add(FailOnStartPlugin { name: "ok", fail: true, order: order.clone() });
        // fail=true:启动即失败 → Faulted(而非 Stopped)
        assert!(mgr.start_all().await.is_err());
        assert_eq!(mgr.state("ok"), Some(PluginState::Faulted));
        assert!(!mgr.state("ok").unwrap().is_available());
    }

    #[tokio::test]
    async fn double_start_is_rejected_by_state_gate() {
        let order = Arc::new(Mutex::new(Vec::new()));
        let mgr = PluginManager::new().add(LifecyclePlugin {
            name: "a",
            fail_degrade: false,
            fail_resume: false,
            order: order.clone(),
        });

        mgr.start_all().await.unwrap();
        // 二次 start_all:状态机拒绝,start 钩子不重复执行
        mgr.start_all().await.unwrap();
        assert_eq!(mgr.state("a"), Some(PluginState::Running));
        assert_eq!(order.lock().iter().filter(|e| e.as_str() == "start:a").count(), 1);

        // 二次 start_all 不得清空启动记录:stop_all 仍能关闭插件(恰好一次)
        mgr.stop_all().await;
        assert_eq!(mgr.state("a"), Some(PluginState::Stopped));
        assert_eq!(order.lock().iter().filter(|e| e.as_str() == "stop:a").count(), 1);
    }

    #[tokio::test]
    async fn double_stop_does_not_rerun_hooks() {
        let order = Arc::new(Mutex::new(Vec::new()));
        let mgr = PluginManager::new().add(TestPlugin {
            name: "a",
            deps: &[],
            prio: 100,
            order: order.clone(),
        });
        mgr.start_all().await.unwrap();
        mgr.stop_all().await;
        // 已停止后重复 stop_all 为空操作,不再执行 stop 钩子
        mgr.stop_all().await;
        assert_eq!(&*order.lock(), &["start:a", "stop:a"]);
    }

    #[tokio::test]
    async fn restart_after_fault_keeps_stop_record_consistent() {
        let order = Arc::new(Mutex::new(Vec::new()));
        let mgr = PluginManager::new()
            .add(LifecyclePlugin { name: "a", fail_degrade: false, fail_resume: false, order: order.clone() })
            .add(LifecyclePlugin { name: "b", fail_degrade: false, fail_resume: false, order: order.clone() });
        mgr.start_all().await.unwrap();
        assert!(mgr.fault("a").await);
        assert!(mgr.reset("a"));
        // 仅 a 重新启动,b 保持运行;合并记录须去重,a 不得出现两次
        mgr.start_all().await.unwrap();
        mgr.stop_all().await;
        let stops: Vec<String> = order.lock().iter().filter(|e| e.starts_with("stop:")).cloned().collect();
        // a 重启后位于记录末尾,逆序先关 a 再关 b;每个插件恰好关闭一次
        assert_eq!(stops, vec!["stop:a".to_string(), "stop:b".to_string()]);
    }

    /// 在无 async 测试中驱动一个 future(简化:用 tokio runtime 手工 block_on)
    fn futures_block<F: std::future::Future>(fut: F) -> F::Output {
        tokio::runtime::Builder::new_current_thread()
            .enable_all()
            .build()
            .unwrap()
            .block_on(fut)
    }
}