- vanilla nginx + Rust 动态模块(取代 OpenResty+Lua),共享内存为运行期真源 - 三域名分流 18098 ssl:mdm 管理台 / lm LLM 代理 / *.dm 企业转发,共用 *.mayishangshu.cn 通配符证书(证书不入库) - LLM 统一出口:同 Key 鉴权、上游 Key 替换、白名单、限流配额、SSE - 回归夹具 tests/(网关 55 + LLM 34 = 89 断言,夹具 cp 覆盖重置) - 文档:readme(16 章)+ CLAUDE.md + conf/tls/README(acme.sh 证书管理、hairpin 环回链路)
190 lines
6.7 KiB
Rust
190 lines
6.7 KiB
Rust
//! # 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.
|
|
//!
|
|
//! [NGINX]: https://nginx.org/
|
|
//!
|
|
//! ## 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`](https://nginx.org/en/docs/configure.html) 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](#examples) using a
|
|
//! specific version of NGINX:
|
|
//!
|
|
//! ```sh
|
|
//! NGINX_BUILD_DIR=/path/to/nginx-1.30.4/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`].
|
|
//!
|
|
//! [`examples/config`]: https://github.com/bavshin-f5/ngx-rust/blob/main/examples/config
|
|
//! [`examples/config.make`]: https://github.com/bavshin-f5/ngx-rust/blob/main/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.
|
|
//!
|
|
//! [nginx-src]: https://docs.rs/nginx-src/
|
|
//!
|
|
//! ## 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.85.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.
|
|
//!
|
|
//! [Dockerfile]: https://github.com/nginx/ngx-rust/blob/main/Dockerfile
|
|
//! [libclang]: https://rust-lang.github.io/rust-bindgen/requirements.html
|
|
//!
|
|
//! ### 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](https://brew.sh/)
|
|
//! with the following command:
|
|
//!
|
|
//! ```sh
|
|
//! brew install make openssl grep
|
|
//! ```
|
|
//!
|
|
//! Additionally, you may need to set up LLVM and clang. Typically, this is done
|
|
//! as follows:
|
|
//!
|
|
//! ```sh
|
|
//! # make sure xcode tools are installed
|
|
//! xcode-select --install
|
|
//! # instal llvm
|
|
//! brew install --with-toolchain llvm
|
|
//! ```
|
|
#![warn(missing_docs)]
|
|
#![no_std]
|
|
#[cfg(feature = "alloc")]
|
|
extern crate alloc;
|
|
|
|
pub mod allocator;
|
|
#[cfg(feature = "async")]
|
|
pub mod async_;
|
|
pub mod collections;
|
|
|
|
/// The core module.
|
|
///
|
|
/// This module provides fundamental utilities needed to interface with many NGINX primitives.
|
|
/// String conversions, the pool (memory interface) object, and buffer APIs are covered here. These
|
|
/// utilities will generally align with the NGINX 'core' files and APIs.
|
|
pub mod core;
|
|
|
|
/// The ffi module.
|
|
///
|
|
/// This module provides scoped FFI bindings for NGINX symbols.
|
|
pub mod ffi;
|
|
|
|
/// The http module.
|
|
///
|
|
/// This modules provides wrappers and utilities to NGINX http APIs, such as requests,
|
|
/// configuration access, and statuses.
|
|
#[cfg(ngx_feature = "http")]
|
|
pub mod http;
|
|
|
|
/// The log module.
|
|
///
|
|
/// This module provides an interface into the NGINX logger framework.
|
|
pub mod log;
|
|
|
|
pub mod sync;
|
|
|
|
/// Define modules exported by this library.
|
|
///
|
|
/// These are normally generated by the Nginx module system, but need to be
|
|
/// defined when building modules outside of it.
|
|
#[macro_export]
|
|
macro_rules! ngx_modules {
|
|
($( $mod:ident ),+) => {
|
|
#[unsafe(no_mangle)]
|
|
#[allow(non_upper_case_globals)]
|
|
pub static mut ngx_modules: [*const $crate::ffi::ngx_module_t; $crate::count!($( $mod, )+) + 1] = [
|
|
$( unsafe { &$mod } as *const $crate::ffi::ngx_module_t, )+
|
|
::core::ptr::null()
|
|
];
|
|
|
|
#[unsafe(no_mangle)]
|
|
#[allow(non_upper_case_globals)]
|
|
pub static mut ngx_module_names: [*const ::core::ffi::c_char; $crate::count!($( $mod, )+) + 1] = [
|
|
$( concat!(stringify!($mod), "\0").as_ptr() as *const ::core::ffi::c_char, )+
|
|
::core::ptr::null()
|
|
];
|
|
|
|
#[unsafe(no_mangle)]
|
|
#[allow(non_upper_case_globals)]
|
|
pub static mut ngx_module_order: [*const ::core::ffi::c_char; 1] = [
|
|
::core::ptr::null()
|
|
];
|
|
};
|
|
}
|
|
|
|
/// Count number of arguments
|
|
#[macro_export]
|
|
macro_rules! count {
|
|
() => { 0usize };
|
|
($x:tt, $( $xs:tt ),*) => { 1usize + $crate::count!($( $xs, )*) };
|
|
}
|