retriable 4.1.1 → 4.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5961397b426eeaf2d2df8631f0a5dfe05adf52d5b9070ddbdf7b7825fd88f144
-  data.tar.gz: c982809ef09eb85ddedfcee95be53741846f6e4438af27e403c9ad4b020214c1
+  metadata.gz: a551efb6db5acea9e82dde8e48afdea1869f6b93461a3c48c33f8385fbea6392
+  data.tar.gz: fbf6bb8c5ade48420e0f2a43532bafff0e4159eb4cf149bce559116ec1c91e50
 SHA512:
-  metadata.gz: 30d8bfeeff407ab15fa9be7c2af2993142dce86d8406318e220afdb111c728b0c8c7cd2d6b105312ed9623074a5b20c88a9c19a6c33c3169d673d2276e0b52c4
-  data.tar.gz: f333fbf26eff94629f85f5d58688245025be3f39830bcad59da7f42ab52ad1506b155c03e1d96020a728b489ed016cb8ee1fcd5cde0a7a0ce3cfe59ad078c4d8
+  metadata.gz: 19d5ac72e1614b7fdb3984697db76ad3f6ae2e9b1f60ff1eb470e210738cd67154afc2776b55329fca345fad6263035a41eb0748626f427fd2d05cc0bfea9c89
+  data.tar.gz: c1d46594742b7c19985a63037199125b718e6c6395dd8276013719d8c7f9cd64376637471b90fa9249869767da9a2474cafc31afd04f373f73249d8ebdfa0337

data/CHANGELOG.md

@@ -1,5 +1,46 @@
 # HEAD
 
