solid_queue_autoscaler 1.0.15 → 1.0.16

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bafb0cda485024f43bd0e73291bcb0bbbc7275e3f897d4a2acafbd6496140b98
-  data.tar.gz: 4b443c68ca28df2b3efd62a4cd7ae30f6cf53e978c941a1e60aa7ebd0c7befb0
+  metadata.gz: 0d2ec8d0897f2312d05ccc10d075e5b90bd7c31e5e699fc34bfff13ba5be513b
+  data.tar.gz: b6e26a9f33e0c86f8809c4c52f04059ed62b4f1c3097ef6421a25cafb5eeed72
 SHA512:
-  metadata.gz: 943bd220740694c827afc4c3aede77cac6da3b419eda051c686b5fb07cfbb69da28b6b8d5882fcf61122bfc6991352e52b9dab2b7f05982333324efbce20205f
-  data.tar.gz: a201785b1ecc766f744a7d705f64dd1e7afaa611e004f3fb9f003a28a05a397fc412ec276a17b99c4bbad0cf89ed476884f510986e3f95e9f9385252d7e15d31
+  metadata.gz: 4d9cd4937e412fded6a640c9044dfa846b7006848647a3ffa2c78a70fe3f0b03bf1b5f34dc0555f0e5489e0d3c4d23fef575c4e7f16ff421ad2385355ea6919f
+  data.tar.gz: 1ed169508ba540f4ec3dcfaf6bcea5d04812f4385c4231f0033a98d10b891d3722f2b0d46184d4bd7ffea9b860b6e70f5b3b07856533104ae06e3d31d09e2be7

data/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.16] - 2025-01-30
+
+### Added
+- **Comprehensive scale-to-zero documentation** - Added dedicated "Scale to Zero" section in README:
+  - Explains how `min_workers = 0` works with Heroku formation behavior
+  - Documents the v1.0.15 fix for graceful 404 handling
+  - Includes configuration examples and cold-start latency considerations
+  - Guidance on where to run the autoscaler (web dyno vs workers)
+  - Updated Features list and linked Cost-Optimized example
+
 ## [1.0.15] - 2025-01-30
 
 ### Fixed

data/README.md

@@ -10,12 +10,98 @@ A control plane for [Solid Queue](https://github.com/rails/solid_queue) that aut
 - **Metrics-based scaling**: Scales based on queue depth, job latency, and throughput
 - **Multiple scaling strategies**: Fixed increment or proportional scaling based on load
 - **Multi-worker support**: Configure and scale different worker types independently
+- **Scale to zero**: Full support for `min_workers = 0` to eliminate costs during idle periods
 - **Platform adapters**: Native support for Heroku and Kubernetes
 - **Singleton execution**: Uses PostgreSQL advisory locks to ensure only one autoscaler runs at a time
 - **Safety features**: Cooldowns, min/max limits, dry-run mode
 - **Rails integration**: Configuration via initializer, Railtie with rake tasks
 - **Flexible execution**: Run as a recurring Solid Queue job or standalone
 
+## Scale to Zero
+
+The autoscaler fully supports scaling workers to zero (`min_workers = 0`), allowing you to eliminate worker costs during idle periods.
+
+### How It Works
+
+When you configure `min_workers = 0` and the queue becomes idle, the autoscaler will scale your workers down to zero. This is ideal for:
+
+- **Development/staging environments** with sporadic usage
+- **Batch processing workers** that only run when jobs are queued
+- **Cost-sensitive applications** with predictable idle periods
+
+### Heroku Formation Behavior
+
+On Heroku, when a dyno type is scaled to 0, it gets **removed from the formation entirely**. This means:
+
+1. `heroku ps:scale worker=0` removes the `worker` formation
+2. Subsequent API calls to get formation info return **404 Not Found**
+3. When scaling back up, the formation must be **recreated**
+
+As of **v1.0.15**, the autoscaler handles this gracefully:
+
+- When querying a non-existent formation, it returns `0` workers (instead of raising an error)
+- When scaling up a non-existent formation, it automatically creates it using Heroku's batch update API
+- This enables seamless scale-to-zero → scale-up workflows
+
+### Configuration Example
+
+```ruby
+SolidQueueAutoscaler.configure(:batch_worker) do |config|
+  config.adapter = :heroku
+  config.heroku_api_key = ENV['HEROKU_API_KEY']
+  config.heroku_app_name = ENV['HEROKU_APP_NAME']
+  config.process_type = 'batch_worker'
+
+  # Enable scale-to-zero
+  config.min_workers = 0
+  config.max_workers = 5
+
+  # Scale up immediately when any job is queued
+  config.scale_up_queue_depth = 1
+  config.scale_up_latency_seconds = 60
+
+  # Scale down when completely idle
+  config.scale_down_queue_depth = 0
+  config.scale_down_latency_seconds = 10
+
+  # Longer scale-down cooldown to avoid premature scaling to zero
+  config.scale_up_cooldown_seconds = 30
+  config.scale_down_cooldown_seconds = 300  # 5 minutes
+end
+```
+
+### Important Considerations
+
+**Cold-start latency**: When workers are at zero and a job is enqueued, there will be latency before the job is processed:
+1. The autoscaler job must run (depends on your `schedule` interval)
+2. The autoscaler must scale up workers
+3. Heroku must provision and start the dyno (~10-30 seconds)
+4. The worker must boot and start processing
+
+Total cold-start time is typically **30-90 seconds** depending on your configuration and dyno startup time.
+
+**Where to run the autoscaler**: The autoscaler job **must run on a process that's always running** (like your web dyno), NOT on the workers being scaled. If the autoscaler runs on workers and those workers scale to zero, there's nothing to scale them back up!
+
+```yaml
+# config/recurring.yml - runs on whatever process runs the dispatcher
+autoscaler_batch:
+  class: SolidQueueAutoscaler::AutoscaleJob
+  queue: autoscaler
+  schedule: every 30 seconds
+  args: [:batch_worker]
+```
+
+**Procfile setup**: Ensure your web dyno runs the Solid Queue dispatcher (or use a dedicated always-on dyno):
+
+```
+# Procfile
+web: bundle exec puma -C config/puma.rb
+worker: bundle exec rake solid_queue:start
+batch_worker: bundle exec rake solid_queue:start
+```
+
+Alternatively, run the dispatcher in a thread within your web process using `solid_queue.yml` configuration.
+
 ## Installation
 
 Add to your Gemfile:
@@ -308,7 +394,7 @@ autoscaler:
 
 ### Cost-Optimized Setup (Scale to Zero)
 
-For apps with sporadic workloads where you want to minimize costs during idle periods:
+For apps with sporadic workloads where you want to minimize costs during idle periods. See the [Scale to Zero](#scale-to-zero) section for full details on how this works.
 
 ```ruby
 SolidQueueAutoscaler.configure do |config|
@@ -337,7 +423,7 @@ SolidQueueAutoscaler.configure do |config|
 end
 ```
 
-**⚠️ Note:** With `min_workers = 0`, there's cold-start latency when the first job arrives. The autoscaler must run on a web dyno or separate process, not on the workers themselves.
+**⚠️ Note:** With `min_workers = 0`, there's cold-start latency (~30-90s) when the first job arrives. The autoscaler must run on a web dyno or separate always-on process, not on the workers themselves. See [Scale to Zero](#scale-to-zero) for details.
 
 ---
 

data/lib/solid_queue_autoscaler/version.rb

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

metadata

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