y-rb 0.3.0-x86_64-linux → 0.3.1-x86_64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3e764ed148987200b5fbc12af9eaab5d190a92d84cc030598ea26bf27e00de6a
-  data.tar.gz: ae736fae3d90db89290fde484491ed72e214655cc62420cf4a72a056f715a508
+  metadata.gz: 94ee494d71cb95886592130f1aa7b764af02f88273b7c823e5bb3b6cf79ee8b3
+  data.tar.gz: f642a14aa03767aba59754ca064ff958e79f16265141a103c91f6f186e58428e
 SHA512:
-  metadata.gz: c47ffa342eb4a60b90f3c1e3da79f69429f0373a3361aa2b6316118c9d4c7c9b75234a8941bbbe7d8b3a6bcebb92123836eabed7ef6978349768fd99b90a59d4
-  data.tar.gz: 570cb9f86a7d37c990a80ff89bfa97a03b2a96261088f6c729d451a2791f6ac1ef8f36f4a81e1040b35562f66bcf1dd352d0cb52bc82bc43a889bff18c7cf172
+  metadata.gz: 86b47de7253c9350799726b85e636c1716489533d4e39d145d0a505477f024813f9f42b8f223e8ac3a89183cf912aba41c1bc4b5d746c02f61f159f235437367
+  data.tar.gz: '08c8e3b9440cfe0bee4c5ba754cc15ed790da9e1cf7ef69d984d45cbde0fadde0fba621e6928faa9798937215e4a282808601460907d3c8bb9adf4bb5493df43'

data/ext/yrb/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "yrb"
-version = "0.3.0"
+version = "0.3.1"
 authors = ["Hannes Moser <box@hannesmoser.at>", "Hannes Moser <hmoser@gitlab.com>"]
 edition = "2021"
 homepage = "https://github.com/y-crdt/yrb"

data/ext/yrb/src/lib.rs

@@ -1,7 +1,7 @@
 extern crate core;
 
 use crate::yarray::YArray;
-use crate::yawareness::{YAwareness, YAwarenessEvent, YAwarenessUpdate};
+use crate::yawareness::{YAwareness, YAwarenessEvent};
 use crate::ydoc::YDoc;
 use crate::ymap::YMap;
 use crate::ytext::YText;
@@ -488,16 +488,6 @@ fn init() -> Result<(), Error> {
         )
         .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");

data/ext/yrb/src/yawareness.rs

