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

//! `DbnexusKvDao` — SQL 持久化 KV(`garrison_kv` 表):garrison-cli `change-key` / `check-key`
//! 的数据寻址层。`GarrisonDaoDbnexus` 的 KV 委托给进程内实例(如 `InMemoryDao`),跨进程不可
//! 持久化——离线运维命令需要一个把 KV 落在部署库里的委托实现,本模块补齐该空档。
//!
//! `#[cfg(any(db-sqlite, db-postgres, db-mysql))]` 门控(与 [`GarrisonDaoDbnexus`](super::dbnexus_dao) 一致)。
//!
//! # 语义
//!
//! 行为镜像 [`InMemoryDao`](crate::dao::InMemoryDao):glob `keys`(`*`/`?`)、TTL 过期行在读路径
//! 视为不存在(`update`/`expire` 对其显性 `dao-key-missing`,不复活)、`incr`/`decr` 计数器
//! (`incr` 保留原 TTL、`decr` 到 0 删键)、`compare_and_swap` 的 `expected=None` 语义为键不存在。
//! 差异仅在介质:时间基准为 UTC unix 秒(跨进程可比)。`set_if_absent`(含 `compare_and_swap(None)`
//! 委托)为过期行接管原子:SQLite/PG 臂以 `ON CONFLICT (k) DO UPDATE ... WHERE` 过期谓词单语句承载
//! (旧 `INSERT OR IGNORE` 臂为 SQLite 专属语法、PostgreSQL 不可解析的缺陷随本重写闭合);MySQL 臂以
//! 事务 + `SELECT ... FOR UPDATE` 行锁内判定后写入——ODKU 的 affected 计数在 sqlx 无条件
//! CLIENT_FOUND_ROWS 握手下「无变化更新」回报 1,插入/接管/拒绝三态塌缩不可判(MySQL 8.0 真库
//! acceptance 实证),行锁临界区的原子性与单语句等价。
//! 其余读-改-写方法(`incr`/`decr`/`rename`/`get_and_delete`)为两步(调用面为离线 CLI,无并发写者;
//! trait 文档要求的临界区原子性由单语句路径保证)。
//!
//! # vacuum 与升级遗留行
//!
//! [`vacuum_expired`](GarrisonDao::vacuum_expired)(trait 默认 no-op,本实现覆写)全表清理
//! `expire_at` 非空且 ≤ 当前时间的行(`expire_at IS NULL` 永久行不动),幂等返回删除计数;
//! 会话 key 余段 SHA-256 摘要化(`session::token_key`)升级后遗留的 raw key 行不再被寻址,
//! 由本方法或 garrison-cli `vacuum-kv` 收敛。`keys()` 返回的 Token-Session key 余段为摘要形态,
//! 不可反解为 token。本 DAO 的定位仍是「离线 CLI 调用面、无并发写者」——被用作多副本共享会话
//! 后端属超出契约的用法(除单语句方法外无跨进程原子性),如需该用法应自备写者间协调或选用
//! Redis 后端。
//!
//! 结构化表操作与 `eval_lua` 走 trait 默认 `NotImplemented`:前者由
//! [`GarrisonDaoDbnexus`](super::dbnexus_dao) 的 SQL 方法承载,后者属 Redis 后端能力。

use super::GarrisonDao;
use crate::dao::repository::make_statement;
use crate::error::{GarrisonError, GarrisonResult};
use async_trait::async_trait;
use dbnexus::sea_orm::{ConnectionTrait, DbBackend, Value};
use dbnexus::DbPool;
use std::time::Duration;

/// SQL 持久化 KV DAO:`garrison_kv` 表(k / v / expire_at),语义镜像 `InMemoryDao`。
pub struct DbnexusKvDao {
    pool: DbPool,
}

/// 会话 + 连接获取样板(展开出 `$session`(owned)与 `$conn`(借用)两个绑定)。
macro_rules! kv_session {
    ($self:expr, $op:expr, $session:ident, $conn:ident) => {
        let $session = $self
            .pool
            .get_session("admin")
            .await
            .map_err(|e| GarrisonError::Dao(format!("dao-kv-{}-session::{}", $op, e)))?;
        let $conn = $session
            .connection()
            .map_err(|e| GarrisonError::Dao(format!("dao-kv-{}-connection::{}", $op, e)))?;
    };
}

