Files
ipass-plugin-cache/CLAUDE.md
T
adminandClaude Opus 4.8 2c8fb2a1ee refactor: 改造为独立插件仓 ipass-plugin-cache(对齐兄弟仓形态)
- 扁平化:rust/crates/plugin-cache/src → src/,单包 Cargo.toml(name ipass-plugin-cache 2.0.0),
  path 依赖改 ../ipass-core(内核+vendor ngx),删除旧单体拆分残留(rust/ 层级、
  deps/ipass submodule、.gitmodules、conf/、tests/、多页静态 www/、AGENTS.md)
- R19 启停对齐:access/log 热路径加 plugin_registry::plugin_enabled("cache")
  门控,fail-closed 404(数据面是鉴权后磁盘读,禁用放行=无鉴权读缓存盘);
  location 圈定暂用 8 前缀路由表,ipass_cache 指令待 gateway 接入轮
- 旧独立应用形态保留在 tag legacy-app-final
- 文档:CLAUDE.md(装配关系+未挂载待办+本机编译 env 姿势)、README.md、
  docs/cache-usage.md 保留;docs/plugins.md(单体时代)删除
- 验证:cargo check --release 通过,cargo test 4 passed

Co-Authored-By: Claude Opus 4.8 <[email protected]>
2026-09-24 21:15:57 +08:00

50 lines
2.3 KiB
Markdown
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.
# CLAUDE.md
## 入口(规划中,gateway 接入后生效)
| URL | 目标 |
|-----|------|
| `http://nginx/go/ /cargo/ /cargo-dl/ /pypi/ /pypi-files/ /npm/ /maven/ /v2/` | 数据面(nginx 原生 `proxy_cache`;本插件 access 鉴权 + log 计量) |
| `http://nginx/api/admin/cache*` | 本插件认领的管理 API(Admin) |
| `http://nginx/api/v1/cache*` | 账号态接入说明 / 命中统计(User) |
## 装配关系
本仓库是 **ipass-core 内核**的一个 *crate 级* 插件(不是 nginx 动态模块)。
nginx 动态模块没有稳定 ABI,所有插件在 gateway 装配层以 `ipass_plugin_xxx`
extern "C" 入口函数形式注册到单个 cdylib `.so` 内。
**当前状态:尚未挂载到任何 gateway**(2026-09-24 由旧独立应用仓
`ipass/cache` 改造为插件仓;旧形态完整保留在 tag `legacy-app-final`)。
接入时需要做的配套改动:
1. 宿主 gateway 的 `PLUGINS` 数组加 `&ipass_plugin_cache::CachePlugin`
2. 宿主 conf 加 `proxy_cache_path` 与各生态 location;location 级开关
`ipass_cache` 需给 core `loc::Switch` 补 `Cache` 变体,并同步三个
gateway 的穷尽 match(保守 false)——接入轮一并处理
3. ipass-core `plugin_registry::KNOWN_PLUGINS` 加 `"cache"`、
`plugin-config.example.json` 补条目
4. `www/` 重写为 UMD 面板(`plugin-cache-admin.umd.js`,对齐兄弟仓)
## 启停
与其他插件一致走 R19 注册表:配置键 = `cache`(`Plugin::name()` 短名)。
禁用语义与 waf/sso 的「放行」**不同**,是 fail-closed → 404——数据面是
鉴权后的磁盘读,禁用时放行等于无鉴权读缓存(见 `src/handlers.rs`)。
详见 `../ipass-core/docs/toggle.md`。
## 构建/开发
本机不启用 `nginx-sys/vendored`,沿用兄弟仓姿势:env 指向一份已 configure 的
nginx 源码树(bindgen 从其 `objs/Makefile` 抽 `-I`;路径不可 `mv`,
详见 `../ipass-waf/rust/BUILD.md` 同款说明)。
```bash
export LIBCLANG_PATH=/Library/Developer/CommandLineTools/usr/lib
export NGINX_SOURCE_DIR=/Users/xs/Desktop/workspace/ipass/ipass-ssw/build/ngxbuild/nginx-1.30.4
export NGINX_BUILD_DIR=$NGINX_SOURCE_DIR/objs
cargo check --release && cargo test --release
```
兄弟仓库:`../ipass-core/`、`../ipass-plugin-{domain,llm,apix,sso,waf}/`。