diff --git a/nginx-sys/src/lib.rs b/nginx-sys/src/lib.rs index ad1c5d4..df463c8 100644 --- a/nginx-sys/src/lib.rs +++ b/nginx-sys/src/lib.rs @@ -24,10 +24,8 @@ //! ```rust,no_run //! use nginx_sys::nginx_version; //! -//! fn main() { -//! let version = unsafe { nginx_version() }; -//! println!("Nginx version: {}", version); -//! } +//! let version = unsafe { nginx_version() }; +//! println!("Nginx version: {}", version); //! ``` //! #![warn(missing_docs)] @@ -45,7 +43,7 @@ mod bindings { #![allow(dead_code)] #![allow(clippy::all)] #![allow(improper_ctypes)] - #[allow(rustdoc::broken_intra_doc_links)] + #![allow(rustdoc::broken_intra_doc_links)] include!(concat!(env!("OUT_DIR"), "/bindings.rs")); } #[doc(no_inline)] @@ -89,19 +87,11 @@ impl ngx_str_t { /// 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); + let slice = slice::from_raw_parts(self.data, self.len); return std::str::from_utf8(slice).unwrap(); } } - /// 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 an `ngx_str_t` instance from a `String`. /// /// # Arguments @@ -140,7 +130,7 @@ impl From for &[u8] { if s.len == 0 || s.data.is_null() { return Default::default(); } - unsafe { slice::from_raw_parts(s.data, s.len as usize) } + unsafe { slice::from_raw_parts(s.data, s.len) } } } diff --git a/src/core/status.rs b/src/core/status.rs index 3b614d2..7e6c0cf 100644 --- a/src/core/status.rs +++ b/src/core/status.rs @@ -1,10 +1,14 @@ use crate::ffi::*; use std::fmt; +/// Status +/// +/// Rust native wrapper for NGINX status codes. #[derive(Ord, PartialOrd, Eq, PartialEq)] pub struct Status(pub ngx_int_t); impl Status { + /// Is this Status equivalent to NGX_OK? pub fn is_ok(&self) -> bool { self == &Status::NGX_OK } @@ -40,13 +44,23 @@ macro_rules! ngx_codes { } ngx_codes! { + /// NGX_OK - Operation succeeded. (NGX_OK); + /// NGX_ERROR - Operation failed. (NGX_ERROR); + /// NGX_AGAIN - Operation incomplete; call the function again. (NGX_AGAIN); + /// NGX_BUSY - Resource is not available. (NGX_BUSY); + /// NGX_DONE - Operation complete or continued elsewhere. Also used as an alternative success code. (NGX_DONE); + /// NGX_DECLINED - Operation rejected, for example, because it is disabled in the configuration. + /// This is never an error. (NGX_DECLINED); + /// NGX_ABORT - Function was aborted. Also used as an alternative error code. (NGX_ABORT); } + +/// NGX_CONF_ERROR - An error occurred while parsing and validating configuration. pub const NGX_CONF_ERROR: *const () = -1isize as *const (); // pub const CONF_OK: Status = Status(NGX_CONF_OK as ngx_int_t); diff --git a/src/http/module.rs b/src/http/module.rs index 62167dd..96f4a81 100644 --- a/src/http/module.rs +++ b/src/http/module.rs @@ -5,6 +5,7 @@ use crate::ffi::*; use core::ptr; use std::os::raw::{c_char, c_void}; +/// MergeConfigError - configuration cannot be merged with levels above. #[derive(Debug)] pub enum MergeConfigError { /// No value provided for configuration argument @@ -21,7 +22,15 @@ impl std::fmt::Display for MergeConfigError { } } +/// The `Merge` trait provides a method for merging configuration down through each level. +/// +/// A module configuration should implement this trait for setting its configuration throughout +/// each level. pub trait Merge { + /// Module merge function. + /// + /// # Returns + /// Result, Ok on success or MergeConfigError on failure. fn merge(&mut self, prev: &Self) -> Result<(), MergeConfigError>; } @@ -31,9 +40,18 @@ impl Merge for () { } } +/// The `HTTPModule` trait provides the NGINX configuration stage interface. +/// +/// These functions allocate structures, initialize them, and merge through the configuration +/// layers. +/// +/// See https://nginx.org/en/docs/dev/development_guide.html#adding_new_modules for details. pub trait HTTPModule { + /// Configuration in the `http` block. type MainConf: Merge + Default; + /// Configuration in a `server` block within the `http` block. type SrvConf: Merge + Default; + /// Configuration in a `location` block within the `http` block. type LocConf: Merge + Default; /// # Safety diff --git a/src/http/request.rs b/src/http/request.rs index 88607fd..ba0e03f 100644 --- a/src/http/request.rs +++ b/src/http/request.rs @@ -149,6 +149,9 @@ impl Request { Some(co) } + /// Sets the value as the module's context. + /// + /// See https://nginx.org/en/docs/dev/development_guide.html#http_request pub fn set_module_ctx(&self, value: *mut c_void, module: &ngx_module_t) { unsafe { *self.0.ctx.add(module.ctx_index) = value; @@ -191,11 +194,17 @@ impl Request { self.0.headers_out.status = status.into(); } + /// Add header to the `headers_in` object. + /// + /// See https://nginx.org/en/docs/dev/development_guide.html#http_request pub fn add_header_in(&mut self, key: &str, value: &str) -> Option<()> { let table: *mut ngx_table_elt_t = unsafe { ngx_list_push(&mut self.0.headers_in.headers) as _ }; add_to_ngx_table(table, self.0.pool, key, value) } + /// Add header to the `headers_out` object. + /// + /// See https://nginx.org/en/docs/dev/development_guide.html#http_request pub fn add_header_out(&mut self, key: &str, value: &str) -> Option<()> { let table: *mut ngx_table_elt_t = unsafe { ngx_list_push(&mut self.0.headers_out.headers) as _ }; add_to_ngx_table(table, self.0.pool, key, value) @@ -340,6 +349,9 @@ impl fmt::Debug for Request { } } +/// Iterator for `ngx_list_t` types. +/// +/// Implementes the std::iter::Iterator trait. pub struct NgxListIterator { done: bool, part: *const ngx_list_part_t, @@ -459,6 +471,7 @@ impl Method { /// CONNECT pub const CONNECT: Method = Method(MethodInner::Connect); + /// Convert a Method to a &str. #[inline] pub fn as_str(&self) -> &str { match self.0 { diff --git a/src/http/status.rs b/src/http/status.rs index cf02150..0465587 100644 --- a/src/http/status.rs +++ b/src/http/status.rs @@ -49,6 +49,7 @@ impl fmt::Debug for HTTPStatus { } impl HTTPStatus { + /// Convets a u16 to a status code. #[inline] pub fn from_u16(src: u16) -> Result { if !(100..600).contains(&src) { @@ -58,7 +59,7 @@ impl HTTPStatus { Ok(HTTPStatus(src.into())) } - /// Converts a &[u8] to a status code + /// Converts a &[u8] to a status code. pub fn from_bytes(src: &[u8]) -> Result { if src.len() != 3 { return Err(InvalidHTTPStatusCode::new()); diff --git a/src/lib.rs b/src/lib.rs index a2d50b9..8059f76 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -33,9 +33,27 @@ //! ``` #![warn(missing_docs)] +/// 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. pub mod http; + +/// The log module. +/// +/// This module provides an interface into the NGINX logger framework. pub mod log; /// Define modules exported by this library. diff --git a/tests/log_test.rs b/tests/log_test.rs index b5a1858..af6efef 100644 --- a/tests/log_test.rs +++ b/tests/log_test.rs @@ -65,7 +65,7 @@ impl Nginx { // make sure we stop existing nginx and start new master process // intentinally ignore failure in stop pub fn restart(&mut self) -> Result { - self.stop(); + let _ = self.stop(); self.start() }