solid_objects 0.1.0

data/lib/solid_objects/activation_manager.rb

@@ -0,0 +1,102 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  class ActivationManager
+    # @rbs @owner_id: String
+    # @rbs @database_adapter: DatabaseAdapter
+
+    # @rbs (owner_id: String, ?database_adapter: DatabaseAdapter) -> void
+    def initialize(owner_id:, database_adapter: SolidObjects.database_adapter)
+      @owner_id = owner_id
+      @database_adapter = database_adapter
+    end
+
+    # @rbs () -> Activation?
+    def claim_next
+      lease = database_adapter.transaction do
+        now = database_adapter.database_now
+        claimed_lease = nil
+        candidate_instance_ids(now).each do |instance_id|
+          instance = database_adapter.lock_candidates(
+            Instance.where(id: instance_id)
+          ).first
+          next unless instance
+          next unless claimable?(instance, now)
+
+          claimed_lease = Lease.claim(instance:, owner_id:, now:, database_adapter:)
+          break if claimed_lease
+        end
+        claimed_lease
+      end
+      return unless lease
+
+      SolidObjects.instrument(
+        :"activation.claimed",
+        instance_id: lease.instance_id,
+        owner_id:,
+        generation: lease.generation
+      )
+      Activation.new(lease:)
+    rescue
+      lease&.release
+      raise
+    end
+
+    private
+
+    attr_reader :owner_id, :database_adapter
+
+    # @rbs (Time) -> Array[Integer]
+    def candidate_instance_ids(now)
+      (ready_instance_ids(now) + claimed_instance_ids(now)).uniq
+    end
+
+    # @rbs (Time) -> Array[Integer]
+    def ready_instance_ids(now)
+      ReadyMessage
+        .joins(:instance)
+        .where(available_at: ..now)
+        .where("#{Instance.table_name}.paused_at IS NULL")
+        .where(available_lease_sql, now)
+        .group(:instance_id)
+        .order(
+          Arel.sql("MIN(available_at)"),
+          Arel.sql("MIN(#{ReadyMessage.table_name}.id)")
+        )
+        .limit(SolidObjects.configuration.claim_scan_limit)
+        .pluck(:instance_id)
+    end
+
+    # @rbs (Time) -> Array[Integer]
+    def claimed_instance_ids(now)
+      ClaimedMessage
+        .joins(:instance)
+        .where("#{Instance.table_name}.paused_at IS NULL")
+        .where(available_lease_sql, now)
+        .group(:instance_id)
+        .order(
+          Arel.sql("MIN(claimed_at)"),
+          Arel.sql("MIN(#{ClaimedMessage.table_name}.id)")
+        )
+        .limit(SolidObjects.configuration.claim_scan_limit)
+        .pluck(:instance_id)
+    end
+
+    # @rbs (Instance, Time) -> bool
+    def claimable?(instance, now)
+      return false if instance.paused_at
+      return true unless instance.activation_owner_id
+      return true unless instance.activation_expires_at
+
+      instance.activation_expires_at <= now
+    end
+
+    # @rbs () -> String
+    def available_lease_sql
+      table_name = Instance.table_name
+      "#{table_name}.activation_owner_id IS NULL OR " \
+        "#{table_name}.activation_expires_at IS NULL OR " \
+        "#{table_name}.activation_expires_at <= ?"
+    end
+  end
+end

data/lib/solid_objects/actor.rb

