lexxy-realtime 0.7.1 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e13daa738b30059ffd6512349184322d7c5866238a6bf886b60d55ce15006f15
-  data.tar.gz: 91e37a272447251a7c3f8b0a409c9e7264be7958da2bfebd088a059d94d737af
+  metadata.gz: 444a86a830537d630ccb1247fc6a601b84e30498c5e38d8ca5ce789e095117a6
+  data.tar.gz: 4373eae50d13855bf9895cc505ab323e2949bb73a90aa80d50888e9df4d14be2
 SHA512:
-  metadata.gz: b94ee6e879b9aebe10bd52c2fb296afc6e29242d8929c7082434ae4d653d3b9fc5ad3a2e598ad871c9dd7d0e525d411c6f5c9e0d22f1280bde6718da4c360635
-  data.tar.gz: 86deff4da480f6e97d13aa130d545e6625d246a05472792a3c9bcb07f2ee6fbbbc0f4b9a4a5c46b867666c6279d0f30ca906319c2ef20711799cd9df254d5545
+  metadata.gz: 23d8d6e07ccd5af9548f0bab391f4b91b1673fabc4a6e5f51d9ce9b4a7777f3abde513e01ebce95afab2b1c2c3b941fe9b9c3a140086f9f99648253f26c00d86
+  data.tar.gz: c782da01923dbd52a49016f4971d3f6309c3bd0074705b461c8c6cf028d6a7216a2316bc63dfb6b9e621f5b75f5cfaaf5a4e64a3e0c74e127cc03680164b70d7

data/README.md

@@ -21,10 +21,10 @@ bin/rails generate lexxy_realtime:install
 bin/rails db:migrate
 ```
 
-The generator creates `app/channels/document_channel.rb`, installs
-yrby's table migration, and adds the standard Action Cable files when
-they are missing. The `Y::Document` and `Y::DocumentUpdate` models come
-from `yrby-rails`.
+The generator adds yrby's table migration. If the app uses import maps, it
+also adds pins. The channel, `LexxyRealtime::DocumentChannel`, ships in the
+gem. The `Y::Document` and `Y::DocumentUpdate` models come from
+`yrby-rails`.
 
 With a bundler, install the JavaScript package and import it next to
 your Lexxy import:
@@ -33,24 +33,32 @@ your Lexxy import:
 npm install lexxy-realtime   # yarn, bun, and pnpm also work
 ```
 
-With import maps, there is no npm install; the generator pins assets
-this gem ships:
+With import maps, there's no npm install. The generator pins assets this
+gem ships, one for each module the page must load only once:
 
 ```ruby
 # config/importmap.rb, added by the generator
-pin "lexical", to: "lexxy_realtime/lexical.js"
-pin "@37signals/lexxy", to: "lexxy_realtime/lexxy.js"
+pin "@37signals/lexxy", to: "lexxy.js"
 pin "lexxy-realtime", to: "lexxy_realtime/lexxy-realtime.js"
+pin "yrby-client", to: "lexxy_realtime/yrby-client.js"
+pin "yrby-client/element", to: "lexxy_realtime/yrby-client.js"
+pin "yjs", to: "lexxy_realtime/yjs.js"
+pin "@rails/actioncable", to: "actioncable.esm.js"
 pin "@rails/activestorage", to: "activestorage.esm.js"
 ```
 
-`lexical` is the one module the Lexxy and lexxy-realtime bundles share,
-so both ship with it external and it resolves through its own pin. The
-`@37signals/lexxy` pin must point at this gem's build: Lexxy's own
-asset bundles a second copy of `lexical`, and two copies break the
-collaboration binding, so remove any pin of Lexxy's asset. Keep
-`stylesheet_link_tag "lexxy"` for the editor's CSS. These assets are a
-stopgap until Lexxy ships import-map-ready builds itself.
+`@37signals/lexxy` points at the same file as the Lexxy gem's own `lexxy`
+pin, so the browser loads Lexxy once. lexxy-realtime gets lexical from
+Lexxy's `Lexical` export, so there's also one copy of lexical.
+
+yrby-client and yjs are separate files. A second copy of either would mean
+a second `<yrby-document>` class or a second Yjs, and the editor binding
+would break. With separate pins, any other code that imports them gets the
+same copy as lexxy-realtime. `@rails/actioncable` is Rails' own file, and
+`<yrby-document>` uses it for its default consumer.
+
+The generator keeps pins the app already has and adds the missing ones, so
+run it again after upgrading.
 
 Either way, your entrypoint imports both:
 
