wurk 1.11.1 → 1.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (72) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +3 -3
  3. data/config/routes.rb +8 -0
  4. data/exe/sidekiq +8 -0
  5. data/exe/wurk +4 -2
  6. data/lib/generators/wurk/install/install_generator.rb +56 -0
  7. data/lib/generators/wurk/install/templates/wurk.rb +5 -3
  8. data/lib/wurk/boot_checks.rb +210 -5
  9. data/lib/wurk/cli.rb +110 -10
  10. data/lib/wurk/configuration.rb +28 -7
  11. data/lib/wurk/fetcher/oom_drain.rb +0 -5
  12. data/lib/wurk/fetcher/orphan_reclaim.rb +108 -0
  13. data/lib/wurk/{middleware → fetcher}/poison_pill.rb +33 -47
  14. data/lib/wurk/fetcher/reaper.rb +46 -65
  15. data/lib/wurk/fetcher/reliable.rb +4 -5
  16. data/lib/wurk/fetcher/self_reconcile.rb +8 -14
  17. data/lib/wurk/fetcher/unit_of_work.rb +1 -1
  18. data/lib/wurk/job_logger.rb +4 -2
  19. data/lib/wurk/job_util.rb +32 -2
  20. data/lib/wurk/launcher.rb +30 -3
  21. data/lib/wurk/leader.rb +1 -8
  22. data/lib/wurk/lua/reclaim_orphan.lua +31 -0
  23. data/lib/wurk/lua.rb +5 -20
  24. data/lib/wurk/manager.rb +27 -1
  25. data/lib/wurk/middleware/timeout.rb +6 -6
  26. data/lib/wurk/preflight/app_scan.rb +182 -0
  27. data/lib/wurk/preflight/command.rb +21 -5
  28. data/lib/wurk/preflight/redis_guard.rb +98 -0
  29. data/lib/wurk/preflight.rb +9 -5
  30. data/lib/wurk/rails_boot.rb +45 -11
  31. data/lib/wurk/redis_options.rb +5 -0
  32. data/lib/wurk/redis_pool.rb +24 -1
  33. data/lib/wurk/sentry.rb +11 -0
  34. data/lib/wurk/swarm.rb +63 -14
  35. data/lib/wurk/unique.rb +12 -2
  36. data/lib/wurk/version.rb +1 -1
  37. data/lib/wurk/web/rack_app.rb +8 -6
  38. data/lib/wurk/web/stats_routes.rb +93 -0
  39. data/lib/wurk.rb +5 -1
  40. data/vendor/assets/dashboard/assets/{ArgsValue-CmaXArv8.js → ArgsValue-BJol9S0s.js} +1 -1
  41. data/vendor/assets/dashboard/assets/{BatchDetail-nc5yePZW.js → BatchDetail-D_zGQ9Sd.js} +1 -1
  42. data/vendor/assets/dashboard/assets/{Batches-DgEcyOZ_.js → Batches-Dt_xC660.js} +1 -1
  43. data/vendor/assets/dashboard/assets/{Busy-CUZncvCy.js → Busy-CWRthsmc.js} +1 -1
  44. data/vendor/assets/dashboard/assets/{Cron-CIZbaaZs.js → Cron-qeGr2YAm.js} +1 -1
  45. data/vendor/assets/dashboard/assets/Dashboard-DQWaAwPA.js +1 -0
  46. data/vendor/assets/dashboard/assets/Dead-D9gOPHtK.js +1 -0
  47. data/vendor/assets/dashboard/assets/{Extension-Doy4bJoA.js → Extension-DONXVLdA.js} +1 -1
  48. data/vendor/assets/dashboard/assets/{FilterBox-C4bO26_d.js → FilterBox-BbB6gXHp.js} +1 -1
  49. data/vendor/assets/dashboard/assets/{FlowDetail-Dh3SJdFh.js → FlowDetail-CrmnVRp0.js} +1 -1
  50. data/vendor/assets/dashboard/assets/{Flows-C5SMRuhq.js → Flows-g4GC8KmE.js} +1 -1
  51. data/vendor/assets/dashboard/assets/{JobDetailModal-Cg6sAsJB.js → JobDetailModal-C86k_1wj.js} +1 -1
  52. data/vendor/assets/dashboard/assets/{Limiters-BIxwDOJM.js → Limiters-zyO-iMlK.js} +1 -1
  53. data/vendor/assets/dashboard/assets/{Metrics-Qp9q0nF8.js → Metrics-Ckq5fNBv.js} +1 -1
  54. data/vendor/assets/dashboard/assets/{NotFound-DwjPxFjU.js → NotFound-C8NnyjlY.js} +1 -1
  55. data/vendor/assets/dashboard/assets/{Profiles-7dabYVe3.js → Profiles-DRl-FXPA.js} +1 -1
  56. data/vendor/assets/dashboard/assets/Queues-DkXWrihA.js +1 -0
  57. data/vendor/assets/dashboard/assets/Retries-CmlojYIy.js +1 -0
  58. data/vendor/assets/dashboard/assets/Scheduled-Cbbpp3xw.js +1 -0
  59. data/vendor/assets/dashboard/assets/{Search-BAsVE2qw.js → Search-LaEpj2fM.js} +1 -1
  60. data/vendor/assets/dashboard/assets/{charts-DZs138BV.js → charts-D_PQLoyc.js} +1 -1
  61. data/vendor/assets/dashboard/assets/index-FBKGtysy.js +141 -0
  62. data/vendor/assets/dashboard/assets/{useResetPageOnEmpty-DxkLZCIm.js → useResetPageOnEmpty-BiwhHqgh.js} +1 -1
  63. data/vendor/assets/dashboard/assets/{utils-B0kQFNE8.js → utils-CnWZzW2L.js} +1 -1
  64. data/vendor/assets/dashboard/index.html +1 -1
  65. data/vendor/assets/dashboard/wurk-manifest.json +2 -2
  66. metadata +37 -26
  67. data/vendor/assets/dashboard/assets/Dashboard-BWmfAook.js +0 -1
  68. data/vendor/assets/dashboard/assets/Dead-CGKsTZHq.js +0 -1
  69. data/vendor/assets/dashboard/assets/Queues-CMg-gyP8.js +0 -1
  70. data/vendor/assets/dashboard/assets/Retries-CNX8ZtTH.js +0 -1
  71. data/vendor/assets/dashboard/assets/Scheduled-ClVBj0nc.js +0 -1
  72. data/vendor/assets/dashboard/assets/index-CMzPFxNE.js +0 -141
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 8153a2b51dcd55ed7857e54b5cd2d533ca0e37f7d443e93f5d2bc33e5be171c4
4
- data.tar.gz: 85ee27f3ee4bb24004aa8d50372f0a555312e3a9607f8b1f644155d24722114e
3
+ metadata.gz: b0817941e1b8f3ff6a7195567e31ac9d22c5039c338d708f9c329ff87f0bbcec
4
+ data.tar.gz: 966125b576e3a775f868ad39224a70ffe6baddf6cbd35eb8b76fc81d63e6b762
5
5
  SHA512:
6
- metadata.gz: 4153f8cfbcd87743ec7b13a9433ffd2fa2238fbe7a4e5aeae3041d1f14fbea8c74a009287b418e934273938bed6ec619c1671bb411ae0de8c979532a0f7f4fca
7
- data.tar.gz: ae57460f22da77be15b74a36a2b870630eeec2c694dab6e25e3e28bdfe4b48cf6264703e0167b6a47cf5d1258b2d96c168b57370a9172a6dbc34dde0ec2d53fe
6
+ metadata.gz: c265be3c09774f76f6a9d560a59434a6800d56c06eadd471c6391a1cad589eb709ba51fdfbf672c14c5ef39c482d2e40a24a9a3a9ad8861d917a2bb5daa01d14
7
+ data.tar.gz: 998f43d63f710cd96b6e413fe20b6c4783149113c2bc1128d74afa3c33a225e75189b65d2515b4cd8351b8d14f02bfd4bfc390a164d9c01914147161e1532559
data/README.md CHANGED
@@ -22,7 +22,7 @@
22
22
 
23
23
  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.
24
24
 
25
- **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).
25
+ **In production:** Wurk runs background work at partner deployments, across many servers, on the fork-based swarm described below. It is not a preview. Teams running billions of jobs a month on Wurk in production recommend it. Those volumes are user-reported; no production throughput numbers are published yet, and what has been measured is in [docs/benchmarks.md](docs/benchmarks.md).
26
26
 
27
27
  **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).
28
28
 
@@ -303,9 +303,9 @@ Wurk is MIT and stays that way. If what you need is a commercial support contrac
303
303
  + gem "wurk"
304
304
  ```
305
305
 
306
- `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).
306
+ `bundle install && restart`. The worker command stays as it was: Wurk ships `sidekiq` and `sidekiqswarm` executables, so `bundle exec sidekiq -C config/sidekiq.yml` in a Procfile or manifest keeps working. 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).
307
307
 
308
- **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.
308
+ **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, pinned to the tag of the Wurk release you run: `gem "sidekiq", github: "developerz-ai/wurk", tag: "v1.13.0", 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.
309
309
 
310
310
  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.
311
311
 
data/config/routes.rb CHANGED
@@ -1,6 +1,14 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  Wurk::Engine.routes.draw do
4
+ # Sidekiq Web's machine-readable routes (free §25.4), upstream's shapes, for
5
+ # uptime checks and scripts. `HEAD /` is declared before `root`, which would
6
+ # otherwise answer it with the SPA shell and never touch Redis.
7
+ match '/', to: Wurk::Web::StatsRoutes, via: :head
8
+ get 'stats', to: Wurk::Web::StatsRoutes, format: false
9
+ get 'stats/queues', to: Wurk::Web::StatsRoutes, format: false
10
+ get 'dashboard/stats', to: Wurk::Web::StatsRoutes, format: false
11
+
4
12
  root to: 'dashboard#index'
5
13
 
6
14
  # JSON APIs consumed by the SPA. Nested under whatever mount the host chose.
data/exe/sidekiq ADDED
@@ -0,0 +1,8 @@
1
+ #!/usr/bin/env ruby
2
+ # frozen_string_literal: true
3
+
4
+ # Drop-in alias for `wurk`. Sidekiq apps start workers with `bundle exec sidekiq
5
+ # -C config/sidekiq.yml` in a Procfile, systemd unit or k8s manifest; this keeps
6
+ # that exact command working after a one-line gem swap. Spec:
7
+ # docs/target/sidekiq-free.md §21.
8
+ load File.expand_path('wurk', __dir__)
data/exe/wurk CHANGED
@@ -5,6 +5,7 @@
5
5
  # Usage: `exe/wurk -C config/wurk.yml` — worker: one process, thread pool
