wurk 0.0.1

data/lib/wurk/lua.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+require 'digest'
+
+module Wurk
+  # EVALSHA-cached Lua scripts. Loaded once per pool, never re-uploaded.
+  # Bulk enqueue, 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`.
+  # Whitespace edits change the SHA, which forces a re-upload at runtime.
+  #
+  # `: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
+    ZPOPBYSCORE = <<~LUA
+      local key, now = KEYS[1], ARGV[1]
+      local jobs = redis.call("zrange", key, "-inf", now, "byscore", "limit", 0, 1)
+      if jobs[1] then
+        redis.call("zrem", key, jobs[1])
+        return jobs[1]
+      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.
+    # KEYS = [sorted_set, queues_set]
+    # ARGV = [now, queue_prefix]
+    # Returns the number of jobs promoted.
+    # Order matters: decode + push BEFORE zrem. Redis Lua has no rollback,
+    # so a failed cjson.decode after a zrem would lose the job. Decode first;
+    # push first; only then remove from the sorted set. Worst case is a
+    # crash between lpush and zrem → at-least-once redelivery, never loss.
+    RELIABLE_SCHEDULE_PROMOTE = <<~LUA
+      local jobs = redis.call("zrangebyscore", KEYS[1], "-inf", ARGV[1])
+      for i = 1, #jobs do
+        local job = jobs[i]
+        local q = cjson.decode(job)["queue"]
+        redis.call("sadd", KEYS[2], q)
+        redis.call("lpush", ARGV[2] .. q, job)
+        redis.call("zrem", KEYS[1], job)
+      end
+      return #jobs
+    LUA
+
+    # 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]
+    # 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])
+      redis.call("sadd", KEYS[4], ARGV[1])
+      redis.call("lpush", KEYS[3], ARGV[3])
+      return 1
+    LUA
+
+    # 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]
+    # 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
+      local removed = redis.call("srem", KEYS[2], ARGV[1])
+      if removed == 1 then
+        local pending = redis.call("hincrby", KEYS[1], "pending", -1)
+        return { pending, redis.call("scard", KEYS[2]) }
+      end
+      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.
+    # KEYS = [b-<bid>, b-<bid>-jids, b-<bid>-died, b-<bid>-failed]
+    # ARGV = [jid]
+    # Returns [live_jids_remaining, died_count, first_death]. `first_death`
+    # is 1 the first time *any* jid is SADDed into the died set, 0 thereafter
+    # — caller uses it to fire `:death` exactly once per batch.
+    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])
+      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
+      end
+      return { redis.call("scard", KEYS[2]), redis.call("scard", KEYS[3]), first_death }
+    LUA
+
+    # Pro Batch: invalidate all pending jobs. The jobs themselves stay
+    # in their queues — the server middleware short-circuits when it sees
+    # the invalidated flag — but the jids set is cleared so the batch can
+    # no longer accept completion callbacks.
+    # KEYS = [b-<bid>, b-<bid>-jids]
+    # ARGV = []
+    # Returns 1.
+    BATCH_INVALIDATE = <<~LUA
+      redis.call("del", KEYS[2])
+      redis.call("hset", KEYS[1], "invalidated", "1")
+      return 1
+    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.
+    # KEYS = [queue:<name>]
+    # ARGV = [jid]
+    # Returns the number of payloads removed (0 or 1; can be >1 in pathological
+    # duplicate-jid corruption — caller doesn't rely on the value).
+    FAST_DELETE_JOB = <<~LUA
+      local items = redis.call("lrange", KEYS[1], 0, -1)
+      local removed = 0
+      for i = 1, #items do
+        if string.find(items[i], '"jid":"' .. ARGV[1] .. '"', 1, true) then
+          removed = removed + redis.call("lrem", KEYS[1], 1, items[i])
+        end
+      end
+      return removed
+    LUA
+
+    # Pro Fast API (§11): server-side LRANGE+LREM removing every payload whose
+    # `"class":"<klass>"` field matches. Plain-text scan (no JSON parse) so
+    # it tolerates partial corruption — caller drops only well-formed matches.
+    # KEYS = [queue:<name>]
+    # ARGV = [klass]
+    # Returns the number of payloads removed.
+    FAST_DELETE_BY_CLASS = <<~LUA
+      local items = redis.call("lrange", KEYS[1], 0, -1)
+      local removed = 0
+      local needle = '"class":"' .. ARGV[1] .. '"'
+      for i = 1, #items do
+        if string.find(items[i], needle, 1, true) then
+          removed = removed + redis.call("lrem", KEYS[1], 1, items[i])
+        end
+      end
+      return removed
+    LUA
+
+    # Limiter scripts live in `lib/wurk/lua/limiter_*.lua` — one file per
+    # type. Loaded at boot, the file's basename (minus `.lua`) becomes the
+    # SCRIPTS key as a symbol. Keeping them as separate files makes diffing
+    # individual rate-limiter changes painless and keeps each script self-
+    # contained for the `redis-cli --eval` debug workflow.
+    LUA_DIR = File.expand_path('lua', __dir__)
+    FILE_SCRIPTS = Dir.glob(File.join(LUA_DIR, '*.lua')).each_with_object({}) do |path, h|
+      h[File.basename(path, '.lua').to_sym] = File.read(path)
+    end.freeze
+
+    SCRIPTS = {
+      zpopbyscore: ZPOPBYSCORE,
+      bulk_push: BULK_PUSH,
+      reliable_schedule_promote: RELIABLE_SCHEDULE_PROMOTE,
+      batch_push: BATCH_PUSH,
+      batch_ack_success: BATCH_ACK_SUCCESS,
+      batch_ack_complete: BATCH_ACK_COMPLETE,
+      batch_invalidate: BATCH_INVALIDATE,
+      fast_delete_job: FAST_DELETE_JOB,
+      fast_delete_by_class: FAST_DELETE_BY_CLASS
+    }.merge(FILE_SCRIPTS).freeze
+
+    # SHA1 of each script source — matches what `SCRIPT LOAD` returns.
+    # Precomputing keeps `eval_cached` allocation-free in the hot path.
+    SHAS = SCRIPTS.transform_values { |src| Digest::SHA1.hexdigest(src) }.freeze
+  end
+end
+
+require_relative 'lua/loader'

data/lib/wurk/manager.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require_relative 'component'
+require_relative 'processor'
+
+module Wurk
+  # One per Capsule. Lives inside each forked child and owns the Processor
+  # pool. Replaces dead processors on the fly (replace-on-die), forwards
+  # the quiet/stop signals received by the Swarm to its processors, and
+  # ensures in-flight UnitsOfWork are bulk_requeued before threads are killed.
+  #
+  # Lifecycle:
+  #   * `start`         — spawn each processor thread.
+  #   * `quiet`         — stop fetching; in-flight jobs run to completion.
+  #   * `stop(deadline)`— quiet + wait for drain; hard_shutdown on timeout.
+  #
+  # Spec: docs/target/sidekiq-free.md §13.
+  class Manager
+    include Component
+
+    # 0.1 in TTY mode so interactive shutdown feels snappy; 0.5 in
+    # production so the supervisor isn't spinning while threads drain.
+    PAUSE_TIME = $stdout.tty? ? 0.1 : 0.5
+
+    attr_reader :workers, :capsule
+
+    def initialize(capsule)
+      @config = @capsule = capsule
+      @count = capsule.concurrency
+      raise ArgumentError, "Concurrency of #{@count} is not supported" if @count < 1
+
+      @done = false
+      @workers = Set.new
+      @plock = ::Mutex.new
+      @count.times do
+        @workers << Processor.new(@capsule, &method(:processor_result))
+      end
+    end
+
+    def start
+      @workers.each(&:start)
+    end
+
+    def quiet
+      return if @done
+
+      @done = true
+      logger.info { "Terminating quiet threads for #{capsule.name} capsule" }
+      @workers.each(&:terminate)
+    end
+
+    # Graceful shutdown: quiet first, then poll for workers to clear.
+    # If the deadline elapses with workers still alive we fall through to
+    # hard_shutdown, which bulk_requeues their UoWs before killing threads.
+    def stop(deadline)
+      quiet
+      # Lifecycle hooks (e.g. :quiet) can be async; give them a tick to settle
+      # before we start polling. Matches Sidekiq's PAUSE_TIME behavior.
+      sleep PAUSE_TIME
+      return if @workers.empty?
+
+      logger.info { 'Pausing to allow jobs to finish...' }
+      wait_for(deadline) { @workers.empty? }
+      return if @workers.empty?
+
+      hard_shutdown
+    ensure
+      capsule.stop
+    end
+
+    def stopped?
+      @done
+    end
+
+    # Processor#run callback: invoked when a Processor thread exits, whether
+    # cleanly or via raised exception. Removes the dead processor from the
+    # pool and (unless we're already stopping) spawns a replacement so the
+    # capsule's concurrency stays constant.
+    def processor_result(processor, _reason = nil)
+      @plock.synchronize do
+        @workers.delete(processor)
+        unless @done
+          p = Processor.new(@capsule, &method(:processor_result))
+          @workers << p
+          p.start
+        end
+      end
+    end
+
+    # Reached when the deadline expired with workers still busy. We must
+    # push their in-flight UoWs back to the public queues BEFORE raising
+    # Wurk::Shutdown into the threads — losing a job is worse than running
+    # it twice (Sidekiq's at-least-once contract).
+    def hard_shutdown # rubocop:disable Metrics/AbcSize
+      cleanup = nil
+      @plock.synchronize do
+        cleanup = @workers.dup
+      end
+
+      if cleanup.any?
+        jobs = cleanup.map(&:job).compact
+
+        logger.warn { "Terminating #{cleanup.size} busy threads" }
+        logger.debug { "Jobs still in progress #{jobs.inspect}" }
+
+        capsule.fetcher.bulk_requeue(jobs)
+      end
+
+      cleanup.each(&:kill)
+
+      # The caller typically `exit`s immediately after we return; give
+      # threads a brief window to run their `ensure` blocks.
+      deadline = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC) + 3
+      wait_for(deadline) { @workers.empty? }
+    end
+
+    private
+
+    # Polls `condblock` until it returns true or the monotonic deadline
+    # passes. The PAUSE_TIME floor stops us from spinning when only a few
+    # milliseconds remain.
+    def wait_for(deadline)
+      remaining = deadline - ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+      while remaining > PAUSE_TIME
+        return if yield
+
+        sleep PAUSE_TIME
+        remaining = deadline - ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/wurk/metrics/history.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require_relative '../middleware'
+
+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.
+    #
+    # 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|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>-YYMMDD-H  HASH per-class hourly histogram, TTL = MID_TERM
+    #
+    # 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
+    # *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).
+    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
+
+      def call(_worker, job, _queue)
+        klass = job['class']
+        started = monotonic_ms
+        success = false
+        begin
+          result = yield
+          success = true
+          result
+        ensure
+          duration = (monotonic_ms - started).round
+          # Best-effort: a metrics write failure must never propagate into
+          # the job result. The processor already finalized the ack path.
+          begin
+            self.class.record(klass, duration, success: success, redis_pool: redis_pool)
+          rescue StandardError => e
+            handle_error(e)
+          end
+        end
+      end
+
+      class << self
+        # Single Redis round-trip per job. `success: true` → `<klass>|p`;
+        # `success: false` → `<klass>|f`. `<klass>|ms` accumulates total
+        # runtime in milliseconds for *both* outcomes (so an operator can
+        # ask "how much wall-clock time has FooJob consumed?" without
+        # branching on outcome).
+        def record(klass, duration_ms, success:, redis_pool: nil, at: ::Time.now)
+          return if klass.nil? || klass.empty?
+
+          ms = duration_ms.to_i
+          ms = 0 if ms.negative?
+          buckets = { minute: minute_key(at), rollup: rollup_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.
+        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
+
+        def incr_bucket(pipe, key, parts)
+          outcome_field, ms_field, ms, ttl = parts
+          pipe.call('HINCRBY', key, outcome_field, 1)
+          pipe.call('HINCRBY', key, ms_field, ms)
+          pipe.call('EXPIRE', key, ttl)
+        end
+
+        # Public formatters — Wurk::Metrics::Query reuses these so the two
+        # cannot drift on bucket-naming convention.
+        def minute_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)
+        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}"
+        end
+      end
+
+      private
+
+      def monotonic_ms
+        ::Process.clock_gettime(::Process::CLOCK_MONOTONIC, :float_millisecond)
+      end
+
+      def handle_error(err)
+        cfg = config || Wurk.configuration
+        cfg.handle_exception(err, context: 'Wurk::Metrics::History')
+      end
+
+      def self.with_pool(pool, &)
+        if pool
+          pool.with(&)
+        else
+          Wurk.redis(&)
+        end
+      end
+      private_class_method :with_pool
+    end
+  end
+end

