solid_objects 0.1.0

data/lib/solid_objects/serialization.rb

@@ -0,0 +1,99 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  module Serialization
+    MAX_NESTING = 100
+
+    class << self
+      # @rbs (untyped, ?max_bytes: Integer?) -> untyped
+      def dump(value, max_bytes: nil)
+        normalized = normalize(value)
+        encoded = JSON.generate(normalized, max_nesting: MAX_NESTING)
+
+        if max_bytes && encoded.bytesize > max_bytes
+          raise PayloadTooLarge, "serialized value exceeds #{max_bytes} bytes"
+        end
+
+        normalized
+      rescue JSON::GeneratorError, EncodingError => error
+        raise InvalidPayload, error.message
+      end
+
+      # @rbs (untyped) -> untyped
+      def load(value)
+        return nil if value.nil?
+
+        normalize(value)
+      end
+
+      # @rbs (untyped) -> untyped
+      def deep_copy(value)
+        JSON.parse(JSON.generate(normalize(value), max_nesting: MAX_NESTING))
+      rescue JSON::GeneratorError, JSON::ParserError, EncodingError => error
+        raise InvalidPayload, error.message
+      end
+
+      # @rbs (untyped) -> untyped
+      def readonly_copy(value)
+        freeze_recursively(deep_copy(value))
+      end
+
+      private
+
+      # @rbs (untyped) -> untyped
+      def freeze_recursively(value)
+        case value
+        when Array
+          value.each { |item| freeze_recursively(item) }
+        when Hash
+          value.each do |key, item|
+            freeze_recursively(key)
+            freeze_recursively(item)
+          end
+        end
+
+        value.freeze
+      end
+
+      # @rbs (untyped, ?depth: Integer) -> untyped
+      def normalize(value, depth: 0)
+        raise InvalidPayload, "serialized value is nested too deeply" if depth > MAX_NESTING
+
+        case value
+        when nil, true, false, String, Integer
+          value
+        when Float
+          raise InvalidPayload, "non-finite numbers are not supported" unless value.finite?
+
+          value
+        when Symbol
+          value.to_s
+        when Array
+          value.map { |item| normalize(item, depth: depth + 1) }
+        when Hash
+          normalize_hash(value, depth:)
+        else
+          raise InvalidPayload, "#{value.class} is not JSON-compatible"
+        end
+      end
+
+      # @rbs (Hash[untyped, untyped], depth: Integer) -> Hash[String, untyped]
+      def normalize_hash(value, depth:)
+        value.each_with_object({}) do |(key, item), normalized|
+          normalized_key = normalize_key(key)
+          raise InvalidPayload, "duplicate key after normalization: #{normalized_key}" if normalized.key?(normalized_key)
+
+          normalized[normalized_key] = normalize(item, depth: depth + 1)
+        end
+      end
+
+      # @rbs (untyped) -> String
+      def normalize_key(key)
+        return key if key.is_a?(String)
+        return key.to_s if key.is_a?(Symbol)
+
+        raise InvalidPayload, "JSON object keys must be strings or symbols"
+      end
+    end
+  end
+end

data/lib/solid_objects/state.rb

