定位:身份层(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、用户管理界面)
257 lines
8.1 KiB
Markdown
257 lines
8.1 KiB
Markdown
[](https://github.com/nginx/ngx-rust/actions/workflows/ci.yaml)
|
||
[](https://crates.io/crates/ngx)
|
||
[)](https://docs.rs/ngx)
|
||
[)](https://docs.rs/nginx-sys)
|
||
[](https://www.repostatus.org/#wip)
|
||
[](https://github.com/nginx/ngx-rust/discussions)
|
||
|
||
<!-- cargo-sync-readme start -->
|
||
|
||
# Rust bindings for NGINX
|
||
|
||
The `ngx` crate provides a high-level Rust interface for the [NGINX] C APIs,
|
||
allowing creation of NGINX dynamic modules completely in Rust.
|
||
|
||
[NGINX]: https://nginx.org/
|
||
|
||
## Project status
|
||
|
||
This project is in active development. It is stable enough to be used in our
|
||
own products, but the APIs are not stabilized and breaking changes are expected.
|
||
|
||
## Build
|
||
|
||
NGINX modules can be built against a particular version of NGINX. The following
|
||
environment variables can be used to specify the NGINX build to use:
|
||
|
||
- `NGINX_BUILD_DIR` - absolute path to the NGINX build directory.
|
||
Usually it's `objs` under the source directory, but can be changed with the
|
||
`--builddir=` argument of the configure script.
|
||
|
||
- `NGINX_SOURCE_DIR` - absolute path to the NGINX source directory, configured
|
||
with the [`configure`](https://nginx.org/en/docs/configure.html) command.
|
||
|
||
Only the `./configure` step of the NGINX build is mandatory because bindings
|
||
generator don't depend on any of the artifacts generated by `make`.
|
||
|
||
For example, this is how you would compile the [examples](#examples) using a
|
||
specific version of NGINX:
|
||
|
||
```sh
|
||
NGINX_BUILD_DIR=/path/to/nginx-1.30.4/objs cargo build --package=examples --examples
|
||
```
|
||
|
||
### Building with the NGINX build script
|
||
|
||
You can build your Rust-based module as a part of the NGINX build process by
|
||
providing a `config` script implementation and passing the `--add-module`/
|
||
`--add-dynamic-module` options to the configure script.
|
||
|
||
See the following example integration scripts: [`examples/config`] and
|
||
[`examples/config.make`].
|
||
|
||
[`examples/config`]: https://github.com/bavshin-f5/ngx-rust/blob/main/examples/config
|
||
[`examples/config.make`]: https://github.com/bavshin-f5/ngx-rust/blob/main/examples/config.make
|
||
|
||
### Building with vendored NGINX sources
|
||
|
||
It is possible to build module with a vendored copy of the NGINX sources
|
||
provided in the `nginx-src` crate by enabling feature `vendored`:
|
||
|
||
By default, this will use the latest stable release of NGINX and require
|
||
system-wide installation of build dependencies (OpenSSL, PCRE2, Zlib).
|
||
|
||
The behavior of vendored builds can be customized with environment variables,
|
||
as documented in the [nginx-src] crate README.
|
||
|
||
**NOTE**: We recommend to build the module binaries against the exact source and
|
||
configuration of the NGINX build that you are planning to use in production,
|
||
and that is unlikely to be possible with the vendored source.
|
||
|
||
`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.
|
||
|
||
[nginx-src]: https://docs.rs/nginx-src/
|
||
|
||
## Cargo features
|
||
|
||
- `alloc` - **Enabled** by default. This provides APIs that require allocations
|
||
via the `alloc` crate.
|
||
- `async` - Enables a minimal async runtime built on top of the NGINX event loop.
|
||
- `serde` - Enables serialization support for some of the provided and
|
||
re-exported types.
|
||
- `std` - **Enabled** by default. This provides APIs that require the standard
|
||
library.
|
||
- `vendored`: Enables the build scripts to build a copy of nginx source and link
|
||
against it. See the [nginx-src] crate documentation for additional details.
|
||
|
||
## Dependencies
|
||
|
||
The following dependencies are required to build a Rust NGINX module on Linux
|
||
or BSD platform:
|
||
|
||
- NGINX build dependencies: C compiler, make, OpenSSL, PCRE2, and Zlib.
|
||
- Rust toolchain (1.85.0 or later)
|
||
- [libclang] for rust-bindgen
|
||
|
||
The installation process and the package names are system-dependent. Please,
|
||
consult the documentation for your distribution.
|
||
|
||
Note that on some systems you will need `-devel` or `-dev` versions of the
|
||
packages.
|
||
|
||
For example, [Dockerfile] contains the installation commands for Debian Linux.
|
||
|
||
[Dockerfile]: https://github.com/nginx/ngx-rust/blob/main/Dockerfile
|
||
[libclang]: https://rust-lang.github.io/rust-bindgen/requirements.html
|
||
|
||
### macOS dependencies
|
||
|
||
In order to use the optional GNU make build process on macOS, you will need
|
||
to install additional tools. This can be done via [homebrew](https://brew.sh/)
|
||
with the following command:
|
||
|
||
```sh
|
||
brew install make openssl grep
|
||
```
|
||
|
||
Additionally, you may need to set up LLVM and clang. Typically, this is done
|
||
as follows:
|
||
|
||
```sh
|
||
# make sure xcode tools are installed
|
||
xcode-select --install
|
||
# instal llvm
|
||
brew install --with-toolchain llvm
|
||
```
|
||
|
||
<!-- cargo-sync-readme end -->
|
||
|
||
### Examples
|
||
|
||
Example modules are available in [examples] folder.
|
||
You can use `cargo build --package=examples --examples` to build these examples.
|
||
After compilation, the modules can be found in the path `target/debug/examples/`
|
||
(with the `.so` file extension for Linux or `.dylib` for macOS).
|
||
Add `--features=linux` to build Linux specific modules.
|
||
|
||
**NOTE**: adding the "linux" feature on macOS will cause a build failure.
|
||
|
||
For example (all examples plus linux specific):
|
||
|
||
```sh
|
||
cargo build --package=examples --examples --features=linux
|
||
```
|
||
|
||
[examples]: https://github.com/nginx/ngx-rust/tree/main/examples
|
||
|
||
### Docker
|
||
|
||
We provide a multistage [Dockerfile]:
|
||
|
||
```sh
|
||
# build all dynamic modules examples and specify NGINX version to use
|
||
docker buildx build --build-arg NGX_VERSION=1.29.1 -t ngx-rust .
|
||
|
||
# start NGINX using [curl](examples/curl.conf) module example:
|
||
docker run --rm -d -p 8000:8000 ngx-rust nginx -c examples/curl.conf
|
||
|
||
# test it - you should see 403 Forbidden
|
||
curl http://127.0.0.1:8000 -v -H "user-agent: curl"
|
||
|
||
# test it - you should see 404 Not Found
|
||
curl http://127.0.0.1:8000 -v -H "user-agent: foo"
|
||
```
|
||
|
||
## Usage
|
||
|
||
A complete module example using the SDK can be found [here](examples/curl.rs).
|
||
You can build it with `cargo build --package=examples --example=curl` then set
|
||
up NGINX to use it, as shown below:
|
||
|
||
```nginx
|
||
daemon off;
|
||
error_log stderr debug;
|
||
|
||
load_module modules/libcurl.so;
|
||
|
||
events {
|
||
}
|
||
|
||
http {
|
||
server {
|
||
listen 8000;
|
||
server_name localhost;
|
||
|
||
access_log /dev/stdout;
|
||
|
||
location / {
|
||
root /srv/http;
|
||
# ... Other config stuff ...
|
||
|
||
curl on;
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## Support
|
||
|
||
This SDK is currently unstable. Right now, our primary goal is collect feedback
|
||
and stabilize it before offering support.
|
||
Feel free to [contribute](CONTRIBUTING.md) by creating issues, PRs, or github
|
||
discussions.
|
||
|
||
Currently, the supported platforms are:
|
||
|
||
- Darwin (macOS)
|
||
- FreeBSD
|
||
- Linux
|
||
|
||
See the Rust toolchain [platform support] document for supported versions and
|
||
architectures.
|
||
|
||
[platform support]: https://doc.rust-lang.org/rustc/platform-support.html
|
||
|
||
### Tested OS and platforms
|
||
|
||
In addition, we verified that the modules based on this SDK can be built and
|
||
work on the following platforms.
|
||
|
||
- Illumos
|
||
- NetBSD 9-10
|
||
- OpenBSD 7
|
||
- Solaris 11.4
|
||
- Windows 10+/Windows Server 2022+
|
||
|
||
## Roadmap
|
||
|
||
If you have ideas for releases in the future, please suggest them in the github
|
||
discussions.
|
||
|
||
## Contributing
|
||
|
||
We welcome pull requests and issues!
|
||
|
||
Please refer to the [Contributing Guidelines](CONTRIBUTING.md) when doing a PR.
|
||
|
||
## Authors and acknowledgment
|
||
|
||
This project uses some great work from:
|
||
|
||
- [dcoles/nginx-rs](https://github.com/dcoles/nginx-rs),
|
||
- [arvancloud/nginx-rs](https://github.com/arvancloud/nginx-rs).
|
||
|
||
## Projects using the SDK
|
||
|
||
- [ngx-strict-sni](https://github.com/JyJyJcr/ngx-strict-sni) - Strict SNI validator for Nginx
|
||
- [nginx-acme](https://github.com/nginx/nginx-acme) - ACMEv2 client implementation
|
||
|
||
## License
|
||
|
||
All code in this repository is licensed under the
|
||
[Apache License, Version 2.0](./LICENSE).
|
||
|
||
© [F5, Inc.](https://www.f5.com/)
|