solid_objects 0.5.2 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8ac17dc212792f2dfa71c01e701a9e4de27f54b6198ec6e64696b855ff82c4c8
-  data.tar.gz: 45bff1ddb2bbc0ff80ddfb55488fec0380d02c729e08a7f06b000b744dddb82d
+  metadata.gz: 0614e42e260b81ab323d292435cd4f518a4f0b26a21865e5f63c9768db362231
+  data.tar.gz: a8c7d4bc22e431b89ab07058c0ad35ca82a44eef08d30b0a547b28c0dd76f82e
 SHA512:
-  metadata.gz: ffb590f2e07a0de4d4ba2ab5ac1cb7d76420b742d36d656b85ecdb0fc401dbabd92b75e47df73948f7e1d42fe4a289d2f16fa8d86086c8bff336ac4e33ae89dc
-  data.tar.gz: 5a43e24c8358e2352de0ca1428cdc10d15bdf679c62ca1983b420fa1e739d0c975004e0e33ffb64a96fe3d09cbbcd30181db6a95a678c071fd80f85b935811cd
+  metadata.gz: 07caec47a1c3452bb3f3b6fc6f950f60f9c68277ebb558630d112fcc7bfb9e3591f893e8bdaefea4329680cde6d6a86c36c0d9b6531d6ac889507abfda939920
+  data.tar.gz: 23d756629a2b8212d06077569b9d0c35552c6ee416c95851ee78357ecfe1abf672e0a973d9715f0b66942ecebf8e1c007f21d33bde3bfb7e79af30f323a809bf

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 0.7.0 - 2026-08-09
+
+- Add `batch:` to reactive components. Components sharing a batch in one actor
+  scope collapse into a single browser request per revision instead of one
+  request per component. The new `GET /solid_objects/components/batch` endpoint
+  returns HTML frames inside a documented JSON envelope, so Turbo morph and ERB
+  rendering are unchanged while the contract stays machine readable. Duplicate
+  notifications for the same batch and revision coalesce in the browser,
+  unchanged components are never requested, and stale frames cannot overwrite a
+  newer target. Components without `batch:` behave exactly as before.
+- Add a JavaScript test suite for the browser modules, run in CI with Node's
+  test runner and jsdom.
+
+## 0.6.0 - 2026-08-09
+
+- Add `broadcast_payload`, an actor DSL for sending one personalized JSON state
+  payload over the actor stream a page already has open. The block runs once per
+  subscriber with that subscriber's authorization context, so private state
+  never crosses sessions. Payloads carry actor identity and the monotonic state
+  revision, and both the channel and the browser drop stale revisions. Subscribe
+  with `solid_object room, payloads: :playmat_state` and handle the
+  `solid-objects:payload` DOM event. ERB component refreshes remain the default
+  and are unchanged. A mutation that changes payload state without changing a
+  declared observable still invalidates subscribers, through a revision-only
+  broadcast that carries no observable value to the browser.
+
 ## 0.5.2 - 2026-08-09
 
 - Read the database clock once per transaction instead of once per step, and

data/app/assets/javascripts/solid_objects/component_batch_refresh.js

