yrby-rails 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 397e3f48e611d521d0afa26ddca292826276406b1fd04fb2bcfd09858a73081d
-  data.tar.gz: 51e88f6856f8a2859d18823e87ff2d5cd901e678e8b7a618ff7b2b0308d80c1d
+  metadata.gz: 83a5440fa6532dbedcf992660959297611b9b7cf958f7c7c6c1522dd0ac162b0
+  data.tar.gz: 23509b37d1bb0ce706c648a779993236addb244cb603031415de4084a58e4636
 SHA512:
-  metadata.gz: 3299b4149a6dea79105be6bf69e643c8079029ac751bb50f68ce4b8d49ce570541b184f5b601215214d92b7848694a8b9a9a685eaf593f885378cbc8454e0a18
-  data.tar.gz: 4490087a7702972c2e447abcb2f4afff938d72e77704eb7cfc04d5a5272bc6e5248d22a883b193b3840db0aa5c3e602e6a0c50b57fb1d3169839e7530a764ff4
+  metadata.gz: c51b2e0b9acefc89d6c69e3b935206d195ccaba7b302ec13316c39f7fab0115d09fd7a5d108f537294b8c069a54ef2e1a53fc19b39ec21873e7b61be866e7a5d
+  data.tar.gz: 5ffd94a472cd16ada77f62e57c7bd571f7df461a9552756212ef6fd12c9c1a2cb92bdb3ac72fe0320a1992d27f6b22ce8964240db81057ffaaa4cc2be1872124

data/CHANGELOG-rails.md

@@ -7,6 +7,47 @@ this project aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-11-03
+
+Requires yrby 0.9.0 or later.
+
+### Experimental
+
+These are new, and they may change in a minor release. See
+[docs/experimental.md](docs/experimental.md).
+
+- `collaborative_document(:body).edit { |doc| ... }` edits a record's
+  document from Ruby. It records the change in the document's rows, encrypted
+  ones included, and broadcasts it to open editors.
+  `Y::ActionCable.broadcast(key, update)` sends an already recorded update.
+
+### Added
+
+- `collaborative_document(name)` answers `grant(expires_in:)` and `channel`:
+  the grant a page or client subscribes with, and the channel that accepts
+  it. A gem with its own grants and channel, such as lexxy-realtime, returns
+  its own document with both.
+
+### Changed
+
+- `collaborative_document_tag` renders the document's grant and channel, so
+  it works for a gem that returns its own document. `channel:` still
+  overrides the channel.
+
+### Deprecated
+
+- `collaborative_sgid(name, expires_in:)`. Use
+  `collaborative_document(name).grant(expires_in:)`. It logs through
+  `Y.deprecator`, which the engine adds to `Rails.application.deprecators`,
+  and goes away in yrby-rails 0.9.
+
+### Fixed
+
+- The channel relays a client's SyncStep2 to peers as a plain update.
+  Relayed as is, a peer that was still joining could take it for the answer
+  to its own handshake and report itself loaded before it had the server's
+  state.
+
 ## [0.7.0] - 2026-10-01
 
 ### Added

data/README.md

