garrison 0.9.0

Garrison - 面向 Rust 生态的一站式身份认证鉴权框架
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
// Copyright (c) 2026 Kirky.X🌠
// SPDX-License-Identifier: Apache-2.0

//! 事件派发事务绑定(OnCommit 语义)——`GarrisonEventTx` RAII 事务 guard。
//!
//! 解决「写库 + 广播事件」不一致的问题:事件缓冲在 guard 中,事务 commit 成功后才派发;
//! rollback 或未 commit 丢弃 guard 时缓冲事件随之丢弃。
//!
//! # 事务路由边界
//!
//! - 经 guard `execute`(内部 `Session::execute_raw`)的 SQL **加入本事务**(in-tx 路由)。
//! - 既有 DAO / Repository 经 `session.connection()` 的 SQL **不加入本事务**(auto-commit),混用由调用方保证顺序。
//! - DDL 不可经 `execute` 执行;`execute` 为 admin 特权直通通道(dbnexus 对 admin 跳过全部表级权限检查,且 SQL 解析
//!   失败同样放行)——`sql` 内容即权限边界,禁止拼接不可信输入,详见 [`GarrisonEventTx::execute`] 的 `# Security` 段。
//!
//! # 生命周期(状态机在类型层面表达「提交后不可再用」)
//!
//! ```text
//! begin ──→ on_commit / execute(可重复) ──→ commit(mut self)   → 派发缓冲事件
//!                                        └─→ rollback(mut self) → 丢弃缓冲事件
//! 未 commit / rollback 即 drop ──→ 缓冲丢弃 + tracing::warn(uncommitted 原因)
//!                                  + 依赖 dbnexus 级联回滚(Session Drop 归还连接)
//! commit 失败 ──→ 返回 Err + 缓冲丢弃 + tracing::warn(commit-failed 原因)
//! commit 成功后派发中途被取消 ──→ 剩余丢弃 + tracing::warn(dispatch-cancelled
//!                                  原因,携带已派发/总数)
//! ```
//!
//! # 并发 guard 的锁等待语义(生产后端)
//!
//! 并发 guard 各持独立 Session = 独立事务:postgres / mysql 下触碰同一行将持行锁直至 `commit`
//!(锁窗口显著长于 auto-commit);sqlite 文件库并发写会 `SQLITE_BUSY`。begin→commit 之间只放该事务强相关的写与逻辑。
//!
//! # async 取消窗口(已知边界)
//!
//! 派发游标逐事件推进:中途取消时 `Drop` 以 dispatch-cancelled 原因 warn,但两个残余窗口无法精确归因——
//! 取消点恰在 `session.commit().await` 期间(DB 是否已提交不可知,按 commit-failed warn);取消点恰在最后一个
//! 事件的派发 await 期间(在途事件是否到达 listener 不可知)。`Drop` 告警网保证丢弃可见,不保证精确归因。
//!
//! # 典型用法
//!
//! ```rust,ignore
//! let mut tx = GarrisonEventTx::begin(&pool, listener_manager).await?;
//! tx.execute("INSERT INTO app_login_log (...) VALUES (...)").await?;
//! tx.on_commit(GarrisonEvent::Login { .. });
//! let outcome = tx.commit().await?; // DB 提交成功后才派发事件
//! ```

use crate::error::{GarrisonError, GarrisonResult};
// 依赖方向单向:事务 guard 归 dao、依赖 listener;listener 生产代码不反向依赖
// dao(audit.rs 有意持 DbPool 直连),防止未来出现模块环。
use crate::listener::{DispatchOutcome, GarrisonEvent, GarrisonListenerManager};
use dbnexus::DbPool;
use std::sync::Arc;

/// 事件派发事务 guard(OnCommit 语义)。
///
/// 持有一个独立的 dbnexus `Session`(从 `DbPool` 获取)与监听器管理器引用,
/// 缓冲 `GarrisonEvent` 至 commit 成功后派发。参阅[模块文档](super)了解
/// 事务路由边界与生命周期。
pub struct GarrisonEventTx {
    /// 事务会话;`commit`/`rollback` 时 `take`,`None` 表示已终结。
    session: Option<dbnexus::Session>,
    /// OnCommit 档派发通道。
    lm: Arc<GarrisonListenerManager>,
    /// 缓冲事件(FIFO)。
    buffer: Vec<GarrisonEvent>,
    /// DB commit 是否已成功;`Drop` 据此区分 commit-failed 与派发取消两种丢弃。
    committed: bool,
    /// 已完成派发的缓冲前缀长度(派发游标);commit 成功后逐事件推进,
    /// future 被取消时停在原位,供 `Drop` 判定「已派发/总数」。
    dispatched: usize,
}

impl GarrisonEventTx {
    /// 从池获取独立 Session 并开启事务(固定 `"admin"` 角色:进程内框架通道,非用户输入,绕过表级权限检查);begin 失败返回 `Err` 不产生 guard。
    pub async fn begin(pool: &DbPool, lm: Arc<GarrisonListenerManager>) -> GarrisonResult<Self> {
        let session = pool
            .get_session("admin")
            .await
            .map_err(|e| GarrisonError::Dao(format!("event-tx-get-session::{}", e)))?;
        session
            .begin_transaction()
            .await
            .map_err(|e| GarrisonError::Dao(format!("event-tx-begin::{}", e)))?;
        Ok(Self {
            session: Some(session),
            lm,
            buffer: Vec::new(),
            committed: false,
            dispatched: 0,
        })
    }

