diff --git a/src/protocol.rs b/src/protocol.rs index 67b7bb0..234c7d6 100644 --- a/src/protocol.rs +++ b/src/protocol.rs @@ -8,11 +8,13 @@ //! ⚠️ 细节:**只比 major,但 minor 段解析失败会连累整体** //! (`"1.x"` ⇒ 不可解析 ⇒ 不兼容;`"1.2.3"` ⇒ 段数超限 ⇒ 不兼容)。 //! -//! 一次性 WARN 的两条安全约束: -//! - **固定 key 与变量 key 分开计数**:固定 key(`protocol:missing`)永不受变量 key -//! 集合上限影响 —— 对端没法用一堆伪造版本号把「老客户端还在线上」的信号永久静音。 -//! - **对端可控的值进日志前先净化**:去控制字符(含 ANSI ESC 序列)并截断, -//! 防日志伪造 / 终端转义注入。净化**只用于日志**,安全判定一律用原值。 +//! 一次性 WARN 的三条安全约束: +//! - **固定 key 与变量 key 分属两个集合**:固定 key(`protocol:missing`)永不受上限约束 +//! ⇒ 对端没法用一堆伪造版本号把「老客户端还在线上」的信号永久静音。 +//! - **变量 key 集合满了就抑制(不淘汰)** ⇒ 洪水量按每进程 256 条封顶; +//! 若改成淘汰,每来一个新版本串就会补一条 WARN,等于给对端一个「按对端节奏打日志」的放大器。 +//! - **对端可控的值进日志前先净化**:去控制字符(含 ANSI ESC 序列、U+2028/U+2029)并按 +//! 整字符截断,防日志伪造 / 终端转义注入。净化**只用于日志**,安全判定一律用原值。 use std::collections::HashSet; use std::sync::{Mutex, MutexGuard, OnceLock}; @@ -25,7 +27,7 @@ pub const PROTOCOL_VERSION_HEADER: &str = "X-Protocol-Version"; pub const INTERNAL_TOKEN_HEADER: &str = "X-Internal-Token"; /// **变量** key(key 里含对端可控内容)的集合上限(对齐上游 `warnOnce` 的有界集合)。 -/// 固定 key 不受此上限约束 —— 见 [`warn_once`]。 +/// 固定 key 不受此上限约束 —— 见 `warn_once`。 const WARN_ONCE_MAX_KEYS: usize = 256; /// 写入日志前对声明值的净化上限(字节)。 @@ -37,7 +39,7 @@ fn fixed_warned_keys() -> &'static Mutex> { KEYS.get_or_init(|| Mutex::new(HashSet::new())) } -/// 变量 key 的已告警集合:key 含对端可控内容,**有界**(见 [`WARN_ONCE_MAX_KEYS`])。 +/// 变量 key 的已告警集合:key 含对端可控内容,**有界**(见 `WARN_ONCE_MAX_KEYS`)。 fn variable_warned_keys() -> &'static Mutex> { static KEYS: OnceLock>> = OnceLock::new(); KEYS.get_or_init(|| Mutex::new(HashSet::new())) @@ -56,24 +58,16 @@ fn claim_fixed_key(set: &Mutex>, key: &str) -> bool { lock_set(set).insert(key.to_string()) } -/// 登记变量 key:首次登记返回 true。集合有界 —— 满了就淘汰一个旧 key 再插入, -/// 于是对端灌爆集合也只能「挤掉旧告警」,不能让新告警永久失效。 +/// 登记变量 key:首次登记返回 true。 +/// +/// 集合有界:**满了就抑制**(返回 false),**不淘汰**。淘汰会让「每来一个新版本串就补一条 WARN」 +/// 变成按对端节奏的无界日志放大器,而且被淘汰的 key 之后会再次告警,破坏「同 key 只告警一次」。 fn claim_variable_key(set: &Mutex>, key: &str) -> bool { let mut set = lock_set(set); - if set.contains(key) { + if set.len() >= WARN_ONCE_MAX_KEYS { return false; } - while set.len() >= WARN_ONCE_MAX_KEYS { - let victim = { set.iter().next().cloned() }; - match victim { - Some(v) => { - set.remove(&v); - } - None => break, - } - } - set.insert(key.to_string()); - true + set.insert(key.to_string()) } /// 实际打印告警。**调用方必须已释放集合锁**(打印与登记分离,避免持锁做 IO)。 @@ -123,9 +117,10 @@ pub fn is_protocol_acceptable(declared: Option<&str>) -> bool { /// 同 key 只告警一次。返回 true = 本次真的告警了。 /// -/// ⚠️ **key 必须是固定值**(与对端输入无关)—— 固定 key 永不受集合上限约束, -/// 任何时候都能告警。key 里含对端可控内容时请改用 [`warn_once_variable`]。 -pub fn warn_once(key: &str, message: &str) -> bool { +/// ⚠️ **key 必须是固定值**(与对端输入无关)—— 参数类型是 `&'static str`, +/// 传一个对端派生的动态 key **编译不过**。固定 key 永不受集合上限约束,任何时候都能告警。 +/// key 里含对端可控内容时请改用 `warn_once_variable`。 +pub fn warn_once(key: &'static str, message: &str) -> bool { if claim_fixed_key(fixed_warned_keys(), key) { emit_warn(message); true @@ -134,12 +129,12 @@ pub fn warn_once(key: &str, message: &str) -> bool { } } -/// 同 key 只告警一次,但 key 集合**有界**(上限 [`WARN_ONCE_MAX_KEYS`])。 +/// 同 key 只告警一次,但 key 集合**有界**(上限 `WARN_ONCE_MAX_KEYS`,满了即抑制)。 /// 返回 true = 本次真的告警了。 /// /// 用于 key 含对端可控内容(如声明的协议版本)的场景:对端即使灌爆集合, -/// 也只是挤掉旧告警,**不会**让固定 key 的告警失效。 -pub fn warn_once_variable(key: &str, message: &str) -> bool { +/// 也只是让**新的**变量告警不再产生,**不会**让固定 key 的告警失效。 +pub(crate) fn warn_once_variable(key: &str, message: &str) -> bool { if claim_variable_key(variable_warned_keys(), key) { emit_warn(message); true @@ -148,24 +143,27 @@ pub fn warn_once_variable(key: &str, message: &str) -> bool { } } -/// 需要从日志中剔除的字符:控制字符(C0/C1)与方向控制类格式字符。 +/// 需要从日志中剔除的字符:控制字符(C0/C1)、行/段分隔符与方向控制类格式字符。 fn is_log_unsafe(c: char) -> bool { c.is_control() || matches!( c, '\u{200b}'..='\u{200f}' // 零宽字符 + | '\u{2028}'..='\u{2029}' // LINE / PARAGRAPH SEPARATOR(部分查看器当换行处理) | '\u{202a}'..='\u{202e}' // 双向覆写(RLO/LRO) | '\u{2060}'..='\u{206f}' // 双向隔离 + 隐形字符 | '\u{feff}' // BOM / ZWNBSP ) } -/// 净化对端可控的字符串,供**日志 / 告警**用途:去控制字符(含 ANSI ESC 序列)并截断。 +/// 净化对端可控的字符串,供**日志 / 告警**用途:去控制字符(含 ANSI ESC 序列)并按整字符截断。 /// -/// ⚠️ **只用于日志**。安全判定([`is_protocol_compatible`] / [`is_protocol_acceptable`]) +/// ⚠️ **只用于日志**。安全判定(`is_protocol_compatible` / `is_protocol_acceptable`) /// 必须使用原值 —— 净化会引入绕过风险(如 `"1.0\u{1b}[0m"` 净化后变 `"1.0"`, /// 反而可能被误判为兼容)。 -pub fn sanitize_for_log(raw: &str) -> String { +/// +/// 截断**按整字符推进**(不用 `String::truncate`)⇒ 64 字节边界切在多字节字符中间也不会 panic。 +pub(crate) fn sanitize_for_log(raw: &str) -> String { let mut out = String::new(); let mut it = raw.chars().peekable(); while let Some(c) = it.next() { @@ -210,8 +208,9 @@ pub fn sanitize_for_log(raw: &str) -> String { } /// 变量 key:含**净化后**的声明值(防日志伪造 / 终端转义注入)。 -fn incompatible_warn_key(declared: &str) -> String { - format!("protocol:incompatible:{}", sanitize_for_log(declared)) +/// 入参必须**已经是净化过的**字符串(只净化一次,不重复净化)。 +fn incompatible_warn_key(safe: &str) -> String { + format!("protocol:incompatible:{}", safe) } /// 闸门判定 + 一次性告警。返回 `(是否放行, 本次是否真的告警了)`。 @@ -227,13 +226,13 @@ fn check_protocol_with_warn(declared: Option<&str>) -> (bool, bool) { ); return (true, warned); } + // 判定用原值 `d`;日志用净化值(防日志伪造 / 终端转义注入)。 if is_protocol_compatible(d) { return (true, false); } - // 判定用原值;日志用净化值(防日志伪造 / 终端转义注入)。 let safe = sanitize_for_log(d); let warned = warn_once_variable( - &incompatible_warn_key(d), + &incompatible_warn_key(&safe), &format!( "跨端协议版本不兼容(对端 {},本端 {}),请升级对端", safe, PROTOCOL_VERSION @@ -242,7 +241,7 @@ fn check_protocol_with_warn(declared: Option<&str>) -> (bool, bool) { (false, warned) } -/// 闸门判定 + 一次性告警。 +/// 闸门判定 + 一次性告警。返回 true = 放行。 pub fn check_protocol(declared: Option<&str>) -> bool { check_protocol_with_warn(declared).0 } @@ -260,7 +259,7 @@ mod tests { } } - /// 清空全局告警状态,让用例从干净状态开始。 + /// 清空全局告警状态,让用例从干净状态开始(避免用例之间抢 key)。 fn reset_warn_state() { lock_set(fixed_warned_keys()).clear(); lock_set(variable_warned_keys()).clear(); @@ -316,6 +315,16 @@ mod tests { // ---- 闸门本身:判定 + 告警 ---- + #[test] + fn public_check_protocol_is_covered() { + // 公开 API 必须被直接断言(否则把 `.0` 写成 `.1` 也没人发现) + let _g = test_guard(); + reset_warn_state(); + assert!(check_protocol(None), "未声明 ⇒ 兼容期放行"); + assert!(check_protocol(Some("1.4")), "同 major ⇒ 放行"); + assert!(!check_protocol(Some("5.1")), "major 不同 ⇒ 拒绝"); + } + #[test] fn check_protocol_allows_missing_and_compatible_and_rejects_incompatible() { let _g = test_guard(); @@ -365,14 +374,20 @@ mod tests { } // 变量 key 集合仍然有界 assert!(lock_set(variable_warned_keys()).len() <= WARN_ONCE_MAX_KEYS); - // 两个集合分开计数:变量 key 不得污染固定 key 集合 - assert_eq!( - lock_set(fixed_warned_keys()).len(), - 1, - "变量 key 不得污染固定 key 集合" + // 两个集合分开计数(包含性断言,不断言精确条数): + // 固定 key 记在固定集合,变量 key 不许进固定集合 + assert!( + lock_set(fixed_warned_keys()).contains("test:fixed:keep"), + "固定 key 应记在固定集合" + ); + assert!( + !lock_set(fixed_warned_keys()).contains("test:flood:0"), + "变量 key 不得记进固定集合" + ); + assert!( + !lock_set(variable_warned_keys()).contains("test:fixed:keep"), + "固定 key 不得记进变量集合" ); - assert!(lock_set(fixed_warned_keys()).contains("test:fixed:keep")); - assert!(!lock_set(variable_warned_keys()).contains("test:fixed:keep")); // 固定 key 仍被记住 ⇒ 不会被变量集合淘汰 assert!( @@ -385,24 +400,68 @@ mod tests { assert!(allowed); assert!(warned, "变量 key 灌爆后,固定 key 仍必须能告警"); - // 变量 key 路径也没被灌死:新 key 仍拿得到位置 + // 变量 key 路径被上限封顶:新的声明值不再逐条告警(洪水量有界的代价) let (allowed, warned) = check_protocol_with_warn(Some("4.2")); - assert!(!allowed); - assert!(warned, "灌爆后新出现的声明值仍应告警"); + assert!(!allowed, "major 不同 ⇒ 仍然拒绝"); + assert!(!warned, "变量 key 集合已满 ⇒ 新声明值不再告警"); } #[test] fn variable_key_set_stays_bounded() { let local = Mutex::new(HashSet::new()); - for i in 0..(WARN_ONCE_MAX_KEYS * 2) { + for i in 0..WARN_ONCE_MAX_KEYS { assert!( claim_variable_key(&local, &format!("k:{}", i)), - "新 key 应拿到位置" + "上限内的 key 应拿到位置" + ); + } + // 超上限的 key 一律被抑制(不淘汰 ⇒ 不会把老 key 挤掉) + for i in WARN_ONCE_MAX_KEYS..(WARN_ONCE_MAX_KEYS + 32) { + assert!( + !claim_variable_key(&local, &format!("k:{}", i)), + "超上限的 key 应被抑制" ); } assert!(lock_set(&local).len() <= WARN_ONCE_MAX_KEYS); } + #[test] + fn flood_cannot_amplify_log_volume() { + let _g = test_guard(); + reset_warn_state(); + + // 洪水量必须被封顶:每进程至多 WARN_ONCE_MAX_KEYS 条变量告警 + let mut warned = 0usize; + for i in 0..(WARN_ONCE_MAX_KEYS * 4) { + if warn_once_variable(&format!("test:volume:{}", i), "灌水") { + warned += 1; + } + } + assert!( + warned <= WARN_ONCE_MAX_KEYS, + "洪水量必须封顶,实际 {} 条", + warned + ); + assert!(lock_set(variable_warned_keys()).len() <= WARN_ONCE_MAX_KEYS); + } + + #[test] + fn fixed_key_set_is_never_capped() { + let _g = test_guard(); + reset_warn_state(); + + // 固定集合**无上限**:超过 256 个互异 key 也必须每一个都登记成功 + for i in 0..(WARN_ONCE_MAX_KEYS * 2) { + assert!( + claim_fixed_key(fixed_warned_keys(), &format!("test:fixed-flood:{}", i)), + "固定 key 永不被抑制" + ); + } + // 包含性断言:集合里确实有这些 key + assert!(lock_set(fixed_warned_keys()).contains("test:fixed-flood:0")); + assert!(lock_set(fixed_warned_keys()).len() >= WARN_ONCE_MAX_KEYS * 2); + } + // ---- 日志净化(只影响日志,不影响判定) ---- #[test] @@ -414,6 +473,27 @@ mod tests { assert_eq!(sanitize_for_log("1.0\u{1b}[31mRED\u{1b}[0m"), "1.0RED"); assert_eq!(sanitize_for_log("1.0\u{7}2.0"), "1.02.0"); assert_eq!(sanitize_for_log("1.0\u{202e}2.0"), "1.02.0"); + // U+2028 / U+2029 是行/段分隔符,部分查看器当换行处理 ⇒ 必须剔除 + assert_eq!(sanitize_for_log("1.0\u{2028}2.0"), "1.02.0"); + assert_eq!(sanitize_for_log("1.0\u{2029}2.0"), "1.02.0"); + } + + #[test] + fn sanitized_log_value_has_no_control_chars() { + let raw = "1.0\u{1b}[31m\u{2028}\u{2029}\n\u{7}\u{202e}中"; + let s = sanitize_for_log(raw); + assert!( + !s.chars().any(|c| c.is_control()), + "净化后不得残留控制字符:{:?}", + s + ); + assert!( + !s.contains('\u{2028}') && !s.contains('\u{2029}'), + "净化后不得残留 U+2028/U+2029:{:?}", + s + ); + assert!(s.len() <= LOG_MAX_LEN); + assert!(std::str::from_utf8(s.as_bytes()).is_ok(), "必须是合法 UTF-8"); } #[test] @@ -423,6 +503,23 @@ mod tests { assert_eq!(s.len(), LOG_MAX_LEN); } + #[test] + fn sanitize_truncates_on_char_boundary_for_cjk() { + // 64 字节边界会切在多字节字符中间 ⇒ 必须整字符推进,不得 panic + let cjk = "中".repeat(100); + let s = sanitize_for_log(&cjk); + assert!(s.len() <= LOG_MAX_LEN); + assert!(s.chars().all(|c| c == '中')); + assert_eq!(s.len(), 63, "21 个中文字 = 63 字节,第 22 个会越过 64"); + assert!(std::str::from_utf8(s.as_bytes()).is_ok(), "必须是合法 UTF-8"); + + // ASCII 占到 63 字节后再跟一个多字节字符 ⇒ 不得越界、不得 panic + let mixed = format!("{}{}", "a".repeat(LOG_MAX_LEN - 1), "中"); + let s2 = sanitize_for_log(&mixed); + assert!(s2.len() <= LOG_MAX_LEN); + assert_eq!(s2.len(), LOG_MAX_LEN - 1); + } + #[test] fn judgment_uses_raw_value_not_sanitized() { // 净化后是 "1.0"(major 相同 ⇒ 兼容),但判定必须用原值 ⇒ 原值不可解析 ⇒ 仍判不兼容 @@ -440,11 +537,10 @@ mod tests { #[test] fn warn_key_uses_sanitized_value() { - assert_eq!( - incompatible_warn_key("2.0\u{1b}[0m"), - "protocol:incompatible:2.0" - ); - let key = incompatible_warn_key("9.9\n伪造日志行"); + let safe = sanitize_for_log("2.0\u{1b}[0m"); + assert_eq!(safe, "2.0"); + assert_eq!(incompatible_warn_key(&safe), "protocol:incompatible:2.0"); + let key = incompatible_warn_key(&sanitize_for_log("9.9\n伪造日志行")); assert!(!key.contains('\n'), "告警 key 不得带换行"); assert!(!key.contains('\u{1b}'), "告警 key 不得带 ESC"); }