项目状态

此项目仍在开发中，尚未准备好用于生产。

描述

本项目为NGINX代理提供Rust SDK接口，允许完全使用Rust创建NGINX动态模块。

简而言之，此SDK允许使用Rust语言编写NGINX模块。

构建

可以针对特定版本的NGINX构建NGINX模块。以下环境变量可以用来指定特定的NGINX版本或依赖项：

• ZLIB_VERSION（默认1.3.1） - zlib版本
• PCRE2_VERSION（默认10.42，用于NGINX 1.22.0及以后版本，或8.45用于早期版本） - PCRE1或PCRE2版本
• OPENSSL_VERSION（默认3.2.1，用于NGINX 1.22.0及以后版本，或1.1.1w用于早期版本） - OpenSSL版本
• NGX_VERSION（默认1.24.0） - NGINX OSS版本
• NGX_DEBUG（默认为false）- 如果设置为true，则编译NGINX的--with-debug选项

例如，以下是如何使用特定版本的NGINX和启用调试编译示例：

NGX_DEBUG=true NGX_VERSION=1.23.0 cargo build --package=examples --examples --release

要构建仅适用于Linux的模块，请使用"linux"功能

cargo build --package=examples --examples --features=linux --release

编译完成后，模块可以在路径target/release/examples/中找到（Linux使用.so文件扩展名，MacOS使用.dylib文件扩展名）。

此外，文件夹 .cache/nginx/{NGX_VERSION}/{TARGET} （{TARGET} 表示 rustc 的目标三元组字符串）将包含用于构建 SDK 的 NGINX 的编译版本。如果您想测试该模块，可以直接从这个目录启动 NGINX。

以下环境变量可以用于更改缓存目录和 NGINX 目录的位置

• CACHE_DIR （默认 [nginx-sys's root directory]/.cache） - 包含缓存文件的目录，意味着 PGP 密钥、tarball、PGP 签名和解压的源代码。它还包含默认配置下的编译 NGINX。
• NGINX_INSTALL_ROOT_DIR （默认 {CACHE_DIR}/nginx） - 包含其子目录中一系列编译 NGINX 的目录
• NGINX_INSTALL_DIR （默认 {NGINX_INSTALL_BASE_DIR}/{NGX_VERSION}/{TARGET}） - 包含构建中编译的 NGINX 的目录

Mac OS 依赖

为了在 MacOS 上使用可选的 GNU make 构建过程，您需要安装额外的工具。这可以通过以下命令通过 homebrew 完成：

brew install make openssl grep

此外，您可能还需要设置 LLVM 和 clang。通常，这可以通过以下方式完成：

# make sure xcode tools are installed
xcode-select --install
# instal llvm
brew install --with-toolchain llvm

Linux 依赖

有关 Debian Linux 上必需的软件包的示例，请参阅 Dockerfile。

构建示例

示例模块位于 examples 文件夹中。您可以使用 cargo build --package=examples --examples 来构建这些示例。构建完成后，您可以在 .so 或 .dylib 中找到 target/debug 文件夹。添加 --features=linux 以构建特定于 Linux 的模块。**注意**：在 MacOS 上添加 "linux" 功能会导致构建失败。

例如（所有示例加上特定于 Linux 的示例）：cargo build --package=examples --examples --features=linux

使用外部 NGINX 源树进行构建

如果您需要自定义的NGINX配置，您可以在现有的预配置源代码树中构建一个模块。为此，您需要将变量 NGX_OBJS 设置为NGINX构建目录的绝对路径（--builddir，默认为源目录中的objs）。NGINX构建的./configure步骤是强制性的，因为绑定不依赖于由make生成的任何工件。

NGX_OBJS=$PWD/../nginx/objs cargo build --package=examples --examples

此外，可以通过将 --add-module/--add-dynamic-module 选项添加到配置脚本中，利用这种方法将模块作为NGINX构建过程的一部分来构建。请参阅以下集成脚本示例：examples/config 和 examples/config.make。

Docker

我们提供了一个多阶段 Dockerfile

# build all dynamic modules examples and specify NGINX version to use
docker buildx build --build-arg NGX_VERSION=1.23.3 -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"

用法

您可以在这里找到使用SDK的完整模块示例。您可以使用以下命令构建它：cargo build --package=examples --example=curl，然后设置NGINX以使用它。

例如

daemon off;
master_process off;

# unix:
# load_module modules/libcurl.so;

# error_log logs/error.log debug;
error_log /dev/stdout debug;

working_directory /tmp/cores/;
worker_rlimit_core 500M;

events {
}

http {
    access_log /dev/stdout;
    server {
        listen 8000;
        server_name localhost;
        location / {
            alias /srv/http;
            # ... Other config stuff ...

            curl on;
        }
    }
}

支持

目前，此SDK尚不稳定。我们的主要目标是收集反馈并在提供支持之前稳定它。请随时通过创建问题、PR或GitHub讨论来贡献。

目前，唯一支持的平台是

• Darwin (Mac OSX)
• Linux平台

路线图

如果您对未来版本有想法，请通过GitHub讨论提出建议。

贡献

我们欢迎PR和问题！

在进行PR时，请参阅贡献指南。

作者和致谢

本项目使用了一些来自 dcoles/nginx-rs、arvancloud/nginx-rs 的出色工作。

使用SDK的项目

ngx-strict-sni - Nginx的严格SNI验证器

许可

本存储库中的所有代码均根据Apache License v2许可授权。

lib.rs:

nginx-sys

nginx-sys crate提供了对nginx C API的低级绑定，允许Rust应用程序与nginx服务器和模块交互。

用法

在您的Cargo.toml中将nginx-sys作为依赖项添加

[dependencies]
nginx-sys = "0.1.0"

功能

• build：启用构建脚本编译和链接nginx C库。此功能默认启用。

示例

获取Nginx版本

此示例演示了如何检索nginx服务器的版本。

use nginx_sys::nginx_version;

let version = unsafe { nginx_version() };
println!("Nginx version: {}", version);