yrb-lite 0.1.0.beta7 → 0.1.0.beta9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ea20d7a00b104460b01812d463df581b45042d63491ff1e5494acd478fa2047b
-  data.tar.gz: 731010497572899b225ff36fd792e635738d05bad0f41640a4f991af56540d3e
+  metadata.gz: 8d834b5052572c1d84374702a2c45963522725abf47eaaefd62acc934b75a4fe
+  data.tar.gz: 025f4e5ae96c0fd3c9af6e43e2ddd16c4bc22cb34b95b17ad70f8ff74283557b
 SHA512:
-  metadata.gz: 83682aa86e7753b9270274051e0b9850c41e35559817cbae981debe68de53d4b1cd56cff5b21b0d63b411e87ab550cd7ffc11c0ec0c3005845e02e5af145d078
-  data.tar.gz: 282965720af81ee289feb0f555ff828fd593ba24f869054a7792f420c61ba03c87168b963adb6259e143b103c398e70855365d48c1f4cd6a7e693ae8491026b9
+  metadata.gz: 73e9cd5d0bf9ffbf3c729f54390731376dd443d1f59fa597917c926f3c6326089903ab7b9c67a2dc037de343368d6f1f045f937fae99a2c01d430500fd0f6fe5
+  data.tar.gz: 67ad34f34202019617905d035e6cfb91f3693534eebed93d3fbb612b1e410bc75803f4bc2c311bedff076bed15c3718a4100153e3b42ae1de74e9cae0d7f73a5

data/CHANGELOG.md

@@ -5,135 +5,3 @@ All notable changes to this project are documented here. The format is based on
 to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
