solid_objects 0.2.1 → 0.4.0

data/lib/solid_objects/actor.rb

@@ -3,6 +3,7 @@
 module SolidObjects
   class Actor
     EffectIntent = Data.define(:name, :arguments, :success_message_name, :failure_message_name)
+    CommitActionIntent = Data.define(:name, :arguments)
     ReminderIntent = Data.define(:name, :at, :arguments, :interval_seconds, :missed_policy)
     OutboundMessageIntent = Data.define(:actor_type, :actor_id, :message_name, :arguments, :available_at, :idempotency_key)
 
@@ -131,6 +132,7 @@ module SolidObjects
     # @rbs @actor_id: String
     # @rbs @state: State
     # @rbs @effect_intents: Array[EffectIntent]
+    # @rbs @commit_action_intents: Array[CommitActionIntent]
     # @rbs @reminder_intents: Array[ReminderIntent]
     # @rbs @outbound_message_intents: Array[OutboundMessageIntent]
 
@@ -141,6 +143,7 @@ module SolidObjects
       @actor_id = actor_id
       @state = state
       @effect_intents = []
+      @commit_action_intents = []
       @reminder_intents = []
       @outbound_message_intents = []
     end
@@ -175,6 +178,17 @@ module SolidObjects
       nil
     end
 
+    # @rbs (Symbol | String, **untyped) -> nil
+    def commit_action(name, **arguments)
+      CommitActionIntent.new(
+        name: name.to_s,
+        arguments: Serialization.dump(arguments)
+      ).tap do |intent|
+        commit_action_intents << intent
+      end
+      nil
+    end
+
     # @rbs (Symbol | String, at: Time, ?every: Numeric?, ?missed: Symbol | String, arguments: Hash[Symbol | String, untyped]) -> nil
     def schedule(name, at:, every: nil, missed: :latest, arguments: {})
       interval_seconds = every&.to_f
@@ -210,24 +224,43 @@ module SolidObjects
         self.class.definition.queries[message_name.to_sym]
       raise UnknownMessage, "unknown message #{message_name.inspect} for #{self.class.actor_type}" unless handler
 
-      instance_exec(**keyword_arguments(arguments), &handler.block)
+      guard_application_writes(message_name.to_s) do
+        instance_exec(**keyword_arguments(arguments), &handler.block)
+      end
     end
 
     # @rbs () -> Hash[String, untyped]
     def observable_values
-      self.class.definition.observables.each_with_object({}) do |(name, handler), values|
-        values[name.to_s] = Serialization.dump(instance_exec(&handler.block))
+      guard_application_writes("observables") do
+        self.class.definition.observables.each_with_object({}) do |(name, handler), values|
+          values[name.to_s] = Serialization.dump(instance_exec(&handler.block))
+        end
+      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
-      self.class.definition.activation_hooks.each { |hook| instance_exec(&hook) }
+      guard_application_writes("on_activate") do
+        self.class.definition.activation_hooks.each { |hook| instance_exec(&hook) }
+      end
     end
 
     # @rbs () -> void
     def deactivate
-      self.class.definition.deactivation_hooks.each { |hook| instance_exec(&hook) }
+      guard_application_writes("on_deactivate") do
+        self.class.definition.deactivation_hooks.each { |hook| instance_exec(&hook) }
+      end
     end
 
     # @rbs (Reference, Symbol | String, Hash[Symbol | String, untyped], ?available_at: Time?, idempotency_key: String?) -> OutboundMessageIntent
@@ -247,6 +280,11 @@ module SolidObjects
       effect_intents.shift(effect_intents.length)
     end
 
+    # @rbs () -> Array[CommitActionIntent]
+    def drain_commit_action_intents
+      commit_action_intents.shift(commit_action_intents.length)
+    end
+
     # @rbs () -> Array[ReminderIntent]
     def drain_reminder_intents
       reminder_intents.shift(reminder_intents.length)
@@ -260,13 +298,27 @@ module SolidObjects
     # @rbs () -> void
     def discard_intents
       effect_intents.clear
+      commit_action_intents.clear
       reminder_intents.clear
       outbound_message_intents.clear
     end
 
     private
 
-    attr_reader :effect_intents, :reminder_intents, :outbound_message_intents
+    attr_reader :effect_intents,
+      :commit_action_intents,
+      :reminder_intents,
+      :outbound_message_intents
+
+    # @rbs (String) { () -> untyped } -> untyped
+    def guard_application_writes(operation, &block)
+      ApplicationWriteGuard.call(
+        actor_type: self.class.actor_type,
+        actor_id:,
+        operation:,
+        &block
+      )
+    end
 
     # @rbs (Hash[String, untyped]) -> Hash[Symbol, untyped]
     def keyword_arguments(arguments)

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_definition.rb

@@ -136,6 +136,8 @@ module SolidObjects
       migrated
     rescue StateMigrationError
       raise
+    rescue ActiveRecord::ReadOnlyError
+      raise
     rescue => error
       raise StateMigrationError, "state migration failed: #{error.message}"
     end

data/lib/solid_objects/actor_snapshot.rb

