cmdx 1.20.0 → 2.0.0

data/lib/cmdx/retriers/bounded_random.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module CMDx
+  class Retriers
+    # Bounded-random jitter. Produces a uniform delay in `[delay, 2*delay]`.
+    # Guarantees at least the base delay between attempts while still
+    # decorrelating retry timing.
+    #
+    # @api private
+    module BoundedRandom
+
+      extend self
+
+      # @param _attempt [Integer] ignored
+      # @param delay [Float] base delay in seconds
+      # @param _prev_delay [Float, nil] ignored
+      # @return [Float] computed delay
+      def call(_attempt, delay, _prev_delay = nil)
+        delay + (rand * delay)
+      end
+
+    end
+  end
+end

data/lib/cmdx/retriers/decorrelated_jitter.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module CMDx
+  class Retriers
+    # AWS-recommended decorrelated jitter. Produces a uniform delay in
+    # `[delay, prev_delay * 3]`, threading state across attempts via
+    # `prev_delay`. When no previous delay exists the upper bound collapses
+    # to `3 * delay`, matching the AWS reference implementation.
+    #
+    # @see https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/
+    # @api private
+    module DecorrelatedJitter
+
+      extend self
+
+      # @param _attempt [Integer] ignored
+      # @param delay [Float] base delay in seconds (also the lower bound)
+      # @param prev_delay [Float, nil] previous computed delay; falls back to
+      #   `delay` so the first call samples in `[delay, 3*delay]`
+      # @return [Float] computed delay
+      def call(_attempt, delay, prev_delay = nil)
+        base = prev_delay || delay
+        delay + (rand * ((base * 3) - delay))
+      end
+
+    end
+  end
+end

data/lib/cmdx/retriers/exponential.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module CMDx
+  class Retriers
+    # Exponential backoff. Doubles the base delay every attempt:
+    # `delay * (2 ** attempt)`.
+    #
+    # @api private
+    module Exponential
+
+      extend self
+
+      # @param attempt [Integer] zero-based retry attempt
+      # @param delay [Float] base delay in seconds
+      # @param _prev_delay [Float, nil] ignored
+      # @return [Float] computed delay
+      def call(attempt, delay, _prev_delay = nil)
+        delay * (2**attempt)
+      end
+
+    end
+  end
+end

data/lib/cmdx/retriers/fibonacci.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module CMDx
+  class Retriers
+    # Fibonacci backoff. Sleeps `delay * fib(attempt + 1)` where `fib(1) == 1`,
+    # `fib(2) == 1`, `fib(3) == 2`, ... Multipliers grow as 1, 1, 2, 3, 5, 8.
+    # Slower-growing than exponential, faster-growing than linear.
+    #
+    # @api private
+    module Fibonacci
+
+      extend self
+
+      # @param attempt [Integer] zero-based retry attempt
+      # @param delay [Float] base delay in seconds
+      # @param _prev_delay [Float, nil] ignored
+      # @return [Float] computed delay
+      def call(attempt, delay, _prev_delay = nil)
+        delay * sequence(attempt + 1)
+      end
+
+      private
+
+      # Iterative Fibonacci. `sequence(1) == 1`, `sequence(2) == 1`,
+      # `sequence(3) == 2`, ...
+      #
+      # @param n [Integer] one-based index into the Fibonacci sequence
+      # @return [Integer]
+      # @api private
+      def sequence(n)
+        a = 0
+        b = 1
+        n.times { a, b = b, a + b }
+        a
+      end
+
+    end
+  end
+end

data/lib/cmdx/retriers/full_random.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module CMDx
+  class Retriers
+    # Full-random jitter. Produces a uniform delay in `[0, delay]`. Maximizes
+    # spread at the cost of occasional very-fast retries.
+    #
+    # @api private
+    module FullRandom
+
+      extend self
+
+      # @param _attempt [Integer] ignored
+      # @param delay [Float] base delay in seconds
+      # @param _prev_delay [Float, nil] ignored
+      # @return [Float] computed delay
+      def call(_attempt, delay, _prev_delay = nil)
+        rand * delay
+      end
+
+    end
+  end
+end

data/lib/cmdx/retriers/half_random.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module CMDx
+  class Retriers
+    # Half-random jitter. Produces a uniform delay in `[delay/2, delay]`.
+    # Useful when you want a tighter spread than `:full_random` while still
+    # decorrelating retries from synchronized clients.
+    #
+    # @api private
+    module HalfRandom
+
+      extend self
+
+      # @param _attempt [Integer] ignored
+      # @param delay [Float] base delay in seconds
+      # @param _prev_delay [Float, nil] ignored
+      # @return [Float] computed delay
+      def call(_attempt, delay, _prev_delay = nil)
+        (delay / 2.0) + (rand * delay / 2.0)
+      end
+
+    end
+  end
+end

