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
// Copyright (c) 2026 Kirky.X🌠
// SPDX-License-Identifier: Apache-2.0

//! SmsVerificationService / SmsRateLimiter / 验证码比对原语(secure::ct_eq,ADR-0003)单元测试。

use super::*;
use crate::dao::tests::MockDao;
use crate::error::GarrisonError;
use crate::secure::ct_eq::constant_time_eq;
use std::sync::Arc;

/// 构造测试用 SmsVerificationService(默认配置)。
fn make_service() -> SmsVerificationService {
    let dao: Arc<dyn GarrisonDao> = Arc::new(MockDao::new());
    let rate_limiter = SmsRateLimiter::new(dao.clone(), 5, 10);
    let sender: Arc<dyn SmsSender> = Arc::new(NoopSmsSender);
    SmsVerificationService::new(rate_limiter, sender, dao, 3, 100)
}

/// 测试 1:小时限速 5/h 放行(前 5 次成功)。
#[tokio::test]
async fn hourly_limit_allows_first_5() {
    let service = make_service();
    for i in 0..5 {
        let result = service.send_code("13800138000").await;
        assert!(
            result.is_ok(),
            "第 {} 次发送应成功,实际: {:?}",
            i + 1,
            result
        );
    }
}

/// 测试 2:小时限速 5/h 拦截第 6 次。
#[tokio::test]
async fn hourly_limit_blocks_6th() {
    let service = make_service();
    for _ in 0..5 {
        service.send_code("13800138001").await.unwrap();
    }
    let result = service.send_code("13800138001").await;
    assert!(
        matches!(result, Err(GarrisonError::SmsRateLimitExceeded { ref window }) if window == "hourly"),
        "第 6 次应被小时限速拦截,实际: {:?}",
        result
    );
}

/// 测试 3:天限速 10/d 拦截第 11 次(手动递增小时窗计数绕过小时限速,验证天窗独立拦截)。
#[tokio::test]
async fn daily_limit_blocks_11th() {
    let dao: Arc<dyn GarrisonDao> = Arc::new(MockDao::new());
    let service = SmsVerificationService::new(
        SmsRateLimiter::new(dao.clone(), 100, 10),
        Arc::new(NoopSmsSender),
        dao.clone(),
        3,
        100,
    );
    for _ in 0..10 {
        service.send_code("13800138002").await.unwrap();
    }
    let result = service.send_code("13800138002").await;
    assert!(
        matches!(result, Err(GarrisonError::SmsRateLimitExceeded { ref window }) if window == "daily"),
        "第 11 次应被天限速拦截,实际: {:?}",
        result
    );
}

/// 测试 4:验证码验证 3 次后失效(第 4 次返回 SmsVerifyMaxAttempts)。
#[tokio::test]
async fn verify_max_attempts_after_3_failures() {
    let service = make_service();
    service.send_code("13800138003").await.unwrap();
    // 前 3 次错误验证返回 InvalidParam
    for _ in 0..3 {
        let r = service.verify_code("13800138003", "000000").await;
        assert!(
            matches!(r, Err(GarrisonError::InvalidParam(_))),
            "前 3 次错误应返回 InvalidParam"
        );
    }
    // 第 4 次应返回 SmsVerifyMaxAttempts
    let result = service.verify_code("13800138003", "000000").await;
    assert!(
        matches!(result, Err(GarrisonError::SmsVerifyMaxAttempts)),
        "第 4 次应返回 SmsVerifyMaxAttempts,实际: {:?}",
        result
    );
}

/// 测试 5:正确验证码验证通过(验证后验证码被删除)。
#[tokio::test]
async fn correct_code_verifies_and_deletes() {
    let dao: Arc<dyn GarrisonDao> = Arc::new(MockDao::new());
    // 用自定义 sender 捕获验证码
    struct CapturingSender {
        code: parking_lot::Mutex<Option<String>>,
    }
    #[async_trait]
    impl SmsSender for CapturingSender {
        async fn send(&self, _phone: &str, code: &str) -> GarrisonResult<()> {
            *self.code.lock() = Some(code.to_string());
            Ok(())
        }
    }
    let sender = Arc::new(CapturingSender {
        code: parking_lot::Mutex::new(None),
    });
    let service = SmsVerificationService::new(
        SmsRateLimiter::new(dao.clone(), 5, 10),
        sender.clone(),
        dao.clone(),
        3,
        3,
    );
    service.send_code("13800138004").await.unwrap();
    let code = sender.code.lock().as_ref().cloned().unwrap();
    let result = service.verify_code("13800138004", &code).await;
    assert!(result.is_ok(), "正确验证码应验证通过");
    let stored = dao.get("sms:code:13800138004").await.unwrap();
    assert!(stored.is_none(), "验证后验证码应被删除");
}

