From cf5dc099fb9282946372f067795ae0061b36c416 Mon Sep 17 00:00:00 2001 From: Marshall Bowers Date: Wed, 17 Jan 2024 13:38:12 -0500 Subject: [PATCH] Add more documentation to `collab` (#4095) This PR adds more documentation to the `collab` crate. Release Notes: - N/A --------- Co-authored-by: Conrad --- crates/collab/src/auth.rs | 7 +++ crates/collab/src/db.rs | 26 ++++++++ crates/collab/src/db/ids.rs | 20 ++++++ crates/collab/src/db/queries/access_tokens.rs | 2 + crates/collab/src/db/queries/buffers.rs | 10 ++- crates/collab/src/db/queries/channels.rs | 28 +++++++-- crates/collab/src/db/queries/contacts.rs | 8 +++ crates/collab/src/db/queries/messages.rs | 11 ++++ crates/collab/src/db/queries/notifications.rs | 4 ++ crates/collab/src/db/queries/projects.rs | 18 ++++++ crates/collab/src/db/queries/rooms.rs | 6 ++ crates/collab/src/db/queries/servers.rs | 6 ++ crates/collab/src/db/queries/users.rs | 15 +++++ crates/collab/src/db/tables/user.rs | 1 + crates/collab/src/rpc.rs | 62 +++++++++++++++++++ 15 files changed, 219 insertions(+), 5 deletions(-) diff --git a/crates/collab/src/auth.rs b/crates/collab/src/auth.rs index 9ce602c577..df3ded28e4 100644 --- a/crates/collab/src/auth.rs +++ b/crates/collab/src/auth.rs @@ -27,6 +27,8 @@ lazy_static! { .unwrap(); } +/// Validates the authorization header. This has two mechanisms, one for the ADMIN_TOKEN +/// and one for the access tokens that we issue. pub async fn validate_header(mut req: Request, next: Next) -> impl IntoResponse { let mut auth_header = req .headers() @@ -88,6 +90,8 @@ struct AccessTokenJson { token: String, } +/// Creates a new access token to identify the given user. before returning it, you should +/// encrypt it with the user's public key. pub async fn create_access_token(db: &db::Database, user_id: UserId) -> Result { const VERSION: usize = 1; let access_token = rpc::auth::random_token(); @@ -122,6 +126,8 @@ fn hash_access_token(token: &str) -> Result { .to_string()) } +/// Encrypts the given access token with the given public key to avoid leaking it on the way +/// to the client. pub fn encrypt_access_token(access_token: &str, public_key: String) -> Result { let native_app_public_key = rpc::auth::PublicKey::try_from(public_key).context("failed to parse app public key")?; @@ -131,6 +137,7 @@ pub fn encrypt_access_token(access_token: &str, public_key: String) -> Result) -> Result { let token: AccessTokenJson = serde_json::from_str(&token)?; diff --git a/crates/collab/src/db.rs b/crates/collab/src/db.rs index df33416a46..480dcf6f85 100644 --- a/crates/collab/src/db.rs +++ b/crates/collab/src/db.rs @@ -47,6 +47,8 @@ pub use ids::*; pub use sea_orm::ConnectOptions; pub use tables::user::Model as User; +/// Database gives you a handle that lets you access the database. +/// It handles pooling internally. pub struct Database { options: ConnectOptions, pool: DatabaseConnection, @@ -62,6 +64,7 @@ pub struct Database { // The `Database` type has so many methods that its impl blocks are split into // separate files in the `queries` folder. impl Database { + /// Connects to the database with the given options pub async fn new(options: ConnectOptions, executor: Executor) -> Result { sqlx::any::install_default_drivers(); Ok(Self { @@ -82,6 +85,7 @@ impl Database { self.rooms.clear(); } + /// Runs the database migrations. pub async fn migrate( &self, migrations_path: &Path, @@ -123,11 +127,15 @@ impl Database { Ok(new_migrations) } + /// Initializes static data that resides in the database by upserting it. pub async fn initialize_static_data(&mut self) -> Result<()> { self.initialize_notification_kinds().await?; Ok(()) } + /// Transaction runs things in a transaction. If you want to call other methods + /// and pass the transaction around you need to reborrow the transaction at each + /// call site with: `&*tx`. pub async fn transaction(&self, f: F) -> Result where F: Send + Fn(TransactionHandle) -> Fut, @@ -160,6 +168,7 @@ impl Database { self.run(body).await } + /// The same as room_transaction, but if you need to only optionally return a Room. async fn optional_room_transaction(&self, f: F) -> Result>> where F: Send + Fn(TransactionHandle) -> Fut, @@ -210,6 +219,9 @@ impl Database { self.run(body).await } + /// room_transaction runs the block in a transaction. It returns a RoomGuard, that keeps + /// the database locked until it is dropped. This ensures that updates sent to clients are + /// properly serialized with respect to database changes. async fn room_transaction(&self, room_id: RoomId, f: F) -> Result> where F: Send + Fn(TransactionHandle) -> Fut, @@ -330,6 +342,7 @@ fn is_serialization_error(error: &Error) -> bool { } } +/// A handle to a [`DatabaseTransaction`]. pub struct TransactionHandle(Arc>); impl Deref for TransactionHandle { @@ -340,6 +353,8 @@ impl Deref for TransactionHandle { } } +/// [`RoomGuard`] keeps a database transaction alive until it is dropped. +/// so that updates to rooms are serialized. pub struct RoomGuard { data: T, _guard: OwnedMutexGuard<()>, @@ -361,6 +376,7 @@ impl DerefMut for RoomGuard { } impl RoomGuard { + /// Returns the inner value of the guard. pub fn into_inner(self) -> T { self.data } @@ -420,12 +436,14 @@ pub struct WaitlistSummary { pub unknown_count: i64, } +/// The parameters to create a new user. #[derive(Debug, Serialize, Deserialize)] pub struct NewUserParams { pub github_login: String, pub github_user_id: i32, } +/// The result of creating a new user. #[derive(Debug)] pub struct NewUserResult { pub user_id: UserId, @@ -434,6 +452,7 @@ pub struct NewUserResult { pub signup_device_id: Option, } +/// The result of moving a channel. #[derive(Debug)] pub struct MoveChannelResult { pub participants_to_update: HashMap, @@ -441,18 +460,21 @@ pub struct MoveChannelResult { pub moved_channels: HashSet, } +/// The result of renaming a channel. #[derive(Debug)] pub struct RenameChannelResult { pub channel: Channel, pub participants_to_update: HashMap, } +/// The result of creating a channel. #[derive(Debug)] pub struct CreateChannelResult { pub channel: Channel, pub participants_to_update: Vec<(UserId, ChannelsForUser)>, } +/// The result of setting a channel's visibility. #[derive(Debug)] pub struct SetChannelVisibilityResult { pub participants_to_update: HashMap, @@ -460,6 +482,7 @@ pub struct SetChannelVisibilityResult { pub channels_to_remove: Vec, } +/// The result of updating a channel membership. #[derive(Debug)] pub struct MembershipUpdated { pub channel_id: ChannelId, @@ -467,12 +490,14 @@ pub struct MembershipUpdated { pub removed_channels: Vec, } +/// The result of setting a member's role. #[derive(Debug)] pub enum SetMemberRoleResult { InviteUpdated(Channel), MembershipUpdated(MembershipUpdated), } +/// The result of inviting a member to a channel. #[derive(Debug)] pub struct InviteMemberResult { pub channel: Channel, @@ -497,6 +522,7 @@ pub struct Channel { pub name: String, pub visibility: ChannelVisibility, pub role: ChannelRole, + /// parent_path is the channel ids from the root to this one (not including this one) pub parent_path: Vec, } diff --git a/crates/collab/src/db/ids.rs b/crates/collab/src/db/ids.rs index 9dbbfaff8f..a920265b57 100644 --- a/crates/collab/src/db/ids.rs +++ b/crates/collab/src/db/ids.rs @@ -19,19 +19,23 @@ macro_rules! id_type { Deserialize, DeriveValueType, )] + #[allow(missing_docs)] #[serde(transparent)] pub struct $name(pub i32); impl $name { #[allow(unused)] + #[allow(missing_docs)] pub const MAX: Self = Self(i32::MAX); #[allow(unused)] + #[allow(missing_docs)] pub fn from_proto(value: u64) -> Self { Self(value as i32) } #[allow(unused)] + #[allow(missing_docs)] pub fn to_proto(self) -> u64 { self.0 as u64 } @@ -84,21 +88,28 @@ id_type!(FlagId); id_type!(NotificationId); id_type!(NotificationKindId); +/// ChannelRole gives you permissions for both channels and calls. #[derive(Eq, PartialEq, Copy, Clone, Debug, EnumIter, DeriveActiveEnum, Default, Hash)] #[sea_orm(rs_type = "String", db_type = "String(None)")] pub enum ChannelRole { + /// Admin can read/write and change permissions. #[sea_orm(string_value = "admin")] Admin, + /// Member can read/write, but not change pemissions. #[sea_orm(string_value = "member")] #[default] Member, + /// Guest can read, but not write. + /// (thought they can use the channel chat) #[sea_orm(string_value = "guest")] Guest, + /// Banned may not read. #[sea_orm(string_value = "banned")] Banned, } impl ChannelRole { + /// Returns true if this role is more powerful than the other role. pub fn should_override(&self, other: Self) -> bool { use ChannelRole::*; match self { @@ -109,6 +120,7 @@ impl ChannelRole { } } + /// Returns the maximal role between the two pub fn max(&self, other: Self) -> Self { if self.should_override(other) { *self @@ -117,6 +129,7 @@ impl ChannelRole { } } + /// True if the role allows access to all descendant channels pub fn can_see_all_descendants(&self) -> bool { use ChannelRole::*; match self { @@ -125,6 +138,7 @@ impl ChannelRole { } } + /// True if the role only allows access to public descendant channels pub fn can_only_see_public_descendants(&self) -> bool { use ChannelRole::*; match self { @@ -133,6 +147,7 @@ impl ChannelRole { } } + /// True if the role can share screen/microphone/projects into rooms. pub fn can_publish_to_rooms(&self) -> bool { use ChannelRole::*; match self { @@ -141,6 +156,7 @@ impl ChannelRole { } } + /// True if the role can edit shared projects. pub fn can_edit_projects(&self) -> bool { use ChannelRole::*; match self { @@ -149,6 +165,7 @@ impl ChannelRole { } } + /// True if the role can read shared projects. pub fn can_read_projects(&self) -> bool { use ChannelRole::*; match self { @@ -187,11 +204,14 @@ impl Into for ChannelRole { } } +/// ChannelVisibility controls whether channels are public or private. #[derive(Eq, PartialEq, Copy, Clone, Debug, EnumIter, DeriveActiveEnum, Default, Hash)] #[sea_orm(rs_type = "String", db_type = "String(None)")] pub enum ChannelVisibility { + /// Public channels are visible to anyone with the link. People join with the Guest role by default. #[sea_orm(string_value = "public")] Public, + /// Members channels are only visible to members of this channel or its parents. #[sea_orm(string_value = "members")] #[default] Members, diff --git a/crates/collab/src/db/queries/access_tokens.rs b/crates/collab/src/db/queries/access_tokens.rs index 589b6483df..e033818970 100644 --- a/crates/collab/src/db/queries/access_tokens.rs +++ b/crates/collab/src/db/queries/access_tokens.rs @@ -2,6 +2,7 @@ use super::*; use sea_orm::sea_query::Query; impl Database { + /// Creates a new access token for the given user. pub async fn create_access_token( &self, user_id: UserId, @@ -39,6 +40,7 @@ impl Database { .await } + /// Retrieves the access token with the given ID. pub async fn get_access_token( &self, access_token_id: AccessTokenId, diff --git a/crates/collab/src/db/queries/buffers.rs b/crates/collab/src/db/queries/buffers.rs index 9eddb1f618..85e71d753b 100644 --- a/crates/collab/src/db/queries/buffers.rs +++ b/crates/collab/src/db/queries/buffers.rs @@ -9,6 +9,8 @@ pub struct LeftChannelBuffer { } impl Database { + /// Open a channel buffer. Returns the current contents, and adds you to the list of people + /// to notify on changes. pub async fn join_channel_buffer( &self, channel_id: ChannelId, @@ -121,6 +123,7 @@ impl Database { .await } + /// Rejoin a channel buffer (after a connection interruption) pub async fn rejoin_channel_buffers( &self, buffers: &[proto::ChannelBufferVersion], @@ -232,6 +235,7 @@ impl Database { .await } + /// Clear out any buffer collaborators who are no longer collaborating. pub async fn clear_stale_channel_buffer_collaborators( &self, channel_id: ChannelId, @@ -274,6 +278,7 @@ impl Database { .await } + /// Close the channel buffer, and stop receiving updates for it. pub async fn leave_channel_buffer( &self, channel_id: ChannelId, @@ -286,6 +291,7 @@ impl Database { .await } + /// Close the channel buffer, and stop receiving updates for it. pub async fn channel_buffer_connection_lost( &self, connection: ConnectionId, @@ -309,6 +315,7 @@ impl Database { Ok(()) } + /// Close all open channel buffers pub async fn leave_channel_buffers( &self, connection: ConnectionId, @@ -342,7 +349,7 @@ impl Database { .await } - pub async fn leave_channel_buffer_internal( + async fn leave_channel_buffer_internal( &self, channel_id: ChannelId, connection: ConnectionId, @@ -798,6 +805,7 @@ impl Database { Ok(changes) } + /// Returns the latest operations for the buffers with the specified IDs. pub async fn get_latest_operations_for_buffers( &self, buffer_ids: impl IntoIterator, diff --git a/crates/collab/src/db/queries/channels.rs b/crates/collab/src/db/queries/channels.rs index 6243b03bf7..7ff9f00bc1 100644 --- a/crates/collab/src/db/queries/channels.rs +++ b/crates/collab/src/db/queries/channels.rs @@ -40,6 +40,7 @@ impl Database { .id) } + /// Creates a new channel. pub async fn create_channel( &self, name: &str, @@ -97,6 +98,7 @@ impl Database { .await } + /// Adds a user to the specified channel. pub async fn join_channel( &self, channel_id: ChannelId, @@ -179,6 +181,7 @@ impl Database { .await } + /// Sets the visibiltity of the given channel. pub async fn set_channel_visibility( &self, channel_id: ChannelId, @@ -258,6 +261,7 @@ impl Database { .await } + /// Deletes the channel with the specified ID. pub async fn delete_channel( &self, channel_id: ChannelId, @@ -294,6 +298,7 @@ impl Database { .await } + /// Invites a user to a channel as a member. pub async fn invite_channel_member( &self, channel_id: ChannelId, @@ -349,6 +354,7 @@ impl Database { Ok(new_name) } + /// Renames the specified channel. pub async fn rename_channel( &self, channel_id: ChannelId, @@ -387,6 +393,7 @@ impl Database { .await } + /// accept or decline an invite to join a channel pub async fn respond_to_channel_invite( &self, channel_id: ChannelId, @@ -486,6 +493,7 @@ impl Database { }) } + /// Removes a channel member. pub async fn remove_channel_member( &self, channel_id: ChannelId, @@ -530,6 +538,7 @@ impl Database { .await } + /// Returns all channel invites for the user with the given ID. pub async fn get_channel_invites_for_user(&self, user_id: UserId) -> Result> { self.transaction(|tx| async move { let mut role_for_channel: HashMap = HashMap::default(); @@ -565,6 +574,7 @@ impl Database { .await } + /// Returns all channels for the user with the given ID. pub async fn get_channels_for_user(&self, user_id: UserId) -> Result { self.transaction(|tx| async move { let tx = tx; @@ -574,6 +584,8 @@ impl Database { .await } + /// Returns all channels for the user with the given ID that are descendants + /// of the specified ancestor channel. pub async fn get_user_channels( &self, user_id: UserId, @@ -743,6 +755,7 @@ impl Database { Ok(results) } + /// Sets the role for the specified channel member. pub async fn set_channel_member_role( &self, channel_id: ChannelId, @@ -786,6 +799,7 @@ impl Database { .await } + /// Returns the details for the specified channel member. pub async fn get_channel_participant_details( &self, channel_id: ChannelId, @@ -911,6 +925,7 @@ impl Database { .collect()) } + /// Returns the participants in the given channel. pub async fn get_channel_participants( &self, channel: &channel::Model, @@ -925,6 +940,7 @@ impl Database { .collect()) } + /// Returns whether the given user is an admin in the specified channel. pub async fn check_user_is_channel_admin( &self, channel: &channel::Model, @@ -943,6 +959,7 @@ impl Database { } } + /// Returns whether the given user is a member of the specified channel. pub async fn check_user_is_channel_member( &self, channel: &channel::Model, @@ -958,6 +975,7 @@ impl Database { } } + /// Returns whether the given user is a participant in the specified channel. pub async fn check_user_is_channel_participant( &self, channel: &channel::Model, @@ -975,6 +993,7 @@ impl Database { } } + /// Returns a user's pending invite for the given channel, if one exists. pub async fn pending_invite_for_channel( &self, channel: &channel::Model, @@ -991,7 +1010,7 @@ impl Database { Ok(row) } - pub async fn public_parent_channel( + async fn public_parent_channel( &self, channel: &channel::Model, tx: &DatabaseTransaction, @@ -1003,7 +1022,7 @@ impl Database { Ok(path.pop()) } - pub async fn public_ancestors_including_self( + pub(crate) async fn public_ancestors_including_self( &self, channel: &channel::Model, tx: &DatabaseTransaction, @@ -1018,6 +1037,7 @@ impl Database { Ok(visible_channels) } + /// Returns the role for a user in the given channel. pub async fn channel_role_for_user( &self, channel: &channel::Model, @@ -1143,7 +1163,7 @@ impl Database { .await?) } - /// Returns the channel with the given ID + /// Returns the channel with the given ID. pub async fn get_channel(&self, channel_id: ChannelId, user_id: UserId) -> Result { self.transaction(|tx| async move { let channel = self.get_channel_internal(channel_id, &*tx).await?; @@ -1156,7 +1176,7 @@ impl Database { .await } - pub async fn get_channel_internal( + pub(crate) async fn get_channel_internal( &self, channel_id: ChannelId, tx: &DatabaseTransaction, diff --git a/crates/collab/src/db/queries/contacts.rs b/crates/collab/src/db/queries/contacts.rs index f31f1addbd..c66c33b80d 100644 --- a/crates/collab/src/db/queries/contacts.rs +++ b/crates/collab/src/db/queries/contacts.rs @@ -1,6 +1,7 @@ use super::*; impl Database { + /// Retrieves the contacts for the user with the given ID. pub async fn get_contacts(&self, user_id: UserId) -> Result> { #[derive(Debug, FromQueryResult)] struct ContactWithUserBusyStatuses { @@ -86,6 +87,7 @@ impl Database { .await } + /// Returns whether the given user is a busy (on a call). pub async fn is_user_busy(&self, user_id: UserId) -> Result { self.transaction(|tx| async move { let participant = room_participant::Entity::find() @@ -97,6 +99,9 @@ impl Database { .await } + /// Returns whether the user with `user_id_1` has the user with `user_id_2` as a contact. + /// + /// In order for this to return `true`, `user_id_2` must have an accepted invite from `user_id_1`. pub async fn has_contact(&self, user_id_1: UserId, user_id_2: UserId) -> Result { self.transaction(|tx| async move { let (id_a, id_b) = if user_id_1 < user_id_2 { @@ -119,6 +124,7 @@ impl Database { .await } + /// Invite the user with `receiver_id` to be a contact of the user with `sender_id`. pub async fn send_contact_request( &self, sender_id: UserId, @@ -231,6 +237,7 @@ impl Database { .await } + /// Dismisses a contact notification for the given user. pub async fn dismiss_contact_notification( &self, user_id: UserId, @@ -272,6 +279,7 @@ impl Database { .await } + /// Accept or decline a contact request pub async fn respond_to_contact_request( &self, responder_id: UserId, diff --git a/crates/collab/src/db/queries/messages.rs b/crates/collab/src/db/queries/messages.rs index 96942c052d..9ee313d91b 100644 --- a/crates/collab/src/db/queries/messages.rs +++ b/crates/collab/src/db/queries/messages.rs @@ -4,6 +4,7 @@ use sea_orm::TryInsertResult; use time::OffsetDateTime; impl Database { + /// Inserts a record representing a user joining the chat for a given channel. pub async fn join_channel_chat( &self, channel_id: ChannelId, @@ -28,6 +29,7 @@ impl Database { .await } + /// Removes `channel_chat_participant` records associated with the given connection ID. pub async fn channel_chat_connection_lost( &self, connection_id: ConnectionId, @@ -47,6 +49,8 @@ impl Database { Ok(()) } + /// Removes `channel_chat_participant` records associated with the given user ID so they + /// will no longer get chat notifications. pub async fn leave_channel_chat( &self, channel_id: ChannelId, @@ -72,6 +76,9 @@ impl Database { .await } + /// Retrieves the messages in the specified channel. + /// + /// Use `before_message_id` to paginate through the channel's messages. pub async fn get_channel_messages( &self, channel_id: ChannelId, @@ -103,6 +110,7 @@ impl Database { .await } + /// Returns the channel messages with the given IDs. pub async fn get_channel_messages_by_id( &self, user_id: UserId, @@ -190,6 +198,7 @@ impl Database { Ok(messages) } + /// Creates a new channel message. pub async fn create_channel_message( &self, channel_id: ChannelId, @@ -376,6 +385,7 @@ impl Database { Ok(()) } + /// Returns the unseen messages for the given user in the specified channels. pub async fn unseen_channel_messages( &self, user_id: UserId, @@ -449,6 +459,7 @@ impl Database { Ok(changes) } + /// Removes the channel message with the given ID. pub async fn remove_channel_message( &self, channel_id: ChannelId, diff --git a/crates/collab/src/db/queries/notifications.rs b/crates/collab/src/db/queries/notifications.rs index 6f2511c23e..57685e141b 100644 --- a/crates/collab/src/db/queries/notifications.rs +++ b/crates/collab/src/db/queries/notifications.rs @@ -2,6 +2,7 @@ use super::*; use rpc::Notification; impl Database { + /// Initializes the different kinds of notifications by upserting records for them. pub async fn initialize_notification_kinds(&mut self) -> Result<()> { notification_kind::Entity::insert_many(Notification::all_variant_names().iter().map( |kind| notification_kind::ActiveModel { @@ -28,6 +29,7 @@ impl Database { Ok(()) } + /// Returns the notifications for the given recipient. pub async fn get_notifications( &self, recipient_id: UserId, @@ -140,6 +142,7 @@ impl Database { .await } + /// Marks the given notification as read. pub async fn mark_notification_as_read( &self, recipient_id: UserId, @@ -150,6 +153,7 @@ impl Database { .await } + /// Marks the notification with the given ID as read. pub async fn mark_notification_as_read_by_id( &self, recipient_id: UserId, diff --git a/crates/collab/src/db/queries/projects.rs b/crates/collab/src/db/queries/projects.rs index d82a597038..f81403a796 100644 --- a/crates/collab/src/db/queries/projects.rs +++ b/crates/collab/src/db/queries/projects.rs @@ -1,6 +1,7 @@ use super::*; impl Database { + /// Returns the count of all projects, excluding ones marked as admin. pub async fn project_count_excluding_admins(&self) -> Result { #[derive(Copy, Clone, Debug, EnumIter, DeriveColumn)] enum QueryAs { @@ -21,6 +22,7 @@ impl Database { .await } + /// Shares a project with the given room. pub async fn share_project( &self, room_id: RoomId, @@ -100,6 +102,7 @@ impl Database { .await } + /// Unshares the given project. pub async fn unshare_project( &self, project_id: ProjectId, @@ -126,6 +129,7 @@ impl Database { .await } + /// Updates the worktrees associated with the given project. pub async fn update_project( &self, project_id: ProjectId, @@ -346,6 +350,7 @@ impl Database { .await } + /// Updates the diagnostic summary for the given connection. pub async fn update_diagnostic_summary( &self, update: &proto::UpdateDiagnosticSummary, @@ -401,6 +406,7 @@ impl Database { .await } + /// Starts the language server for the given connection. pub async fn start_language_server( &self, update: &proto::StartLanguageServer, @@ -447,6 +453,7 @@ impl Database { .await } + /// Updates the worktree settings for the given connection. pub async fn update_worktree_settings( &self, update: &proto::UpdateWorktreeSettings, @@ -499,6 +506,7 @@ impl Database { .await } + /// Adds the given connection to the specified project. pub async fn join_project( &self, project_id: ProjectId, @@ -704,6 +712,7 @@ impl Database { .await } + /// Removes the given connection from the specified project. pub async fn leave_project( &self, project_id: ProjectId, @@ -805,6 +814,7 @@ impl Database { .map(|guard| guard.into_inner()) } + /// Returns the host connection for a read-only request to join a shared project. pub async fn host_for_read_only_project_request( &self, project_id: ProjectId, @@ -842,6 +852,7 @@ impl Database { .map(|guard| guard.into_inner()) } + /// Returns the host connection for a request to join a shared project. pub async fn host_for_mutating_project_request( &self, project_id: ProjectId, @@ -927,6 +938,10 @@ impl Database { .await } + /// Returns the connection IDs in the given project. + /// + /// The provided `connection_id` must also be a collaborator in the project, + /// otherwise an error will be returned. pub async fn project_connection_ids( &self, project_id: ProjectId, @@ -976,6 +991,7 @@ impl Database { Ok(guest_connection_ids) } + /// Returns the [`RoomId`] for the given project. pub async fn room_id_for_project(&self, project_id: ProjectId) -> Result { self.transaction(|tx| async move { let project = project::Entity::find_by_id(project_id) @@ -1020,6 +1036,7 @@ impl Database { .await } + /// Adds the given follower connection as a follower of the given leader connection. pub async fn follow( &self, room_id: RoomId, @@ -1050,6 +1067,7 @@ impl Database { .await } + /// Removes the given follower connection as a follower of the given leader connection. pub async fn unfollow( &self, room_id: RoomId, diff --git a/crates/collab/src/db/queries/rooms.rs b/crates/collab/src/db/queries/rooms.rs index 178cb712ed..7434e2d20d 100644 --- a/crates/collab/src/db/queries/rooms.rs +++ b/crates/collab/src/db/queries/rooms.rs @@ -1,6 +1,7 @@ use super::*; impl Database { + /// Clears all room participants in rooms attached to a stale server. pub async fn clear_stale_room_participants( &self, room_id: RoomId, @@ -78,6 +79,7 @@ impl Database { .await } + /// Returns the incoming calls for user with the given ID. pub async fn incoming_call_for_user( &self, user_id: UserId, @@ -102,6 +104,7 @@ impl Database { .await } + /// Creates a new room. pub async fn create_room( &self, user_id: UserId, @@ -394,6 +397,7 @@ impl Database { Ok(participant_index) } + /// Returns the channel ID for the given room, if it has one. pub async fn channel_id_for_room(&self, room_id: RoomId) -> Result> { self.transaction(|tx| async move { let room: Option = room::Entity::find() @@ -944,6 +948,7 @@ impl Database { .await } + /// Updates the location of a participant in the given room. pub async fn update_room_participant_location( &self, room_id: RoomId, @@ -1004,6 +1009,7 @@ impl Database { .await } + /// Sets the role of a participant in the given room. pub async fn set_room_participant_role( &self, admin_id: UserId, diff --git a/crates/collab/src/db/queries/servers.rs b/crates/collab/src/db/queries/servers.rs index e5ceee8887..c79b00eee8 100644 --- a/crates/collab/src/db/queries/servers.rs +++ b/crates/collab/src/db/queries/servers.rs @@ -1,6 +1,7 @@ use super::*; impl Database { + /// Creates a new server in the given environment. pub async fn create_server(&self, environment: &str) -> Result { self.transaction(|tx| async move { let server = server::ActiveModel { @@ -14,6 +15,10 @@ impl Database { .await } + /// Returns the IDs of resources associated with stale servers. + /// + /// A server is stale if it is in the specified `environment` and does not + /// match the provided `new_server_id`. pub async fn stale_server_resource_ids( &self, environment: &str, @@ -61,6 +66,7 @@ impl Database { .await } + /// Deletes any stale servers in the environment that don't match the `new_server_id`. pub async fn delete_stale_servers( &self, environment: &str, diff --git a/crates/collab/src/db/queries/users.rs b/crates/collab/src/db/queries/users.rs index 27e64e2598..954ec5f0d8 100644 --- a/crates/collab/src/db/queries/users.rs +++ b/crates/collab/src/db/queries/users.rs @@ -1,6 +1,7 @@ use super::*; impl Database { + /// Creates a new user. pub async fn create_user( &self, email_address: &str, @@ -35,11 +36,13 @@ impl Database { .await } + /// Returns a user by ID. There are no access checks here, so this should only be used internally. pub async fn get_user_by_id(&self, id: UserId) -> Result> { self.transaction(|tx| async move { Ok(user::Entity::find_by_id(id).one(&*tx).await?) }) .await } + /// Returns all users by ID. There are no access checks here, so this should only be used internally. pub async fn get_users_by_ids(&self, ids: Vec) -> Result> { self.transaction(|tx| async { let tx = tx; @@ -51,6 +54,7 @@ impl Database { .await } + /// Returns a user by GitHub login. There are no access checks here, so this should only be used internally. pub async fn get_user_by_github_login(&self, github_login: &str) -> Result> { self.transaction(|tx| async move { Ok(user::Entity::find() @@ -111,6 +115,8 @@ impl Database { .await } + /// get_all_users returns the next page of users. To get more call again with + /// the same limit and the page incremented by 1. pub async fn get_all_users(&self, page: u32, limit: u32) -> Result> { self.transaction(|tx| async move { Ok(user::Entity::find() @@ -123,6 +129,7 @@ impl Database { .await } + /// Returns the metrics id for the user. pub async fn get_user_metrics_id(&self, id: UserId) -> Result { #[derive(Copy, Clone, Debug, EnumIter, DeriveColumn)] enum QueryAs { @@ -142,6 +149,7 @@ impl Database { .await } + /// Set "connected_once" on the user for analytics. pub async fn set_user_connected_once(&self, id: UserId, connected_once: bool) -> Result<()> { self.transaction(|tx| async move { user::Entity::update_many() @@ -157,6 +165,7 @@ impl Database { .await } + /// hard delete the user. pub async fn destroy_user(&self, id: UserId) -> Result<()> { self.transaction(|tx| async move { access_token::Entity::delete_many() @@ -169,6 +178,7 @@ impl Database { .await } + /// Find users where github_login ILIKE name_query. pub async fn fuzzy_search_users(&self, name_query: &str, limit: u32) -> Result> { self.transaction(|tx| async { let tx = tx; @@ -193,6 +203,8 @@ impl Database { .await } + /// fuzzy_like_string creates a string for matching in-order using fuzzy_search_users. + /// e.g. "cir" would become "%c%i%r%" pub fn fuzzy_like_string(string: &str) -> String { let mut result = String::with_capacity(string.len() * 2 + 1); for c in string.chars() { @@ -205,6 +217,7 @@ impl Database { result } + /// Creates a new feature flag. pub async fn create_user_flag(&self, flag: &str) -> Result { self.transaction(|tx| async move { let flag = feature_flag::Entity::insert(feature_flag::ActiveModel { @@ -220,6 +233,7 @@ impl Database { .await } + /// Add the given user to the feature flag pub async fn add_user_flag(&self, user: UserId, flag: FlagId) -> Result<()> { self.transaction(|tx| async move { user_feature::Entity::insert(user_feature::ActiveModel { @@ -234,6 +248,7 @@ impl Database { .await } + /// Return the active flags for the user. pub async fn get_user_flags(&self, user: UserId) -> Result> { self.transaction(|tx| async move { #[derive(Copy, Clone, Debug, EnumIter, DeriveColumn)] diff --git a/crates/collab/src/db/tables/user.rs b/crates/collab/src/db/tables/user.rs index 739693527f..53866b5c54 100644 --- a/crates/collab/src/db/tables/user.rs +++ b/crates/collab/src/db/tables/user.rs @@ -2,6 +2,7 @@ use crate::db::UserId; use sea_orm::entity::prelude::*; use serde::Serialize; +/// A user model. #[derive(Clone, Debug, Default, PartialEq, Eq, DeriveEntityModel, Serialize)] #[sea_orm(table_name = "users")] pub struct Model { diff --git a/crates/collab/src/rpc.rs b/crates/collab/src/rpc.rs index 5d7f68caac..9406b4938a 100644 --- a/crates/collab/src/rpc.rs +++ b/crates/collab/src/rpc.rs @@ -932,11 +932,13 @@ async fn connection_lost( Ok(()) } +/// Acknowledges a ping from a client, used to keep the connection alive. async fn ping(_: proto::Ping, response: Response, _session: Session) -> Result<()> { response.send(proto::Ack {})?; Ok(()) } +/// Create a new room for calling (outside of channels) async fn create_room( _request: proto::CreateRoom, response: Response, @@ -984,6 +986,7 @@ async fn create_room( Ok(()) } +/// Join a room from an invitation. Equivalent to joining a channel if there is one. async fn join_room( request: proto::JoinRoom, response: Response, @@ -1058,6 +1061,7 @@ async fn join_room( Ok(()) } +/// Rejoin room is used to reconnect to a room after connection errors. async fn rejoin_room( request: proto::RejoinRoom, response: Response, @@ -1249,6 +1253,7 @@ async fn rejoin_room( Ok(()) } +/// leave room disonnects from the room. async fn leave_room( _: proto::LeaveRoom, response: Response, @@ -1259,6 +1264,7 @@ async fn leave_room( Ok(()) } +/// Update the permissions of someone else in the room. async fn set_room_participant_role( request: proto::SetRoomParticipantRole, response: Response, @@ -1303,6 +1309,7 @@ async fn set_room_participant_role( Ok(()) } +/// Call someone else into the current room async fn call( request: proto::Call, response: Response, @@ -1371,6 +1378,7 @@ async fn call( Err(anyhow!("failed to ring user"))? } +/// Cancel an outgoing call. async fn cancel_call( request: proto::CancelCall, response: Response, @@ -1408,6 +1416,7 @@ async fn cancel_call( Ok(()) } +/// Decline an incoming call. async fn decline_call(message: proto::DeclineCall, session: Session) -> Result<()> { let room_id = RoomId::from_proto(message.room_id); { @@ -1439,6 +1448,7 @@ async fn decline_call(message: proto::DeclineCall, session: Session) -> Result<( Ok(()) } +/// Update other participants in the room with your current location. async fn update_participant_location( request: proto::UpdateParticipantLocation, response: Response, @@ -1459,6 +1469,7 @@ async fn update_participant_location( Ok(()) } +/// Share a project into the room. async fn share_project( request: proto::ShareProject, response: Response, @@ -1481,6 +1492,7 @@ async fn share_project( Ok(()) } +/// Unshare a project from the room. async fn unshare_project(message: proto::UnshareProject, session: Session) -> Result<()> { let project_id = ProjectId::from_proto(message.project_id); @@ -1500,6 +1512,7 @@ async fn unshare_project(message: proto::UnshareProject, session: Session) -> Re Ok(()) } +/// Join someone elses shared project. async fn join_project( request: proto::JoinProject, response: Response, @@ -1625,6 +1638,7 @@ async fn join_project( Ok(()) } +/// Leave someone elses shared project. async fn leave_project(request: proto::LeaveProject, session: Session) -> Result<()> { let sender_id = session.connection_id; let project_id = ProjectId::from_proto(request.project_id); @@ -1647,6 +1661,7 @@ async fn leave_project(request: proto::LeaveProject, session: Session) -> Result Ok(()) } +/// Update other participants with changes to the project async fn update_project( request: proto::UpdateProject, response: Response, @@ -1673,6 +1688,7 @@ async fn update_project( Ok(()) } +/// Update other participants with changes to the worktree async fn update_worktree( request: proto::UpdateWorktree, response: Response, @@ -1697,6 +1713,7 @@ async fn update_worktree( Ok(()) } +/// Update other participants with changes to the diagnostics async fn update_diagnostic_summary( message: proto::UpdateDiagnosticSummary, session: Session, @@ -1720,6 +1737,7 @@ async fn update_diagnostic_summary( Ok(()) } +/// Update other participants with changes to the worktree settings async fn update_worktree_settings( message: proto::UpdateWorktreeSettings, session: Session, @@ -1743,6 +1761,7 @@ async fn update_worktree_settings( Ok(()) } +/// Notify other participants that a language server has started. async fn start_language_server( request: proto::StartLanguageServer, session: Session, @@ -1765,6 +1784,7 @@ async fn start_language_server( Ok(()) } +/// Notify other participants that a language server has changed. async fn update_language_server( request: proto::UpdateLanguageServer, session: Session, @@ -1787,6 +1807,8 @@ async fn update_language_server( Ok(()) } +/// forward a project request to the host. These requests should be read only +/// as guests are allowed to send them. async fn forward_read_only_project_request( request: T, response: Response, @@ -1809,6 +1831,8 @@ where Ok(()) } +/// forward a project request to the host. These requests are disallowed +/// for guests. async fn forward_mutating_project_request( request: T, response: Response, @@ -1831,6 +1855,7 @@ where Ok(()) } +/// Notify other participants that a new buffer has been created async fn create_buffer_for_peer( request: proto::CreateBufferForPeer, session: Session, @@ -1850,6 +1875,8 @@ async fn create_buffer_for_peer( Ok(()) } +/// Notify other participants that a buffer has been updated. This is +/// allowed for guests as long as the update is limited to selections. async fn update_buffer( request: proto::UpdateBuffer, response: Response, @@ -1909,6 +1936,7 @@ async fn update_buffer( Ok(()) } +/// Notify other participants that a project has been updated. async fn broadcast_project_message_from_host>( request: T, session: Session, @@ -1932,6 +1960,7 @@ async fn broadcast_project_message_from_host, @@ -1969,6 +1998,7 @@ async fn follow( Ok(()) } +/// Stop following another user in a call. async fn unfollow(request: proto::Unfollow, session: Session) -> Result<()> { let room_id = RoomId::from_proto(request.room_id); let project_id = request.project_id.map(ProjectId::from_proto); @@ -2000,6 +2030,7 @@ async fn unfollow(request: proto::Unfollow, session: Session) -> Result<()> { Ok(()) } +/// Notify everyone following you of your current location. async fn update_followers(request: proto::UpdateFollowers, session: Session) -> Result<()> { let room_id = RoomId::from_proto(request.room_id); let database = session.db.lock().await; @@ -2036,6 +2067,7 @@ async fn update_followers(request: proto::UpdateFollowers, session: Session) -> Ok(()) } +/// Get public data about users. async fn get_users( request: proto::GetUsers, response: Response, @@ -2062,6 +2094,7 @@ async fn get_users( Ok(()) } +/// Search for users (to invite) buy Github login async fn fuzzy_search_users( request: proto::FuzzySearchUsers, response: Response, @@ -2092,6 +2125,7 @@ async fn fuzzy_search_users( Ok(()) } +/// Send a contact request to another user. async fn request_contact( request: proto::RequestContact, response: Response, @@ -2138,6 +2172,7 @@ async fn request_contact( Ok(()) } +/// Accept or decline a contact request async fn respond_to_contact_request( request: proto::RespondToContactRequest, response: Response, @@ -2195,6 +2230,7 @@ async fn respond_to_contact_request( Ok(()) } +/// Remove a contact. async fn remove_contact( request: proto::RemoveContact, response: Response, @@ -2245,6 +2281,7 @@ async fn remove_contact( Ok(()) } +/// Create a new channel. async fn create_channel( request: proto::CreateChannel, response: Response, @@ -2279,6 +2316,7 @@ async fn create_channel( Ok(()) } +/// Delete a channel async fn delete_channel( request: proto::DeleteChannel, response: Response, @@ -2308,6 +2346,7 @@ async fn delete_channel( Ok(()) } +/// Invite someone to join a channel. async fn invite_channel_member( request: proto::InviteChannelMember, response: Response, @@ -2344,6 +2383,7 @@ async fn invite_channel_member( Ok(()) } +/// remove someone from a channel async fn remove_channel_member( request: proto::RemoveChannelMember, response: Response, @@ -2385,6 +2425,7 @@ async fn remove_channel_member( Ok(()) } +/// Toggle the channel between public and private async fn set_channel_visibility( request: proto::SetChannelVisibility, response: Response, @@ -2423,6 +2464,7 @@ async fn set_channel_visibility( Ok(()) } +/// Alter the role for a user in the channel async fn set_channel_member_role( request: proto::SetChannelMemberRole, response: Response, @@ -2470,6 +2512,7 @@ async fn set_channel_member_role( Ok(()) } +/// Change the name of a channel async fn rename_channel( request: proto::RenameChannel, response: Response, @@ -2503,6 +2546,7 @@ async fn rename_channel( Ok(()) } +/// Move a channel to a new parent. async fn move_channel( request: proto::MoveChannel, response: Response, @@ -2555,6 +2599,7 @@ async fn notify_channel_moved(result: Option, session: Sessio Ok(()) } +/// Get the list of channel members async fn get_channel_members( request: proto::GetChannelMembers, response: Response, @@ -2569,6 +2614,7 @@ async fn get_channel_members( Ok(()) } +/// Accept or decline a channel invitation. async fn respond_to_channel_invite( request: proto::RespondToChannelInvite, response: Response, @@ -2609,6 +2655,7 @@ async fn respond_to_channel_invite( Ok(()) } +/// Join the channels' room async fn join_channel( request: proto::JoinChannel, response: Response, @@ -2713,6 +2760,7 @@ async fn join_channel_internal( Ok(()) } +/// Start editing the channel notes async fn join_channel_buffer( request: proto::JoinChannelBuffer, response: Response, @@ -2744,6 +2792,7 @@ async fn join_channel_buffer( Ok(()) } +/// Edit the channel notes async fn update_channel_buffer( request: proto::UpdateChannelBuffer, session: Session, @@ -2790,6 +2839,7 @@ async fn update_channel_buffer( Ok(()) } +/// Rejoin the channel notes after a connection blip async fn rejoin_channel_buffers( request: proto::RejoinChannelBuffers, response: Response, @@ -2824,6 +2874,7 @@ async fn rejoin_channel_buffers( Ok(()) } +/// Stop editing the channel notes async fn leave_channel_buffer( request: proto::LeaveChannelBuffer, response: Response, @@ -2885,6 +2936,7 @@ fn send_notifications( } } +/// Send a message to the channel async fn send_channel_message( request: proto::SendChannelMessage, response: Response, @@ -2973,6 +3025,7 @@ async fn send_channel_message( Ok(()) } +/// Delete a channel message async fn remove_channel_message( request: proto::RemoveChannelMessage, response: Response, @@ -2992,6 +3045,7 @@ async fn remove_channel_message( Ok(()) } +/// Mark a channel message as read async fn acknowledge_channel_message( request: proto::AckChannelMessage, session: Session, @@ -3011,6 +3065,7 @@ async fn acknowledge_channel_message( Ok(()) } +/// Mark a buffer version as synced async fn acknowledge_buffer_version( request: proto::AckBufferOperation, session: Session, @@ -3029,6 +3084,7 @@ async fn acknowledge_buffer_version( Ok(()) } +/// Start receiving chat updates for a channel async fn join_channel_chat( request: proto::JoinChannelChat, response: Response, @@ -3049,6 +3105,7 @@ async fn join_channel_chat( Ok(()) } +/// Stop receiving chat updates for a channel async fn leave_channel_chat(request: proto::LeaveChannelChat, session: Session) -> Result<()> { let channel_id = ChannelId::from_proto(request.channel_id); session @@ -3059,6 +3116,7 @@ async fn leave_channel_chat(request: proto::LeaveChannelChat, session: Session) Ok(()) } +/// Retrive the chat history for a channel async fn get_channel_messages( request: proto::GetChannelMessages, response: Response, @@ -3082,6 +3140,7 @@ async fn get_channel_messages( Ok(()) } +/// Retrieve specific chat messages async fn get_channel_messages_by_id( request: proto::GetChannelMessagesById, response: Response, @@ -3104,6 +3163,7 @@ async fn get_channel_messages_by_id( Ok(()) } +/// Retrieve the current users notifications async fn get_notifications( request: proto::GetNotifications, response: Response, @@ -3127,6 +3187,7 @@ async fn get_notifications( Ok(()) } +/// Mark notifications as read async fn mark_notification_as_read( request: proto::MarkNotificationRead, response: Response, @@ -3148,6 +3209,7 @@ async fn mark_notification_as_read( Ok(()) } +/// Get the current users information async fn get_private_user_info( _request: proto::GetPrivateUserInfo, response: Response,