solid_objects 0.1.0

data/lib/solid_objects/actor_snapshot.rb

@@ -0,0 +1,42 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  class ActorSnapshot
+    # @rbs @reference: Reference
+    # @rbs @actor_class: Class
+    # @rbs @actor: Actor
+
+    attr_reader :reference, :actor_class, :actor
+
+    # @rbs (Reference) -> void
+    def initialize(reference)
+      @reference = reference
+      @actor_class = SolidObjects.registry.fetch(reference.actor_type)
+      @actor = build_actor
+    end
+
+    # @rbs () -> Hash[String, untyped]
+    def observable_values
+      actor.observable_values
+    end
+
+    private
+
+    # @rbs () -> Actor
+    def build_actor
+      instance = Instance.find_by(
+        actor_type: reference.actor_type,
+        actor_id: reference.actor_id
+      )
+      state_version = instance&.state_version || actor_class.state_version
+      state_data = actor_class.definition.migrate_state(
+        state_version,
+        instance&.state || {}
+      )
+      actor_class.new(
+        actor_id: reference.actor_id,
+        state: State.new(actor_class.definition.state_definition, state_data)
+      )
+    end
+  end
+end

data/lib/solid_objects/actor_view.rb

@@ -0,0 +1,117 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  class ActorView
+    # @rbs @reference: Reference
+    # @rbs @view_context: untyped
+    # @rbs @authorization_context: untyped
+    # @rbs @snapshot: ActorSnapshot
+
+    attr_reader :reference
+
+    # @rbs (reference: Reference, view_context: untyped, authorization_context: untyped) -> void
+    def initialize(reference:, view_context:, authorization_context:)
+      @reference = reference
+      @view_context = view_context
+      @authorization_context = authorization_context
+      @snapshot = ActorSnapshot.new(reference)
+    end
+
+    # @rbs (Symbol | String) -> untyped
+    def value(name)
+      observable_name = name.to_sym
+      handler = snapshot.actor_class.definition.observables[observable_name]
+      raise UnknownMessage, "unknown observable #{name.inspect}" unless handler
+
+      authorize_read!(observable_name)
+      value = snapshot.observable_values.fetch(observable_name.to_s)
+      view_context.content_tag(
+        :span,
+        display_value(value),
+        id: DomIdentity.observable(reference, observable_name)
+      )
+    end
+
+    # @rbs (Symbol | String, ?partial: String?) -> untyped
+    def component(name, partial: nil)
+      component_name = normalized_component_name(name)
+      authorize_read!(component_name)
+      rendered = view_context.render(
+        partial: partial || default_partial(component_name),
+        locals: { actor: self }
+      )
+      view_context.content_tag(
+        :div,
+        rendered,
+        id: DomIdentity.component(reference, component_name)
+      )
+    end
+
+    # @rbs () -> State
+    def state
+      snapshot.actor.state
+    end
+
+    # @rbs (Symbol, *untyped, **untyped) -> untyped
+    def method_missing(name, *arguments, **keywords)
+      return value(name) if arguments.empty? && keywords.empty? && observable?(name)
+
+      super
+    end
+
+    # @rbs (Symbol, bool) -> bool
+    def respond_to_missing?(name, include_private = false)
+      observable?(name) || super
+    end
+
+    private
+
+    attr_reader :view_context, :authorization_context, :snapshot
+
+    # @rbs (Symbol | String) -> void
+    def authorize_read!(name)
+      authorized = SolidObjects.configuration.authorize_query.call(
+        actor_type: reference.actor_type,
+        actor_id: reference.actor_id,
+        message_name: name.to_s,
+        arguments: {},
+        authorization_context:
+      )
+      return if authorized
+
+      raise Unauthorized, "actor state query is not authorized"
+    end
+
+    # @rbs (Symbol | String) -> bool
+    def observable?(name)
+      snapshot.actor_class.definition.observables.key?(name.to_sym)
+    end
+
+    # @rbs (untyped) -> String
+    def display_value(value)
+      return value if value.is_a?(String)
+      return value.to_s if value.is_a?(Numeric) || value == true || value == false
+      return "" if value.nil?
+
+      JSON.generate(value)
+    end
+
+    # @rbs (Symbol | String) -> String
+    def normalized_component_name(name)
+      component_name = name.to_s
+      unless component_name.match?(/\A[a-zA-Z0-9_]+\z/)
+        raise ArgumentError, "component names may contain only letters, digits, and underscores"
+      end
+
+      component_name
+    end
+
+    # @rbs (String) -> String
+    def default_partial(component_name)
+      actor_name = snapshot.actor_class.name
+      raise InvalidActor, "anonymous actors must provide an explicit component partial" unless actor_name
+
+      "actors/#{actor_name.underscore}/#{component_name}"
+    end
+  end
+end

