wurk 0.0.5 → 1.0.0

data/lib/wurk/fetcher/reaper.rb

@@ -33,10 +33,16 @@ module Wurk
     # is killed into the dead set instead of re-queued, so a job that crashes
     # its worker every time can't loop forever.
     #
-    # SCANs are scoped to the public queues this process serves and gated by
-    # a cluster-wide `SET NX EX` lock, so across a fleet only one process
-    # sweeps per interval ("1/min within process group" in the spec) and the
-    # keyspace touched is bounded to known queues.
+    # The reaper runs two passes, exactly as super_fetch's sweeper does:
+    #
+    #   * a *scoped* sweep every interval ("1/min within process group"): SCANs
+    #     only the public queues this process serves, gated by a cluster `SET NX
+    #     EX` lock so one process sweeps per interval. The cheap common path.
+    #   * a *full* sweep at most once an hour ("full SCAN 1/hr"): SCANs the whole
+    #     `queue:*|*` keyspace, gated by its own hourly lock, so private lists
+    #     whose public queue no live process serves — a renamed/decommissioned
+    #     queue, or a dead host's queue no survivor consumes — are recovered too,
+    #     not stranded forever.
     #
     # Spec: docs/target/sidekiq-pro.md §3.2.
     class Reaper
@@ -47,16 +53,24 @@ module Wurk
       # floor below which cross-host orphans can't be detected anyway.
       DEFAULT_INTERVAL = 60
 
+      # Full-keyspace sweep cadence + its lock TTL: at most once per hour across
+      # the fleet, since a global SCAN is far costlier than the scoped pass.
+      FULL_INTERVAL = 3600
+
       LOCK_KEY = 'super_fetch:reaper'
+      FULL_LOCK_KEY = 'super_fetch:reaper:full'
       SCAN_COUNT = 100
       THREAD_NAME = 'wurk-reaper'
 
       attr_reader :interval
 
-      def initialize(config, interval: DEFAULT_INTERVAL, lock_key: LOCK_KEY)
+      def initialize(config, interval: DEFAULT_INTERVAL, lock_key: LOCK_KEY,
+                     full_interval: FULL_INTERVAL, full_lock_key: FULL_LOCK_KEY)
         @config = config
         @interval = interval
         @lock_key = lock_key
+        @full_interval = full_interval
+        @full_lock_key = full_lock_key
         @thread = nil
         @done = false
         @mutex = ::Mutex.new
@@ -89,12 +103,13 @@ module Wurk
         !@thread.nil? && @thread.alive?
       end
 
-      # One cluster-gated sweep: a no-op (returns 0) unless this process wins
-      # the interval's lock. Used by the loop.
+      # One loop tick: the scoped sweep when this process wins the per-interval
+      # lock, plus the full-keyspace sweep when it also wins the hourly lock.
+      # Returns the total jobs reclaimed across both.
       def reap
-        return 0 unless acquire_lock?
-
-        reclaim!
+        reclaimed = acquire_lock? ? reclaim! : 0
+        reclaimed += reclaim_full! if acquire_full_lock?
+        reclaimed
       end
 
       # One unguarded sweep over every served queue. Returns the number of
@@ -105,6 +120,21 @@ module Wurk
         served_queues.sum { |public_q| reclaim_queue(public_q, prefixes) }
       end
 
+      # One unguarded full-keyspace sweep: every `queue:*|*` private list, even
+      # ones whose public queue this process doesn't serve. Returns the number
+      # of jobs reclaimed. Public so boot paths and tests can drive it without
+      # the hourly lock.
+      def reclaim_full!
+        prefixes = live_process_prefixes
+        reclaimed = 0
+        each_full_private_list do |key, public_q, host, pid|
+          next if owner_alive?(host, pid, prefixes)
+
+          reclaimed += drain(key, public_q)
+        end
+        reclaimed
+      end
+
       private
 
       # Union of `queue:<name>` keys across every capsule this process serves.
