retriable 3.4.1 → 4.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 86086d1d868b9f609e96d2b5e8e5f6e5910a9822b7c21dd86a4014a12105d7f3
-  data.tar.gz: a7324a228f6b0565428cb10afe6ecf3a98b7a6984ced4f83c32595f97767b09b
+  metadata.gz: a551efb6db5acea9e82dde8e48afdea1869f6b93461a3c48c33f8385fbea6392
+  data.tar.gz: fbf6bb8c5ade48420e0f2a43532bafff0e4159eb4cf149bce559116ec1c91e50
 SHA512:
-  metadata.gz: fc0f71e125a40e52fdb8e4cb99b71b066fc84a067e9011b166a14d08a9f98f20a15a32402818705172275ea8b0a0f814963265eabba9fcae6d7ac40cdfc9e520
-  data.tar.gz: d13f82d53fdc1c2be693a056fd4d164cddc4a7b34096c6c7367213f899881687854a3df5a20a07ad3678c3aa257297bd42a68cb36e9cf0718a2fa8be54a3bd56
+  metadata.gz: 19d5ac72e1614b7fdb3984697db76ad3f6ae2e9b1f60ff1eb470e210738cd67154afc2776b55329fca345fad6263035a41eb0748626f427fd2d05cc0bfea9c89
+  data.tar.gz: c1d46594742b7c19985a63037199125b718e6c6395dd8276013719d8c7f9cd64376637471b90fa9249869767da9a2474cafc31afd04f373f73249d8ebdfa0337

data/.github/workflows/main.yml

@@ -7,37 +7,36 @@ on:
     branches: [main]
     types: [opened, synchronize, reopened]
 
+permissions:
+  contents: read
+
 jobs:
   ci:
     # The type of runner that the job will run on
     runs-on: ${{ matrix.os }}
+    # Ruby 4.0 is still in preview. Treat its results as informational so a
+    # preview-only regression doesn't block merges. Drop this gate (or update
+    # the version literal) once Ruby 4.0 is released and we treat it as
+    # required.
+    continue-on-error: ${{ matrix.ruby == '4.0' }}
     strategy:
       matrix:
         os: [ubuntu-24.04]
         ruby:
           [
-            "2.3",
-            "2.4",
-            "2.5",
-            "2.6",
-            "2.7",
-            "3.0",
-            "3.1",
             "3.2",
             "3.3",
             "3.4",
             "4.0",
             jruby,
           ]
-    env:
-      CC_TEST_REPORTER_ID: 20a1139ef1830b4f813a10a03d90e8aa179b5226f75e75c5a949b25756ebf558
 
     steps:
       # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
 
       - name: Setup ruby
-        uses: ruby/setup-ruby@v1
+        uses: ruby/setup-ruby@afeafc3d1ab54a631816aba4c914a0081c12ff2f # v1
         with:
           ruby-version: ${{ matrix.ruby }}
           bundler-cache: true
@@ -47,3 +46,36 @@ jobs:
 
       - name: Run rspec
         run: bundle exec rspec
+
+  lint:
+    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 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/.hound.yml

@@ -1,2 +1,2 @@
 ruby:
-  config_file: .rubocop.yml
+  enabled: false

data/.rubocop.yml

@@ -1,6 +1,6 @@
 AllCops:
   NewCops: enable
-  TargetRubyVersion: 2.3
+  TargetRubyVersion: 3.2
 
 Style/StringLiterals:
   EnforcedStyle: double_quotes
@@ -40,3 +40,6 @@ Metrics/AbcSize:
 
 Style/TrailingCommaInArrayLiteral:
   Enabled: false
+
+Naming/MethodParameterName:
+  MinNameLength: 2

data/CHANGELOG.md

@@ -1,5 +1,123 @@
 # 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
+
+- A per-call or `with_context` `tries:` now clears an inherited `intervals:` from
+  global config or a context, matching the documented precedence. Previously
+  `Retriable.retriable(tries: 1)` was silently ignored when `intervals` was
+  configured, running `intervals.size + 1` times. Passing both `intervals:` and
+  `tries:` in the same call still lets `intervals:` win.
+
+## 4.0.0
+
+**This is a major release with breaking changes. Please read carefully before upgrading.**
+
+### Breaking changes
+
+- Removed `timeout:` option. The `timeout:` option has been removed from `Retriable.retriable`, `Retriable.configure`, and `Retriable.with_override`. It was a thin wrapper around Ruby's `Timeout.timeout`, which has well-documented safety issues: it interrupts execution at arbitrary lines and can corrupt internal state in libraries that are not interrupt-safe (mutexes, file handles, network sockets, allocator state). This was first raised against this gem in [#96](https://github.com/kamui/retriable/issues/96) in 2021; Retriable 3.8.0 deprecated the option, and 4.0 removes the footgun entirely. As a side effect, the historical bug where Retriable's own internal `Timeout::Error` was silently retried by default is no longer reachable, since Retriable no longer raises a timeout itself. User-raised `Timeout::Error` (for example, from a `Timeout.timeout` block you write inside the retried block) is still matched by the default `on: [StandardError]` because `Timeout::Error < RuntimeError < StandardError`. Passing `timeout:` to `Retriable.retriable` or `Retriable.with_override` now raises `ArgumentError`; setting `config.timeout` in `Retriable.configure` now raises `NoMethodError` because the configuration attribute has been removed. See the [4.0 migration section in the README](README.md#migration-from-3x-to-40) for replacement patterns.
+- Minimum Ruby version is now 3.2. Support for Ruby 2.x, 3.0, and 3.1 has been dropped in Retriable 4.0. If you need Retriable on Ruby 2.3.0-3.1.x, the 3.8.x line (`~> 3.8`) remains available.
+
+### Features
+
+- Add [`on_give_up`](README.md#callbacks) callback that runs when Retriable stops retrying after a rescued retriable exception. Receives `(exception, try, elapsed_time, next_interval, reason)`, where `reason` is `:tries_exhausted` or `:max_elapsed_time`. Does not fire for non-retriable exceptions or `retry_if` rejections. Pass `on_give_up: false` to suppress a configured handler for a single call.
+- Accept a [`Set` of `Exception` classes](README.md#configuring-which-options-to-retry-with-on) as the `on:` option, in addition to a single class, an `Array`, or a `Hash`.
+
+### Internal
+
+- Switched `Retriable.retriable`, `Retriable.with_context`, and the `Kernel` extension methods to Ruby 3.1+ anonymous block forwarding. No user-visible behavior change.
+
+## 3.8.0
+
+### Deprecations
+
+- Deprecated the `timeout:` option ahead of its removal in Retriable 4.0. Non-nil timeout values supplied through `Retriable.configure`, `Retriable.retriable(...)`, or `Retriable.with_override(...)` now emit a deprecation warning while keeping the existing runtime behavior unchanged. On Ruby 2.7+ the warning is emitted via `Kernel.warn(..., category: :deprecated)`, so callers can silence it through the standard Ruby controls (`Warning[:deprecated] = false`, `ruby -W:no-deprecated`, or a custom `Warning.warn`). To keep the notice from drowning busy applications, it is emitted at most once per process; suppression via `Warning[:deprecated]` leaves the warner armed for the next call that re-enables the category. Prefer library-native timeout settings, or wrap the retried block in `Timeout.timeout(...)` directly if you still need that behavior. See the README migration guidance for details.
+
+## 3.7.0
+
+- Feature: Opt-in unbounded retries via `tries: Float::INFINITY`. Requires a finite `max_elapsed_time` as a safety bound and is incompatible with custom `intervals:`. Both invalid configurations raise `ArgumentError` from `Config#validate!`.
+
+## 3.6.1
+
+- Fix: Validate the `on:` option before retrying. Previously, passing a non-`Exception` value such as `Object`, `Kernel`, or a plain `Module` (which appear in every `Exception`'s ancestor chain) would silently retry process-critical exceptions like `SystemExit` and `Interrupt`. The `on:` option now requires an `Exception` subclass, an array of them, or a hash whose keys are such classes and whose values are `nil`, a `Regexp`, or an array of `Regexp`s. Invalid shapes raise `ArgumentError` before the block runs.
+- Fix: Validate `with_override(contexts:)` shape before applying overrides. `contexts` may be `nil` or a hash, and each per-context override must be a hash.
+- Docs: Document that `on_retry: false` disables a callback set in `Retriable.configure` for a single call.
+
+## 3.6.0
+
+- Breaking: `Retriable.override` and `Retriable.reset_override` are removed and replaced by block-scoped `Retriable.with_override(opts) { ... }`. The new API requires a block, restores the previous override (or absence of override) when the block exits via `ensure`, and is thread-local — overrides set in one thread do not affect other threads, and child threads do not inherit them. Fibers within a thread still share the thread's active override. Nested `with_override` calls correctly restore the outer override on inner exit. See the README and `docs/testing.md` for migration and testing patterns. This replaces the override API introduced in 3.5.0.
+
+## 3.5.1
+
+- Fix: Validate retry timing and count options before use to reject invalid retry configurations. `tries` must now be a positive integer unless a custom `intervals` array is provided.
+
+## 3.5.0
+
+- Fix: Do not count skipped sleep intervals against `max_elapsed_time` when `sleep_disabled` is true.
+- Add `override` and `reset_override` APIs to force retry settings over local call options when needed (for example, test short-circuiting).
+
 ## 3.4.1
 
 - Fix: Use `Process.clock_gettime(CLOCK_MONOTONIC)` for elapsed time tracking so retry timing is immune to wall-clock adjustments (NTP, manual changes).

data/Gemfile

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