solid_objects 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b7fee6db10af36996dbe9c8484fab405b53e2463a3fd7d2f7414310fedab68d5
-  data.tar.gz: 8b71bb8fbf0dc0359ce8a00097428dbbcd189e4d2b4071ba0339b9c3ec1cd933
+  metadata.gz: 935a2d2bb12fbc5b39121fe44004d0cc0671c3bef82012cf9b024089c3546ac9
+  data.tar.gz: 15de97ea8547bfb552ae848b2ae523fdd6c48a557313ba3fd87d931ee770f9b1
 SHA512:
-  metadata.gz: 62f2ce7ecfa4899f82af3682c5a8fb97d7005e6ba9152a8a63433b2ec345d2edc3d795c29a7f6de24d25f275afd4857986ed34302359d0f3aab018f936656acd
-  data.tar.gz: 2114e1d8b7757bf598562fba6e1b8ecafeea852d6925a5161f74b1dcab6dab9b5750ca71327b0cfa23b927869cbeee348f1bd6d03cbfc5d964d2bfd53a625435
+  metadata.gz: 6633846db212684a9e6d687f76e559cd51448171bd9e067534024e9a067534f1ff7eab223e3c1ab80b7a02765b909a324f2dbb9b1f527e5846d933de5b3639c7
+  data.tar.gz: ce930198b48379439c4947dd41ea5d3a0577ad8ce49eb1513715075ccf23c03b23237bcee77f06a898ea5460b83e3bf6b0c8a54f7b9c16e03c159c2572a03306

data/CHANGELOG.md

@@ -1,5 +1,65 @@
 # Changelog
 
+## 0.10.0 - 2026-08-10
+
+- Report a denied CLI command as a policy decision rather than a crash.
+  Administration denies by default, so an unconfigured host met a thirty-line
+  Ruby backtrace on its first `solid_objects` command. The executable now
+  prints the refusal and the setting that grants access, and exits 1.
+- Measure the query count for a synchronous call. `benchmark/query_count.rb`
+  only measured a worker turn, so the documented synchronous number had no
+  script behind it. It reports three now: a message turn costs 26 queries
+  rather than the documented 29, the caller of a synchronous call costs 49, and
+  a synchronous call in total costs 75, being a caller plus the turn it waits
+  on. Counting is scoped to the measuring thread, since a worker loop polls
+  whether or not a call is in flight and a process-wide count folds those polls
+  into the result.
+
+- Run payload broadcast blocks against the actor instance, like every other
+  block in the actor DSL. `self` was the actor class, so an actor instance
+  method called from a payload block raised
+  `NoMethodError: undefined method 'x' for class PlaymatRoom`. Blocks keep
+  receiving the actor and the authorization context as arguments, so the
+  documented signature is unaffected. A block that relied on the class receiver
+  now raises `InvalidPayloadBroadcast` naming the method and the change instead
+  of an unexplained `NameError`.
+- Add `payload_authorization_context`, the payload counterpart to
+  `component_authorization_context`. Payloads are computed inside the channel,
+  so without a resolver the payload block and its `authorize_query` call
+  received the raw Action Cable connection while a controller render passed an
+  application object, and the authorization hook had to tell them apart. The
+  resolver may also accept `payload_name:`. It defaults to returning the
+  connection unchanged.
+- Confine a failing payload to itself. A raising payload block propagated out of
+  the channel: on subscribe it rejected the subscription, and on a broadcast it
+  abandoned the remaining payload names, which showed up in the browser only as
+  reactive updates that stopped arriving. A failure is now reported as
+  `solid_objects.payload_broadcast_failed` with the actor type, actor id,
+  payload name, and exception class, and delivery continues. The exception
+  message is deliberately excluded so subscriber state cannot leak into logs. A
+  revision with a failed payload does not advance the delivery watermark, so a
+  transient failure is retried on the next broadcast instead of being recorded
+  as delivered and deduplicated away.
+- Run retention on the supervisor rather than leaving it configured but
+  unscheduled. Every actor call writes a durable message row, so a policy that
+  nothing invokes let history grow without bound until an application scheduled
+  its own job. `retention_interval` defaults to one hour, and zero disables it.
+  Retention runs on its own thread, so a slow pass cannot delay replacing a
+  crashed role, and a failed pass retries at monitor cadence with a doubling
+  backoff rather than deferring for the whole interval.
+- Batch component refreshes on reconnect. A reconnecting subscription refreshed
+  every stale component individually, ignoring the batches those components
+  declared, so a page with twenty batched components issued twenty requests
+  instead of one. That happens at the worst moment: a server restart reconnects
+  every client at once. Reconnect now shares the batching the live invalidation
+  path uses.
+- Cover the reconnect burst in the browser suite: convergence of batched and
+  unbatched components, an inert replay of an already-applied revision,
+  cancellation of the request left in flight by the drop, incarnation ordering
+  after a destroy and recreate, and payload delivery exactly once per revision.
+- Add Ruby 4.0 to the compatibility matrix, which now covers Ruby 3.3, 3.4, and
+  4.0 against Rails 8.0 and 8.1.
+
 ## 0.9.0 - 2026-08-10
 
 - Add a browser test suite running the refresh modules against real Chromium and

data/app/controllers/solid_objects/components_controller.rb

@@ -138,26 +138,11 @@ module SolidObjects
     # @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)
