hibiki_rails 0.20.0 → 0.20.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e04ed317fc77afc03ef9dcb0ec2fc1f52833e23dd0700934e3bee3551c0f1549
-  data.tar.gz: b76c0323f43becb86476653aebd6cd58e01e1ab917c18fdf5e7e843c95f01e60
+  metadata.gz: fcb75b30dd2f92f65a4581f6b26ca93f92ef7665c333139b3b6b1f839db70943
+  data.tar.gz: 4de446211377d8a95301b0fc5cd9d5361d6ce76489da9bb224711f90a29d51a2
 SHA512:
-  metadata.gz: c6b3b937fcaeba352b86432ceef1b4ec526e26e74509b83f39a868db656706fd4f89c64d6cd3d3805a6c5553376a1f09765dbd939ec28156bf3bb8cbcb696e45
-  data.tar.gz: 889c7cea1cfc1c772e6a18573e2717fbf8a569ff679a5a4f6208d2b961db6d80c4b7d8c00435e4be8783a7a57adfb22bb162d7d1624b566fedfd4f3ebbaeaf88
+  metadata.gz: b4c546401703167cc3d2f6ed5690a0b93d95f631fd311d3cc1883a51a6b29365a9a631251690fc351708fba80af4e73fd303034c92f5f7192c6148da26aea644
+  data.tar.gz: 3657421c216fcc9f44c2a7d6d7a14a44e0737d9029e37f4e2a0652c31b4b486aba25f4888c045df32d2c88ba1f55f0de4b18cdaf43df29dd68b1fb89cb8b2887

data/CHANGELOG.md

@@ -4,6 +4,28 @@ 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.20.1 — 2026-10-12
+
+### Fixed
+
+**A channel runs its actions in the order the browser sent them.** Action
+Cable hands each incoming message to a worker pool, so two actions sent back
+to back could run swapped. The client sends such a pair whenever a visitor
+types in a debounced field and then clicks or presses Enter at once: the
+typed value and the action leave in the same instant. When they swapped, the
+action ran before the value arrived, so a save could miss the last thing
+typed or be refused.
+
+- The channel now runs each subscription's actions by the number the client
+  gives them. An action that arrives ahead of its turn waits for the ones
+  before it, for at most 100 ms.
+- Update the gem and the npm package together. A client older than 0.20.1
+  still works with the new gem, but its first action after a reconnect waits
+  100 ms.
+- Nothing changes in your channels or views.
+- An unsubscribe is not numbered, and can still overtake an action sent just
+  before the page is left.
+
 ## 0.20.0 — 2026-10-12
 
 ### Added

data/app/assets/javascripts/hibiki.js

