solid_objects 0.1.0

data/lib/solid_objects/configuration.rb

@@ -0,0 +1,168 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  class Configuration
+    # @rbs @table_name_prefix: String
+    # @rbs @polling_interval: Float
+    # @rbs @ask_polling_interval: Float
+    # @rbs @lease_duration: Float
+    # @rbs @lease_renewal_interval: Float
+    # @rbs @idle_deactivation_timeout: Float
+    # @rbs @max_messages_per_activation_pass: Integer
+    # @rbs @max_activation_duration: Float
+    # @rbs @max_mailbox_length: Integer
+    # @rbs @claim_scan_limit: Integer
+    # @rbs @max_payload_bytes: Integer
+    # @rbs @max_state_bytes: Integer
+    # @rbs @max_result_bytes: Integer
+    # @rbs @max_attempts: Integer
+    # @rbs @retry_delay: Proc
+    # @rbs @process_heartbeat_interval: Float
+    # @rbs @process_alive_threshold: Float
+    # @rbs @shutdown_timeout: Float
+    # @rbs @worker_count: Integer
+    # @rbs @effect_worker_count: Integer
+    # @rbs @broadcast_worker_count: Integer
+    # @rbs @reminder_scheduler_count: Integer
+    # @rbs @connects_to: Hash[Symbol, untyped]?
+    # @rbs @logger: untyped
+    # @rbs @stream_signing_secret: String?
+    # @rbs @broadcast_adapter: Proc?
+    # @rbs @wake_up_adapter: untyped
+    # @rbs @authorize_message: Proc
+    # @rbs @authorize_query: Proc
+    # @rbs @authorize_destroy: Proc
+    # @rbs @authorize_subscription: Proc
+    # @rbs @authorize_administration: Proc
+
+    attr_accessor :table_name_prefix,
+      :polling_interval,
+      :ask_polling_interval,
+      :lease_duration,
+      :lease_renewal_interval,
+      :idle_deactivation_timeout,
+      :max_messages_per_activation_pass,
+      :max_activation_duration,
+      :max_mailbox_length,
+      :claim_scan_limit,
+      :max_payload_bytes,
+      :max_state_bytes,
+      :max_result_bytes,
+      :max_attempts,
+      :retry_delay,
+      :process_heartbeat_interval,
+      :process_alive_threshold,
+      :shutdown_timeout,
+      :worker_count,
+      :effect_worker_count,
+      :broadcast_worker_count,
+      :reminder_scheduler_count,
+      :connects_to,
+      :logger,
+      :stream_signing_secret,
+      :broadcast_adapter,
+      :wake_up_adapter,
+      :authorize_message,
+      :authorize_query,
+      :authorize_destroy,
+      :authorize_subscription,
+      :authorize_administration
+
+    # @rbs () -> void
+    def initialize
+      @table_name_prefix = "solid_objects_"
+      @polling_interval = 0.1
+      @ask_polling_interval = 0.05
+      @lease_duration = 30.0
+      @lease_renewal_interval = 10.0
+      @idle_deactivation_timeout = 30.0
+      @max_messages_per_activation_pass = 50
+      @max_activation_duration = 5.0
+      @max_mailbox_length = 10_000
+      @claim_scan_limit = 100
+      @max_payload_bytes = 1.megabyte
+      @max_state_bytes = 5.megabytes
+      @max_result_bytes = 1.megabyte
+      @max_attempts = 5
+      @retry_delay = ->(attempt) { [ 2**(attempt - 1), 60 ].min.to_f }
+      @process_heartbeat_interval = 15.0
+      @process_alive_threshold = 60.0
+      @shutdown_timeout = 15.0
+      @worker_count = 1
+      @effect_worker_count = 1
+      @broadcast_worker_count = 1
+      @reminder_scheduler_count = 1
+      @connects_to = nil
+      @stream_signing_secret = nil
+      @broadcast_adapter = nil
+      @wake_up_adapter = nil
+      @logger = if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+        Rails.logger
+      else
+        Logger.new($stdout)
+      end
+      @authorize_message = ->(**) { false }
+      @authorize_query = ->(**) { false }
+      @authorize_destroy = ->(**) { false }
+      @authorize_subscription = ->(**) { false }
+      @authorize_administration = ->(**) { false }
+    end
+
+    # @rbs () -> self
+    def validate!
+      unless table_name_prefix.match?(/\A[a-z][a-z0-9_]*\z/)
+        raise ArgumentError, "table_name_prefix must contain lowercase letters, digits, and underscores"
+      end
+
+      unless lease_duration > lease_renewal_interval
+        raise ArgumentError, "lease_duration must be greater than lease_renewal_interval"
+      end
+
+      component_counts.each do |name, value|
+        raise ArgumentError, "#{name} must not be negative" if value.negative?
+      end
+      if component_counts.values.sum.zero?
+        raise ArgumentError, "at least one runtime component must be configured"
+      end
+
+      positive_values.each do |name, value|
+        raise ArgumentError, "#{name} must be positive" unless value.positive?
+      end
+
+      self
+    end
+
+    private
+
+    # @rbs () -> Hash[Symbol, Numeric]
+    def positive_values
+      {
+        polling_interval:,
+        ask_polling_interval:,
+        lease_duration:,
+        lease_renewal_interval:,
+        max_messages_per_activation_pass:,
+        max_activation_duration:,
+        max_mailbox_length:,
+        claim_scan_limit:,
+        max_payload_bytes:,
+        max_state_bytes:,
+        max_result_bytes:,
+        max_attempts:,
+        process_heartbeat_interval:,
+        process_alive_threshold:,
+        shutdown_timeout:
+      }
+    end
+
+    # @rbs () -> Hash[Symbol, Integer]
+    def component_counts
+      {
+        worker_count:,
+        effect_worker_count:,
+        broadcast_worker_count:,
+        reminder_scheduler_count:
+      }
+    end
+  end
+end

