solid_queue_autoscaler 1.0.0

data/lib/solid_queue_autoscaler/scaler.rb

@@ -0,0 +1,294 @@
+# frozen_string_literal: true
+
+module SolidQueueAutoscaler
+  class Scaler
+    ScaleResult = Struct.new(
+      :success,
+      :decision,
+      :metrics,
+      :error,
+      :skipped_reason,
+      :executed_at,
+      keyword_init: true
+    ) do
+      def success?
+        success == true
+      end
+
+      def skipped?
+        !skipped_reason.nil?
+      end
+
+      def scaled?
+        success? && decision && !decision.no_change?
+      end
+    end
+
+    # Per-configuration cooldown tracking for multi-worker support
+    class << self
+      def cooldown_mutex
+        @cooldown_mutex ||= Mutex.new
+      end
+
+      def cooldowns
+        @cooldowns ||= {}
+      end
+
+      def last_scale_up_at(config_name = :default)
+        cooldown_mutex.synchronize { cooldowns.dig(config_name, :scale_up) }
+      end
+
+      def set_last_scale_up_at(config_name, value)
+        cooldown_mutex.synchronize do
+          cooldowns[config_name] ||= {}
+          cooldowns[config_name][:scale_up] = value
+        end
+      end
+
+      def last_scale_down_at(config_name = :default)
+        cooldown_mutex.synchronize { cooldowns.dig(config_name, :scale_down) }
+      end
+
+      def set_last_scale_down_at(config_name, value)
+        cooldown_mutex.synchronize do
+          cooldowns[config_name] ||= {}
+          cooldowns[config_name][:scale_down] = value
+        end
+      end
+
+      def reset_cooldowns!(config_name = nil)
+        cooldown_mutex.synchronize do
+          if config_name
+            cooldowns.delete(config_name)
+          else
+            @cooldowns = {}
+          end
+        end
+      end
+
+      # Backward compatibility setters
+      def last_scale_up_at=(value)
+        set_last_scale_up_at(:default, value)
+      end
+
+      def last_scale_down_at=(value)
+        set_last_scale_down_at(:default, value)
+      end
+    end
+
+    def initialize(config: nil)
+      @config = config || SolidQueueAutoscaler.config
+      @lock = AdvisoryLock.new(config: @config)
+      @metrics_collector = Metrics.new(config: @config)
+      @decision_engine = DecisionEngine.new(config: @config)
+      @adapter = @config.adapter
+    end
+
+    def run
+      return skipped_result('Autoscaler is disabled') unless @config.enabled?
+
+      return skipped_result('Could not acquire advisory lock (another instance is running)') unless @lock.try_lock
+
+      begin
+        execute_scaling
+      ensure
+        @lock.release
+      end
+    end
+
+    def run!
+      @lock.with_lock do
+        execute_scaling
+      end
+    end
+
+    private
+
+    def execute_scaling
+      metrics = @metrics_collector.collect
+      current_workers = @adapter.current_workers
+      decision = @decision_engine.decide(metrics: metrics, current_workers: current_workers)
+
+      log_decision(decision, metrics)
+
+      return success_result(decision, metrics) if decision.no_change?
+
+      if cooldown_active?(decision)
+        remaining = cooldown_remaining(decision)
+        return skipped_result("Cooldown active (#{remaining.round}s remaining)", decision: decision, metrics: metrics)
+      end
+
+      apply_decision(decision, metrics)
+    rescue StandardError => e
+      error_result(e)
+    end
+
+    def apply_decision(decision, metrics)
+      @adapter.scale(decision.to)
+      record_scale_time(decision)
+      record_scale_event(decision, metrics)
+
+      log_scale_action(decision)
+
+      success_result(decision, metrics)
+    end
+
+    def cooldown_active?(decision)
+      config_name = @config.name
+      if decision.scale_up?
+        last_scale_up = self.class.last_scale_up_at(config_name)
+        return false unless last_scale_up
+
+        Time.current - last_scale_up < @config.effective_scale_up_cooldown
+      elsif decision.scale_down?
+        last_scale_down = self.class.last_scale_down_at(config_name)
+        return false unless last_scale_down
+
+        Time.current - last_scale_down < @config.effective_scale_down_cooldown
+      else
+        false
+      end
+    end
+
+    def cooldown_remaining(decision)
+      config_name = @config.name
+      if decision.scale_up?
+        elapsed = Time.current - self.class.last_scale_up_at(config_name)
+        @config.effective_scale_up_cooldown - elapsed
+      else
+        elapsed = Time.current - self.class.last_scale_down_at(config_name)
+        @config.effective_scale_down_cooldown - elapsed
+      end
+    end
+
+    def record_scale_time(decision)
+      config_name = @config.name
+      if decision.scale_up?
+        self.class.set_last_scale_up_at(config_name, Time.current)
+      elsif decision.scale_down?
+        self.class.set_last_scale_down_at(config_name, Time.current)
+      end
+    end
+
+    def log_decision(decision, metrics)
+      worker_label = @config.name == :default ? '' : "[#{@config.name}] "
+      logger.info(
+        "[Autoscaler] #{worker_label}Evaluated: action=#{decision.action} " \
+        "workers=#{decision.from}->#{decision.to} " \
+        "queue_depth=#{metrics.queue_depth} " \
+        "latency=#{metrics.oldest_job_age_seconds.round}s " \
+        "reason=\"#{decision.reason}\""
+      )
+    end
+
+    def log_scale_action(decision)
+      prefix = @config.dry_run? ? '[DRY RUN] ' : ''
+      worker_label = @config.name == :default ? '' : "[#{@config.name}] "
+      logger.info(
+        "#{prefix}[Autoscaler] #{worker_label}Scaling #{decision.action}: " \
+        "#{decision.from} -> #{decision.to} workers (#{decision.reason})"
+      )
+    end
+
+    def success_result(decision, metrics)
+      # Record no_change events if configured
+      record_scale_event(decision, metrics) if decision&.no_change? && @config.record_all_events?
+
+      ScaleResult.new(
+        success: true,
+        decision: decision,
+        metrics: metrics,
+        executed_at: Time.current
+      )
+    end
+
+    def skipped_result(reason, decision: nil, metrics: nil)
+      logger.debug("[Autoscaler] Skipped: #{reason}")
+
+      # Record skipped events
+      record_skipped_event(reason, decision, metrics)
+
+      ScaleResult.new(
+        success: true,
+        decision: decision,
+        metrics: metrics,
+        skipped_reason: reason,
+        executed_at: Time.current
+      )
+    end
+
+    def error_result(error)
+      logger.error("[Autoscaler] Error: #{error.class}: #{error.message}")
+
+      # Record error events
+      record_error_event(error)
+
+      ScaleResult.new(
+        success: false,
+        error: error,
+        executed_at: Time.current
+      )
+    end
+
+    def logger
+      @config.logger
+    end
+
+    def record_scale_event(decision, metrics)
+      return unless @config.record_events?
+
+      ScaleEvent.create!(
+        {
+          worker_name: @config.name.to_s,
+          action: decision.action.to_s,
+          from_workers: decision.from,
+          to_workers: decision.to,
+          reason: decision.reason,
+          queue_depth: metrics&.queue_depth || 0,
+          latency_seconds: metrics&.oldest_job_age_seconds || 0.0,
+          metrics_json: metrics&.to_h&.to_json,
+          dry_run: @config.dry_run?
+        },
+        connection: @config.connection
+      )
+    end
+
+    def record_skipped_event(reason, decision, metrics)
+      return unless @config.record_events?
+
+      ScaleEvent.create!(
+        {
+          worker_name: @config.name.to_s,
+          action: 'skipped',
+          from_workers: decision&.from || 0,
+          to_workers: decision&.to || 0,
+          reason: reason,
+          queue_depth: metrics&.queue_depth || 0,
+          latency_seconds: metrics&.oldest_job_age_seconds || 0.0,
+          metrics_json: metrics&.to_h&.to_json,
+          dry_run: @config.dry_run?
+        },
+        connection: @config.connection
+      )
+    end
+
+    def record_error_event(error)
+      return unless @config.record_events?
+
+      ScaleEvent.create!(
+        {
+          worker_name: @config.name.to_s,
+          action: 'error',
+          from_workers: 0,
+          to_workers: 0,
+          reason: "#{error.class}: #{error.message}",
+          queue_depth: 0,
+          latency_seconds: 0.0,
+          metrics_json: nil,
+          dry_run: @config.dry_run?
+        },
+        connection: @config.connection
+      )
+    end
+  end
+end

