wurk 0.0.5 → 1.0.0

data/exe/wurkswarm

@@ -0,0 +1,23 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Standalone multi-process runner — forks N worker children from a preloaded
+# parent (fork-based real parallelism). Does NOT load the Rails engine.
+# Usage: `exe/wurkswarm -C config/wurk.yml`. Drop-in alias: `sidekiqswarm`.
+
+$stdout.sync = true
+$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
+
+require 'wurk'
+
+begin
+  cli = Wurk::CLI.instance
+  cli.parse
+  cli.run_swarm
+rescue StandardError => e
+  raise e if $DEBUG
+
+  warn "wurkswarm: #{e.message}"
+  warn e.backtrace.join("\n")
+  exit 1
+end

data/lib/active_job/queue_adapters/wurk_adapter.rb

@@ -89,6 +89,41 @@ begin
           Sidekiq::Client.push_bulk(items).compact.size
         end
       end
+
+      # Drop-in: a migrating app's config almost always still reads
+      # `queue_adapter = :sidekiq`, and pillar 1 says it must keep working on a
+      # one-line gem swap. Rails resolves `:sidekiq` by const_get'ing
+      # `SidekiqAdapter`, whose autoload target runs `gem "sidekiq"; require
+      # "sidekiq"` (activejob .../sidekiq_adapter.rb:3-4) — that raises at boot
+      # in a wurk-only app where no real sidekiq gem exists.
+      #
+      # When sidekiq is genuinely absent we pre-empt the autoload with a
+      # Wurk-backed adapter (a bare subclass — same enqueue path, same canonical
+      # wrapper payload, shared `@@stopping`, inherited `JobWrapper`). When the
+      # real sidekiq gem IS bundled (mixed mid-migration) we leave its adapter
+      # untouched so a genuine install is never clobbered.
+      #
+      # `gem "sidekiq"` activates without requiring; Bundler raises Gem::LoadError
+      # (or Gem::MissingSpecError, a subclass) when it's not in the bundle. The
+      # inline rescue keeps that probe from escaping to the outer handler.
+      sidekiq_gem_present =
+        begin
+          gem 'sidekiq'
+          true
+        rescue Gem::LoadError
+          false
+        end
+
+      unless sidekiq_gem_present
+        # remove_const drops Rails' pending autoload without firing it, so the
+        # `class` keyword below then defines fresh and never triggers the
+        # `require "sidekiq"`. Same remove-then-define dance as WurkAdapter.
+        remove_const(:SidekiqAdapter) if const_defined?(:SidekiqAdapter, false)
+
+        # Bare subclass: inherits the whole enqueue path, the shared @@stopping
+        # flag, and the JobWrapper constant from WurkAdapter unchanged.
+        class SidekiqAdapter < WurkAdapter; end
+      end
     end
   end
 rescue Gem::LoadError

data/lib/generators/wurk/install/templates/wurk.rb

@@ -1,14 +1,25 @@
 # frozen_string_literal: true
 
 # Wurk configuration. Generated by `bin/rails g wurk:install`.
-# See docs/target/sidekiq-free.md for the full surface area.
+# Full surface area: docs/target/sidekiq-free.md. Coming from Sidekiq?
+# See docs/migrate-from-sidekiq.md.
 
 Wurk.configure_server do |config|
   # config.redis = { url: ENV.fetch("REDIS_URL", "redis://localhost:6379/0") }
-  # config.workers = 2
+
+  # Threads per worker process:
   # config.concurrency = 10
+
+  # Queues this process pulls from (first = highest priority):
   # config.queues = %w[critical default low]
-  # config.shutdown_timeout = 25
+
+  # Seconds to let in-flight jobs finish on shutdown (Sidekiq-compatible key):
+  # config[:timeout] = 25
+
+  # The default is a single worker process (fork). To run several, declare a
+  # topology — `flat` spawns N identical forks; use `slot`s for dedicated
+  # queues. See docs/idea/03-process-model.md.
+  # config.topology = Wurk::Topology.flat(count: 2, queues: %w[critical default low], concurrency: 10)
 end
 
 Wurk.configure_client do |config|

