wurk 1.0.1 → 1.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dc76b5c62f729370d36c966fdbd391aa77bc0cdd9edfc64148024351a52e3191
-  data.tar.gz: 7293ddf887066f715c5263ea9eceb92b5c05bc5a8324651fa857cc4b2486f215
+  metadata.gz: 000bd71bc3b9148d1f4250d32ebe25e300beee9f384b013ed3efabf2f778b1ce
+  data.tar.gz: eec8ea9f45d0ef0ccc0b894515dd6711adf08054757e0475178b45ed8ec81c37
 SHA512:
-  metadata.gz: 0c571b8c549c76c48f12aa7bdc5d249cbcd1fed5f17f08ad96a4621d836e02c9bd587b0d0d22c9e713fa90778a1e48c065063d5d3deb6ca9e109e5bee606430a
-  data.tar.gz: 6c0056e1f4b18f4d63ecb5a5b790fdf2d81ea1cc2a650af8fde6c901181bf858cf602c21b689cd363869cd0301e9981eb3707f2f8a69335f1b9ba7dfa995a355
+  metadata.gz: 7b173cdc536f04367d2eea9b5c549d71f6fe7cbfa27095af3916dc690196421e45356bd663f35a1777a7b340ad57fe6c5b6be24aec3eb57aea3d128de30944a9
+  data.tar.gz: f89b858d93982f20efa5a1d79b8b2230736cf53bdd8b3d95d54fcc4c444bb90dc70822124d8ae80060b2110a68aec8116f807759bccc87b2478cd61872fa890a

data/README.md

