y-rb_actioncable 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4f5ed9889a1aa6f7fbb3aeaa6d41342a595aa3ca603f654ada833973e656985c
-  data.tar.gz: e019eeda236b1260b0b68d1fb375ce82b91a58be48ffec5f040d4b62b268d119
+  metadata.gz: 9aee5ffece065c56362b59a6f7514bbe4e6177d0ea2d782ec1e3bb485cd05a53
+  data.tar.gz: 709e1c51409f66f3134049dbf555db7c6c94bab0f1a66a629d3174051c186f0b
 SHA512:
-  metadata.gz: '0231899eca54164befbd7d6bd7d151058e57f388ff45e4b126827c45e6b7bdca6ca103a4f3c63ce95d3bf2452b2c09319d8bbb731b9356639e5a783212377e12'
-  data.tar.gz: 424848bdee2d1658227871c4cbf72aa6d6ddcd30b759108a8f3d9a75c9b80447d23300ff7153091940b566ef8e4896cd38f07272e9fdf0b640433b22806d7cbf
+  metadata.gz: b16e36125a01866c74585b92580a6391c86f264f44a8cfbd308da0edf48f9d9855f2e464b494c6286eed47a67f7f3655c405b5bd728304e5c6653948e5f03dfb
+  data.tar.gz: d6463f08ecefb4ddfcb629e58cf6e385df9f090eefdf3a9bf1928327bb3bbaf67de8a90650e41e93a98fcaa483e0a75f05938d4f593f1a855e36123c58044ff2

data/README.md

