dexiecable 2.0.1 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 05e9525058173a0392999802c6243cac3eb5c0406a28cb405963a9069d20b098
-  data.tar.gz: 3394af2d34854137a4032dd672bb0e1ebc6073e907872b168a5e31e9ffea1daf
+  metadata.gz: ef549275f108c037de78cad7dcabb5c3b3a0dfae666d6a56e413abd4bc1079f1
+  data.tar.gz: cb55611cd29a96e7fd79885b5e7575534f5f19e4ea417c745c1e8b13da9df59d
 SHA512:
-  metadata.gz: 936fa88cb0cd6dc55665e9214d54064eb914863552bf8b84e58e1ca4d616751863f9572740ceb00c7b09503ed9996fe9ec52640a65279b2bc5249498d3671684
-  data.tar.gz: 1b9a73d2e21d3ac4e5138feeb1c13c958f9b4eccffeb7968c0f7fbc28a45cd24b8dff7f6ab4e2f976730536dcee3fc30758cae5aaa04c4bd8dd3940ec83b5ef6
+  metadata.gz: 2be1d8dcf416c79e83c6227762877c339e9bdb227956108f5f8ce80327b189c25a1c7ac9f974b330e1bf1f50dd058b3aa09ad2399f1e2642d58ed43622243b85
+  data.tar.gz: 8c2f011b0381a44ce0c5bc55ca0eeecd0beda02a359f16022770862d54b2710f6076a7388437f11d3ec673a115c8b4595fb9862332e2f3cd055fd8aaede8110b

data/README.md

@@ -1,11 +1,17 @@
 # DexieCable
 
 > [!NOTE]
-> DexieCable is NOT meant to be a local-first solution. It has no automatic capability to sync updates back to the server. For now, think of it as an alternative to Turbo Streams built with component frameworks (Vue, React, Svelte, etc) in mind.
+> By itself, DexieCable is NOT a local-first solution. It has no automatic capability to push client-side changes back to the server.
 >
-> Full synchronization utilizing event streams will arrive in DexieCable 3.0.
+> An addon providing full synchronization based on event streams is currently in development. But for now, if you need full synchronization, you'll have to roll your own.
 
