Skip to main content

yang_base/
config.rs

1//! 引擎配置(I4):从环境变量分层加载,遵循 12-factor。
2//!
3//! 本模块提供 [`EngineConfig::from_env`]:从 `YANG_` 前缀环境变量读取数据库/Redis
4//! 连接串与连接池参数,解析失败一律走 checked 错误([`BaseError::ConfigError`]),
5//! **不** panic(遵守禁新增生产 panic 约定)。
6//!
7//! 设计取轻量替代(纯 `std::env`,不引入 figment/config/dotenv 重依赖)。未来如需
8//! 「默认 < TOML 文件 < 环境变量」三层覆盖,可在可选 `config` feature 后增量补 TOML 层,
9//! 本类型的 `from_env` 即最高优先级层。
10//!
11//! # 识别的环境变量
12//!
13//! | 变量 | 含义 | 默认 |
14//! |------|------|------|
15//! | `YANG_MYSQL_URL` | MySQL 连接串 | 无(缺失则 `mysql_url` 为 `None`) |
16//! | `YANG_DATABASE_URL` | MySQL 连接串(deprecated,请改用 `YANG_MYSQL_URL`) | 同上 |
17//! | `YANG_POSTGRES_URL` | PostgreSQL 连接串 | 无(缺失则 `postgres_url` 为 `None`) |
18//! | `YANG_REDIS_URL` | Redis 连接串 | 无 |
19//! | `YANG_DB_MAX_CONNECTIONS` | 最大连接数 | 由 `DatabaseConfig::default` 决定 |
20//! | `YANG_DB_MIN_CONNECTIONS` | 最小(保活)连接数 | 同上 |
21//! | `YANG_DB_CONNECT_TIMEOUT` | 连接超时(秒) | 同上 |
22//! | `YANG_DB_IDLE_TIMEOUT` | 空闲超时(秒) | 同上 |
23//! | `YANG_DB_MAX_LIFETIME` | 连接最大存活(秒,0/缺失=不限制) | 不限制 |
24//! | `YANG_DB_TEST_BEFORE_ACQUIRE` | 借出前探活(true/false/1/0) | false |
25//! | `YANG_DB_ENABLE_LOGGING` | SQL 日志(true/false/1/0) | false |
26//!
27//! `postgres` feature 下额外识别 PostgreSQL 会话/连接参数(见 [`EngineConfig::postgres_database`]):
28//!
29//! | 变量 | 含义 | 默认 |
30//! |------|------|------|
31//! | `YANG_PG_SEARCH_PATH` | 连接 `search_path`(逗号分隔,如 `app,public`) | 服务端默认 |
32//! | `YANG_PG_APPLICATION_NAME` | `application_name`(≤63 字节) | 不设置 |
33//! | `YANG_PG_STATEMENT_TIMEOUT_MS` | 单条语句超时(毫秒,0=不限制) | 不设置 |
34//! | `YANG_PG_LOCK_TIMEOUT_MS` | 锁等待超时(毫秒,0=不限制) | 不设置 |
35//! | `YANG_PG_IDLE_IN_TRANSACTION_TIMEOUT_MS` | 事务空闲超时(毫秒,0=不限制) | 不设置 |
36//! | `YANG_PG_SSL_MODE` | `disable`/`prefer`/`require`/`verify-ca`/`verify-full` | 沿用连接串 |
37//! | `YANG_PG_SSL_ROOT_CERT` | 根证书(CA)PEM 路径 | 不设置 |
38//! | `YANG_PG_SSL_CLIENT_CERT` | 客户端证书 PEM 路径(与私钥成对) | 不设置 |
39//! | `YANG_PG_SSL_CLIENT_KEY` | 客户端私钥 PEM 路径(与证书成对) | 不设置 |
40//!
41//! Redis 连接池(`feature = "redis"`):
42//!
43//! | 变量 | 含义 | 默认 |
44//! |------|------|------|
45//! | `YANG_REDIS_MAX_CONNECTIONS` | 最大连接数 | 10 |
46//! | `YANG_REDIS_CONNECT_TIMEOUT` | 建连超时(秒) | 5 |
47//! | `YANG_REDIS_WAIT_TIMEOUT` | 获取连接超时(秒) | 10 |
48//! | `YANG_REDIS_IDLE_TIMEOUT` | 归还回收钩子超时(秒) | 300 |
49//! | `YANG_REDIS_RESPONSE_TIMEOUT_MS` | 命令级响应超时(0=关闭) | 不限制 |
50//! | `YANG_REDIS_RECONNECT_RETRIES` | 断线重试次数 | 2 |
51//! | `YANG_REDIS_RECONNECT_MAX_DELAY_MS` | 重试最大退避 | 200 |
52//! | `YANG_REDIS_PIPELINE_MAX_COMMANDS` | Pipeline 命令数上限 | 10000 |
53//! | `YANG_REDIS_ENABLE_LOGGING` | 脱敏连接目标日志 | false |
54
55use crate::error::BaseError;
56use std::env;
57use std::fmt;
58
59/// 引擎级聚合配置,从环境变量加载(I4)。
60///
61/// 手写 [`fmt::Debug`](而非 derive):`mysql_url` / `postgres_url` / `redis_url`
62/// 可能包含 userinfo 密码与查询串 token,Debug 输出只保留脱敏后的
63/// scheme + host[:port][/path],绝不输出凭据。字段本身始终保存原始连接串。
64#[derive(Clone, Default)]
65#[non_exhaustive]
66pub struct EngineConfig {
67    /// MySQL 连接串(`YANG_MYSQL_URL`,兼容 deprecated `YANG_DATABASE_URL`,缺失为 `None`)。
68    pub mysql_url: Option<String>,
69    /// PostgreSQL 连接串(`YANG_POSTGRES_URL`,缺失为 `None`)。
70    ///
71    /// 与 `postgres` feature 配合使用:连接池、`Record` 解码、声明式 schema 同步与
72    /// `TableQuery` / 内置 CRUD 的 PostgreSQL 执行层均已接入。
73    pub postgres_url: Option<String>,
74    /// Redis 连接串(`YANG_REDIS_URL`,缺失为 `None`)。
75    pub redis_url: Option<String>,
76    /// 数据库连接池配置(由 `YANG_DB_*` 覆盖 `DatabaseConfig::default`)。
77    ///
78    /// 同时启用 `mysql` 与 `postgres` 时沿用 MySQL 配置类型;仅启用 `postgres` 时
79    /// 使用 PostgreSQL 配置类型。
80    #[cfg(feature = "mysql")]
81    pub database: yang_db::DatabaseConfig,
82    /// 数据库连接池配置(由 `YANG_DB_*` 覆盖 `DatabaseConfig::default`)。
83    #[cfg(all(feature = "postgres", not(feature = "mysql")))]
84    pub database: yang_db::PgDatabaseConfig,
85    /// PostgreSQL 连接/会话配置入口(`postgres` feature)。
86    ///
87    /// 除通用 `YANG_DB_*` 连接池参数外,还映射 `YANG_PG_*` 的 `search_path` /
88    /// `application_name` / `statement_timeout` / `lock_timeout` / TLS 等
89    /// [`yang_db::PgDatabaseConfig`] 字段,供 `Database::connect_with_config` 使用。
90    /// 同时启用 `mysql` 时它是访问 PostgreSQL 会话参数的唯一入口(此时 [`Self::database`]
91    /// 仍为 MySQL 配置类型)。
92    #[cfg(feature = "postgres")]
93    pub postgres_database: yang_db::PgDatabaseConfig,
94    /// Redis 连接池配置(由 `YANG_REDIS_*` 覆盖 `RedisConfig::default`)。
95    #[cfg(feature = "redis")]
96    pub redis: yang_db::RedisConfig,
97}
98
99impl fmt::Debug for EngineConfig {
100    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
101        let mut debug = formatter.debug_struct("EngineConfig");
102        debug.field("mysql_url", &self.mysql_url.as_deref().map(RedactedUrl));
103        debug.field(
104            "postgres_url",
105            &self.postgres_url.as_deref().map(RedactedUrl),
106        );
107        debug.field("redis_url", &self.redis_url.as_deref().map(RedactedUrl));
108        #[cfg(feature = "mysql")]
109        debug.field("database", &self.database);
110        #[cfg(all(feature = "postgres", not(feature = "mysql")))]
111        debug.field("database", &self.database);
112        #[cfg(feature = "postgres")]
113        debug.field("postgres_database", &self.postgres_database);
114        #[cfg(feature = "redis")]
115        debug.field("redis", &self.redis);
116        debug.finish()
117    }
118}
119
120/// 仅用于 Debug/日志展示的脱敏连接串。
121struct RedactedUrl<'a>(&'a str);
122
123impl fmt::Debug for RedactedUrl<'_> {
124    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
125        write!(formatter, "{:?}", redact_connection_url(self.0))
126    }
127}
128
129/// 对连接串做展示层脱敏:仅保留 scheme 与 `host[:port][/path]`,剥离 userinfo
130/// (含密码)与 `?` / `#` 查询串与片段;无法识别 scheme 或缺 scheme 的输入
131/// 回退为固定占位文本,不 panic。
132///
133/// 该函数只用于 Debug 格式化,绝不修改 [`EngineConfig`] 中存储的原始连接串。
134fn redact_connection_url(raw: &str) -> String {
135    let Some((scheme, rest)) = raw.split_once("://") else {
136        return "[REDACTED]".to_string();
137    };
138    if !matches!(
139        scheme.to_ascii_lowercase().as_str(),
140        "mysql" | "postgres" | "postgresql" | "redis" | "rediss"
141    ) {
142        return "[REDACTED]".to_string();
143    }
144    // 先剥离 fragment/query(其中可能含 token),再剥离 authority 中的 userinfo
145    // (其中含密码);path 中原生的 '@' 不参与 userinfo 判定。
146    let rest = rest.split(['#', '?']).next().unwrap_or(rest);
147    let (authority, path) = match rest.split_once('/') {
148        Some((authority, path)) => (authority, Some(path)),
149        None => (rest, None),
150    };
151    // 未编码的 `/` 出现在密码里会让 authority 在 `@` 之前被截断,
152    // 此时剩下的 `@host` 落在 path 中;这类输入本身不是合法 URL,
153    // 但 Debug 输出绝不能把密码片段原样带出,整体回退为占位文本。
154    let ambiguous_userinfo = !authority.contains('@')
155        && (path.is_some_and(|path| path.contains('@'))
156            || authority.rsplit_once(':').is_some_and(|(_, tail)| {
157                !tail.is_empty() && !tail.chars().all(|c| c.is_ascii_digit())
158            }));
159    if ambiguous_userinfo {
160        return format!("{scheme}://[REDACTED]");
161    }
162    let authority = authority
163        .rsplit_once('@')
164        .map_or(authority, |(_, host)| host);
165    match path {
166        Some(path) => format!("{scheme}://{authority}/{path}"),
167        None => format!("{scheme}://{authority}"),
168    }
169}
170
171/// 当前编译所使用的数据库连接池配置类型。
172#[cfg(feature = "mysql")]
173type DatabaseConfigType = yang_db::DatabaseConfig;
174#[cfg(all(feature = "postgres", not(feature = "mysql")))]
175type DatabaseConfigType = yang_db::PgDatabaseConfig;
176
177/// 读取一个环境变量并按 `T` 解析;缺失返回 `Ok(None)`,存在但解析失败返回 ConfigError。
178#[cfg(any(feature = "mysql", feature = "postgres", feature = "redis"))]
179fn parse_env<T: std::str::FromStr>(key: &str) -> Result<Option<T>, BaseError>
180where
181    T::Err: std::fmt::Display,
182{
183    match env::var(key) {
184        Ok(raw) => raw
185            .trim()
186            .parse::<T>()
187            .map(Some)
188            .map_err(|e| BaseError::ConfigError(format!("环境变量 {key} 解析失败: {e}"))),
189        Err(env::VarError::NotPresent) => Ok(None),
190        Err(env::VarError::NotUnicode(_)) => Err(BaseError::ConfigError(format!(
191            "环境变量 {key} 含非法 UTF-8"
192        ))),
193    }
194}
195
196/// 解析布尔环境变量:接受 `true/false/1/0`(大小写不敏感),其余报 ConfigError。
197#[cfg(any(feature = "mysql", feature = "postgres", feature = "redis"))]
198fn parse_bool_env(key: &str) -> Result<Option<bool>, BaseError> {
199    match env::var(key) {
200        Ok(raw) => match raw.trim().to_ascii_lowercase().as_str() {
201            "true" | "1" => Ok(Some(true)),
202            "false" | "0" => Ok(Some(false)),
203            other => Err(BaseError::ConfigError(format!(
204                "环境变量 {key} 期望 true/false/1/0,实得 {other:?}"
205            ))),
206        },
207        Err(env::VarError::NotPresent) => Ok(None),
208        Err(env::VarError::NotUnicode(_)) => Err(BaseError::ConfigError(format!(
209            "环境变量 {key} 含非法 UTF-8"
210        ))),
211    }
212}
213
214/// 从 `YANG_DB_*` 读取连接池配置。
215///
216/// MySQL 与 PostgreSQL 的 `DatabaseConfig` 字段名一致,故共用同一读取逻辑;
217/// 具体类型由编译 feature 决定(见 [`DatabaseConfigType`])。
218#[cfg(any(feature = "mysql", feature = "postgres"))]
219fn load_database_config() -> Result<DatabaseConfigType, BaseError> {
220    let mut cfg = DatabaseConfigType::default();
221    if let Some(v) = parse_env::<u32>("YANG_DB_MAX_CONNECTIONS")? {
222        cfg.max_connections = v;
223    }
224    if let Some(v) = parse_env::<u32>("YANG_DB_MIN_CONNECTIONS")? {
225        cfg.min_connections = v;
226    }
227    if let Some(v) = parse_env::<u64>("YANG_DB_CONNECT_TIMEOUT")? {
228        cfg.connect_timeout = v;
229    }
230    if let Some(v) = parse_env::<u64>("YANG_DB_IDLE_TIMEOUT")? {
231        cfg.idle_timeout = v;
232    }
233    if let Some(v) = parse_env::<u64>("YANG_DB_MAX_LIFETIME")? {
234        // 0 视为不限制(与 None 同义),其余设具体秒数
235        cfg.max_lifetime = if v == 0 { None } else { Some(v) };
236    }
237    if let Some(v) = parse_bool_env("YANG_DB_TEST_BEFORE_ACQUIRE")? {
238        cfg.test_before_acquire = v;
239    }
240    if let Some(v) = parse_bool_env("YANG_DB_ENABLE_LOGGING")? {
241        cfg.enable_logging = v;
242    }
243    Ok(cfg)
244}
245
246/// 读取字符串环境变量;缺失返回 `Ok(None)`,非法 UTF-8 返回 ConfigError。
247#[cfg(feature = "postgres")]
248fn parse_string_env(key: &str) -> Result<Option<String>, BaseError> {
249    match env::var(key) {
250        Ok(raw) => Ok(Some(raw)),
251        Err(env::VarError::NotPresent) => Ok(None),
252        Err(env::VarError::NotUnicode(_)) => Err(BaseError::ConfigError(format!(
253            "环境变量 {key} 含非法 UTF-8"
254        ))),
255    }
256}
257
258/// 解析 `YANG_PG_SSL_MODE`(大小写不敏感,`_` 与 `-` 等价)。
259#[cfg(feature = "postgres")]
260fn parse_ssl_mode(key: &str, raw: &str) -> Result<yang_db::PgSslMode, BaseError> {
261    use yang_db::PgSslMode;
262    match raw.trim().to_ascii_lowercase().replace('_', "-").as_str() {
263        "disable" => Ok(PgSslMode::Disable),
264        "prefer" => Ok(PgSslMode::Prefer),
265        "require" => Ok(PgSslMode::Require),
266        "verify-ca" => Ok(PgSslMode::VerifyCa),
267        "verify-full" => Ok(PgSslMode::VerifyFull),
268        other => Err(BaseError::ConfigError(format!(
269            "环境变量 {key} 取值非法: {other:?}(允许 disable/prefer/require/verify-ca/verify-full)"
270        ))),
271    }
272}
273
274/// 从 `YANG_DB_*`(连接池)与 `YANG_PG_*`(会话参数)读取 PostgreSQL 配置。
275///
276/// 加载后立即调用 [`yang_db::PgDatabaseConfig::validate`],让非法组合(如
277/// `idle_timeout <= connect_timeout`、`verify-ca` 缺少根证书)在启动期就报
278/// [`BaseError::ConfigError`],而不是等到建连时才失败。
279#[cfg(feature = "postgres")]
280fn load_postgres_database_config() -> Result<yang_db::PgDatabaseConfig, BaseError> {
281    let mut cfg = yang_db::PgDatabaseConfig::default();
282    // 通用连接池参数:与 MySQL 共用同一组 YANG_DB_* 变量。
283    if let Some(v) = parse_env::<u32>("YANG_DB_MAX_CONNECTIONS")? {
284        cfg.max_connections = v;
285    }
286    if let Some(v) = parse_env::<u32>("YANG_DB_MIN_CONNECTIONS")? {
287        cfg.min_connections = v;
288    }
289    if let Some(v) = parse_env::<u64>("YANG_DB_CONNECT_TIMEOUT")? {
290        cfg.connect_timeout = v;
291    }
292    if let Some(v) = parse_env::<u64>("YANG_DB_IDLE_TIMEOUT")? {
293        cfg.idle_timeout = v;
294    }
295    if let Some(v) = parse_env::<u64>("YANG_DB_MAX_LIFETIME")? {
296        cfg.max_lifetime = if v == 0 { None } else { Some(v) };
297    }
298    if let Some(v) = parse_bool_env("YANG_DB_TEST_BEFORE_ACQUIRE")? {
299        cfg.test_before_acquire = v;
300    }
301    if let Some(v) = parse_bool_env("YANG_DB_ENABLE_LOGGING")? {
302        cfg.enable_logging = v;
303    }
304    // PostgreSQL 会话/连接专属参数。
305    if let Some(v) = parse_string_env("YANG_PG_SEARCH_PATH")? {
306        cfg.search_path = Some(v);
307    }
308    if let Some(v) = parse_string_env("YANG_PG_APPLICATION_NAME")? {
309        cfg.application_name = Some(v);
310    }
311    if let Some(v) = parse_env::<u64>("YANG_PG_STATEMENT_TIMEOUT_MS")? {
312        cfg.statement_timeout_ms = Some(v);
313    }
314    if let Some(v) = parse_env::<u64>("YANG_PG_LOCK_TIMEOUT_MS")? {
315        cfg.lock_timeout_ms = Some(v);
316    }
317    if let Some(v) = parse_env::<u64>("YANG_PG_IDLE_IN_TRANSACTION_TIMEOUT_MS")? {
318        cfg.idle_in_transaction_timeout_ms = Some(v);
319    }
320    if let Some(v) = parse_string_env("YANG_PG_SSL_MODE")? {
321        cfg.ssl_mode = Some(parse_ssl_mode("YANG_PG_SSL_MODE", &v)?);
322    }
323    if let Some(v) = parse_string_env("YANG_PG_SSL_ROOT_CERT")? {
324        cfg.ssl_root_cert = Some(v.into());
325    }
326    if let Some(v) = parse_string_env("YANG_PG_SSL_CLIENT_CERT")? {
327        cfg.ssl_client_cert = Some(v.into());
328    }
329    if let Some(v) = parse_string_env("YANG_PG_SSL_CLIENT_KEY")? {
330        cfg.ssl_client_key = Some(v.into());
331    }
332    cfg.validate()
333        .map_err(|error| BaseError::ConfigError(format!("PostgreSQL 配置无效: {error}")))?;
334    Ok(cfg)
335}
336
337impl EngineConfig {
338    /// 从 `YANG_` 前缀环境变量加载配置。
339    ///
340    /// 缺失的变量回退到默认值;存在但解析失败返回 [`BaseError::ConfigError`]。
341    pub fn from_env() -> Result<Self, BaseError> {
342        // 优先 YANG_MYSQL_URL;兼容 deprecated YANG_DATABASE_URL
343        let mysql_url = match env::var("YANG_MYSQL_URL") {
344            Ok(v) => Some(v),
345            Err(env::VarError::NotPresent) => match env::var("YANG_DATABASE_URL") {
346                Ok(v) => {
347                    eprintln!(
348                        "[yang-base] 环境变量 YANG_DATABASE_URL 已 deprecated,请改用 YANG_MYSQL_URL"
349                    );
350                    Some(v)
351                }
352                Err(env::VarError::NotPresent) => None,
353                Err(env::VarError::NotUnicode(_)) => {
354                    return Err(BaseError::ConfigError(
355                        "环境变量 YANG_DATABASE_URL 含非法 UTF-8".to_string(),
356                    ))
357                }
358            },
359            Err(env::VarError::NotUnicode(_)) => {
360                return Err(BaseError::ConfigError(
361                    "环境变量 YANG_MYSQL_URL 含非法 UTF-8".to_string(),
362                ))
363            }
364        };
365        let postgres_url = match env::var("YANG_POSTGRES_URL") {
366            Ok(v) => Some(v),
367            Err(env::VarError::NotPresent) => None,
368            Err(env::VarError::NotUnicode(_)) => {
369                return Err(BaseError::ConfigError(
370                    "环境变量 YANG_POSTGRES_URL 含非法 UTF-8".to_string(),
371                ))
372            }
373        };
374        let redis_url = match env::var("YANG_REDIS_URL") {
375            Ok(v) => Some(v),
376            Err(env::VarError::NotPresent) => None,
377            Err(env::VarError::NotUnicode(_)) => {
378                return Err(BaseError::ConfigError(
379                    "环境变量 YANG_REDIS_URL 含非法 UTF-8".to_string(),
380                ))
381            }
382        };
383
384        #[cfg(any(feature = "mysql", feature = "postgres"))]
385        let database = load_database_config()?;
386        #[cfg(feature = "postgres")]
387        let postgres_database = load_postgres_database_config()?;
388
389        #[cfg(feature = "redis")]
390        let redis = {
391            let mut cfg = yang_db::RedisConfig::default();
392            if let Some(v) = parse_env::<usize>("YANG_REDIS_MAX_CONNECTIONS")? {
393                cfg.max_connections = v;
394            }
395            if let Some(v) = parse_env::<u64>("YANG_REDIS_CONNECT_TIMEOUT")? {
396                cfg.connect_timeout = v;
397            }
398            if let Some(v) = parse_env::<u64>("YANG_REDIS_WAIT_TIMEOUT")? {
399                cfg.wait_timeout = v;
400            }
401            if let Some(v) = parse_env::<u64>("YANG_REDIS_IDLE_TIMEOUT")? {
402                cfg.idle_timeout = v;
403            }
404            if let Some(v) = parse_env::<u64>("YANG_REDIS_RESPONSE_TIMEOUT_MS")? {
405                // 0 表示显式关闭命令级超时
406                cfg.response_timeout_ms = if v == 0 { None } else { Some(v) };
407            }
408            if let Some(v) = parse_env::<u32>("YANG_REDIS_RECONNECT_RETRIES")? {
409                cfg.reconnect_retries = v;
410            }
411            if let Some(v) = parse_env::<u64>("YANG_REDIS_RECONNECT_MAX_DELAY_MS")? {
412                cfg.reconnect_max_delay_ms = v;
413            }
414            if let Some(v) = parse_env::<usize>("YANG_REDIS_PIPELINE_MAX_COMMANDS")? {
415                cfg.pipeline_max_commands = v;
416            }
417            if let Some(v) = parse_bool_env("YANG_REDIS_ENABLE_LOGGING")? {
418                cfg.enable_logging = v;
419            }
420            cfg.validate()
421                .map_err(|error| BaseError::ConfigError(error.to_string()))?;
422            cfg
423        };
424
425        Ok(Self {
426            mysql_url,
427            postgres_url,
428            redis_url,
429            #[cfg(any(feature = "mysql", feature = "postgres"))]
430            database,
431            #[cfg(feature = "postgres")]
432            postgres_database,
433            #[cfg(feature = "redis")]
434            redis,
435        })
436    }
437
438    /// 返回 Redis 连接串与池配置(仅在同时配置了 `YANG_REDIS_URL` 时)。
439    #[cfg(feature = "redis")]
440    pub fn redis_config(&self) -> Option<(&str, &yang_db::RedisConfig)> {
441        self.redis_url.as_deref().map(|url| (url, &self.redis))
442    }
443}
444
445#[cfg(all(test, any(feature = "mysql", feature = "postgres", feature = "redis")))]
446mod tests {
447    use super::*;
448
449    #[test]
450    fn from_env_reads_postgres_url() {
451        std::env::set_var("YANG_POSTGRES_URL", "postgres://u:p@127.0.0.1:55432/test");
452        let config = EngineConfig::from_env().expect("合法 PostgreSQL URL 应解析成功");
453        std::env::remove_var("YANG_POSTGRES_URL");
454
455        assert_eq!(
456            config.postgres_url.as_deref(),
457            Some("postgres://u:p@127.0.0.1:55432/test")
458        );
459    }
460
461    #[test]
462    fn parse_bool_env_accepts_forms() {
463        // 使用唯一 key 避免与其它测试串扰
464        std::env::set_var("YANG_TEST_BOOL_X", "TRUE");
465        assert_eq!(parse_bool_env("YANG_TEST_BOOL_X").unwrap(), Some(true));
466        std::env::set_var("YANG_TEST_BOOL_X", "0");
467        assert_eq!(parse_bool_env("YANG_TEST_BOOL_X").unwrap(), Some(false));
468        std::env::set_var("YANG_TEST_BOOL_X", "maybe");
469        assert!(parse_bool_env("YANG_TEST_BOOL_X").is_err());
470        std::env::remove_var("YANG_TEST_BOOL_X");
471        assert_eq!(parse_bool_env("YANG_TEST_BOOL_X").unwrap(), None);
472    }
473
474    #[test]
475    fn parse_env_rejects_bad_number() {
476        std::env::set_var("YANG_TEST_NUM_X", "not_a_number");
477        let r = parse_env::<u32>("YANG_TEST_NUM_X");
478        assert!(matches!(r, Err(BaseError::ConfigError(_))));
479        std::env::remove_var("YANG_TEST_NUM_X");
480        assert_eq!(parse_env::<u32>("YANG_TEST_NUM_X").unwrap(), None);
481    }
482
483    /// `YANG_PG_*` 映射到 PostgreSQL 会话/连接参数。
484    #[cfg(feature = "postgres")]
485    #[test]
486    fn from_env_maps_postgres_session_settings() {
487        std::env::set_var("YANG_PG_SEARCH_PATH", "app,public");
488        std::env::set_var("YANG_PG_APPLICATION_NAME", "yang-wave3");
489        std::env::set_var("YANG_PG_STATEMENT_TIMEOUT_MS", "1500");
490        std::env::set_var("YANG_PG_LOCK_TIMEOUT_MS", "2500");
491        std::env::set_var("YANG_PG_SSL_MODE", "require");
492        let config = EngineConfig::from_env().expect("合法 PostgreSQL 会话配置应解析成功");
493        std::env::remove_var("YANG_PG_SEARCH_PATH");
494        std::env::remove_var("YANG_PG_APPLICATION_NAME");
495        std::env::remove_var("YANG_PG_STATEMENT_TIMEOUT_MS");
496        std::env::remove_var("YANG_PG_LOCK_TIMEOUT_MS");
497        std::env::remove_var("YANG_PG_SSL_MODE");
498
499        let pg = &config.postgres_database;
500        assert_eq!(pg.search_path.as_deref(), Some("app,public"));
501        assert_eq!(pg.application_name.as_deref(), Some("yang-wave3"));
502        assert_eq!(pg.statement_timeout_ms, Some(1500));
503        assert_eq!(pg.lock_timeout_ms, Some(2500));
504        assert_eq!(pg.ssl_mode, Some(yang_db::PgSslMode::Require));
505    }
506
507    /// 非法 SSL 模式必须报 ConfigError,且错误信息带变量名。
508    #[cfg(feature = "postgres")]
509    #[test]
510    fn parse_ssl_mode_rejects_unknown_value() {
511        let error =
512            parse_ssl_mode("YANG_PG_SSL_MODE", "sometimes").expect_err("未知 SSL 模式应被拒绝");
513        let message = error.to_string();
514        assert!(message.contains("YANG_PG_SSL_MODE"), "实得: {message}");
515        assert!(message.contains("sometimes"), "实得: {message}");
516    }
517
518    /// F058 RED 场景:derive(Debug) 会把连接串里的 userinfo 密码与查询串原样输出。
519    #[test]
520    fn engine_config_debug_redacts_connection_credentials() {
521        let config = EngineConfig {
522            mysql_url: Some(
523                "mysql://mysql-user:mysql-pass@mysql.example.test:3306/app?ssl-mode=required"
524                    .to_string(),
525            ),
526            postgres_url: Some(
527                "postgres://pg-user:pg-pass@pg.example.test:5432/app#fragment".to_string(),
528            ),
529            redis_url: Some("rediss://redis-user:redis-pass@redis.example.test:6379/0".to_string()),
530            ..EngineConfig::default()
531        };
532
533        let debug = format!("{config:?}");
534        for secret in [
535            "mysql-user",
536            "mysql-pass",
537            "pg-user",
538            "pg-pass",
539            "redis-user",
540            "redis-pass",
541            "ssl-mode=required",
542            "fragment",
543        ] {
544            assert!(
545                !debug.contains(secret),
546                "EngineConfig Debug 泄露 {secret}: {debug}"
547            );
548        }
549        // 展示层仍保留主机与库名,便于排障。
550        assert!(debug.contains("mysql.example.test:3306/app"), "{debug}");
551        assert!(debug.contains("pg.example.test:5432/app"), "{debug}");
552        assert!(
553            debug.contains("rediss://redis.example.test:6379/0"),
554            "{debug}"
555        );
556        // 存储值必须保持原始连接串(脱敏只作用于 Debug 文本)。
557        assert_eq!(
558            config.mysql_url.as_deref(),
559            Some("mysql://mysql-user:mysql-pass@mysql.example.test:3306/app?ssl-mode=required")
560        );
561    }
562
563    #[test]
564    fn redact_connection_url_handles_schemes_and_invalid_input() {
565        assert_eq!(
566            redact_connection_url("mysql://u:p@host:3306/db?x=1#frag"),
567            "mysql://host:3306/db"
568        );
569        assert_eq!(
570            redact_connection_url("postgresql://u:p@host/db"),
571            "postgresql://host/db"
572        );
573        assert_eq!(
574            redact_connection_url("redis://:p@host:6379/0"),
575            "redis://host:6379/0"
576        );
577        assert_eq!(redact_connection_url("rediss://host/0"), "rediss://host/0");
578        assert_eq!(redact_connection_url("not a url"), "[REDACTED]");
579        assert_eq!(redact_connection_url("ftp://u:p@host/db"), "[REDACTED]");
580        // 密码含未编码 `/`:authority 被截断,输出不得包含密码片段。
581        assert_eq!(
582            redact_connection_url("mysql://user:pa/ss@host/db"),
583            "mysql://[REDACTED]"
584        );
585        assert_eq!(
586            redact_connection_url("mysql://user:pa?ss@host/db"),
587            "mysql://[REDACTED]"
588        );
589    }
590}