Skip to main content

gitflow_core/
auth.rs

1//! 认证领域类型与平台抽象。
2//!
3//! 定义了认证状态数据,以及跨平台实现所需的 [`AuthProvider`] trait。
4//! GitHub、GitLab、GitCode 等平台实现都需实现该 trait,使上层
5//! 命令层可统一处理登录、登出、状态查询及 Token 管理。
6
7use async_trait::async_trait;
8use serde::{Deserialize, Serialize};
9
10use crate::Result;
11
12/// 当前认证状态。
13///
14/// 由 [`AuthProvider::status`] 返回,用于判断用户是否已登录、
15/// 当前用户身份以及持有的权限范围。
16#[derive(Debug, Clone, Serialize, Deserialize)]
17#[serde(rename_all = "camelCase")]
18pub struct AuthStatus {
19    /// 用户是否已登录。
20    pub logged_in: bool,
21    /// 当前登录用户名(未登录时为 None)。
22    #[serde(skip_serializing_if = "Option::is_none")]
23    pub user: Option<String>,
24    /// 已授权的权限范围列表。
25    #[serde(default)]
26    pub scopes: Vec<String>,
27}
28
29/// 认证操作的平台抽象。
30///
31/// 所有平台实现(GitHub/GitLab/GitCode)都必须实现此 trait,
32/// 以提供统一的登录、登出、状态查询及 Token 获取能力。
33///
34/// # Errors
35///
36/// 所有方法在平台调用失败、反序列化失败或鉴权失败时返回
37/// [`CoreError`](crate::CoreError)。
38///
39/// [`CoreError`]: crate::CoreError
40#[async_trait]
41pub trait AuthProvider: std::fmt::Debug + Send + Sync {
42    /// 执行登录流程(交互式或非交互式)。
43    ///
44    /// 如果提供了 `token`,则使用 token 进行非交互式登录;
45    /// 否则启动交互式登录流程。
46    ///
47    /// 登录成功后凭据会被持久化到本地存储。
48    ///
49    /// # Errors
50    ///
51    /// 当认证失败或凭据存储失败时返回错误。
52    async fn login(&self, token: Option<&str>) -> Result<()>;
53
54    /// 执行登出流程,清除本地凭据。
55    ///
56    /// # Errors
57    ///
58    /// 当凭据清除失败时返回错误。
59    async fn logout(&self) -> Result<()>;
60
61    /// 查询当前认证状态。
62    ///
63    /// # Errors
64    ///
65    /// 当无法读取本地凭据或平台 API 调用失败时返回错误。
66    async fn status(&self) -> Result<AuthStatus>;
67
68    /// 获取当前有效的访问 Token。
69    ///
70    /// 返回的字符串可用于后续的平台 API 调用。
71    ///
72    /// # Errors
73    ///
74    /// 当用户未登录或 Token 获取失败时返回错误。
75    async fn token(&self) -> Result<String>;
76}
77
78#[cfg(test)]
79mod tests {
80    use super::*;
81
82    #[test]
83    fn test_should_deserialize_auth_status_logged_in() {
84        let json = r#"{
85            "loggedIn": true,
86            "user": "octocat",
87            "scopes": ["repo", "read:org"]
88        }"#;
89        let status: AuthStatus = serde_json::from_str(json).expect("valid AuthStatus JSON");
90
91        assert!(status.logged_in);
92        assert_eq!(status.user.as_deref(), Some("octocat"));
93        assert_eq!(
94            status.scopes,
95            vec!["repo".to_string(), "read:org".to_string()]
96        );
97    }
98
99    #[test]
100    fn test_should_deserialize_auth_status_not_logged_in() {
101        let json = r#"{
102            "loggedIn": false
103        }"#;
104        let status: AuthStatus = serde_json::from_str(json).expect("valid AuthStatus JSON");
105
106        assert!(!status.logged_in);
107        assert!(status.user.is_none());
108        assert!(status.scopes.is_empty());
109    }
110
111    #[test]
112    fn test_should_roundtrip_auth_status_via_serde() {
113        let json = r#"{
114            "loggedIn": true,
115            "user": "alice",
116            "scopes": ["repo"]
117        }"#;
118        let status: AuthStatus = serde_json::from_str(json).expect("deserialize");
119        let re_serialized = serde_json::to_string(&status).expect("serialize");
120        let round_tripped: AuthStatus =
121            serde_json::from_str(&re_serialized).expect("re-deserialize");
122
123        assert_eq!(round_tripped.logged_in, status.logged_in);
124        assert_eq!(round_tripped.user, status.user);
125        assert_eq!(round_tripped.scopes, status.scopes);
126    }
127
128    #[test]
129    fn test_should_serialize_auth_status_camel_case() {
130        let status = AuthStatus {
131            logged_in: true,
132            user: Some("bob".into()),
133            scopes: vec!["gist".into()],
134        };
135        let json = serde_json::to_string(&status).expect("serialize");
136        assert!(json.contains("\"loggedIn\":true"));
137        assert!(json.contains("\"user\":\"bob\""));
138        assert!(json.contains("\"scopes\""));
139        assert!(!json.contains("\"logged_in\""));
140    }
141
142    #[test]
143    fn test_should_omit_none_user_on_serialize() {
144        let status = AuthStatus {
145            logged_in: false,
146            user: None,
147            scopes: vec![],
148        };
149        let json = serde_json::to_string(&status).expect("serialize");
150        assert!(!json.contains("null"));
151        assert!(!json.contains("\"user\":"));
152        assert!(json.contains("\"loggedIn\":false"));
153    }
154
155    #[test]
156    fn test_should_default_empty_scopes() {
157        let json = r#"{"loggedIn":true,"user":"u"}"#;
158        let status: AuthStatus = serde_json::from_str(json).expect("deserialize");
159        assert!(status.scopes.is_empty());
160    }
161
162    #[test]
163    fn test_auth_status_debug_derive() {
164        let status = AuthStatus {
165            logged_in: true,
166            user: Some("test".into()),
167            scopes: vec!["repo".into()],
168        };
169        let debug = format!("{status:?}");
170        assert!(debug.contains("AuthStatus"));
171        assert!(debug.contains("test"));
172    }
173}