live_cable 0.3.0 → 0.4.0

data/lib/live_cable/connection.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'monitor'
+
 module LiveCable
   class Connection
     include ComponentManagement
@@ -14,6 +16,37 @@ module LiveCable
       @request = request
       @containers = Hash.new { |hash, key| hash[key] = Container.new }
       @components = {}
+      @monitor = Monitor.new
+    end
+
+    # Run a block holding this connection's lock.
+    #
+    # One Connection is shared by every component on a socket, but ActionCable
+    # runs a socket's work - each incoming message, each subscribe and
+    # unsubscribe, each stream_from callback - as separate jobs on a worker
+    # pool shared by the whole server, with nothing keeping two jobs for the
+    # same socket apart. Every such entry point holds this lock for its whole
+    # duration, action and render included, so a stream callback can't land
+    # between an action's write and the push that follows it.
+    #
+    # A Monitor rather than a Mutex because the calls nest: receive ->
+    # broadcast_changeset -> add_component all take it again on one thread.
+    # Only ever one connection's lock per job - never take another
+    # connection's while holding this one.
+    def synchronize(&)
+      @monitor.synchronize(&)
+    end
+
+    # A fresh view for one socket render. The controller behind it is kept,
+    # and built again when a code reload replaces ApplicationController.
+    #
+    # @return [ActionView::Base]
+    def view_context
+      unless @controller.instance_of?(ApplicationController)
+        @controller = Rendering::ControllerRenderer.controller_for(ApplicationController)
+      end
+
+      @controller.view_context
     end
 
     private

data/lib/live_cable/container.rb

@@ -18,7 +18,7 @@ module LiveCable
   # - Shared reactive variables use a special SHARED_CONTAINER
   # - During message processing, mutations are tracked in a changeset
   # - After message processing, components with dirty changesets are re-rendered
-  # - Changesets are reset after broadcasting updates
+  # - Changesets are reset when the next message or stream callback starts
   #
   # Change Tracking:
   # 1. Value is stored via []=
@@ -46,11 +46,12 @@ module LiveCable
     #   container[:user] = User.new              # ActiveRecord - wrapped in Delegator
     def []=(key, value)
       # Remove observer from the old value so it stops notifying this container
-      self[key].try(:remove_live_cable_observer, observer, key)
+      remove_observer_from(self[key], key)
 
-      # ActiveRecord models get observers attached directly
-      if value.class < ModelObserver
-        value.add_live_cable_observer(observer, key)
+      # ActiveRecord models get observers attached directly, even when stored wrapped
+      record = value.is_a?(Delegator) ? value.__getobj__ : value
+      if record.class < ModelObserver
+        record.add_live_cable_observer(observer, key)
       end
 
       # If value is already a Delegator, add observer and store as-is
@@ -59,7 +60,7 @@ module LiveCable
         super
       else
         # Wrap supported types in Delegators for change tracking
-        super(key, Delegator.create_if_supported(value, key, observer))
+        super(key, Delegator.create_if_supported(Delegator.unwrap(value), key, observer))
       end
     end
 
@@ -87,8 +88,8 @@ module LiveCable
       !@changeset.empty?
     end
 
-    # Clear the changeset after broadcasting updates.
-    # Called by Connection after all components have been re-rendered.
+    # Clear the changeset before tracking a new round of changes.
+    # Called by Connection before each message or stream callback.
     #
     # @return [void]
     def reset_changeset
@@ -114,9 +115,7 @@ module LiveCable
       # Note: We only remove this specific observer, not all observers,
       # because the same object might be shared across multiple containers
       each do |variable, value|
-        if value.respond_to?(:remove_live_cable_observer)
-          value.remove_live_cable_observer(observer, variable)
-        end
+        remove_observer_from(value, variable)
       end
 
       # Clear the container's data
@@ -124,5 +123,12 @@ module LiveCable
       @changeset&.clear
       @observer = nil
     end
+
+    private
+
+    def remove_observer_from(value, key)
+      value.try(:remove_live_cable_observer, observer, key)
+      value.__getobj__.try(:remove_live_cable_observer, observer, key) if value.is_a?(Delegator)
+    end
   end
 end