@@ -422,10 +422,19 @@ export class ChannelController extends Controller {
   // undefined when the payload went nowhere — the socket turned out to
   // be closed, or the island was already offline — and the caller owns
   // recovery.
+  //
+  // The server runs a subscription's actions in seq order (Action Cable's
+  // worker pool can swap two sent back to back), so the numbers it sees
+  // must run from 1 with none missing: an action dropped in the offline gap
+  // takes no number, and linkClosed starts the count again for the fresh
+  // subscription a reconnect makes.
   perform(action, payload = {}) {
+    delete payload.hbt
+    // The offline gap: dropped, and the return says so — a truthy seq here
+    // would tell a public caller a repaint is coming when none is.
+    if (!this.subscribed && this.connectedOnce) return undefined
     const seq = ++this.seq
     payload.hbk = seq
-    delete payload.hbt
     if (this.subscribed) {
       this.sendTrips(payload)
       this.beginBusy(seq, action)
@@ -453,15 +462,10 @@ export class ChannelController extends Controller {
     // the socket dropped, and the island is stamped `offline` for the
     // whole gap — the signal the connect window cannot give, where the
     // page is painted and looks live.
-    if (!this.connectedOnce) {
-      this.sendTrips(payload)
-      this.beginBusy(seq, action)
-      this.queued.push([action, payload])
-      return seq
-    }
-    // The offline gap: dropped, and the return says so — a truthy seq here
-    // would tell a public caller a repaint is coming when none is.
-    return undefined
+    this.sendTrips(payload)
+    this.beginBusy(seq, action)
+    this.queued.push([action, payload])
+    return seq
   }
 
   // ActionCable's `connected`, i.e. the server confirmed the subscription.
@@ -484,6 +488,8 @@ export class ChannelController extends Controller {
     // reason — their acks are never coming.
     this.queued = []
     this.settleAll()
+    // The fresh subscription expects its actions numbered from 1.
+    this.seq = 0
   }
 
   setState(state) {

data/lib/hibiki/rails/action_order.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "concurrent/scheduled_task"
+
+module Hibiki
+  module Rails
+    # Puts one subscription's incoming actions back in the order the client
+    # sent them. ActionCable hands every websocket message to a worker pool
+    # (Connection#receive is send_async), so two actions sent back to back
+    # can reach Channel#perform_action in either order — and the client's
+    # flush sends a typed field and the click after it in one tick.
+    #
+    # The client numbers its actions under `hbk`, from 1 per subscription
+    # with no gaps. #submit calls each job when its number comes up: one
+    # ahead of its turn is held until the missing ones arrive, or until
+    # GRACE runs out for that gap (a client older than this numbers on
+    # across a reconnect, so its first action there waits one grace). A
+    # number whose turn has passed, a repeat, and anything that is not an
+    # Integer run at once.
+    #
+    # Jobs run under the lock, on whichever thread releases them, so they
+    # must only enqueue: the order of the calls is the order of the queue.
+    # Like Registry, this is glue touched from many cable threads, not the
+    # graph; a lock is the right tool here.
+    class ActionOrder
+      # Seconds one gap is waited for. A websocket does not lose messages,
+      # so only a number that was never sent waits it out.
+      GRACE = 0.1
+
+      def initialize
+        @lock = Mutex.new
+        @due = 1
+        @held = {}
+        @closed = false
+      end
+
+      def submit(seq, &job)
+        return job.call unless seq.is_a?(Integer)
+
+        @lock.synchronize do
+          next job.call if @closed || seq < @due || @held.key?(seq)
+
+          @held[seq] = job
+          release
+        end
+      end
+
+      # Run what is held, in order, and let everything after straight
+      # through. Channel#unsubscribed calls it ahead of the dispose.
+      def close
+        @lock.synchronize do
+          @closed = true
+          disarm
+          @held.sort.each { |_, job| job.call }
+          @held.clear
+        end
+      end
+
+      private
+
+      def release
+        while (job = @held.delete(@due))
+          @due += 1
+          job.call
+        end
+        watch
+      end
+
+      # One timer per gap: more arrivals behind the same gap do not restart
+      # it. `@waiting` is the number waited for, which is also what tells a
+      # timer that fires late it is stale.
+      def watch
+        return disarm if @held.empty?
+        return if @waiting == @due
+
+        disarm
+        waiting = @waiting = @due
+        @timer = Concurrent::ScheduledTask.execute(GRACE) { give_up(waiting) }
+      end
+
+      def disarm
+        @timer&.cancel
+        @timer = @waiting = nil
+      end
+
+      def give_up(waiting)
+        @lock.synchronize do
+          next unless @waiting == waiting
+
+          @due = @held.keys.min
+          release
+        end
+      end
+    end
+  end
+end

data/lib/hibiki/rails/channel.rb

@@ -93,14 +93,17 @@ module Hibiki
       # `hbt` is the third reserved key: the trips the browser timed since
       # its last action (see Instrumentation#trips_from). Deleted whether or
       # not anyone listens, for the same reason as `hbk`.
+      #
+      # ActionCable runs this on its worker pool, several at once and in no
+      # order, so the post waits for the seq's turn (see ActionOrder). An
+      # action with no seq takes no turn. `asked` is read on arrival: a held
+      # action's wait is part of its `action` event.
       def perform_action(data)
         seq = data.delete("hbk")
         trips = trips_from(data.delete("hbt"))
         asked = Process.clock_gettime(Process::CLOCK_MONOTONIC)
 
-        # A nil actor means the subscription was rejected or already torn
-        # down; drop the action rather than blow up the cable thread.
-        posted = @__hibiki_actor&.post do
+        post_in_turn(seq) do
           trips.each { instrument("trip", it) }
           instrument_action(data, asked) { Hibiki.batch { super(data) } }
         ensure
@@ -111,13 +114,6 @@ module Hibiki
           # in exactly the case the user most needs it to stop.
           transmit({ ack: seq }) if seq
         end
-
-        # post yields nil (no actor) or false (queue closed): the block
-        # never ran, so neither did its ensure. `dropped` is also what lets
-        # the client tell "late" from "never" — nothing is coming for this
-        # seq, so it settles immediately rather than waiting out the grace
-        # window.
-        transmit({ ack: seq, dropped: true }) if seq && !posted
       end
 
       private
@@ -126,6 +122,7 @@ module Hibiki
         super
         return reject if cid.blank?
 
+        @__hibiki_order = ActionOrder.new
         @__hibiki_actor = build_graph_actor
         # The block runs owned + untracked (Hibiki.root); the effects it
         # creates do their dependency-collecting first run right here, on
@@ -144,10 +141,32 @@ module Hibiki
         return unless @__hibiki_actor
 
         Hibiki::Rails.registry.unregister(self)
+        # Held actions run first: the dispose must be the last job posted.
+        @__hibiki_order.close
         @__hibiki_actor.post { instrument("unsubscribe") { @__hibiki_root.dispose } }
         @__hibiki_actor.stop
       end
 
+      # Post the job to the graph when the action numbered `seq` is due. A
+      # rejected subscription has no order and nothing to keep in order.
+      #
+      # A nil actor means the subscription was rejected or already torn
+      # down; drop the action rather than blow up the cable thread. post
+      # yields nil (no actor) or false (queue closed): the job never ran, so
+      # neither did its ensure. `dropped` is also what lets the client tell
+      # "late" from "never" — nothing is coming for this seq, so it settles
+      # immediately rather than waiting out the grace window.
+      def post_in_turn(seq, &job)
+        return post_or_drop(seq, job) unless @__hibiki_order
+
+        @__hibiki_order.submit(seq) { post_or_drop(seq, job) }
+      end
+
+      def post_or_drop(seq, job)
+        posted = @__hibiki_actor&.post(&job)
+        transmit({ ack: seq, dropped: true }) if seq && !posted
+      end
+
       # Build the signal graph: create states/deriveds/effects as instance
       # variables so actions can reach them. Runs once, on the graph's
       # thread, inside Hibiki.root.

data/lib/hibiki/rails/version.rb

@@ -2,6 +2,6 @@
 
 module Hibiki
   module Rails
-    VERSION = "0.20.0"
+    VERSION = "0.20.1"
   end
 end

data/lib/hibiki/rails.rb

@@ -67,6 +67,7 @@ end
 require_relative "rails/version"
 require_relative "rails/registry"
 require_relative "rails/graph_actor"
+require_relative "rails/action_order"
 require_relative "rails/debounce"
 require_relative "rails/instrumentation"
 require_relative "rails/broadcasts"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hibiki_rails
 version: !ruby/object:Gem::Version
-  version: 0.20.0
+  version: 0.20.1
 platform: ruby
 authors:
 - planetaska
@@ -181,6 +181,7 @@ files:
 - lib/generators/hibiki/rails/upload_field_helpers.rb
 - lib/generators/hibiki/rails/upload_field_injections.rb
 - lib/hibiki/rails.rb
+- lib/hibiki/rails/action_order.rb
 - lib/hibiki/rails/broadcasts.rb
 - lib/hibiki/rails/channel.rb
 - lib/hibiki/rails/commands.rb