live_cable 0.3.0 → 0.4.0

data/lib/live_cable/component/broadcasting.rb

@@ -12,11 +12,24 @@ module LiveCable
       end
 
       def broadcast_subscribe
-        broadcast({ _status: 'subscribed', id: live_id })
+        broadcast({ _status: 'subscribed', id: live_id, _subscribed: true })
+
+        # Deliver any events queued before this component had a channel of its
+        # own (e.g. dispatched while it was rendered inline by a parent). The
+        # broadcast_render path flushes events itself, so this only matters for
+        # an already-rendered component that subscribes without re-rendering.
+        broadcast_events
+      end
+
+      # Sends any queued events on their own, for when there's no render for
+      # them to ride along with.
+      def broadcast_events
+        events = flush_events
+        broadcast(_events: events) if events.any?
       end
 
-      # Sent when a received message didn't change any reactive variables,
-      # so the client can clear its loading state without a re-render.
+      # Answers a message batch when the component's own render didn't -
+      # nothing changed, or its render went out inside its parent's.
       def broadcast_ack
         broadcast({ _ack: true })
       end
@@ -26,17 +39,35 @@ module LiveCable
         @subscribed = false
       end
 
-      def broadcast_render
+      # @param subscribed [Boolean] whether this is the render sent when the
+      #   component subscribes
+      # @return [Boolean] false when the render changed nothing on the page, so
+      #   no _refresh went out
+      def broadcast_render(subscribed: false)
+        sent = false
+
         run_callbacks :render do
-          data = { _refresh: render.as_json }
+          result = render
+          events = flush_events
+
+          # Leaves the reply unclaimed, so the message is answered with an _ack
+          if !subscribed && result.is_a?(LiveCable::Rendering::RenderResult) && result.blank?
+            broadcast(_events: events) if events.any?
+            next
+          end
+
+          data = { _refresh: result.as_json, _reply: live_connection&.take_reply(self) }
+          data[:_subscribed] = true if subscribed
 
           # Events ride along with the render so the client can fire them
           # after the DOM has been morphed
-          events = flush_events
           data[:_events] = events if events.any?
 
           broadcast(data)
+          sent = true
         end
+
+        sent
       end
     end
   end

data/lib/live_cable/component/dispatching.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module LiveCable
+  class Component
+    module Dispatching
+      extend ActiveSupport::Concern
+
+      included do
+        define_model_callbacks :dispatch, only: :before
+      end
+
+      # @return [LiveCable::Dispatch, nil] The client message being dispatched
+      attr_reader :current_dispatch
+
+      # Run the before_dispatch callbacks, then the action or reactive write
+      # the message asks for, unless a callback threw :abort.
+      #
+      # @param dispatch [LiveCable::Dispatch] Already checked against the
+      #   component's actions and writable variables
+      def perform_dispatch(dispatch)
+        @current_dispatch = dispatch
+
+        run_callbacks :dispatch do
+          if dispatch.reactive?
+            public_send("#{dispatch.name}=", dispatch.value)
+          else
+            action = method(dispatch.name)
+            action.arity.positive? ? action.call(dispatch.params) : action.call
+          end
+        end
+      ensure
+        @current_dispatch = nil
+      end
+    end
+  end
+end

data/lib/live_cable/component/lifecycle.rb

@@ -44,7 +44,7 @@ module LiveCable
         broadcast_destroy
 
         # Destroy children as well
-        previous_render_context&.children&.map(&:destroy)
+        owned_children.each(&:destroy)
       end
 
       # Allow the component to access the identified_by methods from the connection

data/lib/live_cable/component/reactive_variables.rb

@@ -5,6 +5,10 @@ module LiveCable
     module ReactiveVariables
       extend ActiveSupport::Concern
 
+      # A client may write a shared name only if every class sharing it declares
+      # it writable. Keyed by class name so a reload replaces the entry.
+      SHARED_DECLARATIONS = Concurrent::Map.new
+
       included do
         class_attribute :shared_variables, default: []
         class_attribute :reactive_variables, default: []
@@ -29,12 +33,22 @@ module LiveCable
           end
 
           create_reactive_variables(variable, initial_value, shared: shared)
