videosdk/resources/

rooms.rs

//! The rooms (meetings) API.

use std::sync::Arc;

use futures_util::Stream;
use reqwest::Method;
use serde::{Deserialize, Serialize};
use serde_json::{Map, Value};

use crate::client::{CallOptions, Client};
use crate::common::{string_enum, Region, ResourceLinks};
use crate::error::Result;
use crate::pagination::{auto_page, paginate, ListParams, Page, PageFetcher};
use crate::query::QueryBuilder;
use crate::resources::escape;

const PATH: &str = "/v2/rooms";

string_enum! {
    /// What happens when a room's session ends.
    ///
    /// This rides on every [`Room`] response, so it is an open string newtype: a
    /// closed enum would fail to deserialize — taking the whole room with it —
    /// the moment the API adds a value this SDK predates.
    AutoCloseType {
        /// End the session. The default.
        SESSION_ENDS => "session-ends",
        /// End the session and deactivate the room.
        SESSION_END_AND_DEACTIVATE => "session-end-and-deactivate",
    }
}

/// A room-level webhook subscription, as carried on a [`Room`].
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RoomWebhook {
    /// The HTTPS endpoint that receives room and session events (≤512 chars).
    #[serde(rename = "endPoint")]
    pub end_point: String,
    /// The subscribed event names. Wildcards like `session*` are accepted.
    #[serde(default, deserialize_with = "crate::common::null_to_default")]
    pub events: Vec<String>,
}

/// The auto-close behavior of a room's session, as carried on a [`Room`].
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AutoCloseConfig {
    /// What happens when the session closes.
    #[serde(rename = "type", skip_serializing_if = "Option::is_none")]
    pub kind: Option<AutoCloseType>,
    /// The maximum session duration, in seconds.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub duration: Option<u32>,
}

/// Independently starts multiple compositions of the same type.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct MultiComposition {
    /// Allow multiple concurrent recordings.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub recording: Option<bool>,
    /// Allow multiple concurrent HLS streams.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub hls: Option<bool>,
    /// Allow multiple concurrent RTMP streams.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub rtmp: Option<bool>,
}

/// Compositions to start automatically when a session begins.
///
/// Each entry mirrors the corresponding composition's start options and is
/// passed through to the API as-is.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct AutoStartConfig {
    /// Start a recording when the session begins.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub recording: Option<Value>,
    /// Start an HLS stream when the session begins.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub hls: Option<Value>,
    /// Start a composite composition when the session begins.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub composite: Option<Value>,
}

/// Subscribes a room to its session events.
#[derive(Debug, Clone)]
pub struct RoomWebhookInput {
    /// The HTTPS endpoint that receives room and session events (≤512 chars).
    pub url: String,
    /// The event names to subscribe to. Wildcards like `session*` are accepted.
    pub events: Vec<String>,
}

/// The auto-close behavior for a room's session.
#[derive(Debug, Clone, Default)]
pub struct AutoCloseConfigInput {
    /// Automatically close the session after this many seconds.
    pub after_inactive_seconds: Option<u32>,
    /// What happens when the session closes. Defaults to
    /// [`AutoCloseType::SESSION_ENDS`].
    pub kind: Option<AutoCloseType>,
}

/// The parameters for [`RoomsResource::create`].
#[derive(Debug, Clone, Default)]
pub struct RoomCreateParams {
    /// A caller-supplied stable id. Creation is idempotent on this value.
    pub custom_room_id: Option<String>,
    /// Pins the room to a region. Falls back to the API key's region.
    pub geo_fence: Option<Region>,
    /// Subscribes the room to its session events.
    pub webhook: Option<RoomWebhookInput>,
    /// The auto-close behavior when the session ends.
    pub auto_close_config: Option<AutoCloseConfigInput>,
    /// Compositions to start automatically when a session begins.
    pub auto_start_config: Option<AutoStartConfig>,
    /// Independently starts multiple compositions of the same type.
    pub multi_composition: Option<MultiComposition>,
    /// Restricts which participant ids may join.
    pub allowed_participant_ids: Option<Vec<String>>,
}

/// The wire body of a create request. The friendly parameters above rename onto
/// this: `webhook.url` becomes `webhook.endPoint`, and
/// `auto_close_config.after_inactive_seconds` becomes `autoCloseConfig.duration`.
#[derive(Debug, Serialize)]
#[serde(rename_all = "camelCase")]
struct RoomCreateWire {
    #[serde(skip_serializing_if = "Option::is_none")]
    custom_room_id: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    geo_fence: Option<Region>,
    #[serde(skip_serializing_if = "Option::is_none")]
    auto_start_config: Option<AutoStartConfig>,
    #[serde(skip_serializing_if = "Option::is_none")]
    multi_composition: Option<MultiComposition>,
    #[serde(skip_serializing_if = "Option::is_none")]
    allowed_participant_ids: Option<Vec<String>>,
    #[serde(skip_serializing_if = "Option::is_none")]
    webhook: Option<RoomWebhook>,
    #[serde(skip_serializing_if = "Option::is_none")]
    auto_close_config: Option<AutoCloseConfig>,
}

