yrb-lite-actioncable 0.1.0.beta5 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8d48432476f4a644c91c193f72d6857aa5ce6bb0f2ded537b3277d31e8c49cfb
-  data.tar.gz: e28d77164e95bbba949133989f11555015160f39786a0c17bab9acacaaf05570
+  metadata.gz: 927dca0304b576a035cbbeff9f5e4c72a9c947c01e4a8de584462842b4412d13
+  data.tar.gz: 6c7cdde2224501295ee6238562876cf1bd7caea452ac8bac26a8376387cc5e26
 SHA512:
-  metadata.gz: d69b40149fccf8d84d8fc4cbfffe7f9ce4309a47e9971bbb0c65befc9bed6a5827d2251caa807da6da5b2b5b7f3ef13c4c8659d2856868848df13748deed77d2
-  data.tar.gz: a8babf32c1f72b70ff9f3e551c826b62306dd446ee86d44d09b71b5f5164b4c0817328a5ad14e16bcbc0134f1fc4a20624d59abc13a75766292d1a567933e432
+  metadata.gz: f3d2b8170e6749403cc9bfb9f84734fc1346fc4200192bd0a35d6e119004aee5d040e5961f2990ac247e1a33665803df532e36a717b20ed6c8be282dd94e2731
+  data.tar.gz: c811d7a6ad403ab3465d0d4469751c7632fb5012b950e0854445c2b2f3238f7d582f93456f919de844d3630dd3e96cd8a5eb2ddd699df23273a2b0848fe66992

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/lib/yrb-lite-actioncable.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/action_cable"

data/lib/yrb_lite/action_cable/sync.rb

@@ -2,7 +2,6 @@
 
 require "yrb_lite"
 require "base64"
-require "securerandom"
 
 module YrbLite::ActionCable # rubocop:disable Style/ClassAndModuleChildren
   # y-websocket protocol over ActionCable.
@@ -12,7 +11,7 @@ module YrbLite::ActionCable # rubocop:disable Style/ClassAndModuleChildren
   # y-protocols binary messages, base64-encoded in a JSON envelope:
   #
   #   { "update" => "<base64 bytes>", "id" => 42 } # client -> server
-  #   { "update" => "...", "origin" => "<id>" }    # server -> subscribers
+  #   { "update" => "<base64 bytes>" }             # server -> subscribers
   #   { "ack" => 42 }                              # server -> sender
   #
   # Example:
@@ -20,30 +19,29 @@ module YrbLite::ActionCable # rubocop:disable Style/ClassAndModuleChildren
   #     include YrbLite::ActionCable::Sync
   #
   #     on_load { |key| Document.find_by(key: key)&.content }
-  #     # on_change blocks run in the channel instance's context, so instance
-  #     # methods (current_user, params, ...) are available without plumbing:
+  #     # on_change runs in the channel instance's context, so instance methods
+  #     # (current_user, params, ...) are available:
   #     on_change { |key, update| Document.record!(key, update, by: current_user) }
   #
   #     def subscribed
-  #       sync_for params[:id]
+  #       sync_subscribed params[:id]
   #     end
   #
   #     def receive(data)
   #       sync_receive(data)
   #     end
-  #
-  #     def unsubscribed
-  #       sync_unsubscribed
-  #     end
   #   end
   #
+  # There is no unsubscribe hook: the server keeps no per-connection document or
+  # presence state, so a disconnect needs no server-side cleanup.
+  #
   # The concern is store-backed and fail-closed: every document update is
   # validated against `on_load`, recorded through `on_change`, then broadcast.
   # No authoritative document state is kept in ActionCable process memory.
   module Sync
-    # Frame kinds we act on, from Awareness#message_kind. The other codes it can
-    # return -- 0 (drop: malformed/truncated/multi-message/unknown) and 4
-    # (awareness query) -- fall through to a no-op in the dispatch below.
+    # Frame kinds we act on, from YrbLite.message_kind. Its other codes (0 for a
+    # drop: malformed/truncated/multi-message/unknown, and 4 for an awareness
+    # query) fall through to a no-op in the dispatch below.
     MSG_KIND_SYNC_STEP1 = 1
     MSG_KIND_UPDATE = 2
     MSG_KIND_AWARENESS = 3
