Skip to main content

fauna_api/
rooms.rs

1use std::ops::Deref;
2use std::sync::{Arc, Mutex, MutexGuard, PoisonError};
3
4use chrono::{DateTime, Utc};
5use serde::{Deserialize, Serialize};
6use serde_json::{Value, json};
7
8use crate::authentification::{CredentialsOrApiKey, Profile};
9use crate::error::Result;
10use crate::http::{client, encode, ok};
11use crate::shared::server::{
12    Authorization, Hooks as ServerHooks, Presence, Room, connect as connect_server,
13};
14
15/// What a member may do: `read` sees the state, `write` can also set it.
16#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
17#[serde(rename_all = "lowercase")]
18pub enum Role {
19    #[default]
20    Read,
21    Write,
22}
23
24/// Who is in a room: every member of a group, or one person by email.
25#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
26#[serde(untagged)]
27pub enum Member {
28    Group { group: String, role: Role },
29    Email { email: String, role: Role },
30}
31
32/// A live room an app (or a person) owns. Everyone in it sees `state` change live.
33#[derive(Debug, Clone, Serialize, Deserialize)]
34pub struct LiveRoom {
35    pub id: String,
36    pub name: String,
37
38    pub members: Vec<Member>,
39
40    /// Any JSON, up to 256 KB, always set whole. Fauna never reads it.
41    pub state: Value,
42    /// Goes up by one with every state change.
43    pub version: u64,
44
45    pub created: DateTime<Utc>,
46    pub updated: DateTime<Utc>,
47}
48
49/// What `create` takes. Every field is optional.
50#[derive(Debug, Clone, Default, Serialize)]
51pub struct Draft {
52    #[serde(skip_serializing_if = "Option::is_none")]
53    pub name: Option<String>,
54    #[serde(skip_serializing_if = "Option::is_none")]
55    pub members: Option<Vec<Member>>,
56    #[serde(skip_serializing_if = "Option::is_none")]
57    pub state: Option<Value>,
58}
59
60/// Someone in a room: their profile, and which of the room's groups they're in.
61#[derive(Debug, Clone, Serialize, Deserialize)]
62pub struct Person {
63    pub profile: Profile,
64    #[serde(default)]
65    pub groups: Vec<String>,
66}
67
68/// Room hooks, plus `on_state` whenever someone changes the state. Every method
69/// defaults to a no-op.
70pub trait Hooks: ServerHooks {
71    fn on_state(&self, _room: &StateRoom, _state: &Value, _version: u64) {}
72}
73
74impl Hooks for () {}
75
76/// Make a live room. Signed in with an API key, the key owns it; otherwise you do.
77/// Only the owner changes who is in it or deletes it.
78pub async fn create(authorization: &CredentialsOrApiKey, draft: &Draft) -> Result<LiveRoom> {
79    let response = client()
80        .post(format!("{}/rooms", crate::get_url()))
81        .header(
82            "Authorization",
83            match authorization {
84                CredentialsOrApiKey::Credentials(credentials) => {
85                    format!("Token {}", credentials.token)
86                }
87                CredentialsOrApiKey::ApiKey(key) => format!("ApiKey {}", key.id),
88            },
89        )
90        .json(draft)
91        .send()
92        .await?;
93    Ok(ok(response).await?.json().await?)
94}
95
96/// A room you own or are a member of, with its state.
97pub async fn get(authorization: &CredentialsOrApiKey, id: &str) -> Result<LiveRoom> {
98    let response = client()
99        .get(format!("{}/rooms/{}", crate::get_url(), encode(id)))
100        .header(
101            "Authorization",
102            match authorization {
103                CredentialsOrApiKey::Credentials(credentials) => {
104                    format!("Token {}", credentials.token)
105                }
106                CredentialsOrApiKey::ApiKey(key) => format!("ApiKey {}", key.id),
107            },
108        )
109        .send()
110        .await?;
111    Ok(ok(response).await?.json().await?)
112}
113
114/// Everyone in a room, each group's members listed. Anyone who can read the room.
115pub async fn people(authorization: &CredentialsOrApiKey, id: &str) -> Result<Vec<Person>> {
116    let response = client()
117        .get(format!("{}/rooms/{}/people", crate::get_url(), encode(id)))
118        .header(
119            "Authorization",
120            match authorization {
121                CredentialsOrApiKey::Credentials(credentials) => {
122                    format!("Token {}", credentials.token)
123                }
124                CredentialsOrApiKey::ApiKey(key) => format!("ApiKey {}", key.id),
125            },
126        )
127        .send()
128        .await?;
129    Ok(ok(response).await?.json().await?)
130}
131
132/// Replace who is in a room. Owner only.
133pub async fn set_members(
134    authorization: &CredentialsOrApiKey,
135    id: &str,
136    members: &[Member],
137) -> Result<LiveRoom> {
138    let response = client()
139        .put(format!("{}/rooms/{}/members", crate::get_url(), encode(id)))
140        .header(
141            "Authorization",
142            match authorization {
143                CredentialsOrApiKey::Credentials(credentials) => {
144                    format!("Token {}", credentials.token)
145                }
146                CredentialsOrApiKey::ApiKey(key) => format!("ApiKey {}", key.id),
147            },
148        )
149        .json(&json!({ "members": members }))
150        .send()
151        .await?;
152    Ok(ok(response).await?.json().await?)
153}
154
155/// Replace a room's state; everyone in it sees the change. The owner and writers
156/// only. With `if_version`, it writes only while the room is still at that
157/// version. Resolves to the new version.
158pub async fn set_state(
159    authorization: &CredentialsOrApiKey,
160    id: &str,
161    state: &Value,
162    if_version: Option<u64>,
163) -> Result<u64> {
164    let response = client()
165        .put(format!("{}/rooms/{}/state", crate::get_url(), encode(id)))
166        .header(
167            "Authorization",
168            match authorization {
169                CredentialsOrApiKey::Credentials(credentials) => {
170                    format!("Token {}", credentials.token)
171                }
172                CredentialsOrApiKey::ApiKey(key) => format!("ApiKey {}", key.id),
173            },
174        )
175        .json(&json!({ "state": state, "ifVersion": if_version }))
176        .send()
177        .await?;
178    let body: Value = ok(response).await?.json().await?;
179    Ok(body["version"].as_u64().unwrap_or_default())
180}
181
182/// Delete a room; everyone in it is disconnected. Owner only.
183pub async fn remove(authorization: &CredentialsOrApiKey, id: &str) -> Result<()> {
184    let response = client()
185        .delete(format!("{}/rooms/{}", crate::get_url(), encode(id)))
186        .header(
187            "Authorization",
188            match authorization {
189                CredentialsOrApiKey::Credentials(credentials) => {
190                    format!("Token {}", credentials.token)
191                }
192                CredentialsOrApiKey::ApiKey(key) => format!("ApiKey {}", key.id),
193            },
194        )
195        .send()
196        .await?;
197    ok(response).await?;
198    Ok(())
199}
200
201#[derive(Default)]
202struct Snapshot {
203    name: String,
204    state: Value,
205    version: u64,
206    role: Role,
207}
208
209/// A live room you are in: its state, kept current, and who else is here.
210#[derive(Clone)]
211pub struct StateRoom {
212    room: Room,
213    snapshot: Arc<Mutex<Snapshot>>,
214}
215
216impl Deref for StateRoom {
217    type Target = Room;
218    fn deref(&self) -> &Room {
219        &self.room
220    }
221}
222
223struct StateHooks {
224    snapshot: Arc<Mutex<Snapshot>>,
225    user: Arc<dyn Hooks>,
226}
227
228impl StateHooks {
229    fn room(&self, room: &Room) -> StateRoom {
230        StateRoom {
231            room: room.clone(),
232            snapshot: self.snapshot.clone(),
233        }
234    }
235}
236
237impl ServerHooks for StateHooks {
238    fn create_room(&self, room: &Room, state: &Value) {
239        self.user.create_room(room, state);
240    }
241
242    fn create_presence(&self, room: &Room, presence: &Presence) {
243        self.user.create_presence(room, presence);
244    }
245
246    fn remove_presence(&self, room: &Room, presence: &Presence) {
247        self.user.remove_presence(room, presence);
248    }
249
250    fn on_connection(&self, room: &Room, state: &Value) {
251        self.room(room).hydrate(state);
252        self.user.on_connection(room, state);
253    }
254
255    fn on_event(&self, room: &Room, packet: &Value) -> bool {
256        let live = self.room(room);
257        let handled = live.handle_event(packet);
258        if handled {
259            self.user.on_state(&live, &live.state(), live.version());
260        }
261        self.user.on_event(room, packet) || handled
262    }
263
264    fn on_presence(&self, room: &Room) {
265        self.user.on_presence(room);
266    }
267
268    fn on_closed(&self, room: &Room, reason: Option<&str>) {
269        self.user.on_closed(room, reason);
270    }
271}
272
273impl StateRoom {
274    fn snapshot(&self) -> MutexGuard<'_, Snapshot> {
275        self.snapshot.lock().unwrap_or_else(PoisonError::into_inner)
276    }
277
278    pub fn name(&self) -> String {
279        self.snapshot().name.clone()
280    }
281
282    pub fn state(&self) -> Value {
283        self.snapshot().state.clone()
284    }
285
286    pub fn version(&self) -> u64 {
287        self.snapshot().version
288    }
289
290    /// What you may do here. The owner writes.
291    pub fn role(&self) -> Role {
292        self.snapshot().role
293    }
294
295    pub fn hydrate(&self, snapshot: &Value) {
296        if !snapshot.is_object() {
297            return;
298        }
299        let mut current = self.snapshot();
300        current.name = snapshot["name"].as_str().unwrap_or_default().to_string();
301        current.state = snapshot["state"].clone();
302        current.version = snapshot["version"].as_u64().unwrap_or_default();
303        current.role = if snapshot["role"] == "write" {
304            Role::Write
305        } else {
306            Role::Read
307        };
308    }
309
310    pub fn handle_event(&self, packet: &Value) -> bool {
311        if packet["event"] != "state" {
312            return false;
313        }
314        let mut current = self.snapshot();
315        current.state = packet["data"]["state"].clone();
316        if let Some(version) = packet["data"]["version"].as_u64() {
317            current.version = version;
318        }
319        true
320    }
321
322    /// Replace the state for everyone here. Writers only; with `if_version`, only
323    /// while the room is at that version.
324    pub fn set_state(&self, state: &Value, if_version: Option<u64>) {
325        self.post(&json!({
326            "event": "set-state",
327            "data": { "state": state, "ifVersion": if_version },
328        }));
329    }
330
331    pub async fn connect(
332        authorization: &CredentialsOrApiKey,
333        target_id: &str,
334        hooks: Option<Arc<dyn Hooks>>,
335    ) -> Result<(StateRoom, Presence)> {
336        let snapshot = Arc::new(Mutex::new(Snapshot::default()));
337        let me = connect_server(
338            Authorization::Server {
339                authorization: authorization.clone(),
340                server: format!("fauna:live:{target_id}"),
341                group: None,
342            },
343            &format!("{}/rooms/live", crate::get_url()),
344            Arc::new(StateHooks {
345                snapshot: snapshot.clone(),
346                user: hooks.unwrap_or_else(|| Arc::new(())),
347            }),
348        )
349        .await?;
350        let room = StateRoom {
351            room: me.room().clone(),
352            snapshot,
353        };
354        Ok((room, me))
355    }
356}