impl DbnexusKvDao {
    /// 创建 KV DAO(表由 [`ensure_table`](Self::ensure_table) 幂等创建)。
    pub fn new(pool: DbPool) -> Self {
        Self { pool }
    }

    /// 幂等建表(CLI 打开即调;部署库亦可经 `migrate_core` 的 `018_kv_store.sql` 预建)。
    pub async fn ensure_table(&self) -> GarrisonResult<()> {
        kv_session!(self, "ensure-table", session, conn);
        // MySQL 的 VARCHAR 必须带长度(裸 VARCHAR 是语法错误),与 `018_kv_store.sql` 的
        // MySQL 迁移文件对齐用 VARCHAR(255);SQLite/PG 裸 VARCHAR 合法
        let k_type = match conn.get_database_backend() {
            DbBackend::MySql => "VARCHAR(255)",
            _ => "VARCHAR",
        };
        let stmt = make_statement(
            conn,
            &format!(
                "CREATE TABLE IF NOT EXISTS garrison_kv (\
                 k {k_type} PRIMARY KEY, \
                 v TEXT NOT NULL, \
                 expire_at BIGINT)"
            ),
            vec![],
        );
        conn.execute_raw(stmt)
            .await
            .map_err(|e| GarrisonError::Dao(format!("dao-kv-ensure-table-execute::{e}")))?;
        Ok(())
    }

    fn now_secs() -> i64 {
        std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .map(|d| d.as_secs() as i64)
            .unwrap_or_default()
    }

    /// 「未过期」谓词(绑定尾部 `now` 参数后使用)。
    fn live_cond() -> &'static str {
        "(expire_at IS NULL OR expire_at > ?)"
    }

    fn expire_at_from_ttl(ttl_seconds: u64) -> Option<i64> {
        if ttl_seconds == 0 {
            None
        } else {
            Some(Self::now_secs() + ttl_seconds as i64)
        }
    }

    fn remaining_secs(expire_at: Option<i64>) -> Option<Duration> {
        expire_at.map(|at| Duration::from_secs((at - Self::now_secs()).max(0) as u64))
    }

    async fn query_row(
        &self,
        op: &str,
        sql: &str,
        values: Vec<Value>,
    ) -> GarrisonResult<Option<(String, Option<i64>)>> {
        kv_session!(self, op, session, conn);
        let stmt = make_statement(conn, sql, values);
        let rows = conn
            .query_all_raw(stmt)
            .await
            .map_err(|e| GarrisonError::Dao(format!("dao-kv-{op}-query::{e}")))?;
        match rows.first() {
            None => Ok(None),
            Some(row) => {
                let v = row
                    .try_get::<String>("", "v")
                    .map_err(|e| GarrisonError::Dao(format!("dao-kv-{op}-read-v::{e}")))?;
                let expire_at = row
                    .try_get::<Option<i64>>("", "expire_at")
                    .map_err(|e| GarrisonError::Dao(format!("dao-kv-{op}-read-expire::{e}")))?;
                Ok(Some((v, expire_at)))
            },
        }
    }

    async fn execute(&self, op: &str, sql: &str, values: Vec<Value>) -> GarrisonResult<u64> {
        kv_session!(self, op, session, conn);
        let stmt = make_statement(conn, sql, values);
        let result = conn
            .execute_raw(stmt)
            .await
            .map_err(|e| GarrisonError::Dao(format!("dao-kv-{op}-execute::{e}")))?;
        Ok(result.rows_affected())
    }

    /// upsert(`expire_at: None` = 永久);方言分支仅冲突处理子句不同。
    async fn upsert(&self, key: &str, value: &str, expire_at: Option<i64>) -> GarrisonResult<()> {
        kv_session!(self, "upsert", session, conn);
        let sql = match conn.get_database_backend() {
            DbBackend::MySql => {
                "INSERT INTO garrison_kv (k, v, expire_at) VALUES (?, ?, ?) \
                 ON DUPLICATE KEY UPDATE v = VALUES(v), expire_at = VALUES(expire_at)"
            },
            _ => {
                "INSERT INTO garrison_kv (k, v, expire_at) VALUES (?, ?, ?) \
                 ON CONFLICT (k) DO UPDATE SET v = excluded.v, expire_at = excluded.expire_at"
            },
        };
        let stmt = make_statement(
            conn,
            sql,
            vec![
                Value::String(Some(key.to_string())),
                Value::String(Some(value.to_string())),
                Value::BigInt(expire_at),
            ],
        );
        conn.execute_raw(stmt)
            .await
            .map_err(|e| GarrisonError::Dao(format!("dao-kv-upsert-execute::{e}")))?;
        Ok(())
    }

    /// 读取未过期行的 `(v, expire_at)`;过期行顺带惰性删除(与 InMemoryDao 的访问清理一致)。
    async fn live_row(&self, op: &str, key: &str) -> GarrisonResult<Option<(String, Option<i64>)>> {
        let now = Self::now_secs();
        let found = self
            .query_row(
                op,
                &format!(
                    "SELECT v, expire_at FROM garrison_kv WHERE k = ? AND {}",
                    Self::live_cond()
                ),
                vec![
                    Value::String(Some(key.to_string())),
                    Value::BigInt(Some(now)),
                ],
            )
            .await?;
        if found.is_none() {
            self.execute(
                &format!("{op}-cleanup"),
                &format!(
                    "DELETE FROM garrison_kv WHERE k = ? AND {}",
                    Self::expired_cond()
                ),
                vec![
                    Value::String(Some(key.to_string())),
                    Value::BigInt(Some(now)),
                ],
            )
            .await?;
        }
        Ok(found)
    }

    fn expired_cond() -> &'static str {
        "(expire_at IS NOT NULL AND expire_at <= ?)"
    }
}

