solid_objects 0.1.0

data/lib/solid_objects/mailbox.rb

@@ -0,0 +1,178 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  class Mailbox
+    INSTANCE_RETRY_LIMIT = 3
+
+    # @rbs @database_adapter: DatabaseAdapter
+
+    # @rbs (?database_adapter: DatabaseAdapter) -> void
+    def initialize(database_adapter: SolidObjects.database_adapter)
+      @database_adapter = database_adapter
+    end
+
+    # @rbs (Reference, Symbol | String, Hash[Symbol | String, untyped], kind: String, ?available_at: Time?, idempotency_key: String?) -> MessageReference
+    def enqueue(reference, message_name, arguments, kind:, available_at: nil, idempotency_key: nil)
+      actor_class = SolidObjects.registry.fetch(reference.actor_type)
+      normalized_arguments = Serialization.dump(
+        arguments,
+        max_bytes: SolidObjects.configuration.max_payload_bytes
+      )
+      message = with_instance_retry do
+        database_adapter.transaction do
+          enqueue_in_transaction(
+            reference,
+            message_name,
+            normalized_arguments,
+            kind:,
+            available_at:,
+            idempotency_key:,
+            actor_class:
+          )
+        end
+      end
+
+      announce(message)
+      MessageReference.from_message(message)
+    end
+
+    # @rbs (Reference, Symbol | String, Hash[Symbol | String, untyped], kind: String, ?available_at: Time?, idempotency_key: String?, ?actor_class: Class?) -> Message
+    def enqueue_in_transaction(
+      reference,
+      message_name,
+      arguments,
+      kind:,
+      available_at: nil,
+      idempotency_key: nil,
+      actor_class: nil
+    )
+      actor_class ||= SolidObjects.registry.fetch(reference.actor_type)
+      normalized_arguments = Serialization.dump(
+        arguments,
+        max_bytes: SolidObjects.configuration.max_payload_bytes
+      )
+      instance = find_or_create_instance(reference, actor_class)
+      instance.lock!
+
+      existing = find_idempotent_message(instance, idempotency_key)
+      return validate_idempotent_message!(existing, message_name, kind, normalized_arguments) if existing
+
+      enforce_mailbox_limit!(instance)
+      create_message(
+        instance,
+        reference,
+        message_name,
+        normalized_arguments,
+        kind:,
+        available_at:,
+        idempotency_key:
+      )
+    end
+
+    # @rbs (Message) -> void
+    def announce(message)
+      SolidObjects.instrument(
+        :"message.enqueued",
+        message_id: message.id,
+        actor_type: message.actor_type,
+        actor_id: message.actor_id,
+        sequence: message.sequence,
+        request_id: message.request_id
+      )
+      SolidObjects.wake_up.signal
+    end
+
+    private
+
+    attr_reader :database_adapter
+
+    # @rbs () { () -> Message } -> Message
+    def with_instance_retry
+      attempts = 0
+      begin
+        yield
+      rescue ActiveRecord::RecordNotFound
+        attempts += 1
+        retry if attempts < INSTANCE_RETRY_LIMIT
+
+        raise ActorDestroyed, "actor changed repeatedly while enqueueing"
+      end
+    end
+
+    # @rbs (Reference, Class) -> Instance
+    def find_or_create_instance(reference, actor_class)
+      Instance.create_or_find_by!(
+        actor_type: reference.actor_type,
+        actor_id: reference.actor_id
+      ) do |instance|
+        instance.state = {}
+        instance.state_version = actor_class.state_version
+      end
+    end
+
+    # @rbs (Instance, String?) -> Message?
+    def find_idempotent_message(instance, idempotency_key)
+      return unless idempotency_key
+
+      Message.find_by(instance_id: instance.id, idempotency_key:)
+    end
+
+    # @rbs (Message, Symbol | String, String, untyped) -> Message
+    def validate_idempotent_message!(message, message_name, kind, arguments)
+      matches = message.message_name == message_name.to_s &&
+        message.message_kind == kind &&
+        message.arguments == arguments
+      return message if matches
+
+      raise IdempotencyConflict, "idempotency key belongs to a different actor invocation"
+    end
+
+    # @rbs (Instance) -> void
+    def enforce_mailbox_limit!(instance)
+      live_count = ReadyMessage.where(instance_id: instance.id).count +
+        ClaimedMessage.where(instance_id: instance.id).count
+      return if live_count < SolidObjects.configuration.max_mailbox_length
+
+      raise MailboxFull, "mailbox is full for #{instance.actor_type}(#{instance.actor_id.inspect})"
+    end
+
+    # @rbs (Instance, Reference, Symbol | String, untyped, kind: String, available_at: Time?, idempotency_key: String?) -> Message
+    def create_message(instance, reference, message_name, arguments, kind:, available_at:, idempotency_key:)
+      sequence = instance.next_message_sequence
+      now = database_adapter.database_now
+      scheduled_at = normalize_availability(available_at, now)
+      instance.update!(next_message_sequence: sequence + 1)
+      message = Message.create!(
+        instance:,
+        actor_type: reference.actor_type,
+        actor_id: reference.actor_id,
+        message_name: message_name.to_s,
+        message_kind: kind,
+        arguments:,
+        sequence:,
+        max_attempts: SolidObjects.configuration.max_attempts,
+        request_id: SecureRandom.uuid,
+        idempotency_key:,
+        enqueued_at: now,
+        available_at: scheduled_at
+      )
+      ReadyMessage.create!(
+        message:,
+        instance:,
+        sequence:,
+        available_at: scheduled_at
+      )
+      message
+    end
+
+    # @rbs (Time?, Time) -> Time
+    def normalize_availability(available_at, now)
+      return now unless available_at
+
+      time = available_at.respond_to?(:to_time) ? available_at.to_time : available_at
+      raise ArgumentError, "available_at must be a time" unless time.is_a?(Time)
+
+      [ time, now ].max
+    end
+  end
+end

