solid_objects 0.2.0 → 0.3.0

data/lib/solid_objects/sync_diagnostics.rb

@@ -0,0 +1,133 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  class SyncDiagnostics
+    # @rbs (Message, timeout: Numeric) -> SyncTimeout
+    def call(message, timeout:)
+      message = Message.uncached { Message.find(message.id) }
+      instance = Instance.uncached { Instance.find(message.instance_id) }
+      blocker = earlier_blocker(message)
+      status = message_status(message)
+      waiting_on = waiting_reason(message, instance, blocker)
+      activation = activation_details(instance)
+      error = SyncTimeout.new(
+        timeout:,
+        actor_type: message.actor_type,
+        actor_id: message.actor_id,
+        message_name: message.message_name,
+        message_id: message.id,
+        request_id: message.request_id,
+        sequence: message.sequence,
+        status:,
+        waiting_on:,
+        activation:,
+        blocker: blocker_details(blocker)
+      )
+      SolidObjects.instrument(
+        :"sync.timeout",
+        message_id: message.id,
+        request_id: message.request_id,
+        actor_type: message.actor_type,
+        actor_id: message.actor_id,
+        sequence: message.sequence,
+        status:,
+        waiting_on:,
+        activation_owner_id: activation["owner_id"],
+        activation_generation: activation["generation"]
+      )
+      error
+    end
+
+    private
+
+    # @rbs (Message) -> String
+    def message_status(message)
+      return "rejected" if message.rejected?
+      return "completed" if message.completed?
+      return "dead" if message.dead?
+      return "claimed" if ClaimedMessage.where(message_id: message.id).exists?
+      return "ready" if ReadyMessage.where(message_id: message.id).exists?
+
+      "unknown"
+    end
+
+    # @rbs (Message, Instance, Message?) -> String
+    def waiting_reason(message, instance, blocker)
+      return "actor_paused" if instance.paused_at
+      return "activation_held" if live_activation?(instance)
+      return "earlier_message" if blocker
+      return "message_claimed" if ClaimedMessage.where(message_id: message.id).exists?
+
+      ready_message = ReadyMessage.find_by(message_id: message.id)
+      return "not_yet_available" if future?(ready_message)
+      return "ready_unclaimed" if ready_message
+
+      "unknown"
+    end
+
+    # @rbs (ReadyMessage?) -> bool
+    def future?(ready_message)
+      ready_message&.available_at.present? &&
+        ready_message.available_at > SolidObjects.database_adapter.database_now
+    end
+
+    # @rbs (Instance) -> bool
+    def live_activation?(instance)
+      instance.activation_owner_id.present? &&
+        instance.activation_expires_at.present? &&
+        instance.activation_expires_at > SolidObjects.database_adapter.database_now
+    end
+
+    # @rbs (Message) -> Message?
+    def earlier_blocker(message)
+      ready = Message
+        .joins(:ready_message)
+        .where(instance_id: message.instance_id, sequence: ...message.sequence)
+        .order(:sequence)
+        .first
+      claimed = Message
+        .joins(:claimed_message)
+        .where(instance_id: message.instance_id, sequence: ...message.sequence)
+        .order(:sequence)
+        .first
+
+      [ ready, claimed ].compact.min_by(&:sequence)
+    end
+
+    # @rbs (Instance) -> Hash[String, untyped]
+    def activation_details(instance)
+      process_record = Process.find_by(id: instance.activation_owner_id)
+      {
+        "owner_id" => instance.activation_owner_id,
+        "generation" => instance.activation_generation,
+        "expires_at" => instance.activation_expires_at&.iso8601(6),
+        "process" => process_details(process_record)
+      }
+    end
+
+    # @rbs (Process?) -> Hash[String, untyped]?
+    def process_details(process_record)
+      return unless process_record
+
+      {
+        "kind" => process_record.kind,
+        "hostname" => process_record.hostname,
+        "pid" => process_record.pid,
+        "last_heartbeat_at" => process_record.last_heartbeat_at&.iso8601(6),
+        "shutdown_state" => process_record.shutdown_state
+      }
+    end
+
+    # @rbs (Message?) -> Hash[String, untyped]?
+    def blocker_details(blocker)
+      return unless blocker
+
+      {
+        "message_id" => blocker.id,
+        "sequence" => blocker.sequence,
+        "message_name" => blocker.message_name,
+        "status" => message_status(blocker)
+      }
+    end
+  end
+end

