opentalk_roomserver_types/

client_parameters.rs

// SPDX-License-Identifier: EUPL-1.2
// SPDX-FileCopyrightText: OpenTalk Team <mail@opentalk.eu>

use opentalk_types_common::{
    roomserver::DeviceSecret,
    time::TimeZone,
    users::{UserId, UserInfo},
    utils::ExampleData,
};
use opentalk_types_signaling::ParticipationVisibility;
use serde::{Deserialize, Serialize};

use crate::{public_user_profile::PublicUserProfile, room_kind::RoomKind};

/// Client context required for a signaling connection
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema), schema(example = json!(ClientParameters::example_data())))]
pub struct ClientParameters {
    /// Identifier to maintain participant state across reconnections, is generated by the client
    pub device_secret: DeviceSecret,

    /// Information about a registered user
    #[serde(flatten)]
    pub kind: ClientKind,

    /// The role that the client assumes in the meeting.
    pub role: Role,
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
#[serde(rename_all = "snake_case", tag = "kind")]
pub enum ClientKind {
    /// A registered user
    Registered { profile: PublicUserProfile },

    /// A guest participant
    Guest,

    /// Invisible recording participant
    Recorder {
        /// Room for which the recording was requested from
        ///
        /// Recorders may only access the recording-service commands & events in this room
        room: RoomKind,
    },

    /// Invisible service participant used by the transcription service
    Transcription {
        /// Room for which the transcription was requested from
        room: RoomKind,
    },

    /// Telephone call-In participant which identifies via a meeting id & pin
    CallIn,

    /// Same as `ClientKind::CallIn` but the controller may associate a user to the call-in
    /// participant if phonenumber matching is enabled
    RegisteredCallIn { profile: PublicUserProfile },
}

impl ClientKind {
    pub fn user_id(&self) -> Option<UserId> {
        match self {
            ClientKind::Registered { profile } | ClientKind::RegisteredCallIn { profile } => {
                Some(profile.id)
            }
            ClientKind::Guest
            | ClientKind::Recorder { .. }
            | ClientKind::CallIn
            | ClientKind::Transcription { .. } => None,
        }
    }

    pub fn email(&self) -> Option<&str> {
        match self {
            ClientKind::Registered { profile } | ClientKind::RegisteredCallIn { profile } => {
                Some(&profile.email)
            }
            ClientKind::Guest
            | ClientKind::Recorder { .. }
            | ClientKind::CallIn
            | ClientKind::Transcription { .. } => None,
        }
    }

    pub fn avatar_url(&self) -> Option<&str> {
        match self {
            ClientKind::Registered { profile } | ClientKind::RegisteredCallIn { profile } => {
                Some(&profile.user_info.avatar_url)
            }
            ClientKind::CallIn
            | ClientKind::Guest
            | ClientKind::Recorder { .. }
            | ClientKind::Transcription { .. } => None,
        }
    }

    pub fn user_info(&self) -> Option<&UserInfo> {
        match self {
            ClientKind::Registered { profile } | ClientKind::RegisteredCallIn { profile } => {
                Some(&profile.user_info)
            }
            ClientKind::CallIn
            | ClientKind::Guest
            | ClientKind::Recorder { .. }
            | ClientKind::Transcription { .. } => None,
        }
    }

    pub fn participant_kind(&self) -> ParticipationKind {
        match &self {
            ClientKind::Registered { .. } => ParticipationKind::Registered,
            ClientKind::Guest => ParticipationKind::Guest,
            ClientKind::Recorder { .. } => ParticipationKind::Recorder,
            ClientKind::Transcription { .. } => ParticipationKind::Transcription,
            ClientKind::CallIn => ParticipationKind::CallIn,
            ClientKind::RegisteredCallIn { .. } => ParticipationKind::RegisteredCallIn,
        }
    }

    pub fn is_service(&self) -> bool {
        match self {
            ClientKind::Registered { .. }
            | ClientKind::Guest
            | ClientKind::CallIn
            | ClientKind::RegisteredCallIn { .. } => false,
            ClientKind::Recorder { .. } | ClientKind::Transcription { .. } => true,
        }
    }

