Crate ngx

Source
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’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 --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 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.

§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.