solid_objects 0.1.0

data/lib/solid_objects/engine.rb

@@ -0,0 +1,33 @@
+# rbs_inline: enabled
+
+require_relative "../../app/models/solid_objects/record"
+
+module SolidObjects
+  class Engine < ::Rails::Engine
+    isolate_namespace SolidObjects
+
+    config.generators do |generators|
+      generators.test_framework :minitest
+    end
+
+    initializer "solid_objects.configuration" do
+      SolidObjects.configuration.validate!
+      SolidObjects::LogSubscriber.install
+    end
+
+    initializer "solid_objects.database", after: :load_config_initializers do
+      SolidObjects::Record.configure_connection
+    end
+
+    initializer "solid_objects.helpers" do
+      ActiveSupport.on_load(:action_view) do
+        include SolidObjects::ActorHelper
+      end
+    end
+
+    rake_tasks do
+      tasks_path = File.expand_path("../tasks", __dir__)
+      Dir[File.join(tasks_path, "**/*.rake")].sort.each { |task| load task }
+    end
+  end
+end

data/lib/solid_objects/errors.rb

@@ -0,0 +1,65 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  class Error < StandardError
+  end
+
+  class UnsupportedDatabase < Error
+  end
+
+  class InvalidActor < Error
+  end
+
+  class UnknownActorType < Error
+  end
+
+  class UnknownMessage < Error
+  end
+
+  class InvalidPayload < Error
+  end
+
+  class PayloadTooLarge < InvalidPayload
+  end
+
+  class MailboxFull < Error
+  end
+
+  class IdempotencyConflict < Error
+  end
+
+  class Unauthorized < Error
+  end
+
+  class InvalidStreamToken < Error
+  end
+
+  class LostActivation < Error
+  end
+
+  class ActorDestroyed < LostActivation
+  end
+
+  class AskTimeout < Error
+  end
+
+  class MessageFailed < Error
+    # @rbs @message_id: Integer
+    # @rbs @details: Hash[String, untyped]
+
+    attr_reader :message_id, :details
+
+    # @rbs (String, message_id: Integer, details: Hash[String, untyped]) -> void
+    def initialize(message, message_id:, details:)
+      @message_id = message_id
+      @details = details
+      super(message)
+    end
+  end
+
+  class StateMigrationError < Error
+  end
+
+  class ActorCallCycle < Error
+  end
+end

data/lib/solid_objects/executor.rb

