garrison 0.7.2

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
//! Copyright (c) 2026 Kirky.X. All rights reserved.
//! See LICENSE for full license text.

//! GarrisonDaoOxcache 实现(从 mod.rs 迁移,Rule 25 合规)。

use super::GarrisonDao;
#[cfg(feature = "cache-redis")]
use super::RedisConfig;
#[cfg(feature = "tenant-isolation")]
use crate::constants::DaoKeyPrefix;
use crate::error::{GarrisonError, GarrisonResult};
use async_trait::async_trait;
use oxcache::Cache;
use std::time::Duration;

/// 根据租户上下文返回实际存储 key。
///
/// - `tenant-isolation` feature 启用且 `TENANT.try_get()` 返回 `Ok(ctx)`:
///   返回 `format!("{}{}:{}", DaoKeyPrefix::Tenant, ctx.tenant_id, key)`
/// - feature 关闭或 `TENANT` 上下文不存在(`try_get` 返回 `Err`):返回 `key.to_string()`(不变)
///
/// # 设计
///
/// - `TENANT.try_get()` 返回 `Err` 而非 `None`(tokio task_local 语义),用 `Ok` 模式匹配
/// - 不 panic:无上下文时 key 保持原样,保证向后兼容
/// - 同步函数:`try_get` 是同步的,无需 async
fn prefixed_key(key: &str) -> String {
    #[cfg(feature = "tenant-isolation")]
    {
        if let Ok(ctx) = crate::context::tenant::TENANT.try_get() {
            return format!("{}{}:{}", DaoKeyPrefix::Tenant, ctx.tenant_id, key);
        }
    }
    // feature 关闭或无 TENANT 上下文时 key 保持原样
    #[allow(unused_variables)]
    let _ = key;
    key.to_string()
}

/// 通配符匹配(支持 `*` 匹配任意字符序列)。
///
/// 用于 `keys()` 方法过滤匹配 pattern 的 key。
/// pattern 如 `"anomalous:login:*"` 匹配 `"anomalous:login:1001:1234567890"`。
#[cfg(feature = "anomalous-detector-dual")]
fn matches_pattern(key: &str, pattern: &str) -> bool {
    if pattern == "*" {
        return true;
    }
    if let Some(prefix) = pattern.strip_suffix('*') {
        return key.starts_with(prefix);
    }
    key == pattern
}

/// 去除 DAO 前缀,返回原始 key(`prefixed_key` 的逆操作)。
///
/// `prefixed_key` 在 `tenant-isolation` 启用且有 TENANT 上下文时
/// 返回 `format!("tenant:{id}:{key}")`,否则原样返回。
/// 本函数逆向该操作:去除 `"tenant:{id}:"` 前缀,或原样返回。
#[cfg(feature = "anomalous-detector-dual")]
fn strip_prefix(prefixed: &str) -> String {
    #[cfg(feature = "tenant-isolation")]
    {
        // 格式 "tenant:{id}:{key}",找到第二个 ':' 之后的内容
        if let Some(rest) = prefixed.strip_prefix("tenant:") {
            if let Some(pos) = rest.find(':') {
                return rest[pos + 1..].to_string();
            }
        }
    }
    // 无前缀(tenant-isolation 关闭或无 TENANT 上下文)时原样返回
    prefixed.to_string()
}