/// 测试 6:错误验证码计数增加。
#[tokio::test]
async fn wrong_code_increments_attempts() {
    let dao: Arc<dyn GarrisonDao> = Arc::new(MockDao::new());
    let service = SmsVerificationService::new(
        SmsRateLimiter::new(dao.clone(), 5, 10),
        Arc::new(NoopSmsSender),
        dao.clone(),
        3,
        3,
    );
    service.send_code("13800138005").await.unwrap();
    service
        .verify_code("13800138005", "wrong")
        .await
        .unwrap_err();
    let attempts = dao.get("sms:attempts:13800138005").await.unwrap();
    assert_eq!(attempts, Some("1".to_string()));
    service
        .verify_code("13800138005", "wrong")
        .await
        .unwrap_err();
    let attempts = dao.get("sms:attempts:13800138005").await.unwrap();
    assert_eq!(attempts, Some("2".to_string()));
}

/// 测试 7:验证码不存在返回 SmsCodeNotFound。
#[tokio::test]
async fn missing_code_returns_not_found() {
    let service = make_service();
    let result = service.verify_code("13800138006", "123456").await;
    assert!(
        matches!(result, Err(GarrisonError::SmsCodeNotFound)),
        "不存在的验证码应返回 SmsCodeNotFound,实际: {:?}",
        result
    );
}

/// 测试 8:限速账本 key 格式验证(quota:hour:sms:{phone})。
#[tokio::test]
async fn rate_key_format_hour() {
    let dao: Arc<dyn GarrisonDao> = Arc::new(MockDao::new());
    let service = SmsVerificationService::new(
        SmsRateLimiter::new(dao.clone(), 5, 10),
        Arc::new(NoopSmsSender),
        dao.clone(),
        3,
        3,
    );
    service.send_code("13800138007").await.unwrap();
    // 账本模型:小时窗 key 形如 quota:hour:sms:{phone}(无时间桶成分)
    let value = dao.get("quota:hour:sms:13800138007").await.unwrap();
    assert!(
        value.is_some(),
        "应存在 quota:hour:sms:{{phone}} 格式的限速账本 key"
    );
}

/// 测试 9:验证码 key 格式验证(sms:code:{phone})。
#[tokio::test]
async fn code_key_format() {
    let dao: Arc<dyn GarrisonDao> = Arc::new(MockDao::new());
    let service = SmsVerificationService::new(
        SmsRateLimiter::new(dao.clone(), 5, 10),
        Arc::new(NoopSmsSender),
        dao.clone(),
        3,
        3,
    );
    service.send_code("13800138008").await.unwrap();
    let stored = dao.get("sms:code:13800138008").await.unwrap();
    assert!(stored.is_some(), "应存在 sms:code:{{phone}} 格式的 key");
}

/// 测试 10:并发发送不超限(用 MockDao 的原子 incr 保证)。
#[tokio::test(flavor = "multi_thread")]
async fn concurrent_send_does_not_exceed_limit() {
    let dao: Arc<dyn GarrisonDao> = Arc::new(MockDao::new());
    let service = Arc::new(SmsVerificationService::new(
        SmsRateLimiter::new(dao.clone(), 5, 10),
        Arc::new(NoopSmsSender),
        dao.clone(),
        3,
        100,
    ));
    let mut handles = Vec::new();
    for _ in 0..10 {
        let s = service.clone();
        handles.push(tokio::spawn(
            async move { s.send_code("13800138009").await },
        ));
    }
    let mut success = 0;
    let mut rate_limited = 0;
    for handle in handles {
        match handle.await.unwrap() {
            Ok(()) => success += 1,
            Err(GarrisonError::SmsRateLimitExceeded { .. }) => rate_limited += 1,
            Err(e) => panic!("不应返回其他错误: {:?}", e),
        }
    }
    assert_eq!(success, 5, "仅 5 次发送应成功(小时限速 5/h)");
    assert_eq!(rate_limited, 5, "其余 5 次应被限速");
}

/// 测试 11:SmsSender mock(NoopSmsSender 不报错)。
#[tokio::test]
async fn noop_sms_sender_does_not_error() {
    let sender = NoopSmsSender;
    let result = sender.send("13800138010", "123456").await;
    assert!(result.is_ok(), "NoopSmsSender 不应报错");
}

