Expand description
§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.
§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’sobjs
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 theconfigure
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 --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
.
§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.
§Cargo features
alloc
- Enabled by default. This provides APIs that require allocations via thealloc
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.81.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.
§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 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
Modules§
- allocator
- The allocator module.
- async_
- Async runtime and set of utilities on top of the NGINX event loop.
- collections
- Collection types.
- core
- The core module.
- ffi
- The ffi module.
- http
- The http module.
- log
- The log module.
- sync
- Synchronization primitives over shared memory.
Macros§
- count
- Count number of arguments
- http_
request_ handler - Define a static request handler.
- http_
subrequest_ handler - Define a static post subrequest handler.
- http_
upstream_ init_ peer_ pt - Define a static upstream peer initializer
- http_
variable_ get - Define a static variable evaluator.
- http_
variable_ set - Define a static variable setter.
- ngx_
conf_ log_ error - Write to logger with the context of currently processed configuration file.
- ngx_
container_ of - Gets an outer object pointer from a pointer to one of its fields. While there is no corresponding C macro, the pattern is common in the NGINX source.
- ngx_
log_ debug - Write to logger at debug level.
- ngx_
log_ debug_ http - Log to request connection log at level
NGX_LOG_DEBUG_HTTP
. - ngx_
log_ debug_ mask - Log with requested debug mask.
- ngx_
log_ error - Write to logger at a specified level.
- ngx_
modules - Define modules exported by this library.
- ngx_
string - Static string initializer for
ngx_str_t
.