solid_objects 0.7.0 → 0.7.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0614e42e260b81ab323d292435cd4f518a4f0b26a21865e5f63c9768db362231
-  data.tar.gz: a8c7d4bc22e431b89ab07058c0ad35ca82a44eef08d30b0a547b28c0dd76f82e
+  metadata.gz: 3c9697331316791269c98ec881f02a59e7556c2ab2abf98c3feb662e5f8cf742
+  data.tar.gz: 12b0390bfcceca1362e7e1779bcb1562ea2e640259ca9ccefac9835b0b2d9a2e
 SHA512:
-  metadata.gz: 07caec47a1c3452bb3f3b6fc6f950f60f9c68277ebb558630d112fcc7bfb9e3591f893e8bdaefea4329680cde6d6a86c36c0d9b6531d6ac889507abfda939920
-  data.tar.gz: 23d756629a2b8212d06077569b9d0c35552c6ee416c95851ee78357ecfe1abf672e0a973d9715f0b66942ecebf8e1c007f21d33bde3bfb7e79af30f323a809bf
+  metadata.gz: 1acdc877187c455dee2843527e8826a719ab66c2f3917233eb1d565c19b6662a9fd6d319213f3340ada04e60f2d299dff8ad675de8762f65e336630a40b7ef79
+  data.tar.gz: f69a34ac8c724164ec597ad3b78637d8537c1d76a527998aa50fa9f7bd7c3327244449be9555a2214c2a9ae7f019e119b5f35c58ad2d28528ea824aad0a0f538

data/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.7.2 - 2026-08-09
+
+- Render batched component partials as HTML regardless of the request format.
+  The batch endpoint is requested with a JSON `Accept` header, so Rails looked
+  for JSON templates, raised `ActionView::MissingTemplate`, and the batch
+  returned 404 for applications whose components are ordinary
+  `.html.erb` partials. The outer response is still JSON. Single-component
+  refresh was never affected and is unchanged.
+- Pass `registrations:` to `component_authorization_context`: one registration
+  for a single refresh, all of them for a batch, so applications no longer have
+  to inspect `params[:tokens]`. Callbacks accepting only `controller:` keep
+  working unchanged.
+
+## 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

data/app/controllers/solid_objects/components_controller.rb

@@ -43,10 +43,7 @@ module SolidObjects
         return head :conflict
       end
 
