retriable 4.1.1 → 5.0.0

data/docs/agents/triage-labels.md

@@ -0,0 +1,17 @@
+# Triage Labels
+
+The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker.
+
+| Label in mattpocock/skills | Label in our tracker | Meaning                                  |
+| -------------------------- | -------------------- | ---------------------------------------- |
+| `needs-triage`             | `needs-triage`       | Maintainer needs to evaluate this issue  |
+| `needs-info`               | `needs-info`         | Waiting on reporter for more information |
+| `ready-for-agent`          | `ready-for-agent`    | Fully specified, ready for an AFK agent  |
+| `ready-for-human`          | `ready-for-human`    | Requires human implementation            |
+| `wontfix`                  | `wontfix`            | Will not be actioned                     |
+
+When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table.
+
+Edit the right-hand column to match whatever vocabulary you actually use.
+
+None of these labels exist in `kamui/retriable` yet. Create one on first use with `gh label create <name>`; the repo's existing labels (`question`, `dependencies`, `ruby`) don't collide with any of them.

data/docs/migration.md

@@ -0,0 +1,84 @@
+# Migrating Retriable
+
+Upgrade guides for Retriable's breaking changes, newest first. See the
+[CHANGELOG](../CHANGELOG.md) for the full history of every release.
+
+- [4.x to 5.x](#4x-to-5x)
+- [3.x to 4.0](#3x-to-40)
+
+## 4.x to 5.x
+
+Retriable 5.0 makes configuration copy-on-write so that concurrent readers see
+one complete configuration. As part of that change, `Retriable.config` returns a
+deeply frozen snapshot. Code that mutates this snapshot directly now raises
+`FrozenError`:
+
+```ruby
+Retriable.config.sleep_disabled = true # => FrozenError
+Retriable.config.contexts[:api] = {}   # => FrozenError
+```
+
+Move these writes into a `Retriable.configure` block:
+
+```ruby
+Retriable.configure do |config|
+  config.sleep_disabled = true
+  config.contexts[:api] = {}
+end
+```
+
+Check test setup files such as `spec_helper` and `rails_helper`, where direct
+configuration writes are common. Reading `Retriable.config` is unchanged.
+
+## 3.x to 4.0
+
+### Ruby version
+
+Retriable 4.0 requires Ruby 3.2 or later. If your application still runs Ruby
+2.3.0 through 3.1.x, pin Retriable to the 3.8 release line in your Gemfile:
+
+```ruby
+gem "retriable", "~> 3.8"
+```
+
+### `timeout:` option removed
+
+Retriable 4.0 removes the `timeout:` option deprecated in 3.8.0. The option
+called `Timeout.timeout`, which can interrupt code at any line and leave
+non-interrupt-safe libraries in a corrupt state. [Issue #96](https://github.com/kamui/retriable/issues/96)
+has the original bug report.
+
+Replace code such as `Retriable.retriable(timeout: 5) { ... }` with one of the
+following approaches.
+
+1. Prefer the library's own timeout setting, such as `Net::HTTP#read_timeout`,
+   Faraday's `request.timeout`, or a database statement timeout. These settings
+   avoid the arbitrary interruption caused by `Timeout.timeout`.
+
+2. If the library has no timeout setting, wrap the operation yourself:
+
+   ```ruby
+   require "timeout"
+
+   Retriable.retriable do
+     Timeout.timeout(5) do
+       # code here...
+     end
+   end
+   ```
+
+   This keeps the old behavior, including its risks. `Timeout.timeout` may
+   interrupt code while it holds a mutex, file handle, network socket, or other
+   internal state. Use it only when the library offers no safer timeout. For more
+   detail, read [why Ruby's `Timeout` is dangerous](https://jvns.ca/blog/2015/11/27/why-rubys-timeout-is-dangerous-and-thread-dot-raise-is-terrifying/),
+   [Headius on `Thread#raise` and `Timeout`](http://blog.headius.com/2008/02/ruby-threadraise-threadkill-timeoutrb.html),
+   [In Ruby, don't use `Timeout`](https://adamhooper.medium.com/in-ruby-dont-use-timeout-77d9d4e5a001), or
+   [Timeout: Ruby's most dangerous API](https://www.mikeperham.com/2015/05/08/timeout-rubys-most-dangerous-api/).
+
+   `Timeout.timeout(5)` applies to each attempt, so every retry gets a new
+   five-second limit. Use `max_elapsed_time:` to cap the total time spent across
+   all attempts.
+
+Passing `timeout:` to `Retriable.retriable` or `Retriable.with_override` now
+raises `ArgumentError`. Setting `timeout` in `Retriable.configure` now raises
+`NoMethodError` because the configuration attribute no longer exists.

data/lib/retriable/config.rb

@@ -18,16 +18,22 @@ module Retriable
       contexts
     ]).freeze
 
+    CONTEXT_ATTRIBUTES = (ATTRIBUTES - %i[contexts]).freeze
+    private_constant :CONTEXT_ATTRIBUTES
+
+    OWNED_CONTAINER_ATTRIBUTES = %i[on intervals contexts].freeze
+    private_constant :OWNED_CONTAINER_ATTRIBUTES
+
     attr_accessor(*ATTRIBUTES)
 
     def initialize(opts = {})
-      backoff = ExponentialBackoff.new
+      defaults = ExponentialBackoff::DEFAULTS
 
-      @tries            = backoff.tries
-      @base_interval    = backoff.base_interval
-      @max_interval     = backoff.max_interval
-      @rand_factor      = backoff.rand_factor
-      @multiplier       = backoff.multiplier
+      @tries            = defaults[:tries]
+      @base_interval    = defaults[:base_interval]
+      @max_interval     = defaults[:max_interval]
+      @rand_factor      = defaults[:rand_factor]
+      @multiplier       = defaults[:multiplier]
       @sleep_disabled   = false
       @max_elapsed_time = 900 # 15 min
       @intervals        = nil
@@ -51,6 +57,7 @@ module Retriable
     end
 
     def validate!
+      validate_contexts
       validate_callable(:retry_if, retry_if)
       validate_callable(:on_retry, on_retry)
       validate_callable(:on_give_up, on_give_up)
@@ -68,8 +75,124 @@ module Retriable
       validate_backoff_options
     end
 
+    # Deep-freezes the containers this Config owns, then itself. Without the deep
+    # part a "frozen" Config stays mutable one level down
+    # (`config.contexts[:api][:tries] = 1`), which is precisely the corruption a
+    # published snapshot exists to rule out. Leaves — procs, exception classes,
+    # regexps, scalars — are shared by reference and left untouched.
+    #
+    # Retriable only ever freezes a #dup it produced itself, so this never
+    # freezes a container the caller still holds.
+    def freeze
+      return self if frozen?
+
+      OWNED_CONTAINER_ATTRIBUTES.each do |attribute|
+        deep_freeze(instance_variable_get(:"@#{attribute}"))
+      end
+      super
+    end
+
     private
 
+    def validate_contexts
+      return unless contexts.is_a?(Hash)
+      return if contexts.empty?
+
+      contexts.each_value do |options|
+        next unless options.is_a?(Hash)
+
+        options.each_key do |k|
+          next if CONTEXT_ATTRIBUTES.include?(k)
+
+          raise ArgumentError, "#{k} is not a valid option"
+        end
+      end
+    end
+
+    def initialize_copy(other)
+      super
+      OWNED_CONTAINER_ATTRIBUTES.each do |attribute|
+        instance_variable_set(:"@#{attribute}", deep_dup(other.public_send(attribute)))
+      end
+    end
+
+    # Recursively copies the mutable containers (Hash/Array/Set) so a dup is fully
+    # isolated from the original, leaving leaves (scalars, procs, exception
+    # classes, regexps) shared by reference.
+    #
+    # Copies start from #dup rather than a fresh literal. Rebuilding into a bare
+    # `{}` silently downgrades a Hash subclass to Hash and drops its
+    # default/default_proc, so a `contexts` hash with indifferent access would
+    # stop resolving string keys after the first #configure.
+    #
+    # Frozen state is deliberately not carried over: a dup is the mutable working
+    # copy that a #configure block mutates, and Retriable re-freezes it on
+    # publish.
+    #
+    # `seen` maps each source container to its copy so a self-referential
+    # structure terminates instead of recursing until the stack blows.
+    def deep_dup(value, seen = {}.compare_by_identity)
+      case value
+      when Hash, Array, Set
+        return seen[value] if seen.key?(value)
+
+        copy = value.dup
+        seen[value] = copy
+        deep_dup_into(value, copy, seen)
+        copy
+      else value
+      end
+    end
+
+    def deep_dup_into(value, copy, seen)
+      case value
+      when Hash then deep_dup_hash(value, copy, seen)
+      when Array then value.each_with_index { |val, index| copy[index] = deep_dup(val, seen) }
+      when Set then copy.replace(value.map { |val| deep_dup(val, seen) })
+      end
+    end
+
+    # Keys are deliberately left alone. Ruby already dups and freezes an unfrozen
+    # String key on assignment, and the supported key types (Symbols for
+    # `contexts`, exception classes for `on`) are immutable already.
+    #
+    # A mutable default value is part of the copied graph, because a shared one
+    # would let `config.contexts[:absent] << x` mutate the caller's object. A
+    # default_proc stays shared: it is a callable leaf, like every other proc a
+    # Config holds.
+    def deep_dup_hash(value, copy, seen)
+      value.each { |key, val| copy[key] = deep_dup(val, seen) }
+      copy.default = deep_dup(value.default, seen) unless value.default_proc
+    end
+
+    # Freezes exactly what #deep_dup treats as a container, so the two agree on
+    # where a Config's mutable surface ends. `seen` guards the same
+    # self-referential case.
+    def deep_freeze(value, seen = {}.compare_by_identity)
+      case value
+      when Hash then deep_freeze_hash(value, seen)
+      when Array, Set then deep_freeze_collection(value, seen)
+      else value
+      end
+    end
+
+    def deep_freeze_hash(value, seen)
+      return value if seen[value]
+
+      seen[value] = true
+      value.each_value { |val| deep_freeze(val, seen) }
+      deep_freeze(value.default, seen) unless value.default_proc
+      value.freeze
+    end
+
+    def deep_freeze_collection(value, seen)
+      return value if seen[value]
+
+      seen[value] = true
+      value.each { |val| deep_freeze(val, seen) }
+      value.freeze
+    end
+
     def validate_backoff_options
       validate_non_negative_number(:base_interval, base_interval)
       validate_non_negative_number(:multiplier, multiplier)

data/lib/retriable/core_ext/kernel.rb

@@ -10,4 +10,6 @@ module Kernel
   def retriable_with_context(context_key, opts = {}, &)
     Retriable.with_context(context_key, opts, &)
   end
+
+  private :retriable, :retriable_with_context
 end

data/lib/retriable/exponential_backoff.rb

@@ -14,14 +14,22 @@ module Retriable
       rand_factor
     ].freeze
 
+    DEFAULTS = {
+      tries: 3,
+      base_interval: 0.5,
+      max_interval: 60,
+      rand_factor: 0.5,
+      multiplier: 1.5
+    }.freeze
+
     attr_accessor(*ATTRIBUTES)
 
     def initialize(opts = {})
-      @tries         = 3
-      @base_interval = 0.5
-      @max_interval  = 60
-      @rand_factor   = 0.5
-      @multiplier    = 1.5
+      @tries         = DEFAULTS[:tries]
+      @base_interval = DEFAULTS[:base_interval]
+      @max_interval  = DEFAULTS[:max_interval]
+      @rand_factor   = DEFAULTS[:rand_factor]
+      @multiplier    = DEFAULTS[:multiplier]
 
       opts.each do |k, v|
         raise ArgumentError, "#{k} is not a valid option" if !ATTRIBUTES.include?(k)

data/lib/retriable/version.rb

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

data/lib/retriable.rb

@@ -12,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,24 +99,34 @@ module Retriable
   end
 
   def with_context(context_key, options = {}, &)
-    contexts = available_contexts
+    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(context_options_for(context_key, options), &)
+    retriable_with_config(config_snapshot, context_options_for(context_key, configured_contexts, options), &)
   end
 
   def retriable(opts = {}, &)
+    retriable_with_config(config, opts, &)
+  end
+
+  def retriable_with_config(base_config, opts = {}, &)
     override_config = current_override
     local_config = if opts.empty? && !override_config
-                     config
+                     base_config
                    else
-                     Config.new(apply_override_options(merge_layer(config.to_h, 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.
@@ -97,6 +165,9 @@ module Retriable
       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)
 
@@ -229,12 +300,11 @@ module Retriable
     merged
   end
 
-  def available_contexts
-    config_contexts.merge(override_contexts)
-  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 = merge_layer(context_options, options)
 
@@ -244,8 +314,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
@@ -258,7 +328,28 @@ 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,
@@ -271,7 +362,6 @@ module Retriable
     :hash_exception_match?,
     :apply_override_options,
     :merge_layer,
-    :available_contexts,
     :context_options_for,
     :config_contexts,
     :override_contexts,

data/sig/retriable.rbs

@@ -2,10 +2,10 @@ module Retriable
   VERSION: String
   OVERRIDE_THREAD_KEY: Symbol
 
-  def self.configure: () { (Config) -> void } -> void
+  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.with_context: (Symbol context_key, ?Hash[Symbol, untyped] options) { (Integer) -> untyped } -> untyped
   def self.retriable: (?Hash[Symbol, untyped] options) { (Integer) -> untyped } -> untyped
 
   class Config