wurk 1.1.0 → 1.1.2

data/lib/wurk/batch/server_middleware.rb

@@ -17,8 +17,9 @@ module Wurk
     # failure → BATCH_ACK_FAILED → the jid joins `b-<bid>-failed` and
     # `failures` reflects the count of currently-failing jobs. A later
     # successful retry clears it; a terminal death moves it to `b-<bid>-died`.
-    # Clean handled exits (JobRetry::Skip from expiry/interrupt, cooperative
-    # IterableJob interruption) are re-raised without counting as failures.
+    # Clean handled exits (JobRetry::Skip — from the interrupt handler or a
+    # Limiter::Rescheduled re-enqueue — and cooperative IterableJob
+    # interruption) are re-raised as neither success nor failure.
     #
     # Invalidated batches short-circuit: the job is skipped without
     # raising — counts as a "success" for batch purposes per spec §12.
@@ -43,9 +44,12 @@ module Wurk
 
       private
 
-      # A handled/skip exit or a cooperative interruption is not a failure —
-      # re-raise it untouched. Any other exception means the job failed and
-      # will retry (or eventually die): record it before re-raising.
+      # A handled/skip exit — including a Limiter::Rescheduled, where the
+      # limiter already re-enqueued the job (Rescheduled < JobRetry::Skip <
+      # Handled) — or a cooperative interruption is *neither* success nor
+      # failure: re-raise it untouched, acking neither. Any other exception
+      # means the job failed and will retry (or eventually die): record it
+      # before re-raising.
       def run_and_ack(bid, jid)
         yield
         ack_success(bid, jid)

data/lib/wurk/batch.rb

@@ -185,6 +185,9 @@ module Wurk
       collect_jobs(&block)
       # By the time we check, the buffer (if any) has flushed, so `total`
       # reflects everything the block pushed — a flat count is reliable.
+      # Scheduled (`perform_in`) jobs count here too: BATCH_SCHEDULE moves
+      # `total` at creation, so a scheduled-only block does not misfire the
+      # marker as if it were empty.
       enqueue_empty_marker if job_count == pre_count
       @mutable = false
       self

data/lib/wurk/capsule.rb

@@ -25,7 +25,7 @@ module Wurk
       @weights = { 'default' => 0 }
       @fetcher = nil
       @redis_pool = nil
-      @local_redis_pool = nil
+      @fetch_redis_pool = nil
       @client_chain = nil
       @server_chain = nil
     end
@@ -65,7 +65,7 @@ module Wurk
     def prepare!
       @fetcher ||= build_fetcher
       redis_pool
-      local_redis_pool
+      fetch_redis_pool
       client_middleware
       server_middleware
       self
@@ -86,20 +86,27 @@ module Wurk
       chain
     end
 
-    # Pool size = concurrency + POOL_OVERHEAD. Every processor thread can
-    # be parked in a blocking BLMOVE (reliable fetch), holding its slot
-    # for ~3s. POOL_OVERHEAD reserves connections for the Launcher's
-    # heartbeat thread + the Scheduled::Poller so they can never be
-    # starved by busy fetchers. Without this, concurrency=1 deadlocks
-    # immediately (worker holds the only slot, heartbeat times out).
-    POOL_OVERHEAD = 2
+    # Headroom above `concurrency` for the main pool; the whole pool is then
+    # floored at MIN_POOL_SIZE. Blocking BLMOVE fetch has its own pool
+    # (#fetch_redis_pool), so the main pool serves only the background loops —
+    # heartbeat, scheduled poller, leader election, cron, the two metrics
+    # rollups, reaper, history, health probe — plus the host's own job-code
+    # checkouts. `concurrency + 5` (floor 10) gives each an unstarvable slot;
+    # the old `concurrency + 2` starved them once fetch also drew from here —
+    # the #101 `0/N` pool-exhaustion incident. Override via `config.redis[:size]`.
+    POOL_HEADROOM = 5
+    MIN_POOL_SIZE = 10
 
     def redis_pool
-      @redis_pool ||= build_pool(size: @concurrency + POOL_OVERHEAD, name: "#{@name}-main")
+      @redis_pool ||= build_pool(size: main_pool_size, name: "#{@name}-main")
     end
 
