定位:身份层(IdP + IAP),不含动态域名转发 / LLM 上游代理 / 用量计费。 代码(source/rust,nginx 动态模块 + Rust,单进程零外部依赖) - IdP:authorization_code(含 PKCE)/ refresh_token / client_credentials / password 四种 grant,含 discovery / introspect / userinfo / jwks 占位 - IAP:access 阶段门禁,注入 X-Auth-* 到后端,客户端伪造同名头被覆盖 - MaxKey 互通:/oauth/v20/* 与 /oauth2.0/* 别名 + context-path 归一化 + 扁平字段 - 管理接口:账号(含角色/部门/用户组)与 OAuth 接入方注册表,热写穿共享内存 - 模块改名 ngx_http_sso_module,指令 sso_state / sso_data_dir / sso_api / sso_iap, Cookie sso_sid(终端用户)与 sso_admin_session(管理员)两套身份两套会话 配置(source/conf) - nginx.conf 生产模板(TLS、IAP 子域、含 auth_sub 的日志格式) - nginx.test.conf 本机验证配置(明文 18095-18099) - tls/README.md 证书约定与公钥比对校验 前端(source/www/admin.html) - 三 tab:账号管理 / 接入方 / 接入指南;去掉审核队列、域名、LLM 上游、用量统计 测试与脚本 - tests/ 三套端到端:协议基线 14 项 · MaxKey 互通与接入 24 项 · 管理接口 31 项,全绿 - tests/demo-system 演示业务系统(Python 标准库),覆盖应用自建客户端与 IAP 零改造两种姿势 - scripts/run-local-e2e.sh 本机一键起停;scripts/seed-data.sh 物化运行时数据目录 文档 - README.md 概览与快速开始;CLAUDE.md 硬约定与排障速查 - docs/design.md 完整设计;docs/roadmap.md 待执行任务(v2 RS256+JWKS、用户管理界面)
5.8 KiB
nginx-sys
The nginx-sys crate provides low-level bindings for the nginx C API, allowing
Rust applications to interact with nginx servers and modules.
Usage
Add nginx-sys as a dependency in your Cargo.toml:
[dependencies]
nginx-sys = "0.5.0"
Set the path to your nginx sources and build directory using the
environment variables, or enable the nginx-sys/vendored
feature to use a downloaded copy of the nginx sources.
Note that it is recommended to use the exact source and configure arguments
of the nginx build you are planning to use in production.
configure arguments alter the APIs and the symbols visible to the Rust code,
and some OS distributions are known to ship nginx packages with API-breaking
patches applied.
Features
-
http- Enabled by default. Allows generation of bindings for the HTTP module,ngx_http.h. The feature will be ignored if NGINX is configured without HTTP support, thus it may be necessary to check forhttpinDEP_NGINX_FEATURES. -
mail: Allows generation of bindings for the Mail module,ngx_mail.h. The feature will be ignored if NGINX is configured without Mail support, thus it may be necessary to check formailinDEP_NGINX_FEATURES. -
stream: Allows generation of bindings for the Stream module,ngx_stream.h. The feature will be ignored if NGINX is configured without Stream support, thus it may be necessary to check forstreaminDEP_NGINX_FEATURES. -
vendored: Enables the build scripts to download and build a copy of nginx source and link against it. Seenginx-srccrate documentation for additional details.
Input variables
NGINX_SOURCE_DIR, NGINX_BUILD_DIR control paths to an external nginx source
tree and a configured build directory. Normally, specifying either of these is
sufficient, as the build directory defaults to objs under the source dir.
However, it's possible to set the latter to any valid path with
configure --builddir=<...>, and we need both paths to support such
configuration.
The variables above are optional, but take preference when the vendored crate
feature is enabled.
Output variables
Following metadata variables are passed to the build scripts of any direct dependents of the package.
Check the using another sys crate and the links manifest key sections of the Cargo Book for more details about passing metadata between packages.
DEP_NGINX_FEATURES
nginx has various configuration options that may affect the availability of functions, constants and structure fields. This is not something that can be detected at runtime, as an attempt to use a symbol unavailable in the bindings would result in compilation error.
DEP_NGINX_FEATURES_CHECK contains the full list of feature flags supported
by nginx-sys, i.e. everything that can be used for feature checks.
The most common use for this variable is to specify cargo::rustc-check-cfg.
DEP_NGINX_FEATURES contains the list of features enabled in the version of
nginx being built against.
An example of a build script with these variables:
// Specify acceptable values for `ngx_feature`.
println!("cargo::rerun-if-env-changed=DEP_NGINX_FEATURES_CHECK");
println!(
"cargo::rustc-check-cfg=cfg(ngx_feature, values({}))",
std::env::var("DEP_NGINX_FEATURES_CHECK").unwrap_or("any()".to_string())
);
// Read feature flags detected by nginx-sys and pass to the compiler.
println!("cargo::rerun-if-env-changed=DEP_NGINX_FEATURES");
if let Ok(features) = std::env::var("DEP_NGINX_FEATURES") {
for feature in features.split(',').map(str::trim) {
println!("cargo::rustc-cfg=ngx_feature=\"{}\"", feature);
}
}
And an usage example:
#[cfg(ngx_feature = "debug")]
println!("this nginx binary was built with debug logging enabled");
DEP_NGINX_OS
Version, as detected by the nginx configuration script.
DEP_NGINX_OS_CHECK contains the full list of supported values, and
DEP_NGINX_OS the currently detected one.
Usage examples:
// Specify acceptable values for `ngx_os`
println!("cargo::rerun-if-env-changed=DEP_NGINX_OS_CHECK");
println!(
"cargo::rustc-check-cfg=cfg(ngx_os, values({}))",
std::env::var("DEP_NGINX_OS_CHECK").unwrap_or("any()".to_string())
);
// Read operating system detected by nginx-sys and pass to the compiler.
println!("cargo::rerun-if-env-changed=DEP_NGINX_OS");
if let Ok(os) = std::env::var("DEP_NGINX_OS") {
println!("cargo::rustc-cfg=ngx_os=\"{}\"", os);
}
#[cfg(ngx_os = "freebsd")]
println!("this nginx binary was built on FreeBSD");
Version and build information
DEP_NGINX_VERSION_NUMBER: a numeric representation with 3 digits for each component:1026002DEP_NGINX_VERSION: human-readable string in a product/version format:nginx/1.26.2DEP_NGINX_BUILD: version string with the optional build name (--build=) included:nginx/1.25.5 (nginx-plus-r32)
Usage example:
println!("cargo::rustc-check-cfg=cfg(nginx1_27_0)");
println!("cargo::rerun-if-env-changed=DEP_NGINX_VERSION_NUMBER");
if let Ok(version) = std::env::var("DEP_NGINX_VERSION_NUMBER") {
let version: u64 = version.parse().unwrap();
if version >= 1_027_000 {
println!("cargo::rustc-cfg=nginx1_27_0");
}
}
Examples
Get nginx Version
This example demonstrates how to retrieve the version of the nginx server.
use nginx_sys::nginx_version;
println!("nginx version: {}", nginx_version);