/// 测试 12:异常发送检测(连续未验证 3 次后回收通道)。
#[tokio::test]
async fn unverified_threshold_recycles_channel() {
    let dao: Arc<dyn GarrisonDao> = Arc::new(MockDao::new());
    // unverified_threshold = 3:第 4 次未验证发送应触发回收
    let service = SmsVerificationService::new(
        SmsRateLimiter::new(dao.clone(), 100, 100),
        Arc::new(NoopSmsSender),
        dao.clone(),
        3,
        3,
    );
    // 前 3 次发送成功(unverified 计数 1, 2, 3)
    for i in 0..3 {
        let r = service.send_code("13800138011").await;
        assert!(r.is_ok(), "第 {} 次发送应成功", i + 1);
    }
    // 第 4 次发送应触发通道回收
    let result = service.send_code("13800138011").await;
    assert!(
        matches!(result, Err(GarrisonError::SmsChannelRecycled)),
        "第 4 次发送应触发 SmsChannelRecycled,实际: {:?}",
        result
    );
    // 通道已回收,后续发送直接被拒
    let result = service.send_code("13800138011").await;
    assert!(
        matches!(result, Err(GarrisonError::SmsChannelRecycled)),
        "通道回收后应继续返回 SmsChannelRecycled"
    );
}

// 常量时间比较测试(verify_code 存储码与用户输入的统一比较原语)

/// 验证 constant_time_eq 对相同输入返回 true。
#[test]
fn constant_time_eq_same_string_returns_true() {
    assert!(constant_time_eq(b"123456", b"123456"));
    assert!(constant_time_eq(b"", b""));
    assert!(constant_time_eq(b"abcdef", b"abcdef"));
}

/// 验证 constant_time_eq 对不同输入返回 false。
#[test]
fn constant_time_eq_different_string_returns_false() {
    assert!(!constant_time_eq(b"123456", b"000000"));
    assert!(!constant_time_eq(b"123456", b"123457"));
    assert!(!constant_time_eq(b"abcdef", b"abcdeF"));
}

/// 验证 constant_time_eq 对不同长度输入返回 false。
#[test]
fn constant_time_eq_different_length_returns_false() {
    assert!(!constant_time_eq(b"12345", b"123456"));
    assert!(!constant_time_eq(b"1234567", b"123456"));
    assert!(!constant_time_eq(b"", b"123456"));
    assert!(!constant_time_eq(b"123456", b""));
}

/// 验证 constant_time_eq 对仅首位不同的输入返回 false(覆盖首字节差异)。
#[test]
fn constant_time_eq_first_byte_diff_returns_false() {
    assert!(!constant_time_eq(b"023456", b"123456"));
}

/// 验证 constant_time_eq 对仅末位不同的输入返回 false(覆盖末字节差异)。
#[test]
fn constant_time_eq_last_byte_diff_returns_false() {
    assert!(!constant_time_eq(b"123450", b"123456"));
}

/// 超长/短验证码按「错误验证码」失败路径处理(计入尝试次数)。
///
/// 安全属性:定长 6 位保证长度不符必然不等,`verify_code` 进入比较前即拒绝——用户可控长度不得放大服务端计算量;长度公开,提前拒绝不泄露秘密。
#[tokio::test]
async fn wrong_length_code_counts_as_failed_attempt() {
    let dao: Arc<dyn GarrisonDao> = Arc::new(MockDao::new());
    let rate_limiter = SmsRateLimiter::new(dao.clone(), 100, 100);
    let sender: Arc<dyn SmsSender> = Arc::new(NoopSmsSender);
    let service = SmsVerificationService::new(rate_limiter, sender, dao.clone(), 3, 100);

    service.send_code("13800138020").await.unwrap();
    // 超长输入:拒绝且计入一次失败尝试
    let oversized = "1".repeat(4096);
    let result = service.verify_code("13800138020", &oversized).await;
    assert!(
        matches!(result, Err(GarrisonError::InvalidParam(ref m)) if m.starts_with(service::ERR_SMS_CODE_WRONG)),
        "超长验证码应按错误验证码拒绝,实际: {:?}",
        result
    );
    // 短输入同型
    let result = service.verify_code("13800138020", "12345").await;
    assert!(matches!(result, Err(GarrisonError::InvalidParam(_))));
    let attempts = dao.get("sms:attempts:13800138020").await.unwrap();
    assert_eq!(
        attempts,
        Some("2".to_string()),
        "长度不符的输入应计入失败尝试"
    );
}

// 验证码生成范围测试(排除 000000)

/// 验证 generate_code 返回 6 位字符串。
#[test]
fn generate_code_returns_6_char_string() {
    let code = super::service::generate_code().expect("生成验证码不应失败");
    assert_eq!(code.len(), 6, "验证码必须是 6 位字符: {}", code);
}

/// 验证 generate_code 永不返回 "000000"(弱验证码)。
///
/// 生成 10000 次断言无 "000000" 且均为 6 位数字:旧 `gen_range(0..1000000)` 有 1/1000000 概率生成 0,高频下累积风险不可忽视。
#[test]
fn generate_code_never_returns_000000() {
    for _ in 0..10000 {
        let code = super::service::generate_code().expect("生成验证码不应失败");
        assert_ne!(code, "000000", "验证码不应为 000000(弱验证码)");
        assert_eq!(code.len(), 6, "验证码必须是 6 位字符: {}", code);
    }
}