data/lib/cmdx/retriers/linear.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module CMDx
+  class Retriers
+    # Linear backoff. Sleeps `delay * (attempt + 1)` — multiples of the base
+    # delay grow arithmetically (1x, 2x, 3x, ...).
+    #
+    # @api private
+    module Linear
+
+      extend self
+
+      # @param attempt [Integer] zero-based retry attempt
+      # @param delay [Float] base delay in seconds
+      # @param _prev_delay [Float, nil] ignored
+      # @return [Float] computed delay
+      def call(attempt, delay, _prev_delay = nil)
+        delay * (attempt + 1)
+      end
+
+    end
+  end
+end

data/lib/cmdx/retriers.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module CMDx
+  # Registry of named retry/jitter strategies used by `Retry` to compute the
+  # sleep duration between attempts. Ships with built-ins for `:exponential`,
+  # `:half_random`, `:full_random`, `:bounded_random`, `:linear`, `:fibonacci`,
+  # and `:decorrelated_jitter`. A retrier is any callable accepting
+  # `call(attempt, delay, prev_delay)` that returns the next delay in seconds.
+  class Retriers
+
+    attr_reader :registry
+
+    def initialize
+      @registry = {
+        exponential: Retriers::Exponential,
+        half_random: Retriers::HalfRandom,
+        full_random: Retriers::FullRandom,
+        bounded_random: Retriers::BoundedRandom,
+        linear: Retriers::Linear,
+        fibonacci: Retriers::Fibonacci,
+        decorrelated_jitter: Retriers::DecorrelatedJitter
+      }
+    end
+
+    # @param source [Retriers] registry to duplicate
+    # @return [void]
+    def initialize_copy(source)
+      @registry = source.registry.dup
+    end
+
+    # Registers a named retrier, overwriting any existing entry.
+    #
+    # @param name [Symbol]
+    # @param callable [#call, nil] pass either this or a block
+    # @param block [#call, nil] retrier callable when `callable` is omitted
+    # @yield retrier body — `call(attempt, delay, prev_delay)`
+    # @return [Retriers] self for chaining
+    # @raise [ArgumentError] when both `callable` and a block are given, or
+    #   when the resolved retrier isn't callable
+    def register(name, callable = nil, &block)
+      retrier = callable || block
+
+      if callable && block
+        raise ArgumentError, "provide either a callable or a block, not both"
+      elsif !retrier.respond_to?(:call)
+        raise ArgumentError, "retrier must respond to #call"
+      end
+
+      registry[name.to_sym] = retrier
+      self
+    end
+
+    # @param name [Symbol]
+    # @return [Retriers] self for chaining
+    def deregister(name)
+      registry.delete(name.to_sym)
+      self
+    end
+
+    # @param name [Symbol]
+    # @return [Boolean] whether a retrier is registered under `name`
+    def key?(name)
+      registry.key?(name.to_sym)
+    end
+
+    # @param name [Symbol]
+    # @return [#call] the registered retrier
+    # @raise [ArgumentError] when `name` isn't registered
+    def lookup(name)
+      registry[name] || begin
+        raise ArgumentError, "unknown retrier: #{name.inspect}"
+      end
+    end
+
+    # Resolves a `:jitter` spec to a concrete callable. Accepts a Symbol
+    # (registry lookup) or any object responding to `#call`. `nil` resolves
+    # to `nil` so callers can fall back to the unjittered base delay.
+    #
+    # @param spec [Symbol, #call, nil]
+    # @return [#call, nil]
+    # @raise [ArgumentError] when `spec` is an unknown symbol or not callable
+    def resolve(spec)
+      case spec
+      when NilClass
+        nil
+      when Symbol
+        lookup(spec)
+      else
+        return spec if spec.respond_to?(:call)
+
+        raise ArgumentError, "unknown retrier: #{spec.inspect}"
+      end
+    end
+
+    # @return [Boolean]
+    def empty?
+      registry.empty?
+    end
+
+    # @return [Integer]
+    def size
+      registry.size
+    end
+
+  end
+end

data/lib/cmdx/retry.rb