@@ -0,0 +1,271 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  class Actor
+    EffectIntent = Data.define(:name, :arguments, :success_message_name, :failure_message_name)
+    ReminderIntent = Data.define(:name, :at, :arguments, :interval_seconds, :missed_policy)
+    OutboundMessageIntent = Data.define(:actor_type, :actor_id, :message_name, :arguments, :available_at, :idempotency_key)
+
+    class << self
+      # @rbs (Class) -> void
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@definition, definition.duplicate)
+        subclass.instance_variable_set(:@generated_attribute_methods, generated_attribute_methods.dup)
+      end
+
+      # @rbs (?String | Symbol) -> String
+      def actor_type(value = nil)
+        if value
+          @actor_type = value.to_s
+          SolidObjects.register_actor(@actor_type, self)
+        end
+
+        @actor_type ||= default_actor_type
+      end
+
+      # @rbs (Symbol | String, ?default: untyped) -> StateDefinition::Attribute
+      def attribute(name, default: nil)
+        attribute_name = name.to_sym
+        ensure_attribute_methods_available!(attribute_name)
+        attribute = definition.add_attribute(attribute_name, default:)
+        @defining_attribute_methods = true
+        begin
+          define_method(attribute_name) { state.fetch(attribute_name) }
+          define_method(:"#{attribute_name}=") { |value| state.write(attribute_name, value) }
+          generated_attribute_methods[attribute_name] = true
+          generated_attribute_methods[:"#{attribute_name}="] = true
+        ensure
+          @defining_attribute_methods = false
+        end
+        attribute
+      end
+
+      # @rbs (Symbol | String) { (*untyped, **untyped) -> untyped } -> ActorDefinition::Handler
+      def message(name, &block)
+        definition.add_message(name, block)
+      end
+
+      # @rbs (Symbol | String) { (*untyped, **untyped) -> untyped } -> ActorDefinition::Handler
+      def query(name, &block)
+        definition.add_query(name, block)
+      end
+
+      # @rbs (Symbol | String) ?{ () -> untyped } -> ActorDefinition::Handler
+      def observable(name, &block)
+        definition.add_observable(name, block)
+      end
+
+      # @rbs (?Integer) -> Integer
+      def state_version(version = nil)
+        definition.set_state_version(version) if version
+        definition.state_version
+      end
+
+      # @rbs (from: Integer, to: Integer) { (Hash[String, untyped]) -> Hash[String, untyped] } -> ActorDefinition::StateMigration
+      def migrate_state(from:, to:, &block)
+        definition.add_state_migration(from, to, block)
+      end
+
+      # @rbs () { () -> untyped } -> Proc
+      def on_activate(&block)
+        definition.activation_hooks << block
+        block
+      end
+
+      # @rbs () { () -> untyped } -> Proc
+      def on_deactivate(&block)
+        definition.deactivation_hooks << block
+        block
+      end
+
+      # @rbs (String | Integer) -> Reference
+      def ref(actor_id)
+        ensure_registered!
+        Reference.new(actor_type:, actor_id: actor_id.to_s)
+      end
+
+      # @rbs () -> ActorDefinition
+      def definition
+        (@definition ||= ActorDefinition.new).synchronize_instance_messages(self)
+      end
+
+      # @rbs () -> Class
+      def ensure_registered!
+        SolidObjects.register_actor(actor_type, self)
+      end
+
+      private
+
+      # @rbs (Symbol) -> void
+      def method_added(name)
+        super
+        generated_attribute_methods.delete(name) unless @defining_attribute_methods
+      end
+
+      # @rbs () -> Hash[Symbol, bool]
+      def generated_attribute_methods
+        @generated_attribute_methods ||= {}
+      end
+
+      # @rbs (Symbol) -> void
+      def ensure_attribute_methods_available!(attribute_name)
+        conflicting_name = [ attribute_name, :"#{attribute_name}=" ].find do |method_name|
+          method_defined?(method_name) ||
+            private_method_defined?(method_name) ||
+            protected_method_defined?(method_name)
+        end
+        return unless conflicting_name
+
+        raise InvalidActor, "attribute #{attribute_name.inspect} conflicts with actor method #{conflicting_name}"
+      end
+
+      # @rbs () -> String
+      def default_actor_type
+        raise InvalidActor, "anonymous actor classes must declare actor_type" unless name
+
+        name
+      end
+    end
+
+    # @rbs @actor_id: String
+    # @rbs @state: State
+    # @rbs @effect_intents: Array[EffectIntent]
+    # @rbs @reminder_intents: Array[ReminderIntent]
+    # @rbs @outbound_message_intents: Array[OutboundMessageIntent]
+
+    attr_reader :actor_id, :state
+
+    # @rbs (actor_id: String, state: State) -> void
+    def initialize(actor_id:, state:)
+      @actor_id = actor_id
+      @state = state
+      @effect_intents = []
+      @reminder_intents = []
+      @outbound_message_intents = []
+    end
+
+    # @rbs () -> MessageContext?
+    def current_message
+      Context.current_message
+    end
+
+    # @rbs (Symbol | String, ?on_success: Symbol | String?, ?on_failure: Symbol | String?, **untyped) -> EffectIntent
+    def emit(name, on_success: nil, on_failure: nil, **arguments)
+      validate_effect_callback!(on_success)
+      validate_effect_callback!(on_failure)
+      EffectIntent.new(
+        name: name.to_s,
+        arguments: Serialization.dump(arguments),
+        success_message_name: on_success&.to_s,
+        failure_message_name: on_failure&.to_s
+      ).tap do |intent|
+        effect_intents << intent
+      end
+    end
+
+    # @rbs (Symbol | String, at: Time, ?every: Numeric?, ?missed: Symbol | String, arguments: Hash[Symbol | String, untyped]) -> ReminderIntent
+    def schedule(name, at:, every: nil, missed: :latest, arguments: {})
+      interval_seconds = every&.to_f
+      if interval_seconds && !interval_seconds.positive?
+        raise ArgumentError, "reminder interval must be positive"
+      end
+      missed_policy = missed.to_s
+      unless %w[all latest].include?(missed_policy)
+        raise ArgumentError, "missed reminder policy must be all or latest"
+      end
+
+      ReminderIntent.new(
+        name: name.to_s,
+        at:,
+        arguments: Serialization.dump(arguments),
+        interval_seconds:,
+        missed_policy:
+      ).tap do |intent|
+        reminder_intents << intent
+      end
+    end
+
+    # @rbs (Reference, Symbol | String, ?available_at: Time?, ?idempotency_key: String?, **untyped) -> OutboundMessageIntent
+    def send_to(reference, message_name, available_at: nil, idempotency_key: nil, **arguments)
+      stage_outbound_message(reference, message_name, arguments, available_at:, idempotency_key:)
+    end
+
+    # @rbs (Symbol | String, Hash[String, untyped]) -> untyped
+    def invoke(message_name, arguments)
+      handler = self.class.definition.messages[message_name.to_sym] ||
+        self.class.definition.queries[message_name.to_sym]
+      raise UnknownMessage, "unknown message #{message_name.inspect} for #{self.class.actor_type}" unless handler
+
+      instance_exec(**keyword_arguments(arguments), &handler.block)
+    end
+
+    # @rbs () -> Hash[String, untyped]
+    def observable_values
+      self.class.definition.observables.each_with_object({}) do |(name, handler), values|
+        values[name.to_s] = Serialization.dump(instance_exec(&handler.block))
+      end
+    end
+
+    # @rbs () -> void
+    def activate
+      self.class.definition.activation_hooks.each { |hook| instance_exec(&hook) }
+    end
+
+    # @rbs () -> void
+    def deactivate
+      self.class.definition.deactivation_hooks.each { |hook| instance_exec(&hook) }
+    end
+
+    # @rbs (Reference, Symbol | String, Hash[Symbol | String, untyped], ?available_at: Time?, idempotency_key: String?) -> OutboundMessageIntent
+    def stage_outbound_message(reference, message_name, arguments, available_at: nil, idempotency_key: nil)
+      OutboundMessageIntent.new(
+        actor_type: reference.actor_type,
+        actor_id: reference.actor_id,
+        message_name: message_name.to_s,
+        arguments: Serialization.dump(arguments),
+        available_at:,
+        idempotency_key:
+      ).tap { |intent| outbound_message_intents << intent }
+    end
+
+    # @rbs () -> Array[EffectIntent]
+    def drain_effect_intents
+      effect_intents.shift(effect_intents.length)
+    end
+
+    # @rbs () -> Array[ReminderIntent]
+    def drain_reminder_intents
+      reminder_intents.shift(reminder_intents.length)
+    end
+
+    # @rbs () -> Array[OutboundMessageIntent]
+    def drain_outbound_message_intents
+      outbound_message_intents.shift(outbound_message_intents.length)
+    end
+
+    # @rbs () -> void
+    def discard_intents
+      effect_intents.clear
+      reminder_intents.clear
+      outbound_message_intents.clear
+    end
+
+    private
+
+    attr_reader :effect_intents, :reminder_intents, :outbound_message_intents
+
+    # @rbs (Hash[String, untyped]) -> Hash[Symbol, untyped]
+    def keyword_arguments(arguments)
+      arguments.each_with_object({}) { |(key, value), converted| converted[key.to_sym] = value }
+    end
+
+    # @rbs (Symbol | String?) -> void
+    def validate_effect_callback!(message_name)
+      return unless message_name
+      return if self.class.definition.messages.key?(message_name.to_sym)
+
+      raise UnknownMessage, "unknown effect callback message #{message_name.inspect}"
+    end
+  end
+end

