yrb-lite 0.1.0.beta6 → 0.1.0.beta9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9553ad44479cc56e9ccd2645017c8ebf3dba79a0d5905651396b5f397ca1ad6a
-  data.tar.gz: 8c81c7a844a50def1af8b4a2cdbb1bbf95f576077976b7cc6fc4aef740173164
+  metadata.gz: 8d834b5052572c1d84374702a2c45963522725abf47eaaefd62acc934b75a4fe
+  data.tar.gz: 025f4e5ae96c0fd3c9af6e43e2ddd16c4bc22cb34b95b17ad70f8ff74283557b
 SHA512:
-  metadata.gz: 0db8acba6f12e4f9f9289cb80b7d2aa4870ed2c26f090eea1529fd19fa1a1b07c6731ec36097c96a47735f5f6abbf91f592701512250487acf053edd734eb771
-  data.tar.gz: d5c4e9e3a98f16735b150c76c68e5e7b584c329f554edf12c3949d4104e5b9a06c31fe9d3082bc2f510f67f17fa0ea9402d373ad926320c2f96eb2af744f60a1
+  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,18 +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::{ClientID, Doc, ReadTxn, Transact};
+use yrs::updates::encoder::Encode;
+use yrs::{Doc, ReadTxn, Transact};
 
 mod protocol;
-use protocol::{
-    awareness_client_ids_in, classify_message, doc_has_pending, merged_doc_update,
-    update_advances_doc, update_is_ready, validate_frame_client_ids,
-    validate_state_vector_client_ids, validate_update_client_ids,
-};
+use protocol::{classify_message, merged_doc_update, update_advances_doc, update_is_ready};
 
 /// Wrapper around yrs Doc.
 ///
@@ -24,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,
@@ -131,9 +102,9 @@ fn copy_bytes(s: RString) -> Vec<u8> {
 }
 
 /// Build a `YrbLite::Error` (the gem's own error class, defined in `init`) so
