wurk 1.9.0 → 1.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e5540591682172d88b9972b1cfc33cfca88c9c88d823c0b50fe80cb3556e8c08
-  data.tar.gz: a19e9d8e68fd2f9f93131cfad4f845595bc95f45aacb65047da452da52916cdd
+  metadata.gz: d9594aab6027f299c217e81215d9d10d5764a5f5533b3e40cde2cd1feaae8a86
+  data.tar.gz: 26161ff0d0ea58e60acbabd550e212ca354824f31434f0d085fabbc9401b8490
 SHA512:
-  metadata.gz: 0d264b8039051e56d2f6cec5aaebb4ce1f99d62ad498a247bece1b6464c316685f43562a76c87ec46f31e846ff6cb6d536f51a11b6d9d06348c32c999d4f2be5
-  data.tar.gz: 9f695bfc7da4e5ad9e24e6874431a115b80bf3dab52f175a11b8f383d0586694b2d611f3137b6698eb896c1c2107ef18e97d33b7877a1a4fd3af60f380f0f47a
+  metadata.gz: 3f2c0b2115f2c7132ab9104e7850f85cf34ac694d4d67b89f615cac765112582506197ae139753489de05f7e6217abb7770129aefbd3125e6dd2be17c04a50ac
+  data.tar.gz: 0f08e99addbeeebefc503916d3a033aa88dd9ccc3ad1f557ce4aabfd43e7809b07392589e0137deff11b358304b435ed798766d89f3d3f205c3a105484a65875

data/README.md

@@ -22,11 +22,11 @@
 
 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.
 
