dexiecable 2.0.0.alpha2 → 2.0.0.alpha4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 714562cd7c933eb48e81e9159acd326d77b6133a807cdd541000f350281c1c94
-  data.tar.gz: d3bcacdc18d5f9c7a8be970f9ede859be19e282e8ca35aa4d27c81e581310eb3
+  metadata.gz: 502a99e32deef9551c55b8cb0bdae2e2d74af751e4f9889543f76ceea6d5a2ce
+  data.tar.gz: f42e9bca1c1d05ef287b3b72373e7c264af8ab78c350c092b8ccd9f887aa0270
 SHA512:
-  metadata.gz: ed0dbe4fdfade70f3300d9c2a61882f6a00320c384fe74ad76b6ba11ef0733a26b86f6949606117b4847efdd5221709bf1a091088a510a0155d6ff9f48a87774
-  data.tar.gz: d5cef46c7417c0e34ff4e08c08e0df846ff653f19ae0eeacbffe9de433a362c9ae9af60b32f669a6daa301b64a05d3844f227587cf20af4da23ecf149b39cfb9
+  metadata.gz: 37dc5d8afc9449875b3074c2684856ebb5d1f29e44a0c8d83558d061cf96baa270b8e5d1ad2a35a17bd01363b25956ec2946aead6929c3c465bee447a0c5d8d8
+  data.tar.gz: 7c370e6be94b70a65c63cf8bd47bb762b353df0ce0e964cd0f68b256703514c6a790124605a973008595358976319f9d6fdb3876fd5cfc97eeba65a8b5902642

data/README.md

@@ -5,7 +5,7 @@
 >
 > Full synchronization utilizing event streams will arrive in DexieCable 3.0.
 