@@ -0,0 +1,290 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  class Executor
+    # @rbs @activation: Activation
+    # @rbs @message: Message
+
+    # @rbs (activation: Activation, message: Message) -> void
+    def initialize(activation:, message:)
+      @activation = activation
+      @message = message
+    end
+
+    # @rbs () -> bool
+    def call
+      state_before = actor.state.to_h
+      observables_before = actor.observable_values
+      message_context = MessageContext.new(
+        id: message.id,
+        attempt: message.attempt_count,
+        enqueued_at: message.enqueued_at,
+        idempotency_key: message.idempotency_key,
+        request_id: message.request_id
+      )
+
+      SolidObjects.instrument(:"message.started", **instrumentation_payload)
+      result = Context.with(actor:, message: message_context) do
+        actor.invoke(message.message_name, message.arguments)
+      end
+      ensure_query_did_not_mutate_state!(state_before)
+      observable_changes = changed_observables(observables_before, actor.observable_values)
+      complete(result, observable_changes)
+      true
+    rescue LostActivation
+      raise
+    rescue => error
+      activation.restore_state(state_before) if state_before
+      actor.discard_intents
+      fail_message(error)
+      false
+    end
+
+    private
+
+    attr_reader :activation, :message
+
+    # @rbs () -> Actor
+    def actor
+      activation.actor
+    end
+
+    # @rbs (Hash[String, untyped]) -> void
+    def ensure_query_did_not_mutate_state!(state_before)
+      return unless message.message_kind == "ask"
+      return unless actor.class.definition.queries.key?(message.message_name.to_sym)
+      return if actor.state.to_h == state_before
+
+      raise InvalidActor, "query #{message.message_name.inspect} mutated actor state"
+    end
+
+    # @rbs (Hash[String, untyped], Hash[String, untyped]) -> Hash[String, untyped]
+    def changed_observables(before, after)
+      after.each_with_object({}) do |(name, value), changes|
+        changes[name] = value unless before[name] == value
+      end
+    end
+
+    # @rbs (untyped, Hash[String, untyped]) -> void
+    def complete(result, observable_changes)
+      serialized_state = Serialization.dump(
+        actor.state.to_h,
+        max_bytes: SolidObjects.configuration.max_state_bytes
+      )
+      serialized_result = Serialization.dump(
+        (message.message_kind == "ask") ? result : nil,
+        max_bytes: SolidObjects.configuration.max_result_bytes
+      )
+      effect_intents = actor.drain_effect_intents
+      reminder_intents = actor.drain_reminder_intents
+      outbound_message_intents = actor.drain_outbound_message_intents
+      enqueued_effects = []
+
+      activation.lease.fenced_transaction do |instance|
+        claimed_message = matching_claim!
+        locked_message = Message.lock.find(message.id)
+        instance.update!(
+          state: serialized_state,
+          state_version: actor.class.state_version,
+          last_used_at: SolidObjects.database_adapter.database_now
+        )
+        locked_message.update!(
+          result: serialized_result,
+          error: nil,
+          completed_at: SolidObjects.database_adapter.database_now
+        )
+        enqueued_effects.concat(enqueue_effects(locked_message, instance, effect_intents))
+        schedule_reminders(instance, reminder_intents)
+        enqueued_effects.concat(
+          enqueue_actor_messages(locked_message, instance, outbound_message_intents)
+        )
+        enqueue_broadcasts(locked_message, instance, observable_changes)
+        claimed_message.destroy!
+      end
+
+      observable_changes.each_key do |observable_name|
+        SolidObjects.instrument(
+          :"broadcast.enqueued",
+          **instrumentation_payload,
+          observable_name:
+        )
+      end
+      enqueued_effects.each do |effect|
+        SolidObjects.instrument(
+          :"effect.enqueued",
+          effect_id: effect.effect_id,
+          effect_name: effect.name,
+          message_id: effect.message_id,
+          actor_type: message.actor_type,
+          actor_id: message.actor_id
+        )
+      end
+      SolidObjects.instrument(:"message.completed", **instrumentation_payload)
+      SolidObjects.wake_up.signal
+    end
+
+    # @rbs (Message, Instance, Array[Actor::EffectIntent]) -> Array[Effect]
+    def enqueue_effects(locked_message, instance, intents)
+      intents.map do |intent|
+        Effect.create!(
+          message: locked_message,
+          instance:,
+          effect_id: SecureRandom.uuid,
+          name: intent.name,
+          arguments: intent.arguments,
+          success_message_name: intent.success_message_name,
+          failure_message_name: intent.failure_message_name,
+          status: "pending",
+          max_attempts: SolidObjects.configuration.max_attempts,
+          available_at: SolidObjects.database_adapter.database_now
+        )
+      end
+    end
+
+    # @rbs (Instance, Array[Actor::ReminderIntent]) -> void
+    def schedule_reminders(instance, intents)
+      intents.each do |intent|
+        reminder = Reminder.find_or_initialize_by(instance:, name: intent.name)
+        reminder.assign_attributes(
+          actor_type: instance.actor_type,
+          actor_id: instance.actor_id,
+          message_name: intent.name,
+          arguments: intent.arguments,
+          next_run_at: intent.at,
+          interval_seconds: intent.interval_seconds,
+          missed_policy: intent.missed_policy,
+          status: "scheduled",
+          claimed_by: nil,
+          claimed_at: nil
+        )
+        reminder.save!
+      end
+    end
+
+    # @rbs (Message, Instance, Array[Actor::OutboundMessageIntent]) -> Array[Effect]
+    def enqueue_actor_messages(locked_message, instance, intents)
+      intents.map do |intent|
+        Effect.create!(
+          message: locked_message,
+          instance:,
+          effect_id: SecureRandom.uuid,
+          name: EffectExecutor::ACTOR_MESSAGE_EFFECT,
+          arguments: {
+            "actor_type" => intent.actor_type,
+            "actor_id" => intent.actor_id,
+            "message_name" => intent.message_name,
+            "arguments" => intent.arguments,
+            "available_at" => intent.available_at&.iso8601(6),
+            "idempotency_key" => intent.idempotency_key
+          },
+          status: "pending",
+          max_attempts: SolidObjects.configuration.max_attempts,
+          available_at: SolidObjects.database_adapter.database_now
+        )
+      end
+    end
+
+    # @rbs (Message, Instance, Hash[String, untyped]) -> void
+    def enqueue_broadcasts(locked_message, instance, observable_changes)
+      observable_changes.each do |observable_name, value|
+        Broadcast.create!(
+          message: locked_message,
+          instance:,
+          broadcast_id: SecureRandom.uuid,
+          observable_name:,
+          value:,
+          state_version: actor.class.state_version,
+          activation_generation: activation.lease.generation,
+          status: "pending",
+          available_at: SolidObjects.database_adapter.database_now
+        )
+      end
+    end
+
+    # @rbs (Exception) -> void
+    def fail_message(error)
+      error_details = serialized_error(error)
+      dead = false
+
+      activation.lease.fenced_transaction do
+        claimed_message = matching_claim!
+        locked_message = Message.lock.find(message.id)
+        now = SolidObjects.database_adapter.database_now
+        locked_message.update!(error: error_details, last_failed_at: now)
+        claimed_message.destroy!
+
+        if locked_message.attempt_count >= locked_message.max_attempts
+          create_dead_letter(locked_message, error_details, now)
+          dead = true
+        else
+          ReadyMessage.create!(
+            message: locked_message,
+            instance: locked_message.instance,
+            sequence: locked_message.sequence,
+            available_at: now + SolidObjects.configuration.retry_delay.call(locked_message.attempt_count)
+          )
+        end
+      end
+
+      SolidObjects.instrument(
+        :"message.failed",
+        **instrumentation_payload,
+        error_class: error.class.name,
+        dead:
+      )
+      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_generation: activation.lease.generation
+      )
+    rescue ActiveRecord::RecordNotFound
+      raise LostActivation, "message claim changed"
+    end
+
+    # @rbs (Exception) -> Hash[String, untyped]
+    def serialized_error(error)
+      Serialization.dump(
+        {
+          "class" => error.class.name,
+          "message" => error.message.to_s.byteslice(0, 8_192),
+          "backtrace" => Array(error.backtrace).first(50)
+        }
+      )
+    end
+
+    # @rbs (Message, Hash[String, untyped], Time) -> DeadLetter
+    def create_dead_letter(locked_message, error_details, now)
+      DeadLetter.create!(
+        message: locked_message,
+        instance: locked_message.instance,
+        actor_type: locked_message.actor_type,
+        actor_id: locked_message.actor_id,
+        message_name: locked_message.message_name,
+        arguments: locked_message.arguments,
+        attempts: locked_message.attempt_count,
+        exception_class: error_details.fetch("class"),
+        exception_message: error_details.fetch("message"),
+        backtrace: error_details.fetch("backtrace"),
+        first_failed_at: locked_message.last_failed_at || now,
+        last_failed_at: now
+      )
+    end
+
+    # @rbs () -> Hash[Symbol, untyped]
+    def instrumentation_payload
+      {
+        message_id: message.id,
+        actor_type: message.actor_type,
+        actor_id: message.actor_id,
+        sequence: message.sequence,
+        attempt: message.attempt_count,
+        request_id: message.request_id
+      }
+    end
+  end
+end

