live_cable 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a08ab617cc974271c9f4b2784bb52ca53d1430942fd72e761fe52cd650a86141
-  data.tar.gz: abd1b26ca97b149de015b9fb7b9b457ff6b6f21e224a61318788876115fcd9d9
+  metadata.gz: 9eab70af0621e69a52c7eaccce2d76a400a8627223c6aa91525230d262179782
+  data.tar.gz: 1a6ca70d53e728fc4893607bc5de7ab12094bbdefb06d52cd2a83afefd653ac5
 SHA512:
-  metadata.gz: e3b932fcbdfcf3fb5d6b939320798eb151c82d0e6bc85c61c2452ff729233855b477752e10465c8098f4601651d04f9e67449293b9635cde3eefa47bde08733c
-  data.tar.gz: 6476ba238c1960655922da93588b175ed0468294364dd1252b05ad044eb26cb0d94360254581cb791ddc6def81155940c82d310835398b7c791b8cb3daf6884c
+  metadata.gz: b43cf0bd548271aeae7534a26d1d950266078f3f571165fb99d5daec8021d1c8af16b29f2b71866aa6030594b5e829ecc59bcf4186b4209666472f81d3b7c9bf
+  data.tar.gz: 3d7753820b0ff173ae72a210eb4ecfbf77704e1897a2ebf570c085e7bad6ec1a7531bb7138beb64cf0fadd2af39ee77cf6be0f0e493961d770cd11182e2d3a43

data/CHANGELOG.md

@@ -6,6 +6,104 @@ The Ruby gem (`live_cable`) and the npm package (`@isometriks/live_cable`) are
 released together and share a single version number. Entries below note which
 side of the pair a change affects when it isn't both.
 
