live_cable 0.0.1

data/lib/live_cable/component.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+module LiveCable
+  class Component
+    include ActiveSupport::Rescuable
+
+    class_attribute :is_compound, default: false
+    class_attribute :shared_variables, default: []
+    class_attribute :reactive_variables, default: []
+    class_attribute :shared_reactive_variables, default: []
+
+    class << self
+      def compound
+        self.is_compound = true
+      end
+
+      def actions(*names)
+        @allowed_actions = names.map!(&:to_sym).freeze
+      end
+
+      def allowed_actions
+        @allowed_actions || []
+      end
+
+      def reactive(variable, initial_value = nil, shared: false)
+        list_name = shared ? :shared_reactive_variables : :reactive_variables
+        current   = (public_send(list_name) || []).dup
+        public_send("#{list_name}=", current << variable)
+
+        if shared
+          shared_reactive_variables << variable
+        else
+          reactive_variables << variable
+        end
+
+        create_reactive_variables(variable, initial_value, shared: shared)
+      end
+
+      def shared(variable, initial_value = nil)
+        self.shared_variables = (shared_variables || []).dup << variable
+
+        create_reactive_variables(variable, initial_value, shared: true)
+      end
+
+      def component_string
+        name.underscore.delete_prefix('live/')
+      end
+
+      def component_id(id)
+        "#{component_string}/#{id}"
+      end
+
+      private
+
+      def create_reactive_variables(variable, initial_value, shared: false)
+        define_method(variable) do
+          container_name = shared ? Connection::SHARED_CONTAINER : live_id
+
+          if live_connection
+            return live_connection.get(container_name, self, variable, initial_value)
+          elsif prerender_container.key?(variable)
+            return prerender_container[variable]
+          end
+
+          return if initial_value.nil?
+
+          if initial_value.arity.positive?
+            initial_value.call(self)
+          else
+            initial_value.call
+          end
+        end
+
+        define_method("#{variable}=") do |value|
+          container_name = shared ? Connection::SHARED_CONTAINER : live_id
+
+          if live_connection
+            live_connection.set(container_name, variable, value)
+          else
+            prerender_container[variable] = value
+          end
+        end
+      end
+    end
+
+    attr_reader :rendered, :defaults
+
+    def initialize(id)
+      @live_id = self.class.component_id(id)
+      @rendered = false
+      @subscribed = false
+    end
+
+    def broadcast(data)
+      ActionCable.server.broadcast(channel_name, data)
+    end
+
+    def render
+      @rendered = true
+      ApplicationController.renderer.render(self, layout: false)
+    end
+
+    def broadcast_subscribe
+      broadcast({ _status: 'subscribed', id: live_id })
+      @subscribed = true
+    end
+
+    def broadcast_destroy
+      broadcast({ _status: 'destroy' })
+      @subscribed = false
+    end
+
+    def render_broadcast
+      before_render
+      broadcast(_refresh: render)
+      after_render
+    end
+
+    def status
+      subscribed? ? 'subscribed' : 'disconnected'
+    end
+
+    def subscribed?
+      @subscribed
+    end
+
+    def destroy
+      broadcast_destroy
+    end
+
+    # Lifecycle hooks - override in subclasses to add custom behavior
+    def connected
+      # Called when the component is first subscribed to the channel
+    end
+
+    def disconnected
+      # Called when the component is unsubscribed from the channel
+    end
+
+    def before_render
+      # Called before each render/broadcast
+    end
+
+    def after_render
+      # Called after each render/broadcast
+    end
+
+    attr_accessor :live_connection, :channel
+
+    def live_id
+      @live_id ||= SecureRandom.uuid
+    end
+
+    def channel_name
+      "#{live_connection.channel_name}/#{live_id}"
+    end
+
+    def to_partial_path
+      base = self.class.name.underscore
+
+      if self.class.is_compound
+        "#{base}/#{template_state}"
+      else
+        base
+      end
+    end
+
+    def template_state
+      'component'
+    end
+
+    def render_in(view_context)
+      # @TODO: Figure out where to put this
+      ActionView::Base.annotate_rendered_view_with_filenames = false
+
+      view, render_context = view_context.with_render_context(self) do
+        view_context.render(template: to_partial_path, layout: false, locals:)
+      end
+
+      if @previous_render_context
+        destroyed = @previous_render_context.children - render_context.children
+
+        destroyed.each(&:destroy)
+      end
+
+      @previous_render_context = render_context
+
+      view
+    end
+
+    def all_reactive_variables
+      self.class.reactive_variables + self.class.shared_reactive_variables
+    end
+
+    def dirty(*variables)
+      variables.each do |variable|
+        unless all_reactive_variables.include?(variable)
+          raise Error, "Invalid reactive variable: #{variable}"
+        end
+
+        container_name = self.class.reactive_variables.include?(variable) ? live_id : Connection::SHARED_CONTAINER
+
+        live_connection.dirty(container_name, variable)
+      end
+    end
+
+    def defaults=(defaults)
+      # Don't set defaults more than once
+      return if defined?(@defaults)
+
+      @defaults = (defaults || {}).symbolize_keys
+      keys = all_reactive_variables & @defaults.keys
+
+      keys.each do |key|
+        public_send("#{key}=", @defaults[key])
+      end
+    end
+
+    # Allow the component to access the identified_by methods from the connection
+    def respond_to_missing?(method_name, _include_private = false)
+      return false unless channel
+
+      channel.connection.identifiers.include?(method_name)
+    end
+
+    def method_missing(method_name, *, &)
+      channel.connection.public_send(method_name, *, &)
+    end
+
+    private
+
+    def stream_from(channel_name, callback = nil, coder: nil, &block)
+      channel.stream_from(channel_name, coder:) do |payload|
+        callback ||= block
+        callback.call(payload)
+
+        live_connection.broadcast_changeset
+      end
+    end
+
+    def prerender_container
+      @prerender_container ||= {}
+    end
+
+    def locals
+      identifiers = channel ? channel.connection.identifiers.to_a : []
+
+      (all_reactive_variables | (self.class.shared_variables || []) | identifiers).
+        to_h { |v| [v, public_send(v)] }.
+        merge(
+          component: self
+        )
+    end
+  end
+end

