wurk 1.1.0 → 1.1.2

data/lib/wurk/manager.rb

@@ -38,15 +38,25 @@ module Wurk
     end
 
     def start
-      @workers.each(&:start)
+      workers_snapshot.each(&:start)
     end
 
     def quiet
       return if @done
 
-      @done = true
+      snapshot = @plock.synchronize do
+        @done = true
+        @workers.dup
+      end
+      # Halt fetching for the whole capsule up front: the shared fetcher's drain
+      # flag makes retrieve_work return nil immediately, so a processor can't pull
+      # a fresh job between quiet and its own terminate taking effect. Safe-nav
+      # covers a quiet that lands before Capsule#prepare! materializes the fetcher
+      # (e.g. a signal-driven quiet on a partially-booted launcher) — nothing is
+      # fetching yet, so there is nothing to halt.
+      capsule.fetcher&.terminate
       logger.info { "Terminating quiet threads for #{capsule.name} capsule" }
-      @workers.each(&:terminate)
+      snapshot.each(&:terminate)
     end
 
     # Graceful shutdown: quiet first, then poll for workers to clear.
@@ -57,11 +67,11 @@ module Wurk
       # 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?
+      return if workers_empty?
 
       logger.info { 'Pausing to allow jobs to finish...' }
-      wait_for(deadline) { @workers.empty? }
-      return if @workers.empty?
+      wait_for(deadline) { workers_empty? }
+      return if workers_empty?
 
       hard_shutdown
     ensure
@@ -75,27 +85,38 @@ module Wurk
     # 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.
+    # capsule's concurrency stays constant. If the replacement itself can't be
+    # spawned, crash the child (the swarm respawns it) rather than silently
+    # dropping concurrency. Snapshot under @plock; start the replacement — a
+    # side effect — outside the lock.
     def processor_result(processor, _reason = nil)
-      @plock.synchronize do
+      replacement = @plock.synchronize do
         @workers.delete(processor)
         unless @done
           p = Processor.new(@capsule, &method(:processor_result))
           @workers << p
-          p.start
+          p
         end
       end
+      replacement&.start
+    rescue StandardError => e
+      # Replacement spawn failed (e.g. ThreadError at the OS thread limit).
+      # Silently running one Processor short for the life of the process is
+      # invisible degradation; instead report and crash the child on the main
+      # thread so the swarm respawns it at full concurrency (plan 02 §6).
+      @capsule.config.handle_exception(e, { context: 'Manager could not replace a dead Processor' })
+      main_thread.raise(e)
     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).
+    # Reached when the deadline expired with workers still busy. Atomically
+    # move their in-flight UoWs private→public (Reliable#bulk_requeue) BEFORE
+    # raising Wurk::Shutdown into the threads, so a job killed mid-perform is
+    # re-run once (Sidekiq's at-least-once contract). `job` is read off another
+    # thread, so a Processor can ACK between this map and the requeue — but
+    # bulk_requeue's LREM guard skips the RPUSH on a miss, so a job that
+    # finished in that window is not resurrected onto the public queue.
     def hard_shutdown # rubocop:disable Metrics/AbcSize
-      cleanup = nil
-      @plock.synchronize do
-        cleanup = @workers.dup
-      end
+      cleanup = workers_snapshot
 
       if cleanup.any?
         jobs = cleanup.map(&:job).compact
@@ -103,7 +124,9 @@ module Wurk
         logger.warn { "Terminating #{cleanup.size} busy threads" }
         logger.debug { "Jobs still in progress #{jobs.inspect}" }
 
-        capsule.fetcher.bulk_requeue(jobs)
+        # `&.` like #quiet: a TERM in the pre-prepare! window (traps install
+        # before launcher.run) reaches here with no fetcher built yet.
+        capsule.fetcher&.bulk_requeue(jobs)
       end
 
       cleanup.each(&:kill)
@@ -111,11 +134,28 @@ module Wurk
       # 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? }
+      wait_for(deadline) { workers_empty? }
     end
 
     private
 
+    # The @workers Set is mutated from Processor threads (processor_result)
+    # while the lifecycle methods read/iterate it from the manager thread.
+    # Snapshot under @plock, then act on the copy outside the lock.
+    def workers_snapshot
+      @plock.synchronize { @workers.dup }
+    end
+
+    def workers_empty?
+      @plock.synchronize { @workers.empty? }
+    end
+
+    # Seam over Thread.main: lets processor_result's replacement-failure crash
+    # be unit-tested against a controlled thread instead of the live runner.
+    def main_thread
+      Thread.main
+    end
+
     # 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.

