Yehowshua/ZIm
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add more documentation to collab (#4095)

Browse source 
This PR adds more documentation to the `collab` crate.

Release Notes:

- N/A

---------

Co-authored-by: Conrad <conrad@zed.dev>
This commit is contained in:
Marshall Bowers 2024-01-17 13:38:12 -05:00 • committed by GitHub
parent 4e4a1e0dd1
commit cf5dc099fb
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
15 changed files with 219 additions and 5 deletions
Download patch file Download diff file Expand all files Collapse all files

20
crates/collab/src/db/ids.rs
View file

@ -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<i32> 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,

2
crates/collab/src/db/queries/access_tokens.rs
View file

@ -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,

10
crates/collab/src/db/queries/buffers.rs
View file

@ -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<Item = BufferId>,

28
crates/collab/src/db/queries/channels.rs
View file

@ -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<Vec<Channel>> {
self.transaction(|tx| async move {
let mut role_for_channel: HashMap<ChannelId, ChannelRole> = 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<ChannelsForUser> {
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<Channel> {
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,

8
crates/collab/src/db/queries/contacts.rs
View file

@ -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<Vec<Contact>> {
#[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<bool> {
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<bool> {
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,

11
crates/collab/src/db/queries/messages.rs
View file

@ -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,

4
crates/collab/src/db/queries/notifications.rs
View file

@ -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,

18
crates/collab/src/db/queries/projects.rs
View file

@ -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<usize> {
#[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<RoomId> {
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,

6
crates/collab/src/db/queries/rooms.rs
View file

@ -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<Option<ChannelId>> {
self.transaction(|tx| async move {
let room: Option<room::Model> = 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,

6
crates/collab/src/db/queries/servers.rs
View file

@ -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<ServerId> {
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,

15
crates/collab/src/db/queries/users.rs
View file

@ -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<Option<user::Model>> {
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<UserId>) -> Result<Vec<user::Model>> {
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<Option<User>> {
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<Vec<User>> {
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<String> {
#[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<Vec<User>> {
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<FlagId> {
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<Vec<String>> {
self.transaction(|tx| async move {
#[derive(Copy, Clone, Debug, EnumIter, DeriveColumn)]

1
crates/collab/src/db/tables/user.rs
View file

@ -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 {