y-ruby-actioncable 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f6045cee5c0df8e1173a6826135235f0ff4b1051a94fab0443445477ad2e883e
+  data.tar.gz: f2307d757c48a851ae47277880b40a16ffbd8994cb9f7a3ed8a32e11e11c7c4d
+SHA512:
+  metadata.gz: 9c881cc8349796218c3507a9294c824321496fddb9861b05533b329f30017a10aca01bc0287de0952e018e3ecc405f08771232b7d8ab4c3e0021c98165a9a505
+  data.tar.gz: 9b8f5adaebc6d6c48e5e062a18e7e24eed6a0e63620b561b4ecf2b42157afb41e8dccab829eb4fc9d41e440ba4f37070654ea8a31c3210b5a87af63fe2920034

data/CHANGELOG-actioncable.md

@@ -0,0 +1,23 @@
+# Changelog — y-ruby-actioncable
+
+All notable changes to the `y-ruby-actioncable` gem are documented here. The
+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.2.0] - 2026-06-28
+
+First release under the **`y-ruby-actioncable`** name (previously developed as
+`yrb-lite-actioncable`).
+
+### Changed
+- **Renamed `yrb-lite-actioncable` → `y-ruby-actioncable`.** Channel concern
+  `YrbLite::ActionCable::Sync` → **`Y::ActionCable::Sync`**; require
+  `require "yrb_lite/action_cable"` → `require "y/action_cable"`. ActionCable
+  stream prefix `yrb_lite:` → `y_ruby:`. Depends on `y-ruby >= 0.2.0`.
+
+### Notes
+- Full y-websocket protocol over ActionCable/AnyCable: origin-filtered relay,
+  awareness, on_load/on_save persistence hooks, optional record-before-distribute
+  audit mode, and AnyCable `sync_backend :store`.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,413 @@
+# y-ruby
+
+[![CI](https://github.com/jpcamara/y-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/jpcamara/y-ruby/actions/workflows/ci.yml)
+
+Collaborative editing for Rails, backed by [y-crdt](https://github.com/y-crdt/y-crdt)
+(the Rust library behind Y.js). Your Rails server speaks the y-websocket sync
+protocol directly, so there's no separate Node process hosting the Y.js
+documents.
+
+```ruby
+class DocumentChannel < ApplicationCable::Channel
+  include Y::ActionCable::Sync
+
+  on_load   { |key|         MyStore.load(key) }
+  on_change { |key, update| MyStore.append(key, update) }
+
+  def subscribed    = sync_subscribed(params[:id])
+  def receive(data) = sync_receive(data, params[:id])
+end
+```
+
+On the browser, use the `ActionCableProvider` from the 
+[`@y-ruby/client`](https://www.npmjs.com/package/@y-ruby/client) npm package.
+Integrates with any editor that includes Y.js support, such as Tiptap, ProseMirror
+and [Lexxy](https://www.npmjs.com/package/lexxy-realtime).
+
+## Usage
+
+Install the gem and npm package:
+
+```
+gem install y-ruby-actioncable # depends on y-ruby
+npm install @y-ruby/client
+```
+
+## What you get
+
+- A thread-safe Ruby `Doc` you can share across Ruby threads/fibers, and native CRDT work
+  runs with the GVL released.
+- The y-websocket protocol (document sync plus awareness/presence) as a
+  one-include ActionCable concern.
+- Authoritative record-before-distribute semantics: each document change can be
+  recorded durably before it goes out to anyone.
+- 
+
+## Why "lite"
+
+The "lite" is the size of the surface. `y-ruby` binds just the part of `y-crdt` you
+need to *sync and persist* collaborative documents - a `Doc`, awareness, and the
+y-websocket protocol primitives. The Ruby side treats a document as opaque CRDT
+state: it applies updates, answers sync handshakes, and records deltas, but never
+reaches in to read or edit the contents. The browser editor owns the document's
+shape.
+
+## What isn't "lite"
+
+The surface area may be "lite", but a core focus is on durability, resiliency, delivery
+guarantees, correctness, and thread safety.
+
+Towards that goal, `y-ruby` adds capabilities that may even stand out in the Yjs ecosystem:
+
+- Built-in update acknowledgement: the `ActionCableProvider` in `@y-ruby/client` will continue to
+  send updates until an ack is received from the server. [`y-ruby-actioncable`](https://rubygems.org/gems/y-ruby-actioncable)
+  only sends an ack when applying an update is successful. The goal is at-least-once delivery,
+  and because CRDTs are idempotent a duplicate update is effectively a no-op.
+- Gap detection in document updates: before applying an update and sending an ack to the client,
+  `y-ruby` checks whether the update results in any causal gap. Ie, an update comes through
+  which depends on a previous update that is not yet present in the document. This can result in
+  a document stuck with "pending" updates, which will _never_ apply if the missing update is not sent.
+  To avoid this, `y-ruby` does not apply the update, and starts a new y-protocol sync with the client.
+  That will cause the client to synchronize its document with the server, sending through any updates
+  that may have been missed
+
+## What about [yrb](https://github.com/y-crdt/yrb)?
+
+`yrb` has a much larger interface that gives you most of the Yjs type system - 
+shared text, arrays, maps, XML - to build and query documents in Ruby. It was a great
+inspiration for my use of Yjs in Ruby/Rails, and I originally considered building
+on top of it. There are a few reasons I went with `y-ruby` instead:
+
+- `yrb` is largely unmaintained. It was built as an experiment for GitLab, and the original
+  author mostly moved onto other projects.
+- [It isn't thread-safe](https://github.com/y-crdt/yrb/issues/72). It segfaults in a threaded
+  environment (such as ActionCable...)
+- It's a much larger set of features to maintain, which most people don't need. The vast
+  majority of people manipulate Y.js documents in the browser, not from a server-side language.
+
+## Testing
+
+Ruby and Rust unit tests cover the core. CI also runs the npm client tests and a
+Rails demo smoke slice against the real ActionCable stack. The demo includes
+heavier local suites for hostile input, crash recovery, multi-browser editing,
+AnyCable, and load testing. The benchmark note below is from a single laptop.
+Issues and PRs are welcome.
+
+## Install
+
+```ruby
+# Core CRDT + protocol primitives:
+gem "y-ruby"
+
+# For the Rails/ActionCable server concern (Y::ActionCable::Sync):
+gem "y-ruby-actioncable"
+```
+
+Requires Ruby 3.4 or newer. The release workflow builds precompiled gems for
+Ruby 3.4 and 4.0 across the supported Ruby platforms, with native smoke tests
+on Linux x86_64 and macOS arm64. Installing from a matching platform gem needs
+no Rust; a source build needs [Rust](https://rustup.rs).
+
+To work on the gem itself:
+
+```bash
+git clone https://github.com/jpcamara/y-ruby
+cd y-ruby
+bundle install
+bundle exec rake compile test
+```
+
+The rest of the dev setup, plus the demo, is in [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Docs
+
+- The ActionCable concern and a quickstart are [below](#actioncable-integration).
+- [`examples/actioncable-demo`](examples/actioncable-demo): a runnable Rails +
+  Tiptap app with collaborative cursors, the AnyCable setup, a Postgres store,
+  and the test/load suites.
+- [CHANGELOG.md](CHANGELOG.md) and [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Usage
+
+### Doc (Low-Level Document Sync)
+
+```ruby
+require "y"
+
+# Create docs
+doc = Y::Doc.new        # random client ID
+doc = Y::Doc.new(12345) # specific client ID (used for CRDT identity)
+
+# Encoding
+doc.encode_state_vector           # => current state vector
+doc.encode_state_as_update        # => full update
+doc.encode_state_as_update(sv)    # => update diff against state vector
+
+# Applying updates
+doc.apply_update(update_bytes)    # apply raw V1 update
+
+# 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
+```
+
+### Protocol codec (module functions)
+
+Classifying and unwrapping wire frames is stateless, so it's exposed as
+`Y` 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
+Y.message_kind(frame)         # => 0 drop / 1 step1 / 2 update / 3 awareness / 4 query
+Y.update_from_message(frame)  # => the document delta carried by a frame, or nil
+Y.wrap_update(update_bytes)   # => wrap a raw doc update as a sync Update frame
+```
+
+### ActionCable Integration
+
+`Y::ActionCable::Sync` (from the `y-ruby-actioncable` gem) is a channel
+concern that implements the full y-websocket protocol (document sync +
+awareness/presence) over ActionCable:
+
+```ruby
+# app/channels/document_channel.rb
+class DocumentChannel < ApplicationCable::Channel
+  include Y::ActionCable::Sync
+
+  on_load { |key| MyStore.load(key) }                 # source of truth
+  on_change { |key, update| MyStore.append(key, update) } # durable record
+
+  def subscribed
+    sync_subscribed params[:id]
+  end
+
+  def receive(data)
+    sync_receive(data, params[:id])
+  end
+end
+```
+
+The concern is store-backed. A handshake is answered from `on_load`; document
+changes are checked against that durable state, recorded through `on_change`,
+then broadcast. Nothing authoritative is kept in ActionCable process memory, so
+AnyCable RPC workers, Puma workers, and separate dynos can all handle messages
+for the same document as long as they share the same store and cable adapter.
+
+`on_load` and `on_change` are required. If either is missing, the channel fails 
+before it can acknowledge or broadcast edits. Presence is ephemeral:
+awareness frames are relayed, and `@y-ruby/client` sends a best-effort
+presence-removal frame on disconnect/pagehide, with the client-side awareness
+timeout as the fallback for abrupt disconnects.
+
+Incoming frames are validated as a single well-formed protocol message before
+anything processes or relays them. Malformed, truncated, multi-message,
+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 update triggers `on_change` before it's acked or
+  broadcast (record-before-distribute). If exactly-once updates matter for you, **you
+  must make `on_change` idempotent**. But remember that the CRDT can handle duplicates.
+- **A raising `on_change` rejects the update implicitly.** If the block raises,
+  the update is neither acked nor broadcast (record-before-distribute stops both).
+  There is no negative-ack: the client simply never receives the ack, keeps the
+  update pending, and retransmits on its timer/reconnect. This is built for
+  *transient* failures (the store is briefly down → a retry lands). A block that
+  raises *deterministically* — a validation that always fails for this edit —
+  will be retried forever, since nothing tells the client to stop. Enforce hard
+  rejections before the edit reaches `on_change` (channel authorization in
+  `subscribed`), not by raising inside it.
+- **An over-cap frame is dropped the same silent way.** A frame larger than
+  `max_frame_bytes` (default 8 MiB) is dropped before decoding — no ack, no
+  broadcast — to bound the work a client can force. For a genuine document
+  update that means the same implicit rejection as above: unacked, retransmitted
+  forever. Normal typing never approaches the cap, but a large paste, an embedded
+  image, or a big initial `SyncStep2` can. The drop is logged (`warn` for
+  over-cap, `debug` for undecodable) with the document key and update id so it's
+  findable; override `sync_log_context` on the channel to add a user/connection
+  id. Size the cap for your largest expected payload, and reject
+  genuinely-too-big content upstream rather than relying on the cap to reject it
+  gracefully.
+
+#### Multi-process deployments
+
+Most Rails apps run several processes, and any of them might serve a given document. 
+Two pieces keep them in step.
+
+Broadcasts cross processes through the Action Cable adapter, so it needs to something
+like `redis` or `solid_cable`, not `async`. With that in place, a change
+on one process reaches clients on all of them.
+
+Every process rebuilds document state from the durable store through `on_load`.
+Because changes are recorded before broadcast, record-before-distribute holds
+across processes: whichever process receives a change records it to the shared
+store before anyone, anywhere, sees it.
+
+`bun multiprocess.mjs` in the demo runs clients across two processes and checks
+convergence, fresh reads on both, presence across processes, and one shared log.
+
+##### AnyCable
+
+`y-ruby` fully supports AnyCable.
+
+The demo checks this against a real anycable-go + RPC server
+(`frontend/anycable_probe.mjs`, `anycable_concurrent.mjs`): liveness, the
+y-ruby client provider, cross-process reads, and concurrent convergence.
+
+##### Demo
+
+[`examples/actioncable-demo`](examples/actioncable-demo) is a full Rails + Tiptap
+app using the y-ruby provider, with end-to-end tests.
+
+#### Record Before Distribute
+
+Every document change is handed to the `on_change` handler before broadcasting.
+It is up to you to durably record it:
+
+```ruby
+class DocumentChannel < ApplicationCable::Channel
+  include Y::ActionCable::Sync
+
+  # ...
+
+  on_change do |key, update|
+    # Synchronous, durable write. `update` is the exact CRDT delta.
+    AuditLog.append!(key, update)   # raise to REJECT the change
+  end
+
+  # ...
+end
+```
+
+If the recorder raises (say the store is down), the change is rejected: not
+applied, not sent to anyone. The cost is a synchronous durable write on the path
+of every change. There's no in-gem per-document lock; concurrent writes to one
+document can both record (at-least-once), and since CRDT apply is idempotent a
+duplicate record replays to the same document.
+
+The demo wires `on_change` to a durable Postgres-backed log by default, and checks
+end to end that the log alone rebuilds the document.
+
+#### Reliable delivery (acks)
+
+y-ruby document delivery is ack-tracked. Browser document updates carry an
+`"id"`, and the server replies `{ "ack": <id> }` once `on_change` has succesfully fired.
+A causally-gapped update is not acked; the server sends a resync request, and
+the client keeps the update queued until it lands.
+
+```
+client -> server   { "update": "<base64 update>", "id": 42 }
+server -> client   { "ack": 42 }     # update accepted; safe to forget
+```
+
+`@y-ruby/client`'s `ActionCableProvider` handles this automatically. It keeps
+the unacknowledged local document tail in a queue and sends the merged tail as a
+single causally-complete delta. The id is the highest sequence in the batch, so
+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.
+
+Presence (cursors, selections) is owned by the browser clients — the server
+never sets or holds presence state, it only relays awareness frames opaquely.
+See `@y-ruby/client` for the client-side awareness API.
+
+## Thread Safety
+
+A `Doc` is safe to share across Ruby threads — used concurrently from Puma
+workers, ActionCable connection threads, or background jobs without external
+locking.
+
+`test/thread_safety_test.rb` runs shared docs, the full sync handshake, and
+fan-in sync across 8 threads at once, and checks the interleaving doesn't change
+convergence.
+
+### Parallelism (GVL release)
+
+Every method that does real CRDT work (applying updates, encoding state,
+handling sync messages) releases Ruby's Global VM Lock
+(`rb_thread_call_without_gvl`) while the native code runs. That buys two things.
+
+CRDT work runs in parallel across Ruby threads on MRI, not just
+JRuby/TruffleRuby. `bench/parallelism_bench.rb` measures over 2x wall-clock
+speedup applying a ~900 KB update concurrently; native code that held the GVL
+couldn't beat serial time.
+
+A slow operation also can't stall the VM. A thread applying a large update holds
+the doc's write lock without holding the GVL, so other Ruby threads keep running
+instead of queuing behind it.
+
+Each method has the same shape: copy Ruby byte strings first, drop the GVL, do
+the yrs work while taking and releasing native locks entirely inside the
+closure, take the GVL back, then build Ruby objects. No Ruby API is touched
+without the GVL, and no native lock is held while reacquiring it, so the lock
+order can't deadlock. Panics in native code are caught and re-raised as Ruby
+exceptions.
+
+## Message Type Constants
+
+```ruby
+Y::MSG_SYNC            # 0 - Document sync messages
+Y::MSG_AWARENESS       # 1 - User presence data
+
+Y::MSG_SYNC_STEP1      # 0 - State vector request
+Y::MSG_SYNC_STEP2      # 1 - Update response
+Y::MSG_SYNC_UPDATE     # 2 - Incremental update
+```
+
+## Sync Flow
+
+```
+Client A                          Server
+   |                                  |
+   |-------- connect() ------------->|
+   |  (SyncStep1 + Awareness)        |
+   |                                  |
+   |<--- handle_sync_message resp ---|
+   |  (SyncStep2)                    |
+   |                                  |
+   |  (Document synchronized!)        |
+   |                                  |
+   |<------- updates ----------------|
+   |-------- updates --------------->|
+```
+
+## Development
+
+```bash
+# Setup
+bundle install
+
+# Build extension
+rake compile
+
+# Run tests
+rake test
+
+# Clean build artifacts
+rake clean
+```
+
+## License
+
+MIT License
+
+## Acknowledgments
+
+- [y-crdt/yrs](https://github.com/y-crdt/y-crdt) - The Rust implementation of Y.js
+- [Magnus](https://github.com/matsadler/magnus) - Ruby bindings for Rust
+- [rb-sys](https://github.com/oxidize-rb/rb-sys) - Rust extensions for Ruby

data/lib/y/action_cable/sync.rb

@@ -0,0 +1,313 @@
+# frozen_string_literal: true
+
+require "y"
+require "base64"
+
+module Y::ActionCable # rubocop:disable Style/ClassAndModuleChildren
+  # y-websocket protocol over ActionCable.
+  #
+  # Include this module in an ActionCable channel to sync Y.js documents
+  # (and awareness/presence) with browser clients. Messages are the standard
+  # y-protocols binary messages, base64-encoded in a JSON envelope:
+  #
+  #   { "update" => "<base64 bytes>", "id" => 42 } # client -> server
+  #   { "update" => "<base64 bytes>" }             # server -> subscribers
+  #   { "ack" => 42 }                              # server -> sender
+  #
+  # Example:
+  #   class DocumentChannel < ApplicationCable::Channel
+  #     include Y::ActionCable::Sync
+  #
+  #     on_load { |key| Document.find_by(key: key)&.content }
+  #     # on_change runs in the channel instance's context, so instance methods
+  #     # (current_user, params, ...) are available:
+  #     on_change { |key, update| Document.record!(key, update, by: current_user) }
+  #
+  #     def subscribed
+  #       sync_subscribed params[:id]
+  #     end
+  #
+  #     def receive(data)
+  #       sync_receive(data)
+  #     end
+  #   end
+  #
+  # There is no unsubscribe hook: the server keeps no per-connection document or
+  # presence state, so a disconnect needs no server-side cleanup.
+  #
+  # The concern is store-backed and fail-closed: every document update is
+  # validated against `on_load`, recorded through `on_change`, then broadcast.
+  # No authoritative document state is kept in ActionCable process memory.
+  module Sync
+    # Frame kinds we act on, from Y.message_kind. Its other codes (0 for a
+    # drop: malformed/truncated/multi-message/unknown, and 4 for an 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
+
+    # Default incoming-frame size cap (decoded bytes). Generous enough for a
+    # large initial SyncStep2, small enough to bound a single message's
+    # allocation/parse cost. Override per channel with `max_frame_bytes`.
+    DEFAULT_MAX_FRAME_BYTES = 8 * 1024 * 1024
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    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). Runs in the channel
+      # instance's context (instance_exec).
+      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
+      end
+
+      # Record every document change durably before it is applied or
+      # distributed. Called synchronously with (key, update), where update is
+      # the exact CRDT delta. If the block raises, the change is rejected:
+      # neither acknowledged nor broadcast to other subscribers.
+      #
+      # Runs in the channel instance's context (instance_exec). 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
+      end
+
+      # Maximum size, in decoded bytes, of an incoming document/awareness frame.
+      # Oversized frames are dropped before base64 decode and before native
+      # parsing, so a client can't force huge allocations/CPU (a DoS vector).
+      # Defaults to DEFAULT_MAX_FRAME_BYTES; set to nil to disable the cap.
+      def max_frame_bytes(bytes = :__unset__)
+        # Combined reader/writer; the sentinel keeps nil a real value (disables the cap).
+        @max_frame_bytes = bytes unless bytes == :__unset__
+        return @max_frame_bytes if defined?(@max_frame_bytes)
+
+        superclass.respond_to?(:max_frame_bytes) ? superclass.max_frame_bytes : DEFAULT_MAX_FRAME_BYTES
+      end
+    end
+
+    # Call from `subscribed`. Streams broadcasts for this document and
+    # transmits the server's opening handshake (SyncStep1 from the store).
+    def sync_subscribed(key)
+      @sync_key = key.to_s
+      sync_validate_required_hooks!
+
+      # 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
+
+    # Call from `receive`. Applies the client's message, replies directly
+    # when the protocol calls for it, and relays document/awareness changes
+    # to the other subscribers.
+    #
+    # Reliable delivery: document updates carry an "id", and the server replies
+    # `{ "ack" => id }` once the update has been durably recorded. A
+    # causally-gapped update is not acked; it gets a resync instead, so the
+    # client retransmits until the update lands.
+    def sync_receive(data, key = nil)
+      # Pass `key` (params[:id]) when your transport doesn't keep the channel
+      # instance alive across actions. Under AnyCable each RPC command gets a
+      # fresh channel, so instance variables set in `subscribed` are gone here.
+      @sync_key = key.to_s if key
+
+      encoded = data.is_a?(Hash) ? data["update"] : nil
+      return unless encoded.is_a?(String)
+
+      # Optional client-supplied id for reliable delivery (see sync_send_ack).
+      # data is known to be a Hash here (encoded came from it above).
+      id = data["id"]
+
+      # Frame-size cap: drop oversized frames before decoding (the encoded form
+      # is ~4/3 the decoded size) and again after, so a client can't force large
+      # base64 decodes / native parses / merges. A dropped frame is never acked,
+      # and there is no protocol NACK, so a legitimate oversized update is
+      # retransmitted indefinitely. Log the drop so it is at least findable.
+      cap = self.class.max_frame_bytes
+      if cap && encoded.bytesize > (cap * 4 / 3) + 4
+        sync_log_drop(:warn, "encoded #{encoded.bytesize}B exceeds max_frame_bytes #{cap}B", id)
+        return
+      end
+
+      begin
+        bytes = Base64.strict_decode64(encoded)
+      rescue ArgumentError
+        sync_log_drop(:debug, "not valid base64", id) # garbage or a probe, rarely a real client
+        return # ignore the frame and keep the connection
+      end
+
+      if cap && bytes.bytesize > cap
+        sync_log_drop(:warn, "decoded #{bytes.bytesize}B exceeds max_frame_bytes #{cap}B", id)
+        return
+      end
+
+      sync_send_ack(id, sync_handle_frame(encoded, bytes))
+    end
+
+    private
+
+    # Ask this connection's client to resync: re-send SyncStep1 carrying the
+    # server's current (gap-free) state vector. The client replies SyncStep2
+    # with everything the server is missing, delivered as one causally-complete
+    # delta, which heals the gap that triggered the resync.
+    def sync_request_resync(doc)
+      sync_transmit(doc.sync_step1)
+    end
+
+    # Reliable delivery: acknowledge an accepted update back to the sending
+    # connection. An ack-aware client tags each outgoing update with an "id"
+    # and retains it until the matching `{ "ack" => id }` returns, retransmitting
+    # on a timer or reconnect; idempotent CRDT apply makes resends free. Acks
+    # are sent only after the update has been durably recorded, or when a retry
+    # is already present in the durable store.
+    def sync_send_ack(id, outcome)
+      return if id.nil?
+      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.
+      transmit({ "ack" => id })
+    end
+
+    # Single broadcast point so relay semantics live in one place and tests can
+    # observe distribution. Store-backed streams intentionally echo to the
+    # sender; applying the same CRDT update twice is a no-op.
+    def sync_distribute(encoded)
+      ActionCable.server.broadcast(sync_stream_name, sync_envelope(encoded))
+    end
+
+    # Transmit raw protocol bytes to this connection.
+    def sync_transmit(bytes)
+      transmit(sync_envelope(Base64.strict_encode64(bytes)))
+    end
+
+    def sync_envelope(encoded)
+      { "update" => encoded }
+    end
+
+    # Override in the channel to add identifying context to dropped-frame logs --
+    # a user id, a connection id, a request id. Return a short string (or nil for
+    # none); it is appended to the log line. Default: no extra context.
+    def sync_log_context
+      nil
+    end
+
+    # Surface a dropped frame through the channel logger. Drops are otherwise
+    # invisible (no ack, no broadcast); an oversized legitimate update is never
+    # acked and the client retransmits it forever, so make it findable. Names the
+    # document key, the reliable-delivery id when present, and whatever
+    # sync_log_context returns, so a drop can be tied to a specific document,
+    # update, and connection.
+    def sync_log_drop(level, reason, id = nil)
+      logger.public_send(level) do
+        parts = ["key=#{@sync_key.inspect}"]
+        parts << "id=#{id}" unless id.nil?
+        # A broken context hook must surface, not take down frame handling.
+        context = begin
+          sync_log_context
+        rescue StandardError => e
+          "log-context-error=#{e.class}"
+        end
+        parts << context if context
+        "[y-ruby] dropped frame (#{parts.join(" ")}): #{reason}"
+      end
+    end
+
+    # This concern acks updates as durably recorded, so it must have both a
+    # loader (to rebuild the doc and detect causal gaps) and a recorder (to
+    # actually persist before acking). Fail closed rather than silently acking
+    # and broadcasting updates that were never stored, which a cold load or
+    # reconnect would then lose.
+    def sync_validate_required_hooks!
+      missing = []
+      missing << :on_load unless self.class.on_load
+      missing << :on_change unless self.class.on_change
+      return if missing.empty?
+
+      raise Y::Error,
+            "Y::ActionCable::Sync requires #{missing.join(" and ")}. Updates are acked as " \
+            "durably recorded; without a loader and recorder, an ack would claim a persistence " \
+            "that never happened, and a cold load would lose the edit."
+    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.
+    # 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_handle_frame(encoded, bytes)
+      sync_validate_required_hooks!
+
+      case Y.message_kind(bytes)
+      when MSG_KIND_SYNC_STEP1
+        result = sync_load_doc.handle_sync_message(bytes)
+        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
+      when MSG_KIND_AWARENESS
+        sync_distribute(encoded)
+        :noop
+      else
+        :noop
+      end
+    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
+      doc = Y::Doc.new
+      state = instance_exec(@sync_key, &self.class.on_load)
+      doc.apply_update(state) if state
+      doc
+    end
+
+    def sync_stream_name
+      "y_ruby:#{@sync_key}"
+    end
+
+    def sync_awareness_stream_name
+      "#{sync_stream_name}:awareness"
+    end
+
+    # Invoke the on_change recorder in this channel instance's context
+    # (instance_exec) so it can reach the channel's own methods. Mirrors how
+    # sync_load_doc fetches and runs on_load.
+    def sync_record_change(update)
+      instance_exec(@sync_key, update, &self.class.on_change)
+    end
+  end
+end

data/lib/y/action_cable/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Y
+  module ActionCable
+    VERSION = "0.2.0"
+  end
+end

data/lib/y/action_cable.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "y"
+require "y/action_cable/version"
+
+module Y
+  # ActionCable integration for y-ruby.
+  #
+  # Provides Y::ActionCable::Sync, a channel concern implementing the
+  # y-websocket sync protocol and awareness/presence over ActionCable (and
+  # AnyCable), so a Rails app can be the collaboration server for Y.js editors
+  # with no Node sidecar. The CRDT documents, awareness, and protocol primitives
+  # themselves come from the core `y-ruby` gem.
+  module ActionCable
+  end
+end
+
+require "y/action_cable/sync"

data/lib/y-ruby-actioncable.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Entry point matching the gem name, so `Bundler.require` loads it automatically.
+require "y/action_cable"

metadata

@@ -0,0 +1,139 @@
+--- !ruby/object:Gem::Specification
+name: y-ruby-actioncable
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- JP Camara
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: y-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+- !ruby/object:Gem::Dependency
+  name: actioncable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: 'y-ruby-actioncable adds a Rails ActionCable channel concern (Y::ActionCable::Sync)
+  on top of the y-ruby y-crdt bindings: the full y-websocket sync protocol, awareness/presence,
+  record-before-distribute auditing, and memory/store backends (AnyCable-ready), so
+  a Rails app can be the collaboration server for Y.js editors with no Node sidecar.'
+email:
+- johnpcamara@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG-actioncable.md
+- LICENSE
+- README.md
+- lib/y-ruby-actioncable.rb
+- lib/y/action_cable.rb
+- lib/y/action_cable/sync.rb
+- lib/y/action_cable/version.rb
+homepage: https://github.com/jpcamara/y-ruby
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/jpcamara/y-ruby
+  changelog_uri: https://github.com/jpcamara/y-ruby/blob/main/CHANGELOG-actioncable.md
+  bug_tracker_uri: https://github.com/jpcamara/y-ruby/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.4.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: 'ActionCable integration for y-ruby: the y-websocket sync protocol and awareness
+  over ActionCable/AnyCable'
+test_files: []