/// 断言结果均落在 [100000, 999999]:旧 `gen_range(0..1000000)` 约 10% 概率生成 < 100000(首位 '0'),10000 次迭代必然暴露。
#[test]
fn generate_code_always_in_6_digit_range() {
    for _ in 0..10000 {
        let code = super::service::generate_code().expect("生成验证码不应失败");
        let parsed: u32 = code
            .parse()
            .unwrap_or_else(|_| panic!("验证码必须是纯数字: {}", code));
        assert!(
            (100000..1000000).contains(&parsed),
            "验证码必须在 [100000, 999999] 范围内: {}",
            code
        );
        // 首位字符不应为 '0'(与 000000 弱验证码防护一致)
        assert_ne!(
            code.chars().next().unwrap(),
            '0',
            "验证码首位不应为 0: {}",
            code
        );
    }
}

// SmsRateLimiter::validate_phone 校验分支测试(key 注入 / DoS 防护)

/// 空手机号返回 InvalidParam(secure-phone-empty)。
#[test]
fn validate_phone_rejects_empty() {
    let result = rate_limiter::validate_phone("");
    assert!(
        matches!(&result, Err(GarrisonError::InvalidParam(msg)) if msg.contains("secure-phone-empty")),
        "空手机号应返回 InvalidParam(secure-phone-empty),实际: {:?}",
        result
    );
}

/// 含 ':' 的手机号返回 InvalidParam(key 注入防护)。
#[test]
fn validate_phone_rejects_colon() {
    let result = rate_limiter::validate_phone("138:00138000");
    assert!(
        matches!(&result, Err(GarrisonError::InvalidParam(msg)) if msg.contains("secure-phone-no-colon")),
        "含冒号手机号应返回 InvalidParam(secure-phone-no-colon),实际: {:?}",
        result
    );
}

/// 含控制字符的手机号返回 InvalidParam(如 \n / \u{1})。
#[test]
fn validate_phone_rejects_control_char() {
    for phone in ["138\n00138000", "138\u{1}00138000"] {
        let result = rate_limiter::validate_phone(phone);
        assert!(
            matches!(&result, Err(GarrisonError::InvalidParam(msg)) if msg.contains("secure-phone-no-control-char")),
            "含控制字符手机号应返回 InvalidParam(secure-phone-no-control-char),实际: {:?}",
            result
        );
    }
}

/// 长度超过 20 的手机号返回 InvalidParam;恰好 20 字符放行(边界)。
#[test]
fn validate_phone_rejects_over_20_chars() {
    let result = rate_limiter::validate_phone(&"1".repeat(21));
    assert!(
        matches!(&result, Err(GarrisonError::InvalidParam(msg)) if msg.contains("secure-phone-too-long")),
        "21 字符手机号应返回 InvalidParam(secure-phone-too-long),实际: {:?}",
        result
    );
    assert!(
        rate_limiter::validate_phone(&"1".repeat(20)).is_ok(),
        "恰好 20 字符应放行(边界值)"
    );
}

/// 合法手机号通过校验。
#[test]
fn validate_phone_accepts_valid() {
    assert!(rate_limiter::validate_phone("13800138000").is_ok());
    assert!(rate_limiter::validate_phone("+8613800138000").is_ok());
}

// SmsRateLimiter 错误路径 / 回滚测试(FaultDao:incr/decr 可独立注入失败)

/// 可注入故障的 DAO:incr / decr 可独立配置失败,其余委托内存 MockDao。
struct FaultDao {
    inner: MockDao,
    /// incr 注入失败(模拟 limiteron incr_with_ttl 上游错误)。
    fail_incr: bool,
    /// decr 注入失败(模拟回滚递减失败,触发 warn 日志分支)。
    fail_decr: bool,
}

impl FaultDao {
    fn ok() -> Self {
        Self {
            inner: MockDao::new(),
            fail_incr: false,
            fail_decr: false,
        }
    }

    fn with_fail_incr() -> Self {
        Self {
            inner: MockDao::new(),
            fail_incr: true,
            fail_decr: false,
        }
    }

    fn with_fail_decr() -> Self {
        Self {
            inner: MockDao::new(),
            fail_incr: false,
            fail_decr: true,
        }
    }
}

#[async_trait]
impl GarrisonDao for FaultDao {
    async fn get(&self, key: &str) -> GarrisonResult<Option<String>> {
        self.inner.get(key).await
    }

    async fn set(&self, key: &str, value: &str, ttl_seconds: u64) -> GarrisonResult<()> {
        self.inner.set(key, value, ttl_seconds).await
    }

    async fn update(&self, key: &str, value: &str) -> GarrisonResult<()> {
        self.inner.update(key, value).await
    }

    async fn expire(&self, key: &str, seconds: u64) -> GarrisonResult<()> {
        self.inner.expire(key, seconds).await
    }

    async fn delete(&self, key: &str) -> GarrisonResult<()> {
        self.inner.delete(key).await
    }

