//! 插件装配契约 —— 内核与插件之间唯一的接口。 //! //! 沿用 ssw/sso 的形态,签名保持一致(若将来与 sso 合流,trait 不用再改)。 //! //! ## 刻意没有 `commands()` //! //! nginx 的 `ngx_module_t.commands` 是 null 结尾的**连续**数组,不同 crate 的 //! `static` 数组无法拼接。配置指令由 gateway 集中声明(`ipass_*` 七条不变), //! 插件通过 [`crate::loc::Switch`] 查询自己所在 location 是否开启—— //! **指令解析归壳、行为归插件**。 //! //! ## `dispatch_api` 语义 //! //! 「不认领就返回 `None`,让下一个插件试」,**绝不自行 404**——否则后注册的 //! 插件永远收不到请求。404 由 gateway 在全部插件都返回 `None` 后统一发出。 use core::sync::atomic::{AtomicUsize, Ordering}; use ngx::core::Status; use ngx::ffi::{ngx_conf_t, ngx_http_request_t}; /// 本网关 `ngx_module_t` 的 `ctx_index`(gateway 在 postconfiguration 前 /// 通过 [`set_ctx_index`] 注入)。插件用它在 `r->ctx` 上挂自己的请求级状态 /// (如 usage_filter 的扫描窗口)。 static CTX_INDEX: AtomicUsize = AtomicUsize::new(usize::MAX); pub fn set_ctx_index(idx: usize) { CTX_INDEX.store(idx, Ordering::Relaxed); } /// 当前模块的 ctx_index;`usize::MAX` = 尚未注入(此时插件应放弃请求级状态)。 pub fn ctx_index() -> usize { CTX_INDEX.load(Ordering::Relaxed) } pub trait Plugin: Sync { /// 插件名(日志与排障用) fn name(&self) -> &'static str; /// 配置解析前:注册本插件自己的 nginx 变量。 /// 返回 false = 注册失败,gateway 会 EMERG 退出。 fn preconfig(&self, _cf: *mut ngx_conf_t) -> bool { true } /// 配置解析后:注册 phase handler / body filter。 /// 返回 false = 注册失败,gateway 会 EMERG 退出。 fn postconfig(&self, _cf: *mut ngx_conf_t) -> bool { true } /// 管理 API 分发:认领则返回响应状态,不认领返回 `None`。 fn dispatch_api(&self, _r: *mut ngx_http_request_t) -> Option { None } /// fork 前预装载共享内存(zone init 回调里调用一次)。 /// 返回装载条数(gateway 汇总打日志)。 fn zone_load(&self) -> usize { 0 } /// log 阶段旁路处理器(与 sso 对齐保留;返回 true 表示已处理)。 fn log_handler(&self, _r: *mut ngx_http_request_t) -> bool { true } }