solid_objects 0.1.0 → 0.2.0

data/lib/solid_objects/actor.rb

@@ -150,7 +150,17 @@ module SolidObjects
       Context.current_message
     end
 
-    # @rbs (Symbol | String, ?on_success: Symbol | String?, ?on_failure: Symbol | String?, **untyped) -> EffectIntent
+    # @rbs (Symbol | String, String, ?details: Hash[String | Symbol, untyped]) -> bot
+    def reject(code, message, details: {})
+      rejection_code = code.to_s
+      unless rejection_code.match?(/\A[a-z][a-z0-9_]*\z/)
+        raise ArgumentError, "rejection code must contain lowercase letters, digits, and underscores"
+      end
+
+      raise Rejected.new(code: rejection_code, message:, details:)
+    end
+
+    # @rbs (Symbol | String, ?on_success: Symbol | String?, ?on_failure: Symbol | String?, **untyped) -> nil
     def emit(name, on_success: nil, on_failure: nil, **arguments)
       validate_effect_callback!(on_success)
       validate_effect_callback!(on_failure)
@@ -162,9 +172,10 @@ module SolidObjects
       ).tap do |intent|
         effect_intents << intent
       end
+      nil
     end
 
-    # @rbs (Symbol | String, at: Time, ?every: Numeric?, ?missed: Symbol | String, arguments: Hash[Symbol | String, untyped]) -> ReminderIntent
+    # @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
       if interval_seconds && !interval_seconds.positive?
@@ -184,11 +195,13 @@ module SolidObjects
       ).tap do |intent|
         reminder_intents << intent
       end
+      nil
     end
 
-    # @rbs (Reference, Symbol | String, ?available_at: Time?, ?idempotency_key: String?, **untyped) -> OutboundMessageIntent
+    # @rbs (Reference, Symbol | String, ?available_at: Time?, ?idempotency_key: String?, **untyped) -> nil
     def send_to(reference, message_name, available_at: nil, idempotency_key: nil, **arguments)
       stage_outbound_message(reference, message_name, arguments, available_at:, idempotency_key:)
+      nil
     end
 
     # @rbs (Symbol | String, Hash[String, untyped]) -> untyped

data/lib/solid_objects/caller_process.rb

@@ -0,0 +1,57 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  class CallerProcess
+    # @rbs @mutex: Thread::Mutex
+    # @rbs @process_id: Integer?
+    # @rbs @registry: ProcessRegistry?
+
+    # @rbs () -> void
+    def initialize
+      @mutex = Thread::Mutex.new
+      @process_id = nil
+      @registry = nil
+    end
+
+    # @rbs () -> ProcessRegistry
+    def process_registry
+      mutex.synchronize do
+        reset_after_fork
+        register unless reusable_registry?
+        registry.heartbeat
+        registry
+      end
+    end
+
+    private
+
+    attr_reader :mutex, :registry
+
+    # @rbs () -> void
+    def reset_after_fork
+      return if @process_id == ::Process.pid
+
+      @process_id = ::Process.pid
+      @registry = nil
+    end
+
+    # @rbs () -> bool
+    def reusable_registry?
+      return false unless registry&.process_record
+
+      registry.process_record.reload.shutdown_state == "running"
+    rescue ActiveRecord::RecordNotFound
+      false
+    end
+
+    # @rbs () -> ProcessRegistry
+    def register
+      @registry = ProcessRegistry.new
+      registry.register(
+        kind: "caller",
+        metadata: { execution: "synchronous" }
+      )
+      registry
+    end
+  end
+end

data/lib/solid_objects/client.rb

@@ -1,6 +1,7 @@
 # rbs_inline: enabled
 
 require "solid_objects/mailbox"
+require "solid_objects/synchronous_invocation"
 
 module SolidObjects
   class Client
@@ -12,7 +13,7 @@ module SolidObjects
     end
 
     # @rbs (Reference, Symbol | String, Hash[Symbol | String, untyped], ?available_at: Time?, ?idempotency_key: String?, ?authorization_context: untyped) -> MessageReference