    /// 缓冲事件,commit 成功后按 FIFO 顺序派发。
    pub fn on_commit(&mut self, event: GarrisonEvent) {
        self.buffer.push(event);
    }

    /// 在本事务内执行写 SQL(INSERT / UPDATE / DELETE),返回受影响行数;仅经 guard 的写加入本事务
    ///(DAO / Repository 经 `session.connection()` 的 SQL 为 auto-commit,不加入)。
    ///
    /// # Security(特权直通通道)
    ///
    /// `begin` 以固定 `"admin"` 角色建 Session,dbnexus 对 admin **跳过全部表级权限检查,且 SQL 解析失败同样放行**——
    /// `sql` 内容即权限边界:严禁拼接不可信输入;签名不支持占位符绑定(继承 `Session::execute_raw`),
    /// 含动态值的写应改用支持参数绑定的 DAO / Repository 通道,确需本通道时仅限框架内部受控 SQL。
    pub async fn execute(&self, sql: &str) -> GarrisonResult<u64> {
        let session = self
            .session
            .as_ref()
            .ok_or_else(|| GarrisonError::Internal("event-tx-already-finished".to_string()))?;
        let result = session
            .execute_raw(sql)
            .await
            .map_err(|e| GarrisonError::Dao(format!("event-tx-execute::{}", e)))?;
        Ok(result.rows_affected())
    }

    /// 提交事务(消耗 `self`,提交后不可再用——编译期保证)并按 FIFO 派发全部缓冲事件。
    ///
    /// commit 失败(含 dbnexus `Arc::try_unwrap` 并发冲突)返回 `Err`,缓冲不派发、随 guard 丢弃并由 `Drop` warn;
    /// 单个 listener `Err`/panic 不中断派发,计入 [`DispatchOutcome::failed`](审计链缺口显性化)。
    /// 派发中途 future 被取消时无返回值,`Drop` 以 dispatch-cancelled 原因 warn 已派发/总数。
    pub async fn commit(mut self) -> GarrisonResult<DispatchOutcome> {
        let session = self
            .session
            .take()
            .ok_or_else(|| GarrisonError::Internal("event-tx-already-finished".to_string()))?;
        session
            .commit()
            .await
            .map_err(|e| GarrisonError::Dao(format!("event-tx-commit::{}", e)))?;
        // 提交后立即归还池连接:dbnexus 仅在 Session Drop 时归还槽位,持有跨派发阶段会让
        // 同步审计 listener(audit.rs 直连同一池取连接)在并发 in-flight commit ≥ 池上限时
        // 等满 acquire_timeout 并计入 failed,放大本特性要消除的审计链缺口。
        drop(session);
        self.committed = true;
        let mut outcome = DispatchOutcome::default();
        for index in self.dispatched..self.buffer.len() {
            let one = self
                .lm
                .broadcast_after_commit(std::slice::from_ref(&self.buffer[index]))
                .await;
            outcome.dispatched += one.dispatched;
            outcome.failed += one.failed;
            self.dispatched = index + 1;
        }
        Ok(outcome)
    }

    /// 回滚事务(消耗 `self`)并丢弃全部缓冲事件——事件与未提交写同生共死,回滚结果不影响「事件不派发」语义。
    pub async fn rollback(mut self) -> GarrisonResult<()> {
        let session = self
            .session
            .take()
            .ok_or_else(|| GarrisonError::Internal("event-tx-already-finished".to_string()))?;
        self.buffer.clear();
        session
            .rollback()
            .await
            .map_err(|e| GarrisonError::Dao(format!("event-tx-rollback::{}", e)))?;
        Ok(())
    }
}

impl Drop for GarrisonEventTx {
    fn drop(&mut self) {
        // 兜底安全网:缓冲事件未派发即丢弃的三条路径都在此显性化——
        // (1) 未 commit/rollback 即 drop:打开事务随 SessionState drop 级联回滚(sqlx 语义),连接入池;
        // (2) commit() 失败后 guard 被消耗:session 已 take、buffer 非空且未 committed;
        // (3) commit 成功后派发中途被取消:游标停在中途,warn 已派发/总数让审计链缺口可见。
        let open_tx = self.session.take().is_some();
        if open_tx {
            let count = self.buffer.len().to_string();
            let kinds = event_summary(&self.buffer);
            tracing::warn!(
                "{}",
                crate::i18n::translate_detail(
                    "logs-event-tx-dropped-without-commit",
                    &[("count", count.as_str()), ("kinds", kinds.as_str())]
                )
            );
        } else if !self.buffer.is_empty() && !self.committed {
            let count = self.buffer.len().to_string();
            let kinds = event_summary(&self.buffer);
            tracing::warn!(
                "{}",
                crate::i18n::translate_detail(
                    "logs-event-tx-discarded-after-commit-failure",
                    &[("count", count.as_str()), ("kinds", kinds.as_str())]
                )
            );
        } else if self.committed && self.dispatched < self.buffer.len() {
            let dispatched = self.dispatched.to_string();
            let total = self.buffer.len().to_string();
            let kinds = event_summary(&self.buffer[self.dispatched..]);
            tracing::warn!(
                "{}",
                crate::i18n::translate_detail(
                    "logs-event-tx-dispatch-cancelled-after-commit",
                    &[
                        ("dispatched", dispatched.as_str()),
                        ("total", total.as_str()),
                        ("kinds", kinds.as_str()),
                    ]
                )
            );
        }
        self.buffer.clear();
    }
}