6
6
  # `exe/wurk api --port 7433` — machine HTTP API, runs no jobs
7
7
  # `exe/wurk preflight` / `verify` — read-only cutover checks, run no jobs
8
+ # `exe/wurk boot-check -r .` — boot the app as wurkswarm (or `--runner wurk`) would, then exit (CI)
8
9
 
9
10
  $stdout.sync = true
10
11
  $LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
@@ -20,8 +21,9 @@ begin
20
21
  cli = Wurk::CLI.instance
21
22
  cli.parse
22
23
  case cli.command
23
- when 'api' then cli.run_api
24
- else cli.run
24
+ when 'api' then cli.run_api
25
+ when 'boot-check' then exit(cli.run_boot_check)
26
+ else cli.run
25
27
  end
26
28
  rescue StandardError => e
27
29
  raise e if $DEBUG
@@ -1,15 +1,23 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  require 'rails/generators'
4
+ require 'bundler'
5
+ require 'wurk/version'
4
6
 
5
7
  module Wurk
6
8
  module Generators
7
9
  # `bin/rails g wurk:install`
8
10
  # Writes a config initializer and adds a commented-out mount line to routes.
9
11
  # The host app picks the mount path; the generator suggests /wurk.
12
+ # Reads Gemfile.lock and Procfile to print what a Sidekiq app must change;
13
+ # it edits neither.
10
14
  class InstallGenerator < ::Rails::Generators::Base
11
15
  source_root File.expand_path('templates', __dir__)
12
16
 
17
+ # Sidekiq's own tiers depend on `sidekiq` too, but the swap removes them.
18
+ SIDEKIQ_TIERS = %w[sidekiq sidekiq-pro sidekiq-ent].freeze
19
+ SIDEKIQ_COMMAND = /\bsidekiq(?:swarm)?\b/
20
+
13
21
  def copy_initializer
14
22
  template 'wurk.rb', 'config/initializers/wurk.rb'
15
23
  end