data/lib/live_cable/defaults_signer.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module LiveCable
+  # Signs and verifies the reactive-variable defaults that travel from a
+  # server-rendered page to the client and back on subscribe.
+  #
+  # Defaults originate on the server in the `live(...)` helper, but they are
+  # emitted into the DOM as a `live-defaults` attribute and re-sent by the
+  # client when its ActionCable subscription connects. Because that value
+  # round-trips through the browser, it cannot be trusted: without signing, a
+  # user could edit the attribute (or craft the subscribe frame) to set *any*
+  # reactive variable at subscribe time - including ones deliberately not
+  # marked `writable:`, such as a record id, price, or tenant key.
+  #
+  # The blob is signed with a key derived from secret_key_base and bound to the
+  # component's live_id, so a tampered or replayed value verifies as invalid
+  # and is treated as no defaults at all.
+  module DefaultsSigner
+    PURPOSE = 'live_cable/defaults'
+
+    module_function
+
+    # Equal defaults always sign to the same blob, so the client can compare
+    # blobs to tell whether a component's defaults have changed.
+    #
+    # @param defaults [Hash] The reactive-variable defaults to sign
+    # @param live_id [String] The component instance the defaults belong to
+    # @return [String] A signed, tamper-evident blob
+    def sign(defaults, live_id)
+      defaults = (defaults || {}).as_json.sort.to_h
+
+      verifier.generate({ 'live_id' => live_id, 'defaults' => defaults }, purpose: PURPOSE)
+    end
+
+    # The defaults as the component gets them back from the page on
+    # subscribe, so a prerender can render with the same values. In
+    # development and test, warns about any default that changes on the way.
+    #
+    # @param defaults [Hash]
+    # @param component_class [Class] Named in the warning
+    # @return [Hash] String-keyed, JSON-native defaults
+    def round_trip(defaults, component_class)
+      defaults ||= {}
+      json = JSON.parse(JSON.generate(defaults.as_json))
+
+      warn_about_changed(defaults, json, component_class) if Rails.env.local?
+
+      json
+    end
+
+    # @param blob [String, nil] A blob previously produced by {sign}
+    # @param live_id [String] The component instance the blob must be bound to
+    # @return [Hash] The verified defaults, or an empty hash when the blob is
+    #   blank, not a string, tampered with, or bound to a different component
+    def verify(blob, live_id)
+      return {} unless blob.is_a?(String) && blob.present?
+
+      data = verifier.verify(blob, purpose: PURPOSE)
+      return {} unless data.is_a?(Hash) && data['live_id'] == live_id
+
+      data['defaults'] || {}
+    rescue ActiveSupport::MessageVerifier::InvalidSignature
+      {}
+    end
+
+    def warn_about_changed(defaults, json, component_class)
+      defaults.each do |key, value|
+        next if json[key.to_s] == value
+
+        LiveCable.warn_once(
+          "[LiveCable] #{component_class.name} default :#{key} (#{value.class}) is not JSON-native, so it " \
+          'reaches the component as its JSON form. Pass strings, numbers, booleans, nil, or arrays and ' \
+          'string-keyed hashes of those - an id rather than a record, which the component loads itself.'
+        )
+      end
+    end
+
+    # @return [ActiveSupport::MessageVerifier]
+    def verifier
+      # JSON serializer keeps the payload to simple, safe types (no Marshal).
+      ActiveSupport::MessageVerifier.new(secret, serializer: JSON, url_safe: true)
+    end
+
+    # A key derived for this purpose alone, as Rails' own verifiers do, rather
+    # than secret_key_base itself - which would make these signatures
+    # interchangeable with anything else HMAC'd under the raw secret.
+    def secret
+      if Rails.application&.secret_key_base.blank?
+        raise LiveCable::Error, 'secret_key_base is required to sign LiveCable defaults'
+      end
+
+      Rails.application.key_generator.generate_key(PURPOSE)
+    end
+  end
+end

data/lib/live_cable/delegation/array.rb

@@ -4,16 +4,19 @@ module LiveCable
   module Delegation
     module Array
       extend Methods
-      extend Enumerable
 
       GETTER_METHODS = %i[
         []
+        at
         chunk
         collect
         compact
         cycle
+        detect
+        dig
         drop
         drop_while
+        fetch
         filter
         find
         find_all
@@ -24,9 +27,14 @@ module LiveCable
         group_by
         last
         map
+        max
+        max_by
+        min
+        min_by
         reject
         reverse
         rotate
+        sample
         select
         shuffle
         slice
@@ -39,21 +47,36 @@ module LiveCable
         zip
       ].freeze
 
