wurk 1.2.1 → 1.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6924007f22a9b940826d61f2eb5b60dc58efd2557fc0cce886a06f8b901a9afd
-  data.tar.gz: ccac331e25f6cf03aa9c11165e237d5167aebc24f554822fb2b61a62fd2949b6
+  metadata.gz: 2b1f8eac5cefbd9f645598b9a37dca543aeebb361967d820f369cc14420ad3f6
+  data.tar.gz: 813958b643c78cdd2ffa5063798bb3994f6510b1b0d50a0a54db1622f3bb325a
 SHA512:
-  metadata.gz: e3021cb0c71aee76255849da78c97f520ec91244cf35991ece101867194384a8791308926c239b898b36226eba1e8c438c43088ca2d9797fa7a93afe54852a4a
-  data.tar.gz: 5181dd6eb9a19c285f7d20346c0e15f3bafeeb211be5ba0dbfa0fb2e90a4399f72d99384fc9ea4119a7db9722f684b3269a1a63379421a5e9b73fdcf230cb998
+  metadata.gz: 65ca6b60bf079d626f3887d9e1e12b7d1d1f91ab264c5fcba7c77f54667961159fb8a63c8be89d44e9583ef7c264669e546eb15ab4bc13e392ef85b35dfea6ad
+  data.tar.gz: b865d8cd28483589bad0f6d879d80a85c9f9d5cb9b79a494634c90ebaf0f5371169ed7012303dabdc736b32be3596dbffd2ac60b2bbeb3d24c1b40514e483b54

data/README.md

@@ -71,6 +71,7 @@ Plus Wurk extras: a worker topology DSL, a Kubernetes liveness/readiness listene
 - **[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.
 - **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)**

data/lib/wurk/configuration.rb

@@ -6,6 +6,7 @@ require_relative 'middleware/chain'
 require_relative 'capsule'
 require_relative 'context'
 require_relative 'topology'
+require_relative 'redis_options'
 
 module Wurk
   # Owns runtime knobs (concurrency, queues, timeouts, lifecycle events,
@@ -169,8 +170,14 @@ module Wurk
 
     # --- Redis ------------------------------------------------------------
 
+    # Validated here, in the process running the initializer, rather than later
+    # in whichever process first builds a pool. The swarm's children are the ones
+    # that construct pools, so a bad key used to kill every child on boot while
+    # the parent stayed up and healthy — Running pod, passing probe, zero jobs
+    # processed (#283).
     def redis=(hash)
       guard_frozen!
+      RedisOptions.validate!(hash)
       @redis_config = @redis_config.merge(hash.transform_keys(&:to_sym))
     end
 

data/lib/wurk/redis_options.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require 'redis-client'
+
+module Wurk
+  # Translates a Sidekiq-shaped `config.redis` hash into the exact keyword set
+  # redis-client accepts.
+  #
+  # Sidekiq normalizes the hash itself before handing it over
+  # (`sidekiq/redis_client_adapter.rb#client_opts`), so initializers in the wild
+  # carry keys redis-client has never known. Wurk used to splat the hash straight
+  # into `RedisClient.config`, which surfaced as
+  # `ArgumentError: unknown keyword: :network_timeout` — and only inside the
+  # forked children, which build their own pools (#283). The parent booted fine,
+  # the liveness probe passed, and the swarm respawn loop churned forever
+  # processing zero jobs. Hence `validate!`, called from Configuration#redis= so
+  # a bad hash raises in the parent where someone can actually see it.
+  #
+  # Reference: sidekiq 7.3 / 8.1 `client_opts` — namespace rejected,
+  # size/pool_timeout dropped, `network_timeout` → `timeout`, `master_name` →
+  # `name`, role/driver symbolized, `reconnect_attempts ||= 1`.
+  module RedisOptions
+    # Consumed by the pool layer (RedisPool / Capsule); never a socket concern.
+    POOL_KEYS = %i[size name pool_name pool_timeout on_error].freeze
+
+    # Accepted for Sidekiq parity, then dropped: Sidekiq used `logger` for its
+    # own "connecting to Redis with options ..." line and `cluster_safe` to
+    # unlock `:nodes`. redis-client has no keyword for either.
+    IGNORED_KEYS = %i[logger cluster_safe].freeze
+
+    # Sidekiq-only spellings this module rewrites into redis-client keywords.
+    TRANSLATED_KEYS = %i[network_timeout master_name].freeze
+
+    # The umbrella socket timeout, under both its names. `network_timeout` is
+    # the redis-rb-era spelling every "widen the timeouts for a slow/remote
+    # Redis" snippet still uses; `timeout` is redis-client's own.
+    UMBRELLA_TIMEOUT_KEYS = %i[network_timeout timeout].freeze
+
+    # Wurk splits the socket timeouts (#101) and passes all three explicitly, and
+    # redis-client lets an explicit `read_timeout` win over `timeout` — so
+    # forwarding the umbrella verbatim would silently drop the host's value.
+    # Fan it out instead; a host-supplied split timeout still wins over the fan-out.
+    SPLIT_TIMEOUT_KEYS = %i[connect_timeout read_timeout write_timeout].freeze
+
+    # Symbols in redis-client, strings in plenty of YAML-sourced configs.
+    SYMBOLIZED_KEYS = %i[driver role].freeze
+
+    # Keys that mean something in Sidekiq but have no Wurk equivalent. Raise
+    # naming the key and its replacement — the alternative is an opaque
+    # `unknown keyword:` from three layers down inside a forked child.
+    REJECTED_KEYS = {
+      namespace: 'Redis namespacing was dropped in Sidekiq 7 and Wurk never implemented it ' \
+                 '(docs/migrate-from-sidekiq.md §4). Give Wurk its own Redis database ' \
+                 '(redis://host:6379/1) or its own instance instead.',
+      nodes: 'Wurk does not run on Redis Cluster. Point config.redis at a single server with ' \
+             '`url:`, or at a Sentinel set with `sentinels:`.'
+    }.freeze
+
+    # Keyword parameter kinds in Method#parameters.
+    KEYWORD_PARAMS = %i[key keyreq].freeze
+
+    class << self
+      # The keyword hash for RedisClient.config / RedisClient.sentinel.
+      # `defaults` are Wurk's own socket defaults; everything the host supplied
+      # wins over them.
+      def normalize(options, defaults: {})
+        opts = symbolize(options)
+        validate!(opts)
+        opts = translate(opts)
+
+        # A default `url` is meaningless next to a sentinel set and actively
+        # harmful: SentinelConfig derives the master name and db from it.
+        defaults = defaults.except(:url) if sentinel?(opts)
+
+        defaults.merge(split_timeouts(opts), opts.except(*UMBRELLA_TIMEOUT_KEYS))
+      end
+
+      # Raises for anything redis-client would reject. Cheap and pure, so it runs
+      # in the parent (Configuration#redis=) as well as at pool-build time.
+      def validate!(options)
+        opts = symbolize(options)
+
+        REJECTED_KEYS.each do |key, hint|
+          raise ArgumentError, "config.redis[:#{key}] is not supported. #{hint}" if opts.key?(key)
+        end
+
+        unknown = opts.keys - known_keys
+        return if unknown.empty?
+
+        raise ArgumentError,
+              "config.redis: unknown option#{'s' if unknown.size > 1} " \
+              "#{unknown.map(&:inspect).join(', ')}. Supported keys: #{known_keys.sort.join(', ')}."
+      end
+
+      # Sentinel sets go through RedisClient.sentinel — RedisClient.config
+      # rejects `sentinels:` outright. Same routing Sidekiq does.
+      def sentinel?(client_config)
+        client_config.key?(:sentinels)
+      end
+
+      # Every keyword redis-client itself accepts, read off its own signatures so
+      # the list can't drift from the installed version. Config#initialize takes
+      # a **kwargs rest and forwards to Config::Common, so both have to be walked;
+      # SentinelConfig adds the sentinel-only keys.
+      def known_keys
+        @known_keys ||= [
+          ::RedisClient::Config, ::RedisClient::Config::Common, ::RedisClient::SentinelConfig
+        ].flat_map { |mod| keyword_params(mod) }.union(POOL_KEYS, IGNORED_KEYS, TRANSLATED_KEYS)
+      end
+
+      private
+
+      # Drop what redis-client has no keyword for, then rewrite the Sidekiq
+      # spellings it does have an equivalent for.
+      def translate(opts)
+        opts = opts.except(*POOL_KEYS, *IGNORED_KEYS)
+        opts[:name] = opts.delete(:master_name) if opts.key?(:master_name)
+        SYMBOLIZED_KEYS.each { |key| opts[key] = opts[key].to_sym if opts[key] }
+        opts
+      end
+
+      def keyword_params(mod)
+        mod.instance_method(:initialize).parameters.filter_map do |kind, key|
+          key if KEYWORD_PARAMS.include?(kind)
+        end
+      end
+
+      # The umbrella timeout fanned out across the three split ones. Returns {}
+      # when the host set neither, leaving Wurk's defaults in place.
+      def split_timeouts(opts)
+        umbrella = opts.values_at(*UMBRELLA_TIMEOUT_KEYS).compact.first
+        return {} unless umbrella
+
+        SPLIT_TIMEOUT_KEYS.to_h { |key| [key, umbrella] }
+      end
+
+      def symbolize(options)
+        options.transform_keys(&:to_sym)
+      end
+    end
+  end
+end

data/lib/wurk/redis_pool.rb

@@ -3,6 +3,7 @@
 require 'redis-client'
 require 'connection_pool'
 require_relative 'redis_client_adapter'
+require_relative 'redis_options'
 
 module Wurk
   # Per-process pool over redis-client + connection_pool. Never share a socket
@@ -37,6 +38,15 @@ module Wurk
     DEFAULT_WRITE_TIMEOUT      = 2.5
     DEFAULT_RECONNECT_ATTEMPTS = 1
 
+    # The floor every pool starts from; any key the host passed wins over it.
+    DEFAULT_CLIENT_CONFIG = {
+      url: DEFAULT_URL,
+      connect_timeout: DEFAULT_CONNECT_TIMEOUT,
+      read_timeout: DEFAULT_READ_TIMEOUT,
+      write_timeout: DEFAULT_WRITE_TIMEOUT,
+      reconnect_attempts: DEFAULT_RECONNECT_ATTEMPTS
+    }.freeze
+
     # Server-side messages where the connection is closed and the block retried
     # exactly once. READONLY is itself a RedisClient::ConnectionError subclass,
     # so this message match must be tested BEFORE the generic ConnectionError
@@ -60,9 +70,12 @@ module Wurk
 
     # Takes the standard Sidekiq `config.redis` hash: `pool_timeout` tunes the
     # ConnectionPool checkout; `connect_timeout`/`read_timeout`/`write_timeout`/
-    # `reconnect_attempts` plus any other key (driver, ssl_params, …) forward
-    # verbatim to RedisClient.config. `on_error` is an optional callable fired
-    # per retry / final give-up with { error:, attempt:, retried:, pool: }.
+    # `reconnect_attempts` plus any other redis-client key (driver, ssl_params,
+    # sentinels, …) reach the client. Sidekiq-only spellings (`network_timeout`,
+    # `master_name`, `logger`, …) are translated or dropped by {RedisOptions};
+    # a key redis-client would reject raises there with the key named.
+    # `on_error` is an optional callable fired per retry / final give-up with
+    # { error:, attempt:, retried:, pool: }.
     def initialize(size:, name: DEFAULT_NAME, on_error: nil, **options)
       @size          = size
       @name          = name
@@ -112,24 +125,29 @@ module Wurk
 
     private
 
-    # Socket config forwarded to RedisClient.config. Host-supplied keys win over
-    # the defaults; `pool_timeout` is dropped (it's a pool concern, not a socket
-    # one) and unknown keys pass straight through.
+    # Socket config forwarded to redis-client. RedisOptions owns the translation
+    # of the Sidekiq-shaped hash (network_timeout, master_name, pool-only keys,
+    # …) so this class stays about pooling; host-supplied keys win over the
+    # defaults.
     def build_client_config(options)
-      {
-        url: DEFAULT_URL,
-        connect_timeout: DEFAULT_CONNECT_TIMEOUT,
-        read_timeout: DEFAULT_READ_TIMEOUT,
-        write_timeout: DEFAULT_WRITE_TIMEOUT,
-        reconnect_attempts: DEFAULT_RECONNECT_ATTEMPTS
-      }.merge(options.except(:pool_timeout)).freeze
+      RedisOptions.normalize(options, defaults: DEFAULT_CLIENT_CONFIG).freeze
     end
 
     # Wrapped in the CompatClient decorator so `Sidekiq.redis { |c| c.smembers }`
     # method-style commands work like Sidekiq 7+ (#204). Wurk's own code paths
     # use #call, which the decorator forwards.
     def build_client
-      RedisClientAdapter::CompatClient.new(RedisClient.config(**@client_config).new_client)
+      RedisClientAdapter::CompatClient.new(redis_client_config.new_client)
+    end
+
+    # A Sentinel set is a different constructor, not a different keyword:
+    # `RedisClient.config(sentinels: [...])` raises. Sidekiq routes the same way.
+    def redis_client_config
+      if RedisOptions.sentinel?(@client_config)
+        RedisClient.sentinel(**@client_config)
+      else
+        RedisClient.config(**@client_config)
+      end
     end
 
     def safe_close(conn)

data/lib/wurk/sentry/error_handler.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require_relative '../configuration'
+
+module Wurk
+  module Sentry
+    # `config.error_handlers` entry: reports the failures that never become a
+    # job failure — fetch-loop errors (`context: "Error fetching job"`),
+    # shutdown-path errors (`"!shutdown"`), unparseable payloads
+    # (`"Invalid JSON"`), and the retry machinery's own meta-errors (a raising
+    # `sidekiq_retry_in` / `sidekiq_retries_exhausted` block, a raising death
+    # handler). {Middleware} covers job failures; these are the rest.
+    #
+    # Handler signature is Sidekiq's: `call(exception, context_hash, config)`.
+    class ErrorHandler
+      # Transport blips the pool already retried before re-raising. Wurk's
+      # default handler logs these at WARN precisely because they are
+      # self-healing (`Configuration::REDIS_ERROR_CLASSES`), and the fetch loop
+      # runs them in a tight `sleep(1)` cycle: on one production Dragonfly
+      # backend a single Sentry issue accumulated ~136,000 events from fetch
+      # blips while the job pipeline was completely healthy. They stay in the
+      # logs; they just stop paging anyone.
+      DEFAULT_FILTERED_ERROR_CLASSES = Wurk::Configuration::REDIS_ERROR_CLASSES
+
+      attr_reader :filtered_error_classes
+
+      def initialize(filter_transport_errors: true, filtered_error_classes: nil)
+        @filter_transport_errors = filter_transport_errors
+        @filtered_error_classes = (filtered_error_classes || DEFAULT_FILTERED_ERROR_CLASSES).to_a.freeze
+      end
+
+      def call(exception, context = {}, _config = nil)
+        return nil unless Wurk::Sentry.enabled?
+        return nil if exception.is_a?(Wurk::Shutdown)
+        return nil if filtered?(exception)
+
+        ::Sentry.capture_exception(exception, extra: extra_for(context), tags: tags_for(context))
+        nil
+      end
+
+      def filtered?(exception)
+        return false unless @filter_transport_errors
+
+        @filtered_error_classes.any? { |klass| exception.is_a?(klass) }
+      end
+
+      private
+
+      # Same rule as {JobContext}: job arguments never reach Sentry. `jobstr`
+      # (the raw payload of an unparseable job) is dropped wholesale — it *is*
+      # the args, unparsed.
+      def extra_for(context)
+        return {} unless context.is_a?(::Hash)
+
+        context.each_with_object({}) do |(key, value), out|
+          next if key.to_s == 'jobstr'
+
+          out[key] = value.is_a?(::Hash) ? scrub_args(value) : value
+        end
+      end
+
+      def scrub_args(hash)
+        hash.reject { |key, _| key.to_s == 'args' }
+      end
+
+      # Wurk's context labels are a small fixed set, so this is a low-cardinality
+      # tag you can facet the issue stream on.
+      def tags_for(context)
+        label = context[:context] if context.is_a?(::Hash)
+        label ? { wurk_context: label } : {}
+      end
+    end
+  end
+end

data/lib/wurk/sentry/job_context.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Wurk
+  module Sentry
+    # Builds the per-job Sentry scope: transaction name, tags, and the `wurk`
+    # context block. Split out from {Middleware} so the *shape* of what Sentry
+    # sees can change without touching the capture policy.
+    module JobContext
+      CONTEXT_KEY = :wurk
+
+      # Sentry groups issues by transaction name, and sentry-sidekiq names its
+      # transactions `Sidekiq/<JobClass>`. Mirroring that shape as
+      # `Wurk/<JobClass>` keeps a migrating app's issue list legible: the same
+      # job reads the same way before and after the swap, and the only diff is
+      # the prefix — so history stays searchable instead of fragmenting into
+      # unnamed transactions.
+      TRANSACTION_PREFIX = 'Wurk/'
+
+      module_function
+
+      def apply(scope, job, queue)
+        scope.clear_breadcrumbs
+        scope.set_transaction_name(transaction_name(job), source: :task)
+        scope.set_tags(tags(job, queue))
+        scope.set_context(CONTEXT_KEY, context(job, queue))
+        scope
+      end
+
+      def transaction_name(job)
+        "#{TRANSACTION_PREFIX}#{job['class']}"
+      end
+
+      def tags(job, queue)
+        { queue: job['queue'] || queue, jid: job['jid'] }
+      end
+
+      # Deliberately enumerated, never `job.dup.except("args")`: job arguments
+      # routinely carry PII, tokens, or `encrypt: true` ciphertext, and Sentry
+      # is not a place any of that belongs. An allow-list can't leak a new
+      # payload key that a future Wurk release starts stamping.
+      def context(job, queue)
+        {
+          'class' => job['class'],
+          'jid' => job['jid'],
+          'queue' => job['queue'] || queue,
+          'retry_count' => job['retry_count'],
+          'created_at' => job['created_at'],
+          'enqueued_at' => job['enqueued_at']
+        }
+      end
+    end
+  end
+end

data/lib/wurk/sentry/middleware.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative '../middleware'
+require_relative '../job_retry'
+require_relative 'job_context'
+require_relative 'retry_policy'
+
+module Wurk
+  module Sentry
+    # Server middleware: scopes every job for Sentry, and reports the job's
+    # terminal failure.
+    #
+    # Both halves are needed because a *job* failure never reaches
+    # `config.error_handlers`. `JobRetry#local` rescues the exception, books
+    # the retry, and raises `JobRetry::Handled`, which `Processor#process`
+    # swallows — so an error handler alone sees fetch-loop errors and nothing
+    # else. The middleware runs *inside* `JobRetry#local` (see
+    # `Processor#dispatch`), which is the only place the raw exception is
+    # still in flight.
+    #
+    # The exception is always re-raised: Wurk's retry pipeline, not this
+    # middleware, owns the failure.
+    class Middleware
+      include Wurk::Middleware::ServerMiddleware
+
+      def call(instance, job, queue, &block)
+        return yield unless Wurk::Sentry.enabled?
+
+        # Each Processor owns a thread, and Sentry's hub is thread-local.
+        # Without this the worker thread starts from an empty hub and the
+        # scope set below is invisible to the capture.
+        ::Sentry.clone_hub_to_current_thread
+
+        ::Sentry.with_scope do |scope|
+          JobContext.apply(scope, job, queue)
+          monitor(instance, job, &block)
+        end
+      end
+
+      private
+
+      def monitor(instance, job)
+        yield
+      rescue Wurk::JobRetry::Handled, Wurk::Shutdown
+        # Handled/Skip: an inner middleware already booked the outcome (the
+        # limiter re-enqueued, the interrupt handler re-pushed). Shutdown: the
+        # job is requeued and will run again — a deploy is not a failure.
+        raise
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        raise if caused_by_shutdown?(e)
+
+        ::Sentry.capture_exception(e) if RetryPolicy.terminal?(job, instance, config)
+        raise
+      end
+
+      # Mirrors `JobRetry#exception_caused_by_shutdown?`: user code that
+      # rescued `Wurk::Shutdown` and re-raised something else is still a
+      # shutdown, not a job failure.
+      def caused_by_shutdown?(exception, checked = [])
+        cause = exception.cause
+        return false unless cause
+
+        checked << exception.object_id
+        return false if checked.include?(cause.object_id)
+
+        cause.instance_of?(Wurk::Shutdown) || caused_by_shutdown?(cause, checked)
+      end
+    end
+  end
+end

data/lib/wurk/sentry/retry_policy.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require_relative '../job_retry'
+
+module Wurk
+  module Sentry
+    # Answers one question: "if this job raises right now, is that the end of
+    # the road?" Only terminal failures are worth an alert — reporting every
+    # attempt turns a single flaky job into 25 Sentry events over ~21 days.
+    #
+    # The prediction has to be made *ahead* of {Wurk::JobRetry}, because the
+    # server middleware chain runs inside `JobRetry#local` (see
+    # `Processor#dispatch`): the middleware's rescue fires before the retry
+    # layer has touched the payload. So at rescue time `retry_count` is still
+    # the number of retries already *performed*, and this class re-derives
+    # what `JobRetry#process_retry` is about to conclude:
+    #
+    #   * `bump_retry_count` sets `retry_count = 0` on the first failure and
+    #     `retry_count += 1` thereafter — so the post-bump count is
+    #     `retry_count.nil? ? 0 : retry_count + 1`.
+    #   * `exhausted?` kills the job once that count reaches `max_attempts`.
+    #
+    # Which makes the last attempt the one that arrives with
+    # `retry_count == max_attempts - 1` (and, for `retry: 0` / `retry: false`,
+    # the very first one).
+    #
+    # Not predictable from the payload — and therefore reported one attempt
+    # late, or not at all: a `sidekiq_retry_in` block returning `:discard` or
+    # `:kill`. Those are host decisions made after this point.
+    module RetryPolicy
+      module_function
+
+      def terminal?(job, instance = nil, config = nil)
+        retry_option = retry_option_for(job, instance)
+        return true unless retry_option
+        # `retry_for` is a wall-clock budget that supersedes the attempt count
+        # entirely (JobRetry#exhausted? branches on it before looking at max).
+        return retry_for_elapsed?(job) if job['retry_for']
+
+        next_retry_count(job) >= max_attempts(retry_option, config)
+      end
+
+      # Mirrors `JobRetry#local`: a payload with no `retry` key falls back to
+      # the worker class's own `sidekiq_options`.
+      def retry_option_for(job, instance)
+        value = job['retry']
+        return value unless value.nil?
+
+        klass = instance&.class
+        klass.respond_to?(:get_sidekiq_options) ? klass.get_sidekiq_options['retry'] : true
+      end
+
+      def next_retry_count(job)
+        count = job['retry_count']
+        count ? count + 1 : 0
+      end
+
+      def max_attempts(retry_option, config)
+        return retry_option if retry_option.is_a?(::Integer)
+
+        configured_max_retries(config) || Wurk::JobRetry::DEFAULT_MAX_RETRY_ATTEMPTS
+      end
+
+      # `config` is whatever the Chain bound to the middleware — a Capsule in a
+      # running worker, a Configuration in tests. Only the latter has `[]`.
+      def configured_max_retries(config)
+        return nil if config.nil?
+
+        inner = config.respond_to?(:config) ? config.config : config
+        inner.respond_to?(:[]) ? inner[:max_retries] : nil
+      end
+
+      def retry_for_elapsed?(job)
+        failed_at = job['failed_at']
+        # First failure: JobRetry stamps `failed_at = now` and then finds the
+        # budget un-spent, so the job always gets at least one retry.
+        return false unless failed_at
+
+        time_for(failed_at) + job['retry_for'] < ::Time.now
+      end
+
+      # Wire format matches JobRetry#time_for: Float seconds or Integer millis.
+      def time_for(value)
+        return ::Time.at(value) if value.is_a?(::Float)
+
+        ::Time.at(value / 1000, value % 1000, :millisecond)
+      end
+    end
+  end
+end

data/lib/wurk/sentry.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative '../wurk'
+require_relative 'sentry/error_handler'
+require_relative 'sentry/middleware'
+
+module Wurk
+  # Opt-in Sentry integration. Not loaded by `require "wurk"` — pull it in
+  # explicitly and install it on the server config:
+  #
+  #   # config/initializers/wurk.rb
+  #   require "wurk/sentry"
+  #
+  #   Wurk.configure_server do |config|
+  #     Wurk::Sentry.install!(config)
+  #   end
+  #
+  # This exists because `sentry-sidekiq` **cannot be used with Wurk**: its
+  # gemspec declares `add_dependency "sidekiq"`, so Bundler installs real
+  # Sidekiq alongside Wurk and `require "sidekiq"` loads a broken hybrid.
+  # (The `ecosystem/sidekiq-shim/` git source is the escape hatch for gems
+  # you must keep; see docs/sentry.md.)
+  #
+  # `sentry-ruby` is **not** a runtime dependency — it is never required here,
+  # and every call site is guarded by {enabled?}. Loading this file in an app
+  # without sentry-ruby, or before `Sentry.init` has run, is a no-op.
+  #
+  # See docs/sentry.md.
+  module Sentry
+    class << self
+      # Registers the server middleware and the error handler. Idempotent:
+      # `Chain#add` dedupes by class, and a previously-installed
+      # {ErrorHandler} is replaced rather than stacked, so calling this twice
+      # (or calling it after an auto-install) never doubles a report.
+      #
+      # @param config [Wurk::Configuration] usually the block argument of
+      #   `Wurk.configure_server`.
+      # @param filter_transport_errors [Boolean] drop self-healing Redis /
+      #   connection-pool errors instead of reporting them. See
+      #   {ErrorHandler::DEFAULT_FILTERED_ERROR_CLASSES}.
+      # @param filtered_error_classes [Array<Class>, nil] replaces the default
+      #   filter list. Extend it with
+      #   `Wurk::Sentry::ErrorHandler::DEFAULT_FILTERED_ERROR_CLASSES + [MyError]`.
+      # @return [Wurk::Configuration] the config, for chaining.
+      def install!(config = Wurk.configuration, filter_transport_errors: true, filtered_error_classes: nil)
+        config.server_middleware.add(Middleware)
+        install_error_handler(config, filter_transport_errors, filtered_error_classes)
+        config
+      end
+
+      # True only when sentry-ruby is loaded *and* `Sentry.init` has run.
+      # Guards every call into the SDK so the integration is inert by default.
+      def enabled?
+        defined?(::Sentry) && ::Sentry.respond_to?(:initialized?) && ::Sentry.initialized?
+      end
+
+      private
+
+      def install_error_handler(config, filter, classes)
+        handlers = config.error_handlers
+        handlers.reject! { |handler| handler.is_a?(ErrorHandler) }
+        handlers << ErrorHandler.new(
+          filter_transport_errors: filter,
+          filtered_error_classes: classes
+        )
+      end
+    end
+  end
+end

data/lib/wurk/version.rb

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

data/lib/wurk.rb

@@ -224,6 +224,22 @@ module Wurk
     def ent?
       false
     end
+
+    # Lazily loads the Rails engine the first time something asks for
+    # `Wurk::Engine`. See the note above the `require "wurk/rails"` guard at the
+    # bottom of this file for why the guard alone isn't enough (#282), and why
+    # this loads the engine and not the railtie.
+    def const_missing(name)
+      return super unless name == :Engine
+      return super unless defined?(::Rails::Engine) && defined?(::ActionDispatch::Routing::RouteSet)
+
+      require_relative 'wurk/engine'
+      # If engine.rb somehow didn't define it, fall through to the real NameError
+      # rather than recursing back into here.
+      return super unless const_defined?(:Engine, false)
+
+      const_get(:Engine, false)
+    end
   end
 end
 
@@ -318,3 +334,30 @@ require_relative 'wurk/compat'
 # 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)
+
+# The gate above is evaluated exactly once, when this file is first required —
+# which is too early for the standalone runners (#282). `exe/wurk` and
+# `exe/wurkswarm` require "wurk" before Rails exists (the gate is false, nothing
+# Rails-y loads), then boot the host app themselves via
+# Wurk::CLI#boot_rails_application. By then "wurk" is in $LOADED_FEATURES, so the
+# app's own `Bundler.require` is a no-op and the gate never gets a second look. A
+# host that did exactly what the README says — `mount Wurk::Engine => "/wurk"` in
+# config/routes.rb — then dies during boot with `uninitialized constant
+# Wurk::Engine`, from the worker process only. Web processes are unaffected:
+# there Bundler.require runs after railties, so the gate passes.
+#
+# `Wurk.const_missing` (defined in the class << self block above) closes that
+# window without giving up the lean standalone boot: nothing loads until
+# something actually asks for Wurk::Engine, and even then only when Rails is
+# really present. It reuses the same two-part condition as the guard above, so
+# the ecosystem carve-out (rails/engine/railties without ActionDispatch, per
+# sidekiq-cron's test helper) still falls through to a plain NameError instead of
+# crashing on `isolate_namespace`.
+#
+# It deliberately loads `wurk/engine`, not `wurk/rails`: the railtie's
+# `config.after_initialize` is a *global* ActiveSupport load hook registered at
+# require time, and routes are drawn before those hooks run — so dragging the
+# railtie in there would fork a swarm inside a `wurkswarm` parent that is about
+# to fork its own. The runner owns the swarm; the routes file only needs the
+# constant. `defined?(Wurk::Engine)` stays nil until first use, which is what the
+# "standalone stays Rails-free" tests assert.

data/vendor/assets/dashboard/wurk-manifest.json

@@ -1,4 +1,4 @@
 {
-  "version": "1.2.1",
-  "timestamp": "2026-07-24T16:52:00.511Z"
+  "version": "1.3.1",
+  "timestamp": "2026-07-26T15:00:00.106Z"
 }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: wurk
 version: !ruby/object:Gem::Version
-  version: 1.2.1
+  version: 1.3.1
 platform: ruby
 authors:
 - developerz.ai
@@ -270,10 +270,16 @@ files:
 - lib/wurk/railtie.rb
 - lib/wurk/redis_client_adapter.rb
 - lib/wurk/redis_connection.rb
+- lib/wurk/redis_options.rb
 - lib/wurk/redis_pool.rb
 - lib/wurk/retry_set.rb
 - lib/wurk/scheduled.rb
 - lib/wurk/scheduled_set.rb
+- lib/wurk/sentry.rb
+- lib/wurk/sentry/error_handler.rb
+- lib/wurk/sentry/job_context.rb
+- lib/wurk/sentry/middleware.rb
+- lib/wurk/sentry/retry_policy.rb
 - lib/wurk/sorted_entry.rb
 - lib/wurk/stats.rb
 - lib/wurk/swarm.rb