yrb-lite-actioncable 0.1.0.beta3 → 0.1.0.beta5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2a29ee03d2c3eb1dd68e3b6be4ffc8d57f7c244c6ace2b4edcc715467f525d60
-  data.tar.gz: c80b92042a593af7bc9cf22233032af3ca783c507a7a2df2cce052501aadfcd2
+  metadata.gz: 8d48432476f4a644c91c193f72d6857aa5ce6bb0f2ded537b3277d31e8c49cfb
+  data.tar.gz: e28d77164e95bbba949133989f11555015160f39786a0c17bab9acacaaf05570
 SHA512:
-  metadata.gz: 2687a09e9f83d54240f6b9fc6c40858a30864b8912e2dc8b146a70bc95f5069933efe3ed5643fada439ecdafeb0c392c8edfaff147b38ab67dd206378db9f373
-  data.tar.gz: 39f410248b09f295d83a8621e7a7cdada6661fa9aa2b81fc967b75838a878a84583f1e3ec7e6dcf9f300ed840f32eca62c8b4d1cc13ab874efb2fc753cb47523
+  metadata.gz: d69b40149fccf8d84d8fc4cbfffe7f9ce4309a47e9971bbb0c65befc9bed6a5827d2251caa807da6da5b2b5b7f3ef13c4c8659d2856868848df13748deed77d2
+  data.tar.gz: a8babf32c1f72b70ff9f3e551c826b62306dd446ee86d44d09b71b5f5164b4c0817328a5ad14e16bcbc0134f1fc4a20624d59abc13a75766292d1a567933e432

data/CHANGELOG-actioncable.md

@@ -5,50 +5,3 @@ format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 this project aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
-
-## [0.1.0.beta3] - 2026-06-22
-
-### Changed
-
-- Document streams and awareness streams are separate under AnyCable. Document
-  streams are normal server-relayed streams; awareness streams are subscribed
-  with `whisper: true` and carry only ephemeral presence frames.
-- The channel accepts and emits the canonical document envelope,
-  `{ "update" => "<base64 frame>" }`. Accepted document updates carrying an
-  `"id"` are acknowledged with `{ "ack" => id }`.
-- Removed the backend switch. `YrbLite::ActionCable::Sync` is always
-  store-backed and fails closed unless both `on_load` and `on_change` are
-  configured, so acknowledgements always mean the update is durably recorded.
-- Requires `yrb-lite >= 0.1.0.beta6` (uses the new `update_advances?` and
-  wire client-id frame validation).
-
-## [0.1.0.beta2] - 2026-06-20
-
-### Added
-
-- Automatic AnyCable whispering for awareness/presence. When running under
-  AnyCable, the channel now enables client-to-client whispering on its stream
-  (`stream_from key, whisper: true`), so a client that whispers awareness has its
-  presence frames broadcast directly to other subscribers with no server
-  round-trip. It's automatic -- no configuration -- and a no-op on plain
-  ActionCable (no whisper support), where presence stays server-relayed. Document
-  updates are never whispered.
-
-## [0.1.0.beta1] - 2026-06-18
-
-### Added
-
-- Initial release, extracted from `yrb-lite` (which shipped this as
-  `YrbLite::Sync` through 0.1.0.beta4). Provides `YrbLite::ActionCable::Sync`, an
-  ActionCable channel concern implementing the y-websocket sync protocol and
-  awareness/presence over ActionCable and AnyCable: record-before-distribute
-  auditing (`on_change`), persistence hooks, presence reaping, idle-document
-  eviction, and multi-process replica sync. Depends on `yrb-lite`
-  (>= 0.1.0.beta5) for the CRDT documents, awareness, and protocol primitives.
-- `on_change` recorders run in the channel instance's context (carried over from
-  `yrb-lite` 0.1.0.beta4), so a recorder can call the channel's own methods
-  directly.
-
-[Unreleased]: https://github.com/jpcamara/yrb-lite/commits/main
-[0.1.0.beta2]: https://github.com/jpcamara/yrb-lite/commits/main
-[0.1.0.beta1]: https://github.com/jpcamara/yrb-lite/releases/tag/v0.1.0.beta5

data/README.md

@@ -19,12 +19,12 @@ end
 
 On the browser, use the `yrb-lite-client` `ActionCableProvider`. Tiptap,
 ProseMirror, and BlockNote all sync through the `Y.Doc` you pass in and the
