solid_objects 0.3.0 → 0.4.0

data/docs/realtime.md

@@ -1,13 +1,15 @@
 # Realtime integration
 
-## Rendering
+## Scalars and components
 
 `solid_object` performs initial server rendering and emits one
 `turbo-cable-stream-source` for the actor:
 
 ```erb
-<%= solid_object ShoppingCartActor.ref(current_user.id) do |cart| %>
+<%= solid_object ShoppingCartActor.ref(current_user.id),
+  authorization_context: current_user do |cart| %>
   Items: <%= cart.items_count %>
+  <%= cart.component :summary, observes: %i[items checkout_status] %>
 <% end %>
 ```
 
@@ -15,9 +17,39 @@ Every observable gets a stable opaque DOM ID. Multiple values share the one
 actor subscription and Action Cable multiplexes actor subscriptions over the
 browser's physical WebSocket.
 
-`actor.component(:summary)` renders a host partial by convention at
-`actors/<actor_class>/_summary`. Initial component rendering is implemented;
-durable background component replacement is not yet implemented.
+Scalar observable calls such as `cart.items_count` render stable `<span>`
+targets. Their broadcast remains a direct escaped text replacement.
+
+A reactive component declares one or more explicit observable dependencies.
+`actor.component(:summary, observes: ...)` resolves the host partial by
+convention at `actors/<actor_class>/_summary` and wraps it in a stable Turbo
+Frame. Reactive components do not accept `partial:` because a client must
+never influence partial resolution. The older
+`actor.component(:summary, partial: "server/chosen/path")` form remains
+available for initial-only static rendering.
+
+The partial receives exactly two component locals:
+
+- `actor`, which exposes the declared observables as deeply frozen ordinary
+  Ruby values plus `actor_id` and `reference`; and
+- `authorization_context`, the context for this initial render or refresh.
+
+`actor.state` is unavailable in reactive components. Reading an observable not
+listed in `observes:` raises `UnknownComponentDependency`. This keeps
+invalidation correct and prevents a partial from silently depending on state
+that cannot wake it.
+
+```erb
+<ul>
+  <% actor.recent_messages.each do |message| %>
+    <li><%= message.fetch("body") %></li>
+  <% end %>
+</ul>
+```
+
+Arrays, hashes, loops, conditionals, nested markup, and host helper output are
+normal ERB. Escaping remains Action View's responsibility; Solid Objects never
+marks actor strings as HTML safe.
 
 ## Authorization
 
@@ -26,18 +58,69 @@ it does not grant access. `ActorChannel` verifies the token, resolves the actor
 through the registry, calls `authorize_subscription`, and streams only after
 approval.
 
-Initial observable method reads separately call `authorize_query`. Never
-authorize solely from actor ID, token possession, stream name, or DOM ID.
+Initial scalar and component reads call `authorize_query` with the context
+passed to `solid_object`. The refresh controller resolves a new request context
+through `component_authorization_context`, then calls `authorize_query` again
+for the component name and every declared dependency. The default resolver
+supplies the engine controller; applications commonly resolve it to
+`Current.user`:
+
+```ruby
+configuration.component_authorization_context = ->(controller:) { Current.user }
+```
+
+The three 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 |
+
+Do not substitute a signed token for any of them. Never authorize solely from
+actor ID, token possession, stream name, component name, or DOM ID.
 
 ## Broadcast durability
 
 The actor's fenced commit compares observables before and after the turn and
-inserts one broadcast row per changed value. A broadcast process later sends a
-Turbo replacement and records delivery. No direct broadcast occurs inside the
-actor transaction.
+inserts one broadcast row per changed value. The actor state, monotonic
+`state_revision`, message completion, and broadcast rows commit atomically. A
+rolled-back or fenced-out turn therefore cannot invalidate a component.
+
+A broadcast process later sends small invalidation metadata and records
+delivery. Its scalar Turbo replacement is transmitted only when that observable
+target was rendered and signed into the scope's stream token. Component-only
+dependencies therefore do not expose their serialized values over Cable. The
+runtime never stores or broadcasts personalized component HTML. Each
+authorized browser requests affected components through the engine endpoint
+with its normal cookies. Responses are `private, no-store`.
+
+Several changed dependencies from one message sequence produce one logical
+refresh for a component. An unrelated observable does not refresh it. If a
+newer invalidation arrives while a Turbo Frame request is in flight, the new
+frame replaces the old frame element; the detached older response has no
+current target.
 
 If Cable delivery is lost, reconnecting `ActorChannel` transmits replacements