-    def tell(reference, message_name, arguments, available_at: nil, idempotency_key: nil, authorization_context: nil)
+    def async(reference, message_name, arguments, available_at: nil, idempotency_key: nil, authorization_context: nil)
       actor_class = SolidObjects.registry.fetch(reference.actor_type)
       message_symbol = message_name.to_sym
       raise UnknownMessage, "unknown message #{message_name.inspect}" unless actor_class.definition.messages.key?(message_symbol)
@@ -28,14 +29,14 @@ module SolidObjects
         reference,
         message_name,
         arguments,
-        kind: "tell",
+        kind: "async",
         available_at:,
         idempotency_key:
       )
     end
 
     # @rbs (Reference, Symbol | String, Hash[Symbol | String, untyped], timeout: Numeric, ?idempotency_key: String?, ?authorization_context: untyped) -> untyped
-    def ask(reference, message_name, arguments, timeout:, idempotency_key: nil, authorization_context: nil)
+    def sync(reference, message_name, arguments, timeout:, idempotency_key: nil, authorization_context: nil)
       actor_class = SolidObjects.registry.fetch(reference.actor_type)
       message_symbol = message_name.to_sym
       query = actor_class.definition.queries.key?(message_symbol)
@@ -53,10 +54,10 @@ module SolidObjects
         reference,
         message_name,
         arguments,
-        kind: "ask",
+        kind: "sync",
         idempotency_key:
       )
-      wait_for_result(message_reference, timeout:)
+      SynchronousInvocation.new.call(message_reference, timeout:)
     end
 
     # @rbs (Reference, ?authorization_context: untyped) -> bool
@@ -117,37 +118,5 @@ module SolidObjects
 
       raise Unauthorized, "actor destruction is not authorized"
     end
-
-    # @rbs (MessageReference, timeout: Numeric) -> untyped
-    def wait_for_result(message_reference, timeout:)
-      deadline = monotonic_now + timeout.to_f
-
-      loop do
-        message = Message.uncached { Message.find(message_reference.id) }
-        return message.result if message.completed?
-
-        if message.dead?
-          raise MessageFailed.new(
-            "actor message failed permanently",
-            message_id: message.id,
-            details: message.error || {}
-          )
-        end
-
-        remaining = deadline - monotonic_now
-        raise AskTimeout, "actor request timed out after #{timeout} seconds" unless remaining.positive?
-
-        SolidObjects.wake_up.wait(
-          timeout: [ remaining, SolidObjects.configuration.ask_polling_interval ].min
-        )
-      end
-    rescue ActiveRecord::RecordNotFound
-      raise ActorDestroyed, "actor was destroyed while waiting for its result"
-    end
-
-    # @rbs () -> Float
-    def monotonic_now
-      ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
-    end
   end
 end

data/lib/solid_objects/configuration.rb

@@ -4,7 +4,7 @@ module SolidObjects
   class Configuration
     # @rbs @table_name_prefix: String
     # @rbs @polling_interval: Float
-    # @rbs @ask_polling_interval: Float
+    # @rbs @sync_polling_interval: Float
     # @rbs @lease_duration: Float
     # @rbs @lease_renewal_interval: Float
     # @rbs @idle_deactivation_timeout: Float
@@ -37,7 +37,7 @@ module SolidObjects
 
     attr_accessor :table_name_prefix,
       :polling_interval,
-      :ask_polling_interval,
+      :sync_polling_interval,
       :lease_duration,
       :lease_renewal_interval,
       :idle_deactivation_timeout,
@@ -72,7 +72,7 @@ module SolidObjects
     def initialize
       @table_name_prefix = "solid_objects_"
       @polling_interval = 0.1
-      @ask_polling_interval = 0.05
+      @sync_polling_interval = 0.05
       @lease_duration = 30.0
       @lease_renewal_interval = 10.0
       @idle_deactivation_timeout = 30.0
