Files
ipass-plugin-cache/src/cache.rs
T

1156 lines
52 KiB
Rust
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
//! 缓存插件的 nginx 变量层:把「上游表 + 请求 URI」算成 `proxy_pass` 能用的值。
//!
//! 注册**只读**变量(求值时算,模块从不主动写):
//!
//! | 变量 | 值 | 谁用 |
//! | --- | --- | --- |
//! | `$cache_target` | **被选中源**的 `base + 上游路径前缀 + 尾部 [+ ?query]` | `proxy_pass $cache_target` |
//! | `$cache_host` | **被选中源**的 Host(含端口) | `proxy_set_header Host $cache_host` |
//! | `$cache_upstream_key` | **被选中源**用的上游凭据**原值**(未配置为空) | 排障/日志 |
//! | `$cache_auth` | **被选中源****实际下发**的 Authorization 值(含防 `sk_` 泄漏规则) | `proxy_set_header Authorization $cache_auth` |
//! | `$cache_eco` | 生态名(`go` / `cargo` / …) | 日志与排障 |
//! | `$cache_key` | `<route>:<uri>` | `proxy_cache_key`(显式给定,不依赖 `$proxy_host`) |
//! | `$cache_target_alt` / `$cache_target_alt2` | 备选 1 / 备选 2 的完整上游 URL | 多跳回退 |
//! | `$cache_auth_alt` / `$cache_auth_alt2` | 备选 1 / 备选 2 的 Authorization | 多跳回退 |
//! | `$cache_pick` | 本请求的选源结果(`"i0\|i1\|i2"`,如 `"2\|0\|1"`) | 日志/排障 |
//!
//! ⚠️ `$proxy_host` 在**变量式 `proxy_pass`** 下不可靠,所以 `proxy_cache_key`
//! 必须显式指定;用本变量即可(同 zone 内 URI 唯一,跨 zone 天然隔离)。
//!
//! 这就是「UI 配上游 + 动态注入」的落点:上游地址与凭据都来自共享内存
//! (`cx:<route>`),改配置立即生效,无需改 nginx conf、无需 reload。
//!
//! ## 请求级 memo(一个请求只查一次上游表)
//!
//! 多源下同一请求会求值 `$cache_target` / `$cache_host` / `$cache_auth` /
//! `$cache_upstream_key` / 四个 alt / `$cache_pick` 等**十个**变量;每次都
//! `lookup_upstream()` 就是每次都把整份上游 payload 拷一遍 + 逐行解码 +
//! 再克隆一份源列表(单次 ≈ 25 次堆分配 ⇒ 一个请求 ≈ 200 次额外分配,
//! 而 nginx 自己每请求也就几十次分配)。
//!
//! ⇒ 用一个**内部**变量 `$cache_ctx` 承载请求级 memo:它的值槽里存的不是
//! 字符串,而是**指向请求内存池里 `Memo` 的指针**。nginx 侧
//! `ngx_http_get_indexed_variable()`(`ngx_http_variables.c`)在
//! `r->variables[index].valid` 为真时**直接返回、不再调 get_handler**
//! ⇒ 天然是请求级缓存;`Memo` 本体由请求池分配(`Pool::allocate` 注册池
//! cleanup,负责 drop 内部的 `Vec`/`String`)⇒ 请求结束随池回收,
//! 不跨请求、不泄漏。
use core::sync::atomic::{AtomicIsize, Ordering};
use ngx::core::{Pool, Status};
use ngx::ffi::{
NGX_HTTP_VAR_CHANGEABLE, NGX_HTTP_VAR_NOCACHEABLE, NGX_HTTP_VAR_NOHASH, ngx_conf_t,
ngx_http_add_variable, ngx_http_get_indexed_variable, ngx_http_get_variable_index,
ngx_http_request_t, ngx_http_variable_value_t, ngx_int_t, ngx_str_t, ngx_uint_t,
};
use ngx::ngx_string;
use ipass_core::{http, state, util};
use crate::config;
use crate::handlers;
use crate::models::CacheSource;
use crate::upstreams;
// ===========================================================================
// 变量分派标记
// ===========================================================================
/// `$cache_target`:完整上游 URL
pub const VAR_TARGET: usize = 1;
/// `$cache_host`:上游 Host 头
pub const VAR_HOST: usize = 2;
/// `$cache_upstream_key`:上游凭据(空 = 不下发鉴权头)
pub const VAR_UPSTREAM_KEY: usize = 3;
/// `$cache_eco`:生态名
pub const VAR_ECO: usize = 4;
/// `$cache_key`:缓存键(`<route>:<uri>`)
pub const VAR_KEY: usize = 5;
/// `$cache_auth`:**实际下发给上游**的 `Authorization` 头值(含防泄漏规则)
pub const VAR_AUTH: usize = 6;
/// `$cache_target_alt`:备选 1 的完整上游 URL
pub const VAR_TARGET_ALT: usize = 7;
/// `$cache_target_alt2`:备选 2 的完整上游 URL
///
/// ⚠️ **源数 < 3 的路由上 alt2 与 alt 指向同一个源** ⇒ **conf 不得对
/// 源数 < 3 的路由使用 alt2**;跳数按 `min(3, 该路由源数)` 裁
/// (cargo-dl 的池是 2 个源 ⇒ 2 跳;docker 的池 2026-10-30 起只剩
/// 1 个源 ⇒ 1 跳)。
pub const VAR_TARGET_ALT2: usize = 8;
/// `$cache_auth_alt`:备选 1 的 Authorization
pub const VAR_AUTH_ALT: usize = 9;
/// `$cache_auth_alt2`:备选 2 的 Authorization
///
/// ⚠️ 同 [`VAR_TARGET_ALT2`]:源数 < 3 时 alt2 与 alt 同源 ⇒ conf 不得使用。
pub const VAR_AUTH_ALT2: usize = 10;
/// `$cache_pick`:本请求的选源结果(**请求内缓存**)
pub const VAR_PICK: usize = 11;
/// `$cache_ctx`:**内部**变量,值槽里存的是指向请求池里 [`Memo`] 的指针
const VAR_MEMO: usize = 12;
/// `$cache_pick` 的变量索引(postconfig 解析一次,运行时按索引读)。
///
/// 为什么不用 `ngx_http_get_variable()` 现查:那个 API 的 `key` 参数是
/// **哈希桶号**,传 0 会导致间歇性查不到(详见 `read_pick_var` 的注释)。
static CACHE_PICK_IDX: AtomicIsize = AtomicIsize::new(-1);
/// `$cache_ctx` 的变量索引(postconfig 解析一次,运行时按索引读)。
static CACHE_MEMO_IDX: AtomicIsize = AtomicIsize::new(-1);
/// 供 `handlers::prefetch_indexes`(postconfig)填 `$cache_pick` 的变量索引。
pub(crate) fn set_pick_index(idx: isize) {
CACHE_PICK_IDX.store(idx, Ordering::Relaxed);
}
/// 解析内部变量 `$cache_ctx` 的索引(postconfig)。
///
/// ⚠️ 必须 postconfig 期做:`ngx_http_get_variable_index()` 会在
/// `cmcf->variables` 里建索引项,而 `ngx_http_variables_init_vars()`
/// (nginx 在**所有** postconfig 跑完之后才执行)才把本插件在 preconfig
/// 注册的 `get_handler` 挂到那个索引上。
pub(crate) fn prefetch_memo_index(cf: *mut ngx_conf_t) -> bool {
let mut n = ngx_str_t {
len: "cache_ctx".len(),
data: b"cache_ctx\0".as_ptr() as *mut u8,
};
// SAFETY: cf 由 nginx 传入且有效
let idx = unsafe { ngx_http_get_variable_index(cf, &mut n) };
if idx < 0 {
return false;
}
CACHE_MEMO_IDX.store(idx as isize, Ordering::Relaxed);
true
}
/// 注册本插件的全部变量。返回 false = 失败,gateway 会 EMERG 退出。
///
/// # Safety
/// `cf` 必须由 nginx 传入且有效。
pub unsafe fn preconfig(cf: *mut ngx_conf_t) -> bool {
let mut target = ngx_string!("cache_target");
let mut host = ngx_string!("cache_host");
let mut ukey = ngx_string!("cache_upstream_key");
let mut eco = ngx_string!("cache_eco");
let mut ckey = ngx_string!("cache_key");
let mut auth = ngx_string!("cache_auth");
let mut t_alt = ngx_string!("cache_target_alt");
let mut t_alt2 = ngx_string!("cache_target_alt2");
let mut a_alt = ngx_string!("cache_auth_alt");
let mut a_alt2 = ngx_string!("cache_auth_alt2");
let mut pick = ngx_string!("cache_pick");
let mut memo = ngx_string!("cache_ctx");
unsafe {
add_var(cf, &raw mut target, VAR_TARGET, false)
&& add_var(cf, &raw mut host, VAR_HOST, false)
&& add_var(cf, &raw mut ukey, VAR_UPSTREAM_KEY, false)
&& add_var(cf, &raw mut eco, VAR_ECO, false)
&& add_var(cf, &raw mut ckey, VAR_KEY, false)
&& add_var(cf, &raw mut auth, VAR_AUTH, false)
&& add_var(cf, &raw mut t_alt, VAR_TARGET_ALT, false)
&& add_var(cf, &raw mut t_alt2, VAR_TARGET_ALT2, false)
&& add_var(cf, &raw mut a_alt, VAR_AUTH_ALT, false)
&& add_var(cf, &raw mut a_alt2, VAR_AUTH_ALT2, false)
// ⚠️ $cache_pick 必须**请求内缓存**:target / auth / host 三个变量
// 必须取到同一组源,否则会出现「请求打向 A 源却带 B 源凭据」的错配。
&& add_var(cf, &raw mut pick, VAR_PICK, true)
// 内部变量:值槽里存的是指针,不是字符串 ⇒ 只能由本模块自己读。
&& add_internal_var(cf, &raw mut memo)
}
}
/// 注册一个只读变量,值由 [`var_get`] 按 `slot` 分派计算。
///
/// `NOCACHEABLE`:本变量是「读时现算」,若被 nginx 缓存进 `r->variables`,
/// 同一请求多次求值(`proxy_pass` 一次、`proxy_set_header` 再读)会拿到
/// 首次结果——对上游配置**中途变更**的场景会读到旧值,故标记不可缓存。
///
/// ⚠️ 例外:`$cache_pick` 必须**可缓存**(`cacheable = true`)——
/// 选源结果一旦算出就要在同一请求内被 target/auth/host 共用,
/// 每次重算(尤其冷却状态被别的 worker 改动时)会造成「打向 A 源、带 B 源凭据」。
/// 代价:上游配置中途变更对本请求不可见(下一个请求可见)——可接受。
unsafe fn add_var(cf: *mut ngx_conf_t, name: *mut ngx_str_t, slot: usize, cacheable: bool) -> bool {
let flags = if cacheable {
NGX_HTTP_VAR_CHANGEABLE as ngx_uint_t
} else {
(NGX_HTTP_VAR_CHANGEABLE | NGX_HTTP_VAR_NOCACHEABLE) as ngx_uint_t
};
// SAFETY: cf 由 nginx 传入;name 指向调用方栈上的 ngx_str_t,注册时被拷贝
let var = unsafe { ngx_http_add_variable(cf, name, flags) };
if var.is_null() {
return false;
}
// SAFETY: var 非空且由本函数独占初始化;data 承载分派标记
unsafe {
(*var).get_handler = Some(var_get);
(*var).set_handler = None;
(*var).data = slot;
}
true
}
/// 注册**内部**变量 `$cache_ctx`(请求级 memo 的载体)。
///
/// 与 [`add_var`] 的区别:
/// * 值不是字符串,而是**指向请求池里 [`Memo`] 的指针** ⇒ 只有本模块自己读;
/// * `NOHASH` ⇒ 不进 nginx 的变量哈希表 ⇒ 运行期没人能按名字把它取出来
/// (conf 里引用它也没意义——它不是字符串);
/// * **不带** `NOCACHEABLE` ⇒ nginx 侧 `ngx_http_get_indexed_variable()`
/// 在 `r->variables[index].valid` 为真时直接返回、不再调 get_handler
/// ⇒ 天然请求级缓存(这是 R-T4-2 的实现基础)。
unsafe fn add_internal_var(cf: *mut ngx_conf_t, name: *mut ngx_str_t) -> bool {
// SAFETY: cf 由 nginx 传入;name 指向调用方栈上的 ngx_str_t,注册时被拷贝
let var = unsafe { ngx_http_add_variable(cf, name, NGX_HTTP_VAR_NOHASH as ngx_uint_t) };
if var.is_null() {
return false;
}
// SAFETY: var 非空且由本函数独占初始化
unsafe {
(*var).get_handler = Some(var_get);
(*var).set_handler = None;
(*var).data = VAR_MEMO;
}
true
}
// ===========================================================================
// 求值
// ===========================================================================
/// 管理台「测试」用的探针前缀。conf 里对应一个 `internal` location:
///
/// ```nginx
/// location /_cache_test/ {
/// internal; # 挡住外部直连(否则可绕过鉴权触达上游)
/// proxy_pass $cache_target; # 复用同一个变量,只是 tail 变成 "/"
/// proxy_set_header Host $cache_host;
/// proxy_set_header Authorization $cache_upstream_key;
/// }
/// ```
///
/// 与 apix 的 `/_apix_probe/`、llm 的 `/_upstream_test/` 同一手法:
/// **对外出口与内部探针共用同一套「定上游 + 换凭据」逻辑**,探针才能真正
/// 代表真实转发的行为(自己另写一套探针代码必然漂移)。
pub const PROBE_PREFIX: &str = "/_cache_test/";
/// 解析请求 URI → `(route, tail)`。
///
/// * 正常路径:`/go/pkg-a` → `("go", "/pkg-a")`;`/v2/library/x` → `("docker", "/library/x")`
/// * 探针路径:`/_cache_test/go` → `("go", "/")` —— 固定打上游根,只验连通与凭据
///
/// `tail` 恒以 `/` 开头(上游拼 URL 用),空尾也归一成 `/`。
pub fn resolve_route(uri: &str) -> Option<(&'static str, String)> {
if let Some(rest) = uri.strip_prefix(PROBE_PREFIX) {
let seg = rest.trim_start_matches('/').split('/').next().unwrap_or("");
let route = config::route_of_seg(seg)?;
return Some((route, "/".to_owned()));
}
let route = config::route_of_uri(uri)?;
let seg = uri.trim_start_matches('/').split('/').next().unwrap_or("");
let tail = uri.get(1 + seg.len()..).unwrap_or("");
let tail = if tail.is_empty() { "/" } else { tail };
Some((route, tail.to_owned()))
}
/// 取 base 的 host 部分(含端口)。`https://a.b:8443/x` → `a.b:8443`
pub fn host_of(base: &str) -> &str {
let rest = base.split_once("://").map(|(_, r)| r).unwrap_or(base);
rest.split('/').next().unwrap_or(rest)
}
// ===========================================================================
// 选源(纯函数,可单测)
// ===========================================================================
/// FNV-1a 64 位散列(选源用;只需稳定散列,不抗碰撞)。
pub fn fnv1a(data: &[u8]) -> u64 {
let mut h: u64 = 0xcbf2_9ce4_8422_2325;
for b in data {
h ^= *b as u64;
h = h.wrapping_mul(0x0000_0100_0000_01b3);
}
h
}
/// 选源:返回三个顺位对应的源下标。
///
/// 规则:
/// 1. 起点 = `hash % n`,按顺位轮转;
/// 2. **冷却中的源降权排后**——冷却是降权不是禁用:
/// 池里只剩冷却源时仍要能出请求(宁可重试也不 500)。
/// ⚠️ 链长恒为 3 ⇒ 源数 `n > 3` 时,被冷却的源**进不了前 3 个槽**
/// (它排在健康源之后,但没有第 4 个槽位留给它);只有 `n ≤ 3` 时
/// 才谈得上「挪到尾部」这回事;
/// 3. 源数不足 3 时重复最后一个 ⇒ **链长恒为 3**,
/// conf 里写死的三跳链永远拿得到值。
pub fn select(n: usize, hash: u64, cooled: &[bool]) -> [usize; config::MAX_SLOTS] {
if n == 0 {
return [0; config::MAX_SLOTS];
}
let start = (hash % n as u64) as usize;
let mut order: Vec<usize> = Vec::with_capacity(n);
for k in 0..n {
let i = (start + k) % n;
if !cooled.get(i).copied().unwrap_or(false) {
order.push(i);
}
}
for k in 0..n {
let i = (start + k) % n;
if cooled.get(i).copied().unwrap_or(false) {
order.push(i);
}
}
let last = order.len() - 1;
let mut slots = [order[0]; config::MAX_SLOTS];
for (s, slot) in slots.iter_mut().enumerate() {
*slot = order[s.min(last)];
}
slots
}
/// 把选源结果编码成 `"i0|i1|i2"`(`$cache_pick` 的值)。
///
/// ⚠️ 格式**不许改**(R-T4-3):log handler(Task 5)按这个格式读它。
pub fn encode_pick(slots: &[usize; config::MAX_SLOTS]) -> String {
format!("{}|{}|{}", slots[0], slots[1], slots[2])
}
/// 解析 `$cache_pick`(拿不到 / 格式不对返回 `None`)。
pub fn parse_pick(raw: &str) -> Option<[usize; config::MAX_SLOTS]> {
let mut it = raw.split('|');
let mut slots = [0usize; config::MAX_SLOTS];
for slot in slots.iter_mut() {
*slot = it.next()?.trim().parse::<usize>().ok()?;
}
Some(slots)
}
/// 该源实际使用的上游凭据:源自己的优先,空则回落路由级 `key`。
///
/// ⚠️ **多源路由不应配路由级 `key`**(由 **Task 6** 落实强制)。
/// 本函数把路由级 `key` **复制给每一个没配自己凭据的源** ⇒ 池里
/// **任意一个**第三方镜像站都会收到这份路由级凭据 —— 等价于把一份凭据
/// 发给 N 个互不信任的第三方。
/// 多源路由的正确做法是**逐源配凭据**(每个源用各自的 `key`)。
/// 今天保留「空则回落路由级」的语义(单源路由依赖它),
/// 本条只是把约束**写死在注释里**,真正的强制在 Task 6。
pub fn effective_key(up: &upstreams::Decoded, src: &CacheSource) -> String {
if !src.key.is_empty() {
return src.key.clone();
}
up.key.clone()
}
/// 该路由**是否允许把客户端的 `Authorization` 转发给上游**。
///
/// 规则(2026-10-30 pre-flight 扫描 R33,源自 R21):
/// * **多源路由**(`source_count > 1`)⇒ **不转发**客户端凭据
/// —— 客户端的凭据(不只本系统的 `sk_`,也包括客户端自己带的其它
/// `Authorization`)绝不能被下发到池里**任意一个第三方镜像站**;
/// (源或路由级**配了**凭据时仍用配置值——那是管理员的显式意图,
/// 见 [`auth_header_for`] 的优先级);
/// * **docker 路由** ⇒ **始终转发**(docker 客户端只会把**镜像站 token**
/// 放进 `Authorization`,且加不了自定义头 ⇒ 不转发会陷入 401 挑战死循环,
/// 见 CLAUDE.md 硬事实 #6);
/// * **单源路由** ⇒ 转发(向后兼容的硬约束:今天的语义不变)。
///
/// ⚠️ 事实(2026-10-30):当前 8 条路由的路由级 `key` **全是空**
/// ⇒ 多源路由下**一个凭据都不会下发**(客户端自带的 `Authorization`
/// 在 go/cargo/pypi/npm/maven 上都不会被转发到第三方镜像站——这正是
/// spec §9 / R21 要的)。
/// ⚠️ 但 **docker 是例外**:docker 路由的客户端 token **会**被转发给池里的
/// 第三方镜像站(1panel / daocloud)——这是 CLAUDE.md 硬事实 #6 逼出来的
/// **已知取舍,不是遗漏**。
///
/// ⚠️ docker 的**运行期**源池当前只有 1 个源(`docker.1panel.live`;
/// `docker.m.daocloud.io` 对 `/v2/` 恒 401 已被剔除)⇒ 它走「单源 ⇒
/// 保持今天的透传语义」那条分支,结果同样是「转发」⇒ 行为不变。
/// 本函数**不对 docker 的源数做特判**(语义与运行时池大小无关)。
pub fn allow_client_auth(route: &str, source_count: usize) -> bool {
if route == "docker" {
return true;
}
source_count <= 1
}
/// 该路由各源是否处于冷却中。
///
/// 冷却项用 `expires_at` 自动过期 ⇒ 这里只需查「还活着没有」。
///
/// ⚠️ **键是「源下标」不是「源 id」**(R-T5-3)⇒ 池子变了必须清
/// 该路由的 `ch:` 条目(见 [`cool_down`] 的注释 / Task 6)。
pub fn cooled_flags(route: &str, n: usize) -> Vec<bool> {
let now = util::now();
(0..n)
.map(|i| {
let name = format!("{route}:{i}");
state::get_live(config::KEY_CH_PREFIX, name.as_bytes(), now).is_some()
})
.collect()
}
/// 把某个源打入冷却(`config::COOLDOWN_SECS` 秒后自动恢复)。
///
/// ⚠️ **键是「源下标」不是「源 id」**(R-T5-3):`ch:<route>:<下标>`。
/// ⇒ 管理员在管理台**重排 / 增删源**之后,旧的 `ch:` 条目会**套到别的源头上**。
/// ⇒ **改池子时必须清掉该路由的 `ch:` 条目**(由 **Task 6** 落实)。
/// (好消息:共享内存是匿名的 ⇒ **Pod 重启即清空全部 `ch:`**;
/// 只有「不重启就改池子」才会踩到。)
pub fn cool_down(route: &str, idx: usize) {
let name = format!("{route}:{idx}");
let until = util::now() + config::COOLDOWN_SECS;
if !state::put(config::KEY_CH_PREFIX, name.as_bytes(), b"1", until) {
util::log_err(&format!(
"[cache] 源冷却写入失败 route={route} idx={idx}(共享内存可能已满)"
));
}
}
/// 哪些**顺位**失败了(纯函数,可单测)。
///
/// * `all_failed` = 最终状态是 403/5xx ⇒ 整条换源链都失败 ⇒ 全部顺位都冷却;
/// * `slot` = 换源链写下的**失败顺位**(响应头 `X-Cache-Failed-Slot`)。
///
/// ⚠️ `Some(k)` ⇒ 冷却 **`0..=k`(整段)**,**不是**只冷却第 k 跳:
/// 走到第 k 跳说明 `slots[0..=k]` **全都失败过**(前面几跳正是因为失败
/// 才换到这里的)。
/// 只冷却最后一跳 ⇒ **首选源永远不会被踢出轮转** ⇒ 每次请求都要先撞一次
/// 死源才换源 ⇒ **熔断形同虚设**。
/// (2026-10-30 pre-flight 扫描 R34 / 裁决 R-T5-4)
///
/// `None` + 非 `all_failed` ⇒ **没换过源** ⇒ 不冷却任何源。
///
/// ⚠️ 上界裁剪:返回的顺位**不会超过 `config::MAX_SLOTS - 1`**。
/// 换源链只有 `MAX_SLOTS` 跳 ⇒ 更大的顺位不可能出现;
/// 但 `slot` 来自**响应头**(外部可控的字符串)⇒ 必须裁剪,
/// 否则一个 `X-Cache-Failed-Slot: 18446744073709551615` 就能让本函数
/// 分配一个天文大小的 `Vec`(OOM)。
pub fn failed_slots(all_failed: bool, slot: Option<usize>) -> Vec<usize> {
if all_failed {
return (0..config::MAX_SLOTS).collect();
}
let Some(k) = slot else {
return Vec::new();
};
let last = k.min(config::MAX_SLOTS - 1);
(0..=last).collect()
}
/// 本次请求的散列种子:优先用 `$request_id`(每请求唯一 ⇒ 冷请求天然分散),
/// 拿不到时退化为 URI+args 的散列。
pub fn hash_of_request(r: *mut ngx_http_request_t) -> u64 {
let rid = handlers::read_request_id(r);
if !rid.is_empty() {
return fnv1a(rid.as_bytes());
}
// ⚠️ 简报原稿写的是 `String` 缓冲 + `extend_from_slice(&args)`,但
// `http::args_raw` 给的是 `Vec<u8>`、`String::extend_from_slice` 只吃
// `&str` ⇒ 原稿这段过不了编译。这里改成字节缓冲,语义等价(拼
// `uri?args` 后整体散列)。
let mut buf: Vec<u8> = http::uri(r).into_bytes();
let args = http::args_raw(r);
buf.push(b'?');
buf.extend_from_slice(&args);
fnv1a(&buf)
}
/// 由 `(route, tail, base)` 拼出上游完整 URL。
///
/// 再补回 [`config::upstream_path_prefix`](只有 Docker 非空)。
///
/// 变量形式的 `proxy_pass` **不会自动追加 query**(nginx 已知行为),
/// 所以这里必须自己把 `args` 拼上去——否则 `?archive=tar.gz` 这类参数会被吞掉。
pub fn build_target(route: &str, tail: &str, base: &str, args: &str) -> String {
let mut t = format!("{base}{}{tail}", config::upstream_path_prefix(route));
if !args.is_empty() {
t.push('?');
t.push_str(args);
}
t
}
/// 该源实际下发的 `Authorization`(空 = 不下发任何凭据)。
///
/// `allow_client = false` ⇒ **只认配置的凭据**,客户端带什么都不转发。
///
/// `configured` 是本路由在管理台配的上游凭据(原值,管理员自己写全
/// `Bearer xxx` / `Basic yyy`)。
///
/// 三种情形,按镜像型缓存的真实需求排:
///
/// 1. **管理台配了凭据** → 用配置值(管理员自己写全 `Bearer xxx` / `Basic yyy`,
/// 这样正好覆盖私有 registry 的各种鉴权方案,模块不去猜 scheme)。
/// 2. **没配凭据** → 透传客户端带来的 `Authorization`。Docker Hub 走的就是这条:
/// 客户端先向 `auth.docker.io` 换一个短期 Bearer token,再拿它来拉镜像;
/// 如果这里把 Authorization 抹成空,`/v2/` 下的镜像一律 401。
/// ⚠️ 但多源路由下这一条**被关掉**(见 [`allow_client_auth`]):
/// 第三方镜像站不认本网关的 Key,透传等于把客户端的凭据泄给池里的镜像站。
/// 3. **但客户端的值若就是本网关的下行 `sk_` Key,一律丢弃**。
///
/// 第 3 条是安全底线:`sk_` 是客户端访问**本网关**的身份(`auth::downstream_key`
/// 认 `Authorization: Bearer` / `x-api-key` 等携带位)。原样透传给上游,
/// 等于把网关自己的钥匙递给上游——对方可拿它反调本网关的其它路由刷额度。
/// ipass 的 LLM 路径在 `docs/llm/UPSTREAM_PROTOCOL_AND_AUTH.md` 记过同一个坑
/// (宽松厂商会把这个缺陷掩盖成 200,换严格厂商才暴露成 401)。
///
/// 判据是**逐字节比较**:只有客户端放在 Authorization 里的值等于本次鉴权用的
/// 那把 `sk_` 才丢弃;换任何别的值(真上游 token)都照传。
///
/// ⚠️ 第 1 条必须**先判**且不能被跳过:本函数只认客户端的头是不够的
/// ——那样「配了凭据的路由」永远下发不了凭据,而且客户端带的是 `sk_` 时会被
/// 第 3 条抹成空(实测症状:管理台配了 token,上游仍收到空 Authorization,
/// 而测试里「未配凭据 → 不下发」那条却通过,很容易误判成上游问题)。
fn auth_header_for(r: *mut ngx_http_request_t, configured: &str, allow_client: bool) -> String {
// 1) 管理台配了凭据 → 用配置值(配置是管理员的显式意图,优先级最高)
let configured = configured.trim();
if !configured.is_empty() {
return configured.to_owned();
}
// 1.5) 多源路由 ⇒ 客户端的凭据一律不下发(不下发任何凭据)
if !allow_client {
return String::new();
}
let raw = match http::header(r, "authorization") {
Some(v) => v.trim().to_owned(),
None => return String::new(),
};
let Some(dk) = ipass_core::auth::downstream_key(r) else {
// 客户端没带网关 Key → 原样透传(如纯 x-api-key 场景)
return raw;
};
let bare = raw
.strip_prefix("Bearer ")
.or_else(|| raw.strip_prefix("bearer "))
.unwrap_or(&raw)
.trim();
if bare == dk { String::new() } else { raw }
}
// ===========================================================================
// 请求级 memo(一个请求只查一次上游表)
// ===========================================================================
/// 一个请求内的选源结果 + 源列表。
///
/// ⚠️ 本体由 **nginx 请求池**分配(`Pool::allocate` 会注册池 cleanup,
/// 负责 drop 内部的 `Vec`/`String`)⇒ 请求结束随池回收,
/// 不跨请求、不泄漏。**不要**改成 `Box`(那会绕过请求池生命周期)。
///
/// ## 取舍:同时持 `up` 与 `sources`(源列表双份常驻)
///
/// `up`(路由级配置)与 `sources`(该路由的有效源列表)在多源下**内容重叠**
/// ——`sources` 就是从 `up` 派生的(`upstreams::effective_sources`),
/// 于是同一个请求里源信息**存了两份**。
///
/// 之所以仍然两份,是为了让「取源」(`picked_source(sources, …)`)与
/// 「取路由级凭据」(`effective_key(up, src)`)都只做**借用**、不重算:
/// 若只留 `sources`,路由级 `key` 就得另找地方存(要么再加一个字段,
/// 要么把 `effective_key` 改成在 `sources` 里翻找——后者会把
/// 「源自己的 key 优先、路由级兜底」的语义藏进数据里,更难读)。
///
/// 代价是每请求多一份 `Vec<CacheSource>` 的常驻内存(源数 × 每源一串
/// URL/key/note,通常几百字节 ⇒ 每请求几百字节)——相对于 nginx 自己
/// 每请求几十次分配,这个量级可接受;换来的是**零重算、零重复查表**。
/// 若将来源数涨到几十个、这份开销变成问题,再考虑让 `sources` 借用
/// `up` 的存储。
struct Memo {
/// 本次请求的路由(自检用:memo 与调用方的路由必须一致)。
route: &'static str,
/// 三个顺位对应的源下标。
slots: [usize; config::MAX_SLOTS],
/// 该路由的**有效源列表**(单源模式下由 base/key 包成一条)。
sources: Vec<CacheSource>,
/// 路由级上游配置(`effective_key` 的回落来源)。
up: upstreams::Decoded,
}
impl Memo {
/// 算一次:查上游表 ⇒ 取有效源 ⇒ 看冷却 ⇒ 选源。
///
/// ⚠️ **本函数是「一个请求只查一次上游表」的唯一入口**(R-T4-2):
/// 查表(`lookup_upstream`)在整个请求路径上只发生在这里一次,
/// 之后 target / host / auth / upstream_key / 四个 alt / pick
/// 全部复用本请求的这一份快照。
fn build(r: *mut ngx_http_request_t, route: &'static str) -> Option<Memo> {
// ⭐ 全请求唯一的一次上游表读取
let up = upstreams::lookup_upstream(route)?;
let sources = upstreams::effective_sources(&up);
let slots = compute_pick(r, route, &sources)?;
Some(Memo {
route,
slots,
sources,
up,
})
}
}
/// 取本请求的 memo(**请求级缓存**:一个请求只查一次上游表)。
///
/// nginx 侧:`ngx_http_get_indexed_variable()` 在 `r->variables[index].valid`
/// 为真时直接返回缓存、不再调 get_handler ⇒ 同一请求里无论求值多少次变量,
/// 都拿到**同一份**源列表与**同一组**槽位(否则会出现「打向 A 源却带 B 源
/// 凭据」的错配)。
///
/// 返回**裸指针**而不是引用:memo 由请求池分配,生命周期 = 本请求,
/// 借用期不该比请求长。
///
/// # Safety
/// `r` 必须是 nginx 传入的有效请求指针。
unsafe fn memo_of(r: *mut ngx_http_request_t) -> Option<*const Memo> {
let idx = CACHE_MEMO_IDX.load(Ordering::Relaxed);
if idx < 0 {
return None;
}
// SAFETY: r 有效;索引在 postconfig 已解析
let v = unsafe { ngx_http_get_indexed_variable(r, idx as ngx_uint_t) };
if v.is_null() || (*v).not_found() != 0 || (*v).data.is_null() {
return None;
}
// ⚠️ 取巧护栏(F6):值槽里存的是**指针**(不是字符串)⇒ `len` 必须恒为 0。
// 若哪天有人给 `$cache_ctx` 加了 `NOCACHEABLE`、或改了 `memo_get` 里的
// `set_len`,nginx 会把值槽当**字符串**处理 ⇒ 指针被当字符串读/拷
// ⇒ **静默**出错(不报错、只是拿到垃圾)。
// `debug_assert!` 在 release 构建里被消掉 ⇒ 运行时零开销。
debug_assert_eq!((*v).len(), 0, "$cache_ctx 的值槽只存指针,len 必须恒为 0");
// 值槽里存的是 `Memo` 的指针(不是字符串)
Some((*v).data as *const Memo)
}
/// 取本请求的 memo,**但只在它的路由与 `route` 一致时**返回。
///
/// ⚠️ **路由不一致 ⇒ 返回 `None`(fail-closed)**:memo 是在 **access 阶段**
/// 建的,数据面在 **content 阶段**用;两者之间理论上 URI 不会变
/// (本仓的 conf 里缓存 location 没有 rewrite / try_files),
/// 但一旦变了(例如将来加了 rewrite),继续用旧 memo 就会
/// 「拿 A 路由的源列表去算 B 路由的 target」⇒ 凭据发错上游。
/// 与其错配,不如**判为未配置**(503 / 变量未找到)——宁可失败也不外泄凭据。
///
/// # Safety
/// `r` 必须是 nginx 传入的有效请求指针。
unsafe fn memo_for(r: *mut ngx_http_request_t, route: &str) -> Option<*const Memo> {
let m = unsafe { memo_of(r) }?;
// SAFETY: 指针指向请求池里的 Memo,请求存活期间有效
if unsafe { (*m).route } != route {
return None;
}
Some(m)
}
/// 槽位 ⇒ 源:**所有变量都经这一个函数取源**。
///
/// ⭐ 这是「打向 A 源就绝不会带 B 源凭据」的**结构性保证**:
/// target / host / upstream_key / auth 全部走 `slot 0`,
/// alt 变量走 `slot 1` / `slot 2` ⇒ 同一个槽位**必然**解析到同一个源。
///
/// 槽位下标来自同一份 `Memo.slots`,源列表来自同一份 `Memo.sources`
/// ⇒ 一个请求内所有变量看到的源集合与槽位完全一致(R-T4-2)。
fn picked_source<'a>(
sources: &'a [CacheSource],
slots: &[usize; config::MAX_SLOTS],
slot: usize,
) -> Option<&'a CacheSource> {
let idx = *slots.get(slot)?;
sources.get(idx)
}
/// 该路由在**本请求内**是否已配置上游。
///
/// 走**请求级 memo** ⇒ 一个请求内对同一路由**只查一次上游表**
/// (R-T4-2):access handler 的「上游是否配置」预检与数据面变量的
/// 取源共用同一份快照 ⇒ 两者永远看到同一个源列表。
///
/// `r` 必须是 nginx 传入的有效请求指针。
pub fn upstream_configured(r: *mut ngx_http_request_t, route: &str) -> bool {
// SAFETY: r 有效;memo 的路由必须与本路由一致
unsafe { memo_for(r, route) }.is_some()
}
/// 取本请求 memo 里的**有效源个数**(log 阶段用)。
///
/// `pub(crate)`:Task 5 的 `handlers::cool_down_failed` 要用它做
/// 「顺位下标 → 源下标」的边界检查。走 memo ⇒ **不再查一次上游表**、
/// **不再 clone 整份源列表**(log 阶段多一次 shm 读 + 逐行解码 +
/// String 分配的纯浪费)。
///
/// ⚠️ memo 里的源列表**就是**本次请求选源时用的那一份 ⇒ 顺位下标
/// (`$cache_pick`)与它是**同一个下标空间** ⇒ 边界检查恒成立
/// (保留检查是为了「越界就跳过」这条防御语义不变)。
///
/// `r` 必须是 nginx 传入的有效请求指针。
pub(crate) fn memo_source_count(r: *mut ngx_http_request_t, route: &str) -> Option<usize> {
// SAFETY: r 有效;memo 的路由必须与本路由一致
let m = unsafe { memo_for(r, route) }?;
// SAFETY: 指针指向请求池里的 Memo,请求存活期间有效
Some(unsafe { (*m).sources.len() })
}
/// 读 `$cache_pick` 的字符串值(空串 = 还没有)。
///
/// ⚠️ **不能用 `ngx_http_get_variable(r, name, 0)`**。
/// nginx 源码 `ngx_http_get_variable()`(src/http/ngx_http_variables.c:689)
/// 内部是 `ngx_hash_find(&cmcf->variables_hash, key, name->data, name->len)`,
/// 而 `ngx_hash_find()`(src/core/ngx_hash.c:23)用 `key % hash->size`
/// **选桶**、再线性探测 ⇒ 传 `key = 0` 等于「只从 0 号桶开始找」,
/// 能不能命中全看变量名恰好落在哪个桶 ⇒ **间歇性读到空串**。
/// `sent_http_*` 前缀变量走的是另一条路径(`prefix_variables` 兜底),
/// 所以它传 0 反而没事——**别把那个写法照抄到这里**。
///
/// 正确做法(与 `handlers.rs` 读 `$upstream_cache_status` 同一套):
/// postconfig 取一次索引,运行时用 `ngx_http_get_indexed_variable()` 读。
///
/// `pub(crate)`:Task 5 的 `handlers::cool_down_failed` 要用它把
/// 「失败顺位」映射回**本次请求实际用的源下标**(R-T5-5:以 `$cache_pick`
/// 为真相源,不另查上游表)。
pub(crate) fn read_pick_var(r: *mut ngx_http_request_t) -> String {
let idx = CACHE_PICK_IDX.load(Ordering::Relaxed);
if idx < 0 {
return String::new();
}
// SAFETY: r 由 nginx 传入且有效;索引在 postconfig 已解析
unsafe { read_indexed_var(r, idx as ngx_uint_t) }
}
/// 按变量索引读字符串值(拿不到返回空串)。
///
/// 与 `handlers.rs::read_indexed` 同义,这里复制一份是为了让 `cache.rs`
/// 不必反向依赖 `handlers`(handlers 已经依赖 cache)。
///
/// # Safety
/// `r` 必须是 nginx 传入的有效请求指针;`idx` 必须是已解析的变量索引。
unsafe fn read_indexed_var(r: *mut ngx_http_request_t, idx: ngx_uint_t) -> String {
// SAFETY: r 有效;idx 来自 postconfig 解析的索引
let v = unsafe { ngx_http_get_indexed_variable(r, idx) };
if v.is_null() || (*v).not_found() != 0 || (*v).data.is_null() {
return String::new();
}
let len = (*v).len() as usize;
if len == 0 {
return String::new();
}
String::from_utf8_lossy(core::slice::from_raw_parts((*v).data, len)).into_owned()
}
/// 算槽位(hash 轮转 + 跳过冷却源)。
///
/// ⚠️ **不查上游表**:`sources` 由调用方给出([`Memo::build`] 已经查过一次),
/// 本函数只做纯计算 ⇒ 一个请求内 `lookup_upstream` 只执行一次(R-T4-2)。
fn compute_pick(
r: *mut ngx_http_request_t,
route: &str,
sources: &[CacheSource],
) -> Option<[usize; config::MAX_SLOTS]> {
if sources.is_empty() {
return None;
}
let cooled = cooled_flags(route, sources.len());
Some(select(sources.len(), hash_of_request(r), &cooled))
}
// ===========================================================================
// 变量求值
// ===========================================================================
/// 全部变量共用一个 get_handler,靠 `var.data`(即 `slot`)分派。
pub extern "C" fn var_get(
r: *mut ngx_http_request_t,
v: *mut ngx_http_variable_value_t,
data: usize,
) -> ngx_int_t {
// SAFETY: r/v 由 nginx 传入且有效;本函数只读请求结构、只写 v
unsafe {
// 内部变量:值槽里存的是 memo 指针(不是字符串)
if data == VAR_MEMO {
return memo_get(r, v);
}
let resolved = (|| -> Option<String> {
let uri = http::uri(r);
let (route, tail) = resolve_route(&uri)?;
// ⭐ 请求级 memo:一个请求内只查一次上游表,且所有变量共用
// 同一份源列表与同一组槽位(否则会出现「打向 A 源却带 B 源
// 凭据」的错配)。
// ⚠️ `memo_for` 会**核对路由**:memo 是 access 阶段建的,
// 这里(content 阶段)若 URI 变了导致路由不同 ⇒ 判为
// 「未配置」⇒ 变量未找到(500),**绝不**拿旧路由的源
// 去算新路由的 target(fail-closed,见 `memo_for` 注释)。
// SAFETY: r 有效
let memo = memo_for(r, route)?;
// SAFETY: 指针指向请求池里的 Memo,请求存活期间有效
let memo = &*memo;
let up = &memo.up;
let sources = &memo.sources;
let slots = memo.slots;
// 是否允许把客户端凭据转发给上游(多源 ⇒ 否,docker ⇒ 是)
let allow_client = allow_client_auth(route, sources.len());
Some(match data {
VAR_TARGET => {
let src = picked_source(sources, &slots, 0)?;
let args = http::args_raw(r);
let args = core::str::from_utf8(&args).unwrap_or("");
build_target(route, &tail, &src.url, args)
}
VAR_TARGET_ALT | VAR_TARGET_ALT2 => {
let slot = if data == VAR_TARGET_ALT { 1 } else { 2 };
let src = picked_source(sources, &slots, slot)?;
let args = http::args_raw(r);
let args = core::str::from_utf8(&args).unwrap_or("");
build_target(route, &tail, &src.url, args)
}
// ⚠️ Host 必须跟着**被选中源**走(多源下上游按 Host 路由,
// 留在路由级 base 上会打错后端或被拒)。
VAR_HOST => {
let src = picked_source(sources, &slots, 0)?;
host_of(&src.url).to_owned()
}
// ⚠️ 同样跟着被选中源走(生产 conf 的 `/_cache_test/` 用它当
// `Authorization` 头)。
VAR_UPSTREAM_KEY => {
let src = picked_source(sources, &slots, 0)?;
effective_key(up, src)
}
VAR_AUTH => {
let src = picked_source(sources, &slots, 0)?;
auth_header_for(r, &effective_key(up, src), allow_client)
}
VAR_AUTH_ALT | VAR_AUTH_ALT2 => {
let slot = if data == VAR_AUTH_ALT { 1 } else { 2 };
let src = picked_source(sources, &slots, slot)?;
auth_header_for(r, &effective_key(up, src), allow_client)
}
// 选源结果本身:请求内缓存(见 `add_var` 的说明)
VAR_PICK => encode_pick(&slots),
VAR_ECO => config::eco_of_route(route).to_owned(),
// 缓存键必须含 query(完整资源身份):npm 的 `?write=true`、
// docker 的 `?ns=`、go 的 `?go-get=1`、cargo 的 `?archive=tar.gz`
// 都靠 query 区分实体。而**变量式 proxy_pass 不把 query 写进
// `$uri`**,只看 `$uri` 会让「带 query 的请求」命中「不带 query
// 的缓存」,把错的制品发出去(实测:`/go/@v/list?x=1` 命中了
// `/go/@v/list` 的缓存体,且完全没有回源)。
VAR_KEY => {
let args = http::args_raw(r);
match core::str::from_utf8(&args) {
Ok(a) if !a.is_empty() => format!("{route}:{uri}?{a}"),
_ => format!("{route}:{uri}"),
}
}
_ => return None,
})
})();
match resolved {
Some(value) => set_value(r, v, &value, data == VAR_PICK),
None => {
// 未配置上游 / 非受管制路由:把变量置为「未找到」。
// nginx 的变量式 proxy_pass 拿到空值会报 500(no host in upstream),
// 所以 access handler 必须先一步用 503 拦掉,别让请求走到这里。
(*v).set_not_found(1);
(*v).set_valid(0);
Status::NGX_ERROR.into()
}
}
}
}
/// 内部变量 `$cache_ctx` 的 get_handler:算一次 memo,把**指针**写进值槽。
///
/// ⚠️ 值槽里存的是**指针**(不是字符串)⇒ `len` 恒为 0:万一有人误在 conf
/// 里引用 `$cache_ctx`,nginx 只会拷到 0 字节(不会把指针/结构体泄出去)。
/// 正常路径下只有本模块自己读这个槽(见 [`memo_of`])。
///
/// # Safety
/// `r`/`v` 必须由 nginx 传入且在本调用期间有效。
unsafe fn memo_get(r: *mut ngx_http_request_t, v: *mut ngx_http_variable_value_t) -> ngx_int_t {
let uri = http::uri(r);
let Some((route, _tail)) = resolve_route(&uri) else {
return memo_not_found(v);
};
let Some(memo) = Memo::build(r, route) else {
return memo_not_found(v);
};
// 请求池分配;`Pool::allocate` 注册池 cleanup ⇒ 请求结束自动 drop
// 内部的 Vec/String ⇒ 不泄漏、不跨请求。
let pool = Pool::from_ngx_pool((*r).pool);
let p = pool.allocate(memo);
if p.is_null() {
return memo_not_found(v);
}
// ⚠️ 取巧护栏(F6):请求池分配 ⇒ 指针必须对齐到 `Memo`。
// 不对齐 ⇒ `&*memo` 就是未定义行为(且多半不崩 ⇒ 更难查)。
debug_assert_eq!(
p as usize % core::mem::align_of::<Memo>(),
0,
"请求池分配的 Memo 指针必须对齐"
);
(*v).data = p as *mut u8;
(*v).set_len(0);
(*v).set_valid(1);
(*v).set_no_cacheable(0);
(*v).set_not_found(0);
Status::NGX_OK.into()
}
/// memo 算不出来(路由未配置上游 / 分配失败)⇒ 标记「未找到」。
///
/// # Safety
/// `v` 必须由 nginx 传入且在本调用期间有效。
unsafe fn memo_not_found(v: *mut ngx_http_variable_value_t) -> ngx_int_t {
(*v).set_not_found(1);
(*v).set_valid(0);
Status::NGX_ERROR.into()
}
/// 把字符串写进 nginx 变量值(数据从请求内存池分配,生命周期由请求保证)。
///
/// `cacheable = false` ⇒ 值标记为「不可缓存」⇒ nginx 每次读都重算
/// (上游配置中途变更对本请求可见)。
/// `cacheable = true` ⇒ 值在本请求内缓存(`$cache_pick` 用)。
///
/// # Safety
/// `r` / `v` 必须由 nginx 传入且在本调用期间有效。
unsafe fn set_value(
r: *mut ngx_http_request_t,
v: *mut ngx_http_variable_value_t,
value: &str,
cacheable: bool,
) -> ngx_int_t {
let pool = Pool::from_ngx_pool((*r).pool);
let bytes = value.as_bytes();
let data = pool.alloc(bytes.len()) as *mut u8;
if data.is_null() {
(*v).set_not_found(1);
return Status::NGX_ERROR.into();
}
core::ptr::copy_nonoverlapping(bytes.as_ptr(), data, bytes.len());
(*v).data = data;
(*v).set_len(bytes.len() as _);
(*v).set_valid(1);
(*v).set_no_cacheable(if cacheable { 0 } else { 1 });
(*v).set_not_found(0);
Status::NGX_OK.into()
}
/// 头字段用的变量名清单——管理台与文档引用它,避免两处写不一致。
pub const VARIABLE_DOCS: &[(&str, &str)] = &[
("$cache_target", "上游完整 URL(proxy_pass)= 本次被选中源的那一条"),
(
"$cache_host",
"上游 Host 头 = 本次被选中源的那个(多源下必须跟着选源走)",
),
(
"$cache_upstream_key",
"本次被选中源用的上游凭据原值(源自己的优先,空则回落路由级;未配置为空)",
),
(
"$cache_auth",
"实际下发的 Authorization:配了凭据就用它,没配就透传客户端值,但会剔除下游 sk_ 自身(多源路由不透传客户端凭据)",
),
("$cache_eco", "生态名"),
(
"$cache_key",
"缓存键(proxy_cache_key)= <route>:<uri>[?args],含 query、不含任何下游凭据(全站共享)",
),
("$cache_target_alt", "备选 1(第二个顺位源)的上游完整 URL"),
(
"$cache_target_alt2",
"备选 2(第三个顺位源)的上游完整 URL(源数 < 3 时与 alt 同源)",
),
("$cache_auth_alt", "备选 1 的 Authorization"),
(
"$cache_auth_alt2",
"备选 2 的 Authorization(源数 < 3 时与 alt 同源)",
),
(
"$cache_pick",
"本次请求的选源结果(下标三元组,如 2|0|1;请求内一致)",
),
];
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn fnv1a_is_stable_and_spread() {
assert_eq!(fnv1a(b"abc"), fnv1a(b"abc"));
assert_ne!(fnv1a(b"abc"), fnv1a(b"abd"));
}
#[test]
fn select_starts_at_hash_position() {
// 4 个源全部健康:起点 = hash % 4 = 2
assert_eq!(select(4, 2, &[false; 4]), [2, 3, 0]);
}
#[test]
fn select_moves_cooled_sources_to_the_tail() {
// 源 1 在冷却:健康源 0/2/3 排前,冷却源 1 排后(不丢弃)
assert_eq!(select(4, 0, &[false, true, false, false]), [0, 2, 3]);
}
#[test]
fn select_always_returns_three_slots() {
assert_eq!(select(1, 0, &[false]), [0, 0, 0]);
assert_eq!(select(2, 1, &[false, false]), [1, 0, 0]);
assert_eq!(select(2, 1, &[true, true]), [1, 0, 0]);
}
#[test]
fn select_with_zero_sources_is_safe() {
assert_eq!(select(0, 0, &[]), [0, 0, 0]);
}
#[test]
fn select_tolerates_cooled_len_mismatch() {
// cooled 比源数短:缺失的按「不冷却」处理,不 panic
assert_eq!(select(3, 0, &[false, true]), [0, 2, 1]);
// cooled 比源数长:多出来的被忽略,不 panic
assert_eq!(select(2, 0, &[false, true, false]), [0, 1, 1]);
}
#[test]
fn select_keeps_cooled_source_when_only_two_sources() {
// 「挪尾」而不是「丢弃」:源 0 健康排头,源 1 被冷却但仍在链上
assert_eq!(select(2, 0, &[false, true]), [0, 1, 1]);
}
#[test]
fn pick_encoding_roundtrip() {
let slots = [2usize, 0, 1];
assert_eq!(encode_pick(&slots), "2|0|1");
assert_eq!(parse_pick("2|0|1"), Some([2usize, 0, 1]));
assert_eq!(parse_pick(""), None);
assert_eq!(parse_pick("x"), None);
}
#[test]
fn source_credential_falls_back_to_route_key() {
let up = crate::upstreams::decode("https://a\nROUTEKEY\nproxy\nv2\nhttps://b\n\n");
let srcs = crate::upstreams::effective_sources(&up);
assert_eq!(srcs[0].key, ""); // 源没配凭据
assert_eq!(effective_key(&up, &srcs[0]), "ROUTEKEY");
}
// F1:路由级 key 会被**复制给每一个没配自己凭据的源** —— 多源路由
// 不应配路由级 key(由 Task 6 强制)。这里把**当前语义**钉住,
// 免得 Task 6 改语义时无声漂移。
#[test]
fn route_level_key_is_copied_to_every_source_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");
// 源自己配了凭据 ⇒ 用自己的,不受路由级影响
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-T5-4)
// -----------------------------------------------------------------
#[test]
fn failed_slots_all_failed_cools_every_slot() {
assert_eq!(failed_slots(true, None), vec![0, 1, 2]);
}
#[test]
fn failed_slots_some_zero_cools_only_first_slot() {
assert_eq!(failed_slots(false, Some(0)), vec![0]);
}
#[test]
fn failed_slots_some_one_cools_the_whole_prefix() {
// ⚠️ 整段 0..=k(不是只冷却第 k 跳):走到第 1 跳说明第 0 跳也失败过
assert_eq!(failed_slots(false, Some(1)), vec![0, 1]);
}
#[test]
fn failed_slots_none_cools_nothing() {
assert_eq!(failed_slots(false, None), Vec::<usize>::new());
}
#[test]
fn failed_slots_clamps_out_of_range_slot() {
// 响应头是外部可控的 ⇒ 越界顺位必须被裁到 MAX_SLOTS-1
// (否则一个恶意头就能让本函数分配天文大小的 Vec)
assert_eq!(failed_slots(false, Some(99)), vec![0, 1, 2]);
assert_eq!(failed_slots(false, Some(usize::MAX)), vec![0, 1, 2]);
}
#[test]
fn client_auth_not_forwarded_on_multi_source_routes_except_docker() {
// 多源 + 没有任何配置凭据 ⇒ 不下发客户端凭据(R21/R33)
assert!(!allow_client_auth("go", 4));
assert!(!allow_client_auth("pypi", 5));
// 单源 ⇒ 保持今天的透传语义(向后兼容的硬约束)
assert!(allow_client_auth("go", 1));
// docker ⇒ 例外,永远转发(否则 docker 客户端陷入 401 挑战死循环)
assert!(allow_client_auth("docker", 2));
}
// -----------------------------------------------------------------
// 请求级 memo 的不变量(R-T4-2)
// -----------------------------------------------------------------
fn src(url: &str, key: &str) -> CacheSource {
CacheSource {
id: String::new(),
url: url.to_owned(),
key: key.to_owned(),
note: String::new(),
}
}
#[test]
fn picked_source_resolves_slot_through_shared_slots() {
// 三个源,槽位 [2, 0, 1](与简报的 encode_pick 例子一致)
let sources = vec![
src("https://a", "KA"),
src("https://b", "KB"),
src("https://c", "KC"),
];
let slots = [2usize, 0, 1];
// 每个槽位解析到哪个源,只由**同一份** slots + sources 决定
assert_eq!(picked_source(&sources, &slots, 0).unwrap().url, "https://c");
assert_eq!(picked_source(&sources, &slots, 1).unwrap().url, "https://a");
assert_eq!(picked_source(&sources, &slots, 2).unwrap().url, "https://b");
}
#[test]
fn target_and_auth_always_resolve_to_the_same_source() {
// ⭐ R-T4-2 的核心不变量:同一个槽位**必须**解析到同一个源。
// 凭据(effective_key)取自**同一个** src ⇒ 不可能「打向 A 源
// 却带 B 源凭据」。
let sources = vec![
src("https://a", "KA"),
src("https://b", "KB"),
src("https://c", "KC"),
];
let up = crate::upstreams::decode("https://route-base\nROUTEKEY\nproxy");
for slots in [[0usize, 1, 2], [2, 0, 1], [1, 2, 0]] {
for slot in 0..config::MAX_SLOTS {
let s = picked_source(&sources, &slots, slot).unwrap();
// target 用的 url 与 auth 用的凭据来自**同一次**解析
assert_eq!(s.url, picked_source(&sources, &slots, slot).unwrap().url);
assert_eq!(
effective_key(&up, s),
if s.key.is_empty() { "ROUTEKEY" } else { &s.key }
);
}
}
}
#[test]
fn picked_source_is_none_for_out_of_range_slot_or_source() {
let sources = vec![src("https://a", "K")];
// 槽位越界 ⇒ None(fail-closed:变量求值失败 ⇒ nginx 报变量未找到)
assert!(picked_source(&sources, &[0, 1, 2], 1).is_none());
// 源列表为空 ⇒ None
assert!(picked_source(&[], &[0, 1, 2], 0).is_none());
}
}