faraday-retry-2.3.2/0000755000004100000410000000000015026104522014315 5ustar www-datawww-datafaraday-retry-2.3.2/lib/0000755000004100000410000000000015026104522015063 5ustar www-datawww-datafaraday-retry-2.3.2/lib/faraday/0000755000004100000410000000000015026104522016472 5ustar www-datawww-datafaraday-retry-2.3.2/lib/faraday/retry.rb0000644000004100000410000000045515026104522020170 0ustar www-datawww-data# frozen_string_literal: true require 'faraday' require_relative 'retriable_response' require_relative 'retry/middleware' require_relative 'retry/version' module Faraday # Middleware main module. module Retry Faraday::Request.register_middleware(retry: Faraday::Retry::Middleware) end end faraday-retry-2.3.2/lib/faraday/retriable_response.rb0000644000004100000410000000024315026104522022705 0ustar www-datawww-data# frozen_string_literal: true # Faraday namespace. module Faraday # Exception used to control the Retry middleware. class RetriableResponse < Error end end faraday-retry-2.3.2/lib/faraday/retry/0000755000004100000410000000000015026104522017637 5ustar www-datawww-datafaraday-retry-2.3.2/lib/faraday/retry/retryable.rb0000644000004100000410000000224515026104522022160 0ustar www-datawww-data# frozen_string_literal: true module Faraday # 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 end faraday-retry-2.3.2/lib/faraday/retry/version.rb0000644000004100000410000000013515026104522021650 0ustar www-datawww-data# frozen_string_literal: true module Faraday module Retry VERSION = '2.3.2' end end faraday-retry-2.3.2/lib/faraday/retry/middleware.rb0000644000004100000410000002411015026104522022277 0ustar www-datawww-data# frozen_string_literal: true require_relative 'retryable' module Faraday module Retry # This class provides the main implementation for your middleware. # Your middleware can implement any of the following methods: # * on_request - called when the request is being prepared # * on_complete - called when the response is being processed # # Optionally, you can also override the following methods from Faraday::Middleware # * initialize(app, options = {}) - the initializer method # * call(env) - the main middleware invocation method. # This already calls on_request and on_complete, so you normally don't need to override it. # You may need to in case you need to "wrap" the request or need more control # (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 ].freeze IDEMPOTENT_METHODS = %i[delete get head options put].freeze # Options contains the configurable parameters for the Retry middleware. class Options < Faraday::Options.new(:max, :interval, :max_interval, :interval_randomness, :backoff_factor, :exceptions, :methods, :retry_if, :retry_block, :retry_statuses, :rate_limit_retry_header, :rate_limit_reset_header, :header_parser_block, :exhausted_retries_block) DEFAULT_CHECK = ->(_env, _exception) { false } def self.from(value) if value.is_a?(Integer) new(value) else super(value) end end def max (self[:max] ||= 2).to_i end def interval (self[:interval] ||= 0).to_f end def max_interval (self[:max_interval] ||= Float::MAX).to_f end def interval_randomness (self[:interval_randomness] ||= 0).to_f end def backoff_factor (self[:backoff_factor] ||= 1).to_f end def exceptions Array(self[:exceptions] ||= DEFAULT_EXCEPTIONS) end def methods Array(self[:methods] ||= IDEMPOTENT_METHODS) end def retry_if self[:retry_if] ||= DEFAULT_CHECK end def retry_block self[:retry_block] ||= proc {} end def retry_statuses Array(self[:retry_statuses] ||= []) end def exhausted_retries_block self[:exhausted_retries_block] ||= proc {} end end # @param app [#call] # @param options [Hash] # @option options [Integer] :max (2) Maximum number of retries # @option options [Integer] :interval (0) Pause in seconds between retries # @option options [Integer] :interval_randomness (0) The maximum random # interval amount expressed as a float between # 0 and 1 to use in addition to the interval. # @option options [Integer] :max_interval (Float::MAX) An upper limit # for the interval # @option options [Integer] :backoff_factor (1) The amount to multiply # each successive retry's interval amount by in order to provide backoff # @option options [Array] :exceptions ([ Errno::ETIMEDOUT, # '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, 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 # the env object and the exception raised # and should decide if the code should retry still the action or # not independent of the retry count. This would be useful # if the exception produced is non-recoverable or if the # the HTTP method called is not idempotent. # @option options [Block] :retry_block block that is executed before # every retry. The block will be yielded keyword arguments: # * env [Faraday::Env]: Request environment # * options [Faraday::Options]: middleware options # * retry_count [Integer]: how many retries have already occured (starts at 0) # * exception [Exception]: exception that triggered the retry, # will be the synthetic `Faraday::RetriableResponse` if the # retry was triggered by something other than an exception. # * will_retry_in [Float]: retry_block is called *before* the retry # delay, actual retry will happen in will_retry_in number of # seconds. # @option options [Array] :retry_statuses Array of Integer HTTP status # codes or a single Integer value that determines whether to raise # a Faraday::RetriableResponse exception based on the HTTP status code # of an HTTP response. # @option options [Block] :header_parser_block block that will receive # 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) @errmatch = build_exception_matcher(@options.exceptions) end def calculate_sleep_amount(retries, env) retry_after = [calculate_retry_after(env), calculate_rate_limit_reset(env)].compact.max retry_interval = calculate_retry_interval(retries) return if retry_after && retry_after > @options.max_interval if retry_after && retry_after >= retry_interval retry_after else retry_interval end end # @param env [Faraday::Env] def call(env) retries = @options.max request_body = env[:body] 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 end end # An exception matcher for the rescue clause can usually be any object # that responds to `===`, but for Ruby 1.8 it has to be a Class or Module. # # @param exceptions [Array] # @api private # @return [Module] an exception matcher def build_exception_matcher(exceptions) matcher = Module.new ( class << matcher self end).class_eval do define_method(:===) do |error| exceptions.any? do |ex| if ex.is_a? Module error.is_a? ex else Object.const_defined?(ex.to_s) && error.is_a?(Object.const_get(ex.to_s)) end end end end matcher end private def retry_request?(env, exception) @options.methods.include?(env[:method]) || @options.retry_if.call(env, exception) end def rewind_files(body) return unless defined?(Faraday::UploadIO) return unless body.is_a?(Hash) body.each do |_, value| value.rewind if value.is_a?(Faraday::UploadIO) end end # RFC for RateLimit Header Fields for HTTP: # https://www.ietf.org/archive/id/draft-ietf-httpapi-ratelimit-headers-05.html#name-fields-definition def calculate_rate_limit_reset(env) reset_header = @options.rate_limit_reset_header || 'RateLimit-Reset' parse_retry_header(env, reset_header) end # MDN spec for Retry-After header: # https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After def calculate_retry_after(env) retry_header = @options.rate_limit_retry_header || 'Retry-After' parse_retry_header(env, retry_header) end def calculate_retry_interval(retries) retry_index = @options.max - retries current_interval = @options.interval * (@options.backoff_factor**retry_index) current_interval = [current_interval, @options.max_interval].min random_interval = rand * @options.interval_randomness.to_f * @options.interval current_interval + random_interval end def parse_retry_header(env, header) response_headers = env[:response_headers] return unless response_headers retry_after_value = env[:response_headers][header] if @options.header_parser_block @options.header_parser_block.call(retry_after_value) else # Try to parse date from the header value begin datetime = DateTime.rfc2822(retry_after_value) datetime.to_time - Time.now.utc rescue ArgumentError retry_after_value.to_f end end end end end end faraday-retry-2.3.2/LICENSE.md0000644000004100000410000000207315026104522015723 0ustar www-datawww-dataThe MIT License (MIT) Copyright (c) 2021 Mattia Giuffrida Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. faraday-retry-2.3.2/faraday-retry.gemspec0000644000004100000410000000563515026104522020445 0ustar www-datawww-data######################################################### # This file has been automatically generated by gem2tgz # ######################################################### # -*- encoding: utf-8 -*- # stub: faraday-retry 2.3.2 ruby lib Gem::Specification.new do |s| s.name = "faraday-retry".freeze s.version = "2.3.2" s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version= s.metadata = { "bug_tracker_uri" => "https://github.com/lostisland/faraday-retry/issues", "changelog_uri" => "https://github.com/lostisland/faraday-retry/blob/v2.3.2/CHANGELOG.md", "documentation_uri" => "http://www.rubydoc.info/gems/faraday-retry/2.3.2", "homepage_uri" => "https://github.com/lostisland/faraday-retry", "source_code_uri" => "https://github.com/lostisland/faraday-retry" } if s.respond_to? :metadata= s.require_paths = ["lib".freeze] s.authors = ["Mattia Giuffrida".freeze] s.date = "1980-01-02" s.description = "Catches exceptions and retries each request a limited number of times.\n".freeze s.email = ["giuffrida.mattia@gmail.com".freeze] s.files = ["CHANGELOG.md".freeze, "LICENSE.md".freeze, "README.md".freeze, "lib/faraday/retriable_response.rb".freeze, "lib/faraday/retry.rb".freeze, "lib/faraday/retry/middleware.rb".freeze, "lib/faraday/retry/retryable.rb".freeze, "lib/faraday/retry/version.rb".freeze] s.homepage = "https://github.com/lostisland/faraday-retry".freeze s.licenses = ["MIT".freeze] s.required_ruby_version = Gem::Requirement.new([">= 2.6".freeze, "< 4".freeze]) s.rubygems_version = "3.3.15".freeze s.summary = "Catches exceptions and retries each request a limited number of times".freeze if s.respond_to? :specification_version then s.specification_version = 4 end if s.respond_to? :add_runtime_dependency then s.add_development_dependency(%q.freeze, ["~> 2.0"]) s.add_runtime_dependency(%q.freeze, ["~> 2.0"]) s.add_development_dependency(%q.freeze, ["~> 13.0"]) s.add_development_dependency(%q.freeze, ["~> 3.0"]) s.add_development_dependency(%q.freeze, ["~> 1.21.0"]) s.add_development_dependency(%q.freeze, ["~> 0.5.0"]) s.add_development_dependency(%q.freeze, ["~> 1.0"]) s.add_development_dependency(%q.freeze, ["~> 2.0"]) s.add_development_dependency(%q.freeze, ["~> 0.21.0"]) else s.add_dependency(%q.freeze, ["~> 2.0"]) s.add_dependency(%q.freeze, ["~> 2.0"]) s.add_dependency(%q.freeze, ["~> 13.0"]) s.add_dependency(%q.freeze, ["~> 3.0"]) s.add_dependency(%q.freeze, ["~> 1.21.0"]) s.add_dependency(%q.freeze, ["~> 0.5.0"]) s.add_dependency(%q.freeze, ["~> 1.0"]) s.add_dependency(%q.freeze, ["~> 2.0"]) s.add_dependency(%q.freeze, ["~> 0.21.0"]) end end faraday-retry-2.3.2/README.md0000644000004100000410000001665015026104522015604 0ustar www-datawww-data# Faraday Retry [![CI](https://github.com/lostisland/faraday-retry/actions/workflows/ci.yml/badge.svg)](https://github.com/lostisland/faraday-retry/actions/workflows/ci.yml) [![Gem](https://img.shields.io/gem/v/faraday-retry.svg?style=flat-square)](https://rubygems.org/gems/faraday-retry) [![License](https://img.shields.io/github/license/lostisland/faraday-retry.svg?style=flat-square)](LICENSE.md) The `Retry` middleware automatically retries requests that fail due to intermittent client or server errors (such as network hiccups). By default, it retries 2 times and handles only timeout exceptions. It can be configured with an arbitrary number of retries, a list of exceptions to handle, a retry interval, a percentage of randomness to add to the retry interval, and a backoff factor. The middleware can also handle the [`Retry-After`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After) header automatically when configured with the right status codes (see below for an example). ## Installation Add this line to your application's Gemfile: ```ruby gem 'faraday-retry' ``` And then execute: ```shell bundle install ``` Or install it yourself as: ```shell gem install faraday-retry ``` ## Usage This example will result in a first interval that is random between 0.05 and 0.075 and a second interval that is random between 0.1 and 0.125. ```ruby require 'faraday' require 'faraday/retry' retry_options = { max: 2, interval: 0.05, interval_randomness: 0.5, backoff_factor: 2 } conn = Faraday.new(...) do |f| f.request :retry, retry_options #... end conn.get('/') ``` ### Control when the middleware will retry requests By default, the `Retry` middleware will only retry idempotent methods and the most common network-related exceptions. You can change this behaviour by providing the right option when adding the middleware to your connection. #### Specify which methods will be retried You can provide a `methods` option with a list of HTTP methods. This will replace the default list of HTTP methods: `delete`, `get`, `head`, `options`, `put`. ```ruby retry_options = { methods: %i[get post] } ``` #### Specify which exceptions should trigger a retry You can provide an `exceptions` option with a list of exceptions that will replace 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 retry_options = { exceptions: [Faraday::ResourceNotFound, Faraday::UnauthorizedError] } ``` 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. However, you can specify a list of HTTP statuses you'd like to be retried. When you do so, the middleware will check the response `status` code and will retry the request if included in the list. ```ruby retry_options = { retry_statuses: [401, 409] } ``` #### Automatically handle the `Retry-After` and `RateLimit-Reset` headers Some APIs, like the [Slack API](https://api.slack.com/docs/rate-limits), will inform you when you reach their API limits by replying with a response status code of `429` and a response header of `Retry-After` containing a time in seconds. You should then only retry querying after the amount of time provided by the `Retry-After` header, otherwise you won't get a response. Other APIs communicate their rate limits via the [RateLimit-xxx](https://www.ietf.org/archive/id/draft-ietf-httpapi-ratelimit-headers-05.html#name-providing-ratelimit-fields) headers where `RateLimit-Reset` behaves similarly to the `Retry-After`. You can automatically handle both headers and have Faraday pause and retry for the right amount of time by including the `429` status code in the retry statuses list: ```ruby retry_options = { retry_statuses: [429] } ``` If you are working with an API which does not comply with the Rate Limit RFC you can specify custom headers to be used for retry and reset, as well as a block to parse the headers: ```ruby retry_options = { retry_statuses: [429], rate_limit_retry_header: 'x-rate-limit-retry-after', rate_limit_reset_header: 'x-rate-limit-reset', header_parser_block: ->(value) { Time.at(value.to_i).utc - Time.now.utc } } ``` #### Specify a custom retry logic You can also specify a custom retry logic with the `retry_if` option. This option accepts a block that will receive the `env` object and the exception raised and should decide if the code should retry still the action or not independent of the retry count. This would be useful if the exception produced is non-recoverable or if the the HTTP method called is not idempotent. **NOTE:** this option will only be used for methods that are not included in the `methods` option. If you want this to apply to all HTTP methods, pass `methods: []` as an additional option. ```ruby # Retries the request if response contains { success: false } retry_options = { retry_if: -> (env, _exc) { env.body[:success] == 'false' } } ``` ### Call a block on every retry 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 response_statuses = [] retry_options = { retry_block: -> (env:, options:, retry_count:, exception:, will_retry_in:) { response_statuses << env.status } } ``` ### 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. Then, run `bin/test` to run the tests. To install this gem onto your local machine, run `rake build`. ### Releasing a new version To release a new version, make a commit with a message such as "Bumped to 0.0.2", and change the _Unreleased_ heading in `CHANGELOG.md` to a heading like "0.0.2 (2022-01-01)", and then use GitHub Releases to author a release. A GitHub Actions workflow then publishes a new gem to [RubyGems.org](https://rubygems.org/gems/faraday-retry). ## Contributing Bug reports and pull requests are welcome on [GitHub](https://github.com/lostisland/faraday-retry). ## License 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/included/raising-errors faraday-retry-2.3.2/CHANGELOG.md0000644000004100000410000000353015026104522016127 0ustar www-datawww-data# 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]! ## v2.1.0 (2023-03-03) * Support for custom RateLimit headers. [PR #13](https://github.com/lostisland/faraday-retry/pull/13). Thanks, [@brookemckim]! v2.1.1 (2023-02-17) is a spurious not-released version that you may have seen mentioned in this CHANGELOG. ## v2.0.0 (2022-06-08) ### Changed * `retry_block` now takes keyword arguments instead of positional (backwards incompatible) * `retry_block`'s `retry_count` argument now counts up from 0, instead of old `retries_remaining` ### Added * Support for the `RateLimit-Reset` header. [PR #9](https://github.com/lostisland/faraday-retry/pull/9). Thanks, [@maxprokopiev]! * `retry_block` has additional `will_retry_in` argument with upcoming delay before retry in seconds. ## v1.0 Initial release. This release consists of the same middleware that was previously bundled with Faraday but removed in Faraday v2.0, plus: ### Fixed * Retry middleware `retry_block` is not called if retry will not happen due to `max_interval`, https://github.com/lostisland/faraday/pull/1350 [@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