wurk 0.0.5 → 1.0.0

data/lib/wurk/job.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'worker'
+require_relative 'worker/setter'
 
 module Wurk
   # Sidekiq 7+ alias for Wurk::Worker. `include Wurk::Job` and
@@ -20,6 +21,13 @@ module Wurk
     # Spec: docs/target/sidekiq-free.md §6.4.
     class Interrupted < RuntimeError; end
 
+    # Per-call option carrier returned by `set(...)`. Sidekiq 7+ documents it
+    # under the modern mixin name `Sidekiq::Job::Setter`; since
+    # `Sidekiq::Job = Wurk::Job`, this rebind is what makes that constant
+    # resolve (without it `Sidekiq::Job::Setter` raises NameError). Same class
+    # as `Sidekiq::Worker::Setter`. Spec: docs/target/sidekiq-free.md §6.3.
+    Setter = Wurk::Worker::Setter
+
     def self.included(base)
       base.include(Wurk::Worker)
     end

data/lib/wurk/job_record.rb

@@ -53,6 +53,15 @@ module Wurk
     def args          = item['args']
     def jid           = item['jid']
     def bid           = item['bid']
+
+    # IterableJob progress for this job, or nil for a non-iterable job (no
+    # `it-<jid>` HASH). Spec §19.3. Reads via the IterableJobQuery data API.
+    def iterable_state
+      return nil if jid.nil? || jid.to_s.empty?
+
+      Wurk::IterableJobQuery.new([jid])[jid]
+    end
+
     def tags          = item['tags'] || []
     def enqueued_at   = parse_time(item['enqueued_at'])
     def created_at    = parse_time(item['created_at'])
@@ -96,10 +105,16 @@ module Wurk
       @display_class = active_job_wrapper? ? unwrap_class : klass
     end
 
+    # UI-facing args. Encrypted jobs (§4.7) get their envelope last arg
+    # masked as "<encrypted>" so ciphertext never reaches the dashboard;
+    # redaction keys off the envelope shape, so it fires whether or not the
+    # stored hash carried the `encrypt` flag. Cleartext preceding args stay
+    # visible for triage. Display-only — the stored payload is untouched.
     def display_args
       return @display_args if defined?(@display_args)
 
-      @display_args = active_job_wrapper? ? unwrap_args : args
+      base = active_job_wrapper? ? unwrap_args : args
+      @display_args = Wurk::Encryption.redact_args('args' => base, 'encrypt' => item['encrypt'])
     end
 
     # @api internal

data/lib/wurk/job_set.rb

@@ -122,10 +122,10 @@ module Wurk
       count
     end
 
-    # Moves every job in this set to the dead set. `notify_failure: false`
-    # because this is a UI-initiated bulk action, not a retry-exhausted
-    # event. Returns the count of jobs moved.
-    def kill_all(notify_failure: false, ex: nil)
+    # Moves every job in this set to the dead set. Death handlers fire per
+    # entry by default — `each(&:kill)` equivalence with Sidekiq; pass
+    # `notify_failure: false` to suppress. Returns the count of jobs moved.
+    def kill_all(notify_failure: true, ex: nil)
       count = 0
       dead = DeadSet.new
       until size.zero?

data/lib/wurk/job_util.rb

@@ -9,10 +9,15 @@ module Wurk
   #
   # Spec: docs/target/sidekiq-free.md §9 (Sidekiq::JobUtil).
   module JobUtil # rubocop:disable Metrics/ModuleLength
-    # Top-level keys stripped from every payload before raw_push. Mutable so
-    # Pro/Ent/extension code (e.g. TransactionAwareClient adding "client_class")
-    # can append at load time without monkey-patching.
-    TRANSIENT_ATTRIBUTES = [] # rubocop:disable Style/MutableConstant
+    # Top-level keys consumed at enqueue time but stripped from every payload
+    # before raw_push — they must never reach the wire (spec §2.2):
+    #   `pool`         selects the Redis pool (resolved in client_push/build_client)
+    #   `client_class` swaps the enqueue client (Wurk.transactional_push!)
+    # Both carry non-JSON values (a pool / a Class). Baked into the literal rather
+    # than appended at load: a load-time `<<` is fragile under the parallel test
+    # runner (a test that add/deletes the same key clobbers it for later suites).
+    # Still mutable so other extensions can append without monkey-patching.
+    TRANSIENT_ATTRIBUTES = %w[pool client_class] # rubocop:disable Style/MutableConstant
 
     RETRY_FOR_MAX = 1_000_000_000
 
