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