wurk 1.8.0 → 1.9.0

data/lib/wurk/configuration.rb

@@ -163,7 +163,7 @@ module Wurk
       @capsules = {}
       @directory = {}
       @client_chain = Middleware::Chain.new
-      @server_chain = Middleware::Chain.new
+      @server_chain = Middleware::Chain.new(on_registration: method(:warn_on_late_server_registration))
       @redis_config = { url: ENV.fetch('REDIS_URL', 'redis://localhost:6379/0') }
       @web_redis_pool = nil
       @logger = nil
@@ -705,7 +705,26 @@ module Wurk
     # (200 only when Redis is reachable AND heartbeat fired within
     # `ready_window` seconds).
     #
-    # Off by default — call this in a `configure_server` block to enable.
+    # Off by default. Put this in Rails `config/initializers/wurk.rb` loaded
+    # by the worker boot, or in the Ruby boot file loaded via `-r` by `wurk`,
+    # `wurkswarm`, or `sidekiqswarm`:
+    #
+    #   Wurk.configure_server do |config|
+    #     config.health_check(port: 7433)
+    #   end
+    #
+    # `configure_server` executes its block only when the current process is
+    # already in server mode. Configuration is process-local: configuring a
+    # separate web/client process cannot enable the worker's probes.
+    #
+    # For explicit embedding, configure the embedded worker directly before
+    # calling `run`; `configure_embed` does not enter server mode:
+    #
+    #   embedded = Wurk.configure_embed do |config|
+    #     config.health_check(port: 7433)
+    #   end
+    #   embedded.run
+    #
     # Spec: docs/target/sidekiq-ent.md §7.1.2.
     #
     # `metrics:` serves the Prometheus scrape on the same listener (on by
@@ -773,15 +792,33 @@ module Wurk
 
     # --- Configure blocks (Sidekiq.configure_server / _client) -----------
 
-    def configure_server(&block)
-      yield self if block && server?
+    # The gate is evaluated per call: a skipped block is never yielded and
+    # never replayed, and an allowed one yields the configuration and returns
+    # the block's value. A skip reports itself once per gate per instance —
+    # the flags below decide only whether the skip is reported again, and
+    # they live outside @options so a frozen configuration can still warn.
+    def configure_server
+      return unless block_given?
+      return yield self if server?
+      return if @configure_server_skip_warned
+
+      @configure_server_skip_warned = true
+      logger.warn { 'configure_server block skipped: server? is false' }
+      nil
     end
 
     # A web process that also boots the swarm (Wurk::RailsBoot) is flagged
     # server, yet every enqueue it makes from a request is client work, so
-    # `client_in_server` lets its configure_client blocks run too.
-    def configure_client(&block)
-      yield self if block && (!server? || @options[:client_in_server])
+    # `client_in_server` lets its configure_client blocks run too. Same
+    # one-warning-per-gate contract as configure_server.
+    def configure_client
+      return unless block_given?
+      return yield self if !server? || @options[:client_in_server]
+      return if @configure_client_skip_warned
+
+      @configure_client_skip_warned = true
+      logger.warn { 'configure_client block skipped: server? is true and client_in_server is false or nil' }
+      nil
     end
 
     def server?
@@ -854,6 +891,7 @@ module Wurk
       prepare_for_fork!
       @capsules.each_value(&:freeze)
       @capsules.freeze
+      warn_on_missing_server_middleware
       warn_on_small_db_pool
       self
     end
@@ -868,6 +906,47 @@ module Wurk
 
     private
 