-
-## [0.1.0.beta6] - 2026-06-22
-
-(yrb-lite core gem. The `yrb-lite-client` npm package ships these client changes as 0.1.2.)
-
-### Added
-
-- `yrb-lite-client`, the TypeScript client package for the yrb-lite
-  ActionCable/AnyCable protocol. It provides `ActionCableProvider`,
-  `YProtocolSession`, and the standalone `ReliableSync` delivery core.
-
-### Changed
-
-- Document delivery is ack-tracked by default in `yrb-lite-client`: document
-  frames use `{ update, id }`, acknowledgements use `{ ack }`, and pending
-  document updates stay queued until acked.
-- The ActionCable protocol surface uses a single canonical document envelope:
-  `{ "update" => "<base64 frame>" }`.
-- AnyCable awareness/presence uses an awareness-only whisper envelope,
-  `{ awareness: "<base64 awareness frame>" }`, while document frames stay on
-  the server persistence/ack path.
-
-### Fixed
-
-- Incoming protocol frames are validated before mutating documents or awareness
-  state, including trailing-byte rejection on the TypeScript client.
-- Native/Rust protocol entry points reject wire client IDs that are unsafe for
-  JavaScript clients.
-- `lib0` is declared as a direct runtime dependency of `yrb-lite-client`.
-
-## [0.1.0.beta5] - 2026-06-18
-
-### Changed
-
-- **Breaking:** the ActionCable integration has been extracted into a separate
-  gem, [`yrb-lite-actioncable`](https://rubygems.org/gems/yrb-lite-actioncable).
-  `yrb-lite` is now a standalone y-crdt wrapper: CRDT documents, awareness, and
-  the y-websocket sync protocol primitives, with no Rails/ActionCable coupling
-  (mirrors the `y-rb` / `yrb-actioncable` split). The `base64` runtime
-  dependency moved with it.
-
-### Migration
-
-- Using `YrbLite::Sync`? Add `gem "yrb-lite-actioncable"` and change
-  `include YrbLite::Sync` to `include YrbLite::ActionCable::Sync`. The concern's
-  API is otherwise unchanged. If you only use `YrbLite::Doc`/`YrbLite::Awareness`,
-  nothing changes.
-
-## [0.1.0.beta4] - 2026-06-18
-
-### Changed
-
-- `on_change` block recorders now run in the **channel instance's context**
-  (via `instance_exec`), so a recorder can call the channel's own methods --
-  `current_user`, `params`, request/connection-scoped accessors -- directly,
-  instead of plumbing them in through a thread-local. A non-Proc callable (an
-  object responding to `#call`) is still invoked with `#call` and its own
-  context. Existing block recorders that use
-  only the `(key, update)` arguments and lexically-scoped constants are
-  unaffected; the only behavioral change is `self` inside the block.
-
-## [0.1.0.beta3] - 2026-06-18
-
-### Changed
-
-- Upgraded the bundled `yrs` (y-crdt) from 0.21 to 0.27.2. No change to the
-  `YrbLite::Doc`, `YrbLite::Awareness`, or `YrbLite::Sync` public API; existing
-  code and the wire protocol are unaffected.
-- Thread-safety is preserved across the upgrade. yrs 0.27 dropped `Awareness`'s
-  internal locking (its mutating methods now take `&mut self`, and `Awareness`
-  is no longer `Sync`), so `YrbLite::Awareness` now serializes access through an
-  internal `Mutex`. The lock is taken only while the GVL is released and is
-  never held across the GVL boundary, so concurrent access from multiple Ruby
-  threads stays safe and deadlock-free, and document reads still run in parallel
-  (they operate on a cheaply-cloned, `Arc`-backed `Doc` handle, not under the
-  presence lock).
-
-### Build
-
-- Building the gem from source now requires **Rust 1.94 or newer** (yrs 0.27.2
-  uses `let`-chains). The precompiled platform gems are unaffected -- they need
-  no Rust toolchain to install.
-
-## [0.1.0.beta2] - 2026-06-16
-
-### Added
-
-- Reliable delivery (opt-in, client-driven). A client may tag a document update
-  with an `"id"`; the server replies `{ "ack": <id> }` once the update has been
-  durably recorded. This lets an
-  ack-aware client retain and retransmit an update until delivery is confirmed,
-  so an edit can't be silently lost on a flaky connection. Clients that omit
-  `"id"` are still accepted, but their delivery is not ack-tracked.
-- Demo coverage for reliable delivery with "sync-since-last-ack" framing (the
-  unacknowledged tail is sent as one merged, causally-complete delta), plus a
-  minimal reference client and an intensive message-loss stress test.
-
-### Fixed
-
-- Causal-gap protection. The authoritative, fast, and store paths now reject a
-  document update that isn't causally ready -- one whose dependencies are
-  missing because an earlier update was lost in transit or its durable record
-  failed -- and ask the client to resync, instead of recording or relaying an
-  un-integrable update that would leave the log permanently pending. Adds native
-  `Doc#update_ready?`/`#pending?` (cheap, read-only checks) used to gate the
-  record-before-distribute path.
-
-## [0.1.0.beta1]
-
-### 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).
-- 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.
-- Store-backed ActionCable delivery for AnyCable and multi-process use.
-- 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/compare/v0.1.0.beta5...main
-[0.1.0.beta5]: https://github.com/jpcamara/yrb-lite/compare/v0.1.0.beta4...v0.1.0.beta5
-[0.1.0.beta4]: https://github.com/jpcamara/yrb-lite/compare/v0.1.0.beta3...v0.1.0.beta4
-[0.1.0.beta3]: https://github.com/jpcamara/yrb-lite/compare/v0.1.0.beta2...v0.1.0.beta3
-[0.1.0.beta2]: https://github.com/jpcamara/yrb-lite/compare/v0.1.0.beta1...v0.1.0.beta2
-[0.1.0.beta1]: https://github.com/jpcamara/yrb-lite/releases/tag/v0.1.0.beta1

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/ext/yrb_lite/src/lib.rs

@@ -1,16 +1,13 @@
 use magnus::{
     function, method, prelude::*, Error, ExceptionClass, RString, Ruby, TryConvert, Value,
 };
-use std::sync::Mutex;
-use yrs::sync::{Awareness, DefaultProtocol, Message, Protocol, SyncMessage};
+use yrs::sync::{Message, SyncMessage};
 use yrs::updates::decoder::Decode;
-use yrs::updates::encoder::{Encode, Encoder, EncoderV1};
+use yrs::updates::encoder::Encode;
 use yrs::{Doc, ReadTxn, Transact};
 
 mod protocol;
-use protocol::{
-    classify_message, doc_has_pending, merged_doc_update, update_advances_doc, update_is_ready,
-};
+use protocol::{classify_message, merged_doc_update, update_advances_doc, update_is_ready};
 
 /// Wrapper around yrs Doc.
 ///
@@ -22,37 +19,13 @@ use protocol::{
 #[magnus::wrap(class = "YrbLite::Doc", free_immediately, size)]
 struct RbDoc(Doc);
 
-/// Wrapper around yrs Awareness (which contains a Doc).
-///
-/// Thread safety: as of yrs 0.27 `Awareness` dropped its internal locking and
-/// its mutating methods (`handle`, `set_local_state`, `clean_local_state`,
-/// `remove_state`, `update_with_clients`) take `&mut self`. It is `Send` but no
-/// longer `Sync`, so we serialize all access through a `Mutex`.
-///
-/// CRITICAL: the `Mutex` is ALWAYS locked inside the `nogvl` closure (never with
-/// the GVL held) and the guard is dropped before the closure returns. This obeys
-/// the same rule as the doc's RwLock (see `nogvl`): a thread never waits on this
-/// lock while holding the GVL, and never reacquires the GVL while holding this
-/// lock, so the GVL and this `Mutex` can't deadlock on lock order. Locking with
-/// the GVL held (outside `nogvl`) reintroduces that deadlock -- don't.
-///
-/// For doc-only reads we clone the (Arc-backed) `Doc` out under the brief lock
-/// and operate on the owned clone, so a long encode holds only the doc's own
-/// RwLock, not this `Mutex`, and never blocks presence updates on another
-/// thread. Lock order is always Mutex-then-doc-RwLock (or doc-RwLock alone),
-/// never the reverse.
-#[magnus::wrap(class = "YrbLite::Awareness", free_immediately, size)]
-struct RbAwareness(Mutex<Awareness>);
-
-/// Compile-time proof that the wrapped types are thread-safe. If a future
-/// yrs upgrade makes Doc lose Send/Sync, or Awareness lose Send, this fails the
-/// build instead of silently shipping a thread-unsafe gem. (Awareness is no
-/// longer `Sync` as of yrs 0.27, hence the `Mutex` wrapper, which restores it.)
+/// Compile-time proof that the wrapped Doc is thread-safe. If a future yrs
+/// upgrade makes Doc lose Send/Sync, this fails the build instead of silently
+/// shipping a thread-unsafe gem.
 #[allow(dead_code)]
 fn assert_thread_safe() {
     fn is_send_sync<T: Send + Sync>() {}
     is_send_sync::<Doc>();
-    is_send_sync::<Mutex<Awareness>>();
 }
 
 /// Run `f` with the GVL (Global VM Lock) released, so other Ruby threads,
@@ -161,14 +134,6 @@ impl RbDoc {
         Ok(RbDoc(doc))
     }
 
-    fn client_id(&self) -> u64 {
-        self.0.client_id().get()
-    }
-
-    fn guid(&self) -> String {
-        self.0.guid().to_string()
-    }
-
     fn encode_state_vector(&self) -> RString {
         let doc = &self.0;
         let sv = nogvl(move || {
@@ -228,13 +193,6 @@ impl RbDoc {
         nogvl(move || update_advances_doc(doc, &update_bytes)).map_err(yrb_error)
     }
 
-    /// True if the document holds pending (un-integrable) structs waiting on a
-    /// missing dependency.
-    fn pending(&self) -> bool {
-        let doc = &self.0;
-        nogvl(move || doc_has_pending(doc))
-    }
-
     /// Sync step 1: Create a sync message with our state vector
     fn sync_step1(&self) -> RString {
         let doc = &self.0;
@@ -246,20 +204,6 @@ impl RbDoc {
         binary_string(&encoded)
     }
 
-    /// Sync step 2: Create a sync message with updates for the given state vector
-    fn sync_step2(&self, sv_bytes: RString) -> Result<RString, Error> {
-        let sv_data = copy_bytes(sv_bytes);
-        let doc = &self.0;
-        let encoded = nogvl(move || -> Result<Vec<u8>, String> {
-            let sv = yrs::StateVector::decode_v1(&sv_data).map_err(|e| e.to_string())?;
-            let txn = doc.transact();
-            let update = txn.encode_state_as_update_v1(&sv);
-            Ok(Message::Sync(SyncMessage::SyncStep2(update)).encode_v1())
-        })
-        .map_err(yrb_error)?;
-        Ok(binary_string(&encoded))
-    }
-
     /// Handle a sync message and return response (if any)
     /// Returns [message_type, sync_type, response_bytes] or nil
     fn handle_sync_message(&self, data: RString) -> Result<Option<(u8, u8, RString)>, Error> {
@@ -306,255 +250,46 @@ impl RbDoc {
 
         Ok(Some((msg_type, sync_type, binary_string(&response))))
     }
-
-    /// Encode raw update bytes as a sync Update message
-    fn encode_update_message(&self, update: RString) -> RString {
-        let update_bytes = copy_bytes(update);
-        let msg = Message::Sync(SyncMessage::Update(update_bytes));
-        binary_string(&msg.encode_v1())
-    }
 }
 
 // ============================================================================
-// Awareness Implementation (includes Doc + presence)
+// Protocol codec (stateless) -- exposed as `YrbLite` module functions
 // ============================================================================
+//
+// The server never holds presence or document state to classify a frame; these
+// are pure functions of their bytes. (Presence lives in the browser clients; the
+// server only relays awareness frames opaquely.)
+
+/// Wrap a raw document update in a sync Update message frame, ready to relay.
+fn wrap_update(update: RString) -> RString {
+    let update_bytes = copy_bytes(update);
+    let msg = Message::Sync(SyncMessage::Update(update_bytes));
+    binary_string(&msg.encode_v1())
+}
 
-impl RbAwareness {
-    /// Create a new Awareness with an optional client_id
-    fn new(args: &[Value]) -> Result<Self, Error> {
-        let awareness = if args.is_empty() {
-            Awareness::new(Doc::new())
-        } else {
-            let client_id: u64 = TryConvert::try_convert(args[0])?;
-            Awareness::new(Doc::with_client_id(client_id))
-        };
-        Ok(RbAwareness(Mutex::new(awareness)))
-    }
-
-    fn client_id(&self) -> u64 {
-        let awareness = &self.0;
-        nogvl(move || awareness.lock().unwrap().doc().client_id().get())
-    }
-
-    fn guid(&self) -> String {
-        let awareness = &self.0;
-        nogvl(move || awareness.lock().unwrap().doc().guid().to_string())
-    }
-
-    /// A standalone SyncStep1 message (the server's state vector). Sent as its
-    /// own frame in the opening handshake so providers that parse one message
-    /// per frame (e.g. @y-rb/actioncable) handle it correctly.
-    fn sync_step1(&self) -> RString {
-        let awareness = &self.0;
-        let encoded = nogvl(move || {
-            let doc = awareness.lock().unwrap().doc().clone();
-            let txn = doc.transact();
-            let sv = txn.state_vector();
-            Message::Sync(SyncMessage::SyncStep1(sv)).encode_v1()
-        });
-        binary_string(&encoded)
-    }
-
-    /// Create initial sync messages to send when connection opens.
-    /// Returns binary data containing SyncStep1 + Awareness update.
-    fn start(&self) -> Result<RString, Error> {
-        let awareness = &self.0;
-        let encoded = nogvl(move || -> Result<Vec<u8>, String> {
-            let awareness = awareness.lock().unwrap();
-            let protocol = DefaultProtocol;
-            let mut encoder = EncoderV1::new();
-            protocol
-                .start(&awareness, &mut encoder)
-                .map_err(|e| e.to_string())?;
-            Ok(encoder.to_vec())
-        })
-        .map_err(yrb_error)?;
-        Ok(binary_string(&encoded))
-    }
-
-    /// Handle incoming message and return response messages (if any).
-    /// Returns binary data containing response messages, or empty if no response needed.
-    fn handle(&self, data: RString) -> Result<RString, Error> {
-        let data_bytes = copy_bytes(data);
-        let awareness = &self.0;
-
-        let encoded = nogvl(move || -> Result<Vec<u8>, String> {
-            let mut awareness = awareness.lock().unwrap();
-            let protocol = DefaultProtocol;
-            let responses = protocol
-                .handle(&mut awareness, &data_bytes)
-                .map_err(|e| e.to_string())?;
-
-            if responses.is_empty() {
-                return Ok(Vec::new());
-            }
-
-            let mut encoder = EncoderV1::new();
-            for msg in responses {
-                msg.encode(&mut encoder);
-            }
-            Ok(encoder.to_vec())
-        })
-        .map_err(yrb_error)?;
-        Ok(binary_string(&encoded))
-    }
-
-    /// Encode an update message for broadcasting changes to peers.
-    fn encode_update(&self, update: RString) -> RString {
-        let update_bytes = copy_bytes(update);
-        let msg = Message::Sync(SyncMessage::Update(update_bytes));
-        binary_string(&msg.encode_v1())
-    }
-
-    fn encode_state_vector(&self) -> RString {
-        let awareness = &self.0;
-        let sv = nogvl(move || {
-            let doc = awareness.lock().unwrap().doc().clone();
-            let txn = doc.transact();
-            txn.state_vector().encode_v1()
-        });
-        binary_string(&sv)
-    }
-
-    /// Encode state as update (optionally diffed against a state vector)
-    fn encode_state_as_update(&self, args: &[Value]) -> Result<RString, Error> {
-        let sv_bytes: Option<Vec<u8>> = if args.is_empty() {
-            None
-        } else {
-            let sv_string: RString = TryConvert::try_convert(args[0])?;
-            Some(copy_bytes(sv_string))
-        };
-        let awareness = &self.0;
-        let update = nogvl(move || -> Result<Vec<u8>, String> {
-            let sv = match &sv_bytes {
-                None => yrs::StateVector::default(),
-                Some(bytes) => yrs::StateVector::decode_v1(bytes).map_err(|e| e.to_string())?,
-            };
-            let doc = awareness.lock().unwrap().doc().clone();
-            let txn = doc.transact();
-            Ok(txn.encode_state_as_update_v1(&sv))
-        })
-        .map_err(yrb_error)?;
-        Ok(binary_string(&update))
-    }
-
-    /// Set local awareness state (JSON string)
-    fn set_local_state(&self, json: String) -> Result<(), Error> {
-        let value: serde_json::Value =
-            serde_json::from_str(&json).map_err(|e| yrb_error(e.to_string()))?;
-        let awareness = &self.0;
-        nogvl(move || -> Result<(), String> {
-            awareness
-                .lock()
-                .unwrap()
-                .set_local_state(value)
-                .map_err(|e| e.to_string())
-        })
-        .map_err(yrb_error)
-    }
-
-    /// Get local awareness state as JSON string (or nil if not set)
-    fn local_state(&self) -> Option<String> {
-        let awareness = &self.0;
-        nogvl(move || {
-            awareness
-                .lock()
-                .unwrap()
-                .local_state::<serde_json::Value>()
-                .map(|v| v.to_string())
-        })
-    }
-
-    /// Clear local awareness state
-    fn clear_local_state(&self) {
-        let awareness = &self.0;
-        nogvl(move || awareness.lock().unwrap().clean_local_state());
-    }
-
-    /// Get awareness update for broadcasting to peers
-    fn encode_awareness_update(&self) -> Result<RString, Error> {
-        let awareness = &self.0;
-        let encoded = nogvl(move || -> Result<Vec<u8>, String> {
-            let awareness = awareness.lock().unwrap();
-            let update = awareness.update().map_err(|e| e.to_string())?;
-            Ok(Message::Awareness(update).encode_v1())
-        })
-        .map_err(yrb_error)?;
-        Ok(binary_string(&encoded))
-    }
-
-    fn apply_update(&self, update: RString) -> Result<(), Error> {
-        let update_bytes = copy_bytes(update);
-        let awareness = &self.0;
-        nogvl(move || -> Result<(), String> {
-            let update = yrs::Update::decode_v1(&update_bytes).map_err(|e| e.to_string())?;
-            let doc = awareness.lock().unwrap().doc().clone();
-            let mut txn = doc.transact_mut();
-            txn.apply_update(update).map_err(|e| e.to_string())
-        })
-        .map_err(yrb_error)
-    }
-
-    /// True if applying `update` would integrate cleanly (its dependencies are
-    /// all present). False means it depends on a missing, causally-prior update.
-    /// Pure read; does not mutate.
-    fn update_ready(&self, update: RString) -> Result<bool, Error> {
-        let update_bytes = copy_bytes(update);
-        let awareness = &self.0;
-        nogvl(move || {
-            let doc = awareness.lock().unwrap().doc().clone();
-            update_is_ready(&doc, &update_bytes)
-        })
-        .map_err(yrb_error)
-    }
-
-    /// True if applying `update` would change the document, false if it's an
-    /// already-applied retry. See `update_advances_doc`. Pure read.
-    fn update_advances(&self, update: RString) -> Result<bool, Error> {
-        let update_bytes = copy_bytes(update);
-        let awareness = &self.0;
-        nogvl(move || {
-            let doc = awareness.lock().unwrap().doc().clone();
-            update_advances_doc(&doc, &update_bytes)
-        })
-        .map_err(yrb_error)
-    }
-
-    /// True if the document holds pending (un-integrable) structs waiting on a
-    /// missing dependency.
-    fn pending(&self) -> bool {
-        let awareness = &self.0;
-        nogvl(move || {
-            let doc = awareness.lock().unwrap().doc().clone();
-            doc_has_pending(&doc)
-        })
-    }
-
-    /// Classify a frame for safe routing and relay. Returns a code only when
-    /// the frame is exactly one well-formed message that consumes the whole
-    /// buffer, so a malformed, truncated, multi-message, or trailing-garbage
-    /// frame (which a malicious client could craft to disrupt others if
-    /// relayed) is rejected up front:
-    ///   0 = drop (malformed, multiple, unknown, or empty)
-    ///   1 = sync step1       (a request: respond, do not relay)
-    ///   2 = sync step2/update (a document change: record/apply/relay)
-    ///   3 = awareness        (presence: relay)
-    ///   4 = awareness query  (a request: respond, do not relay)
-    fn message_kind(&self, data: RString) -> u8 {
-        let data_bytes = copy_bytes(data);
-        nogvl(move || classify_message(&data_bytes))
-    }
+/// Classify a frame for safe routing and relay. Returns a code only when the
+/// frame is exactly one well-formed message that consumes the whole buffer, so
+/// a malformed, truncated, multi-message, or trailing-garbage frame (which a
+/// malicious client could craft to disrupt others if relayed) is rejected up
+/// front:
+///   0 = drop (malformed, multiple, unknown, or empty)
+///   1 = sync step1       (a request: respond, do not relay)
+///   2 = sync step2/update (a document change: record/apply/relay)
+///   3 = awareness        (presence: relay)
+///   4 = awareness query  (a request: respond, do not relay)
+fn message_kind(data: RString) -> u8 {
+    let data_bytes = copy_bytes(data);
+    nogvl(move || classify_message(&data_bytes))
+}
 
-    /// Extract the document-update delta carried by a protocol message: the
-    /// payloads of any Update or SyncStep2 sub-messages, merged into a single
-    /// update. Returns nil if the message carries no document change (for
-    /// instance a SyncStep1 request or an awareness update). The store-backed
-    /// path records this exact delta before relaying it.
-    fn update_from_message(&self, data: RString) -> Result<Option<RString>, Error> {
-        let data_bytes = copy_bytes(data);
-        let merged = nogvl(move || merged_doc_update(&data_bytes)).map_err(yrb_error)?;
-        Ok(merged.map(|b| binary_string(&b)))
-    }
+/// Extract the document-update delta carried by a protocol message: the payloads
+/// of any Update or SyncStep2 sub-messages, merged into a single update. Returns
+/// nil if the message carries no document change (a SyncStep1 request or an
+/// awareness update). The store-backed path records this exact delta before relay.
+fn update_from_message(data: RString) -> Result<Option<RString>, Error> {
+    let data_bytes = copy_bytes(data);
+    let merged = nogvl(move || merged_doc_update(&data_bytes)).map_err(yrb_error)?;
+    Ok(merged.map(|b| binary_string(&b)))
 }
 
 // ============================================================================
@@ -572,8 +307,6 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     // Define Doc class
     let doc_class = module.define_class("Doc", ruby.class_object())?;
     doc_class.define_singleton_method("new", function!(RbDoc::new, -1))?;
-    doc_class.define_method("client_id", method!(RbDoc::client_id, 0))?;
-    doc_class.define_method("guid", method!(RbDoc::guid, 0))?;
     doc_class.define_method(
         "encode_state_vector",
         method!(RbDoc::encode_state_vector, 0),
@@ -585,54 +318,15 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     doc_class.define_method("apply_update", method!(RbDoc::apply_update, 1))?;
     doc_class.define_method("update_ready?", method!(RbDoc::update_ready, 1))?;
     doc_class.define_method("update_advances?", method!(RbDoc::update_advances, 1))?;
-    doc_class.define_method("pending?", method!(RbDoc::pending, 0))?;
     doc_class.define_method("sync_step1", method!(RbDoc::sync_step1, 0))?;
-    doc_class.define_method("sync_step2", method!(RbDoc::sync_step2, 1))?;
     doc_class.define_method(
         "handle_sync_message",
         method!(RbDoc::handle_sync_message, 1),
     )?;
-    doc_class.define_method(
-        "encode_update_message",
-        method!(RbDoc::encode_update_message, 1),
-    )?;
-
-    // Define Awareness class
-    let awareness_class = module.define_class("Awareness", ruby.class_object())?;
-    awareness_class.define_singleton_method("new", function!(RbAwareness::new, -1))?;
-    awareness_class.define_method("client_id", method!(RbAwareness::client_id, 0))?;
-    awareness_class.define_method("guid", method!(RbAwareness::guid, 0))?;
-    awareness_class.define_method("start", method!(RbAwareness::start, 0))?;
-    awareness_class.define_method("sync_step1", method!(RbAwareness::sync_step1, 0))?;
-    awareness_class.define_method("handle", method!(RbAwareness::handle, 1))?;
-    awareness_class.define_method("encode_update", method!(RbAwareness::encode_update, 1))?;
-    awareness_class.define_method(
-        "encode_state_vector",
-        method!(RbAwareness::encode_state_vector, 0),
-    )?;
-    awareness_class.define_method(
-        "encode_state_as_update",
-        method!(RbAwareness::encode_state_as_update, -1),
-    )?;
-    awareness_class.define_method("apply_update", method!(RbAwareness::apply_update, 1))?;
-    awareness_class.define_method("update_ready?", method!(RbAwareness::update_ready, 1))?;
-    awareness_class.define_method("update_advances?", method!(RbAwareness::update_advances, 1))?;
-    awareness_class.define_method("pending?", method!(RbAwareness::pending, 0))?;
-    awareness_class.define_method("set_local_state", method!(RbAwareness::set_local_state, 1))?;
-    awareness_class.define_method("local_state", method!(RbAwareness::local_state, 0))?;
-    awareness_class.define_method(
-        "clear_local_state",
-        method!(RbAwareness::clear_local_state, 0),
-    )?;
-    awareness_class.define_method(
-        "encode_awareness_update",
-        method!(RbAwareness::encode_awareness_update, 0),
-    )?;
-    awareness_class.define_method(
-        "update_from_message",
-        method!(RbAwareness::update_from_message, 1),
-    )?;
-    awareness_class.define_method("message_kind", method!(RbAwareness::message_kind, 1))?;
+    // Stateless protocol codec, as YrbLite module functions.
+    module.define_module_function("wrap_update", function!(wrap_update, 1))?;
+    module.define_module_function("message_kind", function!(message_kind, 1))?;
+    module.define_module_function("update_from_message", function!(update_from_message, 1))?;
 
     // Define message type constants
     module.const_set("MSG_SYNC", 0u8)?;

data/ext/yrb_lite/src/protocol.rs

@@ -53,7 +53,7 @@ pub(crate) fn merged_doc_update(bytes: &[u8]) -> Result<Option<Vec<u8>>, String>
     let update = yrs::Update::decode_v1(&merged).map_err(|e| e.to_string())?;
     // A genuine no-op (e.g. the empty SyncStep2 in an opening handshake) carries
     // no structs, no deletes, and no dependencies. We must NOT treat a causally-
-    // pending update as a no-op: since yrs 0.26 such an update reports an empty
+    // pending update as a no-op: such an update reports an empty
     // state_vector (its structs can't integrate yet), but it still carries
     // content and a non-empty lower bound (the deps it's waiting on). Dropping it
     // here would silently swallow a gappy update instead of rejecting + resyncing.
@@ -115,8 +115,9 @@ pub(crate) fn update_advances_doc(doc: &Doc, update_bytes: &[u8]) -> Result<bool
 }
 
 /// True if the doc holds pending structs or a pending delete set -- blocks that
-/// couldn't integrate because a dependency is missing. Used as a backstop after
-/// loading from storage: leftover pending means the stored log has a causal gap.
+/// couldn't integrate because a dependency is missing. Test-only: asserts the
+/// causal-chain parking behavior in the unit tests below.
+#[cfg(test)]
 pub(crate) fn doc_has_pending(doc: &Doc) -> bool {
     let txn = doc.transact();
     txn.store().pending_update().is_some() || txn.store().pending_ds().is_some()

data/lib/yrb_lite/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yrb-lite
 version: !ruby/object:Gem::Version
-  version: 0.1.0.beta7
+  version: 0.1.0.beta9
 platform: ruby
 authors:
 - JP Camara