@@ -111,13 +116,17 @@ module Wurk
 
     # Pro `expires_in:` → absolute epoch-float `expiry` resolved once at push,
     # so the server middleware doesn't redo the math. Spec: sidekiq-pro.md §7.
+    # For scheduled jobs the clock origin is `at` (epoch seconds), not
+    # `created_at` (epoch millis) — otherwise any delay > expires_in makes the
+    # job born-expired: perform_in(2h) + expires_in: 1h must expire at 3h.
     # nil.respond_to?(:to_f) is true on modern Ruby (returns 0.0), so we must
     # gate on a non-nil duration before coercing.
     def stamp_expiry(item)
       d = item['expires_in']
-      return if d.nil?
+      return if d.nil? || !d.respond_to?(:to_f)
 
-      item['expiry'] ||= (item['created_at'].to_f / 1000.0) + d.to_f if d.respond_to?(:to_f)
+      origin = item['at'] ? item['at'].to_f : (item['created_at'].to_f / 1000.0)
+      item['expiry'] ||= origin + d.to_f
     end
 
     def report_unsafe(item, offender, mode)

data/lib/wurk/keys.rb

@@ -29,6 +29,16 @@ module Wurk
     # Live process identities (heartbeat membership).
     PROCESSES      = 'processes'
 
+    # Ent Historical Metrics: capped Redis stream of periodic snapshots written
+    # by Wurk::History (§5.3). Same key a migrated Sidekiq Ent install uses, so
+    # its existing data renders without rewrite. Spec: sidekiq-ent.md §5.3, §10.
+    HISTORY_METRICS = 'history:metrics'
+
+    # Profiles (v8.0+): ZSET of `<token>-<jid>` keys, score = expiry epoch;
+    # each member also has a `<token>-<jid>` HASH holding the profile blob.
+    # Spec: docs/target/sidekiq-free.md §1.7.
+    PROFILES       = 'profiles'
+
     # Global processed counter; per-day variants append `:YYYY-MM-DD`.
     STAT_PROCESSED = 'stat:processed'
 

data/lib/wurk/launcher.rb

@@ -10,6 +10,8 @@ require_relative 'scheduled'
 require_relative 'leader'
 require_relative 'cron'
 require_relative 'metrics/rollup'
+require_relative 'metrics/queue_rollup'
+require_relative 'history'
 require_relative 'fetcher/reaper'
 
 module Wurk
@@ -41,7 +43,7 @@ module Wurk
     # (Sidekiq's drop-in surface). The single source of truth is Heartbeat.
     BEAT_PAUSE = Heartbeat::BEAT_PAUSE
 
-    attr_accessor :managers, :poller, :cron_poller, :metrics_rollup
+    attr_accessor :managers, :poller, :cron_poller, :metrics_rollup, :queue_rollup, :history
 
     def initialize(config, embedded: false)
       @config = config
@@ -51,6 +53,8 @@ module Wurk
       @poller = build_poller
       @cron_poller = build_cron_poller
       @metrics_rollup = build_metrics_rollup
+      @queue_rollup = build_queue_rollup
+      @history = build_history
       @leader = build_leader
       @reaper = build_reaper
       @started_at = nil
@@ -81,8 +85,11 @@ module Wurk
       @leader&.start
       @cron_poller&.start
       @metrics_rollup&.start
+      @queue_rollup&.start
+      @history&.start
       @managers.each(&:start)
       @reaper.start
+      boot_reclaim
       @health_server&.start
     end
 
@@ -114,6 +121,8 @@ module Wurk
       # releasing the lock so no tick races a follower's promotion.
       @cron_poller&.terminate
       @metrics_rollup&.terminate
+      @queue_rollup&.terminate
+      @history&.terminate
       @reaper&.stop
       # CAS-release the cluster lock now (planned shutdown) so a follower can
       # take over immediately instead of waiting out the TTL.
@@ -247,6 +256,20 @@ module Wurk
       Wurk::Metrics::Rollup.new(@config)
     end
 
