retriable 3.8.0 → 5.0.1

data/benchmark/config_publication.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+
+require "rbconfig"
+require "retriable"
+
+RUN_SECONDS = Float(ENV.fetch("RETRIABLE_BENCH_SECONDS", "1.0"))
+THREAD_COUNTS = ENV.fetch("RETRIABLE_BENCH_THREADS", "1,2,4,8")
+                   .split(",")
+                   .map { |value| Integer(value, 10) }
+                   .uniq
+                   .freeze
+BATCH_SIZE = 100
+
+raise ArgumentError, "RETRIABLE_BENCH_SECONDS must be positive" unless RUN_SECONDS.positive?
+raise ArgumentError, "RETRIABLE_BENCH_THREADS must contain positive integers" unless THREAD_COUNTS.all?(&:positive?)
+
+SnapshotHolder = Struct.new(:value)
+snapshot_holder = SnapshotHolder.new(Retriable.config)
+
+BENCHMARK_CASES = {
+  "plain_snapshot_read" => -> { snapshot_holder.value },
+  "published_config_read" => -> { Retriable.config },
+  "successful_retriable" => -> { Retriable.retriable { nil } }
+}.freeze
+
+def monotonic_time
+  Process.clock_gettime(Process::CLOCK_MONOTONIC)
+end
+
+def measure(operation, thread_count)
+  ready = Queue.new
+  start = Queue.new
+  threads = Array.new(thread_count) do
+    Thread.new do
+      ready << true
+      start.pop
+      count = 0
+      deadline = monotonic_time + RUN_SECONDS
+
+      loop do
+        BATCH_SIZE.times { operation.call }
+        count += BATCH_SIZE
+        break if monotonic_time >= deadline
+      end
+
+      count
+    end
+  end
+
+  thread_count.times { ready.pop }
+  started_at = monotonic_time
+  thread_count.times { start << true }
+  operation_count = threads.sum(&:value)
+  elapsed = monotonic_time - started_at
+
+  operation_count / elapsed
+end
+
+BENCHMARK_CASES.each_value do |operation|
+  5_000.times { operation.call }
+end
+
+puts "ruby=#{RUBY_DESCRIPTION}"
+puts "engine=#{RUBY_ENGINE}"
+puts "host_cpu=#{RbConfig::CONFIG.fetch("host_cpu")}"
+puts "seconds_per_case=#{RUN_SECONDS}"
+puts "case,threads,operations_per_second"
+
+BENCHMARK_CASES.each do |name, operation|
+  THREAD_COUNTS.each do |thread_count|
+    operations_per_second = measure(operation, thread_count)
+    puts format(
+      "%<name>s,%<threads>d,%<operations>d",
+      name: name, threads: thread_count, operations: operations_per_second.round,
+    )
+  end
+end

data/docs/adr/0001-copy-on-write-config-publication.md