impl From<RoomCreateParams> for RoomCreateWire {
    fn from(params: RoomCreateParams) -> Self {
        Self {
            custom_room_id: params.custom_room_id,
            geo_fence: params.geo_fence,
            auto_start_config: params.auto_start_config,
            multi_composition: params.multi_composition,
            allowed_participant_ids: params.allowed_participant_ids,
            webhook: params.webhook.map(|webhook| RoomWebhook {
                end_point: webhook.url,
                events: webhook.events,
            }),
            auto_close_config: params.auto_close_config.map(|config| AutoCloseConfig {
                // The server requires a type whenever the config is present.
                kind: Some(config.kind.unwrap_or(AutoCloseType::SESSION_ENDS)),
                duration: config.after_inactive_seconds,
            }),
        }
    }
}

/// A room, a.k.a. a "meeting": a durable id that hosts live sessions.
#[derive(Debug, Clone, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Room {
    /// The room's database id.
    pub id: String,
    /// The VideoSDK room id, formatted `xxxx-xxxx-xxxx`.
    #[serde(default, deserialize_with = "crate::common::null_to_default")]
    pub room_id: String,
    /// The caller-supplied stable id, if one was given.
    pub custom_room_id: Option<String>,
    /// The API key that owns the room.
    pub api_key: Option<String>,
    /// The region the room is pinned to.
    pub geo_fence: Option<Region>,
    /// Whether the room has been deactivated.
    #[serde(default, deserialize_with = "crate::common::null_to_default")]
    pub disabled: bool,
    /// The room's webhook subscription.
    pub webhook: Option<RoomWebhook>,
    /// The room's auto-close behavior.
    pub auto_close_config: Option<AutoCloseConfig>,
    /// Compositions started automatically when a session begins.
    ///
    /// Deliberately untyped: it mirrors whichever composition options were set.
    pub auto_start_config: Option<Value>,
    /// Whether multiple compositions of the same type may run concurrently.
    pub multi_composition: Option<Value>,
    /// The participant ids permitted to join.
    #[serde(default, deserialize_with = "crate::common::null_to_default")]
    pub allowed_participant_ids: Vec<String>,
    /// When the room was created.
    pub created_at: Option<String>,
    /// When the room was last updated.
    pub updated_at: Option<String>,
    /// HATEOAS-style links to related resources.
    #[serde(default, deserialize_with = "crate::common::null_to_default")]
    pub links: ResourceLinks,
    /// Any fields the server returned that this SDK does not model yet.
    #[serde(flatten)]
    pub extra: Map<String, Value>,
}

/// The result of [`RoomsResource::validate`].
#[derive(Debug, Clone)]
pub struct RoomValidation {
    /// Whether the id belongs to the caller: it matched a `room_id` or a
    /// `custom_room_id`.
    pub valid: bool,
    /// The room id that was validated, echoed back.
    pub room_id: String,
    /// The resolved room. Present only when [`valid`](RoomValidation::valid).
    pub room: Option<Room>,
}

/// The query parameters for [`RoomsResource::list`].
#[derive(Debug, Clone, Default)]
pub struct RoomListParams {
    /// The 1-based page number.
    pub page: Option<u32>,
    /// Items per page.
    pub per_page: Option<u32>,
    /// An opaque cursor from a previous page. Overrides `page` and `per_page`.
    pub cursor: Option<String>,
    /// An exact match on `room_id` or `custom_room_id`.
    pub query: Option<String>,
    /// Scopes the listing to a specific user. Admin tokens only.
    pub user_id: Option<String>,
}

impl RoomListParams {
    fn pagination(&self) -> ListParams {
        ListParams {
            page: self.page,
            per_page: self.per_page,
            cursor: self.cursor.clone(),
        }
    }
}

/// The rooms (meetings) API. Reached via [`Client::rooms`].
#[derive(Debug, Clone, Copy)]
pub struct RoomsResource<'a> {
    client: &'a Client,
}

impl<'a> RoomsResource<'a> {
    pub(crate) fn new(client: &'a Client) -> Self {
        Self { client }
    }

    /// Creates a room. Idempotent when `custom_room_id` is supplied.
    pub async fn create(&self, params: RoomCreateParams) -> Result<Room> {
        let body = RoomCreateWire::from(params);
        self.client
            .json(Method::POST, PATH, CallOptions::json(&body)?)
            .await
    }

    /// Lists rooms, one page at a time.
    pub async fn list(&self, params: RoomListParams) -> Result<Page<Room>> {
        paginate(self.fetcher(&params), &params.pagination(), "data", None).await
    }

    /// Lists rooms, transparently fetching every page.
    pub fn list_stream(&self, params: RoomListParams) -> impl Stream<Item = Result<Room>> + Send {
        auto_page(self.fetcher(&params), params.pagination(), "data", None)
    }

    /// Fetches a room by `id`, `room_id`, or `custom_room_id`.
    pub async fn get(&self, room_id: &str) -> Result<Room> {
        let path = format!("{PATH}/{}", escape(room_id));
        self.client
            .json(Method::GET, &path, CallOptions::new())
            .await
    }