data/lib/solid_queue_autoscaler/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SolidQueueAutoscaler
+  VERSION = '1.0.0'
+end

data/lib/solid_queue_autoscaler.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require 'active_record'
+require 'active_support'
+require 'active_support/core_ext/numeric/time'
+
+require_relative 'solid_queue_autoscaler/version'
+require_relative 'solid_queue_autoscaler/errors'
+require_relative 'solid_queue_autoscaler/adapters'
+require_relative 'solid_queue_autoscaler/configuration'
+require_relative 'solid_queue_autoscaler/advisory_lock'
+require_relative 'solid_queue_autoscaler/metrics'
+require_relative 'solid_queue_autoscaler/decision_engine'
+require_relative 'solid_queue_autoscaler/cooldown_tracker'
+require_relative 'solid_queue_autoscaler/scale_event'
+require_relative 'solid_queue_autoscaler/scaler'
+
+module SolidQueueAutoscaler
+  class << self
+    # Registry of named configurations for multi-worker support
+    def configurations
+      @configurations ||= {}
+    end
+
+    # Configure a named worker type (default: :default for backward compatibility)
+    # @param name [Symbol] The name of the worker type (e.g., :critical_worker, :default_worker)
+    # @yield [Configuration] The configuration object to customize
+    # @return [Configuration] The configured configuration object
+    def configure(name = :default)
+      config_obj = configurations[name] ||= Configuration.new
+      config_obj.name = name
+      yield(config_obj) if block_given?
+      config_obj.validate!
+      config_obj
+    end
+
+    # Get configuration for a named worker type
+    # @param name [Symbol] The name of the worker type
+    # @return [Configuration] The configuration object
+    def config(name = :default)
+      configurations[name] || configure(name)
+    end
+
+    # Scale a specific worker type
+    # @param name [Symbol] The name of the worker type to scale
+    # @return [Scaler::ScaleResult] The result of the scaling operation
+    def scale!(name = :default)
+      Scaler.new(config: config(name)).run
+    end
+
+    # Scale all configured worker types
+    # @return [Hash<Symbol, Scaler::ScaleResult>] Results keyed by worker name
+    def scale_all!
+      return {} if configurations.empty?
+
+      # Copy keys to avoid modifying hash during iteration
+      worker_names = configurations.keys.dup
+      worker_names.each_with_object({}) do |name, results|
+        results[name] = scale!(name)
+      end
+    end
+
+    # Get metrics for a specific worker type
+    # @param name [Symbol] The name of the worker type
+    # @return [Metrics::Result] The collected metrics
+    def metrics(name = :default)
+      Metrics.new(config: config(name)).collect
+    end
+
+    # Get current worker count for a specific worker type
+    # @param name [Symbol] The name of the worker type
+    # @return [Integer] The current number of workers
+    def current_workers(name = :default)
+      config(name).adapter.current_workers
+    end
+
+    # List all registered worker type names
+    # @return [Array<Symbol>] List of configured worker names
+    def registered_workers
+      configurations.keys
+    end
+
+    # Reset all configurations (useful for testing)
+    def reset_configuration!
+      @configurations = {}
+      Scaler.reset_cooldowns!
+    end
+
+    # Backward compatibility: single configuration accessor
+    def configuration
+      configurations[:default]
+    end
+
+    def configuration=(config_obj)
+      if config_obj.nil?
+        @configurations = {}
+      else
+        config_obj.name ||= :default
+        configurations[:default] = config_obj
+      end
+    end
+  end
+end
+
+require_relative 'solid_queue_autoscaler/railtie' if defined?(Rails::Railtie)
+require_relative 'solid_queue_autoscaler/dashboard'
+
+require_relative 'solid_queue_autoscaler/autoscale_job' if defined?(ActiveJob::Base)