data/lib/live_cable/connection.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+module LiveCable
+  class Connection
+    attr_reader :session_id
+
+    SHARED_CONTAINER = '_shared'
+
+    def initialize(request)
+      @request = request
+      @session_id = SecureRandom.uuid
+      @containers = {} # @todo Use Hash.new with a proc to make a container / hash
+      @components = {}
+      @channels = {}
+    end
+
+    def get_component(id)
+      components[id]
+    end
+
+    def add_component(component)
+      component.live_connection = self
+      components[component.live_id] = component
+    end
+
+    def remove_component(component)
+      components.delete(component.live_id)
+      containers.delete(component.live_id)
+    end
+
+    def set_channel(component, channel)
+      @channels[component] = channel
+    end
+
+    def get_channel(component)
+      @channels[component]
+    end
+
+    def remove_channel(component)
+      @channels.delete(component)
+    end
+
+    def get(container_name, component, variable, initial_value)
+      containers[container_name] ||= Container.new
+      containers[container_name][variable] ||= process_initial_value(component, variable, initial_value)
+    end
+
+    def set(container_name, variable, value)
+      dirty(container_name, variable)
+
+      containers[container_name] ||= Container.new
+      containers[container_name][variable] = value
+    end
+
+    def receive(component, data)
+      check_csrf_token(data)
+      reset_changeset
+
+      return unless data['messages'].present?
+
+      data['messages'].each do |message|
+        action(component, message)
+      end
+
+      broadcast_changeset
+    end
+
+    def action(component, data)
+      params = parse_params(data)
+
+      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}"
+        end
+
+        method = component.method(action)
+
+        if method.arity.positive?
+          method.call(params)
+        else
+          method.call
+        end
+      end
+    rescue StandardError => e
+      handle_error(component, e)
+    end
+
+    def reactive(component, data)
+      unless component.all_reactive_variables.include?(data['name'].to_sym)
+        raise Error, "Invalid reactive variable: #{data['name']}"
+      end
+
+      component.public_send("#{data['name']}=", data['value'])
+    rescue StandardError => e
+      handle_error(component, e)
+    end
+
+    def channel_name
+      "live_#{session_id}"
+    end
+
+    def dirty(container_name, *variables)
+      containers[container_name] ||= Container.new
+      containers[container_name].mark_dirty(*variables)
+    end
+
+    def broadcast_changeset
+      # Use a copy of the components since new ones can get added while rendering
+      # and causes an issue here.
+      components.values.dup.each do |component|
+        container = containers[component.live_id]
+        if container&.changed?
+          component.render_broadcast
+
+          next
+        end
+
+        shared_changeset = containers[SHARED_CONTAINER]&.changeset || []
+
+        if (component.shared_reactive_variables || []).intersect?(shared_changeset)
+          component.render_broadcast
+        end
+      end
+    end
+
+    private
+
+    attr_reader :request
+
+    # @return [Hash<String, Container>]
+    attr_reader :containers
+
+    # @return [Hash<String, Component>]
+    attr_reader :components
+
+    def check_csrf_token(data)
+      session = request.session
+      return unless session[:_csrf_token]
+
+      token = data['_csrf_token']
+      unless csrf_checker.valid?(session, token)
+        raise LiveCable::Error, 'Invalid CSRF token'
+      end
+    end
+
+    def csrf_checker
+      @csrf_checker ||= LiveCable::CsrfChecker.new(request)
+    end
+
+    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 Error, "Initial value for \":#{variable}\" must be a proc or nil"
+      end
+    rescue StandardError => e
+      handle_error(component, e)
+    end
+
+    def parse_params(data)
+      params = data['params'] || ''
+
+      ActionController::Parameters.new(
+        ActionDispatch::ParamBuilder.from_pairs(
+          ActionDispatch::QueryParser.each_pair(params)
+        )
+      )
+    end
+
+    def reset_changeset
+      containers.each_value(&:reset_changeset)
+    end
+
+    def handle_error(component, error)
+      html = <<~HTML
+        <details>
+          <summary style="color: #f00; cursor: pointer">
+            <strong>#{component.class.name}</strong> - #{error.class.name}: #{error.message}
+          </summary>
+          <small>
+            <ol>
+              #{error.backtrace&.map { "<li>#{it}</li>" }&.join("\n")}
+            </ol>
+          </small>
+        </details>
+      HTML
+
+      component.broadcast(_refresh: html)
+    ensure
+      raise(error)
+    end
+  end
+end