data/lib/solid_objects/synchronous_invocation.rb

@@ -2,12 +2,26 @@
 
 require "solid_objects/activation_manager"
 require "solid_objects/lease_renewer"
+require "solid_objects/sync_diagnostics"
 
 module SolidObjects
   class SynchronousInvocation
     # @rbs (MessageReference, timeout: Numeric) -> untyped
     def call(message_reference, timeout:)
-      deadline = monotonic_now + timeout.to_f
+      return call_before_deadline(message_reference, timeout:) if SyncDeadline.active?
+
+      SyncDeadline.with(timeout:) do
+        call_before_deadline(message_reference, timeout:)
+      end
+    rescue ActiveRecord::RecordNotFound
+      raise ActorDestroyed, "actor was destroyed while waiting for its result"
+    end
+
+    private
+
+    # @rbs (MessageReference, timeout: Numeric) -> untyped
+    def call_before_deadline(message_reference, timeout:)
+      deadline = monotonic_now + SyncDeadline.remaining
 
       loop do
         message = load_message(message_reference)
@@ -15,17 +29,22 @@ module SolidObjects
 
         remaining = deadline - monotonic_now
         unless remaining.positive?
-          raise SyncTimeout, "actor invocation timed out after #{timeout} seconds"
+          message = load_message(message_reference)
+          return completed_result(message) if message.completed? || message.dead?
+
+          raise SyncDiagnostics.new.call(message, timeout:)
         end
 
         processed = assist(message, deadline:)
-        wait(remaining) if processed.zero?
+        remaining = deadline - monotonic_now
+        wait(remaining) if processed.zero? && remaining.positive?
       end
-    rescue ActiveRecord::RecordNotFound
-      raise ActorDestroyed, "actor was destroyed while waiting for its result"
-    end
+    rescue DatabaseDeadlineExceeded
+      message = load_message(message_reference)
+      return completed_result(message) if message.completed? || message.dead?
 
-    private
+      raise SyncDiagnostics.new.call(message, timeout:)
+    end
 
     # @rbs (MessageReference) -> Message
     def load_message(message_reference)

data/lib/solid_objects/test_helper.rb

@@ -0,0 +1,78 @@
+# rbs_inline: enabled
+
+require "solid_objects"
+
+module SolidObjects
+  module TestHelper
+    class << self
+      # @rbs (Class) -> void
+      def included(test_case)
+        test_case.use_transactional_tests = false if test_case.respond_to?(:use_transactional_tests=)
+        test_case.setup { reset_actors! }
+        test_case.teardown { reset_actors! }
+      end
+
+      # @rbs () -> void
+      def reset_actors!
+        SolidObjects.reset_caller_process!
+        Instance.delete_all
+        Process.delete_all
+      end
+    end
+
+    # @rbs () -> void
+    def reset_actors!
+      TestHelper.reset_actors!
+    end
+
+    # @rbs (?roles: Array[Symbol], ?max_passes: Integer) -> Integer
+    def drain_solid_objects(
+      roles: [ :reminders, :actors, :effects, :broadcasts ],
+      max_passes: 1_000
+    )
+      runners = build_solid_objects_runners(roles)
+      total = 0
+
+      max_passes.times do
+        processed = runners.sum { |runner| solid_objects_runner_result(runner) }
+        break if processed.zero?
+
+        total += processed
+      end
+
+      total
+    ensure
+      runners&.uniq&.each(&:stop)
+    end
+
+    private
+
+    # @rbs (Array[Symbol]) -> Array[Worker | EffectExecutor | ReminderScheduler | BroadcastExecutor]
+    def build_solid_objects_runners(roles)
+      unknown_roles = roles - [ :actors, :effects, :reminders, :broadcasts ]
+      raise ArgumentError, "unknown Solid Objects test roles: #{unknown_roles.join(", ")}" if unknown_roles.any?
+
+      runners = {}
+      runners[:actors] = Worker.new if roles.include?(:actors)
+      runners[:effects] = EffectExecutor.new if roles.include?(:effects)
+      runners[:reminders] = ReminderScheduler.new if roles.include?(:reminders)
+      runners[:broadcasts] = BroadcastExecutor.new if roles.include?(:broadcasts)
+
+      [
+        runners[:reminders],
+        runners[:actors],
+        runners[:effects],
+        runners[:actors],
+        runners[:broadcasts]
+      ].compact
+    end
+
+    # @rbs (Worker | EffectExecutor | ReminderScheduler | BroadcastExecutor) -> Integer
+    def solid_objects_runner_result(runner)
+      result = runner.run_once
+      return result if result.is_a?(Integer)
+
+      result ? 1 : 0
+    end
+  end
+end