data/lib/solid_objects/message_reference.rb

@@ -0,0 +1,52 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  class MessageReference
+    class << self
+      # @rbs (Message) -> MessageReference
+      def from_message(message)
+        new(
+          id: message.id,
+          request_id: message.request_id,
+          actor_type: message.actor_type,
+          actor_id: message.actor_id,
+          sequence: message.sequence
+        )
+      end
+    end
+
+    # @rbs @id: Integer
+    # @rbs @request_id: String
+    # @rbs @actor_type: String
+    # @rbs @actor_id: String
+    # @rbs @sequence: Integer
+
+    attr_reader :id, :request_id, :actor_type, :actor_id, :sequence
+
+    # @rbs (id: Integer, request_id: String, actor_type: String, actor_id: String, sequence: Integer) -> void
+    def initialize(id:, request_id:, actor_type:, actor_id:, sequence:)
+      @id = id
+      @request_id = request_id
+      @actor_type = actor_type
+      @actor_id = actor_id
+      @sequence = sequence
+      freeze
+    end
+
+    # @rbs () -> String
+    def status
+      message = Message.find(id)
+      return "completed" if message.completed?
+      return "dead" if message.dead?
+      return "claimed" if message.claimed?
+      return "ready" if message.ready?
+
+      "unknown"
+    end
+
+    # @rbs () -> untyped
+    def result
+      Message.find(id).result
+    end
+  end
+end

data/lib/solid_objects/process_registry.rb