+    def warn_on_late_server_registration(klass)
+      affected = @capsules.each_value.filter_map do |capsule|
+        capsule.name if capsule.prepared? && capsule.server_middleware_missing?(klass)
+      end
+      return if affected.empty?
+
+      logger.warn do
+        "Global server middleware #{klass} registered after preparation for capsules: #{affected.join(', ')}; " \
+          'existing worker snapshots remain unchanged. Register middleware before worker boot, then restart workers. ' \
+          'This diagnostic only inspects capsules in this process.'
+      end
+    end
+
+    # Registrations run against the singleton when wurk is loaded, not when a
+    # host constructs a Configuration. Resolve classes here to avoid making
+    # configuration.rb depend on middleware load order or mutable global chains.
+    def warn_on_missing_server_middleware
+      built_ins = %w[
+        Middleware::InterruptHandler Middleware::Expiry Middleware::Timeout
+        Middleware::Status Middleware::I18n::Server Batch::ServerMiddleware
+        Limiter::ServerMiddleware Metrics::Statsd Metrics::History
+      ].filter_map { |name| loaded_middleware_class(name) }
+      return if @server_chain.entries.any? { |entry| built_ins.include?(entry.klass) }
+
+      logger.warn do
+        'Wurk configuration has no built-in server middleware; batch callbacks, limiter handling, ' \
+          'job expiry, timeouts, status tracking, locale propagation, interrupt handling and metrics ' \
+          'may be unavailable. Fresh Configuration.new instances do not inherit load-time registrations. ' \
+          'Use Wurk.default_configuration or explicitly install the middleware your jobs need. ' \
+          'Custom-only chains are allowed; this warning does not change the chain.'
+      end
+    end
+
+    def loaded_middleware_class(name)
+      name.split('::').reduce(Wurk) do |namespace, part|
+        break unless namespace.const_defined?(part, false)
+
+        namespace.const_get(part, false)
+      end
+    end
+
     def validate_constructor_options!
       @options[:global_concurrency] = normalize_global_concurrency(@options[:global_concurrency])
       RedisPool.validate_idle_timeout(@options[:redis_idle_timeout])

data/lib/wurk/encryption.rb

@@ -70,6 +70,13 @@ module Wurk
     class Error < StandardError; end
     class KeyMissingError < Error; end
 
+    # Raised when crypto is enabled too late to reach the workers. A capsule
+    # that already holds the server middleware chain its workers run can never
+    # receive ServerMiddleware again, so enabling now would seal arguments the
+    # workers cannot open — `perform` would receive the raw envelope. The
+    # enablement is refused whole: nothing is enabled, nothing is sealed.
+    class UnsafeEnablementError < Error; end
+
     # Marker for a terminal, non-retryable decryption failure (missing or
     # rotated-away key, tampered ciphertext). The server middleware raises
     # JobRetry::Skip after routing the job to the dead set, so this class
@@ -88,16 +95,20 @@ module Wurk
       # keys for any older in-flight versions so they decrypt.
       #
       # Idempotent: re-calling rebinds the resolver and rebuilds the cache.
-      # Middleware is installed at most once per chain.
-      def enable(active_version:, &resolver)
+      # Middleware is installed at most once per chain. `config` selects the
+      # chains and capsules to check, not a separate crypto context: enabled
+      # state, active version, resolver and key cache remain process-global.
+      def enable(config = Wurk.configuration, active_version:, &resolver)
         raise ArgumentError, 'active_version is required' unless active_version
         raise ArgumentError, 'block returning the key bytes is required' unless resolver
 
+        refuse_unreachable_enablement!(config)
+
         @active_version = Integer(active_version)
         @resolver = resolver
         @key_cache = {}
         @enabled = true
-        register_middleware!
+        register_middleware!(config)
         true
       end
 
@@ -223,6 +234,34 @@ module Wurk
 
       private
 
+      # The client middleware chain is live: a middleware registered on the
+      # Configuration is picked up by the very next push. The server chain is
+      # a snapshot — a capsule that has been prepared to run jobs holds the
+      # copy its workers run, and a middleware registered after that copy was
+      # taken can never reach it. Enabling crypto then would seal arguments
+      # the workers cannot open, so the enablement is refused before any
+      # state changes: `enabled?` stays false and the client middleware keeps
+      # the last argument in cleartext.
+      #
+      # The guard is per-process: it sees this process's capsules only. A
+      # producer in another process that enabled crypto while some worker
+      # never enabled it at all is a different misconfiguration — enable
+      # everywhere, not just on workers.
+      def refuse_unreachable_enablement!(config)
+        unreachable = config.capsules.values.select do |capsule|
+          capsule.prepared? && capsule.server_middleware_missing?(ServerMiddleware)
+        end
+        return if unreachable.empty?
+
+        raise UnsafeEnablementError, <<~MSG
+          Wurk::Encryption.enable was called too late to reach the workers: the #{unreachable.map(&:name).join(', ')} \
+          capsule(s) already hold the server middleware chain their workers run, and that chain cannot \
+          receive Wurk::Encryption::ServerMiddleware — the workers would execute encrypted jobs without the \
+          decryptor and hand `perform` the raw envelope. Enable crypto before the worker boots — in a \
+          config/initializers file, not an after_initialize hook — then restart the workers.
+        MSG
+      end
+
       def build_decrypt_cipher(envelope, key)
         cipher = ::OpenSSL::Cipher.new(CIPHER_NAME).decrypt
         cipher.key = key
