yrby-actioncable 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c93259f7cd51c197d4203903e5f8b522e526e164a858f17992c538e0a0b1f6f4
-  data.tar.gz: 46289b0f4544899a64a23c40f44a998667b399f1a9f0b6cbc1c9cbd63e7d613d
+  metadata.gz: 827ae0b501facdd048905f0f61de31f54386cc9a22633b33abb4f2214b715329
+  data.tar.gz: aa6e35a4476d57b59f2d837723804e3f752b287ab2885af579497ae43650eb20
 SHA512:
-  metadata.gz: ab99efb5b5244556492419d8d646bd394f5e4f672729c1f6355571b0ab65c927122aa1833154150041fd550b0dc21a681a60f6bb5a952ac160fb05060e5609d5
-  data.tar.gz: 7d66edea6a44ba686d825da4d370d3e38be94a28c9df7aafea20ee9e506c31300d5011b94cb6d0fa2b62f0e3bfea2599984ec185503b96912fc037d58b8ae9cd
+  metadata.gz: bcaf23e4c38a919d41176fd3e21ff52f519964913b6cf19c927e5954955f4923d2641e80a636e7fa9077f53f6c0330d98df66420f8bd800ba6b6ec3997a35efd
+  data.tar.gz: 374dabb00df41e74e0d9060a2914c3c66355a702e448175a9c315628dd4030838c288ea6fcf5b3185b6999e57a31a61f52366867ef838a82735e87a7ce611261

data/CHANGELOG-actioncable.md

@@ -6,40 +6,26 @@ this project aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-07-01
+
+### Removed
+
+- The unhealable-gap strike defense that shipped in 0.3.0. That release was
+  published prematurely, before the feature had been reviewed; 0.3.1 supersedes
+  it with the defense removed while review happens. 0.3.0 remains installable
+  and functional; the feature returns in a future release once reviewed.
+
 ## [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).
+Published prematurely (see 0.3.1): shipped the unhealable-gap strike defense
+(settle + drop a repeatedly-gapped update, `{ "ack" => id, "dropped" => true }`,
+`gap_strike_limit`, istate-backed strikes under AnyCable) alongside the fixes
+below. The fixes carry forward; the defense was withdrawn in 0.3.1 pending
+review.
 
-### Fixed
+Fixes from a full source review:
 
-Fixes from a full source review (a 0.2.4 was prepared but never published; its
-changes ship here):
+### Fixed
 
 - **A lost-ack retry now re-broadcasts.** If the original attempt recorded the
   update and then crashed (or the pub/sub broadcast failed) before

data/README.md

@@ -242,21 +242,6 @@ 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,7 +2,6 @@
 
 require "y"
 require "base64"
-require "digest"
 
 module Y::ActionCable # rubocop:disable Style/ClassAndModuleChildren
   # y-websocket protocol over ActionCable.
@@ -52,31 +51,8 @@ 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
@@ -115,24 +91,6 @@ 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
@@ -214,87 +172,11 @@ module Y::ActionCable # rubocop:disable Style/ClassAndModuleChildren
     # is already present in the durable store.
     def sync_send_ack(id, outcome)
       return if id.nil?
-      # :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)
+      return unless %i[recorded applied].include?(outcome)
 
       # The braces are required: a bare hash would bind to transmit's `via:`
       # keyword instead of its positional data argument.
-      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
+      transmit({ "ack" => id })
     end
 
     # Single broadcast point so relay semantics live in one place and tests can
@@ -379,8 +261,7 @@ 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, :dropped_unhealable when a repeatedly-gapped update
-    # is settled + dropped, :noop for everything else.
+    # rejected for a resync, :noop for everything else.
     def sync_handle_frame(encoded, bytes)
       sync_validate_required_hooks!
       sync_validate_key!
@@ -391,7 +272,32 @@ module Y::ActionCable # rubocop:disable Style/ClassAndModuleChildren
         sync_transmit(result[2])
         :noop
       when MSG_KIND_UPDATE
-        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 instead so the gap
+        # heals as one complete delta.
+        unless doc.update_ready?(update)
+          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_distribute(encoded)
+          return :applied
+        end
+
+        sync_record_change(update) # record before relay
+        sync_distribute(encoded)
+        :recorded
       when MSG_KIND_AWARENESS
         sync_distribute(encoded)
         :noop
@@ -400,49 +306,6 @@ 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.3.0"
+    VERSION = "0.3.1"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yrby-actioncable
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - JP Camara