diff --git a/Cargo.toml b/Cargo.toml index 1ee7bb6..5388e8c 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -14,7 +14,7 @@ license = "Apache-2.0" # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html [dependencies] -nginx-sys = { path = "nginx-sys"} +nginx-sys = { path = "nginx-sys", version = "0.1"} [build-dependencies] bindgen = "0.64.0" diff --git a/nginx-sys/Cargo.toml b/nginx-sys/Cargo.toml index d17233d..cca1d02 100644 --- a/nginx-sys/Cargo.toml +++ b/nginx-sys/Cargo.toml @@ -2,15 +2,20 @@ name = "nginx-sys" version = "0.1.0" edition = "2021" +categories = ["external-ffi-bindings"] +description = "FFI bindings to NGINX" +repository = "https://github.com/nginxinc/ngx-rust" +homepage = "https://github.com/nginxinc/ngx-rust" license = "Apache-2.0" +keywords = ["nginx", "ffi", "sys"] [lib] -crate-type = ["staticlib","rlib"] +crate-type = ["staticlib", "rlib"] [dependencies] [build-dependencies] -bindgen = "0.64.0" +bindgen = "0.65.0" which = "4.4.0" duct = "0.13.6" ureq = { version = "2.6.2", features = ["tls"] } diff --git a/nginx-sys/src/lib.rs b/nginx-sys/src/lib.rs index cf11f1a..ad1c5d4 100644 --- a/nginx-sys/src/lib.rs +++ b/nginx-sys/src/lib.rs @@ -1,16 +1,75 @@ -#![allow(non_upper_case_globals)] -#![allow(non_camel_case_types)] -#![allow(non_snake_case)] -#![allow(dead_code)] -#![allow(clippy::all)] -#![allow(improper_ctypes)] - -include!(concat!(env!("OUT_DIR"), "/bindings.rs")); +//! # nginx-sys +//! +//! The `nginx-sys` crate provides low-level bindings for the nginx C API, allowing Rust applications to interact with nginx servers and modules. +//! +//! ## Usage +//! +//! Add `nginx-sys` as a dependency in your `Cargo.toml`: +//! +//! ```toml +//! [dependencies] +//! nginx-sys = "0.1.0" +//! ``` +//! +//! ## Features +//! +//! - `build`: Enables the build scripts to compile and link against the nginx C library. This feature is enabled by default. +//! +//! ## Examples +//! +//! ### Get Nginx Version +//! +//! This example demonstrates how to retrieve the version of the nginx server. +//! +//! ```rust,no_run +//! use nginx_sys::nginx_version; +//! +//! fn main() { +//! let version = unsafe { nginx_version() }; +//! println!("Nginx version: {}", version); +//! } +//! ``` +//! +#![warn(missing_docs)] use std::fmt; use std::ptr::copy_nonoverlapping; use std::slice; +#[doc(hidden)] +mod bindings { + #![allow(missing_docs)] + #![allow(non_upper_case_globals)] + #![allow(non_camel_case_types)] + #![allow(non_snake_case)] + #![allow(dead_code)] + #![allow(clippy::all)] + #![allow(improper_ctypes)] + #[allow(rustdoc::broken_intra_doc_links)] + include!(concat!(env!("OUT_DIR"), "/bindings.rs")); +} +#[doc(no_inline)] +pub use bindings::*; + +/// Convert a string slice (`&str`) to a raw pointer (`*mut u_char`) allocated in the given nginx memory pool. +/// +/// # Arguments +/// +/// * `pool` - A pointer to the nginx memory pool (`ngx_pool_t`). +/// * `data` - The string slice to convert to a raw pointer. +/// +/// # Safety +/// This function is marked as unsafe because it involves raw pointer manipulation and direct memory allocation using `ngx_palloc`. +/// +/// # Returns +/// A raw pointer (`*mut u_char`) to the allocated memory containing the converted string data. +/// +/// # Example +/// ```rust +/// let pool: *mut ngx_pool_t = ...; // Obtain a pointer to the nginx memory pool +/// let data: &str = "example"; // The string to convert +/// let ptr = str_to_uchar(pool, data); +/// ``` pub fn str_to_uchar(pool: *mut ngx_pool_t, data: &str) -> *mut u_char { let ptr: *mut u_char = unsafe { ngx_palloc(pool, data.len() as _) as _ }; unsafe { @@ -20,7 +79,14 @@ pub fn str_to_uchar(pool: *mut ngx_pool_t, data: &str) -> *mut u_char { } impl ngx_str_t { - // convert nginx string to str slice + /// Convert the nginx string to a string slice (`&str`). + /// + /// # Safety + /// This function is marked as unsafe because it involves raw pointer manipulation. + /// It assumes that the underlying `data` pointer is valid and points to a valid UTF-8 encoded string. + /// + /// # Returns + /// A string slice (`&str`) representing the nginx string. pub fn to_str(&self) -> &str { unsafe { let slice = slice::from_raw_parts(self.data, self.len as usize); @@ -28,12 +94,23 @@ impl ngx_str_t { } } - // get string + /// Convert the nginx string to a `String` by copying its contents. + /// + /// # Returns + /// A new `String` containing the contents of the nginx string. pub fn to_string(&self) -> String { return String::from(self.to_str()); } - /// create from string + /// Create an `ngx_str_t` instance from a `String`. + /// + /// # Arguments + /// + /// * `pool` - A pointer to the nginx memory pool (`ngx_pool_t`). + /// * `data` - The `String` from which to create the nginx string. + /// + /// # Returns + /// An `ngx_str_t` instance representing the given `String`. pub fn from_string(pool: *mut ngx_pool_t, data: String) -> Self { ngx_str_t { data: str_to_uchar(pool, data.as_str()), @@ -41,7 +118,15 @@ impl ngx_str_t { } } - /// create from string + /// Create an `ngx_str_t` instance from a string slice (`&str`). + /// + /// # Arguments + /// + /// * `pool` - A pointer to the nginx memory pool (`ngx_pool_t`). + /// * `data` - The string slice from which to create the nginx string. + /// + /// # Returns + /// An `ngx_str_t` instance representing the given string slice. pub fn from_str(pool: *mut ngx_pool_t, data: &str) -> Self { ngx_str_t { data: str_to_uchar(pool, data), @@ -82,6 +167,29 @@ impl TryFrom for &str { } } +/// Add a key-value pair to an nginx table entry (`ngx_table_elt_t`) in the given nginx memory pool. +/// +/// # Arguments +/// +/// * `table` - A pointer to the nginx table entry (`ngx_table_elt_t`) to modify. +/// * `pool` - A pointer to the nginx memory pool (`ngx_pool_t`) for memory allocation. +/// * `key` - The key string to add to the table entry. +/// * `value` - The value string to add to the table entry. +/// +/// # Safety +/// This function is marked as unsafe because it involves raw pointer manipulation and direct memory allocation using `str_to_uchar`. +/// +/// # Returns +/// An `Option<()>` representing the result of the operation. `Some(())` indicates success, while `None` indicates a null table pointer. +/// +/// # Example +/// ```rust +/// let table: *mut ngx_table_elt_t = ...; // Obtain a pointer to the nginx table entry +/// let pool: *mut ngx_pool_t = ...; // Obtain a pointer to the nginx memory pool +/// let key: &str = "key"; // The key to add +/// let value: &str = "value"; // The value to add +/// let result = add_to_ngx_table(table, pool, key, value); +/// ``` pub fn add_to_ngx_table(table: *mut ngx_table_elt_t, pool: *mut ngx_pool_t, key: &str, value: &str) -> Option<()> { if table.is_null() { return None;