-      authorization_context = SolidObjects
-        .configuration
-        .component_authorization_context
-        .call(controller: self)
+      authorization_context = component_authorization_context(registrations)
       frames = registrations.map do |registration|
         rendered = ComponentRenderer.new(
           snapshot:,
@@ -112,10 +109,7 @@ module SolidObjects
         return head :conflict
       end
 
-      authorization_context = SolidObjects
-        .configuration
-        .component_authorization_context
-        .call(controller: self)
+      authorization_context = component_authorization_context([ registration ])
       rendered = ComponentRenderer.new(
         snapshot:,
         registration:,
@@ -138,6 +132,34 @@ module SolidObjects
       head :bad_request
     end
 
+    # Callbacks written before batching accept only `controller:`. Those keep
+    # working; a callback that also accepts `registrations:` receives one
+    # registration for a single refresh and all of them for a batch.
+    # @rbs (Array[ComponentRegistration]) -> untyped
+    def component_authorization_context(registrations)
+      callable = SolidObjects.configuration.component_authorization_context
+      return callable.call(controller: self) unless accepts_registrations?(callable)
+
+      callable.call(controller: self, registrations:)
+    end
+
+    # A lambda answers `parameters` directly; a callable object answers it
+    # through its `call` method.
+    # @rbs (untyped) -> bool
+    def accepts_registrations?(callable)
+      callable_parameters(callable).any? do |type, name|
+        type == :keyrest || (%i[key keyreq].include?(type) && name == :registrations)
+      end
+    end
+
+    # @rbs (untyped) -> Array[[ Symbol, Symbol ]]
+    def callable_parameters(callable)
+      return callable.parameters if callable.respond_to?(:parameters)
+      return callable.method(:call).parameters if callable.respond_to?(:call)
+
+      []
+    end
+
     # @rbs (ComponentRegistration) -> Hash[Symbol, untyped]
     def registration_payload(registration)
       {

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

@@ -290,6 +290,20 @@ commonly resolve it to `Current.user`:
 configuration.component_authorization_context = ->(controller:) { Current.user }
 ```
 
+A callback may also accept `registrations:`, which receives one registration for
+a single component refresh and every registration in the group for a batch
+refresh. This avoids decoding `params[:tokens]` by hand when a policy depends on
+which components were requested:
+
+```ruby
+configuration.component_authorization_context = lambda do |controller:, registrations:|
+  Current.user if registrations.all? { |registration| registration.component_key == controller.session[:seat] }
+end
+```
+
+Callbacks that accept only `controller:` continue to work; the extra keyword is
+passed only to callables that declare it.
+
 The three contexts are intentionally different:
 
 | Boundary | Authorization context |

data/docs/roadmap.md

@@ -17,18 +17,26 @@
 - One-shot and recurring reminders with `:latest` or `:all` catch-up
 - Durable observable invalidations, scalar Turbo replacement, keyed ERB
   components, signed component locals, and authorized replace or morph refresh
+- Batched component refreshes: components sharing a signed `batch:` collapse to
+  one browser request per revision, served as HTML frames in a JSON envelope
+- Personalized state payload broadcasts computed per subscriber under that
+  subscriber's authorization context, fenced by actor revision
 - Reconciliation read APIs
 - Installation doctor, authorization reference, fit guide, and legacy-state
   migration cookbook
 - Handler Active Record write isolation, same-database commit actions, ambient
-  transaction rejection, adapter lock/query deadlines, structured sync timeout
-  diagnostics, and result recovery
+  transaction rejection, adapter lock/query deadlines, bounded SQLite lock
+  retries outside those deadlines, structured sync timeout diagnostics, and
+  result recovery
 - Bounded message/process pruning, actor-type opt-in instance expiration,
   graceful caller shutdown, committed state snapshots, and an opt-in Minitest
   helper
 - SQLite, PostgreSQL, and MySQL integration suites
 - Inline RBS generation/validation, Steep, Standard Ruby, Solid Queue's exact
   RuboCop policy, and a warning-free Brakeman scan
+- A JavaScript suite covering the state payload and batched refresh browser
+  modules, run in CI with Node's test runner and jsdom, with every GitHub
+  Actions reference pinned to a commit SHA
 
 ## Partially implemented
 
@@ -36,14 +44,24 @@
   role or run periodic maintenance automatically.
 - Wake-up strategy: in-process signaling plus durable polling and injection are
   implemented; PostgreSQL `LISTEN/NOTIFY` and optional Redis adapters are not.
+  Signaling cannot cross process boundaries, so a commit in a web process does
+  not wake a broadcast executor in a worker process; that delivery waits up to
+  `polling_interval`, 100 ms by default. This is the largest remaining term in
+  reactive update latency, and neither batching nor state payloads reduce it.
 - Realtime: scalar and dependency-driven keyed ERB component replacement or
   morphing, personalized refresh authorization, revision fencing, coalescing,
-  and reconnect convergence are implemented; application-directed Turbo
-  append intents are not.
+  reconnect convergence, batched refreshes, and personalized state payloads are
+  implemented; application-directed Turbo append intents are not. Batch
+  coalescing happens in the browser rather than the broadcast executor, so one
+  commit still sends one Action Cable message per changed observable even
+  though it costs one browser request.
 - Backpressure: mailbox/payload/state/result caps and fair yields exist;
   distributed per-actor rate limits and global admission control do not.
 - Administration: actor and dead-letter views plus policy hooks exist; richer
   filtering, audit records, and bulk-safe tools do not.
+- Browser module coverage: the state payload and batched refresh modules have
+  JavaScript tests; `component_refresh.js`, which drives individual morph
+  refreshes, does not.
 - Outboxes use portable status rows with polling indexes; future versions may
   introduce narrow ready/claimed membership tables for very large outboxes.
 
@@ -51,7 +69,8 @@
 
 1. Add automatic supervisor role replacement and periodic dead-process cleanup.
 2. Add PostgreSQL notification and optional Redis wake-up adapters with latency
-   benchmarks and polling-race tests.
+   benchmarks and polling-race tests, removing the cross-process polling delay
+   rather than shrinking it with a smaller `polling_interval`.
 3. Add result lookup by request ID and broader deadlock retry classification.
 4. Add scheduled retention and stale-process maintenance.
 5. Add database/server-version checks and MySQL InnoDB verification at boot.
@@ -61,7 +80,9 @@
 8. Expand security scanning and run compatibility CI across supported Rails and
    Ruby versions.
 9. Benchmark all workloads under documented hardware/database settings and
-   publish adapter-specific adoption measurements.
+   publish adapter-specific adoption measurements. Throughput, synchronous
+   latency, query counts, and the three reactive delivery paths are measured on
+   SQLite; adapter-specific and end-to-end browser measurements are not.
 
 No production-ready claim should be made until these hardening milestones have
 operational soak evidence.

data/lib/solid_objects/component_renderer.rb

@@ -32,6 +32,7 @@ module SolidObjects
       )
       view_context.render(
         partial: default_partial,
+        formats: [ :html ],
         locals: registration.locals.transform_keys(&:to_sym).merge(
           actor:,
           authorization_context:,

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/version.rb

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

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

@@ -21,6 +21,20 @@ module SolidObjects
     # @rbs (Hash[Symbol, untyped]) -> void
     def refresh: (Hash[Symbol, untyped]) -> void
 
+    # Callbacks written before batching accept only `controller:`. Those keep
+    # working; a callback that also accepts `registrations:` receives one
+    # registration for a single refresh and all of them for a batch.
+    # @rbs (Array[ComponentRegistration]) -> untyped
+    def component_authorization_context: (Array[ComponentRegistration]) -> untyped
+
+    # A lambda answers `parameters` directly; a callable object answers it
+    # through its `call` method.
+    # @rbs (untyped) -> bool
+    def accepts_registrations?: (untyped) -> bool
+
+    # @rbs (untyped) -> Array[[ Symbol, Symbol ]]
+    def callable_parameters: (untyped) -> Array[[ Symbol, Symbol ]]
+
     # @rbs (ComponentRegistration) -> Hash[Symbol, untyped]
     def registration_payload: (ComponentRegistration) -> Hash[Symbol, untyped]
 

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: solid_objects
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.7.2
 platform: ruby
 authors:
 - Lucas Carlson
@@ -287,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