data/lib/sidekiq/api.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Drop-in require path (see lib/sidekiq.rb). Wurk loads this surface whole.
+require 'wurk'

data/lib/sidekiq/cli.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# Drop-in require path (see lib/sidekiq.rb). In Sidekiq, `Sidekiq.server?`
+# is literally "has sidekiq/cli been required" — apps and ecosystem test
+# helpers require this file to make `configure_server` blocks run. Wurk
+# always loads its CLI class internally, so the passthrough carries the
+# *semantic*: requiring it declares this process a server.
+require 'wurk'
+Wurk.enter_server_mode

data/lib/sidekiq/client.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Drop-in require path (see lib/sidekiq.rb). Wurk loads this surface whole.
+require 'wurk'

data/lib/sidekiq/job.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Drop-in require path (see lib/sidekiq.rb). Wurk loads this surface whole.
+require 'wurk'

data/lib/sidekiq/launcher.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Drop-in require path (see lib/sidekiq.rb). Wurk loads this surface whole.
+require 'wurk'

data/lib/sidekiq/middleware/chain.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Drop-in require path (see lib/sidekiq.rb). Wurk loads this surface whole.
+require 'wurk'

data/lib/sidekiq/middleware/server/statsd.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Drop-in require shim for Sidekiq Pro's documented statsd setup:
+#
+#   require "sidekiq/middleware/server/statsd"
+#   chain.add Sidekiq::Middleware::Server::Statsd
+#
+# The constant itself is defined by Wurk (lib/wurk/metrics/statsd.rb, aliased as
+# Wurk::Middleware::Server::Statsd → Sidekiq::Middleware::Server::Statsd via the
+# compat layer). This file just ensures Wurk is loaded so the verbatim Pro
+# `require` resolves instead of raising LoadError. Spec: docs/target/sidekiq-pro.md §9.1.
+require 'wurk' unless defined?(Sidekiq::Middleware::Server::Statsd)

data/lib/sidekiq/rails.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Drop-in require path (see lib/sidekiq.rb): `require "sidekiq/rails"` in a
+# Sidekiq app loads the Rails integration. Sidekiq's is railtie-grade and
+# needs only railties — ecosystem test helpers load it with `rails/railtie`
+# alone, no ActionDispatch — so this maps to the railtie, NOT the dashboard
+# engine (a wurk-native extra; `require "wurk/rails"` for that). Sidekiq::Web
+# stays mountable as a plain Rack app either way, exactly like upstream.
+require 'wurk'
+require 'wurk/railtie'

data/lib/sidekiq/redis_connection.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Drop-in require path (see lib/sidekiq.rb). Wurk loads this surface whole.
+require 'wurk'

data/lib/sidekiq/scheduled.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Drop-in require path (see lib/sidekiq.rb). Wurk loads this surface whole.
+require 'wurk'

data/lib/sidekiq/testing.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Drop-in require path (see lib/sidekiq.rb). Wurk loads this surface whole.
+require 'wurk'

data/lib/sidekiq/version.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Drop-in require path (see lib/sidekiq.rb). Wurk loads this surface whole.
+require 'wurk'

data/lib/sidekiq/web.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Drop-in require path (see lib/sidekiq.rb). Wurk loads this surface whole.
+require 'wurk'

data/lib/sidekiq/worker.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Drop-in require path (see lib/sidekiq.rb). Wurk loads this surface whole.
+require 'wurk'

