yrb-lite 0.1.0.beta9 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8d834b5052572c1d84374702a2c45963522725abf47eaaefd62acc934b75a4fe
-  data.tar.gz: 025f4e5ae96c0fd3c9af6e43e2ddd16c4bc22cb34b95b17ad70f8ff74283557b
+  metadata.gz: 44da78141b84de4cf438a8b0315b4fdf92bf10290787f569e1c9f63087f2abf8
+  data.tar.gz: dce6b3a9227637b8e8828c8d23726b178107c19dd8670bd580da6d71d848bb6a
 SHA512:
-  metadata.gz: 73e9cd5d0bf9ffbf3c729f54390731376dd443d1f59fa597917c926f3c6326089903ab7b9c67a2dc037de343368d6f1f045f937fae99a2c01d430500fd0f6fe5
-  data.tar.gz: 67ad34f34202019617905d035e6cfb91f3693534eebed93d3fbb612b1e410bc75803f4bc2c311bedff076bed15c3718a4100153e3b42ae1de74e9cae0d7f73a5
+  metadata.gz: d4b3df640c6e502acd8545e18e019998c8d4200f3e7c3a6e70fc9f4616dc468fd57253b55d149713d314d4b706a029716dc42a09bbbe461e22c9ec3247241689
+  data.tar.gz: 14673427e3ebd711859572c5b589cdccfb0e8727d7e767daac214e9c5cef8d35fa12c3e7192ed415a4e18c3cedae6e4bf03b08ac1070fe4bec9e160a6aede1a7

data/README.md

@@ -11,9 +11,8 @@ documents.
 class DocumentChannel < ApplicationCable::Channel
   include YrbLite::ActionCable::Sync
 
-  def subscribed   = sync_for(params[:id])
+  def subscribed   = sync_subscribed(params[:id])
   def receive(data) = sync_receive(data)
-  def unsubscribed = sync_unsubscribed(params[:id])
 end
 ```
 
@@ -35,6 +34,22 @@ What it doesn't do: auth, read-only connections, rate limiting, webhooks,
 metrics. Hocuspocus ships extensions for those; here you'd build them with
 Rails.
 
+## Why "lite"
+
+The "lite" is the size of the surface. yrb-lite binds just the part of y-crdt you
+need to *sync and persist* collaborative documents — a `Doc`, awareness, and the
+y-websocket protocol primitives. The Ruby side treats a document as opaque CRDT
+state: it applies updates, answers sync handshakes, and records deltas, but never
+reaches in to read or edit the contents. The browser editor owns the document's
+shape; Rails owns durability and delivery.
+
+A full y-crdt Ruby binding like `y-rb` gives you the whole type system — shared
+text, arrays, maps, XML — to build and query documents in Ruby. yrb-lite leaves
+that out on purpose. What's left is a sync engine plus a one-include ActionCable
+concern, with the server concerns it skips (auth, rate limiting, metrics — see
+above) built from the Rails you already run, and no Node process hosting the
+documents.
+
 ## Testing
 
 Ruby and Rust unit tests cover the core. CI also runs the npm client tests and a
@@ -130,16 +145,12 @@ class DocumentChannel < ApplicationCable::Channel
   on_change { |key, update| MyStore.append(key, update) } # durable record
 
   def subscribed
-    sync_for params[:id]
+    sync_subscribed params[:id]
   end
 
   def receive(data)
     sync_receive(data, params[:id])
   end
-
-  def unsubscribed
-    sync_unsubscribed(params[:id])
-  end
 end
 ```
 
@@ -182,6 +193,26 @@ servers:
   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.
+- **A raising `on_change` rejects the update implicitly.** If the block raises,
+  the update is neither acked nor broadcast (record-before-distribute stops both).
+  There is no negative-ack: the client simply never receives the ack, keeps the
+  update pending, and retransmits on its timer/reconnect. This is built for
+  *transient* failures (the store is briefly down → a retry lands). A block that
+  raises *deterministically* — a validation that always fails for this edit —
+  will be retried forever, since nothing tells the client to stop. Enforce hard
+  rejections before the edit reaches `on_change` (channel authorization in
+  `subscribed`), not by raising inside it.
+- **An over-cap frame is dropped the same silent way.** A frame larger than
+  `max_frame_bytes` (default 8 MiB) is dropped before decoding — no ack, no
+  broadcast — to bound the work a client can force. For a genuine document
+  update that means the same implicit rejection as above: unacked, retransmitted
+  forever. Normal typing never approaches the cap, but a large paste, an embedded
+  image, or a big initial `SyncStep2` can. The drop is logged (`warn` for
+  over-cap, `debug` for undecodable) with the document key and update id so it's
+  findable; override `sync_log_context` on the channel to add a user/connection
+  id. Size the cap for your largest expected payload, and reject
+  genuinely-too-big content upstream rather than relying on the cap to reject it
+  gracefully.
 
 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