-from current actor state. The durable state row remains source of truth.
+from current actor state. It compares the signed component revision with the
+latest `(instance_id, state_revision)` pair and refreshes stale components.
+The incarnation ID handles destroy-and-recreate; the state revision handles
+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.
+
+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 and replacing the entire Turbo Frame
+generation.
+
+## Cost model
+
+The durable row cost is unchanged: one broadcast row per changed observable,
+containing its JSON value and the message/instance references needed to derive
+invalidation metadata. No rendered document is stored. Each affected component
+adds one authorized GET and one partial render per non-coalesced state
+revision. Scalar observables remain the cheaper path for one text value.
 
 ## Deployment
 
@@ -48,4 +131,15 @@ require Redis.
 
 Changing or removing observable names during a rolling deploy can strand old
 broadcast rows or old DOM targets. Keep old names compatible until the outbox
-and old pages have drained.
+and old pages have drained. Keep component partial names and dependency
+observables compatible across a rolling deploy for the same reason.
+
+Reactive components require the engine mount because their signed refresh path
+is generated from that mount. Applications with more than one engine mount can
+set `component_path_resolver` to return the intended same-origin
+`components_path`.
+
+```ruby
+# config/routes.rb
+mount SolidObjects::Engine => "/solid_objects"
+```

data/docs/roadmap.md

@@ -15,7 +15,8 @@
 - Transactional effects with success/failure actor messages
 - Actor-to-actor asynchronous outbox delivery
 - One-shot and recurring reminders with `:latest` or `:all` catch-up
-- Durable observable broadcast outbox and authorized Action Cable refresh
+- Durable observable invalidations, scalar Turbo replacement, and authorized
+  request-time ERB component refresh
 - Reconciliation read APIs
 - Installation doctor, authorization reference, fit guide, and legacy-state
   migration cookbook
@@ -35,8 +36,9 @@
   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.
-- Realtime: observable replacement and reconnect refresh are implemented;
-  durable component replacement and Turbo append actions are not.
+- Realtime: scalar and dependency-driven ERB component replacement,
+  personalized refresh authorization, revision fencing, coalescing, and
+  reconnect convergence are implemented; Turbo append actions are not.
 - 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
@@ -52,8 +54,7 @@
 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.
-6. Add component broadcast rendering, Turbo append intents, and reconnect tests
-   in a full browser.
+6. Add Turbo append intents and expand reconnect coverage in a full browser.
 7. Add distributed rate limits, global admission hooks, and cache-capacity
    eviction.
 8. Expand security scanning and run compatibility CI across supported Rails and

data/examples/application/README.md

@@ -10,7 +10,8 @@ key. The chat actor also gives every submitted chat message a caller-generated
 message ID and checks that ID in durable actor state, because actor handlers may
 be redelivered.
 
-The views demonstrate initial `solid_object` rendering and live observable
-replacement. Live cart-summary replacement and chat-message append are
-deliberately not shown as working behavior because component broadcasts and
-Turbo append intents remain roadmap items.
+The views demonstrate scalar observable replacement and a live chat-message
+ERB component. The chat component receives `recent_messages` as an ordinary
+Ruby array, rerenders its `<ol>` after committed changes, and refreshes through
+the authenticated host request context. Turbo append intents remain roadmap
+work.

data/examples/application/app/views/actors/chat_room_actor/_messages.html.erb

@@ -1,5 +1,5 @@
 <ol>
-  <% actor.state.recent_messages.each do |message| %>
+  <% actor.recent_messages.each do |message| %>
     <li id="message_<%= message.fetch("id") %>">
       <strong><%= message.fetch("user_id") %></strong>
       <%= message.fetch("body") %>

data/examples/application/app/views/chat_rooms/show.html.erb

@@ -1,8 +1,8 @@
-<%= solid_object @room do |room| %>
+<%= solid_object @room, authorization_context: current_user do |room| %>
   <p>
     Present:
     <%= room.presence %>
   </p>
 
