retriable 4.2.0 → 5.0.0

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

@@ -21,6 +21,9 @@ module Retriable
     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 = {})
@@ -72,6 +75,23 @@ 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
@@ -89,6 +109,90 @@ module Retriable
       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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Retriable
-  VERSION = "4.2.0"
+  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 = {})
@@ -43,22 +101,32 @@ module Retriable
   def with_context(context_key, options = {}, &)
     raise ArgumentError, "with_context requires a block" unless block_given?
 
-    contexts = available_contexts
+    # 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
 
-    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.
@@ -232,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)
 
@@ -247,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
@@ -261,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,
@@ -274,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,7 +2,7 @@ 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

data/spec/config_spec.rb

@@ -209,4 +209,153 @@ describe Retriable::Config do
       expect { described_class.new(contexts: { api: { tries: 3, base_interval: 1.0 } }) }.not_to raise_error
     end
   end
+
+  context "#dup (copy-on-write isolation)" do
+    it "deep-copies contexts so mutating the copy leaves the original intact" do
+      original = described_class.new(contexts: { sql: { tries: 1 } })
+      copy = original.dup
+
+      copy.contexts[:http] = { tries: 2 }
+      copy.contexts[:sql][:tries] = 99
+
+      expect(original.contexts).to eq(sql: { tries: 1 })
+    end
+
+    it "deep-copies on and intervals collections" do
+      original = described_class.new(on: [StandardError], intervals: [1, 2])
+      copy = original.dup
+
+      copy.on << ArgumentError
+      copy.intervals << 3
+
+      expect(original.on).to eq([StandardError])
+      expect(original.intervals).to eq([1, 2])
+    end
+
+    it "preserves a non-collection on value (Exception class) without duping it" do
+      original = described_class.new(on: StandardError)
+      expect(original.dup.on).to be(StandardError)
+    end
+
+    it "deep-copies a Hash on value so the copy is a distinct hash" do
+      original = described_class.new(on: { StandardError => /boom/ })
+      copy = original.dup
+
+      copy.on[ArgumentError] = /other/
+
+      expect(original.on).to eq(StandardError => /boom/)
+    end
+
+    it "deep-copies mutable values nested inside a context's options" do
+      original = described_class.new(contexts: { api: { intervals: [1, 2] } })
+      copy = original.dup
+
+      copy.contexts[:api][:intervals] << 3
+
+      expect(original.contexts[:api][:intervals]).to eq([1, 2])
+    end
+
+    it "deep-copies the collection values of a Hash on" do
+      original = described_class.new(on: { StandardError => [/boom/] })
+      copy = original.dup
+
+      copy.on[StandardError] << /bang/
+
+      expect(original.on[StandardError]).to eq([/boom/])
+    end
+
+    it "preserves the container class of a Hash subclass" do
+      subclass = Class.new(Hash)
+      contexts = subclass.new
+      contexts[:api] = { tries: 1 }
+
+      expect(described_class.new(contexts: contexts).dup.contexts).to be_a(subclass)
+    end
+
+    it "preserves a contexts default_proc so absent keys still resolve" do
+      contexts = Hash.new { |hash, key| hash[key] = { tries: 7 } }
+      copy = described_class.new(contexts: contexts).dup
+
+      expect(copy.contexts[:never_set]).to eq(tries: 7)
+    end
+
+    it "deep-copies a mutable Hash default" do
+      fallback = []
+      contexts = Hash.new(fallback)
+      copy = described_class.new(contexts: contexts).dup
+
+      copy.contexts.default << :copy_only
+
+      expect(copy.contexts.default).not_to equal(fallback)
+      expect(fallback).to be_empty
+    end
+
+    it "preserves a self-referential Hash default" do
+      contexts = {}
+      contexts.default = contexts
+      copy = described_class.new(contexts: contexts).dup
+
+      expect(copy.contexts.default).to equal(copy.contexts)
+    end
+
+    it "unfreezes copied containers so a configure block can mutate them" do
+      original = described_class.new(contexts: { api: { tries: 1 } }.freeze)
+
+      expect { original.dup.contexts[:added] = { tries: 2 } }.not_to raise_error
+    end
+
+    it "terminates on a self-referential contexts structure" do
+      original = described_class.new
+      original.contexts[:api] = { tries: 1 }
+      original.contexts[:api][:cycle] = original.contexts
+
+      copy = original.dup
+
+      expect(copy.contexts).not_to equal(original.contexts)
+      expect(copy.contexts[:api][:cycle]).to equal(copy.contexts)
+    end
+  end
+
+  context "#freeze (published snapshot immutability)" do
+    it "rejects mutation of the config itself" do
+      config = described_class.new.freeze
+
+      expect { config.tries = 99 }.to raise_error(FrozenError)
+    end
+
+    it "rejects mutation one level down, inside contexts" do
+      config = described_class.new(contexts: { api: { tries: 1 } }).freeze
+
+      expect { config.contexts[:api][:tries] = 99 }.to raise_error(FrozenError)
+    end
+
+    it "rejects mutation of the on collection" do
+      config = described_class.new(on: [StandardError]).freeze
+
+      expect { config.on << ArgumentError }.to raise_error(FrozenError)
+    end
+
+    it "freezes a mutable Hash default" do
+      fallback = []
+      contexts = Hash.new(fallback)
+      contexts[:api] = { tries: 1 }
+      config = described_class.new(contexts: contexts).freeze
+
+      expect(config.contexts.default).to be_frozen
+    end
+
+    it "leaves leaves such as procs untouched" do
+      handler = ->(_exception) { true }
+      described_class.new(retry_if: handler).freeze
+
+      expect(handler).not_to be_frozen
+    end
+
+    it "is idempotent" do
+      config = described_class.new.freeze
+
+      expect { config.freeze }.not_to raise_error
+      expect(config.freeze).to equal(config)
+    end
+  end
 end