data/lib/solid_objects/instrumentation.rb

@@ -0,0 +1,10 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  module Instrumentation
+    # @rbs (Symbol, **untyped) { (Hash[Symbol, untyped]) -> untyped } -> untyped
+    def instrument(event, **payload, &block)
+      ActiveSupport::Notifications.instrument("solid_objects.#{event}", payload, &block)
+    end
+  end
+end

data/lib/solid_objects/lease.rb

@@ -0,0 +1,172 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  class Lease
+    class << self
+      # @rbs (instance: Instance, owner_id: String, now: Time, ?duration: Numeric, database_adapter: DatabaseAdapter) -> Lease?
+      def claim(
+        instance:,
+        owner_id:,
+        now:,
+        database_adapter:, duration: SolidObjects.configuration.lease_duration
+      )
+        return if held_by_another_live_owner?(instance, owner_id, now)
+
+        generation = instance.activation_generation + 1
+        expires_at = now + duration
+        instance.update!(
+          activation_owner_id: owner_id,
+          activation_expires_at: expires_at,
+          activation_generation: generation,
+          activated_at: now,
+          last_claimed_at: now
+        )
+        new(
+          instance_id: instance.id,
+          owner_id:,
+          generation:,
+          expires_at:,
+          database_adapter:
+        )
+      end
+
+      # @rbs (instance_id: Integer, owner_id: String, ?duration: Numeric, ?database_adapter: DatabaseAdapter) -> Lease?
+      def acquire(
+        instance_id:,
+        owner_id:,
+        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:)
+        end
+
+        if lease
+          SolidObjects.instrument(
+            :"activation.claimed",
+            instance_id:,
+            owner_id:,
+            generation: lease.generation
+          )
+        end
+
+        lease
+      end
+
+      private
+
+      # @rbs (Instance, String, Time) -> bool
+      def held_by_another_live_owner?(instance, owner_id, now)
+        instance.activation_owner_id.present? &&
+          instance.activation_owner_id != owner_id &&
+          instance.activation_expires_at.present? &&
+          instance.activation_expires_at > now
+      end
+    end
+
+    # @rbs @instance_id: Integer
+    # @rbs @owner_id: String
+    # @rbs @generation: Integer
+    # @rbs @expires_at: Time
+    # @rbs @database_adapter: DatabaseAdapter
+
+    attr_reader :instance_id, :owner_id, :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:)
+      @instance_id = instance_id
+      @owner_id = owner_id
+      @generation = generation
+      @expires_at = expires_at
+      @database_adapter = database_adapter
+    end
+
+    # @rbs (?duration: Numeric) -> Lease
+    def renew(duration: SolidObjects.configuration.lease_duration)
+      renewed_lease = database_adapter.transaction do
+        instance = locked_owned_instance!
+        now = database_adapter.database_now
+        verify_unexpired!(instance, now)
+        renewed_expiration = now + duration
+        instance.update!(activation_expires_at: renewed_expiration)
+
+        self.class.new(
+          instance_id:,
+          owner_id:,
+          generation:,
+          expires_at: renewed_expiration,
+          database_adapter:
+        )
+      end
+      SolidObjects.instrument(
+        :"activation.renewed",
+        instance_id:,
+        owner_id:,
+        generation:,
+        expires_at: renewed_lease.expires_at
+      )
+      renewed_lease
+    end
+
+    # @rbs () -> bool
+    def release
+      released = database_adapter.transaction do
+        instance = Instance.lock.find_by(id: instance_id)
+        next false unless instance
+        next false unless owned_generation?(instance)
+
+        instance.update!(activation_owner_id: nil, activation_expires_at: nil)
+        true
+      end
+
+      if released
+        SolidObjects.instrument(
+          :"activation.released",
+          instance_id:,
+          owner_id:,
+          generation:
+        )
+      end
+
+      released
+    end
+
+    # @rbs () { (Instance) -> untyped } -> untyped
+    def fenced_transaction
+      database_adapter.transaction do
+        instance = locked_owned_instance!
+        verify_unexpired!(instance, database_adapter.database_now)
+        yield instance
+      end
+    end
+
+    private
+
+    attr_reader :database_adapter
+
+    # @rbs () -> Instance
+    def locked_owned_instance!
+      instance = Instance.lock.find_by(id: instance_id)
+      raise ActorDestroyed, "actor instance no longer exists" unless instance
+
+      instance.tap do
+        raise LostActivation, "activation owner or generation changed" unless owned_generation?(instance)
+      end
+    end
+
+    # @rbs (Instance) -> bool
+    def owned_generation?(instance)
+      instance.activation_owner_id == owner_id &&
+        instance.activation_generation == generation
+    end
+
+    # @rbs (Instance, Time) -> void
+    def verify_unexpired!(instance, now)
+      return if instance.activation_expires_at && instance.activation_expires_at > now
+
+      raise LostActivation, "activation lease expired"
+    end
+  end
+end

