hibiki_rails 0.17.0 → 0.17.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fbcb87c658d3e83cc6c10f216a69e78266878aa8396ed9662e3f06d8c6213027
-  data.tar.gz: d6a66d149293d26e43edf4cd31ec20eb5886cc0d3db2b935b5b0c3c333965292
+  metadata.gz: 83e9656d09f3910405a4db7167b526c173158eb1035d5cb5129e4f916c88c278
+  data.tar.gz: e22b25605c6522e98cfdc86dcd685e62b3c60ed31ca865eb2daa53f74aaaf946
 SHA512:
-  metadata.gz: 0e027bd60c62abdf4d269b94cd38f0e008889b42d205b9f2d98d737f1455acd60f467cf9951a5a35f77bbc3ee02120b8e5f6397fc43dc9b7dc7842d91c73372e
-  data.tar.gz: 28a6058a2a235ef23e02d52b5dbdf7177f97b6ba96971d9c72ea0d0302d6eaf380854b2e283069177b2038a06a2d45af540bf3b929a62f53baa7144589c33bc3
+  metadata.gz: 8c459eb9453de6af88c6e7859849a41dcbf7c0daa5d2e79da12e5ac8f729f4b85093e9d10c176d97cb8cd5141ef47ffeb0bcb2482aa03b223e42b2af4b13d9a6
+  data.tar.gz: 7ccd090ef5fdd72735d7bb45d356a1f7085fb6c323d42692c91b7226a5fd6ac058f0ea477efaa6d7693dfbfe66254d85c358e8ea5ca7d3fcd49f6fde56366040

data/CHANGELOG.md

@@ -4,6 +4,70 @@ The gem and the npm package are released in lockstep and share these version
 numbers — `app/assets/javascripts/hibiki.js` is a single copy served both ways,
 so importmap and bundler apps always resolve identical client code.
 
+## 0.17.2 — 2026-10-11
+
+### Fixed
+
+**A save the model refused could leave a `reactive_association` form unable
+to save.** The form keeps one record between attempts. When a `commit` was
+refused, the join rows were rolled back, but the record still remembered the
+selection that attempt had written, and the next `commit` was compared with
+that memory instead of the table. If the refused attempt had removed an id
+that the next one still held, the retry inserted a join row that was already
+there. With a unique index on the pair, which the `multiselect` generator
+writes, that raised `ActiveRecord::RecordNotUnique` and the visitor saw a
+Save that did nothing, every time, until the form was opened again. Without
+the index it wrote a duplicate row.
+
+- Any refused save could set it up, not only one about the association: a
+  blank name saved together with a removed tag was enough.
+- A refused `commit` or `commit!` now unloads the associations named in
+  `reactive_association`, and the join association behind a
+  `has_many :through` or a `has_and_belongs_to_many`. The form keeps the
+  visitor's selection; nothing changes in the channel or the view.
+- An app that calls `record.reload` before `commit` to get round this can
+  remove the call.
+- `hibiki_associations` on a form class lists the names it declared.
+
+**A form that had saved once could save its `reactive_association` wrongly
+after another session changed the same record.** The cause is the same
+memory. If the other session had added an id this form then added too, the
+commit raised `ActiveRecord::RecordNotUnique`. If it had removed an id this
+form still showed, the commit returned `true` and did not write it.
+
+- `commit` now reads the association from the table each time, at the cost
+  of one query per association when it was already loaded.
+- The later save still wins: the form's selection replaces the other
+  session's, as its other fields already did.
+- Nested forms (`reactive_nested`) are not changed.
+- The npm package is unchanged apart from its version.
+
+## 0.17.1 — 2026-10-09
+
+### Fixed
+
+**Renders sent over the broadcast transport could reach the page out of
+order.** Action Cable hands each broadcast to a pool of threads, so two
+renders a channel sent a millisecond apart could be delivered in either
+order. When both drew the same target, the page ended on the older one and
+stayed wrong until something rendered that target again: a Save button left
+enabled, a note that contradicted the server's state. It was always
+possible; since 0.17.0 sends a debounced field's text just ahead of a click
+or a submit, any form with one did it routinely.
+
+- `broadcast_replace` and `broadcast_morph` now number their renders, and
+  the client applies them in the order the channel sent them. Nothing changes
+  in the channel or the view.
+- A render that arrives ahead of an earlier one waits for it, for at most
+  100 ms. One that arrives later than that is still drawn, unless a newer
+  render has drawn the same target since.
+- `broadcast_refresh`, the transmit transport, and streams an app sends with
+  `Turbo::StreamsChannel` itself are not affected and not changed.
+- Both halves are needed, so update the gem and the npm package together. A
+  page on one side only behaves as 0.17.0 did.
+- `broadcast_replace` and `broadcast_morph` also accept `attributes:`, which
+  are kept on the stream beside the gem's own.
+
 ## 0.17.0 — 2026-10-08
 
 ### Added