@@ -0,0 +1,124 @@
+# 1. Copy-on-write config publication
+
+## Status
+
+Accepted.
+
+## Context
+
+`Retriable.config` is a single mutable object read on every `Retriable.retriable`
+call and written rarely, usually once at boot. That shape had three races:
+
+- `@config ||= Config.new` was check-then-act, so two threads booting at once
+  could build two different `Config` objects.
+- `retriable` read attributes off the live shared config one at a time, so a
+  concurrent `configure` could hand a single call an inconsistent mix of old and
+  new values.
+- `with_context` read the config more than once. The existence check and the
+  option resolution could straddle a `configure`. The check could pass against
+  the old snapshot before resolution silently dropped the context's retry
+  options from the new one.
+
+Reads vastly outnumber writes, so a scheme that keeps readers cheap and pays the
+cost on the writer is the right trade.
+
+## Decision
+
+Configuration is copy-on-write.
+
+`configure` takes `CONFIG_MUTEX`, duplicates the published config, yields the
+duplicate, and publishes it only if the block returns without raising. Writers
+serialize against each other; a raising block leaves the previous config in
+place. Publication does not change the method's return contract: `configure`
+returns the block's result, not the candidate or published snapshot.
+
+**One publication seam, one engine path.** `CONFIG_PUBLICATION_MUTEX` guards the
+`@config` reference and is held only for a reference read or the publishing
+write, never across the user's block, so a writer blocks a reader for no longer
+than a pointer swap. We do not special-case MRI. An unsynchronized read would be
+safe there thanks to the GVL, but it would leave a second memory model to
+maintain for JRuby and TruffleRuby.
+
+The mutex is part of the hot path. A `retriable` call with no local options or
+override uses the published `Config` directly, so it does not otherwise pay for
+`Config.new`, `to_h`, or a merge. `benchmark/config_publication.rb` measures both
+raw config reads and successful retry calls with one or more reader threads. We
+accept the mutex cost for a portable memory-visibility guarantee, but we do not
+assume that cost is free. If the benchmark shows material contention on a
+supported engine, `Concurrent::AtomicReference` is the preferred alternative.
+An engine-conditional unsynchronized read is not.
+
+**The published snapshot is deeply frozen.** Atomic publication alone does not
+deliver a consistent read: if the published object stays mutable, any caller can
+still do `Retriable.config.contexts[:api][:tries] = 1` and corrupt what every
+other thread is reading. `Config#freeze` therefore freezes `on`, `intervals` and
+`contexts` recursively before freezing the config itself. `configure` publishes a
+*copy* of the candidate so freezing never reaches a container the caller still
+owns (`c.on = my_array` must not leave `my_array` frozen).
+
+**`dup` copies containers, not leaves, and never preserves frozen state.**
+`Config#initialize_copy` deep-copies `on`, `intervals` and `contexts`; scalars,
+procs, exception classes and regexps are shared by reference. A Hash's mutable
+default *value* is part of the copied graph, because a shared one would let
+`config.contexts[:absent] << x` reach the caller's object; a `default_proc`
+remains a shared callable leaf. Copies start from `#dup` rather than a fresh
+literal so a container's class and a Hash's default behavior survive. Rebuilding
+into a bare `{}` would silently downgrade an indifferent-access `contexts` hash
+and break string-key lookups. Frozen state is deliberately dropped, because a dup
+is the mutable working copy a `configure` block mutates; publication re-freezes
+it.
+
+Hash *keys* are left as-is. Ruby already dups and freezes an unfrozen String key
+on assignment. The supported key types, Symbols for `contexts` and exception
+classes for `on`, are immutable. Copying keys would buy immutability only for
+container keys, still miss arbitrary mutable objects, and break `compare_by_identity`
+lookups, so the boundary stays where Ruby puts it.
+
+Deep immutability covers the containers owned by `Config`. Callable leaves can
+hold their own mutable state, and a shared `default_proc` can mutate state outside
+the config. Callers remain responsible for synchronizing that state when the
+callable runs from multiple threads.
+
+**Two mechanisms, two questions.** A thread-local (`CONFIGURING_THREAD_KEY`)
+answers "is this thread mid-`configure`?", which is what lets the configuring
+thread and its fibers see their own candidate. Which snapshot a *single*
+`retriable`/`with_context` call resolves against is a different question,
+answered by passing that snapshot as an argument to `retriable_with_config`. A
+thread-local would leak the resolved snapshot across the caller's block and
+change what `Retriable.config` returns inside it, so the two are kept apart. The
+snapshot travels one hop; `with_context` resolves its contexts hash once and
+passes that.
+
+**Nested calls join the outer transaction.** A nested `configure` sees the
+candidate stored in `CONFIGURING_THREAD_KEY` and yields that same object without
+taking `CONFIG_MUTEX` again. This preserves the behavior supported before
+copy-on-write and avoids recursive locking. The outermost block alone publishes.
+If it raises, Retriable discards every change made by nested blocks. A nested call
+does not create an independent commit or savepoint. Fibers on the configuring
+thread share the transaction because `CONFIGURING_THREAD_KEY` is a true thread
+local.
+
+## Consequences
+
+- Direct mutation of `Retriable.config` now raises `FrozenError`. This is a
+  breaking change for code that reached around `configure`; the migration is to
+  use `configure`. Reading `Retriable.config` is unaffected. This change will
+  ship in Retriable 5.0.
+- Nested `configure` remains supported. Nested blocks mutate the outer working
+  copy and do not publish separately.
+- Writer blocks are serialized for their full duration. A block must not wait
+  for work that may call `configure`, because that work cannot acquire
+  `CONFIG_MUTEX` until the current block returns. Readers do not take that mutex
+  and continue using the last published snapshot.
+- `configure` pays two deep copies per call (one to build the candidate, one to
+  take ownership before freezing). `configure` is a rare, usually boot-time
+  operation, so this is not on any hot path.
+- Every `retriable` call takes one uncontended mutex to read the config
+  reference. The checked-in benchmark measures the cost on CRuby and JRuby. A
+  measured optimization may replace the publication mechanism, but it must keep
+  one memory model across supported engines.
+- The structural snapshot is thread-safe. User-supplied callbacks and other
+  callable leaves must synchronize their own mutable state.
+- `Retriable.config` is still a global. This ADR makes the global safe to read
+  concurrently; it does not introduce per-thread, per-instance, or Ractor-safe
+  configuration.

