wordval-web 1.0.13

Wordval web layer: router, middleware, extractors, responses, session-based authentication
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
//! 全局资源注册表
//!
//! 所有资源统一通过全局单例访问,代码更简洁。
//!
//! # 示例
//!
//! ```ignore
//! use wordval::{db, db_default, cfg, render_template};
//!
//! async fn query_user(id: &str) -> Result<Option<Row>, String> {
//!     let users = db_default().find_by_id("user", id).await?;
//!     Ok(users)
//! }
//!
//! async fn page_home() -> Result<Html<String>, String> {
//!     let content = render_template("home.html", &json!({"title": cfg().app_name}))?;
//!     Ok(Html(content))
//! }
//! ```

#[cfg(feature = "db")]
use parking_lot::RwLock;
#[cfg(feature = "db")]
use std::collections::HashMap;
use std::sync::Arc;
use std::sync::OnceLock;
use std::time::Duration;

use crate::audit::{AuditRecord, AuditWriter};
#[cfg(feature = "template")]
use crate::template_engine::TemplateEngine;
#[cfg(feature = "cache")]
use wordval_cache::SharedCache;
use wordval_config::ConfigManager;
#[cfg(feature = "db")]
use wordval_db::Db;
#[cfg(feature = "fs")]
use wordval_fs::FsBackendEnum;

// 全局资源实例(单例,标准库 OnceLock)
/// 命名数据库注册表:别名 → Db。
/// 运行时可扩展([`register_db`]/[`remove_db`]),读多写少,parking_lot RwLock 保护。
/// 访问器返回 `Db` 的廉价克隆(内部连接池是 Arc),避免返回内部引用的生存期问题。
#[cfg(feature = "db")]
static DBS: OnceLock<RwLock<HashMap<String, Db>>> = OnceLock::new();
#[cfg(feature = "cache")]
static CACHE: OnceLock<SharedCache> = OnceLock::new();
static CONFIG: OnceLock<Arc<ConfigManager>> = OnceLock::new();
#[cfg(feature = "fs")]
static FS: OnceLock<FsBackendEnum> = OnceLock::new();
#[cfg(feature = "template")]
static TEMPLATE: OnceLock<TemplateEngine> = OnceLock::new();
static UPLOAD_PATH: OnceLock<String> = OnceLock::new();
static DOWNLOAD_PATH: OnceLock<String> = OnceLock::new();
/// 审计写入器:`AuditWriter` 内部含 `Mutex`/一次性 flush 句柄,不可克隆,
/// 故以 `Arc` 单例形式全局共享。
static AUDIT: OnceLock<Arc<AuditWriter>> = OnceLock::new();

// ── 设置资源(框架启动时调用)───────────────────────────────────────

/// 注册表句柄(首次访问时惰性建空表)
#[cfg(feature = "db")]
fn registry() -> &'static RwLock<HashMap<String, Db>> {
    DBS.get_or_init(|| RwLock::new(HashMap::new()))
}

/// 初始化数据库(单库便捷入口,等价于仅注册 `default` 命名库)
#[cfg(feature = "db")]
pub fn set_db(db: Db) -> Result<(), &'static str> {
    let mut map = registry().write();
    if map.contains_key(DEFAULT_DB_NAME) {
        return Err("数据库资源已初始化");
    }
    map.insert(DEFAULT_DB_NAME.to_string(), db);
    Ok(())
}

/// 默认数据库别名,与 [`crate::resources::set_dbs`] 的注册表约定一致
#[cfg(feature = "db")]
pub const DEFAULT_DB_NAME: &str = "default";

/// 批量初始化命名数据库注册表(多库入口)
///
/// 注册表必须包含 `default` 别名([`db_default`] 返回它);已初始化时拒绝重复写入。
/// 整表替换语义:应先于任何 [`register_db`] 调用(框架启动期专用)。
#[cfg(feature = "db")]
pub fn set_dbs(dbs: HashMap<String, Db>) -> Result<(), &'static str> {
    if !dbs.contains_key(DEFAULT_DB_NAME) {
        return Err("数据库注册表必须包含 default 库");
    }
    let mut map = registry().write();
    if map.contains_key(DEFAULT_DB_NAME) {
        return Err("数据库资源已初始化");
    }
    *map = dbs;
    Ok(())
}

/// 初始化缓存
#[cfg(feature = "cache")]
pub fn set_cache(cache: SharedCache) -> Result<(), &'static str> {
    CACHE.set(cache).map_err(|_| "缓存资源已初始化")
}

/// 初始化文件存储后端
#[cfg(feature = "fs")]
pub fn set_fs(fs: FsBackendEnum) -> Result<(), &'static str> {
    FS.set(fs).map_err(|_| "文件存储资源已初始化")
}

