3个不稳定版本

0.4.1 2023年10月26日
0.4.0-beta2023年8月28日
0.3.0-beta2023年5月17日

#315 in 网络编程

34 个月下载量

Apache-2.0

110KB
2K SLoC

Rust crates.io Project Status: Concept – Minimal or no implementation has been done yet, or the repository is only intended to be a limited example, demo, or proof-of-concept. Community Support

项目状态

此项目仍在开发中,尚未准备好投入生产。

描述

此项目为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-rsarvancloud/nginx-rs的一些优秀工作。

许可

本存储库中的所有代码均采用Apache License v2许可协议

依赖项

~0-3MB
~54K SLoC