/// oxcache 0.3 默认实现,包装 `oxcache::Cache<String, String>`。
///
/// - L1(内存)+ L2(redis)由 oxcache 0.3 自动管理(oxcache 0.3 支持 per-entry TTL)。
/// - Garrison 自身不实现任何缓存逻辑,全部委托给 oxcache。
/// - 启用 `sync_mode(true)` 后使用 `_sync` API,
///   要求调用方在 multi_thread tokio runtime 中执行。
///
/// # TTL 保留
/// - `update` 通过 `cache.ttl_sync()` 读取剩余 TTL,用 `set_with_ttl_sync` 保留原 TTL(不重置过期时间)
/// - `expire` 通过 `cache.expire_sync()` 原子更新 TTL(不触碰 value)
/// - 依赖本地 oxcache 仓库(crates.io 0.3.0 未暴露 `Cache<K,V>::ttl_sync()`,本地仓库已暴露)
///
/// # 性能约束(A-009 评估结论)
///
/// `_sync` API 仅适用于 oxcache in-memory 后端:
/// - 读操作(`get_sync`/`exists_sync`/`ttl_sync`):无锁读,<100ns
/// - 写操作(`set_with_ttl_sync`/`delete_sync`/`expire_sync`):短临界区,<1μs
/// - 对比 `tokio::task::spawn_blocking` 开销:~10-50μs(线程池调度)
///
/// 结论:对 in-memory backend,`_sync` 调用比 `spawn_blocking` 更快,保留现有实现。
///
/// **后续跟进**:若未来引入 Redis/分布式 backend,需改用 async API(`_sync` 在网络 I/O 场景下会阻塞 tokio worker 线程)。
pub struct GarrisonDaoOxcache {
    cache: Cache<String, String>,
    /// 原子操作锁,仅用于 `get_and_delete` 的进程内原子性保护。
    /// 其他操作(get/set/delete 等)不持有此锁,不影响并发性能。
    atomic_lock: parking_lot::Mutex<()>,
    /// Redis 部署模式配置(仅在 `cache-redis` feature 启用时存在)。
    ///
    /// 通过 [`with_redis_config`] builder 方法设置。未设置时为 `None`,
    /// oxcache 使用默认 Redis 配置。
    #[cfg(feature = "cache-redis")]
    redis_config: Option<RedisConfig>,
    /// key 索引,用于实现 `keys()` 方法(oxcache 0.3.3 无原生 keys/iter API)。
    /// 仅在 `anomalous-detector-dual` feature 启用时维护,避免影响其他场景的内存开销。
    /// TTL 过期的 key 会在 `keys()` 调用时惰性清理。
    #[cfg(feature = "anomalous-detector-dual")]
    key_index: parking_lot::RwLock<std::collections::HashSet<String>>,
}

impl GarrisonDaoOxcache {
    /// 创建默认的 oxcache DAO 实例。
    ///
    /// 启用 `sync_mode(true)` 以支持 `_sync` API。
    ///
    /// # 返回
    /// 已初始化的 `GarrisonDaoOxcache` 实例(内部 `oxcache::Cache` 已就绪,sync_mode 启用)。
    ///
    /// # 错误
    /// - `GarrisonError::Dao`:oxcache 初始化失败(消息含 "oxcache 初始化失败")。
    pub async fn new() -> GarrisonResult<Self> {
        let cache = Cache::builder()
            .sync_mode(true)
            .build()
            .await
            .map_err(|e| GarrisonError::Dao(format!("dao-oxcache-init::{}", e)))?;
        Ok(Self {
            cache,
            atomic_lock: parking_lot::Mutex::new(()),
            #[cfg(feature = "cache-redis")]
            redis_config: None,
            #[cfg(feature = "anomalous-detector-dual")]
            key_index: parking_lot::RwLock::new(std::collections::HashSet::new()),
        })
    }

    /// 设置 Redis 部署模式配置。
    ///
    /// 仅在 `cache-redis` feature 启用时可用。消费 self 并返回新实例(builder 模式)。
    /// 调用后 oxcache 的 Redis L2 后端使用指定部署模式。
    /// 未调用时保持现有行为(oxcache 默认 Redis 配置)。
    ///
    /// # 参数
    /// - `config`: Redis 配置(包含部署模式、连接池参数、认证信息)。
    ///
    /// # 返回
    /// 消费 self 并返回新实例。
    #[cfg(feature = "cache-redis")]
    pub fn with_redis_config(mut self, config: RedisConfig) -> Self {
        tracing::info!(
            mode = %config.mode,
            db = config.db,
            pool_size = config.pool_size,
            "设置 Redis 部署模式配置"
        );
        self.redis_config = Some(config);
        self
    }