+    # Leader-only per-queue gauge sampler. Like the metrics rollup, every
+    # process runs one but only the leader writes the `qm|…` size/latency
+    # buckets the Historical tab's per-queue charts read.
+    def build_queue_rollup
+      Wurk::Metrics::QueueRollup.new(@config)
+    end
+
+    # Ent §5 Historical Metrics snapshotter — only when the host opted in via
+    # `config.retain_history`. Leader-gated like the rollups, so just one
+    # process emits the cluster-wide snapshot per interval.
+    def build_history
+      Wurk::History.new(@config) if @config.history_enabled?
+    end
+
     # Every worker process campaigns for the single cluster lock (`dear-leader`);
     # one wins and renews it, the rest follow and promote on its death. Cadence
     # falls back to the spec defaults (TTL 30 / renew 15 / follower 60) unless
@@ -260,6 +283,17 @@ module Wurk
       )
     end
 
+    # Deterministic boot-time orphan sweep: a SIGKILLed sibling's in-flight jobs
+    # would otherwise wait a full reaper interval before recovery. One unguarded
+    # scoped reclaim at start (no cluster lock — every booting worker helps) gets
+    # them re-queued immediately. Best-effort: a Redis hiccup here must not abort
+    # boot. Spec: docs/target/sidekiq-pro.md §3.2.
+    def boot_reclaim
+      @reaper.reclaim!
+    rescue StandardError => e
+      handle_exception(e, context: 'launcher-boot-reclaim') if respond_to?(:handle_exception)
+    end
+
     # Reliable-fetch orphan reclamation. Every worker runs one; a cluster
     # `SET NX EX` lock ensures only one actually sweeps per interval, so this
     # is leader-independent (it keeps working if the leader dies). Tune the

data/lib/wurk/leader.rb

@@ -20,7 +20,8 @@ module Wurk
   #
   # Cadence per spec: renew every 15s while leader, recheck every 60s as
   # follower, lock TTL 30s. Opt out a process from campaigning entirely
-  # with `WURK_LEADER=false` (useful for hot-standby pools).
+  # with `WURK_LEADER=false` (or its Sidekiq alias `SIDEKIQ_LEADER=false`),
+  # useful for hot-standby pools.
   #
   # Spec: docs/target/sidekiq-ent.md §6.
   class Leader
@@ -29,9 +30,17 @@ module Wurk
     DEFAULT_TTL = 30
     DEFAULT_RENEW_INTERVAL = 15
     DEFAULT_FOLLOWER_INTERVAL = 60
-    OPT_OUT_ENV = 'WURK_LEADER'
+    OPT_OUT_ENV = 'WURK_LEADER'            # native opt-out env
+    SIDEKIQ_OPT_OUT_ENV = 'SIDEKIQ_LEADER' # Sidekiq Ent drop-in alias (§6.2/§7.2)
     THREAD_NAME = 'wurk-leader'
 
+    # True when this process has opted out of campaigning via `WURK_LEADER=false`
+    # or its Sidekiq alias `SIDEKIQ_LEADER=false` (hot-standby pools that must
+    # never lead). Either env name works.
+    def self.opted_out?
+      [OPT_OUT_ENV, SIDEKIQ_OPT_OUT_ENV].any? { |k| ENV[k].to_s.downcase == 'false' }
+    end
+
     attr_reader :key, :ttl, :owner, :token, :config
 
     def initialize(config: nil, key: DEFAULT_KEY, ttl: DEFAULT_TTL, # rubocop:disable Metrics/ParameterLists
@@ -53,11 +62,11 @@ module Wurk
       @sleeper = ::ConditionVariable.new
     end
 
-    # `WURK_LEADER=false` makes `acquire` a no-op and `leader?` permanently
-    # false; the renewal thread also refuses to start. Useful for hot-
-    # standby pools that must never campaign.
+    # `WURK_LEADER=false` (or `SIDEKIQ_LEADER=false`) makes `acquire` a no-op and
+    # `leader?` permanently false; the renewal thread also refuses to start.
+    # Useful for hot-standby pools that must never campaign.
     def disabled?
-      ENV[OPT_OUT_ENV].to_s.downcase == 'false'
+      self.class.opted_out?
     end
 
     # SET NX EX. If the key already holds *our* owner string (rare — same

data/lib/wurk/limiter/bucket.rb

@@ -71,9 +71,20 @@ module Wurk
       end
 
       def acquire(used)
-        lua(:limiter_bucket_acquire,
-            keys: ["lmtr-b:#{@name}"],
-            argv: [@options[:count], interval_seconds, used, ttl])
+        # Resolve the epoch from the Redis clock (spec §1: timing from TIME, not
+        # the client clock) and pass the single fully-qualified key. One declared
+        # key is safe on both Redis Cluster (no CROSSSLOT) and Dragonfly (no
+        # undeclared-key access) — see lua/limiter_bucket_acquire.lua (#91).
+        Wurk::Limiter.redis do |c|
+          now = c.call('TIME').first.to_i
+          epoch = now / interval_seconds
+          remaining = ((epoch + 1) * interval_seconds) - now
+          Wurk::Lua::Loader.eval_cached(
+            c, :limiter_bucket_acquire,
+            keys: ["lmtr-b:#{@name}:#{epoch}"],
+            argv: [@options[:count], used, ttl, remaining]
+          )
+        end
       end
     end
   end

data/lib/wurk/limiter/concurrent.rb

@@ -87,7 +87,7 @@ module Wurk
       # Lowest slot expiry epoch (the next slot to free), or nil when empty.
       def soonest_expiry
         row = Wurk::Limiter.redis { |c| c.call('ZRANGE', state_key, 0, 0, 'WITHSCORES') }
-        row && !row.empty? ? row[1].to_f : nil
+        Wurk::Limiter.first_score(row)
       end
 
       def state_key

data/lib/wurk/limiter/window.rb

@@ -63,7 +63,8 @@ module Wurk
       # Oldest timestamp + interval = the moment it leaves the window.
       def oldest_expiry
         row = Wurk::Limiter.redis { |c| c.call('ZRANGE', state_key, 0, 0, 'WITHSCORES') }
-        row && !row.empty? ? row[1].to_f + interval_seconds : nil
+        score = Wurk::Limiter.first_score(row)
+        score && (score + interval_seconds)
       end
 
       def interval_seconds

data/lib/wurk/limiter.rb

@@ -140,6 +140,18 @@ module Wurk
         pool.with(&)
       end
 
+      # `ZRANGE key 0 0 WITHSCORES` yields a single [member, score] pair, but the
+      # shape depends on the protocol: RESP3 (redis-client's default vs Redis >= 7)
+      # nests it as [[member, score]]; RESP2 returns a flat [member, score].
+      # Return the score as a Float across both, or nil when the set is empty.
+      # (The old flat-only `row[1]` silently collapsed to 0.0 under RESP3.)
+      def first_score(row)
+        pair = row.first
+        return nil if pair.nil?
+
+        (pair.is_a?(Array) ? pair.last : row[1]).to_f
+      end
+
       def concurrent(name, limit, wait_timeout: DEFAULT_WAIT_TIMEOUT, lock_timeout: DEFAULT_LOCK_TIMEOUT,
                      policy: :raise, backoff: nil, ttl: DEFAULT_TTL)
         Concurrent.new(name,

data/lib/wurk/lua/loader.rb

@@ -38,6 +38,16 @@ module Wurk
           evalsha(redis, sha, keys, argv)
         end
 
+        # Source-embedded EVAL — the slow but cache-independent counterpart to
+        # `eval_cached`. Used on retry from a pipelined NOSCRIPT recovery where
+        # EVALSHA can still race a freshly-loaded script under heavy CI load
+        # (cf. WorkerTest NOSCRIPT flake on test (3.4, 7.2)). EVAL ships the
+        # full source every call, so it never raises NOSCRIPT.
+        def eval_with_source(redis, name, keys:, argv:)
+          src = SCRIPTS.fetch(name) { raise ArgumentError, "unknown Lua script: #{name.inspect}" }
+          redis.call('EVAL', src, keys.size, *keys, *argv)
+        end
+
         private
 
         def evalsha(redis, sha, keys, argv)

data/lib/wurk/lua.rb

@@ -12,7 +12,7 @@ module Wurk
   #
   # `:zpopbyscore` is reproduced verbatim from sidekiq-free.md §1.8 and
   # MUST NOT diverge — parity tests will fail on a single byte change.
-  module Lua
+  module Lua # rubocop:disable Metrics/ModuleLength
     ZPOPBYSCORE = <<~LUA
       local key, now = KEYS[1], ARGV[1]
       local jobs = redis.call("zrange", key, "-inf", now, "byscore", "limit", 0, 1)
@@ -58,13 +58,31 @@ module Wurk
 
     # Pro Batch: register a job into a batch and push it to its queue
     # atomically. Keeps total/pending in sync with the jids set.
-    # KEYS = [b-<bid>, b-<bid>-jids, queue_list, queues_set]
-    # ARGV = [queue_name, jid, job_json]
+    #
+    # A jid found in `b-<bid>-died` is a manual retry of a dead job (morgue
+    # "retry" / "add to queue") — it rejoins the live set without recounting:
+    # total and pending already include it, because a death never decrements
+    # pending. When that drains the died set the batch is no longer dead, so
+    # the durable `death` success-suppression flag clears and the bid leaves
+    # `dead-batches` — a later full drain can then fire `:success` (spec §2.4:
+    # success after the dead job is manually retried to success). The
+    # `b-<bid>-death` notify dedup key is untouched, so `:death` cannot
+    # re-fire.
+    # KEYS = [b-<bid>, b-<bid>-jids, queue_list, queues_set, b-<bid>-died, dead-batches]
+    # ARGV = [queue_name, jid, job_json, bid]
     # Returns 1.
     BATCH_PUSH = <<~LUA
-      redis.call("hincrby", KEYS[1], "total", 1)
-      redis.call("hincrby", KEYS[1], "pending", 1)
-      redis.call("sadd", KEYS[2], ARGV[2])
+      if redis.call("srem", KEYS[5], ARGV[2]) == 1 then
+        redis.call("sadd", KEYS[2], ARGV[2])
+        if redis.call("scard", KEYS[5]) == 0 then
+          redis.call("hdel", KEYS[1], "death")
+          redis.call("zrem", KEYS[6], ARGV[4])
+        end
+      else
+        redis.call("hincrby", KEYS[1], "total", 1)
+        redis.call("hincrby", KEYS[1], "pending", 1)
+        redis.call("sadd", KEYS[2], ARGV[2])
+      end
       redis.call("sadd", KEYS[4], ARGV[1])
       redis.call("lpush", KEYS[3], ARGV[3])
       return 1
@@ -72,12 +90,21 @@ module Wurk
 
     # Pro Batch: ACK a job that completed successfully. SREM from the live
     # jids set and decrement pending iff the jid was a member (idempotent
-    # against double-success on a flaky retry).
-    # KEYS = [b-<bid>, b-<bid>-jids]
+    # against double-success on a flaky retry). A success also clears any
+    # outstanding "currently failing" record for the jid (a retry that finally
+    # passed), decrementing `failures` so it converges to the count of jobs
+    # *still* failing — Sidekiq Pro semantics, spec §2.5. The failed-set clear
+    # runs *before* the live-jids check so an invalidated batch (BATCH_INVALIDATE
+    # deletes the jids set) still converges failures to 0 on its short-circuited
+    # success ack, instead of stranding the jid in failed forever.
+    # KEYS = [b-<bid>, b-<bid>-jids, b-<bid>-failed]
     # ARGV = [jid]
     # Returns [new_pending, live_jids_remaining], or [-1, -1] when the jid
     # was not a member (treat as already acked).
     BATCH_ACK_SUCCESS = <<~LUA
+      if redis.call("srem", KEYS[3], ARGV[1]) == 1 then
+        redis.call("hincrby", KEYS[1], "failures", -1)
+      end
       local removed = redis.call("srem", KEYS[2], ARGV[1])
       if removed == 1 then
         local pending = redis.call("hincrby", KEYS[1], "pending", -1)
@@ -86,9 +113,28 @@ module Wurk
       return { -1, -1 }
     LUA
 
-    # Pro Batch: ACK a job that exhausted retries and died. Records death,
-    # bumps failures, and SREMs from live jids so the batch can fire
-    # `:complete` even with terminally failed jobs.
+    # Pro Batch: record a job that failed and will retry (transient failure).
+    # SADDs the jid to the `failed` set and bumps `failures` only on the first
+    # add, so `failures` == SCARD(b-<bid>-failed) == the number of jobs
+    # currently in a failing/retrying state. Re-failures of the same jid are
+    # idempotent. Cleared by BATCH_ACK_SUCCESS (retry passed) or
+    # BATCH_ACK_COMPLETE (job died). Spec §2.5, §2.8.
+    # KEYS = [b-<bid>, b-<bid>-failed]
+    # ARGV = [jid]
+    # Returns 1.
+    BATCH_ACK_FAILED = <<~LUA
+      if redis.call("sadd", KEYS[2], ARGV[1]) == 1 then
+        redis.call("hincrby", KEYS[1], "failures", 1)
+      end
+      return 1
+    LUA
+
+    # Pro Batch: ACK a job that exhausted retries and died. Moves the jid from
+    # "currently failing" to "died": SREMs from the failed set (decrementing
+    # `failures` if it was recorded as failing), SADDs to died, and SREMs from
+    # live jids so the batch can fire `:complete` even with terminally failed
+    # jobs. `b-<bid>-failed` holds only currently-retrying jids; `b-<bid>-died`
+    # holds terminally-dead ones (spec §2.8 — the two sets are distinct).
     # KEYS = [b-<bid>, b-<bid>-jids, b-<bid>-died, b-<bid>-failed]
     # ARGV = [jid]
     # Returns [live_jids_remaining, died_count, first_death]. `first_death`
@@ -97,9 +143,10 @@ module Wurk
     BATCH_ACK_COMPLETE = <<~LUA
       local was_pre_existing_death = redis.call("scard", KEYS[3])
       redis.call("srem", KEYS[2], ARGV[1])
-      redis.call("sadd", KEYS[4], ARGV[1])
+      if redis.call("srem", KEYS[4], ARGV[1]) == 1 then
+        redis.call("hincrby", KEYS[1], "failures", -1)
+      end
       local died_added = redis.call("sadd", KEYS[3], ARGV[1])
-      redis.call("hincrby", KEYS[1], "failures", 1)
       local first_death = 0
       if was_pre_existing_death == 0 and died_added == 1 then
         first_death = 1
@@ -120,6 +167,48 @@ module Wurk
       return 1
     LUA
 
+    # Pro Batch (§2.4): atomically append one callback triple to the
+    # `callbacks` JSON array on the batch hash. Server-side append (vs a
+    # Ruby read-modify-write) so two processes registering callbacks on the
+    # same reopened batch cannot lose each other's writes. Refuses to write
+    # when the batch hash is gone — resurrecting a bare hash would create a
+    # batch that can never fire anything.
+    # KEYS = [b-<bid>]
+    # ARGV = [callback triple JSON, event name]
+    # Returns -1 when the batch hash does not exist; otherwise the event's
+    # fired flag ("1", or nil when it has not fired yet).
+    BATCH_APPEND_CALLBACK = <<~LUA
+      if redis.call("exists", KEYS[1]) == 0 then
+        return -1
+      end
+      local raw = redis.call("hget", KEYS[1], "callbacks")
+      local list
+      if raw and raw ~= "" then
+        list = cjson.decode(raw)
+      else
+        list = {}
+      end
+      list[#list + 1] = cjson.decode(ARGV[1])
+      redis.call("hset", KEYS[1], "callbacks", cjson.encode(list))
+      return redis.call("hget", KEYS[1], ARGV[2])
+    LUA
+
+    # Ent Unique (§3): atomic compare-and-delete of a lock key. Replaces the
+    # two-command GET-then-DEL — between those calls the key can expire and a
+    # fresh enqueue can grab it, and the bare DEL would then drop the new
+    # owner's lock. Shared by `Unique::ServerMiddleware#release` (normal
+    # success/start release) and `Unique::DEATH_HANDLER` (automatic-death
+    # release) so the two paths cannot drift.
+    # KEYS = [unique:<sha256>]
+    # ARGV = [owning jid]
+    # Returns 1 when the key was deleted, 0 otherwise.
+    RELEASE_IF_OWNER = <<~LUA
+      if redis.call("get", KEYS[1]) == ARGV[1] then
+        return redis.call("del", KEYS[1])
+      end
+      return 0
+    LUA
+
     # Pro Fast API (§11): server-side LRANGE+LREM to delete a single job by
     # jid from a queue list. Pure-Ruby Queue#find_job + JobRecord#delete is
     # O(N) round-trips; this is O(1) round-trip with O(N) Lua work.
@@ -172,10 +261,13 @@ module Wurk
       reliable_schedule_promote: RELIABLE_SCHEDULE_PROMOTE,
       batch_push: BATCH_PUSH,
       batch_ack_success: BATCH_ACK_SUCCESS,
+      batch_ack_failed: BATCH_ACK_FAILED,
       batch_ack_complete: BATCH_ACK_COMPLETE,
       batch_invalidate: BATCH_INVALIDATE,
+      batch_append_callback: BATCH_APPEND_CALLBACK,
       fast_delete_job: FAST_DELETE_JOB,
-      fast_delete_by_class: FAST_DELETE_BY_CLASS
+      fast_delete_by_class: FAST_DELETE_BY_CLASS,
+      release_if_owner: RELEASE_IF_OWNER
     }.merge(FILE_SCRIPTS).freeze
 
     # SHA1 of each script source — matches what `SCRIPT LOAD` returns.

data/lib/wurk/metrics/history.rb

@@ -147,5 +147,10 @@ module Wurk
       end
       private_class_method :with_pool
     end
+
+    # Sidekiq exposes this as `Sidekiq::Metrics::Middleware` (via
+    # `Sidekiq::Metrics`, aliased to `Wurk::Metrics` in compat). Mirror that
+    # name so the drop-in constant resolves. Spec: docs/target/sidekiq-free.md §10.3.
+    Middleware = History
   end
 end

data/lib/wurk/metrics/query.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+require_relative '../keys'
 require_relative 'history'
 require_relative 'rollup'
+require_relative 'queue_rollup'
 
 module Wurk
   module Metrics
@@ -59,6 +61,43 @@ module Wurk
         starts.zip(rows).map { |at, (p, f, ms)| { at: at, p: p.to_i, f: f.to_i, ms: ms.to_i } }
       end
 
+      # Per-queue size/latency gauge time-series written by
+      # Metrics::QueueRollup. `bucket` is '1m'/'5m'/'1h'; `window_seconds` is
+      # clamped to the bucket's retention. Returns one entry per live queue
+      # (or the explicit `queues:` list) — `[{name:, points: [{at:, size:,
+      # latency:}, …]}, …]` — oldest→newest, gap-filled with zeros so a chart
+      # has a continuous x-axis. Capped at MAX_QUEUE_SERIES queues to bound the
+      # payload; the cap is logged-free because queue cardinality is small.
+      def queue_history(bucket, window_seconds, queues: nil, now: ::Time.now)
+        step, ttl = bucket_spec!(bucket)
+        starts = bucket_starts(now, step, clamp_history_window!(window_seconds, ttl))
+        names = queue_names(queues)
+        return [] if names.empty?
+
+        hashes = queue_bucket_hashes(bucket, starts)
+        names.map { |name| { name: name, points: queue_points(name, starts, hashes) } }
+      end
+
+      def queue_bucket_hashes(bucket, starts)
+        pipeline_hgetall(starts.map { |s| Wurk::Metrics::QueueRollup.bucket_key(bucket, s) })
+          .map { |h| h.is_a?(::Array) ? h.each_slice(2).to_h : (h || {}) }
+      end
+
+      MAX_QUEUE_SERIES = 25
+
+      def queue_names(queues)
+        names = queues || Wurk.redis { |c| c.call('SMEMBERS', Wurk::Keys::QUEUES_SET) }
+        names.sort.first(MAX_QUEUE_SERIES)
+      end
+
+      def queue_points(name, starts, hashes)
+        size_field = "#{name}|#{Wurk::Metrics::QueueRollup::SIZE_KIND}"
+        lat_field  = "#{name}|#{Wurk::Metrics::QueueRollup::LAT_KIND}"
+        starts.zip(hashes).map do |at, hash|
+          { at: at, size: hash[size_field].to_i, latency: (hash[lat_field] || 0).to_f }
+        end
+      end
+
       def bucket_spec!(bucket)
         Wurk::Metrics::Rollup::BUCKETS.fetch(bucket) do
           raise ArgumentError, "bucket must be one of #{Wurk::Metrics::Rollup::BUCKETS.keys.inspect}"