@@ -215,9 +246,8 @@ class DocumentChannel < ApplicationCable::Channel
   on_load  { |key| MyStore.load(key) }          # required: source of truth
   on_change { |key, update| MyStore.append(key, update) }  # required: record
 
-  def subscribed   = sync_for(params[:id])
+  def subscribed   = sync_subscribed(params[:id])
   def receive(data) = sync_receive(data, params[:id])   # pass the key each call
-  def unsubscribed = sync_unsubscribed(params[:id])
 end
 ```
 
@@ -229,8 +259,8 @@ end
   separate awareness stream with AnyCable `whisper: true`, so cursor traffic can
   take the low-latency client-to-client path without bypassing document
   durability.
-- Pass `params[:id]` into `sync_receive`/`sync_unsubscribed` so the document key
-  survives AnyCable's per-command instances.
+- Pass `params[:id]` into `sync_receive` so the document key survives AnyCable's
+  per-command instances.
 - The sender gets its own updates echoed back (no Ruby callback to filter them).
   That's a no-op, since applying an update twice does nothing.
 
@@ -267,9 +297,8 @@ class DocumentChannel < ApplicationCable::Channel
     AuditLog.append!(key, update)   # raise to REJECT the change
   end
 
-  def subscribed = sync_for(params[:id])
+  def subscribed = sync_subscribed(params[:id])
   def receive(data) = sync_receive(data, params[:id])
-  def unsubscribed = sync_unsubscribed(params[:id])
 end
 ```
 