    /// 返回当前 Redis 配置(仅在 `cache-redis` feature 启用时可用)。
    ///
    /// 用于测试与诊断:确认 `with_redis_config` 是否已调用。
    #[cfg(feature = "cache-redis")]
    pub fn redis_config(&self) -> Option<&RedisConfig> {
        self.redis_config.as_ref()
    }
}

#[async_trait]
impl GarrisonDao for GarrisonDaoOxcache {
    async fn get(&self, key: &str) -> GarrisonResult<Option<String>> {
        let actual_key = prefixed_key(key);
        self.cache
            .get_sync(&actual_key)
            .map_err(|e| GarrisonError::Dao(format!("dao-oxcache-get-sync::{}", e)))
    }

    async fn set(&self, key: &str, value: &str, ttl_seconds: u64) -> GarrisonResult<()> {
        let actual_key = prefixed_key(key);
        let ttl = if ttl_seconds == 0 {
            None
        } else {
            Some(Duration::from_secs(ttl_seconds))
        };
        self.cache
            .set_with_ttl_sync(&actual_key, &value.to_string(), ttl)
            .map_err(|e| GarrisonError::Dao(format!("dao-oxcache-set-with-ttl-sync::{}", e)))?;
        #[cfg(feature = "anomalous-detector-dual")]
        self.key_index.write().insert(actual_key);
        Ok(())
    }

    async fn update(&self, key: &str, value: &str) -> GarrisonResult<()> {
        // 通过 cache.ttl_sync() 读取剩余 TTL,用 set_with_ttl_sync 保留原 TTL(不重置过期时间)。
        // ttl_sync() 返回 None 表示永久驻留(set_with_ttl_sync 接受 None 表示无 TTL)。
        // 但 None 也可能表示键不存在,需要先检查键存在性。
        let actual_key = prefixed_key(key);
        if !self
            .cache
            .exists_sync(&actual_key)
            .map_err(|e| GarrisonError::Dao(format!("dao-oxcache-exists-sync::{}", e)))?
        {
            return Err(GarrisonError::Dao(format!("dao-key-missing::{}", key)));
        }
        let remaining_ttl = self
            .cache
            .ttl_sync(&actual_key)
            .map_err(|e| GarrisonError::Dao(format!("dao-oxcache-ttl-sync::{}", e)))?;
        self.cache
            .set_with_ttl_sync(&actual_key, &value.to_string(), remaining_ttl)
            .map_err(|e| GarrisonError::Dao(format!("dao-oxcache-update-set-with-ttl-sync::{}", e)))
    }

    async fn expire(&self, key: &str, seconds: u64) -> GarrisonResult<()> {
        // oxcache 0.3 的 Cache<K,V> 暴露了 expire_sync(key, ttl) 方法(原子更新 TTL,不触碰 value)。
        // expire_sync 返回 bool:true=更新成功,false=键不存在。
        // 注意:seconds=0 表示永久驻留,需要用 get_sync + set_with_ttl_sync(None) 实现
        // (cache.expire_sync(key, Duration::from_secs(0)) 会让键立即过期,不符合 spec 的 0=永久语义)。
        let actual_key = prefixed_key(key);
        if seconds == 0 {
            let value = self
                .cache
                .get_sync(&actual_key)
                .map_err(|e| GarrisonError::Dao(format!("dao-oxcache-get-sync::{}", e)))?
                .ok_or_else(|| GarrisonError::Dao(format!("dao-key-missing::{}", key)))?;
            self.cache
                .set_with_ttl_sync(&actual_key, &value, None)
                .map_err(|e| {
                    GarrisonError::Dao(format!("dao-oxcache-expire-set-with-ttl-sync::{}", e))
                })
        } else {
            let updated = self
                .cache
                .expire_sync(&actual_key, Duration::from_secs(seconds))
                .map_err(|e| GarrisonError::Dao(format!("dao-oxcache-expire-sync::{}", e)))?;
            if !updated {
                return Err(GarrisonError::Dao(format!("dao-key-missing::{}", key)));
            }
            Ok(())
        }
    }