-  <%= room.component :messages %>
+  <%= room.component :messages, observes: :recent_messages %>
 <% end %>

data/examples/application/config/initializers/solid_objects.rb

@@ -2,16 +2,22 @@
 
 SolidObjects.configure do |configuration|
   configuration.authorize_message = lambda do |actor_type:, actor_id:, authorization_context:, **|
-    next false unless authorization_context.respond_to?(:current_user)
+    user = if authorization_context.respond_to?(:current_user)
+      authorization_context.current_user
+    else
+      authorization_context
+    end
+    next false unless user
 
     if actor_type == ShoppingCartActor.actor_type
-      authorization_context.current_user.id.to_s == actor_id
+      user.id.to_s == actor_id
     else
-      ChatRoomPolicy.new(authorization_context.current_user).access?(actor_id)
+      ChatRoomPolicy.new(user).access?(actor_id)
     end
   end
   configuration.authorize_query = configuration.authorize_message
   configuration.authorize_subscription = configuration.authorize_message
+  configuration.component_authorization_context = ->(controller:) { Current.user }
 end
 
 SolidObjects.register_effect(:charge_payment) do |arguments, context|

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

@@ -49,6 +49,9 @@ SolidObjects.configure do |configuration|
   configuration.authorize_subscription = ->(**) { false }
   configuration.authorize_administration = ->(**) { false }
 
+  # Configure component_authorization_context to return the authenticated
+  # principal used for reactive component refreshes.
+
   # 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.rb

@@ -238,6 +238,17 @@ module SolidObjects
       end
     end
 
+    # @rbs (Symbol | String) -> untyped
+    def observable_value(name)
+      observable_name = name.to_sym
+      handler = self.class.definition.observables[observable_name]
+      raise UnknownMessage, "unknown observable #{name.inspect}" unless handler
+
+      guard_application_writes("observable.#{observable_name}") do
+        Serialization.dump(instance_exec(&handler.block))
+      end
+    end
+
     # @rbs () -> void
     def activate
       guard_application_writes("on_activate") do

data/lib/solid_objects/actor_channel.rb

@@ -17,13 +17,81 @@ module SolidObjects
       )
       return reject unless authorized
 
-      reference = Reference.new(actor_type:, actor_id:)
-      stream_from StreamName.for(reference)
-      ActorSnapshot.new(reference).observable_values.each do |name, value|
-        transmit TurboStreamRenderer.observable_value(reference, name, value)
+      @reference = Reference.new(actor_type:, actor_id:)
+      @scalar_observables = identity["observables"]
+      validate_scalar_observables!
+      @component_subscriptions = ComponentSubscriptions.parse(
+        params["components"],
+        reference:
+      )
+      stream_from StreamName.for(reference) do |stream|
+        receive_broadcast(stream)
+      end
+      snapshot = ActorSnapshot.new(reference)
+      scalar_observable_names(snapshot).each do |name|
+        transmit TurboStreamRenderer.observable_value(
+          reference,
+          name,
+          snapshot.observable_value(name)
+        )
       end
-    rescue KeyError, InvalidStreamToken, UnknownActorType
+      refresh_outdated_components(snapshot)
+    rescue KeyError,
+      JSON::ParserError,
+      InvalidStreamToken,
+      InvalidComponentToken,
+      UnknownActorType
       reject
     end
+
+    private
+
+    attr_reader :reference, :component_subscriptions, :scalar_observables
+
+    # @rbs (String) -> void
+    def receive_broadcast(stream)
+      invalidation = TurboStreamRenderer.invalidation(stream)
+      if !invalidation ||
+          scalar_observables.nil? ||
+          scalar_observables.include?(invalidation.fetch("observable_name"))
+        transmit stream
+      end
+      return unless invalidation
+
+      component_subscriptions
+        .refreshes_for(invalidation)
+        .each { |refresh| transmit refresh }
+    end
+
+    # @rbs (ActorSnapshot) -> void
+    def refresh_outdated_components(snapshot)
+      component_subscriptions
+        .reconnect_refreshes(snapshot)
+        .each { |refresh| transmit refresh }
+    end
+
+    # @rbs () -> void
+    def validate_scalar_observables!
+      return unless scalar_observables
+
+      observables = SolidObjects
+        .registry
+        .fetch(reference.actor_type)
+        .definition
+        .observables
+      unknown = scalar_observables.find do |name|
+        !observables.key?(name.to_sym)
+      end
+      return unless unknown
+
+      raise InvalidStreamToken, "unknown scalar observable #{unknown.inspect}"
+    end
+
+    # @rbs (ActorSnapshot) -> Array[String]
+    def scalar_observable_names(snapshot)
+      return scalar_observables if scalar_observables
+
+      snapshot.actor_class.definition.observables.keys.map(&:to_s)
+    end
   end
 end

