solid_queue_autoscaler 1.0.18 → 1.0.20

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 12251748d310789a1f51b7276742e216bb4f45c1baa17a70999210f65dce31a0
-  data.tar.gz: 2ee4b1e5aada9cd196021b9cc18d84b2a3e8550ff4e42b430c98318dd5fe2267
+  metadata.gz: 0f94990d679958250735f0fd7fa473c1d7e232d0f817479cfbd5f13c68d4f75b
+  data.tar.gz: 89178dfc3eed39b2553c99e778412158b6fe0582f6e3b59628892fd3a5e0251b
 SHA512:
-  metadata.gz: bbac46ee43f97d0c4beac6e5c54c1edd646b82c673eb524833ce5c9e3a812808ec1229385af5c4a28eff98b10e9d5b7ca52b3a2cc87776d4cbe0f5a34ef3d3e4
-  data.tar.gz: 9139d323751360748f79ea86263a59d6cf68eb4b1b7888d35659cf5c5fba76f0b9f3817b52695de98f388a4d981e7a20d363c608ecb3419239beeaf7943f4b25
+  metadata.gz: 9a7aaffab4800907fdf86f2037e64ce7aaff36999f1fe9bd4eae77e768ac4633261cc2ebb0e411977314ae9b50b110f5dc2350bc5c2b4ce059f41dd02bd3b91e
+  data.tar.gz: 3787b68c1338cd3df627487a145419c82a687930b050999237943008b1cb2a5521dac9bf74e0e82febf4571a789dc28fcaffc7a721676b402954320210734c57

data/CHANGELOG.md

