@isometriks/live_cable 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -6,6 +6,104 @@ The Ruby gem (`live_cable`) and the npm package (`@isometriks/live_cable`) are
6
6
  released together and share a single version number. Entries below note which
7
7
  side of the pair a change affects when it isn't both.
8
8
 
9
+ ## 0.3.0 - 2026-09-26
10
+
11
+ ### Upgrading from 0.2
12
+
13
+ Upgrade the gem and the npm package together. The 0.3 client no longer sends
14
+ the `_csrf_token` field that the 0.2 gem checks on every message, so a newer
15
+ client talking to an older gem has every action refused.
16
+
17
+ If your `ApplicationCable::Connection` follows the 0.2 installation guide,
18
+ delete both LiveCable lines from it. LiveCable now attaches `live_connection`
19
+ to every connection itself.
20
+
21
+ ```ruby
22
+ # app/channels/application_cable/connection.rb - delete these
23
+ identified_by :live_connection
24
+
25
+ def connect
26
+ self.live_connection = LiveCable::Connection.new(request)
27
+ end
28
+ ```
29
+
30
+ Delete them together. Without `identified_by` there is no `live_connection=`
31
+ for `connect` to call and every handshake fails. Without the `connect` override
32
+ the identifier shadows the `live_connection` LiveCable attaches with a nil one,
33
+ and every subscribe fails with a `LiveCable::Error` that says so. Leaving both
34
+ in place keeps working, at the cost described under *Changed*.
35
+
36
+ ### Fixed
37
+
38
+ - **A message could be refused with no answer, leaving the component stuck in
39
+ its loading state.** `LiveChannel#receive` had no rescue of its own, so
40
+ anything raised before an action's own rescue — a component that failed to
41
+ subscribe, the CSRF check — went to ActionCable, which only logs it. The
42
+ client holds `live-loading` and `live-disable-with` until it hears back, so
43
+ the button stayed disabled until a reload. Every batch is now answered with a
44
+ `_refresh`, `_ack` or `_error`. A subscribe that fails at any point transmits
45
+ an `_error` too, and the client's unsubscribe then removes the half-built
46
+ component from the connection rather than leaving it for the next subscribe
47
+ to resurrect (gem).
48
+
49
+ ### Changed
50
+
51
+ - `live_connection` is attached to every `ActionCable::Connection` by LiveCable
52
+ itself, so the connection no longer declares it. As an identifier, the
53
+ per-socket `LiveCable::Connection` became part of the connection's identity,
54
+ which `ActionCable.server.remote_connections` has to match in full, so an
55
+ application could never disconnect its users' sockets on sign-out. See
56
+ *Upgrading from 0.2* above (gem).
57
+
58
+ ### Removed
59
+
60
+ - The per-message CSRF token check, and with it the `_csrf_token` field the
61
+ client sent with every batch. A WebSocket is protected at its handshake by
62
+ ActionCable's origin check and the `SameSite=Lax` session cookie, and the
63
+ check added nothing on top of those except a way to wedge a socket: it ran
64
+ against the session captured at the handshake, and a socket never sees
65
+ cookies set afterwards, so once the session's token rotated — Devise does
66
+ this on every sign-in — every message on that socket was refused until the
67
+ socket reconnected. A socket that outlives a sign-in is handled as for any
68
+ other channel, by the application disconnecting it; see the architecture
69
+ guide (gem + npm).
70
+
71
+ ## 0.2.1 - 2026-08-13
72
+
73
+ ### Removed
74
+
75
+ - `Component#channel_name` and `Connection#channel_name`. A component no longer
76
+ subscribes to a stream of its own now that payloads are written straight to its
77
+ channel, so the name identified a stream nothing published to or read from.
78
+ Subscribing to external streams with `stream_from` is unaffected (gem).
79
+
80
+ ### Fixed
81
+
82
+ - **The opening payload from `LiveChannel#subscribed` could be dropped.**
83
+ Payloads were published through the pubsub adapter, but ActionCable registers
84
+ `stream_from` asynchronously — so the initial render could be published before
85
+ the subscription it targets existed, and pubsub delivers only to subscribers
86
+ present at that moment, with no buffering or retry. The component was left
87
+ showing `data-live-status-value="disconnected"`, with no cached render on the
88
+ client for a Turbo reattach to replay, until some later action happened to
89
+ produce a refresh. When a subscribe render raised, the `_error` payload was
90
+ lost outright and the failure never surfaced in the browser at all. A
91
+ component's stream belongs to exactly one connection, so payloads are now
92
+ written straight to that connection rather than published, which removes the
93
+ race along with a pubsub round trip (gem).
94
+ - **Components not reattaching after a Turbo Drive navigation.** Navigating to a
95
+ page containing a component that is already subscribed deliberately keeps the
96
+ existing subscription, so `LiveChannel#subscribed` does not run again and the
97
+ server sends nothing. The newly rendered element was left with its
98
+ server-rendered status of `disconnected` and never received the component's
99
+ current state. A reconnecting controller now re-syncs the subscription's status
100
+ and replays the last render into the new element (npm).
101
+ - Building DOM from a server render used iterator helpers
102
+ (`childNodes.values().find(...)`), an ES2025 feature, which raised
103
+ `TypeError: ... .find is not a function` on runtimes that do not implement them
104
+ — Node 20 and earlier, and browsers older than Chrome 122 / Firefox 131 /
105
+ Safari 18.4. Rewritten with `Array.from` (npm).
106
+
9
107
  ## 0.2.0