-/// native decode/apply/validation failures surface as a project-specific error
-/// rather than a generic RuntimeError. Falls back to RuntimeError only if the
-/// class somehow can't be resolved.
+/// native decode/apply failures surface as a project-specific error rather than
+/// a generic RuntimeError. Falls back to RuntimeError only if the class somehow
+/// can't be resolved.
 fn yrb_error(msg: String) -> Error {
     let ruby = Ruby::get().unwrap();
     let class = ruby
@@ -142,26 +113,10 @@ fn yrb_error(msg: String) -> Error {
     Error::new(class, msg)
 }
 
-/// Yjs/lib0 client IDs must be JS-safe integers (<= 2^53 - 1). Above that they
-/// round or collide when crossing the JS/Yjs boundary, and a client-id collision
-/// corrupts a CRDT. Explicit (Ruby-supplied) IDs are validated here; the random
-/// default IDs that yrs generates are already in range.
-const MAX_SAFE_CLIENT_ID: u64 = (1 << 53) - 1;
-
-/// Pure predicate (no Ruby), so the boundary is unit-testable without a VM.
-pub(crate) fn is_safe_client_id(id: u64) -> bool {
-    id <= MAX_SAFE_CLIENT_ID
-}
-
-fn validate_client_id(id: u64) -> Result<u64, Error> {
-    if !is_safe_client_id(id) {
-        return Err(yrb_error(format!(
-            "client_id {id} exceeds the maximum safe integer ({MAX_SAFE_CLIENT_ID} = 2^53 - 1); \
-             Yjs client IDs must be JS-safe integers to avoid collisions"
-        )));
-    }
-    Ok(id)
-}
+// CLIENT IDs ARE NOT VALIDATED -- whoever supplies the id (the app via
+// `Doc.new(id)` / `Awareness.new(id)`, or a remote peer over the wire) is
+// responsible for keeping it JS-safe (<= 2^53 - 1). See the protocol.rs header
+// for why (and `ClientID::try_new`, proposed upstream, for strict rejection).
 
 // ============================================================================
 // Doc Implementation
@@ -173,23 +128,12 @@ impl RbDoc {
         let doc = if args.is_empty() {
             Doc::new()
         } else {
-            let client_id = validate_client_id(TryConvert::try_convert(args[0])?)?;
+            let client_id: u64 = TryConvert::try_convert(args[0])?;
             Doc::with_client_id(client_id)
         };
         Ok(RbDoc(doc))
     }
 
-    /// Get the client ID
-    fn client_id(&self) -> u64 {
-        self.0.client_id().get()
-    }
-
-    /// Get the document GUID
-    fn guid(&self) -> String {
-        self.0.guid().to_string()
-    }
-
-    /// Get the current state vector encoded as bytes
     fn encode_state_vector(&self) -> RString {
         let doc = &self.0;
         let sv = nogvl(move || {
@@ -220,12 +164,10 @@ impl RbDoc {
         Ok(binary_string(&update))
     }
 
-    /// Apply a V1 update to the document
     fn apply_update(&self, update: RString) -> Result<(), Error> {
         let update_bytes = copy_bytes(update);
         let doc = &self.0;
         nogvl(move || -> Result<(), String> {
-            validate_update_client_ids(&update_bytes)?;
             let update = yrs::Update::decode_v1(&update_bytes).map_err(|e| e.to_string())?;
             let mut txn = doc.transact_mut();
             txn.apply_update(update).map_err(|e| e.to_string())
@@ -251,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;
@@ -269,21 +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> {
-            validate_state_vector_client_ids(&sv_data)?;
-            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> {
@@ -292,7 +212,6 @@ impl RbDoc {
 
         let (msg_type, sync_type, response) =
             nogvl(move || -> Result<(u8, u8, Vec<u8>), String> {
-                validate_frame_client_ids(&data_bytes)?;
                 let msg = Message::decode_v1(&data_bytes).map_err(|e| e.to_string())?;
 
                 match msg {
@@ -331,309 +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 = validate_client_id(TryConvert::try_convert(args[0])?)?;
-            Awareness::new(Doc::with_client_id(client_id))
-        };
-        Ok(RbAwareness(Mutex::new(awareness)))
-    }
-
-    /// Get the client ID of the underlying document
-    fn client_id(&self) -> u64 {
-        let awareness = &self.0;
-        nogvl(move || awareness.lock().unwrap().doc().client_id().get())
-    }
-
-    /// Get the document GUID
-    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> {
-            validate_frame_client_ids(&data_bytes)?;
-            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) -> Result<RString, Error> {
-        let update_bytes = copy_bytes(update);
-        nogvl({
-            let update_bytes = update_bytes.clone();
-            move || validate_update_client_ids(&update_bytes)
-        })
-        .map_err(yrb_error)?;
-        let msg = Message::Sync(SyncMessage::Update(update_bytes));
-        Ok(binary_string(&msg.encode_v1()))
-    }
-
-    /// Get the current state vector encoded as bytes
-    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))
-    }
-
-    /// Apply a raw update to the underlying document
-    fn apply_update(&self, update: RString) -> Result<(), Error> {
-        let update_bytes = copy_bytes(update);
-        let awareness = &self.0;
-        nogvl(move || -> Result<(), String> {
-            validate_update_client_ids(&update_bytes)?;
-            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)
-        })
-    }
-
-    /// Decode the awareness client IDs referenced by a protocol message
-    /// (which may pack several sub-messages together). Sync sub-messages are
-    /// ignored. The ActionCable layer uses this to learn which presence
-    /// states arrived on a connection, so it can clear them when that
-    /// connection closes.
-    fn awareness_client_ids(&self, data: RString) -> Result<Vec<u64>, Error> {
-        let data_bytes = copy_bytes(data);
-        nogvl(move || awareness_client_ids_in(&data_bytes)).map_err(yrb_error)
-    }
-
-    /// 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))
-    }
-
-    /// 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 strict audit
-    /// path records this exact delta before applying 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)))
-    }
+/// 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))
+}
 
-    /// Mark the given clients as disconnected and return an awareness protocol
-    /// message (null-state, bumped clock) announcing their removal to peers.
-    /// Only clients currently known to this Awareness are removed; unknown
-    /// IDs are skipped (so we never broadcast phantom removals). Returns an
-    /// empty string when nothing was removed.
-    fn remove_clients(&self, client_ids: Vec<u64>) -> Result<RString, Error> {
-        let client_ids = client_ids
-            .into_iter()
-            .map(validate_client_id)
-            .collect::<Result<Vec<_>, _>>()?;
-        let awareness = &self.0;
-        let encoded = nogvl(move || -> Result<Vec<u8>, String> {
-            let mut awareness = awareness.lock().unwrap();
-            let mut removed = Vec::new();
-            for id in client_ids {
-                let cid = ClientID::new(id);
-                if awareness.meta(cid).is_some() {
-                    awareness.remove_state(cid);
-                    removed.push(cid);
-                }
-            }
-            if removed.is_empty() {
-                return Ok(Vec::new());
-            }
-            let update = awareness
-                .update_with_clients(removed)
-                .map_err(|e| e.to_string())?;
-            Ok(Message::Awareness(update).encode_v1())
-        })
-        .map_err(yrb_error)?;
-        Ok(binary_string(&encoded))
-    }
+/// 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)))
 }
 
 // ============================================================================
@@ -651,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),
@@ -664,59 +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(
-        "awareness_client_ids",
-        method!(RbAwareness::awareness_client_ids, 1),
-    )?;
-    awareness_class.define_method("remove_clients", method!(RbAwareness::remove_clients, 1))?;
-    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

@@ -1,219 +1,18 @@
-// Pure protocol helpers: no Ruby, no GVL, no `unsafe`. Everything here operates
-// on plain byte slices and `yrs` types, so it's unit-tested directly (see the
-// `tests` module below) without a Ruby VM. The Ruby-facing wrappers in lib.rs
-// copy bytes out of Ruby strings and call into these under `nogvl`.
-use crate::is_safe_client_id;
-use std::sync::Arc;
-use yrs::encoding::read::{Cursor, Error as ReadError, Read};
-use yrs::sync::protocol::{
-    MessageReader, MSG_AUTH, MSG_AWARENESS, MSG_QUERY_AWARENESS, MSG_SYNC, MSG_SYNC_STEP_1,
-    MSG_SYNC_STEP_2, MSG_SYNC_UPDATE, PERMISSION_DENIED,
-};
+// Pure rust protocol helpers (ie, no Ruby interop).
+//
+// CLIENT IDs ARE NOT VALIDATED HERE -- on purpose. We deliberately don't police it -- every
+// legitimate peer (browser Yjs, and yrs's own `ClientID::random`) already emits
+// 53-bit ids, so it's the client's responsibility not to send a bad one, and we
+// don't want to own that logic.
+use yrs::encoding::read::{Cursor, Read};
+use yrs::sync::protocol::MessageReader;
 use yrs::sync::{Message, SyncMessage};
-use yrs::updates::decoder::{Decode, Decoder, DecoderV1};
-use yrs::{Any, ClientID, Doc, ReadTxn, Transact, ID};
-
-fn unsafe_client_id_error(id: u64) -> ReadError {
-    ReadError::Custom(format!(
-        "client_id {id} exceeds the maximum safe integer (2^53 - 1); \
-         Yjs client IDs must be JS-safe integers to avoid collisions"
-    ))
-}
-
-fn checked_client_id(id: u64) -> Result<ClientID, ReadError> {
-    if !is_safe_client_id(id) {
-        return Err(unsafe_client_id_error(id));
-    }
-    Ok(ClientID::new(id))
-}
-
-fn validate_raw_client_id(id: u64) -> Result<(), ReadError> {
-    if !is_safe_client_id(id) {
-        return Err(unsafe_client_id_error(id));
-    }
-    Ok(())
-}
-
-struct CheckedDecoderV1<'a> {
-    cursor: Cursor<'a>,
-}
-
-impl<'a> CheckedDecoderV1<'a> {
-    fn new(cursor: Cursor<'a>) -> Self {
-        CheckedDecoderV1 { cursor }
-    }
-
-    fn read_id(&mut self) -> Result<ID, ReadError> {
-        let client: u64 = self.read_var()?;
-        validate_raw_client_id(client)?;
-        let clock = self.read_var()?;
-        Ok(ID::new(ClientID::new(client), clock))
-    }
-}
-
-impl<'a> Read for CheckedDecoderV1<'a> {
-    #[inline]
-    fn read_u8(&mut self) -> Result<u8, ReadError> {
-        self.cursor.read_u8()
-    }
-
-    #[inline]
-    fn read_exact(&mut self, len: usize) -> Result<&[u8], ReadError> {
-        self.cursor.read_exact(len)
-    }
-}
-
-impl<'a> Decoder for CheckedDecoderV1<'a> {
-    #[inline]
-    fn reset_ds_cur_val(&mut self) {}
-
-    #[inline]
-    fn read_ds_clock(&mut self) -> Result<u32, ReadError> {
-        self.read_var()
-    }
-
-    #[inline]
-    fn read_ds_len(&mut self) -> Result<u32, ReadError> {
-        self.read_var()
-    }
-
-    #[inline]
-    fn read_left_id(&mut self) -> Result<ID, ReadError> {
-        self.read_id()
-    }
-
-    #[inline]
-    fn read_right_id(&mut self) -> Result<ID, ReadError> {
-        self.read_id()
-    }
-
-    #[inline]
-    fn read_client(&mut self) -> Result<ClientID, ReadError> {
-        let client: u64 = self.cursor.read_var()?;
-        checked_client_id(client)
-    }
-
-    #[inline]
-    fn read_info(&mut self) -> Result<u8, ReadError> {
-        self.cursor.read_u8()
-    }
-
-    #[inline]
-    fn read_parent_info(&mut self) -> Result<bool, ReadError> {
-        let info: u32 = self.cursor.read_var()?;
-        Ok(info == 1)
-    }
-
-    #[inline]
-    fn read_type_ref(&mut self) -> Result<u8, ReadError> {
-        self.cursor.read_u8()
-    }
-
-    #[inline]
-    fn read_len(&mut self) -> Result<u32, ReadError> {
-        self.read_var()
-    }
-
-    #[inline]
-    fn read_any(&mut self) -> Result<Any, ReadError> {
-        Any::decode(self)
-    }
-
-    #[inline]
-    fn read_json(&mut self) -> Result<Any, ReadError> {
-        let src = self.read_string()?;
-        Any::from_json(src)
-    }
-
-    #[inline]
-    fn read_key(&mut self) -> Result<Arc<str>, ReadError> {
-        let str: Arc<str> = self.read_string()?.into();
-        Ok(str)
-    }
-
-    #[inline]
-    fn read_to_end(&mut self) -> Result<&[u8], ReadError> {
-        Ok(&self.cursor.buf[self.cursor.next..])
-    }
-}
-
-pub(crate) fn validate_state_vector_client_ids(bytes: &[u8]) -> Result<(), String> {
-    let mut cursor = Cursor::new(bytes);
-    let len: u32 = cursor.read_var().map_err(|e| e.to_string())?;
-    for _ in 0..len {
-        let client: u64 = cursor.read_var().map_err(|e| e.to_string())?;
-        validate_raw_client_id(client).map_err(|e| e.to_string())?;
-        let _: u32 = cursor.read_var().map_err(|e| e.to_string())?;
-    }
-    if cursor.has_content() {
-        return Err("state vector has trailing bytes".to_string());
-    }
-    Ok(())
-}
-
-pub(crate) fn validate_update_client_ids(update_bytes: &[u8]) -> Result<(), String> {
-    let mut decoder = CheckedDecoderV1::new(Cursor::new(update_bytes));
-    yrs::Update::decode(&mut decoder).map_err(|e| e.to_string())?;
-    if decoder.cursor.has_content() {
-        return Err("update has trailing bytes".to_string());
-    }
-    Ok(())
-}
-
-fn validate_awareness_update_client_ids(bytes: &[u8]) -> Result<(), String> {
-    let mut cursor = Cursor::new(bytes);
-    let len: u32 = cursor.read_var().map_err(|e| e.to_string())?;
-    for _ in 0..len {
-        let client: u64 = cursor.read_var().map_err(|e| e.to_string())?;
-        validate_raw_client_id(client).map_err(|e| e.to_string())?;
-        let _: u32 = cursor.read_var().map_err(|e| e.to_string())?;
-        let _ = cursor.read_string().map_err(|e| e.to_string())?;
-    }
-    if cursor.has_content() {
-        return Err("awareness update has trailing bytes".to_string());
-    }
-    Ok(())
-}
-
-pub(crate) fn validate_frame_client_ids(bytes: &[u8]) -> Result<(), String> {
-    let mut cursor = Cursor::new(bytes);
-    while cursor.has_content() {
-        let tag: u8 = cursor.read_var().map_err(|e| e.to_string())?;
-        match tag {
-            MSG_SYNC => {
-                let sync_tag: u8 = cursor.read_var().map_err(|e| e.to_string())?;
-                let payload = cursor.read_buf().map_err(|e| e.to_string())?;
-                match sync_tag {
-                    MSG_SYNC_STEP_1 => validate_state_vector_client_ids(payload)?,
-                    MSG_SYNC_STEP_2 | MSG_SYNC_UPDATE => validate_update_client_ids(payload)?,
-                    _ => return Err("unknown sync message type".to_string()),
-                }
-            }
-            MSG_AWARENESS => {
-                let payload = cursor.read_buf().map_err(|e| e.to_string())?;
-                validate_awareness_update_client_ids(payload)?;
-            }
-            MSG_AUTH => {
-                let permission: u8 = cursor.read_var().map_err(|e| e.to_string())?;
-                if permission == PERMISSION_DENIED {
-                    let _ = cursor.read_string().map_err(|e| e.to_string())?;
-                }
-            }
-            MSG_QUERY_AWARENESS => {}
-            _ => {
-                let _ = cursor.read_buf().map_err(|e| e.to_string())?;
-            }
-        }
-    }
-    Ok(())
-}
+use yrs::updates::decoder::{Decode, DecoderV1};
+use yrs::{Doc, ReadTxn, Transact};
 
 /// Classify a frame: a non-zero code only for exactly one well-formed message
 /// that consumes the whole buffer (see `RbAwareness::message_kind` for codes).
 pub(crate) fn classify_message(bytes: &[u8]) -> u8 {
-    if validate_frame_client_ids(bytes).is_err() {
-        return 0;
-    }
     let mut decoder = DecoderV1::new(Cursor::new(bytes));
     let msg = match Message::decode(&mut decoder) {
         Ok(msg) => msg,
@@ -236,7 +35,6 @@ pub(crate) fn classify_message(bytes: &[u8]) -> u8 {
 /// frame into one update, or `None` if the frame carries no document change
 /// (a request, an awareness update, or a no-op handshake SyncStep2).
 pub(crate) fn merged_doc_update(bytes: &[u8]) -> Result<Option<Vec<u8>>, String> {
-    validate_frame_client_ids(bytes)?;
     let mut decoder = DecoderV1::new(Cursor::new(bytes));
     let mut updates: Vec<Vec<u8>> = Vec::new();
     for msg in MessageReader::new(&mut decoder) {
@@ -255,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.
@@ -268,26 +66,12 @@ pub(crate) fn merged_doc_update(bytes: &[u8]) -> Result<Option<Vec<u8>>, String>
     Ok(Some(merged))
 }
 
-/// Collect the awareness client IDs referenced by a frame's awareness messages.
-pub(crate) fn awareness_client_ids_in(bytes: &[u8]) -> Result<Vec<u64>, String> {
-    validate_frame_client_ids(bytes)?;
-    let mut decoder = DecoderV1::new(Cursor::new(bytes));
-    let mut ids = Vec::new();
-    for msg in MessageReader::new(&mut decoder) {
-        if let Message::Awareness(update) = msg.map_err(|e| e.to_string())? {
-            ids.extend(update.clients.keys().map(|c| c.get()));
-        }
-    }
-    Ok(ids)
-}
-
 /// True if applying `update_bytes` to `doc` would integrate cleanly: every
 /// dependency the update references is already present (the doc's state vector
 /// covers the update's lower bound). A pure read; does not mutate the doc.
 /// When false, applying it would park a pending struct -- the signal that an
 /// earlier, causally-prior update is missing.
 pub(crate) fn update_is_ready(doc: &Doc, update_bytes: &[u8]) -> Result<bool, String> {
-    validate_update_client_ids(update_bytes)?;
     let update = yrs::Update::decode_v1(update_bytes).map_err(|e| e.to_string())?;
     Ok(doc.transact().state_vector() >= update.state_vector_lower())
 }
@@ -309,7 +93,6 @@ pub(crate) fn update_is_ready(doc: &Doc, update_bytes: &[u8]) -> Result<bool, St
 /// double-record a pure-delete retry, but it NEVER drops a real deletion, which
 /// is the safe direction. Assumes the update is already causally ready.
 pub(crate) fn update_advances_doc(doc: &Doc, update_bytes: &[u8]) -> Result<bool, String> {
-    validate_update_client_ids(update_bytes)?;
     let update = yrs::Update::decode_v1(update_bytes).map_err(|e| e.to_string())?;
     if !update.delete_set().is_empty() {
         return Ok(true); // can't cheaply prove a delete is a duplicate; record it
@@ -332,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()
@@ -342,10 +126,8 @@ pub(crate) fn doc_has_pending(doc: &Doc) -> bool {
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::is_safe_client_id;
-    use yrs::encoding::write::Write;
     use yrs::sync::Awareness;
-    use yrs::updates::encoder::{Encode, Encoder, EncoderV1};
+    use yrs::updates::encoder::Encode;
     use yrs::Text;
 
     fn text_update(content: &str) -> Vec<u8> {
@@ -374,42 +156,6 @@ mod tests {
         Message::Awareness(awareness.update().unwrap()).encode_v1()
     }
 
-    fn unsafe_struct_client_update() -> Vec<u8> {
-        let mut update = EncoderV1::new();
-        update.write_var(1u32); // client count
-        update.write_var(0u32); // block count for this client
-        update.write_var(1u64 << 53); // unsafe client id
-        update.write_var(0u32); // clock
-        update.write_var(0u32); // delete-set client count
-        update.to_vec()
-    }
-
-    fn unsafe_awareness_frame() -> Vec<u8> {
-        let mut payload = EncoderV1::new();
-        payload.write_var(1u32); // client count
-        payload.write_var(1u64 << 53); // unsafe client id
-        payload.write_var(1u32); // clock
-        payload.write_string("{}");
-
-        let mut frame = EncoderV1::new();
-        frame.write_var(MSG_AWARENESS);
-        frame.write_buf(payload.to_vec());
-        frame.to_vec()
-    }
-
-    fn unsafe_step1_frame() -> Vec<u8> {
-        let mut sv = EncoderV1::new();
-        sv.write_var(1u32); // state-vector entry count
-        sv.write_var(1u64 << 53); // unsafe client id
-        sv.write_var(0u32); // clock
-
-        let mut frame = EncoderV1::new();
-        frame.write_var(MSG_SYNC);
-        frame.write_var(MSG_SYNC_STEP_1);
-        frame.write_buf(sv.to_vec());
-        frame.to_vec()
-    }
-
     #[test]
     fn classify_accepts_clean_single_messages() {
         assert_eq!(classify_message(&step1_frame()), 1);
@@ -500,51 +246,6 @@ mod tests {
         );
     }
 
-    #[test]
-    fn client_id_safe_integer_boundary() {
-        assert!(is_safe_client_id(0), "zero is fine");
-        assert!(
-            is_safe_client_id((1 << 53) - 1),
-            "2^53 - 1 is the max safe id"
-        );
-        assert!(!is_safe_client_id(1 << 53), "2^53 is unsafe");
-        assert!(!is_safe_client_id(1 << 63), "2^63 is unsafe");
-        assert!(!is_safe_client_id(u64::MAX), "u64::MAX is unsafe");
-    }
-
-    #[test]
-    fn wire_client_id_validation_rejects_unsafe_sync_update_clients() {
-        let update = unsafe_struct_client_update();
-        assert!(
-            validate_update_client_ids(&update).is_err(),
-            "raw unsafe update client id is rejected before yrs can mask it"
-        );
-
-        let frame = Message::Sync(SyncMessage::Update(update)).encode_v1();
-        assert_eq!(
-            classify_message(&frame),
-            0,
-            "unsafe sync frame is not relayable"
-        );
-        assert!(merged_doc_update(&frame).is_err());
-    }
-
-    #[test]
-    fn wire_client_id_validation_rejects_unsafe_awareness_and_step1_clients() {
-        assert!(
-            validate_frame_client_ids(&unsafe_awareness_frame()).is_err(),
-            "raw unsafe awareness client id is rejected"
-        );
-        assert_eq!(classify_message(&unsafe_awareness_frame()), 0);
-        assert!(awareness_client_ids_in(&unsafe_awareness_frame()).is_err());
-
-        assert!(
-            validate_frame_client_ids(&unsafe_step1_frame()).is_err(),
-            "raw unsafe state-vector client id is rejected"
-        );
-        assert_eq!(classify_message(&unsafe_step1_frame()), 0);
-    }
-
     #[test]
     fn merged_doc_update_extracts_and_skips_no_ops() {
         // A document update yields a delta that reconstructs the content.
@@ -582,18 +283,6 @@ mod tests {
         assert!(yrs::Update::decode_v1(&merged).is_ok());
     }
 
-    #[test]
-    fn awareness_client_ids_are_collected() {
-        assert_eq!(
-            awareness_client_ids_in(&awareness_frame(111)).unwrap(),
-            vec![111]
-        );
-        // A document frame has no awareness client ids.
-        assert!(awareness_client_ids_in(&update_frame("x"))
-            .unwrap()
-            .is_empty());
-    }
-
     #[test]
     fn update_readiness_and_pending_detect_a_causal_gap() {
         // Three sequential single-char inserts from one client: A, then B, then

data/lib/yrb_lite/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module YrbLite
-  VERSION = "0.1.0.beta6"
+  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.beta6
+  version: 0.1.0.beta9
 platform: ruby
 authors:
 - JP Camara