-provider's Awareness instance, unless you supply your own.
+provider's Awareness instance.
 
 ## What you get
 
-- Thread-safe Ruby wrappers for `Doc` and `Awareness`. You can share them
-  across Puma threads; native CRDT work runs with the GVL released.
+- A thread-safe Ruby `Doc` you can share across Puma threads; native CRDT work
+  runs with the GVL released.
 - The y-websocket protocol (document sync plus awareness/presence) as a
   one-include ActionCable concern.
 - Store-backed ActionCable/AnyCable delivery for multi-process deployments.
@@ -86,11 +86,7 @@ require "yrb_lite"
 
 # Create docs
 doc = YrbLite::Doc.new        # random client ID
-doc = YrbLite::Doc.new(12345) # specific client ID
-
-# Get document info
-doc.client_id  # => unique client identifier
-doc.guid       # => document GUID
+doc = YrbLite::Doc.new(12345) # specific client ID (used for CRDT identity)
 
 # Encoding
 doc.encode_state_vector           # => current state vector
@@ -100,36 +96,23 @@ doc.encode_state_as_update(sv)    # => update diff against state vector
 # Applying updates
 doc.apply_update(update_bytes)    # apply raw V1 update
 
-# Sync protocol messages
-doc.sync_step1                    # => SyncStep1 message (contains state vector)
-doc.sync_step2(state_vector)      # => SyncStep2 message (contains update)
-doc.handle_sync_message(data)     # => [msg_type, sync_type, response]
-doc.encode_update_message(update) # => wrap update as sync Update message
+# Sync protocol
+doc.sync_step1                    # => SyncStep1 message (this doc's state vector)
+doc.handle_sync_message(data)     # => [msg_type, sync_type, response]; answers a
+                                  #    peer's SyncStep1 with a SyncStep2
 ```
 
-### Awareness (Document + Presence)
-
-```ruby
-# Create awareness instances (each contains a Doc)
-awareness = YrbLite::Awareness.new        # random client ID
-awareness = YrbLite::Awareness.new(12345) # specific client ID
-
-# Get document info
-awareness.client_id  # => unique client identifier
-awareness.guid       # => document GUID
-```
+### Protocol codec (module functions)
 
-### Handling Sync Messages
+Classifying and unwrapping wire frames is stateless, so it's exposed as
+`YrbLite` module functions rather than a class. The server never holds presence
+or document state to route a frame — presence lives in the browser clients, and
+the server only relays awareness frames opaquely.
 
 ```ruby
