ngx/http/
module.rs

1use core::error;
2use core::ffi::{c_char, c_void};
3use core::fmt;
4use core::ptr;
5
6use crate::core::NGX_CONF_ERROR;
7use crate::core::*;
8use crate::ffi::*;
9
10/// MergeConfigError - configuration cannot be merged with levels above.
11#[derive(Debug)]
12pub enum MergeConfigError {
13    /// No value provided for configuration argument
14    NoValue,
15}
16
17impl error::Error for MergeConfigError {}
18
19impl fmt::Display for MergeConfigError {
20    fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
21        match self {
22            MergeConfigError::NoValue => "no value".fmt(fmt),
23        }
24    }
25}
26
27/// The `Merge` trait provides a method for merging configuration down through each level.
28///
29/// A module configuration should implement this trait for setting its configuration throughout
30/// each level.
31pub trait Merge {
32    /// Module merge function.
33    ///
34    /// # Returns
35    /// Result, Ok on success or MergeConfigError on failure.
36    fn merge(&mut self, prev: &Self) -> Result<(), MergeConfigError>;
37}
38
39impl Merge for () {
40    fn merge(&mut self, _prev: &Self) -> Result<(), MergeConfigError> {
41        Ok(())
42    }
43}
44
45/// The `HTTPModule` trait provides the NGINX configuration stage interface.
46///
47/// These functions allocate structures, initialize them, and merge through the configuration
48/// layers.
49///
50/// See <https://nginx.org/en/docs/dev/development_guide.html#adding_new_modules> for details.
51pub trait HttpModule {
52    /// Returns reference to a global variable of type [ngx_module_t] created for this module.
53    fn module() -> &'static ngx_module_t;
54
55    /// # Safety
56    ///
57    /// Callers should provide valid non-null `ngx_conf_t` arguments. Implementers must
58    /// guard against null inputs or risk runtime errors.
59    unsafe extern "C" fn preconfiguration(_cf: *mut ngx_conf_t) -> ngx_int_t {
60        Status::NGX_OK.into()
61    }
62
63    /// # Safety
64    ///
65    /// Callers should provide valid non-null `ngx_conf_t` arguments. Implementers must
66    /// guard against null inputs or risk runtime errors.
67    unsafe extern "C" fn postconfiguration(_cf: *mut ngx_conf_t) -> ngx_int_t {
68        Status::NGX_OK.into()
69    }
70
71    /// # Safety
72    ///
73    /// Callers should provide valid non-null `ngx_conf_t` arguments. Implementers must
74    /// guard against null inputs or risk runtime errors.
75    unsafe extern "C" fn create_main_conf(cf: *mut ngx_conf_t) -> *mut c_void
76    where
77        Self: super::HttpModuleMainConf,
78        Self::MainConf: Default,
79    {
80        let mut pool = Pool::from_ngx_pool((*cf).pool);
81        pool.allocate::<Self::MainConf>(Default::default()) as *mut c_void
82    }
83
84    /// # Safety
85    ///
86    /// Callers should provide valid non-null `ngx_conf_t` arguments. Implementers must
87    /// guard against null inputs or risk runtime errors.
88    unsafe extern "C" fn init_main_conf(_cf: *mut ngx_conf_t, _conf: *mut c_void) -> *mut c_char
89    where
90        Self: super::HttpModuleMainConf,
91        Self::MainConf: Default,
92    {
93        ptr::null_mut()
94    }
95
96    /// # Safety
97    ///
98    /// Callers should provide valid non-null `ngx_conf_t` arguments. Implementers must
99    /// guard against null inputs or risk runtime errors.
100    unsafe extern "C" fn create_srv_conf(cf: *mut ngx_conf_t) -> *mut c_void
101    where
102        Self: super::HttpModuleServerConf,
103        Self::ServerConf: Default,
104    {
105        let mut pool = Pool::from_ngx_pool((*cf).pool);
106        pool.allocate::<Self::ServerConf>(Default::default()) as *mut c_void
107    }
108
109    /// # Safety
110    ///
111    /// Callers should provide valid non-null `ngx_conf_t` arguments. Implementers must
112    /// guard against null inputs or risk runtime errors.
113    unsafe extern "C" fn merge_srv_conf(
114        _cf: *mut ngx_conf_t,
115        prev: *mut c_void,
116        conf: *mut c_void,
117    ) -> *mut c_char
118    where
119        Self: super::HttpModuleServerConf,
120        Self::ServerConf: Merge,
121    {
122        let prev = &mut *(prev as *mut Self::ServerConf);
123        let conf = &mut *(conf as *mut Self::ServerConf);
124        match conf.merge(prev) {
125            Ok(_) => ptr::null_mut(),
126            Err(_) => NGX_CONF_ERROR as _,
127        }
128    }
129
130    /// # Safety
131    ///
132    /// Callers should provide valid non-null `ngx_conf_t` arguments. Implementers must
133    /// guard against null inputs or risk runtime errors.
134    unsafe extern "C" fn create_loc_conf(cf: *mut ngx_conf_t) -> *mut c_void
135    where
136        Self: super::HttpModuleLocationConf,
137        Self::LocationConf: Default,
138    {
139        let mut pool = Pool::from_ngx_pool((*cf).pool);
140        pool.allocate::<Self::LocationConf>(Default::default()) as *mut c_void
141    }
142
143    /// # Safety
144    ///
145    /// Callers should provide valid non-null `ngx_conf_t` arguments. Implementers must
146    /// guard against null inputs or risk runtime errors.
147    unsafe extern "C" fn merge_loc_conf(
148        _cf: *mut ngx_conf_t,
149        prev: *mut c_void,
150        conf: *mut c_void,
151    ) -> *mut c_char
152    where
153        Self: super::HttpModuleLocationConf,
154        Self::LocationConf: Merge,
155    {
156        let prev = &mut *(prev as *mut Self::LocationConf);
157        let conf = &mut *(conf as *mut Self::LocationConf);
158        match conf.merge(prev) {
159            Ok(_) => ptr::null_mut(),
160            Err(_) => NGX_CONF_ERROR as _,
161        }
162    }
163}
ngx/http/module.rs

ngx/http/
module.rs
