yrby-actioncable 0.2.3 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 71d5dea23772a176b12bbe5cbfe75a2a8cbe3dfff8e8c73f909330ef9844084b
-  data.tar.gz: 78f4d54167275c9e6e2fbade09e17e5c6d2cce7e7975e662ffa7e626fb03cdc1
+  metadata.gz: c93259f7cd51c197d4203903e5f8b522e526e164a858f17992c538e0a0b1f6f4
+  data.tar.gz: 46289b0f4544899a64a23c40f44a998667b399f1a9f0b6cbc1c9cbd63e7d613d
 SHA512:
-  metadata.gz: b434c280c1574f2b34f3517c04b653efaf09ce1cdc279795356b6e2d23b6c68e3dcf92c5a7a42e74f59a43745ccacc305f8372fec143d038dbabf22b53a32a5c
-  data.tar.gz: 790513cb6941bb5c9e6f6c3aaa1ce5496e1780fa093872ba867771a3bc3a51ed7b610ec0f291d69e102eee4ef5b8da0f5280cfe51e11b4162e6c97fc9a5879a6
+  metadata.gz: ab99efb5b5244556492419d8d646bd394f5e4f672729c1f6355571b0ab65c927122aa1833154150041fd550b0dc21a681a60f6bb5a952ac160fb05060e5609d5
+  data.tar.gz: 7d66edea6a44ba686d825da4d370d3e38be94a28c9df7aafea20ee9e506c31300d5011b94cb6d0fa2b62f0e3bfea2599984ec185503b96912fc037d58b8ae9cd

data/CHANGELOG-actioncable.md

@@ -6,6 +6,60 @@ this project aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-07-01
+
+### Added
+- **Unhealable-gap defense — on plain ActionCable AND AnyCable.** When the same
+  update is rejected as a causal gap repeatedly on one connection, the channel
+  now stops resyncing it forever and instead settles it and drops it. A gap that
+  survives repeated resyncs is unhealable — its missing dependency is gone for
+  good (a permanently-orphaned pending struct) — and resyncing it endlessly just
+  feeds the client's retransmit loop (the "id-less frames several times a
+  second" failure mode). A *healable* gap heals within a resync or two, well
+  under the limit, so this only trips on genuinely-dead updates.
+
+  - The settle ack carries `"dropped" => true` so an aware client can tell
+    "durably recorded" from "abandoned" and surface the loss instead of
+    silently reporting synced (`yrby-client` raises it via
+    `onError(..., "ack-dropped")`; older clients ignore the extra key).
+  - Configurable via `gap_strike_limit` (default `3`; `nil` disables — always
+    resync). Limits below `2` raise `ArgumentError`: strike 1 must send a
+    resync before any drop can be justified.
+  - Strikes are tracked per update (SHA-256) per connection, guarded by a
+    mutex (ActionCable dispatches a connection's messages to a worker pool).
+    The table is bounded; at capacity a single lowest-count entry is evicted,
+    and only when inserting a new key — a client cycling distinct gaps can't
+    reset a tracked key's count. A gap that finally records frees its slot.
+  - Under AnyCable — where every RPC command gets a fresh channel instance —
+    the table is persisted via anycable-rails' `state_attr_accessor` (istate,
+    round-tripped through anycable-go), declared automatically when
+    anycable-rails is loaded. Verified end-to-end on both stacks
+    (`frontend/gap_strike.mjs` in the demo).
+
+### Fixed
+
+Fixes from a full source review (a 0.2.4 was prepared but never published; its
+changes ship here):
+
+- **A lost-ack retry now re-broadcasts.** If the original attempt recorded the
+  update and then crashed (or the pub/sub broadcast failed) before
+  distributing, the retry was previously settled as `:applied` without
+  re-broadcasting — live subscribers stayed stale until their next full resync,
+  and nothing else could reach them. The retry now re-broadcasts before acking;
+  idempotent CRDT apply makes the duplicate free for every receiver.
+- **A missing document key now fails closed.** Under a transport that doesn't
+  keep the channel instance alive across actions (AnyCable), an app that forgot
+  to pass `key` to `sync_receive` silently recorded updates under a nil key,
+  broadcast them to a stream no one subscribes to, and still acked them. The
+  frame now raises `Y::Error` instead.
+
+### Changed
+
+- Raised the `yrby` floor to `>= 0.3.1`, whose `update_ready?` is exact
+  (trial-integration, not just per-client clocks). With an older core, a
+  cross-client-origin gap passed the ready check and the `update_advances?`
+  probe then acked-and-dropped real content.
+
 ## [0.2.3] - 2026-07-01
 
 ### Changed

data/README.md

