Files
ipass-plugin-cache/src/cache.rs
T
admin 34eb8c7d0b feat(cache): 三档上游目标变量 + 请求内一致的选源
新增 $cache_target_alt/_alt2、$cache_auth_alt/_alt2 与内部 $cache_pick。
$cache_pick 请求内缓存 ⇒ target/auth/host 必定同源;
$cache_pick 按变量索引读(postconfig 取索引),不用名字查找。
单源配置下行为与旧版逐字节相同。
2026-10-30 20:07:53 +08:00

1030 lines
46 KiB
Rust
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
//! 缓存插件的 nginx 变量层:把「上游表 + 请求 URI」算成 `proxy_pass` 能用的值。
//!
//! 注册**只读**变量(求值时算,模块从不主动写):
//!
//! | 变量 | 值 | 谁用 |
//! | --- | --- | --- |
//! | `$cache_target` | **被选中源**的 `base + 上游路径前缀 + 尾部 [+ ?query]` | `proxy_pass $cache_target` |
//! | `$cache_host` | **被选中源**的 Host(含端口) | `proxy_set_header Host $cache_host` |
//! | `$cache_upstream_key` | **被选中源**用的上游凭据**原值**(未配置为空) | 排障/日志 |
//! | `$cache_auth` | **被选中源****实际下发**的 Authorization 值(含防 `sk_` 泄漏规则) | `proxy_set_header Authorization $cache_auth` |
//! | `$cache_eco` | 生态名(`go` / `cargo` / …) | 日志与排障 |
//! | `$cache_key` | `<route>:<uri>` | `proxy_cache_key`(显式给定,不依赖 `$proxy_host`) |
//! | `$cache_target_alt` / `$cache_target_alt2` | 备选 1 / 备选 2 的完整上游 URL | 多跳回退 |
//! | `$cache_auth_alt` / `$cache_auth_alt2` | 备选 1 / 备选 2 的 Authorization | 多跳回退 |
//! | `$cache_pick` | 本请求的选源结果(`"i0\|i1\|i2"`,如 `"2\|0\|1"`) | 日志/排障 |
//!
//! ⚠️ `$proxy_host` 在**变量式 `proxy_pass`** 下不可靠,所以 `proxy_cache_key`
//! 必须显式指定;用本变量即可(同 zone 内 URI 唯一,跨 zone 天然隔离)。
//!
//! 这就是「UI 配上游 + 动态注入」的落点:上游地址与凭据都来自共享内存
//! (`cx:<route>`),改配置立即生效,无需改 nginx conf、无需 reload。
//!
//! ## 请求级 memo(一个请求只查一次上游表)
//!
//! 多源下同一请求会求值 `$cache_target` / `$cache_host` / `$cache_auth` /
//! `$cache_upstream_key` / 四个 alt / `$cache_pick` 等**十个**变量;每次都
//! `lookup_upstream()` 就是每次都把整份上游 payload 拷一遍 + 逐行解码 +
//! 再克隆一份源列表(单次 ≈ 25 次堆分配 ⇒ 一个请求 ≈ 200 次额外分配,
//! 而 nginx 自己每请求也就几十次分配)。
//!
//! ⇒ 用一个**内部**变量 `$cache_ctx` 承载请求级 memo:它的值槽里存的不是
//! 字符串,而是**指向请求内存池里 `Memo` 的指针**。nginx 侧
//! `ngx_http_get_indexed_variable()`(`ngx_http_variables.c`)在
//! `r->variables[index].valid` 为真时**直接返回、不再调 get_handler**
//! ⇒ 天然是请求级缓存;`Memo` 本体由请求池分配(`Pool::allocate` 注册池
//! cleanup,负责 drop 内部的 `Vec`/`String`)⇒ 请求结束随池回收,
//! 不跨请求、不泄漏。
use core::sync::atomic::{AtomicIsize, Ordering};
use ngx::core::{Pool, Status};
use ngx::ffi::{
NGX_HTTP_VAR_CHANGEABLE, NGX_HTTP_VAR_NOCACHEABLE, NGX_HTTP_VAR_NOHASH, ngx_conf_t,
ngx_http_add_variable, ngx_http_get_indexed_variable, ngx_http_get_variable_index,
ngx_http_request_t, ngx_http_variable_value_t, ngx_int_t, ngx_str_t, ngx_uint_t,
};
use ngx::ngx_string;
use ipass_core::{http, state, util};
use crate::config;
use crate::handlers;
use crate::models::CacheSource;
use crate::upstreams;
// ===========================================================================
// 变量分派标记
// ===========================================================================
/// `$cache_target`:完整上游 URL
pub const VAR_TARGET: usize = 1;
/// `$cache_host`:上游 Host 头
pub const VAR_HOST: usize = 2;
/// `$cache_upstream_key`:上游凭据(空 = 不下发鉴权头)
pub const VAR_UPSTREAM_KEY: usize = 3;
/// `$cache_eco`:生态名
pub const VAR_ECO: usize = 4;
/// `$cache_key`:缓存键(`<route>:<uri>`)
pub const VAR_KEY: usize = 5;
/// `$cache_auth`:**实际下发给上游**的 `Authorization` 头值(含防泄漏规则)
pub const VAR_AUTH: usize = 6;
/// `$cache_target_alt`:备选 1 的完整上游 URL
pub const VAR_TARGET_ALT: usize = 7;
/// `$cache_target_alt2`:备选 2 的完整上游 URL
///
/// ⚠️ **源数 < 3 的路由上 alt2 与 alt 指向同一个源** ⇒ **conf 不得对
/// 源数 < 3 的路由使用 alt2**;跳数按 `min(3, 该路由源数)` 裁
/// (cargo-dl 的池是 2 个源 ⇒ 2 跳;docker 的池 2026-10-30 起只剩
/// 1 个源 ⇒ 1 跳)。
pub const VAR_TARGET_ALT2: usize = 8;
/// `$cache_auth_alt`:备选 1 的 Authorization
pub const VAR_AUTH_ALT: usize = 9;
/// `$cache_auth_alt2`:备选 2 的 Authorization
///
/// ⚠️ 同 [`VAR_TARGET_ALT2`]:源数 < 3 时 alt2 与 alt 同源 ⇒ conf 不得使用。
pub const VAR_AUTH_ALT2: usize = 10;
/// `$cache_pick`:本请求的选源结果(**请求内缓存**)
pub const VAR_PICK: usize = 11;
/// `$cache_ctx`:**内部**变量,值槽里存的是指向请求池里 [`Memo`] 的指针
const VAR_MEMO: usize = 12;
/// `$cache_pick` 的变量索引(postconfig 解析一次,运行时按索引读)。
///
/// 为什么不用 `ngx_http_get_variable()` 现查:那个 API 的 `key` 参数是
/// **哈希桶号**,传 0 会导致间歇性查不到(详见 `read_pick_var` 的注释)。
static CACHE_PICK_IDX: AtomicIsize = AtomicIsize::new(-1);
/// `$cache_ctx` 的变量索引(postconfig 解析一次,运行时按索引读)。
static CACHE_MEMO_IDX: AtomicIsize = AtomicIsize::new(-1);
/// 供 `handlers::prefetch_indexes`(postconfig)填 `$cache_pick` 的变量索引。
pub(crate) fn set_pick_index(idx: isize) {
CACHE_PICK_IDX.store(idx, Ordering::Relaxed);
}
/// 解析内部变量 `$cache_ctx` 的索引(postconfig)。
///
/// ⚠️ 必须 postconfig 期做:`ngx_http_get_variable_index()` 会在
/// `cmcf->variables` 里建索引项,而 `ngx_http_variables_init_vars()`
/// (nginx 在**所有** postconfig 跑完之后才执行)才把本插件在 preconfig
/// 注册的 `get_handler` 挂到那个索引上。
pub(crate) fn prefetch_memo_index(cf: *mut ngx_conf_t) -> bool {
let mut n = ngx_str_t {
len: "cache_ctx".len(),
data: b"cache_ctx\0".as_ptr() as *mut u8,
};
// SAFETY: cf 由 nginx 传入且有效
let idx = unsafe { ngx_http_get_variable_index(cf, &mut n) };
if idx < 0 {
return false;
}
CACHE_MEMO_IDX.store(idx as isize, Ordering::Relaxed);
true
}
/// 注册本插件的全部变量。返回 false = 失败,gateway 会 EMERG 退出。
///
/// # Safety
/// `cf` 必须由 nginx 传入且有效。
pub unsafe fn preconfig(cf: *mut ngx_conf_t) -> bool {
let mut target = ngx_string!("cache_target");
let mut host = ngx_string!("cache_host");
let mut ukey = ngx_string!("cache_upstream_key");
let mut eco = ngx_string!("cache_eco");
let mut ckey = ngx_string!("cache_key");
let mut auth = ngx_string!("cache_auth");
let mut t_alt = ngx_string!("cache_target_alt");
let mut t_alt2 = ngx_string!("cache_target_alt2");
let mut a_alt = ngx_string!("cache_auth_alt");
let mut a_alt2 = ngx_string!("cache_auth_alt2");
let mut pick = ngx_string!("cache_pick");
let mut memo = ngx_string!("cache_ctx");
unsafe {
add_var(cf, &raw mut target, VAR_TARGET, false)
&& add_var(cf, &raw mut host, VAR_HOST, false)
&& add_var(cf, &raw mut ukey, VAR_UPSTREAM_KEY, false)
&& add_var(cf, &raw mut eco, VAR_ECO, false)
&& add_var(cf, &raw mut ckey, VAR_KEY, false)
&& add_var(cf, &raw mut auth, VAR_AUTH, false)
&& add_var(cf, &raw mut t_alt, VAR_TARGET_ALT, false)
&& add_var(cf, &raw mut t_alt2, VAR_TARGET_ALT2, false)
&& add_var(cf, &raw mut a_alt, VAR_AUTH_ALT, false)
&& add_var(cf, &raw mut a_alt2, VAR_AUTH_ALT2, false)
// ⚠️ $cache_pick 必须**请求内缓存**:target / auth / host 三个变量
// 必须取到同一组源,否则会出现「请求打向 A 源却带 B 源凭据」的错配。
&& add_var(cf, &raw mut pick, VAR_PICK, true)
// 内部变量:值槽里存的是指针,不是字符串 ⇒ 只能由本模块自己读。
&& add_internal_var(cf, &raw mut memo)
}
}
/// 注册一个只读变量,值由 [`var_get`] 按 `slot` 分派计算。
///
/// `NOCACHEABLE`:本变量是「读时现算」,若被 nginx 缓存进 `r->variables`,
/// 同一请求多次求值(`proxy_pass` 一次、`proxy_set_header` 再读)会拿到
/// 首次结果——对上游配置**中途变更**的场景会读到旧值,故标记不可缓存。
///
/// ⚠️ 例外:`$cache_pick` 必须**可缓存**(`cacheable = true`)——
/// 选源结果一旦算出就要在同一请求内被 target/auth/host 共用,
/// 每次重算(尤其冷却状态被别的 worker 改动时)会造成「打向 A 源、带 B 源凭据」。
/// 代价:上游配置中途变更对本请求不可见(下一个请求可见)——可接受。
unsafe fn add_var(cf: *mut ngx_conf_t, name: *mut ngx_str_t, slot: usize, cacheable: bool) -> bool {
let flags = if cacheable {
NGX_HTTP_VAR_CHANGEABLE as ngx_uint_t
} else {
(NGX_HTTP_VAR_CHANGEABLE | NGX_HTTP_VAR_NOCACHEABLE) as ngx_uint_t
};
// SAFETY: cf 由 nginx 传入;name 指向调用方栈上的 ngx_str_t,注册时被拷贝
let var = unsafe { ngx_http_add_variable(cf, name, flags) };
if var.is_null() {
return false;
}
// SAFETY: var 非空且由本函数独占初始化;data 承载分派标记
unsafe {
(*var).get_handler = Some(var_get);
(*var).set_handler = None;
(*var).data = slot;
}
true
}
/// 注册**内部**变量 `$cache_ctx`(请求级 memo 的载体)。
///
/// 与 [`add_var`] 的区别:
/// * 值不是字符串,而是**指向请求池里 [`Memo`] 的指针** ⇒ 只有本模块自己读;
/// * `NOHASH` ⇒ 不进 nginx 的变量哈希表 ⇒ 运行期没人能按名字把它取出来
/// (conf 里引用它也没意义——它不是字符串);
/// * **不带** `NOCACHEABLE` ⇒ nginx 侧 `ngx_http_get_indexed_variable()`
/// 在 `r->variables[index].valid` 为真时直接返回、不再调 get_handler
/// ⇒ 天然请求级缓存(这是 R-T4-2 的实现基础)。
unsafe fn add_internal_var(cf: *mut ngx_conf_t, name: *mut ngx_str_t) -> bool {
// SAFETY: cf 由 nginx 传入;name 指向调用方栈上的 ngx_str_t,注册时被拷贝
let var = unsafe { ngx_http_add_variable(cf, name, NGX_HTTP_VAR_NOHASH as ngx_uint_t) };
if var.is_null() {
return false;
}
// SAFETY: var 非空且由本函数独占初始化
unsafe {
(*var).get_handler = Some(var_get);
(*var).set_handler = None;
(*var).data = VAR_MEMO;
}
true
}
// ===========================================================================
// 求值
// ===========================================================================
/// 管理台「测试」用的探针前缀。conf 里对应一个 `internal` location:
///
/// ```nginx
/// location /_cache_test/ {
/// internal; # 挡住外部直连(否则可绕过鉴权触达上游)
/// proxy_pass $cache_target; # 复用同一个变量,只是 tail 变成 "/"
/// proxy_set_header Host $cache_host;
/// proxy_set_header Authorization $cache_upstream_key;
/// }
/// ```
///
/// 与 apix 的 `/_apix_probe/`、llm 的 `/_upstream_test/` 同一手法:
/// **对外出口与内部探针共用同一套「定上游 + 换凭据」逻辑**,探针才能真正
/// 代表真实转发的行为(自己另写一套探针代码必然漂移)。
pub const PROBE_PREFIX: &str = "/_cache_test/";
/// 解析请求 URI → `(route, tail)`。
///
/// * 正常路径:`/go/pkg-a` → `("go", "/pkg-a")`;`/v2/library/x` → `("docker", "/library/x")`
/// * 探针路径:`/_cache_test/go` → `("go", "/")` —— 固定打上游根,只验连通与凭据
///
/// `tail` 恒以 `/` 开头(上游拼 URL 用),空尾也归一成 `/`。
pub fn resolve_route(uri: &str) -> Option<(&'static str, String)> {
if let Some(rest) = uri.strip_prefix(PROBE_PREFIX) {
let seg = rest.trim_start_matches('/').split('/').next().unwrap_or("");
let route = config::route_of_seg(seg)?;
return Some((route, "/".to_owned()));
}
let route = config::route_of_uri(uri)?;
let seg = uri.trim_start_matches('/').split('/').next().unwrap_or("");
let tail = uri.get(1 + seg.len()..).unwrap_or("");
let tail = if tail.is_empty() { "/" } else { tail };
Some((route, tail.to_owned()))
}
/// 取 base 的 host 部分(含端口)。`https://a.b:8443/x` → `a.b:8443`
pub fn host_of(base: &str) -> &str {
let rest = base.split_once("://").map(|(_, r)| r).unwrap_or(base);
rest.split('/').next().unwrap_or(rest)
}
// ===========================================================================
// 选源(纯函数,可单测)
// ===========================================================================
/// FNV-1a 64 位散列(选源用;只需稳定散列,不抗碰撞)。
pub fn fnv1a(data: &[u8]) -> u64 {
let mut h: u64 = 0xcbf2_9ce4_8422_2325;
for b in data {
h ^= *b as u64;
h = h.wrapping_mul(0x0000_0100_0000_01b3);
}
h
}
/// 选源:返回三个顺位对应的源下标。
///
/// 规则:
/// 1. 起点 = `hash % n`,按顺位轮转;
/// 2. **冷却中的源降权排后**——冷却是降权不是禁用:
/// 池里只剩冷却源时仍要能出请求(宁可重试也不 500)。
/// ⚠️ 链长恒为 3 ⇒ 源数 `n > 3` 时,被冷却的源**进不了前 3 个槽**
/// (它排在健康源之后,但没有第 4 个槽位留给它);只有 `n ≤ 3` 时
/// 才谈得上「挪到尾部」这回事;
/// 3. 源数不足 3 时重复最后一个 ⇒ **链长恒为 3**,
/// conf 里写死的三跳链永远拿得到值。
pub fn select(n: usize, hash: u64, cooled: &[bool]) -> [usize; config::MAX_SLOTS] {
if n == 0 {
return [0; config::MAX_SLOTS];
}
let start = (hash % n as u64) as usize;
let mut order: Vec<usize> = Vec::with_capacity(n);
for k in 0..n {
let i = (start + k) % n;
if !cooled.get(i).copied().unwrap_or(false) {
order.push(i);
}
}
for k in 0..n {
let i = (start + k) % n;
if cooled.get(i).copied().unwrap_or(false) {
order.push(i);
}
}
let last = order.len() - 1;
let mut slots = [order[0]; config::MAX_SLOTS];
for (s, slot) in slots.iter_mut().enumerate() {
*slot = order[s.min(last)];
}
slots
}
/// 把选源结果编码成 `"i0|i1|i2"`(`$cache_pick` 的值)。
///
/// ⚠️ 格式**不许改**(R-T4-3):log handler(Task 5)按这个格式读它。
pub fn encode_pick(slots: &[usize; config::MAX_SLOTS]) -> String {
format!("{}|{}|{}", slots[0], slots[1], slots[2])
}
/// 解析 `$cache_pick`(拿不到 / 格式不对返回 `None`)。
pub fn parse_pick(raw: &str) -> Option<[usize; config::MAX_SLOTS]> {
let mut it = raw.split('|');
let mut slots = [0usize; config::MAX_SLOTS];
for slot in slots.iter_mut() {
*slot = it.next()?.trim().parse::<usize>().ok()?;
}
Some(slots)
}
/// 该源实际使用的上游凭据:源自己的优先,空则回落路由级 `key`。
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` 自动过期 ⇒ 这里只需查「还活着没有」。
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` 秒后自动恢复)。
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}(共享内存可能已满)"
));
}
}
/// 本次请求的散列种子:优先用 `$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 条必须**先判**且不能被跳过:`auth_header` 只认客户端的头是不够的
/// ——那样「配了凭据的路由」永远下发不了凭据,而且客户端带的是 `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 }
}
/// 兼容旧调用点(单源语义:允许转发客户端凭据)。
///
/// 保留它是为了**语义不变**:单源路由今天的透传行为一字不改。
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,
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);
}
(*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");
}
#[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());
}
}