data/lib/sidekiq.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Drop-in require entrypoint (#204): `require "sidekiq"` loads Wurk and its
+# Sidekiq::* alias layer (lib/wurk/compat.rb), so code and third-party gems
+# written against Sidekiq load Wurk without changing a single require. The
+# sibling files under lib/sidekiq/ cover the documented `require "sidekiq/…"`
+# sub-paths the ecosystem uses; all are one-line passthroughs because Wurk
+# loads its full surface (web included) from the single "wurk" entrypoint.
+#
+# Bundler-level substitution (a gem's `add_dependency "sidekiq"`) is handled
+# by the companion shim gem in ecosystem/sidekiq-shim/.
+require 'wurk'
+
+# Upstream sidekiq.rb does exactly this: a Rails host that Bundler.requires
+# the gem gets the Rails integration without a separate require.
+require_relative 'sidekiq/rails' if defined?(Rails::Engine)

data/lib/wurk/batch/callbacks.rb

@@ -15,25 +15,45 @@ module Wurk
     module Callbacks
       module_function
 
-      # Called from the server middleware after BATCH_ACK_SUCCESS. Fires
-      # `:complete` when live jids hit 0; fires `:success` when pending
-      # also hits 0 and there have been no deaths.
+      # Called from the server middleware after BATCH_ACK_SUCCESS (and from
+      # DeathHandler when a death drains the last live jid). Fires `:complete`
+      # when live jids hit 0; fires `:success` when pending also hits 0 and
+      # there have been no deaths.
+      #
+      # Both fires are additionally gated on `b-<bid>-pkids` being empty —
+      # children whose own subtree hasn't finished yet (#209). Spec §2.4:
+      # child `:complete`/`:success` fire before the parent's, so when the
+      # parent's *own* last job acks while a child batch is still running,
+      # nothing fires here; the last child's propagate_to_parent re-invokes
+      # this and fires then. The SREM in pkids_drained? happens before that
+      # re-invocation, so exactly one of the racing paths fires (dedup_set
+      # absorbs the overlap).
       def maybe_fire(bid, pending:, live:)
         return unless live.zero?
+        return unless kids_finished?(bid)
 
         fire_complete(bid)
-        fire_success(bid) if pending.zero? && !death_fired?(bid)
+        fire_success(bid) if pending.zero? && !subtree_dead?(bid)
         propagate_to_parent(bid)
       end
 
-      # Fired from Wurk::Batch::DeathHandler on the FIRST permanent death
-      # in the batch only. Subsequent deaths bump the counter but do not
-      # re-enqueue the callback.
-      def fire_death(bid)
-        return unless dedup_set(bid, 'death')
+      def kids_finished?(bid)
+        Wurk.redis { |conn| conn.call('SCARD', "b-#{bid}-pkids") }.to_i.zero?
+      end
 
+      # Fired from Wurk::Batch::DeathHandler whenever a death makes the died
+      # set go non-empty: the first death, or the first re-death after every
+      # dead jid was manually retried back into the live set (#212 — that
+      # retry's BATCH_PUSH cleared the death mark). The mark — durable `death`
+      # flag, `death_at`, `dead-batches` membership — is (re-)applied before
+      # the dedup guard so it is restored on re-death; the callback enqueue
+      # and parent cascade stay behind the guard so `:death` is enqueued at
+      # most once per batch.
+      def fire_death(bid)
         record_event(bid, 'death_at')
         Wurk.redis { |conn| conn.call('ZADD', 'dead-batches', Time.now.to_f.to_s, bid) }
+        return unless dedup_set(bid, 'death')
+
         enqueue_callbacks(bid, 'death')
         cascade_death(bid)
       end
@@ -61,10 +81,30 @@ module Wurk
         return unless dedup_set(bid, 'success')
 
         record_event(bid, 'success_at')
+        emit_duration_metric(bid)
         enqueue_callbacks(bid, 'success')
         apply_linger(bid)
       end
 
+      # Pro statsd metric (spec §9.3): wall-clock seconds from batch creation to
+      # full success. `created_at` shares the CLOCK_REALTIME epoch we record it
+      # with. No-op without a dogstatsd client.
+      #
+      # Strictly best-effort: `fire_success` has already burned the `success`
+      # dedup key by the time we run, so a raise here (e.g. a Redis hiccup on the
+      # HGET) would permanently strand the success callbacks and linger that
+      # follow — a retry can't re-fire them. Swallow and log instead.
+      def emit_duration_metric(bid)
+        created = Wurk.redis { |conn| conn.call('HGET', "b-#{bid}", 'created_at') }
+        return if created.nil? || created.to_s.empty?
+
+        seconds = ::Process.clock_gettime(::Process::CLOCK_REALTIME) - created.to_f
+        Wurk::Metrics::Statsd.distribution('batch.duration_dist', seconds)
+      rescue StandardError => e
+        Wurk.logger.warn("batch #{bid}: duration metric emit failed: #{e.class}: #{e.message}")
+        nil
+      end
+
       # Post-success retention: a succeeded batch no longer coordinates any
       # jobs, so its keys expire after the per-batch `linger` override (else
       # 24h) instead of the 30d pending TTL. Mirrors Sidekiq Pro §2.8.
@@ -106,6 +146,50 @@ module Wurk
         Wurk.redis { |conn| conn.call('HGET', "b-#{bid}", 'death') } == '1'
       end
 
+      # A batch's subtree is still dead while it carries the durable death
+      # mark OR any direct child does — deaths cascade up the parent chain,
+      # so a dead descendant keeps every ancestor's child marked. This gates
+      # `:success`, which must never fire while a job in the subtree is
+      # terminally dead (spec §2.4). The child check matters for the brief
+      # window where a batch with both its own dead job and a dead child has
+      # its OWN dead job retried to success: BATCH_PUSH (#212) clears that
+      # batch's own mark when its died set drains, but the child subtree is
+      # still dead, so `death_fired?` alone would wrongly let `:success` fire.
+      def subtree_dead?(bid)
+        death_fired?(bid) || any_child_dead?(bid)
+      end
+
+      # Recovery counterpart to cascade_death (#226). When a descendant's
+      # last dead job is manually retried back to success, the descendant
+      # clears its OWN death mark (#212, in BATCH_PUSH) — but every ancestor
+      # was marked by the death *cascade*, not by a jid in its own died set,
+      # so nothing here ever cleared them and the ancestor's `:success`
+      # stayed suppressed forever. Re-evaluate this batch: drop its durable
+      # death mark and `dead-batches` membership once its own died set is
+      # empty AND no child still carries a death mark. The `b-<bid>-death`
+      # notify dedup key is deliberately left intact, so a later re-death
+      # re-marks the batch (fire_death restores the flag before its own
+      # dedup guard) without ever re-enqueuing `:death`.
+      def clear_death_on_recovery(bid)
+        return unless death_fired?(bid)
+        return if own_died_remaining?(bid)
+        return if any_child_dead?(bid)
+
+        Wurk.redis do |conn|
+          conn.call('HDEL', "b-#{bid}", 'death')
+          conn.call('ZREM', 'dead-batches', bid)
+        end
+      end
+
+      def own_died_remaining?(bid)
+        Wurk.redis { |conn| conn.call('SCARD', "b-#{bid}-died") }.to_i.positive?
+      end
+
+      def any_child_dead?(bid)
+        kids = Wurk.redis { |conn| conn.call('SMEMBERS', "b-#{bid}-kids") }
+        kids.any? { |kid| death_fired?(kid) }
+      end
+
       # Per-callback rescue: one bad spec or a transient enqueue failure must
       # not strand the batch with the remaining callbacks for this event
       # un-enqueued. Log and move on so every other callback still fires.
@@ -146,15 +230,21 @@ module Wurk
         )
       end
 
-      # When a child batch's `:success` fires, decrement the parent's pkids
-      # set so the parent's own `:success` waits on the full subtree. When
-      # parent's pkids hits 0 *and* its own pending is 0, parent's success
-      # fires too.
+      # When a child batch finishes (its live jids hit 0 — by success or
+      # death), remove it from the parent's pkids set so the parent's own
+      # callbacks wait on the full subtree. When the parent's pkids hits 0,
+      # re-run the parent's maybe_fire: if its own counts are already at
+      # zero (the parent-acks-first race), this is what finally fires it.
       def propagate_to_parent(bid)
         parent_bid = parent_bid_for(bid)
         return if parent_bid.nil? || parent_bid.empty?
         return unless pkids_drained?(parent_bid, bid)
 
+        # A recovered child may have lifted the last death from the parent's
+        # subtree — clear the parent's cascaded mark before its gate runs, so
+        # `:success` can fire. Harmless on the death path: the dying child
+        # still carries its mark, so any_child_dead? keeps the parent dead.
+        clear_death_on_recovery(parent_bid)
         maybe_fire(parent_bid, pending: pending_for(parent_bid), live: live_for(parent_bid))
       end
 

data/lib/wurk/batch/death_handler.rb

@@ -29,8 +29,11 @@ module Wurk
         Wurk::Batch::Callbacks.fire_death(bid) if first_death == 1
         return unless live.zero?
 
