wurk 1.0.0 → 1.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 774727bf58b55972fbc4ace533c90803233ad6e4a42d6e8b8cec0f464972bae3
-  data.tar.gz: e06ddec0e9138bb50be07a50184d46b500affe8f9212d5aaa290be75b35a73da
+  metadata.gz: 000bd71bc3b9148d1f4250d32ebe25e300beee9f384b013ed3efabf2f778b1ce
+  data.tar.gz: eec8ea9f45d0ef0ccc0b894515dd6711adf08054757e0475178b45ed8ec81c37
 SHA512:
-  metadata.gz: e0f7924f14f94fc5f4143be95389f461c988d2772cb05d4502a77d9959431420d4392a5dc7d9d390038fa372da0b492b4f0d095bb566d6abc0fc4a6bf3fa5605
-  data.tar.gz: 8cc09f2445d8e75f40cdc06ac84597748de5e2a7cbfd99ec9ad062e88ca5df03f7be7e117c221533c796304a6b90e6e47555f26d307a04a44b550b570449ceeb
+  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/cron.rb

@@ -574,6 +574,9 @@ module Wurk
       end
 
       def enqueue!(loop_obj)
+        aj = active_job_class(loop_obj.klass)
+        return enqueue_active_job(aj, loop_obj) if aj
+
         @client.push(
           'class' => loop_obj.klass,
           'args' => loop_obj.args,
@@ -582,6 +585,32 @@ module Wurk
         )
       end
 
+      # Resolve a loop's class name to an ActiveJob::Base subclass, or nil when
+      # ActiveJob isn't loaded (standalone wurk) or the class isn't one.
+      # sidekiq-cron parity: a cron loop targeting an ActiveJob must enqueue
+      # through the AJ adapter so the job runs via Sidekiq::ActiveJob::Wrapper
+      # with full callbacks/serialization — a bare `client.push('class' => …)`
+      # would make the processor call `Klass.new.perform`, skipping all of AJ.
+      def active_job_class(name)
+        return nil unless defined?(::ActiveJob::Base)
+
+        const = name.split('::').inject(::Object) { |mod, c| mod.const_get(c) }
+        const if const.is_a?(::Class) && const < ::ActiveJob::Base
+      rescue ::NameError
+        nil
+      end
+
+      # Enqueue via the AJ adapter (→ wurk). Only override the queue when the
+      # loop set one explicitly; otherwise the job's own `queue_as` wins. AJ's
+      # `retry_on`/`discard_on` govern retries, so the Sidekiq `retry` option
+      # doesn't apply here. Returns the wurk jid (provider_job_id) so the fire
+      # history records it; nil if a before_enqueue callback halted the push.
+      def enqueue_active_job(klass, loop_obj)
+        target = loop_obj.queue == 'default' ? klass : klass.set(queue: loop_obj.queue)
+        job = target.perform_later(*loop_obj.args)
+        job.provider_job_id if job.respond_to?(:provider_job_id)
+      end
+
       def read_fire_marks(lid)
         @config.redis do |c|
           vals = c.call('HMGET', "#{LOOP_PREFIX}#{lid}", 'lf', 'nf')

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.0"
+  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)