data/lib/solid_objects/version.rb

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

data/lib/solid_objects/worker.rb

@@ -43,7 +43,7 @@ module SolidObjects
     rescue ActorDestroyed
       release_activation(activation) if activation
       0
-    rescue StateMigrationError, LostActivation => error
+    rescue StateMigrationError, ApplicationWriteForbidden, LostActivation => error
       release_activation(activation) if activation
       SolidObjects.configuration.logger.error(
         event: "solid_objects.worker.error",

data/lib/solid_objects.rb

@@ -12,6 +12,7 @@ require "securerandom"
 
 require "solid_objects/version"
 require "solid_objects/errors"
+require "solid_objects/sync_deadline"
 require "solid_objects/configuration"
 require "solid_objects/instrumentation"
 require "solid_objects/log_subscriber"
@@ -20,19 +21,25 @@ require "solid_objects/context"
 require "solid_objects/actor_registry"
 require "solid_objects/state"
 require "solid_objects/actor_definition"
+require "solid_objects/application_write_guard"
 require "solid_objects/actor"
 require "solid_objects/reference"
 require "solid_objects/message_reference"
 require "solid_objects/dead_letter_manager"
+require "solid_objects/message_pruner"
+require "solid_objects/instance_pruner"
+require "solid_objects/process_pruner"
 require "solid_objects/stream_name"
 require "solid_objects/dom_identity"
 require "solid_objects/stream_token"
 require "solid_objects/turbo_stream_renderer"
 require "solid_objects/actor_snapshot"
+require "solid_objects/state_snapshot"
 require "solid_objects/actor_view"
 require "solid_objects/action_cable_broadcast_adapter"
 require "solid_objects/wake_up"
 require "solid_objects/effect_registry"
+require "solid_objects/commit_action_registry"
 require "solid_objects/lease"
 require "solid_objects/lease_renewer"
 require "solid_objects/worker"
@@ -72,6 +79,16 @@ module SolidObjects
       effect_registry.register(name, handler)
     end
 
+    # @rbs () -> CommitActionRegistry
+    def commit_action_registry
+      @commit_action_registry ||= CommitActionRegistry.new
+    end
+
+    # @rbs (String | Symbol) { (Hash[String, untyped], CommitActionContext) -> untyped } -> Proc
+    def register_commit_action(name, &handler)
+      commit_action_registry.register(name, handler)
+    end
+
     # @rbs () -> Client
     def client
       require "solid_objects/client"
@@ -84,6 +101,17 @@ module SolidObjects
       @caller_process ||= CallerProcess.new
     end
 
+    # @rbs () -> bool
+    def reset_caller_process!
+      caller_process = @caller_process
+      @caller_process = nil
+      return false unless caller_process
+
+      caller_process.stop
+    rescue ActiveRecord::ActiveRecordError
+      false
+    end
+
     # @rbs () -> DeadLetterManager
     def dead_letters
       @dead_letters ||= DeadLetterManager.new
@@ -99,6 +127,11 @@ module SolidObjects
       registry.register(type, actor_class)
     end
 
+    # @rbs (untyped) -> untyped
+    def mutable_copy(value)
+      Serialization.deep_copy(value)
+    end
+
     # @rbs () -> void
     def reset!
       @configuration = Configuration.new
@@ -108,6 +141,7 @@ module SolidObjects
       @wake_up = nil
       @caller_process = nil
       @effect_registry = EffectRegistry.new
+      @commit_action_registry = CommitActionRegistry.new
       @dead_letters = nil
     end
 

data/lib/tasks/solid_objects_tasks.rake

@@ -0,0 +1,10 @@
+require "solid_objects/doctor"
+
+namespace :solid_objects do
+  desc "Verify the Solid Objects installation"
+  task doctor: :environment do
+    report = SolidObjects::Doctor.new.call
+    puts report
+    abort "Solid Objects doctor failed" unless report.healthy?
+  end
+end

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

@@ -59,6 +59,9 @@ module SolidObjects
     # @rbs (Instance) -> Actor
     def build_actor: (Instance) -> Actor
 
+    # @rbs () -> void
+    def release_lease: () -> void
+
     # @rbs () -> Message?
     def claim_next_message: () -> Message?
 

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

@@ -19,6 +19,19 @@ module SolidObjects
       def members: () -> [ :name, :arguments, :success_message_name, :failure_message_name ]
     end
 
+    class CommitActionIntent < Data
+      attr_reader name(): untyped
+
+      attr_reader arguments(): untyped
+
+      def self.new: (untyped name, untyped arguments) -> instance
+                  | (name: untyped, arguments: untyped) -> instance
+
+      def self.members: () -> [ :name, :arguments ]
+
+      def members: () -> [ :name, :arguments ]
+    end
+
     class ReminderIntent < Data
       attr_reader name(): untyped
 
@@ -114,6 +127,8 @@ module SolidObjects
 
     @reminder_intents: Array[ReminderIntent]
 
+    @commit_action_intents: Array[CommitActionIntent]
+
     @effect_intents: Array[EffectIntent]
 
     @state: State
@@ -136,6 +151,9 @@ module SolidObjects
     # @rbs (Symbol | String, ?on_success: Symbol | String?, ?on_failure: Symbol | String?, **untyped) -> nil
     def emit: (Symbol | String, ?on_success: Symbol | String?, ?on_failure: Symbol | String?, **untyped) -> nil
 
+    # @rbs (Symbol | String, **untyped) -> nil
+    def commit_action: (Symbol | String, **untyped) -> nil
+
     # @rbs (Symbol | String, at: Time, ?every: Numeric?, ?missed: Symbol | String, arguments: Hash[Symbol | String, untyped]) -> nil
     def schedule: (Symbol | String, at: Time, arguments: Hash[Symbol | String, untyped], ?every: Numeric?, ?missed: Symbol | String) -> nil
 
@@ -160,6 +178,9 @@ module SolidObjects
     # @rbs () -> Array[EffectIntent]
     def drain_effect_intents: () -> Array[EffectIntent]
 
+    # @rbs () -> Array[CommitActionIntent]
+    def drain_commit_action_intents: () -> Array[CommitActionIntent]
+
     # @rbs () -> Array[ReminderIntent]
     def drain_reminder_intents: () -> Array[ReminderIntent]
 
@@ -173,10 +194,15 @@ module SolidObjects
 
     attr_reader effect_intents: untyped
 
+    attr_reader commit_action_intents: untyped
+
     attr_reader reminder_intents: untyped
 
     attr_reader outbound_message_intents: untyped
 
+    # @rbs (String) { () -> untyped } -> untyped
+    def guard_application_writes: (String) { () -> untyped } -> untyped
+
     # @rbs (Hash[String, untyped]) -> Hash[Symbol, untyped]
     def keyword_arguments: (Hash[String, untyped]) -> Hash[Symbol, untyped]
 

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

@@ -0,0 +1,8 @@
+# Generated from lib/solid_objects/application_write_guard.rb with RBS::Inline
+
+module SolidObjects
+  class ApplicationWriteGuard
+    # @rbs (actor_type: String, actor_id: String, operation: String) { () -> untyped } -> untyped
+    def self.call: (actor_type: String, actor_id: String, operation: String) { () -> untyped } -> untyped
+  end
+end

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

@@ -8,12 +8,17 @@ module SolidObjects
 
     @registry: ProcessRegistry?
 
+    @shutdown_hook_installed: bool
+
     # @rbs () -> void
     def initialize: () -> void
 
     # @rbs () -> ProcessRegistry
     def process_registry: () -> ProcessRegistry
 
+    # @rbs () -> bool
+    def stop: () -> bool
+
     private
 
     attr_reader mutex: untyped
@@ -28,5 +33,11 @@ module SolidObjects
 
     # @rbs () -> ProcessRegistry
     def register: () -> ProcessRegistry
+
+    # @rbs () -> void
+    def install_shutdown_hook: () -> void
+
+    # @rbs () -> bool
+    def stop_after_exit: () -> bool
   end
 end

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

@@ -11,6 +11,15 @@ module SolidObjects
     # @rbs () -> void
     def cleanup: () -> void
 
+    # @rbs () -> void
+    def prune_messages: () -> void
+
+    # @rbs () -> void
+    def prune_instances: () -> void
+
+    # @rbs () -> void
+    def prune_processes: () -> void
+
     # @rbs () -> void
     def dead_letters: () -> void
 
@@ -25,7 +34,7 @@ module SolidObjects
     # @rbs (Symbol, Integer) -> Integer
     def numeric_option: (Symbol, Integer) -> Integer
 
-    # @rbs (Symbol) -> void
-    def authorize_administration!: (Symbol) -> void
+    # @rbs (Symbol, resource: String) -> void
+    def authorize_administration!: (Symbol, resource: String) -> void
   end
 end

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

@@ -13,6 +13,12 @@ module SolidObjects
     # @rbs (Reference, Symbol | String, Hash[Symbol | String, untyped], timeout: Numeric, ?idempotency_key: String?, ?authorization_context: untyped) -> untyped
     def sync: (Reference, Symbol | String, Hash[Symbol | String, untyped], timeout: Numeric, ?idempotency_key: String?, ?authorization_context: untyped) -> untyped
 
+    # @rbs (MessageReference, timeout: Numeric, ?authorization_context: untyped) -> untyped
+    def wait: (MessageReference, timeout: Numeric, ?authorization_context: untyped) -> untyped
+
+    # @rbs (Reference, ?authorization_context: untyped) -> StateSnapshot
+    def snapshot: (Reference, ?authorization_context: untyped) -> StateSnapshot
+
     # @rbs (Reference, ?authorization_context: untyped) -> bool
     def destroy: (Reference, ?authorization_context: untyped) -> bool
 
@@ -20,6 +26,15 @@ module SolidObjects
 
     attr_reader mailbox: untyped
 
+    # @rbs (Reference, Symbol | String, Hash[Symbol | String, untyped], idempotency_key: String?, timeout: Numeric) -> MessageReference
+    def enqueue_sync: (Reference, Symbol | String, Hash[Symbol | String, untyped], idempotency_key: String?, timeout: Numeric) -> MessageReference
+
+    # @rbs (MessageReference, Message) -> void
+    def validate_message_reference!: (MessageReference, Message) -> void
+
+    # @rbs (Reference, Symbol | String) -> void
+    def reject_sync_inside_transaction!: (Reference, Symbol | String) -> void
+
     # @rbs (Proc, Reference, Symbol | String, Hash[Symbol | String, untyped], authorization_context: untyped) -> void
     def authorize!: (Proc, Reference, Symbol | String, Hash[Symbol | String, untyped], authorization_context: untyped) -> void
 

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

@@ -0,0 +1,43 @@
+# Generated from lib/solid_objects/commit_action_registry.rb with RBS::Inline
+
+module SolidObjects
+  class CommitActionContext < Data
+    attr_reader message_id(): untyped
+
+    attr_reader request_id(): untyped
+
+    attr_reader actor_type(): untyped
+
+    attr_reader actor_id(): untyped
+
+    attr_reader activation_generation(): untyped
+
+    def self.new: (untyped message_id, untyped request_id, untyped actor_type, untyped actor_id, untyped activation_generation) -> instance
+                | (message_id: untyped, request_id: untyped, actor_type: untyped, actor_id: untyped, activation_generation: untyped) -> instance
+
+    def self.members: () -> [ :message_id, :request_id, :actor_type, :actor_id, :activation_generation ]
+
+    def members: () -> [ :message_id, :request_id, :actor_type, :actor_id, :activation_generation ]
+  end
+
+  class CommitActionRegistry
+    @handlers: Hash[String, Proc]
+
+    @mutex: Mutex
+
+    # @rbs () -> void
+    def initialize: () -> void
+
+    # @rbs (String | Symbol, Proc) -> Proc
+    def register: (String | Symbol, Proc) -> Proc
+
+    # @rbs (String | Symbol) -> Proc
+    def fetch: (String | Symbol) -> Proc
+
+    private
+
+    attr_reader handlers: untyped
+
+    attr_reader mutex: untyped
+  end
+end

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

@@ -2,16 +2,22 @@
 
 module SolidObjects
   class Configuration
-    @max_attempts: Integer
-
-    @retry_delay: Proc
-
-    @process_heartbeat_interval: Float
+    @table_name_prefix: String
 
     @process_alive_threshold: Float
 
     @shutdown_timeout: Float
 
+    @message_retention: Numeric
+
+    @message_retention_by_actor_type: Hash[String, Numeric]
+
+    @instance_retention_by_actor_type: Hash[String, Numeric]
+
+    @process_retention: Numeric
+
+    @prune_batch_size: Integer
+
     @worker_count: Integer
 
     @effect_worker_count: Integer
@@ -40,8 +46,6 @@ module SolidObjects
 
     @authorize_administration: Proc
 
-    @table_name_prefix: String
-
     @polling_interval: Float
 
     @sync_polling_interval: Float
@@ -66,6 +70,12 @@ module SolidObjects
 
     @max_result_bytes: Integer
 
+    @max_attempts: Integer
+
+    @retry_delay: Proc
+
+    @process_heartbeat_interval: Float
+
     attr_accessor table_name_prefix: untyped
 
     attr_accessor polling_interval: untyped
@@ -102,6 +112,16 @@ module SolidObjects
 
     attr_accessor shutdown_timeout: untyped
 
+    attr_accessor message_retention: untyped
+
+    attr_accessor message_retention_by_actor_type: untyped
+
+    attr_accessor instance_retention_by_actor_type: untyped
+
+    attr_accessor process_retention: untyped
+
+    attr_accessor prune_batch_size: untyped
+
     attr_accessor worker_count: untyped
 
     attr_accessor effect_worker_count: untyped

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

@@ -36,6 +36,15 @@ module SolidObjects
 
     attr_reader fixed_connection: untyped
 
+    # @rbs (untyped) { () -> untyped } -> untyped
+    def with_transaction_deadline: (untyped) { () -> untyped } -> untyped
+
+    # @rbs (untyped) -> void
+    def configure_transaction_deadline: (untyped) -> void
+
+    # @rbs (Exception) -> bool
+    def deadline_error?: (Exception) -> bool
+
     # @rbs () { (untyped) -> untyped } -> untyped
     def with_connection: () { (untyped) -> untyped } -> untyped
   end