@@ -242,6 +242,21 @@ servers:
   causal dependencies are already in the store (checked against `on_load`); a
   causally-incomplete update triggers a resync instead, so the log always
   rebuilds cleanly.
+- **An unhealable gap is dropped, not resynced forever.** A resync heals a gap
+  whose missing dependency is still in flight. But a *permanently*-orphaned update
+  (its dependency is gone for good) stays gappy through every resync, and a client
+  retransmitting it would loop endlessly (server resyncs → client resends →
+  repeat). After `gap_strike_limit` rejections of the same update on one
+  connection (default 3, minimum 2), the channel settles it with
+  `{ "ack" => id, "dropped" => true }` and drops it instead of resyncing again —
+  breaking the loop while never dropping a *healable* gap (those heal within a
+  resync or two, and healing frees the strike). The `dropped` flag lets the
+  client surface the loss (`yrby-client` reports it via `onError`) instead of
+  silently showing synced. Set `gap_strike_limit nil` to disable. Works on both
+  transports: plain ActionCable keeps strikes on the channel instance; under
+  AnyCable (fresh instance per RPC command) they persist through
+  anycable-rails' `state_attr_accessor` (istate), declared automatically when
+  anycable-rails is loaded.
 - **`on_change` is at-least-once, and the durable guarantee is that replaying the
   log reconstructs the document.** Every update triggers `on_change` before it's acked or
   broadcast (record-before-distribute). If exactly-once updates matter for you, **you

data/lib/y/action_cable/sync.rb

@@ -2,6 +2,7 @@
 
 require "y"
 require "base64"
+require "digest"
 
 module Y::ActionCable # rubocop:disable Style/ClassAndModuleChildren
   # y-websocket protocol over ActionCable.
@@ -51,8 +52,31 @@ module Y::ActionCable # rubocop:disable Style/ClassAndModuleChildren
     # allocation/parse cost. Override per channel with `max_frame_bytes`.
     DEFAULT_MAX_FRAME_BYTES = 8 * 1024 * 1024
 
+    # After this many times the *same* update is rejected as a causal gap on one
+    # connection, stop resyncing and instead settle it (ack) + drop it. A gap
+    # that survives repeated resyncs is unhealable — its missing dependency is
+    # gone for good (a permanently-orphaned pending struct) — and resyncing it
+    # forever just amplifies the client's retransmit loop. A healable gap heals
+    # within a resync or two, well under this. Override with `gap_strike_limit`;
+    # set to nil to disable (always resync). See `sync_gap_strike`.
+    DEFAULT_GAP_STRIKE_LIMIT = 3
+
+    # Cap on distinct gappy updates tracked per connection, so a client can't
+    # grow the strike table without bound by sending endless distinct gaps.
+    GAP_STRIKE_MAX_KEYS = 64
+
     def self.included(base)
       base.extend(ClassMethods)
+      # Durable strike state under AnyCable. Each AnyCable RPC command gets a
+      # fresh channel instance, so a plain ivar resets every message and the
+      # unhealable-gap drop would never trip. anycable-rails' state_attr_accessor
+      # persists the value into the subscription's istate, which anycable-go
+      # round-trips on every command — so strikes accumulate there too. On plain
+      # ActionCable (anycable-rails loaded but not serving) the accessor behaves
+      # like attr_accessor; without anycable-rails we fall back to an ivar.
+      # NOTE: anycable-rails must be loaded before the channel class is defined
+      # for this declaration to take effect (standard Bundler.require order).
+      base.state_attr_accessor :yrby_gap_strikes if base.respond_to?(:state_attr_accessor)
     end
 
     module ClassMethods
@@ -91,6 +115,24 @@ module Y::ActionCable # rubocop:disable Style/ClassAndModuleChildren
 
         superclass.respond_to?(:max_frame_bytes) ? superclass.max_frame_bytes : DEFAULT_MAX_FRAME_BYTES
       end
+
+      # Number of times the same update may be rejected as a gap on one
+      # connection before it is settled + dropped instead of resynced again.
+      # Defaults to DEFAULT_GAP_STRIKE_LIMIT; set to nil to always resync.
+      # A limit below 2 is rejected: strike 1 must send a resync (the heal
+      # attempt) before any drop, or a first-sight healable gap would be
+      # settled with no recovery ever attempted.
+      def gap_strike_limit(limit = :__unset__)
+        # Combined reader/writer; the sentinel keeps nil a real value (disables the drop).
+        unless limit == :__unset__
+          raise ArgumentError, "gap_strike_limit must be nil or >= 2 (got #{limit.inspect})" if limit && limit < 2
+
+          @gap_strike_limit = limit
+        end
+        return @gap_strike_limit if defined?(@gap_strike_limit)
+
+        superclass.respond_to?(:gap_strike_limit) ? superclass.gap_strike_limit : DEFAULT_GAP_STRIKE_LIMIT
+      end
     end
 
     # Call from `subscribed`. Streams broadcasts for this document and