data/lib/solid_objects/actor_channel.rb

@@ -0,0 +1,29 @@
+# rbs_inline: enabled
+
+require "action_cable/channel/base"
+
+module SolidObjects
+  class ActorChannel < ActionCable::Channel::Base
+    # @rbs () -> void
+    def subscribed
+      identity = StreamToken.verify(params.fetch("token"))
+      actor_type = identity.fetch("actor_type")
+      actor_id = identity.fetch("actor_id")
+      SolidObjects.registry.fetch(actor_type)
+      authorized = SolidObjects.configuration.authorize_subscription.call(
+        actor_type:,
+        actor_id:,
+        authorization_context: connection
+      )
+      return reject unless authorized
+
+      reference = Reference.new(actor_type:, actor_id:)
+      stream_from StreamName.for(reference)
+      ActorSnapshot.new(reference).observable_values.each do |name, value|
+        transmit TurboStreamRenderer.observable_value(reference, name, value)
+      end
+    rescue KeyError, InvalidStreamToken, UnknownActorType
+      reject
+    end
+  end
+end

data/lib/solid_objects/actor_definition.rb

@@ -0,0 +1,212 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  class ActorDefinition
+    Handler = Data.define(:name, :block)
+    StateMigration = Data.define(:from, :to, :block)
+
+    # @rbs @state_definition: StateDefinition
+    # @rbs @messages: Hash[Symbol, Handler]
+    # @rbs @queries: Hash[Symbol, Handler]
+    # @rbs @observables: Hash[Symbol, Handler]
+    # @rbs @state_version: Integer
+    # @rbs @state_migrations: Array[StateMigration]
+    # @rbs @activation_hooks: Array[Proc]
+    # @rbs @deactivation_hooks: Array[Proc]
+    # @rbs @attribute_queries: Hash[Symbol, bool]
+    # @rbs @method_messages: Hash[Symbol, bool]
+
+    attr_reader :state_definition,
+      :messages,
+      :queries,
+      :observables,
+      :state_version,
+      :state_migrations,
+      :activation_hooks,
+      :deactivation_hooks
+
+    # @rbs () -> void
+    def initialize
+      @state_definition = StateDefinition.new
+      @messages = {}
+      @queries = {}
+      @observables = {}
+      @state_version = 1
+      @state_migrations = []
+      @activation_hooks = []
+      @deactivation_hooks = []
+      @attribute_queries = {}
+      @method_messages = {}
+    end
+
+    # @rbs (Symbol | String, default: untyped) -> StateDefinition::Attribute
+    def add_attribute(name, default:)
+      attribute_name = name.to_sym
+      if messages.key?(attribute_name) || queries.key?(attribute_name)
+        raise InvalidActor, "#{attribute_name.inspect} is already defined"
+      end
+
+      state_definition.attribute(attribute_name, default:).tap do
+        queries[attribute_name] = Handler.new(
+          name: attribute_name,
+          block: -> { state.fetch(attribute_name) }
+        )
+        attribute_queries[attribute_name] = true
+      end
+    end
+
+    # @rbs (Symbol | String, Proc) -> Handler
+    def add_message(name, block)
+      add_handler(messages, name, block)
+    end
+
+    # @rbs (Symbol | String, Proc) -> Handler
+    def add_query(name, block)
+      query_name = name.to_sym
+      if attribute_queries.delete(query_name)
+        return Handler.new(name: query_name, block:).tap do |handler|
+          queries[query_name] = handler
+        end
+      end
+
+      add_handler(queries, name, block)
+    end
+
+    # @rbs (Symbol | String, Proc?) -> Handler
+    def add_observable(name, block = nil)
+      observable_name = name.to_sym
+      raise InvalidActor, "#{observable_name.inspect} observable is already defined" if observables.key?(observable_name)
+
+      observable_block = block || -> { state.fetch(observable_name) }
+      Handler.new(name: observable_name, block: observable_block).tap do |handler|
+        observables[observable_name] = handler
+      end
+    end
+
+    # @rbs (Class) -> ActorDefinition
+    def synchronize_instance_messages(actor_class)
+      names = actor_message_method_names(actor_class)
+
+      (method_messages.keys - names).each do |name|
+        messages.delete(name)
+        method_messages.delete(name)
+      end
+
+      names.each { |name| add_method_message(name) unless method_messages.key?(name) }
+      self
+    end
+
+    # @rbs (Integer) -> Integer
+    def set_state_version(version)
+      raise InvalidActor, "state version must be positive" unless version.positive?
+
+      @state_version = version
+    end
+
+    # @rbs (Integer, Integer, Proc) -> StateMigration
+    def add_state_migration(from, to, block)
+      unless to == from + 1
+        raise InvalidActor, "state migrations must advance exactly one version"
+      end
+
+      if state_migrations.any? { |migration| migration.from == from }
+        raise InvalidActor, "state migration from version #{from} is already defined"
+      end
+
+      StateMigration.new(from:, to:, block:).tap { |migration| state_migrations << migration }
+    end
+
+    # @rbs (Integer, Hash[String, untyped]) -> Hash[String, untyped]
+    def migrate_state(version, data)
+      migrated = Serialization.deep_copy(data)
+      current_version = version
+
+      while current_version < state_version
+        migration = state_migrations.find { |candidate| candidate.from == current_version }
+        raise StateMigrationError, "missing state migration from version #{current_version}" unless migration
+
+        migrated = Serialization.dump(migration.block.call(migrated))
+        current_version = migration.to
+      end
+
+      if current_version > state_version
+        raise StateMigrationError, "stored state version #{current_version} is newer than code version #{state_version}"
+      end
+
+      migrated
+    rescue StateMigrationError
+      raise
+    rescue => error
+      raise StateMigrationError, "state migration failed: #{error.message}"
+    end
+
+    # @rbs () -> ActorDefinition
+    def duplicate
+      self.class.new.tap do |copy|
+        copy.instance_variable_set(:@state_definition, state_definition.duplicate)
+        copy.instance_variable_set(:@messages, messages.dup)
+        copy.instance_variable_set(:@queries, queries.dup)
+        copy.instance_variable_set(:@observables, observables.dup)
+        copy.instance_variable_set(:@state_version, state_version)
+        copy.instance_variable_set(:@state_migrations, state_migrations.dup)
+        copy.instance_variable_set(:@activation_hooks, activation_hooks.dup)
+        copy.instance_variable_set(:@deactivation_hooks, deactivation_hooks.dup)
+        copy.instance_variable_set(:@attribute_queries, attribute_queries.dup)
+        copy.instance_variable_set(:@method_messages, method_messages.dup)
+      end
+    end
+
+    private
+
+    attr_reader :attribute_queries, :method_messages
+
+    # @rbs (Symbol) -> Handler
+    def add_method_message(name)
+      if messages.key?(name) || queries.key?(name)
+        raise InvalidActor, "#{name.inspect} is already defined"
+      end
+
+      Handler.new(
+        name:,
+        block: ->(**arguments) { public_send(name, **arguments) }
+      ).tap do |handler|
+        messages[name] = handler
+        method_messages[name] = true
+      end
+    end
+
+    # @rbs (Class) -> Array[Symbol]
+    def actor_message_method_names(actor_class)
+      actor_ancestors = actor_class.ancestors.take_while { |ancestor| ancestor != Actor }
+      attribute_method_names = actor_class.send(:generated_attribute_methods).keys
+      validate_attribute_methods!(attribute_method_names)
+
+      actor_class.public_instance_methods.filter_map do |name|
+        method_name = name.to_sym
+        next if attribute_method_names.include?(method_name)
+        next unless actor_ancestors.include?(actor_class.instance_method(method_name).owner)
+
+        method_name
+      end.uniq
+    end
+
+    # @rbs (Array[Symbol]) -> void
+    def validate_attribute_methods!(attribute_method_names)
+      state_definition.to_h.each_key do |name|
+        [ name, :"#{name}=" ].each do |method_name|
+          next if attribute_method_names.include?(method_name)
+
+          raise InvalidActor, "actor method #{method_name} overrides attribute #{name.inspect}"
+        end
+      end
+    end
+
+    # @rbs (Hash[Symbol, Handler], Symbol | String, Proc) -> Handler
+    def add_handler(collection, name, block)
+      handler_name = name.to_sym
+      raise InvalidActor, "#{handler_name.inspect} is already defined" if messages.key?(handler_name) || queries.key?(handler_name)
+
+      Handler.new(name: handler_name, block:).tap { |handler| collection[handler_name] = handler }
+    end
+  end
+end

