sidekiq-routing 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0119411113d408ffff9aa353faf8a1d9b4dfd7572edd26efb39dc97b048d204e'
-  data.tar.gz: cec0724470361bdbf22d98b9be14387acbd46c1f895ad3f0f4f27d3f77a3f477
+  metadata.gz: 4026ae7773cd59cf7d6f4c47f965fbd6d4f27c2f337d1043a67c6c6ef9a4982c
+  data.tar.gz: 57da9b38e4ae73d1ce7664bf54c851941527641cb8d596fa312283172f297983
 SHA512:
-  metadata.gz: 6f299c288a571de2e21cfb6a8ece1be70df3b30f16b6251c1eb81eacb29ab788eea272d51187f6b919fbdbef07f8f176d6291637aefc32190699c90d20b3e702
-  data.tar.gz: fa64c7f1d15224a0011e9f5a7f16747ca1699781cdb50a6d84b69281814885481fc1ebf555bb9ea59a02727f2fa1536627900ebcc94631fb30af413b1d4f0537
+  metadata.gz: fa372018993a3b5ee70f4b19b4ddb26a344a1f1b244063a51ab122632b4808721d3085ebf7de584ec998bb475b32461758172549d92d49c66104939164e941b9
+  data.tar.gz: 9a7864642c6695d4313dc69170cc09925e088ee9e72d13239c163010b4c066fb16822bdf5e07ab01a8be8341ffdfd84dce905f2ef714773f586938a280fbd02b

data/README.md

@@ -4,11 +4,11 @@ Runtime, per-job-class **queue routing for Sidekiq** — park, blackhole, or
 auto-reroute a job class **without a deploy**.
 
 Background jobs often share a handful of latency-tiered queues
-(`within_5_seconds`, `within_1_minute`, …). The queue name is a contract: every
-job on a tier should start within that window. That sharing is efficient until
-one class misbehaves — a flood, a runaway argument, a broken downstream — and
-then the only built-in lever, pausing the whole queue, punishes every other
-class on the tier. `sidekiq-routing` gives you a finer lever, applied at
+(`within_5_seconds`, `within_1_minute`, …). The queue name is a contract:
+every job on a tier should start within that window. That sharing is efficient
+until one class misbehaves — a flood, a runaway argument, a broken downstream
+— and then the only built-in lever, pausing the whole queue, punishes every
+other class on the tier. `sidekiq-routing` gives you a finer lever, applied at
 runtime to a single job class:
 
 | Kind | Purpose | Driver | Target |
@@ -33,7 +33,7 @@ bundle install
 ```
 
 Requires Ruby >= 3.1 and Sidekiq >= 7.0 (tested on Sidekiq 7.3.x and 8.x). The
-gem depends only on `sidekiq` — no Rails or ActiveSupport required.
+gem depends only on `sidekiq`.
 
 ## Quick start
 
@@ -52,9 +52,7 @@ Sidekiq::Routing.install! # registers the client + server middleware
 ```
 
 `install!` prepends the client middleware (so enqueues are diverted) and adds
-the server middleware (so in-flight jobs are diverted). If
-[sidekiq-unique-jobs](https://github.com/mhenrixon/sidekiq-unique-jobs) is
-present, the routing server middleware is inserted *after* it automatically.
+the server middleware (so in-flight jobs are diverted).
 
 Then, from a console during an incident:
 
@@ -76,27 +74,42 @@ runtime, without pausing the rest of its queue or shipping a deploy.
   added to the Dead set). Only for classes you can afford to lose.
 
 ```ruby
-Sidekiq::Routing.park("HardJob")
+Sidekiq::Routing.park("RunawayImportJob")
 Sidekiq::Routing.blackhole("FireAndForgetJob")
-Sidekiq::Routing.unpark("HardJob")
+Sidekiq::Routing.unpark("RunawayImportJob")
 
-Sidekiq::Routing.routed?("HardJob")  # => true/false
-Sidekiq::Routing.parked?("HardJob")  # => true only when in park mode
-Sidekiq::Routing.mode("HardJob")     # => "park" | "blackhole" | nil
-Sidekiq::Routing.routes              # => { "HardJob" => { "mode" => "park", ... } }
+Sidekiq::Routing.routed?("RunawayImportJob")  # => true/false
+Sidekiq::Routing.parked?("RunawayImportJob")  # => true only when in park mode
+Sidekiq::Routing.mode("RunawayImportJob")     # => "park" | "blackhole" | nil
+Sidekiq::Routing.routes              # => { "RunawayImportJob" => { "mode" => "park", ... } }
 ```
 
 A route accepts a Class or a String. ActiveJob jobs are matched by their real
 ("wrapped") class, not the adapter's job wrapper.
 
+### Identifying the class flooding a live queue
+
+During a latency alert, inspect the breached queue with a capped, read-only
+scan:
+
+```ruby
+report = Sidekiq::Routing.queue_composition("within_1_minute")
+puts report
+# RunawayImportJob                                      count=12345     oldest=380s ago
+# OtherJob                                             count=12        oldest=45s ago
+# scanned 12357 of 12357 (cap 250000)
+
+report.offender["class"] # => "RunawayImportJob"
+```
+
 ### Clearing an existing backlog into the parking queue
 
 `park` only diverts jobs from the moment it's set. To move a class's jobs that
 are *already enqueued* on a live queue into the parking queue, sweep them:
 
 ```ruby
-Sidekiq::Routing.sweep("HardJob", queue: "within_1_minute")
-Sidekiq::Routing.sweep("HardJob", queue: "within_1_minute", limit: 10_000)
+Sidekiq::Routing.sweep("RunawayImportJob", queue: "within_1_minute")
+Sidekiq::Routing.sweep("RunawayImportJob", queue: "within_1_minute", limit: 10_000)
 ```
 
 A queue must be resolvable — pass `queue:` explicitly (the sweep deliberately
@@ -108,11 +121,11 @@ never scans every queue, which would hammer Redis during an incident).
 # Move parked jobs back to their original queue (stamps them so an active
 # route won't immediately bounce them back).
 Sidekiq::Routing.process_parked
-Sidekiq::Routing.process_parked(klass: "HardJob", limit: 1_000)
+Sidekiq::Routing.process_parked(klass: "RunawayImportJob", limit: 1_000)
 
 # Introspection
 Sidekiq::Routing.parked_size       # O(1) count of the parking queue
-Sidekiq::Routing.parked_breakdown  # { "HardJob" => { "count" => 12, "by_original_queue" => {...} } }
+Sidekiq::Routing.parked_breakdown  # { "RunawayImportJob" => { "count" => 12, "by_original_queue" => {...} } }
 ```
 
 A processed parked job has its payload rewritten to target its original queue,
@@ -130,8 +143,8 @@ export SIDEKIQ_ROUTING_AUTO_REROUTE_ENABLED=true
 ```
 
 Auto rerouting only ever moves jobs to the *next* live SLA tier
-(`within_5_seconds` → `within_1_minute` → `within_5_minutes` → `within_1_hour`).
-It never parks or blackholes.
+(`within_5_seconds` → `within_1_minute` → `within_5_minutes` →
+`within_1_hour`). It never parks or blackholes.
 
 Wire it up in your initializer:
 
@@ -161,18 +174,18 @@ routing_auto_reroute:
   class: "Sidekiq::Routing::Auto::RerouteJob"
 ```
 
-`RerouteJob` checks each SLA queue's estimated workload against its capacity and,
-for any tier over `capacity_threshold_percent`, moves the noisiest classes to
-the next tier. `RerouteJob` itself is excluded from rerouting by default.
+`RerouteJob` checks each SLA queue's estimated workload against its capacity
+and, for any tier over `capacity_threshold_percent`, moves the noisiest classes
+to the next tier. `RerouteJob` itself is excluded from rerouting by default.
 
 ## Web tab
 
 A read-only "Routing" tab for Sidekiq Web shows active routes and parking-queue
-depth/breakdown. Every mutating action stays on the console API — the tab never
-exposes park/blackhole/unpark/sweep, so destructive operations stay deliberate.
+depth/breakdown. Every mutating action stays on the console API — the tab
+never exposes park/blackhole/unpark/sweep, so destructive operations stay
+deliberate.
 
-Require it only where you mount Sidekiq Web (so worker processes never load the
-web framework):
+Require it only where you mount Sidekiq Web:
 
 ```ruby
 require "sidekiq/web"
@@ -180,6 +193,8 @@ require "sidekiq/routing/web" # registers the "Routing" tab
 mount Sidekiq::Web => "/sidekiq"
 ```
 
+<img width="2964" height="1550" alt="CleanShot 2026-06-26 at 13 59 49@2x" src="https://github.com/user-attachments/assets/8da1149d-c76d-47d6-8be6-7aef921d54ea" />
+
 ## Configuration reference
 
 `Sidekiq::Routing.setup { |config| ... }`:
@@ -217,17 +232,6 @@ snapshot, so console changes take effect immediately for the writer and within
 one TTL everywhere else. Parking rewrites the `queue` field *inside the job
 payload*, which is what makes recovery and retry-to-original-queue correct.
 
-## Development
-
-```sh
-bin/setup            # or: bundle install
-bundle exec rake test
-```
-
-The test suite talks to a real Redis. It uses logical DB 15 of
-`redis://localhost:6379` by default; override with `REDIS_URL` (point it at a
-disposable Redis). No Rails or database is involved.
-
 ## License
 
 Released under the [MIT License](LICENSE).

data/lib/sidekiq/routing/queue_composition.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Sidekiq
+  module Routing
+    # Read-only, capped scan of a live queue grouped by displayed job class.
+    # Used during incidents to answer: "which class is flooding this SLA tier?"
+    class QueueComposition
+      DEFAULT_SCAN_LIMIT = 250_000
+
+      Report = Struct.new(:queue, :rows, :scanned, :size, :scan_limit, keyword_init: true) do
+        def offender
+          rows.first
+        end
+
+        def to_h
+          {
+            "queue" => queue,
+            "rows" => rows.map(&:dup),
+            "scanned" => scanned,
+            "size" => size,
+            "scan_limit" => scan_limit
+          }
+        end
+
+        def to_s
+          lines = rows.map do |row|
+            age = row["oldest_age_seconds"] ? "#{row["oldest_age_seconds"].round}s ago" : "n/a"
+            format("%-55s count=%-9d oldest=%s", row["class"], row["count"], age)
+          end
+          lines << "scanned #{scanned} of #{size} (cap #{scan_limit})"
+          lines.join("\n")
+        end
+
+        alias inspect to_s
+      end
+
+      def initialize(queue_name, scan_limit: DEFAULT_SCAN_LIMIT, now: Time.now)
+        @queue_name = normalize_queue_name(queue_name)
+        @scan_limit = normalize_scan_limit(scan_limit)
+        @now = now
+      end
+
+      def call
+        by_class = Hash.new { |hash, key| hash[key] = { count: 0, oldest_at: nil } }
+        queue = Sidekiq::Queue.new(@queue_name)
+        scanned = 0
+
+        queue.each do |job|
+          break if scanned >= @scan_limit
+
+          scanned += 1
+          row = by_class[job.display_class]
+          row[:count] += 1
+
+          enqueued_at = job.enqueued_at
+          row[:oldest_at] = enqueued_at if older?(enqueued_at, row[:oldest_at])
+        end
+
+        Report.new(
+          queue: @queue_name,
+          rows: build_rows(by_class),
+          scanned: scanned,
+          size: queue.size,
+          scan_limit: @scan_limit
+        )
+      end
+
+      private
+
+        def build_rows(by_class)
+          by_class.sort_by { |klass, stats| [-stats[:count], klass] }.map do |klass, stats|
+            oldest_at = stats[:oldest_at]
+            {
+              "class" => klass,
+              "count" => stats[:count],
+              "oldest_at" => oldest_at,
+              "oldest_age_seconds" => oldest_at && (@now - oldest_at)
+            }
+          end
+        end
+
+        def normalize_queue_name(queue_name)
+          name = queue_name.to_s
+          raise ArgumentError, "queue_name must be present" if name.empty?
+
+          name
+        end
+
+        def normalize_scan_limit(scan_limit)
+          limit = begin
+            Integer(scan_limit)
+          rescue ArgumentError, TypeError
+            raise ArgumentError, "scan_limit must be a non-negative integer"
+          end
+          raise ArgumentError, "scan_limit must be non-negative" if limit.negative?
+
+          limit
+        end
+
+        def older?(candidate, current)
+          candidate && (current.nil? || candidate < current)
+        end
+    end
+  end
+end

data/lib/sidekiq/routing/store.rb

@@ -27,14 +27,38 @@ module Sidekiq
         # -> {"mode"=>...} or nil
         def fetch(name)
           raw = Sidekiq.redis { |conn| conn.hget(HASH_KEY, name) }
-          raw && JSON.parse(raw)
+          raw && parse_entry(name, raw)
         end
 
         # -> { "ClassName" => {"mode"=>...}, ... }
         def all
           Sidekiq.redis { |conn| conn.hgetall(HASH_KEY) }