+## 4.2.0
+
+### Bug fixes
+
+- The `Kernel` extension methods (`require "retriable/core_ext/kernel"`) are now
+  private, matching idiomatic `Kernel` helpers like `puts` and `rand`.
+  Previously `retriable` and `retriable_with_context` were public instance
+  methods, so they leaked onto every object's public API and could be invoked
+  with an explicit receiver (e.g. `"foo".retriable { ... }`). They remain
+  callable in the documented receiver-less form.
+  ([#146](https://github.com/kamui/retriable/pull/146))
+- `Retriable.with_context` (and `Kernel#retriable_with_context`) now raises
+  `ArgumentError` when called without a block, matching `with_override`.
+  Previously a missing block was silently ignored: the call returned `nil` and
+  the intended block never ran, hiding a caller bug. Behavior change: code that
+  relied on the silent no-op will now raise.
+- `Config#validate!` now validates the structure of each entry in `contexts`,
+  so configured contexts are checked on every `Retriable.retriable`/
+  `with_context` call rather than only when a given context is first used. A
+  context whose options contain an unknown key (including a nested `contexts`
+  key) now raises `ArgumentError, "<key> is not a valid option"`, matching the
+  `with_override` path. Non-Hash `contexts` and non-Hash per-context values
+  remain leniently treated as empty options (no behavior change). Option
+  _values_ are still validated lazily at retry time, unchanged.
+
+### Docs
+
+- Document that `on_retry` receives `next_interval: nil` on the final rescued
+  attempt, when Retriable is about to give up because `tries` are exhausted.
+  `on_retry` still fires before `on_give_up` (unchanged behavior); the `nil`
+  contract is now called out in the `on_retry` documentation so handlers guard
+  arithmetic or logging on `next_interval`.
+
+### Performance
+
+- `Config#initialize` no longer allocates a throwaway `ExponentialBackoff` (and
+  runs its redundant `validate!`) just to read default values. Defaults now live
+  in a frozen `ExponentialBackoff::DEFAULTS` constant, removing an allocation and
+  redundant validation from the `retriable` hot path.
+  ([#149](https://github.com/kamui/retriable/pull/149))
+
 ## 4.1.1
 
 ### Bug fixes

data/Gemfile

@@ -12,7 +12,7 @@ end
 group :development do
   gem "bundler-audit", "~> 0.9"
   gem "listen", "~> 3.1"
-  gem "rbs", "~> 3.0", platforms: :ruby
+  gem "rbs", "~> 4.0", platforms: :ruby
   gem "rubocop", "~> 1.86"
 end
 

data/README.md

@@ -248,8 +248,13 @@ do not inherit it. This makes `#with_override` safe to use in parallel test
 runners. Fibers running inside the same thread share the thread's active
 override.
 
-`#with_override` stores the provided options directly. Do not mutate the
-options hash or nested values for the duration of the block.
+`#with_override` stores the provided options hash **by reference** and reads
+from it on every attempt while the block runs. Treat the hash and all of its
+nested values as immutable for the duration of the block: do not mutate them
+from inside the block, and do not mutate them from another thread or fiber that
+shares this thread's active override. Mutating the options mid-block results in
+undefined retry behavior. If options must be computed, build the hash before
+calling `#with_override` and do not retain a reference you will later mutate.
 
 For test-integration patterns (RSpec `around`, helper methods, Minitest, etc.),
 see [docs/testing.md](docs/testing.md).
@@ -367,6 +372,8 @@ Retriable.retriable(on_retry: do_this_on_each_retry) do
 end
 ```
 
+> **Note:** On the final rescued attempt — when Retriable is about to give up because `tries` are exhausted — `on_retry` still fires (before `on_give_up`; see below), but `next_interval` is **`nil`** because there is no next retry. Guard any handler that does arithmetic or formatting on `next_interval` (for example `next_interval&.*(1000)`, or `if next_interval`), and avoid unconditionally logging messages like `"retrying in #{next_interval}s"` since no retry is coming. This mirrors the `nil` contract documented for [`on_give_up`](#callbacks) below.
+
 #### Disabling a Configured Callback Per Call
 
 If `on_retry` is set in `Retriable.configure`, every call uses it by default. To opt a specific call out — for example, a critical call site that should not log on retry — pass `on_retry: false` or `on_retry: nil`.
@@ -471,6 +478,9 @@ Retriable.with_context(:mysql, tries: 30) do
 end
 ```
 
+`#with_context` requires a block and raises `ArgumentError` if called without
+one.
+
 ## Kernel Extension
 
 If you want to call `Retriable.retriable` without the `Retriable` module prefix and you don't mind extending `Kernel`,

data/lib/retriable/config.rb

@@ -18,16 +18,19 @@ module Retriable
       contexts
     ]).freeze
 
+    CONTEXT_ATTRIBUTES = (ATTRIBUTES - %i[contexts]).freeze
+    private_constant :CONTEXT_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 +54,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)
@@ -70,6 +74,21 @@ module Retriable
 
     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 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 = "4.2.0"
 end

data/lib/retriable.rb

@@ -41,6 +41,8 @@ module Retriable
   end
 
   def with_context(context_key, options = {}, &)
+    raise ArgumentError, "with_context requires a block" unless block_given?
+
     contexts = available_contexts
 
     if !contexts.key?(context_key)
@@ -48,8 +50,6 @@ module Retriable
             "#{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), &)
   end
 
@@ -97,6 +97,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)
 

data/sig/retriable.rbs

@@ -5,7 +5,7 @@ module Retriable
   def self.configure: () { (Config) -> void } -> void
   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

data/spec/config_spec.rb

@@ -180,4 +180,33 @@ describe Retriable::Config do
       end
     end
   end