@@ -1,165 +1,144 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Manages retry logic and state for task execution.
-  #
-  # The Retry class tracks retry availability, attempt counts, and
-  # remaining retries for a given task. It also resolves exception
-  # matching and computes wait times using configurable jitter strategies.
+  # Configurable retry-on-exception wrapper around a task's `work`. Supports
+  # exception list, attempt `:limit`, base `:delay`, `:max_delay` cap, and
+  # `:jitter` strategy (symbol, proc, or a configured block). Declared via
+  # `Task.retry_on` and accumulates across inheritance.
   class Retry
 
-    # Returns the task instance associated with this retry.
-    #
-    # @return [Task] the task being retried
-    #
-    # @example
-    #   retry_instance.task # => #<CreateUser ...>
-    #
-    # @rbs @task: Task
-    attr_reader :task
+    attr_reader :exceptions
 
-    # Creates a new Retry instance for the given task.
-    #
-    # @param task [Task] the task to manage retries for
-    #
-    # @return [Retry] a new Retry instance
-    #
-    # @example
-    #   retry_instance = Retry.new(task)
-    #
-    # @rbs (Task task) -> void
-    def initialize(task)
-      @task = task
+    # @param exceptions [Array<Class>] exceptions to retry on
+    # @param options [Hash{Symbol => Object}]
+    # @param block [#call, nil] optional jitter callable used when `:jitter` isn't set
+    # @option options [Integer] :limit (3) maximum retry attempts
+    # @option options [Float] :delay (0.5) base delay in seconds between attempts
+    # @option options [Float] :max_delay clamp for computed delays
+    # @option options [Symbol, Proc, #call] :jitter built-in strategy (`:exponential`,
+    #   `:half_random`, `:full_random`, `:bounded_random`, `:linear`, `:fibonacci`,
+    #   `:decorrelated_jitter`) or custom
+    # @yieldparam attempt [Integer]
+    # @yieldparam delay [Float]
+    def initialize(exceptions, options = EMPTY_HASH, &block)
+      @exceptions = exceptions.flatten
+      @options    = options.freeze
+      @block      = block
     end
 
-    # Returns the total number of retries configured for the task.
-    #
-    # @return [Integer] the configured retry count
-    #
-    # @example
-    #   retry_instance.available # => 3
-    #
-    # @rbs () -> Integer
-    def available
-      Integer(task.class.settings.retries || 0)
-    end
+    # Returns a new Retry layering `new_exceptions` and `new_options` onto the
+    # current one. Used for inheritance so subclasses extend rather than
+    # replace.
+    #
+    # @param new_exceptions [Array<Class>]
+    # @param new_options [Hash{Symbol => Object}]
+    # @param block [#call, nil] replacement jitter callable (falls back to the prior block)
+    # @yield [attempt, delay] optional replacement jitter block
+    # @return [Retry]
+    def build(new_exceptions, new_options, &block)
+      return self if new_exceptions.empty?
 
-    # Checks if the task has any retries configured.
-    #
-    # @return [Boolean] true if retries are configured
-    #
-    # @example
-    #   retry_instance.available? # => true
-    #
-    # @rbs () -> bool
-    def available?
-      available.positive?
+      merged_exceptions = exceptions | new_exceptions.flatten
+      merged_options    = @options.merge(new_options)
+
+      self.class.new(merged_exceptions, merged_options, &block || @block)
     end
 
-    # Returns the number of retry attempts already made.
-    #
-    # @return [Integer] the current retry attempt count
-    #
-    # @example
-    #   retry_instance.attempts # => 1
-    #
-    # @rbs () -> Integer
-    def attempts
-      Integer(task.result.retries || 0)
+    # @return [Integer]
+    def limit
+      @options[:limit] || 3
     end
 
-    # Checks if the task has been retried at least once.
-    #
-    # @return [Boolean] true if at least one retry has occurred
-    #
-    # @example
-    #   retry_instance.retried? # => true
-    #
-    # @rbs () -> bool
-    def retried?
-      attempts.positive?
+    # @return [Float] base delay in seconds
+    def delay
+      @options[:delay] || 0.5
     end
 
-    # Returns the number of retries still available.
-    #
-    # @return [Integer] the remaining retry count
-    #
-    # @example
-    #   retry_instance.remaining # => 2
-    #
-    # @rbs () -> Integer
-    def remaining
-      available - attempts
+    # @return [Float, nil] upper bound for computed delays
+    def max_delay
+      @options[:max_delay]
     end
 
-    # Checks if there are retries still available.
-    #
-    # @return [Boolean] true if remaining retries exist
-    #
-    # @example
-    #   retry_instance.remaining? # => true
-    #
-    # @rbs () -> bool
-    def remaining?
-      remaining.positive?
+    # @return [Symbol, Proc, #call, nil] jitter strategy or the block given to {#initialize}
+    def jitter
+      @options[:jitter] || @block
     end
 
