feat: request handler trait

Author: ensh63

examples/curl.rs

@@ -2,34 +2,21 @@ use std::ffi::{c_char, c_void};
 
 use ngx::core;
 use ngx::ffi::{
-    ngx_array_push, ngx_command_t, ngx_conf_t, ngx_http_handler_pt, ngx_http_module_t,
-    ngx_http_phases_NGX_HTTP_ACCESS_PHASE, ngx_int_t, ngx_module_t, ngx_str_t, ngx_uint_t,
+    ngx_command_t, ngx_conf_t, ngx_http_module_t, ngx_int_t, ngx_module_t, ngx_str_t, ngx_uint_t,
     NGX_CONF_TAKE1, NGX_HTTP_LOC_CONF, NGX_HTTP_LOC_CONF_OFFSET, NGX_HTTP_MODULE, NGX_LOG_EMERG,
 };
-use ngx::http::{self, HttpModule, MergeConfigError};
-use ngx::http::{HttpModuleLocationConf, HttpModuleMainConf, NgxHttpCoreModule};
-use ngx::{http_request_handler, ngx_conf_log_error, ngx_log_debug_http, ngx_string};
+use ngx::http::{self, HttpModule, HttpModuleLocationConf, HttpRequestHandler, MergeConfigError};
+use ngx::{ngx_conf_log_error, ngx_log_debug_http, ngx_string};
 
 struct Module;
 
 impl http::HttpModule for Module {
     fn module() -> &'static ngx_module_t {
         unsafe { &*::core::ptr::addr_of!(ngx_http_curl_module) }
     }
-
     unsafe extern "C" fn postconfiguration(cf: *mut ngx_conf_t) -> ngx_int_t {
-        // SAFETY: this function is called with non-NULL cf always
-        let cf = &mut *cf;
-        let cmcf = NgxHttpCoreModule::main_conf_mut(cf).expect("http core main conf");
-
-        let h = ngx_array_push(
-            &mut cmcf.phases[ngx_http_phases_NGX_HTTP_ACCESS_PHASE as usize].handlers,
-        ) as *mut ngx_http_handler_pt;
-        if h.is_null() {
-            return core::Status::NGX_ERROR.into();
-        }
-        // set an Access phase handler
-        *h = Some(curl_access_handler);
+        let cf = unsafe { &mut *cf };
+        CurlRequestHandler::register(cf);
         core::Status::NGX_OK.into()
     }
 }
@@ -90,25 +77,32 @@ impl http::Merge for ModuleConfig {
     }
 }
 
