y-rb 0.6.0-x86_64-linux-gnu

data/lib/y/awareness.rb

@@ -0,0 +1,290 @@
+# 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"
+  #   }
+  #
+  #   awareness = Y::Awareness.new
+  #   awareness.local_state = local_state
+  #   awareness.diff # [1,227,245,175,195,11,1,65,123, …]
+  #
+  # @example Two connected clients
+  #   local_state_a = { name: "User A" }
+  #
+  #   client_a = Y::Awareness.new
+  #   client_a.local_state = local_state
+  #
+  #   local_state_b = { name: "User B" }
+  #
+  #   client_b = Y::Awareness.new
+  #   client_b.local_state = local_state_b
+  #
+  #   client_a.sync(client_b.diff)
+  #   client_a.clients # {1242157267=>"{\"name\":\"User A\"}", 2401067547=>…
+  class Awareness
+    # 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 diff [Array<Integer>] 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"
+    #   }
+    #
+    #   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
+      transform = yawareness_clients.map do |client_id, state|
+        [client_id, JSON.parse!(state)]
+      end
+      transform.to_h
+    end
+
+    # Returns the state of the local Awareness instance.
+    #
+    # @example Create local state and inspect it
+    #   local_state = {
+    #     editing: { field: "description", pos: 0 },
+    #     name: "Hannes Moser"
+    #   }
+    #
+    #   awareness = Y::Awareness.new
+    #   awareness.local_state = local_state
+    #   awareness.local_state # {  editing: { field: "description", ...
+    #
+    # @return [String] The current state of the local client
+    def local_state
+      json = yawareness_local_state
+      JSON.parse!(json) if json
+    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"
+    #   }
+    #
+    #   awareness = Y::Awareness.new
+    #   awareness.local_state = local_state
+    #
+    # @param [#to_json] state
+    # @return [void]
+    def local_state=(state)
+      raise "state cannot be encoded to JSON" unless state.respond_to? :to_json
+
+      yawareness_set_local_state(state.to_json)
+    end
+
+    # Subscribes to changes
+    #
+    # @return [Integer] The subscription ID
+    def attach(callback = nil, &block)
+      return yawareness_on_update(callback) unless callback.nil?
+
+      yawareness_on_update(block.to_proc) unless block.nil?
+    end
+
+    # Clears out a state of a given client, effectively marking it as
+    # disconnected.
+    #
+    # @param client_id [Integer] Clears the state for given client_id
+    # @return [void]
+    def remove_state(client_id)
+      yawareness_remove_state(client_id)
+    end
+
+    # 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
+
+    # 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 clients [::Array<Integer>] 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
+
+    # rubocop:disable Lint/UselessAccessModifier
+    private
+
+    # @!method yawareness_apply_update(update)
+    #   Applies an update
+    #
+    # @param A [Y::AwarenessUpdate] Structure that represents an encodable state
+    #   of an Awareness struct.
+    # @!visibility private
+
+    # @!method yawareness_apply_update(update)
+    #   Applies an update
+    #
+    # @param A [Y::AwarenessUpdate] Structure that represents an encodable state
+    #   of an Awareness struct.
+    # @!visibility private
+
+    # @!method yawareness_clean_local_state
+    #   Clears out a state of a current client , effectively marking it as
+    #   disconnected.
+    # @!visibility private
+
+    # @!method yawareness_client_id
+    #   Returns a globally unique client ID of an underlying Doc.
+    # @return [Integer] The Client ID
+    # @!visibility private
+
+    # @!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
+    # @!visibility private
+
+    # @!method yawareness_local_state
+    #
+    # @return [String, nil] Returns a JSON string state representation of a
+    #   current Awareness instance.
+    # @!visibility private
+
+    # @!method yawareness_on_update(callback, &block)
+    #
+    # @param callback [callback]
+    # @return [Integer] The subscription ID
+    # @!visibility private
+
+    # @!method yawareness_remove_on_update(subscription_id)
+    #
+    # @param subscription_id [Integer] The subscription id to remove
+    # @!visibility private
+
+    # @!method yawareness_remove_state(client_id)
+    #   Clears out a state of a given client, effectively marking it as
+    #   disconnected.
+    #
+    # @param client_id [Integer] A Client ID
+    # @return [String, nil] Returns a JSON string state representation of a
+    #   current Awareness instance.
+    # @!visibility private
+
+    # @!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 Returns [String] 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.
+    # @!visibility private
+
+    # @!method yawareness_update
+    #   Returns a serializable update object which is representation of a
+    #   current Awareness state.
+    #
+    # @return [Y::AwarenessUpdate] The update object
+    # @!visibility private
+
+    # @!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 clients [::Array<Integer>]
+    # @return [::Array<Integer>] A serialized (binary encoded) update object
+    # @!visibility private
+
+    # rubocop:enable Lint/UselessAccessModifier
+  end
+
+  # @!visibility private
+  class AwarenessEvent
+    private # rubocop:disable Lint/UselessAccessModifier
+
+    # @!method added
+    # @return [::Array<Integer>] Added clients
+    # @!visibility private
+
+    # @!method updated
+    # @return [::Array<Integer>] Updated clients
+    # @!visibility private
+
+    # @!method removed
+    # @return [::Array<Integer>] Removed clients
+    # @!visibility private
+  end
+end