+          declare_shared(variable, writable:) if shared
         end
 
         def shared(variable, initial_value = nil)
           self.shared_variables = (shared_variables || []).dup << variable
 
           create_reactive_variables(variable, initial_value, shared: true)
+          declare_shared(variable, writable: false)
+        end
+
+        # @return [Boolean] whether a client message may set the variable
+        def client_writable?(variable)
+          return false unless writable_reactive_variables.include?(variable)
+          return true unless shared_reactive_variables.include?(variable)
+
+          SHARED_DECLARATIONS.fetch(variable, {}).values.all?
         end
 
         def actions(*names)
@@ -48,7 +62,15 @@ module LiveCable
 
         private
 
+        def declare_shared(variable, writable:)
+          SHARED_DECLARATIONS.compute_if_absent(variable) { Concurrent::Map.new }[name || self] = writable
+        end
+
         def create_reactive_variables(variable, initial_value, shared: false)
+          unless initial_value.nil? || initial_value.is_a?(Proc)
+            raise ArgumentError, "Initial value for :#{variable} must be a proc or nil"
+          end
+
           define_method(variable) do
             container_name = shared ? Connection::SHARED_CONTAINER : live_id
 
@@ -60,11 +82,12 @@ module LiveCable
 
             return if initial_value.nil?
 
-            if initial_value.arity.positive?
-              initial_value.call(self)
-            else
-              initial_value.call
-            end
+            prerender_container[variable] =
+              if initial_value.arity.positive?
+                initial_value.call(self)
+              else
+                initial_value.call
+              end
           end
 
           define_method("#{variable}=") do |value|
@@ -99,6 +122,11 @@ module LiveCable
         @defaults = (defaults || {}).symbolize_keys
       end
 
+      # @api private
+      def round_trip_defaults
+        self.defaults = DefaultsSigner.round_trip(defaults, self.class)
+      end
+
       def apply_defaults
         # Don't set defaults more than once
         return if defaults_applied

data/lib/live_cable/component/rendering.rb

@@ -17,6 +17,8 @@ module LiveCable
 
       def render
         @rendered = true
+        return render_in(live_connection.view_context) if live_connection
+
         ApplicationController.renderer.render(self, layout: false)
       end
 
@@ -38,13 +40,15 @@ module LiveCable
       end
 
       def render_in(view_context)
+        template_changed = false
+
         view, render_context = view_context.with_render_context(self) do
-          result = view_context.render(template: to_partial_path, locals:)
+          result = view_context.render(template: to_partial_path, locals: locals(view_context))
 
           unless result.is_a?(LiveCable::Rendering::Partial)