data/lib/live_cable/container.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module LiveCable
+  # Storage for reactive variable values with automatic change tracking.
+  #
+  # A Container is a Hash subclass that stores the values of reactive variables
+  # for a single component instance. It automatically wraps supported types
+  # (Arrays, Hashes, ActiveRecord models) in Delegators that track mutations.
+  #
+  # @example Basic usage
+  #   container = Container.new
+  #   container[:username] = "john"           # Stored as-is
+  #   container[:tags] = ['ruby', 'rails']    # Wrapped in Delegator
+  #   container[:tags] << 'rspec'             # Automatically marks :tags as dirty
+  #
+  # Architecture:
+  # - Each component instance has its own Container (identified by live_id)
+  # - 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
+  #
+  # Change Tracking:
+  # 1. Value is stored via []=
+  # 2. If value is an Array/Hash/Model, it's wrapped in a Delegator
+  # 3. Delegator attaches observers to the value
+  # 4. When value is mutated, observers mark the variable as dirty
+  # 5. Component re-renders if changeset contains the variable
+  class Container < Hash
+    # @param args [Array] Arguments passed to Hash.new
+    def initialize(...)
+      super
+      @changeset = []
+    end
+
+    # Store a value in the container, automatically wrapping supported types
+    # in Delegators for change tracking.
+    #
+    # @param key [Symbol] The reactive variable name
+    # @param value [Object] The value to store
+    # @return [Object] The stored value (possibly wrapped in a Delegator)
+    #
+    # @example Storing different types
+    #   container[:count] = 0                    # Number - stored as-is
+    #   container[:tags] = ['ruby']              # Array - wrapped in Delegator
+    #   container[:user] = User.new              # ActiveRecord - wrapped in Delegator
+    def []=(key, value)
+      # ActiveRecord models get observers attached directly
+      if value.class < ModelObserver
+        value.add_live_cable_observer(observer, key)
+      end
+
+      # If value is already a Delegator, add observer and store as-is
+      if value.is_a?(Delegator)
+        value.add_live_cable_observer(observer, key)
+        super
+      else
+        # Wrap supported types in Delegators for change tracking
+        super(key, Delegator.create_if_supported(value, key, observer))
+      end
+    end
+
+    # Mark one or more variables as dirty (changed).
+    # Dirty variables will trigger a re-render of their component.
+    #
+    # @param variables [Array<Symbol>] Variable names to mark as dirty
+    # @return [void]
+    #
+    # @example
+    #   container.mark_dirty(:username, :email)
+    def mark_dirty(*variables)
+      @changeset |= variables # Union operator keeps values unique
+    end
+
+    # Returns the list of variables that have changed during this message cycle.
+    #
+    # @return [Array<Symbol>] List of dirty variable names
+    attr_reader :changeset
+
+    # Check if any variables have changed.
+    #
+    # @return [Boolean] true if changeset is not empty
+    def changed?
+      !@changeset.empty?
+    end
+
+    # Clear the changeset after broadcasting updates.
+    # Called by Connection after all components have been re-rendered.
+    #
+    # @return [void]
+    def reset_changeset
+      @changeset = []
+    end
+
+    # Get or create the observer for this container.
+    # Each container has exactly one observer instance.
+    #
+    # @return [LiveCable::Observer] The observer instance
+    def observer
+      @observer ||= Observer.new(self)
+    end
+  end
+end