@@ -172,11 +214,87 @@ module Y::ActionCable # rubocop:disable Style/ClassAndModuleChildren
     # is already present in the durable store.
     def sync_send_ack(id, outcome)
       return if id.nil?
-      return unless %i[recorded applied].include?(outcome)
+      # :dropped_unhealable settles a permanently-orphaned retry so the client
+      # stops retransmitting it (it was never going to integrate anywhere). The
+      # envelope carries "dropped" so the client can tell "durably recorded"
+      # from "abandoned" and surface it, instead of silently reporting synced
+      # over lost data. Clients that don't know the key ignore it.
+      return unless %i[recorded applied dropped_unhealable].include?(outcome)
 
       # The braces are required: a bare hash would bind to transmit's `via:`
       # keyword instead of its positional data argument.
-      transmit({ "ack" => id })
+      if outcome == :dropped_unhealable
+        transmit({ "ack" => id, "dropped" => true })
+      else
+        transmit({ "ack" => id })
+      end
+    end
+
+    # Count consecutive gap rejections of `update` on this connection, returning
+    # the new count. Keyed by update content (SHA-256) so independent gaps track
+    # separately — a slow-to-heal legit gap must not push an unrelated one toward
+    # the drop.
+    #
+    # Where the state lives:
+    # - Plain ActionCable reuses the channel instance across a connection's
+    #   messages, so an ivar accumulates (guarded by a mutex: ActionCable
+    #   dispatches messages to a worker pool, so two receives on one instance
+    #   can run concurrently).
+    # - Under AnyCable each RPC command gets a fresh instance, so the table is
+    #   persisted via anycable-rails' `state_attr_accessor` (istate), which
+    #   anycable-go round-trips on every command. See `self.included`.
+    def sync_gap_strike(update)
+      key = Digest::SHA256.hexdigest(update)
+      sync_gap_strike_mutex.synchronize do
+        strikes = sync_read_gap_strikes
+        # Bound the table so endless *distinct* gaps can't grow it without
+        # limit. Evict a single lowest-count entry, and only when inserting a
+        # genuinely new key: clearing wholesale would let a client cycling 64
+        # distinct gaps reset every tracked strike (defense bypass) and would
+        # starve a legitimate hot key.
+        if !strikes.key?(key) && strikes.size >= GAP_STRIKE_MAX_KEYS
+          strikes.delete(strikes.min_by { |_, count| count }.first)
+        end
+        strikes[key] = strikes.fetch(key, 0) + 1
+        sync_write_gap_strikes(strikes)
+        strikes[key]
+      end
+    end
+
+    # A gap that finally records has healed: free its strike slot so it can't
+    # bias a future eviction and the table reflects only live gaps.
+    def sync_clear_gap_strike(update)
+      sync_gap_strike_mutex.synchronize do
+        strikes = sync_read_gap_strikes
+        next_key = Digest::SHA256.hexdigest(update)
+        if strikes.key?(next_key)
+          strikes.delete(next_key)
+          sync_write_gap_strikes(strikes)
+        end
+      end
+    end
+
+    def sync_gap_strike_mutex
+      @sync_gap_strike_mutex ||= Mutex.new
+    end
+
+    # Strike-table storage: istate-backed under AnyCable (survives the
+    # per-command fresh instance), plain ivar otherwise. Values round-trip JSON
+    # under AnyCable, so the table is a plain Hash of hex-digest => Integer.
+    def sync_read_gap_strikes
+      if respond_to?(:yrby_gap_strikes)
+        (yrby_gap_strikes || {}).to_h { |k, v| [k.to_s, v.to_i] }
+      else
+        @gap_strikes || {}
+      end
+    end
+
+    def sync_write_gap_strikes(strikes)
+      if respond_to?(:yrby_gap_strikes=)
+        self.yrby_gap_strikes = strikes
+      else
+        @gap_strikes = strikes
+      end
     end
 
     # Single broadcast point so relay semantics live in one place and tests can
@@ -240,6 +358,20 @@ module Y::ActionCable # rubocop:disable Style/ClassAndModuleChildren
             "that never happened, and a cold load would lose the edit."
     end
 
+    # Fail closed when no document key is set (typically: AnyCable rebuilt the
+    # channel instance and the app forgot to pass `key` to sync_receive).
+    # Proceeding would record under nil, broadcast to a stream nobody
+    # subscribes to, and still ack — the client believes the edit was
+    # delivered when it reached no one.
+    def sync_validate_key!
+      return unless @sync_key.nil? || @sync_key.empty?
+
+      raise Y::Error,
+            "Y::ActionCable::Sync has no document key. Call sync_subscribed(key) in " \
+            "subscribed, and pass the key to sync_receive(data, key) when the transport " \
+            "doesn't keep the channel instance alive across actions (e.g. AnyCable)."
+    end
+
     # Stateless per message: any process can handle any document. A client's
     # SyncStep1 is answered from the store, document changes are recorded durably
     # before relay and then broadcast, and awareness is relayed best-effort.