data/lib/solid_objects/broadcast_executor.rb

@@ -0,0 +1,162 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  class BroadcastExecutor
+    # @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: "broadcast")
+      @stopped = false
+      @shutdown_requested = false
+    end
+
+    # @rbs () -> bool
+    def run_once
+      return false if stopped?
+
+      process_registry.heartbeat
+      broadcast = claim_next
+      return false unless broadcast
+
+      broadcast_adapter.call(broadcast)
+      complete(broadcast)
+      true
+    rescue => error
+      fail_broadcast(broadcast, error) if broadcast
+      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 () -> Broadcast?
+    def claim_next
+      database_adapter.transaction do
+        now = database_adapter.database_now
+        stale_at = now - SolidObjects.configuration.process_alive_threshold
+        relation = Broadcast
+          .where(status: "pending", available_at: ..now)
+          .or(Broadcast.where(status: "processing", claimed_at: ..stale_at))
+          .order(:available_at, :id)
+        broadcast = database_adapter.lock_candidates(relation).first
+        next unless broadcast
+
+        broadcast.update!(
+          status: "processing",
+          attempt_count: broadcast.attempt_count + 1,
+          claimed_by: process_registry.process_record.id,
+          claimed_at: now
+        )
+        broadcast
+      end
+    end
+
+    # @rbs () -> Proc | ActionCableBroadcastAdapter
+    def broadcast_adapter
+      SolidObjects.configuration.broadcast_adapter ||
+        ActionCableBroadcastAdapter.new
+    end
+
+    # @rbs (Broadcast) -> void
+    def complete(broadcast)
+      database_adapter.transaction do
+        locked_broadcast = Broadcast.lock.find(broadcast.id)
+        verify_claim!(locked_broadcast)
+        locked_broadcast.update!(
+          status: "delivered",
+          error: nil,
+          delivered_at: database_adapter.database_now,
+          claimed_by: nil,
+          claimed_at: nil
+        )
+      end
+      SolidObjects.instrument(
+        :"broadcast.delivered",
+        broadcast_id: broadcast.broadcast_id,
+        message_id: broadcast.message_id,
+        actor_type: broadcast.instance.actor_type,
+        actor_id: broadcast.instance.actor_id,
+        observable_name: broadcast.observable_name,
+        attempt: broadcast.attempt_count
+      )
+    end
+
+    # @rbs (Broadcast, Exception) -> void
+    def fail_broadcast(broadcast, error)
+      database_adapter.transaction do
+        locked_broadcast = Broadcast.lock.find(broadcast.id)
+        verify_claim!(locked_broadcast)
+        dead = locked_broadcast.attempt_count >= SolidObjects.configuration.max_attempts
+        locked_broadcast.update!(
+          status: dead ? "dead" : "pending",
+          available_at: database_adapter.database_now +
+            SolidObjects.configuration.retry_delay.call(locked_broadcast.attempt_count),
+          error: {
+            "class" => error.class.name,
+            "message" => error.message.to_s.byteslice(0, 8_192),
+            "backtrace" => Array(error.backtrace).first(50)
+          },
+          claimed_by: nil,
+          claimed_at: nil
+        )
+      end
+    rescue ActiveRecord::RecordNotFound, LostActivation
+      nil
+    end
+
+    # @rbs (Broadcast) -> void
+    def verify_claim!(broadcast)
+      return if broadcast.status == "processing" &&
+        broadcast.claimed_by == process_registry.process_record.id
+
+      raise LostActivation, "broadcast claim changed"
+    end
+  end
+end

