Breaking changes

The release contains too many breaking changes to offer a complete migration guide. We will strive to do better in future releases; meanwhile, we suggest to look at the changes in example modules:

git diff v0.4.1..v0.5.0 -- examples/*.rs

Build experience

In this release, we shifted the focus to an integration into the NGINX build process.

The default set of features now requires providing a preconfigured NGINX source tree with NGINX_SOURCE_DIR and NGINX_BUILD_DIR variables (#67, #124).

The option to build a copy of NGINX as a part of the module process was preserved as a feature flag vendored and no longer requires downloading sources from the network (#160). We encourage you to limit use of this feature to testing only.

The examples directory provides config, config.make and auto/rust scripts to add a Rust-based module to the nginx build, linked statically with --add-module= or dynamically with --add-dynamic-module=. nginx-acme offers another, more complete example (#67, #95, #124, #154, #176).

In addition, we now have a proper detection of the features available in the build of NGINX (#97). See build.rs for the necessary setup for your project.

Module declaration

The traits for declaring a module and accessing module configuration underwent significant changes in #142 with the goal of reducing the amount of unsafe code and enforcing type safety.

See https://github.com/nginx/ngx-rust/pull/142#issuecomment-2755624647 for a summary and migration steps.

Allocators

ngx now offers custom allocator support based on the allocator-api2 crate. The ngx::core::Pool and ngx::core::SlabPool can be used for failible allocations within the NGINX pools and shared zones correspondingly (#164, #171).

Most of the crates with allocator-api2 support are compatible with this implementation. We also provide wrappers for common data structures implemented in NGINX in ngx::collections (#164, #181).

Other

• We audited the code and fixed or removed most of the methods that made wrong assumptions and could panic or crash (#91, #152, #183).
• no_std build support (#111).
• Logging API improvements (#113, #187)
• The SDK and the example modules can be built and are tested in CI on Windows (#124, #161). No further porting or testing work was done.
• Reimplementations for nginx-sys methods and macros that cannot be translated with bindgen (#131, , )

Supported versions

The minimum supported Rust version is 1.81.0. The version was chosen to support the packaged Rust toolchain in the recent versions of popular Linux and BSD distributions.

The minimum supported NGINX version is 1.22. The bindings may compile with an older version of NGINX, but we do not test that regularly.

Full changelog: v0.4.1..v0.5.0