garrison 0.9.0

Garrison - 面向 Rust 生态的一站式身份认证鉴权框架
Documentation
//! 匿名 Session 模块(启用 `anonymous-session` feature 后编译)。
//!
//! 为未登录用户提供匿名会话支持(购物车、访客浏览等),使用独立 key 空间 `token:session:anon:{sha256(token)}`
//! 与登录 Session 隔离:login_id 为空字符串,不参与 `login_token_map`。
use super::sha256_hex;
use super::{GarrisonSession, TokenSession};
use crate::constants::DaoKeyPrefix;
use crate::error::{GarrisonError, GarrisonResult};
use chrono::Utc;
use std::collections::HashMap;

/// 生成匿名 Token-Session 的存储 key(格式 `token:session:anon:{sha256(token)}`)。
///
/// 余段为 token 的 SHA-256 摘要:裸 bearer 凭据不得留在落库 key 名(与登录会话同一原则);
/// 升级即存量匿名会话一次性失效(旧 raw key 行不再被寻址,客户端重新获取匿名 token)。
fn anon_token_key(token: &str) -> String {
    format!("{}session:anon:{}", DaoKeyPrefix::Token, sha256_hex(token))
}

/// 校验匿名 token 输入:拒绝空字符串和超长 token(>128 字节),防止 DoS 和语义混淆。
fn validate_anon_token(token: &str) -> GarrisonResult<()> {
    if token.is_empty() {
        return Err(GarrisonError::InvalidParam(
            "session-token-empty::".to_string(),
        ));
    }
    if token.len() > 128 {
        return Err(GarrisonError::InvalidParam(
            "session-token-too-long::".to_string(),
        ));
    }
    Ok(())
}

/// 获取匿名 Token-Session,不存在则创建。
///
/// 首次调用创建匿名 Session(`login_id = ""`, `is_anon = true`)并存储到 DAO,后续返回已存在 Session;
/// TTL 由 `anon_session_timeout` 控制。
pub async fn get_anon_token_session(
    session: &GarrisonSession,
    token: &str,
) -> GarrisonResult<TokenSession> {
    validate_anon_token(token)?;
    let key = anon_token_key(token);

    // 使用 per-token 锁保护 check-then-set 序列,避免并发 lost update
    session
        .with_token_session_lock(token, async {
            if let Some(json) = session.dao.get(&key).await? {
                let ts: TokenSession = serde_json::from_str(&json).map_err(|e| {
                    GarrisonError::Session(format!("session-sim-anon-deserialize::{}", e))
                })?;
                return Ok(ts);
            }

            let now = Utc::now().timestamp();
            let ts = TokenSession {
                token: token.to_string(),
                login_id: String::new(),
                created_at: now,
                last_active_at: now,
                attrs: HashMap::new(),
                device: None,
                ip: None,
                user_agent: None,
                safe_services: HashMap::new(),
                #[cfg(feature = "session-extra")]
                dynamic_active_timeout: None,
                is_anon: true,
                effective_timeout: None,
                amr_ledger: Vec::new(),
                auth_time: None,
            };

            let json = serde_json::to_string(&ts).map_err(|e| {
                GarrisonError::Session(format!("session-sim-anon-serialize::{}", e))
            })?;
            session
                .dao
                .set(&key, &json, session.anon_session_timeout)
                .await?;

            Ok(ts)
        })
        .await
}

/// 判断 token 是否为匿名 Session(检查 `token:session:anon:{token}` 是否存在)。
pub async fn is_anon(session: &GarrisonSession, token: &str) -> GarrisonResult<bool> {
    validate_anon_token(token)?;
    let key = anon_token_key(token);
    Ok(session.dao.get(&key).await?.is_some())
}