-    def local_redis_pool
-      @local_redis_pool ||= build_pool(size: @concurrency, name: "#{@name}-local")
+    # Dedicated pool for the reliable fetcher's blocking BLMOVE: one slot per
+    # processor thread (`concurrency`), since at most that many threads park in
+    # fetch at once. Keeping fetch off the main pool is what lets an idle worker
+    # hold zero main-pool connections again.
+    def fetch_redis_pool
+      @fetch_redis_pool ||= build_pool(size: @concurrency, name: "#{@name}-fetch")
     end
 
     # Disconnect and drop cached pools. Called by Wurk::Swarm just before
@@ -109,14 +116,20 @@ module Wurk
     def reset_redis_pools!
       @redis_pool&.disconnect!
       @redis_pool = nil
-      @local_redis_pool&.disconnect!
-      @local_redis_pool = nil
+      @fetch_redis_pool&.disconnect!
+      @fetch_redis_pool = nil
     end
 
     def redis(&)
       redis_pool.with(&)
     end
 
+    # Checkout from the dedicated fetch pool. Only the reliable fetcher's
+    # blocking BLMOVE uses this, so a parked fetch never holds a main-pool slot.
+    def fetch_redis(&)
+      fetch_redis_pool.with(&)
+    end
+
     def lookup(name)
       @config.lookup(name)
     end
@@ -196,14 +209,14 @@ module Wurk
       parsed.flat_map { |q, w| [q] * w }
     end
 
+    # `config.redis = { size: N }` pins the main pool at N; otherwise
+    # `concurrency + POOL_HEADROOM`, floored at MIN_POOL_SIZE.
+    def main_pool_size
+      @config.redis_config[:size] || [@concurrency + POOL_HEADROOM, MIN_POOL_SIZE].max
+    end
+
     def build_pool(size:, name:)
-      cfg = @config.redis_config
-      RedisPool.new(
-        size: size,
-        url: cfg[:url] || RedisPool::DEFAULT_URL,
-        timeout: cfg[:timeout] || RedisPool::DEFAULT_TIMEOUT,
-        name: name
-      )
+      @config.new_redis_pool(size, name)
     end
   end
 end

data/lib/wurk/cli.rb

@@ -45,7 +45,12 @@ module Wurk
         cli.launcher.quiet
       end,
       'TTIN' => BACKTRACE_DUMPER,
-      'INFO' => BACKTRACE_DUMPER
+      'INFO' => BACKTRACE_DUMPER,
+      'USR2' => lambda do |cli|
+        cli.logger.info 'Received USR2, reopening logs'
+        # reopen_logs is private — an explicit receiver needs __send__.
+        cli.__send__(:reopen_logs)
+      end
     }.freeze
 
     # Table-driven so adding a flag doesn't grow `define_value_flags`'s ABC
@@ -137,7 +142,8 @@ module Wurk
       validate_pool_sizes!
       @config[:identity] = identity
       ::Process.warmup if warmup && ::Process.respond_to?(:warmup) && ENV['RUBY_DISABLE_WARMUP'] != '1'
-      @swarm = Wurk::Swarm.new(topology: @config.topology, config: @config)
+      @swarm = Wurk::Swarm.new(topology: @config.topology, config: @config,
+                               shutdown_timeout: @config[:timeout] || Swarm::DEFAULT_SHUTDOWN_TIMEOUT)
       @swarm.boot(install_signals: true)
       @swarm.supervise
     end
@@ -189,7 +195,14 @@ module Wurk
     end
 
     def signal_names
-      %w[INT TERM TSTP TTIN INFO]
+      %w[INT TERM TSTP TTIN INFO USR2]
+    end
+
+    def reopen_logs
+      log = logger
+      log.reopen if log.respond_to?(:reopen)
+    rescue StandardError
+      nil
     end
 
     def validate_redis!

data/lib/wurk/client/buffered.rb

@@ -137,20 +137,38 @@ module Wurk
         def capture_pool_from_client(client)
           return unless client && !buffer_client_factory
 