@@ -0,0 +1,111 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  class StateDefinition
+    Attribute = Data.define(:name, :default)
+
+    # @rbs @attributes: Hash[Symbol, Attribute]
+
+    # @rbs () -> void
+    def initialize
+      @attributes = {}
+    end
+
+    # @rbs (Symbol | String, ?default: untyped) -> Attribute
+    def attribute(name, default: nil)
+      attribute_name = name.to_sym
+      raise InvalidActor, "state attribute #{attribute_name.inspect} is already defined" if attributes.key?(attribute_name)
+
+      attributes[attribute_name] = Attribute.new(name: attribute_name, default:)
+    end
+
+    # @rbs () -> Hash[Symbol, Attribute]
+    def to_h
+      attributes.dup.freeze
+    end
+
+    # @rbs () -> StateDefinition
+    def duplicate
+      self.class.new.tap do |definition|
+        attributes.each_value { |attribute| definition.attribute(attribute.name, default: attribute.default) }
+      end
+    end
+
+    private
+
+    attr_reader :attributes
+  end
+
+  class State
+    # @rbs @definition: StateDefinition
+    # @rbs @data: Hash[String, untyped]
+
+    # @rbs (StateDefinition, Hash[String, untyped]?) -> void
+    def initialize(definition, data = nil)
+      @definition = definition
+      @data = data ? Serialization.deep_copy(data) : {}
+      apply_defaults
+    end
+
+    # @rbs () -> Hash[String, untyped]
+    def to_h
+      Serialization.deep_copy(data)
+    end
+
+    # @rbs (Symbol | String) -> untyped
+    def fetch(name)
+      key = name.to_s
+      raise NoMethodError, "undefined state attribute #{name.inspect}" unless defined_attribute?(name)
+
+      data.fetch(key)
+    end
+
+    # @rbs (Symbol | String, untyped) -> untyped
+    def write(name, value)
+      key = name.to_s
+      raise NoMethodError, "undefined state attribute #{name.inspect}" unless defined_attribute?(name)
+
+      data[key] = value
+    end
+
+    # @rbs (Symbol, *untyped) -> untyped
+    def method_missing(name, *arguments)
+      name_string = name.to_s
+
+      if name_string.end_with?("=")
+        attribute_name = name_string.delete_suffix("=")
+        return write(attribute_name, arguments.fetch(0)) if arguments.one? && defined_attribute?(attribute_name)
+      elsif arguments.empty? && defined_attribute?(name)
+        return fetch(name)
+      end
+
+      super
+    end
+
+    # @rbs (Symbol, bool) -> bool
+    def respond_to_missing?(name, include_private = false)
+      attribute_name = name.to_s.delete_suffix("=")
+      defined_attribute?(attribute_name) || super
+    end
+
+    private
+
+    attr_reader :definition, :data
+
+    # @rbs () -> void
+    def apply_defaults
+      definition.to_h.each_value do |attribute|
+        key = attribute.name.to_s
+        next if data.key?(key)
+
+        value = attribute.default.respond_to?(:call) ? attribute.default.call : attribute.default
+        data[key] = Serialization.deep_copy(value)
+      end
+    end
+
+    # @rbs (Symbol | String) -> bool
+    def defined_attribute?(name)
+      definition.to_h.key?(name.to_sym)
+    end
+  end
+end

data/lib/solid_objects/stream_name.rb

@@ -0,0 +1,29 @@
+# rbs_inline: enabled
+
+require "digest"
+
+module SolidObjects
+  module StreamName
+    module_function
+
+    # @rbs (Reference | Hash[String, String]) -> String
+    def for(reference)
+      identity = identity_for(reference)
+      digest = Digest::SHA256.hexdigest(
+        "#{identity.fetch("actor_type")}\0#{identity.fetch("actor_id")}"
+      ).first(32)
+      "solid_objects_stream_#{digest}"
+    end
+
+    # @rbs (Reference | Hash[String, String]) -> Hash[String, String]
+    def identity_for(reference)
+      return reference if reference.is_a?(Hash)
+
+      {
+        "actor_type" => reference.actor_type,
+        "actor_id" => reference.actor_id
+      }
+    end
+    private_class_method :identity_for
+  end
+end

data/lib/solid_objects/stream_token.rb

@@ -0,0 +1,59 @@
+# rbs_inline: enabled
+
+require "active_support/message_verifier"
+
+module SolidObjects
+  module StreamToken
+    PURPOSE = "solid_objects.actor_stream"
+
+    module_function
+
+    # @rbs (Reference) -> String
+    def generate(reference)
+      verifier.generate(
+        {
+          "actor_type" => reference.actor_type,
+          "actor_id" => reference.actor_id
+        },
+        purpose: PURPOSE
+      )
+    end
+
+    # @rbs (String) -> Hash[String, String]
+    def verify(token)
+      identity = verifier.verified(token, purpose: PURPOSE)
+      unless identity.is_a?(Hash) &&
+          identity["actor_type"].is_a?(String) &&
+          identity["actor_id"].is_a?(String)
+        raise InvalidStreamToken, "invalid actor stream token"
+      end
+
+      identity
+    rescue ActiveSupport::MessageVerifier::InvalidSignature
+      raise InvalidStreamToken, "invalid actor stream token"
+    end
+
+    # @rbs () -> ActiveSupport::MessageVerifier
+    def verifier
+      ActiveSupport::MessageVerifier.new(
+        signing_secret,
+        digest: "SHA256",
+        serializer: JSON
+      )
+    end
+    private_class_method :verifier
+
+    # @rbs () -> String
+    def signing_secret
+      configured_secret = SolidObjects.configuration.stream_signing_secret
+      return configured_secret if configured_secret
+
+      if defined?(Rails) && Rails.respond_to?(:application) && Rails.application
+        return Rails.application.key_generator.generate_key(PURPOSE, 64)
+      end
+
+      raise ArgumentError, "configure stream_signing_secret outside a Rails application"
+    end
+    private_class_method :signing_secret
+  end
+end