@@ -73,10 +81,13 @@ end
 <% end %>
 ```
 
-Add your app's access check to `authorized?` in the generated channel,
-then open the page in two browsers and edit together. The record must be persisted
-(the document key derives from it). A record with an existing body works: the
-first collaborative open seeds the document from it.
+Render the form only for users who may edit the record, then open the page
+in two browsers and edit together. You don't write a channel. The helper
+renders a signed grant for the record and field, and
+`LexxyRealtime::DocumentChannel` opens a document only for a valid grant.
+The record must be saved first, because the document key comes from its id.
+If the record already has a body, the first editor to open it copies that
+body into the new document.
 
 Encryption works the way Action Text's does:
 
@@ -84,37 +95,114 @@ Encryption works the way Action Text's does:
 has_collaborative_rich_text :body, encrypted: true
 ```
 
-The rendered body goes through `ActionText::EncryptedRichText`, and the
-collaborative document (CRDT state and update payloads) is stored through
-yrby's `Y::EncryptedDocument`. Both use Active Record encryption, so the
-app must configure encryption keys. Without Action Text, declare
-`encrypts` on the plain attribute yourself.
+Action Text stores the rendered body with `ActionText::EncryptedRichText`.
+yrby's `Y::EncryptedDocument` stores the collaborative document, both the
+CRDT state and each update. Both use Active Record encryption, so the app
+needs encryption keys configured. Without Action Text, declare `encrypts`
+on the plain attribute yourself.
 
-Use it for new attributes. Existing plaintext rows need migration
-before you add `encrypted: true`: enable `support_unencrypted_data`,
-rewrite each document, update, and rich-text row through its encrypted
-class, then turn it back off. There is no built-in task for that yet.
-And if your channel came from an earlier pre-release checkout, update it
-to the current record-based storage first; a channel calling
-`Y::Document` directly stores encrypted attributes as plaintext.
+This works best on new attributes. To encrypt an attribute that already
+has plaintext rows, enable `support_unencrypted_data`, rewrite each
+document, update, and rich-text row through its encrypted class, then
+turn the setting off again. The gem doesn't include a task for this.
 
 ## How the body stays current
 
-The channel records each CRDT update, renders the full document with
+The channel saves each CRDT update, renders the full document with
 `Y::Lexxy`, and saves the HTML through the Action Text writer. This
-happens synchronously in `refresh_collaborative_rich_text`, so
-reads use the stored `post.body` value.
+happens in `post.collaborative_document(:body).refresh`, inside the
+channel's handler for each update. There's no background job, so
+`post.body` is up to date as soon as the channel finishes handling the
+update. An edit from Ruby, `post.collaborative_document(:body).edit`,
+renders the body the same way.
 
-If rendering fails, the update remains stored and the error is logged.
-The next successful update renders the full document again. Until then,
-`post.body` keeps its previous value.
+If rendering fails, the channel logs the error and keeps the update. The
+next update renders the full document again. Until then, `post.body`
+keeps its previous value.
 
 ## Access control
 