data/lib/solid_objects/cli.rb

@@ -0,0 +1,118 @@
+# rbs_inline: enabled
+
+require "thor"
+
+module SolidObjects
+  class CLI < Thor
+    package_name "solid_objects"
+
+    desc "start", "Start actor, effect, reminder, and broadcast processes"
+    option :environment, type: :string, aliases: "-e"
+    option :workers, type: :numeric
+    option :effect_workers, type: :numeric
+    option :broadcast_workers, type: :numeric
+    option :reminder_schedulers, type: :numeric
+
+    # @rbs () -> void
+    def start
+      boot_application
+      supervisor = Supervisor.new(
+        worker_count: numeric_option(:workers, SolidObjects.configuration.worker_count),
+        effect_worker_count: numeric_option(:effect_workers, SolidObjects.configuration.effect_worker_count),
+        broadcast_worker_count: numeric_option(:broadcast_workers, SolidObjects.configuration.broadcast_worker_count),
+        reminder_scheduler_count: numeric_option(:reminder_schedulers, SolidObjects.configuration.reminder_scheduler_count)
+      )
+      %w[INT TERM].each do |signal|
+        Signal.trap(signal) { Thread.new { supervisor.stop } }
+      end
+      supervisor.run
+    end
+
+    desc "status", "Print registered runtime processes"
+    option :environment, type: :string, aliases: "-e"
+
+    # @rbs () -> void
+    def status
+      boot_application
+      authorize_administration!(:status)
+      rows = SolidObjects::Process.order(:kind, :started_at).map do |process_record|
+        {
+          id: process_record.id,
+          kind: process_record.kind,
+          hostname: process_record.hostname,
+          pid: process_record.pid,
+          state: process_record.shutdown_state,
+          last_heartbeat_at: process_record.last_heartbeat_at
+        }
+      end
+      puts JSON.pretty_generate(rows)
+    end
+
+    desc "cleanup", "Release coordination records owned by dead processes"
+    option :environment, type: :string, aliases: "-e"
+
+    # @rbs () -> void
+    def cleanup
+      boot_application
+      authorize_administration!(:cleanup)
+      puts JSON.generate(cleaned_processes: ProcessRegistry.cleanup_dead)
+    end
+
+    desc "dead_letters", "Print dead actor messages"
+    option :environment, type: :string, aliases: "-e"
+
+    # @rbs () -> void
+    def dead_letters
+      boot_application
+      rows = SolidObjects.dead_letters
+        .all(authorization_context: { source: "cli" })
+        .map(&:attributes)
+      puts JSON.pretty_generate(rows)
+    end
+
+    desc "retry_dead_letter ID", "Retry one dead actor message"
+    option :environment, type: :string, aliases: "-e"
+
+    # @rbs (String) -> void
+    def retry_dead_letter(id)
+      boot_application
+      message_reference = SolidObjects.dead_letters.retry(
+        Integer(id),
+        authorization_context: { source: "cli" }
+      )
+      puts JSON.generate(message_id: message_reference.id)
+    end
+
+    private
+
+    # @rbs () -> void
+    def boot_application
+      path = options[:environment] ||
+        File.expand_path("config/environment.rb", Dir.pwd)
+      unless File.file?(path)
+        raise Error, "Rails environment not found at #{path}"
+      end
+
+      require path
+    end
+
+    # @rbs (Symbol, Integer) -> Integer
+    def numeric_option(name, default)
+      value = options[name]
+      value ? Integer(value) : default
+    end
+
+    # @rbs (Symbol) -> void
+    def authorize_administration!(action)
+      authorized = SolidObjects.configuration.authorize_administration.call(
+        action:,
+        resource: "processes",
+        resource_id: nil,
+        authorization_context: { source: "cli" }
+      )
+      return if authorized
+
+      raise Unauthorized, "actor administration is not authorized"
+    end
+  end
+end