data/lib/solid_objects/context.rb

@@ -0,0 +1,41 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  MessageContext = Data.define(:id, :attempt, :enqueued_at, :idempotency_key, :request_id)
+
+  module Context
+    STORAGE_KEY = :solid_objects_context
+    Frame = Data.define(:actor, :message, :authorization_context)
+
+    class << self
+      # @rbs () -> Frame?
+      def current
+        ActiveSupport::IsolatedExecutionState[STORAGE_KEY]
+      end
+
+      # @rbs () -> Actor?
+      def current_actor
+        current&.actor
+      end
+
+      # @rbs () -> MessageContext?
+      def current_message
+        current&.message
+      end
+
+      # @rbs () -> untyped
+      def authorization_context
+        current&.authorization_context
+      end
+
+      # @rbs (actor: Actor?, message: MessageContext?, authorization_context: untyped) { () -> untyped } -> untyped
+      def with(actor:, message:, authorization_context: nil)
+        previous = current
+        ActiveSupport::IsolatedExecutionState[STORAGE_KEY] = Frame.new(actor:, message:, authorization_context:)
+        yield
+      ensure
+        ActiveSupport::IsolatedExecutionState[STORAGE_KEY] = previous
+      end
+    end
+  end
+end

data/lib/solid_objects/database_adapter.rb

@@ -0,0 +1,82 @@
+# rbs_inline: enabled
+
+require "time"
+
+module SolidObjects
+  class DatabaseAdapter
+    class << self
+      # @rbs (untyped) -> DatabaseAdapter
+      def for(connection)
+        case connection.adapter_name
+        when /postgres/i
+          DatabaseAdapters::Postgresql.new(connection)
+        when /mysql/i
+          DatabaseAdapters::Mysql.new(connection)
+        when /sqlite/i
+          DatabaseAdapters::Sqlite.new(connection)
+        else
+          raise UnsupportedDatabase, "unsupported database adapter #{connection.adapter_name.inspect}"
+        end
+      end
+    end
+
+    # @rbs @connection_pool: untyped
+    # @rbs @fixed_connection: untyped
+
+    # @rbs (untyped) -> void
+    def initialize(connection)
+      @connection_pool = connection.respond_to?(:pool) ? connection.pool : nil
+      @fixed_connection = connection_pool ? nil : connection
+    end
+
+    # @rbs () -> bool
+    def supports_skip_locked?
+      false
+    end
+
+    # @rbs () -> String?
+    def claim_lock
+      nil
+    end
+
+    # @rbs () -> String
+    def current_time_expression
+      "CURRENT_TIMESTAMP"
+    end
+
+    # @rbs () -> Time
+    def database_now
+      value = with_connection do |connection|
+        connection.select_value("SELECT #{current_time_expression}")
+      end
+      value.is_a?(Time) ? value.utc : Time.parse("#{value} UTC").utc
+    end
+
+    # @rbs () { () -> untyped } -> untyped
+    def transaction(&block)
+      with_connection do |connection|
+        connection.transaction(requires_new: true, &block)
+      end
+    end
+
+    # @rbs (ActiveRecord::Relation[untyped]) -> ActiveRecord::Relation[untyped]
+    def lock_candidates(relation)
+      claim_lock ? relation.lock(claim_lock) : relation
+    end
+
+    private
+
+    attr_reader :connection_pool, :fixed_connection
+
+    # @rbs () { (untyped) -> untyped } -> untyped
+    def with_connection
+      return yield fixed_connection unless connection_pool
+
+      connection_pool.with_connection { |connection| yield connection }
+    end
+  end
+end
+
+require "solid_objects/database_adapters/postgresql"
+require "solid_objects/database_adapters/mysql"
+require "solid_objects/database_adapters/sqlite"