@@ -5,34 +5,59 @@ 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 = actor_class.definition.migrate_state(
-        state_version,
-        instance&.state || {}
-      )
+      state_data = ApplicationWriteGuard.call(
+        actor_type: reference.actor_type,
+        actor_id: reference.actor_id,
+        operation: "state_migration"
+      ) do
+        actor_class.definition.migrate_state(
+          state_version,
+          instance&.state || {}
+        )
+      end
       actor_class.new(
         actor_id: reference.actor_id,
         state: State.new(actor_class.definition.state_definition, state_data)

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

@@ -0,0 +1,24 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  class ApplicationWriteGuard
+    class << self
+      # @rbs (actor_type: String, actor_id: String, operation: String) { () -> untyped } -> untyped
+      def call(actor_type:, actor_id:, operation:)
+        ActiveRecord::Base.while_preventing_writes { yield }
+      rescue ActiveRecord::ReadOnlyError
+        SolidObjects.instrument(
+          :"actor_code.write_forbidden",
+          actor_type:,
+          actor_id:,
+          operation:
+        )
+        raise ApplicationWriteForbidden.new(
+          actor_type:,
+          actor_id:,
+          message_name: operation
+        )
+      end
+    end
+  end
+end

data/lib/solid_objects/caller_process.rb

@@ -5,12 +5,14 @@ module SolidObjects
     # @rbs @mutex: Thread::Mutex
     # @rbs @process_id: Integer?
     # @rbs @registry: ProcessRegistry?
+    # @rbs @shutdown_hook_installed: bool
 
     # @rbs () -> void
     def initialize
       @mutex = Thread::Mutex.new
       @process_id = nil
       @registry = nil
+      @shutdown_hook_installed = false
     end
 
     # @rbs () -> ProcessRegistry
@@ -18,11 +20,22 @@ module SolidObjects
       mutex.synchronize do
         reset_after_fork
         register unless reusable_registry?
+        install_shutdown_hook
         registry.heartbeat
         registry
       end
     end
 
+    # @rbs () -> bool
+    def stop
+      mutex.synchronize do
+        return false unless @process_id == ::Process.pid
+        return false unless registry&.process_record
+
+        registry.stop.tap { @registry = nil }
+      end
+    end
+
     private
 
     attr_reader :mutex, :registry
@@ -53,5 +66,20 @@ module SolidObjects
       )
       registry
     end
+
+    # @rbs () -> void
+    def install_shutdown_hook
+      return if @shutdown_hook_installed
+
+      @shutdown_hook_installed = true
+      at_exit { stop_after_exit }
+    end
+
+    # @rbs () -> bool
+    def stop_after_exit
+      stop
+    rescue
+      false
+    end
   end
 end

data/lib/solid_objects/cli.rb

@@ -34,7 +34,7 @@ module SolidObjects
     # @rbs () -> void
     def status
       boot_application
-      authorize_administration!(:status)
+      authorize_administration!(:status, resource: "processes")
       rows = SolidObjects::Process.order(:kind, :started_at).map do |process_record|
         {
           id: process_record.id,
@@ -54,10 +54,49 @@ module SolidObjects
     # @rbs () -> void
     def cleanup
       boot_application
-      authorize_administration!(:cleanup)
+      authorize_administration!(:cleanup, resource: "processes")
       puts JSON.generate(cleaned_processes: ProcessRegistry.cleanup_dead)
     end
 
+    desc "prune_messages", "Preview or delete expired terminal message history"
+    option :environment, type: :string, aliases: "-e"
+    option :execute, type: :boolean, default: false
+
+    # @rbs () -> void
+    def prune_messages
+      boot_application
+      authorize_administration!(:prune, resource: "messages")
+      pruner = MessagePruner.new
+      count = options[:execute] ? pruner.prune : pruner.preview
+      puts JSON.generate(mode: options[:execute] ? "execute" : "preview", messages: count)
+    end
+
+    desc "prune_instances", "Preview or delete expired idle actor instances"
+    option :environment, type: :string, aliases: "-e"
+    option :execute, type: :boolean, default: false
+
+    # @rbs () -> void
+    def prune_instances
+      boot_application
+      authorize_administration!(:prune, resource: "instances")
+      pruner = InstancePruner.new
+      count = options[:execute] ? pruner.prune : pruner.preview
+      puts JSON.generate(mode: options[:execute] ? "execute" : "preview", instances: count)
+    end
+
+    desc "prune_processes", "Preview or delete expired stopped process records"
+    option :environment, type: :string, aliases: "-e"
+    option :execute, type: :boolean, default: false
+
+    # @rbs () -> void
+    def prune_processes
+      boot_application
+      authorize_administration!(:prune, resource: "processes")
+      pruner = ProcessPruner.new
+      count = options[:execute] ? pruner.prune : pruner.preview
+      puts JSON.generate(mode: options[:execute] ? "execute" : "preview", processes: count)
+    end
+
     desc "dead_letters", "Print dead actor messages"
     option :environment, type: :string, aliases: "-e"
 
@@ -102,11 +141,11 @@ module SolidObjects
       value ? Integer(value) : default
     end
 
-    # @rbs (Symbol) -> void
-    def authorize_administration!(action)
+    # @rbs (Symbol, resource: String) -> void
+    def authorize_administration!(action, resource:)
       authorized = SolidObjects.configuration.authorize_administration.call(
         action:,
-        resource: "processes",
+        resource:,
         resource_id: nil,
         authorization_context: { source: "cli" }
       )