dexiecable 2.0.0.alpha3 → 2.0.0.alpha5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2c2de6d52cf60491a659aebc8452a88ca8b8878142d08e842fadc8fb4bb1050b
-  data.tar.gz: 6be72c303e815a4809aff6b88a718b3e9ec1df8d5ebd341af03768225ee86bc3
+  metadata.gz: 16d440593b555940ff8039e04091edf54026d8678183acfb5d56b6189b08560c
+  data.tar.gz: 78c9c8e4b7e8e9cd3ae3d8cb7367b040962ef7ea0149d167a20396c58093a938
 SHA512:
-  metadata.gz: ac607ef7627a7a0562459042bcc8b23244362553624cb2f7543a7997430842c5185d5c889b8557c3ad28f10265d286f7a557a1ce76c397473adc97ead82b13d5
-  data.tar.gz: 1386543cc03df9409d17f184a8e1b4b80e85f993663009a32324da9b8e79561000c907c42e25c84c683bef4d4f11e525a5c1cd6dda58a0817595d53417880786
+  metadata.gz: d1d15766bb5dde84e8aaac57998da45e3dc88665740c6beb333d12dafddb3115b148b4e3b49ec8badf706d898eaba1c6fd7c8ad33e77b2aa60083b6b6e3b3a88
+  data.tar.gz: c716de1ee2d50979513c911b168879da8fc640d49f85ddd288ad70715197691c35ffb9020872a2250ae00a62fb35909214a501f91cdeb458323d31cb201bf511

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:
 
@@ -81,11 +88,17 @@ Stream tokens are signed with the application secret, so a client can only subsc
 DexieChannel.stream_token_for(target)
 ```
 
-For an ActiveRecord model it signs the record's GlobalID:
+For an ActiveRecord model it returns a signed GlobalID (Rails' `signed_id`):
 
 ```ruby
 DexieChannel.stream_token_for(current_user)
-# => "signed token for gid://app/User/1"
+# => "signed global id"
+```
+
+Tokens never expire by default. Pass `expires_in:` or `expires_at:` to limit a token's lifetime:
+
+```ruby
+DexieChannel.stream_token_for(current_user, expires_in: 1.day)
 ```
 
 Send that token to the client (render it in a view, return it from an endpoint, etc.) and add it to the subscription:
@@ -107,20 +120,25 @@ 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
-  # Push a snapshot when a private stream is added.
+# app/channels/dexie_channel.rb
+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
   end
 
@@ -131,7 +149,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,125 @@
+# 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:"
+  STREAM_TOKEN_PURPOSE = "dexiecable:streams"
+
+  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). Send it to the client,
+    # which passes it to +subscription.addStream+.
+    #
+    # Tokens never expire by default. Pass +expires_in:+ (a duration) or
+    # +expires_at:+ (a time) to limit a token's lifetime.
+    def stream_token_for(target, expires_at: nil, expires_in: nil)
+      options = { for: STREAM_TOKEN_PURPOSE }
+
+      if expires_at
+        options[:expires_at] = expires_at
+      elsif expires_in
+        options[:expires_in] = expires_in
+      else
+        options[:expires_at] = nil # never expire
+      end
+
+      target.to_sgid_param(**options)
+    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)
+    record = resolve_subscribe_target(data["stream"])
+    return unless record
+
+    stream_for record
+    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
+
+    stop_stream_from self.class.broadcasting_for(record)
+  end
+
+  def remove_all_streams(_data)
+    stop_all_streams
+  end
+
+  def add_public_stream(data)
+    name = data["stream"].to_s
+    return if name.blank?
+
+    stream_from public_stream_name(name)
+    params = data.except("action", "stream").with_indifferent_access
+    subscribed_to(name, params)
+  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 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)
+  end
+
+  private
+
+  def public_stream_name(name)
+    self.class.broadcasting_for("#{PUBLIC_STREAM_PREFIX}#{name}")
+  end
+
+  def resolve_subscribe_target(token)
+    GlobalID::Locator.locate_signed(token, for: STREAM_TOKEN_PURPOSE)
+  rescue ActiveRecord::RecordNotFound, NameError
+    nil
+  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.alpha5"
 end

data/lib/dexiecable.rb

@@ -1,10 +1,11 @@
 # frozen_string_literal: true
 
 require_relative "dexiecable/version"
+require "global_id/railtie" if defined?(Rails::Railtie)
+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.alpha5
 platform: ruby
 authors:
 - Stefan Buhrmester
@@ -37,6 +37,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: globalid
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.6'
 description: DexieCable augments ActionCable channels with a query DSL that mirrors
   the Dexie.js API, letting you push database mutations from the server to the client
   in real time. Includes an ActiveRecord macro (syncs_to_dexie) for automatic change
@@ -50,7 +64,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