wordval-web 1.0.13

Wordval web layer: router, middleware, extractors, responses, session-based authentication
Documentation
//! 中间件链装配:优先级注册表
//!
//! 语义约定:**priority 数值越小越靠外(越早执行)**。
//! 装配时按 priority 升序稳定排序后反向依次 `router.layer(...)`——
//! Tower 中后添加的 layer 位于更外层,因此最小优先级最后添加、处于最外。
//!
//! 内置中间件的默认优先级见 [`priorities`],与历史写死顺序等价;
//! 用户可通过 `App::middleware(name, priority, apply)` 按数值插入自定义层。

use axum::Router;

/// 中间件条目:名称 + 优先级 + 套层闭包
pub struct MiddlewareEntry {
    /// 中间件名称(启动日志与排查用)
    pub name: String,
    /// 优先级,数值越小越靠外(越早执行)
    pub priority: i32,
    /// 套层闭包:接收当前 Router,返回套层后的 Router
    pub apply: Box<dyn FnOnce(Router) -> Router + Send>,
}

impl MiddlewareEntry {
    pub fn new(
        name: impl Into<String>,
        priority: i32,
        apply: impl FnOnce(Router) -> Router + Send + 'static,
    ) -> Self {
        Self {
            name: name.into(),
            priority,
            apply: Box::new(apply),
        }
    }
}

/// 内置中间件默认优先级(数值越小越靠外)
///
/// 该顺序带有安全语义(如 RequestId 最外覆盖所有短路响应、
/// ClientIdentity 必须在限流/日志外侧先注入已解析 IP),
/// 调整内置优先级或插入自定义层时请理解各层的依赖关系。
pub mod priorities {
    /// 请求 ID:最外层,覆盖所有短路响应
    pub const REQUEST_ID: i32 = 0;
    /// 客户端身份:统一解析可信 client IP,供日志/限流/nonce 读取
    pub const CLIENT_IDENTITY: i32 = 10;
    /// 访问日志:记录全部响应(含短路)
    pub const REQUEST_LOG: i32 = 20;
    /// 安全响应头:所有响应都携带
    pub const SECURITY_HEADERS: i32 = 30;
    /// CORS:业务保护层外侧(预检短路时仍被外壳层覆盖)
    pub const CORS: i32 = 40;
    /// 响应压缩
    pub const COMPRESSION: i32 = 50;
    /// 请求体限额:按 `upload.max_size_mb` 装配 DefaultBodyLimit,
    /// 取代 axum 隐式 2MB 上限(提取器级限制,位置不影响生效)
    pub const BODY_LIMIT: i32 = 55;
    /// IP 滑动窗口限流:读取 ClientIdentity 注入的 ClientIp
    pub const RATE_LIMIT: i32 = 60;
    /// 身份解析(可选认证):有 token 则注入 CurrentUser
    pub const SESSION_RESOLVER: i32 = 70;
    /// 租户上下文:建立 task-local scope
    pub const TENANT_CONTEXT: i32 = 80;
    /// 操作审计:位于身份/租户层之内、认证/权限层之外,
    /// 因此既能读到 CurrentUser 与租户,也能看到认证/鉴权短路的 401/403 响应
    pub const AUDIT: i32 = 85;
    /// 强制登录:检查 extensions 中的 CurrentUser
    pub const REQUIRE_AUTH: i32 = 90;
    /// 路径权限校验
    pub const PERMISSION_CHECK: i32 = 100;
    /// Nonce 防重放:最内层,绑定 CurrentUser
    pub const NONCE: i32 = 110;
}

/// 装配中间件链:按 priority 升序稳定排序(同优先级保持注册序,
/// 先注册者在更外层),随后反向依次套层(Tower 后加的层在外侧,
/// 因此优先级最大的最先套、位于最内)。
///
/// 返回最终 Router 与装配顺序(外 -> 内)的名称列表,供启动日志输出。
pub fn apply_chain(mut router: Router, mut entries: Vec<MiddlewareEntry>) -> (Router, Vec<String>) {
    entries.sort_by_key(|e| e.priority);
    let order: Vec<String> = entries
        .iter()
        .map(|e| format!("{}({})", e.name, e.priority))
        .collect();
    for entry in entries.into_iter().rev() {
        router = (entry.apply)(router);
    }
    (router, order)
}

#[cfg(test)]
mod tests {
    use super::*;

    /// 乱序注册三个 from_fn 层,验证按优先级排序后外层先执行
    #[test]
    fn chain_applies_smaller_priority_outermost() {
        use std::sync::{Arc, Mutex};

        let order: Arc<Mutex<Vec<&'static str>>> = Arc::new(Mutex::new(Vec::new()));

        let mk = |name: &'static str, priority: i32| {
            let order = order.clone();
            MiddlewareEntry::new(name, priority, move |r: Router| {
                let o = order.clone();
                r.layer(axum::middleware::from_fn(
                    move |req: axum::extract::Request, next: axum::middleware::Next| {
                        let o = o.clone();
                        async move {
                            o.lock().unwrap().push(name);
                            next.run(req).await
                        }
                    },
                ))
            })
        };

        // 乱序注册:验证按优先级排序而非注册序
        let entries = vec![mk("inner", 900), mk("outer", 0), mk("mid", 500)];
        let (router, names) = apply_chain(Router::new(), entries);
        assert_eq!(names, vec!["outer(0)", "mid(500)", "inner(900)"]);

        let rt = tokio::runtime::Builder::new_current_thread()
            .enable_all()
            .build()
            .unwrap();
        rt.block_on(async {
            use tower::ServiceExt;
            let req = axum::http::Request::builder()
                .uri("/")
                .body(axum::body::Body::empty())
                .unwrap();
            let _ = router.oneshot(req).await.unwrap();
        });
        // 外层先执行
        assert_eq!(*order.lock().unwrap(), vec!["outer", "mid", "inner"]);
    }

    #[test]
    fn same_priority_keeps_registration_order() {
        let entries = vec![
            MiddlewareEntry::new("a", 100, |r| r),
            MiddlewareEntry::new("b", 100, |r| r),
            MiddlewareEntry::new("c", 50, |r| r),
        ];
        let (_router, names) = apply_chain(Router::new(), entries);
        assert_eq!(names, vec!["c(50)", "a(100)", "b(100)"]);
    }
}