feat: request handler trait

Author: ensh63

examples/curl.rs

@@ -2,13 +2,12 @@ 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_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::HttpModuleLocationConf;
+use ngx::http::{self, HttpModule, MergeConfigError, RequestHandler};
+use ngx::{ngx_conf_log_error, ngx_log_debug_http, ngx_string};
 
 struct Module;
 
@@ -17,20 +16,8 @@ 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()
+    fn request_handlers() -> impl Iterator<Item = impl RequestHandler<Module = Self>> {
+        ::core::iter::once(CurlRequestHandler)
     }
 }
 
@@ -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 RequestHandler 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) -> ngx::core::NgxResult {
+        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::Status::NGX_DECLINED.into()
+        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::Status::NGX_DECLINED.into()
+                }
             }
+            false => core::Status::NGX_DECLINED.into(),
         }
-        false => core::Status::NGX_DECLINED.into(),
     }
-});
+}
 
 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

@@ -6,6 +6,7 @@ use core::ptr;
 use crate::core::NGX_CONF_ERROR;
 use crate::core::*;
 use crate::ffi::*;
+use crate::http::RequestHandler;
 
 /// MergeConfigError - configuration cannot be merged with levels above.
 #[derive(Debug)]
@@ -52,22 +53,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 handlers provided by this module.
+    fn request_handlers() -> impl Iterator<Item = impl RequestHandler<Module = Self>> {
+        // returns empty iterator by default
+        core::iter::empty::<super::EmptyHandler<Self>>()
+    }
+    /// 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 rh in Self::request_handlers() {
+            if !rh.register(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

@@ -1,6 +1,7 @@
 use core::error;
 use core::ffi::c_void;
 use core::fmt;
+use core::marker::PhantomData;
 use core::ptr::NonNull;
 use core::slice;
 use core::str::FromStr;
@@ -10,6 +11,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 +91,49 @@ macro_rules! http_variable_get {
     };
 }
 
+/// Trait for static request handler.
+pub trait RequestHandler {
+    /// The phase in which the handler is invoked
+    const PHASE: NgxHttpPhases;
+    /// The module to which the handler belongs
+    type Module: HttpModule + ?Sized;
+    /// The handler function
+    fn handler(request: &mut Request) -> NgxResult;
+    /// Wrapper for the handler function to match the C function signature
+    ///
+    /// # Safety
+    /// The caller must provide 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 res: NgxResult = Self::handler(unsafe { Request::from_ngx_http_request(r) });
+        res.unwrap_or_else(|_| Status::NGX_ERROR.into())
+    }
+    /// Register a request handler for a specified phase.
+    fn register(&self, 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
+    }
+}
+
+pub(crate) struct EmptyHandler<M: HttpModule + ?Sized>(PhantomData<M>);
+
+impl<M: HttpModule + ?Sized> RequestHandler for EmptyHandler<M> {
+    const PHASE: NgxHttpPhases = NgxHttpPhases::Access;
+    type Module = M;
+
+    fn handler(_request: &mut Request) -> NgxResult {
+        Status::NGX_OK.into()
+    }
+}
+
 /// Wrapper struct for an [`ngx_http_request_t`] pointer, providing methods for working with HTTP
 /// requests.
 ///