-# When connection opens, send initial sync messages
-initial_message = awareness.start
-# Send initial_message to peer via WebSocket
-
-# When receiving messages from peer
-response = awareness.handle(incoming_data)
-# Send response back to peer if not empty
-send_to_peer(response) unless response.empty?
+YrbLite.message_kind(frame)         # => 0 drop / 1 step1 / 2 update / 3 awareness / 4 query
+YrbLite.update_from_message(frame)  # => the document delta carried by a frame, or nil
+YrbLite.wrap_update(update_bytes)   # => wrap a raw doc update as a sync Update frame
 ```
 
 ### ActionCable Integration
@@ -178,6 +161,34 @@ oversized, or unknown frames are dropped. A bad frame can't crash the process: a
 Rust panic is caught at the FFI boundary and re-raised as a Ruby exception. And
 no single client can relay garbage that breaks the others in a room.
 
+#### Delivery guarantees
+
+The contract is the same at every scale — one process, or hundreds across many
+servers:
+
+- **The document always converges.** CRDT updates are commutative and
+  idempotent, so out-of-order, duplicate, or concurrent delivery all converge to
+  the same correct document. This needs no coordination and holds everywhere.
+- **The durable log never goes gappy.** An update is recorded only once its
+  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.
+- **`on_change` is at-least-once, and the durable guarantee is that replaying the
+  log reconstructs the document.** Every change is recorded before it's acked or
+  broadcast (record-before-distribute). Entry count is not 1:1 with edits: a
+  best-effort check skips most lost-ack retries but isn't cross-process exact (a
+  retry on another process can record the same update twice), and a resync can
+  coalesce a client's un-acked tail into a single record. So **make `on_change`
+  idempotent** if duplicate side effects would matter (a webhook, a counter) — a
+  raw append-only delta log is naturally fine, since it replays to the same
+  document either way.
+
+There is deliberately no in-gem cross-process lock. One that only spanned a
+single process would give exactly-once at small scale and silently degrade as
+you scale out, so the guarantee is uniform instead. If you need exactly-once
+*side effects*, enforce it in your store (a unique key on the update) or with
+your own distributed lock — the gem stays storage-agnostic and assumes neither.
+
 #### Multi-process deployments
 
 Most Rails apps run several processes (Puma workers, multiple dynos), and any of
@@ -295,43 +306,15 @@ one `{ ack: id }` cumulatively confirms everything up to it. Because CRDT apply
 is idempotent, a resend that already landed is a harmless no-op that just
 re-acks. Awareness stays ephemeral and is not acked.
 
-### User Awareness/Presence
-
-```ruby
-# Set local user state (cursor position, name, etc.)
-awareness.set_local_state('{"user": {"name": "Alice", "color": "#ff0000"}}')
-
-# Get local state
-awareness.local_state  # => '{"user": {"name": "Alice", "color": "#ff0000"}}'
-
-# Clear local state (e.g., when disconnecting)
-awareness.clear_local_state
-
-# Encode awareness update for broadcasting
-update = awareness.encode_awareness_update
-```
-
-### Low-Level Access
-
-```ruby
-# Get state vector for manual sync
-sv = awareness.encode_state_vector
-
-# Get update diffed against a state vector
-update = awareness.encode_state_as_update(remote_state_vector)
-
-# Apply raw update to the document
-awareness.apply_update(update_bytes)
-
-# Wrap raw update data in a sync message
-message = awareness.encode_update(update_bytes)
-```
+Presence (cursors, selections) is owned by the browser clients — the server
+never sets or holds presence state, it only relays awareness frames opaquely.
+See `yrb-lite-client` for the client-side awareness API.
 
 ## Thread Safety
 
-`Doc` and `Awareness` are safe to share across Ruby threads. A `Doc` or
-`Awareness` can be used concurrently from Puma workers, ActionCable connection
-threads, or background jobs without external locking.
+A `Doc` is safe to share across Ruby threads — used concurrently from Puma
+workers, ActionCable connection threads, or background jobs without external
+locking.
 
 That comes from how the underlying types work, not from locking on top:
 

data/lib/yrb_lite/action_cable/sync.rb

@@ -41,15 +41,12 @@ module YrbLite::ActionCable # rubocop:disable Style/ClassAndModuleChildren
   # validated against `on_load`, recorded through `on_change`, then broadcast.
   # No authoritative document state is kept in ActionCable process memory.
   module Sync
-    # Validated frame kinds from Awareness#message_kind. A frame only gets a
-    # non-DROP kind if it is exactly one well-formed message; anything
-    # malformed, truncated, multi-message, or unknown is dropped before it can
-    # be processed or relayed.
-    MSG_KIND_DROP = 0
+    # Frame kinds we act on, from Awareness#message_kind. The other codes it can
+    # return -- 0 (drop: malformed/truncated/multi-message/unknown) and 4
+    # (awareness query) -- fall through to a no-op in the dispatch below.
     MSG_KIND_SYNC_STEP1 = 1
     MSG_KIND_UPDATE = 2
     MSG_KIND_AWARENESS = 3
-    MSG_KIND_AWARENESS_QUERY = 4
 
     # Default incoming-frame size cap (decoded bytes). Generous enough for a
     # large initial SyncStep2, small enough to bound a single message's
@@ -61,10 +58,11 @@ module YrbLite::ActionCable # rubocop:disable Style/ClassAndModuleChildren
     end
 
     module ClassMethods
-      # Load persisted document state. Called once per key with (key);
-      # return a binary Y.js update (or nil for a fresh document).
-      def on_load(callable = nil, &block)
-        @on_load = callable || block if callable || block
+      # Load persisted document state. Called once per key with (key); return a
+      # binary Y.js update (or nil for a fresh document). The block runs in the
+      # channel instance's context, the same as on_change (see below).
+      def on_load(&block)
+        @on_load = block if block
         return @on_load if defined?(@on_load) && @on_load
 
         superclass.respond_to?(:on_load) ? superclass.on_load : nil
@@ -75,13 +73,12 @@ module YrbLite::ActionCable # rubocop:disable Style/ClassAndModuleChildren
       # the exact CRDT delta. If the block raises, the change is rejected:
       # neither acknowledged nor broadcast to other subscribers.
       #
-      # A block recorder runs in the *channel instance's* context, so it can
-      # call the channel's own methods (current_user, params, a per-connection
-      # Current.* accessor) directly, with no thread-local plumbing. (A non-Proc
-      # callable is invoked with #call instead, since it carries its own
-      # context.) on_change always fires from within sync_receive.
-      def on_change(callable = nil, &block)
-        @on_change = callable || block if callable || block
+      # The block runs in the *channel instance's* context (via instance_exec),
+      # so it can call the channel's own methods (current_user, params, a
+      # per-connection Current.* accessor) directly, with no thread-local
+      # plumbing. on_change always fires from within sync_receive.
+      def on_change(&block)
+        @on_change = block if block
         return @on_change if defined?(@on_change) && @on_change
 
         superclass.respond_to?(:on_change) ? superclass.on_change : nil
@@ -106,8 +103,11 @@ module YrbLite::ActionCable # rubocop:disable Style/ClassAndModuleChildren
       @sync_origin = SecureRandom.hex(8)
       sync_require_store_recorder!
 
-      sync_stream sync_stream_name
-      sync_stream sync_awareness_stream_name, whisper: true if respond_to?(:whispers_to)
+      # The document stream is never whisper-enabled; under AnyCable we also
+      # subscribe an awareness stream with `whisper: true`, scoping the client-to-
+      # client path to ephemeral presence rather than the durable document stream.
+      stream_from sync_stream_name
+      stream_from sync_awareness_stream_name, whisper: true if respond_to?(:whispers_to)
       sync_transmit(sync_load_doc.sync_step1)
     end
 
@@ -145,18 +145,11 @@ module YrbLite::ActionCable # rubocop:disable Style/ClassAndModuleChildren
 
       return if cap && bytes.bytesize > cap
 
-      sync_send_ack(id, sync_dispatch(encoded, bytes))
+      sync_send_ack(id, sync_handle_frame(encoded, bytes))
     end
 
-    # Route a decoded frame to the backend/path that handles it and return the
-    # outcome symbol (:recorded/:applied/:gap/:noop) used by the reliable-
-    # delivery ack. A dropped frame returns nil (never acked).
-    def sync_dispatch(encoded, bytes)
-      sync_receive_store_backed(encoded, bytes)
-    end
-
-    # Kept as the ActionCable lifecycle hook target. There is no cached document
-    # or server-owned presence state to clean up in the store-backed design.
+    # The `unsubscribed` hook target. Nothing to clean up: the server keeps no
+    # per-connection document or presence state.
     def sync_unsubscribed(key = nil)
       @sync_key = key.to_s if key
     end
@@ -201,7 +194,6 @@ module YrbLite::ActionCable # rubocop:disable Style/ClassAndModuleChildren
       transmit(sync_envelope(Base64.strict_encode64(bytes)))
     end
 
-    # Build an outgoing envelope.
     def sync_envelope(encoded, extra = {})
       { "update" => encoded }.merge(extra)
     end
@@ -223,53 +215,44 @@ module YrbLite::ActionCable # rubocop:disable Style/ClassAndModuleChildren
             "that never happened, and a cold load would lose the edit."
     end
 
-    # Subscribe to a broadcast stream. The document stream is never whisper-
-    # enabled; when AnyCable is present we separately subscribe an awareness
-    # stream with `whisper: true`, so the client-to-client path is scoped to
-    # ephemeral presence instead of the durable document stream.
-    def sync_stream(name, **, &)
-      stream_from(name, **, &)
-    end
-
-    # Stateless per message: no warm replica, no assumptions about which process
-    # owns a 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. Echoing back to the sender is harmless,
-    # since the CRDT apply is idempotent.
+    # 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.
+    # Echoing back to the sender is harmless, since the CRDT apply is idempotent.
     #
     # 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.
-    def sync_receive_store_backed(encoded, bytes)
+    def sync_handle_frame(encoded, bytes)
       sync_require_store_recorder!
 
-      case Sync.codec.message_kind(bytes)
+      case YrbLite.message_kind(bytes)
       when MSG_KIND_SYNC_STEP1
         result = sync_load_doc.handle_sync_message(bytes)
         sync_transmit(result[2]) if result
         :noop
       when MSG_KIND_UPDATE
-        update = Sync.codec.update_from_message(bytes)
+        update = YrbLite.update_from_message(bytes)
         return :noop unless update
 
-        Sync.lock_for(@sync_key).synchronize do
-          # To tell whether this update is causally ready we rebuild the doc
-          # from the store and check against it. That's an O(history) load per
-          # update, mitigated by snapshotting in the app's load path if needed.
-          doc = sync_load_doc
-          unless doc.update_ready?(update)
-            sync_request_resync(doc)
-            next :gap
-          end
-
-          # Lost-ack retry: the durable store already contains this update.
-          # Ack it without recording or relaying again.
-          next :applied unless doc.update_advances?(update)
-
-          sync_record_change(self.class.on_change, update) # record before relay
-          sync_distribute(encoded)
-          :recorded
+        # 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(self.class.on_change, update) # record before relay
+        sync_distribute(encoded)
+        :recorded
       when MSG_KIND_AWARENESS
         sync_distribute(encoded)
         :noop
@@ -281,7 +264,8 @@ module YrbLite::ActionCable # rubocop:disable Style/ClassAndModuleChildren
     # Build a fresh document from the durable store (on_load).
     def sync_load_doc
       doc = YrbLite::Doc.new
-      state = self.class.on_load&.call(@sync_key)
+      loader = self.class.on_load
+      state = instance_exec(@sync_key, &loader) if loader
       doc.apply_update(state) if state
       doc
     end
@@ -294,19 +278,14 @@ module YrbLite::ActionCable # rubocop:disable Style/ClassAndModuleChildren
       "#{sync_stream_name}:awareness"
     end
 
-    # Invoke the on_change recorder. A block/proc runs in this channel instance's
-    # context (instance_exec) so it can reach the channel's own methods; a
-    # non-Proc callable is invoked with #call, since it carries its own context.
+    # Invoke the on_change recorder in this channel instance's context
+    # (instance_exec) so it can reach the channel's own methods.
     def sync_record_change(recorder, update)
-      args = [@sync_key, update]
-      recorder.is_a?(Proc) ? instance_exec(*args, &recorder) : recorder.call(*args)
+      instance_exec(@sync_key, update, &recorder)
     end
 
     # -- Shared process state ----------------------------------------------
 
-    @locks = {}
-    @registry_mutex = Mutex.new
-
     class << self
       # A stable id for this server process, stamped on every broadcast so
       # other processes know to apply it to their replica and this process
@@ -314,29 +293,6 @@ module YrbLite::ActionCable # rubocop:disable Style/ClassAndModuleChildren
       def process_id
         @process_id ||= SecureRandom.hex(8)
       end
-
-      # A shared, stateless decoder for the store-backed path. message_kind and
-      # update_from_message only read their argument (they don't touch the
-      # instance's document), so one shared instance is safe across threads.
-      def codec
-        @codec ||= YrbLite::Awareness.new
-      end
-
-      # Per-document mutex serializing load -> record -> broadcast within this
-      # process. The durable store remains the cross-process source of truth.
-      # Only briefly holds the registry mutex to fetch/create the lock; the
-      # durable write itself runs while holding only this per-key lock.
-      def lock_for(key)
-        @registry_mutex.synchronize { @locks[key] ||= Mutex.new }
-      end
-
-      # Clear process-local locks and codec (useful for testing).
-      def reset!
-        @registry_mutex.synchronize do
-          @locks = {}
-          @codec = nil
-        end
-      end
     end
   end
 end

data/lib/yrb_lite/action_cable/version.rb

@@ -2,6 +2,6 @@
 
 module YrbLite
   module ActionCable
-    VERSION = "0.1.0.beta3"
+    VERSION = "0.1.0.beta5"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yrb-lite-actioncable
 version: !ruby/object:Gem::Version
-  version: 0.1.0.beta3
+  version: 0.1.0.beta5
 platform: ruby
 authors:
 - JP Camara
@@ -29,14 +29,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.0.beta6
+        version: 0.1.0.beta9
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.0.beta6
+        version: 0.1.0.beta9
 - !ruby/object:Gem::Dependency
   name: actioncable
   requirement: !ruby/object:Gem::Requirement