-            .transform_values { |raw| JSON.parse(raw) }
+            .each_with_object({}) do |(name, raw), routes|
+              entry = parse_entry(name, raw)
+              routes[name] = entry if entry
+            end
         end
+
+        private
+
+          # A route entry must be a JSON object; anything else is skipped with a
+          # warning, never raised on. The reads feed the client-middleware hot
+          # path inside every perform_async, and the raw value can be foreign
+          # data — e.g. a desynced pooled connection handing HGETALL the reply
+          # of a RESP HELLO handshake ({"server"=>"redis", "proto"=>"3", ...}).
+          def parse_entry(name, raw)
+            entry = JSON.parse(raw)
+            entry.is_a?(Hash) ? entry : warn_invalid(name, raw)
+          rescue JSON::ParserError
+            warn_invalid(name, raw)
+          end
+
+          # -> nil
+          def warn_invalid(name, raw)
+            Routing.logger.warn(
+              "[Routing] ignoring invalid route entry #{name.inspect} => #{raw.inspect.byteslice(0, 200)}")
+            nil
+          end
       end
     end
   end

data/lib/sidekiq/routing/version.rb

@@ -2,6 +2,6 @@
 
 module Sidekiq
   module Routing
-    VERSION = "0.1.0"
+    VERSION = "0.1.2"
   end
 end

data/lib/sidekiq/routing.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "sidekiq"
+require "sidekiq/api"
 require "json"
 
 # Runtime, per-job-class parking/blackhole mechanism for Sidekiq incident response.
@@ -25,6 +26,8 @@ module Sidekiq
     MODE_BLACKHOLE = "blackhole"
     MODES = [MODE_PARK, MODE_BLACKHOLE].freeze
 
+    EMPTY_ROUTES = {}.freeze
+
     @snapshot = nil
     @snapshot_at = nil
     @snapshot_mutex = Mutex.new
@@ -121,7 +124,11 @@ module Sidekiq
         end
       end
 
-      # ---- parking queue introspection ----
+      # ---- queue introspection ----
+
+      def queue_composition(queue_name, scan_limit: QueueComposition::DEFAULT_SCAN_LIMIT)
+        QueueComposition.new(queue_name, scan_limit:).call
+      end
 
       def parked_size
         Sidekiq::Queue.new(parked_queue).size
@@ -196,13 +203,25 @@ module Sidekiq
             current = @snapshot
             fresh = current && ttl.positive? && (now - @snapshot_at) < ttl
             unless fresh
-              @snapshot = Store.all.freeze
+              @snapshot = refresh_snapshot(current)
               @snapshot_at = now
               current = @snapshot
             end
           end
           current
         end
+
+        # Fail open: the refresh runs inside every perform_async via the client
+        # middleware, so a Redis hiccup here must never fail the push. Keep
+        # serving the previous snapshot (or route nothing) until the next TTL
+        # window instead of raising.
+        def refresh_snapshot(current)
+          Store.all.freeze
+        rescue StandardError => error
+          fallback = current ? "keeping stale snapshot" : "routing nothing this TTL window"
+          logger.warn("[Routing] snapshot refresh failed, #{fallback} (#{error.class}: #{error.message})")
+          current || EMPTY_ROUTES
+        end
     end
   end
 end

data/lib/sidekiq-routing.rb

@@ -13,6 +13,7 @@ require "sidekiq/routing"
 require "sidekiq/routing/configuration"
 require "sidekiq/routing/store"
 require "sidekiq/routing/mover"
+require "sidekiq/routing/queue_composition"
 require "sidekiq/routing/sweeper"
 require "sidekiq/routing/parked_processor"
 require "sidekiq/routing/middleware/client"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sidekiq-routing
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
-- Vishnu M
+- Neeraj Singh
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-26 00:00:00.000000000 Z
+date: 2026-07-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sidekiq
@@ -33,7 +33,7 @@ description: |
   from a process-local snapshot, so the per-job hot path stays an in-memory
   lookup rather than a Redis round-trip.
 email:
-- vishnu.m@bigbinary.com
+- neeraj@neeto.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -53,6 +53,7 @@ files:
 - lib/sidekiq/routing/middleware/server.rb
 - lib/sidekiq/routing/mover.rb
 - lib/sidekiq/routing/parked_processor.rb
+- lib/sidekiq/routing/queue_composition.rb
 - lib/sidekiq/routing/store.rb
 - lib/sidekiq/routing/sweeper.rb
 - lib/sidekiq/routing/version.rb