@@ -101,6 +101,7 @@ bin/rails generate yrby:install && bin/rails db:migrate
   - [Rendering to HTML](#rendering-to-html)
   - [Protocol codec (module functions)](#protocol-codec-module-functions)
   - [ActionCable Integration](#actioncable-integration)
+- [Experimental: writing from Ruby](#experimental-writing-from-ruby)
 - [Thread Safety](#thread-safety)
   - [Parallelism (GVL release)](#parallelism-gvl-release)
 - [Message Type Constants](#message-type-constants)
@@ -117,7 +118,9 @@ primitives. By default the Ruby side treats a document as opaque CRDT state. It
 applies updates, answers sync handshakes, and records deltas without reading
 the contents, and the browser editor decides what shape the document has. When
 you do need to look inside, `Doc#read_text` and `Doc#read_map` rebuild it in
-Ruby.
+Ruby, and live handles (`Doc#get_map`, `get_array`, `get_text`,
+`get_xml_text`) write to it. The handles are
+[experimental](docs/experimental.md).
 
 ## Durability and delivery
 
@@ -338,12 +341,12 @@ every editor configures its own. `Y::Lexical` is the core Lexical base
 (paragraphs, headings, quotes, code, lists, tables, links, and the full
 text-format model), and other Lexical editors extend it with rules.
 
-It handles every node in the Lexxy 0.9.x set: paragraphs, headings, every text
-format and their combinations, links, the four list types with nesting,
-blockquotes, code blocks, tabs and soft breaks, horizontal rules, tables with
-header cells, image galleries, and ActionText attachments. Uploads and mentions
-both render as `<action-text-attachment>` elements, which ActionText can
-re-render.
+It handles every node in Lexxy 1.0, which has the same set as 0.9.x:
+paragraphs, headings, every text format and their combinations, links, the
+four list types with nesting, blockquotes, code blocks, tabs and soft breaks,
+horizontal rules, tables with header cells, image galleries, and ActionText
+attachments. Uploads and mentions both render as `<action-text-attachment>`
+elements, which ActionText can re-render.
 
 The Lexical support has the same two layers. `Y::Lexical` handles core Lexical
 structure natively, and everything Lexxy adds is in `Y::Lexxy`'s rule set,
@@ -401,6 +404,13 @@ attribute names your templates and blocks will read, and `children` and `text`
 tell you which `contains:` to pick. Child block types mean `:blocks`, and text
 means `:inline`.
 
+`unknown_types` lists the types whose `handled` is nil. `to_html` still
+renders them as well as it can. An unknown container or inline wrapper renders
+its children without its own markup, so its text stays. A node that keeps its
+content only in its attributes renders nothing. Either way, the node's markup is
+missing from the HTML, and nothing raises. When you add editor nodes, add a test
+that renders a real document and asserts `unknown_types` is empty.
+
 When a declarative rule can't express the markup, give the node a block:
 
 ```ruby
@@ -673,7 +683,7 @@ gets blocked at the next reconnect. To avoid that, pair `expires_in:` with
 # app/controllers/posts_controller.rb
 def grant
   @post = current_user.posts.find(params[:id])   # your own authorization, again
-  render json: { grant: @post.collaborative_sgid(:body, expires_in: 10.minutes) }
+  render json: { grant: @post.collaborative_document(:body).grant(expires_in: 10.minutes) }
 end
 ```
 
@@ -737,7 +747,7 @@ up the record from it, so the page decides which document the client gets.
 
 ```erb
 <%# the view picks the document and signs it %>
-<%= tag.div data: { grant: post.collaborative_sgid(:body) } %>
+<%= tag.div data: { grant: post.collaborative_document(:body).grant } %>
 ```
 
 ```ruby
@@ -1067,6 +1077,18 @@ The browser clients manage presence (cursors, selections). The server doesn't
 set or hold presence state, and it relays awareness frames without reading
 them. See `yrby-client` for the client-side awareness API.
 
+## Experimental: writing from Ruby
+
+These APIs are new. They may change in any minor release, and they aren't
+covered by yrby's usual compatibility promise.
+[docs/experimental.md](docs/experimental.md) documents them:
+
+- Live `Y::Map`, `Y::Array`, and `Y::Text` handles that write to a document
+- Writing Lexical rich text from Ruby, with `Y::Lexical` and `Y::Lexxy`
+- Anchors: a block's identity as a value
+- Streaming into a document with `Doc#edit`
+- Editing a record's document from Ruby
+
 ## Thread Safety
 
 You can share a `Doc` across Ruby threads. Puma workers, ActionCable connection

data/app/channels/y/document_channel.rb

@@ -6,7 +6,7 @@ module Y
   # doesn't write a channel of its own.
   #
   # The client never picks its own document. It sends the signed grant the
-  # page rendered (record.collaborative_sgid(name)), and the channel opens
+  # page rendered (record.collaborative_document(name).grant), and the channel opens
   # whatever document that grant verifies to. Your controller authorized the
   # request when it rendered the tag, and the grant is how that decision gets
   # to the socket. You can also register an authorize_document block to check

data/lib/y/action_cable/sync.rb

@@ -398,7 +398,7 @@ module Y::ActionCable # rubocop:disable Style/ClassAndModuleChildren
         update = Y.update_from_message(bytes)
         return :noop unless update
 
-        sync_handle_document_update(update, encoded)
+        sync_handle_document_update(update, sync_relay_frame(update, encoded, bytes))
       when MSG_KIND_AWARENESS
         sync_distribute(encoded)
         :noop
@@ -422,6 +422,16 @@ module Y::ActionCable # rubocop:disable Style/ClassAndModuleChildren
       :recorded
     end
 
+    # A client's SyncStep2 answers the server's Step1 and is meant for the
+    # server. Peers get it as a plain update, so the only Step2 a client ever
+    # receives is the server's answer to its own handshake, which is how a
+    # client knows it has loaded.
+    def sync_relay_frame(update, encoded, bytes)
+      return encoded unless bytes.getbyte(1) == Y::MSG_SYNC_STEP2
+
+      Base64.strict_encode64(Y.wrap_update(update))
+    end
+
     # 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
@@ -432,7 +442,7 @@ module Y::ActionCable # rubocop:disable Style/ClassAndModuleChildren
     end
 
     def sync_stream_name
-      "yrby:#{@sync_key}"
+      Y::ActionCable.stream_name(@sync_key)
     end
 
     def sync_awareness_stream_name

data/lib/y/action_cable.rb

@@ -17,6 +17,17 @@ module Y
     def self.included(base)
       base.include(Sync)
     end
+
+    # The stream a document's subscribers listen on.
+    def self.stream_name(key) = "yrby:#{key}"
+
+    # Sends an update to everyone subscribed to a document, from outside a
+    # channel: a job, a console, or Y::Collaborative::Attribute#edit. Record
+    # the update first. This only distributes it.
+    def self.broadcast(key, update)
+      encoded = Base64.strict_encode64(Y.wrap_update(update))
+      ::ActionCable.server.broadcast(stream_name(key), { "update" => encoded })
+    end
   end
 end
 

data/lib/y/collaborative/attribute.rb

@@ -22,6 +22,42 @@ module Y
       # this to return before it acknowledges or broadcasts the change.
       def append(update) = document_row.append(update)
 
+      # A signed grant for this document, what a page or a Ruby client
+      # subscribes with. It's a signed GlobalID scoped to this attribute, and
+      # Y::Collaborative.locate turns it back into the record. Pass
+      # expires_in: to limit how long it lasts. Without it GlobalID's own
+      # default applies, which is one month under Rails. The option goes
+      # through only when it's given, because an explicit nil would mean
+      # "never expire".
+      def grant(expires_in: nil)
+        options = { for: Y::Collaborative.sgid_purpose(name) }
+        options[:expires_in] = expires_in if expires_in
+        record.to_sgid(**options).to_s
+      end
+
+      # The channel that accepts this document's grant. A gem with its own
+      # grants and channel, such as lexxy-realtime, returns its own document
+      # with both.
+      def channel = "Y::DocumentChannel"
+
+      # Edits the document from Ruby the way a browser does: yields the
+      # current document, records what the block changed, and broadcasts it so
+      # open editors apply it. Returns the update, or nil when the block
+      # changed nothing.
+      #
+      #   post.collaborative_document(:body).edit do |doc|
+      #     Y::Lexxy.append_paragraph(doc, "Reviewed by ops.")
+      #   end
+      def edit
+        doc = y_doc
+        update = doc.edit { yield doc }
+        return unless update
+
+        append(update)
+        Y::ActionCable.broadcast(key, update)
+        update
+      end
+
       # Builds a new Y::Doc from storage on every call.
       def y_doc
         Y::Doc.new.tap do |doc|

data/lib/y/collaborative/helper.rb

@@ -9,15 +9,18 @@ module Y
     #
     # renders the auto-connecting element:
     #
-    #   <yrby-document grant="<signed sgid>" name="body"></yrby-document>
+    #   <yrby-document channel="Y::DocumentChannel" grant="<signed grant>" name="body"></yrby-document>
     #
     # Importing "yrby-client/element" registers the element. It subscribes to
-    # Y::DocumentChannel by itself and exposes the synced Y.Doc through its
+    # the document's channel by itself and exposes the synced Y.Doc through its
     # `doc` property and `yrby:synced` event, much like the element behind
     # turbo_stream_from.
     #
-    # The grant is a signed GlobalID scoped to this record and attribute
-    # (record.collaborative_sgid(name)). Only render the tag on pages where
+    # The grant and channel come from record.collaborative_document(name), so
+    # the tag works for any gem that returns its own document, such as
+    # lexxy-realtime. Pass channel: for an app's own Y::DocumentChannel
+    # subclass. The grant is scoped to this record and attribute. Only render
+    # the tag on pages where
     # the user may edit the record, because by default anyone holding the
     # grant can open the document. To also check the user's current
     # permissions when they subscribe, use Y::DocumentChannel.authorize_document.
@@ -30,18 +33,18 @@ module Y
     # expires_in: limits how long the grant lasts. refresh: is a URL the
     # element fetches a new grant from when a subscription is rejected, so it
     # can resubscribe without a page load. The app's action there re-runs its
-    # own authorization and renders { grant: record.collaborative_sgid(name) }:
+    # own authorization and renders { grant: record.collaborative_document(name).grant }:
     #
     #   <%= collaborative_document_tag @post, :body, expires_in: 10.minutes,
     #                                  refresh: grant_post_path(@post) %>
     module Helper
       def collaborative_document_tag(record, name, expires_in: nil, refresh: nil, **, &)
-        grant = record.collaborative_sgid(name, **{ expires_in: expires_in }.compact)
-        attributes = { grant: grant, name: name }
+        document = record.collaborative_document(name)
+        attributes = { grant: document.grant(expires_in:), name: name }
         attributes[:refresh] = refresh if refresh
-        # The helper's attributes go last because a later key wins in a keyword
-        # splat, so a template can't override the grant or the name.
-        tag.yrby_document(**, **attributes, &)
+        # A later key wins in a keyword splat. A template can pass its own
+        # channel, but it can't override the grant or the name.
+        tag.yrby_document(channel: document.channel, **, **attributes, &)
       end
     end
   end

data/lib/y/collaborative.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
 require "active_support/concern"
+require "active_support/deprecation"
 require "global_id"
+require "y/action_cable"
 
 module Y
   # The signed token that connects a page to a channel for record-backed
@@ -12,7 +14,7 @@ module Y
   # record up from it. The token is a signed GlobalID scoped to one attribute.
   #
   #   # the view
-  #   tag.div data: { grant: post.collaborative_sgid(:body) }
+  #   tag.div data: { grant: post.collaborative_document(:body).grant }
   #
   #   # the channel
   #   def authorized?(_key)
@@ -28,6 +30,10 @@ module Y
   #
   # The engine includes this into ActiveRecord::Base so any channel's
   # authorized? can use it. lexxy-realtime uses the same token flow.
+  # Warns about yrby-rails methods that are going away. The engine adds it to
+  # Rails.application.deprecators, so the app's deprecation settings apply.
+  def self.deprecator = @deprecator ||= ActiveSupport::Deprecation.new("0.9", "yrby-rails")
+
   module Collaborative
     extend ActiveSupport::Concern
 
@@ -39,7 +45,7 @@ module Y
       # shipped one can both resolve the same tokens for an attribute.
       def sgid_purpose(name) = "yrby/#{name}"
 
-      # Looks up the record for a token from `collaborative_sgid(name)`.
+      # Looks up the record for a grant from `collaborative_document(name).grant`.
       # Returns nil for an invalid, tampered, expired, or wrong-attribute
       # token, and for a record that no longer exists.
       def locate(sgid, name)
@@ -76,20 +82,17 @@ module Y
     end
 
     # Returns the document for one attribute, stored the way the model
-    # declared. It responds to load_state, append, y_doc, and key.
+    # declared. It responds to load_state, append, edit, y_doc, key, grant,
+    # and channel.
     def collaborative_document(name)
       Attribute.new(self, name)
     end
 
-    # A signed token that a channel can pass to Y::Collaborative.locate to get
-    # this record back, for this attribute only. Pass expires_in: to limit how
-    # long the grant lasts. Without it GlobalID's own default applies, which is
-    # one month under Rails. We pass the option through only when it's given,
-    # because an explicit nil would mean "never expire".
+    # Deprecated. Use collaborative_document(name).grant. This one always
+    # signs yrby's own grant, as it did before.
     def collaborative_sgid(name, expires_in: nil)
-      options = { for: Y::Collaborative.sgid_purpose(name) }
-      options[:expires_in] = expires_in if expires_in
-      to_sgid(**options).to_s
+      Y.deprecator.warn("collaborative_sgid(name) is deprecated. Use collaborative_document(name).grant instead.")
+      Attribute.new(self, name).grant(expires_in:)
     end
   end
 end

data/lib/yrby/engine.rb

@@ -12,5 +12,9 @@ module Yrby
       ActiveSupport.on_load(:active_record) { include Y::Collaborative }
       ActiveSupport.on_load(:action_view) { include Y::Collaborative::Helper }
     end
+
+    initializer "yrby.deprecator" do |app|
+      app.deprecators[:yrby] = Y.deprecator
+    end
   end
 end

data/lib/yrby/rails/version.rb

@@ -2,6 +2,6 @@
 
 module Yrby
   module Rails
-    VERSION = "0.7.0"
+    VERSION = "0.8.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yrby-rails
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - JP Camara
@@ -57,14 +57,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.7.0
+        version: 0.9.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.7.0
+        version: 0.9.0
 - !ruby/object:Gem::Dependency
   name: actioncable
   requirement: !ruby/object:Gem::Requirement