The ngx crate provides a high-level Rust interface for the NGINX C APIs, allowing creation of NGINX dynamic modules completely in Rust.
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.
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 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 using a specific version of NGINX:
NGINX_BUILD_DIR=/path/to/nginx-1.28.0/objs cargo build --package=examples --examplesBuilding 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.
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.
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.The following dependencies are required to build a Rust NGINX module on Linux or BSD platform:
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.
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 with the following command:
brew install make openssl grep
Additionally, you may need to set up LLVM and clang. Typically, this is done as follows:
# make sure xcode tools are installed xcode-select --install # instal llvm brew install --with-toolchain llvm
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):
cargo build --package=examples --examples --features=linux
We provide a multistage Dockerfile:
# 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"
A complete module example using the SDK can be found here. You can build it with cargo build --package=examples --example=curl then set up NGINX to use it, as shown below:
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;
}
}
}
This SDK is currently unstable. Right now, our primary goal is collect feedback and stabilize it before offering support. Feel free to contribute by creating issues, PRs, or github discussions.
Currently, the supported platforms are:
See the Rust toolchain platform support document for supported versions and architectures.
In addition, we verified that the modules based on this SDK can be built and work on the following platforms.
If you have ideas for releases in the future, please suggest them in the github discussions.
We welcome pull requests and issues!
Please refer to the Contributing Guidelines when doing a PR.
Authors and acknowledgmentThis project uses some great work from:
All code in this repository is licensed under the Apache License, Version 2.0.
© F5, Inc.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4