@@ -138,7 +138,7 @@ module SolidObjects
     def positive_values
       {
         polling_interval:,
-        ask_polling_interval:,
+        sync_polling_interval:,
         lease_duration:,
         lease_renewal_interval:,
         max_messages_per_activation_pass:,

data/lib/solid_objects/engine.rb

@@ -21,6 +21,7 @@ module SolidObjects
 
     initializer "solid_objects.helpers" do
       ActiveSupport.on_load(:action_view) do
+        require_relative "../../app/helpers/solid_objects/actor_helper"
         include SolidObjects::ActorHelper
       end
     end

data/lib/solid_objects/errors.rb

@@ -40,7 +40,23 @@ module SolidObjects
   class ActorDestroyed < LostActivation
   end
 
-  class AskTimeout < Error
+  class SyncTimeout < Error
+  end
+
+  class Rejected < Error
+    # @rbs @code: String
+    # @rbs @details: Hash[String, untyped]
+    # @rbs @message_id: Integer?
+
+    attr_reader :code, :details, :message_id
+
+    # @rbs (code: String | Symbol, message: String, ?details: Hash[String | Symbol, untyped], ?message_id: Integer?) -> void
+    def initialize(code:, message:, details: {}, message_id: nil)
+      @code = code.to_s
+      @details = Serialization.dump(details)
+      @message_id = message_id
+      super(message)
+    end
   end
 
   class MessageFailed < Error

data/lib/solid_objects/executor.rb

@@ -33,6 +33,11 @@ module SolidObjects
       true
     rescue LostActivation
       raise
+    rescue Rejected => rejection
+      activation.restore_state(state_before) if state_before
+      actor.discard_intents
+      reject_message(rejection)
+      false
     rescue => error
       activation.restore_state(state_before) if state_before
       actor.discard_intents
@@ -51,7 +56,7 @@ module SolidObjects
 
     # @rbs (Hash[String, untyped]) -> void
     def ensure_query_did_not_mutate_state!(state_before)
-      return unless message.message_kind == "ask"
+      return unless message.message_kind == "sync"
       return unless actor.class.definition.queries.key?(message.message_name.to_sym)
       return if actor.state.to_h == state_before
 
@@ -72,7 +77,7 @@ module SolidObjects
         max_bytes: SolidObjects.configuration.max_state_bytes
       )
       serialized_result = Serialization.dump(
-        (message.message_kind == "ask") ? result : nil,
+        (message.message_kind == "sync") ? result : nil,
         max_bytes: SolidObjects.configuration.max_result_bytes
       )
       effect_intents = actor.drain_effect_intents
@@ -235,11 +240,46 @@ module SolidObjects
       SolidObjects.wake_up.signal
     end
 
+    # @rbs (Rejected) -> void
+    def reject_message(rejection)
+      rejection_data = Serialization.dump(
+        {
+          "code" => rejection.code,
+          "message" => rejection.message.to_s.byteslice(0, 8_192),
+          "details" => rejection.details
+        },
+        max_bytes: SolidObjects.configuration.max_result_bytes
+      )
+
+      activation.lease.fenced_transaction do |instance|
+        claimed_message = matching_claim!
+        locked_message = Message.lock.find(message.id)
+        now = SolidObjects.database_adapter.database_now
+        instance.update!(last_used_at: now)
+        locked_message.update!(
+          result: nil,
+          rejection: rejection_data,
+          error: nil,
+          rejected_at: now,
+          completed_at: now
+        )
+        claimed_message.destroy!
+      end
+
+      SolidObjects.instrument(
+        :"message.rejected",
+        **instrumentation_payload,
+        code: rejection.code
+      )
+      SolidObjects.wake_up.signal
+    end
+
     # @rbs () -> ClaimedMessage
     def matching_claim!
       ClaimedMessage.lock.find_by!(
         message_id: message.id,
         process_id: activation.lease.owner_id,
+        activation_token: activation.lease.activation_token,
         activation_generation: activation.lease.generation
       )
     rescue ActiveRecord::RecordNotFound

data/lib/solid_objects/lease.rb

@@ -3,19 +3,21 @@
 module SolidObjects
   class Lease
     class << self
