solid_objects 0.2.0 → 0.3.0

data/lib/solid_objects/errors.rb

@@ -4,6 +4,9 @@ module SolidObjects
   class Error < StandardError
   end
 
+  class NonRetryableError < Error
+  end
+
   class UnsupportedDatabase < Error
   end
 
@@ -40,7 +43,148 @@ module SolidObjects
   class ActorDestroyed < LostActivation
   end
 
+  class DatabaseDeadlineExceeded < Error
+  end
+
+  class SyncEnqueueTimeout < Error
+    # @rbs @timeout: Numeric
+    # @rbs @actor_type: String
+    # @rbs @actor_id: String
+    # @rbs @message_name: String
+
+    attr_reader :timeout, :actor_type, :actor_id, :message_name
+
+    # @rbs (timeout: Numeric, actor_type: String, actor_id: String, message_name: String) -> void
+    def initialize(timeout:, actor_type:, actor_id:, message_name:)
+      @timeout = timeout
+      @actor_type = actor_type
+      @actor_id = actor_id
+      @message_name = message_name
+      super(
+        "actor invocation could not be durably enqueued within #{timeout} seconds for " \
+          "#{actor_type}(#{actor_id.inspect}).#{message_name}"
+      )
+    end
+  end
+
   class SyncTimeout < Error
+    # @rbs @timeout: Numeric
+    # @rbs @actor_type: String
+    # @rbs @actor_id: String
+    # @rbs @message_name: String
+    # @rbs @message_id: Integer
+    # @rbs @request_id: String
+    # @rbs @sequence: Integer
+    # @rbs @status: String
+    # @rbs @waiting_on: String
+    # @rbs @activation: Hash[String, untyped]
+    # @rbs @blocker: Hash[String, untyped]?
+
+    attr_reader :timeout,
+      :actor_type,
+      :actor_id,
+      :message_name,
+      :message_id,
+      :request_id,
+      :sequence,
+      :status,
+      :waiting_on,
+      :activation,
+      :blocker
+
+    # @rbs (timeout: Numeric, actor_type: String, actor_id: String, message_name: String, message_id: Integer, request_id: String, sequence: Integer, status: String, waiting_on: String, activation: Hash[String, untyped], blocker: Hash[String, untyped]?) -> void
+    def initialize(
+      timeout:,
+      actor_type:,
+      actor_id:,
+      message_name:,
+      message_id:,
+      request_id:,
+      sequence:,
+      status:,
+      waiting_on:,
+      activation:,
+      blocker:
+    )
+      @timeout = timeout
+      @actor_type = actor_type
+      @actor_id = actor_id
+      @message_name = message_name
+      @message_id = message_id
+      @request_id = request_id
+      @sequence = sequence
+      @status = status
+      @waiting_on = waiting_on
+      @activation = Serialization.readonly_copy(activation)
+      @blocker = Serialization.readonly_copy(blocker)
+      super(
+        "actor invocation timed out after #{timeout} seconds for " \
+          "#{actor_type}(#{actor_id.inspect}).#{message_name} " \
+          "message_id=#{message_id} sequence=#{sequence} status=#{status} waiting_on=#{waiting_on}"
+      )
+    end
+
+    # @rbs () -> MessageReference
+    def message_reference
+      MessageReference.new(
+        id: message_id,
+        request_id:,
+        actor_type:,
+        actor_id:,
+        sequence:
+      )
+    end
+  end
+
+  class SyncInsideTransaction < Error
+    # @rbs @actor_type: String
+    # @rbs @actor_id: String
+    # @rbs @message_name: String
+
+    attr_reader :actor_type, :actor_id, :message_name
+
+    # @rbs (actor_type: String, actor_id: String, message_name: String) -> void
+    def initialize(actor_type:, actor_id:, message_name:)
+      @actor_type = actor_type
+      @actor_id = actor_id
+      @message_name = message_name
+      super(
+        "cannot synchronously invoke #{actor_type}(#{actor_id.inspect}).#{message_name} " \
+          "inside an open database transaction; call it before the transaction or enqueue it with async"
+      )
+    end
+  end
+
+  class ApplicationWriteForbidden < NonRetryableError
+    # @rbs @actor_type: String
+    # @rbs @actor_id: String
+    # @rbs @message_name: String
+
+    attr_reader :actor_type, :actor_id, :message_name
+
+    # @rbs (actor_type: String, actor_id: String, message_name: String) -> void
+    def initialize(actor_type:, actor_id:, message_name:)
+      @actor_type = actor_type
+      @actor_id = actor_id
+      @message_name = message_name
+      super(
+        "#{actor_type}(#{actor_id.inspect}).#{message_name} attempted an Active Record write; " \
+          "mutate actor state, stage a commit action, or emit a durable effect instead"
+      )
+    end
+  end
+
+  class CommitActionUnavailable < NonRetryableError
+    # @rbs (actor_type: String, actor_id: String, message_name: String) -> void
+    def initialize(actor_type:, actor_id:, message_name:)
+      super(
+        "#{actor_type}(#{actor_id.inspect}).#{message_name} staged a commit action, " \
+          "but Solid Objects uses a separate database from Active Record"
+      )
+    end
+  end
+
+  class UnknownCommitAction < NonRetryableError
   end
 
   class Rejected < Error