@@ -23,13 +23,15 @@ impl YAwareness {
         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_apply_update(&self, update: Vec<u8>) -> Result<(), Error> {
+        AwarenessUpdate::decode_v1(update.as_slice())
+            .map_err(|_error| Error::runtime_error("cannot decode update"))
+            .and_then(|value| {
+                self.0
+                    .borrow_mut()
+                    .apply_update(value)
+                    .map_err(|_error| Error::runtime_error("cannot apply awareness update"))
+            })
     }
 
     pub(crate) fn yawareness_clean_local_state(&self) {
@@ -76,23 +78,25 @@ impl YAwareness {
         self.0.borrow_mut().set_local_state(json)
     }
 
-    pub(crate) fn yawareness_update(&self) -> Result<YAwarenessUpdate, Error> {
+    pub(crate) fn yawareness_update(&self) -> Result<Vec<u8>, Error> {
         self.0
             .borrow_mut()
             .update()
-            .map(YAwarenessUpdate::from)
-            .map_err(|_error| Error::runtime_error("cannot update awareness"))
+            .map(|update| update.encode_v1())
+            .map_err(|_error| Error::runtime_error("cannot create update for current state"))
     }
 
     pub(crate) fn yawareness_update_with_clients(
         &self,
         clients: Vec<ClientID>,
-    ) -> Result<YAwarenessUpdate, Error> {
+    ) -> Result<Vec<u8>, Error> {
         self.0
             .borrow_mut()
             .update_with_clients(clients)
-            .map(YAwarenessUpdate::from)
-            .map_err(|_error| Error::runtime_error("cannot update awareness with clients"))
+            .map(|update| update.encode_v1())
+            .map_err(|_error| {
+                Error::runtime_error("cannot create update for current state and given clients")
+            })
     }
 }
 
@@ -102,34 +106,6 @@ impl From<Awareness> for YAwareness {
     }
 }
 
-#[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);
 

data/lib/y/awareness.rb

@@ -1,50 +1,168 @@
 # frozen_string_literal: true
 
 module Y
+  # 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.client_id). 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.
+  #
+  # Awareness is an integral part of collaborative applications, you can read
+  # more about the concept here: https://docs.yjs.dev/getting-started/adding-awareness
+  #
+  # @example Instantiate awareness instance and encode update for broadcast
+  #   local_state = {
+  #     editing: { field: "description", pos: 0 },
+  #     name: "Hannes Moser"
+  #   }.to_json
+  #
+  #   awareness = Y::Awareness.new
+  #   awareness.local_state = local_state
+  #   awareness.diff # [1,227,245,175,195,11,1,65,123, …]
+  #
+  #
   class Awareness
-    def apply_update(update)
-      yawareness_apply_update(update)
+    # Applies an incoming update. This gets the local awareness instance in
+    # sync with changes from another client. i.e., updates the state of another
+    # user in the local awareness instance.
+    #
+    # @example Apply an incoming update
+    #   update = [1,227,245,175,195,11,1,65,123, …]
+    #
+    #   awareness = Y::Awareness.new
+    #   awareness.sync(update)
+    #
+    # @param [Array<Integer>] diff A binary encoded update
+    # @return [void]
+    def sync(diff)
+      yawareness_apply_update(diff)
     end
 
+    # Clears out a state of a current client, effectively marking it as
+    # disconnected.
+    #
+    # @return [void]
     def clean_local_state
       yawareness_clean_local_state
     end
 
+    # Returns a globally unique client ID of an underlying Doc.
+    #
+    # @return [Integer] Returns the client_id of the local user
     def client_id
       yawareness_client_id
     end
 
+    # 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.
+    #
+    # @example Instantiate awareness instance and encode update for broadcast
+    #   local_state = {
+    #     editing: { field: "description", pos: 0 },
+    #     name: "Hannes Moser"
+    #   }.to_json
+    #
+    #   awareness = Y::Awareness.new
+    #   awareness.local_state = local_state
+    #   awareness.clients # {312134501=>"{\"editing\":{\"field\":\"descriptio …
+    #
+    # @return [Hash] All clients and their current state
     def clients
       yawareness_clients
     end
 
+    # Returns a JSON string state representation of a current Awareness
+    # instance.
+    #
+    # @example Create local state and inspect it
+    #   local_state = {
+    #     editing: { field: "description", pos: 0 },
+    #     name: "Hannes Moser"
+    #   }.to_json
+    #
+    #   awareness = Y::Awareness.new
+    #   awareness.local_state = local_state
+    #   local_state # "{\"editing\":{\"field\":\"description\",\"pos\":0}, …
+    #
+    # @return [String] The current state of the local client
     def local_state
       yawareness_local_state
     end
 
+    # Sets a current Awareness instance state to a corresponding JSON string.
+    # This state will be replicated to other clients as part of the
+    # AwarenessUpdate.
+    #
+    # @example Set local state
+    #   local_state = {
+    #     editing: { field: "description", pos: 0 },
+    #     name: "Hannes Moser"
+    #   }.to_json
+    #
+    #   awareness = Y::Awareness.new
+    #   awareness.local_state = local_state
+    #
+    # @return [void]
     def local_state=(json)
       yawareness_set_local_state(json)
     end
 
+    # Subscribes to changes
+    #
+    # @return [Integer] The subscription ID
     def attach(callback, &block)
       return yawareness_on_update(callback) unless callback.nil?
 
       yawareness_on_update(block.to_proc) unless block.nil?
     end
 
+    # Unsubscribe from changes
+    #
+    # @param [Integer] subscription_id
+    # @return [void]
     def detach(subscription_id)
       yawareness_remove_on_update(subscription_id)
     end
 
+    # Clears out a state of a given client, effectively marking it as
+    # disconnected.
+    #
+    # @param [Integer] client_id Clears the state for given client_id
+    # @return [void]
     def remove_state(client_id)
       yawareness_remove_state(client_id)
     end
 
-    def update
+    # Returns a serializable update object which is representation of a current
+    # Awareness state.
+    #
+    # @return [::Array<Integer>] Binary encoded update of the local instance
+    def diff
       yawareness_update
     end
 
-    def 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.
+    #
+    # @param [::Array<Integer>] clients A list of client IDs
+    # @return [String] Binary encoded update including all given client IDs
+    def diff_with_clients(*clients)
       yawareness_update_with_clients(clients)
     end
 
@@ -57,6 +175,12 @@ module Y
     # @param [Y::AwarenessUpdate] A structure that represents an encodable state
     #   of an Awareness struct.
 
+    # @!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.
@@ -91,7 +215,7 @@ module Y
     #   Clears out a state of a given client, effectively marking it as
     #   disconnected.
     #
-    # @param [Integer] A Client ID
+    # @param [Integer] client_id A Client ID
     # @return [String|nil] Returns a JSON string state representation of a
     #   current Awareness instance.
 
@@ -119,8 +243,8 @@ module Y
     #   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
+    # @param [::Array<Integer>] clients
+    # @return [::Array<Integer>] A serialized (binary encoded) update object
 
     # rubocop:enable Lint/UselessAccessModifier
   end
@@ -130,28 +254,13 @@ module Y
     private
 
     # @!method added
-    # @return [Array<Integer>] Added clients
+    # @return [::Array<Integer>] Added clients
 
     # @!method updated
-    # @return [Array<Integer>] Updated clients
+    # @return [::Array<Integer>] Updated clients
 
     # @!method removed
-    # @return [Array<Integer>] Removed clients
-  end
-  # rubocop:enable Lint/UselessAccessModifier
-
-  # rubocop:disable Lint/UselessAccessModifier
-  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
+    # @return [::Array<Integer>] Removed clients
   end
   # rubocop:enable Lint/UselessAccessModifier
 end

data/lib/y/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: y-rb
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: x86_64-linux
 authors:
 - Hannes Moser
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-10-20 00:00:00.000000000 Z
+date: 2022-10-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake