wurk 1.2.1 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6924007f22a9b940826d61f2eb5b60dc58efd2557fc0cce886a06f8b901a9afd
-  data.tar.gz: ccac331e25f6cf03aa9c11165e237d5167aebc24f554822fb2b61a62fd2949b6
+  metadata.gz: be0f3ba28a3db0217dc5a1a99eff9e0d2154eafb6e7a1b2c005df1c479ef7156
+  data.tar.gz: 69aff128e339a14b77e8e28927bd5c1168eaf308ff1b4d08b27b215bb4d24a76
 SHA512:
-  metadata.gz: e3021cb0c71aee76255849da78c97f520ec91244cf35991ece101867194384a8791308926c239b898b36226eba1e8c438c43088ca2d9797fa7a93afe54852a4a
-  data.tar.gz: 5181dd6eb9a19c285f7d20346c0e15f3bafeeb211be5ba0dbfa0fb2e90a4399f72d99384fc9ea4119a7db9722f684b3269a1a63379421a5e9b73fdcf230cb998
+  metadata.gz: 505ff2863233ddfd349bc28a213cebf91e8d81d6146d68306304aca78235fba82a55061d9e67db6e97ca2638ed61f184ef36f97152035c1c4d2d32b06cd85cae
+  data.tar.gz: b60e5455d8352e4e16aa6d025c70253dff1af1637dfc73ca244781e22059efd8201a826afc6c441638e062db6d5b84987036c885b9d5451d68aab05ac0583522

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/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.0"
 end

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.0",
+  "timestamp": "2026-07-26T14:23:49.421Z"
 }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: wurk
 version: !ruby/object:Gem::Version
-  version: 1.2.1
+  version: 1.3.0
 platform: ruby
 authors:
 - developerz.ai
@@ -274,6 +274,11 @@ files:
 - 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