retriable 3.8.0 → 4.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/.github/workflows/main.yml +38 -9
- data/.hound.yml +1 -1
- data/.rubocop.yml +4 -1
- data/CHANGELOG.md +89 -0
- data/Gemfile +4 -1
- data/README.md +105 -50
- data/lib/retriable/config.rb +25 -57
- data/lib/retriable/core_ext/kernel.rb +6 -4
- data/lib/retriable/exponential_backoff.rb +13 -5
- data/lib/retriable/validation.rb +11 -7
- data/lib/retriable/version.rb +1 -1
- data/lib/retriable.rb +55 -31
- data/retriable.gemspec +2 -7
- data/sig/retriable.rbs +29 -1
- data/spec/config_spec.rb +63 -97
- data/spec/retriable_spec.rb +345 -95
- data/spec/spec_helper.rb +3 -14
- metadata +7 -53
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: a551efb6db5acea9e82dde8e48afdea1869f6b93461a3c48c33f8385fbea6392
|
|
4
|
+
data.tar.gz: fbf6bb8c5ade48420e0f2a43532bafff0e4159eb4cf149bce559116ec1c91e50
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 19d5ac72e1614b7fdb3984697db76ad3f6ae2e9b1f60ff1eb470e210738cd67154afc2776b55329fca345fad6263035a41eb0748626f427fd2d05cc0bfea9c89
|
|
7
|
+
data.tar.gz: c1d46594742b7c19985a63037199125b718e6c6395dd8276013719d8c7f9cd64376637471b90fa9249869767da9a2474cafc31afd04f373f73249d8ebdfa0337
|
data/.github/workflows/main.yml
CHANGED
|
@@ -14,26 +14,22 @@ jobs:
|
|
|
14
14
|
ci:
|
|
15
15
|
# The type of runner that the job will run on
|
|
16
16
|
runs-on: ${{ matrix.os }}
|
|
17
|
+
# Ruby 4.0 is still in preview. Treat its results as informational so a
|
|
18
|
+
# preview-only regression doesn't block merges. Drop this gate (or update
|
|
19
|
+
# the version literal) once Ruby 4.0 is released and we treat it as
|
|
20
|
+
# required.
|
|
21
|
+
continue-on-error: ${{ matrix.ruby == '4.0' }}
|
|
17
22
|
strategy:
|
|
18
23
|
matrix:
|
|
19
24
|
os: [ubuntu-24.04]
|
|
20
25
|
ruby:
|
|
21
26
|
[
|
|
22
|
-
"2.3",
|
|
23
|
-
"2.4",
|
|
24
|
-
"2.5",
|
|
25
|
-
"2.6",
|
|
26
|
-
"2.7",
|
|
27
|
-
"3.0",
|
|
28
|
-
"3.1",
|
|
29
27
|
"3.2",
|
|
30
28
|
"3.3",
|
|
31
29
|
"3.4",
|
|
32
30
|
"4.0",
|
|
33
31
|
jruby,
|
|
34
32
|
]
|
|
35
|
-
env:
|
|
36
|
-
CC_TEST_REPORTER_ID: 20a1139ef1830b4f813a10a03d90e8aa179b5226f75e75c5a949b25756ebf558
|
|
37
33
|
|
|
38
34
|
steps:
|
|
39
35
|
# Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
|
|
@@ -50,3 +46,36 @@ jobs:
|
|
|
50
46
|
|
|
51
47
|
- name: Run rspec
|
|
52
48
|
run: bundle exec rspec
|
|
49
|
+
|
|
50
|
+
lint:
|
|
51
|
+
runs-on: ubuntu-24.04
|
|
52
|
+
|
|
53
|
+
steps:
|
|
54
|
+
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
|
|
55
|
+
|
|
56
|
+
- name: Setup ruby
|
|
57
|
+
uses: ruby/setup-ruby@afeafc3d1ab54a631816aba4c914a0081c12ff2f # v1
|
|
58
|
+
with:
|
|
59
|
+
ruby-version: "3.3"
|
|
60
|
+
bundler-cache: true
|
|
61
|
+
|
|
62
|
+
- name: Run rubocop
|
|
63
|
+
run: bundle exec rubocop
|
|
64
|
+
|
|
65
|
+
- name: Validate RBS
|
|
66
|
+
run: bundle exec rbs -I sig validate
|
|
67
|
+
|
|
68
|
+
audit:
|
|
69
|
+
runs-on: ubuntu-24.04
|
|
70
|
+
|
|
71
|
+
steps:
|
|
72
|
+
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
|
|
73
|
+
|
|
74
|
+
- name: Setup ruby
|
|
75
|
+
uses: ruby/setup-ruby@afeafc3d1ab54a631816aba4c914a0081c12ff2f # v1
|
|
76
|
+
with:
|
|
77
|
+
ruby-version: "3.3"
|
|
78
|
+
bundler-cache: true
|
|
79
|
+
|
|
80
|
+
- name: Run bundler-audit
|
|
81
|
+
run: bundle exec bundle-audit check --update
|
data/.hound.yml
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
1
|
ruby:
|
|
2
|
-
|
|
2
|
+
enabled: false
|
data/.rubocop.yml
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
AllCops:
|
|
2
2
|
NewCops: enable
|
|
3
|
-
TargetRubyVersion: 2
|
|
3
|
+
TargetRubyVersion: 3.2
|
|
4
4
|
|
|
5
5
|
Style/StringLiterals:
|
|
6
6
|
EnforcedStyle: double_quotes
|
|
@@ -40,3 +40,6 @@ Metrics/AbcSize:
|
|
|
40
40
|
|
|
41
41
|
Style/TrailingCommaInArrayLiteral:
|
|
42
42
|
Enabled: false
|
|
43
|
+
|
|
44
|
+
Naming/MethodParameterName:
|
|
45
|
+
MinNameLength: 2
|
data/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,94 @@
|
|
|
1
1
|
# HEAD
|
|
2
2
|
|
|
3
|
+
## 4.2.0
|
|
4
|
+
|
|
5
|
+
### Bug fixes
|
|
6
|
+
|
|
7
|
+
- The `Kernel` extension methods (`require "retriable/core_ext/kernel"`) are now
|
|
8
|
+
private, matching idiomatic `Kernel` helpers like `puts` and `rand`.
|
|
9
|
+
Previously `retriable` and `retriable_with_context` were public instance
|
|
10
|
+
methods, so they leaked onto every object's public API and could be invoked
|
|
11
|
+
with an explicit receiver (e.g. `"foo".retriable { ... }`). They remain
|
|
12
|
+
callable in the documented receiver-less form.
|
|
13
|
+
([#146](https://github.com/kamui/retriable/pull/146))
|
|
14
|
+
- `Retriable.with_context` (and `Kernel#retriable_with_context`) now raises
|
|
15
|
+
`ArgumentError` when called without a block, matching `with_override`.
|
|
16
|
+
Previously a missing block was silently ignored: the call returned `nil` and
|
|
17
|
+
the intended block never ran, hiding a caller bug. Behavior change: code that
|
|
18
|
+
relied on the silent no-op will now raise.
|
|
19
|
+
- `Config#validate!` now validates the structure of each entry in `contexts`,
|
|
20
|
+
so configured contexts are checked on every `Retriable.retriable`/
|
|
21
|
+
`with_context` call rather than only when a given context is first used. A
|
|
22
|
+
context whose options contain an unknown key (including a nested `contexts`
|
|
23
|
+
key) now raises `ArgumentError, "<key> is not a valid option"`, matching the
|
|
24
|
+
`with_override` path. Non-Hash `contexts` and non-Hash per-context values
|
|
25
|
+
remain leniently treated as empty options (no behavior change). Option
|
|
26
|
+
_values_ are still validated lazily at retry time, unchanged.
|
|
27
|
+
|
|
28
|
+
### Docs
|
|
29
|
+
|
|
30
|
+
- Document that `on_retry` receives `next_interval: nil` on the final rescued
|
|
31
|
+
attempt, when Retriable is about to give up because `tries` are exhausted.
|
|
32
|
+
`on_retry` still fires before `on_give_up` (unchanged behavior); the `nil`
|
|
33
|
+
contract is now called out in the `on_retry` documentation so handlers guard
|
|
34
|
+
arithmetic or logging on `next_interval`.
|
|
35
|
+
|
|
36
|
+
### Performance
|
|
37
|
+
|
|
38
|
+
- `Config#initialize` no longer allocates a throwaway `ExponentialBackoff` (and
|
|
39
|
+
runs its redundant `validate!`) just to read default values. Defaults now live
|
|
40
|
+
in a frozen `ExponentialBackoff::DEFAULTS` constant, removing an allocation and
|
|
41
|
+
redundant validation from the `retriable` hot path.
|
|
42
|
+
([#149](https://github.com/kamui/retriable/pull/149))
|
|
43
|
+
|
|
44
|
+
## 4.1.1
|
|
45
|
+
|
|
46
|
+
### Bug fixes
|
|
47
|
+
|
|
48
|
+
- `retry_if`, `on_retry`, and `on_give_up` are now validated to be callable
|
|
49
|
+
(respond to `#call`) or falsy. A non-callable truthy value raises
|
|
50
|
+
`ArgumentError` at configuration time instead of a later `NoMethodError` on a
|
|
51
|
+
retry path. ([#140](https://github.com/kamui/retriable/pull/140))
|
|
52
|
+
|
|
53
|
+
### Internal
|
|
54
|
+
|
|
55
|
+
- Add RBS type signatures for the public API (`Retriable.configure`, `config`,
|
|
56
|
+
`retriable`, `with_override`, `with_context`, and `Retriable::Config`) and
|
|
57
|
+
validate them in CI with `rbs validate`.
|
|
58
|
+
([#142](https://github.com/kamui/retriable/pull/142))
|
|
59
|
+
- Enforce a minimum test coverage floor and add a `bundler-audit` dependency
|
|
60
|
+
audit job to CI. ([#143](https://github.com/kamui/retriable/pull/143))
|
|
61
|
+
- Remove an unused `CC_TEST_REPORTER_ID` from the CI workflow.
|
|
62
|
+
([#141](https://github.com/kamui/retriable/pull/141))
|
|
63
|
+
|
|
64
|
+
## 4.1.0
|
|
65
|
+
|
|
66
|
+
### Bug fixes
|
|
67
|
+
|
|
68
|
+
- A per-call or `with_context` `tries:` now clears an inherited `intervals:` from
|
|
69
|
+
global config or a context, matching the documented precedence. Previously
|
|
70
|
+
`Retriable.retriable(tries: 1)` was silently ignored when `intervals` was
|
|
71
|
+
configured, running `intervals.size + 1` times. Passing both `intervals:` and
|
|
72
|
+
`tries:` in the same call still lets `intervals:` win.
|
|
73
|
+
|
|
74
|
+
## 4.0.0
|
|
75
|
+
|
|
76
|
+
**This is a major release with breaking changes. Please read carefully before upgrading.**
|
|
77
|
+
|
|
78
|
+
### Breaking changes
|
|
79
|
+
|
|
80
|
+
- 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.
|
|
81
|
+
- 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.
|
|
82
|
+
|
|
83
|
+
### Features
|
|
84
|
+
|
|
85
|
+
- 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.
|
|
86
|
+
- 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`.
|
|
87
|
+
|
|
88
|
+
### Internal
|
|
89
|
+
|
|
90
|
+
- Switched `Retriable.retriable`, `Retriable.with_context`, and the `Kernel` extension methods to Ruby 3.1+ anonymous block forwarding. No user-visible behavior change.
|
|
91
|
+
|
|
3
92
|
## 3.8.0
|
|
4
93
|
|
|
5
94
|
### Deprecations
|
data/Gemfile
CHANGED
data/README.md
CHANGED
|
@@ -1,13 +1,13 @@
|
|
|
1
1
|
# Retriable
|
|
2
2
|
|
|
3
3
|
|
|
4
|
-
[](https://houndci.com)
|
|
5
4
|
|
|
6
5
|
Retriable is a simple DSL to retry failed code blocks with randomized [exponential backoff](http://en.wikipedia.org/wiki/Exponential_backoff) time intervals. This is especially useful when interacting external APIs, remote services, or file system calls.
|
|
7
6
|
|
|
8
7
|
## Table of Contents
|
|
9
8
|
|
|
10
9
|
- [Requirements](#requirements)
|
|
10
|
+
- [Migration from 3.x to 4.0](#migration-from-3x-to-40)
|
|
11
11
|
- [Installation](#installation)
|
|
12
12
|
- [Usage](#usage)
|
|
13
13
|
- [Defaults](#defaults)
|
|
@@ -17,10 +17,11 @@ Retriable is a simple DSL to retry failed code blocks with randomized [exponenti
|
|
|
17
17
|
- [Configuration](#configuration)
|
|
18
18
|
- [Override](#override)
|
|
19
19
|
- [Example Usage](#example-usage)
|
|
20
|
-
- [Migrating off `timeout:`](#migrating-off-timeout)
|
|
21
20
|
- [Custom Interval Array](#custom-interval-array)
|
|
21
|
+
- [Unbounded Retries (Opt-in)](#unbounded-retries-opt-in)
|
|
22
22
|
- [Turn off Exponential Backoff](#turn-off-exponential-backoff)
|
|
23
23
|
- [Callbacks](#callbacks)
|
|
24
|
+
- [Disabling a Configured Callback Per Call](#disabling-a-configured-callback-per-call)
|
|
24
25
|
- [Ensure/Else](#ensureelse)
|
|
25
26
|
- [Contexts](#contexts)
|
|
26
27
|
- [Kernel Extension](#kernel-extension)
|
|
@@ -31,13 +32,47 @@ Retriable is a simple DSL to retry failed code blocks with randomized [exponenti
|
|
|
31
32
|
|
|
32
33
|
## Requirements
|
|
33
34
|
|
|
34
|
-
Ruby
|
|
35
|
+
Ruby 3.2+
|
|
35
36
|
|
|
36
|
-
If you need
|
|
37
|
+
If you need Ruby 2.3.0-3.1.x support, use the [3.8.x branch](https://github.com/kamui/retriable/tree/3.8.x) by specifying `~> 3.8` in your Gemfile.
|
|
37
38
|
|
|
38
|
-
If you need
|
|
39
|
+
If you need Ruby 2.0.0-2.2.x support, use the [3.1 branch](https://github.com/kamui/retriable/tree/3.1.x) by specifying `~3.1` in your Gemfile.
|
|
39
40
|
|
|
40
|
-
If you need
|
|
41
|
+
If you need Ruby 1.9.3 support, use the [2.x branch](https://github.com/kamui/retriable/tree/2.x) by specifying `~2.1` in your Gemfile.
|
|
42
|
+
|
|
43
|
+
If you need Ruby 1.8.x to 1.9.2 support, use the [1.x branch](https://github.com/kamui/retriable/tree/1.x) by specifying `~1.4` in your Gemfile.
|
|
44
|
+
|
|
45
|
+
## Migration from 3.x to 4.0
|
|
46
|
+
|
|
47
|
+
### Ruby version
|
|
48
|
+
|
|
49
|
+
Retriable 4.0 requires Ruby 3.2 or later. If you run Ruby 2.3.0-3.1.x, or want to stay on the 3.x gem line, use Retriable 3.8.x by specifying `~> 3.8` in your Gemfile.
|
|
50
|
+
|
|
51
|
+
### `timeout:` option removed
|
|
52
|
+
|
|
53
|
+
The `timeout:` option was deprecated in Retriable 3.8.0 and has been removed in Retriable 4.0. It was a thin wrapper around `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. See [issue #96](https://github.com/kamui/retriable/issues/96) for the original report of this problem.
|
|
54
|
+
|
|
55
|
+
If you previously used `Retriable.retriable(timeout: 5) { ... }`, you have two recommended alternatives:
|
|
56
|
+
|
|
57
|
+
1. **Use your library's native timeout** (preferred). For example, configure `Net::HTTP#read_timeout`, Faraday's `request.timeout`, or your database client's statement timeout. Library-native timeouts do not have the safety issues of `Timeout.timeout`.
|
|
58
|
+
|
|
59
|
+
2. **Manage the timeout yourself inside the block** if no native option exists:
|
|
60
|
+
|
|
61
|
+
```ruby
|
|
62
|
+
require "timeout"
|
|
63
|
+
|
|
64
|
+
Retriable.retriable do
|
|
65
|
+
Timeout.timeout(5) do
|
|
66
|
+
# code here...
|
|
67
|
+
end
|
|
68
|
+
end
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
**Note:** This still uses `Timeout.timeout`, which has the same safety issues that motivated removing the option — interruption can happen at any line, including inside non-interrupt-safe library code (mutexes, file handles, network sockets, allocator state). Prefer option 1 wherever possible. For background, see [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), and [Timeout: Ruby's most dangerous API](https://www.mikeperham.com/2015/05/08/timeout-rubys-most-dangerous-api/).
|
|
72
|
+
|
|
73
|
+
Like the removed `timeout:` option, `Timeout.timeout(5)` inside the block is per-try — each retry gets a fresh 5-second budget. For an overall cap across all retries, use `max_elapsed_time:` instead.
|
|
74
|
+
|
|
75
|
+
Passing `timeout:` to `Retriable.retriable` or `Retriable.with_override` now raises `ArgumentError`. The `timeout` configuration attribute has also been removed, so `Retriable.configure { |c| c.timeout = 5 }` now raises `NoMethodError`.
|
|
41
76
|
|
|
42
77
|
## Installation
|
|
43
78
|
|
|
@@ -56,7 +91,7 @@ require 'retriable'
|
|
|
56
91
|
In your Gemfile:
|
|
57
92
|
|
|
58
93
|
```ruby
|
|
59
|
-
gem 'retriable', '~>
|
|
94
|
+
gem 'retriable', '~> 4.0'
|
|
60
95
|
```
|
|
61
96
|
|
|
62
97
|
## Usage
|
|
@@ -103,29 +138,29 @@ The default interval table with 10 tries looks like this (in seconds, rounded to
|
|
|
103
138
|
|
|
104
139
|
Here are the available options, in some vague order of relevance to most common use patterns:
|
|
105
140
|
|
|
106
|
-
| Option | Default | Definition
|
|
107
|
-
| ---------------------- | ----------------- |
|
|
108
|
-
| **`tries`** | `3` | Number of attempts to make at running your code block (includes initial attempt). Pass `Float::INFINITY` to keep retrying until success or until `max_elapsed_time` is reached.
|
|
109
|
-
| **`on`** | `[StandardError]` | Type of exceptions to retry. [Read more](#configuring-which-options-to-retry-with-on).
|
|
110
|
-
| **`retry_if`** | `nil` | Callable (for example a `Proc` or lambda) that receives the rescued exception and returns true/false to decide whether to retry. [Read more](#advanced-retry-matching-with-retry_if).
|
|
111
|
-
| **`on_retry`** | `nil` | `Proc` to call after each try is rescued. Pass `false` to disable a callback set in `#configure` for a single call. [Read more](#callbacks).
|
|
112
|
-
| **`
|
|
113
|
-
| **`
|
|
114
|
-
| **`
|
|
115
|
-
| **`
|
|
116
|
-
| **`
|
|
117
|
-
| **`
|
|
118
|
-
| **`
|
|
119
|
-
| **`
|
|
120
|
-
|
|
121
|
-
Timing options are validated before retrying. `tries` must be a positive integer when Retriable generates intervals, or `Float::INFINITY` for unbounded retries. `base_interval`, `max_interval`, `multiplier`,
|
|
141
|
+
| Option | Default | Definition |
|
|
142
|
+
| ---------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
143
|
+
| **`tries`** | `3` | Number of attempts to make at running your code block (includes initial attempt). Pass `Float::INFINITY` to keep retrying until success or until `max_elapsed_time` is reached. |
|
|
144
|
+
| **`on`** | `[StandardError]` | Type of exceptions to retry. [Read more](#configuring-which-options-to-retry-with-on). |
|
|
145
|
+
| **`retry_if`** | `nil` | Callable (for example a `Proc` or lambda) that receives the rescued exception and returns true/false to decide whether to retry. [Read more](#advanced-retry-matching-with-retry_if). |
|
|
146
|
+
| **`on_retry`** | `nil` | `Proc` to call after each try is rescued. Pass `false` to disable a callback set in `#configure` for a single call. [Read more](#callbacks). |
|
|
147
|
+
| **`on_give_up`** | `nil` | `Proc` to call when Retriable stops retrying after a rescued retriable exception. [Read more](#callbacks). |
|
|
148
|
+
| **`sleep_disabled`** | `false` | When true, disable exponential backoff and attempt retries immediately. |
|
|
149
|
+
| **`base_interval`** | `0.5` | The initial interval in seconds between tries. |
|
|
150
|
+
| **`max_elapsed_time`** | `900` (15 min) | The maximum amount of total time in seconds that code is allowed to keep being retried. Set to `nil` to disable the time limit and retry based solely on `tries`. |
|
|
151
|
+
| **`max_interval`** | `60` | The maximum interval in seconds that any individual retry can reach. |
|
|
152
|
+
| **`multiplier`** | `1.5` | Each successive interval grows by this factor. A multipler of 1.5 means the next interval will be 1.5x the current interval. |
|
|
153
|
+
| **`rand_factor`** | `0.5` | The percentage to randomize the next retry interval time. The next interval calculation is `randomized_interval = retry_interval * (random value in range [1 - randomization_factor, 1 + randomization_factor])` |
|
|
154
|
+
| **`intervals`** | `nil` | Skip generated intervals and provide your own array of intervals in seconds. [Read more](#custom-interval-array). |
|
|
155
|
+
|
|
156
|
+
Timing options are validated before retrying. `tries` must be a positive integer when Retriable generates intervals, or `Float::INFINITY` for unbounded retries. `base_interval`, `max_interval`, `multiplier`, and `max_elapsed_time` must be non-negative numbers, with `max_elapsed_time` also accepting `nil`. `rand_factor` must be a number from `0` through `1`. If provided, `intervals` must be an array of non-negative numbers; because it replaces generated intervals, it also overrides `tries`, `base_interval`, `max_interval`, `rand_factor`, and `multiplier` validation. `intervals` cannot be combined with `tries: Float::INFINITY`.
|
|
122
157
|
|
|
123
158
|
#### Configuring Which Options to Retry With :on
|
|
124
159
|
|
|
125
160
|
**`:on`** Can take the form:
|
|
126
161
|
|
|
127
162
|
- An `Exception` class (retry every exception of this type, including subclasses)
|
|
128
|
-
- An `Array` of `Exception` classes (retry any exception of one of these types, including subclasses)
|
|
163
|
+
- An `Array` or `Set` of `Exception` classes (retry any exception of one of these types, including subclasses)
|
|
129
164
|
- A `Hash` where the keys are `Exception` classes and the values are one of:
|
|
130
165
|
- `nil` (retry every exception of the key's type, including subclasses)
|
|
131
166
|
- A single `Regexp` pattern (retries exceptions ONLY if their `message` matches the pattern)
|
|
@@ -171,6 +206,11 @@ end
|
|
|
171
206
|
`#configure` sets defaults only. Per-call options passed to `Retriable.retriable` and
|
|
172
207
|
`Retriable.with_context` still take precedence.
|
|
173
208
|
|
|
209
|
+
When a higher-precedence layer sets `tries:` without `intervals:`, it clears any
|
|
210
|
+
`intervals:` inherited from a lower layer (so `retriable(tries: 1)` runs once even
|
|
211
|
+
if `intervals` was configured). Within a single call, passing `intervals:` still
|
|
212
|
+
overrides `tries:`.
|
|
213
|
+
|
|
174
214
|
### Override
|
|
175
215
|
|
|
176
216
|
`#with_override` is a block-scoped API for forcing retry options that should
|
|
@@ -208,8 +248,13 @@ do not inherit it. This makes `#with_override` safe to use in parallel test
|
|
|
208
248
|
runners. Fibers running inside the same thread share the thread's active
|
|
209
249
|
override.
|
|
210
250
|
|
|
211
|
-
`#with_override` stores the provided options
|
|
212
|
-
|
|
251
|
+
`#with_override` stores the provided options hash **by reference** and reads
|
|
252
|
+
from it on every attempt while the block runs. Treat the hash and all of its
|
|
253
|
+
nested values as immutable for the duration of the block: do not mutate them
|
|
254
|
+
from inside the block, and do not mutate them from another thread or fiber that
|
|
255
|
+
shares this thread's active override. Mutating the options mid-block results in
|
|
256
|
+
undefined retry behavior. If options must be computed, build the hash before
|
|
257
|
+
calling `#with_override` and do not retain a reference you will later mutate.
|
|
213
258
|
|
|
214
259
|
For test-integration patterns (RSpec `around`, helper methods, Minitest, etc.),
|
|
215
260
|
see [docs/testing.md](docs/testing.md).
|
|
@@ -219,6 +264,8 @@ see [docs/testing.md](docs/testing.md).
|
|
|
219
264
|
This example will only retry on a `Timeout::Error`, retry 3 times and sleep for a full second before each try.
|
|
220
265
|
|
|
221
266
|
```ruby
|
|
267
|
+
require "timeout"
|
|
268
|
+
|
|
222
269
|
Retriable.retriable(on: Timeout::Error, tries: 3, base_interval: 1) do
|
|
223
270
|
# code here...
|
|
224
271
|
end
|
|
@@ -227,6 +274,8 @@ end
|
|
|
227
274
|
You can also specify multiple errors to retry on by passing an array of exceptions.
|
|
228
275
|
|
|
229
276
|
```ruby
|
|
277
|
+
require "timeout"
|
|
278
|
+
|
|
230
279
|
Retriable.retriable(on: [Timeout::Error, Errno::ECONNRESET]) do
|
|
231
280
|
# code here...
|
|
232
281
|
end
|
|
@@ -244,28 +293,6 @@ Retriable.retriable(on: {
|
|
|
244
293
|
end
|
|
245
294
|
```
|
|
246
295
|
|
|
247
|
-
#### Migrating off `timeout:`
|
|
248
|
-
|
|
249
|
-
The `timeout:` option is deprecated in Retriable 3.8.0 and will be removed in Retriable 4.0. It still works in 3.x, but any non-nil value supplied through `Retriable.configure`, `Retriable.retriable(...)`, or `Retriable.with_override(...)` emits a deprecation warning. In Retriable 4.0, passing `timeout:` will raise `ArgumentError` because it will no longer be a valid option.
|
|
250
|
-
|
|
251
|
-
`timeout:` is deprecated because it is a thin wrapper around `Timeout.timeout`, which may be [unsafe](https://jvns.ca/blog/2015/11/27/why-rubys-timeout-is-dangerous-and-thread-dot-raise-is-terrifying/) [and](http://blog.headius.com/2008/02/ruby-threadraise-threadkill-timeoutrb.html) [even](https://adamhooper.medium.com/in-ruby-dont-use-timeout-77d9d4e5a001) [dangerous](https://www.mikeperham.com/2015/05/08/timeout-rubys-most-dangerous-api/). It can interrupt the retried block at any line, including inside libraries that are not interrupt-safe.
|
|
252
|
-
|
|
253
|
-
Prefer timeout settings from the library you are calling, such as `Net::HTTP#read_timeout`, `Net::HTTP#open_timeout`, or Faraday's request timeout options. If you still need `Timeout.timeout`, wrap the retried block explicitly so the risk is visible at the call site:
|
|
254
|
-
|
|
255
|
-
```ruby
|
|
256
|
-
require "timeout"
|
|
257
|
-
|
|
258
|
-
Retriable.retriable(on: Timeout::Error, tries: 3) do
|
|
259
|
-
Timeout.timeout(5) do
|
|
260
|
-
# code here...
|
|
261
|
-
end
|
|
262
|
-
end
|
|
263
|
-
```
|
|
264
|
-
|
|
265
|
-
Like the deprecated `timeout:` option, `Timeout.timeout(5)` inside the block is per-try — each retry gets a fresh 5-second budget. If you want an overall cap across all retries instead, prefer `max_elapsed_time:`.
|
|
266
|
-
|
|
267
|
-
The deprecation warning is emitted under the `:deprecated` warning category and at most once per process. To silence it (for example, in tests), use the standard Ruby controls — set `Warning[:deprecated] = false`, run with `ruby -W:no-deprecated`, or override `Warning.warn` to filter the message.
|
|
268
|
-
|
|
269
296
|
If you need millisecond units of time for the sleep interval:
|
|
270
297
|
|
|
271
298
|
```ruby
|
|
@@ -345,9 +372,11 @@ Retriable.retriable(on_retry: do_this_on_each_retry) do
|
|
|
345
372
|
end
|
|
346
373
|
```
|
|
347
374
|
|
|
375
|
+
> **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.
|
|
376
|
+
|
|
348
377
|
#### Disabling a Configured Callback Per Call
|
|
349
378
|
|
|
350
|
-
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
|
|
379
|
+
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`.
|
|
351
380
|
|
|
352
381
|
```ruby
|
|
353
382
|
Retriable.configure do |c|
|
|
@@ -365,6 +394,28 @@ Retriable.retriable(on_retry: false) do
|
|
|
365
394
|
end
|
|
366
395
|
```
|
|
367
396
|
|
|
397
|
+
You can also use `:on_give_up` to run a callback when Retriable stops retrying after a rescued retriable exception. This callback receives the `exception`, the `try_number`, the `elapsed_time` for all tries so far, the `next_interval`, and the `reason` Retriable is giving up. The `reason` is either `:tries_exhausted` or `:max_elapsed_time`.
|
|
398
|
+
|
|
399
|
+
```ruby
|
|
400
|
+
do_this_when_retries_stop = Proc.new do |exception, try, elapsed_time, next_interval, reason|
|
|
401
|
+
log "#{exception.class}: '#{exception.message}' - gave up after #{try} tries because #{reason}."
|
|
402
|
+
end
|
|
403
|
+
|
|
404
|
+
Retriable.retriable(on_give_up: do_this_when_retries_stop) do
|
|
405
|
+
# code here...
|
|
406
|
+
end
|
|
407
|
+
```
|
|
408
|
+
|
|
409
|
+
When the reason is `:tries_exhausted`, `next_interval` is `nil` because there is no next retry. When the reason is `:max_elapsed_time`, `next_interval` is the interval that would have been slept before the next try. This reason means the next retry would exceed `max_elapsed_time`, not necessarily that the elapsed time has already exceeded it.
|
|
410
|
+
|
|
411
|
+
If both `:on_retry` and `:on_give_up` are configured, `:on_retry` still runs first for the final rescued retriable exception. This preserves the existing behavior that `:on_retry` runs whenever Retriable rescues an exception that matches its retry rules.
|
|
412
|
+
|
|
413
|
+
If you configure a default `:on_give_up` callback but want to suppress it for a specific call, pass `on_give_up: false` (or `nil`). Both are treated as "no callback".
|
|
414
|
+
|
|
415
|
+
`:on_give_up` is invoked only when Retriable rescued an exception that matched the retry rules and then decided to stop. It does **not** fire when the block raises an exception that is not in `:on`, nor when `:retry_if` returns false. Both of those cases are immediate re-raises, not retry exhaustion, and should be handled with normal Ruby `rescue` blocks around the `Retriable.retriable` call.
|
|
416
|
+
|
|
417
|
+
If `:on_give_up` itself raises, that exception propagates to the caller and replaces the original retried exception. Keep the handler defensive (rescue inside it) if you need the original exception to surface.
|
|
418
|
+
|
|
368
419
|
### Ensure/Else
|
|
369
420
|
|
|
370
421
|
What if I want to execute a code block at the end, whether or not an exception was rescued ([ensure](http://ruby-doc.org/docs/keywords/1.9/Object.html#method-i-ensure))? Or what if I want to execute a code block if no exception is raised ([else](http://ruby-doc.org/docs/keywords/1.9/Object.html#method-i-else))? Instead of providing more callbacks, I recommend you just wrap retriable in a begin/retry/else/ensure block:
|
|
@@ -392,7 +443,8 @@ Retriable.configure do |c|
|
|
|
392
443
|
c.contexts[:aws] = {
|
|
393
444
|
tries: 3,
|
|
394
445
|
base_interval: 5,
|
|
395
|
-
on_retry: Proc.new { puts 'Curse you, AWS!' }
|
|
446
|
+
on_retry: Proc.new { puts 'Curse you, AWS!' },
|
|
447
|
+
on_give_up: Proc.new { |_e, _try, _elapsed, _interval, reason| puts "Gave up on AWS: #{reason}" }
|
|
396
448
|
}
|
|
397
449
|
c.contexts[:mysql] = {
|
|
398
450
|
tries: 10,
|
|
@@ -426,6 +478,9 @@ Retriable.with_context(:mysql, tries: 30) do
|
|
|
426
478
|
end
|
|
427
479
|
```
|
|
428
480
|
|
|
481
|
+
`#with_context` requires a block and raises `ArgumentError` if called without
|
|
482
|
+
one.
|
|
483
|
+
|
|
429
484
|
## Kernel Extension
|
|
430
485
|
|
|
431
486
|
If you want to call `Retriable.retriable` without the `Retriable` module prefix and you don't mind extending `Kernel`,
|
data/lib/retriable/config.rb
CHANGED
|
@@ -11,43 +11,33 @@ module Retriable
|
|
|
11
11
|
sleep_disabled
|
|
12
12
|
max_elapsed_time
|
|
13
13
|
intervals
|
|
14
|
-
timeout
|
|
15
14
|
on
|
|
16
15
|
retry_if
|
|
17
16
|
on_retry
|
|
17
|
+
on_give_up
|
|
18
18
|
contexts
|
|
19
19
|
]).freeze
|
|
20
20
|
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
"can interrupt execution at arbitrary lines and corrupt internal state " \
|
|
24
|
-
"in libraries that are not interrupt-safe. Prefer your library's native " \
|
|
25
|
-
"timeout, or wrap your block in `Timeout.timeout(...)` yourself."
|
|
26
|
-
private_constant :TIMEOUT_DEPRECATION_MESSAGE
|
|
27
|
-
|
|
28
|
-
@timeout_deprecation_warned = false
|
|
29
|
-
|
|
30
|
-
class << self
|
|
31
|
-
attr_accessor :timeout_deprecation_warned
|
|
32
|
-
end
|
|
21
|
+
CONTEXT_ATTRIBUTES = (ATTRIBUTES - %i[contexts]).freeze
|
|
22
|
+
private_constant :CONTEXT_ATTRIBUTES
|
|
33
23
|
|
|
34
24
|
attr_accessor(*ATTRIBUTES)
|
|
35
25
|
|
|
36
26
|
def initialize(opts = {})
|
|
37
|
-
|
|
27
|
+
defaults = ExponentialBackoff::DEFAULTS
|
|
38
28
|
|
|
39
|
-
@tries =
|
|
40
|
-
@base_interval =
|
|
41
|
-
@max_interval =
|
|
42
|
-
@rand_factor =
|
|
43
|
-
@multiplier =
|
|
29
|
+
@tries = defaults[:tries]
|
|
30
|
+
@base_interval = defaults[:base_interval]
|
|
31
|
+
@max_interval = defaults[:max_interval]
|
|
32
|
+
@rand_factor = defaults[:rand_factor]
|
|
33
|
+
@multiplier = defaults[:multiplier]
|
|
44
34
|
@sleep_disabled = false
|
|
45
35
|
@max_elapsed_time = 900 # 15 min
|
|
46
36
|
@intervals = nil
|
|
47
|
-
@timeout = nil
|
|
48
37
|
@on = [StandardError]
|
|
49
38
|
@retry_if = nil
|
|
50
39
|
@on_retry = nil
|
|
40
|
+
@on_give_up = nil
|
|
51
41
|
@contexts = {}
|
|
52
42
|
|
|
53
43
|
opts.each do |k, v|
|
|
@@ -60,14 +50,14 @@ module Retriable
|
|
|
60
50
|
end
|
|
61
51
|
|
|
62
52
|
def to_h
|
|
63
|
-
ATTRIBUTES.
|
|
64
|
-
hash[key] = public_send(key)
|
|
65
|
-
end
|
|
53
|
+
ATTRIBUTES.to_h { |key| [key, public_send(key)] }
|
|
66
54
|
end
|
|
67
55
|
|
|
68
56
|
def validate!
|
|
69
|
-
|
|
70
|
-
|
|
57
|
+
validate_contexts
|
|
58
|
+
validate_callable(:retry_if, retry_if)
|
|
59
|
+
validate_callable(:on_retry, on_retry)
|
|
60
|
+
validate_callable(:on_give_up, on_give_up)
|
|
71
61
|
validate_on(on)
|
|
72
62
|
validate_intervals
|
|
73
63
|
if unbounded_tries?(tries)
|
|
@@ -84,41 +74,19 @@ module Retriable
|
|
|
84
74
|
|
|
85
75
|
private
|
|
86
76
|
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
# notice is emitted under the `:deprecated` category, so callers can use the
|
|
91
|
-
# standard controls (`Warning[:deprecated] = false`, `-W:no-deprecated`,
|
|
92
|
-
# `Warning.warn` override) to silence it. On older Rubies the kwarg is not
|
|
93
|
-
# available and we fall back to plain `Kernel.warn`.
|
|
94
|
-
#
|
|
95
|
-
# When the warning is suppressed (either because `Warning[:deprecated]` is
|
|
96
|
-
# false or the runtime has otherwise muted the category), we deliberately
|
|
97
|
-
# leave the once-per-process flag unset so a future call with the category
|
|
98
|
-
# re-enabled still surfaces the notice.
|
|
99
|
-
def warn_timeout_deprecation
|
|
100
|
-
return if timeout.nil?
|
|
101
|
-
return if self.class.timeout_deprecation_warned
|
|
102
|
-
|
|
103
|
-
category_supported = deprecated_warning_category_supported?
|
|
104
|
-
return if category_supported && !deprecated_warnings_enabled?
|
|
105
|
-
|
|
106
|
-
self.class.timeout_deprecation_warned = true
|
|
107
|
-
if category_supported
|
|
108
|
-
Kernel.warn(TIMEOUT_DEPRECATION_MESSAGE, category: :deprecated)
|
|
109
|
-
else
|
|
110
|
-
Kernel.warn(TIMEOUT_DEPRECATION_MESSAGE)
|
|
111
|
-
end
|
|
112
|
-
end
|
|
77
|
+
def validate_contexts
|
|
78
|
+
return unless contexts.is_a?(Hash)
|
|
79
|
+
return if contexts.empty?
|
|
113
80
|
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
end
|
|
81
|
+
contexts.each_value do |options|
|
|
82
|
+
next unless options.is_a?(Hash)
|
|
117
83
|
|
|
118
|
-
|
|
119
|
-
|
|
84
|
+
options.each_key do |k|
|
|
85
|
+
next if CONTEXT_ATTRIBUTES.include?(k)
|
|
120
86
|
|
|
121
|
-
|
|
87
|
+
raise ArgumentError, "#{k} is not a valid option"
|
|
88
|
+
end
|
|
89
|
+
end
|
|
122
90
|
end
|
|
123
91
|
|
|
124
92
|
def validate_backoff_options
|
|
@@ -3,11 +3,13 @@
|
|
|
3
3
|
require_relative "../../retriable"
|
|
4
4
|
|
|
5
5
|
module Kernel
|
|
6
|
-
def retriable(opts = {}, &
|
|
7
|
-
Retriable.retriable(opts, &
|
|
6
|
+
def retriable(opts = {}, &)
|
|
7
|
+
Retriable.retriable(opts, &)
|
|
8
8
|
end
|
|
9
9
|
|
|
10
|
-
def retriable_with_context(context_key, opts = {}, &
|
|
11
|
-
Retriable.with_context(context_key, opts, &
|
|
10
|
+
def retriable_with_context(context_key, opts = {}, &)
|
|
11
|
+
Retriable.with_context(context_key, opts, &)
|
|
12
12
|
end
|
|
13
|
+
|
|
14
|
+
private :retriable, :retriable_with_context
|
|
13
15
|
end
|