@@ -252,11 +291,11 @@ module Wurk
         bytes
       end
 
-      def register_middleware!
-        Wurk.configuration.client_middleware.add(ClientMiddleware) \
-          unless Wurk.configuration.client_middleware.exists?(ClientMiddleware)
-        Wurk.configuration.server_middleware.add(ServerMiddleware) \
-          unless Wurk.configuration.server_middleware.exists?(ServerMiddleware)
+      def register_middleware!(config)
+        client_chain = config.client_middleware
+        server_chain = config.server_middleware
+        client_chain.add(ClientMiddleware) unless client_chain.exists?(ClientMiddleware)
+        server_chain.add(ServerMiddleware) unless server_chain.exists?(ServerMiddleware)
       end
     end
 

data/lib/wurk/fetcher/private_list_key.rb

@@ -9,6 +9,9 @@ module Wurk
     # Reliable.private_queue_name) for the Reaper's liveness check. Pure string
     # work, no Redis.
     module PrivateListKey
+      # The nonce shape Component::PROCESS_NONCE writes (`SecureRandom.hex(6)`).
+      NONCE_PATTERN = /\A[0-9a-f]{12}\z/
+
       module_function
 
       # `queue:<public>|<host>|<pid>|<nonce>|<idx>` → [public_q, host, pid,
@@ -19,7 +22,11 @@ module Wurk
       # preference order and the first one leaving a real public queue behind
       # wins. The narrow reading is what saves a pre-nonce key from an all-digit
       # host (`queue:q|123456789012|<pid>|<idx>` — a bare Docker hostname is 12
-      # hex chars): read wide, its host segment eats the whole queue name.
+      # hex chars): read wide, its host segment either eats the whole queue
+      # name (plain queue — nothing left over) or truncates it at the first
+      # pipe and puts the real pid in the nonce slot (pipe-bearing queue).
+      # Both misreads are refused: the leftover must be a real queue name and
+      # the pseudo-nonce must be nonce-shaped (see wide_tail).
       def parse_full(key)
         parts = key.split('|')
         owner_tails(parts).each do |host, pid, nonce, width|
@@ -57,8 +64,14 @@ module Wurk
       end
 
       # `<host>|<pid>|<nonce>|<idx>` — the shape every current process writes.
+      # The nonce slot must carry PROCESS_NONCE's exact shape (NONCE_PATTERN):
+      # on a pre-nonce key read wide it holds the real pid, which is never 12
+      # hex, so the guard is what falls such a key through to narrow_tail
+      # instead of misreading it. Guarded here rather than in parse_full
+      # because parse_owner reads through owner_tails too — one guard, and the
+      # two parsers agree on every input.
       def wide_tail(parts)
-        [parts[-4], parts[-3].to_i, parts[-2], 4] if parts.size >= 4 && integer?(parts[-3])
+        [parts[-4], parts[-3].to_i, parts[-2], 4] if parts.size >= 4 && integer?(parts[-3]) && nonce?(parts[-2])
       end
 
       # `<host>|<pid>|<idx>` — written before the nonce existed. Such a list can
@@ -71,6 +84,10 @@ module Wurk
       def integer?(str)
         str.is_a?(String) && str.match?(/\A\d+\z/)
       end
+
+      def nonce?(str)
+        str.is_a?(String) && str.match?(NONCE_PATTERN)
+      end
     end
   end
 end

data/lib/wurk/fetcher/reaper.rb

@@ -23,15 +23,15 @@ module Wurk
     # Liveness is decided per owner:
     #   * our own host and nonce — the pid was minted in our PID namespace, so
     #     the OS is authoritative: `Process.kill(0, pid)`. This is instant and
-    #     ignores a stale `processes` SET entry whose 60s TTL hasn't lapsed
-    #     yet, so a `kill -9`ed sibling is reclaimed the moment the supervisor
-    #     reaps it rather than 60s later. (Pid reuse by an unrelated process in
-    #     the same tree is the one blind spot — the supervisor respawns with a
-    #     fresh pid, so it does not arise in practice.)
+    #     ignores a stale `processes` SET member — the SET carries no TTL, so
+    #     the member lingers after its heartbeat hash expires (60s) until
+    #     `ProcessSet#cleanup` prunes it. A `kill -9`ed sibling is reclaimed
+    #     the moment the supervisor reaps it, not 60s later. (Pid reuse by an
+    #     unrelated process in the same tree is the one blind spot — the
+    #     supervisor respawns with a fresh pid, so it does not arise in practice.)
     #   * any other incarnation — its pid means nothing in our namespace, so we
-    #     trust the heartbeat: the owner is alive iff its identity is a live
-    #     `processes` member (one whose `info` hash still exists). Such reclaim
-    #     therefore waits out the 60s heartbeat TTL, exactly as the spec says.
+    #     trust the heartbeat: the owner is alive iff its identity's `info`
+    #     hash still exists. Such reclaim waits out the 60s heartbeat TTL.
     #
     # The heartbeat verdict is a snapshot taken before a SCAN that can run for
     # a long time on a big keyspace, and a booting process can claim jobs a
@@ -128,7 +128,10 @@ module Wurk
       # this component exists to recover from. A straggler is left running
       # instead — and still referenced, like every other periodic component, so
       # a restart after a timed-out stop can't spawn a second sweep loop
-      # alongside it. Its own tick_once rescues and reports.
+      # alongside it. The sweep honours @done at its queue/list/page
+      # boundaries, so a straggler runs at most one more Redis round trip past
+      # the stop, not the rest of the keyspace. Its own tick_once rescues and
+      # reports.
       def stop
         @mutex.synchronize do
           @done = true
@@ -153,9 +156,21 @@ module Wurk
       # One unguarded sweep over every served queue. Returns the number of
       # jobs reclaimed (re-queued or killed). Public so boot paths and tests
       # can drive a deterministic pass without the cluster lock.
+      #
+      # Honours #stop at each boundary: a stop bounding its join leaves the
+      # sweep a straggler by design, and the straggler finishes the list it is
+      # already draining (its LMOVEs stay applied) but starts nothing new —
+      # otherwise it keeps requeueing orphans and holding the sweep locks
+      # past the stop, into whatever runs next.
       def reclaim!
         owners = live_owners
-        served_queues.sum { |public_q| reclaim_queue(public_q, owners) }
+        reclaimed = 0
+        served_queues.each do |public_q|
+          break if done?
+
+          reclaimed += reclaim_queue(public_q, owners)
+        end
+        reclaimed
       end
 
       # One unguarded full-keyspace sweep: every `queue:*|*` private list, even
@@ -166,6 +181,7 @@ module Wurk
         owners = live_owners
         reclaimed = 0
         each_full_private_list do |key, public_q, host, pid, nonce|
+          break if done?
           next unless orphaned?(key, host, pid, nonce, owners)
 
           reclaimed += drain(key, public_q)
@@ -189,6 +205,7 @@ module Wurk
       def reclaim_queue(public_q, owners)
         reclaimed = 0
         each_private_list(public_q) do |key, host, pid, nonce|
+          break if done?
           next unless orphaned?(key, host, pid, nonce, owners)
 
           reclaimed += drain(key, public_q)
@@ -202,6 +219,8 @@ module Wurk
       def each_private_list(public_q)
         cursor = '0'
         loop do
+          break if done?
+
           cursor, keys = redis(idempotent: true) do |c|
             c.call('SCAN', cursor, 'MATCH', "#{public_q}|*", 'COUNT', SCAN_COUNT)
           end
@@ -220,6 +239,8 @@ module Wurk
       def each_full_private_list
         cursor = '0'
         loop do
+          break if done?
+
           cursor, keys = redis(idempotent: true) do |c|
             c.call('SCAN', cursor, 'MATCH', "#{Keys::QUEUE_PREFIX}*|*", 'COUNT', FULL_SCAN_COUNT)
           end
@@ -245,8 +266,11 @@ module Wurk
       # The nonce settles it: minted once per process image and inherited across
       # fork, so a key carrying ours provably came from this very process tree.
       # Every other owner goes through the namespace-blind heartbeat — alive iff
-      # its identity is a live `processes` member. A pre-nonce key can only be
-      # matched on the `<host>:<pid>` prefix of that identity.
+      # its identity's `info` hash still exists. `processes` membership is not
+      # liveness: the SET carries no TTL, so a member outlives the hash that
+      # proves it alive, and a nonce-bearing identity is alive on its hash
+      # alone even once it has been pruned from the SET. A pre-nonce key can
+      # only be matched on the `<host>:<pid>` prefix of that identity.
       def orphaned?(key, host, pid, nonce, owners)
         return !local_pid_alive?(pid) if nonce == process_nonce && host == hostname
         return false if owners.include?(owner_key(host, pid, nonce))

data/lib/wurk/fetcher/unparseable_keys.rb

@@ -5,10 +5,21 @@ require_relative '../keys'
 module Wurk
   class Fetcher
     # The Reaper's report on a `queue:*|*` key that is not a private list it
-    # can read the owner of — a Sidekiq Pro super_fetch list in a shape Wurk
-    # does not write, say, left behind by a live migration. Nothing will ever
-    # reclaim its jobs, so it is said once per key per process (WARN, with the
-    # list's length) rather than skipped in silence on every sweep.
+    # can read the owner of — a list whose owner tail does not parse, say
+    # `queue:<queue>|<host>|not-a-pid|<index>`, left behind by a producer that
+    # is not Wurk. Sidekiq Pro's four-part shape
+    # (`queue:<queue>|<host>|<pid>|<index>`) parses as the pre-nonce tail and
+    # is reclaimed, so Pro's lists are not reported. Nothing will ever reclaim
+    # the jobs of an unparseable list, so it is said once per key per process
+    # (WARN, with the list's length) rather than skipped in silence on every
+    # sweep.
+    #
+    # The dedup memory is an in-memory ::Set in THIS process only: one
+    # UnparseableKeys per Reaper, one Reaper per Launcher, one Launcher per
+    # worker process, all of them built after the fork. Nothing about it
+    # reaches Redis — no key, no TTL, nothing shared — so there is no
+    # fleet-wide suppression: every worker that sweeps the key logs it for
+    # itself, and a restart starts with an empty set and reports it again.
     #
     # A public queue whose own name contains `|` matches the same SCAN pattern,
     # so a key whose name is in the `queues` SET is not reported.
@@ -32,9 +43,13 @@ module Wurk
         @reported.clear if @reported.size >= MEMORY
         @reported << key
         @config.logger.warn do
-          "reaper: #{key.inspect} looks like a reliable-fetch private list but does not match " \
-            "queue:<queue>|<host>|<pid>|<nonce>|<index>; its #{size} job(s) will not be recovered " \
-            'automatically. Inspect it and LMOVE them back onto their queue by hand if they belong to a dead process.'
+          "reaper: #{key.inspect} looks like a reliable-fetch private list but matches neither " \
+            'queue:<queue>|<host>|<pid>|<nonce>|<index> nor the pre-nonce ' \
+            "queue:<queue>|<host>|<pid>|<index>; its #{size} job(s) will not be recovered " \
+            'automatically. Inspect it and LMOVE them back onto their queue by hand ' \
+            'if they belong to a dead process. ' \
+            'Reported once per process: every worker that sees the key logs it for itself, ' \
+            'and it is reported again after a restart.'
         end
       rescue StandardError => e
         @config.handle_exception(e, context: 'wurk-reaper')

data/lib/wurk/fetcher.rb

@@ -5,7 +5,12 @@ module Wurk
   # we ship and the only one we recommend — BLMOVE-based reliable fetch.
   # No "basic fetch" mode.
   class Fetcher
-    def retrieve_work; end
+    # Instant nil spins Processor#run, which immediately fetches again. Concrete
+    # implementations must block or back off before returning nil when empty.
+    def retrieve_work
+      raise NotImplementedError, "#{self.class} must override #retrieve_work and block or back off when empty"
+    end
+
     def bulk_requeue(in_progress); end
 
     # Quiet hook: Manager#quiet calls this so retrieve_work can short-circuit

data/lib/wurk/health.rb

@@ -6,7 +6,11 @@ require_relative 'metrics/prometheus'
 
 module Wurk
   # Thin HTTP listener for k8s liveness/readiness probes. Optional, off by
-  # default — opt in with `config.health_check(port: 7433)`.
+  # default — opt in with `config.health_check(port: 7433)`, then scrape
+  # GET /metrics on that configured port (7433 in this example).
+  # Mounting Wurk::Engine does not expose Prometheus metrics: this deliberate
+  # separation keeps internal metrics off the host application's HTTP surface
+  # so access can be restricted independently on the dedicated listener port.
   #
   # Endpoints:
   #   * GET /live  → 200 while the Launcher is running (not in quiet/stop).

data/lib/wurk/job_logger.rb

@@ -69,7 +69,7 @@ module Wurk
     private
 
     def elapsed(start)
-      (::Process.clock_gettime(::Process::CLOCK_MONOTONIC) - start).round(3)
+      ((::Process.clock_gettime(::Process::CLOCK_MONOTONIC) - start) * 1000).round(3)
     end
 
     # The attribute list is a host setting (defaults to %w[bid tags]), so the

data/lib/wurk/job_util.rb

@@ -152,6 +152,9 @@ module Wurk
     def valid_at?(item) = !item.key?('at') || item['at'].is_a?(Numeric)
     def valid_tags?(item) = !item.key?('tags') || item['tags'].is_a?(Array)
 
+    # The cap binds the COERCED value, not the raw one: 1_000_000_000.7 is
+    # valid and stores as 1_000_000_000 (§2.2 / §9: over 1_000_000_000 after
+    # coercion rejected; exactly 1_000_000_000 is valid).
     def valid_retry_for?(item)
       return true unless item.key?('retry_for')
 
@@ -165,7 +168,7 @@ module Wurk
     def numeric_retry_for(value)
       case value
       when Integer then value
-      when Numeric then value.to_i
+      when Numeric then (value.to_i if value.finite? && value.real?)
       when String then (Integer(value, 10) if value.match?(/\A-?\d+\z/))
       end
     end

data/lib/wurk/launcher.rb

@@ -118,7 +118,7 @@ module Wurk
       @done = true
       @managers.each(&:quiet)
       @poller&.terminate
-      # The cron poller is intentionally NOT terminated here: a USR1-quieted
+      # The cron poller is intentionally NOT terminated here: a TSTP-quieted
       # leader still enqueues periodic jobs — it only stops fetching for itself.
       # Loops stop only on full shutdown (#stop). Spec: sidekiq-ent.md §2.6.
       fire_event(:quiet, reverse: true)
@@ -379,8 +379,9 @@ module Wurk
     # a *quieted* process keeps beating so it publishes `quiet=true` instead of
     # vanishing (#236). Each tick is rescued on its own — a raise escaping one
     # beat (a signal re-delivery the kernel refuses, a hook) would otherwise end
-    # the thread, and a process that stops beating expires out of `processes`
-    # while still running jobs, which the reaper then reclaims.
+    # the thread, and a process that stops beating is still running jobs but
+    # stops being LIVE: its heartbeat hash lapses (60s TTL), so the reaper
+    # reclaims its jobs, and cleanup prunes its stale `processes` entry.
     def start_heartbeat
       @beat_timer.run do
         heartbeat

data/lib/wurk/lua.rb

@@ -4,7 +4,7 @@ require 'digest'
 
 module Wurk
   # EVALSHA-cached Lua scripts. Loaded once per pool, never re-uploaded.
-  # Bulk enqueue, multi-pop, atomic schedule promotion, batch ops.
+  # Multi-pop, atomic schedule promotion, batch ops.
   #
   # Source strings are intentionally bare — the SHA1 of each is computed
   # at load time and is the same value Redis reports from `SCRIPT LOAD`.
@@ -24,18 +24,6 @@ module Wurk
       end
     LUA
 
-    # Bulk enqueue to a single queue.
-    # KEYS = [queue_list, queues_set]
-    # ARGV = [queue_name, job_json, ...]
-    # Returns the number of jobs pushed.
-    BULK_PUSH = <<~LUA
-      redis.call("sadd", KEYS[2], ARGV[1])
-      for i = 2, #ARGV do
-        redis.call("lpush", KEYS[1], ARGV[i])
-      end
-      return #ARGV - 1
-    LUA
-
     # Pro reliable scheduler: atomically promote all due jobs in a sorted
     # set to their target queues. Pure-Ruby promotion does ZRANGE → ZREM →
     # LPUSH non-atomically and can lose jobs on a mid-step crash.
@@ -224,7 +212,6 @@ module Wurk
 
     SCRIPTS = {
       zpopbyscore: ZPOPBYSCORE,
-      bulk_push: BULK_PUSH,
       reliable_schedule_promote: RELIABLE_SCHEDULE_PROMOTE,
       reliable_requeue: RELIABLE_REQUEUE,
       fast_delete_job: FAST_DELETE_JOB,

data/lib/wurk/metrics/dashboard_series.rb

@@ -64,12 +64,31 @@ module Wurk
       # Bucket start times oldest→newest and their keys: one per minute for
       # `minutes`, one per 10 minutes for `hours` (which wins when both given).
       def window_buckets(minutes, hours, now)
-        stride, keyproc = Query::ROLLUPS.fetch(hours ? :hourly : :minutely)
-        count = hours ? cap_hours!(hours) * 6 : cap_minutes!(minutes)
+        minutes, buckets = promote_minute_window(minutes, hours)
+        stride, keyproc = Query::ROLLUPS.fetch(buckets ? :hourly : :minutely)
+        count = buckets || cap_minutes!(minutes)
         stamps = bucket_starts(now, stride, count * stride).map { |s| ::Time.at(s).utc }
         [stamps, stamps.map(&keyproc)]
       end
 
+      # 10-minute bucket counts for the requested window — nil stays on the
+      # per-minute buckets. An explicit `hours:` is six buckets per hour
+      # (cap_hours! still bounds it). A minute window past MAX_MINUTES
+      # promotes onto the 10-minute buckets (whose 30-day retention covers
+      # it) instead of raising; it still WindowTooWides past MAX_HOURS * 60
+      # minutes — checked in minutes first so the error names the unit the
+      # caller passed. The promoted window is counted in 10-minute buckets,
+      # ceil(minutes / 10), not rounded up to whole hours (#726): 490 minutes
+      # is 49 buckets, not 9 hours' 54, so the totals never reach past the
+      # window the caller asked for by more than the trailing partial bucket.
+      def promote_minute_window(minutes, hours)
+        return [minutes, cap_hours!(hours) * 6] unless hours.nil?
+        return [minutes, nil] unless minutes && minutes > Query::MAX_MINUTES
+
+        checked = check_window!(Integer(minutes), Query::MAX_HOURS * 60, 'minutes')
+        [nil, (checked / 10.0).ceil]
+      end
+
       def sum_totals(hashes)
         totals = ::Hash.new { |h, k| h[k] = { p: 0, f: 0, ms: 0 } }
         hashes.each do |raw|

data/lib/wurk/metrics/history.rb

@@ -14,7 +14,7 @@ module Wurk
     # reads what Wurk wrote (spec: docs/target/sidekiq-free.md §1.6, §20).
     #
     #   j|YYMMDD|H:MM   HASH  per-minute bucket, TTL = SHORT_TERM (8h)
-    #   j|YYMMDD|H:M    HASH  10-minute bucket (minute's tens digit), TTL = MID_TERM (3d)
+    #   j|YYMMDD|H:M    HASH  10-minute bucket (minute's tens digit), TTL = MID_TERM (30d)
     #     <klass>|p     INT   executions, failures included
     #     <klass>|f     INT   failures
     #     <klass>|ms    INT   total ms of the executions that did not fail
@@ -32,8 +32,11 @@ module Wurk
     class History
       include Wurk::Middleware::ServerMiddleware
 
-      # Upstream's ExecutionTracker constants, same names.
-      MID_TERM = 3 * 24 * 60 * 60
+      # Upstream's ExecutionTracker constants, same names. MID_TERM diverges:
+      # upstream TTLs the 10-minute buckets at 3 days, but Wurk's dashboard
+      # serves 7d/30d tabs off them (Query::MAX_HOURS = 720), so they must
+      # live 30 days. Longer retention changes no key, field, or score.
+      MID_TERM = 30 * 24 * 60 * 60
       SHORT_TERM = 8 * 60 * 60
 
       MINUTE_KEY_FORMAT = 'j|%y%m%d|%-H:%M'
@@ -62,7 +65,10 @@ module Wurk
         rescue Wurk::Job::Interrupted, Wurk::Job::DeadlineExceeded
           # Neither is the job failing. A cooperative interruption is not a
           # failure: InterruptHandler self-prepends, so it sits *outside* this
-          # middleware, Interrupted passes through here before it becomes a
+          # middleware (registered by
+          # `Wurk.configuration.server_middleware.prepend(Wurk::Middleware::InterruptHandler)`
+          # in lib/wurk/middleware/interrupt_handler.rb:50); Interrupted passes
+          # through here before it becomes a
           # JobRetry::Skip, and without this arm one interrupted IterableJob
           # books a spurious `<klass>|f` (#394). Upstream's
           # ExecutionTracker#track books `p` + `ms` for that Skip and reserves
@@ -72,7 +78,9 @@ module Wurk
           # docs/plans/2026/08/07/101-beyond-sidekiq/00-semantics-signoff.md §1.
           #
           # A job cut by its absolute deadline lands in the same bucket for a
-          # plainer reason: Middleware::Expiry, also outside this one, catches
+          # plainer reason: Middleware::Expiry, also outside this one (registered
+          # by `Wurk.configuration.server_middleware.add(Wurk::Middleware::Expiry)`
+          # in lib/wurk/middleware/expiry.rb:111), catches
           # that raise and books the job `expired`. Booking `f` here too would
           # put one abandoned job in two of the three counts an operator
           # subtracts (executed = processed - failed - expired), and would make

data/lib/wurk/metrics/query.rb

@@ -20,7 +20,11 @@ module Wurk
     # dashboard JSON API.
     class Query
       MAX_MINUTES = 480
-      MAX_HOURS = 72
+      # Class-level dashboard cap: the 10-minute buckets live MID_TERM
+      # (30 days), so a 720-hour window is fully backed by data. The
+      # instance-side clamp below keeps upstream's 72h cap — Sidekiq parity
+      # is pinned by test/parity/metrics_query_test.rb.
+      MAX_HOURS = 720
       MAX_QUEUE_SERIES = 25
 
       class WindowTooWide < ::ArgumentError; end
@@ -129,10 +133,13 @@ module Wurk
 
       # Upstream's DoS caps: an oversized minute window falls back to the
       # 60-minute default, an oversized hour window to the 72h ceiling.
+      # The 72 is upstream's literal, not MAX_HOURS: the class-level cap
+      # moved to 720 with the 30-day bucket retention, but this Sidekiq-
+      # compatible instance API must keep clamping at 72h.
       def clamp(minutes, hours)
         minutes = 60 unless minutes || hours
         minutes = 60 if minutes && minutes > MAX_MINUTES
-        [minutes, hours && [hours, MAX_HOURS].min]
+        [minutes, hours && [hours, 72].min]
       end
 
       def add_bucket(result, time, hash, class_filter)