10
108
 
11
109
  The gem and npm package versions are realigned in this release. The npm package
package/README.md CHANGED
@@ -30,21 +30,19 @@ bundle install
30
30
 
31
31
  ## Configuration
32
32
 
33
- To use LiveCable, you need to set up your `ApplicationCable::Connection` to initialize a `LiveCable::Connection`.
34
-
35
- Add this to your `app/channels/application_cable/connection.rb`:
36
-
37
- ```ruby
38
- module ApplicationCable
39
- class Connection < ActionCable::Connection::Base
40
- identified_by :live_connection
41
-
42
- def connect
43
- self.live_connection = LiveCable::Connection.new(self.request)
44
- end
45
- end
46
- end
47
- ```
33
+ There is nothing to configure on the cable side. LiveCable attaches itself to
34
+ `ActionCable::Connection::Base`, so your `ApplicationCable::Connection` stays as
35
+ it is, with whatever `identified_by` it declares or none at all. LiveCable needs
36
+ no identifiers of its own.
37
+
38
+ If you followed an earlier version of this guide, remove the
39
+ `identified_by :live_connection` line and the `connect` override that went with
40
+ it. Remove both at once, since either one on its own breaks every connection.
41
+ Together they keep working, but they make a per-socket object part of the
42
+ connection's identity, which stops `ActionCable.server.remote_connections` from
43
+ ever finding your users' sockets. See the
44
+ [architecture guide](https://livecable.io/guide/architecture#sign-in-and-sign-out)
45
+ for what to do about sockets when a user signs in or out.
48
46
 
49
47
  ## JavaScript Setup
50
48
 
@@ -166,20 +166,17 @@ export default class extends Controller {
166
166
  }
167
167
  }
168
168
 
169
+ // Batch any pending debounced messages ahead of this one so they are sent
170
+ // in the order they were triggered
169
171
  #flushDebounced(message) {
170
172
  const messages = [message]
171
173
 
172
- // Add all pending debounced messages to be sent immediately
173
174
  for (const [source, { timeout, message: debouncedMessage }] of this.#debounces) {
174
175
  clearTimeout(timeout)
175
176
  messages.unshift(debouncedMessage)
176
177
  }
177
178
  this.#debounces.clear()
178
179
 
179
- return { messages, _csrf_token: this.#csrfToken }
180
- }
181
-
182
- get #csrfToken() {
183
- return document.querySelector("meta[name='csrf-token']")?.getAttribute("content")
180
+ return { messages }
184
181
  }
185
182
  }
@@ -34,8 +34,7 @@ function createDOMFromHTML(html) {
34
34
  template.innerHTML = html
35
35
 
36
36
  // Find a node that isn't a comment
37
- const node = template.content.childNodes
38
- .values()
37
+ const node = Array.from(template.content.childNodes)
39
38
  .find(n => n.nodeName !== '#comment')
40
39
 
41
40
  if (node) {
@@ -230,6 +229,15 @@ class ComponentState {
230
229
  return this.#element
231
230
  }
232
231
 
232
+ /**
233
+ * Whether a render has been received and cached, and can therefore be
234
+ * replayed into a freshly attached element.
235
+ * @returns {boolean}
236
+ */
237
+ get hasRender() {
238
+ return this.#lastTemplate !== null && Boolean(this.#partsByTemplate[this.#lastTemplate])
239
+ }
240
+
233
241
  /**
234
242
  * Create a DOM element from stored state.
235
243
  * @param {Object} refresh - Optional refresh data to update state
@@ -345,12 +353,44 @@ class Subscription {
345
353
 
346
354
  /**
347
355
  * Update the controller reference.
348
- * Called when a Stimulus controller reconnects to an existing subscription.
356
+ * Called when a Stimulus controller reconnects to an existing subscription —
357
+ * most importantly after a Turbo Drive navigation to a page that contains the
358
+ * same component, where prune() deliberately keeps the subscription alive.
359
+ *
360
+ * In that case the ActionCable subscription is never recreated, so
361
+ * LiveChannel#subscribed does not run again and the server sends nothing.
362
+ * Without re-syncing here, the newly rendered element keeps the
363
+ * server-rendered status of "disconnected" forever and never receives the
364
+ * component's current state.
349
365
  *
350
366
  * @param {Object} controller - Stimulus controller instance
351
367
  */
352
368
  set controller(controller) {
369
+ const previous = this.#controller
370
+
353
371
  this.#controller = controller
372
+ this.#componentState.element = controller.element
373
+
374
+ if (previous && previous !== controller) {
375
+ this.#reattach()
376
+ }
377
+ }
378
+
379
+ /**
380
+ * Bring a freshly connected controller up to date with state this
381
+ * subscription already holds.
382
+ * @private
383
+ */
384
+ #reattach() {
385
+ if (this.#currentStatus) {
386
+ this.#controller.statusValue = this.#currentStatus
387
+ }
388
+
389
+ // Replay the last render into the new element. The server-side component
390
+ // is the same instance, so the cached parts are its current state.
391
+ if (this.#componentState.hasRender) {
392
+ this.#handleRefresh(null)
393
+ }
354
394
  }
355
395
 
356
396
  /**
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@isometriks/live_cable",
3
- "version": "0.2.0",
3
+ "version": "0.3.0",
4
4
  "type": "module",
5
5
  "files": [
6
6
  "app/assets/javascript",