fauna-api 1.0.686

The Fauna SDK for Rust: accounts, Drive, groups, calendar, chats, payments, Parrot and live rooms.
Documentation
use std::ops::Deref;
use std::sync::{Arc, Mutex, MutexGuard, PoisonError};

use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};
use serde_json::{Value, json};

use crate::authentification::{CredentialsOrApiKey, Profile};
use crate::error::Result;
use crate::http::{client, encode, ok};
use crate::shared::server::{
    Authorization, Hooks as ServerHooks, Presence, Room, connect as connect_server,
};

/// What a member may do: `read` sees the state, `write` can also set it.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum Role {
    #[default]
    Read,
    Write,
}

/// Who is in a room: every member of a group, or one person by email.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(untagged)]
pub enum Member {
    Group { group: String, role: Role },
    Email { email: String, role: Role },
}

/// A live room an app (or a person) owns. Everyone in it sees `state` change live.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct LiveRoom {
    pub id: String,
    pub name: String,

    pub members: Vec<Member>,

    /// Any JSON, up to 256 KB, always set whole. Fauna never reads it.
    pub state: Value,
    /// Goes up by one with every state change.
    pub version: u64,

    pub created: DateTime<Utc>,
    pub updated: DateTime<Utc>,
}

/// What `create` takes. Every field is optional.
#[derive(Debug, Clone, Default, Serialize)]
pub struct Draft {
    #[serde(skip_serializing_if = "Option::is_none")]
    pub name: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub members: Option<Vec<Member>>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub state: Option<Value>,
}

/// Someone in a room: their profile, and which of the room's groups they're in.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Person {
    pub profile: Profile,
    #[serde(default)]
    pub groups: Vec<String>,
}

/// Room hooks, plus `on_state` whenever someone changes the state. Every method
/// defaults to a no-op.
pub trait Hooks: ServerHooks {
    fn on_state(&self, _room: &StateRoom, _state: &Value, _version: u64) {}
}

impl Hooks for () {}

/// Make a live room. Signed in with an API key, the key owns it; otherwise you do.
/// Only the owner changes who is in it or deletes it.
pub async fn create(authorization: &CredentialsOrApiKey, draft: &Draft) -> Result<LiveRoom> {
    let response = client()
        .post(format!("{}/rooms", crate::get_url()))
        .header(
            "Authorization",
            match authorization {
                CredentialsOrApiKey::Credentials(credentials) => {
                    format!("Token {}", credentials.token)
                }
                CredentialsOrApiKey::ApiKey(key) => format!("ApiKey {}", key.id),
            },
        )
        .json(draft)
        .send()
        .await?;
    Ok(ok(response).await?.json().await?)
}

/// A room you own or are a member of, with its state.
pub async fn get(authorization: &CredentialsOrApiKey, id: &str) -> Result<LiveRoom> {
    let response = client()
        .get(format!("{}/rooms/{}", crate::get_url(), encode(id)))
        .header(
            "Authorization",
            match authorization {
                CredentialsOrApiKey::Credentials(credentials) => {
                    format!("Token {}", credentials.token)
                }
                CredentialsOrApiKey::ApiKey(key) => format!("ApiKey {}", key.id),
            },
        )
        .send()
        .await?;
    Ok(ok(response).await?.json().await?)
}

/// Everyone in a room, each group's members listed. Anyone who can read the room.
pub async fn people(authorization: &CredentialsOrApiKey, id: &str) -> Result<Vec<Person>> {
    let response = client()
        .get(format!("{}/rooms/{}/people", crate::get_url(), encode(id)))
        .header(
            "Authorization",
            match authorization {
                CredentialsOrApiKey::Credentials(credentials) => {
                    format!("Token {}", credentials.token)
                }
                CredentialsOrApiKey::ApiKey(key) => format!("ApiKey {}", key.id),
            },
        )
        .send()
        .await?;
    Ok(ok(response).await?.json().await?)
}

/// Replace who is in a room. Owner only.
pub async fn set_members(
    authorization: &CredentialsOrApiKey,
    id: &str,
    members: &[Member],
) -> Result<LiveRoom> {
    let response = client()
        .put(format!("{}/rooms/{}/members", crate::get_url(), encode(id)))
        .header(
            "Authorization",
            match authorization {
                CredentialsOrApiKey::Credentials(credentials) => {
                    format!("Token {}", credentials.token)
                }
                CredentialsOrApiKey::ApiKey(key) => format!("ApiKey {}", key.id),
            },
        )
        .json(&json!({ "members": members }))
        .send()
        .await?;
    Ok(ok(response).await?.json().await?)
}

/// Replace a room's state; everyone in it sees the change. The owner and writers
/// only. With `if_version`, it writes only while the room is still at that
/// version. Resolves to the new version.
pub async fn set_state(
    authorization: &CredentialsOrApiKey,
    id: &str,
    state: &Value,
    if_version: Option<u64>,
) -> Result<u64> {
    let response = client()
        .put(format!("{}/rooms/{}/state", crate::get_url(), encode(id)))
        .header(
            "Authorization",
            match authorization {
                CredentialsOrApiKey::Credentials(credentials) => {
                    format!("Token {}", credentials.token)
                }
                CredentialsOrApiKey::ApiKey(key) => format!("ApiKey {}", key.id),
            },
        )
        .json(&json!({ "state": state, "ifVersion": if_version }))
        .send()
        .await?;
    let body: Value = ok(response).await?.json().await?;
    Ok(body["version"].as_u64().unwrap_or_default())
}