data/lib/wurk/metrics/history.rb

@@ -6,42 +6,42 @@ 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.
+    # wire-compat with Sidekiq's history pane — Sidekiq keys the per-minute
+    # HASH as `j|<YYYYMMDD>|<H>:<M>`, so dashboards (and Sidekiq data migrated
+    # in place) keep resolving against the same key after a drop-in swap.
     #
     # 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|YYYYMMDD|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>-YYYYMMDD-H  HASH per-class hourly histogram, TTL = MID_TERM
     #
-    #   <klass>-YYMMDD-H  HASH per-class hourly histogram, TTL = MID_TERM
+    # We deliberately do NOT write a `H:m0` 10-minute rollup. Its key format
+    # collides with the real minute-0 bucket, so rolling x1..x9 into it turns
+    # that minute's value into a decade total — and the read side (Query) then
+    # sums the minute-0 bucket alongside x1..x9 and double-counts. Sidekiq
+    # itself doesn't keep that rollup (the daily/hourly rollups are commented
+    # out in its ExecutionTracker); Query reads the last N per-minute keys.
     #
-    # 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
+    # Every bucket TTL is set on every write (not NX): as long as a class keeps
+    # running we keep its 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).
+    # The middleware is hot-path — every successful job pays for it. Writes are
+    # pipelined in a single round-trip per job (1 HINCRBY × 2 + 1 EXPIRE per
+    # bucket × 2 buckets = 6 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
+      DATE_FORMAT = '%Y%m%d'           # YYYYMMDD — matches Sidekiq's j| key
 
       def call(_worker, job, _queue)
         klass = job['class']
@@ -74,28 +74,20 @@ module Wurk
 
           ms = duration_ms.to_i
           ms = 0 if ms.negative?
-          buckets = { minute: minute_key(at), rollup: rollup_key(at), hour: hour_key(klass, at) }
+          buckets = { minute: minute_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.
+        # The minute bucket carries per-class `<klass>|p|f|ms` fields; the
+        # hourly bucket is already class-scoped so its fields are bare
+        # `p|f|ms`. Pipeline all 6 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
@@ -115,12 +107,6 @@ module Wurk
                  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}"

data/lib/wurk/metrics/queue_rollup.rb

@@ -3,6 +3,7 @@
 require_relative '../component'
 require_relative '../keys'
 require_relative '../job_record'
+require_relative '../timer_loop'
 require_relative 'rollup'
 
 module Wurk
@@ -45,28 +46,16 @@ module Wurk
 
       def initialize(config)
         @config = config
-        @done = false
-        @mutex = ::Mutex.new
-        @sleeper = ::ConditionVariable.new
-        @tick_interval = config[:metrics_rollup_interval] || DEFAULT_TICK_SECONDS
+        @timer = TimerLoop.new(config[:metrics_rollup_interval] || DEFAULT_TICK_SECONDS)
         @thread = nil
       end
 
       def start
-        @thread ||= safe_thread('queue-metrics') do # rubocop:disable Naming/MemoizedInstanceVariableName
-          wait
-          until @done
-            tick
-            wait
-          end
-        end
+        @thread ||= safe_thread('queue-metrics') { @timer.run { tick } } # rubocop:disable Naming/MemoizedInstanceVariableName
       end
 
       def terminate
-        @mutex.synchronize do
-          @done = true
-          @sleeper.signal
-        end
+        @timer.terminate
       end
 
       # Leader-gated: only the elected leader samples, so N workers don't each
@@ -140,12 +129,6 @@ module Wurk
       rescue ::JSON::ParserError, ::TypeError, ::ArgumentError
         0.0
       end
-
-      def wait
-        @mutex.synchronize do
-          @sleeper.wait(@mutex, @tick_interval) unless @done
-        end
-      end
     end
   end
 end

data/lib/wurk/metrics/rollup.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative '../component'
+require_relative '../timer_loop'
 require_relative 'history'
 
 module Wurk
@@ -53,28 +54,16 @@ module Wurk
 
       def initialize(config)
         @config = config
-        @done = false
-        @mutex = ::Mutex.new
-        @sleeper = ::ConditionVariable.new
-        @tick_interval = config[:metrics_rollup_interval] || DEFAULT_TICK_SECONDS
+        @timer = TimerLoop.new(config[:metrics_rollup_interval] || DEFAULT_TICK_SECONDS)
         @thread = nil
       end
 
       def start