/// 事件丢弃 warn 的事件摘要:按变体名聚合计数(如 `Login=1, PermissionCheck=2`)。
/// `event_kind` 为穷尽 match(无 `_` 兜底),新增变体在此编译报错提醒;仅取变体名控制兜底日志体积。
fn event_summary(events: &[GarrisonEvent]) -> String {
    let mut counts: Vec<(&'static str, usize)> = Vec::new();
    for event in events {
        let kind = event_kind(event);
        match counts.iter_mut().find(|(k, _)| *k == kind) {
            Some((_, count)) => *count += 1,
            None => counts.push((kind, 1)),
        }
    }
    counts
        .iter()
        .map(|(kind, count)| format!("{kind}={count}"))
        .collect::<Vec<_>>()
        .join(", ")
}

/// [`GarrisonEvent`] 变体名(丢弃 warn 摘要用)。
fn event_kind(event: &GarrisonEvent) -> &'static str {
    match event {
        GarrisonEvent::Login { .. } => "Login",
        GarrisonEvent::Logout { .. } => "Logout",
        GarrisonEvent::Kickout { .. } => "Kickout",
        GarrisonEvent::PermissionCheck { .. } => "PermissionCheck",
        GarrisonEvent::RoleCheck { .. } => "RoleCheck",
        GarrisonEvent::TokenExpired { .. } => "TokenExpired",
        GarrisonEvent::LoginFailure { .. } => "LoginFailure",
        GarrisonEvent::PasswordRehashed { .. } => "PasswordRehashed",
        GarrisonEvent::TokenRefresh { .. } => "TokenRefresh",
        GarrisonEvent::RevokeToken { .. } => "RevokeToken",
        GarrisonEvent::SessionTimeout { .. } => "SessionTimeout",
        GarrisonEvent::AccountLocked { .. } => "AccountLocked",
        GarrisonEvent::FirewallBlock { .. } => "FirewallBlock",
        GarrisonEvent::Replaced { .. } => "Replaced",
        GarrisonEvent::ConfigReload { .. } => "ConfigReload",
        GarrisonEvent::SocialLogin { .. } => "SocialLogin",
        GarrisonEvent::TenantSwitch { .. } => "TenantSwitch",
        GarrisonEvent::TokenRotate { .. } => "TokenRotate",
        GarrisonEvent::TempCredentialConsumed { .. } => "TempCredentialConsumed",
        GarrisonEvent::InvitationCreated { .. } => "InvitationCreated",
        GarrisonEvent::InvitationRedeemed { .. } => "InvitationRedeemed",
        GarrisonEvent::InvitationRevoked { .. } => "InvitationRevoked",
        GarrisonEvent::QrLoginCreated { .. } => "QrLoginCreated",
        GarrisonEvent::QrLoginScanned { .. } => "QrLoginScanned",
        GarrisonEvent::QrLoginConfirmed { .. } => "QrLoginConfirmed",
        GarrisonEvent::QrLoginCancelled { .. } => "QrLoginCancelled",
        GarrisonEvent::DeviceBlock { .. } => "DeviceBlock",
        GarrisonEvent::DeviceUnblock { .. } => "DeviceUnblock",
        #[cfg(feature = "anomalous-detector-dual")]
        GarrisonEvent::AnomalousLoginDetected { .. } => "AnomalousLoginDetected",
        #[cfg(feature = "credit-metering")]
        GarrisonEvent::CreditConsumed { .. } => "CreditConsumed",
        #[cfg(feature = "credit-metering")]
        GarrisonEvent::CreditAlert { .. } => "CreditAlert",
    }
}

// 单元测试(事件派发事务绑定;覆盖 commit/rollback/drop 三路径、FIFO、并发、
// commit 失败与派发取消的 warn 捕获;listener 以运行时 register 注入 mock,绕开 inventory 污染)

#[cfg(all(test, feature = "db-sqlite", feature = "listener"))]
mod tests {
    use super::*;
    use crate::dao::{init_dbnexus, GarrisonMigration};
    use crate::listener::GarrisonListener;
    use async_trait::async_trait;
    use dbnexus::sea_orm::{ConnectionTrait, DbBackend, Statement};
    use parking_lot::Mutex;
    use std::path::PathBuf;

