yrb-lite 0.1.0.beta7-aarch64-linux → 0.2.0-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be184ab40b68d255418e7c177aba626e49d0df4d5e765fafb3a67427c23a7715
-  data.tar.gz: '08691e24a9c271bbe1b38a761570fde125849d79ebff1c9243c47f3960973f95'
+  metadata.gz: 20d4b2778b6436a336918c2699c6e5b568dd9cb1eff9fc566087ff5d698bba7d
+  data.tar.gz: 5bb8144def22e55471c679729accd6fc5da455bcbc67294eacb631c80adce937
 SHA512:
-  metadata.gz: 2206c081675d25280b912477bbe6dcd2c12d20ec439dc6345166fdf7f3a602168a17dd69429e79e8a75f6ef25275d08fa5f1ac43f8b1eba4bfbbaf734bb7798f
-  data.tar.gz: 68c4c14af5815e0c6020baed54f04d80cee83a412872a56eac4b1e80d90b34f715d7949d42cee2103de9ecce9fc8691bec52482ae39b6a0d87ee098e16782984
+  metadata.gz: 06a6155479bbaf77ce62ea573ae00c9e6754d63fc43e6aa952d379959df903ce67bca95ddd8625e0542d9bda4e8193f54abaf31149a227ded1ad3ed4b45e7a55
+  data.tar.gz: a245cfc5703b100092dcd817dd172339da1f498de813f4612347cd378bf37f113075766a21a2f73bfd8f950257c53ff8619837d4e06be974063b1e50369d3ecd

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

@@ -11,20 +11,19 @@ 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
 ```
 
 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.
@@ -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
@@ -86,11 +101,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 +111,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)
+### Protocol codec (module functions)
 
-```ruby
-# Create awareness instances (each contains a Doc)
-awareness = YrbLite::Awareness.new        # random client ID
-awareness = YrbLite::Awareness.new(12345) # specific client ID
-
-# Get document info
-awareness.client_id  # => unique client identifier
-awareness.guid       # => document GUID
-```
-
-### Handling Sync Messages
+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
@@ -147,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
 ```
 
@@ -178,6 +172,54 @@ 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.
+- **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
+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
@@ -204,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
 ```
 
@@ -218,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.
 
@@ -256,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
 ```
 
@@ -295,43 +335,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:
 
@@ -379,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/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.beta7"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: yrb-lite
 version: !ruby/object:Gem::Version
-  version: 0.1.0.beta7
+  version: 0.2.0
 platform: aarch64-linux
 authors:
 - JP Camara
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-06-23 00:00:00.000000000 Z
+date: 2026-06-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest