sidekiq-fairplay 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8da6198834317f72485926227a1a0798f26fa2cb89506248b8430f36445c3d8e
+  data.tar.gz: 1b09fd7ff17a68822a77d2944a22f9913a3048660e591aebb0fcdcf71ef69b8f
+SHA512:
+  metadata.gz: 74bfa63effdd8815a733acb146f7acd5bfa6203eef103c22ba79f1b170fc3de9085b52cd6086b37d86d32d7da2110af2896e8ce562f191648c47c6e924b33292
+  data.tar.gz: f06564822787aa2e4c01072a450f12dc7ba78539457bef069ed6c38708d8989bf03b1881b4bd9a26e3e0ae2ffa3002bf455bcc959b403424cafc019728be98fb

data/.github/workflows/ci.yml

@@ -0,0 +1,76 @@
+name: CI
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+
+jobs:
+  test:
+    name: Test (Ruby ${{ matrix.ruby }}, Sidekiq ${{ matrix.sidekiq }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ['3.4']
+        sidekiq: ['7', '8']
+
+    services:
+      redis:
+        image: redis:7-alpine
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd "redis-cli ping || exit 1"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+
+      - name: Select Gemfile for Sidekiq ${{ matrix.sidekiq }}
+        run: |
+          export BUNDLE_GEMFILE="gemfiles/sidekiq_${{ matrix.sidekiq }}.gemfile"
+          echo "BUNDLE_GEMFILE=$BUNDLE_GEMFILE" >> $GITHUB_ENV
+
+      - name: Bundle install
+        run: bundle install --jobs 4 --retry 3
+
+      - name: Run specs
+        env:
+          REDIS_URL: redis://localhost:6379/1
+        run: |
+          bundle exec rspec --format progress
+
+      - uses: qltysh/qlty-action/coverage@v2
+        if: matrix.sidekiq == '8' && matrix.ruby == '3.4'
+        with:
+          token: ${{secrets.QLTY_COVERAGE_TOKEN}}
+          files: coverage/.resultset.json
+
+  lint:
+    name: Lint (standardrb)
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.4'
+          bundler-cache: true
+
+      - name: Run StandardRB
+        run: bundle exec standardrb

data/.gitignore

@@ -0,0 +1,37 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+spec/examples.txt
+.byebug_history
+
+## Documentation cache and generated files
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# System files
+.DS_Store
+
+# Editors
+.vscode
+.ruby-lsp
+
+# Unnecessary for Ruby gems
+Gemfile.lock
+.ruby-version
+.ruby-gemset
+.tool-versions

data/.standard.yml

@@ -0,0 +1,9 @@
+plugins:
+  - standard-performance
+  - standard-rspec
+
+ignore:
+  - 'spec/**/*_spec.rb':
+    - RSpec/MultipleMemoizedHelpers
+    - RSpec/MultipleExpectations
+    - RSpec/ExampleLength

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Alexander Baygeldin
+
+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,191 @@
+# sidekiq-fairplay
+
+[![Build workflow](https://github.com/baygeldin/sidekiq-fairplay/actions/workflows/ci.yml/badge.svg)](https://github.com/baygeldin/sidekiq-fairplay/actions/workflows/ci.yml)
+[![Gem Version](https://img.shields.io/gem/v/sidekiq-fairplay.svg)](https://rubygems.org/gems/sidekiq-fairplay)
+[![Code Coverage](https://qlty.sh/gh/baygeldin/projects/sidekiq-fairplay/coverage.svg)](https://qlty.sh/gh/baygeldin/projects/sidekiq-fairplay)
+[![Maintainability](https://qlty.sh/gh/baygeldin/projects/sidekiq-fairplay/maintainability.svg)](https://qlty.sh/gh/baygeldin/projects/sidekiq-fairplay)
+
+> [!NOTE]
+> This gem is a reference implementation of the approach I describe in my EuRuKo 2025 talk *“Prioritization justice: lessons from making background jobs fair at scale”*.
+> While the approach itself is battle-tested in production in a real multi-tenant app with lots of users, the gem is not (yet). So, use at your own peril 🫣
+
+Are you treating your users fairly? They could be stuck in the queue while a greedy user monopolizes your workers—and you might not even know it! This gem implements fair background job prioritization for Sidekiq: instead of letting a single noisy tenant hog your queues, `sidekiq‑fairplay` enqueues jobs in balanced rounds, using dynamically calculated tenant weights. It works especially well in multi‑tenant apps, where you want *fairness* even when some tenants are "needier" than others.
+
+Take a look at the most basic example below: it intercepts all jobs you try to enqueue (e.g., via `HeavyJob.perform_async`) and slowly releases them into the main queue in batches of 100 jobs every minute, ensuring no tenant is forgotten.
+
+```ruby
+class HeavyJob
+  include Sidekiq::Job
+  include Sidekiq::Fairplay::Job
+
+  sidekiq_fairplay_options(
+    enqueue_interval: 1.minute,
+    enqueue_jobs: 100,
+    tenant_key: ->(user_id, _foo) { user_id }
+  )
+
+  def perform(user_id, foo)
+    # do heavy work
+  end
+end
+```
+
+<a href="https://evilmartians.com/?utm_source=sidekiq-fair_tenant">
+  <picture>
+    <source
+      media="(prefers-color-scheme: dark)"
+      srcset="https://evilmartians.com/badges/sponsored-by-evil-martians_v2.0_for-dark-bg@2x.png"
+    >
+    <img
+      src="https://evilmartians.com/badges/sponsored-by-evil-martians_v2.0@2x.png"
+      alt="Sponsored by Evil Martians"
+      width="236"
+      height="54"
+    >
+  </picture>
+</a>
+
+## Requirements
+- Ruby >= 3.4
+- Sidekiq >= 7
+
+## Installation
+
+Add to your Gemfile and bundle:
+
+```ruby
+gem 'sidekiq-fairplay'
+```
+
+Configure the client middleware on both client and server:
+
+```ruby
+Sidekiq.configure_client do |config|
+  config.client_middleware do |chain|
+    chain.add Sidekiq::Fairplay::Middleware
+  end
+end
+
+Sidekiq.configure_server do |config|
+  config.client_middleware do |chain|
+    chain.add Sidekiq::Fairplay::Middleware
+  end
+end
+```
+
+## API
+
+In the following example you can see all of the available configuration parameters and their meaning:
+
+```ruby
+class HeavyJob
+  include Sidekiq::Job
+  include Sidekiq::Fairplay::Job
+
+  sidekiq_options queue: :heavy_stuff
+
+  sidekiq_fairplay_options(
+    # How often the planner tries to enqueue more jobs into `heavy_stuff` (in seconds).
+    # It should be large enough for the planner job to finish executing in that time.
+    enqueue_interval: 60,
+
+    # How many jobs the planner tries to enqueue every `enqueue_interval`.
+    # If the jobs are processed faster than the planner enqueues them, increase this number.
+    enqueue_jobs: 100,
+
+    # Tenant ID extraction from the job arguments. It's required and it should return a string.
+    # It is called in the client middleware (i.e. every time you call `SomeWorker.perform_async`).
+    tenant_key: ->(tenant_id, *_args) { tenant_id },
+
+    # Tenant weights extraction. It accepts a list of tenants who currently have jobs waiting to be enqueued.
+    # It should return a hash with keys being tenant IDs and values being their respective weights/priorities.
+    # It's called during the planning and it should be able to execute within `enqueue_interval`.
+    tenant_weights: ->(tenant_ids) { tenant_ids.to_h { |tid| [tid, 1] } }
+
+    # A *very* important parameter to control backpressure and avoid flooding the queue (in seconds).
+    # If the latency of `heavy_stuff` is larger than this number, the planner will skip a beat.
+    latency_threshold: 60,
+
+    # The queue in which the planner job should be executing.
+    planner_queue: 'default',
+
+    # For how long should the planner job hold the lock (in seconds).
+    # This is a protection against accidentally running multiple planners at the same time.
+    planner_lock_ttl: 60,
+  )
+
+  def perform(tenant_id, foo)
+    # do heavy work
+  end
+end
+```
+
+## Configuration
+You can specify some of the default values in `sidekiq.yml`:
+
+```yaml
+fairplay:
+  :default_latency_threshold: 60
+  :default_planner_queue: default
+  :default_planner_lock_ttl: 60
+```
+
+Or directly in the code:
+```ruby
+Sidekiq::Fairplay::Config.default_latency_threshold = 60
+Sidekiq::Fairplay::Config.default_planner_queue = 'default'
+Sidekiq::Fairplay::Config.default_planner_lock_ttl = 60
+Sidekiq::Fairplay::Config.default_tenant_weights = ->(tenant_ids) { tenant_ids.to_h { |tid| [tid, 1] } }
+```
+
+## How it works
+
+At a high level, `sidekiq-fairplay` introduces **virtual per-tenant queues**. Instead of enqueuing jobs directly into Sidekiq, each job first goes into its tenant's queue. Then, at regular intervals, a special planner job (`Sidekiq::Fairplay::Planner`) runs. The planner decides which jobs to promote from tenant queues into the main Sidekiq queue—while keeping things fair.
+
+### Backpressure
+
+Without backpressure, we’d just dump all jobs from tenant queues into the main queue and end up back at square one (high latency and unhappy users). To avoid that, the planner checks queue latency before enqueuing. If latency is already high, it waits. This ensures that **new tenants arriving later still get a chance** to have their jobs processed, even if older tenants are sitting on mountains of unprocessed work.
+
+### Dynamic weights
+
+We keep track of how many jobs are waiting to be enqueued for each tenant. Only tenants with pending work are passed to your `tenant_weights` callback, so your calculations can stay efficient. The callback returns weights: larger numbers mean more jobs get promoted to the main queue. So, weight `10` > weight `1` (just like [Sidekiq’s built-in queue weights](https://github.com/sidekiq/sidekiq/wiki/Advanced-Options#queues)).
+
+From there, you can apply **your own prioritization logic**—for example:
+- Favor paying customers over freeloaders.
+- Cool down tenants who've just had a large batch processed.
+- Balance "needy" vs. "quiet" tenants.
+
+### Reliability
+
+All operations—pushing jobs into tenant queues, pulling them out—are performed atomically in Redis using Lua scripts. This guarantees **consistent state** with a single round-trip. However, if a network failure or process crash happens after a job is enqueued into the main queue but before it’s dropped from its tenant queue, that job may be processed twice. In other words, `sidekiq-fairplay` provides **at-least-once delivery semantics**. 
+
+### Concurrency
+
+We use two simple Redis-backed distributed locks:
+
+1. **Planner deduplication lock**
+   - Ensures only one planner per job class is enqueued within `enqueue_interval`.
+   - This is needed to avoid flooding Sidekiq with duplicate jobs.
+
+2. **Planner execution lock**  
+   - Ensures only one planner per job class runs at a time.
+   - Not strictly necessary (the first lock already prevents most issues), but adds safety.  
+
+⚠️ Note: If a planner takes longer than its `planner_lock_ttl`, multiple planners may run concurrently.  
+It's not the end of the world, but it means you probably should **optimize your `tenant_weights` logic** and/or increase the `enqueue_interval`.
+
+## Troubleshooting
+
+If you use Sidekiq Pro and are using `reliable_scheduler!`, then keep in mind that it bypasses the client middlewares. This essentially means that all jobs scheduled via `perform_in/perform_at` will bypass the planner and go directly into the main queue.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. To execute the test suite simply run `rake`.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/baygeldin/sidekiq-fairplay.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,7 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "standard/rake"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: %i[spec standard]

data/bin/console

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "sidekiq/fairplay"
+
+require "pry"
+Pry.start

data/bin/setup

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install

data/gemfiles/sidekiq_7.gemfile

@@ -0,0 +1,5 @@
+source "https://rubygems.org"
+
+gemspec path: "../"
+
+gem "sidekiq", "~> 7.0"

data/gemfiles/sidekiq_8.gemfile

@@ -0,0 +1,5 @@
+source "https://rubygems.org"
+
+gemspec path: "../"
+
+gem "sidekiq", "~> 8.0"

data/lib/sidekiq/fairplay/config.rb

@@ -0,0 +1,29 @@
+module Sidekiq
+  module Fairplay
+    module Config
+      include ActiveSupport::Configurable
+
+      def self.options
+        Sidekiq.default_configuration[:fairplay] || {}
+      end
+
+      config_accessor :default_latency_threshold do
+        options[:default_latency_threshold] || 60 # seconds
+      end
+
+      config_accessor :default_planner_queue do
+        options[:default_planner_queue] || "default"
+      end
+
+      config_accessor :default_planner_lock_ttl do
+        options[:default_planner_lock_ttl] || 60 # seconds
+      end
+
+      # By default, all tenants have equal weight.
+      config_accessor :default_tenant_weights do
+        options[:default_tenant_weights] ||
+          ->(tenant_ids) { tenant_ids.to_h { |tid| [tid, 1] } }
+      end
+    end
+  end
+end

data/lib/sidekiq/fairplay/middleware.rb

@@ -0,0 +1,54 @@
+module Sidekiq
+  module Fairplay
+    class Middleware
+      def call(job_class, job, _queue, _redis_pool)
+        klass = job_class.is_a?(String) ? constantize(job_class) : job_class
+        return nil unless klass
+
+        opts = klass.respond_to?(:sidekiq_fairplay_options_hash) ? klass.sidekiq_fairplay_options_hash : {}
+        args = job["args"] || []
+
+        # For jobs scheduled via `perform_in` or `perform_at`, let it schedule as usual (including the planner job itself).
+        # When the job is pushed onto the main queue from the scheduled set by Sidekiq, it will go through this middleware again.
+        # NOTE: `reliable_scheduler` in Sidekiq Pro skips client middlewares, so such jobs will be enqueued bypassing the planner.
+        return yield if job.key?("at")
+
+        # Skip enqueuing the planner if it was already enqueued recently.
+        if klass == Sidekiq::Fairplay::Planner
+          target_job_class = constantize(args.first)
+          return nil unless target_job_class
+          return nil if redis.planner_enqueued_recently?(target_job_class)
+
+          return yield
+        end
+
+        # Only apply fairplay logic to jobs that have it enabled.
+        return yield unless klass.respond_to?(:sidekiq_fairplay_options_hash)
+
+        # Perform the job as usual if it was enqueued by the planner.
+        return yield if job["fairplay_enqueued_at"]
+
+        tenant_id = klass.instance_exec(*args, &opts[:tenant_key])
+        raise ArgumentError, "sidekiq-fairplay: tenant key cannot be nil" if tenant_id.nil?
+
+        redis.push_tenant_job(klass, tenant_id, args.to_json)
+
+        ::Sidekiq::Fairplay::Planner.set(queue: opts[:planner_queue]).perform_async(klass.name)
+
+        nil # short-circuit job execution
+      end
+
+      private
+
+      def constantize(name)
+        name.constantize
+      rescue NameError
+        nil
+      end
+
+      def redis
+        @redis ||= Sidekiq::Fairplay::Redis.new
+      end
+    end
+  end
+end

data/lib/sidekiq/fairplay/planner.rb

@@ -0,0 +1,102 @@
+require "json"
+require "sidekiq/api"
+
+module Sidekiq
+  module Fairplay
+    class Planner
+      include Sidekiq::Job
+
+      sidekiq_options retry: false
+
+      def perform(job_class_name)
+        @job_class = constantize(job_class_name)
+        return unless job_class&.respond_to?(:sidekiq_fairplay_options_hash)
+
+        planner = self.class.set(queue: options[:planner_queue])
+        planner.perform_in(options[:enqueue_interval].to_i, job_class.name)
+
+        return if job_queue.latency > options[:latency_threshold].to_i
+
+        redis.with_planner_lock(job_class, Sidekiq::Context.current["jid"]) do
+          enqueue_more_jobs!
+        end
+      end
+
+      private
+
+      attr_reader :job_class
+
+      def enqueue_more_jobs!
+        counts = fetch_tenant_counts
+        return if counts.empty?
+
+        weighted_tenant_ids = build_weighted_tenant_ids(counts.keys)
+        return if weighted_tenant_ids.empty?
+
+        pushed = 0
+
+        while pushed < options[:enqueue_jobs]
+          tid = weighted_tenant_ids.sample
+          break unless tid && enqueue_job_for_tenant(tid)
+
+          counts[tid] -= 1
+          pushed += 1
+
+          weighted_tenant_ids.reject! { it == tid } if counts[tid] <= 0
+        end
+      end
+
+      def fetch_tenant_counts
+        redis.tenant_counts(job_class)
+          .transform_values { |c| c.to_i }
+          .select { |_tid, c| c.positive? }
+      end
+
+      # Build a sampling bag with tenant IDs proportional to their weights.
+      def build_weighted_tenant_ids(tenant_ids)
+        weights = job_class.instance_exec(tenant_ids, &options[:tenant_weights])
+
+        tenant_ids.each_with_object([]) do |tid, memo|
+          weights[tid].to_i.times { memo << tid }
+        end
+      end
+
+      def enqueue_job_for_tenant(tid)
+        job_payload = redis.peek_tenant(job_class, tid)
+
+        ok = Sidekiq::Client.push(
+          "class" => job_class,
+          "queue" => job_queue.name,
+          "args" => JSON.parse(job_payload),
+          "fairplay_enqueued_at" => Time.now.to_i
+        )
+        return false unless ok
+
+        # Only remove the job from the tenant queue if it was successfully enqueued,
+        # so that we don't lose a job if the process is killed or in case of a network issue.
+        # However, this may lead to a job being processed more than once.
+        redis.pop_tenant_job(job_class, tid)
+
+        true
+      end
+
+      def constantize(name)
+        name.constantize
+      rescue NameError
+        nil
+      end
+
+      def options
+        @options ||= job_class.sidekiq_fairplay_options_hash
+      end
+
+      def job_queue
+        @job_queue ||= Sidekiq::Queue.new(job_class.get_sidekiq_options["queue"] || "default")
+      end
+
+      def redis
+        @redis ||= Sidekiq::Fairplay::Redis.new
+      end
+    end
+  end
+end