@@ -247,9 +379,11 @@ module Y::ActionCable # rubocop:disable Style/ClassAndModuleChildren
     #
     # Returns an outcome symbol for the reliable-delivery ack: :recorded when a
     # document update was durably recorded and relayed, :gap when it was
-    # rejected for a resync, :noop for everything else.
+    # rejected for a resync, :dropped_unhealable when a repeatedly-gapped update
+    # is settled + dropped, :noop for everything else.
     def sync_handle_frame(encoded, bytes)
       sync_validate_required_hooks!
+      sync_validate_key!
 
       case Y.message_kind(bytes)
       when MSG_KIND_SYNC_STEP1
@@ -257,27 +391,7 @@ module Y::ActionCable # rubocop:disable Style/ClassAndModuleChildren
         sync_transmit(result[2])
         :noop
       when MSG_KIND_UPDATE
-        update = Y.update_from_message(bytes)
-        return :noop unless update
-
-        # Rebuild from the store (O(history) per update; snapshot in on_load if
-        # that cost bites).
-        doc = sync_load_doc
-
-        # Don't record a causally-incomplete update; resync instead so the gap
-        # heals as one complete delta.
-        unless doc.update_ready?(update)
-          sync_request_resync(doc)
-          return :gap
-        end
-
-        # Skip a lost-ack retry the store already has. Best-effort, not
-        # cross-process exactly-once (see "Delivery guarantees" in the README).
-        return :applied unless doc.update_advances?(update)
-
-        sync_record_change(update) # record before relay
-        sync_distribute(encoded)
-        :recorded
+        sync_handle_update(encoded, bytes)
       when MSG_KIND_AWARENESS
         sync_distribute(encoded)
         :noop
@@ -286,6 +400,49 @@ module Y::ActionCable # rubocop:disable Style/ClassAndModuleChildren
       end
     end
 
+    # The document-update arm of sync_handle_frame: gate on causal readiness
+    # (with the unhealable-gap strike defense), skip-but-rebroadcast retries,
+    # and record-before-distribute for genuinely new content.
+    def sync_handle_update(encoded, bytes)
+      update = Y.update_from_message(bytes)
+      return :noop unless update
+
+      # Rebuild from the store (O(history) per update; snapshot in on_load if
+      # that cost bites).
+      doc = sync_load_doc
+
+      # Don't record a causally-incomplete update; resync so the gap heals as
+      # one complete delta. But a gap that survives repeated resyncs is
+      # unhealable (its missing dependency is gone for good) — resyncing it
+      # forever just feeds the client's retransmit loop. After
+      # `gap_strike_limit` rejections of the same update, settle it (ack via
+      # the :dropped_unhealable outcome) and drop it instead.
+      unless doc.update_ready?(update)
+        limit = self.class.gap_strike_limit
+        if limit && sync_gap_strike(update) >= limit
+          sync_log_drop(:info, "dropping unhealable gappy update after #{limit} strikes")
+          return :dropped_unhealable
+        end
+        sync_request_resync(doc)
+        return :gap
+      end
+
+      # A lost-ack retry: already recorded, so skip on_change — but DO
+      # re-broadcast. If the first attempt died between record and broadcast,
+      # this retry is the only path left to the live subscribers. Duplicate
+      # broadcasts are free (CRDT apply is idempotent).
+      unless doc.update_advances?(update)
+        sync_clear_gap_strike(update) # a formerly-gappy update that healed
+        sync_distribute(encoded)
+        return :applied
+      end
+
+      sync_record_change(update) # record before relay
+      sync_clear_gap_strike(update) # a gap that finally recorded has healed
+      sync_distribute(encoded)
+      :recorded
+    end
+
     # Build a fresh document from the durable store (on_load). Callers validate
     # the hooks first, so on_load is present; a nil state means a fresh document.
     def sync_load_doc

data/lib/y/action_cable/version.rb

@@ -2,6 +2,6 @@
 
 module Y
   module ActionCable
-    VERSION = "0.2.3"
+    VERSION = "0.3.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yrby-actioncable
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.3.0
 platform: ruby
 authors:
 - JP Camara
@@ -29,14 +29,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.3.0
+        version: 0.3.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.3.0
+        version: 0.3.1
 - !ruby/object:Gem::Dependency
   name: actioncable
   requirement: !ruby/object:Gem::Requirement