wurk 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6ec30c1dfc5983b7182b0f5765ec40acd60d9682a8ef69dd2f5f5abb547c9a59
-  data.tar.gz: 1d6a8578a6743782463582302d240a3be94d4474a2b1ed8c26209ebcc78c2836
+  metadata.gz: '0995fd5827870e14584104a8998db58e9927339197460596567c05f2dacc7da0'
+  data.tar.gz: 8159d245826bf646a9c6025e4e06a49717f957aabe18dad5d2a5b58ed99818c0
 SHA512:
-  metadata.gz: 529fb49080a16a23f3834b99f37d4f34dd2d080e772529cb9afff46f1f0ca1d9694b35804d1a538fdf7ccd9a59e297c0ab3bd712792874fe37a05792fb991a3b
-  data.tar.gz: a75598d81e4182d798fbf220febbf50c2960134f3273f238f4182fcf4f03baac65613cfc3efdbeb871e14a38f0d20a775b90962315a8a21473a44f5cb4d0c037
+  metadata.gz: d45c20c9a8c29695c7ea2e04066dda58454fea0ce56453ed866cd111e38977fb1739ae47429a60b68380fac2f4d7fe85f232b420f92f95cba330c389ee435b5b
+  data.tar.gz: 94c5599bc28408e1e5eb30967d1b0fad4806d415a17e515774c057120d0833660f3c2860d9cf0cb2ea320ae3a27bd9ce683385ce5ace1c347d46530a96cd9a1a

data/README.md

@@ -6,7 +6,7 @@
 
 <p align="center"><strong>Wurk, wurk.</strong> 🪓 <em>Ready to work. Zug zug.</em></p>
 
-<p align="center"><strong>A 100% drop-in replacement for Sidekiq + Sidekiq Pro + Sidekiq Enterprise. Free forever. Faster.</strong></p>
+<p align="center"><strong>A 100% drop-in replacement for Sidekiq + Sidekiq Pro + Sidekiq Enterprise. Free forever.</strong></p>
 
 <div align="center">
 
@@ -21,6 +21,8 @@
 
 Wurk is wire-compatible with Sidekiq — same Redis keys, same job JSON, same Ruby DSL. Swap one line in your `Gemfile` and your existing jobs, batches, limiters, cron entries, and live Redis data keep working untouched. The Pro and Enterprise feature sets ship in the same free gem, with no license check and no tiers.
 
+**On speed:** Wurk is not currently faster than stock Sidekiq — it runs at roughly 0.87×–1.02× depending on workload shape, with parity on CPU and I/O but still behind on framework overhead (noop) and boot time. Numbers, method, and the reproduction command are in [docs/benchmarks.md](docs/benchmarks.md); run them yourself with `rake bench:vs_sidekiq`.
+
 ## Install
 
 ```ruby

data/app/controllers/concerns/wurk/stream_concurrency_guard.rb

@@ -7,28 +7,45 @@ module Wurk
   # we 503 with Retry-After — the SPA's EventSource reconnects (and its polling
   # fallback honors Retry-After) once a slot frees. Per-process is the right
   # scope: it's this process's own thread pool we're protecting.
+  #
+  # Slots are held as thread references rather than tallied in a counter so the
+  # cap can heal itself. A stream whose thread is killed mid-flight never
+  # reaches the `ensure` below (Puma hard-reaps worker threads past
+  # `force_shutdown_after`, and a thread killed inside an uninterruptible read
+  # can skip its ensure), which a counter would record as a slot held by nobody
+  # — ten of those and `/api/stream` 503s for the life of the process. A dead
+  # holder is instead evicted by the next acquire.
   module StreamConcurrencyGuard
     extend ActiveSupport::Concern
 
     MAX_CONCURRENT_STREAMS = 10
     RETRY_AFTER_SECONDS = 3
 
-    @open = 0
+    @holders = []
     @lock = Mutex.new
 
     class << self
-      # Reserve a stream slot; false when the cap is already reached.
+      # Reserve a stream slot for the calling thread; false when the cap is
+      # already reached by threads that are still alive.
       def acquire
         @lock.synchronize do
-          return false if @open >= MAX_CONCURRENT_STREAMS
+          @holders.keep_if(&:alive?)
+          return false if @holders.size >= MAX_CONCURRENT_STREAMS
 
-          @open += 1
+          @holders << Thread.current
           true
         end
       end
 
+      # Drops one slot held by the calling thread. Acquire and release always
+      # bracket a single block on one thread (`#with_stream_slot`), so a call
+      # from a thread holding nothing is a no-op rather than a slot taken away
+      # from whoever is actually streaming.
       def release