/// Delete a room; everyone in it is disconnected. Owner only.
pub async fn remove(authorization: &CredentialsOrApiKey, id: &str) -> Result<()> {
    let response = client()
        .delete(format!("{}/rooms/{}", crate::get_url(), encode(id)))
        .header(
            "Authorization",
            match authorization {
                CredentialsOrApiKey::Credentials(credentials) => {
                    format!("Token {}", credentials.token)
                }
                CredentialsOrApiKey::ApiKey(key) => format!("ApiKey {}", key.id),
            },
        )
        .send()
        .await?;
    ok(response).await?;
    Ok(())
}

#[derive(Default)]
struct Snapshot {
    name: String,
    state: Value,
    version: u64,
    role: Role,
}

/// A live room you are in: its state, kept current, and who else is here.
#[derive(Clone)]
pub struct StateRoom {
    room: Room,
    snapshot: Arc<Mutex<Snapshot>>,
}

impl Deref for StateRoom {
    type Target = Room;
    fn deref(&self) -> &Room {
        &self.room
    }
}

struct StateHooks {
    snapshot: Arc<Mutex<Snapshot>>,
    user: Arc<dyn Hooks>,
}

impl StateHooks {
    fn room(&self, room: &Room) -> StateRoom {
        StateRoom {
            room: room.clone(),
            snapshot: self.snapshot.clone(),
        }
    }
}

impl ServerHooks for StateHooks {
    fn create_room(&self, room: &Room, state: &Value) {
        self.user.create_room(room, state);
    }

    fn create_presence(&self, room: &Room, presence: &Presence) {
        self.user.create_presence(room, presence);
    }

    fn remove_presence(&self, room: &Room, presence: &Presence) {
        self.user.remove_presence(room, presence);
    }

    fn on_connection(&self, room: &Room, state: &Value) {
        self.room(room).hydrate(state);
        self.user.on_connection(room, state);
    }

    fn on_event(&self, room: &Room, packet: &Value) -> bool {
        let live = self.room(room);
        let handled = live.handle_event(packet);
        if handled {
            self.user.on_state(&live, &live.state(), live.version());
        }
        self.user.on_event(room, packet) || handled
    }

    fn on_presence(&self, room: &Room) {
        self.user.on_presence(room);
    }

    fn on_closed(&self, room: &Room, reason: Option<&str>) {
        self.user.on_closed(room, reason);
    }
}

impl StateRoom {
    fn snapshot(&self) -> MutexGuard<'_, Snapshot> {
        self.snapshot.lock().unwrap_or_else(PoisonError::into_inner)
    }

    pub fn name(&self) -> String {
        self.snapshot().name.clone()
    }

    pub fn state(&self) -> Value {
        self.snapshot().state.clone()
    }

    pub fn version(&self) -> u64 {
        self.snapshot().version
    }

    /// What you may do here. The owner writes.
    pub fn role(&self) -> Role {
        self.snapshot().role
    }

    pub fn hydrate(&self, snapshot: &Value) {
        if !snapshot.is_object() {
            return;
        }
        let mut current = self.snapshot();
        current.name = snapshot["name"].as_str().unwrap_or_default().to_string();
        current.state = snapshot["state"].clone();
        current.version = snapshot["version"].as_u64().unwrap_or_default();
        current.role = if snapshot["role"] == "write" {
            Role::Write
        } else {
            Role::Read
        };
    }

    pub fn handle_event(&self, packet: &Value) -> bool {
        if packet["event"] != "state" {
            return false;
        }
        let mut current = self.snapshot();
        current.state = packet["data"]["state"].clone();
        if let Some(version) = packet["data"]["version"].as_u64() {
            current.version = version;
        }
        true
    }

    /// Replace the state for everyone here. Writers only; with `if_version`, only
    /// while the room is at that version.
    pub fn set_state(&self, state: &Value, if_version: Option<u64>) {
        self.post(&json!({
            "event": "set-state",
            "data": { "state": state, "ifVersion": if_version },
        }));
    }

    pub async fn connect(
        authorization: &CredentialsOrApiKey,
        target_id: &str,
        hooks: Option<Arc<dyn Hooks>>,
    ) -> Result<(StateRoom, Presence)> {
        let snapshot = Arc::new(Mutex::new(Snapshot::default()));
        let me = connect_server(
            Authorization::Server {
                authorization: authorization.clone(),
                server: format!("fauna:live:{target_id}"),
                group: None,
            },
            &format!("{}/rooms/live", crate::get_url()),
            Arc::new(StateHooks {
                snapshot: snapshot.clone(),
                user: hooks.unwrap_or_else(|| Arc::new(())),
            }),
        )
        .await?;
        let room = StateRoom {
            room: me.room().clone(),
            snapshot,
        };
        Ok((room, me))
    }
}