    async fn set_if_absent(
        &self,
        key: &str,
        value: &str,
        ttl_seconds: u64,
    ) -> GarrisonResult<bool> {
        self.inner.set_if_absent(key, value, ttl_seconds).await
    }

    async fn rename(&self, old_key: &str, new_key: &str) -> GarrisonResult<()> {
        self.inner.rename(old_key, new_key).await
    }

    async fn get_and_delete(&self, key: &str) -> GarrisonResult<Option<String>> {
        self.inner.get_and_delete(key).await
    }

    async fn keys(&self, pattern: &str) -> GarrisonResult<Vec<String>> {
        self.inner.keys(pattern).await
    }

    async fn compare_and_swap(
        &self,
        key: &str,
        expected: Option<&str>,
        new_value: &str,
        ttl_seconds: u64,
    ) -> GarrisonResult<bool> {
        self.inner
            .compare_and_swap(key, expected, new_value, ttl_seconds)
            .await
    }

    async fn incr(&self, key: &str, ttl_seconds: u64) -> GarrisonResult<u64> {
        if self.fail_incr {
            return Err(GarrisonError::Dao("mock-incr-failed".to_string()));
        }
        self.inner.incr(key, ttl_seconds).await
    }

    async fn decr(&self, key: &str) -> GarrisonResult<u64> {
        if self.fail_decr {
            return Err(GarrisonError::Dao("mock-decr-failed".to_string()));
        }
        self.inner.decr(key).await
    }
}

/// 读取指定手机号当前小时/天窗口账本值(不存在返回 None);账本键 `quota:{hour,day}:sms:{phone}`,无时间成分。
async fn window_counter_value(
    dao: &Arc<dyn GarrisonDao>,
    phone: &str,
    window: &str,
) -> Option<String> {
    dao.get(&format!("quota:{}:sms:{}", window, phone))
        .await
        .unwrap()
}

/// 小时窗口超限应回滚本次 incr(计数回到拒绝前的值),返回 hourly 限流错误。
#[tokio::test]
async fn check_and_increment_hourly_exceed_rolls_back_counter() {
    let dao: Arc<dyn GarrisonDao> = Arc::new(FaultDao::ok());
    let limiter = SmsRateLimiter::new(dao.clone(), 1, 100);

    // 第 1 次:hour=1 <= 1,放行
    limiter.check_and_increment("15800000001").await.unwrap();
    // 第 2 次:hour=2 > 1,超限 → 回滚 incr → hour 回到 1
    let result = limiter.check_and_increment("15800000001").await;
    assert!(
        matches!(&result, Err(GarrisonError::SmsRateLimitExceeded { window }) if window == "hourly"),
        "第 2 次应返回 hourly 限流错误,实际: {:?}",
        result
    );
    assert_eq!(
        window_counter_value(&dao, "15800000001", "hour").await,
        Some("1".to_string()),
        "超限请求应回滚:hour 计数应回到拒绝前的 1"
    );
}

/// 天窗口超限应回滚天与小时两个计数器,返回 daily 限流错误。
#[tokio::test]
async fn check_and_increment_daily_exceed_rolls_back_both_counters() {
    let dao: Arc<dyn GarrisonDao> = Arc::new(FaultDao::ok());
    let limiter = SmsRateLimiter::new(dao.clone(), 100, 1);

    // 第 1 次:day=1 <= 1,放行
    limiter.check_and_increment("15800000002").await.unwrap();
    // 第 2 次:hour=2 <= 100 通过,day=2 > 1 超限 → 回滚 day 与 hour
    let result = limiter.check_and_increment("15800000002").await;
    assert!(
        matches!(&result, Err(GarrisonError::SmsRateLimitExceeded { window }) if window == "daily"),
        "第 2 次应返回 daily 限流错误,实际: {:?}",
        result
    );
    assert_eq!(
        window_counter_value(&dao, "15800000002", "day").await,
        Some("1".to_string()),
        "超限请求应回滚:day 计数应回到拒绝前的 1"
    );
    assert_eq!(
        window_counter_value(&dao, "15800000002", "hour").await,
        Some("1".to_string()),
        "超限请求应回滚:hour 计数应回到拒绝前的 1"
    );
}

/// 小时超限且回滚 decr 失败时仅记录 warn,不改变返回的 hourly 限流错误。
#[tokio::test]
async fn check_and_increment_hourly_exceed_rollback_failure_only_warns() {
    // fail_decr:回滚递减失败 → 触发 rollback failed warn 分支
    let dao: Arc<dyn GarrisonDao> = Arc::new(FaultDao::with_fail_decr());
    let limiter = SmsRateLimiter::new(dao, 0, 100);
    let result = limiter.check_and_increment("15800000003").await;
    assert!(
        matches!(&result, Err(GarrisonError::SmsRateLimitExceeded { window }) if window == "hourly"),
        "回滚失败不应改变返回值,仍应返回 hourly 限流错误,实际: {:?}",
        result
    );
}