@@ -143,6 +173,39 @@ module Wurk
         end
       end
 
+      # Yields [private_list_key, public_q, host, pid] for every private list in
+      # the keyspace. MATCH `queue:*|*` matches only private lists (public queue
+      # keys carry no `|`); parse_full_key drops anything that isn't a
+      # well-formed `queue:<public>|<host>|<pid>|<idx>`.
+      def each_full_private_list
+        cursor = '0'
+        loop do
+          cursor, keys = redis { |c| c.call('SCAN', cursor, 'MATCH', "#{Keys::QUEUE_PREFIX}*|*", 'COUNT', SCAN_COUNT) }
+          keys.each do |key|
+            parsed = parse_full_key(key)
+            yield key, *parsed if parsed
+          end
+          break if cursor == '0'
+        end
+      end
+
+      # `queue:<public>|<host>|<pid>|<idx>` → [public_q, host, pid], parsed from
+      # the right (pid + idx are integers, host precedes them) so a `|` inside
+      # the queue name is tolerated. nil when the key isn't a well-formed
+      # private list.
+      def parse_full_key(key)
+        parts = key.split('|')
+        return nil if parts.size < 4
+
+        host, pid, idx = parts.last(3)
+        return nil unless integer?(pid) && integer?(idx)
+
+        public_q = parts[0...-3].join('|')
+        return nil unless public_q.start_with?(Keys::QUEUE_PREFIX) && public_q != Keys::QUEUE_PREFIX
+
+        [public_q, host, pid.to_i]
+      end
+
       # `<public_q>|<host>|<pid>|<idx>` → [host, pid] (pid as Integer), or
       # [nil, nil] when the suffix isn't a well-formed `host|pid|idx` triple.
       # Splitting the suffix off the known public-queue prefix tolerates a
@@ -219,7 +282,7 @@ module Wurk
       end
 
       def poison_off(public_q, job, queue_name)
-        return unless Middleware::PoisonPill.track!(job, queue: queue_name) == :poison
+        return unless Middleware::PoisonPill.track!(job, queue: queue_name, config: @config) == :poison
 
         # track! already ZADDed the payload to the dead set; pull the copy we
         # just LMOVE'd onto the public tail so it isn't also re-run.
@@ -230,6 +293,10 @@ module Wurk
         redis { |c| c.call('SET', @lock_key, '1', 'NX', 'EX', @interval) } == 'OK'
       end
 
+      def acquire_full_lock?
+        redis { |c| c.call('SET', @full_lock_key, '1', 'NX', 'EX', @full_interval) } == 'OK'
+      end
+
       def spawn_loop_thread
         t = Thread.new { run_loop }
         t.name = THREAD_NAME

data/lib/wurk/fetcher/reliable.rb

@@ -15,15 +15,18 @@ module Wurk
     # next boot of this process reclaims it via bulk_requeue.
     #
     # Priority handling: iterate queues_cmd in order with non-blocking
-    # LMOVE, then fall back to a 2s BLMOVE on the first queue so an
+    # LMOVE, then fall back to a blocking BLMOVE on the first queue so an
     # empty poll doesn't spin Redis. BLMOVE has no multi-key form, so
-    # blocking on a single queue is the best Redis gives us.
+    # blocking on a single queue is the best Redis gives us. The block
+    # timeout defaults to TIMEOUT (2s) and is overridable per the Pro
+    # super_fetch §3.3 `config.fetch_poll_interval` knob.
     #
-    # Spec: docs/target/sidekiq-pro.md §3 (super_fetch),
+    # Spec: docs/target/sidekiq-pro.md §3 (super_fetch, §3.3 poll interval),
     # docs/target/sidekiq-free.md §15 (TIMEOUT=2).
     class Reliable < Fetcher
       include Component
 
+      # Default BLMOVE block timeout; overridable via config.fetch_poll_interval.
       TIMEOUT = 2
 
       # Carries the public queue key, the raw (still-JSON) job payload,
@@ -126,13 +129,20 @@ module Wurk
 
       def blmove(public_q)
         priv = self.class.private_queue_name(public_q)
+        timeout = poll_interval
         # Extend the socket read-timeout past BLMOVE's own timeout so the
         # default 1s pool timeout doesn't fire before BLMOVE returns.
         job = config.redis do |conn|
-          conn.blocking_call(TIMEOUT + 1, 'BLMOVE', public_q, priv, 'RIGHT', 'LEFT', TIMEOUT)
+          conn.blocking_call(timeout + 1, 'BLMOVE', public_q, priv, 'RIGHT', 'LEFT', timeout)
         end
         job ? UnitOfWork.new(queue: public_q, job: job, config: config) : nil
       end
+
+      # BLMOVE block timeout for an empty poll. `config.fetch_poll_interval`
+      # (Pro super_fetch §3.3) overrides the TIMEOUT default; nil → TIMEOUT.
+      def poll_interval
+        config.fetch_poll_interval || TIMEOUT
+      end
     end
   end
 end

data/lib/wurk/heartbeat.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'etc'
+
 require_relative 'component'
 require_relative 'keys'
 require_relative 'processor'
@@ -151,9 +153,52 @@ module Wurk
         'identity' => @identity,
         'version' => Wurk::VERSION,
         'embedded' => @embedded
+      }.merge(host_facts)
+    end
+
+    # Static hardware facts for the Busy page's per-host grouping. Additive
+    # `info` fields only — Sidekiq Web ignores keys it doesn't know, so the
+    # drop-in wire contract holds. Best-effort: nil/0 when the platform has
+    # no readable source (the dashboard renders a dash).
+    def host_facts
+      @host_facts ||= {
+        'cpu_model' => cpu_model,
+        'cores' => cores,
+        'memory_total_kb' => memory_total_kb
       }
     end
 
+    def cores(etc = Etc)
+      etc.nprocessors
+    # NotImplementedError is a ScriptError, outside StandardError — and it's
+    # exactly what Etc raises on platforms without sysconf.
+    rescue StandardError, NotImplementedError
+      nil
+    end
+
+    def cpu_model
+      if ::File.exist?('/proc/cpuinfo')
+        line = ::File.foreach('/proc/cpuinfo').find { |l| l.start_with?('model name') }
+        line&.split(':', 2)&.last&.strip
+      else
+        model = `sysctl -n machdep.cpu.brand_string 2>/dev/null`.strip
+        model.empty? ? nil : model
+      end
+    rescue StandardError
+      nil
+    end
+
+    def memory_total_kb
+      if ::File.exist?('/proc/meminfo')
+        line = ::File.foreach('/proc/meminfo').find { |l| l.start_with?('MemTotal') }
+        line.to_s[/\d+/].to_i
+      else
+        `sysctl -n hw.memsize 2>/dev/null`.to_i / 1024
+      end
+    rescue StandardError
+      0
+    end
+
     def capsules_info
       @config.capsules.transform_values do |cap|
         { 'concurrency' => cap.concurrency, 'mode' => cap.mode.to_s, 'weights' => cap.weights }

data/lib/wurk/history.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require_relative 'component'
+require_relative 'keys'
+require_relative 'stats'
+require_relative 'metrics/statsd'
+
+module Wurk
+  # Sidekiq Enterprise §5 Historical Metrics snapshotter. A leader-gated
+  # background thread that, every `config.retain_history` seconds, emits a
+  # statsd-shaped snapshot to the configured dogstatsd client — either the
+  # default §5.2 gauge set or a user-supplied collector block.
+  #
+  # Configured in a server block:
+  #
+  #   Sidekiq.configure_server do |config|
+  #     config.dogstatsd = -> { Datadog::Statsd.new('localhost', 8125) }
+  #     config.retain_history(30)                      # default §5.2 gauges
+  #     # …or a custom collector:
+  #     config.retain_history(30) do |s|
+  #       Sidekiq::Queue.all.each do |q|
+  #         s.gauge("sidekiq.queue.size", q.size, tags: ["queue:#{q.name}"])
+  #       end
+  #     end
+  #   end
+  #
+  # The block receives the raw dogstatsd client `s` (quacks like
+  # `Datadog::Statsd`: gauge/count/histogram/batch) and writes fully-qualified
+  # `sidekiq.*` metric names itself, matching Sidekiq Ent. Leader-gated via the
+  # cluster `dear-leader` lock so exactly one process emits per cluster.
+  #
+  # Every snapshot is also appended to the capped Redis stream
+  # `history:metrics` (§5.3) — the same key a migrated Sidekiq Ent install
+  # uses — so the dashboard's Historical view has a data source independent of
+  # any external statsd, and pre-existing Ent stream data renders without
+  # rewrite. The stream write happens whenever the snapshotter runs; the
+  # dogstatsd emit is skipped only when no client is configured.
+  #
+  # Aliased as `Sidekiq::History` (drop-in contract).
+  # Spec: docs/target/sidekiq-ent.md §5.1–§5.3.
+  class History
+    include Component
+
+    # Stream field → Stats reader. Single source for both the `history:metrics`
+    # stream entry and the default §5.2 statsd gauge set (which prefixes
+    # `sidekiq.`). Order is the display order.
+    SNAPSHOT_FIELDS = {
+      'processed' => :processed,
+      'failures' => :failed,
+      'enqueued' => :enqueued,
+      'retries' => :retry_size,
+      'dead' => :dead_size,
+      'scheduled' => :scheduled_size,
+      'busy' => :workers_size
+    }.freeze
+
+    # Approximate cap on retained snapshots (XADD MAXLEN ~). At the default 30s
+    # interval this is ~3.5 days of history; older points age out. `~` lets
+    # Redis trim in whole macro-nodes, so the actual length can briefly exceed
+    # the cap — matching Ent's best-effort retention.
+    STREAM_CAP = 10_000
+    STREAM_DEFAULT_LIMIT = 1000
+
+    def initialize(config)
+      @config = config
+      @interval = config.history_interval
+      @collector = config.history_collector
+      @stream_cap = config[:history_stream_cap] || STREAM_CAP
+      @done = false
+      @mutex = ::Mutex.new
+      @sleeper = ::ConditionVariable.new
+      @thread = nil
+    end
+
+    def start
+      @thread ||= safe_thread('history-snapshot') do # rubocop:disable Naming/MemoizedInstanceVariableName
+        wait
+        until @done
+          tick
+          wait
+        end
+      end
+    end
+
+    def terminate
+      @mutex.synchronize do
+        @done = true
+        @sleeper.signal
+      end
+    end
+
+    # Leader-gated: only the elected leader emits, so N workers don't each
+    # publish the same cluster-wide gauges every interval.
+    def tick
+      return unless leader?
+
+      snapshot
+    rescue StandardError => e
+      handle_exception(e, { context: 'history-snapshot' })
+    end
+
+    # One snapshot, bypassing the leader gate and the sleep loop. Public so
+    # deterministic specs and a manual "snapshot now" can drive it directly.
+    # Always appends to the `history:metrics` stream (the dashboard's source);
+    # additionally emits to dogstatsd when a client is configured.
+    def snapshot
+      values = collect_values
+      record_stream(values)
+      emit_statsd(values)
+      nil
+    end
+
+    # Most-recent snapshots from the `history:metrics` stream, oldest→newest.
+    # Each point is `{ at: <epoch seconds>, <field>: <numeric>, … }`. Fields are
+    # read generically, so a migrated Sidekiq Ent install's entries render
+    # without rewrite regardless of which fields they carry.
+    def self.recent(limit: STREAM_DEFAULT_LIMIT)
+      count = limit.to_i.clamp(1, STREAM_CAP)
+      entries = Wurk.redis { |c| c.call('XREVRANGE', Keys::HISTORY_METRICS, '+', '-', 'COUNT', count) }
+      entries.reverse.map { |entry_id, fields| parse_entry(entry_id, fields) }
+    end
+
+    def self.parse_entry(entry_id, fields)
+      pairs = fields.is_a?(::Array) ? fields.each_slice(2).to_h : fields
+      point = { at: stream_epoch(entry_id) }
+      pairs.each { |field, value| point[field.to_sym] = numeric(value) }
+      point
+    end
+
+    # Redis stream IDs are "<ms>-<seq>"; the ms half is the snapshot time.
+    def self.stream_epoch(entry_id)
+      entry_id.to_s.split('-', 2).first.to_i / 1000.0
+    end
+
+    # Coerce a stream field to Int/Float for charting; leave non-numeric Ent
+    # fields (e.g. a label) untouched so nothing is silently dropped.
+    def self.numeric(value)
+      float = Float(value)
+      (float % 1).zero? ? float.to_i : float
+    rescue ::ArgumentError, ::TypeError
+      value
+    end
+
+    private
+
+    def collect_values
+      stats = Wurk::Stats.new
+      SNAPSHOT_FIELDS.transform_values { |reader| stats.public_send(reader) }
+    end
+
+    def record_stream(values)
+      fields = values.flat_map { |field, value| [field, value] }
+      redis do |c|
+        c.call('XADD', Keys::HISTORY_METRICS, 'MAXLEN', '~', @stream_cap, '*', *fields)
+      end
+    end
+
+    # §5.2 default gauge set carries the `sidekiq.` prefix so a dashboard built
+    # for Sidekiq Ent reads it unchanged. A custom collector replaces it.
+    def emit_statsd(values)
+      client = Wurk::Metrics::Statsd.client
+      return if client.nil?
+      return @collector.call(client) if @collector
+
+      values.each { |field, value| client.gauge("sidekiq.#{field}", value) }
+    end
+
+    def wait
+      @mutex.synchronize do
+        @sleeper.wait(@mutex, @interval) unless @done
+      end
+    end
+  end
+end

data/lib/wurk/iterable_job/active_record_enumerator.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Wurk
+  module IterableJob
+    # Cursor-resumable ActiveRecord iteration helpers for
+    # IterableJob#build_enumerator. Behavior parity with Sidekiq's
+    # `Sidekiq::Job::Iterable::ActiveRecordEnumerator`: the cursor is the
+    # primary key of the last-yielded record, threaded back through AR's
+    # `start:` so iteration resumes after an interruption without re-scanning.
+    #
+    # ActiveRecord is NOT a wurk dependency — these methods simply call the
+    # relation's batching API, so they work when the host app has AR and raise
+    # a plain NoMethodError otherwise (you can't build a relation without AR).
+    #
+    # Spec: docs/target/sidekiq-free.md §6.4; Sidekiq wiki Iteration.
+    class ActiveRecordEnumerator
+      def initialize(relation, cursor: nil, **options)
+        @relation = relation
+        @cursor = cursor
+        @options = options
+      end
+
+      # `[record, record.id]` pairs.
+      def records
+        ::Enumerator.new(-> { @relation.count }) do |yielder|
+          @relation.find_each(**@options, start: @cursor) do |record|
+            yielder.yield(record, record.id)
+          end
+        end
+      end
+
+      # `[records_batch, batch.first.id]` pairs. The size lambda is the record
+      # count, NOT the batch count — byte-for-byte with upstream Sidekiq's
+      # `ActiveRecordEnumerator#batches`, so `enum.size` returns the same value
+      # a drop-in app gets from Sidekiq. (Only the lazy `#size` differs from
+      # `relations`; the run loop never calls it.)
+      def batches
+        ::Enumerator.new(-> { @relation.count }) do |yielder|
+          @relation.find_in_batches(**@options, start: @cursor) do |batch|
+            yielder.yield(batch, batch.first.id)
+          end
+        end
+      end
+
+      # `[relation, first_record.id]` pairs. `:batch_size` is normalized to
+      # `:of` so callers use one option name across all three helpers. Delete
+      # `:batch_size` unconditionally before the `||=` so a caller passing both
+      # `:of` and `:batch_size` can't leak `:batch_size` into `in_batches`
+      # (which has no such keyword) — upstream's `||=` short-circuits and
+      # raises ArgumentError there; valid single-option calls are unaffected.
+      def relations
+        ::Enumerator.new(-> { relations_size }) do |yielder|
+          options = @options.dup
+          batch_size = options.delete(:batch_size)
+          options[:of] ||= batch_size
+
+          @relation.in_batches(**options, start: @cursor) do |relation|
+            yielder.yield(relation, relation.first.id)
+          end
+        end
+      end
+
+      private
+
+      def relations_size
+        batch_size = @options[:batch_size] || 1000
+        (@relation.count + batch_size - 1) / batch_size # ceiling division
+      end
+    end
+  end
+end

