feat: request handler trait

Author: ensh63

examples/curl.rs

@@ -2,13 +2,14 @@ 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, HttpHandlerRegistrar, HttpModule, HttpModuleLocationConf, HttpRequestHandler,
+    MergeConfigError,
+};
+use ngx::{ngx_conf_log_error, ngx_log_debug_http, ngx_string};
 
 struct Module;
 
@@ -17,20 +18,9 @@ impl http::HttpModule for Module {
         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);
-        core::Status::NGX_OK.into()
+    #[allow(refining_impl_trait)]
+    fn request_handler_registrars() -> impl Iterator<Item = fn(&mut ngx_conf_t) -> bool> {
+        ::core::iter::once(CurlRequestHandler::register as _)
     }
 }
 
@@ -90,25 +80,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;
 
-    ngx_log_debug_http!(request, "curl module enabled: {}", co.enable);
+impl HttpRequestHandler<Option<ngx_int_t>> for CurlRequestHandler {
+    const PHASE: nginx_sys::NgxHttpPhases = nginx_sys::NgxHttpPhases::Access;
+    type Module = Module;
 
-    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
+    fn handler(request: &mut http::Request) -> Option<ngx_int_t> {
+        let co = Module::location_conf(request).expect("module config is none");
+
+        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/module.rs

@@ -52,22 +52,43 @@ pub trait HttpModule {
     /// Returns reference to a global variable of type [ngx_module_t] created for this module.
     fn module() -> &'static ngx_module_t;
 
+    /// Returns an iterator over request handler registrar functions provided by this module.
+    fn request_handler_registrars() -> impl Iterator<Item = fn(&mut ngx_conf_t) -> bool> {
+        core::iter::empty()
+    }
+
+    /// Register all request handlers provided by this module.
+    ///
     /// # Safety
     ///
     /// Callers should provide valid non-null `ngx_conf_t` arguments. Implementers must
     /// guard against null inputs or risk runtime errors.
-    unsafe extern "C" fn preconfiguration(_cf: *mut ngx_conf_t) -> ngx_int_t {
+    unsafe fn register_request_handlers(cf: *mut ngx_conf_t) -> ngx_int_t {
+        let cf = unsafe { &mut *cf };
+        for registrar in Self::request_handler_registrars() {
+            if !registrar(cf) {
+                return Status::NGX_ERROR.into();
+            }
+        }
         Status::NGX_OK.into()
     }
 
     /// # Safety
     ///
     /// Callers should provide valid non-null `ngx_conf_t` arguments. Implementers must
     /// guard against null inputs or risk runtime errors.
-    unsafe extern "C" fn postconfiguration(_cf: *mut ngx_conf_t) -> ngx_int_t {
+    unsafe extern "C" fn preconfiguration(_cf: *mut ngx_conf_t) -> ngx_int_t {
         Status::NGX_OK.into()
     }
 
+    /// # Safety
+    ///
+    /// Callers should provide valid non-null `ngx_conf_t` arguments. Implementers must
+    /// guard against null inputs or risk runtime errors.
+    unsafe extern "C" fn postconfiguration(cf: *mut ngx_conf_t) -> ngx_int_t {
+        Self::register_request_handlers(cf)
+    }
+
     /// # Safety
     ///
     /// Callers should provide valid non-null `ngx_conf_t` arguments. Implementers must

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,77 @@ 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;
+}
+
+trait HttpHandlerInternal<ReturnType>: HttpRequestHandler<ReturnType> {
+    fn convert(r: &Request, res: ReturnType) -> ngx_int_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)
+    }
+}
+
+impl<T> HttpHandlerInternal<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 _)
+    }
+}
+
+impl<T, E> HttpHandlerInternal<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 _
+        })
+    }
+}
+
+/// Trait for registering a request handler.
+pub trait HttpHandlerRegistrar<ReturnType> {
+    /// Register a request handler for a specified phase.
+    fn register(cf: &mut ngx_conf_t) -> bool;
+}
+
+impl<T, ReturnType> HttpHandlerRegistrar<ReturnType> for T
+where
+    T: HttpHandlerInternal<ReturnType>,
+{
+    fn register(cf: &mut ngx_conf_t) -> bool {
+        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
+    }
+}
+
 /// Wrapper struct for an [`ngx_http_request_t`] pointer, providing methods for working with HTTP
 /// requests.
 ///