retriable 3.8.0 → 5.0.1

data/lib/retriable/validation.rb

@@ -28,6 +28,13 @@ module Retriable
       validate_non_negative_number(name, value)
     end
 
+    def validate_callable(name, value)
+      return unless value # nil/false disable the callback
+      return if value.respond_to?(:call)
+
+      raise ArgumentError, "#{name} must respond to #call or be nil"
+    end
+
     def validate_rand_factor
       return if finite_number?(rand_factor) && rand_factor >= 0 && rand_factor <= 1
 
@@ -46,7 +53,7 @@ module Retriable
 
     # Validates an `on:` value. Acceptable shapes:
     #   - a Class that descends from Exception
-    #   - an Array whose elements are Classes that descend from Exception
+    #   - an Array or Set whose elements are Classes that descend from Exception
     #   - a Hash whose keys are such Classes and whose values are nil,
     #     a Regexp, or an Array of Regexps
     #
@@ -58,12 +65,12 @@ module Retriable
     # Regexp values explicitly.
     def validate_on(value)
       case value
-      when Hash
+      in Hash
         value.each do |klass, pattern|
           validate_on_class(klass)
           validate_on_hash_value(klass, pattern)
         end
-      when Array
+      in Array | Set
         value.each { |klass| validate_on_class(klass) }
       else
         validate_on_class(value)
@@ -79,10 +86,7 @@ module Retriable
     def validate_on_hash_value(klass, pattern)
       return if pattern.nil?
       return if pattern.is_a?(Regexp)
-      # Ruby 2.3 does not support Enumerable#all?(pattern).
-      # rubocop:disable Style/PredicateWithKind
-      return if pattern.is_a?(Array) && pattern.all? { |p| p.is_a?(Regexp) }
-      # rubocop:enable Style/PredicateWithKind
+      return if pattern.is_a?(Array) && pattern.all?(Regexp)
 
       raise ArgumentError,
             "on[#{klass}] must be nil, a Regexp, or an Array of Regexps, got #{pattern.inspect}"

data/lib/retriable/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Retriable
-  VERSION = "3.8.0"
+  VERSION = "5.0.1"
 end

data/lib/retriable.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require "timeout"
 require_relative "retriable/config"
 require_relative "retriable/exponential_backoff"
 require_relative "retriable/version"
@@ -13,17 +12,75 @@ module Retriable
   # break callers that use fiber-based concurrency.
   OVERRIDE_THREAD_KEY = :retriable_override
 
+  # True thread-local storage marking the Config this thread is currently
+  # building inside #configure. It answers one question — "am I mid-configure?"
+  # Which snapshot a given #retriable/#with_context call resolves against is a
+  # separate question, answered by passing that snapshot as an argument (see
+  # #retriable_with_config). Keeping the two questions on two mechanisms is
+  # deliberate: a thread-local would otherwise leak the resolved snapshot across
+  # the caller's block and change what `Retriable.config` returns inside it.
+  CONFIGURING_THREAD_KEY = :retriable_configuring
+  private_constant :CONFIGURING_THREAD_KEY
+
   RetryPlan = Struct.new(:max_tries, :interval_for)
   private_constant :RetryPlan
 
+  # Serializes complete #configure transactions so concurrent read-modify-write
+  # swaps cannot drop one another's updates.
+  CONFIG_MUTEX = Mutex.new
+  private_constant :CONFIG_MUTEX
+
+  # Guards the single @config reference. Held only for a reference read or the
+  # publishing write, never across the #configure block, so a writer blocks a
+  # reader for no longer than a pointer swap.
+  #
+  # One path on every engine. MRI's GVL would make an unsynchronized read safe,
+  # but JRuby and TruffleRuby offer no such happens-before guarantee. The common
+  # no-options #retriable path uses the snapshot directly, so this mutex has a
+  # measurable cost. benchmark/config_publication.rb tracks that cost. Replace
+  # this mechanism only when measurements justify a portable alternative.
+  CONFIG_PUBLICATION_MUTEX = Mutex.new
+  private_constant :CONFIG_PUBLICATION_MUTEX
+
+  # Eagerly initialized at load time. `require` is serialized in MRI, so this runs
+  # exactly once before any thread can reach #config/#configure, closing the
+  # `@config ||= Config.new` check-then-act race. Frozen like every snapshot
+  # published after it, so reads are immutable from the very first one.
+  @config = Config.new.freeze
+
   module_function
 