    async fn delete(&self, key: &str) -> GarrisonResult<()> {
        let actual_key = prefixed_key(key);
        self.cache
            .delete_sync(&actual_key)
            .map_err(|e| GarrisonError::Dao(format!("dao-oxcache-delete-sync::{}", e)))?;
        #[cfg(feature = "anomalous-detector-dual")]
        self.key_index.write().remove(&actual_key);
        Ok(())
    }

    /// set_permanent 用 set_with_ttl_sync(None) 写入永久键。
    ///
    /// 重写默认实现以使用 oxcache 原生"无 TTL"API(避免 ttl=0 歧义)。
    async fn set_permanent(&self, key: &str, value: &str) -> GarrisonResult<()> {
        let actual_key = prefixed_key(key);
        self.cache
            .set_with_ttl_sync(&actual_key, &value.to_string(), None)
            .map_err(|e| GarrisonError::Dao(format!("dao-oxcache-set-with-ttl-sync::{}", e)))?;
        #[cfg(feature = "anomalous-detector-dual")]
        self.key_index.write().insert(actual_key);
        Ok(())
    }

    /// get_timeout 用 ttl_sync 查询剩余 TTL。
    ///
    /// oxcache 0.3 的 `ttl_sync(key)` 返回 `Option<Duration>`:
    /// - `Some(remaining)`: 键存在且设置了 TTL
    /// - `None`: 键不存在,或键存在但未设置 TTL(永久驻留)
    async fn get_timeout(&self, key: &str) -> GarrisonResult<Option<Duration>> {
        let actual_key = prefixed_key(key);
        self.cache
            .ttl_sync(&actual_key)
            .map_err(|e| GarrisonError::Dao(format!("dao-oxcache-ttl-sync::{}", e)))
    }

    /// rename 用 get → ttl_sync → set_with_ttl_sync → delete 四步。
    ///
    /// 重写默认实现以保留原键 TTL(用 `ttl_sync` 读取剩余 TTL,用 `set_with_ttl_sync` 写入)。
    /// 仍是**非原子**操作(oxcache 0.3.3 无原子 rename API,待 oxcache 提供原子 rename API)。
    async fn rename(&self, old_key: &str, new_key: &str) -> GarrisonResult<()> {
        let actual_old = prefixed_key(old_key);
        let actual_new = prefixed_key(new_key);
        let value = self
            .cache
            .get_sync(&actual_old)
            .map_err(|e| GarrisonError::Dao(format!("dao-oxcache-get-sync::{}", e)))?
            .ok_or_else(|| GarrisonError::InvalidParam(format!("dao-key-missing::{}", old_key)))?;
        let remaining_ttl = self
            .cache
            .ttl_sync(&actual_old)
            .map_err(|e| GarrisonError::Dao(format!("dao-oxcache-ttl-sync::{}", e)))?;
        self.cache
            .set_with_ttl_sync(&actual_new, &value, remaining_ttl)
            .map_err(|e| GarrisonError::Dao(format!("dao-oxcache-set-with-ttl-sync::{}", e)))?;
        self.cache
            .delete_sync(&actual_old)
            .map_err(|e| GarrisonError::Dao(format!("dao-oxcache-delete-sync::{}", e)))
    }