-            warn(
-              "[LiveCable Warning] #{to_partial_path} was rendered without using a .live.erb template, " \
-              'this will be less performant.'
+            LiveCable.warn_once(
+              "[LiveCable] #{to_partial_path} was rendered without a .live.erb template; " \
+              'the full template diff is sent on every change, which is less performant.'
             )
 
             next result
@@ -87,10 +91,8 @@ module LiveCable
         end
 
         if previous_render_context
-          # Children from skipped parts are preserved — their part simply didn't
-          # re-evaluate this cycle, so they haven't actually gone away.
-          preserved = render_context.preserved_children_from(previous_render_context)
-          destroyed = previous_render_context.children - render_context.children - preserved
+          render_context.inherit_skipped(previous_render_context) unless template_changed
+          destroyed = previous_render_context.owned_children - render_context.owned_children
           destroyed.each(&:destroy)
         end
 
@@ -130,6 +132,11 @@ module LiveCable
         previous_render_context&.children || []
       end
 
+      # @return [Array<LiveCable::Component>]
+      def owned_children
+        previous_render_context&.owned_children || []
+      end
+
       private
 
       # @return [Hash<String, Boolean>]
@@ -145,9 +152,10 @@ module LiveCable
         matches = html.match(/(?:\n\s*|^\s*|<!--.*?-->)<([a-zA-Z0-9-]+)/)
 
         unless matches
+          preview = html.to_s.strip[0, 80]
           raise LiveCable::Error,
             "#{self.class.name} template must have a single root HTML element " \
-            '(could not find an opening tag in first part of rendered output)'
+            "(could not find an opening tag in the first part of rendered output: #{preview.inspect})"
         end
 
         attributes = {
@@ -157,17 +165,25 @@ module LiveCable
           'data-live-status-value' => subscribed? ? 'subscribed' : 'disconnected',
         }
 
-        attributes['live-defaults'] = defaults.to_json unless live_connection
+        # Sign the defaults so the client can't tamper with them on the round
+        # trip and set non-writable reactive variables at subscribe time.
+        unless live_connection
+          attributes['live-defaults'] = LiveCable::DefaultsSigner.sign(defaults, live_id)
+        end
 
-        html.insert(matches.end(1), " #{view_context.tag.attributes(attributes)}".html_safe)
-        html
+        # Build a new string rather than mutating `html` in place with
+        # String#insert - the rendered part may be frozen, which would raise
+        # a FrozenError.
+        insert_at = matches.end(1)
+        rendered_attributes = " #{view_context.tag.attributes(attributes)}"
+        "#{html[0...insert_at]}#{rendered_attributes}#{html[insert_at..]}".html_safe
       end
 
-      def locals
+      def locals(view_context)
         identifiers = channel ? channel.connection.identifiers.to_a : []
 
         (all_reactive_variables | (self.class.shared_variables || []) | identifiers).
-          to_h { |v| [v, public_send(v)] }.
+          to_h { |v| [v, view_context.live_cable_unwrap(public_send(v))] }.
           merge(
             component: self
           )

data/lib/live_cable/component/streaming.rb

@@ -11,6 +11,13 @@ module LiveCable
         additional_streams.each do |stream_name|
           channel.stop_stream_from(stream_name)
         end
+
+        additional_streams.clear
+      end
+
+      def stop_stream_from(channel_name)
+        channel.stop_stream_from(channel_name)
+        additional_streams.delete(channel_name)
       end
 
       def stream_from(channel_name, callback = nil, coder: nil, &block)
@@ -19,11 +26,35 @@ module LiveCable
         channel.stream_from(channel_name, coder:) do |payload|
           callback ||= block
 
-          begin
-            callback.call(payload)
-            live_connection.broadcast_changeset
+          # Stopping a stream, as disconnect does, can't take back a broadcast
+          # already queued, which may run after it or wait on the lock below
+          connection = live_connection
+          next unless connection
+
+          # Held across the callback and the render together: the callback's
+          # writes are what race an action on another worker, so locking only
+          # the broadcast would leave the race in place.
+          connection.synchronize do
+            next unless live_connection == connection
+            next unless additional_streams.include?(channel_name)
+
+            connection.reset_changeset
+
+            # A rescue_from handler that takes the error may have changed state
+            # to show it, so render in that case too; after an _error there is
+            # nothing left to render into.
+            handled = begin
+              callback.call(payload)
+              true
+            rescue StandardError => error
+              connection.rescue_error(self, error)
+            end
+
+            connection.broadcast_changeset if handled
+          # Nothing above this rescues a stream callback, so a raising
+          # rescue_from handler or render must not escape to ActionCable
           rescue StandardError => error
-            live_connection.handle_error(self, error)
+            connection.handle_error(self, error)
           end
         end
       end

data/lib/live_cable/component.rb

@@ -6,6 +6,7 @@ module LiveCable
     include ReactiveVariables
     include Identification
     include Lifecycle
+    include Dispatching
     include Broadcasting
     include Events
     include Rendering
@@ -17,6 +18,9 @@ module LiveCable
     # @return [String]
     attr_reader :id
 
+    # @return [Hash]
+    attr_reader :defaults
+
     def initialize(id, **defaults)
       @id = self.class.resolve_id(id)
       @rendered = false
@@ -32,9 +36,6 @@ module LiveCable
     # @return [Boolean]
     attr_reader :subscribed
 
-    # @return [Hash]
-    attr_reader :defaults
-
     # @return [LiveCable::Channel, nil]
     attr_reader :channel
   end

data/lib/live_cable/connection/broadcasting.rb

@@ -8,6 +8,12 @@ module LiveCable
       # @return [Array<LiveCable::Component>] Components that were broadcast to
       #   (rendered or errored), including children rendered by their parents
       def broadcast_changeset
+        synchronize { broadcast_changeset_unsynchronized }
+      end
+
+      private
+
+      def broadcast_changeset_unsynchronized
         rendered = []
         shared_changeset = containers[SHARED_CONTAINER]&.changeset
 
@@ -32,10 +38,16 @@ module LiveCable
 
         # Deliver events from components that didn't broadcast a render this
         # cycle (no state change, or rendered inline by a parent) - rendered
-        # components already flushed their events with the refresh
+        # components already flushed their events with the refresh.
+        #
+        # A component rendered inline by a parent has no channel of its own
+        # yet, so it can't deliver anything. Leave its events queued (don't
+        # flush) so they're delivered when its own subscription connects,
+        # rather than silently dropped here.
         components.each_value do |component|
-          events = component.flush_events
-          component.broadcast(_events: events) if events.any?
+          next unless component.subscribed?
+
+          component.broadcast_events
         end
 
         rendered

data/lib/live_cable/connection/component_management.rb

@@ -10,19 +10,23 @@ module LiveCable
       end
 
       def add_component(component)
-        component.live_connection = self
-        components[component.live_id] = component
+        synchronize do
+          component.live_connection = self
+          components[component.live_id] = component
+        end
       end
 
       def remove_component(component)
-        # Clean up the container to break observer reference chains
-        container = containers.delete(component.live_id)
-        container&.cleanup
+        synchronize do
+          # Clean up the container to break observer reference chains
+          container = containers.delete(component.live_id)
+          container&.cleanup
 
-        components.delete(component.live_id)
+          components.delete(component.live_id)
 
-        # Clean up shared container if no components remain
-        cleanup_shared_container
+          # Clean up shared container if no components remain
+          cleanup_shared_container
+        end
       end
 
       private

data/lib/live_cable/connection/error_handling.rb

@@ -5,6 +5,24 @@ module LiveCable
     module ErrorHandling
       extend ActiveSupport::Concern
 
+      # Offer an error raised by the component's own code - an action, a
+      # reactive write, a stream callback - to its rescue_from handlers, and
+      # fall back to #handle_error when none matches.
+      #
+      # A handled error is a processed message, not a failed one: no _error
+      # goes out, so the caller must still answer with a render or an _ack or
+      # the client's loading state never clears.
+      #
+      # @param component [LiveCable::Component]
+      # @param error [Exception]
+      # @return [Boolean] true when a handler took the error
+      def rescue_error(component, error)
+        return true if component.rescue_with_handler(error)
+
+        handle_error(component, error)
+        false
+      end
+
       # Report an error and replace the component on the client with an
       # error box.
       #
@@ -16,16 +34,19 @@ module LiveCable
       #   through; needed when the component failed before it connected to
       #   one, or when there is no component at all
       def handle_error(component, error, channel: nil)
-        Rails.error.report(error)
+        synchronize do
+          take_reply(component)
+          Rails.error.report(error)
 
-        html = error_html(component, error)
+          html = error_html(component, error)
 
-        # Destroy children first so their _status:destroy messages arrive before _error
-        component&.rendered_children&.each(&:destroy)
+          # Destroy children first so their _status:destroy messages arrive before _error
+          component&.owned_children&.each(&:destroy)
 
-        # Broadcast the error - JS replaces the DOM and calls unsubscribe(),
-        # which triggers LiveChannel#unsubscribed -> component.disconnect for server cleanup
-        (channel || component)&.broadcast(_error: html)
+          # Broadcast the error - JS replaces the DOM and calls unsubscribe(),
+          # which triggers LiveChannel#unsubscribed -> component.disconnect for server cleanup
+          (channel || component)&.broadcast(_error: html)
+        end
       end
 
       private

data/lib/live_cable/connection/messaging.rb

@@ -6,79 +6,67 @@ module LiveCable
       extend ActiveSupport::Concern
 
       def receive(component, data)
-        reset_changeset
+        synchronize do
+          reset_changeset
 
-        return unless data['messages'].present?
+          return unless data['messages'].present?
 
-        # An error broadcasts an _error, which is itself the batch's one
-        # response - so a failed message must suppress the trailing _ack
-        errored = false
-        data['messages'].each do |message|
-          errored = true unless action(component, message)
-        end
-
-        rendered = broadcast_changeset
-
-        # Guarantee exactly one response per message batch so the client can
-        # clear its loading state even when nothing changed
-        component.broadcast_ack unless errored || rendered.include?(component)
-      end
-
-      # @return [Boolean] true when the message was processed, false when an
-      #   error was handled (and an _error broadcast in its place)
-      def action(component, data)
-        params = parse_params(data)
+          @reply_to = component
 
-        if data['_action']
-          action = data['_action']&.to_sym
-
-          if action == :_reactive
-            return reactive(component, data)
-          end
-
-          unless component.class.allowed_actions.include?(action)
-            raise LiveCable::Error, "Unauthorized action: #{action}"
+          data['messages'].each do |message|
+            action(component, message)
           end
 
-          method = component.method(action)
+          broadcast_changeset
 
-          if method.arity.positive?
-            method.call(params)
-          else
-            method.call
-          end
+          # Guarantee exactly one reply per message batch so the client can
+          # clear its loading state: the component's own render, an _error,
+          # or this
+          component.broadcast_ack if take_reply(component)
+        ensure
+          @reply_to = nil
         end
+      end
 
+      # @return [Boolean] true, once, for the frame that answers the message
+      #   batch the component sent
+      def take_reply(component)
+        return false unless component && @reply_to.equal?(component)
+
+        @reply_to = nil
         true
-      rescue StandardError => e
-        handle_error(component, e)
-        false
       end
 
-      # @return [Boolean] true when applied, false when an error was handled
-      def reactive(component, data)
-        unless component.class.writable_reactive_variables.include?(data['name'].to_sym)
-          raise LiveCable::Error, "Non-writable reactive variable: #{data['name']}"
-        end
+      # @return [Boolean] true when the message was processed (including one a
+      #   before_dispatch callback halted, or whose error the component's
+      #   rescue_from took), false when an _error was broadcast in its place
+      def action(component, data)
+        return true unless data['_action']
 
-        component.public_send("#{data['name']}=", data['value'])
+        dispatch = Dispatch.from_message(data)
+        ensure_exposed(component, dispatch)
+        component.perform_dispatch(dispatch)
 
         true
-      rescue StandardError => e
+      rescue LiveCable::Forbidden => e
         handle_error(component, e)
         false
+      rescue StandardError => e
+        rescue_error(component, e)
       end
 
       private
 
-      def parse_params(data)
-        params = data['params'] || ''
+      def ensure_exposed(component, dispatch)
+        if dispatch.reactive?
+          return if component.class.client_writable?(dispatch.name)
+
+          raise LiveCable::Forbidden, "Non-writable reactive variable: #{dispatch.name}"
+        end
+
+        return if component.class.allowed_actions.include?(dispatch.name)
 
-        ActionController::Parameters.new(
-          ActionDispatch::ParamBuilder.from_pairs(
-            ActionDispatch::QueryParser.each_pair(params)
-          )
-        )
+        raise LiveCable::Forbidden, "Unauthorized action: #{dispatch.name}"
       end
     end
   end

data/lib/live_cable/connection/state_management.rb

@@ -10,7 +10,8 @@ module LiveCable
 
         return container[variable] if container.key?(variable)
 
-        container[variable] = process_initial_value(component, variable, initial_value)
+        container[variable] = process_initial_value(component, initial_value)
+        container[variable]
       end
 
       def set(container_name, variable, value)
@@ -31,25 +32,21 @@ module LiveCable
         shared_changeset = containers[SHARED_CONTAINER]&.changeset
         container = containers[component.live_id]
 
-        container.changeset | component.shared_reactive_variables.intersection(shared_changeset)
+        changeset = container.changeset | component.shared_reactive_variables.intersection(shared_changeset)
+        return changeset if changeset.empty?
+
+        changeset | component.shared_variables
       end
 
       private
 
-      def process_initial_value(component, variable, initial_value)
-        case initial_value
-        when nil
-          nil
-        when Proc
-          args = []
-          args << component if initial_value.arity.positive?
-
-          initial_value.call(*args)
-        else
-          raise LiveCable::Error, "Initial value for \":#{variable}\" must be a proc or nil"
-        end
-      rescue StandardError => e
-        handle_error(component, e)
+      def process_initial_value(component, initial_value)
+        return if initial_value.nil?
+
+        args = []
+        args << component if initial_value.arity.positive?
+
+        initial_value.call(*args)
       end
     end
   end