    /// 建池 + 项目 core 迁移 + 专用测试表,供事务写断言。
    async fn setup_pool() -> dbnexus::DbPool {
        let pool = init_dbnexus("sqlite::memory:")
            .await
            .expect("init_dbnexus 应成功");
        let migrations_dir = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
            .join("migrations")
            .join("sqlite");
        let migration = GarrisonMigration::with_base_dir(pool.clone(), migrations_dir);
        migration.migrate_core().await.expect("migrate_core 应成功");
        let session = pool.get_session("admin").await.expect("get_session 应成功");
        session
            .execute_raw_ddl(
                "CREATE TABLE garrison_event_tx_test \
                 (id INTEGER PRIMARY KEY, tag TEXT NOT NULL)",
            )
            .await
            .expect("建测试表应成功");
        drop(session);
        pool
    }

    /// 构造仅含 inventory 注册项 + 一个运行时 listener 的 manager。
    fn manager_with(listener: Arc<dyn GarrisonListener>) -> Arc<GarrisonListenerManager> {
        let lm = Arc::new(GarrisonListenerManager::new());
        lm.register(listener);
        lm
    }

    /// 新 Session 查询测试表内指定 tag 的行数(auto-commit 路径,验证事务结果)。
    async fn count_rows(pool: &dbnexus::DbPool, tag: &str) -> i64 {
        let session = pool.get_session("admin").await.expect("get_session 应成功");
        let conn = session.connection().expect("connection 应可用");
        let stmt = Statement::from_sql_and_values(
            DbBackend::Sqlite,
            "SELECT count(*) AS cnt FROM garrison_event_tx_test WHERE tag = ?",
            vec![tag.to_string().into()],
        );
        let row = conn
            .query_one_raw(stmt)
            .await
            .expect("count 查询应成功")
            .expect("count 应返回一行");
        row.try_get::<i64>("", "cnt").expect("cnt 列应存在")
    }

    /// 记录到达事件的测试标签(运行时注册,绕开 inventory)。
    struct RecordingListener {
        tags: Mutex<Vec<String>>,
    }

    impl RecordingListener {
        fn new() -> Self {
            Self {
                tags: Mutex::new(Vec::new()),
            }
        }

        fn snapshot(&self) -> Vec<String> {
            self.tags.lock().clone()
        }
    }

    #[async_trait]
    impl GarrisonListener for RecordingListener {
        async fn on_event(&self, event: &GarrisonEvent) -> GarrisonResult<()> {
            self.tags.lock().push(event_tag(event));
            Ok(())
        }
    }

    /// 进入 `on_event` 即永久挂起的 listener:先经 oneshot 通知测试已到达派发 await 点,再 `pending()` 永不返回,
    /// 使 commit future 停在派发期间直至被取消。
    struct BlockingListener {
        entered: Mutex<Option<tokio::sync::oneshot::Sender<()>>>,
    }

    #[async_trait]
    impl GarrisonListener for BlockingListener {
        async fn on_event(&self, _event: &GarrisonEvent) -> GarrisonResult<()> {
            if let Some(tx) = self.entered.lock().take() {
                let _ = tx.send(());
            }
            std::future::pending::<()>().await;
            Ok(())
        }
    }

    /// 事件测试标签:FIFO 顺序与到达断言的鉴别符。
    fn event_tag(event: &GarrisonEvent) -> String {
        match event {
            GarrisonEvent::Login { login_id, .. } => format!("login:{login_id}"),
            GarrisonEvent::PermissionCheck { permission, .. } => {
                format!("perm:{permission}")
            },
            GarrisonEvent::Logout { login_id, .. } => format!("logout:{login_id}"),
            _ => "other".to_string(),
        }
    }

    fn login_event(login_id: &str) -> GarrisonEvent {
        GarrisonEvent::Login {
            login_id: login_id.to_string(),
            token: "T1".to_string(),
            device: None,
            request_context: None,
        }
    }

    fn perm_event(permission: &str) -> GarrisonEvent {
        GarrisonEvent::PermissionCheck {
            login_id: "1001".to_string(),
            permission: permission.to_string(),
            request_context: None,
        }
    }

    /// commit 后才派发 + 写与事件同事务(listener 在 commit 前未收到、commit 后收到,且 DB 行存在)。
    #[tokio::test(flavor = "multi_thread")]
    async fn commit_dispatches_after_db_commit() {
        let pool = setup_pool().await;
        let recorder = Arc::new(RecordingListener::new());
        let lm = manager_with(recorder.clone());

        let mut guard = GarrisonEventTx::begin(&pool, lm)
            .await
            .expect("begin 应成功");
        guard.on_commit(login_event("1001"));
        assert!(
            recorder.snapshot().is_empty(),
            "commit 前 listener 不应收到缓冲事件"
        );

        let affected = guard
            .execute("INSERT INTO garrison_event_tx_test (id, tag) VALUES (1, 'committed')")
            .await
            .expect("事务内 INSERT 应成功");
        assert_eq!(affected, 1, "INSERT 应影响 1 行");

        guard.commit().await.expect("commit 应成功");

        assert_eq!(
            recorder.snapshot(),
            vec!["login:1001".to_string()],
            "commit 后 listener 应恰好收到缓冲的 Login 事件"
        );
        assert_eq!(
            count_rows(&pool, "committed").await,
            1,
            "事务提交后写入的行应可见"
        );
    }