-        Wurk::Batch::Callbacks.fire_complete(bid)
-        Wurk::Batch::Callbacks.propagate_to_parent(bid)
+        # Through the gated maybe_fire, not a direct fire_complete: this batch
+        # may still have running child batches, and spec §2.4 ordering says
+        # its `:complete` must wait for theirs (#209). `:success` stays
+        # suppressed regardless — the death above set the durable death flag.
+        Wurk::Batch::Callbacks.maybe_fire(bid, pending: Wurk::Batch::Callbacks.pending_for(bid), live: 0)
       end
     end
   end

data/lib/wurk/batch/server_middleware.rb

@@ -3,6 +3,8 @@
 require 'json'
 require_relative '../middleware'
 require_relative '../lua'
+require_relative '../job'
+require_relative '../job_retry'
 
 module Wurk
   class Batch
@@ -11,6 +13,13 @@ module Wurk
     # enqueue `:success` callback jobs; if live jids hit zero, enqueue
     # `:complete` callback jobs.
     #
+    # On a job raising (and thus heading to retry), records a transient
+    # failure → BATCH_ACK_FAILED → the jid joins `b-<bid>-failed` and
+    # `failures` reflects the count of currently-failing jobs. A later
+    # successful retry clears it; a terminal death moves it to `b-<bid>-died`.
+    # Clean handled exits (JobRetry::Skip from expiry/interrupt, cooperative
+    # IterableJob interruption) are re-raised without counting as failures.
+    #
     # Invalidated batches short-circuit: the job is skipped without
     # raising — counts as a "success" for batch purposes per spec §12.
     #
@@ -29,12 +38,24 @@ module Wurk
           return
         end
 
-        yield
-        ack_success(bid, job['jid'])
+        run_and_ack(bid, job['jid']) { yield }
       end
 
       private
 
+      # A handled/skip exit or a cooperative interruption is not a failure —
+      # re-raise it untouched. Any other exception means the job failed and
+      # will retry (or eventually die): record it before re-raising.
+      def run_and_ack(bid, jid)
+        yield
+        ack_success(bid, jid)
+      rescue Wurk::JobRetry::Handled, Wurk::Job::Interrupted
+        raise
+      rescue StandardError
+        ack_failed(bid, jid)
+        raise
+      end
+
       def invalidated?(bid)
         redis_pool.with { |conn| conn.call('HGET', "b-#{bid}", 'invalidated') } == '1'
       end
@@ -44,7 +65,7 @@ module Wurk
           Wurk::Lua::Loader.eval_cached(
             conn,
             :batch_ack_success,
-            keys: ["b-#{bid}", "b-#{bid}-jids"],
+            keys: ["b-#{bid}", "b-#{bid}-jids", "b-#{bid}-failed"],
             argv: [jid]
           )
         end
@@ -53,6 +74,17 @@ module Wurk
 
         Wurk::Batch::Callbacks.maybe_fire(bid, pending: pending, live: live)
       end
+
+      def ack_failed(bid, jid)
+        redis_pool.with do |conn|
+          Wurk::Lua::Loader.eval_cached(
+            conn,
+            :batch_ack_failed,
+            keys: ["b-#{bid}", "b-#{bid}-failed"],
+            argv: [jid]
+          )
+        end
+      end
     end
   end
 end

data/lib/wurk/batch/status.rb

@@ -54,6 +54,15 @@ module Wurk
         Wurk.redis { |conn| conn.call('SMEMBERS', "b-#{@bid}-failed") }
       end
 
+      # Deprecated pre-Pro8 surface (spec §2.5): an array of per-failure error
+      # detail. The Pro8 data model (§2.8) drops the `b-<bid>-failinfo` hash in
+      # favour of the `failed_jids` set, which Wurk tracks — so the per-jid
+      # error payload is intentionally not persisted and this returns []. Kept
+      # so drop-in callers referencing `#failure_info` don't NameError.
+      def failure_info
+        []
+      end
+
       def dead_jids
         Wurk.redis { |conn| conn.call('SMEMBERS', "b-#{@bid}-died") }
       end