data/docs/agents/domain.md

@@ -0,0 +1,38 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+This repo is **single-context**: one `CONTEXT.md` and one `docs/adr/` at the root.
+
+## Before exploring, read these
+
+- **`CONTEXT.md`** at the repo root
+- **`docs/adr/`**: read ADRs that touch the area you're about to work in.
+
+If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved.
+
+## File structure
+
+```
+/
+├── CONTEXT.md
+├── docs/adr/
+│   ├── 0001-copy-on-write-config.md
+│   └── 0002-randomized-exponential-backoff.md
+├── lib/
+└── spec/
+```
+
+Design decisions belong in `docs/adr/` with a numbered filename. Don't scatter them into other `docs/` subdirectories.
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal: either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
+
+> _Contradicts ADR-0007 (event-sourced orders), but worth reopening because…_

data/docs/agents/issue-tracker.md

@@ -0,0 +1,45 @@
+# Issue tracker: GitHub
+
+Issues and specs for this repo live as GitHub issues on `kamui/retriable`. Use the `gh` CLI for all operations.
+
+## Conventions
+
+- **Create an issue**: `gh issue create --title "..." --body "..."`. Use a heredoc for multi-line bodies.
+- **Read an issue**: `gh issue view <number> --comments`, filtering comments by `jq` and also fetching labels.
+- **List issues**: `gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'` with appropriate `--label` and `--state` filters.
+- **Comment on an issue**: `gh issue comment <number> --body "..."`
+- **Apply / remove labels**: `gh issue edit <number> --add-label "..."` / `--remove-label "..."`
+- **Close**: `gh issue close <number> --comment "..."`
+
+Infer the repo from `git remote -v`; `gh` does this automatically when run inside a clone.
+
+## Pull requests as a triage surface
+
+**PRs as a request surface: no.** _(Set to `yes` if this repo treats external PRs as feature requests; `/triage` reads this flag.)_
+
+When set to `yes`, PRs run through the same labels and states as issues, using the `gh pr` equivalents:
+
+- **Read a PR**: `gh pr view <number> --comments` and `gh pr diff <number>` for the diff.
+- **List external PRs for triage**: `gh pr list --state open --json number,title,body,labels,author,authorAssociation,comments` then keep only `authorAssociation` of `CONTRIBUTOR`, `FIRST_TIME_CONTRIBUTOR`, or `NONE` (drop `OWNER`/`MEMBER`/`COLLABORATOR`).
+- **Comment / label / close**: `gh pr comment`, `gh pr edit --add-label`/`--remove-label`, `gh pr close`.
+
+GitHub shares one number space across issues and PRs, so a bare `#42` may be either: resolve with `gh pr view 42` and fall back to `gh issue view 42`.
+
+## When a skill says "publish to the issue tracker"
+
+Create a GitHub issue.
+
+## When a skill says "fetch the relevant ticket"
+
+Run `gh issue view <number> --comments`.
+
+## Wayfinding operations
+
+Used by `/wayfinder`. The **map** is a single issue with **child** issues as tickets.
+
+- **Map**: a single issue labelled `wayfinder:map`, holding the Notes / Decisions-so-far / Fog body. `gh issue create --label wayfinder:map`.
+- **Child ticket**: an issue linked to the map as a GitHub sub-issue (`gh api` on the sub-issues endpoint). Where sub-issues aren't enabled, add the child to a task list in the map body and put `Part of #<map>` at the top of the child body. Labels: `wayfinder:<type>` (`research`/`prototype`/`grilling`/`task`). Once claimed, the ticket is assigned to the driving dev.
+- **Blocking**: GitHub's **native issue dependencies**, the canonical, UI-visible representation. Add an edge with `gh api --method POST repos/<owner>/<repo>/issues/<child>/dependencies/blocked_by -F issue_id=<blocker-db-id>`, where `<blocker-db-id>` is the blocker's numeric **database id** (`gh api repos/<owner>/<repo>/issues/<n> --jq .id`, _not_ the `#number` or `node_id`). GitHub reports `issue_dependencies_summary.blocked_by` (open blockers only, the live gate). Where dependencies aren't available, fall back to a `Blocked by: #<n>, #<n>` line at the top of the child body. A ticket is unblocked when every blocker is closed.
+- **Frontier query**: list the map's open children (`gh issue list --state open`, scoped to the map's sub-issues / task list), drop any with an open blocker (`issue_dependencies_summary.blocked_by > 0`, or an open issue in the `Blocked by` line) or an assignee; first in map order wins.
+- **Claim**: `gh issue edit <n> --add-assignee @me`, the session's first write.
+- **Resolve**: `gh issue comment <n> --body "<answer>"`, then `gh issue close <n>`, then append a context pointer (gist + link) to the map's Decisions-so-far.

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