-        @thread ||= safe_thread('metrics-rollup') do # rubocop:disable Naming/MemoizedInstanceVariableName
-          wait
-          until @done
-            tick
-            wait
-          end
-        end
+        @thread ||= safe_thread('metrics-rollup') { @timer.run { tick } } # rubocop:disable Naming/MemoizedInstanceVariableName
       end
 
       def terminate
-        @mutex.synchronize do
-          @done = true
-          @sleeper.signal
-        end
+        @timer.terminate
       end
 
       # Leader-gated: only the elected leader writes the cluster-total series,
@@ -158,12 +147,6 @@ module Wurk
       def floor_min(time)
         (time.to_i / 60) * 60
       end
-
-      def wait
-        @mutex.synchronize do
-          @sleeper.wait(@mutex, @tick_interval) unless @done
-        end
-      end
     end
   end
 end

data/lib/wurk/processor.rb

@@ -2,9 +2,9 @@
 
 require_relative 'component'
 require_relative 'context'
+require_relative 'dead_set'
 require_relative 'job_logger'
 require_relative 'job_retry'
-require_relative 'keys'
 require_relative 'profiler'
 
 module Wurk
@@ -175,8 +175,9 @@ module Wurk
           ack = true
         end
       rescue Wurk::JobRetry::Handled
-        # JobRetry::Skip (subclass) or Handled — retry layer / middleware has
-        # already booked the outcome; safe to ack.
+        # Handled / JobRetry::Skip (incl. Limiter::Rescheduled, where the
+        # limiter middleware already re-enqueued the job) — the retry layer or
+        # a middleware booked the outcome and recorded no retry; ack the UoW.
         ack = true
       rescue Wurk::Shutdown
         # Don't ack — UoW stays in private list and is reclaimed on reboot.
@@ -185,16 +186,15 @@ module Wurk
       end
     end
 
-    # Parse JSON; on failure ZADD the raw payload to the dead set and ack.
+    # Parse JSON; on failure send the raw payload to the dead set (ZADD +
+    # trim, via the shared DeadSet#kill_raw so the malformed path caps the
+    # morgue exactly like send_to_morgue does — spec §31.8/§31.9) and ack.
     # Returns nil to signal "no further processing".
     def parse_or_kill(jobstr, uow)
       Wurk.load_json(jobstr)
     rescue ::JSON::ParserError => e
       handle_exception(e, { context: 'Invalid JSON', jobstr: jobstr })
-      now = ::Process.clock_gettime(::Process::CLOCK_REALTIME)
-      @capsule.redis do |conn|
-        conn.call('ZADD', Keys::DEAD, now.to_s, jobstr)
-      end
+      DeadSet.new.kill_raw(jobstr)
       uow.acknowledge
       nil
     end

data/lib/wurk/profile_set.rb

@@ -21,16 +21,23 @@ module Wurk
 
     def size = @keys.size
 
+    # HMGET of the metadata fields only, pipelined into one round-trip:
+    # HGETALL would also pull each profile's `data` field — the multi-MB
+    # gzipped blob — through Redis for every list render.
+    METADATA_FIELDS = %w[jid type token size elapsed started_at].freeze
+
     def each
       return enum_for(:each) unless block_given?
 
-      Wurk.redis do |conn|
-        @keys.each do |key|
-          raw = conn.call('HGETALL', key)
-          hash = raw.is_a?(Hash) ? raw : raw.each_slice(2).to_h
-          yield ProfileRecord.new(hash) unless hash.empty?
+      rows = Wurk.redis do |conn|
+        conn.pipelined do |pipe|
+          @keys.each { |key| pipe.call('HMGET', key, *METADATA_FIELDS) }
         end
       end
+      rows.each do |values|
+        hash = METADATA_FIELDS.zip(Array(values)).to_h
+        yield ProfileRecord.new(hash) unless hash['jid'].nil?
+      end
     end
   end
 
@@ -39,6 +46,14 @@ module Wurk
   class ProfileRecord
     attr_reader :jid, :type, :token, :size, :elapsed
 
+    # Fetch the stored gzipped blob for a profile storage key ("<token>-<jid>")
+    # straight from Redis, without materializing the whole record — the Profiles
+    # data endpoint streams it to the browser as-is. nil if the HASH is gone.
+    # Owns the `data` HASH-field name so web callers don't hardcode the schema.
+    def self.data_for(key)
+      Wurk.redis { |conn| conn.call('HGET', key, 'data') }
+    end
+
     def initialize(hash)
       @hash = hash
       @jid = hash['jid']
