wordval-web 1.0.13

Wordval web layer: router, middleware, extractors, responses, session-based authentication
Documentation
//! 请求级租户上下文(task-local + extensions 双通道)
//!
//! 租户解析与认证解耦,由 [`tenant_context_layer`] 独立完成:
//! - **已登录普通用户**:以会话 `CurrentUser.tenant_id` 为唯一准绳,
//!   租户头(默认 `X-Tenant-Id`,可配 `middleware.tenant_header`)不得覆盖,
//!   避免登录用户带头越权访问其他租户;
//!   会话未绑定租户(数据错误)时返回 `None`,不接受客户端声明;
//! - **平台管理员**(`is_admin_user()`):会话无租户绑定,可用
//!   租户头显式切换目标租户;
//! - **未登录请求**(如登录接口本身):允许读取租户头指定目标租户。
//!
//! 无论是否登录、是否命中 ignore 路径,该层都会为所有请求建立
//! `TENANT` task-local scope,业务侧通过 `current_tenant_id()` 安全读取。

use axum::body::Body;
use axum::extract::Request;
use axum::http::HeaderName;
use axum::middleware::Next;
use axum::response::Response;
use std::future::Future;
use std::sync::OnceLock;
use tokio::task_local;

use crate::middleware::CurrentUser;
use wordval_core::api::ApiError;
use wordval_core::error_registry::{error_message_of, ErrorCode};

/// 租户头名全局单例:App 启动时从 `middleware.tenant_header` 配置初始化,
/// 未初始化时回退默认 `x-tenant-id`(提取器在测试等无 App 场景下可用)。
static TENANT_HEADER: OnceLock<HeaderName> = OnceLock::new();

/// 设置租户头名;非法 HTTP 头名返回错误,调用方应 fail-fast。
/// 相同值重复设置为幂等;已初始化为不同值时返回错误。
pub fn set_tenant_header(name: &str) -> std::result::Result<(), String> {
    let parsed: HeaderName = name
        .trim()
        .parse()
        .map_err(|e| format!("middleware.tenant_header 非法头名 '{}': {}", name, e))?;
    match TENANT_HEADER.get() {
        Some(existing) if existing == parsed => Ok(()),
        Some(existing) => Err(format!(
            "租户头名已初始化为 '{}',不能改为 '{}'",
            existing, parsed
        )),
        None => TENANT_HEADER
            .set(parsed)
            .map_err(|_| "租户头名重复设置".to_string()),
    }
}

/// 当前生效的租户标识请求头名
pub fn tenant_header() -> &'static HeaderName {
    TENANT_HEADER.get_or_init(|| HeaderName::from_static("x-tenant-id"))
}

task_local! {
    /// 请求级租户上下文
    static TENANT: TenantContext;
}

/// 租户上下文(同时注入 request extensions 供提取器读取)
///
/// 内部载体类型:业务侧统一通过 [`crate::TenantId`] 提取器或
/// [`current_tenant_id`] 读取租户,不直接提取本类型,避免多条
/// 读租户路径并存。
#[derive(Clone, Copy, Debug, Default)]
pub(crate) struct TenantContext {
    /// 当前请求的租户 ID(`None` 表示未注入 / 系统默认)
    pub tenant_id: Option<i64>,
}

/// 读取当前请求的租户 ID
///
/// 未建立 task-local scope(如中间件链之外调用)时安全返回 `None`,不会 panic。
pub fn current_tenant_id() -> Option<i64> {
    TENANT.try_with(|t| t.tenant_id).ok().flatten()
}

/// 读取当前请求的租户 ID,未注入则返回 403
pub fn require_tenant_id() -> std::result::Result<i64, ApiError> {
    current_tenant_id().ok_or_else(|| ApiError::forbidden(error_message_of(ErrorCode::Forbidden)))
}

/// 从租户头(默认 `X-Tenant-Id`,可配)读取目标租户 ID
fn read_tenant_header(req: &Request<Body>) -> Option<i64> {
    req.headers()
        .get(tenant_header())
        .and_then(|v| v.to_str().ok())
        .and_then(|s| s.trim().parse::<i64>().ok())
}

/// 解析租户 ID(区分管理员与普通用户,防止客户端声明的租户头越权):
/// - 普通登录用户:以会话租户为唯一准绳,忽略租户头;
/// - 平台管理员:会话无绑定时允许用租户头显式选择目标租户;
/// - 未登录:允许用租户头指定目标租户(如登录接口)。
pub fn resolve_tenant(req: &Request<Body>, session: Option<&CurrentUser>) -> Option<i64> {
    match session {
        Some(u) if u.is_admin_user() => u.tenant_id.or_else(|| read_tenant_header(req)),
        Some(u) => u.tenant_id,
        None => read_tenant_header(req),
    }
}

/// 在指定租户上下文中运行 future(task-local scope)
pub async fn with_tenant<F, T>(tenant_id: Option<i64>, fut: F) -> T
where
    F: Future<Output = T>,
{
    let ctx = TenantContext { tenant_id };
    TENANT.scope(ctx, fut).await
}

/// 租户上下文中间件(from_fn,无状态)
///
/// 身份解析之后、路由策略之前执行:无论请求是否登录、是否公开,
/// 都解析出租户并同时注入 task-local scope 与 request extensions,
/// 保证 `current_tenant_id()` / `TenantId` 提取器在任意路由上都有确定结果。
pub async fn tenant_context_layer(mut req: Request, next: Next) -> Response {
    // 借用 extensions 解析租户(Option<i64> 为 Copy),避免克隆整个 CurrentUser
    let tenant_id = resolve_tenant(&req, req.extensions().get::<CurrentUser>());
    let ctx = TenantContext { tenant_id };
    req.extensions_mut().insert(ctx);
    with_tenant(tenant_id, next.run(req)).await
}