@@ -11,43 +11,36 @@ module Retriable
       sleep_disabled
       max_elapsed_time
       intervals
-      timeout
       on
       retry_if
       on_retry
+      on_give_up
       contexts
     ]).freeze
 
-    TIMEOUT_DEPRECATION_MESSAGE = "NOTE: Retriable's `timeout:` option is deprecated and will be removed in " \
-                                  "Retriable 4.0. It is a thin wrapper around `Timeout.timeout`, which " \
-                                  "can interrupt execution at arbitrary lines and corrupt internal state " \
-                                  "in libraries that are not interrupt-safe. Prefer your library's native " \
-                                  "timeout, or wrap your block in `Timeout.timeout(...)` yourself."
-    private_constant :TIMEOUT_DEPRECATION_MESSAGE
+    CONTEXT_ATTRIBUTES = (ATTRIBUTES - %i[contexts]).freeze
+    private_constant :CONTEXT_ATTRIBUTES
 
-    @timeout_deprecation_warned = false
-
-    class << self
-      attr_accessor :timeout_deprecation_warned
-    end
+    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
-      @timeout          = nil
       @on               = [StandardError]
       @retry_if         = nil
       @on_retry         = nil
+      @on_give_up       = nil
       @contexts         = {}
 
       opts.each do |k, v|
@@ -60,14 +53,14 @@ module Retriable
     end
 
     def to_h
-      ATTRIBUTES.each_with_object({}) do |key, hash|
-        hash[key] = public_send(key)
-      end
+      ATTRIBUTES.to_h { |key| [key, public_send(key)] }
     end
 
     def validate!
-      warn_timeout_deprecation
-      validate_optional_non_negative_number(:timeout, timeout)
+      validate_contexts
+      validate_callable(:retry_if, retry_if)
+      validate_callable(:on_retry, on_retry)
+      validate_callable(:on_give_up, on_give_up)
       validate_on(on)
       validate_intervals
       if unbounded_tries?(tries)
@@ -82,43 +75,122 @@ 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
 
-    # Emits the `timeout:` deprecation notice at most once per process.
+    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.
     #
-    # On Rubies that support `Kernel#warn(category: :deprecated)` (2.7+), the
-    # notice is emitted under the `:deprecated` category, so callers can use the
-    # standard controls (`Warning[:deprecated] = false`, `-W:no-deprecated`,
-    # `Warning.warn` override) to silence it. On older Rubies the kwarg is not
-    # available and we fall back to plain `Kernel.warn`.
+    # 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.
     #
-    # When the warning is suppressed (either because `Warning[:deprecated]` is
-    # false or the runtime has otherwise muted the category), we deliberately
-    # leave the once-per-process flag unset so a future call with the category
-    # re-enabled still surfaces the notice.
-    def warn_timeout_deprecation
-      return if timeout.nil?
-      return if self.class.timeout_deprecation_warned
-
-      category_supported = deprecated_warning_category_supported?
-      return if category_supported && !deprecated_warnings_enabled?
-
-      self.class.timeout_deprecation_warned = true
-      if category_supported
-        Kernel.warn(TIMEOUT_DEPRECATION_MESSAGE, category: :deprecated)
-      else
-        Kernel.warn(TIMEOUT_DEPRECATION_MESSAGE)
+    # 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
 
-    def deprecated_warning_category_supported?
-      defined?(Warning) && Kernel.method(:warn).parameters.any? { |type, name| type == :key && name == :category }
+    # 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 deprecated_warnings_enabled?
-      return true unless defined?(Warning) && Warning.respond_to?(:[])
+    def deep_freeze_collection(value, seen)
+      return value if seen[value]
 
-      Warning[:deprecated]
+      seen[value] = true
+      value.each { |val| deep_freeze(val, seen) }
+      value.freeze
     end
 
     def validate_backoff_options

data/lib/retriable/core_ext/kernel.rb

@@ -3,11 +3,13 @@
 require_relative "../../retriable"
 
 module Kernel
-  def retriable(opts = {}, &block)
-    Retriable.retriable(opts, &block)
+  def retriable(opts = {}, &)
+    Retriable.retriable(opts, &)
   end
 
-  def retriable_with_context(context_key, opts = {}, &block)
-    Retriable.with_context(context_key, opts, &block)
+  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)