+      unless CallableKeywords.accepts?(callable, :registrations)
+        return callable.call(controller: self)
       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)
 
-      []
+      callable.call(controller: self, registrations:)
     end
 
     # @rbs (ComponentRegistration) -> Hash[Symbol, untyped]

data/benchmark/support.rb

@@ -291,24 +291,66 @@ module SolidObjectsBenchmark
 
     # @rbs () -> void
     def query_count
+      turn = message_turn_query_count
+      caller_queries = synchronous_caller_query_count
+      puts "database queries: #{turn} for 1 message turn"
+      puts "database queries: #{caller_queries} for the caller of 1 synchronous call"
+      puts "database queries: #{caller_queries + turn} for 1 synchronous call, caller plus the turn it waits on"
+    end
+
+    private
+
+    # Runs the turn on the measuring thread, so nothing else can contribute.
+    # @rbs () -> Integer
+    def message_turn_query_count
       CounterActor.ref("queries").async(:increment)
       worker = SolidObjects::Worker.new
+      count_queries { worker.run_once }
+    ensure
+      worker&.stop
+    end
+
+    # A synchronous call also registers or heartbeats the caller process,
+    # claims the activation, and observes the result, so the caller costs more
+    # than the turn it waits on. Only the caller thread is counted; the worker
+    # runs on its own thread and its turn is measured separately, because a
+    # worker loop also polls and those polls belong to no particular call. The
+    # first call is discarded because it pays for activation and caller
+    # registration that a steady-state call does not.
+    # @rbs () -> Integer
+    def synchronous_caller_query_count
+      reference = CounterActor.ref("sync-queries")
+      worker = SolidObjects::Worker.new
+      runner = Thread.new { worker.run }
+      reference.sync(:increment)
+      count_queries { reference.sync(:increment) }
+    ensure
+      worker&.request_shutdown
+      runner&.join(5)
+      worker&.stop
+    end
+
+    # Subscriptions are process-wide and notifications run on the thread that
+    # issued the query, so counting is scoped to the measuring thread. Without
+    # that, a worker polling in the background inflates the count by however
+    # many times it happened to poll during the window.
+    # @rbs () { () -> untyped } -> Integer
+    def count_queries
+      measuring = Thread.current
       queries = 0
       subscriber = ActiveSupport::Notifications.subscribe("sql.active_record") do |event|
+        next unless Thread.current.equal?(measuring)
         next if %w[SCHEMA TRANSACTION].include?(event.payload[:name])
         next if event.payload[:cached]
 
         queries += 1
       end
-      processed = worker.run_once
-      puts "database queries: #{queries} for #{processed} message"
+      yield
+      queries
     ensure
       ActiveSupport::Notifications.unsubscribe(subscriber) if subscriber
-      worker&.stop
     end
 