@@ -59,7 +74,7 @@ module Wurk
     # bytes — the web layer streams them straight to the browser with a gzip
     # Content-Encoding. Returns nil if the HASH expired between list and read.
     def data
-      Wurk.redis { |conn| conn.call('HGET', key, 'data') }
+      self.class.data_for(key)
     end
   end
 end

data/lib/wurk/profiler.rb

@@ -50,11 +50,13 @@ module Wurk
         key = profile_key(token, jid)
         gz = gzip(gecko_json)
         with_pool(pool) do |conn|
-          conn.call('HSET', key, 'jid', jid, 'type', type, 'token', token,
-                    'started_at', started_at.to_i, 'elapsed', elapsed_ms.to_i,
-                    'size', gz.bytesize, 'sid', sid.to_s, 'data', gz)
-          conn.call('EXPIRE', key, TTL)
-          conn.call('ZADD', Keys::PROFILES, (now + TTL).to_i, key)
+          conn.pipelined do |pipe|
+            pipe.call('HSET', key, 'jid', jid, 'type', type, 'token', token,
+                      'started_at', started_at.to_i, 'elapsed', elapsed_ms.to_i,
+                      'size', gz.bytesize, 'sid', sid.to_s, 'data', gz)
+            pipe.call('EXPIRE', key, TTL)
+            pipe.call('ZADD', Keys::PROFILES, (now + TTL).to_i, key)
+          end
         end
         key
       end