data/lib/solid_objects/executor.rb

@@ -24,9 +24,7 @@ module SolidObjects
       )
 
       SolidObjects.instrument(:"message.started", **instrumentation_payload)
-      result = Context.with(actor:, message: message_context) do
-        actor.invoke(message.message_name, message.arguments)
-      end
+      result = invoke_actor(message_context)
       ensure_query_did_not_mutate_state!(state_before)
       observable_changes = changed_observables(observables_before, actor.observable_values)
       complete(result, observable_changes)
@@ -54,6 +52,13 @@ module SolidObjects
       activation.actor
     end
 
+    # @rbs (MessageContext) -> untyped
+    def invoke_actor(message_context)
+      Context.with(actor:, message: message_context) do
+        actor.invoke(message.message_name, message.arguments)
+      end
+    end
+
     # @rbs (Hash[String, untyped]) -> void
     def ensure_query_did_not_mutate_state!(state_before)
       return unless message.message_kind == "sync"
@@ -81,6 +86,7 @@ module SolidObjects
         max_bytes: SolidObjects.configuration.max_result_bytes
       )
       effect_intents = actor.drain_effect_intents
+      commit_action_intents = actor.drain_commit_action_intents
       reminder_intents = actor.drain_reminder_intents
       outbound_message_intents = actor.drain_outbound_message_intents
       enqueued_effects = []
@@ -88,6 +94,7 @@ module SolidObjects
       activation.lease.fenced_transaction do |instance|
         claimed_message = matching_claim!
         locked_message = Message.lock.find(message.id)