data/lib/y/diff.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Y
+  # A representation of an uniformly-formatted chunk of rich context stored by
+  # Text or XmlText. It contains a value (which could be a string, embedded
+  # object or another shared type) with optional formatting attributes wrapping
+  # around this chunk.
+  class Diff
+    # @return [Object]
+    def insert
+      ydiff_insert
+    end
+
+    # @return [Hash]
+    def attrs
+      ydiff_attrs
+    end
+
+    # Convert the diff to a Hash representation
+    #
+    # @return [Hash]
+    def to_h
+      {
+        insert: ydiff_insert,
+        attrs: ydiff_attrs
+      }
+    end
+
+    # @!method ydiff_insert()
+    #   Returns string representation of text
+    #
+    # @return [Object]
+
+    # @!method ydiff_attrs()
+    #
+    # @return [Hash]
+  end
+end

data/lib/y/doc.rb

@@ -0,0 +1,313 @@
+# frozen_string_literal: true
+
+require_relative "transaction"
+
+module Y
+  # @example Create a local and remote doc and syncs the diff
+  #   local = Y::Doc.new
+  #   local_map = local.get_map("my map")
+  #   local_map[:hello] = "world"
+  #
+  #   remote = Y::Doc.new
+  #
+  #   diff = local.diff(remote.state)
+  #   remote.sync(diff)
+  #
+  #   remote_map = remote.get_map("my_map")
+  #   pp remote_map.to_h #=> {hello: "world"}
+  class Doc
+    ZERO_STATE = [0].freeze
+    private_constant :ZERO_STATE
+
+    ZERO_STATE_V2 = [0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0].freeze
+    private_constant :ZERO_STATE_V2
+
+    # Attach a listener to document changes. If one of the data structures is
+    # changes, the block is called with the update as its only argument.
+    #
+    # @yield [update] Called when document is updated
+    # @yieldparam [Array<Integer>] update The encoded document updates
+
+    # Example: Attach listener to document changes
+    #   doc = described_class.new
+    #   doc.attach { |update| pp update }
+    #
+    #   text = doc.get_text("my text")
+    #   text << "1"
+    def attach(&block)
+      ydoc_observe_update(block)
+    end
+
+    # Commit current transaction
+    #
+    # This is a convenience method that invokes {Y::Transaction#commit} on the
+    # current transaction used by this document.
+    #
+    # @return [void]
+    def commit
+      current_transaction(&:commit)
+    end
+
+    # Create a diff between this document and another document. The diff is
+    # created based on a state vector provided by the other document. It only
+    # returns the missing blocks, as binary encoded sequence.
+    #
+    # @param state [::Array<Integer>] The state to create the diff against
+    # @return [::Array<Integer>] Binary encoded diff
+    def diff(state = ZERO_STATE)
+      current_transaction { |tx| ydoc_encode_diff_v1(tx, state) }
+    end
+
+    # Create a v2 diff between this document and another document. The diff is
+    # created based on a state vector provided by the other document. It only
+    # returns the missing blocks, as binary encoded sequence.
+    #
+    # @param state [::Array<Integer>] The state to create the diff against
+    # @return [::Array<Integer>] Binary encoded diff
+    def diff_v2(state = ZERO_STATE_V2)
+      current_transaction { |tx| ydoc_encode_diff_v2(tx, state) }
+    end
+
+    # Creates a full diff for the current document. It is similar to {#diff},
+    # but does not take a state. Instead it creates an empty state and passes it
+    # to the encode_diff function.
+    #
+    # @return [::Array<Integer>] Binary encoded diff
+    def full_diff
+      diff
+    end
+
+    # Gets or creates a new array by name
+    #
+    # If the optional values array is present, fills the array up with elements
+    # from the provided array. If the array already exists and isn't
+    # empty, elements are pushed to the end of the array.
+    #
+    # @param name [String] The name of the structure
+    # @param values [::Array] Optional initial values
+    # @return [Y::Array]
+    def get_array(name, values = nil)
+      array = ydoc_get_or_insert_array(name)
+      array.document = self
+      array.concat(values) unless values.nil?
+      array
+    end
+
+    # Gets or creates a new map by name
+    #
+    # If the optional input hash is present, fills the map up with key-value
+    # pairs from the provided input hash. If the map already exists and isn't
+    # empty, any existing keys are overridden and new keys are added.
+    #
+    # @param name [String] The name of the structure
+    # @param input [Hash] Optional initial map key-value pairs
+    # @return [Y::Map]
+    def get_map(name, input = nil)
+      map = ydoc_get_or_insert_map(name)
+      map.document = self
+      input&.each { |key, value| map[key] = value }
+      map
+    end
+
+    # Gets or creates a new text by name
+    #
+    # If the optional input string is provided, fills a new text with the string
+    # at creation time. If the text isn't new and not empty, appends the input
+    # to the end of the text.
+    #
+    # @param name [String] The name of the structure
+    # @param input [String] Optional initial text value
+    # @return [Y::Text]
+    def get_text(name, input = nil)
+      text = ydoc_get_or_insert_text(name)
+      text.document = self
+      text << input unless input.nil?
+      text
+    end
+
+    # Gets or creates a new XMLElement by name
+    #
+    # @param name [String] The name of the structure
+    # @return [Y::XMLElement]
+    def get_xml_element(name)
+      xml_element = ydoc_get_or_insert_xml_element(name)
+      xml_element.document = self
+      xml_element
+    end
+
+    # Gets or creates a new XMLFragment by name
+    #
+    # @param name [String] The name of the fragment
+    # @return [Y::XMLFragment]
+    def get_xml_fragment(name)
+      xml_fragment = ydoc_get_or_insert_xml_fragment(name)
+      xml_fragment.document = self
+      xml_fragment
+    end
+
+    # Gets or creates a new XMLText by name
+    #
+    # @param name [String] The name of the structure
+    # @param input [String] Optional initial text value
+    # @return [Y::XMLText]
+    def get_xml_text(name, input = nil)
+      xml_text = ydoc_get_or_insert_xml_text(name)
+      xml_text.document = self
+      xml_text << input unless input.nil?
+      xml_text
+    end
+
+    # Creates a state vector of this document. This can be used to compare the
+    # state of two documents with each other and to later on sync them.
+    #
+    # @return [::Array<Integer>] Binary encoded state vector
+    def state
+      current_transaction(&:state)
+    end
+
+    # Creates a v2 state vector of this document. This can be used to compare
+    # the state of two documents with each other and to later on sync them.
+    #
+    # @return [::Array<Integer>] Binary encoded state vector
+    def state_v2
+      current_transaction(&:state_v2)
+    end
+
+    # Synchronizes this document with the diff from another document
+    #
+    # @param diff [::Array<Integer>] Binary encoded update
+    # @return [void]
+    def sync(diff)
+      current_transaction { |tx| tx.apply(diff) }
+    end
+
+    # Synchronizes this document with the v2 diff from another document
+    #
+    # @param diff [::Array<Integer>] Binary encoded update
+    # @return [void]
+    def sync_v2(diff)
+      current_transaction { |tx| tx.apply_v2(diff) }
+    end
+
+    # Restores a specific document from an update that contains full state
+    #
+    # This is doing the same as {#sync}, but it exists to be explicit about
+    # the intent. This is the companion to {#full_diff}.
+    #
+    # @param full_diff [::Array<Integer>] Binary encoded update
+    # @return [void]
+    def restore(full_diff)
+      current_transaction { |tx| tx.apply(full_diff) }
+    end
+
+    # Creates a new transaction
+    def transact
+      # 1. release potentially existing transaction
+      if @current_transaction
+        @current_transaction.free
+        @current_transaction = nil
+      end
+
+      # 2. store new transaction in instance variable
+      @current_transaction = ydoc_transact
+      @current_transaction.document = self
+
+      # 3. call block with reference to current_transaction
+      yield @current_transaction
+    ensure
+      @current_transaction&.free
+      @current_transaction = nil
+    end
+
+    # @!visibility private
+    def current_transaction(&block)
+      raise "provide a block" unless block
+
+      # 1. instance variable is set, just use it
+      return yield @current_transaction if @current_transaction
+
+      # 2. forward block to transact
+      transact(&block) unless @current_transaction
+    end
+
+    # @!method ydoc_encode_diff_v1(tx, state_vector)
+    #   Encodes the diff of current document state vs provided state
+    #
+    #   @example Create transaction on doc
+    #     doc = Y::Doc.new
+    #     tx = doc.ydoc_encode_diff_v1(other_state)
+    #
+    # @return [Array<Integer>] Binary encoded update
+    # @!visibility private
+
+    # @!method ydoc_encode_diff_v2(tx, state_vector)
+    #   Encodes the diff of current document state vs provided state in the v2
+    #   format
+    #
+    #   @example Create transaction on doc
+    #     doc = Y::Doc.new
+    #     tx = doc.ydoc_encode_diff_v2(other_state)
+    #
+    # @return [Array<Integer>] Binary encoded update
+    # @!visibility private
+
+    # @!method ydoc_transact
+    #   Creates a new transaction for the document
+    #
+    #   @example Create transaction on doc
+    #     doc = Y::Doc.new
+    #     tx = doc.ydoc_transact
+    #
+    # @return [Y::Transaction] The transaction object
+    # @!visibility private
+
+    # @!method ydoc_get_or_insert_array(name)
+    #   Creates a new array for the document
+    #
+    # @param [String] name
+    # @return [Y::Array]
+    # @!visibility private
+
+    # @!method ydoc_get_or_insert_map(name)
+    #   Creates a new map for the document
+    #
+    # @param [String] name
+    # @return [Y::Map]
+    # @!visibility private
+
+    # @!method ydoc_get_or_insert_text(name)
+    #   Creates a new text for the document
+    #
+    # @param [String] name
+    # @return [Y::Text]
+    # @!visibility private
+
+    # @!method ydoc_get_or_insert_xml_element(name)
+    #   Creates a new XMLText for the document
+    #
+    # @param [String] name
+    # @return [Y::XMLElement]
+    # @!visibility private
+
+    # @!method ydoc_get_or_insert_xml_fragment(name)
+    #   Creates a new XMLFragment for the document
+    #
+    # @param [String] name
+    # @return [Y::XMLFragment]
+    # @!visibility private
+
+    # @!method ydoc_get_or_insert_xml_text(name)
+    #   Creates a new XMLText for the document
+    #
+    # @param [String] name
+    # @return [Y::XMLText]
+    # @!visibility private
+
+    # @!method ydoc_observe_update(block)
+    #   Creates a subscription to observe changes to the document
+    #
+    # @param [Proc] block
+    # @return [Integer]
+    # @!visibility private
+  end
+end