@@ -59,8 +57,8 @@ module YrbLite::ActionCable # rubocop:disable Style/ClassAndModuleChildren
 
     module ClassMethods
       # Load persisted document state. Called once per key with (key); return a
-      # binary Y.js update (or nil for a fresh document). The block runs in the
-      # channel instance's context, the same as on_change (see below).
+      # binary Y.js update (or nil for a fresh document). Runs in the channel
+      # instance's context (instance_exec).
       def on_load(&block)
         @on_load = block if block
         return @on_load if defined?(@on_load) && @on_load
@@ -73,10 +71,8 @@ module YrbLite::ActionCable # rubocop:disable Style/ClassAndModuleChildren
       # the exact CRDT delta. If the block raises, the change is rejected:
       # neither acknowledged nor broadcast to other subscribers.
       #
-      # The block runs in the *channel instance's* context (via instance_exec),
-      # so it can call the channel's own methods (current_user, params, a
-      # per-connection Current.* accessor) directly, with no thread-local
-      # plumbing. on_change always fires from within sync_receive.
+      # Runs in the channel instance's context (instance_exec). Fires from within
+      # sync_receive.
       def on_change(&block)
         @on_change = block if block
         return @on_change if defined?(@on_change) && @on_change
@@ -89,6 +85,7 @@ module YrbLite::ActionCable # rubocop:disable Style/ClassAndModuleChildren
       # parsing, so a client can't force huge allocations/CPU (a DoS vector).
       # Defaults to DEFAULT_MAX_FRAME_BYTES; set to nil to disable the cap.
       def max_frame_bytes(bytes = :__unset__)
+        # Combined reader/writer; the sentinel keeps nil a real value (disables the cap).
         @max_frame_bytes = bytes unless bytes == :__unset__
         return @max_frame_bytes if defined?(@max_frame_bytes)
 
@@ -98,10 +95,9 @@ module YrbLite::ActionCable # rubocop:disable Style/ClassAndModuleChildren
 
     # Call from `subscribed`. Streams broadcasts for this document and
     # transmits the server's opening handshake (SyncStep1 from the store).
-    def sync_for(key)
+    def sync_subscribed(key)
       @sync_key = key.to_s
-      @sync_origin = SecureRandom.hex(8)
-      sync_require_store_recorder!
+      sync_validate_required_hooks!
 
       # The document stream is never whisper-enabled; under AnyCable we also
       # subscribe an awareness stream with `whisper: true`, scoping the client-to-
@@ -117,7 +113,7 @@ module YrbLite::ActionCable # rubocop:disable Style/ClassAndModuleChildren
     #
     # Reliable delivery: document updates carry an "id", and the server replies
     # `{ "ack" => id }` once the update has been durably recorded. A
-    # causally-gapped update is not acked -- it gets a resync instead -- so the
+    # causally-gapped update is not acked; it gets a resync instead, so the
     # client retransmits until the update lands.
     def sync_receive(data, key = nil)
       # Pass `key` (params[:id]) when your transport doesn't keep the channel
@@ -129,37 +125,41 @@ module YrbLite::ActionCable # rubocop:disable Style/ClassAndModuleChildren
       return unless encoded.is_a?(String)
 
       # Optional client-supplied id for reliable delivery (see sync_send_ack).
-      id = data.is_a?(Hash) ? data["id"] : nil
+      # data is known to be a Hash here (encoded came from it above).
+      id = data["id"]
 
       # Frame-size cap: drop oversized frames before decoding (the encoded form
       # is ~4/3 the decoded size) and again after, so a client can't force large
-      # base64 decodes / native parses / merges. A dropped frame is never acked.
+      # base64 decodes / native parses / merges. A dropped frame is never acked,
+      # and there is no protocol NACK, so a legitimate oversized update is
+      # retransmitted indefinitely. Log the drop so it is at least findable.
       cap = self.class.max_frame_bytes