/// 初始化配置
pub fn set_config(config: Arc<ConfigManager>) -> Result<(), &'static str> {
    CONFIG.set(config).map_err(|_| "配置资源已初始化")
}

/// 初始化审计写入器
///
/// 框架启动期按 `middleware.audit` 配置自动调用;宿主实现自己的
/// [`AuditSink`] 时也可经 `App::audit_writer` 传入或直接调用本函数。
/// 已初始化时拒绝重复写入(`Err`),不做静默替换。
pub fn set_audit_writer(writer: Arc<AuditWriter>) -> Result<(), &'static str> {
    AUDIT.set(writer).map_err(|_| "审计写入器已初始化")
}

/// 初始化模板引擎
#[cfg(feature = "template")]
pub fn set_template(template: TemplateEngine) -> Result<(), &'static str> {
    TEMPLATE.set(template).map_err(|_| "模板引擎已初始化")
}

// ── 获取资源(业务代码调用)────────────────────────────────────────

/// [`db`] 返回的包装器:Deref 直接访问 default 库,`.using("alias")` 切换命名库。
///
/// ```ignore
/// db().find_by_id("user", id).await?;          // default 库
/// db().using("report").find_all("events").await?; // 命名库
/// ```
#[cfg(feature = "db")]
pub struct DbHandle {
    db: Db,
}

#[cfg(feature = "db")]
impl std::ops::Deref for DbHandle {
    type Target = Db;
    fn deref(&self) -> &Db {
        &self.db
    }
}

#[cfg(feature = "db")]
impl DbHandle {
    /// 切换到指定别名的命名库(返回 `Db` 廉价克隆,内部连接池是 Arc)
    ///
    /// # Panics
    ///
    /// 别名未注册时 panic(附已注册别名列表便于排查);不确定时请用 [`try_using`]。
    pub fn using(self, alias: &str) -> Db {
        try_using(alias).unwrap_or_else(|| {
            panic!(
                "数据库 '{}' 未注册,已注册别名: {:?}",
                alias,
                db_names()
            )
        })
    }
}

/// 获取默认数据库句柄(Deref 访问 default 库,`.using("alias")` 切换命名库)
///
/// # Panics
///
/// 若未调用 [`set_db`]/[`set_dbs`] 初始化则 panic;不确定时请用 [`try_db`]。
#[cfg(feature = "db")]
pub fn db() -> DbHandle {
    try_db().unwrap_or_else(|| panic!("数据库未初始化,请先调用 set_db()/set_dbs()"))
}

/// 安全获取默认数据库句柄(返回 Option)
#[cfg(feature = "db")]
pub fn try_db() -> Option<DbHandle> {
    try_using(DEFAULT_DB_NAME).map(|db| DbHandle { db })
}

/// 获取默认数据库实例(等价于 `db().using("default")`,适合需要 `&Db` 参数的调用点)
///
/// # Panics
///
/// 若未调用 [`set_db`]/[`set_dbs`] 初始化则 panic。
#[cfg(feature = "db")]
pub fn db_default() -> Db {
    try_using(DEFAULT_DB_NAME)
        .unwrap_or_else(|| panic!("数据库未初始化,请先调用 set_db()/set_dbs()"))
}

/// 安全按别名获取命名数据库(返回 Option)
#[cfg(feature = "db")]
pub fn try_using(alias: &str) -> Option<Db> {
    registry().read().get(alias).cloned()
}

/// 运行时注册/覆盖命名数据库(多租户等动态连库场景)
///
/// 业务层先用 [`wordval_db::create_db`] 建立连接,再注册别名供全局取用。
/// 与启动期的 [`set_db`]/[`set_dbs`] 不同,本函数可在任意时刻调用。
/// 同名重复注册为覆盖语义:旧实例被 Drop,其空闲连接由连接池异步回收。
#[cfg(feature = "db")]
pub fn register_db(alias: &str, db: Db) {
    registry().write().insert(alias.to_string(), db);
}

/// 注销命名数据库
///
/// 返回 `Ok(Some(db))`(被移除的实例)/ `Ok(None)`(别名不存在);
/// `default` 库是 [`db_default`] 的不变量,移除返回 `Err`。
#[cfg(feature = "db")]
pub fn remove_db(alias: &str) -> Result<Option<Db>, &'static str> {
    if alias == DEFAULT_DB_NAME {
        tracing::warn!("拒绝移除 default 数据库(db_default 的不变量)");
        return Err("不能移除 default 数据库");
    }
    Ok(registry().write().remove(alias))
}

/// 已注册的数据库别名列表(未初始化时为空)
#[cfg(feature = "db")]
pub fn db_names() -> Vec<String> {
    registry().read().keys().cloned().collect()
}

/// 获取全局缓存实例
///
/// # Panics
///
/// 若未调用 [`set_cache`] 初始化则 panic;不确定是否已初始化时请使用 [`try_cache`]。
#[cfg(feature = "cache")]
pub fn cache() -> &'static SharedCache {
    CACHE.get().expect("缓存未初始化,请先调用 set_cache()")
}

