换源链在命名 location 里写下 X-Cache-Failed-Slot 响应头, log 阶段据此把失败的源踢出轮转;最终 502/504 时全部冷却(兜底)。
1137 lines
52 KiB
Rust
1137 lines
52 KiB
Rust
//! 缓存插件的 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()
|
||
}
|
||
|
||
/// 读 `$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());
|
||
}
|
||
}
|