y-rb 0.1.7-arm64-darwin → 0.2.0-arm64-darwin

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5c7ae82dbb88d508d98b1e87f7f7e67a102bb97ca228a8deea669c10e38ba2e1
-  data.tar.gz: b72afe1360223ef130a5b9861766bbace0e9faf56ffa66d174d933814de91362
+  metadata.gz: cd1b418e9e3364905d97ce0738d366214c90de9ba04c9718f3ff33d8b1a96c18
+  data.tar.gz: 59b503f6eee7cf2f53aef6a1ab947957192cec3efc872f3fbf800f452e910d7d
 SHA512:
-  metadata.gz: df0ea4eea521ea3a0c49519410f416b30f4e51667c7777274079391f99bdc9c07aaa4ec8da18dace0964cf187d57787b45fc15245e675a707cee0dc781d30467
-  data.tar.gz: 920bf7721948ee98a2711a358e6bac813a360acba8158dd1371024f1d83186344a6639ab432dfcedc359cfff9151ea9dbad05055347a7d39d1c95a867b54b744
+  metadata.gz: b8bff25911b00e3bad728b0e5f8a1d38a7371e3bcc07fa651d48524b3bdc8df25549e0a9a3ee5af6908940d682beb2f88de1b4cbf24184a7382bbbeb998d5617
+  data.tar.gz: 9f1f811cc68c2c950204a3d6cc4b158114abf55ad5b1ecaa09b665f2fc51052796b3c66b2a35925963e983011a82119ae74f05911b506ffc955ecfd7f36b0ac1

data/ext/yrb/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "yrb"
-version = "0.1.7"
+version = "0.2.0"
 authors = ["Hannes Moser <box@hannesmoser.at>", "Hannes Moser <hmoser@gitlab.com>"]
 edition = "2021"
 homepage = "https://github.com/y-crdt/yrb"
@@ -9,6 +9,7 @@ repository = "https://github.com/y-crdt/yrb"
 [dependencies]
 lib0 = "0.12.0" # must match yrs version
 magnus = { git = "https://github.com/matsadler/magnus", rev = "cc852bfa31992d882d42509b1165eb5f67f9dc2c" } # waiting for release with full rb-sys backend
+thiserror = "1.0.37"
 yrs = "0.12.0"
 
 [dev-dependencies]

data/ext/yrb/src/awareness.rs

