rocketmq_auth/authentication/manager/
authentication_metadata_manager.rs

1// Copyright 2023 The RocketMQ Rust Authors
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15//! Authentication metadata manager trait.
16//!
17//! This module defines the high-level interface for managing authentication metadata,
18//! including user creation, modification, deletion, and query operations.
19
20use crate::authentication::model::user::User;
21use crate::config::AuthConfig;
22use crate::AuthServiceResult;
23
24/// Type alias for manager operation results.
25///
26/// Following the same pattern as `AuthorizationMetadataManager::ManagerResult`.
27pub type ManagerResult<T> = AuthServiceResult<T>;
28
29/// Authentication metadata manager trait.
30///
31/// This trait provides high-level operations for managing authentication metadata,
32/// wrapping the underlying `AuthenticationMetadataProvider` and adding validation,
33/// initialization, and error handling logic.
34///
35/// # Responsibilities
36///
37/// - User lifecycle management (create, update, delete)
38/// - User query and listing
39/// - Super user privilege checking
40/// - Provider initialization and shutdown
41/// - Input validation and error handling
42///
43/// # Concurrency
44///
45/// All methods are async and designed for concurrent access. Implementations should
46/// ensure thread-safety through appropriate synchronization mechanisms.
47///
48/// # Example
49///
50/// ```rust,ignore
51/// use rocketmq_auth::AuthenticationMetadataManager;
52/// use rocketmq_auth::AuthConfig;
53///
54/// async fn example(manager: &dyn AuthenticationMetadataManager, config: AuthConfig) {
55///     // Initialize default users
56///     manager.init_user(config).await?;
57///     
58///     // Create a user
59///     let user = User::of_with_type("alice", "password123", UserType::Normal);
60///     manager.create_user(user).await?;
61///     
62///     // Check if user is super user
63///     let is_super = manager.is_super_user("alice").await?;
64/// }
65/// ```
66#[allow(async_fn_in_trait)]
67pub trait AuthenticationMetadataManager: Send + Sync {
68    /// Shutdown the metadata manager and release resources.
69    ///
70    /// This method should cleanup all resources including:
71    /// - Closing database connections
72    /// - Shutting down thread pools
73    /// - Flushing pending operations
74    async fn shutdown(&mut self) -> ManagerResult<()>;
75
76    /// Initialize default super user from configuration.
77    ///
78    /// This method reads the default user credentials from `AuthConfig` and
79    /// creates the super user if it doesn't exist. This is typically called
80    /// during system initialization.
81    ///
82    /// # Arguments
83    ///
84    /// * `auth_config` - Authentication configuration containing default user settings
85    async fn init_user(&self, auth_config: &AuthConfig) -> ManagerResult<()>;
86
87    /// Create a new user.
88    ///
89    /// # Arguments
90    ///
91    /// * `user` - The user to create
92    ///
93    /// # Returns
94    ///
95    /// * `Ok(())` - User created successfully
96    /// * `Err(AuthServiceError)` - Validation failed or creation error
97    ///
98    /// # Errors
99    ///
100    /// - `AuthenticationFailed` - Username is blank or invalid
101    /// - `InvalidCredential` - Password is missing or invalid
102    /// - Storage errors from underlying provider
103    async fn create_user(&self, user: User) -> ManagerResult<()>;
104
105    /// Update an existing user.
106    ///
107    /// # Arguments
108    ///
109    /// * `user` - The user with updated information
110    ///
111    /// # Returns
112    ///
113    /// * `Ok(())` - User updated successfully
114    /// * `Err(AuthServiceError)` - Validation failed or update error
115    async fn update_user(&self, user: User) -> ManagerResult<()>;
116
117    /// Delete a user by username.
118    ///
119    /// # Arguments
120    ///
121    /// * `username` - The username of the user to delete
122    ///
123    /// # Returns
124    ///
125    /// * `Ok(())` - User deleted successfully
126    /// * `Err(AuthServiceError)` - Username is blank or deletion error
127    async fn delete_user(&self, username: &str) -> ManagerResult<()>;
128
129    /// Get a user by username.
130    ///
131    /// # Arguments
132    ///
133    /// * `username` - The username to query
134    ///
135    /// # Returns
136    ///
137    /// * `Ok(User)` - User found
138    /// * `Err(AuthServiceError)` - Username is blank or user not found
139    async fn get_user(&self, username: &str) -> ManagerResult<User>;
140
141    /// List users with optional filtering.
142    ///
143    /// # Arguments
144    ///
145    /// * `filter` - Optional username filter (substring match)
146    ///
147    /// # Returns
148    ///
149    /// * `Ok(Vec<User>)` - List of matching users
150    /// * `Err(AuthServiceError)` - Query error
151    async fn list_users(&self, filter: Option<&str>) -> ManagerResult<Vec<User>>;
152
153    /// Check if a user is a super user.
154    ///
155    /// # Arguments
156    ///
157    /// * `username` - The username to check
158    ///
159    /// # Returns
160    ///
161    /// * `Ok(true)` - User exists and is a super user
162    /// * `Ok(false)` - User doesn't exist or is not a super user
163    /// * `Err(AuthServiceError)` - Query error
164    async fn is_super_user(&self, username: &str) -> ManagerResult<bool>;
165}
rocketmq_auth/authentication/manager/authentication_metadata_manager.rs

rocketmq_auth/authentication/manager/
authentication_metadata_manager.rs