data/lib/solid_objects/supervisor.rb

@@ -0,0 +1,87 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  class Supervisor
+    # @rbs @components: Array[Worker | EffectExecutor | ReminderScheduler | BroadcastExecutor]
+    # @rbs @threads: Array[Thread]
+    # @rbs @started: bool
+
+    # @rbs (?worker_count: Integer, ?effect_worker_count: Integer, ?broadcast_worker_count: Integer, ?reminder_scheduler_count: Integer) -> void
+    def initialize(
+      worker_count: SolidObjects.configuration.worker_count,
+      effect_worker_count: SolidObjects.configuration.effect_worker_count,
+      broadcast_worker_count: SolidObjects.configuration.broadcast_worker_count,
+      reminder_scheduler_count: SolidObjects.configuration.reminder_scheduler_count
+    )
+      @components = build_components(
+        worker_count:,
+        effect_worker_count:,
+        broadcast_worker_count:,
+        reminder_scheduler_count:
+      )
+      @threads = []
+      @started = false
+    end
+
+    # @rbs () -> void
+    def run
+      start
+      threads.each(&:join)
+    ensure
+      stop
+    end
+
+    # @rbs () -> void
+    def start
+      return if @started
+
+      @started = true
+      @threads = components.map { |component| Thread.new { component.run } }
+      SolidObjects.instrument(:"supervisor.started", component_count: components.length)
+    end
+
+    # @rbs () -> void
+    def stop
+      return unless @started
+
+      components.each(&:request_shutdown)
+      join_until_timeout
+      components.reject(&:stopped?).each(&:stop)
+      @started = false
+      SolidObjects.instrument(:"supervisor.stopped", component_count: components.length)
+    end
+
+    private
+
+    attr_reader :components, :threads
+
+    # @rbs (worker_count: Integer, effect_worker_count: Integer, broadcast_worker_count: Integer, reminder_scheduler_count: Integer) -> Array[Worker | EffectExecutor | ReminderScheduler | BroadcastExecutor]
+    def build_components(
+      worker_count:,
+      effect_worker_count:,
+      broadcast_worker_count:,
+      reminder_scheduler_count:
+    )
+      Array.new(worker_count) { Worker.new } +
+        Array.new(effect_worker_count) { EffectExecutor.new } +
+        Array.new(broadcast_worker_count) { BroadcastExecutor.new } +
+        Array.new(reminder_scheduler_count) { ReminderScheduler.new }
+    end
+
+    # @rbs () -> void
+    def join_until_timeout
+      deadline = monotonic_now + SolidObjects.configuration.shutdown_timeout
+      threads.each do |thread|
+        remaining = deadline - monotonic_now
+        break unless remaining.positive?
+
+        thread.join(remaining)
+      end
+    end
+
+    # @rbs () -> Float
+    def monotonic_now
+      ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/solid_objects/turbo_stream_renderer.rb