-        @lock.synchronize { @open -= 1 if @open.positive? }
+        @lock.synchronize do
+          index = @holders.rindex(Thread.current)
+          @holders.delete_at(index) if index
+        end
       end
     end
 

data/lib/wurk/capsule.rb

@@ -17,6 +17,11 @@ module Wurk
     attr_reader :name, :queues, :mode, :weights, :config
     attr_accessor :concurrency, :fetcher
 
+    # Capsule-hosted components (Manager, Processor, Fetcher) hand their capsule
+    # to Component as `config`, and `safe_thread` reads the priority off it.
+    # Sidekiq delegates the same accessor (capsule.rb:30).
+    def thread_priority = @config.thread_priority
+
     def initialize(name, config)
       @name = name.to_s
       @config = config
@@ -25,8 +30,15 @@ module Wurk
       @mode = :strict
       @weights = { 'default' => 0 }
       @fetcher = nil
-      @redis_pool = nil
-      @fetch_redis_pool = nil
+      # One mutable Hash rather than two ivars: the pools are the only part of a
+      # capsule that legitimately changes after Configuration#freeze! — fork
+      # closes them, Launcher#stop releases them, an embedded host that boots
+      # again rebuilds them. `Object#freeze` is shallow, so the Hash stays
+      # writable and freezing a capsule keeps meaning "no more configuration"
+      # instead of "these sockets are yours forever". Before this, a reset on a
+      # frozen capsule disconnected the pool and then raised FrozenError on the
+      # memo, leaving `redis_pool` answering with a shut-down pool for good.
+      @pools = {}
       @client_chain = nil
       @server_chain = nil
     end
@@ -64,9 +76,26 @@ 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!
+      prepare_shared!
       @fetcher ||= build_fetcher
       redis_pool
       fetch_redis_pool
+      self
+    end
+
+    # The half of `prepare!` a forking parent can run on every child's behalf:
+    # the chains are a pure function of this capsule's identity, not of the slot
+    # (queues + concurrency) a swarm child is assigned later, and `copy_for`
+    # opens nothing. Run before the fork, the entries are allocated once and
+    # inherited copy-on-write instead of rebuilt in every child.
+    #
+    # The rest of `prepare!` deliberately stays post-fork: both pools are sized
+    # off the slot's concurrency and one built here would hand every child an
+    # inherited socket, and `build_fetcher` fires the host's
+    # `config[:fetch_setup]` hook, which is per-child — running it in the parent
+    # would let a custom fetcher snapshot the wrong queues, or leak whatever the
+    # hook opened across the fork. Idempotent.
+    def prepare_shared!
       client_middleware
       server_middleware
       self
@@ -99,7 +128,7 @@ module Wurk
     MIN_POOL_SIZE = 10
 
     def redis_pool
-      @redis_pool ||= build_pool(size: main_pool_size, name: "#{@name}-main")
+      @pools[:main] ||= build_pool(size: main_pool_size, name: "#{@name}-main")
     end
 
     # Dedicated pool for the reliable fetcher's blocking BLMOVE: one slot per
@@ -107,18 +136,17 @@ module Wurk
     # fetch at once. Keeping fetch off the main pool is what lets an idle worker
     # hold zero main-pool connections again.
     def fetch_redis_pool
-      @fetch_redis_pool ||= build_pool(size: @concurrency, name: "#{@name}-fetch")
+      @pools[:fetch] ||= build_pool(size: @concurrency, name: "#{@name}-fetch")
     end
 
-    # Disconnect and drop cached pools. Called by Wurk::Swarm just before
-    # fork (parent side: close inherited sockets) and just after fork
-    # (child side: rebuild lazily). Connection_pool#shutdown is terminal,
-    # so dropping the reference is required — `redis_pool` will rebuild.
+    # Disconnect and drop cached pools. Called by Wurk::Swarm just before fork
+    # (parent side: close inherited sockets), just after fork (child side:
+    # rebuild lazily), and by Launcher#stop (release what this process held).
+    # Connection_pool#shutdown is terminal, so dropping the reference is
+    # required — `redis_pool` will rebuild.
     def reset_redis_pools!