@@ -0,0 +1,440 @@
+use std::cell::RefCell;
+use std::collections::hash_map::Entry;
+use std::collections::HashMap;
+use std::rc::{Rc, Weak};
+use std::time::Instant;
+use thiserror::Error;
+use yrs::block::ClientID;
+use yrs::updates::decoder::{Decode, Decoder};
+use yrs::updates::encoder::{Encode, Encoder};
+use yrs::{Doc, SubscriptionId};
+
+const NULL_STR: &str = "null";
+
+/// The Awareness class implements a simple shared state protocol that can be used for non-persistent
+/// data like awareness information (cursor, username, status, ..). Each client can update its own
+/// local state and listen to state changes of remote clients.
+///
+/// Each client is identified by a unique client id (something we borrow from `doc.clientID`).
+/// A client can override its own state by propagating a message with an increasing timestamp
+/// (`clock`). If such a message is received, it is applied if the known state of that client is
+/// older than the new state (`clock < new_clock`). If a client thinks that a remote client is
+/// offline, it may propagate a message with `{ clock, state: null, client }`. If such a message is
+/// received, and the known clock of that client equals the received clock, it will clean the state.
+///
+/// Before a client disconnects, it should propagate a `null` state with an updated clock.
+pub struct Awareness {
+    doc: Doc,
+    states: HashMap<ClientID, String>,
+    meta: HashMap<ClientID, MetaClientState>,
+    on_update: Option<EventHandler<Event>>
+}
+
+unsafe impl Send for Awareness {}
+unsafe impl Sync for Awareness {}
+
+impl Awareness {
+    /// Creates a new instance of [Awareness] struct, which operates over a given document.
+    /// Awareness instance has full ownership of that document. If necessary it can be accessed
+    /// using either [Awareness::doc] or [Awareness::doc_mut] methods.
+    pub fn new(doc: Doc) -> Self {
+        Awareness {
+            doc,
+            on_update: None,
+            states: HashMap::new(),
+            meta: HashMap::new()
+        }
+    }
+
+    /// Returns a channel receiver for an incoming awareness events. This channel can be cloned.
+    pub fn on_update<F>(&mut self, f: F) -> Subscription<Event>
+    where
+        F: Fn(&Awareness, &Event) -> () + 'static
+    {
+        let eh = self.on_update.get_or_insert_with(EventHandler::default);
+        eh.subscribe(f)
+    }
+
+    /// Removes a receiver for incoming awareness events.
+    pub fn remove_on_update(&mut self, subscription_id: u32) {
+        if let Some(eh) = self.on_update.as_mut() {
+            eh.unsubscribe(subscription_id);
+        }
+    }
+
+    /// Returns a globally unique client ID of an underlying [Doc].
+    pub fn client_id(&self) -> ClientID {
+        self.doc.client_id
+    }
+
+    /// Returns a state map of all of the clients tracked by current [Awareness] instance. Those
+    /// states are identified by their corresponding [ClientID]s. The associated state is
+    /// represented and replicated to other clients as a JSON string.
+    pub fn clients(&self) -> &HashMap<ClientID, String> {
+        &self.states
+    }
+
+    /// Returns a JSON string state representation of a current [Awareness] instance.
+    pub fn local_state(&self) -> Option<&str> {
+        Some(self.states.get(&self.doc.client_id)?.as_str())
+    }
+
+    /// Sets a current [Awareness] instance state to a corresponding JSON string. This state will
+    /// be replicated to other clients as part of the [AwarenessUpdate] and it will trigger an event
+    /// to be emitted if current instance was created using [Awareness::with_observer] method.
+    ///
+    pub fn set_local_state<S: Into<String>>(&mut self, json: S) {
+        let client_id = self.doc.client_id;
+        self.update_meta(client_id);
+        let new: String = json.into();
+        match self.states.entry(client_id) {
+            Entry::Occupied(mut e) => {
+                e.insert(new);
+                if let Some(eh) = self.on_update.as_ref() {
+                    eh.trigger(
+                        self,
+                        &Event::new(vec![], vec![client_id], vec![])
+                    );
+                }
+            }
+            Entry::Vacant(e) => {
+                e.insert(new);
+                if let Some(eh) = self.on_update.as_ref() {
+                    eh.trigger(
+                        self,
+                        &Event::new(vec![client_id], vec![], vec![])
+                    );
+                }
+            }
+        }
+    }
+
+    /// Clears out a state of a given client, effectively marking it as disconnected.
+    pub fn remove_state(&mut self, client_id: ClientID) {
+        let prev_state = self.states.remove(&client_id);
+        self.update_meta(client_id);
+        if let Some(eh) = self.on_update.as_ref() {
+            if prev_state.is_some() {
+                eh.trigger(
+                    self,
+                    &Event::new(
+                        Vec::default(),
+                        Vec::default(),
+                        vec![client_id]
+                    )
+                );
+            }
+        }
+    }
+
+    /// Clears out a state of a current client (see: [Awareness::client_id]),
+    /// effectively marking it as disconnected.
+    pub fn clean_local_state(&mut self) {
+        let client_id = self.doc.client_id;
+        self.remove_state(client_id);
+    }
+
+    fn update_meta(&mut self, client_id: ClientID) {
+        match self.meta.entry(client_id) {
+            Entry::Occupied(mut e) => {
+                let clock = e.get().clock + 1;
+                let meta = MetaClientState::new(clock, Instant::now());
+                e.insert(meta);
+            }
+            Entry::Vacant(e) => {
+                e.insert(MetaClientState::new(1, Instant::now()));
+            }
+        }
+    }
+
+    /// Returns a serializable update object which is representation of a current Awareness state.
+    pub fn update(&self) -> Result<AwarenessUpdate, Error> {
+        let clients = self.states.keys().cloned();
+        self.update_with_clients(clients)
+    }
+
+    /// Returns a serializable update object which is representation of a current Awareness state.
+    /// Unlike [Awareness::update], this method variant allows to prepare update only for a subset
+    /// of known clients. These clients must all be known to a current [Awareness] instance,
+    /// otherwise a [Error::ClientNotFound] error will be returned.
+    pub fn update_with_clients<I: IntoIterator<Item = ClientID>>(
+        &self,
+        clients: I
+    ) -> Result<AwarenessUpdate, Error> {
+        let mut res = HashMap::new();
+        for client_id in clients {
+            let clock = if let Some(meta) = self.meta.get(&client_id) {
+                meta.clock
+            } else {
+                return Err(Error::ClientNotFound(client_id));
+            };
+            let json = if let Some(json) = self.states.get(&client_id) {
+                json.clone()
+            } else {
+                String::from(NULL_STR)
+            };
+            res.insert(client_id, AwarenessUpdateEntry { clock, json });
+        }
+        Ok(AwarenessUpdate { clients: res })
+    }
+
+    /// Applies an update (incoming from remote channel or generated using [Awareness::update] /
+    /// [Awareness::update_with_clients] methods) and modifies a state of a current instance.
+    ///
+    /// If current instance has an observer channel (see: [Awareness::with_observer]), applied
+    /// changes will also be emitted as events.
+    pub fn apply_update(
+        &mut self,
+        update: AwarenessUpdate
+    ) -> Result<(), Error> {
+        let now = Instant::now();
+
+        let mut added = Vec::new();
+        let mut updated = Vec::new();
+        let mut removed = Vec::new();
+
+        for (client_id, entry) in update.clients {
+            let mut clock = entry.clock;
+            let is_null = entry.json.as_str() == NULL_STR;
+            match self.meta.entry(client_id) {
+                Entry::Occupied(mut e) => {
+                    let prev = e.get();
+                    let is_removed = prev.clock == clock
+                        && is_null
+                        && self.states.contains_key(&client_id);
+                    let is_new = prev.clock < clock;
+                    if is_new || is_removed {
+                        if is_null {
+                            // never let a remote client remove this local state
+                            if client_id == self.doc.client_id
+                                && self.states.get(&client_id).is_some()
+                            {
+                                // remote client removed the local state. Do not remote state. Broadcast a message indicating
+                                // that this client still exists by increasing the clock
+                                clock += 1;
+                            } else {
+                                self.states.remove(&client_id);
+                                if self.on_update.is_some() {
+                                    removed.push(client_id);
+                                }
+                            }
+                        } else {
+                            match self.states.entry(client_id) {
+                                Entry::Occupied(mut e) => {
+                                    if self.on_update.is_some() {
+                                        updated.push(client_id);
+                                    }
+                                    e.insert(entry.json);
+                                }
+                                Entry::Vacant(e) => {
+                                    e.insert(entry.json);
+                                    if self.on_update.is_some() {
+                                        updated.push(client_id);
+                                    }
+                                }
+                            }
+                        }
+                        e.insert(MetaClientState::new(clock, now));
+                        true
+                    } else {
+                        false
+                    }
+                }
+                Entry::Vacant(e) => {
+                    e.insert(MetaClientState::new(clock, now));
+                    self.states.insert(client_id, entry.json);
+                    if self.on_update.is_some() {
+                        added.push(client_id);
+                    }
+                    true
+                }
+            };
+        }
+
+        if let Some(eh) = self.on_update.as_ref() {
+            if !added.is_empty() || !updated.is_empty() || !removed.is_empty() {
+                eh.trigger(self, &Event::new(added, updated, removed));
+            }
+        }
+
+        Ok(())
+    }
+}
+
+impl Default for Awareness {
+    fn default() -> Self {
+        Awareness::new(Doc::new())
+    }
+}
+
+struct EventHandler<T> {
+    seq_nr: u32,
+    subscribers: Rc<RefCell<HashMap<u32, Box<dyn Fn(&Awareness, &T) -> ()>>>>
+}
+
+impl<T> EventHandler<T> {
+    pub fn subscribe<F>(&mut self, f: F) -> Subscription<T>
+    where
+        F: Fn(&Awareness, &T) -> () + 'static
+    {
+        let subscription_id = self.seq_nr;
+        self.seq_nr += 1;
+        {
+            let func = Box::new(f);
+            let mut subs = self.subscribers.borrow_mut();
+            subs.insert(subscription_id, func);
+        }
+        Subscription {
+            subscription_id,
+            subscribers: Rc::downgrade(&self.subscribers)
+        }
+    }
+
+    pub fn unsubscribe(&mut self, subscription_id: u32) {
+        let mut subs = self.subscribers.borrow_mut();
+        subs.remove(&subscription_id);
+    }
+
+    pub fn trigger(&self, awareness: &Awareness, arg: &T) {
+        let subs = self.subscribers.borrow();
+        for func in subs.values() {
+            func(awareness, arg);
+        }
+    }
+}
+
+impl<T> Default for EventHandler<T> {
+    fn default() -> Self {
+        EventHandler {
+            seq_nr: 0,
+            subscribers: Rc::new(RefCell::new(HashMap::new()))
+        }
+    }
+}
+
+/// Whenever a new callback is being registered, a [Subscription] is made. Whenever this
+/// subscription a registered callback is cancelled and will not be called any more.
+pub struct Subscription<T> {
+    subscription_id: u32,
+    subscribers: Weak<RefCell<HashMap<u32, Box<dyn Fn(&Awareness, &T) -> ()>>>>
+}
+
+impl<T> Into<SubscriptionId> for Subscription<T> {
+    fn into(self) -> SubscriptionId {
+        let id = self.subscription_id;
+        std::mem::forget(self);
+        id
+    }
+}
+
+impl<T> Drop for Subscription<T> {
+    fn drop(&mut self) {
+        if let Some(subs) = self.subscribers.upgrade() {
+            let mut s = subs.borrow_mut();
+            s.remove(&self.subscription_id);
+        }
+    }
+}
+
+/// A structure that represents an encodable state of an [Awareness] struct.
+#[derive(Debug, Eq, PartialEq)]
+pub struct AwarenessUpdate {
+    clients: HashMap<ClientID, AwarenessUpdateEntry>
+}
+
+impl Encode for AwarenessUpdate {
+    fn encode<E: Encoder>(&self, encoder: &mut E) {
+        encoder.write_var(self.clients.len());
+        for (&client_id, e) in self.clients.iter() {
+            encoder.write_var(client_id);
+            encoder.write_var(e.clock);
+            encoder.write_string(&e.json);
+        }
+    }
+}
+
+impl Decode for AwarenessUpdate {
+    fn decode<D: Decoder>(decoder: &mut D) -> Result<Self, lib0::error::Error> {
+        let len: usize = decoder.read_var()?;
+        let mut clients = HashMap::with_capacity(len);
+        for _ in 0..len {
+            let client_id: ClientID = decoder.read_var()?;
+            let clock: u32 = decoder.read_var()?;
+            let json = decoder.read_string()?.to_string();
+            clients.insert(client_id, AwarenessUpdateEntry { clock, json });
+        }
+
+        Ok(AwarenessUpdate { clients })
+    }
+}
+
+/// A single client entry of an [AwarenessUpdate]. It consists of logical clock and JSON client
+/// state represented as a string.
+#[derive(Debug, Eq, PartialEq)]
+pub struct AwarenessUpdateEntry {
+    clock: u32,
+    json: String
+}
+
+/// Errors generated by an [Awareness] struct methods.
+#[derive(Error, Debug)]
+pub enum Error {
+    /// Client ID was not found in [Awareness] metadata.
+    #[error("client ID `{0}` not found")]
+    ClientNotFound(ClientID)
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct MetaClientState {
+    clock: u32,
+    last_updated: Instant
+}
+
+impl MetaClientState {
+    fn new(clock: u32, last_updated: Instant) -> Self {
+        MetaClientState {
+            clock,
+            last_updated
+        }
+    }
+}
+
+/// Event type emitted by an [Awareness] struct.
+#[derive(Debug, Default, Clone, Eq, PartialEq)]
+pub struct Event {
+    added: Vec<ClientID>,
+    updated: Vec<ClientID>,
+    removed: Vec<ClientID>
+}
+
+impl Event {
+    pub fn new(
+        added: Vec<ClientID>,
+        updated: Vec<ClientID>,
+        removed: Vec<ClientID>
+    ) -> Self {
+        Event {
+            added,
+            updated,
+            removed
+        }
+    }
+
+    /// Collection of new clients that have been added to an [Awareness] struct, that was not known
+    /// before. Actual client state can be accessed via `awareness.clients().get(client_id)`.
+    pub fn added(&self) -> &[ClientID] {
+        &self.added
+    }
+
+    /// Collection of new clients that have been updated within an [Awareness] struct since the last
+    /// update. Actual client state can be accessed via `awareness.clients().get(client_id)`.
+    pub fn updated(&self) -> &[ClientID] {
+        &self.updated
+    }
+
+    /// Collection of new clients that have been removed from [Awareness] struct since the last
+    /// update.
+    pub fn removed(&self) -> &[ClientID] {
+        &self.removed
+    }
+}

data/ext/yrb/src/lib.rs

@@ -1,4 +1,7 @@
+extern crate core;
+
 use crate::yarray::YArray;
+use crate::yawareness::{YAwareness, YAwarenessEvent, YAwarenessUpdate};
 use crate::ydoc::YDoc;
 use crate::ymap::YMap;
 use crate::ytext::YText;
@@ -7,10 +10,12 @@ use crate::yxml_element::YXmlElement;
 use crate::yxml_text::YXmlText;
 use magnus::{define_module, function, method, Error, Module, Object};
 
+mod awareness;
 mod utils;
 mod yany;
 mod yarray;
 mod yattrs;
+mod yawareness;
 mod ydoc;
 mod ymap;
 mod ytext;
@@ -472,5 +477,104 @@ fn init() -> Result<(), Error> {
         )
         .expect("cannot define private method: yxml_text_to_s");
 
+    let yawareness = module
+        .define_class("Awareness", Default::default())
+        .expect("cannot define class Y::Awareness");
+    yawareness
+        .define_singleton_method(
+            "new",
+            function!(YAwareness::yawareness_new, 0)
+        )
+        .expect("cannot define singleton method: yawareness_new");
+    yawareness
+        .define_private_method(
+            "yawareness_apply_update",
+            method!(YAwareness::yawareness_apply_update, 1)
+        )
+        .expect("cannot define private method: yawareness_apply_update");
+    yawareness
+        .define_private_method(
+            "yawareness_clean_local_state",
+            method!(YAwareness::yawareness_clean_local_state, 0)
+        )
+        .expect("cannot define private method: yawareness_clean_local_state");
+    yawareness
+        .define_private_method(
+            "yawareness_clients",
+            method!(YAwareness::yawareness_clients, 0)
+        )
+        .expect("cannot define private method: yawareness_clients");
+    yawareness
+        .define_private_method(
+            "yawareness_client_id",
+            method!(YAwareness::yawareness_client_id, 0)
+        )
+        .expect("cannot define private method: yawareness_client_id");
+    yawareness
+        .define_private_method(
+            "yawareness_local_state",
+            method!(YAwareness::yawareness_local_state, 0)
+        )
+        .expect("cannot define private method: yawareness_local_state");
+    yawareness
+        .define_private_method(
+            "yawareness_on_update",
+            method!(YAwareness::yawareness_on_update, 1)
+        )
+        .expect("cannot define private method: yawareness_on_update");
+    yawareness
+        .define_private_method(
+            "yawareness_remove_on_update",
+            method!(YAwareness::yawareness_remove_on_update, 1)
+        )
+        .expect("cannot define private method: yawareness_remove_on_update");
+    yawareness
+        .define_private_method(
+            "yawareness_remove_state",
+            method!(YAwareness::yawareness_remove_state, 1)
+        )
+        .expect("cannot define private method: yawareness_remove_state");
+    yawareness
+        .define_private_method(
+            "yawareness_set_local_state",
+            method!(YAwareness::yawareness_set_local_state, 1)
+        )
+        .expect("cannot define private method: yawareness_set_local_state");
+    yawareness
+        .define_private_method(
+            "yawareness_update",
+            method!(YAwareness::yawareness_update, 0)
+        )
+        .expect("cannot define private method: yawareness_update");
+    yawareness
+        .define_private_method(
+            "yawareness_update_with_clients",
+            method!(YAwareness::yawareness_update_with_clients, 1)
+        )
+        .expect("cannot define private method: yawareness_update_with_clients");
+
+    let yawareness_update = module
+        .define_class("AwarenessUpdate", Default::default())
+        .expect("cannot define class Y:AwarenessUpdate");
+    yawareness_update
+        .define_private_method(
+            "yawareness_update_encode",
+            method!(YAwarenessUpdate::yawareness_update_encode, 0)
+        )
+        .expect("cannot define private method: yawareness_update_encode");
+
+    let yawareness_event = module
+        .define_class("AwarenessEvent", Default::default())
+        .expect("cannot define class Y:AwarenessEvent");
+    yawareness_event
+        .define_method("added", method!(YAwarenessEvent::added, 0))
+        .expect("cannot define private method: added");
+    yawareness_event
+        .define_method("updated", method!(YAwarenessEvent::updated, 0))
+        .expect("cannot define private method: updated");
+    yawareness_event
+        .define_method("removed", method!(YAwarenessEvent::removed, 0))
+        .expect("cannot define private method: removed");
+
     Ok(())
 }