@@ -0,0 +1,35 @@
+# rbs_inline: enabled
+
+require "erb"
+
+module SolidObjects
+  module TurboStreamRenderer
+    module_function
+
+    # @rbs (Broadcast) -> String
+    def observable(broadcast)
+      reference = Reference.new(
+        actor_type: broadcast.instance.actor_type,
+        actor_id: broadcast.instance.actor_id
+      )
+      observable_value(reference, broadcast.observable_name, broadcast.value)
+    end
+
+    # @rbs (Reference, Symbol | String, untyped) -> String
+    def observable_value(reference, name, value)
+      target = DomIdentity.observable(reference, name)
+      content = ERB::Util.html_escape(display_value(value))
+      %(<turbo-stream action="replace" target="#{target}"><template><span id="#{target}">#{content}</span></template></turbo-stream>)
+    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
+    private_class_method :display_value
+  end
+end

data/lib/solid_objects/version.rb

@@ -0,0 +1,5 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  VERSION = "0.1.0"
+end

data/lib/solid_objects/wake_up.rb

@@ -0,0 +1,28 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  class WakeUp
+    # @rbs @mutex: Mutex
+    # @rbs @condition: Thread::ConditionVariable
+
+    # @rbs () -> void
+    def initialize
+      @mutex = Mutex.new
+      @condition = Thread::ConditionVariable.new
+    end
+
+    # @rbs () -> void
+    def signal
+      mutex.synchronize { condition.broadcast }
+    end
+
+    # @rbs (timeout: Numeric) -> void
+    def wait(timeout:)
+      mutex.synchronize { condition.wait(mutex, timeout) }
+    end
+
+    private
+
+    attr_reader :mutex, :condition
+  end
+end

data/lib/solid_objects/worker.rb

@@ -0,0 +1,139 @@
+# rbs_inline: enabled
+
+require "solid_objects/process_registry"
+require "solid_objects/activation_manager"
+require "solid_objects/activation"
+require "solid_objects/executor"
+require "solid_objects/lease_renewer"
+
+module SolidObjects
+  class Worker
+    # @rbs @process_registry: ProcessRegistry
+    # @rbs @activation_manager: ActivationManager
+    # @rbs @activations: Hash[Integer, Activation]
+    # @rbs @stopped: bool
+    # @rbs @shutdown_requested: bool
+
+    # @rbs (?process_registry: ProcessRegistry) -> void
+    def initialize(process_registry: ProcessRegistry.new)
+      @process_registry = process_registry
+      process_record = process_registry.register
+      @activation_manager = ActivationManager.new(owner_id: process_record.id)
+      @activations = {}
+      @stopped = false
+      @shutdown_requested = false
+    end
+
+    # @rbs () -> Integer
+    def run_once
+      return 0 if stopped?
+
+      process_registry.heartbeat
+      maintain_cached_activations
+      activation = cached_ready_activation || activation_manager.claim_next
+      return 0 unless activation
+
+      activations[activation.lease.instance_id] = activation
+      processed = LeaseRenewer.new(
+        activation:,
+        process_registry:
+      ).around { activation.drain }
+      release_activation(activation) if activation.pass_exhausted?
+      processed
+    rescue ActorDestroyed
+      release_activation(activation) if activation
+      0
+    rescue StateMigrationError, LostActivation => error
+      release_activation(activation) if activation
+      SolidObjects.configuration.logger.error(
+        event: "solid_objects.worker.error",
+        process_id: process_registry.process_record&.id,
+        error_class: error.class.name,
+        error_message: error.message
+      )
+      0
+    end
+
+    # @rbs (?max_passes: Integer) -> Integer
+    def run_until_idle(max_passes: 1_000)
+      total = 0
+
+      max_passes.times do
+        processed = run_once
+        break if processed.zero?
+
+        total += processed
+      end
+
+      total
+    end
+
+    # @rbs () -> void
+    def run
+      until shutdown_requested?
+        processed = run_once
+        next if processed.positive?
+
+        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 () -> void
+    def stop
+      return if stopped?
+
+      @stopped = true
+      process_registry.start_draining
+      activations.each_value(&:deactivate)
+      activations.clear
+      process_registry.stop
+    end
+
+    # @rbs () -> bool
+    def stopped?
+      @stopped
+    end
+
+    # @rbs () -> bool
+    def shutdown_requested?
+      @shutdown_requested
+    end
+
+    private
+
+    attr_reader :process_registry, :activation_manager, :activations
+
+    # @rbs () -> Activation?
+    def cached_ready_activation
+      activations.each_value.find(&:ready?)
+    end
+
+    # @rbs () -> void
+    def maintain_cached_activations
+      activations.each_value do |activation|
+        if activation.idle?
+          release_activation(activation)
+        elsif activation.lease_renewal_due?
+          activation.renew_lease
+        end
+      rescue LostActivation
+        release_activation(activation)
+      end
+    end
+
+    # @rbs (Activation) -> void
+    def release_activation(activation)
+      activations.delete(activation.lease.instance_id)
+      activation.yield_ready_messages if activation.pass_exhausted?
+      activation.deactivate
+    end
+  end
+end