3个不稳定版本
0.4.1 | 2023年10月26日 |
---|---|
0.4.0-beta | 2023年8月28日 |
0.3.0-beta | 2023年5月17日 |
#315 in 网络编程
34 个月下载量
110KB
2K SLoC
项目状态
此项目仍在开发中,尚未准备好投入生产。
描述
此项目为NGINX代理提供Rust SDK接口,允许完全使用Rust语言创建NGINX动态模块。
简而言之,此SDK允许使用Rust语言编写NGINX模块。
构建
可以将NGINX模块构建在特定的NGINX版本上。以下环境变量可用于指定特定的NGINX版本或依赖项
ZLIB_VERSION
(默认 1.3) -PCRE2_VERSION
(默认 10.42)OPENSSL_VERSION
(默认 3.0.7)NGX_VERSION
(默认 1.23.3) - 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}/{OS}/
将包含用于构建SDK的NGINX编译版本。如果您想测试模块,可以直接从这个目录启动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依赖项
有关依赖项的示例,请参阅Dockerfile,它展示了Debian Linux上所需软件包的示例。
构建示例
示例模块位于examples文件夹中。您可以使用以下命令构建这些示例:cargo build --package=examples --examples
。构建后,您可以在target/debug
文件夹中找到.so
或.dylib
。添加--features=linux
来构建特定于Linux的模块。注意:在MacOS上添加“linux”功能会导致构建失败。
例如(所有示例加Linux特定):cargo build --package=examples --examples --features=linux
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时,请参阅贡献指南。
作者和致谢
本项目使用了dcoles/nginx-rs和arvancloud/nginx-rs的一些优秀工作。
许可
本存储库中的所有代码均采用Apache License v2许可协议。
依赖项
~0-3MB
~54K SLoC