data/lib/solid_objects/actor_registry.rb

@@ -0,0 +1,65 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  class ActorRegistry
+    # @rbs @actors: Hash[String, Class]
+    # @rbs @mutex: Mutex
+
+    # @rbs () -> void
+    def initialize
+      @actors = {}
+      @mutex = Mutex.new
+    end
+
+    # @rbs (String | Symbol, Class) -> Class
+    def register(type, actor_class)
+      actor_type = normalize(type)
+      validate_actor_class!(actor_class)
+
+      mutex.synchronize do
+        existing = actors[actor_type]
+        if existing && existing != actor_class
+          raise InvalidActor, "#{actor_type.inspect} is already registered by #{existing.name}"
+        end
+
+        actors[actor_type] = actor_class
+      end
+
+      actor_class
+    end
+
+    # @rbs (String | Symbol) -> Class
+    def fetch(type)
+      actor_type = normalize(type)
+      actors.fetch(actor_type) { raise UnknownActorType, "unknown actor type #{actor_type.inspect}" }
+    end
+
+    # @rbs (String | Symbol) -> bool
+    def registered?(type)
+      actors.key?(normalize(type))
+    end
+
+    # @rbs () -> Hash[String, Class]
+    def to_h
+      mutex.synchronize { actors.dup.freeze }
+    end
+
+    private
+
+    attr_reader :actors, :mutex
+
+    # @rbs (String | Symbol) -> String
+    def normalize(type)
+      type.to_s.tap do |value|
+        raise InvalidActor, "actor type cannot be empty" if value.empty?
+      end
+    end
+
+    # @rbs (untyped) -> void
+    def validate_actor_class!(actor_class)
+      return if actor_class.is_a?(Class) && actor_class < Actor
+
+      raise InvalidActor, "registered actor must inherit from SolidObjects::Actor"
+    end
+  end
+end