+        execute_commit_actions(commit_action_intents)
         instance.update!(
           state: serialized_state,
           state_version: actor.class.state_version,
@@ -128,6 +135,58 @@ module SolidObjects
       SolidObjects.wake_up.signal
     end
 
+    # @rbs (Array[Actor::CommitActionIntent]) -> void
+    def execute_commit_actions(intents)
+      ensure_application_database_is_shared! if intents.any?
+      context = CommitActionContext.new(
+        message_id: message.id,
+        request_id: message.request_id,
+        actor_type: message.actor_type,
+        actor_id: message.actor_id,
+        activation_generation: activation.lease.generation
+      )
+
+      intents.each do |intent|
+        handler = SolidObjects.commit_action_registry.fetch(intent.name)
+        execute_commit_action(intent, handler, context)
+      end
+    end
+
+    # @rbs (Actor::CommitActionIntent, Proc, CommitActionContext) -> untyped
+    def execute_commit_action(intent, handler, context)
+      payload = {
+        commit_action_name: intent.name,
+        message_id: message.id,
+        request_id: message.request_id,
+        actor_type: message.actor_type,
+        actor_id: message.actor_id,
+        activation_generation: activation.lease.generation
+      }
+      SolidObjects.instrument(:"commit_action.started", **payload)
+      handler.call(intent.arguments, context).tap do
+        SolidObjects.instrument(:"commit_action.completed", **payload)
+      end
+    rescue => error
+      SolidObjects.instrument(
+        :"commit_action.failed",
+        **payload,
+        error_class: error.class.name,
+        error_message: error.message
+      )
+      raise
+    end
+
+    # @rbs () -> void
+    def ensure_application_database_is_shared!
+      return if SolidObjects::Record.connection_pool.equal?(ActiveRecord::Base.connection_pool)
+
+      raise CommitActionUnavailable.new(
+        actor_type: message.actor_type,
+        actor_id: message.actor_id,
+        message_name: message.message_name
+      )
+    end
+
     # @rbs (Message, Instance, Array[Actor::EffectIntent]) -> Array[Effect]
     def enqueue_effects(locked_message, instance, intents)
       intents.map do |intent|
@@ -218,7 +277,8 @@ module SolidObjects
         locked_message.update!(error: error_details, last_failed_at: now)
         claimed_message.destroy!
 
-        if locked_message.attempt_count >= locked_message.max_attempts
+        if error.is_a?(NonRetryableError) ||
+            locked_message.attempt_count >= locked_message.max_attempts
           create_dead_letter(locked_message, error_details, now)
           dead = true
         else

data/lib/solid_objects/instance_pruner.rb

@@ -0,0 +1,97 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  class InstancePruner
+    # @rbs @now: Time
+    # @rbs @batch_size: Integer
+
+    # @rbs (?now: Time, ?batch_size: Integer) -> void
+    def initialize(
+      now: SolidObjects.database_adapter.database_now,
+      batch_size: SolidObjects.configuration.prune_batch_size
+    )
+      @now = now
+      @batch_size = batch_size
+    end
+
+    # @rbs () -> Integer
+    def preview
+      policy_relations.sum(&:count)
+    end
+
+    # @rbs () -> Integer
+    def prune
+      policy_relations.sum { |relation| prune_relation(relation) }.tap do |count|
+        SolidObjects.instrument(:"instances.pruned", count:)
+      end
+    end
+
+    private
+
+    attr_reader :now, :batch_size
+
+    # @rbs () -> Array[ActiveRecord::Relation[Instance]]
+    def policy_relations
+      SolidObjects.configuration.instance_retention_by_actor_type.map do |actor_type, retention|
+        prunable
+          .where(actor_type: actor_type.to_s)
+          .where("COALESCE(last_used_at, created_at) < ?", now - retention)
+      end
+    end
+
+    # @rbs () -> ActiveRecord::Relation[Instance]
+    def prunable
+      Instance
+        .where(activation_owner_id: nil, paused_at: nil)
+        .where.not(id: ReadyMessage.select(:instance_id))
+        .where.not(id: ClaimedMessage.select(:instance_id))
+        .where.not(
+          id: Reminder.where(status: "scheduled").select(:instance_id)
+        )
+        .where.not(
+          id: Effect.where.not(status: "completed").select(:instance_id)
+        )
+        .where.not(
+          id: Broadcast.where.not(status: "delivered").select(:instance_id)
+        )
+        .where.not(id: DeadLetter.select(:instance_id))
+    end
+
+    # @rbs (ActiveRecord::Relation[Instance]) -> Integer
+    def prune_relation(relation)
+      deleted = 0
+
+      loop do
+        instance_ids = relation.limit(batch_size).pluck(:id)
+        break if instance_ids.empty?
+
+        instance_ids.each do |instance_id|
+          deleted += prune_instance(instance_id, relation)
+        end
+      end
+
+      deleted
+    end
+
+    # @rbs (Integer, ActiveRecord::Relation[Instance]) -> Integer
+    def prune_instance(instance_id, relation)
+      expired_actor = SolidObjects.database_adapter.transaction do
+        instance = Instance.lock.find_by(id: instance_id)
+        next unless instance
+        next unless relation.where(id: instance_id).exists?
+
+        identity = {
+          instance_id:,
+          actor_type: instance.actor_type,
+          actor_id: instance.actor_id
+        }
+        instance.delete
+        identity
+      end
+      return 0 unless expired_actor
+
+      SolidObjects.instrument(:"actor.expired", **expired_actor)
+      1
+    end
+  end
+end

data/lib/solid_objects/message_pruner.rb

@@ -0,0 +1,97 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  class MessagePruner
+    # @rbs @now: Time
+    # @rbs @batch_size: Integer
+
+    # @rbs (?now: Time, ?batch_size: Integer) -> void
+    def initialize(
+      now: SolidObjects.database_adapter.database_now,
+      batch_size: SolidObjects.configuration.prune_batch_size
+    )
+      @now = now
+      @batch_size = batch_size
+    end
+
+    # @rbs () -> Integer
+    def preview
+      policy_relations.sum(&:count)
+    end
+
+    # @rbs () -> Integer
+    def prune
+      policy_relations.sum { |relation| prune_relation(relation) }.tap do |count|
+        SolidObjects.instrument(:"messages.pruned", count:)
+      end
+    end
+
+    private
+
+    attr_reader :now, :batch_size
+
+    # @rbs () -> Array[ActiveRecord::Relation[Message]]
+    def policy_relations
+      overrides = retention_overrides
+      relations = overrides.map do |actor_type, retention|
+        prunable.where(actor_type:, completed_at: ...retention_cutoff(retention))
+      end
+      default_relation = prunable.where(completed_at: ...retention_cutoff(default_retention))
+      default_relation = default_relation.where.not(actor_type: overrides.keys) if overrides.any?
+      relations << default_relation
+    end
+
+    # @rbs () -> ActiveRecord::Relation[Message]
+    def prunable
+      Message
+        .where.not(id: ReadyMessage.select(:message_id))
+        .where.not(id: ClaimedMessage.select(:message_id))
+        .where.not(id: DeadLetter.select(:message_id))
+        .where.not(
+          id: DeadLetter
+            .where.not(retried_message_id: nil)
+            .select(:retried_message_id)
+        )
+        .where.not(
+          id: Effect
+            .where.not(status: "completed")
+            .select(:message_id)
+        )
+        .where.not(
+          id: Broadcast
+            .where.not(status: "delivered")
+            .select(:message_id)
+        )
+    end
+
+    # @rbs (ActiveRecord::Relation[Message]) -> Integer
+    def prune_relation(relation)
+      deleted = 0
+
+      loop do
+        message_ids = relation.limit(batch_size).pluck(:id)
+        break if message_ids.empty?
+
+        deleted += Message.where(id: message_ids).delete_all
+      end
+
+      deleted
+    end
+
+    # @rbs () -> Numeric
+    def default_retention
+      SolidObjects.configuration.message_retention
+    end
+
+    # @rbs () -> Hash[String, Numeric]
+    def retention_overrides
+      SolidObjects.configuration.message_retention_by_actor_type
+        .to_h { |actor_type, retention| [ actor_type.to_s, retention ] }
+    end
+
+    # @rbs (Numeric) -> Time
+    def retention_cutoff(retention)
+      now - retention
+    end
+  end
+end

data/lib/solid_objects/message_reference.rb

@@ -49,5 +49,14 @@ module SolidObjects
     def result
       Message.find(id).result
     end
+
+    # @rbs (?timeout: Numeric, ?authorization_context: untyped) -> untyped
+    def wait(timeout: 5.seconds, authorization_context: nil)
+      SolidObjects.client.wait(
+        self,
+        timeout:,
+        authorization_context:
+      )
+    end
   end
 end

data/lib/solid_objects/process_pruner.rb

@@ -0,0 +1,49 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  class ProcessPruner
+    # @rbs @now: Time
+    # @rbs @batch_size: Integer
+
+    # @rbs (?now: Time, ?batch_size: Integer) -> void
+    def initialize(
+      now: SolidObjects.database_adapter.database_now,
+      batch_size: SolidObjects.configuration.prune_batch_size
+    )
+      @now = now
+      @batch_size = batch_size
+    end
+
+    # @rbs () -> Integer
+    def preview
+      prunable.count
+    end
+
+    # @rbs () -> Integer
+    def prune
+      deleted = 0
+
+      loop do
+        process_ids = prunable.limit(batch_size).pluck(:id)
+        break if process_ids.empty?
+
+        deleted += Process.where(id: process_ids).delete_all
+      end
+
+      SolidObjects.instrument(:"processes.pruned", count: deleted)
+      deleted
+    end
+
+    private
+
+    attr_reader :now, :batch_size
+
+    # @rbs () -> ActiveRecord::Relation[Process]
+    def prunable
+      Process.where(
+        shutdown_state: "stopped",
+        stopped_at: ...(now - SolidObjects.configuration.process_retention)
+      )
+    end
+  end
+end

data/lib/solid_objects/reference.rb

@@ -58,6 +58,11 @@ module SolidObjects
       SolidObjects.client.destroy(self, authorization_context:)
     end
 
+    # @rbs (?authorization_context: untyped) -> StateSnapshot
+    def snapshot(authorization_context: nil)
+      SolidObjects.client.snapshot(self, authorization_context:)
+    end
+
     # @rbs (Symbol, *untyped, **untyped) -> untyped
     def method_missing(name, *arguments, **keywords)
       return super if arguments.any? || block_given?

data/lib/solid_objects/state_snapshot.rb

@@ -0,0 +1,41 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  class StateSnapshot
+    # @rbs @actor_class: Class
+    # @rbs @data: Hash[String, untyped]
+
+    # @rbs (Reference) -> void
+    def initialize(reference)
+      actor_snapshot = ActorSnapshot.new(reference)
+      @actor_class = actor_snapshot.actor_class
+      @data = Serialization.readonly_copy(actor_snapshot.actor.state.to_h)
+    end
+
+    # @rbs () -> Hash[String, untyped]
+    def to_h
+      data
+    end
+
+    # @rbs (Symbol, *untyped, **untyped) -> untyped
+    def method_missing(name, *arguments, **keywords)
+      return data.fetch(name.to_s) if arguments.empty? && keywords.empty? && attribute?(name)
+
+      super
+    end
+
+    # @rbs (Symbol, bool) -> bool
+    def respond_to_missing?(name, include_private = false)
+      attribute?(name) || super
+    end
+
+    private
+
+    attr_reader :actor_class, :data
+
+    # @rbs (Symbol | String) -> bool
+    def attribute?(name)
+      actor_class.definition.state_definition.to_h.key?(name.to_sym)
+    end
+  end
+end

data/lib/solid_objects/sync_deadline.rb

@@ -0,0 +1,57 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  class SyncDeadline
+    KEY = :solid_objects_sync_deadline
+
+    class << self
+      # @rbs (timeout: Numeric) { () -> untyped } -> untyped
+      def with(timeout:)
+        previous_deadline = ActiveSupport::IsolatedExecutionState[KEY]
+        ActiveSupport::IsolatedExecutionState[KEY] = monotonic_now + timeout.to_f
+        yield
+      ensure
+        ActiveSupport::IsolatedExecutionState[KEY] = previous_deadline
+      end
+
+      # @rbs () -> bool
+      def active?
+        !deadline.nil?
+      end
+
+      # @rbs () -> bool
+      def expired?
+        active? && !remaining.positive?
+      end
+
+      # @rbs () -> Float
+      def remaining
+        return Float::INFINITY unless deadline
+
+        deadline - monotonic_now
+      end
+
+      # @rbs () -> Integer
+      def remaining_milliseconds
+        [ (remaining * 1_000).floor, 1 ].max
+      end
+
+      # @rbs () -> Integer
+      def remaining_seconds
+        [ remaining.ceil, 1 ].max
+      end
+
+      private
+
+      # @rbs () -> Float?
+      def deadline
+        ActiveSupport::IsolatedExecutionState[KEY]
+      end
+
+      # @rbs () -> Float
+      def monotonic_now
+        ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end