@@ -0,0 +1,148 @@
+const pendingBatches = new Map()
+const activeBatches = new Map()
+
+class SolidObjectsBatchRefreshElement extends HTMLElement {
+  connectedCallback() {
+    if (this.dataset.started === "true") return
+
+    this.dataset.started = "true"
+    this.enqueue()
+  }
+
+  // Several observables changing in one commit produce several notifications
+  // for the same batch and revision. Merging them in a microtask turns those
+  // into a single request.
+  enqueue() {
+    const batch = this.dataset.batch
+    const revision = this.dataset.revision
+    const source = this.dataset.source
+    const scope = this.closest("[id]")?.id
+    if (!batch || !revision || !source || !scope) return this.remove()
+
+    // Two actor scopes may reuse a batch name on one page. Keying by scope
+    // keeps their requests from merging or cancelling each other.
+    const group = `${scope}:${batch}`
+    const key = `${group}:${revision}`
+    const pending = pendingBatches.get(key)
+    if (pending) {
+      pending.sources.add(source)
+      this.remove()
+      return
+    }
+
+    const merged = { sources: new Set([ source ]) }
+    pendingBatches.set(key, merged)
+    queueMicrotask(() => {
+      pendingBatches.delete(key)
+      requestBatch(group, batch, merged.sources)
+    })
+    this.remove()
+  }
+}
+
+async function requestBatch(group, batch, sources) {
+  const previous = activeBatches.get(group)
+  previous?.abort()
+
+  const controller = new AbortController()
+  activeBatches.set(group, controller)
+
+  try {
+    const url = mergedUrl(sources)
+    if (!url) return
+
+    const response = await fetch(url, {
+      credentials: "same-origin",
+      headers: { Accept: "application/json" },
+      redirect: "error",
+      signal: controller.signal
+    })
+    if (!response.ok) return dispatchBatchError(batch, `http_${response.status}`)
+
+    const body = await response.json()
+    if (!Array.isArray(body?.frames)) {
+      return dispatchBatchError(batch, "invalid_response")
+    }
+
+    body.frames.forEach(applyFrame)
+  } catch (error) {
+    if (error.name !== "AbortError") dispatchBatchError(batch, "request_failed")
+  } finally {
+    if (activeBatches.get(group) === controller) activeBatches.delete(group)
+  }
+}
+
+// Every notification for one batch and revision carries the same endpoint and
+// differs only by which components changed, so the union of their tokens is the
+// complete set to render.
+function mergedUrl(sources) {
+  const urls = [ ...sources ].map((source) => new URL(source, window.location.href))
+  const first = urls[0]
+  if (!first || first.origin !== window.location.origin) return
+
+  const tokens = new Set()
+  urls.forEach((url) => {
+    url.searchParams.getAll("tokens[]").forEach((token) => tokens.add(token))
+  })
+  first.searchParams.delete("tokens[]")
+  tokens.forEach((token) => first.searchParams.append("tokens[]", token))
+  return first
+}
+
+function applyFrame(frame) {
+  const target = document.getElementById(frame?.target)
+  if (!target || !frame.html) return
+  if (!newerRevision(frame.revision, target.dataset.solidObjectsRevision)) return
+
+  const parsed = new DOMParser().parseFromString(frame.html, "text/html")
+  const replacement = parsed.getElementById(frame.target)
+  if (!replacement) return
+
+  const stream = document.createElement("turbo-stream")
+  stream.setAttribute("action", "replace")
+  if (frame.refresh_method === "morph") stream.setAttribute("method", "morph")
+  stream.setAttribute("target", frame.target)
+
+  const template = document.createElement("template")
+  template.content.append(document.importNode(replacement, true))
+  stream.append(template)
+  document.documentElement.append(stream)
+}
+
+function newerRevision(candidate, current) {
+  const candidateRevision = parseRevision(candidate)
+  const currentRevision = parseRevision(current)
+  if (!candidateRevision || !currentRevision) return false
+
+  return candidateRevision[0] > currentRevision[0] ||
+    (candidateRevision[0] === currentRevision[0] &&
+      candidateRevision[1] > currentRevision[1])
+}
+
+function parseRevision(revision) {
+  if (!revision) return
+
+  const values = String(revision).split(":").map(Number)
+  if (
+    values.length !== 2 ||
+    values.some((value) => !Number.isSafeInteger(value) || value < 0)
+  ) return
+
+  return values
+}
+
+function dispatchBatchError(batch, reason) {
+  document.dispatchEvent(
+    new CustomEvent("solid-objects:batch-refresh-error", {
+      bubbles: true,
+      detail: { batch, reason }
+    })
+  )
+}
+
+if (!customElements.get("solid-objects-batch-refresh")) {
+  customElements.define(
+    "solid-objects-batch-refresh",
+    SolidObjectsBatchRefreshElement
+  )
+}

data/app/assets/javascripts/solid_objects/state_payload.js