    /// Returns `true` if the participant is a registered, non call-in user, `false` otherwise.
    pub fn is_registered_non_callin_user(&self) -> bool {
        match self {
            ClientKind::Registered { .. } => true,
            ClientKind::Guest
            | ClientKind::Recorder { .. }
            | ClientKind::Transcription { .. }
            | ClientKind::CallIn
            | ClientKind::RegisteredCallIn { .. } => false,
        }
    }

    pub fn is_guest_or_callin(&self) -> bool {
        match self {
            ClientKind::Registered { .. }
            | ClientKind::Recorder { .. }
            | ClientKind::Transcription { .. } => false,
            ClientKind::Guest | ClientKind::CallIn | ClientKind::RegisteredCallIn { .. } => true,
        }
    }

    /// Returns `true` if the participant is a call-in user, otherwise return `false`.
    pub fn is_call_in(&self) -> bool {
        match self {
            ClientKind::Registered { .. }
            | ClientKind::Guest
            | ClientKind::Recorder { .. }
            | ClientKind::Transcription { .. } => false,
            ClientKind::CallIn | ClientKind::RegisteredCallIn { .. } => true,
        }
    }

    pub fn time_zone(&self) -> Option<TimeZone> {
        match self {
            ClientKind::Registered { profile } | ClientKind::RegisteredCallIn { profile } => {
                Some(profile.timezone)
            }
            ClientKind::Recorder { .. }
            | ClientKind::CallIn
            | ClientKind::Guest
            | ClientKind::Transcription { .. } => None,
        }
    }
}

impl ClientKind {
    pub fn visibility(&self) -> ParticipationVisibility {
        match self {
            ClientKind::Registered { .. }
            | ClientKind::Guest
            | ClientKind::CallIn
            | ClientKind::RegisteredCallIn { .. } => ParticipationVisibility::Visible,
            ClientKind::Recorder { .. } | ClientKind::Transcription { .. } => {
                ParticipationVisibility::Hidden
            }
        }
    }
}

impl ExampleData for ClientParameters {
    fn example_data() -> Self {
        Self {
            device_secret: DeviceSecret::example_data(),
            kind: ClientKind::Registered {
                profile: PublicUserProfile::example_data(),
            },
            role: Role::Moderator,
        }
    }
}

#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
#[serde(rename_all = "snake_case")]
pub enum Role {
    User,
    Moderator,
}

impl Role {
    /// Returns `true` if the role is [`Moderator`].
    ///
    /// [`Moderator`]: Role::Moderator
    #[must_use]
    pub fn is_moderator(&self) -> bool {
        matches!(self, Self::Moderator)
    }

    pub fn to_opentalk_types_signaling_role(self) -> opentalk_types_signaling::Role {
        match self {
            Self::User => opentalk_types_signaling::Role::User,
            Self::Moderator => opentalk_types_signaling::Role::Moderator,
        }
    }
}

#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize, Hash)]
#[serde(rename_all = "snake_case")]
pub enum ParticipationKind {
    Registered,
    Guest,
    Recorder,
    Transcription,
    CallIn,
    RegisteredCallIn,
}

impl From<&ClientKind> for ParticipationKind {
    fn from(value: &ClientKind) -> Self {
        match value {
            ClientKind::Registered { .. } => Self::Registered,
            ClientKind::Guest => Self::Guest,
            ClientKind::Recorder { .. } => Self::Recorder,
            ClientKind::Transcription { .. } => Self::Transcription,
            ClientKind::CallIn => Self::CallIn,
            ClientKind::RegisteredCallIn { .. } => Self::RegisteredCallIn,
        }
    }
}

#[cfg(test)]
mod tests {
    use opentalk_types_common::{roomserver::DeviceSecret, utils::ExampleData};
    use pretty_assertions::assert_eq;
    use serde_json::json;

    use super::ClientKind;
    use crate::{
        client_parameters::{ClientParameters, ParticipationKind, Role},
        public_user_profile::PublicUserProfile,
        room_kind::RoomKind,
    };