+  # Copy-on-write: dup the published config, let the caller mutate the copy, then
+  # atomically publish it, deeply frozen. Readers therefore always observe a
+  # consistent, fully-applied snapshot that nothing can mutate underneath them,
+  # and a failed/raising block leaves the old config intact. Does NOT validate
+  # (validation stays lazy at #retriable time).
+  # Nested calls on the configuring thread share the outer candidate. Only the
+  # outermost call takes CONFIG_MUTEX and publishes, so nesting remains safe even
+  # though the mutex is not reentrant.
   def configure
-    yield(config)
+    candidate = configuring_config
+    return yield(candidate) if candidate
+
+    CONFIG_MUTEX.synchronize do
+      candidate = config.dup
+      Thread.current.thread_variable_set(CONFIGURING_THREAD_KEY, candidate)
+      begin
+        result = yield(candidate)
+        publish_config(candidate)
+        result
+      ensure
+        Thread.current.thread_variable_set(CONFIGURING_THREAD_KEY, nil)
+      end
+    end
   end
 
+  # The configuring thread sees its own candidate, still mutable and mid-build.
+  # Every other reader sees the last fully published snapshot, which is deeply
+  # frozen: mutating it raises FrozenError instead of silently corrupting the
+  # config other threads are reading. Use #configure to change configuration.
   def config
-    @config ||= Config.new
+    configuring_config || published_config
   end
 
   def with_override(opts = {})
@@ -41,35 +98,44 @@ module Retriable
     end
   end
 
-  def with_context(context_key, options = {}, &block)
-    contexts = available_contexts
+  def with_context(context_key, options = {}, &)
+    raise ArgumentError, "with_context requires a block" unless block_given?
+
+    # Resolve the whole call against one snapshot and one traversal of its
+    # contexts. Re-reading `config` here would let a concurrent #configure pass
+    # the existence check on the old snapshot while options resolve against the
+    # new one, silently dropping the context's retry options.
+    config_snapshot = config
+    configured_contexts = config_contexts(config_snapshot)
+    contexts = configured_contexts.merge(override_contexts)
 
     if !contexts.key?(context_key)
       raise ArgumentError,
             "#{context_key} not found in Retriable contexts (including overrides). Available contexts: #{contexts.keys}"
     end
 
-    return unless block_given?
+    retriable_with_config(config_snapshot, context_options_for(context_key, configured_contexts, options), &)
+  end
 
-    retriable(context_options_for(context_key, options), &block)
+  def retriable(opts = {}, &)
+    retriable_with_config(config, opts, &)
   end
 
-  def retriable(opts = {}, &block)
+  def retriable_with_config(base_config, opts = {}, &)
     override_config = current_override
     local_config = if opts.empty? && !override_config
-                     config
+                     # A reused config may have been mutated inside configure.
+                     base_config.validate!
+                     base_config
                    else
-                     Config.new(apply_override_options(config.to_h.merge(opts), override_config))
+                     Config.new(apply_override_options(merge_layer(base_config.to_h, opts), override_config))
                    end
 
-    # Config is mutable through `configure`, so validate again immediately before use.
-    local_config.validate!
-
     plan = retry_plan(local_config)
-    timeout = local_config.timeout
     on = local_config.on
     retry_if = local_config.retry_if
     on_retry = local_config.on_retry
+    on_give_up = local_config.on_give_up
     sleep_disabled = local_config.sleep_disabled
     max_elapsed_time = local_config.max_elapsed_time
 
@@ -79,30 +145,39 @@ module Retriable
     elapsed_time = -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time }
 
     execute_tries(
-      max_tries: plan.max_tries, interval_for: plan.interval_for, timeout: timeout,
+      max_tries: plan.max_tries, interval_for: plan.interval_for,
       exception_list: exception_list, on: on, retry_if: retry_if, on_retry: on_retry,
-      elapsed_time: elapsed_time, max_elapsed_time: max_elapsed_time,
-      sleep_disabled: sleep_disabled, &block
+      on_give_up: on_give_up, elapsed_time: elapsed_time, max_elapsed_time: max_elapsed_time,
+      sleep_disabled: sleep_disabled, &
     )
   end
 
   def execute_tries( # rubocop:disable Metrics/ParameterLists
-    max_tries:, interval_for:, timeout:, exception_list:,
-    on:, retry_if:, on_retry:, elapsed_time:, max_elapsed_time:, sleep_disabled:, &block
+    max_tries:, interval_for:, exception_list:,
+    on:, retry_if:, on_retry:, on_give_up:, elapsed_time:, max_elapsed_time:, sleep_disabled:
   )
     try = 0