data/lib/solid_objects/client.rb

@@ -0,0 +1,153 @@
+# rbs_inline: enabled
+
+require "solid_objects/mailbox"
+
+module SolidObjects
+  class Client
+    # @rbs @mailbox: Mailbox
+
+    # @rbs (?mailbox: Mailbox) -> void
+    def initialize(mailbox: Mailbox.new)
+      @mailbox = mailbox
+    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)
+      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)
+
+      authorize!(
+        SolidObjects.configuration.authorize_message,
+        reference,
+        message_name,
+        arguments,
+        authorization_context:
+      )
+      mailbox.enqueue(
+        reference,
+        message_name,
+        arguments,
+        kind: "tell",
+        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)
+      actor_class = SolidObjects.registry.fetch(reference.actor_type)
+      message_symbol = message_name.to_sym
+      query = actor_class.definition.queries.key?(message_symbol)
+      actor_message = actor_class.definition.messages.key?(message_symbol)
+      raise UnknownMessage, "unknown message #{message_name.inspect}" unless query || actor_message
+
+      authorize!(
+        query ? SolidObjects.configuration.authorize_query : SolidObjects.configuration.authorize_message,
+        reference,
+        message_name,
+        arguments,
+        authorization_context:
+      )
+      message_reference = mailbox.enqueue(
+        reference,
+        message_name,
+        arguments,
+        kind: "ask",
+        idempotency_key:
+      )
+      wait_for_result(message_reference, timeout:)
+    end
+
+    # @rbs (Reference, ?authorization_context: untyped) -> bool
+    def destroy(reference, authorization_context: nil)
+      raise ActorCallCycle, "actors cannot synchronously destroy another actor" if Context.current_actor
+
+      SolidObjects.registry.fetch(reference.actor_type)
+      authorize_destroy!(reference, authorization_context:)
+      instance_id = SolidObjects.database_adapter.transaction do
+        instance = Instance.lock.find_by(
+          actor_type: reference.actor_type,
+          actor_id: reference.actor_id
+        )
+        next unless instance
+
+        instance_id = instance.id
+        instance.delete
+        instance_id
+      end
+      return false unless instance_id
+
+      SolidObjects.instrument(
+        :"actor.destroyed",
+        instance_id:,
+        actor_type: reference.actor_type,
+        actor_id: reference.actor_id
+      )
+      SolidObjects.wake_up.signal
+      true
+    end
+
+    private
+
+    attr_reader :mailbox
+
+    # @rbs (Proc, Reference, Symbol | String, Hash[Symbol | String, untyped], authorization_context: untyped) -> void
+    def authorize!(hook, reference, message_name, arguments, authorization_context:)
+      authorized = hook.call(
+        actor_type: reference.actor_type,
+        actor_id: reference.actor_id,
+        message_name: message_name.to_s,
+        arguments:,
+        authorization_context:
+      )
+      return if authorized
+
+      raise Unauthorized, "actor invocation is not authorized"
+    end
+
+    # @rbs (Reference, authorization_context: untyped) -> void
+    def authorize_destroy!(reference, authorization_context:)
+      authorized = SolidObjects.configuration.authorize_destroy.call(
+        actor_type: reference.actor_type,
+        actor_id: reference.actor_id,
+        authorization_context:
+      )
+      return if authorized
+
+      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