retriable 4.1.0 → 4.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 13cb5eedc133750c87f4678e0e94d1500e1d2c81ef474d0f38fd5ebff14b04a0
-  data.tar.gz: 773776c2ff6ae25aa3cc4202eb851086274204955df5c602dd6b147a17015103
+  metadata.gz: a551efb6db5acea9e82dde8e48afdea1869f6b93461a3c48c33f8385fbea6392
+  data.tar.gz: fbf6bb8c5ade48420e0f2a43532bafff0e4159eb4cf149bce559116ec1c91e50
 SHA512:
-  metadata.gz: 94477379cf7000dd9f81d0926ab02bfeffe31ebdec477ff930281cf8ba67f72c6fe78a116bb7e777f532bf0a58ae91da0a9b87c0dc927d51a754aaac36cef793
-  data.tar.gz: 63f3d0141d5efa4bf789455c10607e85ba2a1fde60cf834ba500b48cfe1bd0f9993e7cefb8ee77beb87e5c0e75034d24860a826330ee920e51a9313353bcd472
+  metadata.gz: 19d5ac72e1614b7fdb3984697db76ad3f6ae2e9b1f60ff1eb470e210738cd67154afc2776b55329fca345fad6263035a41eb0748626f427fd2d05cc0bfea9c89
+  data.tar.gz: c1d46594742b7c19985a63037199125b718e6c6395dd8276013719d8c7f9cd64376637471b90fa9249869767da9a2474cafc31afd04f373f73249d8ebdfa0337

data/.github/workflows/main.yml

@@ -30,8 +30,6 @@ jobs:
             "4.0",
             jruby,
           ]
-    env:
-      CC_TEST_REPORTER_ID: 20a1139ef1830b4f813a10a03d90e8aa179b5226f75e75c5a949b25756ebf558
 
     steps:
       # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
@@ -63,3 +61,21 @@ jobs:
 
       - name: Run rubocop
         run: bundle exec rubocop
+
+      - name: Validate RBS
+        run: bundle exec rbs -I sig validate
+
+  audit:
+    runs-on: ubuntu-24.04
+
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+
+      - name: Setup ruby
+        uses: ruby/setup-ruby@afeafc3d1ab54a631816aba4c914a0081c12ff2f # v1
+        with:
+          ruby-version: "3.3"
+          bundler-cache: true
+
+      - name: Run bundler-audit
+        run: bundle exec bundle-audit check --update

data/CHANGELOG.md

@@ -1,5 +1,66 @@
 # 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
+
+- `retry_if`, `on_retry`, and `on_give_up` are now validated to be callable
+  (respond to `#call`) or falsy. A non-callable truthy value raises
+  `ArgumentError` at configuration time instead of a later `NoMethodError` on a
+  retry path. ([#140](https://github.com/kamui/retriable/pull/140))
+
+### Internal
+
+- Add RBS type signatures for the public API (`Retriable.configure`, `config`,
+  `retriable`, `with_override`, `with_context`, and `Retriable::Config`) and
+  validate them in CI with `rbs validate`.
+  ([#142](https://github.com/kamui/retriable/pull/142))
+- Enforce a minimum test coverage floor and add a `bundler-audit` dependency
+  audit job to CI. ([#143](https://github.com/kamui/retriable/pull/143))
+- Remove an unused `CC_TEST_REPORTER_ID` from the CI workflow.
+  ([#141](https://github.com/kamui/retriable/pull/141))
+
 ## 4.1.0
 
 ### Bug fixes

data/Gemfile

@@ -10,7 +10,9 @@ group :test do
 end
 
 group :development do
+  gem "bundler-audit", "~> 0.9"
   gem "listen", "~> 3.1"
+  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,10 @@ 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)
       validate_on(on)
       validate_intervals
       if unbounded_tries?(tries)
@@ -67,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/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
 

data/lib/retriable/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Retriable
-  VERSION = "4.1.0"
+  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

@@ -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: () { (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.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

data/spec/config_spec.rb

@@ -163,4 +163,50 @@ describe Retriable::Config do
         .to raise_error(ArgumentError, /on must be an Exception class/)
     end
   end
+
+  context "callable option validation" do
+    %i[retry_if on_retry on_give_up].each do |opt|
+      it "accepts a callable for #{opt}" do
+        expect { described_class.new(opt => ->(*) {}) }.not_to raise_error
+      end
+
+      it "accepts nil and false for #{opt}" do
+        expect { described_class.new(opt => nil) }.not_to raise_error
+        expect { described_class.new(opt => false) }.not_to raise_error
+      end
+
+      it "rejects a non-callable truthy value for #{opt}" do
+        expect { described_class.new(opt => 5) }.to raise_error(ArgumentError, /#{opt}.*#call/)
+      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|

data/spec/spec_helper.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
 require "simplecov"
-SimpleCov.start
+SimpleCov.start do
+  minimum_coverage 95
+end
 
 require "pry"
 require_relative "../lib/retriable"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: retriable
 version: !ruby/object:Gem::Version
-  version: 4.1.0
+  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