data/lib/wurk/iterable_job/csv_enumerator.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Wurk
+  module IterableJob
+    # Cursor-resumable CSV iteration helper for IterableJob#build_enumerator.
+    # Byte-for-byte behavior parity with Sidekiq's
+    # `Sidekiq::Job::Iterable::CsvEnumerator`: the cursor is the integer row
+    # (or batch) index, and resume drops that many rows. Requires the host to
+    # have loaded `csv` (we don't force the dependency).
+    #
+    # Spec: docs/target/sidekiq-free.md §6.4; Sidekiq wiki Iteration.
+    class CsvEnumerator
+      def initialize(csv)
+        raise ArgumentError, 'CsvEnumerator.new takes CSV object' unless defined?(::CSV) && csv.instance_of?(::CSV)
+
+        @csv = csv
+      end
+
+      # Enumerator of `[row, index]` pairs, skipping the first `cursor` rows.
+      def rows(cursor:)
+        @csv.lazy
+            .each_with_index
+            .drop(cursor || 0)
+            .to_enum { count_of_rows_in_file }
+      end
+
+      # Enumerator of `[rows_batch, batch_index]` pairs, skipping the first
+      # `cursor` batches.
+      def batches(cursor:, batch_size: 100)
+        @csv.lazy
+            .each_slice(batch_size)
+            .with_index
+            .drop(cursor || 0)
+            .to_enum { (count_of_rows_in_file.to_f / batch_size).ceil }
+      end
+
+      private
+
+      # Best-effort row count for the enumerator's `size` (progress display).
+      # Only invoked if a caller asks for `#size`; the run loop never does.
+      def count_of_rows_in_file
+        filepath = @csv.path
+        return unless filepath
+
+        count = ::IO.popen(['wc', '-l', filepath]) { |out| out.read.strip.to_i }
+        count -= 1 if @csv.headers
+        count
+      end
+    end
+  end
+end

data/lib/wurk/iterable_job.rb

@@ -2,6 +2,8 @@
 
 require 'json'
 require_relative 'job'
+require_relative 'iterable_job/csv_enumerator'
+require_relative 'iterable_job/active_record_enumerator'
 
 module Wurk
   # Iterable jobs split long-running work into small, idempotent chunks.
@@ -70,6 +72,39 @@ module Wurk
       raise NotImplementedError, "#{self.class} must override #each_iteration"
     end
 
+    # --- enumerator builders (§6.4) -------------------------------------
+    # Helpers user code calls from `#build_enumerator` to get a resumable
+    # enumerator of `[item, cursor]` pairs. Cursor parity with Sidekiq:
+    # array/CSV use the integer index; ActiveRecord uses the record's
+    # primary key.
+
+    def array_enumerator(array, cursor:)
+      raise ArgumentError, 'array must be an Array' unless array.is_a?(::Array)
+
+      x = array.each_with_index.drop(cursor || 0)
+      x.to_enum { x.size }
+    end
+
+    def csv_enumerator(csv, cursor:)
+      CsvEnumerator.new(csv).rows(cursor: cursor)
+    end
+
+    def csv_batches_enumerator(csv, cursor:, **)
+      CsvEnumerator.new(csv).batches(cursor: cursor, **)
+    end
+
+    def active_record_records_enumerator(relation, cursor:, **)
+      ActiveRecordEnumerator.new(relation, cursor: cursor, **).records
+    end
+
+    def active_record_batches_enumerator(relation, cursor:, **)
+      ActiveRecordEnumerator.new(relation, cursor: cursor, **).batches
+    end
+
+    def active_record_relations_enumerator(relation, cursor:, **)
+      ActiveRecordEnumerator.new(relation, cursor: cursor, **).relations
+    end
+
     # --- lifecycle hooks (no-op defaults; users override as needed) -----
 
     def on_start; end