metadata

@@ -0,0 +1,179 @@
+--- !ruby/object:Gem::Specification
+name: solid_queue_autoscaler
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- reillyse
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-01-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: platform-api
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+description: A control plane for Solid Queue on Heroku that automatically scales worker
+  dynos based on queue depth, job latency, and throughput. Uses PostgreSQL advisory
+  locks for singleton behavior and the Heroku Platform API for scaling.
+email: []
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/generators/solid_queue_autoscaler/dashboard_generator.rb
+- lib/generators/solid_queue_autoscaler/install_generator.rb
+- lib/generators/solid_queue_autoscaler/migration_generator.rb
+- lib/generators/solid_queue_autoscaler/templates/README
+- lib/generators/solid_queue_autoscaler/templates/create_solid_queue_autoscaler_events.rb.erb
+- lib/generators/solid_queue_autoscaler/templates/create_solid_queue_autoscaler_state.rb.erb
+- lib/generators/solid_queue_autoscaler/templates/initializer.rb
+- lib/solid_queue_autoscaler.rb
+- lib/solid_queue_autoscaler/adapters.rb
+- lib/solid_queue_autoscaler/adapters/base.rb
+- lib/solid_queue_autoscaler/adapters/heroku.rb
+- lib/solid_queue_autoscaler/adapters/kubernetes.rb
+- lib/solid_queue_autoscaler/advisory_lock.rb
+- lib/solid_queue_autoscaler/autoscale_job.rb
+- lib/solid_queue_autoscaler/configuration.rb
+- lib/solid_queue_autoscaler/cooldown_tracker.rb
+- lib/solid_queue_autoscaler/dashboard.rb
+- lib/solid_queue_autoscaler/dashboard/engine.rb
+- lib/solid_queue_autoscaler/dashboard/views/layouts/solid_queue_heroku_autoscaler/dashboard/application.html.erb
+- lib/solid_queue_autoscaler/dashboard/views/solid_queue_heroku_autoscaler/dashboard/dashboard/index.html.erb
+- lib/solid_queue_autoscaler/dashboard/views/solid_queue_heroku_autoscaler/dashboard/events/index.html.erb
+- lib/solid_queue_autoscaler/dashboard/views/solid_queue_heroku_autoscaler/dashboard/workers/index.html.erb
+- lib/solid_queue_autoscaler/dashboard/views/solid_queue_heroku_autoscaler/dashboard/workers/show.html.erb
+- lib/solid_queue_autoscaler/decision_engine.rb
+- lib/solid_queue_autoscaler/errors.rb
+- lib/solid_queue_autoscaler/metrics.rb
+- lib/solid_queue_autoscaler/railtie.rb
+- lib/solid_queue_autoscaler/scale_event.rb
+- lib/solid_queue_autoscaler/scaler.rb
+- lib/solid_queue_autoscaler/version.rb
+homepage: https://github.com/reillyse/solid_queue_autoscaler
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/reillyse/solid_queue_autoscaler
+  source_code_uri: https://github.com/reillyse/solid_queue_autoscaler
+  changelog_uri: https://github.com/reillyse/solid_queue_autoscaler/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Auto-scale Solid Queue workers on Heroku based on queue metrics
+test_files: []