data/lib/wurk/metrics/query.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require_relative 'history'
+require_relative 'rollup'
+
+module Wurk
+  module Metrics
+    # Read-side for the per-class HASH bucket schema written by
+    # `Wurk::Metrics::History`. Backs the Web UI's history pane and any
+    # external dashboarding code; both rely on the same HGETALL fan-out
+    # over a contiguous range of minute / hour keys.
+    #
+    # Window caps are spec-enforced:
+    #
+    #   minutes ≤ 480  (8h — same as the 10-minute rollup retention)
+    #   hours   ≤ 72   (3d — same as MID_TERM retention)
+    #
+    # 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
+      MAX_MINUTES = 480
+      MAX_HOURS = 72
+      TOTAL_FIELDS = %w[p f ms].freeze
+      private_constant :TOTAL_FIELDS
+
+      class WindowTooWide < ::ArgumentError; end
+
+      module_function
+
+      # Aggregate per-job-class totals over a recent window of minute
+      # buckets. Returns array of `[class_name, {p:, f:, ms:}]` tuples
+      # 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
+        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
+
+      # Per-class time-series. `minutes` reads the per-minute bucket; `hours`
+      # reads the per-class hourly bucket (separate keys per spec, so a long
+      # window doesn't fan out over 4320 minute hashes).
+      def for_job(klass, minutes: nil, hours: nil, now: ::Time.now)
+        validate_for_job!(klass, minutes, hours)
+        minutes ? minute_series(klass, now, cap_minutes!(minutes)) : hour_series(klass, now, cap_hours!(hours))
+      end
+
+      # Cluster-total time-series for the dashboard throughput/failures charts,
+      # read from the compact buckets written by Wurk::Metrics::Rollup. `bucket`
+      # is '1m'/'5m'/'1h'; `window_seconds` is clamped to that bucket's
+      # retention. Returns `[{at:, p:, f:, ms:}, ...]` oldest→newest, gap-filled
+      # with zeros so a chart has a continuous x-axis.
+      def history(bucket, window_seconds, now: ::Time.now)
+        step, ttl = bucket_spec!(bucket)
+        starts = bucket_starts(now, step, clamp_history_window!(window_seconds, ttl))
+        rows = pipeline_hmget(starts.map { |s| Wurk::Metrics::Rollup.bucket_key(bucket, s) }, %w[p f ms])
+        starts.zip(rows).map { |at, (p, f, ms)| { at: at, p: p.to_i, f: f.to_i, ms: ms.to_i } }
+      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}"
+        end
+      end
+
+      def clamp_history_window!(window_seconds, ttl)
+        window = Integer(window_seconds)
+        raise ArgumentError, 'window must be positive' if window <= 0
+
+        [window, ttl].min
+      end
+
+      # The last `window/step` step-aligned bucket starts, oldest→newest, so
+      # they match the keys the rollup writes.
+      def bucket_starts(now, step, window)
+        last = (now.to_i / step) * step
+        (0...(window / step)).map { |i| last - (i * step) }.reverse
+      end
+
+      def validate_for_job!(klass, minutes, hours)
+        raise ArgumentError, 'klass required' if klass.nil? || klass.empty?
+        raise ArgumentError, 'pass exactly one of minutes: or hours:' if minutes && hours
+        raise ArgumentError, 'pass minutes: or hours:' if minutes.nil? && hours.nil?
+      end
+
+      def cap_minutes!(minutes)
+        check_window!(Integer(minutes), MAX_MINUTES, 'minutes')
+      end
+
+      def cap_hours!(hours)
+        check_window!(Integer(hours), MAX_HOURS, 'hours')
+      end
+
+      def check_window!(value, max, label)
+        raise ArgumentError, "#{label} must be positive" if value <= 0
+        raise WindowTooWide, "#{label} must be <= #{max} (got #{value})" if value > max
+
+        value
+      end
+
+      def aggregate_minutes(now, minutes)
+        totals = ::Hash.new { |h, k| h[k] = { p: 0, f: 0, ms: 0 } }
+        pipeline_hgetall(minute_keys(now, minutes)).each { |hash| accumulate!(totals, hash) }
+        totals
+      end
+
+      def accumulate!(totals, hash)
+        return if hash.nil? || hash.empty?
+
+        hash.each do |field, value|
+          klass, kind = field.split('|', 2)
+          next unless kind && TOTAL_FIELDS.include?(kind)
+
+          totals[klass][kind.to_sym] += Integer(value)
+        end
+      end
+
+      def minute_series(klass, now, minutes)
+        rows = pipeline_hmget(minute_keys(now, minutes), %W[#{klass}|p #{klass}|f #{klass}|ms])
+        zip_rows(minute_timestamps(now, minutes), rows)
+      end
+
+      def hour_series(klass, now, hours)
+        timestamps = hour_timestamps(now, hours)
+        keys = timestamps.map { |t| Wurk::Metrics::History.hour_key(klass, t) }
+        zip_rows(timestamps, pipeline_hmget(keys, %w[p f ms]))
+      end
+
+      def zip_rows(timestamps, rows)
+        timestamps.zip(rows).map { |at, (p, f, ms)| { at: at, p: p.to_i, f: f.to_i, ms: ms.to_i } }
+      end
+
+      def minute_keys(now, minutes)
+        minute_timestamps(now, minutes).map { |t| Wurk::Metrics::History.minute_key(t) }
+      end
+
+      # Truncate to the minute so the bucket boundary matches what the
+      # writer used. Fractional-second drift would otherwise pull in an
+      # unrelated minute on the edge of the window.
+      def minute_timestamps(now, minutes)
+        floor = floor_to(now, :min)
+        (0...minutes).map { |i| floor - (i * 60) }.reverse
+      end
+
+      def hour_timestamps(now, hours)
+        floor = floor_to(now, :hour)
+        (0...hours).map { |i| floor - (i * 3600) }.reverse
+      end
+
+      def floor_to(time, unit)
+        t = time.utc
+        case unit
+        when :min  then ::Time.utc(t.year, t.month, t.day, t.hour, t.min)
+        when :hour then ::Time.utc(t.year, t.month, t.day, t.hour)
+        end
+      end
+
+      def pipeline_hgetall(keys)
+        return [] if keys.empty?
+
+        Wurk.redis { |c| c.pipelined { |p| keys.each { |k| p.call('HGETALL', k) } } }
+      end
+
+      def pipeline_hmget(keys, fields)
+        return [] if keys.empty?
+
+        Wurk.redis { |c| c.pipelined { |p| keys.each { |k| p.call('HMGET', k, *fields) } } }
+      end
+    end
+  end
+end