data/lib/solid_objects/actor_snapshot.rb

@@ -5,29 +5,48 @@ module SolidObjects
     # @rbs @reference: Reference
     # @rbs @actor_class: Class
     # @rbs @actor: Actor
+    # @rbs @instance_id: Integer
+    # @rbs @revision: Integer
+    # @rbs @observable_values: Hash[String, untyped]?
+    # @rbs @observable_value_cache: Hash[String, untyped]
 
-    attr_reader :reference, :actor_class, :actor
+    attr_reader :reference, :actor_class, :actor, :instance_id, :revision
 
     # @rbs (Reference) -> void
     def initialize(reference)
       @reference = reference
       @actor_class = SolidObjects.registry.fetch(reference.actor_type)
+      @instance = Instance.find_by(
+        actor_type: reference.actor_type,
+        actor_id: reference.actor_id
+      )
+      @instance_id = @instance&.id || 0
+      @revision = @instance&.state_revision || 0
       @actor = build_actor
+      @observable_values = nil
+      @observable_value_cache = {}
     end
 
     # @rbs () -> Hash[String, untyped]
     def observable_values
-      actor.observable_values
+      @observable_values ||= Serialization.readonly_copy(actor.observable_values)
+    end
+
+    # @rbs (Symbol | String) -> untyped
+    def observable_value(name)
+      observable_name = name.to_s
+      return @observable_value_cache.fetch(observable_name) if @observable_value_cache.key?(observable_name)
+
+      @observable_value_cache[observable_name] =
+        Serialization.readonly_copy(actor.observable_value(observable_name))
     end
 
     private
 
+    attr_reader :instance
+
     # @rbs () -> Actor
     def build_actor
