yrb-lite 0.1.0.beta1-aarch64-linux

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 36a12fc8df3bf5db4ca5d3e9e34314d629be626abb3fd483b1afce8f8225d7c2
+  data.tar.gz: b1f3c2b6103377638566340c21cbee122465963c071a2e379f24047046efd81f
+SHA512:
+  metadata.gz: '041491e072e193af612869d9c9ace1d38781fb528c12d9a458861dd1a5992cad27d0f665033b779e234d7c08645d281175b9c79973d17d392e9a124e6d69728e'
+  data.tar.gz: c5170f5245f46d901b298737f51f3732576d4cc33d076e6b761ddc7c4488c4426c5bbcef67c1e50ca9a65099c4cb2cc179664877bb7ed4ff982c24c1e30105c4

data/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to this project 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]
+
+### Added
+
+- Thread-safe `YrbLite::Doc` and `YrbLite::Awareness` over `yrs` (magnus/rb-sys
+  native extension). The GVL is released during CRDT work so docs can run in
+  parallel on MRI.
+- `YrbLite::Sync` ActionCable channel concern implementing the y-websocket
+  protocol (document sync plus awareness/presence). It's wire-compatible with
+  the [`@y-rb/actioncable`](https://www.npmjs.com/package/@y-rb/actioncable)
+  browser provider, and accepts its `{ update: ... }` envelope and `{ m: ... }`.
+- A "record-before-distribute" mode via an `on_change` hook, so every change is
+  recorded durably before it's applied or relayed.
+- Presence cleanup on disconnect, and idle-document eviction.
+- Two backends: `sync_backend :memory` (default, classic ActionCable) and
+  `sync_backend :store` (stateless, AnyCable-ready, multi-process).
+- Hardening against bad input: malformed or multi-message frames are dropped
+  before processing or relay, and native panics are contained at the FFI
+  boundary.
+- Precompiled native gems for common platforms (no Rust toolchain needed to
+  install) via the cross-gem workflow.
+
+[Unreleased]: https://github.com/jpcamara/yrb-lite/commits/main

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,427 @@
+# yrb-lite
+
+[![CI](https://github.com/jpcamara/yrb-lite/actions/workflows/ci.yml/badge.svg)](https://github.com/jpcamara/yrb-lite/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 YrbLite::Sync
+
+  def subscribed   = sync_for(params[:id])
+  def receive(data) = sync_receive(data)
+  def unsubscribed = sync_clear_presence
+end
+```
+
+On the browser, use the [`@y-rb/actioncable`](https://www.npmjs.com/package/@y-rb/actioncable)
+provider as-is. Tiptap, ProseMirror, and BlockNote all sync through it.
+
+## What you get
+
+- Thread-safe `Doc` and `Awareness`. You can share them across Puma threads,
+  and the GVL is released while yrs does the actual work.
+- The y-websocket protocol (document sync plus awareness/presence) as a
+  one-include ActionCable concern.
+- A store-backed mode for AnyCable and multi-process deployments.
+- An optional authoritative mode that records each change durably before it
+  goes out to anyone.
+
+What it doesn't do: auth, read-only connections, rate limiting, webhooks,
+metrics. Hocuspocus ships extensions for those; here you'd build them with
+Rails.
+
+## Testing
+
+Ruby and Rust unit tests cover the core, and an end-to-end suite runs the real
+stack: it fuzzes the protocol, throws garbage and chaos at the server, kills the
+server mid-write to check crash recovery, and drives real browsers under load.
+The benchmark numbers below are from a single laptop. Issues and PRs are
+welcome.
+
+## Install
+
+```ruby
+gem "yrb-lite"
+```
+
+Requires Ruby 3.4 or newer. Precompiled gems ship for Linux and macOS on Ruby
+3.4 and 4.0, so installing there needs no Rust. Other platforms (and any other
+Ruby version) build from source, which needs [Rust](https://rustup.rs).
+
+To work on the gem itself:
+
+```bash
+git clone https://github.com/jpcamara/yrb-lite
+cd yrb-lite
+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 "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
+
+# 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 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
+```
+
+### 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
+```
+
+### Handling Sync Messages
+
+```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?
+```
+
+### ActionCable Integration
+
+`YrbLite::Sync` 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 YrbLite::Sync
+
+  # Optional persistence:
+  # on_load { |key| Document.find_by(key: key)&.content }
+  # on_save { |key, update| Document.find_by(key: key)&.update!(content: update) }
+
+  def subscribed
+    sync_for params[:id]
+  end
+
+  def receive(data)
+    sync_receive(data)
+  end
+
+  def unsubscribed
+    sync_clear_presence
+  end
+end
+```
+
+One `YrbLite::Awareness` is shared per document key. Creating it is
+mutex-serialized; after that everything runs lock-free on the thread-safe
+native types. The concern answers SyncStep1 directly, relays document and
+awareness changes to the other subscribers (not back to the sender), and calls
+`on_save` after any message that changed the document.
+
+`sync_unsubscribed` clears the connection's presence, so a closed tab doesn't
+leave a stale cursor hanging until the client-side timeout. It also unloads the
+document from memory once the last subscriber disconnects, which keeps the
+process from holding onto every document it ever served. That unload only
+happens when `on_load` is set and the document can be reloaded later; without
+it, the in-memory copy is the only one and stays put.
+
+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.
+
+#### Multi-process deployments
+
+Most Rails apps run several processes (Puma workers, multiple dynos), 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 be a
+real one (`redis` or `solid_cable`, not `async`). With that in place, a change
+on one process reaches clients on all of them.
+
+Each process also keeps its own copy of the document and applies broadcasts from
+the others. The merge is an ordinary CRDT apply, idempotent and
+order-independent, which keeps server reads and new-client handshakes current on
+every process. Each broadcast carries a per-process id (`Sync.process_id`) that
+tells a process to skip its own.
+
+A cold process (no copy yet) rebuilds from the durable store through `on_load`.
+In authoritative mode the store is always current, since changes are recorded
+before they go out. Record-before-distribute therefore 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
+the lot: convergence, fresh copies on both, presence across processes, and one
+shared log.
+
+##### AnyCable (`sync_backend :store`)
+
+The default backend keeps that warm in-memory copy and relies on a `stream_from`
+block running in Ruby for each broadcast. AnyCable breaks both assumptions.
+anycable-go delivers broadcasts outside Ruby, so the block never runs. Each RPC
+gets a fresh channel instance, which means ivars set in `subscribed` are gone by
+`receive`. And there's no fixed worker-to-document mapping to lean on.
+
+`sync_backend :store` is the path for that: stateless per message, no warm
+copy.
+
+```ruby
+class DocumentChannel < ApplicationCable::Channel
+  include YrbLite::Sync
+  sync_backend :store
+
+  on_load  { |key| MyStore.load(key) }          # required: source of truth
+  on_change { |key, update| MyStore.append(key, update) }  # required: record
+
+  def subscribed   = sync_for(params[:id])
+  def receive(data) = sync_receive(data, params[:id])   # pass the key each call
+  def unsubscribed = sync_unsubscribed(params[:id])
+end
+```
+
+- `stream_from` is registered without a block; anycable-go does the relaying.
+- A handshake (SyncStep1) is answered from the store. Changes are recorded, then
+  broadcast. Nothing is held in Ruby between calls, so any worker can handle any
+  message.
+- Pass `params[:id]` into `sync_receive`/`sync_unsubscribed` so the document key
+  survives AnyCable's per-command instances.
+- The sender gets its own updates echoed back (no Ruby callback to filter them).
+  That's a no-op, since applying an update twice does nothing.
+
+The demo checks this against a real anycable-go + RPC server
+(`frontend/anycable_probe.mjs`, `anycable_concurrent.mjs`): liveness, the
+`@y-rb/actioncable` provider, cross-process reads, and concurrent convergence.
+
+The wire format is the standard y-protocols binary messages, base64-encoded in
+the ActionCable envelope. The server accepts the `@y-rb/actioncable` provider's
+`{ "update" => ... }` envelope (and its own `{ "m" => ... }`) and sends one
+message per frame, so the off-the-shelf provider works with no custom client
+code:
+
+```js
+import { createConsumer } from "@rails/actioncable"
+import { WebsocketProvider } from "@y-rb/actioncable"
+
+const provider = new WebsocketProvider(ydoc, createConsumer(), "DocumentChannel", { id: docId })
+```
+
+[`examples/actioncable-demo`](examples/actioncable-demo) is a full Rails + Tiptap
+app using that provider, with end-to-end tests.
+
+#### Authoritative audit mode (record before distribute)
+
+By default a change is applied and broadcast immediately (the fast path). If you
+need to durably record every change before anyone else sees it, whether for
+auditing or to guarantee nothing is distributed until it's stored, register an
+`on_change` recorder:
+
+```ruby
+class DocumentChannel < ApplicationCable::Channel
+  include YrbLite::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
+
+  def subscribed = sync_for(params[:id])
+  def receive(data) = sync_receive(data)
+  def unsubscribed = sync_clear_presence
+end
+```
+
+With `on_change` registered, a change is recorded before it goes anywhere. The
+recorder writes the raw CRDT delta synchronously; only then is the change
+applied to the shared document and broadcast. The whole sequence runs under a
+per-document lock, so every change to a document is recorded in the same order
+it's applied. That's what makes the log authoritative. Replay the deltas onto a
+fresh `Y.Doc` and you get the document back exactly.
+
+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 per change,
+which serializes that document's writes. Other documents use other locks and run
+in parallel.
+
+`on_change` and `on_save` are separate. `on_save` snapshots the whole document
+when it gets a chance; `on_change` is the per-change log. The demo's `AUDIT=1`
+mode (in [`examples/actioncable-demo`](examples/actioncable-demo)) wires
+`on_change` to an fsync'd append-only log and checks, end to end, that the log
+alone rebuilds the document.
+
+### 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)
+```
+
+## Thread Safety
+
+Unlike the official `y-rb` gem, yrb-lite is 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.
+
+That comes from how the underlying types work, not from locking on top:
+
+- `yrs::Doc` is `Send + Sync`. Every operation takes the document's internal
+  RwLock with blocking semantics (`read_blocking`/`write_blocking`), so
+  concurrent access serializes instead of erroring or corrupting state.
+- `yrs::sync::Awareness` is built for multi-threaded servers: client states
+  live in a `DashMap` and the whole API is `&self`.
+- The extension adds no interior-mutability tricks. There's no `RefCell`, where
+  a re-entrant borrow would panic and take the Ruby process down with it.
+  Each native method opens and closes its transaction in one call, so no lock
+  or borrow outlives a call and there's nothing to deadlock on.
+- A `Send + Sync` static assertion for both wrapped types lives in `lib.rs`. If
+  a yrs upgrade regressed this, the gem would fail to compile instead of quietly
+  turning thread-unsafe.
+
+`test/thread_safety_test.rb` runs shared docs, the full sync handshake, fan-in
+sync, and awareness state 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 the Ruby byte string, drop the GVL, do the
+yrs work (taking and releasing the doc lock entirely inside the closure), take
+the GVL back, then build Ruby objects. No Ruby API is touched without the GVL,
+and the doc lock is never held across a GVL boundary, so the lock order can't
+deadlock. Panics in native code are caught and re-raised as Ruby exceptions.
+
+## Message Type Constants
+
+```ruby
+YrbLite::MSG_SYNC            # 0 - Document sync messages
+YrbLite::MSG_AWARENESS       # 1 - User presence data
+YrbLite::MSG_AUTH            # 2 - Authentication
+YrbLite::MSG_QUERY_AWARENESS # 3 - Request awareness state
+
+YrbLite::MSG_SYNC_STEP1      # 0 - State vector request
+YrbLite::MSG_SYNC_STEP2      # 1 - Update response
+YrbLite::MSG_SYNC_UPDATE     # 2 - Incremental update
+```
+
+## Sync Flow
+
+```
+Client A                          Server
+   |                                  |
+   |-------- start() --------------->|
+   |  (SyncStep1 + Awareness)        |
+   |                                  |
+   |<------- handle() response ------|
+   |  (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/yrb-lite.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Entry point matching the gem name, so `Bundler.require` works out of the box.
+require "yrb_lite"

data/lib/yrb_lite/sync.rb

@@ -0,0 +1,456 @@
+# frozen_string_literal: true
+
+require "base64"
+require "securerandom"
+
+module YrbLite
+  # 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:
+  #
+  #   { "m" => "<base64 bytes>" }              # client -> server
+  #   { "m" => "...", "origin" => "<id>" }     # server -> subscribers
+  #
+  # Example:
+  #   class DocumentChannel < ApplicationCable::Channel
+  #     include YrbLite::Sync
+  #
+  #     on_load { |key| Document.find_by(key: key)&.content }
+  #     on_save { |key, update| Document.find_by(key: key)&.update!(content: update) }
+  #
+  #     def subscribed
+  #       sync_for params[:id]
+  #     end
+  #
+  #     def receive(data)
+  #       sync_receive(data)
+  #     end
+  #
+  #     def unsubscribed
+  #       sync_clear_presence
+  #     end
+  #   end
+  #
+  # The shared YrbLite::Awareness instances are safe to use from ActionCable's
+  # worker thread pool: the native types are Send + Sync and every operation
+  # releases the GVL, so concurrent clients sync in parallel.
+  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
+    MSG_KIND_SYNC_STEP1 = 1
+    MSG_KIND_UPDATE = 2
+    MSG_KIND_AWARENESS = 3
+    MSG_KIND_AWARENESS_QUERY = 4
+
+    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).
+      def on_load(callable = nil, &block)
+        @on_load = callable || block if callable || block
+        @on_load
+      end
+
+      # Persist document state. Called with (key, update) after every
+      # message that modified the document.
+      def on_save(callable = nil, &block)
+        @on_save = callable || block if callable || block
+        @on_save
+      end
+
+      # Record every document change durably before it is applied or
+      # distributed (authoritative audit mode). Called synchronously with
+      # (key, update), where update is the exact CRDT delta, serialized per
+      # document so the recorded order is the apply order. If the block raises,
+      # the change is rejected: neither applied to the shared document nor
+      # broadcast to other subscribers.
+      #
+      # Registering an on_change switches that channel onto the strict path
+      # (record, apply, broadcast). Without it, the default fast path applies
+      # and broadcasts, with an optional on_save snapshot.
+      def on_change(callable = nil, &block)
+        @on_change = callable || block if callable || block
+        @on_change
+      end
+
+      # Select the document backend:
+      #   :memory (default): keep a warm in-memory replica per process and keep
+      #     it current via a custom stream_from callback. Fast, but it assumes
+      #     classic ActionCable (the callback runs in Ruby) and
+      #     process<->document affinity.
+      #   :store: stateless per message, with no warm replica and no custom
+      #     stream callback. Handshakes and reads are served from the durable
+      #     store (`on_load`); changes are recorded (`on_change`) and relayed.
+      #     Works under AnyCable (broadcasts handled outside Ruby, no worker
+      #     affinity) and across processes. Requires `on_load` and `on_change`.
+      def sync_backend(mode = nil)
+        @sync_backend = mode if mode
+        @sync_backend || :memory
+      end
+    end
+
+    # Call from `subscribed`. Streams broadcasts for this document and
+    # transmits the server's opening handshake (SyncStep1 + awareness).
+    def sync_for(key)
+      @sync_key = key.to_s
+      @sync_origin = SecureRandom.hex(8)
+      @sync_clients = [] # awareness client IDs seen on this connection
+
+      return sync_for_store_backed if self.class.sync_backend == :store
+
+      Sync.subscribe(@sync_key)
+      awareness = sync_awareness
+
+      stream_from sync_stream_name, coder: ActiveSupport::JSON do |payload|
+        sync_on_broadcast(payload)
+      end
+
+      # Opening handshake: SyncStep1 then the current awareness, each as its
+      # own single-message frame, so providers that parse one message per frame
+      # (e.g. @y-rb/actioncable) handle both. The client replies SyncStep2 to
+      # the SyncStep1, delivering its state to the server.
+      sync_transmit(awareness.sync_step1)
+      sync_transmit(awareness.encode_awareness_update)
+    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.
+    #
+    # If an `on_change` recorder is registered, document changes take the
+    # strict authoritative path (record -> apply -> broadcast, serialized per
+    # document); otherwise the fast path is used.
+    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
+
+      # Accept both envelope keys: "m" (yrb-lite's own clients) and "update"
+      # (the @y-rb/actioncable browser provider).
+      m = data.is_a?(Hash) ? (data["m"] || data["update"]) : nil
+      return unless m.is_a?(String)
+
+      begin
+        bytes = Base64.strict_decode64(m)
+      rescue ArgumentError
+        return # not valid base64; ignore the frame and keep the connection
+      end
+
+      return sync_receive_store_backed(m, bytes) if self.class.sync_backend == :store
+
+      awareness = sync_awareness
+      kind = awareness.message_kind(bytes)
+      # Malformed / truncated / multi-message / unknown frames are dropped
+      # before they can be processed or relayed to other clients.
+      return if kind == MSG_KIND_DROP
+
+      sync_track_clients(awareness, bytes) if kind == MSG_KIND_AWARENESS
+
+      if kind == MSG_KIND_UPDATE && self.class.on_change
+        sync_apply_authoritative(awareness, m, bytes)
+      else
+        sync_apply_fast(awareness, m, bytes, kind)
+      end
+    end
+
+    # Call from `unsubscribed`. Clears the presence states this connection
+    # introduced and tells the other subscribers to drop those cursors, so a
+    # closed tab or dropped socket doesn't leave a ghost cursor behind until
+    # the client-side timeout reaps it.
+    def sync_clear_presence
+      return if @sync_clients.nil? || @sync_clients.empty?
+
+      removal = sync_awareness.remove_clients(@sync_clients)
+      @sync_clients = []
+      return if removal.empty?
+
+      sync_distribute(Base64.strict_encode64(removal))
+    end
+
+    # Call from `unsubscribed`. Clears this connection's presence and, when the
+    # last subscriber for the document leaves, persists and unloads it from
+    # memory (only when an `on_load` is configured to bring it back; otherwise
+    # the in-memory document is the only copy and is kept). Prevents a
+    # long-running server from accumulating every document it has ever served.
+    def sync_unsubscribed(key = nil)
+      @sync_key = key.to_s if key
+      return if self.class.sync_backend == :store # nothing cached per process
+
+      sync_clear_presence
+      saver = self.class.on_save
+      Sync.release(@sync_key, evictable: !self.class.on_load.nil?) do |awareness|
+        saver&.call(@sync_key, awareness.encode_state_as_update)
+      end
+    end
+
+    # The shared Awareness (document + presence) for this channel's key.
+    # Also useful for server-side reads, e.g.:
+    #   sync_awareness.encode_state_as_update
+    def sync_awareness
+      Sync.awareness_for(@sync_key, self.class.on_load)
+    end
+
+    private
+
+    # Default path: apply the message, answer direct requests, relay
+    # state-changing messages to the other subscribers. Routing comes from the
+    # native `kind` (from Awareness#message_kind) rather than peeking at bytes.
+    # Document changes (SyncStep2, Update) and awareness get relayed; requests
+    # (SyncStep1, awareness-query) are answered above and not relayed. An
+    # optional on_save snapshot is taken after a document change.
+    def sync_apply_fast(awareness, encoded, bytes, kind)
+      response = awareness.handle(bytes)
+      sync_transmit(response) unless response.empty?
+
+      return unless [MSG_KIND_UPDATE, MSG_KIND_AWARENESS].include?(kind)
+
+      sync_distribute(encoded)
+      sync_persist if kind == MSG_KIND_UPDATE
+    end
+
+    # Authoritative path: record the change durably, then apply it to the
+    # shared document, then distribute it. The sequence runs under a
+    # per-document lock so changes are recorded in a single total order that
+    # matches the order they're applied, and nothing is distributed (or applied)
+    # before it has been recorded. If the recorder raises, the change is
+    # rejected (not applied, not broadcast) and the exception propagates, so the
+    # channel can surface it and the client can resync.
+    def sync_apply_authoritative(awareness, encoded, bytes)
+      recorder = self.class.on_change
+
+      modified = Sync.lock_for(@sync_key).synchronize do
+        update = awareness.update_from_message(bytes)
+        # A no-op message (e.g. the empty SyncStep2 in a client's opening
+        # handshake) carries no change, so there's nothing to record or relay.
+        next false unless update
+
+        recorder.call(@sync_key, update) # durable write; raise to reject
+        awareness.apply_update(update)   # only recorded changes reach the doc
+        sync_distribute(encoded)         # ...and only then the wire
+        true
+      end
+
+      sync_persist if modified
+    end
+
+    # Single broadcast point for both paths (and presence removal), so the
+    # relay semantics live in one place and tests can observe distribution.
+    # `origin` identifies the sending connection (don't echo to it); `pid`
+    # identifies the sending process (other processes apply it to their own
+    # replica; see sync_on_broadcast).
+    def sync_distribute(encoded)
+      ActionCable.server.broadcast(
+        sync_stream_name,
+        sync_envelope(encoded, "origin" => @sync_origin, "pid" => Sync.process_id)
+      )
+    end
+
+    # Transmit raw protocol bytes to this connection (base64, dual-key).
+    def sync_transmit(bytes)
+      transmit(sync_envelope(Base64.strict_encode64(bytes)))
+    end
+
+    # Build an outgoing envelope. We send the payload under both keys: "m"
+    # (yrb-lite's own clients) and "update" (the @y-rb/actioncable provider),
+    # so either client works against the same server.
+    def sync_envelope(encoded, extra = {})
+      { "m" => encoded, "update" => encoded }.merge(extra)
+    end
+
+    # Handle a broadcast delivered by the cable adapter. With a multi-process
+    # adapter (Redis, solid_cable), it may have come from another server
+    # process. Keep this process's in-memory replica current with changes that
+    # originated elsewhere, then relay to this connection's browser.
+    def sync_on_broadcast(payload)
+      sync_apply_remote(payload["m"]) if payload["pid"] != Sync.process_id
+      transmit(payload) unless payload["origin"] == @sync_origin
+    end
+
+    # Apply a change that originated on another process to this process's
+    # replica, without re-recording it (the origin process already recorded it
+    # before broadcasting). The CRDT merge is idempotent and commutative, so a
+    # cold replica converges regardless of ordering, and applying from several
+    # local connections is harmless.
+    def sync_apply_remote(encoded)
+      return unless encoded.is_a?(String)
+
+      begin
+        bytes = Base64.strict_decode64(encoded)
+      rescue ArgumentError
+        return
+      end
+
+      awareness = sync_awareness
+      case awareness.message_kind(bytes)
+      when MSG_KIND_UPDATE
+        update = awareness.update_from_message(bytes)
+        awareness.apply_update(update) if update
+      when MSG_KIND_AWARENESS
+        awareness.handle(bytes)
+      end
+    end
+
+    # -- Store-backed (AnyCable-native) path --------------------------------
+
+    # Subscribe without a custom block, so AnyCable (which delivers broadcasts
+    # outside Ruby) relays them directly. Send the opening SyncStep1 built from
+    # the durable store. No warm replica is kept.
+    def sync_for_store_backed
+      stream_from sync_stream_name
+      sync_transmit(sync_load_doc.sync_step1)
+    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.
+    def sync_receive_store_backed(encoded, bytes)
+      case Sync.codec.message_kind(bytes)
+      when MSG_KIND_SYNC_STEP1
+        result = sync_load_doc.handle_sync_message(bytes)
+        sync_transmit(result[2]) if result
+      when MSG_KIND_UPDATE
+        update = Sync.codec.update_from_message(bytes)
+        return unless update
+
+        self.class.on_change&.call(@sync_key, update) # record before relay
+        sync_distribute(encoded)
+      when MSG_KIND_AWARENESS
+        sync_distribute(encoded)
+      end
+    end
+
+    # 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)
+      doc.apply_update(state) if state
+      doc
+    end
+
+    # Record the awareness client IDs carried by an incoming message (already
+    # known to be an awareness frame) so we can clear them when this connection
+    # closes.
+    def sync_track_clients(awareness, bytes)
+      awareness.awareness_client_ids(bytes).each do |id|
+        @sync_clients << id unless @sync_clients.include?(id)
+      end
+    end
+
+    def sync_stream_name
+      "yrb_lite:#{@sync_key}"
+    end
+
+    def sync_persist
+      return unless (saver = self.class.on_save)
+
+      saver.call(@sync_key, sync_awareness.encode_state_as_update)
+    end
+
+    # -- Shared document registry ------------------------------------------
+
+    @registry = {}
+    @locks = {}
+    @subscribers = Hash.new(0)
+    @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
+      # knows to skip its own. Survives for the life of the process.
+      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
+
+      # Get or create the shared Awareness for a key. Creation (including
+      # the on_load callback) is serialized under a mutex so concurrent
+      # subscribers can never observe two documents for one key; all
+      # subsequent operations run lock-free on the thread-safe native types.
+      def awareness_for(key, loader = nil)
+        @registry_mutex.synchronize do
+          @registry[key] ||= begin
+            awareness = YrbLite::Awareness.new
+            if loader && (state = loader.call(key))
+              awareness.apply_update(state)
+            end
+            awareness
+          end
+        end
+      end
+
+      # Per-document mutex serializing the authoritative record -> apply ->
+      # broadcast section, so a document's audit log is a single total order.
+      # 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
+
+      # Count a new subscriber for a document.
+      def subscribe(key)
+        @registry_mutex.synchronize { @subscribers[key] += 1 }
+      end
+
+      # Drop a subscriber. When the last one leaves and the document is
+      # evictable (there's an on_load to bring it back, so unloading can't lose
+      # data), persist it via the given block and unload it from memory, so a
+      # long-running server doesn't accumulate every document and lock it has
+      # ever seen. Returns true if the document was evicted.
+      #
+      # The persist runs outside the registry lock (it may do I/O), and we
+      # re-check the subscriber count afterward: if someone reconnected while
+      # we were saving, eviction is aborted and the warm document is kept.
+      def release(key, evictable:)
+        awareness = @registry_mutex.synchronize do
+          @subscribers[key] -= 1 if @subscribers[key].positive?
+          next nil unless @subscribers[key].zero?
+
+          @subscribers.delete(key)
+          evictable ? @registry[key] : nil
+        end
+        return false unless awareness
+
+        yield awareness if block_given?
+
+        @registry_mutex.synchronize do
+          # A subscriber may have returned during the persist above.
+          next false unless @subscribers[key].zero?
+
+          @subscribers.delete(key)
+          @locks.delete(key)
+          !@registry.delete(key).nil?
+        end
+      end
+
+      def registry
+        @registry_mutex.synchronize { @registry.dup }
+      end
+
+      # Clear all documents (useful for testing).
+      def reset!
+        @registry_mutex.synchronize do
+          @registry = {}
+          @locks = {}
+          @subscribers = Hash.new(0)
+        end
+      end
+    end
+  end
+end

data/lib/yrb_lite/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module YrbLite
+  VERSION = "0.1.0.beta1"
+end

data/lib/yrb_lite.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "yrb_lite/version"
+
+# Load the native extension. Precompiled gems ship it in a per-Ruby-version
+# subdir (lib/yrb_lite/<major.minor>/yrb_lite.<ext>); a source build puts it
+# flat at lib/yrb_lite/yrb_lite.<ext>. Try the versioned path first, fall back.
+begin
+  RUBY_VERSION =~ /(\d+\.\d+)/
+  require_relative "yrb_lite/#{Regexp.last_match(1)}/yrb_lite"
+rescue LoadError
+  require_relative "yrb_lite/yrb_lite"
+end
+
+module YrbLite
+  # Error class is defined in Rust extension
+
+  # Autoload Sync module - only loaded when ActionCable is available
+  autoload :Sync, "yrb_lite/sync"
+end

metadata

@@ -0,0 +1,119 @@
+--- !ruby/object:Gem::Specification
+name: yrb-lite
+version: !ruby/object:Gem::Version
+  version: 0.1.0.beta1
+platform: aarch64-linux
+authors:
+- JP Camara
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-06-15 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: 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'
+- !ruby/object:Gem::Dependency
+  name: rake-compiler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+description: yrb-lite is a thread-safe Ruby binding over the Rust y-crdt (yrs) library
+  plus an ActionCable concern implementing the full y-websocket sync protocol and
+  awareness. It lets a Rails app be the collaboration server for Y.js editors (Tiptap,
+  ProseMirror, BlockNote) with no Node sidecar.
+email:
+- johnpcamara@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/yrb-lite.rb
+- lib/yrb_lite.rb
+- lib/yrb_lite/3.4/yrb_lite.so
+- lib/yrb_lite/4.0/yrb_lite.so
+- lib/yrb_lite/sync.rb
+- lib/yrb_lite/version.rb
+homepage: https://github.com/jpcamara/yrb-lite
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/jpcamara/yrb-lite
+  changelog_uri: https://github.com/jpcamara/yrb-lite/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/jpcamara/yrb-lite/issues
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: 4.1.dev
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.23
+signing_key: 
+specification_version: 4
+summary: Thread-safe Ruby bindings for y-crdt (Y.js) with the y-websocket sync protocol
+  for ActionCable
+test_files: []