-      @redis_pool&.disconnect!
-      @redis_pool = nil
-      @fetch_redis_pool&.disconnect!
-      @fetch_redis_pool = nil
+      @pools.each_value(&:disconnect!)
+      @pools.clear
     end
 
     def redis(idempotent: false, &)

data/lib/wurk/client/buffered.rb

@@ -119,6 +119,13 @@ module Wurk
             @overflow_mode = nil
             @buffer_client_factory = nil
           end
+          # Stop before dropping: an unstopped drainer thread survives with
+          # its factory nil'd out from under it and ticks forever against
+          # nothing, leaking the thread and everything its closure retains.
+          install_mutex.synchronize do
+            @drainer&.stop
+            @drainer = nil
+          end
         end
 
         # Fork hook, called from the `Process._fork` prepend below and from

data/lib/wurk/client.rb

@@ -26,6 +26,20 @@ module Wurk
     SCHEDULED_BATCH_SIZE      = 100
     SPREAD_INTERVAL_FLOOR     = 5
 
+    # Batched (`bid`) payloads per EVALSHA pipeline. Ours, not Sidekiq's — it
+    # has no batches. Sized to DEFAULT_BATCH_SIZE so no existing caller's
+    # round-trip count moves: `push_bulk` already hands #raw_push at most that
+    # many payloads, so its batched pipeline stays exactly one round trip.
+    #
+    # The cap is for the one path that isn't pre-sliced: `autoflush = true`
+    # buffers a whole `Batch#jobs` block, so #flush_batched can be handed an
+    # unbounded payload set. Unsliced that is one pipeline holding every
+    # command and every reply in memory at once, and — Lua being atomic and
+    # single-threaded — one uninterrupted server-side sweep that blocks every
+    # other client for its duration. Same reasoning as the LIMIT on
+    # RELIABLE_SCHEDULE_PROMOTE.
+    BATCH_PIPELINE_SLICE      = 1_000
+
     # Thread-local slot holding the payloads of the current push whose Redis
     # write is confirmed applied. {Client::Buffered} subtracts them from the set
     # it re-buffers when a *later* phase of the same push loses the connection,
@@ -138,7 +152,21 @@ module Wurk
 
     private
 
+    # #push and #push_bulk verify at different points and both match Sidekiq
+    # exactly: push walks the payload the chain handed back (sidekiq
+    # client.rb:101 — normalize → middleware → verify → raw_push), bulk walks it
+    # inside the innermost block (sidekiq client.rb:165). Push used to do both,
+    # and since `strict_args_mode` defaults to :raise the second full recursive
+    # args walk was never skipped.
+    #
+    # Bulk keeps its walk inside the block on purpose: a client middleware that
+    # halts the job there short-circuits the walk, and hoisting it out would
+    # raise on args that middleware was about to drop.
     def invoke_chain(normed)
+      @chain.invoke(normed['class'], normed, normed['queue'], pool) { normed }
+    end
+
+    def invoke_chain_verified(normed)
       @chain.invoke(normed['class'], normed, normed['queue'], pool) do
         verify_json(normed)
         normed
@@ -191,7 +219,7 @@ module Wurk
         item = base.merge('args' => job_args)
         item['at'] = ats[idx] if ats
         normed = normalize_item(item)
-        invoke_chain(normed)
+        invoke_chain_verified(normed)
       end
     end
 
@@ -314,6 +342,27 @@ module Wurk
       push_batched_pipelined(conn, batched, now) unless batched.empty?
     end
 
+    # One pipeline per BATCH_PIPELINE_SLICE payloads, each marked delivered the
+    # moment its reply is in — same contract as push_plain_group, and for the
+    # same reason: a slice that Redis already accepted must stay out of the
+    # reliable_push ledger, or a later slice's failure would report it as
+    # undelivered.
+    def push_batched_pipelined(conn, batched, now)
+      batched.each_slice(BATCH_PIPELINE_SLICE) do |slice|
+        eval_batched_slice(conn) { |pipe, eval_method| push_batched(pipe, slice, now, eval_method: eval_method) }
+        mark_delivered(slice)
+      end
+    end
+
+    # Same slicing and NOSCRIPT recovery as push_batched_pipelined, for the
+    # scheduled batched path (BATCH_SCHEDULE instead of BATCH_PUSH).
+    def push_batched_scheduled_pipelined(conn, batched)
+      batched.each_slice(BATCH_PIPELINE_SLICE) do |slice|
+        eval_batched_slice(conn) { |pipe, eval_method| push_batched_scheduled(pipe, slice, eval_method: eval_method) }
+        mark_delivered(slice)
+      end
+    end
+
     # Outside of test boots and `SCRIPT FLUSH` the rescue branch is dead
     # code; the eager `script_load_all` after fork keeps the script cache
     # hot for the life of the connection. The retry uses EVAL (source-embedded)