-    loop do
+    while true # rubocop:disable Style/InfiniteLoop -- Kernel#loop swallows StopIteration.
       try += 1
       begin
-        return call_with_timeout(timeout, try, &block)
+        return yield(try)
       rescue *exception_list => e
         raise unless retriable_exception?(e, on, exception_list, retry_if)
 
+        # On the final attempt `interval_for` returns nil (no next retry), and
+        # `on_retry` intentionally fires before the give-up check below, so it
+        # receives `interval: nil`. See the on_retry/on_give_up README contract.
         interval = interval_for.call(try - 1)
         call_on_retry(on_retry, e, try, elapsed_time.call, interval)
 
         elapsed_interval = sleep_disabled == true ? 0 : interval
-        raise unless can_retry?(try, max_tries, elapsed_time.call, elapsed_interval, max_elapsed_time)
+        # Snapshot elapsed_time once so the stop check and on_give_up see the same value.
+        current_elapsed_time = elapsed_time.call
+        stop_reason = retry_stop_reason(try, max_tries, current_elapsed_time, elapsed_interval, max_elapsed_time)
+        if stop_reason
+          call_on_give_up(on_give_up, e, try, current_elapsed_time, interval, stop_reason)
+          raise
+        end
 
         sleep interval if sleep_disabled != true
       end
@@ -132,23 +207,30 @@ module Retriable
     ).interval_provider
   end
 
-  def call_with_timeout(timeout, try)
-    return Timeout.timeout(timeout) { yield(try) } if timeout
-
-    yield(try)
-  end
-
   def call_on_retry(on_retry, exception, try, elapsed_time, interval)
     return unless on_retry
 
     on_retry.call(exception, try, elapsed_time, interval)
   end
 
-  def can_retry?(try, max_tries, elapsed_time, interval, max_elapsed_time)
-    return false if max_tries && try >= max_tries
-    return true if max_elapsed_time.nil?
+  def call_on_give_up( # rubocop:disable Metrics/ParameterLists
+    on_give_up, exception, try, elapsed_time, interval, reason
+  )
+    return unless on_give_up
+
+    on_give_up.call(exception, try, elapsed_time, interval, reason)
+  end
+
+  # `:tries_exhausted` is checked first, but the two conditions can't both hold
+  # on the same try in practice: `retry_plan` returns a nil interval whenever
+  # `try >= max_tries`, so `(elapsed_time + interval) > max_elapsed_time` is not
+  # evaluable on the exhausted-tries try. The early return guards against that
+  # nil and also pins precedence in case the plan ever changes.
+  def retry_stop_reason(try, max_tries, elapsed_time, interval, max_elapsed_time)
+    return :tries_exhausted if max_tries && try >= max_tries
+    return nil if max_elapsed_time.nil?
 
-    (elapsed_time + interval) <= max_elapsed_time
+    :max_elapsed_time if (elapsed_time + interval) > max_elapsed_time
   end
 
   # When `on` is a Hash, we need to verify the exception matches a pattern.
@@ -204,19 +286,26 @@ module Retriable
   def apply_override_options(options, overrides)
     return options unless overrides
 
-    options = options.merge(overrides)
-    options[:intervals] = nil if overrides.key?(:tries) && !overrides.key?(:intervals)
-    options
+    merge_layer(options, overrides)
   end
 
-  def available_contexts
-    config_contexts.merge(override_contexts)
+  # Merge a higher-precedence option layer onto a base layer. A higher layer
+  # that sets `tries` without `intervals` clears the base layer's inherited
+  # `intervals`, so a caller's `tries:` is never silently ignored. When the
+  # higher layer supplies its own `intervals`, those win (same-call override).
+  def merge_layer(base, higher)
+    merged = base.merge(higher)
+    merged[:intervals] = nil if higher.key?(:tries) && !higher.key?(:intervals)
+    merged
   end
 
-  def context_options_for(context_key, options)
-    context_options = config_contexts.fetch(context_key, {})
+  # Takes the already-resolved contexts hash rather than the config snapshot, so
+  # the snapshot travels exactly one hop (into #retriable_with_config) instead of
+  # through every private helper that happens to need a corner of it.
+  def context_options_for(context_key, contexts, options)
+    context_options = contexts.fetch(context_key, {})
     context_options = {} unless context_options.is_a?(Hash)
-    context_options = context_options.merge(options)
+    context_options = merge_layer(context_options, options)
 
     override_context_options = override_contexts[context_key]
     return context_options unless override_context_options.is_a?(Hash)
@@ -224,8 +313,8 @@ module Retriable
     apply_override_options(context_options, override_context_options)
   end
 
-  def config_contexts
-    config.contexts.is_a?(Hash) ? config.contexts : {}
+  def config_contexts(config_snapshot)
+    config_snapshot.contexts.is_a?(Hash) ? config_snapshot.contexts : {}
   end
 
   def override_contexts
@@ -238,19 +327,40 @@ module Retriable
     Thread.current.thread_variable_get(OVERRIDE_THREAD_KEY)
   end
 
+  def configuring_config
+    Thread.current.thread_variable_get(CONFIGURING_THREAD_KEY)
+  end
+
+  def published_config
+    CONFIG_PUBLICATION_MUTEX.synchronize { @config }
+  end
+
+  # Publishes a deeply frozen deep copy of the candidate. The copy matters: it
+  # keeps the freeze off objects the caller still owns, so `c.on = my_array`
+  # inside a #configure block never leaves my_array frozen. The mutex covers the
+  # reference swap only; the copy and freeze happen outside it.
+  def publish_config(candidate)
+    snapshot = candidate.dup.freeze
+    CONFIG_PUBLICATION_MUTEX.synchronize { @config = snapshot }
+  end
+
   private_class_method(
+    :retriable_with_config,
+    :configuring_config,
+    :published_config,
+    :publish_config,
     :validate_override_options,
     :validate_context_override_options,
     :execute_tries,
     :retry_plan,
     :interval_provider,
-    :call_with_timeout,
     :call_on_retry,
-    :can_retry?,
+    :call_on_give_up,
+    :retry_stop_reason,
     :retriable_exception?,
     :hash_exception_match?,
     :apply_override_options,
-    :available_contexts,
+    :merge_layer,
     :context_options_for,
     :config_contexts,
     :override_contexts,

data/retriable.gemspec

@@ -15,15 +15,10 @@ Gem::Specification.new do |spec|
                        "APIs/services or file system calls."
   spec.homepage      = "https://github.com/kamui/retriable"
   spec.license       = "MIT"
+  spec.metadata["rubygems_mfa_required"] = "true"
 
   spec.files         = `git ls-files -z`.split("\x0")
-  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
-  spec.required_ruby_version = ">= 2.3.0"
-
-  spec.add_development_dependency "bundler"
-  spec.add_development_dependency "rspec", "~> 3"
-
-  spec.add_development_dependency "listen", "~> 3.1"
+  spec.required_ruby_version = ">= 3.2"
 end

data/sig/retriable.rbs

@@ -1,4 +1,32 @@
 module Retriable
   VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  OVERRIDE_THREAD_KEY: Symbol
+
+  def self.configure: [Result] () { (Config) -> Result } -> Result
+  def self.config: () -> Config
+  def self.with_override: (Hash[Symbol, untyped] options) { () -> untyped } -> untyped
+  def self.with_context: (Symbol context_key, ?Hash[Symbol, untyped] options) { (Integer) -> untyped } -> untyped
+  def self.retriable: (?Hash[Symbol, untyped] options) { (Integer) -> untyped } -> untyped
+
+  class Config
+    ATTRIBUTES: Array[Symbol]
+
+    attr_accessor tries: Numeric
+    attr_accessor base_interval: Numeric
+    attr_accessor max_interval: Numeric
+    attr_accessor rand_factor: Numeric
+    attr_accessor multiplier: Numeric
+    attr_accessor sleep_disabled: bool
+    attr_accessor max_elapsed_time: Numeric?
+    attr_accessor intervals: Array[Numeric]?
+    attr_accessor on: untyped
+    attr_accessor retry_if: untyped
+    attr_accessor on_retry: untyped
+    attr_accessor on_give_up: untyped
+    attr_accessor contexts: Hash[Symbol, untyped]
+
+    def initialize: (?Hash[Symbol, untyped] opts) -> void
+    def to_h: () -> Hash[Symbol, untyped]
+    def validate!: () -> void
+  end
 end