/// 安全获取缓存(返回 Option)
#[cfg(feature = "cache")]
pub fn try_cache() -> Option<&'static SharedCache> {
    CACHE.get()
}

/// 获取全局文件存储后端
///
/// # Panics
///
/// 若未调用 [`set_fs`] 初始化则 panic;不确定是否已初始化时请使用 [`try_fs`]。
#[cfg(feature = "fs")]
pub fn fs() -> &'static FsBackendEnum {
    FS.get().expect("文件存储未初始化,请先调用 set_fs()")
}

/// 安全获取文件存储后端(返回 Option)
#[cfg(feature = "fs")]
pub fn try_fs() -> Option<&'static FsBackendEnum> {
    FS.get()
}

/// 获取全局配置管理器
///
/// # Panics
///
/// 若未调用 [`set_config`] 初始化则 panic;不确定是否已初始化时请使用 [`try_config`]。
pub fn config() -> &'static Arc<ConfigManager> {
    CONFIG.get().expect("配置未初始化,请先调用 set_config()")
}

/// 安全获取配置(返回 Option)
pub fn try_config() -> Option<&'static Arc<ConfigManager>> {
    CONFIG.get()
}

/// 获取全局配置(快捷方式)
pub fn cfg() -> &'static wordval_config::AppConfig {
    config().get()
}

/// 获取全局审计写入器
///
/// # Panics
///
/// 若未初始化(`middleware.audit.enabled` 或 `set_audit_writer`/`App::audit_writer`)
/// 则 panic;不确定时请用 [`try_audit_writer`],只想丢一条记录时直接用 [`audit_write`]。
pub fn audit_writer() -> &'static AuditWriter {
    AUDIT
        .get()
        .expect("审计未初始化,请启用 middleware.audit.enabled 或调用 set_audit_writer()")
}

/// 安全获取审计写入器(返回 Option)
pub fn try_audit_writer() -> Option<&'static AuditWriter> {
    AUDIT.get().map(Arc::as_ref)
}

/// 提交一条审计记录(业务侧一行入口)
///
/// 未初始化审计写入器时静默忽略——审计是旁路能力,不该让业务代码为它判空;
/// 需要区分"未启用"与"队列满丢弃"时请用 [`try_audit_writer`] 自行判断。
pub fn audit_write(record: AuditRecord) {
    if let Some(writer) = AUDIT.get() {
        writer.write(record);
    }
}

/// 关停全局审计写入器并排空存量记录(框架在优雅停机时调用)
///
/// 未初始化时直接返回 `Ok(())`(幂等,可重复调用)。
pub async fn shutdown_audit_writer(timeout: Duration) -> wordval_core::Result<()> {
    match AUDIT.get() {
        Some(writer) => writer.shutdown(Some(timeout)).await,
        None => Ok(()),
    }
}

/// 渲染模板(便捷函数)
#[cfg(feature = "template")]
pub fn render_template<T: serde::Serialize>(
    name: &str,
    context: &T,
) -> wordval_core::Result<String> {
    TEMPLATE
        .get()
        .ok_or_else(|| wordval_core::Error::Template("模板引擎未初始化".into()))
        .and_then(|t| t.render(name, context))
}

/// 安全获取模板引擎(返回 Option)
#[cfg(feature = "template")]
pub fn try_template() -> Option<&'static TemplateEngine> {
    TEMPLATE.get()
}

/// 初始化上传文件存储路径
pub fn set_upload_path(path: String) -> Result<(), &'static str> {
    UPLOAD_PATH.set(path).map_err(|_| "上传路径已初始化")
}

/// 获取上传文件存储路径
pub fn upload_path() -> &'static str {
    UPLOAD_PATH.get().map(|s| s.as_str()).unwrap_or("uploads")
}

/// 安全获取上传路径(返回 Option)
pub fn try_upload_path() -> Option<&'static str> {
    UPLOAD_PATH.get().map(|s| s.as_str())
}

/// 初始化下载文件存储路径
pub fn set_download_path(path: String) -> Result<(), &'static str> {
    DOWNLOAD_PATH.set(path).map_err(|_| "下载路径已初始化")
}

/// 获取下载文件存储路径
pub fn download_path() -> &'static str {
    DOWNLOAD_PATH
        .get()
        .map(|s| s.as_str())
        .unwrap_or("downloads")
}

/// 安全获取下载路径(返回 Option)
pub fn try_download_path() -> Option<&'static str> {
    DOWNLOAD_PATH.get().map(|s| s.as_str())
}

#[cfg(all(test, feature = "db"))]
mod db_registry_tests {
    use super::*;