@@ -321,24 +370,18 @@ module Wurk
     # NOSCRIPT a second time under heavy CI load (WorkerTest 3.4/7.2 flake).
     # `script_load_all` still primes the cache so the *next* pipeline returns
     # to the EVALSHA fast path.
-    def push_batched_pipelined(conn, batched, now)
-      conn.pipelined { |pipe| push_batched(pipe, batched, now) }
-    rescue RedisClient::CommandError => e
-      raise unless e.message.to_s.start_with?('NOSCRIPT')
-
-      Wurk::Lua::Loader.script_load_all(conn)
-      conn.pipelined { |pipe| push_batched(pipe, batched, now, eval_method: :eval_with_source) }
-    end
-
-    # Same NOSCRIPT-recovery shape as push_batched_pipelined, for the scheduled
-    # batched path (BATCH_SCHEDULE instead of BATCH_PUSH).
-    def push_batched_scheduled_pipelined(conn, batched)
-      conn.pipelined { |pipe| push_batched_scheduled(pipe, batched) }
+    #
+    # Replaying the slice is safe precisely because every command in it is the
+    # same script: a flushed cache NOSCRIPTs all of them and applies none.
+    # Recovery is per slice, so the slices already acknowledged above are never
+    # re-sent. Mirrors Fetcher::Reliable#requeue_pipelined.
+    def eval_batched_slice(conn)
+      conn.pipelined { |pipe| yield(pipe, :eval_cached) }
     rescue RedisClient::CommandError => e
       raise unless e.message.to_s.start_with?('NOSCRIPT')
 
       Wurk::Lua::Loader.script_load_all(conn)
-      conn.pipelined { |pipe| push_batched_scheduled(pipe, batched, eval_method: :eval_with_source) }
+      conn.pipelined { |pipe| yield(pipe, :eval_with_source) }
     end
 
     # One pipeline per queue, marked delivered the moment its reply is in.
@@ -355,27 +398,48 @@ module Wurk
     # Cost is a round trip per distinct queue. The single-queue push — every
     # `perform_async`, every same-class `push_bulk` — still writes exactly the
     # one SADD + LPUSH pipeline it did before.
+    #
+    # `uniform_queue` short-circuits the common case (one job, or many jobs
+    # all destined for the same queue) without paying for the `group_by`
+    # Hash + per-group Array allocations; only a genuinely mixed-queue batch
+    # falls through to grouping.
     def push_plain(conn, payloads, now)
-      payloads.group_by { |j| j['queue'] }.each do |queue, jobs|
-        serialized = jobs.map do |j|
-          j['enqueued_at'] = now
-          Wurk.dump_json(j)
-        end
-        conn.pipelined do |pipe|
-          pipe.call('SADD', 'queues', queue)
-          pipe.call('LPUSH', "queue:#{queue}", *serialized)
-        end
-        mark_delivered(jobs)
+      queue = uniform_queue(payloads)
+      return push_plain_group(conn, queue, payloads, now) if queue
+
+      payloads.group_by { |j| j['queue'] }.each { |q, jobs| push_plain_group(conn, q, jobs, now) }
+    end
+
+    def uniform_queue(payloads)
+      first = payloads[0]['queue']
+      return first if payloads.size == 1
+
+      first if payloads.all? { |j| j['queue'] == first }
+    end
+
+    def push_plain_group(conn, queue, jobs, now)
+      serialized = jobs.map do |j|
+        j['enqueued_at'] = now
+        Wurk.dump_json(j)
+      end
+      conn.pipelined do |pipe|
+        pipe.call('SADD', 'queues', queue)
+        pipe.call('LPUSH', "queue:#{queue}", *serialized)
       end
+      mark_delivered(jobs)
     end
 
     # Batched jobs route through BATCH_PUSH: increments b-<bid> total+pending,
     # SADDs jid into the live set, registers the queue, LPUSHes the payload —