data/lib/live_cable/csrf_checker.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module LiveCable
+  class CsrfChecker
+    include ActiveSupport::Configurable
+    include ActionController::RequestForgeryProtection
+
+    def initialize(request)
+      @request = request
+    end
+
+    def valid?(session, token)
+      valid_authenticity_token?(session, token)
+    end
+
+    private
+
+    attr_reader :request
+  end
+end

data/lib/live_cable/delegation/array.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module LiveCable
+  module Delegation
+    module Array
+      extend Methods
+      extend Enumerable
+
+      GETTER_METHODS = %i[
+        []
+        chunk
+        collect
+        compact
+        cycle
+        drop
+        drop_while
+        filter
+        find_all
+        first
+        flatten
+        grep
+        grep_v
+        group_by
+        last
+        map
+        reject
+        reverse
+        rotate
+        select
+        shuffle
+        slice
+        sort
+        sort_by
+        take
+        take_while
+        transpose
+        uniq
+        zip
+      ].freeze
+
+      MUTATIVE_METHODS = %i[
+        []=
+        <<
+        clear
+        compact!
+        concat
+        delete
+        delete_at
+        delete_if
+        fill
+        flatten!
+        insert
+        keep_if
+        map!
+        pop
+        push
+        reject!
+        replace
+        reverse!
+        rotate!
+        select!
+        shift
+        shuffle!
+        slice!
+        sort!
+        sort_by!
+        uniq!
+        unshift
+      ].freeze
+
+      decorate_getters GETTER_METHODS
+      decorate_mutators MUTATIVE_METHODS
+
+      def each(&)
+        __getobj__.each do |v|
+          yield create_delegator(v)
+        end
+      end
+    end
+  end
+end

data/lib/live_cable/delegation/hash.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module LiveCable
+  module Delegation
+    module Hash
+      extend Methods
+
+      MUTATIVE_METHODS = %i[
+        []=
+        clear
+        compact!
+        deep_merge!
+        deep_stringify_keys!
+        deep_transform_keys!
+        deep_transform_values!
+        delete
+        delete_if
+        except!
+        extract!
+        keep_if
+        merge!
+        rehash
+        reject!
+        reverse_merge!
+        select!
+        shift
+        stringify_keys!
+        symbolize_keys!
+        transform_keys!
+        transform_values!
+        update
+      ].freeze
+
+      decorate_getter :[]
+      decorate_mutators MUTATIVE_METHODS
+    end
+  end
+end