-          pool = client.instance_variable_get(:@pool)
+          pool = client.instance_variable_get(:@redis_pool)
+          # A nil capture must not install a factory: it would pin the drainer
+          # to the DEFAULT pool forever (the `!buffer_client_factory` guard
+          # blocks any later, correct capture) — wrong Redis for jobs pushed
+          # through an explicit-pool client.
+          return unless pool
+
           self.buffer_client_factory = -> { Wurk::Client.new(pool: pool) }
         end
 
         public
 
         # Drain payloads through `raw_push` on the given client. Stops on
-        # the first ConnectionError, preserving order at the head of the
-        # buffer so the next push retries the same payload. Emits statsd
+        # the first transient failure (ConnectionError past the pool's own
+        # retries, or a starved checkout), preserving order at the head of
+        # the buffer so the next push retries the same payload. Emits statsd
         # `jobs.recovered.push` per drained payload.
         def drain!(client)
           drained = 0
           while (payload = pop_head)
-            unless attempt_replay(client, payload)
+            begin
+              replayed = attempt_replay(client, payload)
+            rescue StandardError
+              # Non-connection failures (OOM, LOADING, READONLY…) must not
+              # drop the popped payload — restore it before propagating, or
+              # a recovering-but-not-ready Redis silently eats one buffered
+              # job per drain tick.
+              buffer_mutex.synchronize { buffer.unshift(payload) }
+              raise
+            end
+
+            unless replayed
               buffer_mutex.synchronize { buffer.unshift(payload) }
               break
             end
@@ -206,14 +224,14 @@ module Wurk
           buffer_mutex.synchronize { buffer.shift }
         end
 
-        # Drain marks the thread so our prepended raw_push re-raises
-        # ConnectionError back here instead of swallowing it into the buffer
+        # Drain marks the thread so our prepended raw_push re-raises the
+        # transient error back here instead of swallowing it into the buffer
         # (which would spin forever).
         def attempt_replay(client, payload)
           Thread.current[DRAINING_KEY] = true
           client.send(:raw_push, [payload])
           true
-        rescue RedisClient::ConnectionError
+        rescue RedisClient::ConnectionError, ConnectionPool::TimeoutError
           false
         ensure
           Thread.current[DRAINING_KEY] = false
@@ -222,7 +240,7 @@ module Wurk
 
       # Background drain thread. Wakes every `interval` seconds and tries
       # `Buffered.drain!` against a fresh Wurk::Client. drain! already
-      # short-circuits on the first ConnectionError, so a still-down Redis
+      # short-circuits on the first transient failure, so a still-down Redis
       # just leaves the buffer alone for this tick — no exponential
       # backoff or explicit "reconnect detection" needed; the inner
       # connection retry already lives inside `client.raw_push`.
@@ -292,7 +310,9 @@ module Wurk
       end
 
       # Wraps Wurk::Client. push / push_bulk drain the buffer first;
-      # raw_push catches ConnectionError and buffers non-batched payloads.
+      # raw_push catches transient failures — RedisClient::ConnectionError
+      # past RedisPool's own retries, or a starved checkout
+      # (ConnectionPool::TimeoutError) — and buffers non-batched payloads.
       module InstanceMethods
         def push(item)
           Buffered.drain!(self)
@@ -308,7 +328,7 @@ module Wurk
 
         def raw_push(payloads)
           super
-        rescue RedisClient::ConnectionError
+        rescue RedisClient::ConnectionError, ConnectionPool::TimeoutError
           raise if Thread.current[Buffered::DRAINING_KEY]
 
           bidless, batched = payloads.partition { |p| !p['bid'] }

data/lib/wurk/client.rb

@@ -246,12 +246,26 @@ module Wurk
 
     def atomic_push(conn, payloads)
       if payloads.first['at']
-        conn.pipelined { |pipe| push_scheduled(pipe, payloads) }
+        push_scheduled_split(conn, payloads)
       else
         push_immediate(conn, payloads)
       end
     end
 