-    # all atomically. One Redis round-trip per job (no pipeline grouping)
-    # because the lua needs per-job KEYS bound. Acceptable cost: batch
-    # enqueue is not the hot path; correctness is. `eval_method` is the
+    # all atomically. The Lua binds per-job KEYS, so grouping N jobs into one
+    # EVALSHA isn't available; they ride one pipeline instead (the `conn` here
+    # is always the pipeline #push_batched_pipelined opened), so the cost is
+    # N commands and one round trip, not N round trips. `eval_method` is the
     # Wurk::Lua::Loader entry point (`:eval_cached` for the hot EVALSHA path,
-    # `:eval_with_source` for the EVAL-source retry).
+    # `:eval_with_source` for the EVAL-source retry) — neither reads the reply,
+    # which is what makes the pipelined form legal: `eval_cached`'s inline
+    # NOSCRIPT rescue can't fire against a buffered call, so recovery is the
+    # caller's finalize-time rescue.
     def push_batched(conn, payloads, now, eval_method: :eval_cached)
       payloads.each do |j|
         j['enqueued_at'] = now
@@ -394,9 +458,9 @@ module Wurk
     # total/pending increment registers the job in its batch at creation, and
     # the ZADD defers it onto `schedule`. Payload is stripped of `at`/
     # `enqueued_at` exactly like push_scheduled — `enqueued_at` is stamped fresh