-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-streaming) ActiveRecord macro for automatic change syncing.
+## Who's this for?
+
+DexieCable is made for Ruby on Rails apps that manage their client-side state in [Dexie](https://dexie.org) and use Dexie live queries for reactive UI updates. It's an alternative to Turbo Streams for apps that opt to use component frameworks (React, Vue, Svelte, etc.) instead of Turbo. 
+
+## How does it work?
+
+DexieCable gives your ActionCable channel a query DSL that mirrors the [Dexie.js API](https://dexie.org/docs), 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-streaming) ActiveRecord macro for automatic change syncing.
 
 Push Dexie table updates to a client from anywhere on the server:
 
@@ -26,6 +32,53 @@ class Notification < ApplicationRecord
 end
 ```
 
+## What's new in 2.0
+
+### Custom Channels
+
+DexieCable 2.0 is a mixin. Create your own `DexieChannel` and `include DexieCable`:
+
+```ruby
+class DexieChannel < ApplicationCable::Channel
+  include DexieCable
+end
+```
+
+### Reuse the same subscription for multiple streams
+
+On the client, subscribe to that channel and add streams as needed. `addStream` accepts a signed token or a plain string, and returns a function that removes the stream:
+
+```js
+const subscription = subscribe(db);
+const unsubscribe = subscription.addStream(userStreamToken);
+```
+
+## What's new in 3.0
+
+### `subscribed_to` moved to the model
+
+The `subscribed_to` hook now lives on the record rather than on the channel. Private streams declare their initial snapshot on the record the token was issued for, and receive the channel plus any params sent from the client:
+
+```ruby
+class User < ApplicationRecord
+  subscribed_to do |channel, params|
+    channel.table("notifications").bulkAdd(notifications.map(&:as_json_for_dexie))
+  end
+end
+```
+
+Public streams register a handler by name in your channel. The block runs in the channel's context, so `table` and `transmit` are available:
+
+```ruby
+class DexieChannel < ApplicationCable::Channel
+  include DexieCable
+
+  subscribed_to "feed" do |params|
+    table("announcements").bulkAdd(Announcement.for_stream("feed").map(&:as_json_for_dexie))
+  end
+end
+```
+
 ## Installation
 
 ### Ruby gem
@@ -101,6 +154,8 @@ Tokens never expire by default. Pass `expires_in:` or `expires_at:` to limit a t
 DexieChannel.stream_token_for(current_user, expires_in: 1.day)
 ```
 
+An expired token, or one whose record no longer exists, is rejected. Only plain strings are treated as public stream names.
+
 Send that token to the client (render it in a view, return it from an endpoint, etc.) and add it to the subscription:
 
 ```js
@@ -129,22 +184,46 @@ Add custom actions or push initial data directly on your channel:
 class DexieChannel < ApplicationCable::Channel
   include DexieCable
 
-  # Push a snapshot when a stream is added. `record` is a record for private
-  # streams, or the stream name (String) for public streams.
-  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))
-    when String
-      table(record).bulkAdd(Announcement.for_stream(record).map(&:as_json_for_dexie))
-    end
+  # Push a snapshot when a public stream is added. The block receives the
+  # params sent from the client and runs in the channel's context, so
+  # `table(...)` and `transmit` are available.
+  subscribed_to "feed" do |params|
+    table("feed").bulkAdd(Announcement.for_stream("feed").map(&:as_json_for_dexie))
   end
 
-  # Any public method is a custom action the client can perform.
+  # Any public method is a custom action the client can perform. Always
+  # resolve records through the connection's actor, never from the payload:
+  # `Message.find(data["id"])` would let any client mark anyone's message
+  # read.
   def mark_as_read(data)
-    Message.find(data["id"]).update!(read: true)
+    current_user.messages.find(data["id"]).update!(read: true)
+  end
+end
+```
+
+Private streams declare their snapshot on the record itself, which is where the stream was opened for. The block runs in the record's context and receives the channel — so `channel.table(...)` transmits to just this subscriber — plus the params sent from the client:
+
+```ruby
+class User < ApplicationRecord
+  subscribed_to do |channel, params|
+    channel.table("notifications").bulkAdd(notifications.map(&:as_json_for_dexie))
+  end
+end
+
+class Conversation < ApplicationRecord
+  subscribed_to do |channel, params|
+    channel.table("messages").bulkAdd(messages.where("seq_id > ?", params[:last_seq_id]).map(&:as_json_for_dexie))
+  end
+end
+```
+
+Declare `subscribed_to` more than once to push several snapshots — the blocks run in declaration order. To share a snapshot across models, or take full control, override the instance method instead and call `super` to keep any registered blocks running:
+
+```ruby
+module HasNotifications
+  def subscribed_to(channel, params)
+    channel.table("notifications").bulkAdd(notifications.map(&:as_json_for_dexie))
+    super
   end
 end
 ```
@@ -161,7 +240,7 @@ Pass params from the client when adding a stream:
 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 })`.
+`subscribed_to` runs after the stream is opened, and the snapshot it pushes (via `table(...)` on the channel, or `channel.table(...)` on the record) transmits to just this subscriber, so it arrives before any live mutation. Custom actions are triggered like any ActionCable action: `subscription.perform("mark_as_read", { id: 42 })`. The payload is client-controlled, so pass it through the authenticated actor — `current_user.messages.find(data["id"])`, not `Message.find(data["id"])`.
 
 #### Public streams
 
@@ -228,6 +307,9 @@ Add to any ActiveRecord model. Optionally provide the broadcast target.
 
 ```ruby
 class Message < ApplicationRecord
+  belongs_to :conversation
+  belongs_to :receiver
+  
   # Calls send(:receiver), then broadcasts: DexieChannel.broadcast_to(receiver, ...)
   syncs_to_dexie via: :receiver
 

data/lib/dexiecable/active_record_ext.rb

@@ -70,6 +70,51 @@ module DexieCable
           end
         end
       end
+
+      # Declares what to push to a single subscriber when they subscribe to
+      # this record's stream, before any live mutation is delivered. The block
+      # runs in the record's context and receives the channel and the params
+      # sent by the client:
+      #
+      #   class User < ApplicationRecord
+      #     subscribed_to do |channel, params|
+      #       channel.table("notifications").bulkAdd(notifications.map(&:as_json_for_dexie))
+      #     end
+      #   end
+      #
+      # Declare it more than once to push several snapshots; blocks run in
+      # declaration order.
+      def subscribed_to(&block)
+        raise ArgumentError, "subscribed_to requires a block" if block.nil?
+
+        dexie_subscribed_to_blocks << block
+      end
+
+      # The blocks registered with +subscribed_to+, inherited from
+      # superclasses.
+      def dexie_subscribed_to_blocks
+        @dexie_subscribed_to_blocks ||=
+          if superclass.respond_to?(:dexie_subscribed_to_blocks)
+            superclass.dexie_subscribed_to_blocks.dup
+          else
+            []
+          end
+      end
+    end
+
+    # Called when a client subscribes to this record's private stream. Runs
+    # every block registered with the +subscribed_to+ macro in the record's
+    # context. Override in your model for full control, calling +super+ if you
+    # still want the registered blocks to run:
+    #
+    #   def subscribed_to(channel, params)
+    #     channel.table("notifications").bulkAdd(notifications.map(&:as_json_for_dexie))
+    #     super
+    #   end
+    def subscribed_to(channel, params)
+      self.class.dexie_subscribed_to_blocks.each do |block|
+        instance_exec(channel, params, &block)
+      end
     end
 
     private