+    # Scheduled payloads split like push_immediate: a `bid`-carrying job (a
+    # `perform_in` inside `batch.jobs`) must register into its batch at creation
+    # via BATCH_SCHEDULE so `total`/`pending` move now — a bare ZADD would leave
+    # the batch counters at zero and the empty-marker check would misfire. Plain
+    # scheduled jobs take the bare ZADD. Separate pipelines for the same
+    # NOSCRIPT-replay reason as push_immediate: a Lua NOSCRIPT surfaces only at
+    # pipeline finalize, so a unified retry would replay the plain ZADD and
+    # duplicate the scheduled entry.
+    def push_scheduled_split(conn, payloads)
+      batched, plain = payloads.partition { |j| j['bid'] }
+      conn.pipelined { |pipe| push_scheduled(pipe, plain) } unless plain.empty?
+      push_batched_scheduled_pipelined(conn, batched) unless batched.empty?
+    end
+
     def push_scheduled(conn, payloads)
       args = payloads.flat_map do |hash|
         [hash['at'].to_s, Wurk.dump_json(hash.except('enqueued_at', 'at'))]
@@ -288,6 +302,17 @@ module Wurk
       conn.pipelined { |pipe| push_batched(pipe, batched, now, eval_method: :eval_with_source) }
     end
 
+    # Same NOSCRIPT-recovery shape as push_batched_pipelined, for the scheduled
+    # batched path (BATCH_SCHEDULE instead of BATCH_PUSH).
+    def push_batched_scheduled_pipelined(conn, batched)
+      conn.pipelined { |pipe| push_batched_scheduled(pipe, batched) }
+    rescue RedisClient::CommandError => e
+      raise unless e.message.to_s.start_with?('NOSCRIPT')
+
+      Wurk::Lua::Loader.script_load_all(conn)
+      conn.pipelined { |pipe| push_batched_scheduled(pipe, batched, eval_method: :eval_with_source) }
+    end
+
     def push_plain(conn, payloads, now)
       grouped = payloads.group_by { |j| j['queue'] }
       conn.call('SADD', 'queues', *grouped.keys)
@@ -321,6 +346,25 @@ module Wurk
       end
     end
 
+    # Scheduled batched jobs route through BATCH_SCHEDULE: the SADD-guarded
+    # total/pending increment registers the job in its batch at creation, and
+    # the ZADD defers it onto `schedule`. Payload is stripped of `at`/
+    # `enqueued_at` exactly like push_scheduled — `enqueued_at` is stamped fresh
+    # at promotion, never while the job sits scheduled (spec §7.1). One Redis
+    # round-trip per job because the Lua binds per-job KEYS; scheduled batch
+    # enqueue is not the hot path.
+    def push_batched_scheduled(conn, payloads, eval_method: :eval_cached)
+      payloads.each do |j|
+        Wurk::Lua::Loader.public_send(
+          eval_method,
+          conn,
+          :batch_schedule,
+          keys: ['schedule', "b-#{j['bid']}", "b-#{j['bid']}-jids"],
+          argv: [j['at'].to_s, Wurk.dump_json(j.except('enqueued_at', 'at')), j['jid']]
+        )
+      end
+    end
+
     def pool
       @redis_pool || Thread.current[:wurk_via_pool] || @config.redis_pool
     end

data/lib/wurk/component.rb

@@ -22,6 +22,9 @@ module Wurk
 
     attr_reader :config
 
+    # `leader?` cache TTL — see the method doc below.
+    LEADER_CACHE_TTL_MS = 5_000
+
     # --- clocks ---------------------------------------------------------
 
     def real_ms
@@ -71,20 +74,25 @@ module Wurk
     # --- cluster leadership --------------------------------------------
 
     # True iff this process currently holds the cluster `dear-leader` lock.
-    # Per spec, the check is performed at call time (Wurk does not cache);
-    # callers must not poll faster than the 60s follower cadence. Returns
-    # false unconditionally when `WURK_LEADER=false` (or `SIDEKIQ_LEADER=false`)
-    # is set on the process (opt-out hot-standby). Any Redis error is swallowed →
-    # false, so a transient partition can't propagate as an exception into user
-    # code.
+    # Cached per Component instance for `LEADER_CACHE_TTL_MS` (~5s): cron and
+    # the metrics rollups call this every tick, and an uncached GET would
+    # double their Redis traffic at short intervals for no benefit — the
+    # lock's own renewal cadence (60s+, spec §6.1) easily tolerates a
+    # few-second-stale read. Returns false unconditionally when
+    # `WURK_LEADER=false` (or `SIDEKIQ_LEADER=false`) is set on the process
+    # (opt-out hot-standby). Any Redis error is swallowed → false, so a
+    # transient partition can't propagate as an exception into user code.
     #
     # Spec: docs/target/sidekiq-ent.md §6.1.
     def leader?
       return false if Wurk::Leader.opted_out?
 