-DexieCable ships a single `DexieChannel` with a query DSL that mirrors the Dexie.js API, letting you push database mutations from the server to the client in real time. It also gives you a [`syncs_to_dexie`](#syncs_to_dexie--automatic-model-syncing) ActiveRecord macro for automatic change syncing.
+DexieCable gives your ActionCable channel a query DSL that mirrors the Dexie.js API, letting you push database mutations from the server to the client in real time. It also gives you a [`syncs_to_dexie`](#syncs_to_dexie--automatic-model-syncing) ActiveRecord macro for automatic change syncing.
 
 Push Dexie table updates to a client from anywhere on the server:
 
@@ -73,7 +73,14 @@ setConsumer(createConsumer("wss://example.com/cable"));
 
 ### DexieChannel
 
-DexieCable ships one channel — `DexieChannel` — so you never define your own channels or include anything. Every Dexie broadcast goes through it.
+Create a `DexieChannel` in your app and `include DexieCable` in it. Every Dexie broadcast goes through this channel:
+
+```ruby
+# app/channels/dexie_channel.rb
+class DexieChannel < ApplicationCable::Channel
+  include DexieCable
+end
+```
 
 Stream tokens are signed with the application secret, so a client can only subscribe to streams the server has issued for it:
 
@@ -107,23 +114,45 @@ subscription.removeStream(userStream);
 subscription.removeAllStreams();
 ```
 
-#### Initial data on subscribe
+#### Customizing DexieChannel
 
-To push a snapshot when a stream is added, set `DexieChannel.on_subscribe`. It receives the channel and the subscribed record (resolved from the signed GlobalID), so you can dispatch on the record type:
+Add custom actions or push initial data directly on your channel:
 
 ```ruby
-# config/initializers/dexiecable.rb
-DexieChannel.on_subscribe = ->(channel, record) do
-  case record
-  when User
-    channel.table("notifications").bulkAdd(record.notifications.map(&:as_json_for_dexie))
-  when Conversation
-    channel.table("messages").bulkAdd(record.messages.map(&:as_json_for_dexie))
+# app/channels/dexie_channel.rb
+class DexieChannel < ApplicationCable::Channel
+  include DexieCable
+
+  # Push a snapshot when a private stream is added.
+  def subscribed_to(record, params)
+    case record
+    when User
+      table("notifications").bulkAdd(record.notifications.map(&:as_json_for_dexie))
+    when Conversation
+      table("messages").bulkAdd(record.messages.where("seq_id > ?", params[:last_seq_id]).map(&:as_json_for_dexie))
+    end
+  end
+
+  # Any public method is a custom action the client can perform.
+  def mark_as_read(data)
+    Message.find(data["id"]).update!(read: true)
   end
 end
 ```
 
-The callback runs after the stream is opened, and `channel.table(...)` transmits to just this subscriber — so the snapshot arrives before any live mutation.
+The client subscribes to `DexieChannel` by default:
+
+```js
+const subscription = subscribe(db);
+```
+
+Pass params from the client when adding a stream:
+
+```js
+subscription.addStream(userStream, { last_seq_id: 100 });
+```
+
+`subscribed_to` runs after the stream is opened, and `table(...)` transmits to just this subscriber — so the snapshot arrives before any live mutation. Custom actions are triggered like any ActionCable action: `subscription.perform("mark_as_read", { id: 42 })`.
 
 #### Public streams
 

data/lib/dexiecable/concern.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module DexieCable
+  # Include this in an ActionCable channel to add Dexie broadcasting and
+  # streaming:
+  #
+  #   class DexieChannel < ApplicationCable::Channel
+  #     include DexieCable
+  #
+  #     # Push initial data when a private stream is added.
+  #     def subscribed_to(record, params)
+  #       case record
+  #       when User
+  #         table("notifications").bulkAdd(record.notifications.map(&:as_json_for_dexie))
+  #       end
+  #     end
+  #   end
+  #
+  # The client subscribes to that channel and adds streams dynamically:
+  #
+  #   subscribe(db)                 # subscribes to "DexieChannel"
+  #   subscription.addStream(DexieChannel.stream_token_for(current_user))
+  #   subscription.addPublicStream("feed")
+  #
+  extend ActiveSupport::Concern
+
+  PUBLIC_STREAM_PREFIX = "public:"
+
+  included do
+    public :transmit
+  end
+
+  class_methods do
+    # Open a scoped channel for broadcasting to a specific recipient.
+    #
+    # A String recipient is a public stream name (namespaced under
+    # +public:+); any other recipient targets that recipient's own stream.
+    def [](recipient)
+      target = recipient.is_a?(String) ? "#{PUBLIC_STREAM_PREFIX}#{recipient}" : recipient
+      ScopedChannel.new(self, target)
+    end
+
+    # Returns a signed token for +target+ (a record or other private
+    # target). Send it to the client, which passes it to
+    # +subscription.addStream+.
+    def stream_token_for(target)
+      verifier.generate(target.respond_to?(:to_gid_param) ? target.to_gid_param : target.to_s)
+    end
+
+    def verifier
+      @verifier ||= Rails.application.message_verifier("dexiecable:streams")
+    end
+  end
+
+  # Build a query against a Dexie table, transmitted to all subscribers
+  # of this channel.
+  def table(name)
+    Query.new(self, name)
+  end
+
+  def subscribed
+    # Streams are added dynamically via +add_stream+.
+  end
+
+  def add_stream(data)
+    target = verified_target(data["stream"])
+    return unless target
+
+    stream_for target
+    params = data.except("action", "stream").with_indifferent_access
+    subscribed_to(resolve_subscribe_target(target), params)
+  end
+
+  def remove_stream(data)
+    target = verified_target(data["stream"])
+    return unless target
+
+    stop_stream_from self.class.broadcasting_for(target)
+  end
+
+  def remove_all_streams(_data)
+    stop_all_streams
+  end
+
+  def add_public_stream(data)
+    name = data["stream"].to_s
+    stream_from public_stream_name(name) if name.present?
+  end
+
+  def remove_public_stream(data)
+    name = data["stream"].to_s
+    stop_stream_from public_stream_name(name) if name.present?
+  end
+
+  # Override to push initial data when a private stream is added. +record+
+  # is the resolved target and +params+ are any extra params sent from the
+  # client.
+  def subscribed_to(_record, _params)
+  end
+
+  private
+
+  def public_stream_name(name)
+    self.class.broadcasting_for("#{PUBLIC_STREAM_PREFIX}#{name}")
+  end
+
+  def verified_target(token)
+    return unless token.present?
+
+    self.class.verifier.verify(token)
+  rescue ActiveSupport::MessageVerifier::InvalidSignature
+    nil
+  end
+
+  def resolve_subscribe_target(target)
+    target.start_with?("gid://") ? GlobalID::Locator.locate(target) : target
+  end
+end

data/lib/dexiecable/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DexieCable
-  VERSION = "2.0.0.alpha2"
+  VERSION = "2.0.0.alpha4"
 end

data/lib/dexiecable.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
 require_relative "dexiecable/version"
+require_relative "dexiecable/concern"
 require_relative "dexiecable/scoped_channel"
 require_relative "dexiecable/query"
 require_relative "dexiecable/active_record_ext"
-require_relative "dexiecable/dexie_channel" if defined?(ActionCable::Channel::Base)
 require_relative "dexiecable/railtie" if defined?(Rails::Railtie)
 
 module DexieCable

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dexiecable
 version: !ruby/object:Gem::Version
-  version: 2.0.0.alpha2
+  version: 2.0.0.alpha4
 platform: ruby
 authors:
 - Stefan Buhrmester
@@ -50,7 +50,7 @@ files:
 - README.md
 - lib/dexiecable.rb
 - lib/dexiecable/active_record_ext.rb
-- lib/dexiecable/dexie_channel.rb
+- lib/dexiecable/concern.rb
 - lib/dexiecable/query.rb
 - lib/dexiecable/railtie.rb
 - lib/dexiecable/scoped_channel.rb

data/lib/dexiecable/dexie_channel.rb

@@ -1,119 +0,0 @@
-# frozen_string_literal: true
-
-module DexieCable
-  # The single channel through which all Dexie transfer happens.
-  #
-  # Broadcasts are scoped to a recipient with +DexieChannel[recipient]+ or
-  # +DexieChannel.broadcast_to+. String recipients are public stream names;
-  # any other recipient (e.g. a record) targets a private, signed stream.
-  #
-  #   # private (signed)
-  #   subscription.addStream(DexieChannel.stream_token_for(current_user))
-  #
-  #   # public (no signature, namespaced under "public:")
-  #   subscription.addPublicStream("feed")
-  #
-  # When a private stream is added, +on_subscribe+ is invoked with the
-  # channel and the subscribed record, so initial data can be pushed:
-  #
-  #   DexieChannel.on_subscribe = ->(channel, record) do
-  #     case record
-  #     when User
-  #       channel.table("notifications").bulkAdd(record.notifications.map(&:as_json_for_dexie))
-  #     when Conversation
-  #       channel.table("messages").bulkAdd(record.messages.map(&:as_json_for_dexie))
-  #     end
-  #   end
-  #
-  class DexieChannel < ActionCable::Channel::Base
-    PUBLIC_STREAM_PREFIX = "public:"
-
-    class_attribute :on_subscribe, instance_accessor: false, default: nil
-
-    public :transmit
-
-    # Open a scoped channel for broadcasting to a specific recipient.
-    #
-    # A String recipient is a public stream name (namespaced under
-    # +public:+); any other recipient targets that recipient's own stream.
-    #
-    #   DexieChannel[current_user].table("notifications").add(notification)
-    #   DexieChannel["feed"].table("announcements").add(announcement)
-    #
-    def self.[](recipient)
-      target = recipient.is_a?(String) ? "#{PUBLIC_STREAM_PREFIX}#{recipient}" : recipient
-      ScopedChannel.new(self, target)
-    end
-
-    # Build a query against a Dexie table, transmitted to all subscribers
-    # of this channel.
-    #
-    #   table("messages").where(:room_id).equals(room.id).add(message)
-    #
-    def table(name)
-      Query.new(self, name)
-    end
-
-    # Returns a signed token for +target+ (a record or other private
-    # target). Send it to the client, which passes it to
-    # +subscription.addStream+.
-    def self.stream_token_for(target)
-      verifier.generate(target.respond_to?(:to_gid_param) ? target.to_gid_param : target.to_s)
-    end
-
-    def self.verifier
-      @verifier ||= Rails.application.message_verifier("dexiecable:streams")
-    end
-
-    def subscribed
-      # Streams are added dynamically via +add_stream+.
-    end
-
-    def add_stream(data)
-      target = verified_target(data["stream"])
-      return unless target
-
-      stream_for target
-      self.class.on_subscribe&.call(self, resolve_subscribe_target(target))
-    end
-
-    def remove_stream(data)
-      target = verified_target(data["stream"])
-      return unless target
-
-      stop_stream_from self.class.broadcasting_for(target)
-    end
-
-    def remove_all_streams(_data)
-      stop_all_streams
-    end
-
-    def add_public_stream(data)
-      name = data["stream"].to_s
-      stream_from public_stream_name(name) if name.present?
-    end
-
-    def remove_public_stream(data)
-      name = data["stream"].to_s
-      stop_stream_from public_stream_name(name) if name.present?
-    end
-
-    private
-
-    def public_stream_name(name)
-      self.class.broadcasting_for("#{PUBLIC_STREAM_PREFIX}#{name}")
-    end
-
-    def verified_target(token)
-      return unless token.present?
-
-      self.class.verifier.verify(token)
-    rescue ActiveSupport::MessageVerifier::InvalidSignature
-      nil
-    end
-
-    def resolve_subscribe_target(target)
-      target.start_with?("gid://") ? GlobalID::Locator.locate(target) : target
-    end
-  end
-end