    /// rollback 丢弃缓冲事件与事务写(listener 未收到,新 Session 查 count == 0)。
    #[tokio::test(flavor = "multi_thread")]
    async fn rollback_discards_events_and_writes() {
        let pool = setup_pool().await;
        let recorder = Arc::new(RecordingListener::new());
        let lm = manager_with(recorder.clone());

        let mut guard = GarrisonEventTx::begin(&pool, lm)
            .await
            .expect("begin 应成功");
        guard.on_commit(login_event("2001"));
        guard
            .execute("INSERT INTO garrison_event_tx_test (id, tag) VALUES (2, 'rolled-back')")
            .await
            .expect("事务内 INSERT 应成功");

        guard.rollback().await.expect("rollback 应成功");

        assert!(
            recorder.snapshot().is_empty(),
            "rollback 后缓冲事件不应派发"
        );
        assert_eq!(
            count_rows(&pool, "rolled-back").await,
            0,
            "回滚后事务内写入的行不应存在"
        );
    }

    /// 未 commit/rollback 即 drop 的 RAII 安全网:listener 未收到、事务写经 dbnexus 级联回滚不可见(Drop 仅 warn 不 panic)。
    #[tokio::test(flavor = "multi_thread")]
    async fn drop_without_commit_is_safe() {
        let pool = setup_pool().await;
        let recorder = Arc::new(RecordingListener::new());
        let lm = manager_with(recorder.clone());

        let mut guard = GarrisonEventTx::begin(&pool, lm)
            .await
            .expect("begin 应成功");
        guard.on_commit(login_event("3001"));
        guard
            .execute("INSERT INTO garrison_event_tx_test (id, tag) VALUES (3, 'dropped')")
            .await
            .expect("事务内 INSERT 应成功");
        drop(guard);

        assert!(
            recorder.snapshot().is_empty(),
            "未提交即 drop,缓冲事件不应派发"
        );
        assert_eq!(
            count_rows(&pool, "dropped").await,
            0,
            "级联回滚后事务内写入的行不应存在"
        );
    }

    /// OnCommit 派发顺序为 FIFO(listener 到达顺序 == 缓冲顺序)。
    #[tokio::test(flavor = "multi_thread")]
    async fn dispatch_order_is_fifo() {
        let pool = setup_pool().await;
        let recorder = Arc::new(RecordingListener::new());
        let lm = manager_with(recorder.clone());

        let mut guard = GarrisonEventTx::begin(&pool, lm)
            .await
            .expect("begin 应成功");
        guard.on_commit(perm_event("p1"));
        guard.on_commit(perm_event("p2"));
        guard.on_commit(perm_event("p3"));
        guard.commit().await.expect("commit 应成功");

        assert_eq!(
            recorder.snapshot(),
            vec![
                "perm:p1".to_string(),
                "perm:p2".to_string(),
                "perm:p3".to_string()
            ],
            "派发顺序应与缓冲顺序一致(FIFO)"
        );
    }

    /// 并发 guard 无串扰:各自 listener 恰好收到各自事件,各自事务写各自可见。
    #[tokio::test(flavor = "multi_thread")]
    async fn concurrent_txs_no_crosstalk() {
        let pool_a = setup_pool().await;
        let pool_b = setup_pool().await;
        let recorder_a = Arc::new(RecordingListener::new());
        let recorder_b = Arc::new(RecordingListener::new());
        let lm_a = manager_with(recorder_a.clone());
        let lm_b = manager_with(recorder_b.clone());

        let (outcome_a, outcome_b) = tokio::join!(
            async {
                let mut guard = GarrisonEventTx::begin(&pool_a, lm_a)
                    .await
                    .expect("begin a 应成功");
                guard.on_commit(login_event("tx-a"));
                guard
                    .execute("INSERT INTO garrison_event_tx_test (id, tag) VALUES (10, 'tx-a')")
                    .await
                    .expect("事务 a 内 INSERT 应成功");
                guard.commit().await.expect("commit a 应成功")
            },
            async {
                let mut guard = GarrisonEventTx::begin(&pool_b, lm_b)
                    .await
                    .expect("begin b 应成功");
                guard.on_commit(login_event("tx-b"));
                guard
                    .execute("INSERT INTO garrison_event_tx_test (id, tag) VALUES (11, 'tx-b')")
                    .await
                    .expect("事务 b 内 INSERT 应成功");
                guard.commit().await.expect("commit b 应成功")
            },
        );
        assert_eq!(
            outcome_a.dispatched + outcome_a.failed,
            1,
            "guard a 派发事件总数应为 1"
        );
        assert_eq!(
            outcome_b.dispatched + outcome_b.failed,
            1,
            "guard b 派发事件总数应为 1"
        );

        assert_eq!(
            recorder_a.snapshot(),
            vec!["login:tx-a".to_string()],
            "listener a 应恰好收到 guard a 的事件"
        );
        assert_eq!(
            recorder_b.snapshot(),
            vec!["login:tx-b".to_string()],
            "listener b 应恰好收到 guard b 的事件"
        );
        assert_eq!(count_rows(&pool_a, "tx-a").await, 1, "事务 a 写应可见");
        assert_eq!(count_rows(&pool_b, "tx-b").await, 1, "事务 b 写应可见");
    }

