dexiecable 2.0.0.alpha3 → 2.0.0.alpha4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2c2de6d52cf60491a659aebc8452a88ca8b8878142d08e842fadc8fb4bb1050b
-  data.tar.gz: 6be72c303e815a4809aff6b88a718b3e9ec1df8d5ebd341af03768225ee86bc3
+  metadata.gz: 502a99e32deef9551c55b8cb0bdae2e2d74af751e4f9889543f76ceea6d5a2ce
+  data.tar.gz: f42e9bca1c1d05ef287b3b72373e7c264af8ab78c350c092b8ccd9f887aa0270
 SHA512:
-  metadata.gz: ac607ef7627a7a0562459042bcc8b23244362553624cb2f7543a7997430842c5185d5c889b8557c3ad28f10265d286f7a557a1ce76c397473adc97ead82b13d5
-  data.tar.gz: 1386543cc03df9409d17f184a8e1b4b80e85f993663009a32324da9b8e79561000c907c42e25c84c683bef4d4f11e525a5c1cd6dda58a0817595d53417880786
+  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 don't need to define channels yourself. Every Dexie broadcast goes through it, and you can reopen it to add custom actions or push initial data.
+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,13 +114,15 @@ subscription.removeStream(userStream);
 subscription.removeAllStreams();
 ```
 
-#### Extending DexieChannel
+#### Customizing DexieChannel
 
-To add custom actions or push initial data, reopen `DexieChannel` in your app:
+Add custom actions or push initial data directly on your channel:
 
 ```ruby
-# config/initializers/dexiecable.rb
-class DexieCable::DexieChannel
+# 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
@@ -131,7 +140,7 @@ class DexieCable::DexieChannel
 end
 ```
 
-The client still subscribes to `DexieCable::DexieChannel`, so no extra client config is needed:
+The client subscribes to `DexieChannel` by default:
 
 ```js
 const subscription = subscribe(db);

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.alpha3"
+  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.alpha3
+  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,128 +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")
-  #
-  # Reopen this channel in your app to push initial data or add custom
-  # actions:
-  #
-  #   class DexieCable::DexieChannel
-  #     def subscribed_to(record, params)
-  #       case record
-  #       when User
-  #         table("notifications").bulkAdd(record.notifications.map(&:as_json_for_dexie))
-  #       end
-  #     end
-  #
-  #     def my_custom_action(data)
-  #       # ...
-  #     end
-  #   end
-  #
-  class DexieChannel < ActionCable::Channel::Base
-    PUBLIC_STREAM_PREFIX = "public:"
-
-    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
-      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 by reopening the channel 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
-end