solid_objects 0.6.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6996e5e1ea8fa47b59b66cb6ed0f72e28d1673c2da5697e5507873db55f0b7ff
-  data.tar.gz: edb728dd6427ca4a1486dc791816b7a3ab8d3bdf822992c27d3800ab925c120e
+  metadata.gz: 75595f12197f05985076afb8974ec528b85914db25da49c29b342b9fc531ad97
+  data.tar.gz: d240311fe0bfbbd12386d582c4a8dcb560a2698385d65c1f0781340880cbd11c
 SHA512:
-  metadata.gz: 888370023e0d24e18eda279862a01a31b8583fccc5913fae571fa76d4001de1f408b22e7c3242c23975f01aeb293c47bd9314d94d98177e99c353fb78796caaa
-  data.tar.gz: 130982ddf19508a6268ae7356ac6249cd8efcc10cc29dd5c13e5cd865322540deabae688e511825a3a92bdc6bfe6314cf9f003d3ec2f4d273d968668438a1588
+  metadata.gz: e303049a41809dca76e99ed3b035cde028817e2f0a6a7fadc1fd90f41bde9e108b83bc06247d596722c135ffad4b9b2fda9e5fb75277a89e837acc0c3ade9b25
+  data.tar.gz: 8f800ed5e80df86176ff1f7967da7f117363607c2993872670bfe0d85a0ece83db1eef8f1f4f72a74992182cae77f36bd80ea30ebc81b9c7a5bd03ba16a14785

data/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.7.1 - 2026-08-09
+
+- Retry a contended SQLite write outside a synchronous deadline. Asynchronous
+  enqueue had no Ruby-level retry budget, so it depended entirely on SQLite's
+  busy handler and raised `SQLite3::BusyException` once concurrent writers
+  exhausted it. Bounded by the new `lock_retry_attempts` setting.
+- Pin every GitHub Actions reference to a commit SHA.
+- Add a benchmark comparing individual, batched, and payload delivery for one
+  mutation that changes three components.
+
+## 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

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/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

@@ -32,6 +32,13 @@ 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",
@@ -42,7 +49,9 @@ module SolidObjects
 
       content_tag(
         :div,
-        safe_join([ refresh_client, payload_client, subscription, content ].compact),
+        safe_join(
+          [ refresh_client, batch_client, payload_client, subscription, content ].compact
+        ),
         id: DomIdentity.scope(reference)
       )
     end

data/benchmark/component_delivery.rb

@@ -0,0 +1,5 @@
+# rbs_inline: enabled
+
+require_relative "support"
+
+SolidObjectsBenchmark.component_delivery

data/benchmark/support.rb

@@ -22,6 +22,43 @@ module SolidObjectsBenchmark
     end
   end
 
+  class BenchmarkConnection
+    attr_reader :session_id
+
+    def initialize(session_id)
+      @session_id = session_id
+    end
+  end
+
+  class PlaymatActor < SolidObjects::Actor
+    actor_type "benchmark-playmat"
+
+    attribute :player, default: "unseated"
+    attribute :player_controls, default: -> { [] }
+    attribute :library_search, default: -> { [] }
+    attribute :hands, default: -> { {} }
+
+    observable :player
+    observable :player_controls
+    observable :library_search
+
+    broadcast_payload :playmat_state do |actor, context|
+      {
+        "player" => actor.player,
+        "controls" => actor.player_controls,
+        "library" => actor.library_search,
+        "hand" => actor.hands.fetch(context.session_id, [])
+      }
+    end
+
+    def seat(player:)
+      self.player = player
+      self.player_controls = %w[untap draw]
+      self.library_search = %w[Island Forest]
+      self.hands = hands.merge(player => %w[Island])
+    end
+  end
+
   class << self
     # @rbs () -> Integer
     def count
@@ -189,6 +226,69 @@ module SolidObjectsBenchmark
       worker&.stop
     end
 