-    # at promotion, never while the job sits scheduled (spec §7.1). One Redis
-    # round-trip per job because the Lua binds per-job KEYS; scheduled batch
-    # enqueue is not the hot path.
+    # at promotion, never while the job sits scheduled (spec §7.1). Per-job
+    # KEYS again, so one EVALSHA per job — pipelined by
+    # #push_batched_scheduled_pipelined into one round trip per slice.
     def push_batched_scheduled(conn, payloads, eval_method: :eval_cached)
       payloads.each do |j|
         Wurk::Lua::Loader.public_send(
@@ -436,7 +500,13 @@ module Wurk
     # evict them, and the drain that does land one counts it then — so booking
     # them here would inflate the counter on an outage and double-count every
     # payload that later replays.
+    #
+    # Resolve the client once for the whole batch and bail before touching a
+    # payload: unconfigured is the common case, and the tags below cost two
+    # Strings and an Array per job for `increment` to immediately drop.
     def emit_enqueued(payloads, buffered = nil)
+      return if Wurk::Metrics::Statsd.safe_client.nil?
+
       payloads = reject_by_identity(payloads, buffered) if buffered && !buffered.empty?
       payloads.each do |p|
         Wurk::Metrics::Statsd.increment(

data/lib/wurk/component.rb

@@ -37,8 +37,34 @@ module Wurk
 
     # --- identity -------------------------------------------------------
 
+    # Base36 `thread.object_id ^ pid` — the id in every log line and the key
+    # each Processor publishes its in-flight job under. Constant for the life
+    # of a thread inside one process and read several times per job, so it is
+    # memoized per thread (frozen: it is used as a Hash key, and an unfrozen
+    # String key is duped on every store).
+    #
+    # The pid is memoized alongside it because the thread that calls fork keeps
+    # its thread-locals in the child, where the pid — and therefore the tid —
+    # has changed. Without the guard a forked child would report the parent's
+    # tid and collide with it in `<identity>:work`.
+    #
+    # Thread-local, not `Thread#[]`: the latter is fiber-local, so a job that
+    # runs inside a Fiber (or any Enumerator) would miss the memo and allocate
+    # a fresh String on every read — the identity the memo exists to cache is
+    # the thread's, and it does not change when a fiber does.
+    def self.tid
+      thread = Thread.current
+      memo = thread.thread_variable_get(:wurk_tid)
+      pid = ::Process.pid
+      return memo[1] if memo && memo[0] == pid
+
+      id = (thread.object_id ^ pid).to_s(36).freeze
+      thread.thread_variable_set(:wurk_tid, [pid, id].freeze)
+      id
+    end
+
     def tid
-      (Thread.current.object_id ^ ::Process.pid).to_s(36)
+      Component.tid
     end
 
     def hostname
@@ -110,10 +136,16 @@ module Wurk
     # Spawns a named thread that runs `block` under `watchdog(name)`. The
     # parent must retain the returned Thread; otherwise GC may not, but
     # report_on_exception is disabled so we don't double-log on death.
+    #
+    # Priority resolution matches Sidekiq (component.rb:44-48): explicit
+    # argument, then `config.thread_priority`, then -1. Ruby's default of 0
+    # buys a 100ms timeslice; each negative step halves it, so -1 keeps a
+    # CPU-heavy capsule from starving its siblings for a whole tick.
     def safe_thread(name, priority: nil, &block)
+      resolved = priority || config.thread_priority || DEFAULT_THREAD_PRIORITY
       Thread.new do
         Thread.current.name = name
-        Thread.current.priority = priority || DEFAULT_THREAD_PRIORITY
+        Thread.current.priority = resolved
         Thread.current.report_on_exception = false
         watchdog(name, &block)
       end

data/lib/wurk/configuration.rb

@@ -87,7 +87,16 @@ module Wurk
     #   config.dogstatsd = -> { Datadog::Statsd.new('host', 8125) }
     #
     # Spec: docs/target/sidekiq-pro.md §9.1.
-    attr_accessor :dogstatsd
+    attr_reader :dogstatsd
+
+    # Assignment drops Statsd's resolved-client memo. That memo caches the
+    # "nothing configured" answer too (so the no-client emit path allocates
+    # nothing), which means a builder wired up after the first emit would
+    # otherwise never be picked up.
+    def dogstatsd=(builder)
+      @dogstatsd = builder
+      Wurk::Metrics::Statsd.reset!
+    end
 
     def initialize(options = {})
       @options = deep_dup_defaults.merge(options)
@@ -200,7 +209,7 @@ module Wurk
     end
 
     def redis(idempotent: false, &)
-      PoolCheckout.with(redis_pool, idempotent, &)
+      PoolCheckout.trusted(redis_pool, idempotent, &)
     end
 
     # --- Web dashboard Redis pool ----------------------------------------
@@ -243,6 +252,11 @@ module Wurk
       @directory[name] = instance
     end
 
+    # Memoizes on a miss, and the first miss can land long after boot (an
+    # extension resolved on its first tick), which is why `freeze!` leaves
+    # `@directory` writable: frozen, that lookup raised FrozenError instead of
+    # building the default. `register` — the host-facing half — still refuses
+    # writes past the freeze, so the closed surface is unchanged.
     def lookup(name, default_class = nil)
       @directory[name] ||= default_class&.new
     end
@@ -482,14 +496,39 @@ module Wurk
       mb&.positive? ? mb * 1024 : nil
     end
 
+    # The pre-fork half of `freeze!`, and the only half a forking parent can
+    # run: capsules stay writable until each child has applied its slot
+    # (ChildBoot#apply_slot_to_config) and opened its own Redis pools. What is
+    # left is slot-independent — the options Hash and every capsule's middleware
+    # chains — so the swarm parent settles it once and every child inherits the
+    # result copy-on-write instead of allocating and dirtying its own copy.
+    # Freezing the options here also makes a post-fork option write raise in the
+    # child that wrote it, rather than silently diverging from its siblings.
+    #
+    # `@directory` is deliberately left out — see #lookup.
+    def prepare_for_fork!
+      # The capsule every swarm child configures (ChildBoot reaches for it by
+      # name), and the one a client-only config builds on its first enqueue.
+      # Materialized here so its chains are shared rather than rebuilt N times
+      # — and so `freeze!` can't close `@capsules` around a name that is only
+      # ever resolved later, which turned that first resolution into a
+      # FrozenError on the frozen Hash.
+      default_capsule
+      @capsules.each_value(&:prepare_shared!)
+      @options.freeze
+      @frozen = true
+      self
+    end
+
+    # Guarded on the capsule table, not `@frozen`: a swarm child reaches this
+    # with `prepare_for_fork!` already run in its parent, so `@frozen` is true
+    # while the capsules it has just configured are still open.
     def freeze!
-      return self if @frozen
+      return self if @capsules.frozen?
 
+      prepare_for_fork!
       @capsules.each_value(&:freeze)
       @capsules.freeze
-      @options.freeze
-      @directory.freeze
-      @frozen = true
       self
     end
 

data/lib/wurk/context.rb

@@ -14,7 +14,7 @@ module Wurk
     # context is restored on exit, even if the block raises — safe to nest.
     def self.with(hash)
       prior = Thread.current[KEY]
-      Thread.current[KEY] = (prior || {}).merge(hash)
+      Thread.current[KEY] = prior ? prior.merge(hash) : hash
       yield
     ensure
       Thread.current[KEY] = prior

data/lib/wurk/engine.rb

@@ -25,6 +25,25 @@ module Wurk
     class AssetMount
       PREFIX = '/wurk-assets'
 
+      # Vite fingerprints everything it emits into `assets/`
+      # (`Dashboard-cGKycyd0.js`), so the bytes behind one of those URLs can
+      # never change — cache them for a year and never revalidate. The rest of
+      # the bundle (index.html, the favicons, wurk-manifest.json,
+      # .vite/manifest.json) keeps a stable name across builds, so it must be
+      # revalidated or a client would pin a stale dashboard shell forever.
+      FINGERPRINTED_PREFIX = '/assets/'
+      IMMUTABLE_CACHE_CONTROL = 'public, max-age=31536000, immutable'
+      REVALIDATE_CACHE_CONTROL = 'public, no-cache'
+
+      # Only a served body gets a cache directive. Rack::Files answers more than
+      # file reads: OPTIONS with 200 + Allow, 405 for any other verb
+      # (`ALLOWED_VERBS = %w[GET HEAD OPTIONS]`), and 416 for an unsatisfiable
+      # Range. 405 is cacheable by default (RFC 9110 §15.5.6), so stamping it
+      # `immutable` would let a shared proxy serve "method not allowed" for a
+      # year to everyone behind it.
+      CACHEABLE_METHODS = %w[GET HEAD].freeze
+      CACHEABLE_STATUSES = [200, 206, 304].freeze
+
       def initialize(app, root:)
         @app   = app
         @files = ::Rack::Files.new(root)
@@ -38,7 +57,28 @@ module Wurk
         stripped = path.delete_prefix(PREFIX)
         inner[::Rack::PATH_INFO] = stripped.empty? ? '/' : stripped
         response = @files.call(inner)
-        response[0] == 404 ? @app.call(env) : response
+        return @app.call(env) if response[0] == 404
+
+        stamp_cache_control(response, env, stripped)
+        response
+      end
+
+      private
+
+      # This mount is inserted at index 0 of the HOST app's stack (see the
+      # initializer below), so Rack::ETag and Rack::ConditionalGet never see
+      # these responses — without this the dashboard's fingerprinted bundle
+      # shipped with no cache directive at all and was refetched every load.
+      def stamp_cache_control(response, env, stripped)
+        return unless CACHEABLE_METHODS.include?(env[::Rack::REQUEST_METHOD])
+        return unless CACHEABLE_STATUSES.include?(response[0])
+
+        response[1]['cache-control'] ||=
+          if stripped.start_with?(FINGERPRINTED_PREFIX)
+            IMMUTABLE_CACHE_CONTROL
+          else
+            REVALIDATE_CACHE_CONTROL
+          end
       end
     end
 

data/lib/wurk/errors.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Wurk
+  class Error < StandardError; end
+
+  # Raised inside a worker process to abort the run loop. User code must not
+  # rescue this — the swarm uses it to signal teardown across thread boundaries.
+  # Spec: docs/target/sidekiq-free.md §3.
+  #
+  # Lives in its own file, loaded before everything else, because Processor
+  # freezes its `Thread.handle_interrupt` masks into constants: those are
+  # evaluated the moment `wurk/processor` is required, so this class has to
+  # exist by then.
+  class Shutdown < Interrupt; end
+end

data/lib/wurk/fetcher/reaper.rb

@@ -3,6 +3,7 @@
 require_relative '../component'
 require_relative '../keys'
 require_relative '../middleware/poison_pill'
+require_relative '../timer_loop'
 
 module Wurk
   class Fetcher
@@ -91,13 +92,22 @@ module Wurk
         @thread
       end
 
+      # Bounded at TimerLoop::JOIN_TIMEOUT like every other periodic component.
+      # The full-keyspace sweep is exactly the tick that outlasts a stop: it
+      # SCANs the whole `queue:*|*` keyspace and drains what it finds, so on a
+      # large or slow Redis it can still be running when shutdown lands. Waiting
+      # it out held the entire process's teardown open past the swarm parent's
+      # SHUTDOWN_GRACE — which SIGKILLs the child mid-drain, the one outcome
+      # 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.
       def stop
         @mutex.synchronize do
           @done = true
           @sleeper.signal
         end
-        @thread&.join
-        @thread = nil
+        @thread = nil if @thread&.join(TimerLoop::JOIN_TIMEOUT)
       end
 
       def running?