dexiecable 2.0.0 → 2.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 36154d26195467f83401235810a4bc86b3fec7402c7601aae8bf1bd1c4097406
-  data.tar.gz: eb647d275d24a875a65af6c2d428c057579dda3653f4567cad31de4b15ed610e
+  metadata.gz: c5284c177e5517bff845edf2e5317d1ab9c676deafd605a662b3dea1b7363b6a
+  data.tar.gz: 94f3e811e2bca16d05967c0c0dbf242bcae00b880212ad0dba7d1ee44f8263c9
 SHA512:
-  metadata.gz: c50c143233dfaec03433d26779a6fe0ac0ed3e7e3e0ff4c4701651dee6c5fd4f7edef1b5f0fce319bd188cd1ee5d396363a6e8896dc2d6587ca14ed00ca5f247
-  data.tar.gz: 43c90cfbbf0230a4f74bd0c8a2b5cff21870d2fbe2f4dc4ab64809deeafd2460a39f33c708d84b00c9170c80e2eb2ece5d519b36ba9d06dada851a2a1479c88b
+  metadata.gz: 4999890a88da548b86e19843b40a0221654eb2a144ec52f954c7723cb652c287d7884fd34e0703d5895131e3b1213ee840a427f31defa91ff21738a38133514a
+  data.tar.gz: 67bb97e60d5d9fc7416e239e0695b69ff00a4930df8d97d8380da29bd51686af9f2d70f04bd69d92322e61ea042a71704ce4e98bbc35d14ee5f0a33d13343def

data/README.md

@@ -1,11 +1,11 @@
 # 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-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-streaming) ActiveRecord macro for automatic change syncing.
 
 Push Dexie table updates to a client from anywhere on the server:
 
@@ -18,7 +18,7 @@ class NotificationsController < ApplicationController
 end
 ```
 
-Or sync model changes automatically with the `syncs_to_dexie` macro (more info [below](#syncs_to_dexie--automatic-model-syncing))
+Or sync model changes automatically with the `syncs_to_dexie` macro (more info [below](#syncs_to_dexie-automatic-model-streaming))
 
 ```ruby
 class Notification < ApplicationRecord
@@ -26,6 +26,40 @@ class Notification < ApplicationRecord
 end
 ```
 
+## What's new in 2.0
+
+DexieCable 2.0 is a mixin. Create your own `DexieChannel` and `include DexieCable`:
+
+```ruby
+class DexieChannel < ApplicationCable::Channel
+  include DexieCable
+end
+```
+
+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);
+```
+
+You can then use the new `subscribed_to` hook to push initial data before any live mutation arrives. The first argument is the record the token was issued for, or the plain stream name for a public stream:
+
+```ruby
+class DexieChannel < ApplicationCable::Channel
+  include DexieCable
+
+  def subscribed_to(record, params)
+    case record
+    when "feed"
+      table(record).bulkAdd(Announcement.for_stream(record).map(&:as_json_for_dexie))
+    when User
+      table("notifications").bulkAdd(record.notifications.map(&:as_json_for_dexie))
+    end
+  end
+end
+```
+
 ## Installation
 
 ### Ruby gem
@@ -101,6 +135,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
@@ -114,7 +150,7 @@ const stopStreaming = subscription.addStream(userStream);
 stopStreaming(); // equivalent to subscription.removeStream(userStream)
 ```
 
-`addStream`/`removeStream` perform `add_stream`/`remove_stream` on `DexieChannel`, which verifies the token and then `stream_from`/`stop_stream_from` the decoded identifier. `removeAllStreams()` performs `remove_all_streams`, stopping every current stream — handy on logout:
+`addStream`/`removeStream` perform `add_stream`/`remove_stream` on `DexieChannel`, which verifies the token and then `stream_from`/`stop_stream_from` the decoded identifier. `removeAllStreams()` performs `remove_all_streams`, stopping every current stream. Handy on logout:
 
 ```js
 subscription.removeAllStreams();
@@ -161,11 +197,11 @@ 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 `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:
+For data that's public (a global feed, announcements, etc.), skip the signature. Use a string target. It's namespaced under `public:` automatically:
 
 ```ruby
 DexieChannel["feed"].table("announcements").add(announcement)