+## 0.3.0 - 2026-09-26
+
+### Upgrading from 0.2
+
+Upgrade the gem and the npm package together. The 0.3 client no longer sends
+the `_csrf_token` field that the 0.2 gem checks on every message, so a newer
+client talking to an older gem has every action refused.
+
+If your `ApplicationCable::Connection` follows the 0.2 installation guide,
+delete both LiveCable lines from it. LiveCable now attaches `live_connection`
+to every connection itself.
+
+```ruby
+# app/channels/application_cable/connection.rb - delete these
+identified_by :live_connection
+
+def connect
+  self.live_connection = LiveCable::Connection.new(request)
+end
+```
+
+Delete them together. Without `identified_by` there is no `live_connection=`
+for `connect` to call and every handshake fails. Without the `connect` override
+the identifier shadows the `live_connection` LiveCable attaches with a nil one,
+and every subscribe fails with a `LiveCable::Error` that says so. Leaving both
+in place keeps working, at the cost described under *Changed*.
+
+### Fixed
+
+- **A message could be refused with no answer, leaving the component stuck in
+  its loading state.** `LiveChannel#receive` had no rescue of its own, so
+  anything raised before an action's own rescue — a component that failed to
+  subscribe, the CSRF check — went to ActionCable, which only logs it. The
+  client holds `live-loading` and `live-disable-with` until it hears back, so
+  the button stayed disabled until a reload. Every batch is now answered with a
+  `_refresh`, `_ack` or `_error`. A subscribe that fails at any point transmits
+  an `_error` too, and the client's unsubscribe then removes the half-built
+  component from the connection rather than leaving it for the next subscribe
+  to resurrect (gem).
+
+### Changed
+
+- `live_connection` is attached to every `ActionCable::Connection` by LiveCable
+  itself, so the connection no longer declares it. As an identifier, the
+  per-socket `LiveCable::Connection` became part of the connection's identity,
+  which `ActionCable.server.remote_connections` has to match in full, so an
+  application could never disconnect its users' sockets on sign-out. See
+  *Upgrading from 0.2* above (gem).
+
+### Removed
+
+- The per-message CSRF token check, and with it the `_csrf_token` field the
+  client sent with every batch. A WebSocket is protected at its handshake by
+  ActionCable's origin check and the `SameSite=Lax` session cookie, and the
+  check added nothing on top of those except a way to wedge a socket: it ran
+  against the session captured at the handshake, and a socket never sees
+  cookies set afterwards, so once the session's token rotated — Devise does
+  this on every sign-in — every message on that socket was refused until the
+  socket reconnected. A socket that outlives a sign-in is handled as for any
+  other channel, by the application disconnecting it; see the architecture
+  guide (gem + npm).
+
+## 0.2.1 - 2026-08-13
+
+### Removed
+
+- `Component#channel_name` and `Connection#channel_name`. A component no longer
+  subscribes to a stream of its own now that payloads are written straight to its
+  channel, so the name identified a stream nothing published to or read from.
+  Subscribing to external streams with `stream_from` is unaffected (gem).
+
+### Fixed
+
+- **The opening payload from `LiveChannel#subscribed` could be dropped.**
+  Payloads were published through the pubsub adapter, but ActionCable registers
+  `stream_from` asynchronously — so the initial render could be published before
+  the subscription it targets existed, and pubsub delivers only to subscribers
+  present at that moment, with no buffering or retry. The component was left
+  showing `data-live-status-value="disconnected"`, with no cached render on the
+  client for a Turbo reattach to replay, until some later action happened to
+  produce a refresh. When a subscribe render raised, the `_error` payload was
+  lost outright and the failure never surfaced in the browser at all. A
+  component's stream belongs to exactly one connection, so payloads are now
+  written straight to that connection rather than published, which removes the
+  race along with a pubsub round trip (gem).
+- **Components not reattaching after a Turbo Drive navigation.** Navigating to a
+  page containing a component that is already subscribed deliberately keeps the
+  existing subscription, so `LiveChannel#subscribed` does not run again and the
+  server sends nothing. The newly rendered element was left with its
+  server-rendered status of `disconnected` and never received the component's
+  current state. A reconnecting controller now re-syncs the subscription's status
+  and replays the last render into the new element (npm).
+- Building DOM from a server render used iterator helpers
+  (`childNodes.values().find(...)`), an ES2025 feature, which raised
+  `TypeError: ... .find is not a function` on runtimes that do not implement them
+  — Node 20 and earlier, and browsers older than Chrome 122 / Firefox 131 /
+  Safari 18.4. Rewritten with `Array.from` (npm).
+
 ## 0.2.0
 
 The gem and npm package versions are realigned in this release. The npm package

data/README.md

@@ -30,21 +30,19 @@ bundle install
 
 ## Configuration
 
-To use LiveCable, you need to set up your `ApplicationCable::Connection` to initialize a `LiveCable::Connection`.
-
-Add this to your `app/channels/application_cable/connection.rb`:
-
-```ruby
-module ApplicationCable
-  class Connection < ActionCable::Connection::Base
-    identified_by :live_connection
-
-    def connect
-      self.live_connection = LiveCable::Connection.new(self.request)
-    end
-  end
-end
-```
+There is nothing to configure on the cable side. LiveCable attaches itself to
+`ActionCable::Connection::Base`, so your `ApplicationCable::Connection` stays as
+it is, with whatever `identified_by` it declares or none at all. LiveCable needs
+no identifiers of its own.
+
+If you followed an earlier version of this guide, remove the
+`identified_by :live_connection` line and the `connect` override that went with
+it. Remove both at once, since either one on its own breaks every connection.
+Together they keep working, but they make a per-socket object part of the
+connection's identity, which stops `ActionCable.server.remote_connections` from
+ever finding your users' sockets. See the
+[architecture guide](https://livecable.io/guide/architecture#sign-in-and-sign-out)
+for what to do about sockets when a user signs in or out.
 
 ## JavaScript Setup
 

data/app/assets/javascript/controllers/live_controller.js

@@ -166,20 +166,17 @@ export default class extends Controller {
     }
   }
 
