solid_queue-rate_limit 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f903a1ef2190109dff2e08ad8e57357534a45228f2079097ede82055e095aac2
+  data.tar.gz: 395d34ca629026778e2c6cb96838bedf46250ff4e40d2231e6a63987e49c8288
+SHA512:
+  metadata.gz: 8eadc6cd4a9276e3ffd0f8246c28be9c5da25dbe77398abbd0d2f0ac6c4f08814e1447fd69935e3994a8a17d4ee0767e80b84641be72e7c9d6548c01e87ba5ac
+  data.tar.gz: 6296c9c4d330e516b4ee0c89f57adc84409418b9fea6ba13671010f0e5c4369fa2eb84b6d9894574bbf6957407a64950db605021b40770bafc750794134dac68

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-04
+
+The first release adds `limits_rate`, so workers claim a job class's jobs no faster than a declared rate, and jobs over it wait as scheduled jobs. Install it with `bin/rails generate solid_queue:rate_limit:install`, and there's nothing to upgrade from. The [README](https://github.com/dtcristo/solid_queue-rate_limit/blob/main/README.md#what-the-limit-guarantees) states what the limit guarantees and how to pick a `burst` for a backlog.
+
+### Added
+
+- `limits_rate to:, per:, burst: 1` for Active Job classes on Solid Queue. Workers admit a class's jobs at claim no faster than `to` per `per`, using GCRA, with up to `burst` at once from a recovered budget. A job over the limit waits as a scheduled job with a staggered next check, at most 5 minutes away, and keeps its own `scheduled_at`. `perform_now` and other adapters don't enforce it. ([#12](https://github.com/dtcristo/solid_queue-rate_limit/pull/12))
+- `rate_limit_to`, `rate_limit_per`, `rate_limit_burst` and `rate_limited?` on job classes. ([#12](https://github.com/dtcristo/solid_queue-rate_limit/pull/12))
+- `bin/rails generate solid_queue:rate_limit:install`, which copies the migration for `solid_queue_rate_limits` into the queue database. Enqueueing a limited job before it has run raises `SolidQueue::RateLimitState::PendingMigrations`, and workers hold back limited jobs. ([#12](https://github.com/dtcristo/solid_queue-rate_limit/pull/12))
+- The `defer_rate_limited.solid_queue` event, with `class_name`, `job_ids` and `size`, logged at debug. ([#12](https://github.com/dtcristo/solid_queue-rate_limit/pull/12))
+- Requires Solid Queue 1.7. ([#11](https://github.com/dtcristo/solid_queue-rate_limit/pull/11))
+- A README with recipes, the guarantee and a rule for picking `burst`, and [design notes](https://github.com/dtcristo/solid_queue-rate_limit/blob/main/docs/design.md). ([#13](https://github.com/dtcristo/solid_queue-rate_limit/pull/13))

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) David Cristofaro
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,287 @@
+<div align="center">
+  <h1>Solid Queue Rate Limit</h1>
+  <p>
+    <strong>Rate limits for <a href="https://github.com/rails/solid_queue">Solid Queue</a> jobs</strong>
+  </p>
+</div>
+
+Solid Queue Rate Limit adds `limits_rate` to Active Job classes. Workers claim a class's jobs no faster than the rate you declare, and a job over the limit waits as a scheduled job instead of holding a worker thread, sleeping in `perform` or retrying after a 429.
+
+```ruby
+class SyncStripeJob < ApplicationJob
+  limits_rate to: 100, per: 1.minute, burst: 10
+
+  def perform(account_id)
+    Account.find(account_id).sync_to_stripe!
+  end
+end
+```
+
+The limit is checked when a worker claims the job, inside Solid Queue's own claim transaction, so it holds across any number of workers and processes on SQLite, PostgreSQL and MySQL. Unlimited jobs in the same queue keep running while limited ones wait.
+
+## Table of contents
+
+- [Getting started](#getting-started)
+- [Recipes](#recipes)
+- [How waiting works](#how-waiting-works)
+- [What the limit guarantees](#what-the-limit-guarantees)
+- [Picking a burst for a backlog](#picking-a-burst-for-a-backlog)
+- [Things to know](#things-to-know)
+- [Compatibility](#compatibility)
+- [`limits_rate` options](#limits_rate-options)
+- [Rules and limitations](#rules-and-limitations)
+- [Monitoring](#monitoring)
+- [Testing](#testing)
+- [Roadmap](#roadmap)
+- [License](#license)
+
+## Getting started
+
+Add the gem to your application's Gemfile, alongside Solid Queue, then copy its migration to your queue database's migrations path and run it:
+
+```ruby
+gem "solid_queue-rate_limit"
+```
+
+```bash
+bundle install
+bin/rails generate solid_queue:rate_limit:install
+bin/rails db:migrate
+```
+
+Add `limits_rate` to a job class, then pick a [recipe](#recipes) or read [Picking a burst for a backlog](#picking-a-burst-for-a-backlog).
+
+### Where the migration goes
+
+If Solid Queue doesn't use a database called `queue`, pass the right one with `--database`. For example, `bin/rails generate solid_queue:rate_limit:install --database primary`. Solid Queue's [database configuration](https://github.com/rails/solid_queue/blob/v1.7.0/README.md#database-configuration) and [single database setup](https://github.com/rails/solid_queue/blob/v1.7.0/README.md#single-database-configuration) cover the options.
+
+The generator looks up that database in the current environment's `config/database.yml`. If it isn't there, the generator writes to `db/migrate` without warning, and the migration runs against your primary database. A new Rails app only defines `queue` under `production`, so generate the migration for that environment instead, and let `bin/rails db:prepare` run it when you deploy:
+
+```bash
+RAILS_ENV=production SECRET_KEY_BASE_DUMMY=1 bin/rails generate solid_queue:rate_limit:install
+```
+
+The migration should land in `db/queue_migrate`. `db/queue_schema.rb` doesn't pick up the new table from a production migration. That's fine, because `db:prepare` loads that schema into an empty database and then runs the migration.
+
+### Before the migration runs
+
+Until the migration has run, everything else works as before, and enqueuing a job that uses `limits_rate` raises `SolidQueue::RateLimitState::PendingMigrations`. A limited job that reaches a worker anyway, for example one enqueued before the class declared its limit, isn't claimed. It waits a minute at a time, and each worker process logs one error about the missing table. The limit fails closed, so it never lets jobs through unchecked.
+
+Each process caches whether the table exists, so restart workers and web processes after you migrate. A deploy usually does that for you.
+
+The gem relies on private Solid Queue methods, so its gemspec allows one minor version of Solid Queue at a time.
+
+[CHANGELOG.md](CHANGELOG.md) lists what changed in each version.
+
+## Recipes
+
+Start from what the API on the other end allows.
+
+- [A quota per minute](#stay-under-a-quota-per-minute)
+- [A fixed gap between calls](#space-jobs-out-evenly)
+- [A high rate, with a backlog that has to keep up](#drain-a-backlog-at-the-full-rate)
+
+`Account`, `Address`, `Webhook` and the other names in these recipes stand in for your own code.
+
+### Stay under a quota per minute
+
+Use this when an API allows a number of calls in any minute and you want to stay under it with a burst for spikes.
+
+```ruby
+class SyncStripeCustomerJob < ApplicationJob
+  # At most 10 + 90 = 100 claims in any minute
+  limits_rate to: 90, per: 1.minute, burst: 10
+
+  def perform(account_id)
+    Account.find(account_id).sync_to_stripe!
+  end
+end
+```
+
+A quiet budget lets 10 jobs through at once, then one every 0.67 seconds. The limit isn't a rolling-window counter, so `to:` alone isn't the most a minute can hold. In any window of `w` seconds, workers claim at most `burst + floor(w / (per / to))` jobs. For a quota of `N` per `per`, keep `to + burst` at or below `N`. See [What the limit guarantees](#what-the-limit-guarantees).
+
+### Space jobs out evenly
+
+Use this when an API wants a gap between calls, and two calls close together would fail.
+
+```ruby
+class GeocodeAddressJob < ApplicationJob
+  # The default burst: 1 never claims two jobs less than 5 seconds apart
+  limits_rate to: 1, per: 5.seconds
+
+  def perform(address_id)
+    Address.find(address_id).geocode!
+  end
+end
+```
+
+With `burst: 1` there's no slack, so a backlog drains slower than one job every 5 seconds. [Picking a burst for a backlog](#picking-a-burst-for-a-backlog) explains why, and what it costs to fix.
+
+### Drain a backlog at the full rate
+
+Use this when a backlog builds up and has to drain at the declared rate.
+
+```ruby
+class SendWebhookJob < ApplicationJob
+  # 5 × (1 + 0.1) / 1 = 5.5, rounded up, for the default 1-second dispatcher poll and 0.1-second worker poll
+  limits_rate to: 5, per: 1.second, burst: 6
+
+  def perform(webhook_id)
+    Webhook.find(webhook_id).deliver!
+  end
+end
+```
+
+If 6 jobs at once is too many for the API, make the dispatcher poll more often instead. With a 0.2-second poll, `5 × (0.2 + 0.1) / 1 = 1.5`, which rounds up to 2, so `limits_rate to: 5, per: 1.second, burst: 2` is enough:
+
+```yaml
+# config/queue.yml
+production:
+  dispatchers:
+    - polling_interval: 0.2
+      batch_size: 500
+```
+
+A shorter poll means more queries from the dispatcher. Solid Queue's [configuration docs](https://github.com/rails/solid_queue/blob/v1.7.0/README.md#configuration) cover `polling_interval` and `batch_size`.
+
+## How waiting works
+
+When a worker claims jobs, the gem checks each limited job against its class's budget, in queue order, inside Solid Queue's claim transaction. A job the budget admits is claimed and runs like any other. A job over the limit moves from `solid_queue_ready_executions` to `solid_queue_scheduled_executions`, with a time to check again. It doesn't take a worker thread, and Active Job doesn't see a retry. When that time comes, the dispatcher makes it ready as usual, and the next claim checks it again.
+
+The checks are staggered. Each waiting job gets the next free slot, one interval `per / to` after the last slot handed out, so 100 waiting jobs come back at 100 different times instead of all on the next poll. Slots stop 5 minutes ahead. A job past that checks again in 5 minutes without taking a slot. If waiting jobs get discarded, or you loosen the limit, the slots they held come free within 5 minutes.
+
+A slot is a hint, and never charges the budget. A job that comes back and finds the budget spent waits again, with the next free slot.
+
+The job's own `scheduled_at` in `solid_queue_jobs` stays as it was enqueued. Only the scheduled execution carries the next check. `SolidQueue::Job#scheduled?` is true for a waiting job, so dashboards that read scheduled executions list it as scheduled.
+
+Unlimited jobs keep running. Only limited jobs move to scheduled executions, and the rest of the batch is claimed as usual. When a claim deferred jobs and still has free threads, the worker claims again straight away, up to 5 times per poll, so its threads don't sit idle behind waiting jobs.
+
+## What the limit guarantees
+
+The limit counts claims at the worker gate, the moment a worker takes a job from `solid_queue_ready_executions`. It doesn't count job starts, finishes or the API calls a job makes.
+
+With `T = per / to`, in any window of `w` seconds, workers claim at most `burst + floor(w / T)` of a class's jobs. With `burst: 1` that's even spacing, at least `T` apart. With a larger burst it isn't an exact rolling-window quota. `limits_rate to: 100, per: 1.minute, burst: 10` allows 110 claims in a minute that follows a quiet spell.
+
+Some things fall outside it:
+
+- A claim is charged when it happens, whatever happens next. A worker that crashes after claiming a job has used that budget.
+- A job that comes back to ready is charged again. That covers a `retry_on` retry, a failed job you retry, and a claim released when a worker shuts down.
+- A job can start a moment after its claim, make several API calls, or make one late in a long `perform`. Leave headroom if the API counts something else.
+- Each worker reads the time from its own clock. Skew between hosts can let claims through closer together than `T`, so keep their clocks in sync, as Solid Queue's scheduled jobs already need.
+- It's not FIFO. Jobs are checked in queue order within a claim, but a waiting job can be overtaken by one that arrives after the budget recovers, or one whose slot comes sooner.
+
+## Picking a burst for a backlog
+
+A job that reaches a worker while the budget has room runs straight away, whatever the burst. A backlog is different. Its jobs come back from waiting through the dispatcher, which promotes due jobs once per `polling_interval` (1 second by default), and a worker claims them shortly after.
+
+`burst` also sets how early a job can reach the gate and still get in. Each burst above 1 allows one more interval `per / to`. With `burst: 1` there's no slack. A waiting job that arrives even a millisecond before the interval since the last claim has passed waits again, behind the rest of the backlog. Dispatch and claim delays vary by tens of milliseconds, so this happens to a good share of waiting jobs. Polling more often doesn't help, because the delays still vary.
+
+For a backlog to drain at the full rate, `burst` has to cover two things. A dispatcher poll makes about `to × polling_interval / per` jobs due at once, and one claim takes them together. On top of that, the slack has to cover how much a worker's claim delay varies, which is up to the worker's own `polling_interval`. So set `burst` to at least `to × (dispatcher polling_interval + worker polling_interval) / per`, rounded up, and to at least 2. With Solid Queue's defaults of 1 and 0.1 seconds, that's `burst: 2` for 1 job a second, and `burst: 6` for 5. The cost is that a quiet budget lets that many jobs through at once.
+
+This is a rule of thumb that fits the measurements below and the recipe test's simulation, not a bound. Slow claims or busy workers can need more. In the simulation, 100 jobs a second with a 0.1-second dispatcher poll fell behind with `burst: 11` and kept up with `burst: 20`.
+
+These numbers come from 30 to 60 waiting jobs, with one worker polling every 0.1 seconds, on SQLite:
+
+| Limit | Dispatcher poll | `burst` | Backlog drained at |
+| --- | --- | --- | --- |
+| 1 per second | 1 s | 1 | 0.55 per second |
+| 1 per second | 1 s | 2 | 0.95 per second |
+| 1 per second | 0.1 s | 1 | 0.53 per second |
+| 1 per second | 0.1 s | 2 | 1.0 per second |
+| 2 per second | 1 s | 2 | 1.53 per second |
+| 2 per second | 1 s | 3 | 1.9 per second |
+| 5 per second | 1 s | 5 | 4.61 per second |
+| 5 per second | 1 s | 6 | 4.91 per second |
+| 1 per 3 seconds | 1 s | 1 | 0.30 per second |
+| 1 per 3 seconds | 1 s | 2 | 0.33 per second |
+
+## Things to know
+
+- It's a separate gem that adds to Solid Queue from the outside, with its own table. It only works with the Solid Queue adapter, because it checks the limit inside Solid Queue's claim.
+- The limit counts claims, not API calls, and isn't an exact rolling-window quota once `burst` is above 1. See [What the limit guarantees](#what-the-limit-guarantees).
+- With `burst: 1`, a backlog drains slower than the rate. See [Picking a burst for a backlog](#picking-a-burst-for-a-backlog).
+- A waiting job is a scheduled job with its own `scheduled_at` kept, and checks again at most 5 minutes later. See [How waiting works](#how-waiting-works).
+- Each job class has its own budget, and so does each subclass. See [Rules and limitations](#rules-and-limitations).
+- When the app is eager-loaded and no class declares `limits_rate`, claims run exactly Solid Queue's queries. Otherwise each claim reads the class names of the jobs it locked, and locks one row per limited class.
+
+## Compatibility
+
+| Dependency | Supported |
+| --- | --- |
+| Ruby | 3.2 and newer |
+| Rails | 7.1, 7.2, 8.0 and 8.1. CI also runs Rails main, except on Ruby 3.2 |
+| Solid Queue | 1.7 |
+| Database | MySQL, PostgreSQL and SQLite |
+
+CI runs Ruby 3.2, 3.3, 3.4 and 4.0 against all three databases.
+
+| Feature | Behaviour |
+| --- | --- |
+| `perform_later` and `perform_all_later` | Limited when a worker claims the job |
+| `perform_now` | Runs straight away, unlimited |
+| `set(wait:)` and `set(wait_until:)` | Dispatched at their time, then limited at claim. A job that waits keeps its `scheduled_at` |
+| Recurring tasks | Limited like any other enqueue |
+| Retries | Charged again when they come back to ready |
+| Other adapters | Ignore `limits_rate`. See [Testing](#testing) |
+
+## `limits_rate` options
+
+```ruby
+limits_rate to:, per:, burst: 1
+```
+
+- `to` is required, and is a positive integer: how many jobs a `per` admits.
+- `per` is required, and is a positive duration. Workers admit jobs `per / to` apart, which has to be at least 1 millisecond.
+- `burst` is a positive integer, 1 by default: how many jobs a quiet budget admits at once.
+
+An invalid option raises `ArgumentError` when the class loads. The class gets `rate_limit_to`, `rate_limit_per`, `rate_limit_burst` and `rate_limited?` to read them back.
+
+Changing a limit and deploying applies to the next claim. A looser limit doesn't pay off all the debt the old one built up. The claim caps it at `burst` intervals of the new limit, rounded up to the microsecond, so new admissions start within one new interval and a microsecond. Jobs already waiting keep the next checks the old limit gave them, and new waiting jobs get slots after those, so a backlog can take up to 5 minutes to speed up. A tighter limit starts from the budget as the old one left it.
+
+## Rules and limitations
+
+- A class has one limit, and its budget belongs to that class. A second `limits_rate` in the same class raises `ArgumentError`.
+- A subclass inherits its parent's limit, with a budget of its own. Declaring `limits_rate` on `ApplicationJob` gives each job class its own budget, not one shared between them. A subclass can redeclare the limit.
+- `key:`, `group:` and `name:`, for keyed, shared and multiple limits, raise `ArgumentError` until [#3](https://github.com/dtcristo/solid_queue-rate_limit/issues/3).
+- `limits_rate` and `limits_concurrency` on the same class raise `ArgumentError` in either order, and through inheritance, until [#2](https://github.com/dtcristo/solid_queue-rate_limit/issues/2). A job that still has a concurrency key, after its class switched from one to the other, is admitted without a rate check, because it holds its semaphore while it waits.
+- The budget is stored under the class's name. A job enqueued under an alias, such as a constant kept after a rename, shares the class's budget. On MySQL, whose default collation ignores case, two classes whose names differ only in case share one budget.
+- A job whose class doesn't load, or whose `class_name` isn't a job class, is claimed without a check and fails as it would without the gem.
+- A class that drops its limit has its waiting jobs claimed when they next check, at most 5 minutes later.
+
+The design, and the costs behind these rules, are in [the design notes](https://github.com/dtcristo/solid_queue-rate_limit/blob/main/docs/design.md).
+
+## Monitoring
+
+| Event | When | Payload |
+| --- | --- | --- |
+| `defer_rate_limited.solid_queue` | A claim sent a class's jobs to wait | `class_name`, `job_ids`, `size` |
+
+A claim instruments one event for each class it deferred, inside its transaction. If the claim then rolls back, the event has still fired. A job can wait more than once, so `size` counts deferrals, not distinct jobs.
+
+`SolidQueue::LogSubscriber` logs it at debug level:
+
+```text
+SolidQueue-1.7.2 Defer rate-limited jobs (0.1ms)  class_name: "SyncStripeJob", job_ids: [1, 2], size: 2
+```
+
+A backlog can defer jobs on every claim, so the line isn't built at all above debug.
+
+```ruby
+ActiveSupport::Notifications.subscribe("defer_rate_limited.solid_queue") do |*, payload|
+  Metrics.increment("solid_queue.rate_limit.deferred", payload[:size], tags: payload.slice(:class_name))
+end
+```
+
+## Testing
+
+`perform_now` and adapters other than Solid Queue's don't check the limit, and don't need the table. With the test adapter, `assert_enqueued_with` and `perform_enqueued_jobs` work as before, and jobs run as soon as you perform them.
+
+Tests that run jobs through Solid Queue need the table in the test queue database, or enqueuing a limited job raises `SolidQueue::RateLimitState::PendingMigrations`.
+
+## Roadmap
+
+[#10](https://github.com/dtcristo/solid_queue-rate_limit/issues/10) tracks what comes after 0.1.0, including keyed and shared limits, combining with `limits_concurrency`, and feedback from an API's 429 responses.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/app/models/solid_queue/rate_limit_state.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module SolidQueue
+  # The GCRA state of one limit. +tat+ is the theoretical arrival time: the budget
+  # is full when it's in the past, and each admission moves it on by the interval.
+  # +deferred_until+ is the latest slot handed to a waiting job. It's only a hint
+  # for staggering their next checks, and never charges the budget.
+  class RateLimitState < Record # :nodoc:
+    self.table_name = "solid_queue_rate_limits"
+
+    # The furthest a waiting job is sent ahead, so a job that's cancelled or a limit
+    # that's loosened can't strand capacity for longer than this.
+    MAX_DEFERRAL = 5.minutes
+
+    # Enqueuing a job that uses +limits_rate+ before the gem's migration has run.
+    class PendingMigrations < StandardError
+      def initialize(message = "The rate limiting schema hasn't been installed yet. Run `bin/rails generate solid_queue:rate_limit:install` to copy the migration to your application, and then `bin/rails db:migrate` to run it")
+        super
+      end
+    end
+
+    class << self
+      # Until the app has run the gem's migration everything else works as before.
+      def migrated?
+        @migrated ||= table_exists?
+      end
+
+      # Returns the state of each key, by key, locked until the claim commits. A new
+      # key starts with a full budget. They're inserted and locked in key order, so
+      # claims that share keys can't deadlock on them.
+      def lock_all(keys)
+        keys = keys.sort
+
+        # On PostgreSQL even a skipped insert takes a value from the id sequence
+        if (missing = keys - where(key: keys).pluck(:key)).any?
+          insert_all(missing.map { |key| { key: key, tat: Time.current } })
+        end
+
+        states = where(key: keys).order(:key).lock.index_by(&:key)
+
+        # Under a case-insensitive collation, like MySQL's default, a key can match
+        # a row spelled differently, and then the two share a budget
+        keys.index_with { |key| states[key] || states.fetch(where(key: key).pick(:key)) }
+      end
+    end
+
+    # Charges one admission and returns true, or returns false if the budget is spent.
+    # +interval+ is the seconds between admissions, and +burst+ how many a full
+    # budget admits at once.
+    def admit(interval, burst, now)
+      clamp(interval, burst, now)
+
+      if tat <= now + spare(interval, burst)
+        self.tat = ceil_usec([ tat, now ].max + interval)
+        true
+      else
+        false
+      end
+    end
+
+    # When a job the budget rejected should look again: the next free slot after
+    # the ones already handed out, or MAX_DEFERRAL from now if that's further.
+    def defer(interval, burst, now)
+      clamp(interval, burst, now)
+
+      slot = ceil_usec([ tat - spare(interval, burst), deferred_until&.+(interval) ].compact.max)
+
+      if slot <= now + MAX_DEFERRAL
+        self.deferred_until = slot
+      else
+        now + MAX_DEFERRAL
+      end
+    end
+
+    private
+      # A loosened limit applies at once, instead of after the old one's debt
+      def clamp(interval, burst, now)
+        self.tat = [ tat, ceil_usec(now + burst * interval) ].min
+      end
+
+      def spare(interval, burst)
+        (burst - 1) * interval
+      end
+
+      # Rounding down could erase a little of the debt on every admission
+      def ceil_usec(time)
+        time.ceil(6)
+      end
+  end
+end

data/app/models/solid_queue/ready_execution/rate_limited.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module SolidQueue
+  class ReadyExecution
+    module RateLimited # :nodoc: all
+      extend ActiveSupport::Concern
+
+      class_methods do
+        # Moves the candidates whose class is over its rate to scheduled executions,
+        # leaving their jobs' own scheduled_at as it is, and returns them. Called inside
+        # the claim's transaction, after the candidates have been locked.
+        def defer_rate_limited(executions)
+          jobs = Job.where(id: executions.map(&:job_id)).select(:id, :class_name, :queue_name, :priority, :concurrency_key).index_by(&:id)
+          job_classes = jobs.values.map(&:class_name).uniq.index_with { |class_name| rate_limited_job_class(class_name) }.compact
+
+          # A job with a concurrency key holds its semaphore, so it can't wait here
+          limited = executions.select { |execution| (job = jobs[execution.job_id]) && job.concurrency_key.nil? && job_classes[job.class_name] }
+          return [] if limited.empty?
+
+          next_checks = if RateLimitState.migrated?
+            check_rate_limits(limited, jobs, job_classes)
+          else
+            log_pending_rate_limit_migrations
+            limited.to_h { |execution| [ execution, 1.minute.from_now ] }
+          end
+
+          schedule_rate_limited(next_checks, jobs)
+          next_checks.keys
+        end
+
+        private
+          # Locks every limit the candidates need, in key order, then charges them in queue
+          # order. Returns when each rejected candidate should look again. The time is
+          # read once the locks are held, so claims that share a limit see it move on.
+          # A limit's key is its class's name, which a job enqueued under an alias shares.
+          def check_rate_limits(executions, jobs, job_classes)
+            states = RateLimitState.lock_all(executions.map { |execution| job_classes[jobs[execution.job_id].class_name].name }.uniq)
+            now = Time.current
+
+            next_checks = executions.each_with_object({}) do |execution, deferred|
+              job_class = job_classes[jobs[execution.job_id].class_name]
+              state = states[job_class.name]
+
+              unless state.admit(job_class.rate_limit_interval, job_class.rate_limit_burst, now)
+                deferred[execution] = state.defer(job_class.rate_limit_interval, job_class.rate_limit_burst, now)
+              end
+            end
+
+            states.each_value { |state| state.save! if state.changed? }
+            next_checks
+          end
+
+          def schedule_rate_limited(next_checks, jobs)
+            if next_checks.any?
+              ScheduledExecution.insert_all(next_checks.map do |execution, scheduled_at|
+                jobs[execution.job_id].slice(:queue_name, :priority).merge(job_id: execution.job_id, scheduled_at: scheduled_at)
+              end)
+
+              next_checks.keys.group_by { |execution| jobs[execution.job_id].class_name }.each do |class_name, deferred|
+                SolidQueue.instrument(:defer_rate_limited, class_name: class_name, job_ids: deferred.map(&:job_id), size: deferred.size)
+              end
+            end
+          end
+
+          # A class that can't be loaded fails its jobs when they run, as without the gem
+          def rate_limited_job_class(class_name)
+            job_class = class_name.constantize
+            job_class if job_class.is_a?(Class) && job_class < ActiveJob::Base && job_class.rate_limited?
+          rescue StandardError, ScriptError
+            nil
+          end
+
+          def log_pending_rate_limit_migrations
+            @pending_rate_limit_migrations_logged ||= SolidQueue.logger&.error("Rate-limited jobs are waiting for the rate limiting schema. #{RateLimitState::PendingMigrations.new.message}") || true
+          end
+      end
+    end
+  end
+end

data/lib/active_job/rate_controls.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module ActiveJob
+  # Limits how fast workers start a job class's jobs. See #limits_rate.
+  module RateControls
+    extend ActiveSupport::Concern
+
+    MIN_RATE_LIMIT_INTERVAL = 0.001
+
+    included do
+      class_attribute :rate_limit_to, instance_accessor: false
+      class_attribute :rate_limit_per, instance_accessor: false
+      class_attribute :rate_limit_burst, instance_accessor: false
+    end
+
+    module ClassMethods
+      # Admits this class's jobs at worker claim no faster than +to+ per +per+,
+      # using GCRA. A job over the limit waits as a scheduled job, without taking
+      # a worker thread or a retry, and is checked again when it's dispatched.
+      #
+      #   class SyncStripeJob < ApplicationJob
+      #     limits_rate to: 100, per: 1.minute, burst: 10
+      #   end
+      #
+      # ==== Options
+      #
+      # * +:to+ - Required. A positive integer, how many jobs a +per+ admits.
+      # * +:per+ - Required. A positive duration. Admissions are spaced <tt>per / to</tt>
+      #   apart, which has to be at least 1 ms.
+      # * +:burst+ - How many jobs a fully recovered budget admits at once. Defaults to 1.
+      #
+      # A subclass has its own budget, and can redeclare the limit. An invalid option
+      # raises +ArgumentError+. +perform_now+ and other adapters don't enforce it.
+      def limits_rate(to:, per:, burst: 1, **options)
+        if (planned = options.keys & %i[ key group name ]).any?
+          raise ArgumentError, "`#{planned.first}` isn't supported yet. Follow https://github.com/dtcristo/solid_queue-rate_limit/issues/3 for shared, keyed and multiple limits"
+        elsif options.any?
+          raise ArgumentError, "unknown keyword#{"s" if options.many?}: #{options.keys.map(&:inspect).join(", ")}"
+        end
+
+        unless to.is_a?(Integer) && to.positive?
+          raise ArgumentError, "`to` must be a positive integer"
+        end
+
+        unless per.is_a?(ActiveSupport::Duration) && per.positive?
+          raise ArgumentError, "`per` must be a positive duration"
+        end
+
+        unless burst.is_a?(Integer) && burst.positive?
+          raise ArgumentError, "`burst` must be a positive integer"
+        end
+
+        if per.to_r / to < MIN_RATE_LIMIT_INTERVAL
+          raise ArgumentError, "`limits_rate to: #{to}, per: #{per.inspect}` would admit jobs less than 1 ms apart, and they have to be at least 1 ms apart"
+        end
+
+        if @rate_limit_declared
+          raise ArgumentError, "#{name || "This class"} already declares `limits_rate`"
+        end
+
+        ensure_rate_limit_compatible_with_concurrency_controls(rate_limited: true)
+
+        @rate_limit_declared = SolidQueue::RateLimit.declared = true
+        self.rate_limit_to = to
+        self.rate_limit_per = per
+        self.rate_limit_burst = burst
+      end
+
+      def rate_limited?
+        rate_limit_to.present?
+      end
+
+      # The seconds between admissions
+      def rate_limit_interval # :nodoc:
+        rate_limit_per.to_r / rate_limit_to
+      end
+
+      def limits_concurrency(**) # :nodoc:
+        ensure_rate_limit_compatible_with_concurrency_controls(concurrency_limited: true)
+        super
+      end
+
+      private
+        def ensure_rate_limit_compatible_with_concurrency_controls(rate_limited: rate_limited?, concurrency_limited: concurrency_key.present?)
+          if rate_limited && concurrency_limited
+            raise ArgumentError, "`limits_rate` can't be combined with `limits_concurrency` yet. Follow https://github.com/dtcristo/solid_queue-rate_limit/issues/2"
+          end
+        end
+    end
+  end
+end

data/lib/generators/solid_queue/rate_limit/install/install_generator.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "rails/generators/active_record"
+
+class SolidQueue::RateLimit::InstallGenerator < Rails::Generators::Base
+  include ActiveRecord::Generators::Migration
+
+  source_root File.expand_path("templates", __dir__)
+
+  class_option :database, type: :string, aliases: %i[ --db ], default: "queue",
+    desc: "The database that Solid Queue uses. Defaults to `queue`"
+
+  def copy_migration
+    migration_template "db/create_solid_queue_rate_limits.rb", File.join(db_migrate_path, "create_solid_queue_rate_limits.rb"), skip: true
+  end
+end

data/lib/generators/solid_queue/rate_limit/install/templates/db/create_solid_queue_rate_limits.rb

@@ -0,0 +1,12 @@
+class CreateSolidQueueRateLimits < ActiveRecord::Migration[7.1]
+  def change
+    create_table :solid_queue_rate_limits do |t|
+      t.string :key, null: false
+      t.datetime :tat, null: false
+      t.datetime :deferred_until
+      t.timestamps
+
+      t.index :key, unique: true
+    end
+  end
+end

data/lib/solid_queue/rate_limit/engine.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module SolidQueue
+  module RateLimit
+    class Engine < ::Rails::Engine # :nodoc:
+      initializer "solid_queue.rate_limit.active_job", after: "solid_queue.active_job.extensions" do
+        ActiveSupport.on_load :active_job do
+          include ActiveJob::RateControls
+        end
+      end
+
+      # Solid Queue's models are reloadable, so a reload needs the patches again
+      config.to_prepare { Patches.apply }
+    end
+  end
+end

data/lib/solid_queue/rate_limit/patches.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+# Every place this gem reaches into Solid Queue. All of it depends on private
+# details of the version pinned in the gemspec.
+module SolidQueue
+  module RateLimit
+    module Patches # :nodoc: all
+      # Admission runs in lock_candidates, inside the claim's transaction and after
+      # select_candidates has locked the ready executions with SKIP LOCKED.
+      #
+      # A pass that deferred jobs leaves threads idle that could run jobs behind them,
+      # so the claim looks again, each time in a transaction of its own.
+      module Claiming
+        MAX_CLAIM_PASSES = 5
+
+        private
+          def select_and_lock(queue_relation, process_id, limit)
+            return super unless RateLimit.enforced? && !connection_pool.with_connection(&:transaction_open?)
+
+            claimed = []
+
+            MAX_CLAIM_PASSES.times do |pass|
+              claimed += super(queue_relation, process_id, limit - claimed.size)
+              break unless claimed.size < limit && rate_limit_deferred_in_pass?
+            rescue ActiveRecord::Deadlocked
+              # Whatever earlier passes claimed has been committed
+              raise if pass.zero?
+              break
+            end
+
+            claimed
+          end
+
+          def lock_candidates(executions, process_id)
+            ActiveSupport::IsolatedExecutionState[:solid_queue_rate_limit_deferred] = false
+            return super unless RateLimit.enforced? && executions.any?
+
+            deferred = defer_rate_limited(executions)
+            return super if deferred.empty?
+
+            ActiveSupport::IsolatedExecutionState[:solid_queue_rate_limit_deferred] = true
+
+            super(executions - deferred, process_id).tap do
+              where(id: deferred.map(&:id)).delete_all
+            end
+          end
+
+          def rate_limit_deferred_in_pass?
+            ActiveSupport::IsolatedExecutionState.delete(:solid_queue_rate_limit_deferred)
+          end
+      end
+
+      # Prepended rather than added to the adapter, because RecurringTask calls
+      # Job.enqueue directly. A limited job can't be admitted without the schema,
+      # so it's better to find out when it's enqueued.
+      module Enqueuing
+        def enqueue_all(active_jobs)
+          ensure_rate_limitable if active_jobs.any? { |active_job| active_job.class.rate_limited? }
+          super
+        end
+
+        def enqueue(active_job, **)
+          ensure_rate_limitable if active_job.class.rate_limited?
+          super
+        end
+
+        private
+          def ensure_rate_limitable
+            raise RateLimitState::PendingMigrations unless RateLimitState.migrated?
+          end
+      end
+
+      def self.apply
+        SolidQueue::Job.singleton_class.prepend Enqueuing
+        SolidQueue::ReadyExecution.include SolidQueue::ReadyExecution::RateLimited
+        SolidQueue::ReadyExecution.singleton_class.prepend Claiming
+      end
+    end
+  end
+end
+
+class SolidQueue::LogSubscriber
+  # A backlog can defer jobs on every claim, so above debug it shouldn't build a line for each
+  subscribe_log_level :defer_rate_limited, :debug
+
+  def defer_rate_limited(event) # :nodoc:
+    debug formatted_event(event, action: "Defer rate-limited jobs", **event.payload.slice(:class_name, :job_ids, :size))
+  end
+end

data/lib/solid_queue/rate_limit/version.rb

@@ -0,0 +1,5 @@
+module SolidQueue
+  module RateLimit
+    VERSION = "0.1.0"
+  end
+end

data/lib/solid_queue/rate_limit.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "solid_queue"
+
+require "active_job/rate_controls"
+require "solid_queue/rate_limit/version"
+require "solid_queue/rate_limit/patches"
+require "solid_queue/rate_limit/engine"
+
+module SolidQueue
+  module RateLimit
+    # Set once any job class declares limits_rate
+    mattr_accessor :declared, default: false
+
+    # Without eager loading, a job's class may not be loaded until its job is claimed
+    def self.enforced? # :nodoc:
+      declared || !Rails.application.config.eager_load
+    end
+  end
+end

metadata

@@ -0,0 +1,212 @@
+--- !ruby/object:Gem::Specification
+name: solid_queue-rate_limit
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- David Cristofaro
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: solid_queue
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.7.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.7.0
+- !ruby/object:Gem::Dependency
+  name: appraisal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: debug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: mysql2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rails-omakase
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Adds limits_rate to Active Job classes on Solid Queue. Workers admit
+  a class's jobs no faster than the declared rate, and over-limit jobs wait as scheduled
+  jobs without taking a worker thread.
+email:
+- david@dtcristo.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- MIT-LICENSE
+- README.md
+- app/models/solid_queue/rate_limit_state.rb
+- app/models/solid_queue/ready_execution/rate_limited.rb
+- lib/active_job/rate_controls.rb
+- lib/generators/solid_queue/rate_limit/install/install_generator.rb
+- lib/generators/solid_queue/rate_limit/install/templates/db/create_solid_queue_rate_limits.rb
+- lib/solid_queue/rate_limit.rb
+- lib/solid_queue/rate_limit/engine.rb
+- lib/solid_queue/rate_limit/patches.rb
+- lib/solid_queue/rate_limit/version.rb
+homepage: https://github.com/dtcristo/solid_queue-rate_limit
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/dtcristo/solid_queue-rate_limit
+  source_code_uri: https://github.com/dtcristo/solid_queue-rate_limit
+  documentation_uri: https://www.rubydoc.info/gems/solid_queue-rate_limit
+  changelog_uri: https://github.com/dtcristo/solid_queue-rate_limit/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Rate limits for Solid Queue jobs.
+test_files: []