-      return if cap && encoded.bytesize > (cap * 4 / 3) + 4
+      if cap && encoded.bytesize > (cap * 4 / 3) + 4
+        sync_log_drop(:warn, "encoded #{encoded.bytesize}B exceeds max_frame_bytes #{cap}B", id)
+        return
+      end
 
       begin
         bytes = Base64.strict_decode64(encoded)
       rescue ArgumentError
-        return # not valid base64; ignore the frame and keep the connection
+        sync_log_drop(:debug, "not valid base64", id) # garbage or a probe, rarely a real client
+        return # ignore the frame and keep the connection
       end
 
-      return if cap && bytes.bytesize > cap
+      if cap && bytes.bytesize > cap
+        sync_log_drop(:warn, "decoded #{bytes.bytesize}B exceeds max_frame_bytes #{cap}B", id)
+        return
+      end
 
       sync_send_ack(id, sync_handle_frame(encoded, bytes))
     end
 
-    # The `unsubscribed` hook target. Nothing to clean up: the server keeps no
-    # per-connection document or presence state.
-    def sync_unsubscribed(key = nil)
-      @sync_key = key.to_s if key
-    end
-
     private
 
     # Ask this connection's client to resync: re-send SyncStep1 carrying the
     # server's current (gap-free) state vector. The client replies SyncStep2
     # with everything the server is missing, delivered as one causally-complete
-    # delta -- which heals the gap that triggered the resync.
+    # delta, which heals the gap that triggered the resync.
     def sync_request_resync(doc)
       sync_transmit(doc.sync_step1)
     end
@@ -174,7 +174,7 @@ module YrbLite::ActionCable # rubocop:disable Style/ClassAndModuleChildren
       return if id.nil?
       return unless %i[recorded applied].include?(outcome)
 
-      # Braces are load-bearing: a bare hash would bind to transmit's `via:`
+      # The braces are required: a bare hash would bind to transmit's `via:`
       # keyword instead of its positional data argument.
       transmit({ "ack" => id })
     end
@@ -183,10 +183,7 @@ module YrbLite::ActionCable # rubocop:disable Style/ClassAndModuleChildren
     # observe distribution. Store-backed streams intentionally echo to the
     # sender; applying the same CRDT update twice is a no-op.
     def sync_distribute(encoded)
-      ActionCable.server.broadcast(
-        sync_stream_name,
-        sync_envelope(encoded, "origin" => @sync_origin, "pid" => Sync.process_id)
-      )
+      ActionCable.server.broadcast(sync_stream_name, sync_envelope(encoded))
     end
 
     # Transmit raw protocol bytes to this connection.
@@ -194,16 +191,44 @@ module YrbLite::ActionCable # rubocop:disable Style/ClassAndModuleChildren
       transmit(sync_envelope(Base64.strict_encode64(bytes)))
     end
 
-    def sync_envelope(encoded, extra = {})
-      { "update" => encoded }.merge(extra)
+    def sync_envelope(encoded)
+      { "update" => encoded }
+    end
+
+    # Override in the channel to add identifying context to dropped-frame logs --
+    # a user id, a connection id, a request id. Return a short string (or nil for
+    # none); it is appended to the log line. Default: no extra context.
+    def sync_log_context
+      nil
+    end
+
+    # Surface a dropped frame through the channel logger. Drops are otherwise
+    # invisible (no ack, no broadcast); an oversized legitimate update is never
+    # acked and the client retransmits it forever, so make it findable. Names the
+    # document key, the reliable-delivery id when present, and whatever
+    # sync_log_context returns, so a drop can be tied to a specific document,
+    # update, and connection.
+    def sync_log_drop(level, reason, id = nil)
+      logger.public_send(level) do
+        parts = ["key=#{@sync_key.inspect}"]
+        parts << "id=#{id}" unless id.nil?
+        # A broken context hook must surface, not take down frame handling.
+        context = begin
+          sync_log_context
+        rescue StandardError => e
+          "log-context-error=#{e.class}"
+        end
+        parts << context if context
+        "[yrb-lite] dropped frame (#{parts.join(" ")}): #{reason}"
+      end
     end
 
