solid_objects 0.1.0 → 0.2.1

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

@@ -0,0 +1,311 @@
+# rbs_inline: enabled
+
+require "solid_objects/mailbox"
+require "solid_objects/synchronous_invocation"
+
+module SolidObjects
+  class Doctor
+    class Check
+      # @rbs @name: Symbol
+      # @rbs @status: Symbol
+      # @rbs @message: String
+
+      attr_reader :name, :status, :message
+
+      # @rbs (name: Symbol, status: Symbol, message: String) -> void
+      def initialize(name:, status:, message:)
+        @name = name
+        @status = status
+        @message = message
+        freeze
+      end
+
+      # @rbs () -> bool
+      def failed?
+        status == :fail
+      end
+    end
+
+    class Report
+      # @rbs @checks: Array[Check]
+
+      attr_reader :checks
+
+      # @rbs (checks: Array[Check]) -> void
+      def initialize(checks:)
+        @checks = checks.freeze
+        freeze
+      end
+
+      # @rbs () -> bool
+      def healthy?
+        checks.none?(&:failed?)
+      end
+
+      # @rbs (Symbol) -> Check
+      def check(name)
+        checks.find { |candidate| candidate.name == name } ||
+          raise(KeyError, "unknown doctor check #{name.inspect}")
+      end
+
+      # @rbs () -> String
+      def to_s
+        lines = [ "Solid Objects doctor #{SolidObjects::VERSION}" ]
+        lines.concat(
+          checks.map do |check|
+            "#{check.status.to_s.upcase.ljust(4)} #{check.name}: #{check.message}"
+          end
+        )
+        lines.join("\n")
+      end
+    end
+
+    EXPECTED_COLUMNS = {
+      processes: %w[id kind hostname pid last_heartbeat_at shutdown_state],
+      instances: %w[
+        id actor_type actor_id state state_version next_message_sequence
+        activation_owner_id activation_token activation_expires_at
+        activation_generation
+      ],
+      messages: %w[
+        id instance_id message_kind arguments sequence attempt_count request_id
+        result error rejection completed_at rejected_at
+      ],
+      ready_messages: %w[id message_id instance_id sequence available_at],
+      claimed_messages: %w[
+        id message_id instance_id process_id activation_token
+        activation_generation claimed_at
+      ],
+      reminders: %w[id instance_id message_name next_run_at status],
+      effects: %w[id message_id instance_id effect_id status available_at],
+      broadcasts: %w[id message_id instance_id broadcast_id status available_at],
+      dead_letters: %w[id message_id instance_id actor_type actor_id attempts]
+    }.freeze
+
+    class ProbeActor < Actor
+      actor_type "solid_objects_doctor"
+
+      # @rbs (value: String) -> String
+      def ping(value:)
+        value
+      end
+    end
+
+    # @rbs @connection: untyped
+    # @rbs @configuration: Configuration
+
+    # @rbs (?connection: untyped, ?configuration: Configuration) -> void
+    def initialize(
+      connection: SolidObjects::Record.connection,
+      configuration: SolidObjects.configuration
+    )
+      @connection = connection
+      @configuration = configuration
+    end
+
+    # @rbs () -> Report
+    def call
+      configuration_check = check_configuration
+      schema_check = check_schema
+      checks = [
+        configuration_check,
+        schema_check,
+        check_authorization,
+        schema_check.failed? ? skipped_runtime : check_runtime,
+        ready_for_round_trip?(configuration_check, schema_check) ?
+          check_sync_round_trip :
+          skipped_round_trip
+      ]
+      Report.new(checks:)
+    end
+
+    private
+
+    attr_reader :connection, :configuration
+
+    # @rbs () -> Check
+    def check_configuration
+      configuration.validate!
+      pass(:configuration, "configuration is valid")
+    rescue => error
+      fail_check(:configuration, "#{error.class}: #{error.message}")
+    end
+
+    # @rbs () -> Check
+    def check_schema
+      missing_tables = expected_table_names - connection.data_sources
+      unless missing_tables.empty?
+        return fail_check(:schema, "missing tables: #{missing_tables.join(", ")}")
+      end
+
+      missing_columns = EXPECTED_COLUMNS.each_with_object([]) do |(name, expected), missing|
+        table_name = SolidObjects.table_name(name)
+        actual = connection.columns(table_name).map(&:name)
+        (expected - actual).each { |column| missing << "#{table_name}.#{column}" }
+      end
+      unless missing_columns.empty?
+        return fail_check(:schema, "missing columns: #{missing_columns.join(", ")}")
+      end
+
+      pass(:schema, "schema matches the #{SolidObjects::VERSION} runtime")
+    rescue => error
+      fail_check(:schema, "#{error.class}: #{error.message}")
+    end
+
+    # @rbs () -> Check
+    def check_authorization
+      outcomes = policy_probes.to_h do |name, arguments|
+        outcome = configuration.public_send(name).call(**arguments) ? :allow : :deny
+        [ name, outcome ]
+      rescue
+        [ name, :unknown ]
+      end
+      allowed = outcomes.select { |_, outcome| outcome == :allow }.keys
+      unknown = outcomes.select { |_, outcome| outcome == :unknown }.keys
+
+      if allowed.empty? && unknown.empty?
+        return warn_check(
+          :authorization,
+          "all five policies denied a neutral context; review the generated initializer before use"
+        )
+      end
+      risky = allowed & %i[
+        authorize_destroy
+        authorize_subscription
+        authorize_administration
+      ]
+      unless risky.empty?
+        return warn_check(
+          :authorization,
+          "sensitive policies allowed a neutral context: #{risky.join(", ")}"
+        )
+      end
+      unless unknown.empty?
+        return warn_check(
+          :authorization,
+          "#{allowed.length} of 5 policies allowed a neutral context; " \
+            "#{unknown.join(", ")} could not evaluate without application context"
+        )
+      end
+
+      pass(:authorization, "#{allowed.length} of 5 policies allowed a neutral context")
+    end
+
+    # @rbs () -> Check
+    def check_runtime
+      cutoff = SolidObjects.database_adapter.database_now -
+        configuration.process_alive_threshold
+      counts = Process
+        .where(shutdown_state: "running", last_heartbeat_at: cutoff..)
+        .group(:kind)
+        .count
+      if counts.empty?
+        return info(
+          :runtime,
+          "no live runtime roles; workerless synchronous calls are available, asynchronous features are not"
+        )
+      end
+
+      summary = counts.sort.map { |kind, count| "#{kind}=#{count}" }.join(", ")
+      pass(:runtime, "live runtime roles: #{summary}")
+    rescue => error
+      fail_check(:runtime, "#{error.class}: #{error.message}")
+    end
+
+    # @rbs () -> Check
+    def check_sync_round_trip
+      actor_id = SecureRandom.uuid
+      value = SecureRandom.hex(8)
+      process_registry = SolidObjects.caller_process.process_registry
+      reference = ProbeActor.ref(actor_id)
+      message_reference = Mailbox.new.enqueue(
+        reference,
+        :ping,
+        { value: },
+        kind: "sync"
+      )
+      result = SynchronousInvocation.new.call(message_reference, timeout: 5.seconds)
+      raise Error, "unexpected round-trip result" unless result == value
+
+      pass(:sync_round_trip, "durable synchronous actor call completed without a worker")
+    rescue => error
+      fail_check(:sync_round_trip, "#{error.class}: #{error.message}")
+    ensure
+      Instance.where(actor_type: ProbeActor.actor_type, actor_id:).delete_all if actor_id
+      process_registry&.stop
+      process_registry&.process_record&.delete
+    end
+
+    # @rbs (Check, Check) -> bool
+    def ready_for_round_trip?(configuration_check, schema_check)
+      !configuration_check.failed? && !schema_check.failed?
+    end
+
+    # @rbs () -> Check
+    def skipped_runtime
+      skip(:runtime, "schema check failed")
+    end
+
+    # @rbs () -> Check
+    def skipped_round_trip
+      skip(:sync_round_trip, "configuration or schema check failed")
+    end
+
+    # @rbs () -> Hash[Symbol, Hash[Symbol, untyped]]
+    def policy_probes
+      actor_arguments = {
+        actor_type: ProbeActor.actor_type,
+        actor_id: "doctor",
+        authorization_context: nil
+      }
+      {
+        authorize_message: actor_arguments.merge(
+          message_name: "ping",
+          arguments: { "value" => "doctor" }
+        ),
+        authorize_query: actor_arguments.merge(
+          message_name: "value",
+          arguments: {}
+        ),
+        authorize_destroy: actor_arguments,
+        authorize_subscription: actor_arguments,
+        authorize_administration: {
+          action: "doctor",
+          resource: "runtime",
+          resource_id: nil,
+          authorization_context: nil
+        }
+      }
+    end
+
+    # @rbs () -> Array[String]
+    def expected_table_names
+      EXPECTED_COLUMNS.keys.map { |name| SolidObjects.table_name(name) }
+    end
+
+    # @rbs (Symbol, String) -> Check
+    def pass(name, message)
+      Check.new(name:, status: :pass, message:)
+    end
+
+    # @rbs (Symbol, String) -> Check
+    def info(name, message)
+      Check.new(name:, status: :info, message:)
+    end
+
+    # @rbs (Symbol, String) -> Check
+    def warn_check(name, message)
+      Check.new(name:, status: :warn, message:)
+    end
+
+    # @rbs (Symbol, String) -> Check
+    def fail_check(name, message)
+      Check.new(name:, status: :fail, message:)
+    end
+
+    # @rbs (Symbol, String) -> Check
+    def skip(name, message)
+      Check.new(name:, status: :skip, message:)
+    end
+  end
+end

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,