-    private
-
     # @rbs (ComponentRegistration, untyped, ?snapshot: ActorSnapshot?) -> untyped
     def render_component(registration, view_context, snapshot: nil)
       SolidObjects::ComponentRenderer.new(

data/docs/benchmarks.md

@@ -40,8 +40,25 @@ scenario used four worker threads.
 | Process, four workers | 556.5 messages/s |
 | Synchronous latency | p50 1.8 ms, p95 25.6 ms, p99 156.2 ms |
 | Activation reuse | 98.0%, four activations for 200 messages |
-| Queries for one message turn | 29 |
-| Queries for one synchronous call | 49 |
+
+Query counts are a property of the code rather than the host, so they are
+tracked separately. Re-measured 2026-08-10 against 0.10.0 on SQLite with
+`bundle exec ruby benchmark/query_count.rb`, which is deterministic across runs:
+
+| Scenario | Queries |
+| --- | ---: |
+| One message turn | 26 |
+| The caller of one synchronous call | 49 |
+| One synchronous call, caller plus the turn it waits on | 75 |
+
+A worker turn fell from the 29 recorded earlier. The caller count is unchanged
+at 49, and the combined figure is new: a synchronous call is a caller and a
+worker turn, and only the sum says what the database actually serves.
+
+Counting is scoped to the measuring thread. A worker loop polls whether or not
+a call is in flight, so a process-wide count folds however many polls happened
+to land inside the window into the result. That is also why the caller and the
+turn are measured separately rather than by watching both threads at once.
 
 A synchronous call costs far more queries than a worker turn because the caller
 also registers or heartbeats its caller process, claims the activation, and

data/docs/realtime.md

@@ -237,9 +237,11 @@ 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:
+Declare the payload on the actor. The block runs against the actor instance,
+like every other block in the actor DSL, and receives the actor and the
+subscriber's authorization context as arguments. It runs **once per
+subscriber**, so two sessions watching the same actor never see each other's
+private state:
 
 ```ruby
 class PlaymatRoom < SolidObjects::Actor
@@ -259,6 +261,16 @@ class PlaymatRoom < SolidObjects::Actor
 end
 ```
 
+Because the block runs against the actor, an actor instance method is reachable
+without a receiver, so shared logic does not have to be duplicated into the
+block:
+
+```ruby
+broadcast_payload :playmat_state do |_room, authorization|
+  { "turn" => turn, "hand" => hand_for(authorization.session_id) }
+end
+```
+
 Subscribe the scope to it:
 
 ```erb
@@ -298,6 +310,26 @@ 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.
 
+A payload is one subscriber's view of one name, so a failure is confined to it.
+A raising block does not reject the subscription, stop the other payload names,
+or stop component refreshes on the same connection. The failure is reported as
+`solid_objects.payload_broadcast_failed` carrying the actor type, actor id,
+payload name, and exception class. The exception message is deliberately not
+included: a payload block reads subscriber state, so its message is the one
+place that state could leak into logs.
+
+A revision with a failed payload does not advance the delivery watermark, so a
+transient failure is retried on the next broadcast rather than being recorded as
+delivered. Retries are driven by broadcasts rather than a timer, so a payload
+that fails persistently retries once per actor mutation and reports each
+attempt. A repeating stream of `payload_broadcast_failed` for one `payload_name`
+therefore means a persistent fault in that block, not a one-off; a single event
+that does not recur was transient and has already been recovered.
+
+A payload the subscriber cannot query is skipped rather than served partially;
+that decision is stable, so it settles the revision and the skip is silent by
+design.
+
 ### mtg-playmat before and after
 
 Before, one mutation that touched three observables produced three refresh
@@ -350,13 +382,31 @@ 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:
+Payloads have the same resolver, because they are computed inside the channel
+rather than in a controller. Without one, a payload block and its
+`authorize_query` call receive the Cable connection while a controller render
+passes an application object, and the authorization hook has to tell them
+apart. Resolve both to the same type and it does not:
+
+```ruby
+configuration.component_authorization_context = ->(controller:) { controller.current_account }
+configuration.payload_authorization_context = ->(connection:) { connection.current_account }
+```
+
+The resolved value is what the payload block receives as its second argument and
+what `authorize_query` receives as `authorization_context`. A resolver may also
+accept `payload_name:` when the subject depends on which payload was requested.
+The default returns the connection unchanged, so an application that has not
+configured one is unaffected.
+
+The contexts are intentionally different:
 
 | Boundary | Authorization context |
 | --- | --- |
 | Initial Action View render | Explicit `authorization_context:` passed to `solid_object` |
 | Action Cable subscription | The authenticated Cable connection |
 | Component refresh | Value returned by `component_authorization_context` for the engine controller request |
+| State payload | Value returned by `payload_authorization_context` for the Cable connection |
 
 Do not substitute a signed token for any of them. Keys and locals are visible
 to the browser and signed for integrity, not encrypted or authorized. Never
@@ -393,6 +443,11 @@ ordered commits within one incarnation. Out-of-order invalidations at or below
 the last transmitted pair are ignored. The durable state row remains source of
 truth.
 
+Stale components that share a `batch:` are refreshed together, exactly as a
+live invalidation refreshes them, so reconnecting costs one request per batch
+rather than one per component. That matters most on a restart, when every
+client reconnects at once.
+
 The component endpoint rejects a requested revision newer than the committed
 snapshot. This is a final server-side guard; browser safety primarily comes
 from monotonic channel filtering plus replace-frame detachment or morph

data/docs/roadmap.md

@@ -13,14 +13,21 @@
 - At-least-once retries, terminal domain rejection, strict poison ordering,
   dead letters, and tail retry
 - Transactional effects with success/failure actor messages
-- Actor-to-actor asynchronous outbox delivery
+- Actor-to-actor asynchronous outbox delivery. Effects and broadcasts use
+  portable status rows with polling indexes and database check constraints on
+  status, which works on all three adapters; a future version may add narrow
+  ready/claimed membership tables for very large outboxes, as messages already
+  have
 - 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
+  subscriber's authorization context, fenced by actor revision, resolved through
+  `payload_authorization_context` so the block and `authorize_query` see the
+  same subject a controller render passes, and confined so one failing payload
+  cannot reject the subscription or stop its siblings
 - Reconciliation read APIs
 - Installation doctor, authorization reference, fit guide, and legacy-state
   migration cookbook
@@ -35,7 +42,9 @@
   graceful caller shutdown, committed state snapshots, and an opt-in Minitest
   helper
 - Supervisor role replacement: a role whose thread dies is restarted until
-  shutdown is requested, and dead process records are pruned on an interval
+  shutdown is requested, and dead process records plus expired message and
+  process history are pruned on their own intervals without an application
+  scheduling its own job
 - SQLite, PostgreSQL, and MySQL integration suites
 - Opt-in cross-process wake-up on PostgreSQL through `WakeUpAdapters.for`, with
   a listening connection per waiting thread and release on supervisor shutdown
@@ -44,51 +53,61 @@
   gem's dependencies
 - Inline RBS generation/validation, Steep, Standard Ruby, Solid Queue's exact
   RuboCop policy, and a warning-free Brakeman scan
-- Compatibility CI across the supported span: Ruby 3.3 and 3.4 against Rails 8.0
-  and 8.1, pinned through `RAILS_VERSION` so the advertised range is verified
-  rather than assumed
+- Compatibility CI across the supported span: Ruby 3.3, 3.4, and 4.0 against
+  Rails 8.0 and 8.1, pinned through `RAILS_VERSION` so the advertised range is
+  verified rather than assumed
 - A JavaScript suite covering every browser module, run in CI with Node's test
   runner and jsdom, plus a browser suite running the same modules against real
   Chromium and a real Turbo build, with every GitHub Actions reference pinned to
-  a commit SHA
+  a commit SHA. The browser suite covers the reconnect burst: convergence of
+  batched and unbatched components, an inert replay of an applied revision,
+  cancellation of the request left in flight by the drop, incarnation ordering
+  after a destroy and recreate, and payload delivery exactly once per revision
 
 ## Partially implemented
 
-- Wake-up strategy: in-process signaling, durable polling, injection, and an
-  opt-in PostgreSQL notification adapter are implemented; a Redis adapter is
-  not. In-process signaling cannot cross process boundaries, so without the
-  adapter a commit in a web process does not wake a broadcast executor in a
-  worker process and that delivery waits up to `polling_interval`, 100 ms by
-  default. `WakeUpAdapters.for` removes that delay on PostgreSQL, measured at
-  103.7 ms to 2.9 ms at p50. It is opt-in rather than automatic: it opens a
-  connection per waiting thread outside the pool, and `LISTEN` does not survive
-  a transaction-pooling proxy such as PgBouncer. MySQL has no notification
-  primitive, so MySQL applications keep polling unless they configure the Redis
-  adapter.
+- Wake-up strategy: in-process signaling, durable polling, injection, and
+  cross-process adapters for PostgreSQL and Redis are implemented and tested.
+  What is not done is making any of them automatic. In-process signaling cannot
+  cross process boundaries, so by default a commit in a web process does not
+  wake a broadcast executor in a worker process and that delivery waits up to
+  `polling_interval`, 100 ms. An adapter removes that floor, measured at 103.7 ms
+  to 2.9 ms at p50 on PostgreSQL and 103.8 ms to 5.7 ms on Redis, but each stays
+  opt-in for a reason: the PostgreSQL adapter opens a connection per waiting
+  thread outside the pool and `LISTEN` does not survive a transaction-pooling
+  proxy such as PgBouncer, and Redis is not a dependency of this gem.
+  `WakeUpAdapters.for` selects notifications on PostgreSQL and the in-process
+  default elsewhere; it never selects Redis. An application that configures
+  nothing keeps polling, and MySQL applications keep polling unless they
+  configure Redis explicitly.
 - Realtime: scalar and dependency-driven keyed ERB component replacement or
   morphing, personalized refresh authorization, revision fencing, coalescing,
   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.
+  though it costs one browser request. Reconnect convergence previously
+  bypassed batching entirely, issuing one request per stale component at the
+  moment a restart reconnects every client at once; it now shares the batching
+  the live invalidation path uses. Payload delivery over Action Cable was
+  untested end to end, which is how a raising payload block came to reject the
+  subscription; it is now covered and confined, and the payload authorization
+  context is resolved through `payload_authorization_context` rather than
+  handing the block a raw Cable connection.
 - 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.
-- Outboxes use portable status rows with polling indexes; future versions may
-  introduce narrow ready/claimed membership tables for very large outboxes.
 
 ## Next milestones
 
 1. Add result lookup by request ID and broader deadlock retry classification.
-2. Add scheduled retention and stale-process maintenance.
-3. Add Turbo append intents and expand reconnect coverage in a full browser.
-4. Add distributed rate limits, global admission hooks, and cache-capacity
+2. Add Turbo append intents.
+3. Add distributed rate limits, global admission hooks, and cache-capacity
    eviction.
-5. Expand security scanning. Compatibility CI across supported Rails and Ruby
-   versions is implemented; Ruby 4.0 is not yet in the matrix.
-6. Benchmark all workloads under documented hardware/database settings and
+4. Expand security scanning beyond the Brakeman scan, such as dependency
+   auditing and secret scanning.
+5. Benchmark all workloads under documented hardware/database settings and
    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.

data/exe/solid_objects

@@ -6,4 +6,15 @@ $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
 require "solid_objects"
 require "solid_objects/cli"
 
-SolidObjects::CLI.start(ARGV)
+begin
+  SolidObjects::CLI.start(ARGV)
+rescue SolidObjects::Unauthorized => error
+  # Authorization denies by default, so this is what an unconfigured host sees
+  # from its first command. A policy decision is not a crash, and printing a
+  # backtrace for one buries the single line that says how to grant access.
+  warn "solid_objects: #{error.message}"
+  warn "Set configuration.authorize_administration in your Solid Objects " \
+    "initializer to allow this command. See the commented example in " \
+    "config/initializers/solid_objects.rb."
+  exit 1
+end

data/lib/generators/solid_objects/templates/solid_objects.rb

@@ -52,6 +52,14 @@ SolidObjects.configure do |configuration|
   # Configure component_authorization_context to return the authenticated
   # principal used for reactive component refreshes.
 
+  # Payloads are delivered over Action Cable, so without a resolver the payload
+  # block and authorize_query receive the Cable connection while a controller
+  # render passes an application object. Resolve both to the same type and the
+  # authorization hook stops having to tell them apart:
+  #
+  # configuration.component_authorization_context = ->(controller:) { controller.current_account }
+  # configuration.payload_authorization_context = ->(connection:) { connection.current_account }
+
   # On hosts where shell access is already an authenticated administrative
   # boundary, this enables only gem commands that pass the CLI context:
   #

data/lib/solid_objects/actor_channel.rb

@@ -78,19 +78,59 @@ module SolidObjects
       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
+      # The watermark records what the subscriber has, so a revision with a
+      # failed payload must not advance it: dedup would skip every later
+      # attempt at that revision and the actor may not mutate again for a long
+      # time. Every name is still attempted before the decision is made.
+      attempts = payload_names.map { |name| transmit_state_payload(snapshot, name) }
+      return if attempts.any?(false)
+
       @payload_revision = [ snapshot.instance_id, snapshot.revision ]
     end
 
+    # A payload is one subscriber's view of one name. Letting it raise through
+    # here would reject the subscription or abandon the rest of a broadcast, so
+    # a failure is confined to the payload that caused it and reported. The
+    # exception message is deliberately not instrumented: a payload block reads
+    # actor state, so its message is the one place subscriber state could leak
+    # into logs.
+    #
+    # Returns whether this revision was settled for the name. An unauthorized
+    # payload is settled: the decision is stable, so retrying it would only
+    # re-deliver its authorized siblings.
+    # @rbs (ActorSnapshot, String) -> bool
+    def transmit_state_payload(snapshot, name)
+      payload = PayloadBroadcast.new(
+        snapshot:,
+        name:,
+        authorization_context: payload_authorization_context(name)
+      ).call
+      transmit TurboStreamRenderer.state_payload(payload)
+      true
+    rescue Unauthorized
+      true
+    rescue => error
+      SolidObjects.instrument(
+        :payload_broadcast_failed,
+        actor_type: reference.actor_type,
+        actor_id: reference.actor_id,
+        payload_name: name,
+        error_class: error.class.name
+      )
+      false
+    end
+
+    # Resolves the Cable connection to whatever the application uses as an
+    # authorization subject, so a payload block and `authorize_query` see the
+    # same object a controller render would pass.
+    # @rbs (String) -> untyped
+    def payload_authorization_context(name)
+      callable = SolidObjects.configuration.payload_authorization_context
+      return callable.call(connection:) unless CallableKeywords.accepts?(callable, :payload_name)
+
+      callable.call(connection:, payload_name: name)
+    end
+
     # @rbs (ActorSnapshot) -> bool
     def newer_payload_revision?(snapshot)
       current = @payload_revision

data/lib/solid_objects/callable_keywords.rb

@@ -0,0 +1,29 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  # Authorization context resolvers gained keywords after applications had
+  # already written them, so a resolver is called with what it declared it
+  # accepts rather than with everything the caller could offer.
+  module CallableKeywords
+    class << self
+      # @rbs (untyped, Symbol) -> bool
+      def accepts?(callable, keyword)
+        parameters(callable).any? do |type, name|
+          type == :keyrest || (%i[key keyreq].include?(type) && name == keyword)
+        end
+      end
+
+      private
+
+      # A lambda answers `parameters` directly; a callable object answers it
+      # through its `call` method.
+      # @rbs (untyped) -> Array[[ Symbol, Symbol ]]
+      def parameters(callable)
+        return callable.parameters if callable.respond_to?(:parameters)
+        return callable.method(:call).parameters if callable.respond_to?(:call)
+
+        []
+      end
+    end
+  end
+end

data/lib/solid_objects/component_subscriptions.rb

@@ -52,26 +52,19 @@ module SolidObjects
         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
+      refresh_streams(changed, instance_id, revision)
     end
 
     # @rbs (ActorSnapshot) -> Array[String]
     def reconnect_refreshes(snapshot)
-      registrations.filter_map do |registration|
-        next unless newer_revision?(
+      stale = registrations.select do |registration|
+        newer_revision?(
           registration.dom_id,
           snapshot.instance_id,
           snapshot.revision
         )
-
-        refresh(registration, snapshot.instance_id, snapshot.revision)
       end
+      refresh_streams(stale, snapshot.instance_id, snapshot.revision)
     end
 
     class << self
@@ -91,6 +84,21 @@ module SolidObjects
 
     attr_reader :registrations, :revisions
 
+    # Live invalidations and reconnect replays share this, so a reconnecting
+    # client pays the same number of requests a connected one does.
+    # @rbs (Array[ComponentRegistration], Integer, Integer) -> Array[String]
+    def refresh_streams(changed, instance_id, revision)
+      batched, individual = changed.partition(&:batch)
+      streams = individual.map do |registration|
+        refresh(registration, instance_id, revision)
+      end
+      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 (ComponentRegistration, Integer, Integer) -> void
     def record_revision(registration, instance_id, revision)
       revisions[registration.dom_id] = [ instance_id, revision ]

data/lib/solid_objects/configuration.rb

@@ -22,6 +22,7 @@ module SolidObjects
     # @rbs @process_alive_threshold: Float
     # @rbs @shutdown_timeout: Float
     # @rbs @supervisor_monitor_interval: Float
+    # @rbs @retention_interval: Float
     # @rbs @dead_process_cleanup_interval: Float
     # @rbs @message_retention: Numeric
     # @rbs @message_retention_by_actor_type: Hash[String, Numeric]
@@ -39,6 +40,7 @@ module SolidObjects
     # @rbs @wake_up_adapter: untyped
     # @rbs @component_path_resolver: Proc?
     # @rbs @component_authorization_context: Proc
+    # @rbs @payload_authorization_context: Proc
     # @rbs @authorize_message: Proc
     # @rbs @authorize_query: Proc
     # @rbs @authorize_destroy: Proc
@@ -65,6 +67,7 @@ module SolidObjects
       :process_alive_threshold,
       :shutdown_timeout,
       :supervisor_monitor_interval,
+      :retention_interval,
       :dead_process_cleanup_interval,
       :message_retention,
       :message_retention_by_actor_type,
@@ -82,6 +85,7 @@ module SolidObjects
       :wake_up_adapter,
       :component_path_resolver,
       :component_authorization_context,
+      :payload_authorization_context,
       :authorize_message,
       :authorize_query,
       :authorize_destroy,
@@ -108,6 +112,7 @@ module SolidObjects
       @lock_retry_attempts = 10
       @supervisor_monitor_interval = 1.0
       @dead_process_cleanup_interval = 60.0
+      @retention_interval = 3600.0
       @process_heartbeat_interval = 15.0
       @process_alive_threshold = 60.0
       @shutdown_timeout = 15.0
@@ -126,6 +131,7 @@ module SolidObjects
       @wake_up_adapter = nil
       @component_path_resolver = nil
       @component_authorization_context = ->(controller:) { controller }
+      @payload_authorization_context = ->(connection:) { connection }
       @logger = if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
         Rails.logger
       else
@@ -144,6 +150,10 @@ module SolidObjects
         raise ArgumentError, "table_name_prefix must contain lowercase letters, digits, and underscores"
       end
 
+      if retention_interval.negative?
+        raise ArgumentError, "retention_interval must not be negative"
+      end
+
       unless supervisor_monitor_interval.positive?
         raise ArgumentError, "supervisor_monitor_interval must be positive"
       end
@@ -176,6 +186,9 @@ module SolidObjects
       unless component_authorization_context.respond_to?(:call)
         raise ArgumentError, "component_authorization_context must respond to call"
       end
+      unless payload_authorization_context.respond_to?(:call)
+        raise ArgumentError, "payload_authorization_context must respond to call"
+      end
 
       self
     end

data/lib/solid_objects/payload_broadcast.rb

@@ -41,7 +41,7 @@ module SolidObjects
     # @rbs (ActorDefinition::Handler) -> untyped
     def rendered_payload(handler)
       payload = Serialization.dump(
-        handler.block.call(snapshot.actor, authorization_context),
+        evaluated_payload(handler),
         max_bytes: MAXIMUM_PAYLOAD_BYTES
       )
       return payload if payload.is_a?(Hash) || payload.is_a?(Array)
@@ -50,6 +50,34 @@ module SolidObjects
         "payload broadcast #{name.inspect} must return a JSON object or array"
     end
 
+    # The block runs against the actor instance, like every other block in the
+    # actor DSL, and still receives the actor and the resolved authorization
+    # context as arguments, so blocks written to the documented signature are
+    # unaffected.
+    # @rbs (ActorDefinition::Handler) -> untyped
+    def evaluated_payload(handler)
+      actor = snapshot.actor
+      actor.instance_exec(actor, authorization_context, &handler.block)
+    rescue NameError => error
+      raise unless class_level_receiver?(error)
+
+      raise InvalidPayloadBroadcast,
+        "payload broadcast #{name.inspect} called #{error.name.inspect} on the " \
+          "actor class. Payload blocks now run against the actor instance, like " \
+          "every other actor block. Call it on the class explicitly."
+    end
+
+    # Distinguishes a block that relied on the old class-level receiver from an
+    # ordinary typo, so the one behaviour change reports itself instead of
+    # surfacing as an unexplained NameError.
+    # @rbs (NameError[untyped]) -> bool
+    def class_level_receiver?(error)
+      error.receiver.equal?(snapshot.actor) &&
+        snapshot.actor_class.respond_to?(error.name)
+    rescue ArgumentError, NameError
+      false
+    end
+
     # @rbs () -> void
     def authorize!
       authorized = SolidObjects.configuration.authorize_query.call(

data/lib/solid_objects/supervisor.rb

@@ -2,11 +2,14 @@
 
 module SolidObjects
   class Supervisor
+    MAXIMUM_RETENTION_BACKOFF_DOUBLINGS = 16
+
     # @rbs @components: Array[Worker | EffectExecutor | ReminderScheduler | BroadcastExecutor]
     # @rbs @threads: Array[Thread]
     # @rbs @monitor: Thread?
     # @rbs @started: bool
     # @rbs @cleaned_up_at: Float
+    # @rbs @retention: Thread?
     # @rbs @lifecycle: Thread::Mutex
 
     # @rbs (?worker_count: Integer, ?effect_worker_count: Integer, ?broadcast_worker_count: Integer, ?reminder_scheduler_count: Integer) -> void
@@ -26,6 +29,7 @@ module SolidObjects
       @monitor = nil
       @started = false
       @cleaned_up_at = nil
+      @retention = nil
       @lifecycle = Thread::Mutex.new
     end
 
@@ -44,6 +48,7 @@ module SolidObjects
       @started = true
       @threads = components.map { |component| supervise(component) }
       @monitor = Thread.new { monitor_loop }
+      @retention = Thread.new { retention_loop }
       SolidObjects.instrument(:"supervisor.started", component_count: components.length)
     end
 
@@ -57,6 +62,7 @@ module SolidObjects
         # list, or never starts.
         @lifecycle.synchronize { @started = false }
         stop_monitor
+        stop_retention
         components.each(&:request_shutdown)
         join_until_timeout
         components.reject(&:stopped?).each(&:stop)
@@ -133,6 +139,76 @@ module SolidObjects
       error.class.name
     end
 
+    # Retention gets its own thread rather than sharing the monitor's. A large
+    # backlog or a lock wait can make a pass slow, and role replacement must not
+    # wait behind housekeeping.
+    # @rbs () -> void
+    def retention_loop
+      failures = 0
+      while @started
+        begin
+          prune_expired_records
+          failures = 0
+        rescue => error
+          failures += 1
+          SolidObjects.instrument(
+            :"supervisor.retention_failed",
+            error_class: error.class.name,
+            error_message: error.message
+          )
+        end
+        wait_for_next_retention(failures)
+      end
+    end
+
+    # Sleeping the whole interval would make shutdown wait out an hour-long
+    # nap, so the pause is taken in short steps that notice a stop request.
+    # @rbs (Integer) -> void
+    def wait_for_next_retention(failures)
+      deadline = monotonic_now + retention_pause(failures)
+      step = SolidObjects.configuration.supervisor_monitor_interval
+      while @started && monotonic_now < deadline
+        sleep [ step, deadline - monotonic_now ].min
+      end
+    end
+
+    # Every actor call writes a durable message row, so retention that is only
+    # configured and never run leaves those rows to grow without bound. The
+    # supervisor runs it rather than requiring every application to schedule
+    # its own job.
+    # @rbs () -> void
+    def prune_expired_records
+      return unless SolidObjects.configuration.retention_interval.positive?
+
+      MessagePruner.new.prune
+      ProcessPruner.new.prune
+    end
+
+    # A transient lock or connection error must not defer retention for the
+    # whole interval, so a failed pass retries at monitor cadence. The pause
+    # then doubles per consecutive failure, capped by the interval, so a
+    # database that stays down is not polled once a second forever.
+    # @rbs (Integer) -> Float
+    def retention_pause(failures)
+      interval = SolidObjects.configuration.retention_interval
+      interval = SolidObjects.configuration.supervisor_monitor_interval unless interval.positive?
+      return interval if failures.zero?
+
+      backoff = SolidObjects.configuration.supervisor_monitor_interval *
+        (2**[ failures - 1, MAXIMUM_RETENTION_BACKOFF_DOUBLINGS ].min)
+      [ backoff, interval ].min
+    end
+
+    # @rbs () -> void
+    def stop_retention
+      retention = @retention
+      @retention = nil
+      return unless retention
+
+      retention.join(SolidObjects.configuration.shutdown_timeout)
+      retention.kill if retention.alive?
+    end
+
     # @rbs () -> void
     def cleanup_dead_processes
       interval = SolidObjects.configuration.dead_process_cleanup_interval

data/lib/solid_objects/version.rb

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

data/lib/solid_objects.rb

@@ -13,6 +13,7 @@ require "securerandom"
 require "solid_objects/version"
 require "solid_objects/errors"
 require "solid_objects/sync_deadline"
+require "solid_objects/callable_keywords"
 require "solid_objects/configuration"
 require "solid_objects/instrumentation"
 require "solid_objects/log_subscriber"

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

@@ -27,14 +27,6 @@ module SolidObjects
     # @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/actor_channel.rbs

@@ -21,6 +21,25 @@ module SolidObjects
     # @rbs (ActorSnapshot) -> void
     def transmit_state_payloads: (ActorSnapshot) -> void
 
+    # A payload is one subscriber's view of one name. Letting it raise through
+    # here would reject the subscription or abandon the rest of a broadcast, so
+    # a failure is confined to the payload that caused it and reported. The
+    # exception message is deliberately not instrumented: a payload block reads
+    # actor state, so its message is the one place subscriber state could leak
+    # into logs.
+    #
+    # Returns whether this revision was settled for the name. An unauthorized
+    # payload is settled: the decision is stable, so retrying it would only
+    # re-deliver its authorized siblings.
+    # @rbs (ActorSnapshot, String) -> bool
+    def transmit_state_payload: (ActorSnapshot, String) -> bool
+
+    # Resolves the Cable connection to whatever the application uses as an
+    # authorization subject, so a payload block and `authorize_query` see the
+    # same object a controller render would pass.
+    # @rbs (String) -> untyped
+    def payload_authorization_context: (String) -> untyped
+
     # @rbs (ActorSnapshot) -> bool
     def newer_payload_revision?: (ActorSnapshot) -> bool
 

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

@@ -0,0 +1,16 @@
+# Generated from lib/solid_objects/callable_keywords.rb with RBS::Inline
+
+module SolidObjects
+  # Authorization context resolvers gained keywords after applications had
+  # already written them, so a resolver is called with what it declared it
+  # accepts rather than with everything the caller could offer.
+  module CallableKeywords
+    # @rbs (untyped, Symbol) -> bool
+    def self.accepts?: (untyped, Symbol) -> bool
+
+    # A lambda answers `parameters` directly; a callable object answers it
+    # through its `call` method.
+    # @rbs (untyped) -> Array[[ Symbol, Symbol ]]
+    private def self.parameters: (untyped) -> Array[[ Symbol, Symbol ]]
+  end
+end

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

@@ -31,6 +31,11 @@ module SolidObjects
 
     attr_reader revisions: untyped
 
+    # Live invalidations and reconnect replays share this, so a reconnecting
+    # client pays the same number of requests a connected one does.
+    # @rbs (Array[ComponentRegistration], Integer, Integer) -> Array[String]
+    def refresh_streams: (Array[ComponentRegistration], Integer, Integer) -> Array[String]
+
     # @rbs (ComponentRegistration, Integer, Integer) -> void
     def record_revision: (ComponentRegistration, Integer, Integer) -> void
 

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

@@ -2,10 +2,10 @@
 
 module SolidObjects
   class Configuration
-    @shutdown_timeout: Float
-
     @supervisor_monitor_interval: Float
 
+    @retention_interval: Float
+
     @dead_process_cleanup_interval: Float
 
     @message_retention: Numeric
@@ -40,6 +40,8 @@ module SolidObjects
 
     @component_authorization_context: Proc
 
+    @payload_authorization_context: Proc
+
     @authorize_message: Proc
 
     @authorize_query: Proc
@@ -86,6 +88,8 @@ module SolidObjects
 
     @process_alive_threshold: Float
 
+    @shutdown_timeout: Float
+
     attr_accessor table_name_prefix: untyped
 
     attr_accessor polling_interval: untyped
@@ -126,6 +130,8 @@ module SolidObjects
 
     attr_accessor supervisor_monitor_interval: untyped
 
+    attr_accessor retention_interval: untyped
+
     attr_accessor dead_process_cleanup_interval: untyped
 
     attr_accessor message_retention: untyped
@@ -160,6 +166,8 @@ module SolidObjects
 
     attr_accessor component_authorization_context: untyped
 
+    attr_accessor payload_authorization_context: untyped
+
     attr_accessor authorize_message: untyped
 
     attr_accessor authorize_query: untyped

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

@@ -29,6 +29,19 @@ module SolidObjects
     # @rbs (ActorDefinition::Handler) -> untyped
     def rendered_payload: (ActorDefinition::Handler) -> untyped
 
+    # The block runs against the actor instance, like every other block in the
+    # actor DSL, and still receives the actor and the resolved authorization
+    # context as arguments, so blocks written to the documented signature are
+    # unaffected.
+    # @rbs (ActorDefinition::Handler) -> untyped
+    def evaluated_payload: (ActorDefinition::Handler) -> untyped
+
+    # Distinguishes a block that relied on the old class-level receiver from an
+    # ordinary typo, so the one behaviour change reports itself instead of
+    # surfacing as an unexplained NameError.
+    # @rbs (NameError[untyped]) -> bool
+    def class_level_receiver?: (NameError[untyped]) -> bool
+
     # @rbs () -> void
     def authorize!: () -> void
   end

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

@@ -2,8 +2,12 @@
 
 module SolidObjects
   class Supervisor
+    MAXIMUM_RETENTION_BACKOFF_DOUBLINGS: ::Integer
+
     @lifecycle: Thread::Mutex
 
+    @retention: Thread?
+
     @cleaned_up_at: Float
 
     @started: bool
@@ -52,6 +56,34 @@ module SolidObjects
     # @rbs (Thread?) -> String?
     def thread_error: (Thread?) -> String?
 
+    # Retention gets its own thread rather than sharing the monitor's. A large
+    # backlog or a lock wait can make a pass slow, and role replacement must not
+    # wait behind housekeeping.
+    # @rbs () -> void
+    def retention_loop: () -> void
+
+    # Sleeping the whole interval would make shutdown wait out an hour-long
+    # nap, so the pause is taken in short steps that notice a stop request.
+    # @rbs (Integer) -> void
+    def wait_for_next_retention: (Integer) -> void
+
+    # Every actor call writes a durable message row, so retention that is only
+    # configured and never run leaves those rows to grow without bound. The
+    # supervisor runs it rather than requiring every application to schedule
+    # its own job.
+    # @rbs () -> void
+    def prune_expired_records: () -> void
+
+    # A transient lock or connection error must not defer retention for the
+    # whole interval, so a failed pass retries at monitor cadence. The pause
+    # then doubles per consecutive failure, capped by the interval, so a
+    # database that stays down is not polled once a second forever.
+    # @rbs (Integer) -> Float
+    def retention_pause: (Integer) -> Float
+
+    # @rbs () -> void
+    def stop_retention: () -> void
+
     # @rbs () -> void
     def cleanup_dead_processes: () -> void
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: solid_objects
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Lucas Carlson
@@ -354,6 +354,7 @@ files:
 - lib/solid_objects/application_actor_loader.rb
 - lib/solid_objects/application_write_guard.rb
 - lib/solid_objects/broadcast_executor.rb
+- lib/solid_objects/callable_keywords.rb
 - lib/solid_objects/caller_process.rb
 - lib/solid_objects/cli.rb
 - lib/solid_objects/client.rb
@@ -428,6 +429,7 @@ files:
 - sig/generated/lib/solid_objects/application_actor_loader.rbs
 - sig/generated/lib/solid_objects/application_write_guard.rbs
 - sig/generated/lib/solid_objects/broadcast_executor.rbs
+- sig/generated/lib/solid_objects/callable_keywords.rbs
 - sig/generated/lib/solid_objects/caller_process.rbs
 - sig/generated/lib/solid_objects/cli.rbs
 - sig/generated/lib/solid_objects/client.rbs