-      redis { |c| c.call('GET', Wurk::Leader::DEFAULT_KEY) } == identity
-    rescue StandardError
-      false
+      now = mono_ms
+      if @leader_checked_at.nil? || (now - @leader_checked_at) >= LEADER_CACHE_TTL_MS
+        @leader_checked_at = now
+        @leader_cached = fetch_leader?
+      end
+      @leader_cached
     end
 
     # --- thread boundaries ---------------------------------------------
@@ -127,6 +135,12 @@ module Wurk
 
     private
 
+    def fetch_leader?
+      redis { |c| c.call('GET', Wurk::Leader::DEFAULT_KEY) } == identity
+    rescue StandardError
+      false
+    end
+
     def run_lifecycle_hook(hook, event, reraise)
       hook.call
     rescue StandardError => e

data/lib/wurk/configuration.rb

@@ -43,7 +43,8 @@ module Wurk
       reloader: proc { |&b| b.call },
       backtrace_cleaner: ->(bt) { bt },
       logged_job_attributes: %w[bid tags],
-      redis_idle_timeout: nil
+      redis_idle_timeout: nil,
+      redis_error_handlers: []
     }.freeze
 
     # :fork fires only inside swarm children, after fork + internal AR/Redis
@@ -51,6 +52,13 @@ module Wurk
     LIFECYCLE_EVENTS = %i[startup fork quiet shutdown exit heartbeat beat leader].freeze
     DEFAULT_THREAD_PRIORITY = -1
 
+    # Redis client / pool errors that the pool wrapper already retried before
+    # re-raising. Logged one level up (WARN, not INFO) so a transient blip
+    # surfaces in ops dashboards without drowning steady-state noise (#101).
+    # RedisClient + ConnectionPool are always loaded before this file (capsule
+    # → redis_pool requires both), so referencing them here is safe.
+    REDIS_ERROR_CLASSES = [RedisClient::Error, ConnectionPool::TimeoutError].freeze
+
     # Default error handler. Wraps the report in the thread-local
     # Wurk::Context so logger formatters/JSON layouts can pick up jid/bid/tags.
     # `full_message` (with backtrace) in dev/debug, `detailed_message` in prod —
@@ -62,7 +70,8 @@ module Wurk
       Wurk::Context.with(safe_ctx) do
         dev = $DEBUG || ENV['WURK_DEBUG'] || cfg.logger.debug?
         msg = dev ? ex.full_message : ex.detailed_message
-        cfg.logger.info { msg }
+        level = REDIS_ERROR_CLASSES.any? { |k| ex.is_a?(k) } ? :warn : :info
+        cfg.logger.public_send(level) { msg }
       end
     end
 
@@ -86,6 +95,7 @@ module Wurk
       @client_chain = Middleware::Chain.new
       @server_chain = Middleware::Chain.new
       @redis_config = { url: ENV.fetch('REDIS_URL', 'redis://localhost:6379/0') }
+      @web_redis_pool = nil
       @logger = nil
       @thread_priority = DEFAULT_THREAD_PRIORITY
       @frozen = false
@@ -168,17 +178,13 @@ module Wurk
       default_capsule.redis_pool
     end
 
-    def local_redis_pool
-      @local_redis_pool ||= build_redis_pool(size: 10, name: 'internal')
-    end
-
-    # Disconnect and drop every cached pool — the per-capsule mains plus
-    # the config-level internal pool. Used by Wurk::Swarm so the parent
-    # never leaks sockets into forks and each child can build fresh ones.
+    # Disconnect and drop every capsule's cached pools (main + fetch) plus the
+    # web pool. Used by Wurk::Swarm so the parent never leaks sockets into forks
+    # and each child can build fresh ones.
     def reset_redis_pools!
       @capsules.each_value(&:reset_redis_pools!)
-      @local_redis_pool&.disconnect!
-      @local_redis_pool = nil
+      @web_redis_pool&.disconnect!
+      @web_redis_pool = nil
     end
 
     def new_redis_pool(size, name = 'custom')
