sidekiq-requeue_missing_class 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5efea06725faf4b01f45b52a57344a9fd60c4d34f3145cc514c57f32e261afee
+  data.tar.gz: f89b8d91859416c7bf4253dd9d11e42e79eca3b50dd1ea8efbeabd345eb2f8f0
+SHA512:
+  metadata.gz: a048a9719bd5e5109fc0f74c3cd9d7b6147b7d3e1d8a59962f30c99639353f9cf442d261fd69e445ed71b8f46249473a02e77d2494b40b449775cc7a2d67b932
+  data.tar.gz: fac7f03b37efe1764fa911a7dacb6d0e142ff0dd951c0b92b9a3e11ecc9f5eefee17e3746d9bc27a2063c6790727fc5818468b91913a574ceb2973f5cc879f78

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Change log
+
+## 0.1.0 (2026-07-01)
+
+- Initial version ([@DmitryTsepelev][])
+
+[@DmitryTsepelev]: https://github.com/DmitryTsepelev

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Dmitry Tsepelev
+
+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,67 @@
+# sidekiq-requeue_missing_class ![CI](https://github.com/DmitryTsepelev/sidekiq-requeue_missing_class/actions/workflows/rspec.yml/badge.svg?branch=master) ![](https://ruby-gem-downloads-badge.herokuapp.com/sidekiq-requeue_missing_class?type=total)
+
+`sidekiq-requeue_missing_class` helps you survive rolling deploys that introduce a **new** Sidekiq/ActiveJob class: instead of erroring, jobs whose class is not loadable yet are pushed back with a short delay until an updated worker picks them up.
+
+## Professional Support
+
+Need help with your Sidekiq setup, background jobs architecture, or Rails performance?
+I'm available for consulting — [get in touch](https://dmitrytsepelev.dev/consulting).
+
+## The problem
+
+You add a new job and deploy. Mid-rollout, a freshly started pod (or your scheduler) enqueues `SendShinyNewThingJob` — but the **old** workers are still running and don't have that class yet. An old worker pops the job and blows up:
+
+```
+ActiveJob::UnknownJobClassError (Not::Loaded::Yet)
+# or, for a native worker:
+NameError: uninitialized constant SendShinyNewThingJob
+```
+
+"Just deploy code before you enqueue it" is the textbook answer, and you should do that where you can. But with rolling deploys, autoscaling and schedulers, the race window is real and annoying to close by discipline alone.
+
+## How it works
+
+The gem adds a tiny Sidekiq **server middleware** that, before running a job, checks whether the class meant to run it is actually loadable in *this* process. If it isn't, the job is pushed back with a short delay (instead of erroring), so an updated worker picks it up once the rollout finishes. After a configurable number of attempts it gives up and lets the job run — so a genuinely-missing class still surfaces the usual error instead of looping forever.
+
+Works for both **ActiveJob-over-Sidekiq** and **native Sidekiq** jobs:
+
+- ActiveJob jobs are wrapped, so the middleware looks at the wrapped `job_class`.
+- Native Sidekiq jobs are checked by their worker class directly.
+- "Loadable" means `Object.const_get(name)` succeeds (same autoloading path Sidekiq/Zeitwerk take), so classes that just need autoloading are *not* treated as missing.
+
+## Getting started
+
+Add the gem to your Gemfile:
+
+```ruby
+gem "sidekiq-requeue_missing_class"
+```
+
+and require it:
+
+```ruby
+require "sidekiq/requeue_missing_class"
+```
+
+That's it — the middleware registers itself on the server side. The check is a single constant lookup for jobs whose class is present, so the overhead for the happy path is negligible.
+
+## Configuration
+
+```ruby
+Sidekiq::RequeueMissingClass.configure do |c|
+  c.delay = 30               # seconds before a re-queued job runs again (default: 30)
+  c.max_requeues = 10        # attempts before giving up (default: 10)
+  c.logger = Sidekiq.logger  # or nil to stay quiet
+end
+```
+
+Pick `delay × max_requeues` to comfortably outlast your slowest rollout.
+
+## When you don't need it
+
+- If your deploy strategy already guarantees code-before-enqueue ordering, you may not need this.
+- It only helps with the **missing-class** race, not with incompatible argument changes — version your job arguments separately.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/sidekiq/requeue_missing_class/configuration.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Sidekiq
+  module RequeueMissingClass
+    # Tunables for the middleware. Configure via:
+    #
+    #   Sidekiq::RequeueMissingClass.configure do |c|
+    #     c.delay = 15
+    #     c.max_requeues = 20
+    #   end
+    class Configuration
+      # Seconds to wait before a re-queued job becomes available again.
+      attr_accessor :delay
+
+      # How many times a single job may be re-queued before we give up and let
+      # it run (so the usual "unknown class" error surfaces instead of looping
+      # forever when the class is genuinely gone).
+      attr_accessor :max_requeues
+
+      # Anything responding to #info, or nil to stay quiet.
+      attr_accessor :logger
+
+      def initialize
+        @delay = 30
+        @max_requeues = 10
+        @logger = Sidekiq.logger
+      end
+    end
+  end
+end