#[async_trait]
impl GarrisonDao for DbnexusKvDao {
    async fn get(&self, key: &str) -> GarrisonResult<Option<String>> {
        Ok(self.live_row("get", key).await?.map(|(v, _)| v))
    }

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

    async fn update(&self, key: &str, value: &str) -> GarrisonResult<()> {
        let now = Self::now_secs();
        let affected = self
            .execute(
                "update",
                &format!(
                    "UPDATE garrison_kv SET v = ? WHERE k = ? AND {}",
                    Self::live_cond()
                ),
                vec![
                    Value::String(Some(value.to_string())),
                    Value::String(Some(key.to_string())),
                    Value::BigInt(Some(now)),
                ],
            )
            .await?;
        if affected == 0 {
            return Err(GarrisonError::Dao(format!("dao-key-missing::{key}")));
        }
        Ok(())
    }

    async fn expire(&self, key: &str, seconds: u64) -> GarrisonResult<()> {
        let now = Self::now_secs();
        let affected = self
            .execute(
                "expire",
                &format!(
                    "UPDATE garrison_kv SET expire_at = ? WHERE k = ? AND {}",
                    Self::live_cond()
                ),
                vec![
                    Value::BigInt(Self::expire_at_from_ttl(seconds)),
                    Value::String(Some(key.to_string())),
                    Value::BigInt(Some(now)),
                ],
            )
            .await?;
        if affected == 0 {
            return Err(GarrisonError::Dao(format!("dao-key-missing::{key}")));
        }
        Ok(())
    }

    async fn delete(&self, key: &str) -> GarrisonResult<()> {
        self.execute(
            "delete",
            "DELETE FROM garrison_kv WHERE k = ?",
            vec![Value::String(Some(key.to_string()))],
        )
        .await?;
        Ok(())
    }

    /// 过期行清理(vacuum):全表单语句 DELETE,作用于共享表全命名空间安全——各子系统行均有 TTL,
    /// 过期 = 语义已死;`expire_at IS NULL` 永久行不受影响;幂等,返回物理删除行数。
    async fn vacuum_expired(&self) -> GarrisonResult<u64> {
        let now = Self::now_secs();
        self.execute(
            "vacuum-expired",
            &format!("DELETE FROM garrison_kv WHERE {}", Self::expired_cond()),
            vec![Value::BigInt(Some(now))],
        )
        .await
    }