/// 天超限且回滚 decr 失败时仅记录 warn(day + hour 两次回滚都吞错),仍返回 daily 限流错误。
#[tokio::test]
async fn check_and_increment_daily_exceed_rollback_failure_only_warns() {
    let dao: Arc<dyn GarrisonDao> = Arc::new(FaultDao::with_fail_decr());
    let limiter = SmsRateLimiter::new(dao, 100, 0);
    let result = limiter.check_and_increment("15800000004").await;
    assert!(
        matches!(&result, Err(GarrisonError::SmsRateLimitExceeded { window }) if window == "daily"),
        "回滚失败不应改变返回值,仍应返回 daily 限流错误,实际: {:?}",
        result
    );
}

/// limiter incr 上游失败应返回 Internal(secure-limiter-incr 前缀)。
#[tokio::test]
async fn check_and_increment_incr_failure_returns_internal() {
    let dao: Arc<dyn GarrisonDao> = Arc::new(FaultDao::with_fail_incr());
    let limiter = SmsRateLimiter::new(dao, 100, 100);
    let result = limiter.check_and_increment("15800000005").await;
    assert!(
        matches!(&result, Err(GarrisonError::Internal(msg)) if msg.contains("secure-limiter-incr")),
        "incr 失败应返回 Internal(secure-limiter-incr),实际: {:?}",
        result
    );
}

/// 回滚应递减小时与天两个窗口计数器(递减到 0 时计数器被删除)。
#[tokio::test]
async fn rollback_decrements_hour_and_day_counters() {
    let dao: Arc<dyn GarrisonDao> = Arc::new(FaultDao::ok());
    let limiter = SmsRateLimiter::new(dao.clone(), 100, 100);

    // 先 check_and_increment 成功:hour=1, day=1
    limiter.check_and_increment("15800000006").await.unwrap();
    assert_eq!(
        window_counter_value(&dao, "15800000006", "hour").await,
        Some("1".to_string())
    );
    // 回滚:两个计数器递减到 0 → 被删除
    limiter.rollback("15800000006").await.unwrap();
    assert_eq!(
        window_counter_value(&dao, "15800000006", "hour").await,
        None,
        "回滚后 hour 计数器应被删除(递减到 0)"
    );
    assert_eq!(
        window_counter_value(&dao, "15800000006", "day").await,
        None,
        "回滚后 day 计数器应被删除(递减到 0)"
    );
}

/// 回滚非法手机号返回 InvalidParam(校验前置)。
#[tokio::test]
async fn rollback_invalid_phone_returns_invalid_param() {
    let dao: Arc<dyn GarrisonDao> = Arc::new(FaultDao::ok());
    let limiter = SmsRateLimiter::new(dao, 100, 100);
    let result = limiter.rollback("158:0000007").await;
    assert!(
        matches!(&result, Err(GarrisonError::InvalidParam(msg)) if msg.contains("secure-phone-no-colon")),
        "回滚含冒号手机号应返回 InvalidParam,实际: {:?}",
        result
    );
}

/// 回滚时 decr 失败应透传 Dao 错误(rollback 使用聚合策略:继续回滚天窗口,返回首个错误)。
#[tokio::test]
async fn rollback_decr_failure_propagates_error() {
    let dao: Arc<dyn GarrisonDao> = Arc::new(FaultDao::with_fail_decr());
    let limiter = SmsRateLimiter::new(dao, 100, 100);
    let result = limiter.rollback("15800000008").await;
    assert!(
        matches!(&result, Err(GarrisonError::Dao(msg)) if msg.contains("mock-decr-failed")),
        "回滚 decr 失败应透传 Dao 错误,实际: {:?}",
        result
    );
}

// 窗口桶信息携带:check 与 rollback 共用同一账本

/// check_and_increment_with / rollback_with:携带窗口信息的精确回滚路径。
#[tokio::test]
async fn rollback_with_uses_check_windows() {
    let dao: Arc<dyn GarrisonDao> = Arc::new(FaultDao::ok());
    let limiter = SmsRateLimiter::new(dao.clone(), 100, 100);

    let windows = limiter
        .check_and_increment_with("15800000009")
        .await
        .unwrap();
    assert_eq!(
        window_counter_value(&dao, "15800000009", "hour").await,
        Some("1".to_string())
    );
    // 使用 check 返回的窗口信息回滚:两个计数器递减到 0 → 被删除
    limiter
        .rollback_with("15800000009", &windows)
        .await
        .unwrap();
    assert_eq!(
        window_counter_value(&dao, "15800000009", "hour").await,
        None,
        "rollback_with 后 hour 计数器应被删除"
    );
    assert_eq!(
        window_counter_value(&dao, "15800000009", "day").await,
        None,
        "rollback_with 后 day 计数器应被删除"
    );
}