-      # @rbs (instance: Instance, owner_id: String, now: Time, ?duration: Numeric, database_adapter: DatabaseAdapter) -> Lease?
+      # @rbs (instance: Instance, owner_id: String, activation_token: String, now: Time, ?duration: Numeric, database_adapter: DatabaseAdapter) -> Lease?
       def claim(
         instance:,
         owner_id:,
+        activation_token:,
         now:,
         database_adapter:, duration: SolidObjects.configuration.lease_duration
       )
-        return if held_by_another_live_owner?(instance, owner_id, now)
+        return if held_by_another_live_owner?(instance, activation_token, now)
 
         generation = instance.activation_generation + 1
         expires_at = now + duration
         instance.update!(
           activation_owner_id: owner_id,
+          activation_token:,
           activation_expires_at: expires_at,
           activation_generation: generation,
           activated_at: now,
@@ -24,23 +26,25 @@ module SolidObjects
         new(
           instance_id: instance.id,
           owner_id:,
+          activation_token:,
           generation:,
           expires_at:,
           database_adapter:
         )
       end
 
-      # @rbs (instance_id: Integer, owner_id: String, ?duration: Numeric, ?database_adapter: DatabaseAdapter) -> Lease?
+      # @rbs (instance_id: Integer, owner_id: String, ?activation_token: String, ?duration: Numeric, ?database_adapter: DatabaseAdapter) -> Lease?
       def acquire(
         instance_id:,
         owner_id:,
+        activation_token: SecureRandom.uuid,
         duration: SolidObjects.configuration.lease_duration,
         database_adapter: SolidObjects.database_adapter
       )
         lease = database_adapter.transaction do
           instance = Instance.lock.find(instance_id)
           now = database_adapter.database_now
-          claim(instance:, owner_id:, now:, duration:, database_adapter:)
+          claim(instance:, owner_id:, activation_token:, now:, duration:, database_adapter:)
         end
 
         if lease
@@ -58,9 +62,9 @@ module SolidObjects
       private
 
       # @rbs (Instance, String, Time) -> bool
-      def held_by_another_live_owner?(instance, owner_id, now)
+      def held_by_another_live_owner?(instance, activation_token, now)
         instance.activation_owner_id.present? &&
-          instance.activation_owner_id != owner_id &&
+          instance.activation_token != activation_token &&
           instance.activation_expires_at.present? &&
           instance.activation_expires_at > now
       end
@@ -68,16 +72,18 @@ module SolidObjects
 
     # @rbs @instance_id: Integer
     # @rbs @owner_id: String
+    # @rbs @activation_token: String
     # @rbs @generation: Integer
     # @rbs @expires_at: Time
     # @rbs @database_adapter: DatabaseAdapter
 
-    attr_reader :instance_id, :owner_id, :generation, :expires_at
+    attr_reader :instance_id, :owner_id, :activation_token, :generation, :expires_at
 
-    # @rbs (instance_id: Integer, owner_id: String, generation: Integer, expires_at: Time, database_adapter: DatabaseAdapter) -> void
-    def initialize(instance_id:, owner_id:, generation:, expires_at:, database_adapter:)
+    # @rbs (instance_id: Integer, owner_id: String, activation_token: String, generation: Integer, expires_at: Time, database_adapter: DatabaseAdapter) -> void
+    def initialize(instance_id:, owner_id:, activation_token:, generation:, expires_at:, database_adapter:)
       @instance_id = instance_id
       @owner_id = owner_id
+      @activation_token = activation_token
       @generation = generation
       @expires_at = expires_at
       @database_adapter = database_adapter
@@ -95,6 +101,7 @@ module SolidObjects
         self.class.new(
           instance_id:,
           owner_id:,
+          activation_token:,
           generation:,
           expires_at: renewed_expiration,
           database_adapter:
@@ -117,7 +124,11 @@ module SolidObjects
         next false unless instance
         next false unless owned_generation?(instance)
 
-        instance.update!(activation_owner_id: nil, activation_expires_at: nil)
+        instance.update!(
+          activation_owner_id: nil,
+          activation_token: nil,
+          activation_expires_at: nil
+        )
         true
       end
 
@@ -159,6 +170,7 @@ module SolidObjects
     # @rbs (Instance) -> bool
     def owned_generation?(instance)
       instance.activation_owner_id == owner_id &&
+        instance.activation_token == activation_token &&
         instance.activation_generation == generation
     end
 

data/lib/solid_objects/message_reference.rb

@@ -36,6 +36,7 @@ module SolidObjects
     # @rbs () -> String
     def status
       message = Message.find(id)
+      return "rejected" if message.rejected?
       return "completed" if message.completed?
       return "dead" if message.dead?
       return "claimed" if message.claimed?

data/lib/solid_objects/process_registry.rb

@@ -22,9 +22,13 @@ module SolidObjects
         SolidObjects.database_adapter.transaction do
           Instance.where(activation_owner_id: process_record.id).update_all(
             activation_owner_id: nil,
+            activation_token: nil,
             activation_expires_at: nil
           )
-          ClaimedMessage.where(process_id: process_record.id).update_all(process_id: nil)
+          ClaimedMessage.where(process_id: process_record.id).update_all(
+            process_id: nil,
+            activation_token: nil
+          )
           Effect.where(claimed_by: process_record.id).update_all(
             status: "pending",
             claimed_by: nil,

data/lib/solid_objects/reference.rb

@@ -16,19 +16,20 @@ module SolidObjects
       freeze
     end
 
-    # @rbs (Symbol | String, ?available_at: Time?, ?idempotency_key: String?, ?authorization_context: untyped, **untyped) -> (MessageReference | Actor::OutboundMessageIntent)
-    def tell(message_name, available_at: nil, idempotency_key: nil, authorization_context: nil, **arguments)
+    # @rbs (Symbol | String, ?available_at: Time?, ?idempotency_key: String?, ?authorization_context: untyped, **untyped) -> MessageReference?
+    def async(message_name, available_at: nil, idempotency_key: nil, authorization_context: nil, **arguments)
       if (actor = Context.current_actor)
-        return actor.stage_outbound_message(
+        actor.stage_outbound_message(
           self,
           message_name,
           arguments,
           available_at:,
           idempotency_key:
         )
+        return
       end
 
-      SolidObjects.client.tell(
+      SolidObjects.client.async(
         self,
         message_name,
         arguments,
@@ -39,10 +40,10 @@ module SolidObjects
     end
 
     # @rbs (Symbol | String, ?timeout: Numeric, ?idempotency_key: String?, ?authorization_context: untyped, **untyped) -> untyped
-    def ask(message_name, timeout: 5.seconds, idempotency_key: nil, authorization_context: nil, **arguments)
+    def sync(message_name, timeout: 5.seconds, idempotency_key: nil, authorization_context: nil, **arguments)
       raise ActorCallCycle, "actors cannot synchronously wait for another actor" if Context.current_actor
 
-      SolidObjects.client.ask(
+      SolidObjects.client.sync(
         self,
         message_name,
         arguments,
@@ -60,8 +61,7 @@ module SolidObjects
     # @rbs (Symbol, *untyped, **untyped) -> untyped
     def method_missing(name, *arguments, **keywords)
       return super if arguments.any? || block_given?
-      return tell(name, **keywords) if actor_message?(name)
-      return Serialization.readonly_copy(ask(name, **keywords)) if actor_query?(name)
+      return sync(name, **keywords) if actor_message?(name) || actor_query?(name)
 
       super
     end

data/lib/solid_objects/synchronous_invocation.rb

@@ -0,0 +1,93 @@
+# rbs_inline: enabled
+
+require "solid_objects/activation_manager"
+require "solid_objects/lease_renewer"
+
+module SolidObjects
+  class SynchronousInvocation
+    # @rbs (MessageReference, timeout: Numeric) -> untyped
+    def call(message_reference, timeout:)
+      deadline = monotonic_now + timeout.to_f
+
+      loop do
+        message = load_message(message_reference)
+        return completed_result(message) if message.completed? || message.dead?
+
+        remaining = deadline - monotonic_now
+        unless remaining.positive?
+          raise SyncTimeout, "actor invocation timed out after #{timeout} seconds"
+        end
+
+        processed = assist(message, deadline:)
+        wait(remaining) if processed.zero?
+      end
+    rescue ActiveRecord::RecordNotFound
+      raise ActorDestroyed, "actor was destroyed while waiting for its result"
+    end
+
+    private
+
+    # @rbs (MessageReference) -> Message
+    def load_message(message_reference)
+      Message.uncached { Message.find(message_reference.id) }
+    end
+
+    # @rbs (Message) -> untyped
+    def completed_result(message)
+      raise_rejection(message) if message.rejected?
+      if message.dead?
+        raise MessageFailed.new(
+          "actor message failed permanently",
+          message_id: message.id,
+          details: message.error || {}
+        )
+      end
+
+      Serialization.readonly_copy(message.result)
+    end
+
+    # @rbs (Message) -> bot
+    def raise_rejection(message)
+      rejection = message.rejection
+      raise Rejected.new(
+        code: rejection.fetch("code"),
+        message: rejection.fetch("message"),
+        details: rejection.fetch("details"),
+        message_id: message.id
+      )
+    end
+
+    # @rbs (Message, deadline: Float) -> Integer
+    def assist(message, deadline:)
+      process_registry = SolidObjects.caller_process.process_registry
+      activation = ActivationManager
+        .new(owner_id: process_registry.process_record.id)
+        .claim(instance_id: message.instance_id)
+      return 0 unless activation
+
+      LeaseRenewer.new(
+        activation:,
+        process_registry:
+      ).around do
+        activation.drain_until(message_id: message.id, deadline:)
+      end
+    ensure
+      if activation
+        activation.yield_ready_messages if activation.pass_exhausted?
+        activation.deactivate
+      end
+    end
+
+    # @rbs (Numeric) -> void
+    def wait(remaining)
+      SolidObjects.wake_up.wait(
+        timeout: [ remaining, SolidObjects.configuration.sync_polling_interval ].min
+      )
+    end
+
+    # @rbs () -> Float
+    def monotonic_now
+      ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/solid_objects/version.rb

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

data/lib/solid_objects.rb

@@ -78,6 +78,12 @@ module SolidObjects
       @client ||= Client.new
     end
 
+    # @rbs () -> CallerProcess
+    def caller_process
+      require "solid_objects/caller_process"
+      @caller_process ||= CallerProcess.new
+    end
+
     # @rbs () -> DeadLetterManager
     def dead_letters
       @dead_letters ||= DeadLetterManager.new
@@ -100,6 +106,7 @@ module SolidObjects
       @client = nil
       @database_adapter = nil
       @wake_up = nil
+      @caller_process = nil
       @effect_registry = EffectRegistry.new
       @dead_letters = nil
     end

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

@@ -22,6 +22,9 @@ module SolidObjects
     # @rbs () -> Integer
     def drain: () -> Integer
 
+    # @rbs (message_id: Integer, deadline: Float) -> Integer
+    def drain_until: (message_id: Integer, deadline: Float) -> Integer
+
     # @rbs () -> bool
     def ready?: () -> bool
 
@@ -50,6 +53,9 @@ module SolidObjects
 
     attr_reader actor_class: untyped
 
+    # @rbs (?message_id: Integer?, ?deadline: Float?) -> Integer
+    def drain_messages: (?message_id: Integer?, ?deadline: Float?) -> Integer
+
     # @rbs (Instance) -> Actor
     def build_actor: (Instance) -> Actor
 

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

@@ -12,12 +12,18 @@ module SolidObjects
     # @rbs () -> Activation?
     def claim_next: () -> Activation?
 
+    # @rbs (instance_id: Integer) -> Activation?
+    def claim: (instance_id: Integer) -> Activation?
+
     private
 
     attr_reader owner_id: untyped
 
     attr_reader database_adapter: untyped
 
+    # @rbs (Array[Integer]) -> Activation?
+    def claim_from: (Array[Integer]) -> Activation?
+
     # @rbs (Time) -> Array[Integer]
     def candidate_instance_ids: (Time) -> Array[Integer]