-**In production:** Wurk runs the background work at [developerz.ai](https://developerz.ai) and at partner deployments, across many servers, on the fork-based swarm described below. It is not a preview. Throughput numbers from those deployments are not published yet; what has been measured is in [docs/benchmarks.md](docs/benchmarks.md).
+**In production:** Wurk runs background work at partner deployments, across many servers, on the fork-based swarm described below. It is not a preview. Throughput numbers from those deployments are not published yet; what has been measured is in [docs/benchmarks.md](docs/benchmarks.md).
 
 **At scale:** Wurk is built for fleets, not just for one box. Kubernetes `/live` + `/ready` probes are a config line, not a sidecar; a bearer-scoped [HTTP API](docs/api-http.md) lets non-Ruby services enqueue and inspect; [OpenTelemetry](docs/telemetry.md) traces propagate client → server; per-queue [global concurrency caps](docs/rate-limiting.md) hold cluster-wide limits; and monitoring is the dashboard you already mount — live SSE, charts, no separate stack to run. See [Wurk extras](#wurk-extras).
 
-**AI-managed:** Wurk is a 100% AI-managed project. Every author's issues and pull requests, org members' included, and dependency updates, are triaged, reviewed, merged or closed by the [developerz.ai](https://developerz.ai) maintainer agent, which asks a human only for security reports and license questions, and cuts a release when a shipped fix has waited for one. New features are still built by us, humans and AI together — see [CONTRIBUTING.md](CONTRIBUTING.md) and [AI-maintained](#ai-maintained). The agent always identifies itself as a bot: it works publicly as `developerz-ai[bot]` and marks every comment it posts as bot-made. Its work and its rules are public too — browse the [repository](https://github.com/developerz-ai/wurk) and read the committed policy in [.dz/maintainer/maintainer.yml](.dz/maintainer/maintainer.yml).
+**AI-managed:** Wurk is a 100% AI-managed project. Every author's issues and pull requests, org members' included, and dependency updates, are triaged, reviewed, merged or closed by the [developerz.ai](https://developerz.ai) maintainer agent, which asks a human only for security reports, license questions and breaking changes, and judges weekly whether a release is due. New features are still built by us, humans and AI together — see [CONTRIBUTING.md](CONTRIBUTING.md) and [AI-maintained](#ai-maintained). The agent always identifies itself as a bot: it works publicly as `developerz-ai[bot]` and marks every comment it posts as bot-made. Its work and its rules are public too — browse the [repository](https://github.com/developerz-ai/wurk) and read the committed policy in [.dz/maintainer/maintainer.yml](.dz/maintainer/maintainer.yml).
 
 **On Sidekiq:** Wurk implements Sidekiq's API because it is a genuinely good API. Sidekiq is human-maintained and funds that work through its paid tiers; Wurk is AI-maintained, which is what lets the same surface be free software. Wurk is independent and not affiliated with or endorsed by Sidekiq or its maintainers — see [Why Wurk exists](#why-wurk-exists).
 
@@ -151,7 +151,7 @@ Method, per-invocation records, workload definitions, and the separate `rake ben
 - **[Batches](https://github.com/developerz-ai/wurk/blob/main/docs/batches.md)** · **[Rate limiting](https://github.com/developerz-ai/wurk/blob/main/docs/rate-limiting.md)** · **[Periodic (cron) jobs](https://github.com/developerz-ai/wurk/blob/main/docs/periodic-jobs.md)** · **[Unique jobs](https://github.com/developerz-ai/wurk/blob/main/docs/unique-jobs.md)** — the Pro/Ent features, free.
 - **[Iterable jobs](https://github.com/developerz-ai/wurk/blob/main/docs/iterable-jobs.md)** · **[Middleware](https://github.com/developerz-ai/wurk/blob/main/docs/middleware.md)** · **[Encryption](https://github.com/developerz-ai/wurk/blob/main/docs/encryption.md)** · **[Profiling](https://github.com/developerz-ai/wurk/blob/main/docs/profiling.md)**
 - **[Data API](https://github.com/developerz-ai/wurk/blob/main/docs/api.md)** · **[Metrics](https://github.com/developerz-ai/wurk/blob/main/docs/metrics.md)** — inspect queues and jobs from Ruby; job metrics, Statsd/DogStatsD, custom history.
-- **[Sentry](https://github.com/developerz-ai/wurk/blob/main/docs/sentry.md)** — built-in error reporting (`sentry-sidekiq` can't be installed alongside Wurk); terminal-failure-only reports, per-job scope, no job args.
+- **[Sentry](https://github.com/developerz-ai/wurk/blob/main/docs/sentry.md)** — built-in error reporting (`sentry-sidekiq` needs the `sidekiq` shim gem; prefer this); terminal-failure-only reports, per-job scope, no job args.
 - **API reference (parity specs):** [Sidekiq OSS](https://github.com/developerz-ai/wurk/blob/main/docs/target/sidekiq-free.md) · [Pro](https://github.com/developerz-ai/wurk/blob/main/docs/target/sidekiq-pro.md) · [Enterprise](https://github.com/developerz-ai/wurk/blob/main/docs/target/sidekiq-ent.md) — the authoritative surface Wurk matches exactly.
 - **[Authentication & authorization](https://github.com/developerz-ai/wurk/blob/main/docs/authentication.md)** — gate the dashboard behind Devise/Warden, Sorcery, Basic auth, or a token; role-based read/write; CSRF.
 - **[Securing the dashboard](https://github.com/developerz-ai/wurk/blob/main/docs/dashboard.md)** · **[Metrics history](https://github.com/developerz-ai/wurk/blob/main/docs/metrics-history.md)**
@@ -167,7 +167,7 @@ Method, per-invocation records, workload definitions, and the separate `rake ben
 
 The full test suite also runs as a non-required `compat` workflow job across Ruby 3.2.x and the newest Ruby on the current Rails series, the oldest supported Rails series on the newest Ruby, and Valkey 8 as a drop-in store alongside Redis 7.x.
 
-JRuby, TruffleRuby, and Windows fall back to threads-only mode (no fork) — behaviorally equivalent to stock Sidekiq.
+Without `fork` (JRuby, TruffleRuby, Windows; untested in CI) only the single-process `wurk` runner and `config.wurk.embed_in_web` apply: `wurkswarm` and the railtie's swarm have no fallback.
 
 ## Running the workers
 
@@ -284,13 +284,13 @@ Infrastructure this basic should be free software. A Rails app shouldn't need a
 What has made that hard is maintenance: someone has to be paid to do it. Sidekiq funds a decade of *human* maintenance through its paid tiers, which is an honest trade. Wurk makes a different one — it is maintained **by AI**: every author's issues and pull requests, the team's own included, and dependency updates, are handled end to end by a maintainer agent, and the implementation, parity suite, docs, and benchmarks are written and kept current by AI agents working with the team, which still builds the features and cuts the releases. A fix, a doc update, or a version bump is no longer somebody's week, which is what makes it practical to:
 
 - ship the entire Pro + Enterprise surface with no tier, no flag gate, and no license check;
-- keep parity honest mechanically rather than by hand — an independently written parity oracle suite, pinned to a documented Sidekiq revision, plus sidekiq-cron's upstream suite running against Wurk on every push ([docs/idea/14-ecosystem-compat.md](https://github.com/developerz-ai/wurk/blob/main/docs/idea/14-ecosystem-compat.md) tracks the rest);
+- keep parity honest mechanically rather than by hand — an independently written parity oracle suite, pinned to a documented Sidekiq revision, plus the upstream suites of sidekiq-cron, sidekiq-unique-jobs, sidekiq-failures and sentry-sidekiq running against Wurk on every push ([docs/idea/14-ecosystem-compat.md](https://github.com/developerz-ai/wurk/blob/main/docs/idea/14-ecosystem-compat.md) tracks the rest);
 - keep adding surface Sidekiq doesn't have — the [Wurk extras](#wurk-extras) above landed as one release;
 - hold ourselves to published numbers instead of adjectives — the measured comparison against stock Sidekiq is published [as measured](docs/benchmarks.md), including the unflattering ones, and `rake bench:vs_sidekiq` reproduces it. It is a published measurement, not a per-release CI run.
 
 DHH makes the broader version of this argument in [Let the agents democratize open source](https://world.hey.com/dhh/let-the-agents-democratize-open-source-9fd630a9): open source fought for everyone's right to change the software they run, and refusing agent-written code re-erects the gate it spent decades tearing down — "all programmers are equal, but some programmers are more equal than others." His subject is contributions; ours is maintenance, which is the same economics from the other end. The reason a licence key guards batches and cron is not that the code is precious, it's that somebody had to be paid to keep it working. Drop that cost and the tier stops being necessary.
 
-What makes it work in practice is that the agents run inside machinery built to check them. The parity oracle above is a merge-blocking gate, not decoration; sidekiq-cron's upstream suite runs against Wurk in CI and reports on PRs, but it is not a required check and never gates a merge; the `rake bench` PR regression check flags deltas past a noise-adjusted threshold as an advisory comment; and the published benchmark numbers are one-off historical measurements, reproduced on demand rather than enforced in CI. The release gate has never once let an unverified gem reach RubyGems. Agents supply the pace, the gates supply the certainty — and when a gate does catch something, the fix is to make that class of mistake structurally impossible rather than to slow the agents down. The release lane derives its own tag from `Wurk::VERSION` so the two can't drift apart; [RELEASE.md](https://github.com/developerz-ai/wurk/blob/main/RELEASE.md) walks through it.
+What makes it work in practice is that the agents run inside machinery built to check them. The parity oracle above is a merge-blocking gate, not decoration; four gems' upstream suites run against Wurk in CI and report on PRs, but they are not required checks and never gate a merge; the `rake bench` PR regression check flags deltas past a noise-adjusted threshold as an advisory comment; and the published benchmark numbers are one-off historical measurements, reproduced on demand rather than enforced in CI. The release gate has never once let an unverified gem reach RubyGems. Agents supply the pace, the gates supply the certainty — and when a gate does catch something, the fix is to make that class of mistake structurally impossible rather than to slow the agents down. The release lane derives its own tag from `Wurk::VERSION` so the two can't drift apart; [RELEASE.md](https://github.com/developerz-ai/wurk/blob/main/RELEASE.md) walks through it.
 
 Wurk is MIT and stays that way. If what you need is a commercial support contract and a human on the other end of an email, buying that is a perfectly good answer.
 
@@ -303,9 +303,9 @@ Wurk is MIT and stays that way. If what you need is a commercial support contrac
 + gem "wurk"
 ```
 
-`bundle install && restart`. Wurk reads and writes the same Redis schema, so there is no data migration: Wurk picks up the queues, schedules, retries, batches and periodic loops Sidekiq left behind. Running Sidekiq and Wurk workers against one Redis *at the same time* is not tested yet, so a live production move is a **drain cutover** (stop Sidekiq's workers, confirm nothing is in flight, start Wurk), with a matching rollback; the [production cutover](https://github.com/developerz-ai/wurk/blob/main/docs/migrate-from-sidekiq.md#9-production-cutover) section has every step and command. sidekiq-cron's upstream suite runs against Wurk in the [`ecosystem` CI job](https://github.com/developerz-ai/wurk/blob/main/.github/workflows/ecosystem.yml) (see [`test/ecosystem/`](https://github.com/developerz-ai/wurk/tree/main/test/ecosystem)). sidekiq-unique-jobs, sidekiq-scheduler, sidekiq-status, sidekiq-failures and sidekiq-throttled are target additions tracked in [docs/idea/14-ecosystem-compat.md](https://github.com/developerz-ai/wurk/blob/main/docs/idea/14-ecosystem-compat.md).
+`bundle install && restart`. Wurk reads and writes the same Redis schema, so there is no data migration: Wurk picks up the queues, schedules, retries, batches and periodic loops Sidekiq left behind. Running Sidekiq and Wurk workers against one Redis *at the same time* is not tested yet, so a live production move is a **drain cutover** (stop Sidekiq's workers, confirm nothing is in flight, start Wurk), with a matching rollback; the [production cutover](https://github.com/developerz-ai/wurk/blob/main/docs/migrate-from-sidekiq.md#9-production-cutover) section has every step and command. The upstream suites of sidekiq-cron, sidekiq-unique-jobs, sidekiq-failures and sentry-sidekiq run against Wurk in the [`ecosystem` CI job](https://github.com/developerz-ai/wurk/blob/main/.github/workflows/ecosystem.yml) (see [`test/ecosystem/`](https://github.com/developerz-ai/wurk/tree/main/test/ecosystem)). sidekiq-scheduler, sidekiq-status and sidekiq-throttled are target additions tracked in [docs/idea/14-ecosystem-compat.md](https://github.com/developerz-ai/wurk/blob/main/docs/idea/14-ecosystem-compat.md).
 
-**Keeping a `sidekiq-*` add-on gem?** Those gems declare `add_dependency "sidekiq"`, which would reinstall real Sidekiq next to Wurk. Satisfy it with Wurk's git-only [`sidekiq` shim gem](https://github.com/developerz-ai/wurk/tree/main/ecosystem/sidekiq-shim) instead: `gem "sidekiq", github: "developerz-ai/wurk", glob: "ecosystem/sidekiq-shim/*.gemspec"`. Only sidekiq-cron is exercised that way on every PR; treat the others as untested.
+**Keeping a `sidekiq-*` add-on gem?** Those gems declare `add_dependency "sidekiq"`, which would reinstall real Sidekiq next to Wurk. Satisfy it with Wurk's git-only [`sidekiq` shim gem](https://github.com/developerz-ai/wurk/tree/main/ecosystem/sidekiq-shim) instead: `gem "sidekiq", github: "developerz-ai/wurk", glob: "ecosystem/sidekiq-shim/*.gemspec"`. Only sidekiq-cron, sidekiq-unique-jobs, sidekiq-failures and sentry-sidekiq are exercised that way, by the `ecosystem` workflow; treat the others as untested.
 
 Full walkthrough — config side-by-side, the Redis key/`sidekiq_options` mapping, known incompatibilities, moving sidekiq-cron schedules over (`rake wurk:import:cron`), and the production cutover and rollback playbook: **[docs/migrate-from-sidekiq.md](https://github.com/developerz-ai/wurk/blob/main/docs/migrate-from-sidekiq.md)**. On the night, keep the **[incident runbook](https://github.com/developerz-ai/wurk/blob/main/docs/runbook.md)** open.
 
@@ -332,7 +332,7 @@ TypeScript end to end, MIT, and as measured about its own claims as this file is
 | Dependabot | driven to green and merged |
 | an issue or pull request by anyone with write access (org members, collaborators) | handled like anyone's: triaged, reviewed, driven to green, merged |
 | an outside change to CI, release or publish automation | declined: members maintain the pipeline that publishes the gem |
-| a breaking change | the bot's call, not a human's; a change that breaks the drop-in Sidekiq contract is declined, since a revert cannot take that promise back |
+| a breaking change | a human decides; a change that breaks the drop-in Sidekiq contract is declined, since a revert cannot take that promise back |
 
 Releases follow the work, not a calendar. A weekday checkup asks whether a shipping fix has merged and nobody has released it. When one has, the bot files a release request, its coding fleet opens the `Wurk::VERSION` bump PR, and merging that PR publishes the gem ([RELEASE.md](RELEASE.md)). The bot's policy is committed in [`.dz/maintainer/maintainer.yml`](.dz/maintainer/maintainer.yml).
 

data/app/controllers/wurk/api_controller.rb

@@ -62,7 +62,10 @@ module Wurk
     end
 
     def queues
-      render json: ::Wurk::Stats.new.queue_summaries.map { |q| ::Wurk::Api::Serializers.queue_summary(q) }
+      consumers = ::Wurk.redis(idempotent: true) { |conn| ::Wurk::QueueConsumers.counts(conn) }
+      render json: ::Wurk::Stats.new.queue_summaries.map { |q|
+        ::Wurk::Api::Serializers.queue_summary(q).merge(consumers: consumers.fetch(q.name, 0))
+      }
     end
 
     def queue

data/app/controllers/wurk/dashboard_controller.rb

@@ -18,14 +18,18 @@ module Wurk
   # Vite dev server (default :5173) so contributors get HMR without
   # rebuilding the bundle on every change.
   class DashboardController < ApplicationController
+    # bin/dev exports VITE_PORT and vite.config.ts binds it, with strictPort, so this
+    # has to read the same variable or an overridden port answers every page with a 500.
+    def self.vite_dev_url
+      "http://localhost:#{ENV.fetch('VITE_PORT', '5173')}#{VITE_ASSET_BASE}"
+    end
+
     # Vite serves the dev shell under its `base` (vite.config.ts), which is the
     # same path the engine mounts assets at — so derive these from
     # AssetMount::PREFIX to keep the Ruby side in lockstep. Fetching the server
     # root instead returns Vite's "did you mean /wurk-assets/" hint page, not the
     # shell (issue #181).
-    VITE_DEV_HOST = 'http://localhost:5173'
     VITE_ASSET_BASE = "#{::Wurk::Engine::AssetMount::PREFIX}/".freeze # "/wurk-assets/"
-    VITE_DEV_URL = "#{VITE_DEV_HOST}#{VITE_ASSET_BASE}".freeze
     INDEX_REL_PATH = ['vendor', 'assets', 'dashboard', 'index.html'].freeze
     # The SPA mount point, matched without its closing `>` so the locale hint
     # appends to whatever attributes the shell already carries.
@@ -115,11 +119,12 @@ module Wurk
     end
 
     def fetch_vite_dev_shell
-      uri = ::URI.parse(VITE_DEV_URL)
+      uri = ::URI.parse(self.class.vite_dev_url)
       rewrite_dev_asset_urls(::Net::HTTP.get(uri))
     rescue ::StandardError => e
-      raise "Wurk dashboard: cannot reach Vite dev server at #{VITE_DEV_URL} " \
-            "(#{e.class}: #{e.message}). Run `bin/rake frontend:dev` from the gem root."
+      raise "Wurk dashboard: cannot reach Vite dev server at #{self.class.vite_dev_url} " \
+            "(#{e.class}: #{e.message}). Run `bin/rake frontend:dev` from the gem root, or `bin/dev`, " \
+            'with the same VITE_PORT.'
     end
 
     # The shell's entry URLs (`src="/wurk-assets/@vite/client"`,
@@ -130,7 +135,7 @@ module Wurk
     # `server.origin` covers runtime-generated asset URLs but not these entry
     # tags, so rewrite them here.
     def rewrite_dev_asset_urls(html)
-      html.gsub(/(["'])#{::Regexp.escape(VITE_ASSET_BASE)}/, "\\1#{VITE_DEV_URL}")
+      html.gsub(/(["'])#{::Regexp.escape(VITE_ASSET_BASE)}/, "\\1#{self.class.vite_dev_url}")
     end
 
     def read_built_index

data/exe/wurk

@@ -4,12 +4,18 @@
 # Standalone runner. Does NOT load the Rails engine.
 # Usage: `exe/wurk -C config/wurk.yml`     — worker: one process, thread pool
 #        `exe/wurk api --port 7433`        — machine HTTP API, runs no jobs
+#        `exe/wurk preflight` / `verify`   — read-only cutover checks, run no jobs
 
 $stdout.sync = true
 $LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
 
 require 'wurk'
 
+if %w[preflight verify].include?(ARGV.first)
+  require 'wurk/preflight/command'
+  exit Wurk::Preflight::Command.run(ARGV.dup)
+end
+
 begin
   cli = Wurk::CLI.instance
   cli.parse
@@ -20,7 +26,6 @@ begin
 rescue StandardError => e
   raise e if $DEBUG
 
-  warn "wurk: #{e.message}"
-  warn e.backtrace.join("\n")
+  Wurk::CLI.report_failure('wurk', e)
   exit 1
 end

data/exe/wurkswarm

@@ -17,7 +17,6 @@ begin
 rescue StandardError => e
   raise e if $DEBUG
 
-  warn "wurkswarm: #{e.message}"
-  warn e.backtrace.join("\n")
+  Wurk::CLI.report_failure('wurkswarm', e)
   exit 1
 end

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

@@ -17,6 +17,18 @@ module Wurk
       def insert_mount_line
         route(%(# mount Wurk::Engine => "/wurk"  # uncomment to expose the Wurk dashboard))
       end
+
+      def show_next_steps
+        say <<~STEPS
+
+          Next steps:
+            1. Set the queue adapter if you use Active Job: config.active_job.queue_adapter = :wurk
+            2. Start workers: bundle exec wurkswarm (or bundle exec wurk for one process)
+            3. To use the dashboard, uncomment the mount line in config/routes.rb.
+               It has no login of its own, so put it behind authentication first:
+               docs/authentication.md in the wurk gem's repository
+        STEPS
+      end
     end
   end
 end

data/lib/sidekiq/web.rb

@@ -2,3 +2,8 @@
 
 # Drop-in require path (see lib/sidekiq.rb). Wurk loads this surface whole.
 require 'wurk'
+
+# Extension renderer dependencies, deferred on the worker path (web/extension.rb).
+# Loaded here for a helper called outside a request, as unique-jobs' specs do.
+require 'cgi'
+require 'erb'

data/lib/wurk/boot_checks.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative 'keys'
+require_relative 'queue_consumers'
+
+module Wurk
+  # What a standalone runner says once at boot, after the app loaded. Log only,
+  # and never allowed to stop a boot: none of this changes behaviour by backend,
+  # version or peers.
+  module BootChecks
+    # Oldest version each non-Redis backend has been run against.
+    TESTED_FLOORS = { 'dragonfly' => '1.34.0', 'valkey' => '8.0.0' }.freeze
+    MAX_LISTED = 20
+    SUBCLASS = ::Module.instance_method(:<)
+    NAME = ::Module.instance_method(:name)
+
+    module_function
+
+    def run(config, info)
+      log_backend(config.logger, info)
+      warn_on_foreign_processes(config)
+      warn_on_ignored_locks(config.logger)
+    rescue StandardError => e
+      config.logger.warn { "wurk boot checks skipped: #{e.class}: #{e.message}" }
+    end
+
+    def backend(info)
+      return ['dragonfly', info['dragonfly_version'].to_s.delete_prefix('df-v')] if info['dragonfly_version']
+      return ['valkey', info['valkey_version'].to_s] if info['valkey_version']
+
+      ['redis', info['redis_version'].to_s]
+    end
+
+    def log_backend(logger, info)
+      name, version = backend(info)
+      logger.info { "Wurk #{Wurk::VERSION} on #{name} #{version}" }
+      floor = TESTED_FLOORS[name]
+      return unless floor && ::Gem::Version.correct?(version) && ::Gem::Version.new(version) < ::Gem::Version.new(floor)
+
+      logger.warn { "#{name} #{version} is older than the oldest version Wurk is tested against (#{floor})." }
+    end
+
+    # Both runtimes share `processes` and the same queues, so a mix is safe only
+    # if it is deliberate. Wurk's heartbeat always carries `cores`; stock does not.
+    def warn_on_foreign_processes(config)
+      foreign = process_infos(config).reject { |_, info| info.nil? || ::JSON.parse(info).key?('cores') }.map(&:first)
+      return if foreign.empty?
+
+      config.logger.warn do
+        "Live processes that are not Wurk share this Redis: #{listing(foreign)}. " \
+          'They fetch from the same queues. If this is not a deliberate rolling cutover, stop them.'
+      end
+    end
+
+    def process_infos(config)
+      config.redis(idempotent: true) do |conn|
+        ids = conn.call('SMEMBERS', Keys::PROCESSES)
+        ids.empty? ? [] : ids.zip(conn.pipelined { |pipe| ids.each { |id| pipe.call('HGET', id, 'info') } })
+      end
+    end
+
+    # Without the gem's middleware the option does nothing: the "unique" job
+    # simply enqueues twice. Only classes the app has loaded by now are seen.
+    def warn_on_ignored_locks(logger)
+      return if defined?(::SidekiqUniqueJobs)
+
+      classes = locked_job_classes
+      return if classes.empty?
+
+      logger.warn do
+        'These jobs set `lock:` but sidekiq-unique-jobs is not loaded, so the option does nothing and ' \
+          "duplicates will run: #{listing(classes)}. Keep the gem, or move them to `unique_for:`."
+      end
+    end
+
+    # A walk over every class meets classes that redefine these with other arguments
+    # (Faker::Travel::Airport.name takes required keywords), and one such class must
+    # not cost the app this check.
+    def locked_job_classes
+      ::ObjectSpace.each_object(::Class).filter_map do |klass|
+        next unless SUBCLASS.bind_call(klass, Wurk::Worker)
+
+        name = NAME.bind_call(klass)
+        name if name && klass.get_sidekiq_options.key?('lock')
+      end.sort
+    end
+
+    def listing(names)
+      extra = names.size - MAX_LISTED
+      names.first(MAX_LISTED).join(', ') + (extra.positive? ? " and #{extra} more" : '')
+    end
+  end
+end

data/lib/wurk/capsule.rb

@@ -53,6 +53,8 @@ module Wurk
     #   %w[high default low]        → mode :strict,   weights all 0
     #   %w[high,3 default,2 low,1]  → mode :weighted, weights {q=>w}
     #   %w[a,1 b,1 c,1]             → mode :random,   weights all 1
+    #   %w[a,2 b]                   → mode :weighted, unweighted b fetched as if 1
+    #   %w[a,0 b,0]                 → mode :strict, 0 being the same as no weight
     # `@queues` is expanded by weight so a uniform shuffle gives weighted
     # fairness (e.g. ["high","high","high","default","default","low"]).
     def queues=(val)
@@ -188,6 +190,16 @@ module Wurk
       @pools.clear
     end
 
+    # The fork-path form: closes idle sockets but keeps every pool usable, for a
+    # parent whose own threads may be mid-checkout.
+    def reload_redis_pools!
+      @pools.each_value(&:reload!)
+    end
+
+    def redis_pools_built?
+      !@pools.empty?
+    end
+
     def redis(idempotent: false, &)
       PoolCheckout.with(redis_pool, idempotent, &)
     end
@@ -229,19 +241,32 @@ module Wurk
       copy = server_middleware
       return copy if frozen?
 
-      @config.server_middleware.entries.each do |entry|
+      global = @config.server_middleware.entries
+      global.each_with_index do |entry, index|
         next if @server_middleware_seen.include?(entry.klass)
 
         @server_middleware_seen << entry.klass
-        next if copy.exists?(entry.klass)
-
-        rebound = entry.dup
-        rebound.config = self
-        copy.entries << rebound
+        adopt_server_middleware(copy, entry, global.drop(index + 1)) unless copy.exists?(entry.klass)
       end
       copy
     end
 
+    def adopt_server_middleware(copy, entry, followers)
+      rebound = entry.dup
+      rebound.config = self
+      copy.entries.insert(refresh_position(copy, followers), rebound)
+    end
+
+    # Ahead of the first entry that follows it in the global chain, so a late
+    # `prepend` still wraps what it was prepended to. -1 appends.
+    def refresh_position(copy, followers)
+      followers.each do |follower|
+        position = copy.entries.index { |entry| entry.klass == follower.klass }
+        return position if position
+      end
+      -1
+    end
+
     # 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
@@ -276,7 +301,7 @@ module Wurk
       return [qname, 0] if weight.nil?
 
       weight = Integer(weight)
-      raise ArgumentError, "queue weight must be > 0: `#{entry}`" if weight <= 0
+      raise ArgumentError, "queue weight must not be negative: `#{entry}`" if weight.negative?
 
       [qname, weight]
     end
@@ -295,7 +320,7 @@ module Wurk
     def expand_by_weight(parsed, mode)
       return parsed.map(&:first) if %i[strict random].include?(mode)
 
-      parsed.flat_map { |q, w| [q] * w }
+      parsed.flat_map { |q, w| [q] * [w, 1].max }
     end
 
     # `config.redis = { size: N }` pins the main pool at N; otherwise