Class: CMDx::Retry

Inherits:
Object
  • Object
show all
Defined in:
lib/cmdx/retry.rb

Overview

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.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(exceptions, options = EMPTY_HASH, &block) {|attempt, delay| ... } ⇒ Retry

Returns a new instance of Retry.

Parameters:

  • exceptions (Array<Class>) —

    exceptions to retry on

  • options (Hash{Symbol => Object}) (defaults to: EMPTY_HASH)
  • block (#call, nil) —

    optional jitter callable used when :jitter isn't set

Options Hash (options):

  • :limit (Integer) — default: 3 —

    maximum retry attempts

  • :delay (Float) — default: 0.5 —

    base delay in seconds between attempts

  • :max_delay (Float) —

    clamp for computed delays

  • :jitter (Symbol, Proc, #call) —

    built-in strategy (:exponential, :half_random, :full_random, :bounded_random, :linear, :fibonacci, :decorrelated_jitter) or custom

Yield Parameters:

  • attempt (Integer)
  • delay (Float) 


23
24
25
26
27
 
# File 'lib/cmdx/retry.rb', line 23

def initialize(exceptions, options = EMPTY_HASH, &block)
  @exceptions = exceptions.flatten
  @options    = options.freeze
  @block      = block
end

Instance Attribute Details

#exceptions ⇒ Object (readonly)

Returns the value of attribute exceptions.



10
11
12
 
# File 'lib/cmdx/retry.rb', line 10

def exceptions
  @exceptions
end

Instance Method Details

#build(new_exceptions, new_options, &block) {|attempt, delay| ... } ⇒ Retry

Returns a new Retry layering new_exceptions and new_options onto the current one. Used for inheritance so subclasses extend rather than replace.

Parameters:

  • new_exceptions (Array<Class>)
  • new_options (Hash{Symbol => Object})
  • block (#call, nil) —

    replacement jitter callable (falls back to the prior block)

Yields:

  • (attempt, delay) —

    optional replacement jitter block

Returns:



38
39
40
41
42
43
44
45
 
# File 'lib/cmdx/retry.rb', line 38

def build(new_exceptions, new_options, &block)
  return self if new_exceptions.empty?

  merged_exceptions = exceptions | new_exceptions.flatten
  merged_options    = @options.merge(new_options)

  self.class.new(merged_exceptions, merged_options, &block || @block)
end

#delay ⇒ Float

Returns base delay in seconds.

Returns:

  • (Float) —

    base delay in seconds



53
54
55
 
# File 'lib/cmdx/retry.rb', line 53

def delay
  @options[:delay] || 0.5
end

#jitter ⇒ Symbol, ...

Returns jitter strategy or the block given to #initialize.

Returns:

  • (Symbol, Proc, #call, nil) —

    jitter strategy or the block given to #initialize



63
64
65
 
# File 'lib/cmdx/retry.rb', line 63

def jitter
  @options[:jitter] || @block
end

#limit ⇒ Integer

Returns:

  • (Integer) 


48
49
50
 
# File 'lib/cmdx/retry.rb', line 48

def limit
  @options[:limit] || 3
end

#max_delay ⇒ Float?

Returns upper bound for computed delays.

Returns:

  • (Float, nil) —

    upper bound for computed delays



58
59
60
 
# File 'lib/cmdx/retry.rb', line 58

def max_delay
  @options[:max_delay]
end

#process(task = nil) {|attempt| ... } ⇒ Object

Executes the block up to limit + 1 times. Re-raises the last exception when attempts are exhausted.

Parameters:

  • task (Task, nil) (defaults to: nil) —

    passed to #wait so jitter strategies can use it

Yield Parameters:

  • attempt (Integer) —

    zero-based attempt index

Yield Returns:

  • (Object) —

    the block's successful return value

Returns:

  • (Object) —

    the block's successful return value

Raises:

  • (Exception) —

    the last caught exception once retries exhaust



113
114
115
116
117
118
119
120
121
122
123
124
125
 
# File 'lib/cmdx/retry.rb', line 113

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

#wait(attempt, task = nil, prev_delay = nil) ⇒ Float?

Sleeps attempt's jittered/bounded delay. No-op when the base delay is zero.

Parameters:

  • attempt (Integer) —

    zero-based retry attempt number

  • task (Task, nil) (defaults to: nil) —

    used as receiver for Symbol/Proc jitter strategies

  • prev_delay (Float, nil) (defaults to: nil) —

    previous computed delay; only consumed by :decorrelated_jitter to thread state across attempts

Returns:

  • (Float, nil) —

    the computed (and possibly clamped) delay, or nil when delay is zero



75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
 
# File 'lib/cmdx/retry.rb', line 75

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