@@ -176,11 +212,11 @@ class Announcement < ApplicationRecord
 end
 ```
 
-Then subscribe by name — no token required:
+Then subscribe by name. No token required:
 
 ```js
-const stopPublicStream = subscription.addPublicStream("feed");
-stopPublicStream(); // equivalent to subscription.removePublicStream("feed")
+const stopPublicStream = subscription.addStream("feed");
+stopPublicStream(); // equivalent to subscription.removeStream("feed")
 ```
 
 Public streams are namespaced under `public:`, so this path can never reach a signed (private) stream.
@@ -222,16 +258,19 @@ DexieChannel[current_user]
 
 The full query chain is serialized as JSON and sent over ActionCable. The JS client replays every method call against the local Dexie database in order.
 
-### `syncs_to_dexie` — automatic model streaming
+### `syncs_to_dexie`: automatic model streaming
 
 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
 
-  # String = public stream (subscribe via addPublicStream("public"))
+  # String = public stream (subscribe via addStream("public"))
   syncs_to_dexie via: "public"
 
   # Procs are also supported. If an array is returned, multiple broadcasts are made
@@ -263,8 +302,8 @@ Internally, `syncs_to_dexie` sets up the following ActiveRecord callbacks:
 | `table:` | model's `table_name` | Override the Dexie table name. A Proc is evaluated in the record's context. |
 | `only:` | `[:create, :update, :destroy]` | Limit which events trigger a sync |
 | `with:` | `:as_json_for_dexie` | Method name (Symbol) or Proc for serializing records |
-| `if:` | *(none)* | Symbol (method name) or Proc — only sync when it returns truthy |
-| `unless:` | *(none)* | Symbol (method name) or Proc — skip sync when it returns truthy |
+| `if:` | *(none)* | Symbol (method name) or Proc. Only sync when it returns truthy |
+| `unless:` | *(none)* | Symbol (method name) or Proc. Skip sync when it returns truthy |
 
 You can combine multiple `syncs_to_dexie` declarations, each with different conditions:
 

data/lib/dexiecable/concern.rb

@@ -20,7 +20,7 @@ module DexieCable
   #
   #   subscribe(db)                 # subscribes to "DexieChannel"
   #   subscription.addStream(DexieChannel.stream_token_for(current_user))
-  #   subscription.addPublicStream("feed")
+  #   subscription.addStream("feed") # plain strings are public streams
   #
   extend ActiveSupport::Concern
 
@@ -72,37 +72,40 @@ module DexieCable
   end
 
   def add_stream(data)
-    record = resolve_subscribe_target(data["stream"])
-    return unless record
-
-    stream_for record
+    token = data["stream"].to_s
     params = data.except("action", "stream").with_indifferent_access
-    subscribed_to(record, params)
-  end
 
-  def remove_stream(data)
-    record = resolve_subscribe_target(data["stream"])
-    return unless 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
 
-    stop_stream_from self.class.broadcasting_for(record)
-  end
+      stream_for record
+      subscribed_to(record, params)
+    else
+      return if token.blank?
 
-  def remove_all_streams(_data)
-    stop_all_streams
+      stream_from public_stream_name(token)
+      subscribed_to(token, params)
+    end
   end
 
-  def add_public_stream(data)
-    name = data["stream"].to_s
-    return if name.blank?
+  def remove_stream(data)
+    token = data["stream"].to_s
+
+    if signed_token?(token)
+      record = resolve_subscribe_target(token)
+      return unless record
 
-    stream_from public_stream_name(name)
-    params = data.except("action", "stream").with_indifferent_access
-    subscribed_to(name, params)
+      stop_stream_from self.class.broadcasting_for(record)
+    else
+      stop_stream_from public_stream_name(token) if token.present?
+    end
   end
 
-  def remove_public_stream(data)
-    name = data["stream"].to_s
-    stop_stream_from public_stream_name(name) if name.present?
+  def remove_all_streams(_data)
+    stop_all_streams
   end
 
   # Override to push initial data when a stream is added. +record+ is the
@@ -113,6 +116,15 @@ module DexieCable
 
   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}")
   end

data/lib/dexiecable/version.rb

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

metadata

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