@@ -18,6 +26,27 @@ module Wurk
18
26
  route(%(# mount Wurk::Engine => "/wurk" # uncomment to expose the Wurk dashboard))
19
27
  end
20
28
 
29
+ def show_shim_line
30
+ dependents = sidekiq_dependents
31
+ return if dependents.empty?
32
+
33
+ say <<~SHIM
34
+
35
+ #{dependents.join(', ')} #{dependents.size == 1 ? 'depends' : 'depend'} on the sidekiq gem, which would load real Sidekiq next to Wurk.
36
+ Keep #{dependents.size == 1 ? 'it' : 'them'} by adding the shim to the Gemfile, in place of gem "sidekiq":
37
+ gem "sidekiq", github: "developerz-ai/wurk", tag: "v#{Wurk::VERSION}", glob: "ecosystem/sidekiq-shim/*.gemspec"
38
+ SHIM
39
+ end
40
+
41
+ def show_procfile_runner
42
+ lines = procfile_sidekiq_lines
43
+ return if lines.empty?
44
+
45
+ say "\nProcfile worker lines keep working: wurk ships the sidekiq and sidekiqswarm commands."
46
+ lines.each { |line| say " #{line}" }
47
+ say 'For one process per core, run `bundle exec wurkswarm` with the same flags.'
48
+ end
49
+
21
50
  def show_next_steps
22
51
  say <<~STEPS
23
52
 
@@ -29,6 +58,33 @@ module Wurk
29
58
  docs/authentication.md in the wurk gem's repository
30
59
  STEPS
31
60
  end
61
+
62
+ private
63
+
64
+ def sidekiq_dependents
65
+ specs = locked_specs
66
+ # The shim is the `sidekiq` spec that depends on wurk: already in place.
67
+ return [] if specs.any? { |spec| spec.name == 'sidekiq' && depends_on?(spec, 'wurk') }
68
+
69
+ specs.select { |spec| depends_on?(spec, 'sidekiq') }.map(&:name).uniq
70
+ .reject { |name| SIDEKIQ_TIERS.include?(name) }.sort
71
+ end
72
+
73
+ def locked_specs
74
+ lockfile = File.join(destination_root, 'Gemfile.lock')
75
+ File.file?(lockfile) ? ::Bundler::LockfileParser.new(File.read(lockfile)).specs : []
76
+ end
77
+
78
+ def depends_on?(spec, name)
79
+ spec.dependencies.any? { |dep| dep.name == name }
80
+ end
81
+
82
+ def procfile_sidekiq_lines
83
+ procfile = File.join(destination_root, 'Procfile')
84
+ return [] unless File.file?(procfile)
85
+
86
+ File.readlines(procfile, chomp: true).grep(SIDEKIQ_COMMAND)
87
+ end
32
88
  end
33
89
  end
34
90
  end
@@ -1,8 +1,8 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  # Wurk configuration. Generated by `bin/rails g wurk:install`.
4
- # Full surface area: docs/target/sidekiq-free.md. Coming from Sidekiq?
5
- # See docs/migrate-from-sidekiq.md.
4
+ # Every option: https://github.com/developerz-ai/wurk/blob/main/docs/configuration.md
5
+ # Coming from Sidekiq? https://github.com/developerz-ai/wurk/blob/main/docs/migrate-from-sidekiq.md
6
6
 
7
7
  Wurk.configure_server do |config|
8
8
  # config.redis = { url: ENV.fetch("REDIS_URL", "redis://localhost:6379/0") }
@@ -19,7 +19,9 @@ Wurk.configure_server do |config|
19
19
  # By default Wurk forks one worker process per usable CPU (cgroup quota aware) (set WURK_COUNT, or
20
20
  # SIDEKIQ_COUNT, to override). For full control declare a topology — `flat`
21
21
  # spawns N identical forks; use `slot`s for dedicated queues. Total in-flight
22
- # jobs = forks × concurrency. See docs/idea/03-process-model.md.
22
+ # jobs = forks × concurrency. Topology and sizing:
23
+ # https://github.com/developerz-ai/wurk/blob/main/docs/configuration.md#topology
24
+ # https://github.com/developerz-ai/wurk/blob/main/docs/deployment.md#capacity-and-sizing
23
25
  # config.topology = Wurk::Topology.flat(count: 2, queues: %w[critical default low], concurrency: 10)
24
26
  end
25
27
 
@@ -2,6 +2,7 @@
2
2
 
3
3
  require_relative 'keys'
4
4
  require_relative 'queue_consumers'
5
+ require_relative 'capsule'
5
6
 
6
7
  module Wurk
7
8
  # What a standalone runner says once at boot, after the app loaded. Log only,
@@ -13,13 +14,22 @@ module Wurk
13
14
  MAX_LISTED = 20
14
15
  SUBCLASS = ::Module.instance_method(:<)
15
16
  NAME = ::Module.instance_method(:name)
17
+ UNIQUE_OPTIONS = %w[unique_for unique_until].freeze
18
+ STRICT_ENV = 'WURK_STRICT'
16
19
 
17
20
  module_function
18
21
 
22
+ # `info` is nil when there is no Redis to ask (`wurk boot-check` without
23
+ # `--redis`): only the checks that read the loaded app run then.
19
24
  def run(config, info)
20
- log_backend(config.logger, info)
21
- warn_on_foreign_processes(config)
25
+ if info
26
+ log_backend(config.logger, info)
27
+ warn_on_foreign_processes(config)
28
+ warn_on_unconsumed_framework_queues(config)
29
+ end
22
30
  warn_on_ignored_locks(config.logger)
31
+ warn_on_ignored_unique(config.logger)
32
+ warn_on_client_config_only(config)
23
33
  rescue StandardError => e
24
34
  config.logger.warn { "wurk boot checks skipped: #{e.class}: #{e.message}" }
25
35
  end
@@ -73,18 +83,213 @@ module Wurk
73
83
  end
74
84
  end
75
85
 
86
+ # Only the middleware `unique!` installs reads these options, so without it
87
+ # every push enqueues. Turning it on for the app is a human call, not a
88
+ # boot check's: this only says so.
89
+ def warn_on_ignored_unique(logger)
90
+ return if Wurk::Unique.enabled?
91
+
92
+ classes = job_classes_setting(UNIQUE_OPTIONS)
93
+ return if classes.empty?
94
+
95
+ logger.warn do
96
+ 'These jobs set `unique_for:` or `unique_until:` but unique jobs are not enabled, so the options do ' \
97
+ "nothing and duplicates enqueue: #{listing(classes)}. Enable them once at boot, in an initializer: " \
98
+ '`Sidekiq::Enterprise.unique!`.'
99
+ end
100
+ end
101
+
102
+ # Stock Sidekiq skips a configure_client block in a server without a word,
103
+ # and so does Configuration: an app normally configures both roles. A
104
+ # server where only client blocks were written ran none of them, so the
105
+ # Redis settings, middleware and handlers they hold are all absent here.
106
+ def warn_on_client_config_only(config)
107
+ return unless config.client_config_only?
108
+
109
+ config.logger.warn do
110
+ 'This is a server process, so its configure_client blocks were skipped, and no configure_server block ran: ' \
111
+ 'whatever those blocks set (config.redis, middleware, handlers) does not apply to these workers. Set it ' \
112
+ 'in a configure_server block too, or outside both.'
113
+ end
114
+ end
115
+
116
+ # The topology only shapes what a swarm forks; `wurk` and an embedded
117
+ # worker run one process with the capsules' threads, so a declared one
118
+ # silently does nothing there.
119
+ def warn_on_ignored_topology(config, runner)
120
+ return unless config.topology_assigned?
121
+
122
+ config.logger.warn do
123
+ "config.topology is set, but #{runner} runs a single process and ignores it: its slots' queues and " \
124
+ 'concurrency are not used here. Run wurkswarm to fork it, or set the queues and concurrency on the capsules.'
125
+ end
126
+ end
127
+
128
+ # Rails enqueues its own jobs (mail delivery, Active Storage analysis and
129
+ # purge, Action Mailbox routing) to queues an app never names itself, so
130
+ # they are the ones that go unlistened. Read from Redis, so only with it.
131
+ def warn_on_unconsumed_framework_queues(config)
132
+ wanted = framework_queues
133
+ return if wanted.empty?
134
+
135
+ listened = own_queues(config) | config.redis(idempotent: true) { |conn| QueueConsumers.counts(conn).keys }
136
+ missing = wanted.except(*listened)
137
+ return if missing.empty?
138
+
139
+ config.logger.warn do
140
+ "Rails enqueues to #{listing(missing.map { |queue, what| "#{queue} (#{what})" })}, which neither this " \
141
+ 'process nor any live one listens to, so those jobs wait forever. Add the queues to a worker.'
142
+ end
143
+ end
144
+
145
+ # `{ queue => what Rails sends there }`, for apps whose ActiveJob adapter is Wurk.
146
+ def framework_queues
147
+ return {} unless wurk_active_job?
148
+
149
+ named = {}
150
+ named['mail delivery'] = ::ActionMailer::Base.deliver_later_queue_name if defined?(::ActionMailer::Base)
151
+ named.merge!(framework_queue_set('Active Storage', defined?(::ActiveStorage) && ::ActiveStorage))
152
+ named.merge!(framework_queue_set('Action Mailbox', defined?(::ActionMailbox) && ::ActionMailbox))
153
+ named.compact.to_h { |what, queue| [active_job_queue_name(queue), what] }
154
+ end
155
+
156
+ def framework_queue_set(framework, mod)
157
+ return {} unless mod.respond_to?(:queues) && mod.queues.respond_to?(:to_h)
158
+
159
+ mod.queues.to_h.transform_keys { |kind| "#{framework} #{kind}" }
160
+ end
161
+
162
+ def wurk_active_job?
163
+ return false unless defined?(::ActiveJob::Base)
164
+
165
+ ::ActiveJob::Base.queue_adapter.class.name.to_s.match?(/Wurk|Sidekiq/)
166
+ end
167
+
168
+ def active_job_queue_name(queue)
169
+ prefix = ::ActiveJob::Base.queue_name_prefix
170
+ prefix ? "#{prefix}#{::ActiveJob::Base.queue_name_delimiter}#{queue}" : queue.to_s
171
+ end
172
+
173
+ def own_queues(config)
174
+ queues = config.capsules.each_value.flat_map { |cap| cap.weights.keys }
175
+ return queues unless config.topology_assigned?
176
+
177
+ queues | config.topology.slots.flat_map { |slot| Array(slot.queues).map { |entry| entry.to_s.split(',').first } }
178
+ end
179
+
180
+ def locked_job_classes = job_classes_setting(%w[lock])
181
+
182
+ # Workers, and ActiveJob classes that take `sidekiq_options` (Wurk::Job::Options).
76
183
  # A walk over every class meets classes that redefine these with other arguments
77
184
  # (Faker::Travel::Airport.name takes required keywords), and one such class must
78
185
  # not cost the app this check.
79
- def locked_job_classes
186
+ def job_classes_setting(options)
80
187
  ::ObjectSpace.each_object(::Class).filter_map do |klass|
81
- next unless SUBCLASS.bind_call(klass, Wurk::Worker)
188
+ next unless SUBCLASS.bind_call(klass, Wurk::Worker) || SUBCLASS.bind_call(klass, Wurk::Job::Options)
82
189
 
83
190
  name = NAME.bind_call(klass)
84
- name if name && klass.get_sidekiq_options.key?('lock')
191
+ name if name && klass.get_sidekiq_options.values_at(*options).any?
85
192
  end.sort
86
193
  end
87
194
 
195
+ # The real gem next to Wurk loads both: `Sidekiq::*` is then partly theirs,
196
+ # partly ours. Gems that depend on `sidekiq` pull it in unless the shim gem,
197
+ # which depends on Wurk instead, satisfies the dependency. Runs as Wurk loads.
198
+ def flag_real_sidekiq_gem(logger, specs: ::Gem.loaded_specs, strict: ENV[STRICT_ENV] == '1')
199
+ message = real_sidekiq_message(specs, logger)
200
+ return unless message
201
+ raise Wurk::Error, message if strict
202
+
203
+ logger.error { "#{message} Set #{STRICT_ENV}=1 to refuse to boot instead." }
204
+ end
205
+
206
+ def real_sidekiq_message(specs, logger)
207
+ real = specs['sidekiq']
208
+ return if real.nil? || real.dependencies.any? { |dep| dep.name == 'wurk' }
209
+
210
+ "The bundle holds the real sidekiq #{real.version} gem, so it loads next to Wurk and the process runs " \
211
+ "half on each. Pulled in by: #{sidekiq_dependents(specs)}. Replace it with the shim in the Gemfile: " \
212
+ "gem 'sidekiq', github: 'developerz-ai/wurk', tag: 'v#{Wurk::VERSION}', " \
213
+ "glob: 'ecosystem/sidekiq-shim/*.gemspec'."
214
+ rescue StandardError => e
215
+ logger.warn { "wurk: could not check the bundle for the real sidekiq gem: #{e.class}: #{e.message}" }
216
+ nil
217
+ end
218
+
219
+ def sidekiq_dependents(specs)
220
+ names = specs.each_value.select { |spec| spec.dependencies.any? { |dep| dep.name == 'sidekiq' } }.map(&:name)
221
+ names.empty? ? 'the Gemfile itself' : listing(names.sort)
222
+ end
223
+
224
+ # The role line of a process that forks the topology's children and runs no
225
+ # jobs itself. Its children each run the threads of one slot.
226
+ def log_swarm_role(config, role, ar_pool: active_record_pool)
227
+ slots = config.topology.slots.map do |slot|
228
+ ["#{slot.count} #{slot.count == 1 ? 'process' : 'processes'}", slot.concurrency]
229
+ end
230
+ log_role(config, role, slots, per_process: slots.map(&:last).max, ar_pool: ar_pool)
231
+ rescue StandardError => e
232
+ role_skipped(config.logger, e)
233
+ end
234
+
235
+ # The role line of a process that runs every capsule's threads itself.
236
+ def log_process_role(config, role, ar_pool: active_record_pool)
237
+ capsules = config.capsules.values
238
+ slots = capsules.map { |cap| [capsules.size > 1 ? "capsule #{cap.name}" : '1 process', cap.concurrency] }
239
+ log_role(config, role, slots, per_process: slots.sum(&:last), ar_pool: ar_pool)
240
+ rescue StandardError => e
241
+ role_skipped(config.logger, e)
242
+ end
243
+
244
+ def role_skipped(logger, error)
245
+ logger.warn { "wurk role line skipped: #{error.class}: #{error.message}" }
246
+ end
247
+
248
+ # One line per process: what it is, and how big. `per_process` is the most
249
+ # job threads one process runs, which is what its Active Record pool covers.
250
+ def log_role(config, role, slots, per_process:, ar_pool:)
251
+ sizes = slots.map do |label, threads|
252
+ "#{label} × #{threads} threads (redis pool #{redis_pool_size(config, threads)}, fetch #{threads})"
253
+ end
254
+ config.logger.info { "wurk: #{role}; #{sizes.join(' + ')}#{"; AR pool #{ar_pool}" if ar_pool}" }
255
+ warn_on_small_ar_pool(config.logger, ar_pool, per_process)
256
+ end
257
+
258
+ # DEBUG, not INFO: Wurk logs to stdout, and every `rails runner`, rake task
259
+ # and `wurk preflight --app` boots the app; their stdout is someone's output.
260
+ def log_client_only(logger, reason)
261
+ logger.debug { "wurk: client only (#{reason}); this process enqueues and runs no jobs" }
262
+ end
263
+
264
+ # Capsule#main_pool_size, without building a pool: a swarm parent describes
265
+ # slots whose pools only its children build.
266
+ def redis_pool_size(config, threads)
267
+ config.redis_config[:size] || [threads + Capsule::POOL_HEADROOM, Capsule::MIN_POOL_SIZE].max
268
+ end
269
+
270
+ # Every job thread that touches the database holds a connection; with fewer
271
+ # in the pool the rest wait, then fail with ActiveRecord::ConnectionTimeoutError.
272
+ def warn_on_small_ar_pool(logger, ar_pool, threads)
273
+ return unless ar_pool && ar_pool < threads
274
+
275
+ logger.warn do
276
+ "The Active Record pool holds #{ar_pool} connections but this process runs up to #{threads} job threads, " \
277
+ 'so jobs that use the database wait for a connection and then fail on a timeout. Set `pool:` in ' \
278
+ "config/database.yml to at least #{threads} (plus the web server's threads when jobs run in the web process)."
279
+ end
280
+ end
281
+
282
+ # The pool size the app configured, read without opening a connection; nil
283
+ # without Active Record or a configured database. Rails 8.1 renamed `pool`.
284
+ def active_record_pool
285
+ return unless defined?(::ActiveRecord::Base)
286
+
287
+ db = ::ActiveRecord::Base.connection_db_config
288
+ db.respond_to?(:max_connections) ? db.max_connections : db.pool
289
+ rescue ::ActiveRecord::ActiveRecordError
290
+ nil
291
+ end
292
+
88
293
  def listing(names)
89
294
  extra = names.size - MAX_LISTED
90
295
  names.first(MAX_LISTED).join(', ') + (extra.positive? ? " and #{extra} more" : '')
data/lib/wurk/cli.rb CHANGED
@@ -32,12 +32,13 @@ module Wurk
32
32
  # Subcommands. Bare `wurk` runs the worker — the historical shape, and the
33
33
  # only one the swarm binaries accept — so a subcommand is never anything
34
34
  # but the first argument, and every argument after it is that command's.
35
- COMMANDS = %w[api health].freeze
35
+ COMMANDS = %w[api boot-check health].freeze
36
36
  # Set only across the one re-exec of #load_rails_framework, and removed on arrival.
37
37
  PRELOAD_FIRST_ENV = 'WURK_BOOT_PRELOAD_FIRST'
38
38
  # `bundle exec` loads the binstub in-process, so argv0 is Bundler's executable, and
39
39
  # `ruby -e "load Gem.bin_path(...)"` has `-e` there: the running program can't name it.
40
40
  SWARM_EXECUTABLE = ::File.expand_path('../../exe/wurkswarm', __dir__)
41
+ WURK_EXECUTABLE = ::File.expand_path('../../exe/wurk', __dir__)
41
42
 
42
43
  # A refusal this file raises itself, with nothing a trace would add.
43
44
  class StartupError < ArgumentError; end
@@ -110,6 +111,12 @@ module Wurk
110
111
  ['-s', '--server NAME', :api_server, 'Rack handler to serve with (default: the first installed)']
111
112
  ].freeze
112
113
 
114
+ BOOT_CHECK_OPTION_FLAGS = [
115
+ ['-R', '--redis', :boot_check_redis, 'Also read Redis: version, eviction policy, live peers (read-only)'],
116
+ ['-n', '--runner NAME', :boot_check_runner, 'Boot as wurkswarm (default) or wurk, the runner you deploy']
117
+ ].freeze
118
+ BOOT_CHECK_RUNNERS = %w[wurkswarm wurk].freeze
119
+
113
120
  HEALTH_OPTION_FLAGS = [
114
121
  ['-w', '--window SECONDS', :health_window, 'A heartbeat older than this does not count (default 60)', :to_i],
115
122
  ['-m', '--min COUNT', :health_min, 'Processes on this host that must be beating (default 1)', :to_i],
@@ -118,6 +125,7 @@ module Wurk
118
125
  ].freeze
119
126
 
120
127
  HELP_COMMANDS = "\nCommands:\n " \
128
+ "boot-check Boot as wurkswarm (or --runner wurk) would, then exit; no fork, no fetch (CI)\n " \
121
129
  "health Exit 0 if this host's workers are heartbeating\n " \
122
130
  "preflight Read a live Redis: what will carry over to Wurk (read-only)\n " \
123
131
  "verify Post-cutover check of a live fleet (read-only)\n\nOptions:"
@@ -209,6 +217,8 @@ module Wurk
209
217
  validate_redis!
210
218
  validate_pool_sizes!
211
219
  BootChecks.run(@config, redis_info)
220
+ BootChecks.warn_on_ignored_topology(@config, 'wurk')
221
+ BootChecks.log_process_role(@config, 'wurk')
212
222
  @config[:identity] = identity
213
223
  # Force lazy server-middleware chain so worker threads don't race
214
224
  # against each other constructing it. Spec: Sidekiq::CLI line 104.
@@ -245,15 +255,11 @@ module Wurk
245
255
  # Only the children read it. Rejected here, a typo fails this boot instead of
246
256
  # crash-looping the fleet until the crash-loop exit.
247
257
  Health.options_from_env
248
- if boot_app
249
- load_rails_framework
250
- preload_bundler_groups
251
- boot_application
252
- eager_load_application
253
- end
258
+ boot_swarm_application if boot_app
254
259
  validate_redis!
255
260
  validate_pool_sizes!
256
261
  BootChecks.run(@config, redis_info)
262
+ log_swarm_role
257
263
  @config[:identity] = identity
258
264
  warm_up_process if warmup
259
265
  @swarm = Wurk::Swarm.new(topology: @config.topology, config: @config, exit_on_crash_loop: true,
@@ -270,6 +276,27 @@ module Wurk
270
276
  exit(1) if @swarm.crash_looped?
271
277
  end
272
278
 
279
+ # `wurk boot-check` — the boot of the runner named by --runner up to where it
280
+ # would fork or fetch: #run_swarm's (the default) or #run's, with the same
281
+ # require order, config file and checks, plus what a worker reaches only later
282
+ # (every constant, the routes), so a CI step finds what would crash-loop a
283
+ # deploy. `configure_server` blocks run, since their load errors are the point;
284
+ # no lifecycle event fires (`:startup` included) and periodic loops are never
285
+ # applied. Wurk's Redis pools refuse every command without --redis and every
286
+ # write with it (Preflight::RedisGuard), so boot-time app code cannot touch a
287
+ # real server. Returns the exit code; a boot that raises is the binary's
288
+ # failure report.
289
+ def run_boot_check(boot_app: true)
290
+ require_relative 'preflight/redis_guard'
291
+ Preflight::RedisGuard.install(@config[:boot_check_redis] ? :read_only : :closed, label: 'wurk boot-check')
292
+ enter_server_mode
293
+ boot_check_runner == 'wurk' ? boot_check_as_wurk(boot_app) : boot_check_as_swarm(boot_app)
294
+ logger.info { "wurk boot-check: #{@config[:require]} booted as #{boot_check_runner} would" }
295
+ 0
296
+ ensure
297
+ Preflight::RedisGuard.uninstall
298
+ end
299
+
273
300
  # `wurk health` — see Wurk::HealthProbe. Boots nothing; returns the exit code.
274
301
  def run_health
275
302
  require_relative 'health_probe'
@@ -434,8 +461,54 @@ module Wurk
434
461
 
435
462
  def validate_pool_sizes!
436
463
  @config.capsules.each_pair do |name, cap|
437
- raise StartupError, "Pool size too small for #{name}" if cap.redis_pool.size < cap.concurrency
464
+ size = cap.redis_pool.size
465
+ next if size >= cap.concurrency
466
+
467
+ raise StartupError, "the Redis pool for capsule #{name} holds #{size} connections, fewer than its " \
468
+ "concurrency of #{cap.concurrency}. Set `config.redis = { size: #{cap.concurrency} }` " \
469
+ 'or more, or drop `size:` and Wurk sizes the pool itself (concurrency + 5).'
470
+ end
471
+ end
472
+
473
+ def boot_check_runner = @config[:boot_check_runner] || BOOT_CHECK_RUNNERS.first
474
+
475
+ def boot_check_as_swarm(boot_app)
476
+ Health.options_from_env
477
+ if boot_app
478
+ boot_swarm_application
479
+ boot_check_reach
480
+ end
481
+ validate_pool_sizes!
482
+ BootChecks.run(@config, boot_check_redis_info)
483
+ log_swarm_role
484
+ end
485
+
486
+ def boot_check_as_wurk(boot_app)
487
+ if boot_app
488
+ boot_application
489
+ boot_check_reach
438
490
  end
491
+ validate_pool_sizes!
492
+ BootChecks.run(@config, boot_check_redis_info)
493
+ BootChecks.warn_on_ignored_topology(@config, 'wurk')
494
+ BootChecks.log_process_role(@config, 'boot-check (as wurk)')
495
+ end
496
+
497
+ # What a worker loads only later: every constant, and the routes.
498
+ def boot_check_reach
499
+ eager_load_rails
500
+ draw_routes
501
+ end
502
+
503
+ def boot_check_redis_info
504
+ return unless @config[:boot_check_redis]
505
+
506
+ validate_redis!
507
+ redis_info
508
+ end
509
+
510
+ def log_swarm_role
511
+ BootChecks.log_swarm_role(@config, @command ? "#{@command} (as wurkswarm parent)" : 'wurkswarm parent')
439
512
  end
440
513
 
441
514
  # --- options + config-file --------------------------------------------
@@ -448,6 +521,20 @@ module Wurk
448
521
  COMMANDS.include?(args.first) ? args.shift : nil
449
522
  end
450
523
 
524
+ def boot_swarm_application
525
+ load_rails_framework
526
+ preload_bundler_groups
527
+ boot_application
528
+ eager_load_application
529
+ end
530
+
531
+ # Rails may draw routes only on the first request; a `mount` of a constant
532
+ # only the web process loads must fail here, not on that request.
533
+ def draw_routes
534
+ app = rails_application
535
+ app.reload_routes! if app.respond_to?(:reload_routes!)
536
+ end
537
+
451
538
  def parse_health_options(args)
452
539
  @health_options = {}
453
540
  parser = option_parser(@health_options)
@@ -547,6 +634,7 @@ module Wurk
547
634
  o.separator help_intro if help_intro
548
635
  define_value_flags(o, opts, @command == 'health' ? HEALTH_OPTION_FLAGS : OPTION_FLAGS)
549
636
  define_value_flags(o, opts, API_OPTION_FLAGS) if @command == 'api'
637
+ define_value_flags(o, opts, BOOT_CHECK_OPTION_FLAGS) if @command == 'boot-check'
550
638
  define_meta_flags(o, opts)
551
639
  end
552
640
  end
@@ -627,7 +715,7 @@ module Wurk
627
715
  end
628
716
 
629
717
  def restart_state
630
- { env: ::ENV.to_h, argv: ::ARGV.dup, dir: ::Dir.pwd }
718
+ { env: ::ENV.to_h, argv: [restart_executable, *::ARGV], dir: ::Dir.pwd }
631
719
  end
632
720
 
633
721
  def note_preload_first(first_error)
@@ -644,11 +732,14 @@ module Wurk
644
732
  env = state[:env].merge(PRELOAD_FIRST_ENV => error.message.lines.first.to_s.strip[0, 300])
645
733
  env['BUNDLE_GEMFILE'] ||= ::Bundler.default_gemfile.to_s if defined?(::Bundler)
646
734
  ruby = [::RbConfig.ruby, *('-rbundler/setup' if defined?(::Bundler))]
647
- ::Process.exec(env, *ruby, SWARM_EXECUTABLE, *state[:argv], unsetenv_others: true, chdir: state[:dir])
735
+ ::Process.exec(env, *ruby, *state[:argv], unsetenv_others: true, chdir: state[:dir])
648
736
  rescue ::SystemCallError
649
737
  raise error
650
738
  end
651
739
 
740
+ # The binary that was run: only `wurk boot-check` reaches this with a command.
741
+ def restart_executable = @command ? WURK_EXECUTABLE : SWARM_EXECUTABLE
742
+
652
743
  # The app root for a `-r` that is the app directory or its environment file.
653
744
  def rails_app_root(require_path)
654
745
  path = ::File.expand_path(require_path.to_s)
@@ -688,6 +779,10 @@ module Wurk
688
779
  def eager_load_application
689
780
  return unless preload_app?
690
781
 
782
+ eager_load_rails
783
+ end
784
+
785
+ def eager_load_rails
691
786
  app = rails_application
692
787
  app.eager_load! if app.respond_to?(:eager_load!)
693
788
  end
@@ -747,6 +842,11 @@ module Wurk
747
842
  reason = require_path_problem(@config[:require].to_s)
748
843
  return print_help_and_die(reason) if reason
749
844
 
845
+ runner = @config[:boot_check_runner]
846
+ if runner && !BOOT_CHECK_RUNNERS.include?(runner)
847
+ raise StartupError, "--runner: #{runner.inspect} is not one of #{BOOT_CHECK_RUNNERS.join(', ')}"
848
+ end
849
+
750
850
  %i[concurrency timeout].each do |opt|
751
851
  raise StartupError, "#{opt}: #{@config[opt]} is not a valid value" if @config[opt].to_i <= 0
752
852
  end