@@ -362,8 +391,6 @@ exceptions.
 ```ruby
 YrbLite::MSG_SYNC            # 0 - Document sync messages
 YrbLite::MSG_AWARENESS       # 1 - User presence data
-YrbLite::MSG_AUTH            # 2 - Authentication
-YrbLite::MSG_QUERY_AWARENESS # 3 - Request awareness state
 
 YrbLite::MSG_SYNC_STEP1      # 0 - State vector request
 YrbLite::MSG_SYNC_STEP2      # 1 - Update response

data/ext/yrb_lite/src/lib.rs

@@ -35,14 +35,17 @@ fn assert_thread_safe() {
 /// - It must not touch any Ruby object or call any Ruby API. Inputs are copied
 ///   out of Ruby strings before entering, and results are converted to Ruby
 ///   objects after returning.
-/// - It must be `Send` (it runs while other threads own the GVL). `&Doc` and
-///   `&Mutex<Awareness>` are fine: both are `Sync` (asserted above).
-/// - LOCK DISCIPLINE: any native lock it takes -- the doc's internal RwLock OR
-///   the awareness `Mutex` (`self.0.lock()`) -- must be acquired AND released
-///   inside this closure (GVL already dropped). Never lock with the GVL held
-///   (e.g. before calling `nogvl`), or a thread waiting on the lock while
-///   holding the GVL can deadlock against the GVL reacquire. Same reason we
-///   never hold a lock across the GVL boundary.
+/// - It must be `Send` (it runs while other threads own the GVL). `&Doc` is
+///   fine: it's `Sync` (asserted above).
+/// - Lock discipline: any native lock it takes (the doc's internal RwLock) must
+///   be acquired and released inside this closure, with the GVL already dropped.
+///   Never lock with the GVL held (e.g. before calling `nogvl`), or a thread
+///   waiting on the lock while holding the GVL can deadlock against the GVL
+///   reacquire. Same reason we never hold a lock across the GVL boundary.
+///
+/// The closure runs with no unblock function, so it is not interruptible: a
+/// Thread#kill, timeout, or signal can't preempt it mid-run. That's fine for the
+/// bounded CRDT work it does; never call anything blocking or unbounded inside it.
 ///
 /// Panics inside the closure are caught and re-raised (resumed) after the GVL
 /// is reacquired, where magnus converts them to Ruby exceptions.
@@ -113,11 +116,6 @@ fn yrb_error(msg: String) -> Error {
     Error::new(class, msg)
 }
 
-// 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
 // ============================================================================
@@ -176,7 +174,7 @@ impl RbDoc {
     }
 
     /// True if applying `update` would integrate cleanly (its dependencies are
-    /// all present). False means it would leave a pending struct -- an earlier
+    /// all present). False means it would leave a pending struct, i.e. an earlier
     /// update is missing. Pure read; does not mutate.
     fn update_ready(&self, update: RString) -> Result<bool, Error> {
         let update_bytes = copy_bytes(update);
@@ -204,9 +202,10 @@ impl RbDoc {
         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> {
+    /// Handle a Sync or Awareness message, returning
+    /// [message_type, sync_type, response_bytes]. Only Sync (step1/step2/update)
+    /// and Awareness are handled; any other frame type is rejected.
+    fn handle_sync_message(&self, data: RString) -> Result<(u8, u8, RString), Error> {
         let data_bytes = copy_bytes(data);
         let doc = &self.0;
 
@@ -241,19 +240,19 @@ impl RbDoc {
                         }
                     },
                     Message::Awareness(_) => Ok((1, 0, Vec::new())),
-                    Message::AwarenessQuery => Ok((3, 0, Vec::new())),
-                    Message::Auth(_) => Ok((2, 0, Vec::new())),
-                    Message::Custom(tag, _) => Ok((tag, 0, Vec::new())),
+                    // Auth, awareness-query, and custom frames aren't part of this
+                    // protocol; reject rather than pretend to handle them.
+                    _ => Err("unsupported message type".to_string()),
                 }
             })
             .map_err(yrb_error)?;
 
-        Ok(Some((msg_type, sync_type, binary_string(&response))))
+        Ok((msg_type, sync_type, binary_string(&response)))
     }
 }
 
 // ============================================================================
-// Protocol codec (stateless) -- exposed as `YrbLite` module functions
+// Protocol codec (stateless), exposed as `YrbLite` module functions
 // ============================================================================
 //
 // The server never holds presence or document state to classify a frame; these
@@ -331,8 +330,6 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     // Define message type constants
     module.const_set("MSG_SYNC", 0u8)?;
     module.const_set("MSG_AWARENESS", 1u8)?;
-    module.const_set("MSG_AUTH", 2u8)?;
-    module.const_set("MSG_QUERY_AWARENESS", 3u8)?;
     module.const_set("MSG_SYNC_STEP1", 0u8)?;
     module.const_set("MSG_SYNC_STEP2", 1u8)?;
     module.const_set("MSG_SYNC_UPDATE", 2u8)?;

data/ext/yrb_lite/src/protocol.rs

@@ -1,9 +1,9 @@
-// Pure rust protocol helpers (ie, no Ruby interop).
+// Pure Rust protocol helpers (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.
+// Client ids are not validated here, on purpose: 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};
@@ -11,7 +11,7 @@ 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).
+/// that consumes the whole buffer (the codes are the match arms below).
 pub(crate) fn classify_message(bytes: &[u8]) -> u8 {
     let mut decoder = DecoderV1::new(Cursor::new(bytes));
     let msg = match Message::decode(&mut decoder) {
@@ -69,29 +69,29 @@ pub(crate) fn merged_doc_update(bytes: &[u8]) -> Result<Option<Vec<u8>>, String>
 /// 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
+/// 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> {
     let update = yrs::Update::decode_v1(update_bytes).map_err(|e| e.to_string())?;
     Ok(doc.transact().state_vector() >= update.state_vector_lower())
 }
 
-/// True if applying `update_bytes` would actually change `doc` -- i.e. it carries
-/// content the doc doesn't already have. Lets the server make durable side
+/// True if applying `update_bytes` would actually change `doc`, i.e. it carries
+/// content the doc doesn't already have. This lets the server make durable side
 /// effects exactly-once: a lost-ack retry re-sends an update the server already
 /// applied; that retry is causally ready (so `update_is_ready` is true) but must
-/// NOT re-run `on_change`.
+/// not re-run `on_change`.
 ///
 /// We can't read the update's own state vector to decide this: yrs reports an
-/// EMPTY state_vector() for a causally-pending diff (e.g. a resync delta whose
+/// empty state_vector() for a causally-pending diff (e.g. a resync delta whose
 /// structs depend on updates the doc has but the standalone update doesn't),
 /// which would look identical to a no-op. So measure the real effect: seed an
 /// independent probe with the doc's current state, apply the update there, and
 /// see whether the state vector grew. Deletes don't move the state vector, so we
-/// can't cheaply prove a delete-bearing update is a duplicate -- we
-/// conservatively report it as advancing (record it). That can still
-/// 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.
+/// can't cheaply prove a delete-bearing update is a duplicate; we conservatively
+/// report it as advancing (record it). That can still 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> {
     let update = yrs::Update::decode_v1(update_bytes).map_err(|e| e.to_string())?;
     if !update.delete_set().is_empty() {
@@ -114,7 +114,7 @@ pub(crate) fn update_advances_doc(doc: &Doc, update_bytes: &[u8]) -> Result<bool
     Ok(after != before)
 }
 
-/// True if the doc holds pending structs or a pending delete set -- blocks that
+/// True if the doc holds pending structs or a pending delete set: blocks that
 /// couldn't integrate because a dependency is missing. Test-only: asserts the
 /// causal-chain parking behavior in the unit tests below.
 #[cfg(test)]
@@ -213,8 +213,8 @@ mod tests {
     #[test]
     fn update_advances_handles_a_dependent_diff_update() {
         // A causally-pending diff (its structs depend on content the doc already
-        // has) reports an EMPTY state_vector() in isolation -- a naive check would
-        // misread it as a no-op. Verify the trial-apply gets it right.
+        // has) reports an empty state_vector() in isolation, which a naive check
+        // would misread as a no-op. Verify the trial-apply gets it right.
         let doc = Doc::new();
         let text = doc.get_or_insert_text("content");
         text.insert(&mut doc.transact_mut(), 0, "a");

data/lib/yrb-lite.rb

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

data/lib/yrb_lite/version.rb

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

metadata

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