@@ -0,0 +1,69 @@
+const deliveredRevisions = new Map()
+
+class SolidObjectsPayloadElement extends HTMLElement {
+  connectedCallback() {
+    if (this.dataset.started === "true") return
+
+    this.dataset.started = "true"
+    this.deliver()
+  }
+
+  deliver() {
+    try {
+      const name = this.dataset.name
+      const revision = revisionFor(this)
+      const scope = this.closest("[id]")
+      if (!name || !revision || !scope) return
+
+      const key = `${scope.id}:${name}`
+      if (!newerRevision(revision, deliveredRevisions.get(key))) return
+
+      const payload = JSON.parse(this.textContent)
+      deliveredRevisions.set(key, revision)
+      scope.dispatchEvent(
+        new CustomEvent("solid-objects:payload", {
+          bubbles: true,
+          detail: {
+            name,
+            instanceId: revision[0],
+            revision: revision[1],
+            payload
+          }
+        })
+      )
+    } catch {
+      this.dispatchEvent(
+        new CustomEvent("solid-objects:payload-error", {
+          bubbles: true,
+          detail: { reason: "invalid_payload" }
+        })
+      )
+    } finally {
+      this.remove()
+    }
+  }
+}
+
+function newerRevision(candidate, current) {
+  if (!current) return true
+
+  return candidate[0] > current[0] ||
+    (candidate[0] === current[0] && candidate[1] > current[1])
+}
+
+function revisionFor(element) {
+  const revision = element.dataset.revision
+  if (!revision) return
+
+  const values = revision.split(":").map(Number)
+  if (
+    values.length !== 2 ||
+    values.some((value) => !Number.isSafeInteger(value) || value < 0)
+  ) return
+
+  return values
+}
+
+if (!customElements.get("solid-objects-payload")) {
+  customElements.define("solid-objects-payload", SolidObjectsPayloadElement)
+}

data/app/controllers/solid_objects/components_controller.rb

@@ -6,13 +6,97 @@ module SolidObjects
   class ComponentsController < ActionController::Base
     protect_from_forgery with: :exception
 
+    BATCH_LIMIT = 50
+
     # @rbs () -> void
     def show
       SolidObjects.instrument(:"component.refreshed") { |payload| refresh(payload) }
     end
 
+    # @rbs () -> void
+    def batch
+      SolidObjects.instrument(:"component.batch_refreshed") { |payload| refresh_batch(payload) }
+    end
+
     private
 
