faraday 0.7.4 → 1.0.1

data/lib/faraday/request/retry.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+module Faraday
+  class Request
+    # Catches exceptions and retries each request a limited number of times.
+    #
+    # 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.
+    #
+    # @example Configure Retry middleware using intervals
+    #   Faraday.new do |conn|
+    #     conn.request(:retry, max: 2,
+    #                          interval: 0.05,
+    #                          interval_randomness: 0.5,
+    #                          backoff_factor: 2,
+    #                          exceptions: [CustomException, 'Timeout::Error'])
+    #
+    #     conn.adapter(:net_http) # NB: Last middleware must be the adapter
+    #   end
+    #
+    # 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.15.
+    class Retry < Faraday::Middleware
+      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)
+
+        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
+      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 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 after
+      #   every retry. Request environment, middleware options, current number
+      #   of retries and the exception is passed to the block as parameters.
+      # @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.
+      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)
+        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]
+        begin
+          # after failure env[:body] is set to the response body
+          env[:body] = request_body
+          @app.call(env).tap do |resp|
+            if @options.retry_statuses.include?(resp.status)
+              raise Faraday::RetriableResponse.new(nil, resp)
+            end
+          end
+        rescue @errmatch => e
+          if retries.positive? && retry_request?(env, e)
+            retries -= 1
+            rewind_files(request_body)
+            @options.retry_block.call(env, @options, retries, e)
+            if (sleep_amount = calculate_sleep_amount(retries + 1, env))
+              sleep sleep_amount
+              retry
+            end
+          end
+
+          raise unless e.is_a?(Faraday::RetriableResponse)
+
+          e.response
+        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
+                error.class.to_s == 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 body.is_a?(Hash)
+
+        body.each do |_, value|
+          value.rewind if value.is_a?(UploadIO)
+        end
+      end
+
+      # MDN spec for Retry-After header:
+      # https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After
+      def calculate_retry_after(env)
+        response_headers = env[:response_headers]
+        return unless response_headers
+
+        retry_after_value = env[:response_headers]['Retry-After']
+
+        # 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
+
+      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
+    end
+  end
+end

data/lib/faraday/request/token_authentication.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Faraday
+  class Request
+    # TokenAuthentication is a middleware that adds a 'Token' header to a
+    # Faraday request.
+    class TokenAuthentication < load_middleware(:authorization)
+      # Public
+      def self.header(token, options = nil)
+        options ||= {}
+        options[:token] = token
+        super(:Token, options)
+      end
+
+      def initialize(app, token, options = nil)
+        super(app, token, options)
+      end
+    end
+  end
+end

data/lib/faraday/request/url_encoded.rb

@@ -1,37 +1,56 @@
+# frozen_string_literal: true
+
 module Faraday
-  class Request::UrlEncoded < Faraday::Middleware
-    CONTENT_TYPE = 'Content-Type'.freeze
+  class Request
+    # Middleware for supporting urlencoded requests.
+    class UrlEncoded < Faraday::Middleware
+      unless defined?(::Faraday::Request::UrlEncoded::CONTENT_TYPE)
+        CONTENT_TYPE = 'Content-Type'
+      end
 
-    class << self
-      attr_accessor :mime_type
-    end
-    self.mime_type = 'application/x-www-form-urlencoded'.freeze
+      class << self
+        attr_accessor :mime_type
+      end
+      self.mime_type = 'application/x-www-form-urlencoded'
 
-    def call(env)
-      match_content_type(env) do |data|
-        env[:body] = Faraday::Utils.build_nested_query data
+      # Encodes as "application/x-www-form-urlencoded" if not already encoded or
+      # of another type.
+      #
+      # @param env [Faraday::Env]
+      def call(env)
+        match_content_type(env) do |data|
+          params = Faraday::Utils::ParamsHash[data]
+          env.body = params.to_query(env.params_encoder)
+        end
+        @app.call env
       end
-      @app.call env
-    end
-    
-    def match_content_type(env)
-      type = request_type(env)
-      
-      if process_request?(env)
-        env[:request_headers][CONTENT_TYPE] ||= self.class.mime_type
-        yield env[:body] unless env[:body].respond_to?(:to_str)
+
+      # @param env [Faraday::Env]
+      # @yield [request_body] Body of the request
+      def match_content_type(env)
+        return unless process_request?(env)
+
+        env.request_headers[CONTENT_TYPE] ||= self.class.mime_type
+        yield(env.body) unless env.body.respond_to?(:to_str)
       end
-    end
 
-    def process_request?(env)
-      type = request_type(env)
-      env[:body] and (type.empty? or type == self.class.mime_type)
-    end
+      # @param env [Faraday::Env]
+      #
+      # @return [Boolean] True if the request has a body and its Content-Type is
+      #                   urlencoded.
+      def process_request?(env)
+        type = request_type(env)
+        env.body && (type.empty? || (type == self.class.mime_type))
+      end
 