    async fn set_if_absent(
        &self,
        key: &str,
        value: &str,
        ttl_seconds: u64,
    ) -> GarrisonResult<bool> {
        kv_session!(self, "set-if-absent", session, conn);
        let now = Self::now_secs();
        let expire_at = Self::expire_at_from_ttl(ttl_seconds);
        // 过期接管原子:键不存在或已过期(expired 谓词成立)才写入,存活行拒绝且不动。
        //
        // MySQL 臂:事务 + `SELECT ... FOR UPDATE` 行锁内判定后写入——不可用 ODKU 的 affected
        // 计数承载成败判定:sqlx MySQL 握手无条件置 CLIENT_FOUND_ROWS,ODKU「无变化更新」
        // 回报 matched(1)而非 0,插入/接管/拒绝三态塌缩不可判(2026-10-18 MySQL 8.0 真库
        // acceptance 实证)。行锁下 SELECT 读到最新提交,并发争抢串行化,原子性等价单语句。
        // SQLite/PG 臂:单语句条件 upsert(`ON CONFLICT ... WHERE` 谓词),rows_affected
        // 反映真实插入/更新/跳过(PG cmdTuples、SQLite changes() 均不受 found-rows 类语义影响)。
        if conn.get_database_backend() == DbBackend::MySql {
            use dbnexus::sea_orm::TransactionTrait;
            let txn = conn
                .begin()
                .await
                .map_err(|e| GarrisonError::Dao(format!("dao-kv-set-if-absent-begin::{e}")))?;
            let sel = make_statement(
                &txn,
                "SELECT v, expire_at FROM garrison_kv WHERE k = ? FOR UPDATE",
                vec![Value::String(Some(key.to_string()))],
            );
            let rows = txn
                .query_all_raw(sel)
                .await
                .map_err(|e| GarrisonError::Dao(format!("dao-kv-set-if-absent-select::{e}")))?;
            let live = match rows.first() {
                None => false,
                Some(row) => {
                    let expire = row.try_get::<Option<i64>>("", "expire_at").map_err(|e| {
                        GarrisonError::Dao(format!("dao-kv-set-if-absent-read-expire::{e}"))
                    })?;
                    expire.is_none() || expire > Some(now)
                },
            };
            let result = if live {
                Ok(false)
            } else {
                let up = make_statement(
                    &txn,
                    "INSERT INTO garrison_kv (k, v, expire_at) VALUES (?, ?, ?) \
                     ON DUPLICATE KEY UPDATE v = ?, expire_at = ?",
                    vec![
                        Value::String(Some(key.to_string())),
                        Value::String(Some(value.to_string())),
                        Value::BigInt(expire_at),
                        Value::String(Some(value.to_string())),
                        Value::BigInt(expire_at),
                    ],
                );
                txn.execute_raw(up).await.map_err(|e| {
                    GarrisonError::Dao(format!("dao-kv-set-if-absent-execute::{e}"))
                })?;
                Ok(true)
            };
            txn.commit()
                .await
                .map_err(|e| GarrisonError::Dao(format!("dao-kv-set-if-absent-commit::{e}")))?;
            return result;
        }
        let (sql, values) = (
            "INSERT INTO garrison_kv (k, v, expire_at) VALUES (?, ?, ?) \
             ON CONFLICT (k) DO UPDATE SET v = excluded.v, expire_at = excluded.expire_at \
             WHERE (garrison_kv.expire_at IS NOT NULL AND garrison_kv.expire_at <= ?)",
            vec![
                Value::String(Some(key.to_string())),
                Value::String(Some(value.to_string())),
                Value::BigInt(expire_at),
                Value::BigInt(Some(now)),
            ],
        );
        let stmt = make_statement(conn, sql, values);
        let result = conn
            .execute_raw(stmt)
            .await
            .map_err(|e| GarrisonError::Dao(format!("dao-kv-set-if-absent-execute::{e}")))?;
        Ok(result.rows_affected() > 0)
    }

    async fn get_timeout(&self, key: &str) -> GarrisonResult<Option<Duration>> {
        Ok(self
            .live_row("get-timeout", key)
            .await?
            .and_then(|(_, expire_at)| Self::remaining_secs(expire_at)))
    }

