faraday-retry 2.2.0 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f4c985b60e619c7a2161b8643fda86adcd4927847a66d903bbc22a32ed851d13
-  data.tar.gz: 010d8a002a7310f82c44395344cc81cb3f8acfe9e53ca8aae8ae84cd3b66d90a
+  metadata.gz: af805c058f1e08fba4ab4c53587f88906f086f06bda02dd4daf578123d6aa79f
+  data.tar.gz: 714eeaadf0d8021d7c33f86ece4dda66366fcc6525e8bf395c3e71591d0a8bc2
 SHA512:
-  metadata.gz: b6dc78fe8c3b3ccc189c086271eb646e06f6e598a0a2b311ce3f0831321ba8f00b01d24be1c29521f7bbef5367eb17c43be7f6dfaa6402f0ec9cf206483f8794
-  data.tar.gz: 6338884c1806a7d06f33457db3939d71aaf761c9cc8c427a14c68257600d0601ff6765dde9b061254fd5af8f4ff77315d018a8d42d5326842fd0d26d0e52219f
+  metadata.gz: 6de30437afefef5b6887a0c7b2e72615775b63a92aaee63c37672631d9e09011b0b46fa9c208e6ca280d55ace287e12c9077ed18107968bc5593255cd028b6c1
+  data.tar.gz: dc0e7f4b11e714addd9a11426cc5071eb2245ea8f5cb24a38e7f63ee50030df81b14380912b4f0b786f9bfa53dfeccbc16f802337638054d7e36ad56be667f3f

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## Unreleased
+
+_nothing yet_
+
+## v2.2.1 (2024-04-15)
+
+* Avoid deprecation warning about ::UploadIO constant when used without faraday-multipart gem [PR #37](https://github.com/lostisland/faraday-retry/pull/37) [@iMacTia]
+* Documentation update [PR #30](https://github.com/lostisland/faraday-retry/pull/30) [@olleolleolle]
+* Documentation update [PR #32](https://github.com/lostisland/faraday-retry/pull/32) Thanks, [@Drowze]!
+
 ## v2.2.0 (2023-06-01)
 
 * Support new `header_parser_block` option. [PR #28](https://github.com/lostisland/faraday-retry/pull/28). Thanks, [@zavan]!
@@ -34,3 +44,6 @@ This release consists of the same middleware that was previously bundled with Fa
 [@maxprokopiev]: https://github.com/maxprokopiev
 [@brookemckim]: https://github.com/brookemckim
 [@zavan]: https://github.com/zavan
+[@Drowze]: https://github.com/Drowze
+[@olleolleolle]: https://github.com/olleolleolle
+[@iMacTia]: https://github.com/iMacTia

data/README.md

@@ -75,7 +75,7 @@ retry_options = {
 #### Specify which exceptions should trigger a retry
 
 You can provide an `exceptions` option with a list of exceptions that will replace
-the default list of network-related exceptions: `Errno::ETIMEDOUT`, `Timeout::Error`, `Faraday::TimeoutError`.
+the default exceptions: `Errno::ETIMEDOUT`, `Timeout::Error`, `Faraday::TimeoutError`, `Faraday::Error::RetriableResponse`.
 This can be particularly useful when combined with the [RaiseError][raise_error] middleware.
 
 ```ruby
@@ -84,6 +84,14 @@ retry_options = {
 }
 ```
 
+If you want to inherit default exceptions, do it this way.
+
+```ruby
+retry_options = {
+  exceptions: Faraday::Retry::Middleware::DEFAULT_EXCEPTIONS + [Faraday::ResourceNotFound, Faraday::UnauthorizedError]
+}
+```
+
 #### Specify on which response statuses to retry
 
 By default the `Retry` middleware will only retry the request if one of the expected exceptions arise.
@@ -141,13 +149,11 @@ retry_options = {
 
 ### Call a block on every retry
 
-You can specify a proc object through the `retry_block` option that will be called before every
-retry, before  There are many different applications for this feature, spacing from instrumentation to monitoring.
-
+You can specify a proc object through the `retry_block` option that will be called before every retry.
+There are many different applications for this feature, ranging from instrumentation to monitoring.
 
 The block is passed keyword arguments with contextual information: Request environment, middleware options, current number of retries, exception, and amount of time we will wait before retrying. (retry_block is called before the wait time happens)
 
-
 For example, you might want to keep track of the response statuses:
 
 ```ruby
@@ -157,6 +163,27 @@ retry_options = {
 }
 ```
 
+### Call a block after retries have been exhausted
+
+You can specify a lambda object through the `exhausted_retries_block` option that will be called after all retries are exhausted.
+This block will be called once.
+
+The block is passed keyword arguments with contextual information and passed your data:
+* Request environment,
+* exception,
+* middleware options
+* and your data.
+
+In a lambda you can pass any logic for further work.
+
+For example, you might want to update user by request query.
+
+```ruby
+retry_options = {
+  exhausted_retries_block: -> (user_id:, env:, exception:, options:) { User.find_by!(id: user_id).do_admin! }
+}
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies.
@@ -177,4 +204,4 @@ Bug reports and pull requests are welcome on [GitHub](https://github.com/lostisl
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
-[raise_error]:  https://lostisland.github.io/faraday/middleware/raise-error
+[raise_error]:  https://lostisland.github.io/faraday/#/middleware/included/raising-errors

data/lib/faraday/retry/middleware.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'retryable'
+
 module Faraday
   module Retry
     # This class provides the main implementation for your middleware.
@@ -15,6 +17,8 @@ module Faraday
     #   (see "retry" middleware: https://github.com/lostisland/faraday/blob/main/lib/faraday/request/retry.rb#L142).
     #   IMPORTANT: Remember to call `@app.call(env)` or `super` to not interrupt the middleware chain!
     class Middleware < Faraday::Middleware
+      include Retryable
+
       DEFAULT_EXCEPTIONS = [
         Errno::ETIMEDOUT, 'Timeout::Error',
         Faraday::TimeoutError, Faraday::RetriableResponse
@@ -27,7 +31,8 @@ module Faraday
                                            :backoff_factor, :exceptions,
                                            :methods, :retry_if, :retry_block,
                                            :retry_statuses, :rate_limit_retry_header,
-                                           :rate_limit_reset_header, :header_parser_block)
+                                           :rate_limit_reset_header, :header_parser_block,
+                                           :exhausted_retries_block)
 
         DEFAULT_CHECK = ->(_env, _exception) { false }
 
@@ -78,6 +83,10 @@ module Faraday
         def retry_statuses
           Array(self[:retry_statuses] ||= [])
         end
+
+        def exhausted_retries_block
+          self[:exhausted_retries_block] ||= proc {}
+        end
       end
 
       # @param app [#call]
@@ -95,8 +104,8 @@ module Faraday
       #   'Timeout::Error', Faraday::TimeoutError, Faraday::RetriableResponse])
       #   The list of exceptions to handle. Exceptions can be given as
       #   Class, Module, or String.
-      # @option options [Array] :methods (the idempotent HTTP methods
-      #   in IDEMPOTENT_METHODS) A list of HTTP methods to retry without
+      # @option options [Array<Symbol>] :methods (the idempotent HTTP methods
+      #   in IDEMPOTENT_METHODS) A list of HTTP methods, as symbols, to retry without
       #   calling retry_if. Pass an empty Array to call retry_if
       #   for all exceptions.
       # @option options [Block] :retry_if (false) block that will receive
@@ -124,6 +133,13 @@ module Faraday
       #   the the value of the retry header and should return the number of
       #   seconds to wait before retrying the request. This is useful if the
       #   value of the header is not a number of seconds or a RFC 2822 formatted date.
+      # @option options [Block] :exhausted_retries_block block will receive
+      #   when all attempts are exhausted. The block will be yielded keyword arguments:
+      #     * env [Faraday::Env]: Request environment
+      #     * exception [Exception]: exception that triggered the retry,
+      #       will be the synthetic `Faraday::RetriableResponse` if the
+      #       retry was triggered by something other than an exception.
+      #     * options [Faraday::Options]: middleware options
       def initialize(app, options = nil)
         super(app)
         @options = Options.from(options)
@@ -147,32 +163,14 @@ module Faraday
       def call(env)
         retries = @options.max
         request_body = env[:body]
-        begin
+
+        with_retries(env: env, options: @options, retries: retries, body: request_body, errmatch: @errmatch) do
           # after failure env[:body] is set to the response body
           env[:body] = request_body
+
           @app.call(env).tap do |resp|
             raise Faraday::RetriableResponse.new(nil, resp) if @options.retry_statuses.include?(resp.status)
           end
-        rescue @errmatch => e
-          if retries.positive? && retry_request?(env, e)
-            retries -= 1
-            rewind_files(request_body)
-            if (sleep_amount = calculate_sleep_amount(retries + 1, env))
-              @options.retry_block.call(
-                env: env,
-                options: @options,
-                retry_count: @options.max - (retries + 1),
-                exception: e,
-                will_retry_in: sleep_amount
-              )
-              sleep sleep_amount
-              retry
-            end
-          end
-
-          raise unless e.is_a?(Faraday::RetriableResponse)
-
-          e.response
         end
       end
 
@@ -209,11 +207,11 @@ module Faraday
       end
 
       def rewind_files(body)
-        return unless defined?(UploadIO)
+        return unless defined?(Faraday::UploadIO)
         return unless body.is_a?(Hash)
 
         body.each do |_, value|
-          value.rewind if value.is_a?(UploadIO)
+          value.rewind if value.is_a?(Faraday::UploadIO)
         end
       end
 

data/lib/faraday/retry/retryable.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+# Adds the ability to retry a request based on settings and errors that have occurred.
+module Retryable
+  def with_retries(env:, options:, retries:, body:, errmatch:)
+    yield
+  rescue errmatch => e
+    exhausted_retries(options, env, e) if retries_zero?(retries, env, e)
+
+    if retries.positive? && retry_request?(env, e)
+      retries -= 1
+      rewind_files(body)
+      if (sleep_amount = calculate_sleep_amount(retries + 1, env))
+        options.retry_block.call(
+          env: env,
+          options: options,
+          retry_count: options.max - (retries + 1),
+          exception: e,
+          will_retry_in: sleep_amount
+        )
+        sleep sleep_amount
+        retry
+      end
+    end
+
+    raise unless e.is_a?(Faraday::RetriableResponse)
+
+    e.response
+  end
+
+  private
+
+  def retries_zero?(retries, env, exception)
+    retries.zero? && retry_request?(env, exception)
+  end
+
+  def exhausted_retries(options, env, exception)
+    options.exhausted_retries_block.call(
+      env: env,
+      exception: exception,
+      options: options
+    )
+  end
+end

data/lib/faraday/retry/version.rb

@@ -2,6 +2,6 @@
 
 module Faraday
   module Retry
-    VERSION = '2.2.0'
+    VERSION = '2.3.0'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: faraday-retry
 version: !ruby/object:Gem::Version
-  version: 2.2.0
+  version: 2.3.0
 platform: ruby
 authors:
 - Mattia Giuffrida
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-06-01 00:00:00.000000000 Z
+date: 2025-03-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -151,17 +151,18 @@ files:
 - lib/faraday/retriable_response.rb
 - lib/faraday/retry.rb
 - lib/faraday/retry/middleware.rb
+- lib/faraday/retry/retryable.rb
 - lib/faraday/retry/version.rb
 homepage: https://github.com/lostisland/faraday-retry
 licenses:
 - MIT
 metadata:
   bug_tracker_uri: https://github.com/lostisland/faraday-retry/issues
-  changelog_uri: https://github.com/lostisland/faraday-retry/blob/v2.2.0/CHANGELOG.md
-  documentation_uri: http://www.rubydoc.info/gems/faraday-retry/2.2.0
+  changelog_uri: https://github.com/lostisland/faraday-retry/blob/v2.3.0/CHANGELOG.md
+  documentation_uri: http://www.rubydoc.info/gems/faraday-retry/2.3.0
   homepage_uri: https://github.com/lostisland/faraday-retry
   source_code_uri: https://github.com/lostisland/faraday-retry
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -180,7 +181,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.1.6
-signing_key: 
+signing_key:
 specification_version: 4
 summary: Catches exceptions and retries each request a limited number of times
 test_files: []