/// 前后空白归一化:带空白手机号与裸手机号命中同一限速 key(防 `" 13800138000 "` 绕过限速),key 不含空白。
#[tokio::test]
async fn check_and_increment_normalizes_phone_whitespace() {
    let dao: Arc<dyn GarrisonDao> = Arc::new(FaultDao::ok());
    let limiter = SmsRateLimiter::new(dao.clone(), 100, 100);

    // 带前后空白的手机号发送成功
    limiter
        .check_and_increment("  15800000010  ")
        .await
        .unwrap();
    // key 使用归一化后的手机号(无空白)
    let value = dao.get("quota:hour:sms:15800000010").await.unwrap();
    assert!(
        value.is_some(),
        "归一化手机号应生成 quota:hour:sms:15800000010 的账本 key"
    );
    // 带空白填充的重复请求命中同一个 key(计数 2),而非生成新 key
    limiter.check_and_increment("15800000010").await.unwrap();
    let value = window_counter_value(&dao, "15800000010", "hour")
        .await
        .expect("两个请求应命中同一归一化 key");
    assert_eq!(value, "2", "空白填充与裸手机号应共用同一账本");
    // 不存在含空白填充的 key(任何以空白开头的手机号 key)
    let padded_keys = dao.keys("quota:*:sms: *").await.unwrap();
    assert!(
        padded_keys.is_empty(),
        "不应存在含空白填充的限速 key,实际: {:?}",
        padded_keys
    );
}

/// 内部含空白的手机号被拒绝(前后空白 trim 归一化,内部空白无法归一化故拒绝)。
#[test]
fn validate_phone_rejects_inner_whitespace() {
    let result = rate_limiter::validate_phone("138 0013 8000");
    assert!(
        matches!(&result, Err(GarrisonError::InvalidParam(msg)) if msg.contains("secure-phone-no-whitespace")),
        "内部空白手机号应返回 InvalidParam(secure-phone-no-whitespace),实际: {:?}",
        result
    );
}

// 达到最大尝试次数后的验证行为(安全属性:耗尽后正确码也不得通过)

/// 达到上限后提交**正确**验证码仍被拒绝。
///
/// 安全属性:max attempts 耗尽后验证码已删除失效,此后无论错误码还是正确码都不得通过,也不得开启新尝试窗口。
#[tokio::test]
async fn correct_code_after_max_attempts_still_rejected() {
    let dao: Arc<dyn GarrisonDao> = Arc::new(MockDao::new());
    // 捕获验证码
    struct CapturingSender {
        code: parking_lot::Mutex<Option<String>>,
    }
    #[async_trait]
    impl SmsSender for CapturingSender {
        async fn send(&self, _phone: &str, code: &str) -> GarrisonResult<()> {
            *self.code.lock() = Some(code.to_string());
            Ok(())
        }
    }
    let sender = Arc::new(CapturingSender {
        code: parking_lot::Mutex::new(None),
    });
    let service = SmsVerificationService::new(
        SmsRateLimiter::new(dao.clone(), 100, 100),
        sender.clone(),
        dao.clone(),
        3,
        100,
    );
    let phone = "13800138012";
    service.send_code(phone).await.unwrap();
    let correct_code = sender.code.lock().as_ref().cloned().unwrap();

    // 3 次错误 → 第 4 次触发 MaxAttempts(验证码失效)
    for _ in 0..3 {
        let r = service.verify_code(phone, "000000").await;
        assert!(matches!(r, Err(GarrisonError::InvalidParam(_))));
    }
    let r = service.verify_code(phone, "000000").await;
    assert!(
        matches!(r, Err(GarrisonError::SmsVerifyMaxAttempts)),
        "第 4 次错误应返回 SmsVerifyMaxAttempts"
    );

    // 达上限后提交正确验证码:必须仍被拒绝(不得放行)
    let result = service.verify_code(phone, &correct_code).await;
    assert!(
        result.is_err(),
        "达上限后正确验证码必须被拒绝(验证码已随 MaxAttempts 失效),实际: {:?}",
        result
    );
    // 且不得被当作一次新的错误尝试(返回 ERR_SMS_CODE_WRONG 的 InvalidParam)
    assert!(
        !matches!(&result, Err(GarrisonError::InvalidParam(m)) if m.starts_with(service::ERR_SMS_CODE_WRONG)),
        "达上限后正确验证码不应返回 code-wrong(新尝试窗口),实际: {:?}",
        result
    );
}

// 发送失败清理 & unverified incr 失败回滚(防残留可用验证码)

/// 恒失败的 SmsSender:模拟上游短信网关故障。
struct FailingSmsSender;