@@ -57,6 +57,8 @@ Plus Wurk extras: a worker topology DSL, a Kubernetes liveness/readiness listene
 
 - **[Website](https://developerz-ai.github.io/wurk/)** · **[Wiki / full docs](https://github.com/developerz-ai/wurk/wiki)** — the pitch, install, and the complete guide.
 - **[Getting started & architecture](https://github.com/developerz-ai/wurk/blob/main/docs/idea/01-overview.md)** — how the swarm, manager, fetcher, and processor fit together.
+- **[Starting the worker](https://github.com/developerz-ai/wurk/blob/main/docs/running.md)** — Rails auto-start, the `wurk`/`wurkswarm` runners, and running standalone without Rails.
+- **[Active Job adapter](https://github.com/developerz-ai/wurk/blob/main/docs/active-job.md)** — run `ActiveJob`/`deliver_later` on Wurk with `queue_adapter = :wurk`.
 - **[Migrating from Sidekiq](#migrating-from-sidekiq)** — the one-line swap and what to expect.
 - **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.
 - **[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)**

data/app/controllers/wurk/api_controller.rb

@@ -44,7 +44,7 @@ module Wurk
     def meta
       config = ::Wurk::Web.config
       render json: {
-        read_only: config.read_only?,
+        read_only: config.read_only? || !mutations_authorized?(config),
         read_only_message: config.read_only_message,
         custom_tabs: config.custom_tabs
       }
@@ -294,6 +294,27 @@ module Wurk
 
     private
 
+    # Engine-relative path probed as a representative mutation. Must be a real
+    # mutating route (POST /api/retries — bulk retry/delete/kill) so that a
+    # path-sensitive hook resolves it the same way the Authorization middleware
+    # will resolve the actual mutation. Probing `request.path_info` (which here
+    # is the GET /api/meta path) would let such a hook allow the probe while
+    # still 403ing real mutations, reviving the "button shows, then 403s" gap.
+    MUTATION_PROBE_PATH = '/api/retries'
+
+    # Per-request read-only signal for the SPA. When a registered authorization
+    # hook would reject a *mutating* request for this user (e.g. a viewer role
+    # that may GET but not retry/kill), report `read_only` so the SPA hides the
+    # destructive actions — the Authorization middleware already 403s the
+    # mutation itself, this just stops the buttons from showing. With no hook
+    # registered, `authorized?` is always true, so this is a no-op and the flag
+    # keeps reflecting the global read-only mode. Probes POST on a canonical
+    # mutating path (SAFE_METHODS are GET/HEAD/OPTIONS) so a path-sensitive hook
+    # answers for a real mutation, not the GET /api/meta request carrying it.
+    def mutations_authorized?(config)
+      config.authorized?(request.env, 'POST', MUTATION_PROBE_PATH)
+    end
+
     # Resolves a single entry by "<score>|<jid>" key and applies a whitelisted
     # action. 400 on an unknown action, 404 when the key matches nothing (e.g.
     # the entry was already retried/deleted from another tab).

data/lib/wurk/capsule.rb

@@ -153,13 +153,27 @@ module Wurk
       fetcher
     end
 
+    # Accepts both the CLI/string form (`"name"` / `"name,weight"`) and the
+    # nested-array form Sidekiq's YAML produces for weighted queues
+    # (`:queues: - [critical, 2]` parses to `["critical", 2]`). Without the Array
+    # branch a real sidekiq.yml crashes at boot with `Integer(): " 2]"` (#241).
     def parse_queue_entry(entry)
+      if entry.is_a?(::Array)
+        raise ArgumentError, "queue entry must be `[name]` or `[name, weight]`: `#{entry}`" if entry.size > 2
+
+        return parse_pair_queue_entry(entry[0], entry[1], entry)
+      end
+
       qname, weight_str = entry.to_s.split(',', 2)
-      qname = qname.to_s.strip
+      parse_pair_queue_entry(qname, weight_str, entry)
+    end
+
+    def parse_pair_queue_entry(name, weight, entry)
+      qname = name.to_s.strip
       raise ArgumentError, "queue name cannot be empty: `#{entry}`" if qname.empty?
-      return [qname, 0] if weight_str.nil?
+      return [qname, 0] if weight.nil?
 
-      weight = Integer(weight_str)
+      weight = Integer(weight)
       raise ArgumentError, "queue weight must be > 0: `#{entry}`" if weight <= 0
 
       [qname, weight]

data/lib/wurk/launcher.rb

@@ -48,7 +48,12 @@ module Wurk
     def initialize(config, embedded: false)
       @config = config
       @embedded = embedded
+      # Two separate flags, deliberately. @done = "quieted" (stop fetching, stay
+      # alive, report quiet=true). @stopped = "shutting down" (terminate the
+      # heartbeat loop). Quiet must NOT stop the heartbeat — otherwise a quieted
+      # process never publishes quiet=true and expires out of the live set (#236).
       @done = false
+      @stopped = false
       @managers = config.capsules.values.map { |cap| Manager.new(cap) }
       @poller = build_poller
       @cron_poller = build_cron_poller
@@ -127,6 +132,7 @@ module Wurk
       # CAS-release the cluster lock now (planned shutdown) so a follower can
       # take over immediately instead of waiting out the TTL.
       @leader&.stop
+      stop_heartbeat
       clear_heartbeat
       fire_event(:exit, reverse: true)
     end
@@ -217,11 +223,30 @@ module Wurk
       @health_server&.stop
     end
 
-    # Heartbeat thread loop. `safe_thread` already wraps exceptions; we
-    # exit the loop the moment `stop` flips @done so the thread doesn't
-    # outlive the shutdown.
+    # Terminate the heartbeat loop and wait for it to exit before clear_heartbeat
+    # removes us from the `processes` SET — otherwise a final in-flight beat could
+    # SADD us back right after the SREM. Wakes the thread out of its BEAT_PAUSE
+    # sleep so shutdown isn't delayed up to a full interval.
+    def stop_heartbeat
+      @stopped = true
+      thread = @heartbeat_thread
+      return unless thread
+
+      begin
+        thread.wakeup
+      rescue ThreadError
+        nil
+      end
+      thread.join(BEAT_PAUSE)
+    end
+
+    # Heartbeat thread loop. `safe_thread` already wraps exceptions. Loops on
+    # @stopped — NOT @done — so a *quieted* process keeps beating and publishes
+    # `quiet=true` instead of vanishing from the live set (#236). Only `#stop`
+    # flips @stopped; its `Thread#wakeup` breaks the sleep so the loop re-checks
+    # @stopped and exits without waiting out the interval.
     def start_heartbeat
-      until @done
+      until @stopped
         heartbeat
         sleep BEAT_PAUSE
       end

data/lib/wurk/railtie.rb

@@ -36,7 +36,25 @@ module Wurk
     # and the swarm boot. Console mode is detected reliably here — the console
     # command file defines ::Rails::Console before initializers run.
     def self.skip_boot?
-      ENV['WURK_DISABLED'] == '1' || defined?(::Rails::Console) || ::Rails.env.test?
+      ENV['WURK_DISABLED'] == '1' ||
+        building? ||
+        defined?(::Rails::Console) ||
+        ::Rails.env.test?
+    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 self.building?
+      return true if ENV.key?('SECRET_KEY_BASE_DUMMY')
+
+      defined?(::Rake) && ::Rake.application.top_level_tasks.any?
+    rescue StandardError
+      false
     end
   end
 end

data/lib/wurk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Wurk
-  VERSION = "1.0.1"
+  VERSION = "1.0.3"
 end

data/lib/wurk.rb

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
 # Standalone entry point. Loading "wurk" must work without Rails.
-# The engine and railtie live under "wurk/rails" and are only loaded
-# when the host app opts in.
+# The engine and railtie live under "wurk/rails"; they're auto-loaded at the
+# end of this file when Rails is present (drop-in parity, #246), and stay
+# unloaded otherwise so a no-Rails boot pulls in zero Rails code.
 
 require_relative 'wurk/version'
 require_relative 'wurk/keys'
@@ -280,3 +281,24 @@ require_relative 'wurk/api/fast'
 # fully defined first. compat.rb only redefines names, it does not gate
 # behavior, so trailing the load order is safe.
 require_relative 'wurk/compat'
+
+# Drop-in parity (#246): stock Sidekiq auto-loads its Rails integration when
+# Rails is present (`lib/sidekiq.rb`: `require "sidekiq/rails" if
+# defined?(Rails::Engine)`). Without the equivalent here, a host that follows
+# the README/migration guide with a plain `gem "wurk"` (no `require:`) boots
+# with the engine/railtie unloaded, so the `:wurk` / `:sidekiq` ActiveJob
+# adapter constant is never defined and `config.active_job.queue_adapter =
+# :wurk` raises NameError during the railtie phase. Loading the engine here
+# (idempotent with an explicit `require "wurk/rails"`) closes that gap while
+# keeping standalone, no-Rails boot fully Rails-free.
+#
+# Also gate on ActionDispatch::Routing::RouteSet: the engine's class body calls
+# `isolate_namespace Wurk`, which under railties >= 8.1 eager-reads
+# `ActionDispatch::Routing::RouteSet` to set the engine's @route_set_class.
+# Ecosystem test helpers (sidekiq-cron, …) load `rails/engine/railties` for the
+# railtie API alone — Rails::Engine is defined but ActionDispatch isn't — so a
+# bare `defined?(Rails::Engine)` check would crash with `uninitialized constant
+# Rails::Engine::Configuration::ActionDispatch` mid-`require "sidekiq"`. In a
+# real Rails host both are loaded by `rails/all` before Bundler.require, so the
+# stricter gate is invisible there.
+require_relative 'wurk/rails' if defined?(Rails::Engine) && defined?(::ActionDispatch::Routing::RouteSet)