+      ITERATOR_METHODS = %i[
+        each_cons
+        each_slice
+        each_with_index
+        each_with_object
+        reverse_each
+      ].freeze
+
       MUTATIVE_METHODS = %i[
         []=
         <<
+        append
         clear
+        collect!
         compact!
+        compact_blank!
         concat
         delete
         delete_at
         delete_if
+        extract!
+        extract_options!
         fill
+        filter!
         flatten!
         insert
         keep_if
         map!
         pop
+        prepend
         push
         reject!
         replace
@@ -70,9 +93,12 @@ module LiveCable
       ].freeze
 
       decorate_getters GETTER_METHODS
+      decorate_iterators ITERATOR_METHODS
       decorate_mutators MUTATIVE_METHODS
 
       def each(&)
+        return to_enum(:each) { size } unless block_given?
+
         __getobj__.each do |v|
           yield create_delegator(v)
         end

data/lib/live_cable/delegation/hash.rb

@@ -5,34 +5,88 @@ module LiveCable
     module Hash
       extend Methods
 
+      GETTER_METHODS = %i[
+        []
+        dig
+        fetch
+      ].freeze
+
+      COLLECTION_GETTER_METHODS = %i[
+        fetch_values
+        values
+        values_at
+      ].freeze
+
+      ITERATOR_METHODS = %i[
+        detect
+        each_with_index
+        each_with_object
+        find
+      ].freeze
+
       MUTATIVE_METHODS = %i[
         []=
         clear
         compact!
+        compact_blank!
+        compare_by_identity
         deep_merge!
         deep_stringify_keys!
+        deep_symbolize_keys!
         deep_transform_keys!
         deep_transform_values!
+        default=
+        default_proc=
         delete
         delete_if
         except!
         extract!
+        filter!
         keep_if
         merge!
         rehash
         reject!
+        replace
         reverse_merge!
+        reverse_update
         select!
         shift
+        slice!
+        store
         stringify_keys!
         symbolize_keys!
+        to_options!
         transform_keys!
         transform_values!
         update
+        with_defaults!
       ].freeze
 
-      decorate_getter :[]
+      decorate_getters GETTER_METHODS
+      decorate_collection_getters COLLECTION_GETTER_METHODS
+      decorate_iterators ITERATOR_METHODS
       decorate_mutators MUTATIVE_METHODS
+
+      # Like Hash#each, yields the key and value separately only to blocks that
+      # take more than one argument and a [key, value] pair to the rest.
+      def each_pair(&block)
+        return to_enum(:each_pair) { size } unless block
+
+        split = block.arity > 1
+
+        __getobj__.each_pair do |key, value|
+          value = create_delegator(value)
+
+          split ? yield(key, value) : yield([key, value])
+        end
+      end
+      alias each each_pair
+
+      def each_value
+        return to_enum(:each_value) { size } unless block_given?
+
+        __getobj__.each_value { |value| yield create_delegator(value) }
+      end
     end
   end
 end

data/lib/live_cable/delegation/methods.rb

@@ -19,6 +19,30 @@ module LiveCable
         end
       end
 
+      # A new collection is only wrapped when it holds something trackable, so
+      # a plain list of scalars stays a real Array.
+      def decorate_collection_getters(methods)
+        methods.each do |method|
+          define_method(method) do |*pos, **kwargs, &block|
+            result = __getobj__.method(method).call(*pos, **kwargs, &block)
+
+            result.any? { |value| Delegator.supported?(value) } ? create_delegator(result) : result
+          end
+        end
+      end
+
+      # Runs Enumerable's implementation against the delegator, so elements
+      # arrive through its wrapping #each.
+      def decorate_iterators(methods)
+        methods.each do |method|
+          iterator = ::Enumerable.instance_method(method)
+
+          define_method(method) do |*args, &block|
+            iterator.bind_call(self, *args, &block)
+          end
+        end
+      end
+
       def decorate_mutators(methods)
         methods.each do |method|
           decorate_mutator(method)