    /// `GarrisonEventTx` 需跨 `.await` 持有(Session 字段均为 Send + Sync),
    /// 编译期检查,仿 repository::tests 先例。
    #[test]
    fn garrison_event_tx_is_send_sync() {
        fn assert_send_sync<T: Send + Sync>() {}
        assert_send_sync::<GarrisonEventTx>();
    }

    /// 丢弃 warn 的事件摘要:全部变体在 `event_kind` 中有名(穷尽 match,无 `_` 兜底),同名变体聚合计数。
    #[test]
    fn event_summary_names_all_variants_and_aggregates() {
        let ctx = None;
        #[cfg_attr(
            not(any(feature = "anomalous-detector-dual", feature = "credit-metering")),
            allow(unused_mut)
        )]
        let mut events: Vec<GarrisonEvent> = vec![
            GarrisonEvent::Login {
                login_id: "u".into(),
                token: "t".into(),
                device: None,
                request_context: ctx.clone(),
            },
            GarrisonEvent::Logout {
                login_id: "u".into(),
                token: "t".into(),
                request_context: ctx.clone(),
            },
            GarrisonEvent::Kickout {
                login_id: "u".into(),
                token: "t".into(),
                reason: "r".into(),
                request_context: ctx.clone(),
            },
            GarrisonEvent::PermissionCheck {
                login_id: "u".into(),
                permission: "p".into(),
                request_context: ctx.clone(),
            },
            GarrisonEvent::RoleCheck {
                login_id: "u".into(),
                role: "r".into(),
                request_context: ctx.clone(),
            },
            GarrisonEvent::TokenExpired {
                token: "t".into(),
                request_context: ctx.clone(),
            },
            GarrisonEvent::LoginFailure {
                login_id: "u".into(),
                reason: "invalid_credentials".into(),
                request_context: ctx.clone(),
            },
            GarrisonEvent::PasswordRehashed {
                login_id: "u".into(),
                request_context: ctx.clone(),
            },
            GarrisonEvent::TokenRefresh {
                login_id: "u".into(),
                old_token: "o".into(),
                new_token: "n".into(),
                request_context: ctx.clone(),
            },
            GarrisonEvent::RevokeToken {
                token: "t".into(),
                request_context: ctx.clone(),
            },
            GarrisonEvent::SessionTimeout {
                login_id: "u".into(),
                token: "t".into(),
                request_context: ctx.clone(),
            },
            GarrisonEvent::AccountLocked {
                login_id: "u".into(),
                reason: "r".into(),
                request_context: ctx.clone(),
            },
            GarrisonEvent::FirewallBlock {
                login_id: "u".into(),
                reason: "r".into(),
                request_context: ctx.clone(),
            },
            GarrisonEvent::Replaced {
                login_id: "u".into(),
                token: "t".into(),
                reason: "r".into(),
                request_context: ctx.clone(),
            },
            GarrisonEvent::ConfigReload {
                config_version: 1,
                request_context: ctx.clone(),
            },
            GarrisonEvent::SocialLogin {
                provider: "wechat".into(),
                user_id: "uid".into(),
                login_id: None,
                request_context: ctx.clone(),
            },
            GarrisonEvent::TenantSwitch {
                login_id: "u".into(),
                from_tenant: 1,
                to_tenant: 2,
                request_context: ctx.clone(),
            },
            GarrisonEvent::TokenRotate {
                old_key: "o".into(),
                new_key: "n".into(),
                request_context: ctx.clone(),
            },
            GarrisonEvent::TempCredentialConsumed {
                key: "k".into(),
                value: "v".into(),
                request_context: ctx.clone(),
            },
            GarrisonEvent::InvitationCreated {
                code: "c".into(),
                issuer_id: "i".into(),
            },
            GarrisonEvent::InvitationRedeemed {
                code: "c".into(),
                redeemer_id: "r".into(),
            },
            GarrisonEvent::InvitationRevoked {
                code: "c".into(),
                issuer_id: "i".into(),
            },
            GarrisonEvent::QrLoginCreated {
                qr_id: "q".into(),
                request_context: ctx.clone(),
            },
            GarrisonEvent::QrLoginScanned {
                qr_id: "q".into(),
                app_login_id: "u".into(),
                request_context: ctx.clone(),
            },
            GarrisonEvent::QrLoginConfirmed {
                qr_id: "q".into(),
                app_login_id: "u".into(),
                request_context: ctx.clone(),
            },
            GarrisonEvent::QrLoginCancelled {
                qr_id: "q".into(),
                app_login_id: "u".into(),
                request_context: ctx.clone(),
            },
            GarrisonEvent::DeviceBlock {
                login_id: "u".into(),
                device: "d".into(),
                request_context: ctx.clone(),
            },
            GarrisonEvent::DeviceUnblock {
                login_id: "u".into(),
                device: "d".into(),
                request_context: ctx.clone(),
            },
        ];
        #[cfg(feature = "anomalous-detector-dual")]
        events.push(GarrisonEvent::AnomalousLoginDetected {
            login_id: "u".into(),
            reason: "burst_login".into(),
            detail: serde_json::json!({}),
            timestamp: 1,
            request_context: ctx.clone(),
        });
        #[cfg(feature = "credit-metering")]
        events.extend([
            GarrisonEvent::CreditConsumed {
                tenant_id: 1,
                resource: "r".into(),
                cost: 1,
                credits: 1,
                total_consumed: 1,
                request_context: ctx.clone(),
            },
            GarrisonEvent::CreditAlert {
                tenant_id: 1,
                threshold: 80,
                usage_percent: 81.0,
                total_consumed: 1,
                credit_limit: 100,
                request_context: ctx.clone(),
            },
        ]);

        let summary = event_summary(&events);
        let expected_names = [
            "Login",
            "Logout",
            "Kickout",
            "PermissionCheck",
            "RoleCheck",
            "TokenExpired",
            "LoginFailure",
            "PasswordRehashed",
            "TokenRefresh",
            "RevokeToken",
            "SessionTimeout",
            "AccountLocked",
            "FirewallBlock",
            "Replaced",
            "ConfigReload",
            "SocialLogin",
            "TenantSwitch",
            "TokenRotate",
            "TempCredentialConsumed",
            "InvitationCreated",
            "InvitationRedeemed",
            "InvitationRevoked",
            "QrLoginCreated",
            "QrLoginScanned",
            "QrLoginConfirmed",
            "QrLoginCancelled",
            "DeviceBlock",
            "DeviceUnblock",
        ];
        for name in expected_names {
            assert!(
                summary.contains(&format!("{name}=1")),
                "摘要应含 {name}=1,实际: {summary}"
            );
        }
        #[cfg(feature = "anomalous-detector-dual")]
        assert!(
            summary.contains("AnomalousLoginDetected=1"),
            "摘要应含 AnomalousLoginDetected=1,实际: {summary}"
        );
        #[cfg(feature = "credit-metering")]
        assert!(
            summary.contains("CreditConsumed=1") && summary.contains("CreditAlert=1"),
            "摘要应含 Credit 变体计数,实际: {summary}"
        );

        // 同名变体聚合计数(丢弃 warn 摘要按变体名归并)
        let repeated = vec![login_event("a"), login_event("b"), login_event("c")];
        assert_eq!(event_summary(&repeated), "Login=3");
    }

    // 缓冲事件丢弃显性化:tracing 捕获层断言丢弃 warn
    // (CollectLayer 仿 web_warp request_id 先例;tracing 的 callsite interest
    // 缓存是进程级全局态,并行非订阅者测试可能抢先缓存 Interest::never,
    // 故捕获缺失时重建 interest 后重试)

    /// 进程内 tracing 捕获层:记录 (级别, 事件字段渲染)。
    struct CollectLayer(Arc<Mutex<Vec<(String, String)>>>);

    impl<S> tracing_subscriber::layer::Layer<S> for CollectLayer
    where
        S: tracing::Subscriber + for<'a> tracing_subscriber::registry::LookupSpan<'a>,
    {
        fn on_event(
            &self,
            event: &tracing::Event<'_>,
            _ctx: tracing_subscriber::layer::Context<'_, S>,
        ) {
            let level = event.metadata().level().to_string();
            let mut rendered = String::new();
            event.record(
                &mut |field: &tracing::field::Field, value: &dyn std::fmt::Debug| {
                    rendered.push_str(&format!("{}={:?} ", field.name(), value));
                },
            );
            self.0.lock().push((level, rendered));
        }
    }

    /// 初始化线程局部捕获订阅者并重建 callsite interest 缓存。
    fn init_capture(logs: &Arc<Mutex<Vec<(String, String)>>>) -> tracing::subscriber::DefaultGuard {
        use tracing_subscriber::layer::SubscriberExt;
        use tracing_subscriber::util::SubscriberInitExt;
        let guard = tracing_subscriber::registry()
            .with(CollectLayer(logs.clone()))
            .set_default();
        tracing::callsite::rebuild_interest_cache();
        guard
    }

    /// commit 失败路径显性化:以 session 层预提交消费事务驱动 dbnexus 真实 commit 错误——
    /// guard.commit() 返回 Err、缓冲不派发、产生 commit-failed 丢弃 warn(含事件类型摘要)。
    ///
    /// `Arc::try_unwrap` 并发冲突变体无法经公共 API 稳定构造(`commit(mut self)` 的 move 语义
    /// 禁止同一 guard 并发查询与提交,正是类型层设计目标),故不覆盖。
    #[tokio::test(flavor = "multi_thread")]
    #[serial_test::serial]
    async fn commit_failure_discards_events_with_warn() {
        let pool = setup_pool().await;
        let recorder = Arc::new(RecordingListener::new());
        let lm = manager_with(recorder.clone());

        let mut warn_captured = false;
        for _ in 0..3 {
            let logs: Arc<Mutex<Vec<(String, String)>>> = Arc::new(Mutex::new(Vec::new()));
            let _capture = init_capture(&logs);

            let mut guard = GarrisonEventTx::begin(&pool, lm.clone())
                .await
                .expect("begin 应成功");
            guard.on_commit(login_event("4001"));
            guard
                .session
                .as_ref()
                .expect("session 应存在")
                .commit()
                .await
                .expect("session 层预提交应成功");

            let result = guard.commit().await;
            assert!(
                matches!(&result, Err(GarrisonError::Dao(msg)) if msg.contains("event-tx-commit")),
                "session 层事务已被消费,guard.commit() 应返回 Dao 错误,实际: {result:?}"
            );

            let lines = logs.lock().clone();
            if lines.iter().any(|(level, msg)| {
                level == "WARN"
                    && msg.contains("garrison-event-tx-discarded-after-commit-failure")
                    && msg.contains("Login=1")
            }) {
                warn_captured = true;
                break;
            }
            tracing::callsite::rebuild_interest_cache();
        }
        assert!(
            warn_captured,
            "commit 失败路径应产生 commit-failed 丢弃 warn(含事件类型摘要)"
        );
        assert!(
            recorder.snapshot().is_empty(),
            "commit 失败后缓冲事件不应派发"
        );
    }

    /// 未 commit 即 drop 的 uncommitted 丢弃 warn(捕获层):携带条数与事件类型摘要。
    #[tokio::test(flavor = "multi_thread")]
    #[serial_test::serial]
    async fn drop_without_commit_warns_with_event_summary() {
        let pool = setup_pool().await;
        let recorder = Arc::new(RecordingListener::new());
        let lm = manager_with(recorder.clone());

        let mut warn_captured = false;
        for _ in 0..3 {
            let logs: Arc<Mutex<Vec<(String, String)>>> = Arc::new(Mutex::new(Vec::new()));
            let _capture = init_capture(&logs);

            let mut guard = GarrisonEventTx::begin(&pool, lm.clone())
                .await
                .expect("begin 应成功");
            guard.on_commit(login_event("5001"));
            drop(guard);

            let lines = logs.lock().clone();
            if lines.iter().any(|(level, msg)| {
                level == "WARN"
                    && msg.contains("garrison-event-tx-dropped-without-commit")
                    && msg.contains("Login=1")
            }) {
                warn_captured = true;
                break;
            }
            tracing::callsite::rebuild_interest_cache();
        }
        assert!(
            warn_captured,
            "未 commit 即 drop 应产生 uncommitted 丢弃 warn(含事件类型摘要)"
        );
        assert!(
            recorder.snapshot().is_empty(),
            "未提交即 drop,缓冲事件不应派发"
        );
    }

    /// commit 成功后派发中途被取消:超时取消 commit future(取消点落在派发 await、游标停在 0),
    /// 产生 dispatch-cancelled 丢弃 warn(已派发/总数 + 剩余事件摘要)。
    ///
    /// 取消点确定性:阻塞 listener 先发 entered 信号再挂起,取消时游标必然未推进;
    /// 若取消点落在 `session.commit()` await(判定 committed 之前),entered 与 warn 断言会失败而非误报。
    #[tokio::test(flavor = "multi_thread")]
    #[serial_test::serial]
    async fn cancel_mid_dispatch_warns_with_dispatched_count() {
        let pool = setup_pool().await;

        let mut warn_captured = false;
        for _ in 0..3 {
            let logs: Arc<Mutex<Vec<(String, String)>>> = Arc::new(Mutex::new(Vec::new()));
            let _capture = init_capture(&logs);

            let (entered_tx, mut entered_rx) = tokio::sync::oneshot::channel();
            let lm = manager_with(Arc::new(BlockingListener {
                entered: Mutex::new(Some(entered_tx)),
            }));

            let mut guard = GarrisonEventTx::begin(&pool, lm)
                .await
                .expect("begin 应成功");
            guard.on_commit(login_event("6001"));

            let result =
                tokio::time::timeout(std::time::Duration::from_secs(5), guard.commit()).await;
            assert!(
                result.is_err(),
                "listener 永久挂起,commit 应被超时取消而非完成: {result:?}"
            );
            assert!(
                matches!(entered_rx.try_recv(), Ok(())),
                "取消应发生在 listener 进入 on_event(派发 await 点)之后"
            );

            let lines = logs.lock().clone();
            if lines.iter().any(|(level, msg)| {
                level == "WARN"
                    && msg.contains("garrison-event-tx-dispatch-cancelled-after-commit")
                    // 已派发/总数断言取双语目录兼容形式:en 为 "0 of 1"、zh 为 "0/1"
                    // (该 warn 在 multi_thread worker 线程发射,thread-local locale guard 不可达)
                    && (msg.contains("0 of 1") || msg.contains("0/1"))
                    && msg.contains("Login=1")
            }) {
                warn_captured = true;
                break;
            }
            tracing::callsite::rebuild_interest_cache();
        }
        assert!(
            warn_captured,
            "派发中途被取消应产生 dispatch-cancelled 丢弃 warn(含已派发/总数与摘要)"
        );
    }
}