live_cable 0.3.0 → 0.4.0

data/app/assets/javascript/subscriptions.js

@@ -45,6 +45,18 @@ function createDOMFromHTML(html) {
   return template.content.childNodes[0]
 }
 
+const TEXT_INPUT_TYPES = new Set(['text', 'search', 'email', 'url', 'tel', 'password', 'number'])
+
+/**
+ * Whether the user types the element's value.
+ * @param {Element} element
+ * @returns {boolean}
+ */
+function isTextField(element) {
+  return element instanceof HTMLTextAreaElement ||
+    (element instanceof HTMLInputElement && TEXT_INPUT_TYPES.has(element.type))
+}
+
 /**
  * Manages all LiveCable subscriptions across the application.
  * Ensures that each component (identified by liveId) has at most one
@@ -55,6 +67,8 @@ class SubscriptionManager {
   #subscriptions = {}
   /** @type {Object.<string, ComponentState>} */
   #componentStates = {}
+  /** @type {string|null} - Digest from live_cable_identity_tag the socket was opened under */
+  #identity = null
 
   /**
    * Register a component state before subscription is created.
@@ -75,18 +89,24 @@ class SubscriptionManager {
   /**
    * Subscribe to or reconnect to a LiveCable component.
    * If a subscription already exists for this liveId, updates the controller
-   * reference instead of creating a new subscription.
+   * reference instead of creating a new subscription - unless the element
+   * brings different defaults, in which case the old subscription is replaced
+   * so the server builds the component again from them.
    * If a ComponentState exists and the controller element matches, reuses it.
    *
    * @param {string} id - Raw ID for the component (e.g., "room-1")
    * @param {string} component - Component class name (e.g., "chat/chat_room")
-   * @param {Object} defaults - Default values for reactive variables
+   * @param {string} defaults - Opaque signed defaults blob, forwarded to the server
    * @param {Object} controller - Stimulus controller instance
    * @returns {Subscription} The subscription instance
    */
   subscribe(id, component, defaults, controller) {
     const liveId = `${component}/${id}`
 
+    if (this.#subscriptions[liveId] && this.#defaultsChanged(this.#subscriptions[liveId], defaults)) {
+      this.#subscriptions[liveId].unsubscribe()
+    }
+
     if (!this.#subscriptions[liveId]) {
       const componentState = this.#componentStates[liveId]
 
@@ -107,6 +127,23 @@ class SubscriptionManager {
     return this.#subscriptions[liveId]
   }
 
+  /**
+   * Only a page rendered over HTTP carries a defaults blob; an element rendered
+   * over the socket has none and says nothing about them. Signing is
+   * deterministic, so the same defaults always produce the same blob. A Turbo
+   * preview shows a cached copy of the page, whose blob may be stale; the
+   * page itself follows it.
+   *
+   * @param {Subscription} subscription
+   * @param {string} defaults
+   * @returns {boolean}
+   */
+  #defaultsChanged(subscription, defaults) {
+    return Boolean(defaults) &&
+      defaults !== subscription.defaults &&
+      !document.documentElement.hasAttribute('data-turbo-preview')
+  }
+
   /**
    * Remove a subscription from the manager.
    * Called when the server sends a 'destroy' status, indicating the
@@ -118,6 +155,38 @@ class SubscriptionManager {
     delete this.#subscriptions[liveId]
   }
 
+  /**
+   * Reopen the socket when the page was rendered for someone other than the
+   * socket was opened for.
+   *
+   * A socket is identified once, at its handshake, and Turbo keeps it open
+   * across a sign-in, sign-out or impersonation, so its components would
+   * carry on as the previous identity. The live_cable_identity_tag meta tag
+   * carries a digest of who each page was rendered for; Turbo merges the new
+   * page's head before turbo:before-render, so this runs before the new
+   * body's components subscribe. Reopening closes the socket, the server
+   * drops its components, and they resubscribe on the new socket as the new
+   * session. A page without the tag, and a Turbo preview of a cached page,
+   * say nothing.
+   */
+  syncIdentity() {
+    if (document.documentElement.hasAttribute('data-turbo-preview')) {
+      return
+    }
+
+    const identity = document.head.querySelector('meta[name="live-cable-identity"]')?.content
+
+    if (!identity) {
+      return
+    }
+
+    if (this.#identity && identity !== this.#identity && consumer.connection.isActive()) {
+      consumer.connection.reopen()
+    }
+
+    this.#identity = identity
+  }
+
   /**
    * Unsubscribe components not present in the new page body.
    * Called before Turbo Drive renders a new page so that only components
@@ -134,6 +203,12 @@ class SubscriptionManager {
   prune(newBody) {
     const newLiveIds = this.#extractLiveIds(newBody)
 
+    // Inline children are prerendered without a live id, but a kept component
+    // rebuilds them from their state; the set grows to take in grandchildren
+    newLiveIds.forEach(liveId => {
+      this.getComponentState(liveId)?.childLiveIds.forEach(childId => newLiveIds.add(childId))
+    })
+
     Object.entries(this.#subscriptions).forEach(([liveId, subscription]) => {
       if (!newLiveIds.has(liveId)) {
         subscription.unsubscribe()
@@ -198,6 +273,8 @@ class ComponentState {
   #lastTemplate
   /** @type {HTMLElement} - The DOM element for this component */
   #element
+  /** @type {number} */
+  #renderCount = 0
 
   /**
    * Creates component state from initial render data.
@@ -238,6 +315,24 @@ class ComponentState {
     return this.#lastTemplate !== null && Boolean(this.#partsByTemplate[this.#lastTemplate])
   }
 
+  /**
+   * How many renders have been stored, counting those that arrived in a
+   * parent's refresh.
+   * @returns {number}
+   */
+  get renderCount() {
+    return this.#renderCount
+  }
+
+  /**
+   * Live ids of the child components placed in the last render.
+   * @returns {string[]}
+   */
+  get childLiveIds() {
+    const html = (this.#partsByTemplate[this.#lastTemplate] ?? []).join('')
+    return Array.from(html.matchAll(/<LiveCable child-live-id="([^"]+)"/g), ([, liveId]) => liveId)
+  }
+
   /**
    * Create a DOM element from stored state.
    * @param {Object} refresh - Optional refresh data to update state
@@ -251,6 +346,7 @@ class ComponentState {
       return this.#buildRefreshDOM(html)
     }
 
+    this.#renderCount++
     const [template, parts] = [refresh['h'], refresh['p']]
 
     // Use a default template ID for backward compatibility
@@ -302,7 +398,7 @@ class Subscription {
   #id
   /** @type {string} */
   #component
-  /** @type {Object} */
+  /** @type {string} */
   #defaults
   /** @type {Object|null} */
   #controller
@@ -312,12 +408,18 @@ class Subscription {
   #subscription
   /** @type {string|null} */
   #currentStatus = null
+  /** @type {boolean} - Whether the server has confirmed this subscription on the current socket */
+  #confirmed = false
+  /** @type {Array<Object>} - Messages held until the subscription is confirmed */
+  #pending = []
+  /** @type {number} - The render count when the first in-flight message was sent */
+  #renderCountAtSend = 0
   /**
    * Creates a new subscription to a LiveCable component.
    *
    * @param {string} id - Raw ID for the component (e.g., "room-1")
    * @param {string} component - Component class name (e.g., "chat/chat_room")
-   * @param {Object} defaults - Default values for reactive variables
+   * @param {string} defaults - Opaque signed defaults blob, forwarded to the server
    * @param {Object} controller - Stimulus controller instance
    * @param {ComponentState} [existingState] - Optional existing component state to reuse
    */
@@ -343,6 +445,14 @@ class Subscription {
     this.#subscribe()
   }
 
+  /**
+   * The signed defaults blob this subscription was created with.
+   * @returns {string}
+   */
+  get defaults() {
+    return this.#defaults
+  }
+
   /**
    * Get the component state.
    * @returns {ComponentState}
@@ -394,12 +504,48 @@ class Subscription {
   }
 
   /**
-   * Send a message to the server through the ActionCable subscription.
+   * Send a message to the server, or hold it until the subscription is
+   * confirmed on an open socket.
+   *
+   * ActionCable drops a message sent while its socket is closed - after a
+   * laptop wakes, a network blip, a deploy - and one sent after the socket
+   * reopens but before the re-subscribe is confirmed can reach the server
+   * before the subscription exists there, which drops it too. Either way the
+   * component would wait in its loading state for a reply that is never
+   * coming. Held messages go out, in order, once the server confirms the
+   * subscription.
    *
    * @param {Object} message - Message to send (e.g., action calls, reactive updates)
    */
   send(message) {
-    this.#subscription.send(message)
+    if (this.#controller?.inFlight === 1) {
+      this.#renderCountAtSend = this.#componentState.renderCount
+    }
+
+    if (!this.#confirmed || !this.#subscription.send(message)) {
+      this.#pending.push(message)
+    }
+  }
+
+  /**
+   * How many messages are waiting for a connection.
+   * @returns {number}
+   */
+  get pendingCount() {
+    return this.#pending.length
+  }
+
+  /**
+   * Drop any messages still waiting for a connection. Called when the loading
+   * state gives up on them, so a message the page has said didn't go through
+   * can't then go through after a reconnect.
+   *
+   * @returns {number} How many messages were dropped
+   */
+  discardPending() {
+    const count = this.#pending.length
+    this.#pending = []
+    return count
   }
 
   /**
@@ -424,10 +570,57 @@ class Subscription {
       component: this.#component,
       defaults: this.#defaults,
     }, {
+      connected: this.#connected,
+      disconnected: this.#disconnected,
       received: this.#received,
     })
   }
 
+  /**
+   * The server confirmed the subscription - on first connect, or again after
+   * a reconnect. Anything held while it wasn't goes out now.
+   * @private
+   */
+  #connected = () => {
+    this.#confirmed = true
+    // ActionCable can replace a stale socket without calling disconnected
+    this.#settleLostMessages()
+
+    while (this.#pending.length > 0) {
+      // The socket closed again mid-flush; the next confirmation resumes it
+      if (!this.#subscription.send(this.#pending[0])) {
+        this.#confirmed = false
+        break
+      }
+
+      this.#pending.shift()
+    }
+  }
+
+  /**
+   * The socket closed. ActionCable reconnects and re-subscribes by itself;
+   * until it has, sends are held and the component says so.
+   * @private
+   */
+  #disconnected = () => {
+    this.#confirmed = false
+    this.#settleLostMessages()
+    this.#handleStatus('disconnected')
+  }
+
+  /**
+   * End the loading state of messages sent on a socket that has since
+   * closed - their replies will never arrive. Held messages still will.
+   * @private
+   */
+  #settleLostMessages() {
+    const lost = (this.#controller?.inFlight ?? 0) - this.#pending.length
+
+    for (let i = 0; i < lost; i++) {
+      this.#controller.finishLoading()
+    }
+  }
+
   /**
    * Handle incoming messages from the server.
    * Processes status updates and DOM refreshes.
@@ -436,21 +629,34 @@ class Subscription {
    * @param {string} [data._status] - Status update (e.g., 'subscribed', 'destroy')
    * @param {string} [data._refresh] - HTML to morph into the DOM
    * @param {string} [data._error] - Raw error HTML to replace the component with
-   * @param {boolean} [data._ack] - Acknowledgement that a message was processed
-   *   without producing a re-render; clears the loading state
+   * @param {boolean} [data._reply] - Whether a _refresh answers this
+   *   component's own message; absent from servers before 0.4.1, whose
+   *   refreshes all count as replies
+   * @param {boolean} [data._subscribed] - Marks the frame the server sends
+   *   when it (re)subscribes the component
+   * @param {boolean} [data._ack] - Answers a message when the component's own
+   *   re-render didn't: nothing changed, or its render rode in its parent's
+   *   refresh; clears the loading state
    * @param {Array} [data._events] - Events to dispatch as CustomEvents; when
    *   attached to a _refresh they fire after the DOM has been morphed
    * @private
    */
   #received = (data) => {
+    if (data['_subscribed']) {
+      this.#settleLostMessages()
+    }
+
     if (data['_status']) {
       this.#handleStatus(data['_status'])
     } else if (data['_refresh']) {
-      this.#handleRefresh(data['_refresh'])
+      this.#handleRefresh(data['_refresh'], { reply: !('_reply' in data) || data['_reply'] === true })
     } else if (data['_error']) {
       this.#handleError(data['_error'])
     } else if (data['_ack']) {
-      this.#controller?.finishLoading()
+      // Pending elements skipped the renders that came while they waited
+      if (this.#controller?.finishLoading() && this.#componentState.renderCount !== this.#renderCountAtSend) {
+        this.#handleRefresh(null)
+      }
     }
 
     // Dispatch after the branch above so events attached to a refresh fire
@@ -509,6 +715,8 @@ class Subscription {
 
     // Handle destroy status - permanently remove this subscription
     if (status === 'destroy') {
+      // Replies still on their way go to a subscription that no longer exists
+      this.#controller?.resetLoading()
       this.unsubscribe()
     }
   }
@@ -517,9 +725,12 @@ class Subscription {
    * Handle DOM refreshes from the server.
    * Updates the DOM using morphdom.
    * @param {Object} refresh - Refresh data from the server
+   * @param {Object} [options]
+   * @param {boolean} [options.reply] - Whether the refresh answers this
+   *   component's own message, which ends its loading state
    * @private
    */
-  #handleRefresh(refresh) {
+  #handleRefresh(refresh, { reply = false } = {}) {
     // If we're getting a refresh we must be connected
     this.#handleStatus('subscribed')
 
@@ -528,15 +739,24 @@ class Subscription {
       return
     }
 
+    // A focused field whose form or trigger awaits a reply takes that reply's
+    // value like any other; read before the restore below unmarks it
+    const focused = document.activeElement
+    const focusedAwaitsReply = Boolean(focused?.closest('[live-loading]:not([data-live-id-value])'))
+
     // Restore live-loading / live-disable-with state before morphing so the
     // morph applies the server-rendered truth on top of the original DOM.
-    // With multiple messages in flight this only restores once the last
-    // response arrives - until then the morph below preserves the pending
-    // elements so live-disable-with buttons can't be clicked early.
-    this.#controller.finishLoading()
+    // Only replies count, and with multiple messages in flight this only
+    // restores once the last one arrives - until then the morph below
+    // preserves the pending elements so live-disable-with buttons can't be
+    // clicked early.
+    if (reply) {
+      this.#controller.finishLoading()
+    }
 
     const rootElement = this.#controller.element
     const stillLoading = this.#controller.isLoading
+    const childResults = refresh?.c || {}
 
     const refreshDOM = this.#buildRefreshDOM(refresh)
 
@@ -544,6 +764,8 @@ class Subscription {
       refreshDOM.setAttribute('live-loading', '')
     }
 
+    let keepFocusedValue = false
+
     morphdom(rootElement, refreshDOM, {
       // Preserve elements marked with live-ignore attribute
       onBeforeElUpdated(fromEl, toEl) {
@@ -561,6 +783,39 @@ class Subscription {
           return false
         }
 
+        // A nested component's pending elements wait for its own reply,
+        // unless this refresh carries its render
+        if (fromEl.hasAttribute('live-loading') && !fromEl.hasAttribute('data-live-id-value')) {
+          const owner = fromEl.closest('[data-live-id-value]')
+
+          if (owner && owner !== rootElement) {
+            const liveId = `${owner.getAttribute('data-live-component-value')}/${owner.getAttribute('data-live-id-value')}`
+
+            if (!(liveId in childResults)) {
+              return false
+            }
+          }
+        }
+
+        // defaultValue is what the server last rendered for the field
+        if (fromEl === focused) {
+          keepFocusedValue = !focusedAwaitsReply && isTextField(fromEl) && fromEl.defaultValue === toEl.defaultValue
+        }
+
+        return true
+      },
+      // Skipping its children skips morphdom's value sync, so the focused
+      // field keeps what the user typed
+      onBeforeElChildrenUpdated(fromEl, toEl) {
+        if (keepFocusedValue && fromEl === focused) {
+          return false
+        }
+
+        // morphdom updates a textarea's text node, which an empty one lacks
+        if (fromEl instanceof HTMLTextAreaElement && fromEl.defaultValue !== toEl.defaultValue) {
+          fromEl.defaultValue = toEl.defaultValue
+        }
+
         return true
       },
       // Use stable keys for better morphing performance and state preservation
@@ -611,24 +866,39 @@ class Subscription {
 
     // Replace Child Components
     const childResults = refresh?.c || {}
-    rootNode.querySelectorAll('LiveCable').forEach(component => {
+    const placeholders = [...rootNode.querySelectorAll('LiveCable')]
+    const replaced = new Set()
+
+    while (placeholders.length > 0) {
+      const component = placeholders.shift()
       const liveId = component.getAttribute('child-live-id')
       const childResult = childResults[liveId]
 
+      if (replaced.has(liveId)) {
+        console.error(`[LiveCable] ${liveId} is rendered more than once in a single refresh`)
+        component.remove()
+        continue
+      }
+
+      replaced.add(liveId)
+
       const componentState = subscriptionManager.getComponentState(liveId)
+      let childElement
 
       if (componentState) {
         // ComponentState already exists (either in subscription or standalone)
-        component.replaceWith(
-          componentState.createRefresh(childResult)
-        )
+        childElement = (childResult || componentState.hasRender)
+          ? componentState.createRefresh(childResult)
+          : document.createTextNode('')
       } else {
         // No state exists yet - create ComponentState
-        const childElement = this.#buildChildElement(childResult)
+        childElement = this.#buildChildElement(childResult)
         subscriptionManager.registerComponent(liveId, childElement, childResult)
-        component.replaceWith(childElement)
       }
-    })
+
+      component.replaceWith(childElement)
+      placeholders.push(...(childElement.querySelectorAll?.('LiveCable') ?? []))
+    }
 
     return rootNode
   }

data/app/channels/live_channel.rb

@@ -6,48 +6,70 @@ class LiveChannel < ActionCable::Channel::Base
 
   before_subscribe :ensure_live_connection
 
+  # Each entry point below runs as its own job on ActionCable's worker pool,
+  # so each holds the connection's lock for the whole of its work - see
+  # LiveCable::Connection#synchronize.
+
   # @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]}"
-
-    @component = live_connection.get_component(live_id)
-    rendered = component.present?
-
-    unless component
-      @component = LiveCable.instance_from_string(params[:component], params[:id])
-      live_connection.add_component(component)
-      component.defaults = params[:defaults]
-      component.apply_defaults
-    end
-
-    component.connect(self)
-
-    if rendered
-      component.broadcast_subscribe
-    else
-      component.broadcast_render
+    live_connection.synchronize do
+      live_id = "#{params[:component]}/#{params[:id]}"
+
+      @component = live_connection.get_component(live_id)
+
+      # The client replaces a subscription, to send new defaults, by
+      # unsubscribing first, but ActionCable may run the two out of order
+      if component&.subscribed?
+        component.disconnect
+        @component = nil
+      end
+
+      rendered = component.present?
+
+      unless component
+        @component = LiveCable.instance_from_string(params[:component], params[:id])
+        live_connection.add_component(component)
+        # Defaults round-trip through the client, so verify the signed blob and
+        # bind it to this live_id before trusting it - otherwise a tampered value
+        # could set non-writable reactive variables at subscribe time.
+        component.defaults = LiveCable::DefaultsSigner.verify(params[:defaults], live_id)
+        component.apply_defaults
+      end
+
+      component.connect(self)
+
+      if rendered
+        component.broadcast_subscribe
+      else
+        component.broadcast_render(subscribed: true)
+      end
+    rescue StandardError => error
+      live_connection.handle_error(component, error, channel: self)
     end
-  rescue StandardError => error
-    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.
+  # Every batch must be answered - the client holds its loading state until
+  # its reply, an _ack or an _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.synchronize do
+      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)
+      live_connection.receive(component, data)
+    rescue StandardError => error
+      live_connection.handle_error(component, error, channel: self)
+    end
   end
 
   def unsubscribed
     return unless component
 
-    component.disconnect
-    @component = nil
+    live_connection.synchronize do
+      # Already disconnected by a newer subscription for the same component
+      component.disconnect if live_connection.get_component(component.live_id).equal?(component)
+      @component = nil
+    end
   end
 
   # Exposes #transmit, which ActionCable keeps private to the channel.

data/app/helpers/live_cable_helper.rb

@@ -6,6 +6,9 @@ module LiveCableHelper
     # Add the current component to the parent context before making a new context
     render_context&.add_component(component)
 
+    # A prerendered root is the one component whose defaults are signed into the page
+    component.round_trip_defaults if render_context.nil? && !component.live_connection
+
     # If we had a parent with a live connection, we're connected, so apply defaults now, if not
     # then we apply them to the pre-render container
     component.apply_defaults
@@ -14,7 +17,14 @@ module LiveCableHelper
     context_stack.push(context)
 
     begin
-      value = yield
+      value = nil
+
+      # A connected root runs its render callbacks in broadcast_render
+      if component.live_connection && !context.root?
+        component.run_callbacks(:render) { value = yield }
+      else
+        value = yield
+      end
     ensure
       context_stack.pop
     end
@@ -40,11 +50,30 @@ module LiveCableHelper
     live_id = "#{component}/#{id}"
 
     component = render_context&.get_component(live_id) || LiveCable.instance_from_string(component, id)
-    component.defaults = defaults
+    component.defaults = render_context ? defaults.transform_values { |value| render_context.track(value) } : defaults
 
     render(component)
   end
 
+  # A meta tag carrying a digest of who this page was rendered for. When a
+  # Turbo visit brings a different one - after a sign-in, sign-out or
+  # impersonation - the client reopens its socket, so the new handshake
+  # identifies the new session. Pass what your connection's connect
+  # identifies by; the values are never sent in the clear.
+  #
+  # @param values [Array<Object>] e.g. current_user, or nil when signed out
+  def live_cable_identity_tag(*values)
+    tag.meta(name: 'live-cable-identity', content: LiveCable::IdentityDigest.digest(*values))
+  end
+
+  # Templates get the plain value inside a reactive one, so Rails helpers and
+  # `case` see a real Array or Hash.
+  def live_cable_unwrap(value)
+    return value unless value.is_a?(LiveCable::Delegator)
+
+    render_context.unwrap(value)
+  end
+
   private
 
   # @return [LiveCable::RenderContext, nil]

data/lib/live_cable/action_cable_connection.rb

@@ -11,9 +11,12 @@ module LiveCable
   # there. Keeping LiveCable off the identifiers leaves that mechanism working
   # for the application's own, such as current_user.
   module ActionCableConnection
+    LOCK = Mutex.new
+
     # @return [LiveCable::Connection]
     def live_connection
-      @live_connection ||= LiveCable::Connection.new(request)
+      # A socket's subscribes run as concurrent jobs on ActionCable's worker pool
+      @live_connection || LOCK.synchronize { @live_connection ||= LiveCable::Connection.new(request) }
     end
   end
 end