@@ -29,7 +53,7 @@ module LiveCable
         define_method(method) do |*pos, **kwargs, &block|
           notify_live_cable_observers
 
-          __getobj__.method(method).call(*pos, **kwargs, &block)
+          __getobj__.method(method).call(*Delegator.unwrap(pos), **Delegator.unwrap(kwargs), &block)
         end
       end
     end

data/lib/live_cable/delegation/model.rb

@@ -7,6 +7,18 @@ module LiveCable
 
       decorate_mutator :assign_attributes
       decorate_mutator :update
+
+      # Setters, toggle!, reload and the like reach the record through here
+      def method_missing(...) # rubocop:disable Style/MissingRespondToMissing -- SimpleDelegator defines it
+        record = __getobj__
+        writes = record.live_cable_writes
+
+        begin
+          super
+        ensure
+          notify_live_cable_observers unless record.live_cable_writes == writes
+        end
+      end
     end
   end
 end

data/lib/live_cable/delegator.rb

@@ -48,12 +48,14 @@ module LiveCable
     def initialize(value)
       super
 
-      # Extend with the appropriate delegation module based on value's type
-      Delegation::SUPPORTED.each do |klass, delegator|
-        if value.is_a?(klass)
-          extend delegator
-        end
-      end
+      extend_delegation_modules
+    end
+
+    # dup doesn't copy the singleton class, so the copy needs its modules again
+    def initialize_dup(other)
+      super
+
+      extend_delegation_modules
     end
 
     # Factory method to create a Delegator only if the value's type is supported.
@@ -73,6 +75,30 @@ module LiveCable
       value
     end
 
+    # Replaces every Delegator in value, value included, with the object it
+    # wraps, copying an Array or Hash only when something inside it changes.
+    #
+    # @param value [Object]
+    # @return [Object]
+    def self.unwrap(value, unwrapped = {}.compare_by_identity)
+      value = value.__getobj__ while value.is_a?(Delegator)
+      return unwrapped[value] if unwrapped.key?(value)
+
+      unwrapped[value] = value
+      copy = nil
+      replace = lambda do |key, child|
+        plain = unwrap(child, unwrapped)
+        (copy ||= value.dup)[key] = plain unless plain.equal?(child)
+      end
+
+      case value
+      when ::Array then value.each_with_index { |child, index| replace.call(index, child) }
+      when ::Hash then value.each_pair { |key, child| replace.call(key, child) }
+      end
+
+      unwrapped[value] = copy || value
+    end
+
     # Check if a value's type can be wrapped in a Delegator.
     #
     # @param value [Object] The value to check
@@ -81,8 +107,27 @@ module LiveCable
       Delegation::SUPPORTED.keys.any? { |c| value.is_a?(c) }
     end
 
+    # SimpleDelegator compares its target with `other` as given, and
+    # ActiveRecord's == rejects anything that isn't an instance of the model.
+    def ==(other)
+      equal?(other) || __getobj__ == (other.is_a?(Delegator) ? other.__getobj__ : other)
+    end
+
+    def eql?(other)
+      equal?(other) || __getobj__.eql?(other.is_a?(Delegator) ? other.__getobj__ : other)
+    end
+
     private
 
+    # Extend with the appropriate delegation module based on the value's type
+    def extend_delegation_modules
+      Delegation::SUPPORTED.each do |klass, delegator|
+        if __getobj__.is_a?(klass)
+          extend delegator
+        end
+      end
+    end
+
     # Create a new Delegator for nested values (e.g., nested arrays/hashes).
     # Propagates all observers from the parent delegator to the child.
     #
@@ -94,6 +139,9 @@ module LiveCable
     #   inner = outer[0]  # Returns a Delegator wrapping ['inner']
     #   inner << 'new'    # Notifies same observers as outer
     def create_delegator(value)
+      # A Delegator stored inside raw data carries some other variable's observers
+      value = value.__getobj__ while value.is_a?(Delegator)
+
       return value unless self.class.supported?(value)
 
       # Create new delegator and propagate all observers from parent