@@ -0,0 +1,143 @@
+# rbs_inline: enabled
+
+require "socket"
+
+module SolidObjects
+  class ProcessRegistry
+    class << self
+      # @rbs (?now: Time) -> Integer
+      def cleanup_dead(now: SolidObjects.database_adapter.database_now)
+        stale_at = now - SolidObjects.configuration.process_alive_threshold
+        dead_processes = Process
+          .where.not(shutdown_state: "stopped")
+          .where(last_heartbeat_at: ..stale_at)
+          .to_a
+
+        dead_processes.each { |process_record| cleanup_process(process_record, now) }
+        dead_processes.length
+      end
+
+      # @rbs (Process, ?now: Time) -> bool
+      def deregister(process_record, now: SolidObjects.database_adapter.database_now)
+        SolidObjects.database_adapter.transaction do
+          Instance.where(activation_owner_id: process_record.id).update_all(
+            activation_owner_id: nil,
+            activation_expires_at: nil
+          )
+          ClaimedMessage.where(process_id: process_record.id).update_all(process_id: nil)
+          Effect.where(claimed_by: process_record.id).update_all(
+            status: "pending",
+            claimed_by: nil,
+            claimed_at: nil,
+            available_at: now
+          )
+          Reminder.where(claimed_by: process_record.id).update_all(
+            claimed_by: nil,
+            claimed_at: nil
+          )
+          Broadcast.where(claimed_by: process_record.id).update_all(
+            status: "pending",
+            claimed_by: nil,
+            claimed_at: nil,
+            available_at: now
+          )
+          process_record.update!(
+            shutdown_state: "stopped",
+            stopped_at: now
+          )
+        end
+        true
+      end
+
+      private
+
+      # @rbs (Process, Time) -> void
+      def cleanup_process(process_record, now)
+        deregister(process_record, now:)
+        SolidObjects.instrument(
+          :"process.pruned",
+          process_id: process_record.id,
+          process_kind: process_record.kind,
+          last_heartbeat_at: process_record.last_heartbeat_at
+        )
+      end
+    end
+
+    # @rbs @process_record: Process?
+    # @rbs @last_heartbeat_at: Float?
+
+    attr_reader :process_record
+
+    # @rbs () -> void
+    def initialize
+      @process_record = nil
+      @last_heartbeat_at = nil
+    end
+
+    # @rbs (?kind: String, ?metadata: Hash[String | Symbol, untyped]) -> Process
+    def register(kind: "worker", metadata: {})
+      now = SolidObjects.database_adapter.database_now
+      @process_record = Process.create!(
+        id: SecureRandom.uuid,
+        kind:,
+        hostname: Socket.gethostname,
+        pid: ::Process.pid,
+        started_at: now,
+        last_heartbeat_at: now,
+        metadata: Serialization.dump(default_metadata.merge(metadata))
+      )
+      @last_heartbeat_at = monotonic_now
+      @process_record
+    end
+
+    # @rbs () -> bool
+    def heartbeat
+      return false unless process_record
+      return false if heartbeat_recent?
+
+      process_record.update(
+        last_heartbeat_at: SolidObjects.database_adapter.database_now
+      ).tap { @last_heartbeat_at = monotonic_now }
+    end
+
+    # @rbs () -> bool
+    def start_draining
+      return false unless process_record
+
+      process_record.update(
+        shutdown_state: "draining",
+        shutdown_requested_at: SolidObjects.database_adapter.database_now
+      )
+    end
+
+    # @rbs () -> bool
+    def stop
+      return false unless process_record
+
+      self.class.deregister(process_record)
+    end
+
+    private
+
+    # @rbs () -> Hash[Symbol, String]
+    def default_metadata
+      {
+        solid_objects_version: SolidObjects::VERSION,
+        ruby_version: RUBY_VERSION
+      }
+    end
+
+    # @rbs () -> bool
+    def heartbeat_recent?
+      return false unless @last_heartbeat_at
+
+      monotonic_now - @last_heartbeat_at <
+        SolidObjects.configuration.process_heartbeat_interval
+    end
+
+    # @rbs () -> Float
+    def monotonic_now
+      ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/solid_objects/reference.rb

@@ -0,0 +1,96 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  class Reference
+    # @rbs @actor_type: String
+    # @rbs @actor_id: String
+
+    attr_reader :actor_type, :actor_id
+
+    # @rbs (actor_type: String, actor_id: String) -> void
+    def initialize(actor_type:, actor_id:)
+      raise InvalidActor, "actor ID cannot be empty" if actor_id.empty?
+
+      @actor_type = actor_type
+      @actor_id = actor_id
+      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)
+      if (actor = Context.current_actor)
+        return actor.stage_outbound_message(
+          self,
+          message_name,
+          arguments,
+          available_at:,
+          idempotency_key:
+        )
+      end
+
+      SolidObjects.client.tell(
+        self,
+        message_name,
+        arguments,
+        available_at:,
+        idempotency_key:,
+        authorization_context:
+      )
+    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)
+      raise ActorCallCycle, "actors cannot synchronously wait for another actor" if Context.current_actor
+
+      SolidObjects.client.ask(
+        self,
+        message_name,
+        arguments,
+        timeout:,
+        idempotency_key:,
+        authorization_context:
+      )
+    end
+
+    # @rbs (?authorization_context: untyped) -> bool
+    def destroy(authorization_context: nil)
+      SolidObjects.client.destroy(self, authorization_context:)
+    end
+
+    # @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)
+
+      super
+    end
+
+    # @rbs (Symbol, bool) -> bool
+    def respond_to_missing?(name, include_private = false)
+      actor_message?(name) || actor_query?(name) || super
+    end
+
+    # @rbs () -> String
+    def to_s
+      "#{actor_type}(#{actor_id.inspect})"
+    end
+
+    private
+
+    # @rbs (Symbol | String) -> bool
+    def actor_message?(name)
+      actor_definition.messages.key?(name.to_sym)
+    end
+
+    # @rbs (Symbol | String) -> bool
+    def actor_query?(name)
+      actor_definition.queries.key?(name.to_sym)
+    end
+
+    # @rbs () -> ActorDefinition
+    def actor_definition
+      SolidObjects.registry.fetch(actor_type).definition
+    end
+  end
+end