+    # Compares how many browser requests one actor mutation costs across the
+    # three delivery paths, and how long the server spends producing them.
+    # @rbs () -> void
+    def component_delivery
+      require "action_controller"
+      require "action_view"
+      require "action_view/testing/resolvers"
+
+      SolidObjects.configuration.stream_signing_secret = "benchmark-secret"
+      SolidObjects.configuration.authorize_query = ->(**) { true }
+      reference = PlaymatActor.ref("table")
+      reference.seat(player: "alice")
+
+      view_context = benchmark_view_context
+      snapshot = SolidObjects::ActorSnapshot.new(reference)
+      registrations = %w[player player_controls library_search].map do |name|
+        SolidObjects::ComponentRegistration.issue(
+          reference:,
+          component_name: name,
+          component_key: nil,
+          dependencies: [ name ],
+          locals: {},
+          refresh_method: "morph",
+          snapshot:,
+          refresh_path: "/solid_objects/components",
+          batch: "playmat"
+        )
+      end
+
+      individual = measure_delivery(count) do
+        registrations.each do |registration|
+          render_component(registration, view_context)
+        end
+      end
+      batched = measure_delivery(count) do
+        current = SolidObjects::ActorSnapshot.new(reference)
+        registrations.each do |registration|
+          render_component(registration, view_context, snapshot: current)
+        end
+      end
+      payload = measure_delivery(count) do
+        SolidObjects::PayloadBroadcast.new(
+          snapshot: SolidObjects::ActorSnapshot.new(reference),
+          name: "playmat_state",
+          authorization_context: BenchmarkConnection.new("alice")
+        ).call
+      end
+
+      puts "three components changing in one mutation, #{count} iterations"
+      puts format(
+        "  individual refreshes: 3 requests, %.3fms per mutation",
+        individual
+      )
+      puts format(
+        "  batched refresh:      1 request,  %.3fms per mutation",
+        batched
+      )
+      puts format(
+        "  state payload:        0 requests, %.3fms per mutation",
+        payload
+      )
+    end
+
     # @rbs () -> void
     def query_count
       CounterActor.ref("queries").async(:increment)
@@ -209,6 +309,37 @@ module SolidObjectsBenchmark
 
     private
 
+    # @rbs (ComponentRegistration, untyped, ?snapshot: ActorSnapshot?) -> untyped
+    def render_component(registration, view_context, snapshot: nil)
+      SolidObjects::ComponentRenderer.new(
+        snapshot: snapshot || SolidObjects::ActorSnapshot.new(registration.reference),
+        registration:,
+        view_context:,
+        authorization_context: nil
+      ).call
+    end
+
+    # @rbs (Integer) { () -> untyped } -> Float
+    def measure_delivery(iterations)
+      yield
+      elapsed = Benchmark.realtime { iterations.times { yield } }
+      (elapsed / iterations) * 1_000
+    end
+
+    # @rbs () -> untyped
+    def benchmark_view_context
+      resolver = ActionView::FixtureResolver.new(
+        "actors/solid_objects_benchmark/playmat_actor/_player.html.erb" => "<p><%= actor.player %></p>",
+        "actors/solid_objects_benchmark/playmat_actor/_player_controls.html.erb" => "<ul><% actor.player_controls.each do |c| %><li><%= c %></li><% end %></ul>",
+        "actors/solid_objects_benchmark/playmat_actor/_library_search.html.erb" => "<ul><% actor.library_search.each do |c| %><li><%= c %></li><% end %></ul>"
+      )
+      ActionView::Base.with_empty_template_cache.new(
+        ActionView::LookupContext.new([ resolver ]),
+        {},
+        nil
+      )
+    end
+
     # @rbs () -> void
     def establish_connection
       database_url = ENV["SOLID_OBJECTS_DATABASE_URL"]

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/benchmarks.md

@@ -54,6 +54,28 @@ result is why Solid Objects does not publish one latency promise. Network
 topology, adapter behavior, host schema, logging, callbacks, and contention all
 matter.
 
+## Reactive delivery paths
+
+Measured 2026-08-09 on an Apple M5 with 200 iterations, for one actor mutation
+that changes three components.
+
+| Delivery path | Browser requests | Server render time |
+| --- | ---: | ---: |
+| Individual component refreshes | 3 | 0.535 ms |
+| Batched refresh | 1 | 0.249 ms |
+| State payload broadcast | 0 | 0.100 ms |
+
+The request column is the headline. Server render time is small in every path,
+so the win is not faster rendering, it is fewer round trips: each individual
+refresh costs a full HTTP request through the Rails middleware stack, and a
+batch replaces three of those with one. A state payload removes the HTTP leg
+entirely by travelling on the Action Cable connection the page already holds.
+
+These are server-side numbers. They do not include network latency, Action
+Cable delivery, or browser rendering, which dominate wall-clock time in a real
+deployment and make the request-count difference matter more than it appears
+here. End-to-end latency against a deployed application has not been measured.
+
 ## Durable row growth
 
 The storage cost is deterministic even when latency is not:

data/docs/realtime.md

@@ -110,6 +110,80 @@ 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

data/lib/solid_objects/actor_view.rb

@@ -37,18 +37,19 @@ module SolidObjects
       )
     end
 