    /// 数据库注册表是进程级全局状态:本模块的测试必须串行,
    /// 否则并行的 A 测试刚 `register_db(DEFAULT_DB_NAME, …)` 就被 B 测试换成
    /// 另一个临时库,表现为"表不存在"之类的假失败(单跑必过、并发偶发)。
    static REGISTRY_LOCK: tokio::sync::Mutex<()> = tokio::sync::Mutex::const_new(());

    /// 构造一个独立的 sqlite 临时文件库(经公开工厂创建,避免引入 sqlx 直接依赖)
    async fn temp_db(tag: &str) -> Db {
        let dir = std::env::temp_dir().join(format!("wv_res_db_{}", std::process::id()));
        std::fs::create_dir_all(&dir).unwrap();
        let cfg = wordval_config::DatabaseConfig {
            enabled: true,
            r#type: "sqlite".into(),
            name: dir.join(format!("{tag}.db")).to_string_lossy().into_owned(),
            ..Default::default()
        };
        wordval_db::create_db(&cfg).await.expect("create sqlite db")
    }

    /// 注册表缺少 default 别名时拒绝初始化(fail-fast,不污染全局状态)
    #[test]
    fn set_dbs_requires_default_alias() {
        let err = set_dbs(HashMap::new()).unwrap_err();
        assert!(err.contains("default"), "{err}");
        // 未注册的别名返回 None,不 panic
        assert!(try_using("nope").is_none());
    }

    /// db() Deref 访问 default,db().using("alias") 切换命名库
    #[tokio::test]
    async fn db_handle_using_selects_alias() {
        let _serial = REGISTRY_LOCK.lock().await;
        register_db(DEFAULT_DB_NAME, temp_db("rtdef2").await);
        register_db("using_test", temp_db("rtu").await);

        // Deref:db() 可直接调 default 库方法
        let _handle = db();
        let _default_ref: &Db = &db();
        // using:切换命名库
        let _named = db().using("using_test");
        assert!(db_names().contains(&"using_test".to_string()));
    }

    /// 运行时 register_db/remove_db:动态注册后 try_using 可取用,注销后消失
    #[tokio::test]
    async fn register_and_remove_runtime_alias() {
        register_db("runtime_test", temp_db("rt1").await);
        assert!(try_using("runtime_test").is_some());
        assert!(db_names().contains(&"runtime_test".to_string()));

        // 覆盖注册:再次注册同名别名,取到的是新实例(不同连接池)
        register_db("runtime_test", temp_db("rt2").await);
        assert!(try_using("runtime_test").is_some());

        let removed = remove_db("runtime_test").unwrap();
        assert!(removed.is_some());
        assert!(try_using("runtime_test").is_none());
    }

    /// 事务能力跟 Db 实例走:default 与命名库各自支持事务,互不影响
    #[tokio::test]
    async fn using_alias_supports_transaction() {
        let _serial = REGISTRY_LOCK.lock().await;
        register_db(DEFAULT_DB_NAME, temp_db("txdef").await);
        register_db("tx_other", temp_db("txoth").await);

        for d in [db_default(), db().using("tx_other")] {
            d.execute("CREATE TABLE tx_t (id INTEGER PRIMARY KEY, v TEXT)", &[])
                .await
                .unwrap();
        }

        // default 库事务提交
        db()
            .transaction(|tx| async move {
                tx.execute("INSERT INTO tx_t (v) VALUES ('from-default')", &[])
                    .await?;
                Ok::<(), wordval_db::DbError>(())
            })
            .await
            .unwrap();

        // 命名库事务回滚(闭包返回 Err)
        let e = db()
            .using("tx_other")
            .transaction(|tx| async move {
                tx.execute("INSERT INTO tx_t (v) VALUES ('rollback-me')", &[])
                    .await?;
                Err::<(), wordval_db::DbError>(wordval_db::DbError::Other("业务失败".into()))
            })
            .await
            .unwrap_err();
        assert!(e.to_string().contains("业务失败"), "{e}");

        // 两库互不影响:default 有 1 条提交数据,tx_other 回滚后为空
        assert_eq!(
            db().count("SELECT COUNT(*) FROM tx_t", &[]).await.unwrap(),
            1
        );
        assert_eq!(
            db()
                .using("tx_other")
                .count("SELECT COUNT(*) FROM tx_t", &[])
                .await
                .unwrap(),
            0
        );
    }

    /// default 库是 db_default 的不变量,不允许注销
    #[tokio::test]
    async fn default_alias_cannot_be_removed() {
        let _serial = REGISTRY_LOCK.lock().await;
        register_db(DEFAULT_DB_NAME, temp_db("rtdef").await);
        let err = remove_db(DEFAULT_DB_NAME).unwrap_err();
        assert!(err.contains("default"), "{err}");
        assert!(try_using(DEFAULT_DB_NAME).is_some());
    }
}