+  // Batch any pending debounced messages ahead of this one so they are sent
+  // in the order they were triggered
   #flushDebounced(message) {
     const messages = [message]
 
-    // Add all pending debounced messages to be sent immediately
     for (const [source, { timeout, message: debouncedMessage }] of this.#debounces) {
       clearTimeout(timeout)
       messages.unshift(debouncedMessage)
     }
     this.#debounces.clear()
 
-    return { messages, _csrf_token: this.#csrfToken }
-  }
-
-  get #csrfToken() {
-    return document.querySelector("meta[name='csrf-token']")?.getAttribute("content")
+    return { messages }
   }
 }

data/app/assets/javascript/subscriptions.js

@@ -34,8 +34,7 @@ function createDOMFromHTML(html) {
   template.innerHTML = html
 
   // Find a node that isn't a comment
-  const node = template.content.childNodes
-    .values()
+  const node = Array.from(template.content.childNodes)
     .find(n => n.nodeName !== '#comment')
 
   if (node) {
@@ -230,6 +229,15 @@ class ComponentState {
     return this.#element
   }
 
+  /**
+   * Whether a render has been received and cached, and can therefore be
+   * replayed into a freshly attached element.
+   * @returns {boolean}
+   */
+  get hasRender() {
+    return this.#lastTemplate !== null && Boolean(this.#partsByTemplate[this.#lastTemplate])
+  }
+
   /**
    * Create a DOM element from stored state.
    * @param {Object} refresh - Optional refresh data to update state
@@ -345,12 +353,44 @@ class Subscription {
 
   /**
    * Update the controller reference.
-   * Called when a Stimulus controller reconnects to an existing subscription.
+   * Called when a Stimulus controller reconnects to an existing subscription —
+   * most importantly after a Turbo Drive navigation to a page that contains the
+   * same component, where prune() deliberately keeps the subscription alive.
+   *
+   * In that case the ActionCable subscription is never recreated, so
+   * LiveChannel#subscribed does not run again and the server sends nothing.
+   * Without re-syncing here, the newly rendered element keeps the
+   * server-rendered status of "disconnected" forever and never receives the
+   * component's current state.
    *
    * @param {Object} controller - Stimulus controller instance
    */
   set controller(controller) {
+    const previous = this.#controller
+
     this.#controller = controller
+    this.#componentState.element = controller.element
+
+    if (previous && previous !== controller) {
+      this.#reattach()
+    }
+  }
+
+  /**
+   * Bring a freshly connected controller up to date with state this
+   * subscription already holds.
+   * @private
+   */
+  #reattach() {
+    if (this.#currentStatus) {
+      this.#controller.statusValue = this.#currentStatus
+    }
+
+    // Replay the last render into the new element. The server-side component
+    // is the same instance, so the cached parts are its current state.
+    if (this.#componentState.hasRender) {
+      this.#handleRefresh(null)
+    }
   }
 
   /**

data/app/channels/live_channel.rb

@@ -1,37 +1,46 @@
 # frozen_string_literal: true
 
 class LiveChannel < ActionCable::Channel::Base
-  def subscribed
-    instance = nil
+  # Private so ActionCable does not expose it as an action the client can call
+  delegate :live_connection, to: :connection, private: true
+
+  before_subscribe :ensure_live_connection
 
-    # Build live_id from component and id params
+  # @component is assigned as soon as the component is known, so a failure
+  # later in here still leaves it for unsubscribed to clean up
+  def subscribed
     live_id = "#{params[:component]}/#{params[:id]}"
 
-    instance = live_connection.get_component(live_id)
-    rendered = instance.present?
+    @component = live_connection.get_component(live_id)
+    rendered = component.present?
 
-    unless instance
-      instance = LiveCable.instance_from_string(params[:component], params[:id])
-      live_connection.add_component(instance)
-      instance.defaults = params[:defaults]
-      instance.apply_defaults
+    unless component
+      @component = LiveCable.instance_from_string(params[:component], params[:id])
+      live_connection.add_component(component)
+      component.defaults = params[:defaults]
+      component.apply_defaults
     end
 
-    instance.connect(self)
+    component.connect(self)
 
     if rendered
-      instance.broadcast_subscribe
+      component.broadcast_subscribe
     else
-      instance.broadcast_render
+      component.broadcast_render
     end
-
-    @component = instance
   rescue StandardError => error
-    live_connection.handle_error(instance, error) if instance
+    live_connection.handle_error(component, error, channel: self)
   end
 
+  # Every batch must be answered - the client holds its loading state until a
+  # _refresh, _ack or _error arrives - so nothing raised here may escape to
+  # ActionCable, which would only log it and leave the client hanging.
   def receive(data)
+    raise LiveCable::Error, 'No component was built, so this subscription cannot receive messages' unless component
+
     live_connection.receive(component, data)
+  rescue StandardError => error
+    live_connection.handle_error(component, error, channel: self)
   end
 
   def unsubscribed
@@ -41,8 +50,22 @@ class LiveChannel < ActionCable::Channel::Base
     @component = nil
   end
 
+  # Exposes #transmit, which ActionCable keeps private to the channel.
+  def broadcast(data)
+    transmit(data)
+  end
+
   private
 
   # @return [LiveCable::Component, nil]
   attr_reader :component
+
+  def ensure_live_connection
+    return if live_connection
+
+    raise LiveCable::Error, "#{connection.class.name} still declares identified_by :live_connection, " \
+                            'which shadows the live_connection LiveCable attaches and leaves it nil. ' \
+                            'Remove that line and the connect override that set it; see the 0.3.0 ' \
+                            'upgrade notes.'
+  end
 end

data/lib/live_cable/action_cable_connection.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module LiveCable
+  # Mixed into ActionCable::Connection::Base by the engine, so every socket
+  # carries its LiveCable::Connection without the application declaring
+  # anything.
+  #
+  # Deliberately not an identifier. The identified_by values make up a
+  # connection's identity, which remote_connections.where(...) has to match in
+  # full to disconnect a socket, and a per-socket object can never be named
+  # there. Keeping LiveCable off the identifiers leaves that mechanism working
+  # for the application's own, such as current_user.
+  module ActionCableConnection
+    # @return [LiveCable::Connection]
+    def live_connection
+      @live_connection ||= LiveCable::Connection.new(request)
+    end
+  end
+end

data/lib/live_cable/component/broadcasting.rb

@@ -5,8 +5,10 @@ module LiveCable
     module Broadcasting
       extend ActiveSupport::Concern
 
+      # Nil until the component's own controller subscribes; children rendered
+      # by a parent have no channel to deliver to yet.
       def broadcast(data)
-        ActionCable.server.broadcast(channel_name, data)
+        channel&.broadcast(data)
       end
 
       def broadcast_subscribe

data/lib/live_cable/component/identification.rb

@@ -22,10 +22,6 @@ module LiveCable
       def live_id
         self.class.component_id(id)
       end
-
-      def channel_name
-        "#{live_connection.channel_name}/#{live_id}"
-      end
     end
   end
 end

data/lib/live_cable/component/lifecycle.rb

@@ -23,7 +23,6 @@ module LiveCable
       def connect(channel)
         run_callbacks :connect do
           @channel = channel
-          start_stream
           @subscribed = true
         end
       end

data/lib/live_cable/component/streaming.rb

@@ -7,14 +7,7 @@ module LiveCable
 
       private
 
-      def start_stream
-        channel.stream_from(channel_name)
-      end
-
       def stop_stream
-        channel.stop_stream_from(channel_name)
-
-        # Stop all additional streams started via stream_from
         additional_streams.each do |stream_name|
           channel.stop_stream_from(stream_name)
         end

data/lib/live_cable/connection/error_handling.rb

@@ -5,11 +5,35 @@ module LiveCable
     module ErrorHandling
       extend ActiveSupport::Concern
 
-      def handle_error(component, error)
+      # Report an error and replace the component on the client with an
+      # error box.
+      #
+      # @param component [LiveCable::Component, nil] nil when the failure
+      #   happened before a component existed, such as a subscribe that could
+      #   not build one
+      # @param error [Exception]
+      # @param channel [#broadcast, nil] the channel to deliver the _error
+      #   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)
 
+        html = error_html(component, error)
+
+        # Destroy children first so their _status:destroy messages arrive before _error
+        component&.rendered_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)
+      end
+
+      private
+
+      def error_html(component, error)
         if LiveCable.configuration.verbose_errors
-          summary = "#{component.class.name} - #{error.class.name}: #{ERB::Util.html_escape(error.message)}"
+          name = component ? component.class.name : 'LiveCable'
+          summary = "#{name} - #{error.class.name}: #{ERB::Util.html_escape(error.message)}"
           backtrace_html = <<~HTML
             <small>
               <ol>
@@ -21,19 +45,12 @@ module LiveCable
           summary = 'An error occurred'
         end
 
-        html = <<~HTML
+        <<~HTML
           <details>
             <summary style="color: #f00; cursor: pointer">#{summary}</summary>
             #{backtrace_html}
           </details>
         HTML
-
-        # Destroy children first so their _status:destroy messages arrive before _error
-        component.rendered_children.each(&:destroy)
-
-        # Broadcast the error - JS replaces the DOM and calls unsubscribe(),
-        # which triggers LiveChannel#unsubscribed -> component.disconnect for server cleanup
-        component.broadcast(_error: html)
       end
     end
   end

data/lib/live_cable/connection/messaging.rb

@@ -6,7 +6,6 @@ module LiveCable
       extend ActiveSupport::Concern
 
       def receive(component, data)
-        check_csrf_token(data)
         reset_changeset
 
         return unless data['messages'].present?
@@ -72,20 +71,6 @@ module LiveCable
 
       private
 
-      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 parse_params(data)
         params = data['params'] || ''
 

data/lib/live_cable/connection.rb

@@ -3,7 +3,6 @@
 module LiveCable
   class Connection
     include ComponentManagement
-    include ChannelManagement
     include StateManagement
     include Messaging
     include Broadcasting
@@ -13,17 +12,12 @@ module LiveCable
 
     def initialize(request)
       @request = request
-      @session_id = SecureRandom.uuid
       @containers = Hash.new { |hash, key| hash[key] = Container.new }
       @components = {}
-      @channels = {}
     end
 
     private
 
-    # @return [String]
-    attr_reader :session_id
-
     # @return [ActionDispatch::Request]
     attr_reader :request
 

data/lib/live_cable/engine.rb

@@ -26,6 +26,12 @@ module LiveCable
       ActionView::Template.register_template_handler(:'live.erb', Rendering::Handler)
     end
 
+    initializer 'live_cable.action_cable' do
+      ActiveSupport.on_load(:action_cable_connection) do
+        include LiveCable::ActionCableConnection
+      end
+    end
+
     initializer 'live_cable.active_record' do
       ActiveSupport.on_load :active_record do
         include ModelObserver

data/lib/live_cable/testing/test_channel.rb

@@ -3,19 +3,28 @@
 module LiveCable
   module Testing
     # Stand-in for an ActionCable channel. Records streams started via
-    # stream_from so tests can trigger their callbacks with receive_stream.
+    # stream_from so tests can trigger their callbacks with receive_stream,
+    # and payloads sent by components.
     class TestChannel
       # @return [Hash<String, Hash>] Stream name => { coder:, callback: }
       attr_reader :streams
 
+      # @return [Array<Hash>] Payloads sent by components through this channel
+      attr_reader :transmissions
+
       # @return [LiveCable::Testing::TestCableConnection]
       attr_reader :connection
 
       def initialize(identifiers = {})
         @streams = {}
+        @transmissions = []
         @connection = TestCableConnection.new(identifiers)
       end
 
+      def broadcast(data)
+        @transmissions << data
+      end
+
       def stream_from(name, coder: nil, &block)
         @streams[name] = { coder:, callback: block }
       end

data/lib/live_cable/testing/test_component.rb

@@ -18,9 +18,6 @@ module LiveCable
         super(component)
         @connection = connection
         @channel = channel
-        @broadcasts = []
-
-        capture_broadcasts(component)
       end
 
       # @return [LiveCable::Component] The underlying component instance
@@ -74,15 +71,15 @@ module LiveCable
       #   (e.g. :_refresh, :_ack, :_error, :_status)
       # @return [Array<Hash>]
       def broadcasts(key = nil)
-        return @broadcasts.dup unless key
+        return channel.transmissions.dup unless key
 
-        @broadcasts.select { |broadcast| broadcast.key?(key) }
+        channel.transmissions.select { |broadcast| broadcast.key?(key) }
       end
 
       # Forget previously captured broadcasts. Useful after mounting, to
       # assert on the effects of a single action.
       def clear_broadcasts
-        @broadcasts.clear
+        channel.transmissions.clear
       end
 
       # All events the component has dispatched via dispatch_event, in
@@ -134,14 +131,6 @@ module LiveCable
       def receive_message(message)
         connection.receive(component, { 'messages' => [message] })
       end
-
-      def capture_broadcasts(component)
-        captured = @broadcasts
-
-        component.define_singleton_method(:broadcast) do |data|
-          captured << data
-        end
-      end
     end
   end
 end

data/lib/live_cable/testing.rb

@@ -68,12 +68,11 @@ module LiveCable
     def build_test_connection(raise_errors:)
       require 'action_dispatch/testing/test_request'
 
-      # An empty session skips the CSRF check, like a session-less request
-      request = ActionDispatch::TestRequest.create('rack.session' => {})
+      request = ActionDispatch::TestRequest.create
       connection = LiveCable::Connection.new(request)
 
       if raise_errors
-        def connection.handle_error(_component, error)
+        def connection.handle_error(_component, error, **)
           raise error
         end
       end

data/lib/live_cable/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LiveCable
-  VERSION = '0.2.0'
+  VERSION = '0.3.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: live_cable
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Craig Blanchette
@@ -133,6 +133,7 @@ files:
 - lib/generators/live_cable/component/templates/view.html.live.erb.tt
 - lib/live.rb
 - lib/live_cable.rb
+- lib/live_cable/action_cable_connection.rb
 - lib/live_cable/component.rb
 - lib/live_cable/component/broadcasting.rb
 - lib/live_cable/component/events.rb
@@ -145,13 +146,11 @@ files:
 - lib/live_cable/configuration.rb
 - lib/live_cable/connection.rb
 - lib/live_cable/connection/broadcasting.rb
-- lib/live_cable/connection/channel_management.rb
 - lib/live_cable/connection/component_management.rb
 - lib/live_cable/connection/error_handling.rb
 - lib/live_cable/connection/messaging.rb
 - lib/live_cable/connection/state_management.rb
 - lib/live_cable/container.rb
-- lib/live_cable/csrf_checker.rb
 - lib/live_cable/delegation/array.rb
 - lib/live_cable/delegation/hash.rb
 - lib/live_cable/delegation/methods.rb

data/lib/live_cable/connection/channel_management.rb

@@ -1,13 +0,0 @@
-# frozen_string_literal: true
-
-module LiveCable
-  class Connection
-    module ChannelManagement
-      extend ActiveSupport::Concern
-
-      def channel_name
-        "live_#{session_id}"
-      end
-    end
-  end
-end

data/lib/live_cable/csrf_checker.rb

@@ -1,20 +0,0 @@
-# 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