Skip to main content

fauna_api/
view.rs

1use std::collections::HashMap;
2use std::ops::Deref;
3use std::sync::atomic::{AtomicBool, Ordering};
4use std::sync::{Arc, Mutex, MutexGuard, PoisonError};
5use std::time::Duration;
6
7use base64::Engine;
8use base64::engine::general_purpose::STANDARD;
9use serde::{Deserialize, Serialize};
10use serde_json::{Value, json};
11use tokio::sync::Notify;
12use yrs::types::ToJson;
13use yrs::updates::decoder::Decode;
14use yrs::{
15    Any, Array, ArrayRef, Doc, GetString, Map, MapPrelim, MapRef, OffsetKind, Options, Origin, Out,
16    ReadTxn, Subscription, Text, Transact, Update,
17};
18
19use crate::drive::{self, DriveAuthorization};
20use crate::error::{Error, Result};
21use crate::parrot::share::Attachment;
22use crate::shared::server::{
23    Authorization, Hooks as ServerHooks, Presence, Room, connect as connect_server,
24};
25
26/// What a file opens as in its live room: `text` and `table` are edited together,
27/// `image` is annotated together, and `view` (video, audio, PDF, anything else or
28/// too large to edit) is looked at together.
29#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
30#[serde(rename_all = "lowercase")]
31pub enum Kind {
32    Text,
33    Table,
34    Image,
35    #[default]
36    View,
37}
38
39/// What you may do in a file room: `read` for share links, `write` for owners, group members and chat members.
40#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
41#[serde(rename_all = "lowercase")]
42pub enum Role {
43    #[default]
44    Read,
45    Write,
46}
47
48/// Text and tables over this size open as `view`.
49pub const EDIT_MAX_BYTES: u64 = 1024 * 1024;
50
51const TEXT_TYPES: [&str; 7] = [
52    "application/json",
53    "application/xml",
54    "application/javascript",
55    "application/x-sh",
56    "application/x-yaml",
57    "application/toml",
58    "application/x-ndjson",
59];
60const TEXT_EXTENSIONS: [&str; 48] = [
61    "txt", "md", "markdown", "json", "jsonl", "xml", "html", "htm", "css", "js", "mjs", "cjs",
62    "jsx", "ts", "tsx", "py", "rb", "go", "rs", "java", "kt", "c", "h", "cc", "cpp", "hpp", "cs",
63    "php", "sh", "bash", "zsh", "sql", "yaml", "yml", "toml", "ini", "cfg", "conf", "log", "env",
64    "r", "swift", "lua", "pl", "scala", "vue", "svelte", "tsv",
65];
66
67fn extension(name: &str) -> Option<String> {
68    let (_, extension) = name.rsplit_once('.')?;
69    Some(extension.to_ascii_lowercase())
70}
71
72/// True for files whose bytes are text.
73pub fn is_text(content_type: &str, name: &str) -> bool {
74    content_type.starts_with("text/")
75        || TEXT_TYPES.contains(&content_type)
76        || extension(name).is_some_and(|extension| TEXT_EXTENSIONS.contains(&extension.as_str()))
77}
78
79/// What a file opens as, by its type, name and size.
80pub fn kind_of(content_type: &str, name: &str, size: u64) -> Kind {
81    if content_type.starts_with("image/") {
82        return Kind::Image;
83    }
84    if size > EDIT_MAX_BYTES {
85        return Kind::View;
86    }
87    if content_type == "text/csv" || extension(name).as_deref() == Some("csv") {
88        return Kind::Table;
89    }
90    if is_text(content_type, name) {
91        return Kind::Text;
92    }
93    Kind::View
94}
95
96/// `'pen' | 'box' | 'arrow' | 'note' | 'pin'` in the TypeScript SDK.
97#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
98#[serde(rename_all = "lowercase")]
99pub enum MarkKind {
100    Pen,
101    Box,
102    Arrow,
103    Note,
104    Pin,
105}
106
107/// A mark on an image. Points run from 0 to 1 across the image's width and height.
108#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
109pub struct Mark {
110    pub id: String,
111    pub kind: MarkKind,
112    pub points: Vec<[f64; 2]>,
113    /// A note's or pin's words.
114    #[serde(default, skip_serializing_if = "Option::is_none")]
115    pub text: Option<String>,
116    /// Who made it, by email.
117    pub author: String,
118    pub color: String,
119    pub at: f64,
120}
121
122/// Rows of cells from CSV text: quoted fields, doubled quotes and CRLF all read right.
123pub fn parse_csv(text: &str) -> Vec<Vec<String>> {
124    let mut rows = Vec::new();
125    let mut row = Vec::new();
126    let mut cell = String::new();
127    let mut quoted = false;
128    let mut chars = text.chars().peekable();
129    while let Some(c) = chars.next() {
130        if quoted {
131            if c == '"' && chars.peek() == Some(&'"') {
132                cell.push('"');
133                chars.next();
134            } else if c == '"' {
135                quoted = false;
136            } else {
137                cell.push(c);
138            }
139        } else if c == '"' && cell.is_empty() {
140            quoted = true;
141        } else if c == ',' {
142            row.push(std::mem::take(&mut cell));
143        } else if c == '\n' || c == '\r' {
144            if c == '\r' && chars.peek() == Some(&'\n') {
145                chars.next();
146            }
147            row.push(std::mem::take(&mut cell));
148            rows.push(std::mem::take(&mut row));
149        } else {
150            cell.push(c);
151        }
152    }
153    if !cell.is_empty() || !row.is_empty() {
154        row.push(cell);
155        rows.push(row);
156    }
157    rows
158}
159
160/// CSV text from rows, quoting cells that need it.
161pub fn format_csv(rows: &[Vec<String>]) -> String {
162    let quote = |cell: &String| {
163        let needs = cell.contains(['"', ',', '\r', '\n'])
164            || cell.starts_with(char::is_whitespace)
165            || cell.ends_with(char::is_whitespace);
166        if needs {
167            format!("\"{}\"", cell.replace('"', "\"\""))
168        } else {
169            cell.clone()
170        }
171    };
172    let mut text = rows
173        .iter()
174        .map(|row| row.iter().map(quote).collect::<Vec<_>>().join(","))
175        .collect::<Vec<_>>()
176        .join("\n");
177    if !rows.is_empty() {
178        text.push('\n');
179    }
180    text
181}
182
183// text:  Y.Text 'text'
184// table: Y.Array 'columns' and Y.Array 'rows' of ids, and Y.Map 'cells' from a
185//        row id to a Y.Map of column id to the cell's text
186// image: Y.Array 'marks' of Mark
187
188fn radix36(mut value: u128) -> String {
189    const DIGITS: &[u8] = b"0123456789abcdefghijklmnopqrstuvwxyz";
190    let mut out = Vec::new();
191    loop {
192        out.push(DIGITS[(value % 36) as usize]);
193        value /= 36;
194        if value == 0 {
195            break;
196        }
197    }
198    out.reverse();
199    String::from_utf8(out).unwrap_or_default()
200}
201
202fn id() -> String {
203    let random = radix36(uuid::Uuid::new_v4().as_u128());
204    let now = radix36(chrono::Utc::now().timestamp_millis().max(0) as u128);
205    format!("{}{}", &random[..8], &now[now.len().saturating_sub(4)..])
206}
207
208/// A document with Yjs's text offsets (UTF-16), so indexes match every other client.
209fn new_doc() -> Doc {
210    Doc::with_options(Options {
211        offset_kind: OffsetKind::Utf16,
212        ..Options::default()
213    })
214}
215
216fn out_text<T: ReadTxn>(out: Out, txn: &T) -> String {
217    match out {
218        Out::Any(Any::String(text)) => text.to_string(),
219        out => out.to_string(txn),
220    }
221}
222
223fn strings<T: ReadTxn>(array: &ArrayRef, txn: &T) -> Vec<String> {
224    array.iter(txn).map(|out| out_text(out, txn)).collect()
225}
226
227fn position(array: &[String], item: &str) -> Option<u32> {
228    array
229        .iter()
230        .position(|other| other == item)
231        .map(|index| index as u32)
232}
233
234/// The table's cells in order, as rows of text.
235pub fn table_rows(doc: &Doc) -> Vec<Vec<String>> {
236    let columns = doc.get_or_insert_array("columns");
237    let rows = doc.get_or_insert_array("rows");
238    let cells = doc.get_or_insert_map("cells");
239    let txn = doc.transact();
240    let columns = strings(&columns, &txn);
241    strings(&rows, &txn)
242        .iter()
243        .map(|row| {
244            let map: Option<MapRef> = match cells.get(&txn, row) {
245                Some(Out::YMap(map)) => Some(map),
246                _ => None,
247            };
248            columns
249                .iter()
250                .map(|column| {
251                    map.as_ref()
252                        .and_then(|map| map.get(&txn, column))
253                        .map(|out| out_text(out, &txn))
254                        .unwrap_or_default()
255                })
256                .collect()
257        })
258        .collect()
259}
260
261/// Fill an empty table document from rows of text.
262pub fn fill_table(doc: &Doc, rows: &[Vec<String>]) {
263    let width = rows.iter().map(Vec::len).max().unwrap_or(0).max(1);
264    let columns: Vec<String> = (0..width).map(|_| id()).collect();
265    let row_ids: Vec<String> = rows.iter().map(|_| id()).collect();
266    let columns_ref = doc.get_or_insert_array("columns");
267    let rows_ref = doc.get_or_insert_array("rows");
268    let cells = doc.get_or_insert_map("cells");
269    let mut txn = doc.transact_mut();
270    let length = columns_ref.len(&txn);
271    columns_ref.insert_range(&mut txn, length, columns.clone());
272    let length = rows_ref.len(&txn);
273    rows_ref.insert_range(&mut txn, length, row_ids.clone());
274    for (r, row) in rows.iter().enumerate() {
275        let map: MapPrelim = columns
276            .iter()
277            .zip(row)
278            .filter(|(_, cell)| !cell.is_empty())
279            .map(|(column, cell)| (column.clone(), cell.clone()))
280            .collect();
281        cells.insert(&mut txn, row_ids[r].clone(), map);
282    }
283}
284
285/// Add a row (after `after`, or at the end) and return its id.
286pub fn add_row(doc: &Doc, after: Option<&str>) -> String {
287    let rows = doc.get_or_insert_array("rows");
288    let cells = doc.get_or_insert_map("cells");
289    let row = id();
290    let mut txn = doc.transact_mut();
291    let length = rows.len(&txn);
292    let index = match after {
293        Some(after) => position(&strings(&rows, &txn), after).map_or(0, |index| index + 1),
294        None => length,
295    };
296    rows.insert(&mut txn, index.min(length), row.clone());
297    cells.insert(&mut txn, row.clone(), MapPrelim::default());
298    row
299}
300
301/// Add a column (after `after`, or at the end) and return its id.
302pub fn add_column(doc: &Doc, after: Option<&str>) -> String {
303    let columns = doc.get_or_insert_array("columns");
304    let column = id();
305    let mut txn = doc.transact_mut();
306    let length = columns.len(&txn);
307    let index = match after {
308        Some(after) => position(&strings(&columns, &txn), after).map_or(0, |index| index + 1),
309        None => length,
310    };
311    columns.insert(&mut txn, index.min(length), column.clone());
312    column
313}
314
315pub fn remove_row(doc: &Doc, row: &str) {
316    let rows = doc.get_or_insert_array("rows");
317    let cells = doc.get_or_insert_map("cells");
318    let mut txn = doc.transact_mut();
319    if let Some(index) = position(&strings(&rows, &txn), row) {
320        rows.remove(&mut txn, index);
321    }
322    cells.remove(&mut txn, row);
323}
324
325pub fn remove_column(doc: &Doc, column: &str) {
326    let columns = doc.get_or_insert_array("columns");
327    let mut txn = doc.transact_mut();
328    if let Some(index) = position(&strings(&columns, &txn), column) {
329        columns.remove(&mut txn, index);
330    }
331}
332
333fn decode(content: Option<&[u8]>) -> String {
334    let text = String::from_utf8_lossy(content.unwrap_or_default());
335    text.strip_prefix('\u{feff}').unwrap_or(&text).to_string()
336}
337
338fn any_from_json(value: &Value) -> Any {
339    match value {
340        Value::Null => Any::Null,
341        Value::Bool(value) => Any::Bool(*value),
342        Value::Number(number) => Any::Number(number.as_f64().unwrap_or_default()),
343        Value::String(value) => Any::String(value.as_str().into()),
344        Value::Array(values) => Any::Array(values.iter().map(any_from_json).collect()),
345        Value::Object(fields) => Any::Map(Arc::new(
346            fields
347                .iter()
348                .map(|(key, value)| (key.clone(), any_from_json(value)))
349                .collect::<HashMap<_, _>>(),
350        )),
351    }
352}
353
354/// The largest integer a JavaScript number holds exactly.
355const MAX_SAFE_INTEGER: f64 = 9_007_199_254_740_991.0;
356
357/// A mark's fields in the order the Mark type lists them, then any others by name.
358const MARK_FIELDS: [&str; 7] = ["id", "kind", "points", "text", "author", "color", "at"];
359
360fn write_json(any: &Any, out: &mut String) {
361    match any {
362        Any::Null | Any::Undefined => out.push_str("null"),
363        Any::Bool(value) => out.push_str(if *value { "true" } else { "false" }),
364        Any::Number(number) if number.trunc() == *number && number.abs() <= MAX_SAFE_INTEGER => {
365            out.push_str(&(*number as i64).to_string())
366        }
367        Any::Number(number) => out.push_str(&Value::from(*number).to_string()),
368        Any::BigInt(int) => out.push_str(&int.to_string()),
369        Any::String(value) => out.push_str(&Value::from(value.as_ref()).to_string()),
370        Any::Buffer(bytes) => out.push_str(&Value::from(bytes.to_vec()).to_string()),
371        Any::Array(values) => {
372            out.push('[');
373            for (index, value) in values.iter().enumerate() {
374                if index > 0 {
375                    out.push(',');
376                }
377                write_json(value, out);
378            }
379            out.push(']');
380        }
381        Any::Map(fields) => {
382            let mut keys: Vec<&String> = fields
383                .iter()
384                .filter(|(_, value)| !matches!(value, Any::Undefined))
385                .map(|(key, _)| key)
386                .collect();
387            keys.sort_by_key(|key| {
388                (
389                    MARK_FIELDS
390                        .iter()
391                        .position(|field| field == key)
392                        .unwrap_or(MARK_FIELDS.len()),
393                    key.as_str(),
394                )
395            });
396            out.push('{');
397            for (index, key) in keys.into_iter().enumerate() {
398                if index > 0 {
399                    out.push(',');
400                }
401                out.push_str(&Value::from(key.as_str()).to_string());
402                out.push(':');
403                write_json(&fields[key.as_str()], out);
404            }
405            out.push('}');
406        }
407    }
408}
409
410/// A fresh document holding a file's content: its text, its CSV, or an image's marks as JSON.
411pub fn doc_from(kind: Kind, content: Option<&[u8]>) -> Doc {
412    let doc = new_doc();
413    let text = decode(content);
414    match kind {
415        Kind::Text => {
416            let shared = doc.get_or_insert_text("text");
417            shared.insert(&mut doc.transact_mut(), 0, &text);
418        }
419        Kind::Table => fill_table(&doc, &parse_csv(&text)),
420        Kind::Image => {
421            let marks = if text.is_empty() {
422                Vec::new()
423            } else {
424                match serde_json::from_str::<Value>(&text) {
425                    Ok(Value::Array(marks)) => marks,
426                    _ => Vec::new(),
427                }
428            };
429            let shared = doc.get_or_insert_array("marks");
430            shared.insert_range(&mut doc.transact_mut(), 0, marks.iter().map(any_from_json));
431        }
432        Kind::View => {}
433    }
434    doc
435}
436
437/// What a document saves as: the text, the CSV, or the marks as JSON.
438pub fn content_of(kind: Kind, doc: &Doc) -> Vec<u8> {
439    match kind {
440        Kind::Text => {
441            let text = doc.get_or_insert_text("text");
442            text.get_string(&doc.transact()).into_bytes()
443        }
444        Kind::Table => format_csv(&table_rows(doc)).into_bytes(),
445        Kind::Image => {
446            let marks = doc.get_or_insert_array("marks");
447            let mut json = String::new();
448            write_json(&marks.to_json(&doc.transact()), &mut json);
449            json.into_bytes()
450        }
451        Kind::View => Vec::new(),
452    }
453}
454
455/// Base64 for document updates on the wire.
456pub fn to_base64(bytes: &[u8]) -> String {
457    STANDARD.encode(bytes)
458}
459
460pub fn from_base64(text: &str) -> Result<Vec<u8>> {
461    STANDARD.decode(text).map_err(|_| {
462        Error::Message("The string to be decoded is not correctly encoded.".to_string())
463    })
464}
465
466/// A file to open live: a Drive file (by path or share link) or a chat attachment.
467#[derive(Debug, Clone)]
468#[allow(clippy::large_enum_variant)]
469pub enum Target {
470    File(drive::File),
471    Attachment(Attachment),
472}
473
474/// File room hooks. Every method defaults to a no-op, like the optional members
475/// of the TypeScript `Hooks` object.
476pub trait Hooks: Send + Sync {
477    /// Someone joined or left, or moved their pointer or selection.
478    fn on_people(&self, _room: &ViewRoom) {}
479    /// The file changed outside the room. Editable kinds get a new `doc` to rebind to; others reload the file.
480    fn on_reload(&self, _room: &ViewRoom) {}
481    /// The room's edits were written back to the file.
482    fn on_saved(&self, _room: &ViewRoom) {}
483    /// The room closed or the connection dropped. Connect again to rejoin.
484    fn on_closed(&self, _room: &ViewRoom) {}
485}
486
487impl Hooks for () {}
488
489/// The file as the room sees it: `{ name, contentType, contentLength }` in the
490/// TypeScript SDK.
491#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
492#[serde(rename_all = "camelCase")]
493pub struct ViewFile {
494    pub name: String,
495    pub content_type: String,
496    pub content_length: u64,
497}
498
499/// Edits are sent in batches this far apart.
500const BATCH: Duration = Duration::from_millis(50);
501const REMOTE: &str = "remote";
502
503#[derive(Default)]
504struct View {
505    kind: Kind,
506    role: Role,
507    owner: bool,
508    file: ViewFile,
509    ended: bool,
510    // Edits up to this sequence number are in the file.
511    saved: u64,
512}
513
514struct ViewState {
515    target: Target,
516    hooks: Mutex<Arc<dyn Hooks>>,
517    view: Mutex<View>,
518    doc: Mutex<Doc>,
519    subscription: Mutex<Option<Subscription>>,
520    outgoing: Mutex<Vec<Vec<u8>>>,
521    armed: AtomicBool,
522    notify: Notify,
523}
524
525fn lock<T>(mutex: &Mutex<T>) -> MutexGuard<'_, T> {
526    mutex.lock().unwrap_or_else(PoisonError::into_inner)
527}
528
529/// A live room for one file. Everyone in it sees everyone else, by seat; with
530/// `write`, edits to `doc` reach everyone and are saved back to the file.
531/// Pointers ride in each seat's position (x and y from 0 to 1, z the page) and
532/// text selections in its status.
533#[derive(Clone)]
534pub struct ViewRoom {
535    room: Room,
536    inner: Arc<ViewState>,
537}
538
539impl Deref for ViewRoom {
540    type Target = Room;
541    fn deref(&self) -> &Room {
542        &self.room
543    }
544}
545
546impl ViewRoom {
547    fn view(&self) -> MutexGuard<'_, View> {
548        lock(&self.inner.view)
549    }
550
551    fn hooks(&self) -> Arc<dyn Hooks> {
552        lock(&self.inner.hooks).clone()
553    }
554
555    pub fn target(&self) -> &Target {
556        &self.inner.target
557    }
558
559    pub fn kind(&self) -> Kind {
560        self.view().kind
561    }
562
563    pub fn role(&self) -> Role {
564        self.view().role
565    }
566
567    /// You own the file: you can remove anyone's marks on it.
568    pub fn owner(&self) -> bool {
569        self.view().owner
570    }
571
572    /// The file as the room sees it.
573    pub fn file(&self) -> ViewFile {
574        self.view().file.clone()
575    }
576
577    /// The shared document for `text`, `table` and `image`; empty for `view`.
578    pub fn doc(&self) -> Doc {
579        lock(&self.inner.doc).clone()
580    }
581
582    /// Replace the room's hooks once the UI that renders it is ready.
583    pub fn set_hooks(&self, hooks: Arc<dyn Hooks>) {
584        *lock(&self.inner.hooks) = hooks;
585    }
586
587    /// Everyone else in the room.
588    pub fn people(&self, me: Option<&Presence>) -> Vec<Presence> {
589        self.get_presences()
590            .into_iter()
591            .filter(|presence| me.is_none_or(|me| presence.id() != me.id()))
592            .collect()
593    }
594
595    /// The roster changed.
596    pub fn people_changed(&self) {
597        self.hooks().on_people(self);
598    }
599
600    pub fn hydrate(&self, state: &Value) {
601        {
602            let mut view = self.view();
603            view.kind = serde_json::from_value(state["kind"].clone()).unwrap_or_default();
604            view.role = if state["role"] == "write" {
605                Role::Write
606            } else {
607                Role::Read
608            };
609            view.owner = state["owner"] == true;
610            let file = &state["file"];
611            view.file = ViewFile {
612                name: match &file["name"] {
613                    Value::Null => String::new(),
614                    Value::String(name) => name.clone(),
615                    name => name.to_string(),
616                },
617                content_type: match &file["contentType"] {
618                    Value::Null => String::new(),
619                    Value::String(content_type) => content_type.clone(),
620                    content_type => content_type.to_string(),
621                },
622                content_length: file["contentLength"].as_f64().unwrap_or_default() as u64,
623            };
624            view.saved = state["saved"].as_f64().unwrap_or_default() as u64;
625        }
626        self.replace(state["doc"].as_str());
627    }
628
629    pub fn handle_event(&self, packet: &Value) -> bool {
630        let data = &packet["data"];
631        match packet["event"].as_str() {
632            Some("doc-update") if data["update"].is_string() => {
633                if let Ok(update) = from_base64(data["update"].as_str().unwrap_or_default()) {
634                    apply_remote(&self.doc(), &update);
635                }
636                true
637            }
638            Some("doc-reload") => {
639                if let Some(snapshot) = data["doc"].as_str() {
640                    self.replace(Some(snapshot));
641                }
642                self.hooks().on_reload(self);
643                true
644            }
645            Some("doc-saved") => {
646                let saved = data["saved"].as_f64().unwrap_or_default() as u64;
647                let newer = {
648                    let mut view = self.view();
649                    let newer = saved > view.saved;
650                    if newer {
651                        view.saved = saved;
652                    }
653                    newer
654                };
655                if newer {
656                    self.hooks().on_saved(self);
657                }
658                true
659            }
660            _ => false,
661        }
662    }
663
664    fn replace(&self, snapshot: Option<&str>) {
665        let doc = new_doc();
666        if let Some(update) = snapshot.and_then(|snapshot| from_base64(snapshot).ok()) {
667            apply_remote(&doc, &update);
668        }
669        let state = Arc::downgrade(&self.inner);
670        let subscription = doc.observe_update_v1(move |txn, event| {
671            if txn.origin() == Some(&Origin::from(REMOTE)) {
672                return;
673            }
674            let Some(state) = state.upgrade() else {
675                return;
676            };
677            {
678                let view = lock(&state.view);
679                if view.role != Role::Write || view.ended {
680                    return;
681                }
682            }
683            lock(&state.outgoing).push(event.update.clone());
684            if !state.armed.swap(true, Ordering::SeqCst) {
685                state.notify.notify_one();
686            }
687        });
688        *lock(&self.inner.subscription) = subscription.ok();
689        *lock(&self.inner.doc) = doc;
690    }
691
692    /// Send edits waiting in the batch now.
693    pub fn flush(&self) {
694        self.inner.armed.store(false, Ordering::SeqCst);
695        let outgoing = std::mem::take(&mut *lock(&self.inner.outgoing));
696        if outgoing.is_empty() {
697            return;
698        }
699        let updates = if outgoing.len() == 1 {
700            outgoing
701        } else {
702            match yrs::merge_updates_v1(&outgoing) {
703                Ok(update) => vec![update],
704                Err(_) => outgoing,
705            }
706        };
707        for update in updates {
708            self.post(&json!({ "event": "doc-update", "data": { "update": to_base64(&update) } }));
709        }
710    }
711
712    /// The connection ended: stop sending, and tell the UI once.
713    pub fn closed(&self) {
714        {
715            let mut view = self.view();
716            if view.ended {
717                return;
718            }
719            view.ended = true;
720        }
721        self.inner.notify.notify_one();
722        self.hooks().on_closed(self);
723    }
724
725    pub fn disconnect(&self) {
726        self.flush();
727        self.view().ended = true;
728        self.inner.notify.notify_one();
729        self.room.disconnect();
730    }
731}
732
733fn apply_remote(doc: &Doc, update: &[u8]) {
734    if let Ok(update) = Update::decode_v1(update) {
735        let _ = doc.transact_mut_with(REMOTE).apply_update(update);
736    }
737}
738
739struct ViewHooks {
740    inner: Arc<ViewState>,
741}
742
743impl ViewHooks {
744    fn room(&self, room: &Room) -> ViewRoom {
745        ViewRoom {
746            room: room.clone(),
747            inner: self.inner.clone(),
748        }
749    }
750}
751
752impl ServerHooks for ViewHooks {
753    fn on_connection(&self, room: &Room, state: &Value) {
754        self.room(room).hydrate(state);
755    }
756
757    fn on_event(&self, room: &Room, packet: &Value) -> bool {
758        self.room(room).handle_event(packet)
759    }
760
761    fn on_presence(&self, room: &Room) {
762        self.room(room).people_changed();
763    }
764
765    fn on_closed(&self, room: &Room, _reason: Option<&str>) {
766        self.room(room).closed();
767    }
768}
769
770fn authorization_for(target: &Target) -> Result<Authorization> {
771    let file = match target {
772        Target::Attachment(attachment) => {
773            if !attachment.chat.is_empty() && !attachment.r#ref.is_empty() {
774                let authorization = match &attachment.file.authorization {
775                    DriveAuthorization::Path { authorization, .. }
776                    | DriveAuthorization::AccessCode { authorization, .. }
777                    | DriveAuthorization::Repository { authorization, .. } => authorization.clone(),
778                };
779                return Ok(Authorization::Server {
780                    authorization,
781                    server: format!("fauna:file:chat:{}/{}", attachment.chat, attachment.r#ref),
782                    group: None,
783                });
784            }
785            &attachment.file
786        }
787        Target::File(file) => file,
788    };
789    Ok(match &file.authorization {
790        DriveAuthorization::AccessCode {
791            authorization,
792            access_code,
793        } => Authorization::AccessCode {
794            authorization: authorization.clone(),
795            access_code: access_code.clone(),
796        },
797        DriveAuthorization::Repository { .. } => {
798            return Err(Error::Message(
799                "Repository files open in Termite.".to_string(),
800            ));
801        }
802        DriveAuthorization::Path {
803            authorization,
804            path,
805            group,
806        } => Authorization::Server {
807            authorization: authorization.clone(),
808            server: format!("fauna:file:{path}"),
809            group: group.clone(),
810        },
811    })
812}
813
814/// Join the live room for a file: a Drive file (by path or share link) or a chat
815/// attachment. Owners, group members and chat members can edit; share links look.
816pub async fn connect(
817    target: Target,
818    hooks: Option<Arc<dyn Hooks>>,
819) -> Result<(ViewRoom, Presence)> {
820    let authorization = authorization_for(&target)?;
821    let inner = Arc::new(ViewState {
822        target,
823        hooks: Mutex::new(hooks.unwrap_or_else(|| Arc::new(()))),
824        view: Mutex::new(View::default()),
825        doc: Mutex::new(new_doc()),
826        subscription: Mutex::new(None),
827        outgoing: Mutex::new(Vec::new()),
828        armed: AtomicBool::new(false),
829        notify: Notify::new(),
830    });
831    let me = connect_server(
832        authorization,
833        &format!("{}/drive/live", crate::get_url()),
834        Arc::new(ViewHooks {
835            inner: inner.clone(),
836        }),
837    )
838    .await?;
839    let room = ViewRoom {
840        room: me.room().clone(),
841        inner,
842    };
843
844    let batching = room.clone();
845    tokio::spawn(async move {
846        loop {
847            batching.inner.notify.notified().await;
848            if batching.view().ended {
849                break;
850            }
851            tokio::time::sleep(BATCH).await;
852            if batching.view().ended {
853                break;
854            }
855            batching.flush();
856        }
857    });
858
859    let mut socket_closed = room.socket_closed();
860    let closing = room.clone();
861    tokio::spawn(async move {
862        let _ = socket_closed.wait_for(|closed| *closed).await;
863        closing.closed();
864    });
865
866    Ok((room, me))
867}
868
869#[cfg(test)]
870mod tests {
871    use std::sync::{Arc, Mutex};
872
873    use serde_json::{Value, json};
874    use tokio::sync::mpsc;
875    use tokio_tungstenite::tungstenite::Message;
876    use yrs::{GetString, ReadTxn, StateVector, Text, Transact};
877
878    use super::*;
879    use crate::authentification::{ApiKey, CredentialsOrApiKey};
880    use crate::drive::{FileMeta, from_access_code};
881
882    #[derive(Default)]
883    struct Recorder {
884        events: Mutex<Vec<&'static str>>,
885    }
886
887    impl Hooks for Recorder {
888        fn on_reload(&self, _room: &ViewRoom) {
889            self.events.lock().unwrap().push("reload");
890        }
891        fn on_saved(&self, _room: &ViewRoom) {
892            self.events.lock().unwrap().push("saved");
893        }
894        fn on_closed(&self, _room: &ViewRoom) {
895            self.events.lock().unwrap().push("closed");
896        }
897    }
898
899    fn view_room(recorder: Arc<Recorder>) -> (ViewRoom, mpsc::UnboundedReceiver<Message>) {
900        let (ws, outbox) = mpsc::unbounded_channel();
901        let authorization = CredentialsOrApiKey::ApiKey(ApiKey {
902            id: "key".to_string(),
903            ..ApiKey::default()
904        });
905        let file = from_access_code(authorization.clone(), "code", FileMeta::default());
906        let room = Room::new(
907            "http://localhost/drive/live".to_string(),
908            ws,
909            Authorization::AccessCode {
910                authorization,
911                access_code: "code".to_string(),
912            },
913            "room".to_string(),
914        );
915        let inner = Arc::new(ViewState {
916            target: Target::File(file),
917            hooks: Mutex::new(recorder),
918            view: Mutex::new(View::default()),
919            doc: Mutex::new(new_doc()),
920            subscription: Mutex::new(None),
921            outgoing: Mutex::new(Vec::new()),
922            armed: AtomicBool::new(false),
923            notify: Notify::new(),
924        });
925        (ViewRoom { room, inner }, outbox)
926    }
927
928    fn snapshot(text: &str) -> String {
929        let doc = doc_from(Kind::Text, Some(text.as_bytes()));
930        to_base64(
931            &doc.transact()
932                .encode_state_as_update_v1(&StateVector::default()),
933        )
934    }
935
936    fn text_of(doc: &Doc) -> String {
937        doc.get_or_insert_text("text").get_string(&doc.transact())
938    }
939
940    fn sent(outbox: &mut mpsc::UnboundedReceiver<Message>) -> Vec<Value> {
941        let mut frames = Vec::new();
942        while let Ok(Message::Text(frame)) = outbox.try_recv() {
943            frames.push(serde_json::from_str(frame.as_str()).unwrap());
944        }
945        frames
946    }
947
948    #[test]
949    fn writers_send_their_edits_and_never_echo_remote_ones() {
950        let recorder = Arc::new(Recorder::default());
951        let (room, mut outbox) = view_room(recorder.clone());
952        room.hydrate(&json!({
953            "kind": "text",
954            "role": "write",
955            "owner": true,
956            "file": { "name": "plan.md", "contentType": "text/markdown", "contentLength": 5 },
957            "saved": 2,
958            "doc": snapshot("hello"),
959        }));
960        assert_eq!(room.kind(), Kind::Text);
961        assert_eq!(room.role(), Role::Write);
962        assert!(room.owner());
963        assert_eq!(room.file().name, "plan.md");
964        assert_eq!(text_of(&room.doc()), "hello");
965
966        let peer = Doc::new();
967        apply_remote(
968            &peer,
969            &room
970                .doc()
971                .transact()
972                .encode_state_as_update_v1(&StateVector::default()),
973        );
974        let text = room.doc().get_or_insert_text("text");
975        text.insert(&mut room.doc().transact_mut(), 5, " there");
976        text.insert(&mut room.doc().transact_mut(), 0, ">");
977        room.flush();
978        let frames = sent(&mut outbox);
979        assert_eq!(frames.len(), 1);
980        assert_eq!(frames[0]["event"], "doc-update");
981        apply_remote(
982            &peer,
983            &from_base64(frames[0]["data"]["update"].as_str().unwrap()).unwrap(),
984        );
985        assert_eq!(text_of(&peer), ">hello there");
986
987        let peer_text = peer.get_or_insert_text("text");
988        let update = {
989            let before = room.doc().transact().state_vector();
990            peer_text.insert(&mut peer.transact_mut(), 0, "!");
991            peer.transact().encode_state_as_update_v1(&before)
992        };
993        assert!(room.handle_event(
994            &json!({ "event": "doc-update", "data": { "update": to_base64(&update) } })
995        ));
996        assert_eq!(text_of(&room.doc()), "!>hello there");
997        room.flush();
998        assert!(sent(&mut outbox).is_empty());
999
1000        room.handle_event(&json!({ "event": "doc-saved", "data": { "saved": 3 } }));
1001        room.handle_event(&json!({ "event": "doc-saved", "data": { "saved": 1 } }));
1002        room.handle_event(&json!({ "event": "doc-reload", "data": { "doc": snapshot("fresh") } }));
1003        assert_eq!(text_of(&room.doc()), "fresh");
1004        room.closed();
1005        room.closed();
1006        assert_eq!(
1007            *recorder.events.lock().unwrap(),
1008            vec!["saved", "reload", "closed"]
1009        );
1010
1011        let text = room.doc().get_or_insert_text("text");
1012        text.insert(&mut room.doc().transact_mut(), 0, "late ");
1013        room.flush();
1014        assert!(sent(&mut outbox).is_empty());
1015    }
1016
1017    #[test]
1018    fn readers_keep_their_edits_local() {
1019        let (room, mut outbox) = view_room(Arc::new(Recorder::default()));
1020        room.hydrate(&json!({ "kind": "text", "role": "read", "doc": snapshot("hi") }));
1021        let text = room.doc().get_or_insert_text("text");
1022        text.insert(&mut room.doc().transact_mut(), 2, "!");
1023        room.flush();
1024        assert!(sent(&mut outbox).is_empty());
1025        assert!(!room.handle_event(&json!({ "event": "something-else" })));
1026    }
1027}