-    def request_type(env)
-      type = env[:request_headers][CONTENT_TYPE].to_s
-      type = type.split(';', 2).first if type.index(';')
-      type
+      # @param env [Faraday::Env]
+      #
+      # @return [String]
+      def request_type(env)
+        type = env.request_headers[CONTENT_TYPE].to_s
+        type = type.split(';', 2).first if type.index(';')
+        type
+      end
     end
   end
 end

data/lib/faraday/request.rb

@@ -1,6 +1,9 @@
+# frozen_string_literal: true
+
 module Faraday
-  # Used to setup urls, params, headers, and the request body in a sane manner.
+  # Used to setup URLs, params, headers, and the request body in a sane manner.
   #
+  # @example
   #   @connection.post do |req|
   #     req.url 'http://localhost', 'a' => '1' # 'http://localhost?a=1'
   #     req.headers['b'] = '2' # Header
@@ -9,76 +12,135 @@ module Faraday
   #     req.body = 'abc'
   #   end
   #
-  class Request < Struct.new(:path, :params, :headers, :body, :options)
-    extend AutoloadHelper
-
-    autoload_all 'faraday/request',
-      :JSON       => 'json',
-      :UrlEncoded => 'url_encoded',
-      :Multipart  => 'multipart'
+  # @!attribute method
+  #   @return [Symbol] the HTTP method of the Request
+  # @!attribute path
+  #   @return [URI, String] the path
+  # @!attribute params
+  #   @return [Hash] query parameters
+  # @!attribute headers
+  #   @return [Faraday::Utils::Headers] headers
+  # @!attribute body
+  #   @return [Hash] body
+  # @!attribute options
+  #   @return [RequestOptions] options
+  #
+  # rubocop:disable Style/StructInheritance
+  class Request < Struct.new(:method, :path, :params, :headers, :body, :options)
+    # rubocop:enable Style/StructInheritance
 
-    register_lookup_modules \
-      :json        => :JSON,
-      :url_encoded => :UrlEncoded,
-      :multipart   => :Multipart
+    extend MiddlewareRegistry
 
-    attr_reader :method
+    register_middleware File.expand_path('request', __dir__),
+                        url_encoded: [:UrlEncoded, 'url_encoded'],
+                        multipart: [:Multipart, 'multipart'],
+                        retry: [:Retry, 'retry'],
+                        authorization: [:Authorization, 'authorization'],
+                        basic_auth: [
+                          :BasicAuthentication,
+                          'basic_authentication'
+                        ],
+                        token_auth: [
+                          :TokenAuthentication,
+                          'token_authentication'
+                        ],
+                        instrumentation: [:Instrumentation, 'instrumentation']
 
+    # @param request_method [String]
+    # @yield [request] for block customization, if block given
+    # @yieldparam request [Request]
+    # @return [Request]
     def self.create(request_method)
       new(request_method).tap do |request|
-        yield request if block_given?
+        yield(request) if block_given?
       end
     end
 
-    def initialize(request_method)
-      @method = request_method
-      self.params  = {}
-      self.headers = {}
-      self.options = {}
+    # Replace params, preserving the existing hash type.
+    #
+    # @param hash [Hash] new params
+    def params=(hash)
+      if params
+        params.replace hash
+      else
+        super
+      end
     end
 
-    def url(path, params = {})
-      self.path   = path
-      self.params = params
+    # Replace request headers, preserving the existing hash type.
+    #
+    # @param hash [Hash] new headers
+    def headers=(hash)
+      if headers
+        headers.replace hash
+      else
+        super
+      end
     end
 
+    # Update path and params.
+    #
+    # @param path [URI, String]
+    # @param params [Hash, nil]
+    # @return [void]
+    def url(path, params = nil)
+      if path.respond_to? :query
+        if (query = path.query)
+          path = path.dup
+          path.query = nil
+        end
+      else
+        anchor_index = path.index('#')
+        path = path.slice(0, anchor_index) unless anchor_index.nil?
+        path, query = path.split('?', 2)
+      end
+      self.path = path
+      self.params.merge_query query, options.params_encoder
+      self.params.update(params) if params
+    end
+
+    # @param key [Object] key to look up in headers
+    # @return [Object] value of the given header name
     def [](key)
       headers[key]
     end
 
+    # @param key [Object] key of header to write
+    # @param value [Object] value of header
     def []=(key, value)
       headers[key] = value
     end
 
-    # ENV Keys
-    # :method - a symbolized request method (:get, :post)
-    # :body   - the request body that will eventually be converted to a string.
-    # :url    - Addressable::URI instance of the URI for the current request.
-    # :status           - HTTP response status code
-    # :request_headers  - hash of HTTP Headers to be sent to the server
-    # :response_headers - Hash of HTTP headers from the server
-    # :parallel_manager - sent if the connection is in parallel mode
-    # :request - Hash of options for configuring the request.
-    #   :timeout      - open/read timeout Integer in seconds
-    #   :open_timeout - read timeout Integer in seconds
-    #   :proxy        - Hash of proxy options
-    #     :uri        - Proxy Server URI
-    #     :user       - Proxy server username
-    #     :password   - Proxy server password
-    # :ssl - Hash of options for configuring SSL requests.
-    def to_env(connection)
-      env_params  = connection.params.merge(params)
-      env_headers = connection.headers.merge(headers)
-      request_options = Utils.deep_merge(connection.options, options)
-      Utils.deep_merge!(request_options, :proxy => connection.proxy)
+    # Marshal serialization support.
+    #
+    # @return [Hash] the hash ready to be serialized in Marshal.
+    def marshal_dump
+      {
+        method: method,
+        body: body,
+        headers: headers,
+        path: path,
+        params: params,
+        options: options
+      }
+    end
 
-      { :method           => method,
-        :body             => body,
-        :url              => connection.build_url(path, env_params),
-        :request_headers  => env_headers,
-        :parallel_manager => connection.parallel_manager,
-        :request          => request_options,
-        :ssl              => connection.ssl}
+    # Marshal serialization support.
+    # Restores the instance variables according to the +serialised+.
+    # @param serialised [Hash] the serialised object.
+    def marshal_load(serialised)
+      self.method  = serialised[:method]
+      self.body    = serialised[:body]
+      self.headers = serialised[:headers]
+      self.path    = serialised[:path]
+      self.params  = serialised[:params]
+      self.options = serialised[:options]
+    end
+
+    # @return [Env] the Env for this Request
+    def to_env(connection)
+      Env.new(method, body, connection.build_exclusive_url(path, params),
+              options, headers, connection.ssl, connection.parallel_manager)
     end
   end
 end

data/lib/faraday/response/logger.rb

@@ -1,34 +1,33 @@
+# frozen_string_literal: true
+
 require 'forwardable'
+require 'faraday/logging/formatter'
 
 module Faraday
-  class Response::Logger < Response::Middleware
-    extend Forwardable
-
-    def initialize(app, logger = nil)
-      super(app)
-      @logger = logger || begin
-        require 'logger'
-        ::Logger.new(STDOUT)
+  class Response
+    # Logger is a middleware that logs internal events in the HTTP request
+    # lifecycle to a given Logger object. By default, this logs to STDOUT. See
+    # Faraday::Logging::Formatter to see specifically what is logged.
+    class Logger < Middleware
+      def initialize(app, logger = nil, options = {})
+        super(app)
+        logger ||= begin
+          require 'logger'
+          ::Logger.new($stdout)
+        end
+        formatter_class = options.delete(:formatter) || Logging::Formatter
+        @formatter = formatter_class.new(logger: logger, options: options)
+        yield @formatter if block_given?
       end
-    end
-
-    def_delegators :@logger, :debug, :info, :warn, :error, :fatal
-
-    def call(env)
-      info "#{env[:method]} #{env[:url].to_s}"
-      debug('request') { dump_headers env[:request_headers] }
-      super
-    end
-
-    def on_complete(env)
-      info('Status') { env[:status].to_s }
-      debug('response') { dump_headers env[:response_headers] }
-    end
 
-    private
+      def call(env)
+        @formatter.request(env)
+        super
+      end
 
-    def dump_headers(headers)
-      headers.map { |k, v| "#{k}: #{v.inspect}" }.join("\n")
+      def on_complete(env)
+        @formatter.response(env)
+      end
     end
   end
 end

data/lib/faraday/response/raise_error.rb

@@ -1,16 +1,45 @@
+# frozen_string_literal: true
+
 module Faraday
-  class Response::RaiseError < Response::Middleware
-    def on_complete(env)
-      case env[:status]
-      when 404
-        raise Faraday::Error::ResourceNotFound, response_values(env)
-      when 400...600
-        raise Faraday::Error::ClientError, response_values(env)
+  class Response
+    # RaiseError is a Faraday middleware that raises exceptions on common HTTP
+    # client or server error responses.
+    class RaiseError < Middleware
+      # rubocop:disable Naming/ConstantName
+      ClientErrorStatuses = (400...500).freeze
+      ServerErrorStatuses = (500...600).freeze
+      # rubocop:enable Naming/ConstantName
+
+      def on_complete(env)
+        case env[:status]
+        when 400
+          raise Faraday::BadRequestError, response_values(env)
+        when 401
+          raise Faraday::UnauthorizedError, response_values(env)
+        when 403
+          raise Faraday::ForbiddenError, response_values(env)
+        when 404
+          raise Faraday::ResourceNotFound, response_values(env)
+        when 407
+          # mimic the behavior that we get with proxy requests with HTTPS
+          msg = %(407 "Proxy Authentication Required")
+          raise Faraday::ProxyAuthError.new(msg, response_values(env))
+        when 409
+          raise Faraday::ConflictError, response_values(env)
+        when 422
+          raise Faraday::UnprocessableEntityError, response_values(env)
+        when ClientErrorStatuses
+          raise Faraday::ClientError, response_values(env)
+        when ServerErrorStatuses
+          raise Faraday::ServerError, response_values(env)
+        when nil
+          raise Faraday::NilStatusError, response_values(env)
+        end
+      end
+
+      def response_values(env)
+        { status: env.status, headers: env.response_headers, body: env.body }
       end
-    end
-    
-    def response_values(env)
-      {:status => env[:status], :headers => env[:response_headers], :body => env[:body]}
     end
   end
 end