wurk 1.1.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8911da9e550c5d8078c4293ebb69f3b8620a4285692f6e3a6b37d41b711c9219
-  data.tar.gz: 9cc0cf226409e7fb5f9ffce6749b2a7328324e9319350d7752c8bdf8d33e7437
+  metadata.gz: 811eecb5136dece5d9fcc6481991485b7183666edaa4cc464998b79d86fda34a
+  data.tar.gz: 5637cb5f107647ca79929032653e5410784b153ec72dfb36282199b8cfa45713
 SHA512:
-  metadata.gz: '093767442c103fc2a99fc8b8d0b5fa21c16d50a46cd90be6826b948c82c871217e725c07af71b6df3c98d501788199104601262081cfe8810b7bbd510c099191'
-  data.tar.gz: fe4977ee515f59cbb6758fe4f42a5d6a8a198c863efc5bebccd211e1c47a2f1ff3f11d90ce85ad1e7faa8f335e1b865ff0bb8efbc0a827773c4d977c968e149b
+  metadata.gz: b1b09dc0cb8e65feeed5d641717ba0c7757af64f68d3de360a629e83cff338a8af0cf0ef4f0a2dbab7ff730f73bb50f4601a5ce3690fe71d603d757581fd4662
+  data.tar.gz: b1b5c4d6914c8fa611cff8532a56bc8e618f0f1bd0c601b3280fb9c12ca6ecd2c17e3b02130f73dc41dec93daca5ba54fe89bb4a3d83a70cd0a80767419d83c7

data/README.md

@@ -59,9 +59,20 @@ Plus Wurk extras: a worker topology DSL, a Kubernetes liveness/readiness listene
 - **[API reference (YARD)](https://developerz-ai.github.io/wurk/api/)** — generated docs for the public classes (`Wurk::Worker`, `Wurk::Client`, `Wurk::Configuration`, `Wurk::Batch`, `Wurk::Limiter`, `Wurk::Unique`, and the `Sidekiq::*` aliases). Machine-readable map for AI agents: **[llms.txt](https://developerz-ai.github.io/wurk/llms.txt)**.
 - **[Getting started & architecture](https://github.com/developerz-ai/wurk/blob/main/docs/idea/01-overview.md)** — how the swarm, manager, fetcher, and processor fit together.
 - **[Starting the worker](https://github.com/developerz-ai/wurk/blob/main/docs/running.md)** — Rails auto-start, the `wurk`/`wurkswarm` runners, and running standalone without Rails.
+- **[Configuration reference](https://github.com/developerz-ai/wurk/blob/main/docs/configuration.md)** — every option, env var, YAML key, and CLI flag, with precedence and pool sizing.
+- **[Deploying](https://github.com/developerz-ai/wurk/blob/main/docs/deployment.md)** — systemd, Capistrano, Heroku, Docker, Kubernetes, rolling restarts, memory limits.
 - **[Active Job adapter](https://github.com/developerz-ai/wurk/blob/main/docs/active-job.md)** — run `ActiveJob`/`deliver_later` on Wurk with `queue_adapter = :wurk`.
+- **[Testing jobs](https://github.com/developerz-ai/wurk/blob/main/docs/testing.md)** — fake/inline modes, the jobs array, Minitest and RSpec setup.
 - **[Migrating from Sidekiq](#migrating-from-sidekiq)** — the one-line swap and what to expect.
+
+**Features:**
+
+- **[Retries, backoff & the dead set](https://github.com/developerz-ai/wurk/blob/main/docs/retries.md)** · **[Reliability](https://github.com/developerz-ai/wurk/blob/main/docs/reliability.md)** — the failure lifecycle, and the delivery guarantee with its limits.
+- **[Batches](https://github.com/developerz-ai/wurk/blob/main/docs/batches.md)** · **[Rate limiting](https://github.com/developerz-ai/wurk/blob/main/docs/rate-limiting.md)** · **[Periodic (cron) jobs](https://github.com/developerz-ai/wurk/blob/main/docs/periodic-jobs.md)** · **[Unique jobs](https://github.com/developerz-ai/wurk/blob/main/docs/unique-jobs.md)** — the Pro/Ent features, free.
+- **[Iterable jobs](https://github.com/developerz-ai/wurk/blob/main/docs/iterable-jobs.md)** · **[Middleware](https://github.com/developerz-ai/wurk/blob/main/docs/middleware.md)** · **[Encryption](https://github.com/developerz-ai/wurk/blob/main/docs/encryption.md)** · **[Profiling](https://github.com/developerz-ai/wurk/blob/main/docs/profiling.md)**
+- **[Data API](https://github.com/developerz-ai/wurk/blob/main/docs/api.md)** · **[Metrics](https://github.com/developerz-ai/wurk/blob/main/docs/metrics.md)** — inspect queues and jobs from Ruby; job metrics, Statsd/DogStatsD, custom history.
 - **API reference (parity specs):** [Sidekiq OSS](https://github.com/developerz-ai/wurk/blob/main/docs/target/sidekiq-free.md) · [Pro](https://github.com/developerz-ai/wurk/blob/main/docs/target/sidekiq-pro.md) · [Enterprise](https://github.com/developerz-ai/wurk/blob/main/docs/target/sidekiq-ent.md) — the authoritative surface Wurk matches exactly.
+- **[Authentication & authorization](https://github.com/developerz-ai/wurk/blob/main/docs/authentication.md)** — gate the dashboard behind Devise/Warden, Sorcery, Basic auth, or a token; role-based read/write; CSRF.
 - **[Securing the dashboard](https://github.com/developerz-ai/wurk/blob/main/docs/dashboard.md)** · **[Metrics history](https://github.com/developerz-ai/wurk/blob/main/docs/metrics-history.md)**
 - **[Compatibility & legal basis](https://github.com/developerz-ai/wurk/blob/main/docs/clean-room.md)** — clean-room implementation: Wurk copies the API, not the code (Google v. Oracle).
 - **Live demo:** [wurk.demo.developerz.ai](https://wurk.demo.developerz.ai)
@@ -103,7 +114,16 @@ Mount the engine wherever you like:
 mount Wurk::Engine => "/wurk"
 ```
 
-The precompiled SPA ships inside the gem, so consumers never run Node. Gate it behind your app's auth with one line — see **[Securing the dashboard](https://github.com/developerz-ai/wurk/blob/main/docs/dashboard.md)** for Devise/Warden/Sorcery recipes:
+On Devise, wrap it in `authenticate` so only signed-in admins reach it — unauthenticated visitors get bounced to your login page:
+
+```ruby
+# config/routes.rb
+authenticate :user, ->(u) { u.admin? } do
+  mount Wurk::Engine => "/wurk"
+end
+```
+
+The precompiled SPA ships inside the gem, so consumers never run Node. Outside Rails routing — or when you'd rather keep auth next to the rest of your Wurk config — gate it with any Rack middleware; see **[Authentication & authorization](https://github.com/developerz-ai/wurk/blob/main/docs/authentication.md)** for Devise/Warden/Sorcery/token recipes, role-based read/write splits, and the CSRF model:
 
 ```ruby
 Wurk::Web.use(Rack::Auth::Basic, "Wurk") { |user, pass| user == ENV["WURK_USER"] && pass == ENV["WURK_PASS"] }
@@ -156,7 +176,7 @@ end
 | `/live` | 200 while the Launcher is running; 503 once `stop`/`quiet` is called. |
 | `/ready` | 200 only when Redis is reachable **and** the heartbeat fired within `ready_window` (default 30s); 503 otherwise. |
 
-Knobs: `health_check(port:, bind: "0.0.0.0", ready_window: 30)`. In swarm mode only the first child to `start` binds the port.
+Knobs: `health_check(port:, bind: "0.0.0.0", ready_window: 30)`. In swarm mode one child owns the port; the others poll every 5s and take it over if the owner dies, so probes survive a child restart.
 
 ## Migrating from Sidekiq
 

data/app/controllers/wurk/api_controller.rb

@@ -232,7 +232,7 @@ module Wurk
 
     # Cluster-total throughput/failures time-series for the dashboard charts.
     # `:bucket` is 1m/5m/1h; `?window=24h` (s/m/h/d suffix) is clamped to the
-    # bucket's retention. Recharts-ready array under `series`.
+    # bucket's retention. Chart-ready array under `series`.
     def history
       window = parse_window(params[:window])
       series = ::Wurk::Web::Enterprise::Historical.history(params[:bucket].to_s, window: window)
@@ -255,7 +255,7 @@ module Wurk
     # Per-queue size/latency gauge time-series for the Metrics/Historical tab.
     # `:bucket` is 1m/5m/1h; `?window=24h` (s/m/h/d) is clamped to the bucket's
     # retention; optional `?queue=<name>` narrows to one queue. Each queue's
-    # `points` are Recharts-ready.
+    # `points` are chart-ready.
     def queue_history
       window = parse_window(params[:window])
       queues = params[:queue].present? ? [params[:queue].to_s] : nil

data/lib/sidekiq/testing.rb

@@ -2,3 +2,5 @@
 
 # Drop-in require path (see lib/sidekiq.rb). Wurk loads this surface whole.
 require 'wurk'
+
+Wurk::Testing.deprecated_require!

data/lib/wurk/batch/callback_job.rb

@@ -4,33 +4,73 @@ require_relative '../worker'
 
 module Wurk
   class Batch
-    # Worker that runs a single batch callback. Target may be a Class name
-    # ("MyCallback" → `MyCallback.new.on_<event>(status, options)`) or a
-    # "Klass#method" spec ("Foo#bar" → `Foo.new.bar(status, options)`).
-    # Failures retry like any ordinary job — callbacks MUST be idempotent.
+    # Worker that runs a single batch callback. The target spec is one of:
+    #
+    #   "MyCallback"      → MyCallback.new.on_<event>(status, options)
+    #   "MyCallback#done" → MyCallback.new.done(status, options)
+    #   "#done"           → <batch callback_class>.new.done(status, options)
+    #
+    # The class-less form takes its class from the batch's `callback_class`
+    # (spec §2.2), read from `b-<bid>` at run time — the spec travels through
+    # the job payload as a plain String, so nothing here depends on anything
+    # that a JSON round trip could lose.
+    #
+    # Failures inside the callback retry like any ordinary job — callbacks
+    # MUST be idempotent.
     #
     # Spec: docs/target/sidekiq-pro.md §2.4.
     class CallbackJob
       include Wurk::Job
 
+      # The spec names a class or a method that isn't there. Distinct from a
+      # failure raised *by* the callback so the retry policy can tell the two
+      # apart.
+      class UnresolvableTarget < StandardError; end
+
       sidekiq_options retry: true
 
+      # A missing constant or method does not heal with time, so the default 25
+      # retries over ~21 days would only delay the news. Go straight to the dead
+      # set on the first attempt: death handlers fire, the operator sees it now,
+      # and the Dead tab's retry button is the recovery path once the callback
+      # class is restored. Anything else the callback raises keeps normal retry.
+      sidekiq_retry_in { |_count, exception| :kill if exception.is_a?(UnresolvableTarget) }
+
       def perform(bid, target_spec, event, options)
-        klass, method = resolve(target_spec, event)
+        klass, method = resolve(bid, target_spec.to_s, event)
         instance = klass.new
-        status   = Wurk::Batch::Status.new(bid)
-        instance.public_send(method, status, options || {})
+        unless instance.respond_to?(method)
+          raise UnresolvableTarget, "batch #{bid}: #{klass}##{method} is not a public method"
+        end
+
+        instance.public_send(method, Wurk::Batch::Status.new(bid), options || {})
       end
 
       private
 
-      def resolve(spec, event)
-        if spec.include?('#')
-          klass_name, method_name = spec.split('#', 2)
-          [Object.const_get(klass_name), method_name.to_sym]
-        else
-          [Object.const_get(spec), :"on_#{event}"]
+      def resolve(bid, spec, event)
+        return [constantize(bid, spec), :"on_#{event}"] unless spec.include?('#')
+
+        klass_name, method_name = spec.split('#', 2)
+        klass_name = callback_class_for(bid) if klass_name.empty?
+        [constantize(bid, klass_name), method_name.to_sym]
+      end
+
+      def constantize(bid, name)
+        if name.nil? || name.empty?
+          raise UnresolvableTarget, "batch #{bid}: callback spec names no class and the batch has no callback_class"
         end
+
+        const = Object.const_get(name)
+        raise UnresolvableTarget, "batch #{bid}: callback target #{name} is not a Class" unless const.is_a?(::Class)
+
+        const
+      rescue NameError
+        raise UnresolvableTarget, "batch #{bid}: callback class #{name.inspect} is not defined"
+      end
+
+      def callback_class_for(bid)
+        Wurk.redis { |conn| conn.call('HGET', "b-#{bid}", 'callback_class') }
       end
     end
   end

data/lib/wurk/batch.rb

@@ -60,8 +60,8 @@ module Wurk
     # accumulate here instead of round-tripping per job.
     BUFFER_KEY = :wurk_batch_buffer
 
-    attr_reader :bid, :parent_bid, :linger
-    attr_accessor :description, :callback_queue, :callback_class, :autoflush
+    attr_reader :bid, :parent_bid, :linger, :callback_class
+    attr_accessor :description, :callback_queue, :autoflush
 
     def self.keys_for(bid)
       base = "b-#{bid}"
@@ -108,6 +108,14 @@ module Wurk
       Wurk.redis { |conn| conn.call('HSET', "b-#{@bid}", 'linger', @linger.to_s) }
     end
 
+    # Supplies the class for a class-less `"#method"` callback spec (§2.2).
+    # Accepts a Class or a String and stores a String either way, so the
+    # in-memory value matches what a batch reopened by bid reads back — and so
+    # `CallbackJob` never has to care which form the caller used.
+    def callback_class=(value)
+      @callback_class = value.nil? ? nil : callback_target(value)
+    end
+
     def parent
       return nil if @parent_bid.nil? || @parent_bid.empty?
 

data/lib/wurk/configuration.rb

@@ -279,13 +279,17 @@ module Wurk
       @options[:fetch_poll_interval]
     end
 
-    # --- Reliability (Sidekiq Pro drop-in no-ops) ------------------------
+    # --- Reliability (Sidekiq Pro drop-in toggles) -----------------------
 
-    # Sidekiq Pro's opt-in toggles for reliable fetch and the reliable
-    # scheduler. Both are already the default in Wurk — the fetcher is always
-    # the reliable BLMOVE fetcher with orphan reclamation, and the scheduler is
-    # always atomic Lua — so the toggle itself is a no-op. They exist only so a
-    # Pro initializer drops in unchanged instead of raising NoMethodError.
+    # Sidekiq Pro's opt-in toggle for reliable fetch. Already the default in
+    # Wurk — the fetcher is always the reliable BLMOVE fetcher with orphan
+    # reclamation — so the toggle is a no-op beyond capturing the recovery
+    # callback. It exists so a Pro initializer drops in unchanged instead of
+    # raising NoMethodError.
+    #
+    # NOTE: `reliable_scheduler!` below is NOT a no-op. The default
+    # `scheduled_enq` pops then pushes and has a job-loss window
+    # (Wurk::Scheduled::Enq); only the toggle swaps in the atomic promoter.
     #
     # The optional block is Pro's recovery callback: `|jobstr, pill|`, fired
     # once per orphan recovery (`pill` nil) and once on a poison kill (`pill`

data/lib/wurk/cron.rb

@@ -24,7 +24,7 @@ module Wurk
   #     so a re-registration of the same loop is idempotent.
   #   * `Cron::Manager` — registration DSL. `mgr.register(cron, klass, **opts)`
   #     with `tz=` mass-setter. Writes to Redis (`periodic` SET + `loops:{lid}`
-  #     HASH).
+  #     HASH) and prunes superseded loops for the classes it registers.
   #   * `Cron::LoopSet` — Enumerable view (`each`/`size`/`fetch(lid)`).
   #   * `Cron::ConfigTester` — boot-time validator. Verifies cron syntax and
   #     that every worker class constant resolves.
@@ -397,10 +397,14 @@ module Wurk
       attr_accessor :tz
       attr_reader :loops
 
-      def initialize(config = nil)
+      # `prune: false` registers without superseding — ConfigTester uses it so
+      # validating a config never deletes a live loop.
+      def initialize(config = nil, prune: true)
         @config = config
         @loops = []
         @tz = nil
+        @prune = prune
+        @pruned_klasses = {}
       end
 
       def register(cron, klass, **opts)
@@ -410,8 +414,24 @@ module Wurk
         loop_obj = Loop.new(schedule: cron, klass: klass_name, options: normalized, tz: tz)
         @loops << loop_obj
         Cron.persist(loop_obj)
+        prune_superseded(klass_name)
         loop_obj
       end
+
+      private
+
+      # Once per class per boot: everything else registered for that class is
+      # a leftover from a previous deploy (the lid hashes schedule+options, so
+      # an edited `register` line yields a new loop and orphans the old one).
+      # Registering the same class twice in one block is fine — the second
+      # register re-persists its loop right after the first one's prune.
+      def prune_superseded(klass_name)
+        return unless @prune
+        return if @pruned_klasses[klass_name]
+
+        @pruned_klasses[klass_name] = true
+        Cron.prune_superseded(klass_name, @loops.map(&:lid))
+      end
     end
 
     # Enumerable view of every registered loop. Reads `periodic` SET +
@@ -470,7 +490,7 @@ module Wurk
       def verify(&block)
         raise ArgumentError, 'block required' unless block
 
-        mgr = Manager.new
+        mgr = Manager.new(prune: false)
         block.call(mgr)
         mgr.loops.each { |lp| resolve_klass!(lp.klass) }
         mgr.loops
@@ -666,17 +686,46 @@ module Wurk
         Loop.new(schedule: cron, klass: worker_class.to_s, options: merged).tap { |lp| persist(lp) }
       end
 
+      # `paused` is written with HSETNX, not HSET: a code-declared `paused:`
+      # option is only the *initial* value at first registration, after which
+      # the field belongs to the runtime (Web UI pause/unpause). Writing it
+      # unconditionally un-paused a dashboard-paused loop on the next boot.
       def persist(loop_obj)
+        fields = loop_obj.to_redis_hash
+        paused = fields.delete('paused')
+        key = "#{LOOP_PREFIX}#{loop_obj.lid}"
         Wurk.redis do |c|
           c.call('SADD', PERIODIC_KEY, loop_obj.lid)
-          c.call('HSET', "#{LOOP_PREFIX}#{loop_obj.lid}", *loop_obj.to_redis_hash.flatten)
+          c.call('HSET', key, *fields.flatten)
+          c.call('HSETNX', key, 'paused', paused)
         end
         loop_obj
       end
 
-      # Drop a loop entirely. Used by the Web UI delete action and by the
-      # config-reload path so a removed `register(...)` line vanishes from
-      # Redis on next boot.
+      # Drop every registered loop for `klass` except `keep_lids` — the loops a
+      # booting process just registered for that class. Editing a schedule or
+      # any option changes the lid, so without this the pre-edit loop stays in
+      # `periodic` and keeps firing next to its replacement, forever.
+      #
+      # Scoped to one class deliberately: the registry is fleet-wide, so a
+      # process that registers a subset of the fleet's loops (or none at all,
+      # e.g. a client-only app) must never delete loops for classes it doesn't
+      # register. Idempotent and safe to race — two processes booting the same
+      # code compute the same candidate set, and SREM/DEL repeat harmlessly.
+      def prune_superseded(klass, keep_lids)
+        keep = Array(keep_lids)
+        stale = Wurk.redis do |c|
+          candidates = c.call('SMEMBERS', PERIODIC_KEY) - keep
+          candidates.select { |lid| c.call('HGET', "#{LOOP_PREFIX}#{lid}", 'klass') == klass }
+        end
+        stale.each { |lid| unregister(lid) }
+        stale
+      end
+
+      # Drop a loop entirely: registry membership, hash, and fire history.
+      # Public API for retiring a loop whose `register(...)` line is gone (no
+      # process registers its class any more, so `prune_superseded` cannot see
+      # it); also the primitive behind pruning and ConfigTester rollback.
       def unregister(lid)
         Wurk.redis do |c|
           c.call('SREM', PERIODIC_KEY, lid)

data/lib/wurk/iterable_job.rb

@@ -173,9 +173,11 @@ module Wurk
       fire_lifecycle_start
       @executions += 1
 
-      run_iterations(args)
-
-      finalize_complete
+      if run_iterations(args) == :cancelled
+        finalize_cancelled
+      else
+        finalize_complete
+      end
     rescue Interrupted
       finalize_interrupted
       raise
@@ -205,13 +207,21 @@ module Wurk
     def run_iterations(args)
       enum = build_enumerator(*args, cursor: @cursor)
       enum.each do |item, new_cursor|
-        raise Interrupted if cancelled?
+        return :cancelled if cancelled?
+
+        # Cooperative shutdown. `interrupted?` (Wurk::Worker) is true once the
+        # owning Processor is stopping — quiet, TERM, or a rolling restart.
+        # Without this the loop would run until hard_shutdown raises
+        # Wurk::Shutdown (an Interrupt, not a RuntimeError), which skips the
+        # rescue below and loses everything since the last periodic flush.
+        raise Interrupted if interrupted?
 
         @current_object = item
         around_iteration { each_iteration(item, *args) }
         @cursor = new_cursor
         maybe_flush_state
       end
+      :completed
     end
 
     def finalize_complete
@@ -220,6 +230,18 @@ module Wurk
       delete_state
     end
 
+    # Cancellation is terminal, not an interruption: the job must NOT be
+    # re-pushed, and the state HASH — `cancelled` field included — must go,
+    # otherwise the resumed run would trip on its own flag and re-push again
+    # every cycle until CANCELLATION_PERIOD expires. Callback order matches
+    # upstream Sidekiq, which treats a cancelled run as completed.
+    def finalize_cancelled
+      on_cancel
+      on_stop
+      on_complete
+      delete_state
+    end
+
     def finalize_interrupted
       flush_state(final: true)
       on_cancel if @cancelled_at

data/lib/wurk/metrics/history.rb

@@ -6,42 +6,42 @@ module Wurk
   module Metrics
     # Ent feature parity (§5): server middleware that records per-job-class
     # execution metrics into Redis time-buckets. The on-the-wire schema is
-    # wire-compat with Sidekiq 8.x's history pane so dashboards built against
-    # `j|YYMMDD|H:M` HASH keys keep working unchanged.
+    # wire-compat with Sidekiq's history pane — Sidekiq keys the per-minute
+    # HASH as `j|<YYYYMMDD>|<H>:<M>`, so dashboards (and Sidekiq data migrated
+    # in place) keep resolving against the same key after a drop-in swap.
     #
     # Bucket layout (spec: docs/target/sidekiq-free.md §1.6):
     #
-    #   j|YYMMDD|H:M    HASH   per-minute bucket, TTL = MID_TERM (3 days)
-    #     <klass>|p     INT    processed count
-    #     <klass>|f     INT    failed count
-    #     <klass>|ms    INT    total ms spent
+    #   j|YYYYMMDD|H:M    HASH   per-minute bucket, TTL = MID_TERM (3 days)
+    #     <klass>|p       INT    processed count
+    #     <klass>|f       INT    failed count
+    #     <klass>|ms      INT    total ms spent
     #
-    #   j|YYMMDD|H:m0   HASH   10-minute rollup (last digit zeroed),
-    #                          TTL = SHORT_TERM (8 hours) — short window for
-    #                          quick aggregate queries without scanning 600 minute keys.
+    #   <klass>-YYYYMMDD-H  HASH per-class hourly histogram, TTL = MID_TERM
     #
-    #   <klass>-YYMMDD-H  HASH per-class hourly histogram, TTL = MID_TERM
+    # We deliberately do NOT write a `H:m0` 10-minute rollup. Its key format
+    # collides with the real minute-0 bucket, so rolling x1..x9 into it turns
+    # that minute's value into a decade total — and the read side (Query) then
+    # sums the minute-0 bucket alongside x1..x9 and double-counts. Sidekiq
+    # itself doesn't keep that rollup (the daily/hourly rollups are commented
+    # out in its ExecutionTracker); Query reads the last N per-minute keys.
     #
-    # Every bucket TTL is set on first write (EXPIRE NX-equivalent: only when
-    # the HASH was newly created in this call) — re-asserting TTL on every
-    # write would keep the bucket alive indefinitely while traffic continues,
-    # but that's the desired behavior here: as long as a class keeps running,
-    # we keep the minute bucket around for the retention window measured from
+    # Every bucket TTL is set on every write (not NX): as long as a class keeps
+    # running we keep its bucket around for the retention window measured from
     # *last write*, not from first write. So we EXPIRE unconditionally.
     #
-    # The middleware is hot-path — every successful job pays for it. Writes
-    # are pipelined in a single round-trip per job (1 HINCRBY × 3 + 1 EXPIRE
-    # per bucket × 3 buckets = 12 commands, batched).
+    # The middleware is hot-path — every successful job pays for it. Writes are
+    # pipelined in a single round-trip per job (1 HINCRBY × 2 + 1 EXPIRE per
+    # bucket × 2 buckets = 6 commands, batched).
     class History
       include Wurk::Middleware::ServerMiddleware
 
       # Per spec §1.6 — naming mirrors the upstream constants so anyone
       # grepping the Sidekiq source for `MID_TERM` lands here.
       MID_TERM = 3 * 24 * 60 * 60      # 3 days, in seconds
-      SHORT_TERM = 8 * 60 * 60         # 8 hours, in seconds
 
       MINUTE_KEY_PREFIX = 'j|'
-      DATE_FORMAT = '%y%m%d'           # YYMMDD — two-digit year per spec
+      DATE_FORMAT = '%Y%m%d'           # YYYYMMDD — matches Sidekiq's j| key
 
       def call(_worker, job, _queue)
         klass = job['class']
@@ -74,28 +74,20 @@ module Wurk
 
           ms = duration_ms.to_i
           ms = 0 if ms.negative?
-          buckets = { minute: minute_key(at), rollup: rollup_key(at), hour: hour_key(klass, at) }
+          buckets = { minute: minute_key(at), hour: hour_key(klass, at) }
           with_pool(redis_pool) { |conn| pipeline_write(conn, klass, ms, success, buckets) }
           nil
         end
 
-        # Minute + 10-min rollup share a per-class `|p|f|ms` field layout;
-        # the hourly bucket is already class-scoped so its fields are bare
-        # `p|f|ms`. Pipeline all 9 commands in one round-trip.
+        # The minute bucket carries per-class `<klass>|p|f|ms` fields; the
+        # hourly bucket is already class-scoped so its fields are bare
+        # `p|f|ms`. Pipeline all 6 commands in one round-trip.
         def pipeline_write(conn, klass, ms, success, buckets)
           outcome = success ? 'p' : 'f'
           class_outcome = "#{klass}|#{outcome}"
           class_ms = "#{klass}|ms"
           conn.pipelined do |pipe|
             incr_bucket(pipe, buckets[:minute], [class_outcome, class_ms, ms, MID_TERM])
-            # The minute key and the 10-min rollup key coincide whenever the
-            # minute ends in 0 (rollup zeroes the last digit). Writing both
-            # would double-count the shared field — the minute write above
-            # already lands on it — so skip the rollup write then. Minutes
-            # x1..x9 still accumulate into the x0 rollup key as normal.
-            unless buckets[:rollup] == buckets[:minute]
-              incr_bucket(pipe, buckets[:rollup], [class_outcome, class_ms, ms, SHORT_TERM])
-            end
             incr_bucket(pipe, buckets[:hour], [outcome, 'ms', ms, MID_TERM])
           end
         end
@@ -115,12 +107,6 @@ module Wurk
                  date: t.strftime(DATE_FORMAT), hr: t.hour, min: t.min)
         end
 
-        def rollup_key(time)
-          t = time.utc
-          format("#{MINUTE_KEY_PREFIX}%<date>s|%<hr>d:%<min>d",
-                 date: t.strftime(DATE_FORMAT), hr: t.hour, min: (t.min / 10) * 10)
-        end
-
         def hour_key(klass, time)
           t = time.utc
           "#{klass}-#{t.strftime(DATE_FORMAT)}-#{t.hour}"

data/lib/wurk/metrics/query.rb

@@ -12,11 +12,15 @@ module Wurk
     # external dashboarding code; both rely on the same HGETALL fan-out
     # over a contiguous range of minute / hour keys.
     #
-    # Window caps are spec-enforced:
+    # Window caps are spec-enforced (§20 "DoS caps"), one per argument:
     #
-    #   minutes ≤ 480  (8h — same as the 10-minute rollup retention)
+    #   minutes ≤ 480  (8h)
     #   hours   ≤ 72   (3d — same as MID_TERM retention)
     #
+    # `hours:` is validated against MAX_HOURS only, never re-checked against
+    # MAX_MINUTES after the ×60 conversion: the minute buckets it reads live
+    # for MID_TERM (3 days), so the whole 72h window is backed by real data.
+    #
     # A wider window has no data to read anyway (the buckets are TTL'd out),
     # so we fail loudly rather than silently returning sparse results.
     module Query # rubocop:disable Metrics/ModuleLength
@@ -34,9 +38,8 @@ module Wurk
       # sorted by volume (p + f) descending so the UI's "top jobs" table
       # renders without a second sort pass.
       def top_jobs(class_filter: nil, minutes: 60, hours: nil, now: ::Time.now)
-        minutes = hours * 60 if hours
-        cap_hours!(hours) if hours
-        rows = aggregate_minutes(now, cap_minutes!(minutes)).to_a
+        window = hours ? cap_hours!(hours) * 60 : cap_minutes!(minutes)
+        rows = aggregate_minutes(now, window).to_a
         rows = rows.select { |(k, _)| k.start_with?(class_filter) } if class_filter && !class_filter.empty?
         rows.sort_by { |(_k, s)| -(s[:p] + s[:f]) }
       end

data/lib/wurk/metrics/rollup.rb

@@ -7,7 +7,7 @@ require_relative 'history'
 module Wurk
   module Metrics
     # Leader-only background thread that rolls the per-class minute buckets
-    # written by Wurk::Metrics::History (`j|YYMMDD|H:M`) up into compact,
+    # written by Wurk::Metrics::History (`j|YYYYMMDD|H:M`) up into compact,
     # cluster-total time-series buckets the dashboard "throughput" / "failures"
     # charts read directly:
     #

data/lib/wurk/profiler.rb

@@ -50,11 +50,13 @@ module Wurk
         key = profile_key(token, jid)
         gz = gzip(gecko_json)
         with_pool(pool) do |conn|
-          conn.call('HSET', key, 'jid', jid, 'type', type, 'token', token,
-                    'started_at', started_at.to_i, 'elapsed', elapsed_ms.to_i,
-                    'size', gz.bytesize, 'sid', sid.to_s, 'data', gz)
-          conn.call('EXPIRE', key, TTL)
-          conn.call('ZADD', Keys::PROFILES, (now + TTL).to_i, key)
+          conn.pipelined do |pipe|
+            pipe.call('HSET', key, 'jid', jid, 'type', type, 'token', token,
+                      'started_at', started_at.to_i, 'elapsed', elapsed_ms.to_i,
+                      'size', gz.bytesize, 'sid', sid.to_s, 'data', gz)
+            pipe.call('EXPIRE', key, TTL)
+            pipe.call('ZADD', Keys::PROFILES, (now + TTL).to_i, key)
+          end
         end
         key
       end

data/lib/wurk/sorted_entry.rb

@@ -24,6 +24,12 @@ module Wurk
       @parent = parent
     end
 
+    # JobRecord resolves the queue eagerly and only from a pre-parsed Hash;
+    # a sorted-set entry is almost always built from the raw JSON string, so
+    # read it off the payload instead. Lazy on purpose — a scan over a large
+    # set must not pay JSON cost for entries nobody inspects.
+    def queue = @queue ||= item['queue']
+
     def id = "#{score}|#{jid}"
 
     def at = ::Time.at(score).utc

data/lib/wurk/testing.rb

@@ -56,14 +56,33 @@ module Wurk
         end
       end
 
-      # In-process server-middleware chain used for inline execution. Empty by
+      # In-process server-middleware chain used by `:inline` mode. Empty by
       # default — configure with `Sidekiq::Testing.server_middleware { |c| ... }`.
+      # Deliberately NOT the globally configured chain: Sidekiq builds a fresh
+      # empty chain here too, and inline tests that suddenly ran batch/limiter/
+      # metrics middleware would diverge from a migrated suite's expectations.
+      # `perform_inline` is the explicit-execution path and does use the real
+      # chains (see Wurk::Worker::Setter#perform_inline).
       def server_middleware
         @server_middleware ||= ::Wurk::Middleware::Chain.new(::Wurk.configuration)
         yield @server_middleware if block_given?
         @server_middleware
       end
 
+      # `require "sidekiq/testing"` flips Sidekiq into fake mode as a side
+      # effect; a migrated suite that never calls `fake!` would otherwise push
+      # into real Redis while every `MyJob.jobs` assertion came back empty.
+      # Deprecated in Sidekiq 8 in favour of `Sidekiq.testing!` — hence the
+      # warning. A mode already chosen (globally or for this thread) means the
+      # suite is explicit: don't override it, and don't warn again.
+      def deprecated_require!
+        return if ::Thread.current[THREAD_KEY] || @mode
+
+        ::Kernel.warn '⛔️ `require "sidekiq/testing"` is deprecated and will be removed in Sidekiq 9.0. ' \
+                      'Use `Sidekiq.testing!(:fake)` instead.'
+        fake!
+      end
+
       # --- push hooks invoked by Wurk::Client#raw_push -------------------
 
       # Route a push through the active test mode (only called when enabled?).

data/lib/wurk/unique.rb

@@ -8,7 +8,9 @@ require_relative 'lua'
 module Wurk
   # Sidekiq Enterprise unique jobs. Best-effort dedup at enqueue time keyed
   # by a SHA256 digest of `[class, queue, args]` (overridable via
-  # `sidekiq_unique_context`). Three lock-release strategies:
+  # `sidekiq_unique_context`; ActiveJob-wrapped payloads narrow to the wrapped
+  # class + its arguments — see `active_job_context`). Three lock-release
+  # strategies:
   #
   #   * `unique_until: :success` (default) — lock retained through retries;
   #     server middleware DELs it on successful perform. Surviving across
@@ -47,6 +49,21 @@ module Wurk
     DEFAULT_UNTIL = :success
     VALID_UNTIL = %i[success start].freeze
 
+    # Class names that carry an ActiveJob payload as their single arg. The
+    # canonical one Wurk writes is `Sidekiq::ActiveJob::Wrapper`; the others
+    # appear in payloads enqueued by older Sidekiq/Rails versions still sitting
+    # in Redis at gem-swap time.
+    ACTIVE_JOB_WRAPPERS = [
+      'Sidekiq::ActiveJob::Wrapper',
+      'Wurk::ActiveJob::Wrapper',
+      'ActiveJob::QueueAdapters::SidekiqAdapter::JobWrapper',
+      'ActiveJob::QueueAdapters::WurkAdapter::JobWrapper'
+    ].freeze
+
+    # Raised at enqueue when a worker opts into both `unique_for:` and
+    # `encrypt: true` (§3.8: mutually exclusive).
+    class ConfigurationError < StandardError; end
+
     # Ent parity: a job that dies automatically releases its lock so a
     # duplicate can enqueue immediately. Manual API/UI kills keep the lock
     # until TTL expiry (Ent wiki, Ent-Unique-Jobs) — they reach death
@@ -94,9 +111,9 @@ module Wurk
         nil
       end
 
-      # Compute the lock key for an arbitrary `(queue, klass, args)` triple.
-      # Used by both the client middleware and the public `locked?` probe so
-      # they cannot drift.
+      # Compute the lock key for an arbitrary `(queue, klass, args)` triple,
+      # bypassing `sidekiq_unique_context`. Public so operators can compute
+      # the key of a worker that uses the default context (docs §8).
       def lock_key(klass, queue, args)
         context = [klass.to_s, queue.to_s, args]
         "#{KEY_PREFIX}#{Digest::SHA256.hexdigest(JSON.dump(context))}"
@@ -112,18 +129,49 @@ module Wurk
 
       # Default: `[class, queue, args]`. Workers may override by defining
       # `self.sidekiq_unique_context(job)` returning any JSON-serializable
-      # value (e.g. a subset of args). Spec §3.5.
+      # value (e.g. a subset of args). Spec §3.5. ActiveJob-wrapped payloads
+      # get a narrowed default (see `active_job_context`) because their raw
+      # args can never repeat.
       def unique_context(job)
         klass = resolve_class(job['class'])
-        if klass.respond_to?(:sidekiq_unique_context)
-          klass.sidekiq_unique_context(job)
-        else
-          [job['class'], job['queue'], job['args']]
-        end
+        return klass.sidekiq_unique_context(job) if klass.respond_to?(:sidekiq_unique_context)
+
+        active_job_context(job) || [job['class'], job['queue'], job['args']]
       end
 
       private
 
+      # An ActiveJob payload's args are `[job.serialize]`, and that hash
+      # carries a fresh `job_id` plus an `enqueued_at` timestamp on every
+      # push — digesting it verbatim produces a new key every time, so
+      # nothing is ever deduped. Identity is therefore narrowed to the two
+      # fields that describe *which* job this is:
+      #
+      #   * `job_class`  — the real worker; the wire `class` is only the wrapper.
+      #   * `arguments`  — the serialized perform args.
+      #
+      # Everything else in the serialized hash is per-push state, not
+      # identity: `job_id`/`provider_job_id` (fresh per push), `enqueued_at`
+      # and `scheduled_at` (timestamps), `executions`/`exception_executions`
+      # (retry counters, so a retry re-push would otherwise miss its own
+      # lock), `priority`, `locale` and `timezone` (ambient request state —
+      # the same logical job enqueued from a different locale is still the
+      # same job). `queue_name` is dropped as redundant: the wire-level
+      # `job["queue"]` it was copied into is already in the context, keeping
+      # the "queue is part of the key" rule identical to the plain path.
+      #
+      # The wrapper class name stays in the context so an ActiveJob and a
+      # plain worker of the same name and args can't collide on one lock.
+      def active_job_context(job)
+        return nil unless ACTIVE_JOB_WRAPPERS.include?(job['class'].to_s)
+
+        data = job['args']
+        data = data.first if data.is_a?(::Array) && data.size == 1
+        return nil unless data.is_a?(::Hash) && data.key?('job_class') && data.key?('arguments')
+
+        [job['class'], job['queue'], data['job_class'], data['arguments']]
+      end
+
       def resolve_class(name)
         return nil if name.nil? || name.to_s.empty?
 
@@ -171,7 +219,10 @@ module Wurk
     # @return [String, nil] owning jid, or nil when the lock is free.
     def self.locked?(queue_or_klass, klass_or_args = nil, args = nil)
       queue, klass, payload = normalize_locked_args(queue_or_klass, klass_or_args, args)
-      key = lock_key(klass, queue, payload)
+      # Routed through lock_key_for, not lock_key: the probe must honor
+      # `sidekiq_unique_context` (and the ActiveJob default) or it reports
+      # "free" for every worker that customizes its digest.
+      key = lock_key_for('class' => klass.to_s, 'queue' => queue.to_s, 'args' => payload)
       Wurk.redis { |c| c.call('GET', key) }
     end
 
@@ -203,11 +254,29 @@ module Wurk
         ttl = effective_ttl(job)
         return yield if ttl.nil?
 
+        reject_encrypted!(job)
         acquire_or_drop(redis_pool, job, Wurk::Unique.lock_key_for(job), ttl, &)
       end
 
       private
 
+      # §3.8: unique + encryption are mutually exclusive. Both features append
+      # to the same client chain, so whether the digest sees plaintext args or
+      # a random-IV envelope depended purely on which initializer ran first —
+      # and in the envelope case uniqueness silently never matched again.
+      # Failing the push is the only outcome that is identical in both
+      # orderings and impossible to miss. The check is per job, so the two
+      # features still coexist fine on *different* workers.
+      def reject_encrypted!(job)
+        return unless job['encrypt']
+        return unless defined?(Wurk::Encryption) && Wurk::Encryption.enabled?
+
+        raise Wurk::Unique::ConfigurationError,
+              "#{job['class']} sets both `unique_for` and `encrypt: true`, which cannot work: " \
+              'encryption rewrites the last argument with a fresh IV on every push, so the ' \
+              'unique digest never repeats. Drop one of the two options on this worker.'
+      end
+
       # Add `at - now` delay to the base TTL so a scheduled job's lock
       # spans the wait + execution window (§3.4). Returns nil when the
       # job opts out (`unique_for: false` / missing).

data/lib/wurk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Wurk
-  VERSION = "1.1.1"
+  VERSION = "1.2.0"
 end

data/lib/wurk/web/enterprise.rb

@@ -42,11 +42,33 @@ module Wurk
         # row remains in the UI. Mirrors the §1.5 `#reset` surface — the
         # name is wire-compat, so the trailing-? rule doesn't apply here.
         def reset(name) # rubocop:disable Naming/PredicateMethod
+          limiter = rebuild(name)
+          # Reconstruct the limiter and delegate: only the type itself knows
+          # its state keys. A bucket's counter lives at `lmtr-b:<name>:<epoch>`,
+          # so the bare-prefix DEL below never touched it.
+          limiter ? limiter.reset : reset_by_prefix(name)
+          true
+        end
+
+        # Read-only reconstruction (`register: false`) from the persisted
+        # metadata. Returns nil when the meta HASH is gone or malformed —
+        # LIST membership has no TTL, so a name can outlive its metadata.
+        def rebuild(name)
+          meta = metadata(name)
+          return nil if meta.nil? || meta.empty?
+
+          options = meta['options'] ? ::JSON.parse(meta['options']) : {}
+          Wurk::Limiter.build(name, meta['type'], options)
+        rescue StandardError
+          nil
+        end
+
+        # Metadata-less fallback: wipe every type's un-suffixed state key.
+        def reset_by_prefix(name)
           Wurk.redis do |c|
-            %W[lmtr-cs:#{name} lmtr-b:#{name} lmtr-w:#{name} lmtr-l:#{name}
+            %W[lmtr-cs:#{name} lmtr-w:#{name} lmtr-l:#{name}
                lmtr-p:#{name} lmtr-stats:#{name}].each { |k| c.call('DEL', k) }
           end
-          true
         end
       end
 

data/lib/wurk/worker/setter.rb

@@ -31,8 +31,24 @@ module Wurk
         @klass.client_push(@opts.merge('class' => @klass, 'args' => args))
       end
 
-      def perform_inline(*)
-        @klass.new.perform(*)
+      # Explicit synchronous execution. Runs the payload through the real client
+      # AND server middleware chains rather than calling `perform` directly:
+      # unique-job locks are taken by the client chain and released only by the
+      # server chain (bypassing both leaked every lock until its TTL), and batch
+      # callbacks fire from server middleware. Mirrors Sidekiq's Setter#perform_inline,
+      # including its return contract — nil when middleware halts the job, else true.
+      def perform_inline(*args)
+        config = Wurk.configuration
+        item = normalize_item(@opts.merge('class' => @klass, 'args' => args))
+        pushed = config.client_middleware.invoke(item['class'], item, item['queue'], config.redis_pool) do
+          verify_json(item)
+          item
+        end
+        return nil unless pushed
+
+        # Round-trip through JSON so the job sees exactly the arguments a real
+        # worker would after the payload has crossed Redis.
+        run_job(Wurk.load_json(Wurk.dump_json(item)), config)
       end
       alias perform_sync perform_inline
 
@@ -58,6 +74,17 @@ module Wurk
 
       private
 
+      def run_job(msg, config)
+        instance = @klass.new
+        instance.jid = msg['jid']
+        instance.bid = msg['bid'] if instance.respond_to?(:bid=)
+        ran = config.server_middleware.invoke(instance, msg, msg['queue']) do
+          instance.perform(*msg['args'])
+          true
+        end
+        ran ? true : nil
+      end
+
       def absolute_at(interval)
         unless interval.is_a?(Numeric) || interval.is_a?(Time)
           raise ArgumentError, "interval must be Numeric or Time, got #{interval.class}"

data/lib/wurk/worker.rb

@@ -132,12 +132,12 @@ module Wurk
         Wurk::Worker::Setter.new(self, {}).perform_async(*)
       end
 
-      # Run `#perform` synchronously in the current thread (no Redis). Useful in
-      # tests and for inline execution.
+      # Run the job synchronously in the current thread, through both middleware
+      # chains (see {Wurk::Worker::Setter#perform_inline}). Useful in tests.
       #
-      # @return [Object] the return value of `#perform`
+      # @return [true, nil] nil when middleware halted the job, true otherwise
       def perform_inline(*)
-        new.perform(*)
+        Wurk::Worker::Setter.new(self, {}).perform_inline(*)
       end
       alias perform_sync perform_inline
 

data/vendor/assets/dashboard/wurk-manifest.json

@@ -1,4 +1,4 @@
 {
-  "version": "1.1.1",
-  "timestamp": "2026-07-18T13:06:31.576Z"
+  "version": "1.2.0",
+  "timestamp": "2026-07-21T04:58:05.082Z"
 }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: wurk
 version: !ruby/object:Gem::Version
-  version: 1.1.1
+  version: 1.2.0
 platform: ruby
 authors:
 - developerz.ai