data/lib/sidekiq/requeue_missing_class/middleware.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Sidekiq
+  module RequeueMissingClass
+    # Server middleware that re-queues a job when the class meant to run it is
+    # not defined in the current worker process.
+    #
+    # During a rolling deploy that introduces a new job class, a freshly started
+    # pod (or a scheduler) can enqueue a job for a class that the still-running
+    # OLD workers do not have yet. An old worker that pops it would otherwise
+    # blow up (ActiveJob::UnknownJobClassError / NameError). Instead we push the
+    # job back with a short delay so an updated worker — which has the class —
+    # picks it up once the rollout finishes.
+    class Middleware
+      # ActiveJob wraps the real job; the wrapper class is always present, so we
+      # have to look one level deeper at the wrapped job_class.
+      ACTIVE_JOB_WRAPPERS = [
+        "ActiveJob::QueueAdapters::SidekiqAdapter::JobWrapper",
+        "Sidekiq::ActiveJob::Wrapper"
+      ].freeze
+
+      COUNTER_KEY = "requeue_missing_class_count"
+
+      def call(_worker, job, queue)
+        target = target_class_name(job)
+        return yield if target.nil? || loadable?(target)
+
+        attempts = job.fetch(COUNTER_KEY, 0)
+        return yield if attempts >= config.max_requeues
+
+        requeue(job, queue, target, attempts)
+      end
+
+      private
+
+      def requeue(job, queue, target, attempts)
+        Sidekiq::Client.push(
+          job.merge(
+            "queue" => queue,
+            "at" => (Time.now + config.delay).to_f,
+            COUNTER_KEY => attempts + 1
+          )
+        )
+
+        log_requeue(target, attempts)
+      end
+
+      def log_requeue(target, attempts)
+        config.logger&.info(
+          "[RequeueMissingClass] #{target} not loadable in this process; " \
+          "re-queued with #{config.delay.to_i}s delay (#{attempts + 1}/#{config.max_requeues})"
+        )
+      end
+
+      # The class that will actually run this job: for ActiveJob it's the wrapped
+      # job_class, for a native Sidekiq job it's the worker class itself.
+      def target_class_name(job)
+        if ACTIVE_JOB_WRAPPERS.include?(job["class"])
+          job.dig("args", 0, "job_class")
+        else
+          job["class"]
+        end
+      end
+
+      # Mirrors how Sidekiq/ActiveJob resolve the constant (autoloading through
+      # Zeitwerk): a missing class raises NameError.
+      def loadable?(class_name)
+        Object.const_get(class_name)
+        true
+      rescue NameError
+        false
+      end
+
+      def config
+        RequeueMissingClass.configuration
+      end
+    end
+  end
+end

data/lib/sidekiq/requeue_missing_class/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Sidekiq
+  module RequeueMissingClass
+    VERSION = "0.1.0"
+  end
+end

data/lib/sidekiq/requeue_missing_class.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "sidekiq"
+
+require_relative "requeue_missing_class/version"
+require_relative "requeue_missing_class/configuration"
+require_relative "requeue_missing_class/middleware"
+
+module Sidekiq
+  # Entry point for the gem: holds the singleton configuration and registers the
+  # server middleware. See RequeueMissingClass::Middleware for the actual logic.
+  module RequeueMissingClass
+    class << self
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def configure
+        yield(configuration)
+      end
+    end
+  end
+end
+
+# Register automatically on the server side. The middleware is cheap (a constant
+# lookup) for jobs whose class is present, so it's safe to keep first in the chain.
+Sidekiq.configure_server do |sidekiq_config|
+  sidekiq_config.server_middleware do |chain|
+    chain.add Sidekiq::RequeueMissingClass::Middleware
+  end
+end

metadata

@@ -0,0 +1,109 @@
+--- !ruby/object:Gem::Specification
+name: sidekiq-requeue_missing_class
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Dmitry Tsepelev
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: sidekiq
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.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.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  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: Sidekiq server middleware that re-queues a job when the class meant to
+  run it is not yet loaded in the current process — the race you hit during a rolling
+  deploy that adds a new job class.
+email:
+- dmitry.a.tsepelev@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/sidekiq/requeue_missing_class.rb
+- lib/sidekiq/requeue_missing_class/configuration.rb
+- lib/sidekiq/requeue_missing_class/middleware.rb
+- lib/sidekiq/requeue_missing_class/version.rb
+homepage: https://github.com/DmitryTsepelev/sidekiq-requeue_missing_class
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/DmitryTsepelev/sidekiq-requeue_missing_class
+  source_code_uri: https://github.com/DmitryTsepelev/sidekiq-requeue_missing_class
+  changelog_uri: https://github.com/DmitryTsepelev/sidekiq-requeue_missing_class/blob/master/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Survive rolling deploys that introduce a new Sidekiq/ActiveJob class
+test_files: []