data/lib/wurk/rails_boot.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module Wurk
+  # Coordinates how Wurk boots inside a Rails host: whether this process should
+  # boot at all, whether it may fork the swarm, and the boot itself. The Railtie
+  # owns only the Rails hooks (config namespace + server_mode initializer +
+  # after_initialize) and delegates every decision and side effect here, so the
+  # boot policy stays pure and unit-testable without the Railtie DSL.
+  # See docs/idea/03-process-model.md for the exact ordering.
+  module RailsBoot
+    module_function
+
+    # Invoked from the `wurk.server_mode` initializer, before config/initializers
+    # load. This Rails process forks the workers, so it IS the server. Enter
+    # server mode now — otherwise the app's `Sidekiq.configure_server` blocks
+    # gate on `config.server?` (still false) and are silently dropped. A process
+    # that won't run workers (skip_boot?, or one that refuses to boot under a
+    # preforking web server) is not a server.
+    def enter_server_mode_if_serving(app = ::Rails.application)
+      return if skip_boot?
+      return if boot_action(app) == :refuse
+
+      Wurk.enter_server_mode
+    end
+
+    # Invoked from after_initialize, once the host app has fully initialized.
+    def boot(app = ::Rails.application)
+      return if skip_boot?
+
+      case boot_action(app)
+      when :fork   then boot_swarm
+      when :embed  then boot_embedded
+      when :refuse then refuse_preforking_boot
+      end
+    end
+
+    # A process that won't run workers isn't a server: skip both server mode
+    # and the swarm boot. Console mode is detected reliably here — the console
+    # command file defines ::Rails::Console before initializers run.
+    def skip_boot?
+      ENV['WURK_DISABLED'] == '1' ||
+        building? ||
+        defined?(::Rails::Console) ||
+        ::Rails.env.test?
+    end
+
+    # What boot should do once skip_boot? is false. Pure — reads env / loaded
+    # constants / host config, no side effects — so the boot decision is
+    # unit-testable without forking:
+    #   :fork   — safe to fork the swarm in the background (the default).
+    #   :refuse — a preforking web server owns process forking here; don't.
+    #   :embed  — host opted into in-process threads-only via embed_in_web.
+    def boot_action(app = ::Rails.application)
+      return :fork unless preforking_web_server?
+
+      embed_in_web?(app) ? :embed : :refuse
+    end
+
+    # Preforking / clustered web servers (Puma cluster, Unicorn, Passenger)
+    # fork their own worker processes. Forking the swarm from `after_initialize`
+    # in one of them is the highest-risk boot path: without app preloading every
+    # server-worker re-runs the hook and forks its own full swarm (N×
+    # oversubscription); with preloading the swarm supervisor ends up entangled
+    # with the server's own fork/signal supervision. Detect the common three.
+    def preforking_web_server?
+      return true if defined?(::PhusionPassenger)
+      return true if defined?(::Unicorn)
+
+      puma_cluster?
+    end
+
+    # Puma only preforks in cluster mode (workers > 0); single mode is threaded
+    # and safe to co-host the swarm. Best-effort: a missed cluster falls through
+    # to the historical fork path; an over-eager match is escapable via
+    # embed_in_web / WURK_DISABLED / running the swarm as its own process.
+    def puma_cluster?
+      return false unless defined?(::Puma)
+
+      count = puma_worker_count
+      count.is_a?(Integer) && count.positive?
+    end
+
+    # Worker count from Puma's parsed CLI config when the server booted it, else
+    # from WEB_CONCURRENCY (the near-universal convention for Puma workers).
+    # Guarded — the accessor and options shape vary across Puma versions.
+    def puma_worker_count
+      cfg = ::Puma.cli_config if ::Puma.respond_to?(:cli_config)
+      workers = cfg&.options&.[](:workers)
+      return workers.to_i if workers
+
+      ENV['WEB_CONCURRENCY']&.to_i
+    rescue StandardError
+      nil
+    end
+
+    # Host opt-in (config/application.rb): run workers as in-process threads
+    # instead of forking, like Sidekiq embedded. Set it in application.rb, not
+    # an initializer — server mode is decided before initializers load.
+    def embed_in_web?(app = ::Rails.application)
+      app.config.wurk&.embed_in_web == true
+    rescue StandardError
+      false
+    end
+
+    def boot_swarm
+      swarm = Wurk::Swarm.new(topology: Wurk.configuration.topology,
+                              shutdown_timeout: Wurk.configuration[:timeout] || Swarm::DEFAULT_SHUTDOWN_TIMEOUT)
+      # Co-hosted in the web process (e.g. Puma single mode): the host owns the
+      # process-wide TERM/INT traps. Installing the swarm's own would hijack
+      # them — a deploy TERM would drain the swarm but never stop the HTTP
+      # server. Let the host keep signal ownership and drain the swarm on its
+      # graceful exit (same contract as boot_embedded).
+      swarm.boot(install_signals: false)
+      at_exit { swarm.shutdown }
+      # supervise must still run somewhere or crashed children never respawn and
+      # memory checks never fire. A background thread keeps the host's main
+      # thread free to serve HTTP.
+      Thread.new do
+        swarm.supervise
+      rescue StandardError => e
+        logger.error { "wurk supervisor thread died: #{e.class}: #{e.message}" }
+      end
+    end
+
+    # Sidekiq-embedded parity: a threads-only worker inside the web process, no
+    # fork. Redis validation failure keeps the host serving HTTP (log + carry
+    # on). at_exit drains on the graceful shutdown the web server runs on TERM.
+    def boot_embedded
+      instance = Wurk::Embedded.new(Wurk.configuration)
+      instance.run
+      at_exit { instance.stop }
+      logger.info { 'wurk: running embedded in the web process (config.wurk.embed_in_web) — threads only, no fork' }
+      instance
+    rescue StandardError => e
+      logger.error { "wurk: embedded boot failed: #{e.class}: #{e.message}" }
+      nil
+    end
+
+    def refuse_preforking_boot
+      logger.warn { <<~MSG }
+        wurk: preforking web server detected (Puma cluster / Unicorn / Passenger).
+        Refusing to fork the worker swarm from a process that forks its own workers.
+        Run the swarm as its own process instead:
+
+            bundle exec wurkswarm    # forked swarm, real parallelism
+            bundle exec wurk         # single process, thread pool
+
+        Or run workers inside this web process (threads only, no fork):
+
+            # config/application.rb
+            config.wurk.embed_in_web = true
+
+        Already running workers elsewhere? Set WURK_DISABLED=1 here to silence this.
+      MSG
+    end
+
+    def logger
+      Wurk.configuration.logger
+    end
+
+    # A build/precompile step must never fork the swarm (#247). The default
+    # Rails Dockerfile runs `SECRET_KEY_BASE_DUMMY=1 ./bin/rails
+    # assets:precompile`; that loads `:environment` → fires after_initialize,
+    # but there's no Redis during `docker build`, so a fork would hang/fail the
+    # build. Same for other env-loading rake tasks (db:prepare, db:migrate).
+    # The real server path is unaffected: `rails server` / `puma` boot through
+    # Rails::Command, not Rake, and don't set the dummy secret.
+    def building?
+      return true if ENV.key?('SECRET_KEY_BASE_DUMMY')
+
+      defined?(::Rake) && ::Rake.application.top_level_tasks.any?
+    rescue StandardError
+      false
+    end
+  end
+end