    #[cfg(feature = "dao-key-index")]
    async fn keys(&self, pattern: &str) -> GarrisonResult<Vec<String>> {
        let now = Self::now_secs();
        kv_session!(self, "keys", session, conn);
        let stmt = make_statement(
            conn,
            &format!(
                "SELECT k, expire_at FROM garrison_kv WHERE {}",
                Self::live_cond()
            ),
            vec![Value::BigInt(Some(now))],
        );
        let rows = conn
            .query_all_raw(stmt)
            .await
            .map_err(|e| GarrisonError::Dao(format!("dao-kv-keys-query::{e}")))?;
        let mut keys = Vec::new();
        for row in &rows {
            let k = row
                .try_get::<String>("", "k")
                .map_err(|e| GarrisonError::Dao(format!("dao-kv-keys-read-k::{e}")))?;
            if super::in_memory::glob_match(pattern, &k) {
                keys.push(k);
            }
        }
        Ok(keys)
    }

    async fn rename(&self, old_key: &str, new_key: &str) -> GarrisonResult<()> {
        let Some((v, expire_at)) = self.live_row("rename", old_key).await? else {
            return Err(GarrisonError::InvalidParam(format!(
                "dao-key-not-found::{old_key}"
            )));
        };
        self.upsert(new_key, &v, expire_at).await?;
        self.delete(old_key).await?;
        Ok(())
    }

    async fn get_and_delete(&self, key: &str) -> GarrisonResult<Option<String>> {
        let Some((v, _)) = self.live_row("get-and-delete", key).await? else {
            return Ok(None);
        };
        self.delete(key).await?;
        Ok(Some(v))
    }

    async fn incr(&self, key: &str, ttl_seconds: u64) -> GarrisonResult<u64> {
        let Some((v, expire_at)) = self.live_row("incr", key).await? else {
            self.set(key, "1", ttl_seconds).await?;
            return Ok(1);
        };
        let cur: u64 = v
            .parse()
            .map_err(|_| GarrisonError::Dao(format!("dao-incr-parse-u64::{key}::{v}")))?;
        let new_val = cur
            .checked_add(1)
            .ok_or_else(|| GarrisonError::Dao(format!("dao-incr-overflow-u64::{key}")))?;
        // 保留原 expire_at(不重置 TTL,与 InMemoryDao 语义一致)
        self.upsert(key, &new_val.to_string(), expire_at).await?;
        Ok(new_val)
    }

    async fn decr(&self, key: &str) -> GarrisonResult<u64> {
        let Some((v, expire_at)) = self.live_row("decr", key).await? else {
            return Ok(0);
        };
        let cur: u64 = v
            .parse()
            .map_err(|_| GarrisonError::Dao(format!("dao-decr-parse-u64::{key}::{v}")))?;
        if cur == 0 {
            return Ok(0);
        }
        let new_val = cur - 1;
        if new_val == 0 {
            self.delete(key).await?;
        } else {
            self.upsert(key, &new_val.to_string(), expire_at).await?;
        }
        Ok(new_val)
    }

    async fn compare_and_swap(
        &self,
        key: &str,
        expected: Option<&str>,
        new_value: &str,
        ttl_seconds: u64,
    ) -> GarrisonResult<bool> {
        // 先清理过期行(过期视为不存在)
        let now = Self::now_secs();
        self.execute(
            "compare-and-swap-cleanup",
            &format!(
                "DELETE FROM garrison_kv WHERE k = ? AND {}",
                Self::expired_cond()
            ),
            vec![
                Value::String(Some(key.to_string())),
                Value::BigInt(Some(now)),
            ],
        )
        .await?;
        match expected {
            // 单语句原子 CAS:当前值等于 expected 才写入
            Some(expected_value) => {
                let affected = self
                    .execute(
                        "compare-and-swap",
                        "UPDATE garrison_kv SET v = ?, expire_at = ? WHERE k = ? AND v = ?",
                        vec![
                            Value::String(Some(new_value.to_string())),
                            Value::BigInt(Self::expire_at_from_ttl(ttl_seconds)),
                            Value::String(Some(key.to_string())),
                            Value::String(Some(expected_value.to_string())),
                        ],
                    )
                    .await?;
                Ok(affected > 0)
            },
            None => self.set_if_absent(key, new_value, ttl_seconds).await,
        }
    }
}