//! 缓存插件的 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` | `:` | `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:`),改配置立即生效,无需改 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`:缓存键(`:`) 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 = 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::().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 { 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::<下标>`。 /// ⇒ 管理员在管理台**重排 / 增删源**之后,旧的 `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) -> Vec { 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`、`String::extend_from_slice` 只吃 // `&str` ⇒ 原稿这段过不了编译。这里改成字节缓冲,语义等价(拼 // `uri?args` 后整体散列)。 let mut buf: Vec = 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` 的常驻内存(源数 × 每源一串 /// URL/key/note,通常几百字节 ⇒ 每请求几百字节)——相对于 nginx 自己 /// 每请求几十次分配,这个量级可接受;换来的是**零重算、零重复查表**。 /// 若将来源数涨到几十个、这份开销变成问题,再考虑让 `sources` 借用 /// `up` 的存储。 struct Memo { /// 本次请求的路由(自检用:memo 与调用方的路由必须一致)。 route: &'static str, /// 三个顺位对应的源下标。 slots: [usize; config::MAX_SLOTS], /// 该路由的**有效源列表**(单源模式下由 base/key 包成一条)。 sources: Vec, /// 路由级上游配置(`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 { // ⭐ 全请求唯一的一次上游表读取 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 { // 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 { 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::(), 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)= :[?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::::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()); } }