@@ -189,6 +195,39 @@ module Wurk
       redis_pool.with(&)
     end
 
+    # --- Web dashboard Redis pool ----------------------------------------
+
+    # Default connection count for the dedicated web pool (#web_redis_pool).
+    WEB_POOL_DEFAULT_SIZE = 5
+
+    # Deliberately short checkout wait for the web pool: a saturated dashboard
+    # should fail fast rather than tie up a web-server thread queuing for a slot.
+    WEB_POOL_TIMEOUT = 1.0
+
+    # Connections in the dedicated web pool. `config.web_pool_size = N` overrides
+    # the default; independent of `config.redis[:size]`, which sizes the worker
+    # capsules — the two pools are deliberately disjoint (#101).
+    def web_pool_size
+      @options[:web_pool_size] || WEB_POOL_DEFAULT_SIZE
+    end
+
+    def web_pool_size=(size)
+      guard_frozen!
+      @options[:web_pool_size] = Integer(size)
+    end
+
+    # Dedicated Redis pool for the dashboard / JSON API / SSE, disjoint from
+    # every worker capsule's pool. Dashboard load — an API burst, a long-lived
+    # SSE stream — can no longer drain the connections a co-located (embedded)
+    # worker needs to fetch and heartbeat, and vice versa: the #101 `0/N`
+    # pool-exhaustion incident. Lazy, so a headless worker that never serves the
+    # dashboard builds nothing; web entry points route `Wurk.redis` here through
+    # Wurk::Web::PoolScope. The Configuration instance is never frozen (only its
+    # @options/@capsules are), so this `||=` is safe to fire post-boot.
+    def web_redis_pool
+      @web_redis_pool ||= build_redis_pool(size: web_pool_size, name: 'web', pool_timeout: WEB_POOL_TIMEOUT)
+    end
+
     # --- Service locator (extension registry) ----------------------------
 
     def register(name, instance)
@@ -210,6 +249,19 @@ module Wurk
       @options[:death_handlers]
     end
 
+    # Telemetry hook fired by RedisPool on every transient-error retry and
+    # final give-up. The block receives one Hash: { error:, attempt:, retried:,
+    # pool: }. Opt-in — pools stay silent until a handler is registered.
+    def on_redis_error(&block)
+      raise ArgumentError, 'block required for on_redis_error' unless block
+
+      @options[:redis_error_handlers] << block
+    end
+
+    def redis_error_handlers
+      @options[:redis_error_handlers]
+    end
+
     def average_scheduled_poll_interval=(interval)
       @options[:average_scheduled_poll_interval] = interval
     end
@@ -495,13 +547,26 @@ module Wurk
       logger
     end
 
-    def build_redis_pool(size:, name:)
-      RedisPool.new(
-        size: size,
-        url: @redis_config[:url] || RedisPool::DEFAULT_URL,
-        timeout: @redis_config[:timeout] || RedisPool::DEFAULT_TIMEOUT,
-        name: name
-      )
+    # `size`/`name` are pool-structural (the caller owns them); every other
+    # key the host set via `config.redis = {...}` — url, the split timeouts,
+    # reconnect_attempts, driver, … — flows through to RedisPool verbatim.
+    # `overrides` win over the host config (the web pool pins its own
+    # pool_timeout this way). Every pool built here is wired to the redis-error
+    # telemetry dispatcher.
+    def build_redis_pool(size:, name:, **overrides)
+      RedisPool.new(size: size, name: name, on_error: method(:dispatch_redis_error),
+                    **@redis_config.except(:size, :name), **overrides)
+    end
+
+    # Fan a RedisPool retry/give-up event out to the registered handlers. A
+    # raising handler is logged and skipped so one bad hook can't break the
+    # pool's retry path (mirrors #handle_exception).
+    def dispatch_redis_error(info)
+      redis_error_handlers.each do |handler|
+        handler.call(info)
+      rescue StandardError => e
+        logger.error("redis_error_handler raised: #{e.class}: #{e.message}")
+      end
     end
   end
 end

data/lib/wurk/cron.rb

@@ -170,11 +170,23 @@ module Wurk
         step_i = Integer(step)
         raise ArgumentError, "cron step must be >= 1 (got #{step_i})" if step_i < 1
 