@@ -22,6 +22,123 @@ Or install it yourself as:
 $ gem install y-rb_actioncable
 ```
 
+## Usage
+
+`yrb-actioncable` provides a module that can be used to extend the capabilities
+of a regular channel with a real-time sync mechanism. `yrb-actioncable`
+implements the same protocol as
+[`y-websocket`](https://github.com/yjs/y-websocket/blob/master/bin/utils.js).
+
+It will make sure that a newly connected client will be provided with the
+current state and also syncs changes from the client to the server.
+
+```mermaid
+sequenceDiagram
+    Client->>Server: Subscribe to channel
+    Server->>Client: Successfully subscribed to channel
+    
+    Server->>Client: Send server-side document state-vector
+    Client->>Server: Respond with update based on server-side state-vector
+    
+    Client->>Server: Send client-side document state-vector
+    Server->>Client: Respond with update based on client-side state-vector
+    
+    Client->>Server: Send incremental updates from client
+    Server->>Client: Send incremental updates from server (broadcast)
+```
+
+In order to use the above described protocol, someone can simply include the
+`Sync` module. There are three methods we need to use:
+
+1. Initiate the connection with initial sync steps: `initiate`
+1. Integrate any incoming changes: `integrate`
+1. Broadcast incoming updates to all clients: `sync_to`
+
+```ruby
+# app/channels/sync_channel.rb
+class SyncChannel < ApplicationCable::Channel
+  include Y::Actioncable::Sync
+
+  def subscribed
+    stream_from("document-1", coder: ActiveSupport::JSON) do |message|
+      # integrate updates in the y-rb document
+      integrate(message)
+    end
+
+    # negotiate initial state with client
+    initiate
+  end
+
+  def receive(message)
+    # broadcast update to all connected clients on all servers
+    sync_to("document-1", message)
+  end
+end
+```
+
+**⚠️ Attention:** This integration and API eventually change before the final
+release. The goal for `yrb-actioncable` is simplicity and ease-of-use, and the
+current implementation requires at least some knowledge about internals.
+
+### Persistence
+
+We can also implement a persistence mechanism with `yrb-actioncable` via hooks.
+This is a quite common use case, and therefore it is relatively simple to add.
+
+#### Load document
+
+In order to instantiate the document with some state, `yrb-actioncable` expects
+the `load` method to be called with a block that returns a full state update for
+the document. Internally it just calls `Y::Doc#sync(update)`.
+
+```ruby
+class SyncChannel < ApplicationCable::Channel
+  include Y::Actioncable::Sync
+  
+  def initialize(connection, identifier, params = nil)
+    super
+    load { |id| load_doc(id) }
+  end
+end
+```
+
+#### Persist document
+
+It is usually desirable to persist updates as soon as they arrive. The method
+`persist` expects a block that can process a document full state update for the
+given ID.
+
+```ruby
+
+class SyncChannel < ApplicationCable::Channel
+  include Y::Actioncable::Sync
+
+  def subscribed
+    stream_for(session, coder: ActiveSupport::JSON) do |_message|
+      persist { |id, update| save_doc(id, update) }
+    end
+  end
+end
+```
+
+#### Example implementation for `load_doc` and `save_doc`
+
+We eventually provide storage providers that are easy to use, e.g.
+[`yrb-redis`](https://github.com/y-crdt/yrb-redis), but you can also implement
+your own _store_ methods.
+
+```ruby
+def load_doc(id)
+    data = REDIS.get(id)
+    data = data.unpack("C*") unless data.nil?
+    data
+end
+
+def save_doc(id, update)
+  REDIS.set(id, update.pack("C*"))
+end
+```
+
 ## License
 
 The gem is available as *open source* under the terms of the

data/lib/y/actioncable/sync.rb

@@ -2,12 +2,40 @@
 
 module Y
   module Actioncable
-    module Sync # rubocop:disable Metrics/ModuleLength
+    # A Sync module for Rails ActionCable channels.
+    #
+    # This module contains a set of utility methods that allows a relatively
+    # convenient implementation of a real-time sync channel. The module
+    # implements the synchronization steps described in
+    # [`y-protocols/sync`](https://github.com/yjs/y-protocols/blob/master/sync.js).
+    #
+    # @example Create a SyncChannel including this module
+    #   class SyncChannel
+    #     def subscribed
+    #       # initiate sync & subscribe to updates, with optional persistence mechanism
+    #       sync_for(session) { |id, update| save_doc(id, update) }
+    #     end
+    #
+    #     def receive(message)
+    #       # broadcast update to all connected clients on all servers
+    #       sync_to(session, message)
+    #     end
+    #   end
+    module Sync
       extend ActiveSupport::Concern
 
+      CHANNEL_PREFIX = "sync"
+      FIELD_ORIGIN = "origin"
+      FIELD_UPDATE = "update"
       MESSAGE_SYNC = 0
       MESSAGE_AWARENESS = 1
-      private_constant :MESSAGE_SYNC, :MESSAGE_AWARENESS
+      private_constant(
+        :CHANNEL_PREFIX,
+        :FIELD_ORIGIN,
+        :FIELD_UPDATE,
+        :MESSAGE_SYNC,
+        :MESSAGE_AWARENESS
+      )
 
       # Initiate synchronization. Encodes the current state_vector and transmits
       # to the connecting client.
@@ -25,15 +53,14 @@ module Y
       # This methods should be passed as a block to stream subscription, and not
       # be put into a generic #receive method.
       #
-      # @param [Y::Doc] doc
       # @param [Hash] message The encoded message must include a field named
       #   exactly like the field argument. The field value must be a Base64
       #   binary.
       # @param [String] field The field that the encoded update should be
       #   extracted from.
-      def integrate(message, field: "update")
-        origin = message["origin"]
-        update = Y::Lib0::Decoding.decode_base64_to_uint8_array(message["update"])
+      def integrate(message, field: FIELD_UPDATE) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+        origin = message[FIELD_ORIGIN]
+        update = Y::Lib0::Decoding.decode_base64_to_uint8_array(message[field])
 
         encoder = Y::Lib0::Encoding.create_encoder
         decoder = Y::Lib0::Decoding.create_decoder(update)
@@ -54,6 +81,8 @@ module Y
           end
         when MESSAGE_AWARENESS
           # TODO: implement awareness https://github.com/yjs/y-websocket/blob/master/bin/utils.js#L179-L181
+        else
+          raise "unexpected message_type=`#{message_type}`"
         end
 
         # do not transmit message back to current connection if the connection
@@ -61,8 +90,80 @@ module Y
         transmit(message) if origin != connection.connection_identifier
       end
 
-      def sync_to(to, message, field: "update")
-        update = message["update"]
+      # Sync for given model. This is a utility method that simplifies the setup
+      # of a sync channel.
+      #
+      # @param [Object] model
+      #
+      # for block { |id, update| … }
+      # @yield [id, update] Optional block that allows to persist the document
+      #
+      # @yieldparam [String] id The document ID
+      # @yieldparam [Array<Integer>] update The full document state as binary
+      #   encoded update
+      def sync_for(model, &block)
+        stream_for(model, coder: ActiveSupport::JSON) do |message|
+          # integrate updates in the y-rb document
+          integrate(message)
+
+          # persist document
+          persist(&block) if block
+        end
+
+        # negotiate initial state with client
+        initiate
+      end
+
+      # Sync for given stream. This is a utility method that simplifies the
+      # setup of a sync channel.
+      #
+      # @param [String] broadcasting
+      #
+      # for block { |id, update| … }
+      # @yield [id, update] Optional block that allows to persist the document
+      #
+      # @yieldparam [String] id The document ID
+      # @yieldparam [Array<Integer>] update The full document state as binary
+      #   encoded update
+      def sync_from(broadcasting, &block)
+        stream_from(broadcasting, coder: ActiveSupport::JSON) do |message|
+          # integrate updates in the y-rb document
+          integrate(message)
+
+          # persist document
+          persist(&block) if block
+        end
+
+        # negotiate initial state with client
+        initiate
+      end
+
+      # Synchronize update with all other connected clients (and server
+      # processes).
+      #
+      # @param [String] broadcasting
+      # @param [Hash] message
+      # @param [optional, String] field
+      def sync(broadcasting, message, field: FIELD_UPDATE)
+        update = message[field]
+
+        # we broadcast to all connected clients, but provide the
+        # connection_identifier as origin so that the [#integrate] method is
+        # able to filter sending back the update to its origin.
+        self.class.broadcast(
+          broadcasting,
+          { update: update, origin: connection.connection_identifier }
+        )
+      end
+
+      # Synchronize update with all other connected clients (and server
+      # processes).
+      #
+      # @param [Object] to
+      # @param [Hash] message
+      # @param [optional, String] field
+      def sync_to(to, message, field: FIELD_UPDATE)
+        update = message[field]
 
         # we broadcast to all connected clients, but provide the
         # connection_identifier as origin so that the [#integrate] method is
@@ -101,19 +202,58 @@ module Y
             "#{k.to_s.parameterize}-#{v.to_s.parameterize}"
           end
 
-          "sync:#{params_part.join(":")}"
+          "#{CHANNEL_PREFIX}:#{params_part.join(":")}"
         end
       end
 
+      # Load the current state of a document from an external source and returns
+      # a reference to the document.
+      #
+      # for block { |id| … }
+      # @yield [id] Read document from e.g. an external store
+      #
+      # @yieldparam [String] id The document ID
+      # @yieldreturn [Array<Integer>] The binary encoded state of the document
+      # @return [Y::Doc] A reference to the loaded document
       def load(&block)
-        full_diff = yield(canonical_channel_key)
+        full_diff = nil
+        full_diff = yield(canonical_channel_key) if block
         doc.sync(full_diff) unless full_diff.nil?
+        doc
       end
 
+      # Persist the current document state to an external store.
+      #
+      # for block { |id, update| … }
+      # @yield [id, update] Store document state to e.g. an external store
+      #
+      # @yieldparam [String] id The document ID
+      # @yieldparam [Array<Integer>] update The full document state as binary
+      #   encoded state
       def persist(&block)
-        yield(canonical_channel_key, doc.diff)
+        yield(canonical_channel_key, doc.diff) if block
       end
 
+      # Creates the document once.
+      #
+      # This method can be overriden in case the document should be initialized
+      # with any state other than an empty one. In conjunction with
+      # {Y::Actioncable::Sync#load load}, this allows to provide a document to
+      # clients that is restored from a persistent store like Redis or also an
+      # ActiveRecord model.
+      #
+      # @example Initialize a {Y::Doc} from state stored in Redis
+      #   def doc
+      #     @doc ||= load { |id| load_doc(id) }
+      #   end
+      #
+      #   def load_doc(id)
+      #     data = REDIS.get(id)
+      #     data = data.unpack("C*") unless data.nil?
+      #     data
+      #   end
+      #
+      # @return [Y::Doc] The initialized document
       def doc
         @doc ||= Y::Doc.new
       end

data/lib/y/actioncable/version.rb

@@ -2,6 +2,6 @@
 
 module Y
   module Actioncable
-    VERSION = "0.1.1"
+    VERSION = "0.1.2"
   end
 end

data/lib/y/lib0/decoding.rb

@@ -41,14 +41,10 @@ module Y
         while decoder.pos < size
           r = decoder.arr[decoder.pos]
           decoder.pos += 1
-          num = num + (r & Binary::BITS7) * mult
+          num += ((r & Binary::BITS7) * mult)
           mult *= 128 # next iteration, shift 7 "more" to the left
-          if r < Binary::BIT8
-            return num
-          end
-          if num > Integer::MAX
-            raise "integer out of range"
-          end
+          return num if r < Binary::BIT8
+          raise "integer out of range" if num > Integer::MAX
         end
         raise "unexpected end of array"
       end

data/lib/y/lib0/encoding.rb

@@ -24,7 +24,7 @@ module Y
           size += encoder.bufs[i].size
           i += 1
         end
-        return size
+        size
       end
 
       def self.to_uint8_array(encoder) # rubocop:disable Metrics/MethodLength

data/lib/y/lib0/integer.rb

@@ -3,9 +3,9 @@
 module Y
   module Lib0
     module Integer
-      N_BYTES = [42].pack('i').size
+      N_BYTES = [42].pack("i").size
       N_BITS = N_BYTES * 16
-      MAX = 2 ** (N_BITS - 2) - 1
+      MAX = (2**(N_BITS - 2)) - 1
       MIN = -MAX - 1
     end
   end

data/lib/y/lib0/sync.rb

@@ -7,7 +7,7 @@ module Y
         write_sync_step2(encoder, doc, Decoding.read_var_uint8_array(decoder))
       end
 
-      def self.read_sync_step2(decoder, doc, transaction_origin)
+      def self.read_sync_step2(decoder, doc, _transaction_origin)
         update = Decoding.read_var_uint8_array(decoder)
         doc.sync(update)
       end

data/lib/y/lib0/typed_array.rb

@@ -18,7 +18,7 @@ module Y
       #   Create a new TypedArray from a buffer and offset. The projected
       # @overload initialize(buffer, offset, size)
       def initialize(*args) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
-        if args.size.zero?
+        if args.empty?
           super()
         elsif args.size == 1 && args.first.is_a?(Numeric)
           super(args.first, 0)
@@ -27,7 +27,7 @@ module Y
         elsif args.size == 1 && args.first.is_a?(Enumerable)
           super(args.first.to_a)
         elsif args.size == 2 && args.first.is_a?(Enumerable) && args.last.is_a?(Numeric)
-          super(args.first.to_a[(args.last)..-1])
+          super(args.first.to_a[(args.last)..])
         elsif args.size == 3 && args.first.is_a?(Enumerable) && args[1].is_a?(Numeric) && args.last.is_a?(Numeric)
           super(args.first.to_a[args[1], args.last])
         else

data/lib/y/sync.rb

@@ -31,7 +31,7 @@ module Y
 
     # @param [Y::Lib0::Decoding::Decoder] decoder
     # @param [Y::Doc] doc
-    # @param [Object] transaction_origin
+    # @param [Object, nil] transaction_origin
     # TODO: y-rb sync does not support transaction origins
     def self.read_sync_step2(decoder, doc, _transaction_origin)
       update = Y::Lib0::Decoding.read_var_uint8_array(decoder)
@@ -47,17 +47,17 @@ module Y
 
     # @param [Y::Lib0::Decoding::Decoder] decoder
     # @param [Y::Doc] doc
-    # @param [Object] transaction_origin
-    def self.read_update(decoder, doc, _transaction_origin)
-      read_sync_step2(decoder, doc, _transaction_origin)
+    # @param [Object, nil] transaction_origin
+    def self.read_update(decoder, doc, transaction_origin)
+      read_sync_step2(decoder, doc, transaction_origin)
     end
 
     # @param [Y::Lib0::Decoding::Decoder] decoder
     # @param [Y::Lib0::Encoding::Encoder] encoder
     # @param [Y::Doc] doc
-    # @param [Object] transaction_origin
+    # @param [Object, nil] transaction_origin
     # TODO: y-rb sync does not support transaction origins
-    def self.read_sync_message(decoder, encoder, doc, transaction_origin)
+    def self.read_sync_message(decoder, encoder, doc, transaction_origin) # rubocop:disable Metrics/MethodLength
       message_type = Y::Lib0::Decoding.read_var_uint(decoder)
 
       case message_type

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: y-rb_actioncable
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Hannes Moser
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-01-23 00:00:00.000000000 Z
+date: 2023-01-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -25,20 +25,20 @@ dependencies:
       - !ruby/object:Gem::Version
         version: 7.0.4
 - !ruby/object:Gem::Dependency
-  name: rspec-rails
+  name: y-rb
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
+        version: 0.4.3
+  type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
-description: Reliable message transmission between one or more Y.js clients.
+        version: 0.4.3
+description: An ActionCable companion for Y.js clients.
 email:
 - box@hannesmoser.at
 executables: []
@@ -53,6 +53,7 @@ files:
 - app/jobs/yrb/actioncable/application_job.rb
 - app/models/yrb/actioncable/application_record.rb
 - lib/tasks/yrb/actioncable_tasks.rake
+- lib/y-rb_actioncable.rb
 - lib/y/actioncable.rb
 - lib/y/actioncable/config.rb
 - lib/y/actioncable/config/abstract_builder.rb
@@ -71,7 +72,6 @@ files:
 - lib/y/lib0/sync.rb
 - lib/y/lib0/typed_array.rb
 - lib/y/sync.rb
-- lib/yrb-actioncable.rb
 homepage: https://github.com/y-crdt/yrb-actioncable
 licenses:
 - MIT
@@ -96,7 +96,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.1
+rubygems_version: 3.4.4
 signing_key:
 specification_version: 4
 summary: An ActionCable companion for Y.js clients.