data/lib/wurk/batch.rb

@@ -157,7 +157,9 @@ module Wurk
       raise ArgumentError, "invalid event #{event.inspect}" unless VALID_EVENTS.include?(sym)
       raise ArgumentError, 'callback options must be a Hash' unless options.is_a?(Hash)
 
-      @callbacks << [sym.to_s, callback_target(callback), options]
+      entry = [sym.to_s, callback_target(callback), options]
+      @callbacks << entry
+      persist_callback!(entry) if @flushed_once
       self
     end
 
@@ -224,6 +226,24 @@ module Wurk
       Wurk::Client.new.flush_batched(payloads) unless payloads.empty?
     end
 
+    # Like `linger=`, anything registered after the first flush must reach
+    # Redis — `Callbacks.enqueue_callbacks` reads specs from the hash, so an
+    # in-memory-only append would silently never fire (#213). Covers both
+    # `on` after `#jobs` and batches reopened by bid. The append runs
+    # server-side (Lua) so concurrent registrations from different processes
+    # can't lose each other to a read-modify-write race.
+    def persist_callback!(entry)
+      event = entry[0]
+      fired = Wurk.redis do |conn|
+        Wurk::Lua::Loader.eval_cached(conn, :batch_append_callback,
+                                      keys: ["b-#{@bid}"], argv: [entry.to_json, event])
+      end
+      raise ArgumentError, "cannot register #{event} callback: batch #{@bid} no longer exists" if fired == -1
+      return unless fired == '1'
+
+      Wurk.logger.warn("batch #{@bid}: #{event} callback registered after #{event} already fired — it will never run")
+    end
+
     # First flush writes the core hash, registers in the global `batches`
     # zset, and links tag indexes. Subsequent #jobs invocations skip this
     # — `total` is already there and BATCH_PUSH only increments deltas.
@@ -234,6 +254,8 @@ module Wurk
       Wurk.redis { |conn| conn.pipelined { |pipe| pipelined_first_flush(pipe, now) } }
       @parent_bid = current_parent_bid
       @flushed_once = true
+      # Pro statsd metric (spec §9.3); no-op without a dogstatsd client.
+      Wurk::Metrics::Statsd.increment('batch.created')
     end
 
     def pipelined_first_flush(pipe, now)

data/lib/wurk/capsule.rb

@@ -63,7 +63,7 @@ module Wurk
     # by hand; centralizing it here covers the standalone CLI and embedded
     # paths too (the bug behind a nil `fetcher` in `exe/wurk`). Idempotent.
     def prepare!
-      @fetcher ||= Wurk::Fetcher::Reliable.new(self)
+      @fetcher ||= build_fetcher
       redis_pool
       local_redis_pool
       client_middleware
@@ -121,6 +121,12 @@ module Wurk
       @config.lookup(name)
     end
 
+    # Empty-poll BLMOVE backoff for this capsule's reliable fetcher (Pro
+    # super_fetch §3.3). nil → the fetcher falls back to its TIMEOUT default.
+    def fetch_poll_interval
+      @config[:fetch_poll_interval]
+    end
+
     def logger
       @config.logger
     end
@@ -134,6 +140,19 @@ module Wurk
 
     private
 
+    # Drop-in fetch pluggability (spec §5 / §4.1): instantiate
+    # `config[:fetch_class]` when the host set one — a custom or Pro fetcher —
+    # else the default reliable BLMOVE fetcher (`Sidekiq::BasicFetch`). A
+    # `config[:fetch_setup]` callable, if present, is handed the freshly built
+    # fetcher so it can configure it before the manager starts pulling work.
+    def build_fetcher
+      klass = @config[:fetch_class] || Wurk::Fetcher::Reliable
+      fetcher = klass.new(self)
+      setup = @config[:fetch_setup]
+      setup.call(fetcher) if setup.respond_to?(:call)
+      fetcher
+    end
+
     def parse_queue_entry(entry)
       qname, weight_str = entry.to_s.split(',', 2)
       qname = qname.to_s.strip