-        base_values = base == '*' ? (min..max).to_a : parse_chunk(base, min, max)
+        base_values = step_base_values(base, min, max)
         start = base_values.first
         base_values.select { |v| ((v - start) % step_i).zero? }
       end
 
+      # Vixie cron: a single-value step base means "start..max" (`5/15` in the
+      # minute field = 5,20,35,50), not the single value alone — fugit and
+      # Sidekiq Ent agree.
+      def step_base_values(base, min, max)
+        return (min..max).to_a if base == '*'
+        return parse_range(base, min, max) if base.include?('-')
+
+        v = Integer(base)
+        validate_value!(v, min, max)
+        (v..max).to_a
+      end
+
       def parse_range(chunk, min, max)
         a, b = chunk.split('-', 2).map { |x| Integer(x) }
         raise ArgumentError, "cron range start > end (#{a} > #{b})" if a > b

data/lib/wurk/dead_set.rb

@@ -38,12 +38,27 @@ module Wurk
       Wurk.redis do |conn|
         conn.pipelined do |pipe|
           pipe.call('ZREMRANGEBYSCORE', @name, '-inf', "(#{cutoff}")
-          pipe.call('ZREMRANGEBYRANK', @name, 0, -(max_jobs + 1))
+          pipe.call('ZREMRANGEBYRANK', @name, 0, -max_jobs)
         end
       end
       true
     end
 
+    # ZADD the raw JSON payload (score = now) then apply the two-axis #trim.
+    # Shared primitive behind both morgue entry points so the trim runs on
+    # EVERY kill (spec §31.8), including the malformed-JSON path:
+    #   * JobRetry#send_to_morgue — exhausted retries
+    #   * Processor#parse_or_kill — unparseable payloads
+    # No death handlers: JobRetry fires its own via #run_death_handlers and the
+    # malformed path has no parseable job to hand a handler. `max_jobs:` /
+    # `timeout:` propagate to #trim (see there for the override rationale).
+    def kill_raw(payload, max_jobs: nil, timeout: nil) # rubocop:disable Naming/PredicateMethod
+      now = ::Process.clock_gettime(::Process::CLOCK_REALTIME)
+      Wurk.redis { |conn| conn.call('ZADD', @name, now.to_s, payload) }
+      trim(max_jobs: max_jobs, timeout: timeout)
+      true
+    end
+
     # ZADD the raw JSON payload, trim, fire death handlers. `notify_failure:
     # true` (default) routes the kill through the death-handler chain;
     # UI-initiated kills pass false. `ex` is the originating exception (or

data/lib/wurk/engine.rb

@@ -45,11 +45,27 @@ module Wurk
     # Precompiled SPA lives in vendor/assets/dashboard; the engine serves
     # those files as static assets under the /wurk-assets mount point via
     # AssetMount (above).
+    #
+    # Deliberately unauthenticated: this middleware is inserted straight into
+    # the *host app's* middleware stack (`app.middleware`), not the engine's
+    # own (`middleware.use` in this class, below) — so it runs before
+    # anything wired via `Wurk::Web.use`/`Authorization` even sees the
+    # request, and `/wurk-assets/*` is reachable without passing either
+    # check. That's intentional, not an oversight: the bundle is the
+    # compiled JS/CSS/font shell only (no job payloads, no Redis reads, no
+    # per-user state — every data-bearing byte comes from the JSON API,
+    # which *does* sit behind the engine's Authorization middleware). It's
+    # the same trust model as serving `public/assets` from any other Rails
+    # app. See README "Security notes" for the full reasoning.
     initializer 'wurk.assets' do |app|
       assets_path = Wurk::Engine.root.join('vendor', 'assets', 'dashboard')
       if assets_path.exist?
+        # Index 0, not insert_before(ActionDispatch::Static): Static is only
+        # in the stack when public_file_server is enabled, and a stock
+        # production deploy behind nginx (RAILS_SERVE_STATIC_FILES unset)
+        # omits it — insert_before(Static) would crash the host app's boot.
         app.middleware.insert_before(
-          ::ActionDispatch::Static,
+          0,
           ::Wurk::Engine::AssetMount,
           root: assets_path.to_s
         )