data/lib/live_cable/dispatch.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module LiveCable
+  # A client message on its way to a component: an action call or a
+  # live-reactive write. Exposed as Component#current_dispatch while the
+  # component's before_dispatch callbacks, and the action or write, run.
+  class Dispatch
+    # @return [Symbol] :action or :reactive
+    attr_reader :kind
+
+    # @return [Symbol] The action or reactive variable name
+    attr_reader :name
+
+    # @return [Object] The value a reactive write assigns; nil for an action
+    attr_reader :value
+
+    # @param data [Hash] One message from the client's batch
+    # @return [LiveCable::Dispatch]
+    def self.from_message(data)
+      if data['_action'].to_s == '_reactive'
+        new(:reactive, data['name'], value: data['value'])
+      else
+        new(:action, data['_action'], query: data['params'])
+      end
+    end
+
+    def initialize(kind, name, value: nil, query: nil)
+      @kind = kind
+      @name = name.to_s.to_sym
+      @value = value
+      @query = query
+    end
+
+    def action?
+      kind == :action
+    end
+
+    def reactive?
+      kind == :reactive
+    end
+
+    # @return [ActionController::Parameters, nil] The action's params; nil for
+    #   a reactive write
+    def params
+      return unless action?
+
+      @params ||= ActionController::Parameters.new(
+        ActionDispatch::ParamBuilder.from_pairs(
+          ActionDispatch::QueryParser.each_pair(@query || '')
+        )
+      )
+    end
+  end
+end

data/lib/live_cable/engine.rb

@@ -9,7 +9,7 @@ module LiveCable
       if live_component_dir.directory?
         Rails.autoloaders.main.push_dir(live_component_dir, namespace: Live)
       else
-        warn("[LiveCable Warning] #{live_component_dir} does not exist for components.")
+        LiveCable.warn_once("[LiveCable] #{live_component_dir} does not exist; no components will be autoloaded.")
       end
 
       # Add LiveCable to importmap (skip when using jsbundling/npm)
@@ -35,6 +35,8 @@ module LiveCable
     initializer 'live_cable.active_record' do
       ActiveSupport.on_load :active_record do
         include ModelObserver
+
+        ActiveRecord::PredicateBuilder.prepend(PredicateBuilder)
       end
     end
   end

data/lib/live_cable/forbidden.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module LiveCable
+  # A message asked for an action or reactive write the component doesn't
+  # expose. Never offered to rescue_from.
+  class Forbidden < Error; end
+end

data/lib/live_cable/identity_digest.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module LiveCable
+  # Digests the values that identify who a page was rendered for, so the
+  # client can tell when they change between pages without learning them.
+  #
+  # Keyed with a key derived from secret_key_base: a plain hash of a user id
+  # could be matched by hashing guessed ids.
+  module IdentityDigest
+    PURPOSE = 'live_cable/identity'
+
+    module_function
+
+    # @param values [Array<Object>] Records are identified by their GlobalID,
+    #   as ActionCable identifies a connection; anything else by its to_s
+    # @return [String] A hex digest
+    def digest(*values)
+      payload = values.map { |value| value.respond_to?(:to_gid_param) ? value.to_gid_param : value.to_s }
+
+      OpenSSL::HMAC.hexdigest('SHA256', key, JSON.generate(payload))
+    end
+
+    def key
+      Rails.application.key_generator.generate_key(PURPOSE)
+    end
+  end
+end

data/lib/live_cable/model_observer.rb

@@ -4,10 +4,47 @@ module LiveCable
   module ModelObserver
     include ObserverTracking
 
+    def ==(other)
+      super(other.is_a?(Delegator) ? other.__getobj__ : other)
+    end
+    alias eql? ==
+
     def _write_attribute(...)
       notify_live_cable_observers
 
       super
     end
+
+    def write_attribute(...)
+      notify_live_cable_observers
+
+      super
+    end
+
+    def update_columns(...)
+      super.tap { notify_live_cable_observers }
+    end
+
+    def reload(...)
+      super.tap { notify_live_cable_observers }
+    end
+
+    # Catches in-place changes to serialized and JSON attributes once saved
+    def changes_applied(...)
+      super.tap { notify_live_cable_observers if saved_changes? }
+    end
+
+    # Lets a Delegator around this record see that a call it forwarded wrote to it
+    def live_cable_writes
+      @live_cable_writes || 0
+    end
+
+    private
+
+    def notify_live_cable_observers
+      @live_cable_writes = live_cable_writes + 1
+
+      super
+    end
   end
 end