data/ext/yrb/src/yarray.rs

@@ -15,7 +15,7 @@ pub(crate) struct YArray(pub(crate) RefCell<Array>);
 unsafe impl Send for YArray {}
 
 impl YArray {
-    pub(crate) fn yarray_each(&self, block: Proc) -> () {
+    pub(crate) fn yarray_each(&self, block: Proc) {
         self.0.borrow_mut().iter().for_each(|val| {
             let yvalue = YValue::from(val);
             let args = (yvalue.into(),);
@@ -31,7 +31,7 @@ impl YArray {
         transaction: &YTransaction,
         index: u32,
         value: Value
-    ) -> () {
+    ) {
         let yvalue = YValue::from(value);
         let avalue = Any::from(yvalue);
         self.0.borrow_mut().insert(
@@ -45,7 +45,7 @@ impl YArray {
         transaction: &YTransaction,
         index: u32,
         values: RArray
-    ) -> () {
+    ) {
         let arr: Vec<Any> = values
             .each()
             .into_iter()
@@ -103,7 +103,7 @@ impl YArray {
                     })
                     .partition(Result::is_ok);
 
-                if errors.len() == 0 {
+                if errors.is_empty() {
                     let args = (RArray::from_vec(
                         changes.into_iter().map(Result::unwrap).collect()
                     ),);
@@ -123,7 +123,7 @@ impl YArray {
         &self,
         transaction: &YTransaction,
         value: Value
-    ) -> () {
+    ) {
         let yvalue = YValue::from(value);
         let avalue = Any::from(yvalue);
         self.0
@@ -134,7 +134,7 @@ impl YArray {
         &self,
         transaction: &YTransaction,
         value: Value
-    ) -> () {
+    ) {
         let yvalue = YValue::from(value);
         let avalue = Any::from(yvalue);
         self.0
@@ -145,7 +145,7 @@ impl YArray {
         &self,
         transaction: &YTransaction,
         index: u32
-    ) -> () {
+    ) {
         self.0
             .borrow_mut()
             .remove(&mut transaction.0.borrow_mut(), index)
@@ -155,7 +155,7 @@ impl YArray {
         transaction: &YTransaction,
         index: u32,
         len: u32
-    ) -> () {
+    ) {
         self.0.borrow_mut().remove_range(
             &mut transaction.0.borrow_mut(),
             index,
@@ -170,9 +170,9 @@ impl YArray {
             .map(|v| YValue::from(v).into())
             .collect::<Vec<Value>>();
 
-        return RArray::from_vec(arr);
+        RArray::from_vec(arr)
     }
-    pub(crate) fn yarray_unobserve(&self, subscription_id: u32) -> () {
+    pub(crate) fn yarray_unobserve(&self, subscription_id: u32) {
         self.0.borrow_mut().unobserve(subscription_id);
     }
 }

data/ext/yrb/src/yattrs.rs

@@ -10,7 +10,7 @@ pub(crate) struct YAttrs(pub(crate) Attrs);
 
 impl From<Attrs> for YAttrs {
     fn from(value: Attrs) -> Self {
-        YAttrs { 0: value }
+        YAttrs(value)
     }
 }
 
@@ -29,7 +29,7 @@ impl From<RHash> for YAttrs {
             })
             .expect("cannot iterate attributes hash");
 
-        YAttrs { 0: attrs }
+        YAttrs(attrs)
     }
 }
 

data/ext/yrb/src/yawareness.rs

@@ -0,0 +1,163 @@
+use crate::awareness::{Awareness, AwarenessUpdate, Event};
+use magnus::block::Proc;
+use magnus::{Error, Value};
+use std::borrow::Borrow;
+use std::cell::RefCell;
+use std::collections::HashMap;
+use yrs::block::ClientID;
+use yrs::updates::decoder::Decode;
+use yrs::updates::encoder::Encode;
+use yrs::Doc;
+
+#[magnus::wrap(class = "Y::Awareness")]
+pub(crate) struct YAwareness(pub(crate) RefCell<Awareness>);
+
+/// SAFETY: This is safe because we only access this data when the GVL is held.
+unsafe impl Send for YAwareness {}
+
+impl YAwareness {
+    pub(crate) fn yawareness_new() -> Self {
+        let doc = Doc::new();
+        let awareness = Awareness::new(doc);
+
+        Self(RefCell::new(awareness))
+    }
+
+    pub(crate) fn yawareness_apply_update(
+        &self,
+        update: &YAwarenessUpdate
+    ) -> Result<(), Error> {
+        update.decode().and_then(|value| {
+            self.0.borrow_mut().apply_update(value).map_err(|_error| {
+                Error::runtime_error("cannot decode awareness update")
+            })
+        })
+    }
+
+    pub(crate) fn yawareness_clean_local_state(&self) {
+        self.0.borrow_mut().clean_local_state();
+    }
+
+    pub(crate) fn yawareness_client_id(&self) -> ClientID {
+        self.0.borrow().client_id()
+    }
+
+    pub(crate) fn yawareness_clients(&self) -> HashMap<ClientID, String> {
+        self.0.borrow().clients().to_owned()
+    }
+
+    pub(crate) fn yawareness_local_state(&self) -> Option<String> {
+        self.0.borrow().local_state().map(|value| value.to_string())
+    }
+
+    pub(crate) fn yawareness_on_update(
+        &self,
+        block: Proc
+    ) -> Result<u32, Error> {
+        let subscription_id = self
+            .0
+            .borrow_mut()
+            .on_update(move |_awareness, event| {
+                let awareness_event = YAwarenessEvent::from(event);
+                let args = (awareness_event,);
+                block
+                    .call::<(YAwarenessEvent,), Value>(args)
+                    .expect("cannot call block: on_update");
+            })
+            .into();
+
+        Ok(subscription_id)
+    }
+
+    pub(crate) fn yawareness_remove_on_update(&self, subscription_id: u32) {
+        self.0.borrow_mut().remove_on_update(subscription_id)
+    }
+
+    pub(crate) fn yawareness_remove_state(&self, client_id: ClientID) {
+        self.0.borrow_mut().remove_state(client_id)
+    }
+
+    pub(crate) fn yawareness_set_local_state(&self, json: String) {
+        self.0.borrow_mut().set_local_state(json)
+    }
+
+    pub(crate) fn yawareness_update(&self) -> Result<YAwarenessUpdate, Error> {
+        self.0
+            .borrow_mut()
+            .update()
+            .map(YAwarenessUpdate::from)
+            .map_err(|_error| Error::runtime_error("cannot update awareness"))
+    }
+
+    pub(crate) fn yawareness_update_with_clients(
+        &self,
+        clients: Vec<ClientID>
+    ) -> Result<YAwarenessUpdate, Error> {
+        self.0
+            .borrow_mut()
+            .update_with_clients(clients)
+            .map(YAwarenessUpdate::from)
+            .map_err(|_error| {
+                Error::runtime_error("cannot update awareness with clients")
+            })
+    }
+}
+
+impl From<Awareness> for YAwareness {
+    fn from(value: Awareness) -> Self {
+        Self(RefCell::from(value))
+    }
+}
+
+#[magnus::wrap(class = "Y::AwarenessUpdate")]
+pub(crate) struct YAwarenessUpdate(pub(crate) Vec<u8>);
+
+/// SAFETY: This is safe because we only access this data when the GVL is held.
+unsafe impl Send for YAwarenessUpdate {}
+
+impl YAwarenessUpdate {
+    pub(crate) fn decode(&self) -> Result<AwarenessUpdate, Error> {
+        AwarenessUpdate::decode_v1(self.0.borrow()).map_err(|_error| {
+            Error::runtime_error("cannot decode awareness update")
+        })
+    }
+    pub(crate) fn yawareness_update_encode(&self) -> Vec<u8> {
+        self.0.to_vec()
+    }
+}
+
+impl From<AwarenessUpdate> for YAwarenessUpdate {
+    fn from(value: AwarenessUpdate) -> Self {
+        YAwarenessUpdate(value.encode_v1())
+    }
+}
+
+impl From<Vec<u8>> for YAwarenessUpdate {
+    fn from(value: Vec<u8>) -> Self {
+        YAwarenessUpdate(value)
+    }
+}
+
+#[magnus::wrap(class = "Y::AwarenessEvent")]
+pub(crate) struct YAwarenessEvent(Event);
+
+/// SAFETY: This is safe because we only access this data when the GVL is held.
+unsafe impl Send for YAwarenessEvent {}
+
+impl YAwarenessEvent {
+    pub(crate) fn added(&self) -> Vec<ClientID> {
+        self.0.borrow().added().to_vec()
+    }
+    pub(crate) fn updated(&self) -> Vec<ClientID> {
+        self.0.borrow().updated().to_vec()
+    }
+    pub(crate) fn removed(&self) -> Vec<ClientID> {
+        self.0.borrow().removed().to_vec()
+    }
+}
+
+impl From<&Event> for YAwarenessEvent {
+    fn from(value: &Event) -> Self {
+        Self(value.clone())
+    }
+}

data/ext/yrb/src/ydoc.rs

@@ -26,14 +26,14 @@ impl YDoc {
     pub(crate) fn ydoc_transact(&self) -> YTransaction {
         let transaction = self.0.borrow().transact();
 
-        return YTransaction(RefCell::new(transaction));
+        YTransaction(RefCell::new(transaction))
     }
     pub(crate) fn ydoc_encode_diff_v1(
         &self,
-        state_vector: Vec<u8>,
+        state_vector: Vec<u8>
     ) -> Result<Vec<u8>, Error> {
-        return StateVector::decode_v1(&*state_vector)
+        StateVector::decode_v1(&*state_vector)
             .map(|sv| self.0.borrow().encode_state_as_update_v1(&sv))
-            .map_err(|_e| Error::runtime_error("cannot encode diff"));
+            .map_err(|_e| Error::runtime_error("cannot encode diff"))
     }
 }

data/ext/yrb/src/ymap.rs

@@ -76,7 +76,7 @@ impl YMap {
                         EntryChange::Inserted(v) => {
                             let h = RHash::new();
                             h.aset(
-                                Symbol::new(&key.to_string()),
+                                Symbol::new(key),
                                 *YValue::from(v.clone()).0.borrow()
                             )
                             .expect("cannot add change::inserted");
@@ -100,7 +100,7 @@ impl YMap {
                                 .expect("cannot push change::updated");
 
                             let h = RHash::new();
-                            h.aset(Symbol::new(&key.to_string()), values)
+                            h.aset(Symbol::new(key), values)
                                 .expect("cannot push change::updated");
 
                             let payload = RHash::new();
@@ -115,7 +115,7 @@ impl YMap {
                         EntryChange::Removed(v) => {
                             let h = RHash::new();
                             h.aset(
-                                Symbol::new(&key.to_string()),
+                                Symbol::new(key),
                                 *YValue::from(v.clone()).0.borrow()
                             )
                             .expect("cannot push change::removed");

data/ext/yrb/src/ytext.rs

@@ -153,7 +153,7 @@ impl YText {
                         Delta::Retain(index, attrs) => {
                             let payload = RHash::new();
 
-                            let yvalue = YValue::from(index.clone());
+                            let yvalue = YValue::from(*index);
 
                             payload
                                 .aset(delta_retain, yvalue.0.into_inner())
@@ -183,7 +183,7 @@ impl YText {
                         Delta::Deleted(index) => {
                             let payload = RHash::new();
 
-                            let yvalue = YValue::from(index.clone());
+                            let yvalue = YValue::from(*index);
 
                             payload
                                 .aset(delta_delete, yvalue.0.into_inner())
@@ -194,7 +194,7 @@ impl YText {
                     })
                     .partition(Result::is_ok);
 
-                if errors.len() > 0 {
+                if !errors.is_empty() {
                     // todo: make sure we respect errors and let the method fail by
                     //  by returning a Result containing an Error
                 }

data/ext/yrb/src/ytransaction.rs

@@ -30,17 +30,17 @@ impl YTransaction {
     pub(crate) fn ytransaction_get_array(&self, name: String) -> YArray {
         let a = self.0.borrow_mut().get_array(&*name);
 
-        return YArray(RefCell::from(a));
+        YArray(RefCell::from(a))
     }
     pub(crate) fn ytransaction_get_map(&self, name: String) -> YMap {
         let m = self.0.borrow_mut().get_map(&*name);
 
-        return YMap(RefCell::from(m));
+        YMap(RefCell::from(m))
     }
     pub(crate) fn ytransaction_get_text(&self, name: String) -> YText {
         let t = self.0.borrow_mut().get_text(&*name);
 
-        return YText(RefCell::new(t));
+        YText(RefCell::new(t))
     }
     pub(crate) fn ytransaction_get_xml_element(
         &self,
@@ -48,12 +48,12 @@ impl YTransaction {
     ) -> YXmlElement {
         let el = self.0.borrow_mut().get_xml_element(&*name);
 
-        return YXmlElement(RefCell::new(el));
+        YXmlElement(RefCell::new(el))
     }
     pub(crate) fn ytransaction_get_xml_text(&self, name: String) -> YXmlText {
         let t = self.0.borrow_mut().get_xml_text(&*name);
 
-        return YXmlText(RefCell::new(t));
+        YXmlText(RefCell::new(t))
     }
     pub(crate) fn ytransaction_state_vector(&self) -> Vec<u8> {
         return self.0.borrow_mut().state_vector().encode_v1();

data/ext/yrb/src/yxml_element.rs

@@ -15,7 +15,7 @@ unsafe impl Send for YXmlElement {}
 
 impl YXmlElement {
     pub(crate) fn yxml_element_attributes(&self) -> RHash {
-        RHash::from_iter(self.0.borrow().attributes().into_iter())
+        RHash::from_iter(self.0.borrow().attributes())
     }
     pub(crate) fn yxml_element_first_child(&self) -> Option<Value> {
         self.yxml_element_get(0)

data/ext/yrb/src/yxml_text.rs

@@ -14,7 +14,7 @@ unsafe impl Send for YXmlText {}
 
 impl YXmlText {
     pub(crate) fn yxml_text_attributes(&self) -> RHash {
-        RHash::from_iter(self.0.borrow().attributes().into_iter())
+        RHash::from_iter(self.0.borrow().attributes())
     }
     pub(crate) fn yxml_text_format(
         &self,

data/lib/y/awareness.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module Y
+  class Awareness
+    def apply_update(update)
+      yawareness_apply_update(update)
+    end
+
+    def clean_local_state
+      yawareness_clean_local_state
+    end
+
+    def client_id
+      yawareness_client_id
+    end
+
+    def clients
+      yawareness_clients
+    end
+
+    def local_state
+      yawareness_local_state
+    end
+
+    def local_state=(json)
+      yawareness_set_local_state(json)
+    end
+
+    def attach(callback, &block)
+      return yawareness_on_update(callback) unless callback.nil?
+
+      yawareness_on_update(block.to_proc) unless block.nil?
+    end
+
+    def detach(subscription_id)
+      yawareness_remove_on_update(subscription_id)
+    end
+
+    def remove_state(client_id)
+      yawareness_remove_state(client_id)
+    end
+
+    def update
+      yawareness_update
+    end
+
+    def update_with_clients(clients)
+      yawareness_update_with_clients(clients)
+    end
+
+    private
+
+    # @!method yawareness_apply_update(update)
+    #   Applies an update
+    #
+    # @param [Y::AwarenessUpdate] A structure that represents an encodable state
+    #   of an Awareness struct.
+
+    # @!method yawareness_clean_local_state
+    #   Clears out a state of a current client , effectively marking it as
+    #   disconnected.
+
+    # @!method yawareness_client_id
+    #   Returns a globally unique client ID of an underlying Doc.
+    # @return [Integer] The Client ID
+
+    # @!method yawareness_clients
+    #   Returns a state map of all of the clients
+    #   tracked by current Awareness instance. Those states are identified by
+    #   their corresponding ClientIDs. The associated state is represented and
+    #   replicated to other clients as a JSON string.
+    #
+    # @return [Hash<Integer, String>] Map of clients
+
+    # @!method yawareness_local_state
+    #
+    # @return [String|nil] Returns a JSON string state representation of a
+    #   current Awareness instance.
+
+    # @!method yawareness_on_update(callback, &block)
+    #
+    # @param [Proc] A callback handler for updates
+    # @return [Integer] The subscription ID
+
+    # @!method yawareness_remove_on_update(subscription_id)
+    #
+    # @param [Integer] subscription_id The subscription id to remove
+
+    # @!method yawareness_remove_state(client_id)
+    #   Clears out a state of a given client, effectively marking it as
+    #   disconnected.
+    #
+    # @param [Integer] A Client ID
+    # @return [String|nil] Returns a JSON string state representation of a
+    #   current Awareness instance.
+
+    # @!method yawareness_set_local_state(state)
+    #   Sets a current Awareness instance state to a corresponding JSON string.
+    #   This state will be replicated to other clients as part of the
+    #   AwarenessUpdate and it will trigger an event to be emitted if current
+    #   instance was created using [Awareness::with_observer] method.
+    #
+    # @param [String] Returns a state map of all of the clients tracked by
+    #   current Awareness instance. Those states are identified by their
+    #   corresponding ClientIDs. The associated state is represented and
+    #   replicated to other clients as a JSON string.
+
+    # @!method yawareness_update
+    #   Returns a serializable update object which is representation of a
+    #   current Awareness state.
+    #
+    # @return [Y::AwarenessUpdate] The update object
+
+    # @!method yawareness_update_with_clients(clients)
+    #   Returns a serializable update object which is representation of a
+    #   current Awareness state. Unlike [Y::Awareness#update], this method
+    #   variant allows to prepare update only for a subset of known clients.
+    #   These clients must all be known to a current Awareness instance,
+    #   otherwise an error will be returned.
+    #
+    # @param [Array<Integer>]
+    # @return [Y::AwarenessUpdate] The update object
+  end
+
+  # rubocop:disable Lint/EmptyClass
+  class AwarenessEvent
+    private
+
+    # @!method added
+    # @return [Array<Integer>] Added clients
+
+    # @!method updated
+    # @return [Array<Integer>] Updated clients
+
+    # @!method removed
+    # @return [Array<Integer>] Removed clients
+  end
+  # rubocop:enable Lint/EmptyClass
+
+  class AwarenessUpdate
+    def encode
+      yawareness_update_encode
+    end
+
+    private
+
+    # @!method yawareness_update_encode
+    #   Encode the awareness state for simple transport
+    #
+    # @return [Array<Integer>] Encoded update
+  end
+end

data/lib/y/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Y
-  VERSION = "0.1.7"
+  VERSION = "0.2.0"
 end

data/lib/y-rb.rb

@@ -9,6 +9,7 @@ rescue LoadError
 end
 
 require_relative "y/array"
+require_relative "y/awareness"
 require_relative "y/doc"
 require_relative "y/map"
 require_relative "y/text"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: y-rb
 version: !ruby/object:Gem::Version
-  version: 0.1.7
+  version: 0.2.0
 platform: arm64-darwin
 authors:
 - Hannes Moser
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-10-10 00:00:00.000000000 Z
+date: 2022-10-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -76,11 +76,13 @@ extra_rdoc_files: []
 files:
 - ext/yrb/Cargo.toml
 - ext/yrb/extconf.rb
+- ext/yrb/src/awareness.rs
 - ext/yrb/src/lib.rs
 - ext/yrb/src/utils.rs
 - ext/yrb/src/yany.rs
 - ext/yrb/src/yarray.rs
 - ext/yrb/src/yattrs.rs
+- ext/yrb/src/yawareness.rs
 - ext/yrb/src/ydoc.rs
 - ext/yrb/src/ymap.rs
 - ext/yrb/src/ytext.rs
@@ -94,6 +96,7 @@ files:
 - lib/y-rb.rb
 - lib/y.rb
 - lib/y/array.rb
+- lib/y/awareness.rb
 - lib/y/doc.rb
 - lib/y/map.rb
 - lib/y/text.rb