-http_request_handler!(curl_access_handler, |request: &mut http::Request| {
-    let co = Module::location_conf(request).expect("module config is none");
+struct CurlRequestHandler;
+
+impl HttpRequestHandler<Option<ngx_int_t>> for CurlRequestHandler {
+    const PHASE: nginx_sys::NgxHttpPhases = nginx_sys::NgxHttpPhases::Access;
+    type Module = Module;
 
-    ngx_log_debug_http!(request, "curl module enabled: {}", co.enable);
+    fn handler(request: &mut http::Request) -> Option<ngx_int_t> {
+        let co = Module::location_conf(request).expect("module config is none");
 
-    match co.enable {
-        true => {
-            if request
-                .user_agent()
-                .is_some_and(|ua| ua.as_bytes().starts_with(b"curl"))
-            {
-                http::HTTPStatus::FORBIDDEN.into()
-            } else {
-                core::NGX_O_DECLINED
+        ngx_log_debug_http!(request, "curl module enabled: {}", co.enable);
+
+        match co.enable {
+            true => {
+                if request
+                    .user_agent()
+                    .is_some_and(|ua| ua.as_bytes().starts_with(b"curl"))
+                {
+                    http::HTTPStatus::FORBIDDEN.into()
+                } else {
+                    core::NGX_O_DECLINED
+                }
             }
+            false => core::NGX_O_DECLINED,
         }
-        false => core::NGX_O_DECLINED,
     }
-});
+}
 
 extern "C" fn ngx_http_curl_commands_set_enable(
     cf: *mut ngx_conf_t,

nginx-sys/src/http.rs

@@ -16,3 +16,30 @@ pub const NGX_HTTP_SRV_CONF_OFFSET: usize = offset_of!(ngx_http_conf_ctx_t, srv_
 ///
 /// This is used to access the location configuration context for an HTTP module.
 pub const NGX_HTTP_LOC_CONF_OFFSET: usize = offset_of!(ngx_http_conf_ctx_t, loc_conf);
+
+/// HTTP phases in which a module can register handlers.
+#[repr(u32)]
+pub enum NgxHttpPhases {
+    /// Post-read phase
+    PostRead = crate::ngx_http_phases_NGX_HTTP_POST_READ_PHASE,
+    /// Server rewrite phase
+    ServerRewrite = crate::ngx_http_phases_NGX_HTTP_SERVER_REWRITE_PHASE,
+    /// Find configuration phase
+    FindConfig = crate::ngx_http_phases_NGX_HTTP_FIND_CONFIG_PHASE,
+    /// Rewrite phase
+    Rewrite = crate::ngx_http_phases_NGX_HTTP_REWRITE_PHASE,
+    /// Post-rewrite phase
+    PostRewrite = crate::ngx_http_phases_NGX_HTTP_POST_REWRITE_PHASE,
+    /// Pre-access phase
+    Preaccess = crate::ngx_http_phases_NGX_HTTP_PREACCESS_PHASE,
+    /// Access phase
+    Access = crate::ngx_http_phases_NGX_HTTP_ACCESS_PHASE,
+    /// Post-access phase
+    PostAccess = crate::ngx_http_phases_NGX_HTTP_POST_ACCESS_PHASE,
+    /// Pre-content phase
+    PreContent = crate::ngx_http_phases_NGX_HTTP_PRECONTENT_PHASE,
+    /// Content phase
+    Content = crate::ngx_http_phases_NGX_HTTP_CONTENT_PHASE,
+    /// Log phase
+    Log = crate::ngx_http_phases_NGX_HTTP_LOG_PHASE,
+}

src/http/request.rs

@@ -10,6 +10,7 @@ use allocator_api2::alloc::Allocator;
 use crate::core::*;
 use crate::ffi::*;
 use crate::http::status::*;
+use crate::http::{HttpModule, HttpModuleMainConf, NgxHttpCoreModule};
 
 /// Define a static request handler.
 ///
@@ -89,6 +90,78 @@ macro_rules! http_variable_get {
     };
 }
 
+/// Trait for static request handler.
+/// Predefined return types are `Option<ngx_int_t>`
+/// and `Result<ngx_int_t, E>` where `E: ::core::error::Error`.
+/// Handler with `Result<ngx_int_t, E>` return type logs the error message automatically.
+pub trait HttpRequestHandler<ReturnType> {
+    /// The phase in which the handler is invoked
+    const PHASE: NgxHttpPhases;
+    /// The module to which the handler belongs
+    type Module: HttpModule;
+
+    /// The handler function
+    fn handler(request: &mut Request) -> ReturnType;
+    /// Register a request handler for a specified phase.
+    /// This function must be called from the module's `postconfiguration()` function.
+    fn register(cf: &mut ngx_conf_t) -> bool
+    where
+        Self: HttpHandlerWrapper<ReturnType>,
+    {
+        let cmcf = NgxHttpCoreModule::main_conf_mut(cf).expect("http core main conf");
+        let h: *mut ngx_http_handler_pt =
+            unsafe { ngx_array_push(&mut cmcf.phases[Self::PHASE as usize].handlers) as _ };
+        if h.is_null() {
+            return false;
+        }
+        // set an H::PHASE phase handler
+        unsafe {
+            *h = Some(Self::handler_wrapper);
+        }
+        true
+    }
+}
+
+/// Trait for wrapping a request handler with a C-compatible function.
+pub trait HttpHandlerWrapper<ReturnType>: HttpRequestHandler<ReturnType> {
+    /// Convert the handler return type to `ngx_int_t`.
+    fn convert(r: &Request, res: ReturnType) -> ngx_int_t;
+    /// The C-compatible handler wrapper function.
+    ///
+    /// # Safety
+    ///
+    /// The caller has provided a valid non-null pointer to an `ngx_http_request_t`.
+    unsafe extern "C" fn handler_wrapper(r: *mut ngx_http_request_t) -> ngx_int_t {
+        let r = unsafe { Request::from_ngx_http_request(r) };
+        let res = Self::handler(r);
+        Self::convert(r, res)
+    }
+}
+
+/// Implementation of `HttpHandlerWrapper` for `Option<ngx_int_t>`.
+impl<T> HttpHandlerWrapper<Option<ngx_int_t>> for T
+where
+    T: HttpRequestHandler<Option<ngx_int_t>>,
+{
+    fn convert(_r: &Request, res: Option<ngx_int_t>) -> ngx_int_t {
+        res.unwrap_or(NGX_ERROR as _)
+    }
+}
+
+/// Implementation of `HttpHandlerWrapper` for `Result<ngx_int_t, E>`.
+impl<T, E> HttpHandlerWrapper<Result<ngx_int_t, E>> for T
+where
+    T: HttpRequestHandler<Result<ngx_int_t, E>>,
+    E: ::core::error::Error,
+{
+    fn convert(r: &Request, res: Result<ngx_int_t, E>) -> ngx_int_t {
+        res.unwrap_or_else(|err| {
+            crate::ngx_log_error!(NGX_LOG_ERR, r.log(), "{err}");
+            NGX_ERROR as _
+        })
+    }
+}
+
 /// Wrapper struct for an [`ngx_http_request_t`] pointer, providing methods for working with HTTP
 /// requests.
 ///