@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.20] - 2025-02-02
+
+### Added
+- **Scale-from-zero optimization** - New configuration options for faster cold starts when `min_workers = 0`:
+  - `scale_from_zero_queue_depth` (default: 1) - Scale up immediately when at 0 workers if queue has at least this many jobs
+  - `scale_from_zero_latency_seconds` (default: 1.0) - Job must be at least this old before scaling up (gives other workers a chance to pick it up first)
+  - When at 0 workers, uses these lower thresholds instead of the normal `scale_up_queue_depth` and `scale_up_latency_seconds`
+  - Cooldowns are bypassed when scaling from 0 workers for fast cold start
+  - Comprehensive tests in `scale_to_zero_workflow_spec.rb`
+
+## [1.0.19] - 2025-02-02
+
+### Added
+- **AutoscaleJob string/symbol validation** - Detects when `recurring.yml` passes a quoted string like `":all"` instead of the symbol `:all`
+  - Raises a helpful `ConfigurationError` with exact before/after YAML examples
+  - Plain strings like `"default"` are leniently converted to symbols
+  - New `normalize_worker_name` helper method with comprehensive tests
+
+### Improved
+- **Better error message for missing Procfile process types** - When `batch_update` returns 404 (process type doesn't exist), the error now explains:
+  - The process type doesn't exist in the Procfile
+  - How to verify with `heroku ps -a <app_name>`
+  - That the configured `process_type` must exactly match a Procfile entry
+
 ## [1.0.18] - 2025-01-31
 
 ### Fixed

data/lib/solid_queue_autoscaler/adapters/heroku.rb

@@ -115,9 +115,24 @@ module SolidQueueAutoscaler
         end
         quantity
       rescue Excon::Error => e
+        status = e.respond_to?(:response) ? e.response&.status : nil
+        
+        # 404 from batch_update means the process type doesn't exist in the Procfile
+        # This is different from 404 on formation.update (which means scaled to 0)
+        if status == 404
+          raise HerokuAPIError.new(
+            "Process type '#{process_type}' does not exist. " \
+            "Verify that '#{process_type}:' is defined in your Procfile. " \
+            "Available process types can be viewed with 'heroku ps -a #{app_name}' or in your Procfile. " \
+            "The configured process_type must exactly match a Procfile entry.",
+            status_code: status,
+            response_body: e.respond_to?(:response) ? e.response&.body : nil
+          )
+        end
+
         raise HerokuAPIError.new(
           "Failed to create formation #{process_type} with quantity #{quantity}: #{e.message}",
-          status_code: e.respond_to?(:response) ? e.response&.status : nil,
+          status_code: status,
           response_body: e.respond_to?(:response) ? e.response&.body : nil
         )
       end

data/lib/solid_queue_autoscaler/autoscale_job.rb

@@ -21,6 +21,8 @@ module SolidQueueAutoscaler
     # @param worker_name [Symbol] The worker type to scale (:default, :critical_worker, etc.)
     #                             Pass :all to scale all registered workers
     def perform(worker_name = :default)
+      worker_name = normalize_worker_name(worker_name)
+
       if worker_name == :all
         perform_scale_all
       else
@@ -79,5 +81,33 @@ module SolidQueueAutoscaler
       worker_label = worker_name == :default ? '' : "[#{worker_name}] "
       Rails.logger.error("[AutoscaleJob] #{worker_label}Failed: #{result.error&.message}")
     end
+
+    # Normalize and validate worker_name argument.
+    # Detects common YAML misconfiguration where symbols are quoted as strings.
+    #
+    # @param worker_name [Symbol, String] The worker name to normalize
+    # @return [Symbol] The normalized worker name as a symbol
+    # @raise [ConfigurationError] If a string that looks like a symbol is passed
+    def normalize_worker_name(worker_name)
+      return worker_name if worker_name.is_a?(Symbol)
+
+      # Detect strings that look like symbols (e.g., ":all", ":default")
+      # This is a common YAML misconfiguration
+      if worker_name.is_a?(String) && worker_name.start_with?(':')
+        symbol_name = worker_name[1..] # Remove the leading colon
+        raise ConfigurationError,
+              "Invalid worker_name argument: received string #{worker_name.inspect} instead of symbol :#{symbol_name}. " \
+              "In your recurring.yml, change:\n" \
+              "  args:\n" \
+              "    - \"#{worker_name}\"\n" \
+              "to:\n" \
+              "  args:\n" \
+              "    - :#{symbol_name}\n" \
+              '(Remove the quotes around the symbol)'
+      end
+
+      # Convert plain strings to symbols (lenient mode)
+      worker_name.to_sym
+    end
   end
 end

data/lib/solid_queue_autoscaler/configuration.rb

@@ -69,6 +69,9 @@ module SolidQueueAutoscaler
     # AutoscaleJob settings
     attr_accessor :job_queue, :job_priority
 
+    # Scale-from-zero settings (for faster cold start when min_workers=0)
+    attr_accessor :scale_from_zero_queue_depth, :scale_from_zero_latency_seconds
+
     def initialize
       # Configuration name (auto-set when using named configurations)
       @name = :default
@@ -141,6 +144,11 @@ module SolidQueueAutoscaler
       # AutoscaleJob settings
       @job_queue = :autoscaler # Queue name for the autoscaler job
       @job_priority = nil # Job priority (lower = higher priority, nil = default)
+
+      # Scale-from-zero settings (for faster cold start when min_workers=0)
+      # When at 0 workers, use these lower thresholds instead of normal scale_up thresholds
+      @scale_from_zero_queue_depth = 1 # Scale up if at least 1 job in queue
+      @scale_from_zero_latency_seconds = 1.0 # Job must be at least 1 second old (gives other workers a chance)
     end
 
     # Returns the lock key, auto-generating based on name if not explicitly set
@@ -196,6 +204,10 @@ module SolidQueueAutoscaler
         errors << "scaling_strategy must be one of: #{VALID_SCALING_STRATEGIES.join(', ')}"
       end
 
+      # Validate scale-from-zero settings
+      errors << 'scale_from_zero_queue_depth must be > 0' if scale_from_zero_queue_depth <= 0
+      errors << 'scale_from_zero_latency_seconds must be >= 0' if scale_from_zero_latency_seconds.negative?
+
       raise ConfigurationError, errors.join(', ') if errors.any?
 
       true

data/lib/solid_queue_autoscaler/decision_engine.rb

@@ -41,12 +41,30 @@ module SolidQueueAutoscaler
     def should_scale_up?(metrics, current_workers)
       return false if current_workers >= @config.max_workers
 
+      # Special case: scale-from-zero uses lower thresholds for faster cold start
+      # This allows immediate scaling when at 0 workers with any work in queue
+      if current_workers.zero? && @config.min_workers.zero?
+        return should_scale_from_zero?(metrics)
+      end
+
       queue_depth_high = metrics.queue_depth >= @config.scale_up_queue_depth
       latency_high = metrics.oldest_job_age_seconds >= @config.scale_up_latency_seconds
 
       queue_depth_high || latency_high
     end
 
+    # Scale-from-zero check: uses lower thresholds for faster cold start
+    # Requires:
+    # 1. Queue depth >= scale_from_zero_queue_depth (default: 1)
+    # 2. Oldest job age >= scale_from_zero_latency_seconds (default: 1s)
+    #    This gives other workers/queues a chance to pick up the job first
+    def should_scale_from_zero?(metrics)
+      has_work = metrics.queue_depth >= @config.scale_from_zero_queue_depth
+      job_old_enough = metrics.oldest_job_age_seconds >= @config.scale_from_zero_latency_seconds
+
+      has_work && job_old_enough
+    end
+
     def should_scale_down?(metrics, current_workers)
       return false if current_workers <= @config.min_workers
 
@@ -161,12 +179,22 @@ module SolidQueueAutoscaler
     def build_scale_up_reason(metrics, current_workers = nil, target = nil)
       reasons = []
 
-      if metrics.queue_depth >= @config.scale_up_queue_depth
-        reasons << "queue_depth=#{metrics.queue_depth} >= #{@config.scale_up_queue_depth}"
-      end
+      # Check if this is a scale-from-zero scenario
+      is_scale_from_zero = current_workers&.zero? && @config.min_workers.zero? &&
+                           metrics.queue_depth >= @config.scale_from_zero_queue_depth &&
+                           metrics.oldest_job_age_seconds >= @config.scale_from_zero_latency_seconds
 
-      if metrics.oldest_job_age_seconds >= @config.scale_up_latency_seconds
-        reasons << "latency=#{metrics.oldest_job_age_seconds.round}s >= #{@config.scale_up_latency_seconds}s"
+      if is_scale_from_zero
+        reasons << "scale_from_zero: queue_depth=#{metrics.queue_depth} >= #{@config.scale_from_zero_queue_depth}"
+        reasons << "job_age=#{metrics.oldest_job_age_seconds.round(1)}s >= #{@config.scale_from_zero_latency_seconds}s"
+      else
+        if metrics.queue_depth >= @config.scale_up_queue_depth
+          reasons << "queue_depth=#{metrics.queue_depth} >= #{@config.scale_up_queue_depth}"
+        end
+
+        if metrics.oldest_job_age_seconds >= @config.scale_up_latency_seconds
+          reasons << "latency=#{metrics.oldest_job_age_seconds.round}s >= #{@config.scale_up_latency_seconds}s"
+        end
       end
 
       base_reason = reasons.join(', ')

data/lib/solid_queue_autoscaler/scaler.rb

@@ -185,6 +185,12 @@ module SolidQueueAutoscaler
     end
 
     def cooldown_active?(decision)
+      # Bypass cooldowns when scaling from zero - we want fast cold start
+      # This is safe because there are no workers to destabilize
+      if decision.scale_up? && decision.from.zero? && @config.min_workers.zero?
+        return false
+      end
+
       if @config.persist_cooldowns && cooldown_tracker.table_exists?
         # Use database-persisted cooldowns (survives process restarts)
         if decision.scale_up?

data/lib/solid_queue_autoscaler/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: solid_queue_autoscaler
 version: !ruby/object:Gem::Version
-  version: 1.0.18
+  version: 1.0.20
 platform: ruby
 authors:
 - reillyse
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-01-31 00:00:00.000000000 Z
+date: 2026-02-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord