wurk 0.0.1

data/lib/wurk/job_record.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'zlib'
+
+module Wurk
+  # One job payload viewed from the data API (Queue#each / JobSet#each).
+  # Wraps the raw JSON string from Redis; parses lazily so an O(n) scan
+  # over a large queue doesn't pay JSON cost for jobs that go unused.
+  #
+  # The `value` (raw JSON string) is what Redis stores; `LREM` matches
+  # exact bytes, so `delete` must use it rather than re-serialize.
+  #
+  # Spec: docs/target/sidekiq-free.md §19.3.
+  class JobRecord
+    # Pre-compiled. ActiveJob's wrapper class varies per Rails minor
+    # (`ActiveJob::QueueAdapters::SidekiqAdapter::JobWrapper`,
+    # `ActiveJob::QueueAdapters::WurkAdapter::JobWrapper`, etc.).
+    ACTIVE_JOB_WRAPPER = /\AActiveJob::QueueAdapters::.+::JobWrapper\z/
+    ACTION_MAILER_JOBS = %w[
+      ActionMailer::DeliveryJob
+      ActionMailer::Parameterized::DeliveryJob
+      ActionMailer::MailDeliveryJob
+    ].freeze
+
+    attr_reader :queue
+
+    # @param item [String, Hash] raw JSON payload or pre-parsed hash.
+    # @param queue_name [String, nil] queue this record came from.
+    def initialize(item, queue_name = nil)
+      if item.is_a?(String)
+        @value = item
+        @item = nil
+      else
+        @item = item
+        @value = nil
+      end
+      @queue = queue_name || (@item && @item['queue'])
+    end
+
+    # Lazily parsed payload. Memoized; never re-parses.
+    def item
+      @item ||= Wurk.load_json(@value)
+    end
+
+    # Lazily serialized payload. When constructed from a Hash, we
+    # generate JSON on first call so `delete` (LREM) has exact bytes.
+    def value
+      @value ||= Wurk.dump_json(@item)
+    end
+
+    def klass         = item['class']
+    def args          = item['args']
+    def jid           = item['jid']
+    def bid           = item['bid']
+    def tags          = item['tags'] || []
+    def enqueued_at   = parse_time(item['enqueued_at'])
+    def created_at    = parse_time(item['created_at'])
+    def failed_at     = parse_time(item['failed_at'])
+    def retried_at    = parse_time(item['retried_at'])
+
+    # Hash-like reader for arbitrary payload fields. Spec §19.3.
+    def [](name) = item[name]
+
+    # Sidekiq compresses the bt as base64(zlib.deflate(JSON.dump(bt))).
+    # Returns nil when no error has been recorded.
+    def error_backtrace
+      compressed = item['error_backtrace']
+      return nil unless compressed
+
+      Wurk.load_json(Zlib.inflate(Base64.decode64(compressed)))
+    rescue Zlib::DataError, ArgumentError, ::JSON::ParserError
+      nil
+    end
+
+    # Seconds since enqueued_at. Handles legacy float-seconds and
+    # current integer-ms `enqueued_at` shapes. Returns 0.0 when missing
+    # or somehow in the future (clock skew).
+    def latency
+      JobRecord.latency_from(item['enqueued_at'])
+    end
+
+    # Removes exactly this payload's bytes from the queue list. Returns
+    # true when LREM removed ≥1 entry. Idempotent. Method name is
+    # Sidekiq wire-compat — renaming would break `JobRecord#delete`.
+    def delete # rubocop:disable Naming/PredicateMethod
+      removed = Wurk.redis { |c| c.call('LREM', Keys.queue(@queue), 1, value) }
+      removed.to_i.positive?
+    end
+
+    # ActiveJob/ActionMailer unwrappers — UI-facing only. For plain Wurk
+    # workers, returns the raw class name.
+    def display_class
+      return @display_class if defined?(@display_class)
+
+      @display_class = active_job_wrapper? ? unwrap_class : klass
+    end
+
+    def display_args
+      return @display_args if defined?(@display_args)
+
+      @display_args = active_job_wrapper? ? unwrap_args : args
+    end
+
+    # @api internal
+    # Shared latency math: ms ints (>= 10^10) and float secs (< 10^10)
+    # both stored in `enqueued_at` historically. See spec §31.5.
+    def self.latency_from(enqueued_at, now_ms = nil)
+      return 0.0 if enqueued_at.nil?
+
+      now_ms ||= ::Process.clock_gettime(::Process::CLOCK_REALTIME, :millisecond)
+      enq_ms = enqueued_at < 10_000_000_000 ? enqueued_at * 1_000 : enqueued_at
+      diff = (now_ms - enq_ms) / 1_000.0
+      diff.negative? ? 0.0 : diff
+    end
+
+    private
+
+    def active_job_wrapper?
+      klass.is_a?(String) && (ACTIVE_JOB_WRAPPER.match?(klass) || klass == 'Sidekiq::ActiveJob::Wrapper')
+    end
+
+    def unwrap_class
+      job_class = item['wrapped'] || args.dig(0, 'job_class')
+      return klass unless job_class
+
+      mailer_display(job_class) || job_class
+    end
+
+    def mailer_display(job_class)
+      return nil unless ACTION_MAILER_JOBS.include?(job_class)
+
+      mailer_args = args.dig(0, 'arguments') || []
+      return nil if mailer_args.size < 2
+
+      "#{mailer_args[0]}##{mailer_args[1]}"
+    end
+
+    def unwrap_args
+      job_args = args.dig(0, 'arguments') || []
+      wrapped = item['wrapped']
+      return job_args unless ACTION_MAILER_JOBS.include?(wrapped)
+
+      # ActionMailer payloads start with [mailer, method, "deliver_now", *real_args]
+      job_args.drop(3)
+    end
+
+    # Parse Sidekiq's mixed time formats (Float secs, Integer ms) into Time.
+    def parse_time(value)
+      return nil if value.nil?
+
+      ms = value < 10_000_000_000 ? value * 1_000 : value
+      ::Time.at(ms / 1_000.0)
+    end
+  end
+end

data/lib/wurk/job_retry.rb

@@ -0,0 +1,320 @@
+# frozen_string_literal: true
+
+require 'zlib'
+require_relative 'component'
+
+module Wurk
+  # Owns the retry pipeline. When perform raises, JobRetry decides whether to
+  # reschedule (`retry` ZSET, exponential backoff + jitter), drop, kill, or
+  # send to the morgue. Wire-compat sacred: error_message / error_class /
+  # retry_count / failed_at / retried_at / error_backtrace field names and
+  # encodings (base64 of zlib of JSON for the backtrace) match Sidekiq byte
+  # for byte — third-party gems and the dashboard read them directly.
+  #
+  # Two entry points wrap the dispatch onion in Processor#dispatch:
+  #
+  #   * `global(jobstr, queue)` — outermost, no job instance required.
+  #     Rescues `Exception` so pre-instantiation failures (const_get, reloader)
+  #     still get a retry recorded. Re-raises `Handled` so the processor
+  #     skips ACK logging.
+  #   * `local(jobinst, jobstr, queue)` — inner, runs after the worker is
+  #     instantiated. Honors per-class `sidekiq_retry_in_block` /
+  #     `sidekiq_retries_exhausted_block` (and the wrapped-class variants).
+  #     Raises `Handled` after booking the retry so `global` does not double-
+  #     process the failure.
+  #
+  # Spec: docs/target/sidekiq-free.md §17.
+  class JobRetry # rubocop:disable Metrics/ClassLength
+    include Component
+
+    DEFAULT_MAX_RETRY_ATTEMPTS = 25
+
+    # Raised after process_retry has dealt with the failure. The processor
+    # rescues `Handled` and exits the job cleanly (acked, no re-raise).
+    class Handled < ::RuntimeError; end
+
+    # Subclass of Handled with the same semantics — used when middleware
+    # short-circuits processing (e.g. interrupt-handler re-pushed the job).
+    class Skip < Handled; end
+
+    def initialize(capsule)
+      @capsule = capsule
+      @config = capsule
+      @max_retries = inner_config_get(:max_retries) || DEFAULT_MAX_RETRY_ATTEMPTS
+      @backtrace_cleaner = inner_config_get(:backtrace_cleaner)
+    end
+
+    # Outermost retry guard. Rescues `Exception` so const_get / reloader
+    # failures still get a retry. `Handled` is re-raised intact; `Shutdown`
+    # bubbles up so the swarm can drain.
+    def global(jobstr, queue)
+      yield
+    rescue Handled, Wurk::Shutdown
+      raise
+    rescue Exception => e # rubocop:disable Lint/RescueException
+      raise Wurk::Shutdown if exception_caused_by_shutdown?(e)
+
+      msg = Wurk.load_json(jobstr)
+      if msg['retry']
+        process_retry(nil, msg, queue, e)
+      else
+        run_death_handlers(msg, e)
+      end
+
+      raise Handled
+    end
+
+    # Per-job retry guard. Same rescue semantics as `global` but the worker
+    # instance is in hand, so per-class `sidekiq_retry_in_block` and
+    # `sidekiq_retries_exhausted_block` can run. Raises `Handled` to short-
+    # circuit `global`'s rescue.
+    def local(jobinst, jobstr, queue)
+      yield
+    rescue Handled, Wurk::Shutdown
+      raise
+    rescue Exception => e # rubocop:disable Lint/RescueException
+      raise Wurk::Shutdown if exception_caused_by_shutdown?(e)
+
+      msg = Wurk.load_json(jobstr)
+      msg['retry'] = jobinst.class.get_sidekiq_options['retry'] if msg['retry'].nil?
+
+      raise e unless msg['retry']
+
+      process_retry(jobinst, msg, queue, e)
+      raise Handled
+    end
+
+    # Component's `handle_exception` delegates to `config.handle_exception`.
+    # When initialized with a Capsule, that's not defined directly; route
+    # through the underlying Configuration.
+    def handle_exception(ex, ctx = {})
+      inner_config.handle_exception(ex, ctx)
+    end
+
+    private
+
+    def now_ms
+      ::Process.clock_gettime(::Process::CLOCK_REALTIME, :millisecond)
+    end
+
+    # Bumps retry counters, stamps the error payload, decides next action:
+    #   * `retry_for` exceeded → retries_exhausted
+    #   * count >= attempts    → retries_exhausted
+    #   * sidekiq_retry_in returned :discard → drop + death_handlers
+    #   * sidekiq_retry_in returned :kill    → retries_exhausted (morgue)
+    #   * otherwise → ZADD into `retry` at now + delay + jitter
+    def process_retry(jobinst, msg, queue, exception)
+      max_attempts = retry_attempts_from(msg['retry'], @max_retries)
+
+      msg['queue'] = msg['retry_queue'] || queue
+
+      stamp_error(msg, exception)
+      count = bump_retry_count(msg)
+      stamp_backtrace(msg, exception)
+
+      return if exhausted?(jobinst, msg, count, max_attempts, exception)
+
+      strategy, delay = delay_for(jobinst, count, exception, msg)
+      case strategy
+      when :discard
+        msg['discarded_at'] = now_ms
+        return run_death_handlers(msg, exception)
+      when :kill
+        return retries_exhausted(jobinst, msg, exception)
+      end
+
+      schedule_retry(msg, count, delay)
+    end
+
+    def exhausted?(jobinst, msg, count, max_attempts, exception)
+      rf = msg['retry_for']
+      if rf
+        return false unless retry_for_exceeded?(msg['failed_at'], rf)
+      elsif count < max_attempts
+        return false
+      end
+      retries_exhausted(jobinst, msg, exception)
+      true
+    end
+
+    def stamp_error(msg, exception)
+      m = exception_message(exception)
+      if m.respond_to?(:scrub!)
+        m.force_encoding(::Encoding::UTF_8)
+        m.scrub!
+      end
+      msg['error_message'] = m
+      msg['error_class'] = exception.class.name
+    end
+
+    # Returns the resulting count. First failure: `retry_count=0`, `failed_at`
+    # set; subsequent failures bump `retry_count` and set `retried_at`.
+    def bump_retry_count(msg)
+      if msg['retry_count']
+        msg['retried_at'] = now_ms
+        msg['retry_count'] += 1
+      else
+        msg['failed_at'] = now_ms
+        msg['retry_count'] = 0
+      end
+    end
+
+    # `backtrace: true` → keep all; `backtrace: N` → keep first N.
+    # Stored as base64(zlib(JSON(lines))) — wire-compat with Sidekiq, keeps
+    # Redis payload size bounded for jobs with deep stacks.
+    def stamp_backtrace(msg, exception)
+      return unless msg['backtrace']
+      return if exception.backtrace.nil?
+
+      cleaned = (@backtrace_cleaner || ->(bt) { bt }).call(exception.backtrace)
+      lines = msg['backtrace'] == true ? cleaned : cleaned[0...msg['backtrace'].to_i]
+      msg['error_backtrace'] = compress_backtrace(lines)
+    end
+
+    def retry_for_exceeded?(failed_at, retry_for)
+      return false unless failed_at
+
+      time_for(failed_at) + retry_for < ::Time.now
+    end
+
+    def schedule_retry(msg, count, delay)
+      jitter = rand(10 * (count + 1))
+      retry_at = ::Time.now.to_f + delay + jitter
+      payload = Wurk.dump_json(msg)
+      redis do |conn|
+        conn.call('ZADD', Keys::RETRY, retry_at.to_s, payload)
+      end
+      Wurk::Metrics::Statsd.increment(
+        'jobs.retried',
+        tags: ["worker:#{msg['class']}", "queue:#{msg['queue']}"]
+      )
+    end
+
+    def time_for(item)
+      if item.is_a?(::Float)
+        ::Time.at(item)
+      else
+        ::Time.at(item / 1000, item % 1000)
+      end
+    end
+
+    # Returns `[strategy, seconds]`. Strategy ∈ {:default, :discard, :kill}.
+    # Caller branches on strategy; seconds is meaningful only for :default.
+    def delay_for(jobinst, count, exception, msg)
+      rv = run_retry_in_block(jobinst, count, exception, msg)
+      rv = rv.to_i if rv.is_a?(::Float)
+      default_delay = (count**4) + 15
+
+      case rv
+      when ::Integer
+        return [:default, rv] if rv.positive?
+      when :discard
+        return [:discard, nil]
+      when :kill
+        return [:kill, nil]
+      end
+
+      [:default, default_delay]
+    end
+
+    def run_retry_in_block(jobinst, count, exception, msg) # rubocop:disable Metrics/CyclomaticComplexity
+      block = jobinst&.class&.sidekiq_retry_in_block
+      block = wrapped_block(msg, :sidekiq_retry_in_block) || block if msg['wrapped']
+      block&.call(count, exception, msg)
+    rescue ::Exception => e # rubocop:disable Lint/RescueException
+      handle_exception(e, context: "Failure scheduling retry via `sidekiq_retry_in` on #{jobinst&.class&.name}")
+      nil
+    end
+
+    # Runs `sidekiq_retries_exhausted` (or the wrapped-class variant). Then
+    # `:discard` / `msg["dead"] == false` skips the morgue; otherwise the
+    # raw JSON is ZADD'd into `dead` and trimmed. Death handlers always fire.
+    def retries_exhausted(jobinst, msg, exception)
+      rv = run_exhausted_block(jobinst, msg, exception)
+      discarded = msg['dead'] == false || rv == :discard
+
+      if discarded
+        msg['discarded_at'] = now_ms
+      else
+        send_to_morgue(msg)
+      end
+
+      run_death_handlers(msg, exception)
+    end
+
+    def run_exhausted_block(jobinst, msg, exception)
+      block = jobinst&.class&.sidekiq_retries_exhausted_block
+      block = wrapped_block(msg, :sidekiq_retries_exhausted_block) || block if msg['wrapped']
+      block&.call(msg, exception)
+    rescue ::Exception => e # rubocop:disable Lint/RescueException
+      handle_exception(e, context: 'Error calling retries_exhausted', job: msg)
+      nil
+    end
+
+    # Wrappers (ActiveJob, custom) expose retry blocks on the wrapped class
+    # via `msg["wrapped"]`. We look up the constant and prefer its block.
+    def wrapped_block(msg, attr)
+      wrapped = ::Object.const_get(msg['wrapped'])
+      wrapped.respond_to?(attr) ? wrapped.public_send(attr) : nil
+    rescue ::NameError
+      nil
+    end
+
+    def send_to_morgue(msg)
+      logger.info { "Adding dead #{msg['class']} job #{msg['jid']}" }
+      payload = Wurk.dump_json(msg)
+      now = ::Time.now.to_f
+      redis { |conn| conn.call('ZADD', Keys::DEAD, now.to_s, payload) }
+      DeadSet.new.trim
+    end
+
+    def run_death_handlers(job, exception)
+      inner_config.death_handlers.each do |handler|
+        handler.call(job, exception)
+      rescue ::StandardError => e
+        handle_exception(e, context: 'Error calling death handler', job: job)
+      end
+    end
+
+    def retry_attempts_from(msg_retry, default)
+      msg_retry.is_a?(::Integer) ? msg_retry : default
+    end
+
+    # Walks `e.cause` chain looking for a `Wurk::Shutdown`. Prevents user
+    # `rescue => e` blocks (that should have re-raised Shutdown) from being
+    # treated as a normal failure that triggers retry recording.
+    def exception_caused_by_shutdown?(exception, checked = [])
+      return false unless exception.cause
+
+      checked << exception.object_id
+      return false if checked.include?(exception.cause.object_id)
+
+      exception.cause.instance_of?(Wurk::Shutdown) ||
+        exception_caused_by_shutdown?(exception.cause, checked)
+    end
+
+    def exception_message(exception)
+      exception.message.to_s[0, 10_000]
+    rescue ::StandardError
+      +'!!! ERROR MESSAGE THREW AN ERROR !!!'
+    end
+
+    def compress_backtrace(backtrace)
+      serialized = Wurk.dump_json(backtrace)
+      compressed = ::Zlib::Deflate.deflate(serialized)
+      [compressed].pack('m0')
+    end
+
+    # Returns the Configuration even when @capsule is a Capsule. Capsule
+    # exposes config via `#config`; if a bare Configuration was passed
+    # (tests, embedded mode), it's already the config.
+    def inner_config
+      @capsule.respond_to?(:config) ? @capsule.config : @capsule
+    end
+
+    def inner_config_get(key)
+      cfg = inner_config
+      cfg.respond_to?(:[]) ? cfg[key] : nil
+    end
+  end
+end

data/lib/wurk/job_set.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+require_relative 'sorted_entry'
+
+module Wurk
+  # Base class for the three Sidekiq-compatible sorted-set views over Redis
+  # (`schedule`, `retry`, `dead`). Splits responsibilities: `SortedSet` owns
+  # the generic ZSET reads/clear; `JobSet` owns the job-aware mutations
+  # (schedule/retry_all/kill_all and the JobRecord-yielding iteration).
+  #
+  # Subclasses pick the key by passing it to `super` in `initialize`:
+  #   class RetrySet < JobSet ; def initialize ; super('retry') ; end ; end
+  #
+  # Wire-compat: every Redis call below matches Sidekiq OSS exactly.
+  # Spec: docs/target/sidekiq-free.md §19.5.
+  class SortedSet
+    include Enumerable
+
+    # Page size for paged ZRANGE — matches upstream so dashboards observing
+    # Redis traffic see the same query pattern.
+    PAGE_SIZE = 50
+
+    attr_reader :name
+
+    def initialize(name)
+      @name = name.to_s
+    end
+
+    # ZCARD. O(1) on Redis side.
+    def size
+      Wurk.redis { |conn| conn.call('ZCARD', @name) }
+    end
+
+    # Streams every (value, score) pair through ZSCAN. `match` is wrapped in
+    # `*` glob characters — callers pass a jid or class name fragment.
+    # @yield [String, Float] raw JSON payload and its score.
+    def scan(match, count = 100)
+      return enum_for(:scan, match, count) unless block_given?
+
+      cursor = '0'
+      pattern = "*#{match}*"
+      Wurk.redis do |conn|
+        loop do
+          cursor, pairs = conn.call('ZSCAN', @name, cursor, 'MATCH', pattern, 'COUNT', count)
+          pairs.each_slice(2) { |value, score| yield value, score.to_f }
+          break if cursor == '0'
+        end
+      end
+    end
+
+    # UNLINK over the whole set. Idempotent. Method name is Sidekiq
+    # wire-compat — `clear?` would break the alias.
+    def clear # rubocop:disable Naming/PredicateMethod
+      Wurk.redis { |conn| conn.call('UNLINK', @name) }
+      true
+    end
+
+    def as_json(_options = nil) = { name: @name }
+  end
+
+  # ZSET-of-jobs view. Reverse-paged iteration so callers see newest-first
+  # (highest score, i.e. furthest-out retry/schedule). Mutations use
+  # ZREM-by-value when the exact bytes are known and a (score, jid) scan
+  # otherwise.
+  #
+  # Spec: docs/target/sidekiq-free.md §19.5.
+  class JobSet < SortedSet
+    # ZADD with NX so re-scheduling the same payload doesn't reset its score.
+    # Mirrors Sidekiq::JobSet#schedule exactly.
+    def schedule(timestamp, message)
+      Wurk.redis { |conn| conn.call('ZADD', @name, timestamp.to_f.to_s, Wurk.dump_json(message)) }
+    end
+
+    # Newest-first paged ZRANGE. Yields a SortedEntry per row.
+    def each
+      return enum_for(:each) unless block_given?
+
+      page  = 0
+      added = 0
+      loop do
+        start = page * PAGE_SIZE
+        stop  = start + PAGE_SIZE - 1
+        slice = Wurk.redis { |conn| conn.call('ZRANGE', @name, start, stop, 'REV', 'WITHSCORES') }
+        slice.each do |value, score|
+          yield SortedEntry.new(self, score, value)
+          added += 1
+        end
+        break if slice.size < PAGE_SIZE
+
+        page += 1
+      end
+      added
+    end
+
+    # ZPOPMIN loop. Each iteration pops the single oldest member (lowest
+    # score, e.g. earliest scheduled-at) and yields the raw JSON + score.
+    # Used by the scheduled-poller: it enqueues each popped job through the
+    # client. Stops when the set is empty.
+    def pop_each
+      loop do
+        result = Wurk.redis { |conn| conn.call('ZPOPMIN', @name, 1) }
+        break if result.nil? || result.empty?
+
+        # Newer redis-client returns nested `[[value, score]]` even with COUNT 1;
+        # older `[value, score]`. Normalize both.
+        value, score = result.first.is_a?(Array) ? result.first : result
+        yield value, score.to_f
+      end
+    end
+
+    # Re-enqueues every job in this set via the client. Lossy on errors
+    # mid-iteration; callers expecting transactional behavior should
+    # batch the work themselves.
+    def retry_all
+      count = 0
+      until size.zero?
+        each do |entry|
+          entry.retry
+          count += 1
+        end
+      end
+      count
+    end
+
+    # Moves every job in this set to the dead set. `notify_failure: false`
+    # because this is a UI-initiated bulk action, not a retry-exhausted
+    # event. Returns the count of jobs moved.
+    def kill_all(notify_failure: false, ex: nil)
+      count = 0
+      dead = DeadSet.new
+      until size.zero?
+        each do |entry|
+          entry.send(:remove_job) do |message|
+            dead.kill(Wurk.dump_json(message), notify_failure: notify_failure, ex: ex)
+          end
+          count += 1
+        end
+      end
+      count
+    end
+
+    # O(score) lookup. `score` accepts Time, Numeric, or a Range of either.
+    # Returns the matching entries (possibly multiple at the same exact
+    # score). When `jid` is set, narrows to the single (score, jid) pair.
+    def fetch(score, jid = nil)
+      results = Wurk.redis { |conn| conn.call('ZRANGEBYSCORE', @name, *range_args(score), 'WITHSCORES') }
+      entries = results.map { |value, sc| SortedEntry.new(self, sc, value) }
+      return entries unless jid
+
+      entries.select { |e| e.jid == jid }
+    end
+
+    # ZSCAN-based search by jid substring. Returns the first matching entry
+    # or nil. O(n) on the ZSET — callers iterating many jids should switch
+    # to per-jid hashes or the score-based fetch.
+    def find_job(jid)
+      scan(jid) do |value, score|
+        entry = SortedEntry.new(self, score, value)
+        return entry if entry.jid == jid
+      end
+      nil
+    end
+
+    # Removes the exact (score, jid)-matching member. Backs SortedEntry#delete
+    # when no cached value bytes are present.
+    def remove_job(entry)
+      delete_by_value(@name, entry.value) || delete_by_jid(entry.score, entry.jid)
+    end
+
+    # ZREM by exact bytes. Returns true when ≥1 element was removed. Method
+    # name is Sidekiq wire-compat — `delete_by_value?` would break the alias.
+    def delete_by_value(name, value) # rubocop:disable Naming/PredicateMethod
+      removed = Wurk.redis { |conn| conn.call('ZREM', name, value) }
+      removed.to_i.positive?
+    end
+
+    # Scan the score bracket for a jid match, ZREM the exact bytes once found.
+    # Returns true on success. Aliased as `delete` for Sidekiq wire-compat.
+    # Per-row JSON rescue so a single malformed entry can't shadow a valid
+    # match at the same score.
+    def delete_by_jid(score, jid) # rubocop:disable Naming/PredicateMethod
+      Wurk.redis do |conn|
+        rows = conn.call('ZRANGEBYSCORE', @name, score.to_f, score.to_f)
+        rows.each do |raw|
+          parsed = begin
+            Wurk.load_json(raw)
+          rescue ::JSON::ParserError
+            nil
+          end
+          next unless parsed && parsed['jid'] == jid
+
+          return conn.call('ZREM', @name, raw).to_i.positive?
+        end
+      end
+      false
+    end
+    alias delete delete_by_jid
+
+    private
+
+    # Translates ZRANGEBYSCORE input shapes (Time, Numeric, Range) to the
+    # `min max` pair Redis expects.
+    def range_args(score)
+      case score
+      when Range then [score.begin.to_f, score.end.to_f]
+      when ::Time, Numeric then [score.to_f, score.to_f]
+      else
+        raise ArgumentError, "score must be Numeric, Time, or Range: #{score.inspect}"
+      end
+    end
+  end
+end