    #[test]
    fn guest() {
        let client_parameter = ClientParameters {
            device_secret: DeviceSecret::example_data(),
            kind: ClientKind::Guest,
            role: Role::User,
        };
        assert_eq!(
            client_parameter.kind.participant_kind(),
            ParticipationKind::Guest
        );

        let value = serde_json::to_value(client_parameter).unwrap();

        assert_eq!(
            value,
            json!(
                {
                    "role": "user",
                    "device_secret": "v3rys3cr3tD3v1ce5tr1ng",
                    "kind": "guest",
                }
            )
        );
    }

    #[test]
    fn registered() {
        let client_parameter = ClientParameters {
            device_secret: DeviceSecret::example_data(),
            kind: ClientKind::Registered {
                profile: PublicUserProfile::example_data(),
            },
            role: Role::User,
        };
        assert_eq!(
            client_parameter.kind.participant_kind(),
            ParticipationKind::Registered
        );

        let value = serde_json::to_value(client_parameter).unwrap();

        assert_eq!(
            value,
            json!(
                {
                    "device_secret": "v3rys3cr3tD3v1ce5tr1ng",
                    "kind": "registered",
                    "role": "user",
                    "profile": {
                        "avatar_url": "https://gravatar.com/avatar/c160f8cc69a4f0bf2b0362752353d060",
                        "display_name": "Alice Adams",
                        "email": "alice@example.com",
                        "firstname": "Alice",
                        "lastname": "Adams",
                        "id": "00000000-0000-0000-0000-0000000a11c3",
                        "title": "",
                        "timezone": "Europe/Berlin",
                    }
                }
            )
        )
    }

    #[test]
    fn service() {
        let client_parameter = ClientParameters {
            device_secret: DeviceSecret::example_data(),
            kind: ClientKind::Recorder {
                room: RoomKind::Main,
            },
            role: Role::User,
        };
        assert_eq!(
            client_parameter.kind.participant_kind(),
            ParticipationKind::Recorder
        );

        let value = serde_json::to_value(client_parameter).unwrap();

        assert_eq!(
            value,
            json!({
                "role": "user",
                "device_secret": "v3rys3cr3tD3v1ce5tr1ng",
                "kind": "recorder",
                "room": {
                    "kind": "main",
                }
            })
        );
    }

    #[test]
    fn call_in() {
        let client_parameter = ClientParameters {
            device_secret: DeviceSecret::example_data(),
            kind: ClientKind::CallIn,
            role: Role::User,
        };
        assert_eq!(
            client_parameter.kind.participant_kind(),
            ParticipationKind::CallIn
        );

        let value = serde_json::to_value(client_parameter).unwrap();

        assert_eq!(
            value,
            json!({
                "role": "user",
                "device_secret": "v3rys3cr3tD3v1ce5tr1ng",
                "kind": "call_in",
            })
        );
    }

    #[test]
    fn registered_call_in() {
        let client_parameter = ClientParameters {
            device_secret: DeviceSecret::example_data(),
            kind: ClientKind::RegisteredCallIn {
                profile: PublicUserProfile::example_data(),
            },
            role: Role::User,
        };
        assert_eq!(
            client_parameter.kind.participant_kind(),
            ParticipationKind::RegisteredCallIn
        );

        let value = serde_json::to_value(client_parameter).unwrap();

        assert_eq!(
            value,
            json!({
                "role": "user",
                "device_secret": "v3rys3cr3tD3v1ce5tr1ng",
                "kind": "registered_call_in",
                "profile": {
                    "avatar_url": "https://gravatar.com/avatar/c160f8cc69a4f0bf2b0362752353d060",
                    "display_name": "Alice Adams",
                    "email": "alice@example.com",
                    "firstname": "Alice",
                    "lastname": "Adams",
                    "id": "00000000-0000-0000-0000-0000000a11c3",
                    "title": "",
                    "timezone": "Europe/Berlin",
                }
            })
        );
    }
}