    /// get_and_delete 用 `parking_lot::Mutex` 保护 get+delete。
    ///
    /// 进程内原子:同一进程内并发调用同一 key 仅一个返回 `Some`。
    /// 跨进程限制:多进程共享 Redis L2 时,仍存在 TOCTOU 竞态
    /// (需 Redis Lua 脚本 `redis.call('GET',K[1]);redis.call('DEL',K[1])` 修复,待引入 Redis L2 后端)。
    async fn get_and_delete(&self, key: &str) -> GarrisonResult<Option<String>> {
        let _guard = self.atomic_lock.lock();
        let actual_key = prefixed_key(key);
        let value = self
            .cache
            .get_sync(&actual_key)
            .map_err(|e| GarrisonError::Dao(format!("dao-oxcache-get-sync::{}", e)))?;
        if value.is_some() {
            self.cache
                .delete_sync(&actual_key)
                .map_err(|e| GarrisonError::Dao(format!("dao-oxcache-delete-sync::{}", e)))?;
        }
        Ok(value)
    }

    /// incr 用 `parking_lot::Mutex` 保护原子性(进程内原子)。
    ///
    /// 在单个 lock() 作用域内完成 get → set_with_ttl_sync,保证进程内原子。
    /// key 已存在时通过 `ttl_sync` 读取剩余 TTL 并保留(不重置过期时间)。
    async fn incr(&self, key: &str, ttl_seconds: u64) -> GarrisonResult<u64> {
        let _guard = self.atomic_lock.lock();
        let actual_key = prefixed_key(key);
        match self
            .cache
            .get_sync(&actual_key)
            .map_err(|e| GarrisonError::Dao(format!("dao-oxcache-get-sync::{}", e)))?
        {
            Some(v) => {
                // Rule 12:parse 失败必须显式报错,禁止静默返回 0 导致计数器重置
                let cur_val: u64 = v.parse().map_err(|_| {
                    GarrisonError::Dao(format!(
                        "incr: 现存值非 u64,key={}, value={}",
                        actual_key, v
                    ))
                })?;
                let new_val = cur_val + 1;
                let remaining_ttl = self
                    .cache
                    .ttl_sync(&actual_key)
                    .map_err(|e| GarrisonError::Dao(format!("dao-oxcache-ttl-sync::{}", e)))?;
                self.cache
                    .set_with_ttl_sync(&actual_key, &new_val.to_string(), remaining_ttl)
                    .map_err(|e| {
                        GarrisonError::Dao(format!("dao-oxcache-set-with-ttl-sync::{}", e))
                    })?;
                Ok(new_val)
            },
            None => {
                let ttl = if ttl_seconds == 0 {
                    None
                } else {
                    Some(Duration::from_secs(ttl_seconds))
                };
                self.cache
                    .set_with_ttl_sync(&actual_key, &"1".to_string(), ttl)
                    .map_err(|e| {
                        GarrisonError::Dao(format!("dao-oxcache-set-with-ttl-sync::{}", e))
                    })?;
                Ok(1)
            },
        }
    }

    /// keys 用 key_index 实现(oxcache 0.3.3 无原生 keys/iter API)。
    ///
    /// 遍历 key_index,过滤匹配 pattern 的 key,同时惰性清理已过期的 key。
    /// pattern 支持 `*` 通配符(与 MockDao::keys 一致)。
    #[cfg(feature = "anomalous-detector-dual")]
    async fn keys(&self, pattern: &str) -> GarrisonResult<Vec<String>> {
        let actual_pattern = prefixed_key(pattern);
        let mut result = Vec::new();
        let mut expired_keys = Vec::new();

        {
            let index = self.key_index.read();
            for key in index.iter() {
                if matches_pattern(key, &actual_pattern) {
                    // 检查 key 是否仍然存在(TTL 可能已过期)
                    if self.cache.exists_sync(key).unwrap_or(false) {
                        // 去除 prefix 返回原始 key
                        let raw_key = strip_prefix(key);
                        result.push(raw_key);
                    } else {
                        expired_keys.push(key.clone());
                    }
                }
            }
        }

        // 惰性清理过期 key
        if !expired_keys.is_empty() {
            let mut index = self.key_index.write();
            for key in &expired_keys {
                index.remove(key);
            }
            tracing::debug!("keys() 清理了 {} 个过期 key", expired_keys.len());
        }

        Ok(result)
    }
}