data/app/assets/javascripts/hibiki.js

@@ -66,6 +66,9 @@
 //                 beside them existing to change the text
 //   focus sites   data-hibiki-focus="true|select"      takes focus, and has its
 //                 text selected, when a render this tab caused inserts it
+//   turbo streams data-hibiki-seq="3"                  the render's number, and
+//                 data-hibiki-from="CounterChannel/<cid>" the island it is for;
+//                 see "Render order" below
 //
 // The client writes the protocol's other half at runtime — read-only to
 // app code, addressed to app CSS:
@@ -118,6 +121,16 @@
 // nearest id-bearing ancestor. Only controls: when none of these is there,
 // focus is left where the browser put it. Any render, whoever caused it.
 //
+// Render order. Action Cable hands each broadcast to a worker pool, so two
+// renders the channel sent a millisecond apart can arrive in either order,
+// and the page would end on the older one. The channel numbers its Turbo
+// streams and the island applies them in that order: one that arrives ahead
+// of its turn is held until the missing ones come, or until `orderGrace`
+// runs out on one that never will. A render that turns up after it was
+// given up on is still drawn, unless a later one has drawn the same target
+// since. A stream with no number, or another island's, is left alone. The
+// transmit transport needs none of this: it writes to the socket in order.
+//
 // App JS reaching the graph — the ONE public seam. A gesture that needs
 // script (drag-and-drop, a third-party widget) fires its action through
 // the island's OWN subscription: `perform(action, payload)` on the island