    /// Reports whether a room id belongs to the caller.
    ///
    /// Returns `valid: false` rather than an error for an unknown id — the API
    /// answers those with 400, 402 or 404.
    pub async fn validate(&self, room_id: &str) -> Result<RoomValidation> {
        let path = format!("{PATH}/validate/{}", escape(room_id));
        match self
            .client
            .json::<Room>(Method::GET, &path, CallOptions::new())
            .await
        {
            Ok(room) => Ok(RoomValidation {
                valid: true,
                room_id: if room.room_id.is_empty() {
                    room_id.to_string()
                } else {
                    room.room_id.clone()
                },
                room: Some(room),
            }),
            Err(err) if matches!(err.status(), Some(400 | 402 | 404)) => Ok(RoomValidation {
                valid: false,
                room_id: room_id.to_string(),
                room: None,
            }),
            Err(err) => Err(err),
        }
    }

    /// Deactivates a room and returns the now-disabled room.
    ///
    /// Unlike [`get`](RoomsResource::get) and
    /// [`validate`](RoomsResource::validate), this resolves only the VideoSDK
    /// `room_id`; a `custom_room_id` is rejected with a 402.
    pub async fn end(&self, room_id: &str) -> Result<Room> {
        let body = serde_json::json!({ "roomId": room_id });
        self.client
            .json(
                Method::POST,
                "/v2/rooms/deactivate",
                CallOptions::json(&body)?,
            )
            .await
    }

    fn fetcher(&self, params: &RoomListParams) -> PageFetcher {
        let client = self.client.clone();
        let query = params.query.clone();
        let user_id = params.user_id.clone();

        Arc::new(move |page, per_page| {
            let client = client.clone();
            let query = query.clone();
            let user_id = user_id.clone();
            Box::pin(async move {
                let params = QueryBuilder::new()
                    .opt("page", page)
                    .opt("perPage", per_page)
                    .opt_str("query", query.as_deref())
                    .opt_str("userId", user_id.as_deref())
                    .into_pairs();
                client
                    .json::<Value>(Method::GET, PATH, CallOptions::new().query(params))
                    .await
            })
        })
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use serde_json::json;

    fn wire(params: RoomCreateParams) -> Value {
        serde_json::to_value(RoomCreateWire::from(params)).unwrap()
    }

    #[test]
    fn an_empty_create_sends_an_empty_body() {
        assert_eq!(wire(RoomCreateParams::default()), json!({}));
    }

    #[test]
    fn webhook_url_is_renamed_to_end_point() {
        let body = wire(RoomCreateParams {
            webhook: Some(RoomWebhookInput {
                url: "https://example.com/hook".into(),
                events: vec!["session-started".into()],
            }),
            ..Default::default()
        });
        assert_eq!(
            body["webhook"],
            json!({"endPoint": "https://example.com/hook", "events": ["session-started"]})
        );
        assert!(body["webhook"].get("url").is_none());
    }

    #[test]
    fn auto_close_seconds_are_renamed_to_duration_with_a_default_type() {
        let body = wire(RoomCreateParams {
            auto_close_config: Some(AutoCloseConfigInput {
                after_inactive_seconds: Some(300),
                kind: None,
            }),
            ..Default::default()
        });
        // The server rejects an auto-close config with no `type`.
        assert_eq!(
            body["autoCloseConfig"],
            json!({"type": "session-ends", "duration": 300})
        );
    }

    #[test]
    fn an_explicit_auto_close_type_is_preserved() {
        let body = wire(RoomCreateParams {
            auto_close_config: Some(AutoCloseConfigInput {
                after_inactive_seconds: None,
                kind: Some(AutoCloseType::SESSION_END_AND_DEACTIVATE),
            }),
            ..Default::default()
        });
        assert_eq!(
            body["autoCloseConfig"],
            json!({"type": "session-end-and-deactivate"})
        );
    }

    #[test]
    fn remaining_fields_pass_through_camel_cased() {
        let body = wire(RoomCreateParams {
            custom_room_id: Some("my-room".into()),
            geo_fence: Some(Region::IN002),
            allowed_participant_ids: Some(vec!["p-1".into()]),
            multi_composition: Some(MultiComposition {
                recording: Some(true),
                ..Default::default()
            }),
            ..Default::default()
        });
        assert_eq!(
            body,
            json!({
                "customRoomId": "my-room",
                "geoFence": "in002",
                "allowedParticipantIds": ["p-1"],
                "multiComposition": {"recording": true},
            })
        );
    }

    #[test]
    fn a_room_keeps_unmodeled_fields_in_extra() {
        let room: Room = serde_json::from_value(json!({
            "id": "db-1",
            "roomId": "abcd-efgh-ijkl",
            "somethingNew": 42,
        }))
        .unwrap();
        assert_eq!(room.room_id, "abcd-efgh-ijkl");
        assert!(!room.disabled);
        assert_eq!(room.extra.get("somethingNew"), Some(&json!(42)));
    }
}