-    # @rbs (Symbol | String, ?observes: Symbol | String | Array[Symbol | String]?, ?partial: String?, ?key: untyped, ?locals: Hash[untyped, untyped], ?refresh: String | Symbol) -> untyped
+    # @rbs (Symbol | String, ?observes: Symbol | String | Array[Symbol | String]?, ?partial: String?, ?key: untyped, ?locals: Hash[untyped, untyped], ?refresh: String | Symbol, ?batch: untyped) -> untyped
     def component(
       name,
       observes: nil,
       partial: nil,
       key: nil,
       locals: {},
-      refresh: :replace
+      refresh: :replace,
+      batch: nil
     )
       component_name = normalized_component_name(name)
       unless observes
-        validate_static_options!(key:, locals:, refresh:)
+        validate_static_options!(key:, locals:, refresh:, batch:)
         return static_component(component_name, partial:)
       end
       if partial
@@ -67,7 +68,8 @@ module SolidObjects
         locals:,
         refresh_method: refresh,
         snapshot:,
-        refresh_path:
+        refresh_path:,
+        batch: batch&.to_s
       )
       ensure_unique_component!(registration)
       rendered = ComponentRenderer.new(
@@ -98,6 +100,11 @@ module SolidObjects
       observable_names.dup
     end
 
+    # @rbs () -> bool
+    def batched_components?
+      component_registrations.any?(&:batch)
+    end
+
     # @rbs () -> bool
     def morph_components?
       component_registrations.any?(&:morph?)
@@ -212,9 +219,9 @@ module SolidObjects
           "#{registration.component_key.inspect} is already rendered in this solid_object scope"
     end
 
-    # @rbs (key: untyped, locals: Hash[untyped, untyped], refresh: String | Symbol) -> void
-    def validate_static_options!(key:, locals:, refresh:)
-      return if key.nil? && locals.empty? && refresh.to_s == "replace"
+    # @rbs (key: untyped, locals: Hash[untyped, untyped], refresh: String | Symbol, batch: untyped) -> void
+    def validate_static_options!(key:, locals:, refresh:, batch:)
+      return if key.nil? && locals.empty? && refresh.to_s == "replace" && batch.nil?
 
       raise ArgumentError,
         "key, locals, and refresh require an observable component"

data/lib/solid_objects/component_registration.rb

@@ -7,6 +7,7 @@ module SolidObjects
     # @rbs @reference: Reference
     # @rbs @component_name: String
     # @rbs @component_key: String | Integer?
+    # @rbs @batch: String?
     # @rbs @dependencies: Array[String]
     # @rbs @locals: Hash[String, untyped]
     # @rbs @refresh_method: String
@@ -18,6 +19,7 @@ module SolidObjects
     attr_reader :reference,
       :component_name,
       :component_key,
+      :batch,
       :dependencies,
       :locals,
       :refresh_method,
@@ -26,7 +28,7 @@ module SolidObjects
       :refresh_path,
       :token
 
-    # @rbs (reference: Reference, component_name: String, component_key: String | Integer?, dependencies: Array[String], locals: Hash[String, untyped], refresh_method: String, instance_id: Integer, revision: Integer, refresh_path: String, token: String) -> void
+    # @rbs (reference: Reference, component_name: String, component_key: String | Integer?, dependencies: Array[String], locals: Hash[String, untyped], refresh_method: String, instance_id: Integer, revision: Integer, refresh_path: String, token: String, ?batch: String?) -> void
     def initialize(
       reference:,
       component_name:,
@@ -37,9 +39,11 @@ module SolidObjects
       instance_id:,
       revision:,
       refresh_path:,
-      token:
+      token:,
+      batch: nil
     )
       @reference = reference
+      @batch = batch
       @component_name = component_name
       @component_key = component_key
       @dependencies = dependencies.freeze
@@ -52,7 +56,7 @@ module SolidObjects
     end
 
     class << self
-      # @rbs (reference: Reference, component_name: String, component_key: untyped, dependencies: Array[String], locals: Hash[untyped, untyped], refresh_method: String | Symbol, snapshot: ActorSnapshot, refresh_path: String) -> ComponentRegistration
+      # @rbs (reference: Reference, component_name: String, component_key: untyped, dependencies: Array[String], locals: Hash[untyped, untyped], refresh_method: String | Symbol, snapshot: ActorSnapshot, refresh_path: String, ?batch: String?) -> ComponentRegistration
       def issue(
         reference:,
         component_name:,
@@ -61,7 +65,8 @@ module SolidObjects
         locals:,
         refresh_method:,
         snapshot:,
-        refresh_path:
+        refresh_path:,
+        batch: nil
       )
         token = ComponentToken.generate(
           reference:,
@@ -70,6 +75,7 @@ module SolidObjects
           dependencies:,
           locals:,
           refresh_method:,
+          batch:,
           instance_id: snapshot.instance_id,
           revision: snapshot.revision,
           refresh_path:
@@ -99,6 +105,7 @@ module SolidObjects
           reference:,
           component_name: payload.fetch("component_name"),
           component_key: payload["component_key"],
+          batch: payload["batch"],
           dependencies:,
           locals: payload.fetch("locals"),
           refresh_method: payload.fetch("refresh_method"),
@@ -149,6 +156,18 @@ module SolidObjects
       locals.merge("component_key" => component_key).freeze
     end
 
+    # @rbs (Array[ComponentRegistration], Integer, Integer) -> String
+    def batch_refresh_url(registrations, instance_id, revision)
+      query = URI.encode_www_form(
+        [
+          [ "instance_id", instance_id ],
+          [ "revision", revision ],
+          *registrations.map { |registration| [ "tokens[]", registration.token ] }
+        ]
+      )
+      "#{refresh_path}/batch?#{query}"
+    end
+
     # @rbs (Integer, Integer) -> String
     def refresh_url(instance_id, revision)
       query = URI.encode_www_form(

data/lib/solid_objects/component_subscriptions.rb

@@ -48,16 +48,17 @@ module SolidObjects
       observable_name = invalidation.fetch("observable_name")
       instance_id = invalidation.fetch("instance_id")
       revision = invalidation.fetch("revision")
-      registrations.filter_map do |registration|
-        next unless registration.dependencies.include?(observable_name)
-        next unless newer_revision?(
-          registration.dom_id,
-          instance_id,
-          revision
-        )
-
-        refresh(registration, instance_id, revision)
+      changed = registrations.select do |registration|
+        registration.dependencies.include?(observable_name) &&
+          newer_revision?(registration.dom_id, instance_id, revision)
       end
+      batched, individual = changed.partition(&:batch)
+      streams = individual.map { |registration| refresh(registration, instance_id, revision) }
+      batched.group_by(&:batch).each_value do |group|
+        group.each { |registration| record_revision(registration, instance_id, revision) }
+        streams << TurboStreamRenderer.batch_refresh(group, instance_id, revision)
+      end
+      streams
     end
 
     # @rbs (ActorSnapshot) -> Array[String]
@@ -90,9 +91,14 @@ module SolidObjects
 
     attr_reader :registrations, :revisions
 
+    # @rbs (ComponentRegistration, Integer, Integer) -> void
+    def record_revision(registration, instance_id, revision)
+      revisions[registration.dom_id] = [ instance_id, revision ]
+    end
+
     # @rbs (ComponentRegistration, Integer, Integer) -> String
     def refresh(registration, instance_id, revision)
-      revisions[registration.dom_id] = [ instance_id, revision ]
+      record_revision(registration, instance_id, revision)
       TurboStreamRenderer.component_refresh(
         registration,
         instance_id,

data/lib/solid_objects/component_token.rb

@@ -9,6 +9,7 @@ module SolidObjects
     MAXIMUM_DEPENDENCIES = 50
     MAXIMUM_LOCALS = 50
     MAXIMUM_COMPONENT_KEY_BYTES = 512
+    MAXIMUM_BATCH_BYTES = 64
     REFRESH_METHODS = %w[replace morph].freeze
     RESERVED_LOCALS = %w[actor authorization_context component_key].freeze
     RUBY_KEYWORDS = %w[
@@ -19,7 +20,7 @@ module SolidObjects
 
     module_function
 
-    # @rbs (reference: Reference, component_name: String, dependencies: Array[String], instance_id: Integer, revision: Integer, refresh_path: String, ?component_key: untyped, ?locals: Hash[untyped, untyped], ?refresh_method: String | Symbol) -> String
+    # @rbs (reference: Reference, component_name: String, dependencies: Array[String], instance_id: Integer, revision: Integer, refresh_path: String, ?component_key: untyped, ?locals: Hash[untyped, untyped], ?refresh_method: String | Symbol, ?batch: untyped) -> String
     def generate(
       reference:,
       component_name:,
@@ -29,13 +30,15 @@ module SolidObjects
       refresh_path:,
       component_key: nil,
       locals: {},
-      refresh_method: "replace"
+      refresh_method: "replace",
+      batch: nil
     )
       payload = {
         "actor_type" => reference.actor_type,
         "actor_id" => reference.actor_id,
         "component_name" => component_name,
         "component_key" => Serialization.dump(component_key),
+        "batch" => batch&.to_s,
         "dependencies" => dependencies,
         "locals" => Serialization.dump(locals),
         "refresh_method" => refresh_method.to_s,
@@ -80,6 +83,7 @@ module SolidObjects
 
       validate_component_name!(payload.fetch("component_name"))
       validate_component_key!(payload["component_key"])
+      validate_batch!(payload["batch"])
       validate_dependencies!(payload.fetch("dependencies"))
       validate_locals!(payload.fetch("locals"))
       validate_refresh_method!(payload.fetch("refresh_method"))
@@ -97,6 +101,7 @@ module SolidObjects
       return unless payload.is_a?(Hash)
 
       payload["component_key"] = nil unless payload.key?("component_key")
+      payload["batch"] = nil unless payload.key?("batch")
       payload["locals"] = {} unless payload.key?("locals")
       payload["refresh_method"] = "replace" unless payload.key?("refresh_method")
     end
@@ -124,6 +129,18 @@ module SolidObjects
     end
     private_class_method :validate_component_key!
 
+    # @rbs (untyped) -> void
+    def validate_batch!(batch)
+      return if batch.nil?
+      return if batch.is_a?(String) &&
+        batch.bytesize.positive? &&
+        batch.bytesize <= MAXIMUM_BATCH_BYTES &&
+        batch.match?(/\A[a-zA-Z0-9_]+\z/)
+
+      raise InvalidComponentToken, "invalid actor component batch"
+    end
+    private_class_method :validate_batch!
+
     # @rbs (Array[untyped]) -> void
     def validate_dependencies!(dependencies)
       valid = dependencies.any? &&

data/lib/solid_objects/configuration.rb

@@ -17,6 +17,7 @@ module SolidObjects
     # @rbs @max_result_bytes: Integer
     # @rbs @max_attempts: Integer
     # @rbs @retry_delay: Proc
+    # @rbs @lock_retry_attempts: Integer
     # @rbs @process_heartbeat_interval: Float
     # @rbs @process_alive_threshold: Float
     # @rbs @shutdown_timeout: Float
@@ -57,6 +58,7 @@ module SolidObjects
       :max_result_bytes,
       :max_attempts,
       :retry_delay,
+      :lock_retry_attempts,
       :process_heartbeat_interval,
       :process_alive_threshold,
       :shutdown_timeout,
@@ -99,6 +101,7 @@ module SolidObjects
       @max_result_bytes = 1.megabyte
       @max_attempts = 5
       @retry_delay = ->(attempt) { [ 2**(attempt - 1), 60 ].min.to_f }
+      @lock_retry_attempts = 10
       @process_heartbeat_interval = 15.0
       @process_alive_threshold = 60.0
       @shutdown_timeout = 15.0

data/lib/solid_objects/database_adapters/sqlite.rb

@@ -4,6 +4,7 @@ module SolidObjects
   module DatabaseAdapters
     class Sqlite < DatabaseAdapter
       LOCK_RETRY_INTERVAL = 0.001
+      MAXIMUM_BUSY_RETRY_INTERVAL = 0.25
       LOCK_RETRY_MUTEX = Thread::Mutex.new
       LOCK_RETRY_CONDITION = Thread::ConditionVariable.new
 
@@ -14,9 +15,28 @@ module SolidObjects
 
       # @rbs () { () -> untyped } -> untyped
       def transaction(&block)
-        return super unless SyncDeadline.active?
+        return with_lock_retry { super } if SyncDeadline.active?
 
-        with_lock_retry { super }
+        with_busy_retry { super }
+      end
+
+      # A write outside a synchronous deadline has no Ruby-level budget, so it
+      # depends entirely on SQLite's busy handler. Concurrent writers can
+      # exhaust that, which surfaces as a lock error the caller cannot retry.
+      # @rbs () { () -> untyped } -> untyped
+      def with_busy_retry
+        attempts = 0
+        begin
+          yield
+        rescue => error
+          raise unless busy_error?(error)
+
+          attempts += 1
+          raise if attempts > SolidObjects.configuration.lock_retry_attempts
+
+          wait_before_busy_retry(attempts)
+          retry
+        end
       end
 
       # @rbs () { () -> untyped } -> untyped
@@ -116,6 +136,11 @@ module SolidObjects
       def deadline_error?(error)
         return false unless SyncDeadline.active?
 
+        busy_error?(error)
+      end
+
+      # @rbs (Exception) -> bool
+      def busy_error?(error)
         cause = error
         while cause
           return true if cause.class.name.match?(/BusyException|BusyError/)
@@ -125,6 +150,16 @@ module SolidObjects
         false
       end
 
+      # @rbs (Integer) -> void
+      def wait_before_busy_retry(attempts)
+        LOCK_RETRY_MUTEX.synchronize do
+          LOCK_RETRY_CONDITION.wait(
+            LOCK_RETRY_MUTEX,
+            [ LOCK_RETRY_INTERVAL * (2**(attempts - 1)), MAXIMUM_BUSY_RETRY_INTERVAL ].min
+          )
+        end
+      end
+
       # @rbs () -> void
       def wait_before_retry
         LOCK_RETRY_MUTEX.synchronize do

data/lib/solid_objects/turbo_stream_renderer.rb

@@ -54,6 +54,18 @@ module SolidObjects
       %(<turbo-stream action="replace" target="#{target}"><template><turbo-frame id="#{target}" src="#{source}" data-solid-objects-revision="#{revision_value}" data-solid-objects-refresh="replace"></turbo-frame></template></turbo-stream>)
     end
 
+    # @rbs (Array[ComponentRegistration], Integer, Integer) -> String
+    def batch_refresh(registrations, instance_id, revision)
+      first = registrations.first
+      scope = DomIdentity.scope(first.reference)
+      batch = ERB::Util.html_escape(first.batch)
+      source = ERB::Util.html_escape(
+        first.batch_refresh_url(registrations, instance_id, revision)
+      )
+      targets = ERB::Util.html_escape(registrations.map(&:dom_id).join(" "))
+      %(<turbo-stream action="append" target="#{scope}"><template><solid-objects-batch-refresh data-batch="#{batch}" data-revision="#{instance_id}:#{revision}" data-targets="#{targets}" data-source="#{source}"></solid-objects-batch-refresh></template></turbo-stream>)
+    end
+
     # @rbs (Hash[String, untyped]) -> String
     def state_payload(payload)
       reference = Reference.new(

data/lib/solid_objects/version.rb

@@ -1,5 +1,5 @@
 # rbs_inline: enabled
 
 module SolidObjects
-  VERSION = "0.6.0"
+  VERSION = "0.7.1"
 end

data/sig/generated/controllers/solid_objects/components_controller.rbs

@@ -2,11 +2,22 @@
 
 module SolidObjects
   class ComponentsController < ActionController::Base
+    BATCH_LIMIT: ::Integer
+
     # @rbs () -> void
     def show: () -> void
 
+    # @rbs () -> void
+    def batch: () -> void
+
     private
 
+    # @rbs (Hash[Symbol, untyped]) -> void
+    def refresh_batch: (Hash[Symbol, untyped]) -> void
+
+    # @rbs (Array[ComponentRegistration]) -> void
+    def validate_single_batch!: (Array[ComponentRegistration]) -> void
+
     # @rbs (Hash[Symbol, untyped]) -> void
     def refresh: (Hash[Symbol, untyped]) -> void
 

data/sig/generated/lib/solid_objects/actor_view.rbs

@@ -22,8 +22,8 @@ module SolidObjects
     # @rbs (Symbol | String) -> untyped
     def value: (Symbol | String) -> untyped
 
-    # @rbs (Symbol | String, ?observes: Symbol | String | Array[Symbol | String]?, ?partial: String?, ?key: untyped, ?locals: Hash[untyped, untyped], ?refresh: String | Symbol) -> untyped
-    def component: (Symbol | String, ?observes: Symbol | String | Array[Symbol | String]?, ?partial: String?, ?key: untyped, ?locals: Hash[untyped, untyped], ?refresh: String | Symbol) -> untyped
+    # @rbs (Symbol | String, ?observes: Symbol | String | Array[Symbol | String]?, ?partial: String?, ?key: untyped, ?locals: Hash[untyped, untyped], ?refresh: String | Symbol, ?batch: untyped) -> untyped
+    def component: (Symbol | String, ?observes: Symbol | String | Array[Symbol | String]?, ?partial: String?, ?key: untyped, ?locals: Hash[untyped, untyped], ?refresh: String | Symbol, ?batch: untyped) -> untyped
 
     # @rbs () -> Array[String]
     def component_tokens: () -> Array[String]
@@ -31,6 +31,9 @@ module SolidObjects
     # @rbs () -> Array[String]
     def scalar_observable_names: () -> Array[String]
 
+    # @rbs () -> bool
+    def batched_components?: () -> bool
+
     # @rbs () -> bool
     def morph_components?: () -> bool
 
@@ -79,8 +82,8 @@ module SolidObjects
     # @rbs (ComponentRegistration) -> void
     def ensure_unique_component!: (ComponentRegistration) -> void
 
-    # @rbs (key: untyped, locals: Hash[untyped, untyped], refresh: String | Symbol) -> void
-    def validate_static_options!: (key: untyped, locals: Hash[untyped, untyped], refresh: String | Symbol) -> void
+    # @rbs (key: untyped, locals: Hash[untyped, untyped], refresh: String | Symbol, batch: untyped) -> void
+    def validate_static_options!: (key: untyped, locals: Hash[untyped, untyped], refresh: String | Symbol, batch: untyped) -> void
 
     # @rbs () -> Proc | ComponentPathResolver
     def component_path_resolver: () -> Proc

data/sig/generated/lib/solid_objects/component_registration.rbs

@@ -16,6 +16,8 @@ module SolidObjects
 
     @dependencies: Array[String]
 
+    @batch: String?
+
     @component_key: String | Integer?
 
     @component_name: String
@@ -28,6 +30,8 @@ module SolidObjects
 
     attr_reader component_key: untyped
 
+    attr_reader batch: untyped
+
     attr_reader dependencies: untyped
 
     attr_reader locals: untyped
@@ -42,11 +46,11 @@ module SolidObjects
 
     attr_reader token: untyped
 
-    # @rbs (reference: Reference, component_name: String, component_key: String | Integer?, dependencies: Array[String], locals: Hash[String, untyped], refresh_method: String, instance_id: Integer, revision: Integer, refresh_path: String, token: String) -> void
-    def initialize: (reference: Reference, component_name: String, component_key: String | Integer?, dependencies: Array[String], locals: Hash[String, untyped], refresh_method: String, instance_id: Integer, revision: Integer, refresh_path: String, token: String) -> void
+    # @rbs (reference: Reference, component_name: String, component_key: String | Integer?, dependencies: Array[String], locals: Hash[String, untyped], refresh_method: String, instance_id: Integer, revision: Integer, refresh_path: String, token: String, ?batch: String?) -> void
+    def initialize: (reference: Reference, component_name: String, component_key: String | Integer?, dependencies: Array[String], locals: Hash[String, untyped], refresh_method: String, instance_id: Integer, revision: Integer, refresh_path: String, token: String, ?batch: String?) -> void
 
-    # @rbs (reference: Reference, component_name: String, component_key: untyped, dependencies: Array[String], locals: Hash[untyped, untyped], refresh_method: String | Symbol, snapshot: ActorSnapshot, refresh_path: String) -> ComponentRegistration
-    def self.issue: (reference: Reference, component_name: String, component_key: untyped, dependencies: Array[String], locals: Hash[untyped, untyped], refresh_method: String | Symbol, snapshot: ActorSnapshot, refresh_path: String) -> ComponentRegistration
+    # @rbs (reference: Reference, component_name: String, component_key: untyped, dependencies: Array[String], locals: Hash[untyped, untyped], refresh_method: String | Symbol, snapshot: ActorSnapshot, refresh_path: String, ?batch: String?) -> ComponentRegistration
+    def self.issue: (reference: Reference, component_name: String, component_key: untyped, dependencies: Array[String], locals: Hash[untyped, untyped], refresh_method: String | Symbol, snapshot: ActorSnapshot, refresh_path: String, ?batch: String?) -> ComponentRegistration
 
     # @rbs (String) -> ComponentRegistration
     def self.from_token: (String) -> ComponentRegistration
@@ -69,6 +73,9 @@ module SolidObjects
     # @rbs () -> Hash[String, untyped]
     def authorization_arguments: () -> Hash[String, untyped]
 
+    # @rbs (Array[ComponentRegistration], Integer, Integer) -> String
+    def batch_refresh_url: (Array[ComponentRegistration], Integer, Integer) -> String
+
     # @rbs (Integer, Integer) -> String
     def refresh_url: (Integer, Integer) -> String
   end

data/sig/generated/lib/solid_objects/component_subscriptions.rbs

@@ -31,6 +31,9 @@ module SolidObjects
 
     attr_reader revisions: untyped
 
+    # @rbs (ComponentRegistration, Integer, Integer) -> void
+    def record_revision: (ComponentRegistration, Integer, Integer) -> void
+
     # @rbs (ComponentRegistration, Integer, Integer) -> String
     def refresh: (ComponentRegistration, Integer, Integer) -> String
 

data/sig/generated/lib/solid_objects/component_token.rbs

@@ -12,14 +12,16 @@ module SolidObjects
 
     MAXIMUM_COMPONENT_KEY_BYTES: ::Integer
 
+    MAXIMUM_BATCH_BYTES: ::Integer
+
     REFRESH_METHODS: untyped
 
     RESERVED_LOCALS: untyped
 
     RUBY_KEYWORDS: untyped
 
-    # @rbs (reference: Reference, component_name: String, dependencies: Array[String], instance_id: Integer, revision: Integer, refresh_path: String, ?component_key: untyped, ?locals: Hash[untyped, untyped], ?refresh_method: String | Symbol) -> String
-    def self?.generate: (reference: Reference, component_name: String, dependencies: Array[String], instance_id: Integer, revision: Integer, refresh_path: String, ?component_key: untyped, ?locals: Hash[untyped, untyped], ?refresh_method: String | Symbol) -> String
+    # @rbs (reference: Reference, component_name: String, dependencies: Array[String], instance_id: Integer, revision: Integer, refresh_path: String, ?component_key: untyped, ?locals: Hash[untyped, untyped], ?refresh_method: String | Symbol, ?batch: untyped) -> String
+    def self?.generate: (reference: Reference, component_name: String, dependencies: Array[String], instance_id: Integer, revision: Integer, refresh_path: String, ?component_key: untyped, ?locals: Hash[untyped, untyped], ?refresh_method: String | Symbol, ?batch: untyped) -> String
 
     # @rbs (String) -> Hash[String, untyped]
     def self?.verify: (String) -> Hash[String, untyped]
@@ -36,6 +38,9 @@ module SolidObjects
     # @rbs (untyped) -> void
     def self?.validate_component_key!: (untyped) -> void
 
+    # @rbs (untyped) -> void
+    def self?.validate_batch!: (untyped) -> void
+
     # @rbs (Array[untyped]) -> void
     def self?.validate_dependencies!: (Array[untyped]) -> void
 

data/sig/generated/lib/solid_objects/configuration.rbs

@@ -2,7 +2,7 @@
 
 module SolidObjects
   class Configuration
-    @table_name_prefix: String
+    @process_alive_threshold: Float
 
     @shutdown_timeout: Float
 
@@ -48,6 +48,8 @@ module SolidObjects
 
     @authorize_administration: Proc
 
+    @table_name_prefix: String
+
     @polling_interval: Float
 
     @sync_polling_interval: Float
@@ -76,9 +78,9 @@ module SolidObjects
 
     @retry_delay: Proc
 
-    @process_heartbeat_interval: Float
+    @lock_retry_attempts: Integer
 
-    @process_alive_threshold: Float
+    @process_heartbeat_interval: Float
 
     attr_accessor table_name_prefix: untyped
 
@@ -110,6 +112,8 @@ module SolidObjects
 
     attr_accessor retry_delay: untyped
 
+    attr_accessor lock_retry_attempts: untyped
+
     attr_accessor process_heartbeat_interval: untyped
 
     attr_accessor process_alive_threshold: untyped

data/sig/generated/lib/solid_objects/database_adapters/sqlite.rbs

@@ -5,6 +5,8 @@ module SolidObjects
     class Sqlite < DatabaseAdapter
       LOCK_RETRY_INTERVAL: ::Float
 
+      MAXIMUM_BUSY_RETRY_INTERVAL: ::Float
+
       LOCK_RETRY_MUTEX: untyped
 
       LOCK_RETRY_CONDITION: untyped
@@ -15,6 +17,12 @@ module SolidObjects
       # @rbs () { () -> untyped } -> untyped
       def transaction: () { () -> untyped } -> untyped
 
+      # A write outside a synchronous deadline has no Ruby-level budget, so it
+      # depends entirely on SQLite's busy handler. Concurrent writers can
+      # exhaust that, which surfaces as a lock error the caller cannot retry.
+      # @rbs () { () -> untyped } -> untyped
+      def with_busy_retry: () { () -> untyped } -> untyped
+
       # @rbs () { () -> untyped } -> untyped
       def with_lock_retry: () { () -> untyped } -> untyped
 
@@ -38,6 +46,12 @@ module SolidObjects
       # @rbs (Exception) -> bool
       def deadline_error?: (Exception) -> bool
 
+      # @rbs (Exception) -> bool
+      def busy_error?: (Exception) -> bool
+
+      # @rbs (Integer) -> void
+      def wait_before_busy_retry: (Integer) -> void
+
       # @rbs () -> void
       def wait_before_retry: () -> void
     end

data/sig/generated/lib/solid_objects/turbo_stream_renderer.rbs

@@ -15,6 +15,9 @@ module SolidObjects
     # @rbs (ComponentRegistration, Integer, Integer) -> String
     def self?.component_refresh: (ComponentRegistration, Integer, Integer) -> String
 
+    # @rbs (Array[ComponentRegistration], Integer, Integer) -> String
+    def self?.batch_refresh: (Array[ComponentRegistration], Integer, Integer) -> String
+
     # @rbs (Hash[String, untyped]) -> String
     def self?.state_payload: (Hash[String, untyped]) -> String
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: solid_objects
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.1
 platform: ruby
 authors:
 - Lucas Carlson
@@ -262,6 +262,7 @@ files:
 - MIT-LICENSE
 - README.md
 - Rakefile
+- app/assets/javascripts/solid_objects/component_batch_refresh.js
 - app/assets/javascripts/solid_objects/component_refresh.js
 - app/assets/javascripts/solid_objects/state_payload.js
 - app/controllers/solid_objects/application_controller.rb
@@ -286,6 +287,7 @@ files:
 - benchmark/adoption_latency.rb
 - benchmark/claim.rb
 - benchmark/cold_actors.rb
+- benchmark/component_delivery.rb
 - benchmark/concurrent_actors.rb
 - benchmark/enqueue.rb
 - benchmark/hot_actor.rb