feat(cache): 三档上游目标变量 + 请求内一致的选源

新增 $cache_target_alt/_alt2、$cache_auth_alt/_alt2 与内部 $cache_pick。
$cache_pick 请求内缓存 ⇒ target/auth/host 必定同源;
$cache_pick 按变量索引读(postconfig 取索引),不用名字查找。
单源配置下行为与旧版逐字节相同。
This commit is contained in:
admin committed 2026-10-30 20:07:53 +08:00
1 parent f412ec3dcc
commit 34eb8c7d0b
2 files changed
+672 -39

No files matched your search

+642 -36
View File
@@ -1,25 +1,47 @@
//! 缓存插件的 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_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_conf_t, ngx_http_add_variable,
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;
@@ -28,6 +50,7 @@ use ipass_core::{http, state, util};
use crate::config;
use crate::handlers;
use crate::models::CacheSource;
use crate::upstreams;
// ===========================================================================
@@ -46,6 +69,59 @@ pub const VAR_ECO: usize = 4;
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 退出。
///
@@ -58,13 +134,28 @@ pub unsafe fn preconfig(cf: *mut ngx_conf_t) -> bool {
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)
&& add_var(cf, &raw mut host, VAR_HOST)
&& add_var(cf, &raw mut ukey, VAR_UPSTREAM_KEY)
&& add_var(cf, &raw mut eco, VAR_ECO)
&& add_var(cf, &raw mut ckey, VAR_KEY)
&& add_var(cf, &raw mut auth, VAR_AUTH)
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)
}
}
@@ -73,15 +164,19 @@ pub unsafe fn preconfig(cf: *mut ngx_conf_t) -> bool {
/// `NOCACHEABLE`:本变量是「读时现算」,若被 nginx 缓存进 `r->variables`,
/// 同一请求多次求值(`proxy_pass` 一次、`proxy_set_header` 再读)会拿到
/// 首次结果——对上游配置**中途变更**的场景会读到旧值,故标记不可缓存。
unsafe fn add_var(cf: *mut ngx_conf_t, name: *mut ngx_str_t, slot: usize) -> bool {
// SAFETY: cf 由 nginx 传入;name 指向调用方栈上的 ngx_str_t,注册时被拷贝
let var = unsafe {
ngx_http_add_variable(
cf,
name,
(NGX_HTTP_VAR_CHANGEABLE | NGX_HTTP_VAR_NOCACHEABLE) as ngx_uint_t,
)
///
/// ⚠️ 例外:`$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;
}
@@ -94,6 +189,30 @@ unsafe fn add_var(cf: *mut ngx_conf_t, name: *mut ngx_str_t, slot: usize) -> boo
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
}
// ===========================================================================
// 求值
// ===========================================================================
@@ -157,8 +276,11 @@ pub fn fnv1a(data: &[u8]) -> u64 {
///
/// 规则:
/// 1. 起点 = `hash % n`,按顺位轮转;
/// 2. **冷却中的源排到队尾**(不丢弃)——冷却是降权不是禁用:
/// 池里只剩冷却源时仍要能出请求(宁可重试也不 500);
/// 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] {
@@ -187,6 +309,63 @@ pub fn select(n: usize, hash: u64, cooled: &[bool]) -> [usize; config::MAX_SLOTS
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`。
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` 自动过期 ⇒ 这里只需查「还活着没有」。
@@ -244,7 +423,9 @@ pub fn build_target(route: &str, tail: &str, base: &str, args: &str) -> String {
t
}
/// 决定下发给上游的 `Authorization` 头值。
/// 该源实际下发的 `Authorization`(空 = 不下发任何凭据)。
///
/// `allow_client = false` ⇒ **只认配置的凭据**,客户端带什么都不转发。
///
/// `configured` 是本路由在管理台配的上游凭据(原值,管理员自己写全
/// `Bearer xxx` / `Basic yyy`)。
@@ -256,6 +437,8 @@ pub fn build_target(route: &str, tail: &str, base: &str, args: &str) -> String {
/// 2. **没配凭据** → 透传客户端带来的 `Authorization`。Docker Hub 走的就是这条:
/// 客户端先向 `auth.docker.io` 换一个短期 Bearer token,再拿它来拉镜像;
/// 如果这里把 Authorization 抹成空,`/v2/` 下的镜像一律 401。
/// ⚠️ 但多源路由下这一条**被关掉**(见 [`allow_client_auth`]):
/// 第三方镜像站不认本网关的 Key,透传等于把客户端的凭据泄给池里的镜像站。
/// 3. **但客户端的值若就是本网关的下行 `sk_` Key,一律丢弃**。
///
/// 第 3 条是安全底线:`sk_` 是客户端访问**本网关**的身份(`auth::downstream_key`
@@ -271,12 +454,16 @@ pub fn build_target(route: &str, tail: &str, base: &str, args: &str) -> String {
/// ——那样「配了凭据的路由」永远下发不了凭据,而且客户端带的是 `sk_` 时会被
/// 第 3 条抹成空(实测症状:管理台配了 token,上游仍收到空 Authorization,
/// 而测试里「未配凭据 → 不下发」那条却通过,很容易误判成上游问题)。
fn auth_header(r: *mut ngx_http_request_t, configured: &str) -> String {
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(),
@@ -293,7 +480,209 @@ fn auth_header(r: *mut ngx_http_request_t, configured: &str) -> String {
if bare == dk { String::new() } else { raw }
}
/// 六个变量共用一个 get_handler,靠 `var.data`(即 `slot`)分派。
/// 兼容旧调用点(单源语义:允许转发客户端凭据)。
///
/// 保留它是为了**语义不变**:单源路由今天的透传行为一字不改。
pub fn auth_header(r: *mut ngx_http_request_t, configured: &str) -> String {
auth_header_for(r, configured, true)
}
// ===========================================================================
// 请求级 memo(一个请求只查一次上游表)
// ===========================================================================
/// 一个请求内的选源结果 + 源列表。
///
/// ⚠️ 本体由 **nginx 请求池**分配(`Pool::allocate` 会注册池 cleanup,
/// 负责 drop 内部的 `Vec`/`String`)⇒ 请求结束随池回收,
/// 不跨请求、不泄漏。**不要**改成 `Box`(那会绕过请求池生命周期)。
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;
}
// 值槽里存的是 `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 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))
}
/// 取本次请求的选源结果(**请求级 memo**)。
///
/// 首选 memo(与 target/auth/host 同源同槽位);memo 不可用时读**已缓存**的
/// `$cache_pick`(同一请求内 nginx 只算一次)——**不再自己查上游表**。
pub fn pick_of(r: *mut ngx_http_request_t, route: &str) -> Option<[usize; config::MAX_SLOTS]> {
// 首选:请求级 memo(与 target/auth/host 同源同槽位)
// SAFETY: r 有效;memo 的路由必须与本路由一致(不一致 ⇒ fail-closed)
if let Some(memo) = unsafe { memo_for(r, route) } {
// SAFETY: 指针指向请求池里的 Memo,请求存活期间有效
let m = unsafe { &*memo };
return Some(m.slots);
}
// 兜底:memo 不可用(索引未解析 / 上游未配置)⇒ 读已缓存的 $cache_pick
let raw = read_pick_var(r);
parse_pick(&raw)
}
// ===========================================================================
// 变量求值
// ===========================================================================
/// 全部变量共用一个 get_handler,靠 `var.data`(即 `slot`)分派。
pub extern "C" fn var_get(
r: *mut ngx_http_request_t,
v: *mut ngx_http_variable_value_t,
@@ -301,19 +690,66 @@ pub extern "C" fn var_get(
) -> 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)?;
let (base, key, _mode) = upstreams::lookup(route)?;
// ⭐ 请求级 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, &base, args)
build_target(route, &tail, &src.url, args)
}
VAR_HOST => host_of(&base).to_owned(),
VAR_UPSTREAM_KEY => key,
VAR_AUTH => auth_header(r, &key),
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`
@@ -333,7 +769,7 @@ pub extern "C" fn var_get(
})();
match resolved {
Some(value) => set_value(r, v, &value),
Some(value) => set_value(r, v, &value, data == VAR_PICK),
None => {
// 未配置上游 / 非受管制路由:把变量置为「未找到」。
// nginx 的变量式 proxy_pass 拿到空值会报 500(no host in upstream),
@@ -346,14 +782,60 @@ pub extern "C" fn var_get(
}
}
/// 内部变量 `$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);
}
(*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();
@@ -366,25 +848,45 @@ unsafe fn set_value(
(*v).data = data;
(*v).set_len(bytes.len() as _);
(*v).set_valid(1);
(*v).set_no_cacheable(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_target", "上游完整 URL(proxy_pass)= 本次被选中源的那一条"),
(
"$cache_host",
"上游 Host 头 = 本次被选中源的那个(多源下必须跟着选源走)",
),
(
"$cache_upstream_key",
"本次被选中源用的上游凭据原值(源自己的优先,空则回落路由级;未配置为空)",
),
(
"$cache_auth",
"实际下发的 Authorization:配了凭据就用它,没配就透传客户端值,但会剔除下游 sk_ 自身",
"实际下发的 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)]
@@ -420,4 +922,108 @@ mod tests {
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");
}
#[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());
}
}
+30 -3
View File
@@ -32,9 +32,9 @@ use ngx::http::{HTTPStatus, HttpPhase, HttpRequestHandler, Request};
use ipass_core::{auth, http, plugin_registry, util};
use crate::cache;
use crate::config;
use crate::stats;
use crate::upstreams;
/// `$upstream_cache_status` 的变量索引(postconfig 解析一次,log 阶段复用)
static CACHE_STATUS_IDX: AtomicIsize = AtomicIsize::new(-1);
@@ -43,7 +43,7 @@ static SCHEME_IDX: AtomicIsize = AtomicIsize::new(-1);
/// `$request_id` 的变量索引(选源散列用)。**可选**:拿不到就退化为 URI 散列。
static REQUEST_ID_IDX: AtomicIsize = AtomicIsize::new(-1);
/// postconfiguration:预取两个变量索引。失败返回 false,gateway 会 EMERG 退出。
/// postconfiguration:预取三个变量索引。失败返回 false,gateway 会 EMERG 退出。
///
/// 为什么在 postconfig 而不是 preconfig:`$scheme` 是 core 模块的内建变量,
/// 本模块的 preconfig 早于变量全部注册完成,取 index 可能失败;postconfig
@@ -76,6 +76,25 @@ pub fn prefetch_indexes(cf: *mut ngx_conf_t) -> bool {
let i3 = unsafe { ngx_http_get_variable_index(cf, &mut rid) };
REQUEST_ID_IDX.store(i3 as isize, Ordering::Relaxed);
// `$cache_pick`(本插件自己注册的变量)——运行时按**索引**读,
// 不用 ngx_http_get_variable 的名字查找(那个 API 的 key 是哈希桶号,
// 传 0 会间歇性查不中,详见 cache::read_pick_var 的注释)。
let mut cp = ngx_str_t {
len: "cache_pick".len() as usize,
data: b"cache_pick\0".as_ptr() as *mut u8,
};
// SAFETY: cf 由 nginx 传入且有效;ngx_str_t 指向栈上合法内存
let i4 = unsafe { ngx_http_get_variable_index(cf, &mut cp) };
if i4 < 0 {
return false;
}
crate::cache::set_pick_index(i4 as isize);
// 内部变量 `$cache_ctx`(请求级 memo 的载体)——同样按索引读。
if !crate::cache::prefetch_memo_index(cf) {
return false;
}
true
}
@@ -142,7 +161,15 @@ impl HttpRequestHandler for CacheAccessHandler {
// 上游未配置:**必须在这里拦**。否则变量式 proxy_pass 拿到空
// `$cache_target`,nginx 会报 500 `no host in upstream`,
// 排障时会误以为是缓存本身坏了。
if upstreams::lookup(route).is_none() {
//
// ⚠️ 走**请求级 memo**(`cache::upstream_configured`)而不是
// `upstreams::lookup()`:后者会**再查一次上游表** ⇒
// 一个请求查两次表(access 一次 + 变量求值一次),
// 且两次快照可能不同(中间配置被改)⇒ 判「未配置」与
// 实际选中的源对不上。
// memo 在这里**第一次**被建立(查表发生在此),
// 后面数据面变量求值时**复用同一份快照**(R-T4-2)。
if !cache::upstream_configured(r, route) {
util::log_warn(&format!(
"[cache] 路由 {route} 未配置上游,拒绝 {uri}(client={})",
http::remote_addr(r)