@@ -289,4 +324,10 @@ module Wurk
       end
     end
   end
+
+  # Sidekiq drop-in: upstream homes the iterable module (and its enumerator
+  # classes) under `Sidekiq::Job::Iterable`. Since `Sidekiq::Job == Wurk::Job`,
+  # mirror that so `Sidekiq::Job::Iterable::CsvEnumerator` /
+  # `…::ActiveRecordEnumerator` resolve for ported code.
+  Job::Iterable = IterableJob unless Job.const_defined?(:Iterable, false)
 end

data/lib/wurk/iterable_job_query.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Wurk
+  # Read-side data API for IterableJob progress. Bulk-reads the `it-<jid>`
+  # HASHes (sidekiq-free.md §1.5) in a single pipeline so dashboards and tools
+  # can introspect many iterable jobs without N round trips. The runtime that
+  # *writes* those HASHes lives in Wurk::IterableJob; this is the reader.
+  #
+  # Aliased Sidekiq::IterableJobQuery.
+  #
+  # Spec: docs/target/sidekiq-free.md §19.9.
+  class IterableJobQuery
+    include Enumerable
+
+    # One job's iteration state. `raw` is the `it-<jid>` HASH (String=>String);
+    # the accessors decode the wire fields (`ex`/`rt`/`c`/`cancelled`, §1.5).
+    State = Struct.new(:jid, :raw) do
+      def executions = raw['ex'].to_i
+      def runtime    = raw['rt'].to_f
+      def cursor     = raw['c'] && ::JSON.parse(raw['c'])
+
+      # Epoch-seconds timestamp the job was cancelled at, or nil if it wasn't.
+      def cancelled
+        ts = raw['cancelled']
+        ts && !ts.to_s.empty? ? ts.to_i : nil
+      end
+    end
+
+    # @param jids [Array<String>] job ids to query.
+    def initialize(jids)
+      @states = fetch(Array(jids))
+    end
+
+    # @return [State, nil] state for jid, or nil when no `it-<jid>` HASH exists
+    #   (e.g. a non-iterable job, or one whose state has expired).
+    def [](jid) = @states[jid]
+
+    # Yields each present State, in the order its jid was supplied. Jids with no
+    # state are skipped — only iterable jobs with live state appear.
+    def each(&) = @states.each_value(&)
+
+    private
+
+    def fetch(jids)
+      return {} if jids.empty?
+
+      raws = Wurk.redis do |conn|
+        conn.pipelined { |pipe| jids.each { |jid| pipe.call('HGETALL', "it-#{jid}") } }
+      end
+      build_states(jids, raws)
+    end
+
+    def build_states(jids, raws)
+      states = {}
+      jids.each_with_index do |jid, i|
+        hash = normalize_hgetall(raws[i])
+        states[jid] = State.new(jid, hash) unless hash.empty?
+      end
+      states
+    end
+
+    # redis-client returns HGETALL as a flat array on some adapters and a Hash
+    # on others. Normalize to a String-keyed Hash either way (mirrors the
+    # normalize done in Wurk::IterableJob#load_state).
+    def normalize_hgetall(raw)
+      case raw
+      when Hash  then raw
+      when Array then raw.each_slice(2).to_h
+      else            {}
+      end
+    end
+  end
+end