dexiecable 2.0.0.alpha1 → 2.0.0.alpha3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5262c05d144bc7c002152fd8da1918e87421f4ec81a060100b71c57237c152be
-  data.tar.gz: 339cf7b68cd9923b0b20b4a74c0caf563699be7ff8fbaf32ace71728a87fc787
+  metadata.gz: 2c2de6d52cf60491a659aebc8452a88ca8b8878142d08e842fadc8fb4bb1050b
+  data.tar.gz: 6be72c303e815a4809aff6b88a718b3e9ec1df8d5ebd341af03768225ee86bc3
 SHA512:
-  metadata.gz: e315b48c4d222dd5c4fb04056dded3f61d9d76584dfc7ee02d1645b6d28521120130b945cda897ca6682b7d6483232a3f6b92a3220bc417dc9fb6d8718169416
-  data.tar.gz: a5c155688bd21d6970842b86f28d2f9e4d901561fb5e786a59ed3447ae7b96db083d5b63e1d724b7fc8c5b7c2428661d713b00a5dc41a5c5b0f2a0f62ca568cc
+  metadata.gz: ac607ef7627a7a0562459042bcc8b23244362553624cb2f7543a7997430842c5185d5c889b8557c3ad28f10265d286f7a557a1ce76c397473adc97ead82b13d5
+  data.tar.gz: 1386543cc03df9409d17f184a8e1b4b80e85f993663009a32324da9b8e79561000c907c42e25c84c683bef4d4f11e525a5c1cd6dda58a0817595d53417880786

data/README.md

@@ -73,7 +73,7 @@ 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.
+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.
 
 Stream tokens are signed with the application secret, so a client can only subscribe to streams the server has issued for it:
 
@@ -85,7 +85,7 @@ For an ActiveRecord model it signs the record's GlobalID:
 
 ```ruby
 DexieChannel.stream_token_for(current_user)
-# => "eyJkYXRhIjoiZGV4aWVfY2FibGU6ZGV4aWVfY2hhbm5lbDpnaWQ6Ly9hcHAvVXNlci8xIn0=--signature"
+# => "signed token for gid://app/User/1"
 ```
 
 Send that token to the client (render it in a view, return it from an endpoint, etc.) and add it to the subscription:
@@ -107,6 +107,44 @@ subscription.removeStream(userStream);
 subscription.removeAllStreams();
 ```
 
+#### Extending DexieChannel
+
+To add custom actions or push initial data, reopen `DexieChannel` in your app:
+
+```ruby
+# config/initializers/dexiecable.rb
+class DexieCable::DexieChannel
+  # 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 client still subscribes to `DexieCable::DexieChannel`, so no extra client config is needed:
+
+```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
 
 For data that's public (a global feed, announcements, etc.), skip the signature. Use a string target — it's namespaced under `public:` automatically:

data/lib/dexiecable/dexie_channel.rb

@@ -13,6 +13,22 @@ module DexieCable
   #   # 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:"
 
@@ -40,11 +56,11 @@ module DexieCable
       Query.new(self, name)
     end
 
-    # Returns a signed token for the stream identifier of +target+ (private
-    # record-based streams). Send it to the client, which passes it to
+    # 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(broadcasting_for(target))
+      verifier.generate(target.respond_to?(:to_gid_param) ? target.to_gid_param : target.to_s)
     end
 
     def self.verifier
@@ -56,13 +72,19 @@ module DexieCable
     end
 
     def add_stream(data)
-      stream = verified_stream(data["stream"])
-      stream_from stream if stream
+      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)
-      stream = verified_stream(data["stream"])
-      stop_stream_from stream if stream
+      target = verified_target(data["stream"])
+      return unless target
+
+      stop_stream_from self.class.broadcasting_for(target)
     end
 
     def remove_all_streams(_data)
@@ -79,18 +101,28 @@ module DexieCable
       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_stream(token)
+    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

data/lib/dexiecable/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dexiecable
 version: !ruby/object:Gem::Version
-  version: 2.0.0.alpha1
+  version: 2.0.0.alpha3
 platform: ruby
 authors:
 - Stefan Buhrmester