Bring projects, wikis, and teams together with AI. AppFlowy is the AI collaborative workspace where you achieve more without losing control of your data. The leading open source Notion alternative.
Dart blogconfluence-alternativecontent-managementcontent-servicesdocumentationflutternote-takingnotion-alternativeproject-managementtask-managementteam-collaborationwiki
docs: improve documentation (#3265)
Nathan.fooo1ba7224088e3
diff --git a/frontend/appflowy_flutter/lib/user/application/auth/auth_service.dart b/frontend/appflowy_flutter/lib/user/application/auth/auth_service.dartindex 29a2f7a528..6cfcff4557 100644--- a/frontend/appflowy_flutter/lib/user/application/auth/auth_service.dart+++ b/frontend/appflowy_flutter/lib/user/application/auth/auth_service.dart@@ -12,8 +12,20 @@ class AuthServiceMapKeys {static const String deviceId = 'device_id';}+/// `AuthService` is an abstract class that defines methods related to user authentication.+///+/// This service provides various methods for user sign-in, sign-up,+/// OAuth-based registration, and other related functionalities.abstract class AuthService {+ /// Authenticates a user with their email and password.+ ///+ /// - `email`: The email address of the user.+ /// - `password`: The password of the user.+ /// - `authType`: The type of authentication (optional).+ /// - `params`: Additional parameters for authentication (optional).+ ////// Returns [UserProfilePB] if the user is authenticated, otherwise returns [FlowyError].+Future<Either<FlowyError, UserProfilePB>> signIn({required String email,required String password,@@ -21,6 +33,14 @@ abstract class AuthService {Map<String, String> params,});+ /// Registers a new user with their name, email, and password.+ ///+ /// - `name`: The name of the user.+ /// - `email`: The email address of the user.+ /// - `password`: The password of the user.+ /// - `authType`: The type of authentication (optional).+ /// - `params`: Additional parameters for registration (optional).+ ////// Returns [UserProfilePB] if the user is authenticated, otherwise returns [FlowyError].Future<Either<FlowyError, UserProfilePB>> signUp({required String name,@@ -30,27 +50,46 @@ abstract class AuthService {Map<String, String> params,});+ /// Registers a new user with an OAuth platform.+ ///+ /// - `platform`: The OAuth platform name.+ /// - `authType`: The type of authentication (optional).+ /// - `params`: Additional parameters for OAuth registration (optional).///+ /// Returns [UserProfilePB] if the user is authenticated, otherwise returns [FlowyError].Future<Either<FlowyError, UserProfilePB>> signUpWithOAuth({required String platform,AuthTypePB authType,Map<String, String> params,});- /// Returns a default [UserProfilePB]+ /// Registers a user as a guest.+ ///+ /// - `authType`: The type of authentication (optional).+ /// - `params`: Additional parameters for guest registration (optional).+ ///+ /// Returns a default [UserProfilePB].Future<Either<FlowyError, UserProfilePB>> signUpAsGuest({AuthTypePB authType,Map<String, String> params,});+ /// Authenticates a user with a magic link sent to their email.+ ///+ /// - `email`: The email address of the user.+ /// - `params`: Additional parameters for authentication with magic link (optional).+ ///+ /// Returns [UserProfilePB] if the user is authenticated, otherwise returns [FlowyError].Future<Either<FlowyError, UserProfilePB>> signInWithMagicLink({required String email,Map<String, String> params,});- ///+ /// Signs out the currently authenticated user.Future<void> signOut();- /// Returns [UserProfilePB] if the user has sign in, otherwise returns null.+ /// Retrieves the currently authenticated user's profile.+ ///+ /// Returns [UserProfilePB] if the user has signed in, otherwise returns [FlowyError].Future<Either<FlowyError, UserProfilePB>> getUser();}diff --git a/frontend/rust-lib/flowy-core/src/integrate/server.rs b/frontend/rust-lib/flowy-core/src/integrate/server.rsindex 36e9c05d52..4cc46a05c1 100644--- a/frontend/rust-lib/flowy-core/src/integrate/server.rs+++ b/frontend/rust-lib/flowy-core/src/integrate/server.rs@@ -23,7 +23,7 @@ use flowy_user::event_map::UserCloudServiceProvider;use flowy_user::services::database::{get_user_profile, get_user_workspace, open_collab_db, open_user_db,};-use flowy_user_deps::cloud::UserService;+use flowy_user_deps::cloud::UserCloudService;use flowy_user_deps::entities::*;use lib_infra::future::FutureResult;@@ -59,7 +59,7 @@ impl Display for ServerProviderType {/// The [AppFlowyServerProvider] provides list of [AppFlowyServer] base on the [AuthType]. Using/// the auth type, the [AppFlowyServerProvider] will create a new [AppFlowyServer] if it doesn't/// exist.-/// Each server implements the [AppFlowyServer] trait, which provides the [UserService], etc.+/// Each server implements the [AppFlowyServer] trait, which provides the [UserCloudService], etc.pub struct AppFlowyServerProvider {config: AppFlowyCoreConfig,provider_type: RwLock<ServerProviderType>,@@ -68,7 +68,7 @@ pub struct AppFlowyServerProvider {enable_sync: RwLock<bool>,encryption: RwLock<Arc<dyn AppFlowyEncryption>>,store_preferences: Weak<StorePreferences>,- cache_user_service: RwLock<HashMap<ServerProviderType, Arc<dyn UserService>>>,+ cache_user_service: RwLock<HashMap<ServerProviderType, Arc<dyn UserCloudService>>>,}impl AppFlowyServerProvider {@@ -192,9 +192,9 @@ impl UserCloudServiceProvider for AppFlowyServerProvider {*self.device_id.write() = device_id.to_string();}- /// Returns the [UserService] base on the current [ServerProviderType].+ /// Returns the [UserCloudService] base on the current [ServerProviderType]./// Creates a new [AppFlowyServer] if it doesn't exist.- fn get_user_service(&self) -> Result<Arc<dyn UserService>, FlowyError> {+ fn get_user_service(&self) -> Result<Arc<dyn UserCloudService>, FlowyError> {if let Some(user_service) = self.cache_user_service.read()diff --git a/frontend/rust-lib/flowy-server/src/lib.rs b/frontend/rust-lib/flowy-server/src/lib.rsindex d8e1e5b7f0..338a13b2b4 100644--- a/frontend/rust-lib/flowy-server/src/lib.rs+++ b/frontend/rust-lib/flowy-server/src/lib.rs@@ -6,7 +6,7 @@ use parking_lot::RwLock;use flowy_database_deps::cloud::DatabaseCloudService;use flowy_document_deps::cloud::DocumentCloudService;use flowy_folder_deps::cloud::FolderCloudService;-use flowy_user_deps::cloud::UserService;+use flowy_user_deps::cloud::UserCloudService;pub mod local_server;mod request;@@ -33,12 +33,63 @@ where}}+/// `AppFlowyServer` trait defines a collection of services that offer cloud-based interactions+/// and functionalities in AppFlowy. The methods provided ensure efficient, asynchronous operations+/// for managing and accessing user data, folders, collaborative objects, and documents in a cloud environment.pub trait AppFlowyServer: Send + Sync + 'static {+ /// Enables or disables server sync.+ ///+ /// # Arguments+ ///+ /// * `_enable` - A boolean to toggle the server synchronization.fn set_enable_sync(&self, _enable: bool) {}- fn user_service(&self) -> Arc<dyn UserService>;++ /// Provides access to cloud-based user management functionalities. This includes operations+ /// such as user registration, authentication, profile management, and handling of user workspaces.+ /// The interface also offers methods for managing collaborative objects, subscribing to user updates,+ /// and receiving real-time events.+ ///+ /// # Returns+ ///+ /// An `Arc` wrapping the `UserCloudService` interface.+ fn user_service(&self) -> Arc<dyn UserCloudService>;++ /// Provides a service for managing workspaces and folders in a cloud environment. This includes+ /// functionalities to create workspaces, and fetch data, snapshots, and updates related to specific folders.+ ///+ /// # Returns+ ///+ /// An `Arc` wrapping the `FolderCloudService` interface.fn folder_service(&self) -> Arc<dyn FolderCloudService>;++ /// Offers a set of operations for interacting with collaborative objects within a cloud database.+ /// This includes functionalities such as retrieval of updates for specific objects, batch fetching,+ /// and obtaining snapshots.+ ///+ /// # Returns+ ///+ /// An `Arc` wrapping the `DatabaseCloudService` interface.fn database_service(&self) -> Arc<dyn DatabaseCloudService>;++ /// Facilitates cloud-based document management. This service offers operations for updating documents,+ /// fetching snapshots, and accessing primary document data in an asynchronous manner.+ ///+ /// # Returns+ ///+ /// An `Arc` wrapping the `DocumentCloudService` interface.fn document_service(&self) -> Arc<dyn DocumentCloudService>;++ /// Manages collaborative objects within a remote storage system. This includes operations such as+ /// checking storage status, retrieving updates and snapshots, and dispatching updates. The service+ /// also provides subscription capabilities for real-time updates.+ ///+ /// # Arguments+ ///+ /// * `collab_object` - A reference to the collaborative object.+ ///+ /// # Returns+ ///+ /// An `Option` that might contain an `Arc` wrapping the `RemoteCollabStorage` interface.fn collab_storage(&self, collab_object: &CollabObject) -> Option<Arc<dyn RemoteCollabStorage>>;}diff --git a/frontend/rust-lib/flowy-server/src/local_server/impls/user.rs b/frontend/rust-lib/flowy-server/src/local_server/impls/user.rsindex 96dd5d7747..3ca5c4d0c3 100644--- a/frontend/rust-lib/flowy-server/src/local_server/impls/user.rs+++ b/frontend/rust-lib/flowy-server/src/local_server/impls/user.rs@@ -5,7 +5,7 @@ use collab_plugins::cloud_storage::CollabObject;use lazy_static::lazy_static;use parking_lot::Mutex;-use flowy_user_deps::cloud::UserService;+use flowy_user_deps::cloud::UserCloudService;use flowy_user_deps::entities::*;use flowy_user_deps::DEFAULT_USER_NAME;use lib_infra::box_any::BoxAny;@@ -23,7 +23,7 @@ pub(crate) struct LocalServerUserAuthServiceImpl {pub db: Arc<dyn LocalServerDB>,}-impl UserService for LocalServerUserAuthServiceImpl {+impl UserCloudService for LocalServerUserAuthServiceImpl {fn sign_up(&self, params: BoxAny) -> FutureResult<SignUpResponse, Error> {FutureResult::new(async move {let params = params.unbox_or_error::<SignUpParams>()?;diff --git a/frontend/rust-lib/flowy-server/src/local_server/server.rs b/frontend/rust-lib/flowy-server/src/local_server/server.rsindex 0b4d5f272a..1ee2e3897b 100644--- a/frontend/rust-lib/flowy-server/src/local_server/server.rs+++ b/frontend/rust-lib/flowy-server/src/local_server/server.rs@@ -11,7 +11,7 @@ use flowy_folder_deps::cloud::FolderCloudService;// use flowy_user::services::database::{// get_user_profile, get_user_workspace, open_collab_db, open_user_db,// };-use flowy_user_deps::cloud::UserService;+use flowy_user_deps::cloud::UserCloudService;use flowy_user_deps::entities::*;use crate::local_server::impls::{@@ -48,7 +48,7 @@ impl LocalServer {}impl AppFlowyServer for LocalServer {- fn user_service(&self) -> Arc<dyn UserService> {+ fn user_service(&self) -> Arc<dyn UserCloudService> {Arc::new(LocalServerUserAuthServiceImpl {db: self.local_db.clone(),})diff --git a/frontend/rust-lib/flowy-server/src/self_host/impls/user.rs b/frontend/rust-lib/flowy-server/src/self_host/impls/user.rsindex ee474f592f..c4abc34d3f 100644--- a/frontend/rust-lib/flowy-server/src/self_host/impls/user.rs+++ b/frontend/rust-lib/flowy-server/src/self_host/impls/user.rs@@ -2,7 +2,7 @@ use anyhow::Error;use collab_plugins::cloud_storage::CollabObject;use flowy_error::{ErrorCode, FlowyError};-use flowy_user_deps::cloud::UserService;+use flowy_user_deps::cloud::UserCloudService;use flowy_user_deps::entities::*;use lib_infra::box_any::BoxAny;use lib_infra::future::FutureResult;@@ -20,7 +20,7 @@ impl SelfHostedUserAuthServiceImpl {}}-impl UserService for SelfHostedUserAuthServiceImpl {+impl UserCloudService for SelfHostedUserAuthServiceImpl {fn sign_up(&self, params: BoxAny) -> FutureResult<SignUpResponse, Error> {let url = self.config.sign_up_url();FutureResult::new(async move {diff --git a/frontend/rust-lib/flowy-server/src/self_host/server.rs b/frontend/rust-lib/flowy-server/src/self_host/server.rsindex 9ccff67a54..0802ddbfe3 100644--- a/frontend/rust-lib/flowy-server/src/self_host/server.rs+++ b/frontend/rust-lib/flowy-server/src/self_host/server.rs@@ -5,7 +5,7 @@ use collab_plugins::cloud_storage::{CollabObject, RemoteCollabStorage};use flowy_database_deps::cloud::DatabaseCloudService;use flowy_document_deps::cloud::DocumentCloudService;use flowy_folder_deps::cloud::FolderCloudService;-use flowy_user_deps::cloud::UserService;+use flowy_user_deps::cloud::UserCloudService;use crate::self_host::configuration::SelfHostedConfiguration;use crate::self_host::impls::{@@ -25,7 +25,7 @@ impl SelfHostServer {}impl AppFlowyServer for SelfHostServer {- fn user_service(&self) -> Arc<dyn UserService> {+ fn user_service(&self) -> Arc<dyn UserCloudService> {Arc::new(SelfHostedUserAuthServiceImpl::new(self.config.clone()))}diff --git a/frontend/rust-lib/flowy-server/src/supabase/api/user.rs b/frontend/rust-lib/flowy-server/src/supabase/api/user.rsindex a0d44e1beb..04f2e692fa 100644--- a/frontend/rust-lib/flowy-server/src/supabase/api/user.rs+++ b/frontend/rust-lib/flowy-server/src/supabase/api/user.rs@@ -52,7 +52,7 @@ impl<T> SupabaseUserServiceImpl<T> {}}-impl<T> UserService for SupabaseUserServiceImpl<T>+impl<T> UserCloudService for SupabaseUserServiceImpl<T>whereT: SupabaseServerService,{diff --git a/frontend/rust-lib/flowy-server/src/supabase/server.rs b/frontend/rust-lib/flowy-server/src/supabase/server.rsindex 0bd641d7ee..0837dc2aba 100644--- a/frontend/rust-lib/flowy-server/src/supabase/server.rs+++ b/frontend/rust-lib/flowy-server/src/supabase/server.rs@@ -8,7 +8,7 @@ use flowy_database_deps::cloud::DatabaseCloudService;use flowy_document_deps::cloud::DocumentCloudService;use flowy_folder_deps::cloud::FolderCloudService;use flowy_server_config::supabase_config::SupabaseConfiguration;-use flowy_user_deps::cloud::UserService;+use flowy_user_deps::cloud::UserCloudService;use crate::supabase::api::{RESTfulPostgresServer, RealtimeCollabUpdateHandler, RealtimeEventHandler, RealtimeUserHandler,@@ -108,7 +108,7 @@ impl AppFlowyServer for SupabaseServer {self.set_enable_sync(enable);}- fn user_service(&self) -> Arc<dyn UserService> {+ fn user_service(&self) -> Arc<dyn UserCloudService> {// handle the realtime collab update event.let (user_update_tx, _) = tokio::sync::broadcast::channel(100);diff --git a/frontend/rust-lib/flowy-server/tests/supabase_test/util.rs b/frontend/rust-lib/flowy-server/tests/supabase_test/util.rsindex 9fd5546129..5b9b3f4b75 100644--- a/frontend/rust-lib/flowy-server/tests/supabase_test/util.rs+++ b/frontend/rust-lib/flowy-server/tests/supabase_test/util.rs@@ -15,7 +15,7 @@ use flowy_server::supabase::api::{use flowy_server::supabase::define::{USER_DEVICE_ID, USER_EMAIL, USER_UUID};use flowy_server::{AppFlowyEncryption, EncryptionImpl};use flowy_server_config::supabase_config::SupabaseConfiguration;-use flowy_user_deps::cloud::UserService;+use flowy_user_deps::cloud::UserCloudService;use crate::setup_log;@@ -46,7 +46,7 @@ pub fn database_service() -> Arc<dyn DatabaseCloudService> {Arc::new(SupabaseDatabaseServiceImpl::new(server))}-pub fn user_auth_service() -> Arc<dyn UserService> {+pub fn user_auth_service() -> Arc<dyn UserCloudService> {let (server, _encryption_impl) = appflowy_server(None);Arc::new(SupabaseUserServiceImpl::new(server, vec![], None))}diff --git a/frontend/rust-lib/flowy-test/tests/util.rs b/frontend/rust-lib/flowy-test/tests/util.rsindex 57d703b1a7..074d025ee1 100644--- a/frontend/rust-lib/flowy-test/tests/util.rs+++ b/frontend/rust-lib/flowy-test/tests/util.rs@@ -19,7 +19,7 @@ use flowy_user::entities::{AuthTypePB, UpdateUserProfilePayloadPB, UserCredentiause flowy_user::errors::FlowyError;use flowy_user::event_map::UserCloudServiceProvider;use flowy_user::event_map::UserEvent::*;-use flowy_user_deps::cloud::UserService;+use flowy_user_deps::cloud::UserCloudService;use flowy_user_deps::entities::AuthType;pub fn get_supabase_config() -> Option<SupabaseConfiguration> {@@ -110,7 +110,7 @@ pub fn database_service() -> Arc<dyn DatabaseCloudService> {Arc::new(SupabaseDatabaseServiceImpl::new(server))}-pub fn user_auth_service() -> Arc<dyn UserService> {+pub fn user_auth_service() -> Arc<dyn UserCloudService> {let (server, _encryption_impl) = appflowy_server(None);Arc::new(SupabaseUserServiceImpl::new(server, vec![], None))}diff --git a/frontend/rust-lib/flowy-user-deps/src/cloud.rs b/frontend/rust-lib/flowy-user-deps/src/cloud.rsindex 787d450f86..012a0d3303 100644--- a/frontend/rust-lib/flowy-user-deps/src/cloud.rs+++ b/frontend/rust-lib/flowy-user-deps/src/cloud.rs@@ -58,7 +58,7 @@ impl Display for UserCloudConfig {/// Provide the generic interface for the user cloud service/// The user cloud service is responsible for the user authentication and user profile management-pub trait UserService: Send + Sync {+pub trait UserCloudService: Send + Sync {/// Sign up a new account./// The type of the params is defined the this trait's implementation./// Use the `unbox_or_error` of the [BoxAny] to get the params.diff --git a/frontend/rust-lib/flowy-user/src/event_map.rs b/frontend/rust-lib/flowy-user/src/event_map.rsindex ea72cb0ed5..093580d948 100644--- a/frontend/rust-lib/flowy-user/src/event_map.rs+++ b/frontend/rust-lib/flowy-user/src/event_map.rs@@ -5,7 +5,7 @@ use strum_macros::Display;use flowy_derive::{Flowy_Event, ProtoBuf_Enum};use flowy_error::FlowyResult;-use flowy_user_deps::cloud::{UserCloudConfig, UserService};+use flowy_user_deps::cloud::{UserCloudConfig, UserCloudService};use flowy_user_deps::entities::*;use lib_dispatch::prelude::*;use lib_infra::future::{to_fut, Fut};@@ -106,7 +106,7 @@ pub trait UserCloudServiceProvider: Send + Sync + 'static {fn set_encrypt_secret(&self, secret: String);fn set_auth_type(&self, auth_type: AuthType);fn set_device_id(&self, device_id: &str);- fn get_user_service(&self) -> Result<Arc<dyn UserService>, FlowyError>;+ fn get_user_service(&self) -> Result<Arc<dyn UserCloudService>, FlowyError>;fn service_name(&self) -> String;}@@ -130,7 +130,7 @@ where(**self).set_device_id(device_id)}- fn get_user_service(&self) -> Result<Arc<dyn UserService>, FlowyError> {+ fn get_user_service(&self) -> Result<Arc<dyn UserCloudService>, FlowyError> {(**self).get_user_service()}