data/lib/solid_objects/reminder_scheduler.rb

@@ -0,0 +1,168 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  class ReminderScheduler
+    # @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: "reminder")
+      @stopped = false
+      @shutdown_requested = false
+    end
+
+    # @rbs () -> bool
+    def run_once
+      return false if stopped?
+
+      process_registry.heartbeat
+      reminder = claim_next
+      return false unless reminder
+
+      enqueue(reminder).present?
+    rescue
+      release(reminder) if reminder
+      raise
+    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 () -> Reminder?
+    def claim_next
+      database_adapter.transaction do
+        now = database_adapter.database_now
+        stale_at = now - SolidObjects.configuration.process_alive_threshold
+        relation = Reminder
+          .where(status: "scheduled", next_run_at: ..now)
+          .where("claimed_by IS NULL OR claimed_at <= ?", stale_at)
+          .order(:next_run_at, :id)
+        reminder = database_adapter.lock_candidates(relation).first
+        next unless reminder
+
+        reminder.update!(
+          claimed_by: process_registry.process_record.id,
+          claimed_at: now
+        )
+        reminder
+      end
+    end
+
+    # @rbs (Reminder) -> MessageReference?
+    def enqueue(reminder)
+      actor_class = SolidObjects.registry.fetch(reminder.actor_type)
+      unless actor_class.definition.messages.key?(reminder.message_name.to_sym)
+        raise UnknownMessage, "unknown reminder message #{reminder.message_name.inspect}"
+      end
+
+      mailbox = Mailbox.new(database_adapter:)
+      message = database_adapter.transaction do
+        instance = Instance.lock.find_by(id: reminder.instance_id)
+        next unless instance
+
+        locked_reminder = Reminder.lock.find_by(id: reminder.id)
+        next unless locked_reminder
+        verify_claim!(locked_reminder)
+        now = database_adapter.database_now
+        message = mailbox.enqueue_in_transaction(
+          Reference.new(actor_type: instance.actor_type, actor_id: instance.actor_id),
+          locked_reminder.message_name,
+          locked_reminder.arguments,
+          kind: "internal",
+          idempotency_key: "reminder:#{locked_reminder.id}:#{locked_reminder.occurrence}",
+          actor_class:
+        )
+        recurring = locked_reminder.interval_seconds.present?
+        locked_reminder.update!(
+          status: recurring ? "scheduled" : "completed",
+          occurrence: locked_reminder.occurrence + 1,
+          next_run_at: recurring ? next_run_at(locked_reminder, now) : locked_reminder.next_run_at,
+          claimed_by: nil,
+          claimed_at: nil
+        )
+        message
+      end
+      return unless message
+
+      mailbox.announce(message)
+      SolidObjects.instrument(
+        :"reminder.enqueued",
+        reminder_id: reminder.id,
+        actor_type: reminder.actor_type,
+        actor_id: reminder.actor_id,
+        occurrence: reminder.occurrence
+      )
+      MessageReference.from_message(message)
+    end
+
+    # @rbs (Reminder) -> void
+    def release(reminder)
+      Reminder
+        .where(id: reminder.id, claimed_by: process_registry.process_record.id)
+        .update_all(claimed_by: nil, claimed_at: nil)
+    end
+
+    # @rbs (Reminder) -> void
+    def verify_claim!(reminder)
+      return if reminder.claimed_by == process_registry.process_record.id
+
+      raise LostActivation, "reminder claim changed"
+    end
+
+    # @rbs (Reminder, Time) -> Time
+    def next_run_at(reminder, now)
+      interval = reminder.interval_seconds.to_f
+      next_run = reminder.next_run_at + interval
+      return next_run if reminder.missed_policy == "all" || next_run > now
+
+      missed_intervals = ((now - next_run) / interval).floor + 1
+      next_run + (missed_intervals * interval)
+    end
+  end
+end