data/lib/solid_objects/database_adapters/mysql.rb

@@ -0,0 +1,22 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  module DatabaseAdapters
+    class Mysql < DatabaseAdapter
+      # @rbs () -> bool
+      def supports_skip_locked?
+        true
+      end
+
+      # @rbs () -> String
+      def claim_lock
+        "FOR UPDATE SKIP LOCKED"
+      end
+
+      # @rbs () -> String
+      def current_time_expression
+        "CURRENT_TIMESTAMP(6)"
+      end
+    end
+  end
+end

data/lib/solid_objects/database_adapters/postgresql.rb

@@ -0,0 +1,17 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  module DatabaseAdapters
+    class Postgresql < DatabaseAdapter
+      # @rbs () -> bool
+      def supports_skip_locked?
+        true
+      end
+
+      # @rbs () -> String
+      def claim_lock
+        "FOR UPDATE SKIP LOCKED"
+      end
+    end
+  end
+end

data/lib/solid_objects/database_adapters/sqlite.rb

@@ -0,0 +1,12 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  module DatabaseAdapters
+    class Sqlite < DatabaseAdapter
+      # @rbs () -> String
+      def current_time_expression
+        "STRFTIME('%Y-%m-%d %H:%M:%f', 'NOW')"
+      end
+    end
+  end
+end

data/lib/solid_objects/dead_letter_manager.rb

@@ -0,0 +1,47 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  class DeadLetterManager
+    # @rbs (?authorization_context: untyped) -> ActiveRecord::Relation[DeadLetter]
+    def all(authorization_context: nil)
+      authorize!(:inspect, authorization_context:)
+      DeadLetter.order(last_failed_at: :desc, id: :desc)
+    end
+
+    # @rbs (Integer, ?authorization_context: untyped) -> MessageReference
+    def retry(dead_letter_id, authorization_context: nil)
+      authorize!(:retry, authorization_context:, dead_letter_id:)
+      dead_letter = DeadLetter.find(dead_letter_id)
+      return MessageReference.from_message(Message.find(dead_letter.retried_message_id)) if dead_letter.retried_message_id
+
+      original_message = dead_letter.message
+      message_reference = Mailbox.new.enqueue(
+        Reference.new(
+          actor_type: dead_letter.actor_type,
+          actor_id: dead_letter.actor_id
+        ),
+        dead_letter.message_name,
+        dead_letter.arguments,
+        kind: original_message.message_kind,
+        idempotency_key: "dead-letter:#{dead_letter.id}"
+      )
+      dead_letter.update!(retried_message_id: message_reference.id)
+      message_reference
+    end
+
+    private
+
+    # @rbs (Symbol, authorization_context: untyped, ?dead_letter_id: Integer?) -> void
+    def authorize!(action, authorization_context:, dead_letter_id: nil)
+      authorized = SolidObjects.configuration.authorize_administration.call(
+        action: action.to_s,
+        resource: "dead_letters",
+        resource_id: dead_letter_id,
+        authorization_context:
+      )
+      return if authorized
+
+      raise Unauthorized, "actor administration is not authorized"
+    end
+  end
+end

data/lib/solid_objects/dom_identity.rb