@@ -753,6 +766,11 @@ export default class HibikiController extends ChannelController {
   // stamps no data-hibiki-params-value.
   static values = { channel: String, params: Object }
 
+  // ms a Turbo render that arrived ahead of its turn waits for the ones
+  // before it (see inOrder). Only a lost broadcast waits it out; a late one
+  // is a pool hop behind, a millisecond or two.
+  static orderGrace = 100
+
   // The island stamps its channel; no inference.
   channelName() {
     return this.channelValue
@@ -833,19 +851,23 @@ export default class HibikiController extends ChannelController {
     // Re-scan at the points a fragment can be swapped under us, rather
     // than blanket-observing the document: a MutationObserver over the page
     // is a real per-mutation cost paid by every app on it.
+    this.resetOrder()
     this.streamRender = (event) => {
       const render = event.detail.render
+      const stream = event.detail.newStream
+      // Taken now, not when the render's turn comes: see arrival().
       const arrival = this.arrival()
-      event.detail.render = async (streamElement) => {
-        await render(streamElement)
-        // The Turbo transport's paint. Counting it here is what lets an ack
-        // settle immediately instead of waiting out its grace window. The
-        // listener is on the document, so an unrelated broadcast counts too
-        // — which at worst settles an already-acked trip a few ms early,
-        // never one that has not been acked at all.
-        this.renders++
-        this.scan(arrival)
-      }
+      event.detail.render = (streamElement) =>
+        this.inOrder(stream, async () => {
+          await render(streamElement)
+          // The Turbo transport's paint. Counting it here is what lets an ack
+          // settle immediately instead of waiting out its grace window. The
+          // listener is on the document, so an unrelated broadcast counts too
+          // — which at worst settles an already-acked trip a few ms early,
+          // never one that has not been acked at all.
+          this.renders++
+          this.scan(arrival)
+        })
     }
     document.addEventListener("turbo:before-stream-render", this.streamRender)
     // A refresh stream morphs the page after its own render has returned,
@@ -882,9 +904,99 @@ export default class HibikiController extends ChannelController {
     this.unsent.clear()
     this.marks.clear()
     this.observer.disconnect()
+    this.resetOrder()
     super.disconnect()
   }
 
+  // A reconnect builds a fresh graph, which numbers its renders from 1.
+  linkClosed() {
+    this.resetOrder()
+    super.linkClosed()
+  }
+
+  // ── Render order ──────────────────────────────────────────────────────
+  //
+  // `due` is the number of the next render to apply and `held` the renders
+  // waiting on it, by number. `missed` and `drawn` exist only after a gap
+  // was given up on: the numbers skipped, and the last number drawn into
+  // each target since, which is what tells a late render it is stale.
+
+  // Run `job` (the render and what follows it) when the stream's turn
+  // comes, or never when it is stale. Jobs are CALLED in order and not
+  // awaited: a call reaches the swap, or the motion module's queue, before
+  // it returns, and that queue keeps the order from there.
+  inOrder(stream, job) {
+    const seq = Number(stream?.getAttribute?.("data-hibiki-seq"))
+    if (!seq || stream.getAttribute("data-hibiki-from") !== `${this.channelValue}/${this.cidValue}`) {
+      return job()
+    }
+    const target = stream.getAttribute("target")
+    const run = () => {
+      this.drew(target, seq)
+      return job()
+    }
+    if (seq < this.due) {
+      // Late. A number never given up on is a repeat, or older than
+      // anything remembered.
+      const stale = !this.missed.delete(seq) || this.drawn.get(target) > seq
+      return stale ? Promise.resolve() : run()
+    }
+    if (seq > this.due) {
+      return new Promise((resolve) => {
+        this.held.set(seq, () => resolve(run()))
+        this.orderTimer ??= setTimeout(() => this.giveUp(), this.constructor.orderGrace)
+      })
+    }
+    const done = run()
+    this.due++
+    this.release()
+    return done
+  }
+
+  // Apply the held renders that now follow on. Any still held wait on a
+  // new gap, with a new grace.
+  release() {
+    for (let run; (run = this.held.get(this.due)); this.due++) {
+      this.held.delete(this.due)
+      run()
+    }
+    clearTimeout(this.orderTimer)
+    this.orderTimer = this.held.size
+      ? setTimeout(() => this.giveUp(), this.constructor.orderGrace)
+      : undefined
+  }
+
+  // The grace ran out: move past the missing numbers to the first held.
+  giveUp() {
+    const first = Math.min(...this.held.keys())
+    for (let seq = this.due; seq < first; seq++) this.missed.add(seq)
+    this.missedAt = performance.now()
+    this.due = first
+    this.release()
+  }
+
+  // Remember what was drawn while a missed render may still turn up, and
+  // no longer: one later than the ceiling is lost by the same measure a
+  // trip is.
+  drew(target, seq) {
+    if (performance.now() - this.missedAt > this.constructor.busyCeiling) this.missed.clear()
+    if (!this.missed.size) return this.drawn.clear()
+    if (!(this.drawn.get(target) > seq)) this.drawn.set(target, seq)
+  }
+
+  // Start counting again from 1. Renders still held are the old graph's
+  // last word, so they are applied first, in order.
+  resetOrder() {
+    clearTimeout(this.orderTimer)
+    this.orderTimer = undefined
+    const held = [...(this.held ?? [])].sort(([a], [b]) => a - b)
+    this.due = 1
+    this.held = new Map()
+    this.missed = new Set()
+    this.drawn = new Map()
+    for (const [, run] of held) run()
+  }
+
   // The other swap point: hibiki's own transmit transport. A held swap
   // hands back a promise; the replacement sentinel exists only after it.
   received(data) {

data/lib/hibiki/rails/broadcasts.rb

@@ -17,16 +17,16 @@ module Hibiki
 
       # Replace the element with DOM id `target` (accepts partial:/locals:,
       # html:, or anything Turbo's renderer takes).
-      def broadcast_replace(target:, **rendering)
-        Turbo::StreamsChannel.broadcast_replace_to(*stream_name, target:, **rendering)
+      def broadcast_replace(target:, attributes: {}, **rendering)
+        Turbo::StreamsChannel.broadcast_replace_to(
+          *stream_name, target:, attributes: attributes.merge(render_stamp), **rendering
+        )
       end
 
       # Replace via Turbo 8 morphing (<turbo-stream action="replace"
       # method="morph">): keeps focus/scroll where a plain replace resets.
-      def broadcast_morph(target:, **rendering)
-        Turbo::StreamsChannel.broadcast_replace_to(
-          *stream_name, target:, attributes: { method: :morph }, **rendering
-        )
+      def broadcast_morph(target:, attributes: {}, **rendering)
+        broadcast_replace(target:, attributes: { method: :morph }.merge(attributes), **rendering)
       end
 
       # Tell the page to refresh itself (Turbo 8 morph-everything style).
@@ -47,6 +47,17 @@ module Hibiki
           broadcast_refresh
         end
       end
+
+      # The number each render carries, and the island it is for. Action
+      # Cable hands every broadcast to a worker pool, so two sent a
+      # millisecond apart can reach the page in either order; the client
+      # applies them by number. Counted per subscription from 1, on the
+      # graph thread alone. A refresh carries none: it fetches the page, so
+      # its order does not matter. Part of the private data-hibiki contract.
+      def render_stamp
+        @__hibiki_renders = @__hibiki_renders.to_i + 1
+        { "data-hibiki-seq": @__hibiki_renders, "data-hibiki-from": "#{self.class.name}/#{params[:cid]}" }
+      end
     end
   end
 end

data/lib/hibiki/rails/reactive_form.rb

@@ -77,6 +77,7 @@ module Hibiki
         def reactive_association(*names)
           raise "#{self}: declare reactive_attributes before reactive_association" unless __hibiki_model_declared?
 
+          @hibiki_associations = [*hibiki_associations, *names.map(&:to_sym)]
           names.each { |name| __hibiki_ids_signal(name) }
         end
 
@@ -108,6 +109,10 @@ module Hibiki
           @hibiki_nested || __hibiki_inherited(:hibiki_nested) || {}
         end
 
+        def hibiki_associations
+          @hibiki_associations || __hibiki_inherited(:hibiki_associations) || []
+        end
+
         # The child form class, resolved on every use like hibiki_model so
         # a String declaration never pins a constant across a reload.
         def hibiki_nested_form(name)
@@ -259,7 +264,7 @@ module Hibiki
       # have moved values, and #persisted? flips after an INSERT.
       # rubocop:disable-next Naming/PredicateMethod -- boolean without a ?, exactly like AR's #save
       def commit
-        record = __hibiki_record!
+        record = __hibiki_unloaded_record
         if record.update(**to_h)
           # Unload before re-hydrating, so the reload honors the
           # association's own scope and drops destroyed rows.
@@ -272,13 +277,13 @@ module Hibiki
           # update APPENDS its built new children to the in-memory
           # association — a later success would insert them all again.
           # Unloading makes the next attempt start clean.
-          __hibiki_reset_nested(record)
+          __hibiki_unload(record)
           false
         end
       end
 
       # The raising half. Re-assigns and raises ActiveRecord::RecordInvalid
-      # (no rescue, and no AR constant named here); the nested associations
+      # (no rescue, and no AR constant named here); the record's associations
       # are unloaded even on the raise, so a rescued retry starts clean.
       def commit!
         return true if commit
@@ -287,7 +292,7 @@ module Hibiki
         begin
           record.update!(**to_h)
         ensure
-          __hibiki_reset_nested(record)
+          __hibiki_unload(record)
         end
       end
 
@@ -359,6 +364,34 @@ module Hibiki
         self.class.hibiki_nested.each_key { |name| record.public_send(name).reset }
       end
 
+      # What a refused attempt leaves behind on the record.
+      def __hibiki_unload(record)
+        __hibiki_reset_nested(record)
+        __hibiki_reset_associations(record)
+      end
+
+      # A refused update rolls the join rows back, but the ids writer has
+      # already left the association holding the refused set, and the join
+      # association behind a :through (or a has_and_belongs_to_many) holding
+      # the join records it built. The next ids write would be diffed
+      # against that memory instead of the table, so both are unloaded.
+      def __hibiki_reset_associations(record)
+        self.class.hibiki_associations.each do |name|
+          association = record.association(name)
+          association.reset
+          reflection = association.reflection
+          record.association(reflection.through_reflection.name).reset if reflection.through_reflection?
+        end
+      end
+
+      # The record to write to. Its ids associations are unloaded first, so
+      # the ids writer reads the table and not what this record remembers
+      # from an earlier commit or a preload: rows another session wrote
+      # since would otherwise be inserted twice, or silently left out.
+      def __hibiki_unloaded_record
+        __hibiki_record!.tap { __hibiki_reset_associations(it) }
+      end
+
       def __hibiki_record!
         record || raise("#{self.class} has no record — build it with .from(record)")
       end

data/lib/hibiki/rails/version.rb

@@ -2,6 +2,6 @@
 
 module Hibiki
   module Rails
-    VERSION = "0.17.0"
+    VERSION = "0.17.2"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hibiki_rails
 version: !ruby/object:Gem::Version
-  version: 0.17.0
+  version: 0.17.2
 platform: ruby
 authors:
 - planetaska
@@ -216,7 +216,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
 summary: 'Rails glue for hibiki: connection-scoped signal graphs over ActionCable
   + Turbo Streams.'