/// 注销匿名 Session(删除 `token:session:anon:{token}` 键);不存在的 anon token 幂等返回 `Ok(())`。
pub async fn logout_anon(session: &GarrisonSession, token: &str) -> GarrisonResult<()> {
    validate_anon_token(token)?;
    let key = anon_token_key(token);
    session.dao.delete(&key).await
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::dao::tests::MockDao;
    use std::sync::Arc;
    use std::time::Duration;

    /// 辅助函数:创建带 MockDao + 自定义 anon_session_timeout 的 GarrisonSession。
    fn make_anon_session(
        timeout: u64,
        active_timeout: u64,
        anon_timeout: u64,
    ) -> (Arc<MockDao>, GarrisonSession) {
        let dao = Arc::new(MockDao::new());
        let session = GarrisonSession::new(dao.clone(), timeout, active_timeout, 0)
            .with_anon_session_timeout(anon_timeout);
        (dao, session)
    }

    /// 首次调用创建匿名 Session,login_id 为空,is_anon 为 true。
    #[tokio::test]
    async fn get_anon_token_session_creates_new_on_first_call() {
        let (_dao, session) = make_anon_session(3600, 86400, 1800);

        let ts = session.get_anon_token_session("anon-1").await.unwrap();

        assert_eq!(ts.token, "anon-1");
        assert!(
            ts.login_id.is_empty(),
            "匿名 Session 的 login_id 应为空字符串"
        );
        assert!(ts.is_anon, "匿名 Session 的 is_anon 应为 true");
        assert!(ts.created_at > 0, "created_at 应为有效时间戳");
        assert_eq!(ts.created_at, ts.last_active_at);
    }

    /// 二次获取返回同一个 Session(created_at 不变)。
    #[tokio::test]
    async fn get_anon_token_session_returns_same_on_second_call() {
        let (_dao, session) = make_anon_session(3600, 86400, 1800);

        let ts1 = session.get_anon_token_session("anon-1").await.unwrap();
        let ts2 = session.get_anon_token_session("anon-1").await.unwrap();

        assert_eq!(
            ts1.created_at, ts2.created_at,
            "二次获取应返回同一个 Session(created_at 不变)"
        );
        assert_eq!(ts1.token, ts2.token);
        assert!(ts2.is_anon);
    }

    /// 超时后重新调用创建新 Session(created_at 不同)。
    #[tokio::test]
    async fn get_anon_token_session_recreates_after_timeout() {
        // anon TTL = 2 秒
        let (_dao, session) = make_anon_session(3600, 86400, 2);

        let ts1 = session.get_anon_token_session("anon-1").await.unwrap();

        // 等待超时(TTL=2,sleep 3 秒确保过期)
        tokio::time::sleep(Duration::from_secs(3)).await;

        let ts2 = session.get_anon_token_session("anon-1").await.unwrap();

        assert!(
            ts2.created_at > ts1.created_at,
            "超时后应创建新 Session(created_at 应大于首次)"
        );
        assert!(ts2.is_anon, "新 Session 的 is_anon 应为 true");
        assert!(ts2.login_id.is_empty(), "新 Session 的 login_id 应为空");
    }

    #[tokio::test]
    async fn is_anon_returns_true_for_anon_token() {
        let (_dao, session) = make_anon_session(3600, 86400, 1800);

        session.get_anon_token_session("anon-1").await.unwrap();

        let result = session.is_anon("anon-1").await.unwrap();
        assert!(result, "匿名 token 的 is_anon 应返回 true");
    }

    #[tokio::test]
    async fn is_anon_returns_false_for_login_token() {
        let (_dao, session) = make_anon_session(3600, 86400, 1800);

        session.create("1001", "T1").await.unwrap();

        let result = session.is_anon("T1").await.unwrap();
        assert!(!result, "登录 token 的 is_anon 应返回 false");
    }

    #[tokio::test]
    async fn logout_anon_then_get_creates_new_session() {
        let (_dao, session) = make_anon_session(3600, 86400, 1800);

        session.get_anon_token_session("anon-1").await.unwrap();
        assert!(
            session.is_anon("anon-1").await.unwrap(),
            "首次创建后 is_anon 应为 true"
        );

        session.logout_anon("anon-1").await.unwrap();
        assert!(
            !session.is_anon("anon-1").await.unwrap(),
            "注销后 is_anon 应为 false"
        );

        let ts2 = session.get_anon_token_session("anon-1").await.unwrap();
        assert!(
            session.is_anon("anon-1").await.unwrap(),
            "重新获取后 is_anon 应为 true"
        );
        assert!(ts2.is_anon, "新 Session 的 is_anon 应为 true");
        assert!(ts2.login_id.is_empty(), "新 Session 的 login_id 应为空");
    }

    #[tokio::test]
    async fn logout_anon_nonexistent_returns_ok() {
        let (_dao, session) = make_anon_session(3600, 86400, 1800);

        let result = session.logout_anon("nonexistent-anon").await;
        assert!(
            result.is_ok(),
            "注销不存在的 anon token 应返回 Ok(())(幂等)"
        );
    }

    /// logout 对空 token 保持幂等契约(anonymous-session feature 下不因 InvalidParam 报错)。
    #[tokio::test]
    async fn logout_empty_token_remains_idempotent_with_anon_feature() {
        let (_dao, session) = make_anon_session(3600, 86400, 1800);

        let result = session.logout("").await;
        assert!(
            result.is_ok(),
            "logout(\"\") 应保持幂等契约返回 Ok(()),而非因 is_anon 校验返回 Err"
        );
    }

    /// logout 对超长 token 保持幂等契约。
    #[tokio::test]
    async fn logout_oversized_token_remains_idempotent_with_anon_feature() {
        let (_dao, session) = make_anon_session(3600, 86400, 1800);

        let oversized = "a".repeat(200);
        let result = session.logout(&oversized).await;
        assert!(
            result.is_ok(),
            "logout 对超长 token 应保持幂等契约返回 Ok(())"
        );
    }
}