+    # @rbs (Hash[Symbol, untyped]) -> void
+    def refresh_batch(payload)
+      tokens = Array(params.require(:tokens))
+      raise ActionController::ParameterMissing, :tokens if tokens.empty?
+      raise ArgumentError if tokens.length > BATCH_LIMIT
+
+      registrations = tokens.map { |token| ComponentRegistration.from_token(token) }
+      validate_single_batch!(registrations)
+      requested_revision = requested_revision_key
+      snapshot = ActorSnapshot.new(registrations.first.reference)
+      payload.merge!(
+        actor_type: snapshot.reference.actor_type,
+        actor_id: snapshot.reference.actor_id,
+        batch: registrations.first.batch,
+        components: registrations.map(&:component_name),
+        instance_id: snapshot.instance_id,
+        revision: snapshot.revision
+      )
+      if newer_than_snapshot?(requested_revision, snapshot)
+        payload[:outcome] = "conflict"
+        return head :conflict
+      end
+
+      authorization_context = SolidObjects
+        .configuration
+        .component_authorization_context
+        .call(controller: self)
+      frames = registrations.map do |registration|
+        rendered = ComponentRenderer.new(
+          snapshot:,
+          registration:,
+          view_context: component_view_context,
+          authorization_context:
+        ).call
+        {
+          "target" => registration.dom_id,
+          "revision" => "#{snapshot.instance_id}:#{snapshot.revision}",
+          "refresh_method" => registration.refresh_method,
+          "html" => component_frame(registration, snapshot, rendered)
+        }
+      end
+      response.headers["Cache-Control"] = "private, no-store"
+      payload[:outcome] = "rendered"
+      render json: {
+        "actor_type" => snapshot.reference.actor_type,
+        "actor_id" => snapshot.reference.actor_id,
+        "batch" => registrations.first.batch,
+        "instance_id" => snapshot.instance_id,
+        "revision" => snapshot.revision,
+        "frames" => frames
+      }
+    rescue Unauthorized
+      payload[:outcome] = "unauthorized"
+      head :forbidden
+    rescue UnknownComponent
+      payload[:outcome] = "unknown_component"
+      head :not_found
+    rescue ActionController::ParameterMissing,
+      ArgumentError,
+      InvalidComponentToken
+      payload[:outcome] = "invalid_token"
+      head :bad_request
+    end
+
+    # @rbs (Array[ComponentRegistration]) -> void
+    def validate_single_batch!(registrations)
+      first = registrations.first
+      raise ArgumentError unless first.batch
+      return if registrations.all? do |registration|
+        registration.batch == first.batch &&
+          registration.reference.actor_type == first.reference.actor_type &&
+          registration.reference.actor_id == first.reference.actor_id
+      end
+
+      raise ArgumentError
+    end
+
     # @rbs (Hash[Symbol, untyped]) -> void
     def refresh(payload)
       registration = ComponentRegistration.from_token(

data/app/helpers/solid_objects/actor_helper.rb

@@ -2,8 +2,9 @@
 
 module SolidObjects
   module ActorHelper
-    # @rbs (Reference, ?authorization_context: untyped) { (ActorView) -> untyped } -> untyped
-    def solid_object(reference, authorization_context: self, &block)
+    # @rbs (Reference, ?authorization_context: untyped, ?payloads: untyped) { (ActorView) -> untyped } -> untyped
+    def solid_object(reference, authorization_context: self, payloads: nil, &block)
+      payload_names = Array(payloads).map(&:to_s).uniq.presence
       actor = ActorView.new(
         reference:,
         view_context: self,
@@ -13,7 +14,8 @@ module SolidObjects
       subscription_data = {
         token: StreamToken.generate(
           reference,
-          observables: actor.scalar_observable_names
+          observables: actor.scalar_observable_names,
+          payloads: payload_names
         )
       }
       if actor.component_tokens.any?
@@ -30,10 +32,26 @@ module SolidObjects
           data: { turbo_track: "reload" }
         )
       end
+      batch_client = if actor.batched_components?
+        javascript_include_tag(
+          "solid_objects/component_batch_refresh",
+          type: "module",
+          data: { turbo_track: "reload" }
+        )
+      end
+      payload_client = if payload_names
+        javascript_include_tag(
+          "solid_objects/state_payload",
+          type: "module",
+          data: { turbo_track: "reload" }
+        )
+      end
 
       content_tag(
         :div,
-        safe_join([ refresh_client, subscription, content ].compact),
+        safe_join(
+          [ refresh_client, batch_client, payload_client, subscription, content ].compact
+        ),
         id: DomIdentity.scope(reference)
       )
     end

data/config/routes.rb

@@ -2,6 +2,7 @@
 
 SolidObjects::Engine.routes.draw do
   get :components, to: "components#show"
+  get "components/batch", to: "components#batch"
   resources :instances, only: %i[index show]
   resources :dead_letters, only: %i[index] do
     post :retry, on: :member

data/docs/realtime.md

@@ -110,6 +110,167 @@ applications discover the namespaced engine asset. Applications created with
 explicitly serve the module. Turbo's normal morph rules still apply; use
 `data-turbo-permanent` for elements that must never be changed.
 
+## Batched component refreshes
+
+A component refresh costs one browser request. When one actor mutation changes
+several components, the page pays one request per component. Adding `batch:`
+groups them so a revision costs one request no matter how many components in the
+group changed:
+
+```erb
+<%= actor.component :player, key: 1,
+      observes: :player_one, batch: :playmat, refresh: :morph %>
+
+<%= actor.component :player_controls, key: 1,
+      observes: :player_one_controls, batch: :playmat, refresh: :morph %>
+
+<%= actor.component :library_search, key: 1,
+      observes: :library, batch: :playmat, refresh: :morph %>
+```
+
+Before, one mutation touching all three observables produced three requests:
+
+```
+commit -> 3 invalidations -> 3 refresh elements -> 3 GET /solid_objects/components
+```
+
+After, the three notifications coalesce in the browser into one request:
+
+```
+commit -> 3 invalidations -> 1 GET /solid_objects/components/batch -> 3 frames
+```
+
+### The batch endpoint
+
+`GET /solid_objects/components/batch` takes the signed `tokens[]` of the
+components to render plus the `instance_id` and `revision` the browser holds. It
+returns HTML frames inside a JSON envelope:
+
+```json
+{
+  "actor_type": "playmat_room",
+  "actor_id": "table-1",
+  "batch": "playmat",
+  "instance_id": 12,
+  "revision": 48,
+  "frames": [
+    {
+      "target": "solid-objects-component-...",
+      "revision": "12:48",
+      "refresh_method": "morph",
+      "html": "<turbo-frame id=\"...\" data-solid-objects-revision=\"12:48\">...</turbo-frame>"
+    }
+  ]
+}
+```
+
+**Why frames inside JSON rather than one HTML document or pure JSON state.** HTML
+alone would force the browser to pick frames out of an undocumented document.
+Pure JSON would mean a second renderer and would give up ERB and Turbo morph. A
+JSON envelope of frame descriptors keeps `ComponentRenderer` and Turbo exactly as
+they are while giving the client a documented contract with per-frame revisions.
+
+### What the protocol guarantees
+
+Only components whose dependencies changed are requested; the rest are never
+named in the batch. Duplicate notifications for the same batch and revision merge
+into one request, and a superseded request for the same batch is aborted. Each
+frame carries its own revision and cannot overwrite a target that already holds a
+newer one. Authorization is unchanged: every component in the batch passes the
+same `authorize_query` boundary an individual refresh uses, and the batch name is
+signed into the component token, so a browser cannot invent or widen a group. A
+batch mixing actors or groups is rejected.
+
+Components without `batch:` keep issuing their own request, and a scope can mix
+batched and unbatched components freely.
+
+## Personalized state payloads
+
+Reactive ERB components cost one browser request per changed component. When a
+single actor mutation changes several components, an application pays several
+round trips for one logical update. A payload broadcast collapses that into one
+message on the stream the page already has open.
+
+Declare the payload on the actor. The block receives the actor and the
+subscriber's authorization context, and it runs **once per subscriber**, so two
+sessions watching the same actor never see each other's private state:
+
+```ruby
+class PlaymatRoom < SolidObjects::Actor
+  actor_type "playmat_room"
+
+  attribute :hands, default: -> { {} }
+  attribute :turn, default: 1
+
+  observable :turn
+
+  broadcast_payload :playmat_state do |room, authorization_context|
+    {
+      "turn" => room.turn,
+      "hand" => room.hands.fetch(authorization_context.session_id, [])
+    }
+  end
+end
+```
+
+Subscribe the scope to it:
+
+```erb
+<%= solid_object room, payloads: :playmat_state do |actor| %>
+  <div data-playmat></div>
+<% end %>
+```
+
+Handle it with any JavaScript. The gem dispatches a DOM event and requires no
+framework:
+
+```javascript
+document.addEventListener("solid-objects:payload", (event) => {
+  const { name, revision, payload } = event.detail
+  if (name !== "playmat_state") return
+
+  renderPlaymat(payload)
+})
+```
+
+### What the protocol guarantees
+
+The payload travels as a Turbo Stream element on the existing actor stream, so
+applications do not run a second WebSocket system. Each message carries the
+actor identity plus the `instance_id` and monotonic `state_revision` that fence
+component refreshes, and both the channel and the browser drop a payload that
+is not newer than the last one delivered for that scope and name. A reconnecting
+client receives the current payload on subscribe.
+
+Authorization is the same `authorize_query` boundary that components use, called
+with the payload name and the subscriber's Cable connection. A subscriber that
+fails the check is skipped rather than served a partial payload, and the payload
+name is signed into the stream token, so a browser cannot ask for a payload the
+server did not offer.
+
+Payload blocks read committed actor state through the same snapshot components
+use. They cannot write application records, and the return value must be a JSON
+object or array so the wire format stays inspectable.
+
+### mtg-playmat before and after
+
+Before, one mutation that touched three observables produced three refresh
+elements and three HTTP requests:
+
+```
+commit -> 3 Action Cable messages -> 3 GET /solid_objects/components -> 3 renders
+```
+
+After, the same mutation delivers one personalized payload and the page renders
+once:
+
+```
+commit -> 1 Action Cable message -> 0 HTTP requests -> 1 render
+```
+
+Components remain the default. An actor with no `broadcast_payload` and a scope
+with no `payloads:` option behave exactly as before.
+
 ## Authorization
 
 The HTML contains a signed actor identity token. Signing prevents modification;

data/lib/solid_objects/actor.rb

@@ -57,6 +57,13 @@ module SolidObjects
         definition.add_observable(name, block)
       end
 
+      # @rbs (Symbol | String) { (untyped, untyped) -> untyped } -> ActorDefinition::Handler
+      def broadcast_payload(name, &block)
+        raise InvalidActor, "payload broadcasts require a block" unless block
+
+        definition.add_payload_broadcast(name, block)
+      end
+
       # @rbs (?Integer) -> Integer
       def state_version(version = nil)
         definition.set_state_version(version) if version

data/lib/solid_objects/actor_channel.rb

@@ -19,7 +19,9 @@ module SolidObjects
 
       @reference = Reference.new(actor_type:, actor_id:)
       @scalar_observables = identity["observables"]
+      @payload_names = identity["payloads"]
       validate_scalar_observables!
+      validate_payload_names!
       @component_subscriptions = ComponentSubscriptions.parse(
         params["components"],
         reference:
@@ -36,6 +38,7 @@ module SolidObjects
         )
       end
       refresh_outdated_components(snapshot)
+      transmit_state_payloads(snapshot)
     rescue KeyError,
       JSON::ParserError,
       InvalidStreamToken,
@@ -46,14 +49,20 @@ module SolidObjects
 
     private
 
-    attr_reader :reference, :component_subscriptions, :scalar_observables
+    attr_reader :reference,
+      :component_subscriptions,
+      :scalar_observables,
+      :payload_names
 
     # @rbs (String) -> void
     def receive_broadcast(stream)
       invalidation = TurboStreamRenderer.invalidation(stream)
-      if !invalidation ||
-          scalar_observables.nil? ||
-          scalar_observables.include?(invalidation.fetch("observable_name"))
+      revision_only = invalidation &&
+        invalidation.fetch("observable_name") == PayloadBroadcast::REVISION_OBSERVABLE
+      if !revision_only &&
+          (!invalidation ||
+            scalar_observables.nil? ||
+            scalar_observables.include?(invalidation.fetch("observable_name")))
         transmit stream
       end
       return unless invalidation
@@ -61,6 +70,48 @@ module SolidObjects
       component_subscriptions
         .refreshes_for(invalidation)
         .each { |refresh| transmit refresh }
+      transmit_state_payloads(ActorSnapshot.new(reference))
+    end
+
+    # @rbs (ActorSnapshot) -> void
+    def transmit_state_payloads(snapshot)
+      return if payload_names.nil? || payload_names.empty?
+      return unless newer_payload_revision?(snapshot)
+
+      payload_names.each do |name|
+        payload = PayloadBroadcast.new(
+          snapshot:,
+          name:,
+          authorization_context: connection
+        ).call
+        transmit TurboStreamRenderer.state_payload(payload)
+      rescue Unauthorized
+        next
+      end
+      @payload_revision = [ snapshot.instance_id, snapshot.revision ]
+    end
+
+    # @rbs (ActorSnapshot) -> bool
+    def newer_payload_revision?(snapshot)
+      current = @payload_revision
+      return true unless current
+
+      (current <=> [ snapshot.instance_id, snapshot.revision ]) == -1
+    end
+
+    # @rbs () -> void
+    def validate_payload_names!
+      return unless payload_names
+
+      broadcasts = SolidObjects
+        .registry
+        .fetch(reference.actor_type)
+        .definition
+        .payload_broadcasts
+      unknown = payload_names.find { |name| !broadcasts.key?(name.to_sym) }
+      return unless unknown
+
+      raise InvalidStreamToken, "unknown payload broadcast #{unknown.inspect}"
     end
 
     # @rbs (ActorSnapshot) -> void