data/lib/solid_objects/lease_renewer.rb

@@ -0,0 +1,70 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  class LeaseRenewer
+    # @rbs @activation: Activation
+    # @rbs @process_registry: ProcessRegistry
+    # @rbs @mutex: Thread::Mutex
+    # @rbs @condition: Thread::ConditionVariable
+    # @rbs @stopped: bool
+    # @rbs @thread: Thread?
+
+    # @rbs (activation: Activation, process_registry: ProcessRegistry) -> void
+    def initialize(activation:, process_registry:)
+      @activation = activation
+      @process_registry = process_registry
+      @mutex = Thread::Mutex.new
+      @condition = Thread::ConditionVariable.new
+      @stopped = false
+      @thread = nil
+    end
+
+    # @rbs () { () -> untyped } -> untyped
+    def around
+      start
+      yield
+    ensure
+      stop
+    end
+
+    private
+
+    attr_reader :activation, :process_registry, :mutex, :condition
+
+    # @rbs () -> void
+    def start
+      @thread = Thread.new do
+        loop do
+          break if wait_for_interval
+
+          activation.renew_lease
+          process_registry.heartbeat
+        rescue LostActivation
+          break
+        end
+      end
+    end
+
+    # @rbs () -> bool
+    def wait_for_interval
+      mutex.synchronize do
+        unless @stopped
+          condition.wait(
+            mutex,
+            SolidObjects.configuration.lease_renewal_interval
+          )
+        end
+        @stopped
+      end
+    end
+
+    # @rbs () -> void
+    def stop
+      mutex.synchronize do
+        @stopped = true
+        condition.broadcast
+      end
+      @thread&.join
+    end
+  end
+end

data/lib/solid_objects/log_subscriber.rb

@@ -0,0 +1,29 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  module LogSubscriber
+    class << self
+      # @rbs () -> void
+      def install
+        return if @subscription
+
+        @subscription = ActiveSupport::Notifications.subscribe(/\Asolid_objects\./) do |event|
+          SolidObjects.configuration.logger.info(
+            {
+              event: event.name,
+              duration_ms: event.duration.round(2)
+            }.merge(event.payload)
+          )
+        end
+      end
+
+      # @rbs () -> void
+      def uninstall
+        return unless @subscription
+
+        ActiveSupport::Notifications.unsubscribe(@subscription)
+        @subscription = nil
+      end
+    end
+  end
+end