-The form helper gives clients a signed GlobalID scoped to one record and
-field. `DocumentChannel` uses it to locate the record. Put the user
-access check in `authorized?` (for example,
-`record.editable_by?(current_user)`).
+The form helper renders a signed grant for the record and field.
+`LexxyRealtime::DocumentChannel` extends yrby-rails' `Y::DocumentChannel`
+and adds Action Text rendering. The grant uses its own purpose, so
+`Y::DocumentChannel` rejects it. A client can't get around the block below
+by subscribing to that channel. The channel rejects a missing, tampered,
+expired, or wrong-field grant, a deleted record, and a field that isn't
+declared with `has_collaborative_rich_text`. A valid grant means your app
+rendered the form for this user.
+
+To also check the user's current permissions when they subscribe, give
+the channel a block:
+
+```ruby
+# config/initializers/lexxy_realtime.rb
+Rails.application.config.to_prepare do
+  LexxyRealtime::DocumentChannel.authorize_document do |record, name|
+    record.editable_by?(current_user, attribute: name)
+  end
+end
+```
+
+The block runs inside the channel, so you can use `current_user` and your
+other connection identifiers. `editable_by?` is a placeholder for your own
+permission check. If the block returns false or nil, the channel rejects
+the subscription before it sends anything.
+
+## Grant lifetime and refresh
+
+A grant lasts as long as GlobalID's signed-id default, which is one month
+under Rails, and `expires_in:` on the form helper shortens it. The grant is
+part of the rendered page, though, and Action Cable resubscribes with it
+after every network drop. If the grant expires before the user is done
+editing, the editor stops syncing at the next reconnect. To avoid that,
+pair `expires_in:` with `refresh:`, a URL the page fetches when a
+subscription is rejected:
+
+```erb
+<%= form.collaborative_rich_textarea :body, expires_in: 10.minutes,
+                                             refresh: grant_post_path(@post) %>
+```
+
+```ruby
+# config/routes.rb:  resources :posts do get :grant, on: :member end
+# app/controllers/posts_controller.rb
+def grant
+  @post = current_user.posts.find(params[:id]) # your own authorization, again
+  render json: { grant: @post.collaborative_document(:body).grant(expires_in: 10.minutes) }
+end
+```
+
+For a field declared with `has_collaborative_rich_text`,
+`collaborative_document(:body)` returns this gem's document. Its `grant` is
+the one the form helper renders, its `channel` is
+`LexxyRealtime::DocumentChannel`, `edit` changes the document from Ruby and
+renders the body, and `refresh` renders the body on demand. Code that takes
+a yrby-rails document, such as `collaborative_document_tag`, gets this
+gem's grant and channel for the field.
+
+That action grants write access, so its check must be at least as strict
+as the page that renders the form. If it skips authorization, anyone who
+can reach the URL gets a grant, and a short `expires_in:` protects nothing.
+
+When a subscription is rejected, `<yrby-document>` fetches the URL with the
+session cookie, and the action runs your authorization again. If the
+response is `{ "grant": ... }`, the page resubscribes with the new grant and
+keeps the document and any edits the server hasn't acknowledged. If the
+refresh fails, the editor stops syncing until the page reloads, and
+`<yrby-document>` dispatches `yrby:error`. A refresh fails when the response
+is an error or has no grant, when it takes longer than 15 seconds, or when
+the server rejects the new grant. The page doesn't renew grants on a timer,
+so it won't interrupt a working subscription. Every reconnect after the
+grant expires runs your permission check again, and that's the reason to
+keep the lifetime short.
+
+Without `refresh:`, an editor whose grant has expired stops syncing at its
+next reconnect and starts again after the page reloads.
+
+While a grant is rejected and not renewed, `<yrby-document>` makes the
+editor inert, so nobody types into a document that can't sync. The editor
+is also inert before its first sync and whenever the page can't reach the
+server.
 
 ## Configuration
 
@@ -122,8 +210,8 @@ access check in `authorized?` (for example,
 LexxyRealtime.identity = ->(view) { { name: view.current_user.handle, color: nil } }
 ```
 
-By default, identity uses the first available `current_user` value from
-`name`, `username`, or `handle`, then falls back to `"Anonymous"`.
+By default, the cursor name is the first of `current_user.name`,
+`username`, or `handle` that has a value. Without one it's `"Anonymous"`.
 
 Full documentation, the demo app, and the JavaScript package:
 [repository README](https://github.com/jpcamara/lexxy-realtime#readme).