#[async_trait]
impl SmsSender for FailingSmsSender {
    async fn send(&self, _phone: &str, _code: &str) -> GarrisonResult<()> {
        Err(GarrisonError::Internal("gateway-down".to_string()))
    }
}

/// 发送失败:原始错误保留,且已写入的验证码被删除(防发送失败后验证码仍可验证)。
#[tokio::test]
async fn send_failure_cleans_stored_code_and_keeps_original_error() {
    let dao: Arc<dyn GarrisonDao> = Arc::new(MockDao::new());
    let service = SmsVerificationService::new(
        SmsRateLimiter::new(dao.clone(), 5, 10),
        Arc::new(FailingSmsSender),
        dao.clone(),
        3,
        100,
    );
    let result = service.send_code("13800138010").await;
    assert!(
        matches!(&result, Err(GarrisonError::Internal(m)) if m == "gateway-down"),
        "应保留原始发送错误,实际: {:?}",
        result
    );
    // 验证码必须被清理:同码验证应返回 not found 而非成功
    let code = "123456";
    let verify = service.verify_code("13800138010", code).await;
    assert!(
        matches!(&verify, Err(GarrisonError::SmsCodeNotFound)),
        "发送失败后验证码不应可验证(已清理),实际: {:?}",
        verify
    );
}

/// 仅对 `sms:unverified:` 前缀注入 incr 失败的 DAO:验证「递增失败 → 回滚限速计数 + 删除已存验证码 + 保留原始错误」。
struct UnverifiedIncrFaultDao {
    inner: MockDao,
}

#[async_trait]
impl GarrisonDao for UnverifiedIncrFaultDao {
    async fn get(&self, key: &str) -> GarrisonResult<Option<String>> {
        self.inner.get(key).await
    }

    async fn set(&self, key: &str, value: &str, ttl_seconds: u64) -> GarrisonResult<()> {
        self.inner.set(key, value, ttl_seconds).await
    }

    async fn update(&self, key: &str, value: &str) -> GarrisonResult<()> {
        self.inner.update(key, value).await
    }

    async fn expire(&self, key: &str, seconds: u64) -> GarrisonResult<()> {
        self.inner.expire(key, seconds).await
    }

    async fn delete(&self, key: &str) -> GarrisonResult<()> {
        self.inner.delete(key).await
    }

    async fn set_if_absent(
        &self,
        key: &str,
        value: &str,
        ttl_seconds: u64,
    ) -> GarrisonResult<bool> {
        self.inner.set_if_absent(key, value, ttl_seconds).await
    }

    async fn rename(&self, old_key: &str, new_key: &str) -> GarrisonResult<()> {
        self.inner.rename(old_key, new_key).await
    }

    async fn get_and_delete(&self, key: &str) -> GarrisonResult<Option<String>> {
        self.inner.get_and_delete(key).await
    }

    async fn keys(&self, pattern: &str) -> GarrisonResult<Vec<String>> {
        self.inner.keys(pattern).await
    }

    async fn compare_and_swap(
        &self,
        key: &str,
        expected: Option<&str>,
        new_value: &str,
        ttl_seconds: u64,
    ) -> GarrisonResult<bool> {
        self.inner
            .compare_and_swap(key, expected, new_value, ttl_seconds)
            .await
    }

    async fn incr(&self, key: &str, ttl_seconds: u64) -> GarrisonResult<u64> {
        if key.starts_with("sms:unverified:") {
            return Err(GarrisonError::Dao("unverified-incr-failed".to_string()));
        }
        self.inner.incr(key, ttl_seconds).await
    }

    async fn decr(&self, key: &str) -> GarrisonResult<u64> {
        self.inner.decr(key).await
    }
}

/// unverified incr 失败:错误上抛、已写验证码删除、限速计数回滚(不残留膨胀计数)。
#[tokio::test]
async fn unverified_incr_failure_rolls_back_limiter_and_code() {
    let dao: Arc<dyn GarrisonDao> = Arc::new(UnverifiedIncrFaultDao {
        inner: MockDao::new(),
    });
    let service = SmsVerificationService::new(
        SmsRateLimiter::new(dao.clone(), 5, 10),
        Arc::new(NoopSmsSender),
        dao.clone(),
        3,
        100,
    );
    let result = service.send_code("13800138011").await;
    assert!(
        matches!(&result, Err(GarrisonError::Dao(m)) if m == "unverified-incr-failed"),
        "应保留 unverified incr 的原始错误,实际: {:?}",
        result
    );
    // 已存验证码被删除
    let code = dao.get("sms:code:13800138011").await.unwrap();
    assert!(code.is_none(), "unverified incr 失败后验证码应被删除");
    // 小时限速计数已回滚(不残留本次递增)
    let hourly = window_counter_value(&dao, "13800138011", "hour").await;
    assert!(
        hourly.is_none() || hourly.as_deref() == Some("0"),
        "限速计数应回滚,实际: {:?}",
        hourly
    );
}