feat(cache): 多源路由不许把路由级凭据发给第三方源(R-T6-12)

- effective_key:有效源数 > 1 时不再回落路由级 key(源没配凭据 ⇒ 空),
  单源 / v1 payload 维持原回落语义。
- upsert 写入门禁:落库后有效源数 > 1 且路由级 key 非空 ⇒ Err(⇒ 400),
  错误信息说清哪条路由、为什么、怎么改(逐源配 sources[].key)。
- parse_sources 移到 upstreams.rs 并补 7 条单测;字段存在但类型不对 ⇒ Err。
- decode 恢复纯函数:payload 损坏告警挪到读侧,按路由各告警一次,
  只报结构(源个数),不落任何内容字节。
- mask_key:长度 < 8 的凭据整体打码,不再暴露明文片段。
- 源池条目数上限 16 条/路由。
- upsert 文档注释对齐 R-T6-14 的 base 语义。

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
This commit is contained in:
adminandClaude Sonnet 5.5 committed 2026-10-31 01:48:38 +08:00
1 parent ac1c51d374
commit dc49c758fc
3 files changed
+413 -91

No files matched your search

+1 -25
View File
@@ -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<Vec<upstreams::SourceInput>, 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);
+43 -14
View File
@@ -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)
// -----------------------------------------------------------------
+369 -52
View File
@@ -84,46 +84,42 @@ pub struct Decoded {
pub sources: Vec<CacheSource>,
}
/// 「v2 段行数为奇数」标记(由 [`decode`] 置位,由 [`lookup_upstream`] 取走并告警)。
///
/// **为什么必须留证据**:payload 是**换行分隔**的
/// (`base\nkey\nmode\nv2\n<url1>\n<key1>…`)。
/// 若某行里含 `\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<Vec<String>> = std::sync::Mutex::new(Vec::new());
/// 热路径查表:`route → 完整上游配置(base / key / mode / sources)`
pub fn lookup_upstream(route: &str) -> Option<Decoded> {
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<String, String> {
/// 源标识(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<Vec<SourceInput>, 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<String, String> {
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<CacheSource, String> {
/// 撞 id 时加 `-2` / `-3` 后缀(**同批次即可**:id 只用于展示与人工识别,
/// 运行时认的是**下标** ⇒ 冷却键也不受 id 影响)。
pub fn validate_sources(list: &[SourceInput]) -> Result<Vec<CacheSource>, 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<CacheSource> = 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<String, Strin
// 写入
// ===========================================================================
/// **写入门禁**(R-T6-12 ②):多源路由 + 路由级 key 非空 ⇒ 拒绝。
///
/// ## 为什么
///
/// `cache::effective_key` 的回落语义(「源自己没配 key ⇒ 用路由级 key」)
/// 在**多源路由**上等价于「把一份凭据发给池里**每一个**第三方镜像站」。
/// ⇒ 多源路由必须**逐源**配凭据(每个源用各自的 `sources[].key`)。
///
/// 运行期那道闸(`effective_key` 多源不回落)是**兜底**
/// (管不住手改文件 / 迁移脚本 / 任何绕过 API 的写路径);
/// 这道是**体验** —— 让管理员在保存时就看到明确的 400 与怎么改。
///
/// ## 判据(**落库后**的值)
///
/// * `source_count` = **有效源数**(`item.sources` 为空 ⇒ 1,即单 base 模式;
/// 否则 `item.sources.len()`)⇒ 单源路由**不受影响**(向后兼容);
/// * `route_key` = **落库后**的路由级 key(`key_arg` 为 `None` ⇒ 原值;
/// `Some("")` ⇒ 空;`Some(v)` ⇒ `v`)。
///
/// 抽成纯函数是为了能单测(`upsert` 依赖 shm / 文件,不好直接测)。
fn check_route_key_for_sources(
route: &str,
source_count: usize,
route_key: &str,
) -> 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<String, Strin
///
/// `sources` 传 `None` 表示保留原值、`Some(&[])` 表示**清空源池**(退回单 base 模式)、
/// `Some(list)` 表示**覆盖**。
///
/// ## `base` 与源池的关系(R-T6-14)
///
/// * 管理员**显式**填了 base ⇒ 以他填的为准(哪怕它不在池子里 —— 那是合法用法);
/// * 管理员**没**显式填 base、但提交了**非空**源池 ⇒ base 取**池子头**
/// (`sources[0].url`)—— base 的语义就是「池子的头」,
/// 池子换了 base 不跟着换就会指向一个**已经不在池子里**的旧源;
/// * base 空、源池非空 ⇒ 自动补齐成 `sources[0].url`(**不报错**);
/// * base 与源池**同时**为空 ⇒ 报错(新建时必须填)。
///
/// ⇒ 落库后 **「base 非空」恒等于「已配置」** ⇒ `sync_shm` / `reload_shm` 的
/// `base.is_empty()` 判据一个字都不用改。
///
/// ## 写入门禁(R-T6-12 ②)
///
/// 落库后**有效源数 > 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<String, String> {
// 视图(管理台 / 账号态)
// ===========================================================================
/// 上游凭据掩码:只留末 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<SourceInput> = (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<SourceInput> = (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 {