-    # This concern acks updates as *durably recorded*, so it MUST have both a
+    # This concern acks updates as durably recorded, so it must have both a
     # loader (to rebuild the doc and detect causal gaps) and a recorder (to
     # actually persist before acking). Fail closed rather than silently acking
-    # and broadcasting updates that were never stored -- which a cold load or
+    # and broadcasting updates that were never stored, which a cold load or
     # reconnect would then lose.
-    def sync_require_store_recorder!
+    def sync_validate_required_hooks!
       missing = []
       missing << :on_load unless self.class.on_load
       missing << :on_change unless self.class.on_change
@@ -224,12 +249,12 @@ module YrbLite::ActionCable # rubocop:disable Style/ClassAndModuleChildren
     # document update was durably recorded and relayed, :gap when it was
     # rejected for a resync, :noop for everything else.
     def sync_handle_frame(encoded, bytes)
-      sync_require_store_recorder!
+      sync_validate_required_hooks!
 
       case YrbLite.message_kind(bytes)
       when MSG_KIND_SYNC_STEP1
         result = sync_load_doc.handle_sync_message(bytes)
-        sync_transmit(result[2]) if result
+        sync_transmit(result[2])
         :noop
       when MSG_KIND_UPDATE
         update = YrbLite.update_from_message(bytes)
@@ -250,7 +275,7 @@ module YrbLite::ActionCable # rubocop:disable Style/ClassAndModuleChildren
         # cross-process exactly-once (see "Delivery guarantees" in the README).
         return :applied unless doc.update_advances?(update)
 
-        sync_record_change(self.class.on_change, update) # record before relay
+        sync_record_change(update) # record before relay
         sync_distribute(encoded)
         :recorded
       when MSG_KIND_AWARENESS
@@ -261,11 +286,11 @@ module YrbLite::ActionCable # rubocop:disable Style/ClassAndModuleChildren
       end
     end
 
-    # Build a fresh document from the durable store (on_load).
+    # Build a fresh document from the durable store (on_load). Callers validate
+    # the hooks first, so on_load is present; a nil state means a fresh document.
     def sync_load_doc
       doc = YrbLite::Doc.new
-      loader = self.class.on_load
-      state = instance_exec(@sync_key, &loader) if loader
+      state = instance_exec(@sync_key, &self.class.on_load)
       doc.apply_update(state) if state
       doc
     end
@@ -279,20 +304,10 @@ module YrbLite::ActionCable # rubocop:disable Style/ClassAndModuleChildren
     end
 
     # Invoke the on_change recorder in this channel instance's context
-    # (instance_exec) so it can reach the channel's own methods.
-    def sync_record_change(recorder, update)
-      instance_exec(@sync_key, update, &recorder)
-    end
-
-    # -- Shared process state ----------------------------------------------
-
-    class << self
-      # A stable id for this server process, stamped on every broadcast so
-      # other processes know to apply it to their replica and this process
-      # knows to skip its own. Survives for the life of the process.
-      def process_id
-        @process_id ||= SecureRandom.hex(8)
-      end
+    # (instance_exec) so it can reach the channel's own methods. Mirrors how
+    # sync_load_doc fetches and runs on_load.
+    def sync_record_change(update)
+      instance_exec(@sync_key, update, &self.class.on_change)
     end
   end
 end

data/lib/yrb_lite/action_cable/version.rb

@@ -2,6 +2,6 @@
 
 module YrbLite
   module ActionCable
-    VERSION = "0.1.0.beta5"
+    VERSION = "0.2.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yrb-lite-actioncable
 version: !ruby/object:Gem::Version
-  version: 0.1.0.beta5
+  version: 0.2.0
 platform: ruby
 authors:
 - JP Camara
@@ -29,14 +29,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.0.beta9
+        version: 0.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.0.beta9
+        version: 0.2.0
 - !ruby/object:Gem::Dependency
   name: actioncable
   requirement: !ruby/object:Gem::Requirement