data/lib/dexiecable/concern.rb

@@ -7,12 +7,18 @@ module DexieCable
   #   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
+  #     # Push initial data when a public stream is added. The block runs in
+  #     # the channel's context, so +table+ and +transmit+ are available.
+  #     subscribed_to "feed" do |params|
+  #       table("announcements").bulkAdd(Announcement.for_stream("feed").map(&:as_json_for_dexie))
+  #     end
+  #   end
+  #
+  # Private streams push their initial data from the record itself:
+  #
+  #   class User < ApplicationRecord
+  #     def subscribed_to(channel, params)
+  #       channel.table("notifications").bulkAdd(notifications.map(&:as_json_for_dexie))
   #     end
   #   end
   #
@@ -41,6 +47,28 @@ module DexieCable
       ScopedChannel.new(self, target)
     end
 
+    # Register a handler for a public stream. When a client subscribes to
+    # +name+ (for example +subscription.addStream("feed")+), the block is
+    # evaluated in the channel's context with the params sent by the client:
+    #
+    #   subscribed_to "feed" do |params|
+    #     table("announcements").bulkAdd(Announcement.for_stream("feed"))
+    #   end
+    def subscribed_to(name, &block)
+      dexie_subscribed_to_handlers[name.to_s] = block
+    end
+
+    # The registered public stream handlers. Subclasses inherit the handlers
+    # registered on their superclass.
+    def dexie_subscribed_to_handlers
+      @dexie_subscribed_to_handlers ||=
+        if superclass.respond_to?(:dexie_subscribed_to_handlers)
+          superclass.dexie_subscribed_to_handlers.dup
+        else
+          {}
+        end
+    end
+
     # Returns a signed token for +target+ (a record). Send it to the client,
     # which passes it to +subscription.addStream+.
     #
@@ -72,29 +100,35 @@ module DexieCable
   end
 
   def add_stream(data)
-    record = resolve_subscribe_target(data["stream"])
+    token = data["stream"].to_s
     params = data.except("action", "stream").with_indifferent_access
 
-    if record
+    if signed_token?(token)
+      # A token that no longer resolves (expired, revoked, deleted record) is
+      # rejected instead of being treated as a public stream name.
+      record = resolve_subscribe_target(token)
+      return unless record
+
       stream_for record
-      subscribed_to(record, params)
+      record.subscribed_to(self, params) if record.respond_to?(:subscribed_to)
     else
-      name = data["stream"].to_s
-      return if name.blank?
+      return if token.blank?
 
-      stream_from public_stream_name(name)
-      subscribed_to(name, params)
+      stream_from public_stream_name(token)
+      run_subscribed_to_handler(token, params)
     end
   end
 
   def remove_stream(data)
-    record = resolve_subscribe_target(data["stream"])
+    token = data["stream"].to_s
+
+    if signed_token?(token)
+      record = resolve_subscribe_target(token)
+      return unless record
 
-    if record
       stop_stream_from self.class.broadcasting_for(record)
     else
-      name = data["stream"].to_s
-      stop_stream_from public_stream_name(name) if name.present?
+      stop_stream_from public_stream_name(token) if token.present?
     end
   end
 
@@ -102,13 +136,23 @@ module DexieCable
     stop_all_streams
   end
 
-  # Override to push initial data when a stream is added. +record+ is the
-  # resolved target — a record for private streams, or the stream name for
-  # public streams — and +params+ are any extra params sent from the client.
-  def subscribed_to(_record, _params)
+  private
+
+  # Runs the handler registered with +subscribed_to+ for a public stream, in
+  # the channel's context.
+  def run_subscribed_to_handler(name, params)
+    handler = self.class.dexie_subscribed_to_handlers[name]
+    instance_exec(params, &handler) if handler
   end
 
-  private
+  # Distinguishes a signed stream token from a public stream name. A signed
+  # token keeps a valid signature even after it expires, which is what lets us
+  # reject expired tokens instead of falling back to a public stream.
+  def signed_token?(token)
+    return false if token.blank? || SignedGlobalID.verifier.nil?
+
+    SignedGlobalID.verifier.valid_message?(token)
+  end
 
   def public_stream_name(name)
     self.class.broadcasting_for("#{PUBLIC_STREAM_PREFIX}#{name}")

data/lib/dexiecable/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DexieCable
-  VERSION = "2.0.1"
+  VERSION = "3.0.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dexiecable
 version: !ruby/object:Gem::Version
-  version: 2.0.1
+  version: 3.0.0
 platform: ruby
 authors:
 - Stefan Buhrmester