-    # Returns the list of exception classes eligible for retry.
-    #
-    # @return [Array<Class>] exception classes that trigger a retry
-    #
-    # @example
-    #   retry_instance.exceptions # => [StandardError, CMDx::TimeoutError]
-    #
-    # @rbs () -> Array[Class]
-    def exceptions
-      @exceptions ||= Utils::Wrap.array(
-        task.class.settings.retry_on ||
-        [StandardError, CMDx::TimeoutError]
-      )
+    # Sleeps `attempt`'s jittered/bounded delay. No-op when the base delay is zero.
+    #
+    # @param attempt [Integer] zero-based retry attempt number
+    # @param task [Task, nil] used as receiver for Symbol/Proc jitter strategies
+    # @param prev_delay [Float, nil] previous computed delay; only consumed by
+    #   `:decorrelated_jitter` to thread state across attempts
+    # @return [Float, nil] the computed (and possibly clamped) delay, or `nil` when
+    #   `delay` is zero
+    def wait(attempt, task = nil, prev_delay = nil)
+      return unless delay.positive?
+
+      d =
+        case jitter
+        when NilClass
+          delay
+        when Symbol
+          registry = retriers_registry(task)
+
+          if registry.key?(jitter)
+            registry.lookup(jitter).call(attempt, delay, prev_delay)
+          else
+            task.send(jitter, attempt, delay)
+          end
+        when Proc
+          task.instance_exec(attempt, delay, &jitter)
+        else
+          if jitter.respond_to?(:call)
+            jitter.call(attempt, delay)
+          else
+            delay
+          end
+        end
+
+      d = d.clamp(0, max_delay) if max_delay
+      Kernel.sleep(d) if d.positive?
+      d
     end
 
-    # Checks if the given exception matches any configured retry exception.
-    #
-    # @param exception [Exception] the exception to check
-    #
-    # @return [Boolean] true if the exception qualifies for retry
-    #
-    # @example
-    #   retry_instance.exception?(RuntimeError.new("fail")) # => true
-    #
-    # @rbs (Exception exception) -> bool
-    def exception?(exception)
-      exceptions.any? { |e| exception.class <= e }
+    # Executes the block up to `limit + 1` times. Re-raises the last
+    # exception when attempts are exhausted.
+    #
+    # @param task [Task, nil] passed to {#wait} so jitter strategies can use it
+    # @yieldparam attempt [Integer] zero-based attempt index
+    # @yieldreturn [Object] the block's successful return value
+    # @return [Object] the block's successful return value
+    # @raise [Exception] the last caught exception once retries exhaust
+    def process(task = nil, &)
+      return yield(0) if exceptions.empty? || !limit.positive?
+
+      prev_delay = nil
+      (limit + 1).times do |attempt|
+        return yield(attempt)
+      rescue *exceptions => e
+        raise(e) if attempt >= limit
+        raise(e) unless Util.satisfied?(@options[:if], @options[:unless], task, e, attempt)
+
+        prev_delay = wait(attempt, task, prev_delay)
+      end
     end
 
-    # Computes the wait time before the next retry attempt.
-    #
-    # Supports multiple jitter strategies: a Symbol calls a task method,
-    # a Proc is evaluated in the task instance context, a callable object
-    # receives the task and attempts, and a Numeric is multiplied by the
-    # attempt count.
-    #
-    # @return [Float] the wait duration in seconds
-    #
-    # @example With numeric jitter (0.5 * attempts)
-    #   retry_instance.wait # => 1.0
-    # @example With symbol jitter referencing a task method
-    #   retry_instance.wait # => 2.5
-    #
-    # @rbs () -> Float
-    def wait
-      jitter = task.class.settings.retry_jitter
-
-      if jitter.is_a?(Symbol)
-        task.send(jitter, attempts)
-      elsif jitter.is_a?(Proc)
-        task.instance_exec(attempts, &jitter)
-      elsif jitter.respond_to?(:call)
-        jitter.call(task, attempts)
+    private
+
+    # Resolves the retriers registry to consult for built-in jitter strategies.
+    # Prefers the task class's registry (so per-task `register(:retrier, ...)`
+    # overrides take effect) and falls back to the global configuration when
+    # no task is supplied.
+    #
+    # @param task [Task, nil]
+    # @return [Retriers]
+    def retriers_registry(task)
+      if task && task.class.respond_to?(:retriers)
+        task.class.retriers
       else
-        jitter.to_f * attempts
-      end.to_f
+        CMDx.configuration.retriers
+      end
     end
 
   end