From 34eb8c7d0bd7b0a195a93e67e69ff5d850fcc412 Mon Sep 17 00:00:00 2001 From: admin Date: Fri, 30 Oct 2026 20:07:53 +0800 Subject: [PATCH] =?UTF-8?q?feat(cache):=20=E4=B8=89=E6=A1=A3=E4=B8=8A?= =?UTF-8?q?=E6=B8=B8=E7=9B=AE=E6=A0=87=E5=8F=98=E9=87=8F=20+=20=E8=AF=B7?= =?UTF-8?q?=E6=B1=82=E5=86=85=E4=B8=80=E8=87=B4=E7=9A=84=E9=80=89=E6=BA=90?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新增 $cache_target_alt/_alt2、$cache_auth_alt/_alt2 与内部 $cache_pick。 $cache_pick 请求内缓存 ⇒ target/auth/host 必定同源; $cache_pick 按变量索引读(postconfig 取索引),不用名字查找。 单源配置下行为与旧版逐字节相同。 --- src/cache.rs | 678 +++++++++++++++++++++++++++++++++++++++++++++--- src/handlers.rs | 33 ++- 2 files changed, 672 insertions(+), 39 deletions(-) diff --git a/src/cache.rs b/src/cache.rs index 9732156..0f2a7ff 100644 --- a/src/cache.rs +++ b/src/cache.rs @@ -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` | `:` | `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_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::().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, + /// 路由级上游配置(`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; + } + // 值槽里存的是 `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 { 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)= :[?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()); + } } diff --git a/src/handlers.rs b/src/handlers.rs index f3fb8b1..5c1a1ed 100644 --- a/src/handlers.rs +++ b/src/handlers.rs @@ -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)