diff --git a/src/api.rs b/src/api.rs index 33eaa51..51e4a54 100644 --- a/src/api.rs +++ b/src/api.rs @@ -135,7 +135,7 @@ fn h_admin_save(r: *mut ngx_http_request_t, _actor: Actor) -> Status { // 提交合法空数组 `[]` ⇒ Some(vec![]) ⇒ 清空(退回单 base); // 提交非空数组 ⇒ 覆盖。 let sources = match p.get("sources") { - Some(raw) if !util::trim(raw).is_empty() => match parse_sources(raw) { + Some(raw) if !util::trim(raw).is_empty() => match upstreams::parse_sources(raw) { Ok(v) => Some(v), Err(e) => { util::log_err(&format!("[cache] sources 参数解析失败:{e}")); @@ -190,30 +190,6 @@ fn h_admin_save(r: *mut ngx_http_request_t, _actor: Actor) -> Status { } } -/// 解析管理台提交的 `sources` 字段(JSON 数组字符串)→ 源池条目。 -/// -/// ⚠️ 解析失败**必须**返回 Err:调用方要回 400。 -/// 绝不能回退成空数组(语义 = 清空源池),那会在一次手滑提交里把源池抹掉。 -fn parse_sources(raw: &str) -> Result, String> { - let v: Value = serde_json::from_str(raw).map_err(|e| format!("不是合法 JSON:{e}"))?; - let arr = v - .as_array() - .ok_or_else(|| "必须是 JSON 数组".to_owned())?; - let mut out = Vec::with_capacity(arr.len()); - for item in arr { - let obj = item - .as_object() - .ok_or_else(|| "数组元素必须是对象".to_owned())?; - out.push(upstreams::SourceInput { - id: obj.get("id").and_then(Value::as_str).unwrap_or("").to_owned(), - url: obj.get("url").and_then(Value::as_str).unwrap_or("").to_owned(), - key: obj.get("key").and_then(Value::as_str).unwrap_or("").to_owned(), - note: obj.get("note").and_then(Value::as_str).unwrap_or("").to_owned(), - }); - } - Ok(out) -} - /// 删除一个路由的上游配置。 fn h_admin_delete(r: *mut ngx_http_request_t, _actor: Actor) -> Status { let p = http::params(r); diff --git a/src/cache.rs b/src/cache.rs index e09bc50..5fcfd6a 100644 --- a/src/cache.rs +++ b/src/cache.rs @@ -328,17 +328,35 @@ pub fn parse_pick(raw: &str) -> Option<[usize; config::MAX_SLOTS]> { /// 该源实际使用的上游凭据:源自己的优先,空则回落路由级 `key`。 /// -/// ⚠️ **多源路由不应配路由级 `key`**(由 **Task 6** 落实强制)。 -/// 本函数把路由级 `key` **复制给每一个没配自己凭据的源** ⇒ 池里 -/// **任意一个**第三方镜像站都会收到这份路由级凭据 —— 等价于把一份凭据 -/// 发给 N 个互不信任的第三方。 -/// 多源路由的正确做法是**逐源配凭据**(每个源用各自的 `key`)。 -/// 今天保留「空则回落路由级」的语义(单源路由依赖它), -/// 本条只是把约束**写死在注释里**,真正的强制在 Task 6。 +/// ## 多源路由**不回落**路由级 `key`(R-T6-12 ① · **Task 6 落实强制**) +/// +/// 旧语义把路由级 `key` **复制给每一个没配自己凭据的源** ⇒ 池里 +/// **任意一个**第三方镜像站都会收到这份路由级凭据 —— 等价于把一份凭据 +/// 发给 N 个互不信任的第三方。 +/// +/// ⇒ **多源路由**(**有效源数 > 1**)⇒ 源没配自己的凭据 ⇒ **返回空串** +/// (该源不下发任何凭据)。多源路由的正确做法是**逐源配凭据** +/// (每个源用各自的 `sources[].key`)。 +/// +/// ## 「有效源数」的判据 +/// +/// * `up.sources.len() > 1` ⇒ 多源 ⇒ **不回落**; +/// * `up.sources.len() == 1` ⇒ 单源路由 ⇒ 回落无风险 ⇒ **维持今天的回落语义** +/// (**不误伤**单源); +/// * `up.sources` 为空 ⇒ 旧的 v1 payload / 单 base 模式 ⇒ 有效源数 = 1 +/// ⇒ **维持今天的回落语义**。 +/// +/// ⚠️ 这是**运行期兜底**(结构性保证):管不住手改文件 / 迁移脚本 / +/// 任何绕过管理 API 的写路径 ⇒ 另有一道**写入门禁** +/// (`upstreams::check_route_key_for_sources`,保存时回 400)。 pub fn effective_key(up: &upstreams::Decoded, src: &CacheSource) -> String { if !src.key.is_empty() { return src.key.clone(); } + // 多源路由 ⇒ 不回落路由级 key(见上面的注释)。 + if up.sources.len() > 1 { + return String::new(); + } up.key.clone() } @@ -1031,23 +1049,34 @@ mod tests { assert_eq!(effective_key(&up, &srcs[0]), "ROUTEKEY"); } - // F1:路由级 key 会被**复制给每一个没配自己凭据的源** —— 多源路由 - // 不应配路由级 key(由 Task 6 强制)。这里把**当前语义**钉住, - // 免得 Task 6 改语义时无声漂移。 + // R-T6-12 ①:**多源路由不回落路由级 key**。 + // 旧语义(路由级 key 被复制给每一个没配自己凭据的源)已被 Task 6 改掉 —— + // 这里把**新语义**钉住,免得以后无声漂移。 #[test] - fn route_level_key_is_copied_to_every_source_in_a_multi_source_route() { + fn route_level_key_is_not_fallen_back_to_in_a_multi_source_route() { let up = crate::upstreams::decode("https://a\nROUTEKEY\nproxy\nv2\nhttps://b\n\nhttps://c\n"); let srcs = crate::upstreams::effective_sources(&up); assert_eq!(srcs.len(), 2); // 多源路由 - // 两个源都没配自己的凭据 ⇒ **都**拿到路由级 key - assert_eq!(effective_key(&up, &srcs[0]), "ROUTEKEY"); - assert_eq!(effective_key(&up, &srcs[1]), "ROUTEKEY"); + assert_eq!(up.sources.len(), 2); // 有效源数 > 1 ⇒ 多源 + // 两个源都没配自己的凭据 ⇒ **都不下发任何凭据**(不回落路由级 key) + assert_eq!(effective_key(&up, &srcs[0]), ""); + assert_eq!(effective_key(&up, &srcs[1]), ""); // 源自己配了凭据 ⇒ 用自己的,不受路由级影响 let up2 = crate::upstreams::decode("https://a\nROUTEKEY\nproxy\nv2\nhttps://b\nSRCKEY\n"); let srcs2 = crate::upstreams::effective_sources(&up2); assert_eq!(effective_key(&up2, &srcs2[0]), "SRCKEY"); } + // R-T6-12 ①:「有效源数」的判据 —— **不得误伤单源**。 + // `sources.len() == 1` ⇒ 单源路由 ⇒ 回落路由级 key(无风险)。 + #[test] + fn route_level_key_still_falls_back_in_a_single_source_route() { + let up = crate::upstreams::decode("https://a\nROUTEKEY\nproxy\nv2\nhttps://b\n\n"); + let srcs = crate::upstreams::effective_sources(&up); + assert_eq!(up.sources.len(), 1); // 单源路由 + assert_eq!(effective_key(&up, &srcs[0]), "ROUTEKEY"); + } + // ----------------------------------------------------------------- // 失败顺位 → 该冷却哪些顺位(R-T5-4) // ----------------------------------------------------------------- diff --git a/src/upstreams.rs b/src/upstreams.rs index a25e64c..950530d 100644 --- a/src/upstreams.rs +++ b/src/upstreams.rs @@ -84,46 +84,42 @@ pub struct Decoded { pub sources: Vec, } -/// 「v2 段行数为奇数」标记(由 [`decode`] 置位,由 [`lookup_upstream`] 取走并告警)。 -/// -/// **为什么必须留证据**:payload 是**换行分隔**的 -/// (`base\nkey\nmode\nv2\n\n…`)。 -/// 若某行里含 `\n`(写入端漏拦),`decode` 会把它拆成两行 ⇒ 源列表**整体错位** -/// (每个源的 url/key 串行),**不报错、不 panic** ⇒ 运行时把请求打到错误的 URL 上。 -/// -/// ⚠️ **`decode` 保持纯函数**(它的返回类型被 T2 的测试钉住,且它被单测直接调用) -/// ⇒ 它只**记录**异常,**不打日志**(单测环境里没有 nginx 日志设施)。 -/// 真正的告警在**读 payload 的地方**([`lookup_upstream`])打。 -static ODD_V2_SEEN: std::sync::atomic::AtomicBool = std::sync::atomic::AtomicBool::new(false); - -/// 异常 payload 的**结构**信息(**不含任何内容字节**)。 -/// -/// ⚠️ **绝不能**把 payload 本身(或它的片段)写进日志: -/// payload 第 2 行是**路由级凭据**(`Authorization` 头值), -/// v2 段里每行源凭据也是敏感值 ⇒ 落盘即泄漏。 -/// ⇒ 这里只记**数量**(行数 / 源个数),够定位「哪个路由的数据坏了」。 -static ODD_V2_SHAPE: std::sync::Mutex<(usize, usize)> = std::sync::Mutex::new((0, 0)); - -/// 「已告警过」标记:每个 worker 只告警一次,避免热路径刷日志。 -static ODD_V2_WARNED: std::sync::atomic::AtomicBool = std::sync::atomic::AtomicBool::new(false); - -/// v2 段末尾是否**多出一行非空**(只剩 url 没有 key)⇒ 那个源会被 [`decode`] -/// **静默丢弃**。 +/// payload 的 v2 段末尾是否**多出一行非空**(只剩 url 没有 key) +/// ⇒ 那个源会被 [`decode`] **静默丢弃**。 /// /// ⚠️ 判据用「剩下的那行**非空**」而不是「v2 段行数为奇数」: /// payload 以 `\n` 结尾时 `split` 会多出一个**空**行(= 某个源的 key 为空 /// 或结尾符)⇒ 行数是奇数,但**并没有**真的丢源 ⇒ 不能按奇数报。 /// 「剩下的那行非空」才精确对应「末尾有一对只剩 url 没有 key」。 -fn v2_has_dangling_tail(lines: &[&str]) -> bool { - // v2 段从第 4 行起,每两行一个源(url + key)。 - let mut i = 4; - while i + 1 < lines.len() { - i += 2; +/// +/// ⚠️ **不分配**(只走 `split` 迭代器,不 `collect`): +/// 它跑在**热路径**(每个请求一次)⇒ 不能为了一次告警再堆一个 `Vec`。 +fn payload_has_dangling_tail(payload: &str) -> bool { + let mut it = payload.split(config::PAYLOAD_SEP); + // 前四行:base / key / mode / 版本标记。 + if it.next().is_none() + || it.next().is_none() + || it.next().is_none() + || it.next() != Some(PAYLOAD_V2) + { + return false; // 不是 v2 payload(或行数不够)⇒ 没有 v2 段 } - i < lines.len() && !lines[i].is_empty() + // v2 段:每两行一个源(url + key)。 + // 行数为**奇数** ⇒ 末尾多出一行(只剩 url 没有 key)。 + let mut n = 0usize; + let mut last = ""; + for l in it { + n += 1; + last = l; + } + n % 2 == 1 && !last.is_empty() } /// 解析 payload(v1 / v2 通吃)。 +/// +/// ⚠️ **纯函数**:不改全局状态、不打日志(返回类型被 T2 的测试钉住)。 +/// 「v2 段末尾多出一行」的告警在**读侧**([`lookup_upstream`])打 —— +/// 那里拿得到 `route` ⇒ **按路由各告警一次**。 pub fn decode(payload: &str) -> Decoded { let lines: Vec<&str> = payload.split(config::PAYLOAD_SEP).collect(); let mut sources = Vec::new(); @@ -138,18 +134,6 @@ pub fn decode(payload: &str) -> Decoded { }); i += 2; } - // R-T6-3:末尾多出一行(只剩 url 没有 key)⇒ 那个源被上面 while - // **静默丢弃** ⇒ 记异常(由读 payload 的地方告警),**不改返回类型**。 - if v2_has_dangling_tail(&lines) { - ODD_V2_SEEN.store(true, std::sync::atomic::Ordering::Relaxed); - // 只记**结构**(v2 段行数、解析出的源个数)⇒ **不记任何内容字节** - // (payload 第 2 行是路由级凭据、v2 段里是源凭据 ⇒ 不能落盘)。 - if let Ok(mut g) = ODD_V2_SHAPE.lock() { - if g.0 == 0 { - *g = (lines.len() - 4, sources.len()); - } - } - } } Decoded { base: lines.first().copied().unwrap_or("").to_owned(), @@ -221,23 +205,40 @@ pub fn reload_shm() -> usize { // 查询 // =========================================================================== +/// 已经告警过「payload 损坏」的路由集合(**按路由各告警一次**)。 +/// +/// 键 = 路由名。nginx worker 是进程 ⇒ 每个 worker 各有一份 ⇒ 每个 worker +/// 对每条坏路由告警一次(不会热路径刷日志)。 +static WARNED_BAD_ROUTES: std::sync::Mutex> = std::sync::Mutex::new(Vec::new()); + /// 热路径查表:`route → 完整上游配置(base / key / mode / sources)` pub fn lookup_upstream(route: &str) -> Option { let payload = state::get(config::KEY_CX_PREFIX, route.as_bytes())?.0; let up = decode(&payload); // R-T6-3:v2 段末尾多出一行(只剩 url 没有 key)⇒ 那个源被**静默丢弃**。 // 写入端已按 R-T6-2 拒掉控制字符,所以这基本只可能是**数据损坏 / 旧版本写入**。 - // ⇒ 留证据(每个 worker 只告警一次,避免热路径刷日志)。 + // ⇒ 留证据(**按路由各告警一次**,避免热路径刷日志)。 // // ⚠️ 只报**结构**(行数 / 源个数),**不报 payload 内容**: // payload 第 2 行是路由级凭据、v2 段里是源凭据 ⇒ 落盘即泄漏。 - if ODD_V2_SEEN.swap(false, std::sync::atomic::Ordering::Relaxed) - && !ODD_V2_WARNED.swap(true, std::sync::atomic::Ordering::Relaxed) - { - let (v2_lines, n_sources) = ODD_V2_SHAPE.lock().map(|g| *g).unwrap_or((0, 0)); - util::log_err(&format!( - "[cache] 路由 {route} 的上游 payload v2 段行数为奇数(末尾有一对只剩 url 没有 key)⇒ 该源被静默丢弃(数据损坏?);v2 段行数={v2_lines} 解析出的源个数={n_sources}" - )); + if payload_has_dangling_tail(&payload) { + let first_time = match WARNED_BAD_ROUTES.lock() { + Ok(mut g) => { + if g.iter().any(|r| r == route) { + false + } else { + g.push(route.to_owned()); + true + } + } + Err(_) => true, + }; + if first_time { + util::log_err(&format!( + "[cache] 路由 {route} 的上游 payload v2 段末尾多出一行(只剩 url 没有 key)⇒ 该源被静默丢弃(数据损坏?);解析出的源个数={}", + up.sources.len() + )); + } } if up.base.is_empty() && up.sources.is_empty() { return None; @@ -378,6 +379,14 @@ fn validate_text(raw: &str, max: usize, field: &str) -> Result { /// 源标识(id)上限。 pub const SOURCE_ID_MAX_LEN: usize = 32; +/// 单条路由的**源池条目数上限**(R-T6-17)。 +/// +/// 为什么要有上限:源池进 shm payload(每源两行)⇒ 条数无界 ⇒ +/// 单条 payload 长度无界(shm 单条大小上限**未核实**)。 +/// +/// 16 是宽裕的值:今天的真实池子最多 6 条(6 个生态 + docker)。 +const MAX_SOURCES_PER_ROUTE: usize = 16; + /// 把任意串转成「小写字母/数字/`-`」的 slug(连续分隔符折叠,首尾去掉)。 fn slug(raw: &str) -> String { let mut out = String::with_capacity(raw.len()); @@ -442,6 +451,52 @@ pub struct SourceInput { pub note: String, } +/// 解析管理台提交的 `sources` 字段(**JSON 数组的字符串**)→ 源池条目。 +/// +/// ## 传输格式(为什么是「数组的字符串」而不是数组本身) +/// +/// `ipass_core::http::params()` 解析 JSON body 时,**数组/对象类型的字段会被丢掉** +/// ⇒ 直接传 `{"sources": [...]}` 会被**静默忽略**(看起来「保存成功」但源池根本没变)。 +/// ⇒ 管理台必须把整个数组当**字符串**传: +/// `sources=[{"id":"goproxy-cn","url":"https://goproxy.cn","key":"","note":""}]` +/// +/// ## 错误语义(**绝不能**回退成空数组) +/// +/// 解析失败**必须**返回 `Err`(调用方回 400):空数组的语义是「**清空源池**」, +/// 回退成空数组 ⇒ 一次手滑提交就把源池抹了。 +/// +/// ## 字段类型不对 ⇒ `Err`(不许静默丢) +/// +/// 元素里某字段**存在**但**不是字符串**(如 `"url": 123`)⇒ `Err`。 +/// (旧实现会静默变成空串 ⇒ 报错信息指向不准,且把「类型错」伪装成「没填」。) +pub(crate) fn parse_sources(raw: &str) -> Result, String> { + let v: Value = serde_json::from_str(raw).map_err(|e| format!("不是合法 JSON:{e}"))?; + let arr = v + .as_array() + .ok_or_else(|| "必须是 JSON 数组".to_owned())?; + let mut out = Vec::with_capacity(arr.len()); + for (i, item) in arr.iter().enumerate() { + let obj = item + .as_object() + .ok_or_else(|| format!("数组元素 {i} 必须是对象").to_owned())?; + // 字段**存在**但类型不对 ⇒ Err(不许静默丢)。 + let field = |name: &str| -> Result { + match obj.get(name) { + None => Ok(String::new()), + Some(Value::String(s)) => Ok(s.clone()), + Some(_) => Err(format!("数组元素 {i} 的字段 {name} 必须是字符串")), + } + }; + out.push(SourceInput { + id: field("id")?, + url: field("url")?, + key: field("key")?, + note: field("note")?, + }); + } + Ok(out) +} + /// 源校验与规范化(**单条**;批次内 id 唯一性见 [`validate_sources`])。 /// /// * `url` 必须与 `base` 同规则(http/https、不带尾斜杠、**不含控制字符**); @@ -477,6 +532,13 @@ pub fn validate_source(raw: &SourceInput) -> Result { /// 撞 id 时加 `-2` / `-3` 后缀(**同批次即可**:id 只用于展示与人工识别, /// 运行时认的是**下标** ⇒ 冷却键也不受 id 影响)。 pub fn validate_sources(list: &[SourceInput]) -> Result, String> { + // R-T6-17:源池条目数上限(防止单条 payload 长度无界)。 + if list.len() > MAX_SOURCES_PER_ROUTE { + return Err(format!( + "源池条目数过多(上限 {MAX_SOURCES_PER_ROUTE} 条,实际 {} 条)", + list.len() + )); + } let mut out: Vec = Vec::with_capacity(list.len()); for raw in list { let mut s = validate_source(raw)?; @@ -549,6 +611,41 @@ pub fn resolve_base(base: &str, sources: &[CacheSource]) -> Result Result<(), String> { + if source_count > 1 && !route_key.is_empty() { + return Err(format!( + "路由 {route} 是多源路由({source_count} 个源),不允许配路由级凭据:\ + 路由级凭据会被复制给池里**每一个**第三方镜像站(一份凭据发给 N 个互不信任的第三方)。\ + 请改为逐源配置 —— 在每个源的 sources[].key 上单独填它的凭据。" + )); + } + Ok(()) +} + /// 新增或覆盖一条上游配置。 /// /// `base` 传 `None` 或空串表示「保留原值」(新建时必须填); @@ -557,6 +654,23 @@ pub fn resolve_base(base: &str, sources: &[CacheSource]) -> Result 1** 且**路由级 key 非空** ⇒ 返回 `Err`(⇒ 管理 API 回 400)。 +/// 理由与改法见 [`check_route_key_for_sources`]。 pub fn upsert( route_raw: &str, base_raw: Option<&String>, @@ -661,6 +775,21 @@ pub fn upsert( if let Some(k) = &key_arg { item.key = k.clone(); } + // R-T6-12 ② **写入门禁**:多源路由 + 路由级 key 非空 ⇒ 拒绝(⇒ 400)。 + // + // ⚠️ 判据必须用**落库后**的值(`item.sources` / `item.key`): + // 否则「路由级 key 是上一次留下的、这次只提交了 sources」会漏判。 + // + // ⚠️ 只在**本次写入会形成多源**时拦;单源路由的老配置**不受影响**(向后兼容)。 + { + // 有效源数:`item.sources` 为空 ⇒ 单 base 模式(有效源数 = 1,**不得误伤**)。 + let source_count = if item.sources.is_empty() { + 1 + } else { + item.sources.len() + }; + check_route_key_for_sources(&route, source_count, &item.key)?; + } if let Some(v) = name_v { item.name = v; } @@ -711,11 +840,28 @@ pub fn remove(route_raw: &str) -> Result { // 视图(管理台 / 账号态) // =========================================================================== -/// 上游凭据掩码:只留末 4 位。空串回空串(前端据此显示「未配置」)。 +/// 上游凭据掩码。空串回空串(前端据此显示「未配置」)。 +/// +/// ## 规则(R-T6-16) +/// +/// * 长度 **< 8** ⇒ **整体打码**(`"****"`),**不显示任何明文片段**; +/// * 长度 **≥ 8** ⇒ `"****"` + 末 4 位。 +/// +/// ## 为什么短凭据要整体打码 +/// +/// 旧实现是「`****` + 末 4」⇒ 长度 ≤ 4 的 key **被完整显示** +/// (`"****" + "abcd"` = 原文一字不差)。 +/// T6 把**每个源**的 key 都接进视图 ⇒ 暴露面被放大 ⇒ 短凭据必须整体打码。 +/// +/// (路由级 key 的掩码走同一个函数 ⇒ 一并生效。) pub fn mask_key(k: &str) -> String { if k.is_empty() { return String::new(); } + // 短凭据:整体打码,**不露任何明文**。 + if k.chars().count() < 8 { + return "****".to_owned(); + } let skip = k.chars().count().saturating_sub(4); let tail: String = k.chars().skip(skip).collect(); format!("****{tail}") @@ -1017,6 +1163,177 @@ mod tests { assert!(e.contains("上游基址"), "错误信息应说清缺什么:{e}"); } + // ------------------------------------------------------------------ + // S1:`parse_sources` 单测(「解析失败必须 400、绝不能回退成空数组」) + // ------------------------------------------------------------------ + + #[test] + fn parse_sources_accepts_a_valid_non_empty_array() { + let raw = r#"[{"id":"goproxy-cn","url":"https://goproxy.cn","key":"","note":"n1"}]"#; + let v = parse_sources(raw).unwrap(); + assert_eq!(v.len(), 1); + assert_eq!(v[0].id, "goproxy-cn"); + assert_eq!(v[0].url, "https://goproxy.cn"); + assert_eq!(v[0].key, ""); + assert_eq!(v[0].note, "n1"); + } + + #[test] + fn parse_sources_accepts_a_valid_empty_array_as_clear_semantics() { + // `[]` 是**合法**的(语义 = 清空源池),**不是**解析失败。 + let v = parse_sources("[]").unwrap(); + assert_eq!(v.len(), 0); + } + + #[test] + fn parse_sources_rejects_invalid_json() { + let e = parse_sources("{not json").unwrap_err(); + assert!(e.contains("不是合法 JSON"), "错误信息应说清是什么问题:{e}"); + } + + #[test] + fn parse_sources_rejects_non_array_values() { + // 对象 / 字符串 / 数字 / null ⇒ 都不是数组 ⇒ Err。 + for raw in [r#"{"a":1}"#, r#""abc""#, "123", "null", "true"] { + let e = parse_sources(raw).unwrap_err(); + assert!(e.contains("必须是 JSON 数组"), "错误信息应说清是什么问题:{e}"); + } + } + + #[test] + fn parse_sources_rejects_non_object_array_elements() { + let e = parse_sources(r#"["abc", 1, null]"#).unwrap_err(); + assert!(e.contains("必须是对象"), "错误信息应说清是什么问题:{e}"); + } + + #[test] + fn parse_sources_rejects_a_field_present_with_a_wrong_type() { + // O2:字段**存在**但**不是字符串** ⇒ Err(不许静默变成空串)。 + let e = parse_sources(r#"[{"url":123}]"#).unwrap_err(); + assert!(e.contains("必须是字符串"), "错误信息应说清是哪个字段:{e}"); + // 其余字段同样 + assert!(parse_sources(r#"[{"id":true}]"#).is_err()); + assert!(parse_sources(r#"[{"key":[]}]"#).is_err()); + assert!(parse_sources(r#"[{"note":{}}]"#).is_err()); + } + + #[test] + fn parse_sources_treats_absent_fields_as_empty() { + // 字段**缺失** ⇒ 空串(不是错误)—— 源可以只给 url。 + let v = parse_sources(r#"[{"url":"https://a"}]"#).unwrap(); + assert_eq!(v.len(), 1); + assert_eq!(v[0].url, "https://a"); + assert_eq!(v[0].id, ""); + assert_eq!(v[0].key, ""); + assert_eq!(v[0].note, ""); + } + + // ------------------------------------------------------------------ + // M3:写入门禁(纯函数)单测 + // ------------------------------------------------------------------ + + #[test] + fn route_key_gate_rejects_multi_source_route_with_a_route_level_key() { + // 多源(有效源数 > 1)+ 路由级 key 非空 ⇒ 拒绝。 + let e = check_route_key_for_sources("go", 3, "Bearer secret").unwrap_err(); + assert!(e.contains("go"), "错误信息应说清是哪条路由:{e}"); + assert!(e.contains("sources[].key"), "错误信息应说清怎么改:{e}"); + } + + #[test] + fn route_key_gate_allows_single_source_route_with_a_route_level_key() { + // 单源路由的老配置**不受影响**(向后兼容)。 + assert!(check_route_key_for_sources("go", 1, "Bearer secret").is_ok()); + // 有效源数 = 1(单 base 模式,sources 为空 ⇒ 有效源数 1)⇒ 不拦。 + assert!(check_route_key_for_sources("go", 0, "Bearer secret").is_ok()); + } + + #[test] + fn route_key_gate_allows_multi_source_route_without_a_route_level_key() { + // 多源但路由级 key 为空 ⇒ 允许(逐源配凭据是正确做法)。 + assert!(check_route_key_for_sources("go", 3, "").is_ok()); + } + + // ------------------------------------------------------------------ + // S3:`mask_key` 短凭据整体打码 + // ------------------------------------------------------------------ + + #[test] + fn mask_key_hides_short_credentials_entirely() { + // 长度 < 8 ⇒ 整体打码,**不露任何明文**。 + for k in ["a", "ab", "abcd", "abcde", "abcdefg"] { + let m = mask_key(k); + assert_eq!(m, "****", "短凭据 {k:?} 应整体打码,实际 {m:?}"); + assert!(!m.contains(k), "掩码不得含明文:{m:?}"); + } + } + + #[test] + fn mask_key_shows_only_the_last_four_of_long_credentials() { + // 长度 >= 8 ⇒ `****` + 末 4。 + assert_eq!(mask_key("12345678"), "****5678"); + assert_eq!(mask_key("Bearer abcdefgh"), "****efgh"); + assert_eq!(mask_key("0123456789"), "****6789"); + } + + #[test] + fn mask_key_of_empty_key_is_empty() { + // 空串回空串(前端据此显示「未配置」)。 + assert_eq!(mask_key(""), ""); + } + + // ------------------------------------------------------------------ + // S5:源池条目数上限 + // ------------------------------------------------------------------ + + #[test] + fn source_count_over_the_limit_is_rejected() { + let list: Vec = (0..=MAX_SOURCES_PER_ROUTE) + .map(|i| src("", &format!("https://h{i}.example"), "")) + .collect(); + let e = validate_sources(&list).unwrap_err(); + assert!( + e.contains(&MAX_SOURCES_PER_ROUTE.to_string()), + "错误信息应说清上限:{e}" + ); + } + + #[test] + fn source_count_at_the_limit_is_accepted() { + let list: Vec = (0..MAX_SOURCES_PER_ROUTE) + .map(|i| src("", &format!("https://h{i}.example"), "")) + .collect(); + assert_eq!(validate_sources(&list).unwrap().len(), MAX_SOURCES_PER_ROUTE); + } + + // ------------------------------------------------------------------ + // S2:`decode` 恢复纯函数(无全局状态)+ 读侧告警判据 + // ------------------------------------------------------------------ + + #[test] + fn decode_is_pure_and_does_not_touch_global_state() { + // `decode` 不再有全局静态 ⇒ 同样的输入永远同样的输出(可重复调用)。 + let payload = "https://a\nKEY\nproxy\nv2\nhttps://b\nK2\nhttps://c\n"; + let a = decode(payload); + let b = decode(payload); + assert_eq!(a.sources.len(), 2); + assert_eq!(a.sources[0].url, b.sources[0].url); + assert_eq!(a.sources[1].url, b.sources[1].url); + } + + #[test] + fn dangling_tail_detection_matches_the_dropped_source_case() { + // 末尾多出一行非空(只剩 url 没 key)⇒ 那个源被静默丢弃 ⇒ 判为损坏。 + assert!(payload_has_dangling_tail("b\nk\nm\nv2\nu1\nk1\nu2")); + // 正常(偶数对)⇒ 不报。 + assert!(!payload_has_dangling_tail("b\nk\nm\nv2\nu1\nk1")); + // 末尾是**空**行(key 为空 / 结尾符)⇒ 不是损坏 ⇒ 不报。 + assert!(!payload_has_dangling_tail("b\nk\nm\nv2\nu1\nk1\n")); + // 不是 v2 payload(v1 / 行数不够)⇒ 不报。 + assert!(!payload_has_dangling_tail("b\nk\nm")); + assert!(!payload_has_dangling_tail("b\nk\nm\nv1\nu1\nk1\nu2")); + } + #[test] fn same_sources_compares_url_and_key_only() { let mut a = CacheSource {