-      instance = Instance.find_by(
-        actor_type: reference.actor_type,
-        actor_id: reference.actor_id
-      )
       state_version = instance&.state_version || actor_class.state_version
       state_data = ApplicationWriteGuard.call(
         actor_type: reference.actor_type,

data/lib/solid_objects/actor_view.rb

@@ -6,6 +6,8 @@ module SolidObjects
     # @rbs @view_context: untyped
     # @rbs @authorization_context: untyped
     # @rbs @snapshot: ActorSnapshot
+    # @rbs @component_registrations: Array[ComponentRegistration]
+    # @rbs @observable_names: Array[String]
 
     attr_reader :reference
 
@@ -15,6 +17,8 @@ module SolidObjects
       @view_context = view_context
       @authorization_context = authorization_context
       @snapshot = ActorSnapshot.new(reference)
+      @component_registrations = []
+      @observable_names = []
     end
 
     # @rbs (Symbol | String) -> untyped
@@ -24,7 +28,8 @@ module SolidObjects
       raise UnknownMessage, "unknown observable #{name.inspect}" unless handler
 
       authorize_read!(observable_name)
-      value = snapshot.observable_values.fetch(observable_name.to_s)
+      value = snapshot.observable_value(observable_name)
+      observable_names << observable_name.to_s unless observable_names.include?(observable_name.to_s)
       view_context.content_tag(
         :span,
         display_value(value),
@@ -32,21 +37,54 @@ module SolidObjects
       )
     end
 
-    # @rbs (Symbol | String, ?partial: String?) -> untyped
-    def component(name, partial: nil)
+    # @rbs (Symbol | String, ?observes: Symbol | String | Array[Symbol | String]?, ?partial: String?) -> untyped
+    def component(name, observes: nil, partial: nil)
       component_name = normalized_component_name(name)
-      authorize_read!(component_name)
-      rendered = view_context.render(
-        partial: partial || default_partial(component_name),
-        locals: { actor: self }
+      return static_component(component_name, partial:) unless observes
+      if partial
+        raise ArgumentError,
+          "reactive components resolve partials by actor and component name"
+      end
+
+      dependencies = normalized_dependencies(observes)
+      validate_dependencies!(dependencies)
+      ensure_unique_component!(component_name)
+      refresh_path = component_path_resolver.call(view_context:)
+      registration = ComponentRegistration.issue(
+        reference:,
+        component_name:,
+        dependencies:,
+        snapshot:,
+        refresh_path:
       )
+      rendered = ComponentRenderer.new(
+        snapshot:,
+        component_name:,
+        dependencies:,
+        view_context:,
+        authorization_context:
+      ).call
+      component_registrations << registration
       view_context.content_tag(
-        :div,
+        :"turbo-frame",
         rendered,
-        id: DomIdentity.component(reference, component_name)
+        id: DomIdentity.component(reference, component_name),
+        data: {
+          solid_objects_revision: "#{snapshot.instance_id}:#{snapshot.revision}"
+        }
       )
     end
 
+    # @rbs () -> Array[String]
+    def component_tokens
+      component_registrations.map(&:token)
+    end
+
+    # @rbs () -> Array[String]
+    def scalar_observable_names
+      observable_names.dup
+    end
+
     # @rbs () -> State
     def state
       snapshot.actor.state
@@ -66,7 +104,25 @@ module SolidObjects
 
     private
 
-    attr_reader :view_context, :authorization_context, :snapshot
+    attr_reader :view_context,
+      :authorization_context,
+      :snapshot,
+      :component_registrations,
+      :observable_names
+
+    # @rbs (String, partial: String?) -> untyped
+    def static_component(component_name, partial:)
+      authorize_read!(component_name)
+      rendered = view_context.render(
+        partial: partial || default_partial(component_name),
+        locals: { actor: self }
+      )
+      view_context.content_tag(
+        :div,
+        rendered,
+        id: DomIdentity.component(reference, component_name)
+      )
+    end
 
     # @rbs (Symbol | String) -> void
     def authorize_read!(name)
@@ -106,6 +162,43 @@ module SolidObjects
       component_name
     end
 
+    # @rbs (Symbol | String | Array[Symbol | String]) -> Array[String]
+    def normalized_dependencies(observes)
+      dependencies = Array(observes).map(&:to_s).uniq
+      if dependencies.empty?
+        raise ArgumentError, "reactive components require at least one observable"
+      end
+
+      dependencies
+    end
+
+    # @rbs (Array[String]) -> void
+    def validate_dependencies!(dependencies)
+      unknown = dependencies.find do |dependency|
+        !snapshot.actor_class.definition.observables.key?(dependency.to_sym)
+      end
+      return unless unknown
+
+      raise UnknownComponentDependency,
+        "unknown observable dependency #{unknown.inspect} for #{reference.actor_type}"
+    end
+
+    # @rbs (String) -> void
+    def ensure_unique_component!(component_name)
+      return unless component_registrations.any? do |registration|
+        registration.component_name == component_name
+      end
+
+      raise ArgumentError,
+        "component #{component_name.inspect} is already rendered in this solid_object scope"
+    end
+
+    # @rbs () -> Proc | ComponentPathResolver
+    def component_path_resolver
+      SolidObjects.configuration.component_path_resolver ||
+        ComponentPathResolver.new
+    end
+
     # @rbs (String) -> String
     def default_partial(component_name)
       actor_name = snapshot.actor_class.name

data/lib/solid_objects/component_path_resolver.rb

@@ -0,0 +1,27 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  class ComponentPathResolver
+    # @rbs (view_context: untyped) -> String
+    def call(view_context:)
+      unless mounted?
+        raise UnsupportedComponentRendering,
+          "reactive components require the SolidObjects::Engine to be mounted in the host routes"
+      end
+
+      SolidObjects::Engine.routes.url_helpers.components_path
+    end
+
+    private
+
+    # @rbs () -> bool
+    def mounted?
+      return false unless defined?(Rails) && Rails.application
+
+      Rails.application.routes.routes.any? do |route|
+        route.app.respond_to?(:app) &&
+          route.app.app.equal?(SolidObjects::Engine)
+      end
+    end
+  end
+end