@@ -0,0 +1,38 @@
+# rbs_inline: enabled
+
+require "digest"
+
+module SolidObjects
+  module DomIdentity
+    module_function
+
+    # @rbs (Reference) -> String
+    def scope(reference)
+      "solid_objects_actor_#{identity_digest(reference)}"
+    end
+
+    # @rbs (Reference, Symbol | String) -> String
+    def observable(reference, name)
+      "#{scope(reference)}_observable_#{normalized_name(name)}"
+    end
+
+    # @rbs (Reference, Symbol | String) -> String
+    def component(reference, name)
+      "#{scope(reference)}_component_#{normalized_name(name)}"
+    end
+
+    # @rbs (Reference) -> String
+    def identity_digest(reference)
+      Digest::SHA256.hexdigest(
+        "#{reference.actor_type}\0#{reference.actor_id}"
+      ).first(24)
+    end
+    private_class_method :identity_digest
+
+    # @rbs (Symbol | String) -> String
+    def normalized_name(name)
+      name.to_s.gsub(/[^a-zA-Z0-9_-]/, "_")
+    end
+    private_class_method :normalized_name
+  end
+end

data/lib/solid_objects/effect_executor.rb

@@ -0,0 +1,235 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  EffectContext = Data.define(:id, :attempt, :source_message_id, :actor_type, :actor_id)
+
+  class EffectExecutor
+    ACTOR_MESSAGE_EFFECT = "__actor_message__"
+
+    # @rbs @process_registry: ProcessRegistry
+    # @rbs @database_adapter: DatabaseAdapter
+    # @rbs @stopped: bool
+    # @rbs @shutdown_requested: bool
+
+    # @rbs (?process_registry: ProcessRegistry, ?database_adapter: DatabaseAdapter) -> void
+    def initialize(
+      process_registry: ProcessRegistry.new,
+      database_adapter: SolidObjects.database_adapter
+    )
+      @process_registry = process_registry
+      @database_adapter = database_adapter
+      process_registry.register(kind: "effect")
+      @stopped = false
+      @shutdown_requested = false
+    end
+
+    # @rbs () -> bool
+    def run_once
+      return false if stopped?
+
+      process_registry.heartbeat
+      effect = claim_next
+      return false unless effect
+
+      result = deliver(effect)
+      complete(effect, result)
+      true
+    rescue => error
+      fail_effect(effect, error) if effect
+      false
+    end
+
+    # @rbs () -> void
+    def stop
+      return if stopped?
+
+      @stopped = true
+      process_registry.start_draining
+      process_registry.stop
+    end
+
+    # @rbs () -> void
+    def run
+      until shutdown_requested?
+        worked = run_once
+        next if worked
+
+        SolidObjects.wake_up.wait(timeout: SolidObjects.configuration.polling_interval)
+      end
+    ensure
+      stop
+    end
+
+    # @rbs () -> void
+    def request_shutdown
+      @shutdown_requested = true
+      SolidObjects.wake_up.signal
+    end
+
+    # @rbs () -> bool
+    def stopped?
+      @stopped
+    end
+
+    # @rbs () -> bool
+    def shutdown_requested?
+      @shutdown_requested
+    end
+
+    private
+
+    attr_reader :process_registry, :database_adapter
+
+    # @rbs () -> Effect?
+    def claim_next
+      database_adapter.transaction do
+        now = database_adapter.database_now
+        effect = database_adapter.lock_candidates(
+          Effect.where(status: "pending", available_at: ..now).order(:available_at, :id)
+        ).first
+        next unless effect
+
+        effect.update!(
+          status: "processing",
+          attempt_count: effect.attempt_count + 1,
+          claimed_by: process_registry.process_record.id,
+          claimed_at: now
+        )
+        effect
+      end
+    end
+
+    # @rbs (Effect) -> untyped
+    def deliver(effect)
+      return deliver_actor_message(effect) if effect.name == ACTOR_MESSAGE_EFFECT
+
+      handler = SolidObjects.effect_registry.fetch(effect.name)
+      context = EffectContext.new(
+        id: effect.effect_id,
+        attempt: effect.attempt_count,
+        source_message_id: effect.message_id,
+        actor_type: effect.instance.actor_type,
+        actor_id: effect.instance.actor_id
+      )
+      handler.call(effect.arguments, context)
+    end
+
+    # @rbs (Effect) -> Integer
+    def deliver_actor_message(effect)
+      arguments = effect.arguments
+      reference = Reference.new(
+        actor_type: arguments.fetch("actor_type"),
+        actor_id: arguments.fetch("actor_id")
+      )
+      actor_class = SolidObjects.registry.fetch(reference.actor_type)
+      message_name = arguments.fetch("message_name")
+      unless actor_class.definition.messages.key?(message_name.to_sym)
+        raise UnknownMessage, "unknown actor-to-actor message #{message_name.inspect}"
+      end
+
+      available_at = arguments["available_at"]
+      available_at = Time.iso8601(available_at) if available_at
+      Mailbox.new.enqueue(
+        reference,
+        message_name,
+        arguments.fetch("arguments"),
+        kind: "internal",
+        available_at:,
+        idempotency_key: effect.effect_id
+      ).id
+    end
+
+    # @rbs (Effect, untyped) -> void
+    def complete(effect, result)
+      serialized_result = Serialization.dump(
+        result,
+        max_bytes: SolidObjects.configuration.max_result_bytes
+      )
+      result_message = nil
+      database_adapter.transaction do
+        locked_effect = Effect.lock.find(effect.id)
+        verify_claim!(locked_effect)
+        result_message = enqueue_result_message(
+          locked_effect,
+          locked_effect.success_message_name,
+          "success",
+          { "effect_id" => locked_effect.effect_id, "result" => serialized_result }
+        )
+        locked_effect.update!(
+          status: "completed",
+          result: serialized_result,
+          error: nil,
+          completed_at: database_adapter.database_now,
+          claimed_by: nil,
+          claimed_at: nil
+        )
+      end
+      Mailbox.new.announce(result_message) if result_message
+      SolidObjects.instrument(
+        :"effect.completed",
+        effect_id: effect.effect_id,
+        effect_name: effect.name,
+        message_id: effect.message_id,
+        attempt: effect.attempt_count
+      )
+    end
+
+    # @rbs (Effect, Exception) -> void
+    def fail_effect(effect, error)
+      result_message = nil
+      database_adapter.transaction do
+        locked_effect = Effect.lock.find(effect.id)
+        verify_claim!(locked_effect)
+        dead = locked_effect.attempt_count >= locked_effect.max_attempts
+        error_details = {
+          "class" => error.class.name,
+          "message" => error.message.to_s.byteslice(0, 8_192),
+          "backtrace" => Array(error.backtrace).first(50)
+        }
+        if dead
+          result_message = enqueue_result_message(
+            locked_effect,
+            locked_effect.failure_message_name,
+            "failure",
+            { "effect_id" => locked_effect.effect_id, "error" => error_details }
+          )
+        end
+        locked_effect.update!(
+          status: dead ? "dead" : "pending",
+          available_at: database_adapter.database_now +
+            SolidObjects.configuration.retry_delay.call(locked_effect.attempt_count),
+          error: error_details,
+          claimed_by: nil,
+          claimed_at: nil
+        )
+      end
+      Mailbox.new.announce(result_message) if result_message
+    rescue ActiveRecord::RecordNotFound, LostActivation
+      nil
+    end
+
+    # @rbs (Effect) -> void
+    def verify_claim!(effect)
+      return if effect.status == "processing" &&
+        effect.claimed_by == process_registry.process_record.id
+
+      raise LostActivation, "effect claim changed"
+    end
+
+    # @rbs (Effect, String?, String, Hash[String, untyped]) -> Message?
+    def enqueue_result_message(effect, message_name, outcome, arguments)
+      return unless message_name
+
+      Mailbox.new.enqueue_in_transaction(
+        Reference.new(
+          actor_type: effect.instance.actor_type,
+          actor_id: effect.instance.actor_id
+        ),
+        message_name,
+        arguments,
+        kind: "internal",
+        idempotency_key: "effect:#{effect.effect_id}:#{outcome}"
+      )
+    end
+  end
+end

data/lib/solid_objects/effect_registry.rb

@@ -0,0 +1,34 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  class EffectRegistry
+    # @rbs @handlers: Hash[String, Proc]
+    # @rbs @mutex: Mutex
+
+    # @rbs () -> void
+    def initialize
+      @handlers = {}
+      @mutex = Mutex.new
+    end
+
+    # @rbs (String | Symbol, Proc) -> Proc
+    def register(name, handler)
+      effect_name = name.to_s
+      raise ArgumentError, "effect name cannot be empty" if effect_name.empty?
+
+      mutex.synchronize { handlers[effect_name] = handler }
+      handler
+    end
+
+    # @rbs (String | Symbol) -> Proc
+    def fetch(name)
+      handlers.fetch(name.to_s) do
+        raise InvalidActor, "no effect handler registered for #{name.inspect}"
+      end
+    end
+
+    private
+
+    attr_reader :handlers, :mutex
+  end
+end