+
+  context "context structure validation" do
+    it "rejects a context whose options contain a nested :contexts key" do
+      expect { described_class.new(contexts: { api: { contexts: {} } }) }
+        .to raise_error(ArgumentError, /contexts is not a valid option/)
+    end
+
+    it "rejects a context with an unknown option key" do
+      expect { described_class.new(contexts: { api: { does_not_exist: 1 } }) }
+        .to raise_error(ArgumentError, /does_not_exist is not a valid option/)
+    end
+
+    it "validates context structure even when intervals is provided" do
+      expect { described_class.new(intervals: [0.1], contexts: { api: { contexts: {} } }) }
+        .to raise_error(ArgumentError, /contexts is not a valid option/)
+    end
+
+    it "accepts a non-Hash context value (treated as empty options)" do
+      expect { described_class.new(contexts: { broken: nil }) }.not_to raise_error
+    end
+
+    it "accepts nil contexts" do
+      expect { described_class.new(contexts: nil) }.not_to raise_error
+    end
+
+    it "accepts a valid context" do
+      expect { described_class.new(contexts: { api: { tries: 3, base_interval: 1.0 } }) }.not_to raise_error
+    end
+  end
 end

data/spec/retriable_spec.rb

@@ -52,9 +52,9 @@ describe Retriable do
 
     # These two specs lock in the anonymous block forwarding (`&`) semantics
     # across both delegation layers: Kernel#retriable_with_context ->
-    # Retriable.with_context. If the `&` is dropped at either layer, the
-    # block is not forwarded and the inner `block_given?` check at
-    # lib/retriable.rb:51 short-circuits, causing the block to never run.
+    # Retriable.with_context. If the `&` is dropped at either layer, the block
+    # is not forwarded and the `block_given?` guard in with_context raises
+    # ArgumentError instead of running the block.
     it "forwards a block through Kernel#retriable_with_context" do
       require_relative "../lib/retriable/core_ext/kernel"
       Retriable.configure { |c| c.contexts[:sql] = { tries: 1 } }
@@ -64,13 +64,23 @@ describe Retriable do
       expect(@tries).to eq(1)
     end
 
-    it "returns nil when Kernel#retriable_with_context is called without a block" do
+    it "raises an ArgumentError when Kernel#retriable_with_context is called without a block" do
       require_relative "../lib/retriable/core_ext/kernel"
       Retriable.configure { |c| c.contexts[:sql] = { tries: 1 } }
 
-      expect(retriable_with_context(:sql)).to be_nil
+      expect { retriable_with_context(:sql) }
+        .to raise_error(ArgumentError, /with_context requires a block/)
       expect(@tries).to eq(0)
     end
+
+    it "is not callable with an explicit receiver" do
+      require_relative "../lib/retriable/core_ext/kernel"
+
+      expect { "foo".retriable { increment_tries } }
+        .to raise_error(NoMethodError, /private method/)
+      expect { "foo".retriable_with_context(:sql) { increment_tries } }
+        .to raise_error(NoMethodError, /private method/)
+    end
   end
 
   context "#retriable" do
@@ -1248,8 +1258,15 @@ describe Retriable do
       expect(@tries).to eq(1)
     end
 
-    it "returns nil when called without a block" do
-      expect(described_class.with_context(:sql)).to be_nil
+    it "raises an ArgumentError when called without a block" do
+      expect { described_class.with_context(:sql) }
+        .to raise_error(ArgumentError, /with_context requires a block/)
+      expect(@tries).to eq(0)
+    end
+
+    it "checks for a block before looking up the context" do
+      expect { described_class.with_context(:missing) }
+        .to raise_error(ArgumentError, /with_context requires a block/)
       expect(@tries).to eq(0)
     end
 
@@ -1290,6 +1307,13 @@ describe Retriable do
       expect(@tries).to eq(1)
     end
 
+    it "surfaces an invalid context on any retriable call before that context is used" do
+      described_class.configure { |c| c.contexts[:unused] = { contexts: {} } }
+
+      expect { described_class.retriable { :ok } }
+        .to raise_error(ArgumentError, /contexts is not a valid option/)
+    end
+
     it "invokes on_give_up configured on a context" do
       callback_called = false
       described_class.configure do |c|

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: retriable
 version: !ruby/object:Gem::Version
-  version: 4.1.1
+  version: 4.2.0
 platform: ruby
 authors:
 - Jack Chu
@@ -65,7 +65,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Retriable is a simple DSL to retry failed code blocks with randomized exponential
   backoff