faraday 0.16.2 → 0.17.0

data/lib/faraday/request.rb

@@ -1,9 +1,6 @@
-# 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
@@ -12,53 +9,25 @@ module Faraday
   #     req.body = 'abc'
   #   end
   #
-  # @!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
-
     extend MiddlewareRegistry
 
-    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']
+    register_middleware File.expand_path('../request', __FILE__),
+      :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?
       end
     end
 
-    # Replace params, preserving the existing hash type.
-    #
-    # @param hash [Hash] new params
+    # Public: Replace params, preserving the existing hash type
     def params=(hash)
       if params
         params.replace hash
@@ -67,9 +36,7 @@ module Faraday
       end
     end
 
-    # Replace request headers, preserving the existing hash type.
-    #
-    # @param hash [Hash] new headers
+    # Public: Replace request headers, preserving the existing hash type
     def headers=(hash)
       if headers
         headers.replace hash
@@ -78,14 +45,9 @@ module Faraday
       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)
+        if query = path.query
           path = path.dup
           path.query = nil
         end
@@ -99,35 +61,25 @@ module Faraday
       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
 
-    # 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
+        :method  => method,
+        :body    => body,
+        :headers => headers,
+        :path    => path,
+        :params  => params,
+        :options => options
       }
     end
 
-    # 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]
@@ -137,10 +89,26 @@ module Faraday
       self.options = serialised[:options]
     end
 
-    # @return [Env] the Env for this Request
+    # ENV Keys
+    # :method - a symbolized request method (:get, :post)
+    # :body   - the request body that will eventually be converted to a string.
+    # :url    - URI instance 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.new(method, body, connection.build_exclusive_url(path, params),
-              options, headers, connection.ssl, connection.parallel_manager)
+        options, headers, connection.ssl, connection.parallel_manager)
     end
   end
 end
+

data/lib/faraday/request/authorization.rb

@@ -1,53 +1,41 @@
-# frozen_string_literal: true
-
 module Faraday
-  class Request
-    # Request middleware for the Authorization HTTP header
-    class Authorization < Faraday::Middleware
-      KEY = 'Authorization' unless defined? KEY
+  class Request::Authorization < Faraday::Middleware
+    KEY = "Authorization".freeze unless defined? KEY
 
-      # @param type [String, Symbol]
-      # @param token [String, Symbol, Hash]
-      # @return [String] a header value
-      def self.header(type, token)
-        case token
-        when String, Symbol
-          "#{type} #{token}"
-        when Hash
-          build_hash(type.to_s, token)
-        else
-          raise ArgumentError,
-                "Can't build an Authorization #{type}" \
-                  "header from #{token.inspect}"
-        end
+    # Public
+    def self.header(type, token)
+      case token
+      when String, Symbol
+        "#{type} #{token}"
+      when Hash
+        build_hash(type.to_s, token)
+      else
+        raise ArgumentError, "Can't build an Authorization #{type} header from #{token.inspect}"
       end
+    end
 
-      # @param type [String]
-      # @param hash [Hash]
-      # @return [String] type followed by comma-separated key=value pairs
-      # @api private
-      def self.build_hash(type, hash)
-        comma = ', '
-        values = []
-        hash.each do |key, value|
-          values << "#{key}=#{value.to_s.inspect}"
-        end
-        "#{type} #{values * comma}"
+    # Internal
+    def self.build_hash(type, hash)
+      comma = ", "
+      values = []
+      hash.each do |key, value|
+        values << "#{key}=#{value.to_s.inspect}"
       end
+      "#{type} #{values * comma}"
+    end
 
-      # @param app [#call]
-      # @param type [String, Symbol] Type of Authorization
-      # @param token [String, Symbol, Hash] Token value for the Authorization
-      def initialize(app, type, token)
-        @header_value = self.class.header(type, token)
-        super(app)
-      end
+    def initialize(app, type, token)
+      @header_value = self.class.header(type, token)
+      super(app)
+    end
 
-      # @param env [Faraday::Env]
-      def call(env)
-        env.request_headers[KEY] = @header_value unless env.request_headers[KEY]
-        @app.call(env)
+    # Public
+    def call(env)
+      unless env.request_headers[KEY]
+        env.request_headers[KEY] = @header_value
       end
+      @app.call(env)
     end
   end
 end
+

data/lib/faraday/request/basic_authentication.rb

@@ -1,20 +1,13 @@
-# frozen_string_literal: true
-
 require 'base64'
 
 module Faraday
-  class Request
-    # Authorization middleware for Basic Authentication.
-    class BasicAuthentication < load_middleware(:authorization)
-      # @param login [String]
-      # @param pass [String]
-      #
-      # @return [String] a Basic Authentication header line
-      def self.header(login, pass)
-        value = Base64.encode64([login, pass].join(':'))
-        value.delete!("\n")
-        super(:Basic, value)
-      end
+  class Request::BasicAuthentication < Request.load_middleware(:authorization)
+    # Public
+    def self.header(login, pass)
+      value = Base64.encode64([login, pass].join(':'))
+      value.gsub!("\n", '')
+      super(:Basic, value)
     end
   end
 end
+

data/lib/faraday/request/instrumentation.rb

@@ -1,53 +1,35 @@
-# frozen_string_literal: true
-
 module Faraday
-  class Request
-    # Middleware for instrumenting Requests.
-    class Instrumentation < Faraday::Middleware
-      # Options class used in Request::Instrumentation class.
-      class Options < Faraday::Options.new(:name, :instrumenter)
-        # @return [String]
-        def name
-          self[:name] ||= 'request.faraday'
-        end
-
-        # @return [Class]
-        def instrumenter
-          self[:instrumenter] ||= ActiveSupport::Notifications
-        end
+  class Request::Instrumentation < Faraday::Middleware
+    class Options < Faraday::Options.new(:name, :instrumenter)
+      def name
+        self[:name] ||= 'request.faraday'
       end
 
-      # Instruments requests using Active Support.
-      #
-      # Measures time spent only for synchronous requests.
-      #
-      # @example Using ActiveSupport::Notifications to measure time spent
-      #   for Faraday requests.
-      #   ActiveSupport::Notifications
-      #     .subscribe('request.faraday') do |name, starts, ends, _, env|
-      #     url = env[:url]
-      #     http_method = env[:method].to_s.upcase
-      #     duration = ends - starts
-      #     $stderr.puts '[%s] %s %s (%.3f s)' %
-      #       [url.host, http_method, url.request_uri, duration]
-      #   end
-      # @param app [#call]
-      # @param options [nil, Hash] Options hash
-      # @option options [String] :name ('request.faraday')
-      #   Name of the instrumenter
-      # @option options [Class] :instrumenter (ActiveSupport::Notifications)
-      #   Active Support instrumenter class.
-      def initialize(app, options = nil)
-        super(app)
-        @name, @instrumenter = Options.from(options)
-                                      .values_at(:name, :instrumenter)
+      def instrumenter
+        self[:instrumenter] ||= ActiveSupport::Notifications
       end
+    end
+
+    # Public: Instruments requests using Active Support.
+    #
+    # Measures time spent only for synchronous requests.
+    #
+    # Examples
+    #
+    #   ActiveSupport::Notifications.subscribe('request.faraday') do |name, starts, ends, _, env|
+    #     url = env[:url]
+    #     http_method = env[:method].to_s.upcase
+    #     duration = ends - starts
+    #     $stderr.puts '[%s] %s %s (%.3f s)' % [url.host, http_method, url.request_uri, duration]
+    #   end
+    def initialize(app, options = nil)
+      super(app)
+      @name, @instrumenter = Options.from(options).values_at(:name, :instrumenter)
+    end
 
-      # @param env [Faraday::Env]
-      def call(env)
-        @instrumenter.instrument(@name, env) do
-          @app.call(env)
-        end
+    def call(env)
+      @instrumenter.instrument(@name, env) do
+        @app.call(env)
       end
     end
   end

data/lib/faraday/request/multipart.rb

@@ -1,97 +1,66 @@
-# frozen_string_literal: true
-
-require File.expand_path('url_encoded', __dir__)
+require File.expand_path("../url_encoded", __FILE__)
 require 'securerandom'
 
 module Faraday
-  class Request
-    # Middleware for supporting multi-part requests.
-    class Multipart < UrlEncoded
-      self.mime_type = 'multipart/form-data'
-      unless defined? DEFAULT_BOUNDARY_PREFIX
-        DEFAULT_BOUNDARY_PREFIX = '-----------RubyMultipartPost'
-      end
+  class Request::Multipart < Request::UrlEncoded
+    self.mime_type = 'multipart/form-data'.freeze
+    DEFAULT_BOUNDARY_PREFIX = "-----------RubyMultipartPost".freeze unless defined? DEFAULT_BOUNDARY_PREFIX
 
-      # Checks for files in the payload, otherwise leaves everything untouched.
-      #
-      # @param env [Faraday::Env]
-      def call(env)
-        match_content_type(env) do |params|
-          env.request.boundary ||= unique_boundary
-          env.request_headers[CONTENT_TYPE] +=
-            "; boundary=#{env.request.boundary}"
-          env.body = create_multipart(env, params)
-        end
-        @app.call env
+    def call(env)
+      match_content_type(env) do |params|
+        env.request.boundary ||= unique_boundary
+        env.request_headers[CONTENT_TYPE] += "; boundary=#{env.request.boundary}"
+        env.body = create_multipart(env, params)
       end
+      @app.call env
+    end
 
-      # @param env [Faraday::Env]
-      def process_request?(env)
-        type = request_type(env)
-        env.body.respond_to?(:each_key) && !env.body.empty? && (
-          (type.empty? && has_multipart?(env.body)) ||
-          (type == self.class.mime_type)
-        )
-      end
+    def process_request?(env)
+      type = request_type(env)
+      env.body.respond_to?(:each_key) and !env.body.empty? and (
+        (type.empty? and has_multipart?(env.body)) or
+        type == self.class.mime_type
+      )
+    end
 
-      # Returns true if obj is an enumerable with values that are multipart.
-      #
-      # @param obj [Object]
-      # @return [Boolean]
-      def has_multipart?(obj) # rubocop:disable Naming/PredicateName
-        if obj.respond_to?(:each)
-          (obj.respond_to?(:values) ? obj.values : obj).each do |val|
-            return true if val.respond_to?(:content_type) || has_multipart?(val)
-          end
+    def has_multipart?(obj)
+      # string is an enum in 1.8, returning list of itself
+      if obj.respond_to?(:each) && !obj.is_a?(String)
+        (obj.respond_to?(:values) ? obj.values : obj).each do |val|
+          return true if (val.respond_to?(:content_type) || has_multipart?(val))
         end
-        false
       end
+      false
+    end
 
-      # @param env [Faraday::Env]
-      # @param params [Hash]
-      def create_multipart(env, params)
-        boundary = env.request.boundary
-        parts = process_params(params) do |key, value|
-          part(boundary, key, value)
-        end
-        parts << Faraday::Parts::EpiloguePart.new(boundary)
-
-        body = Faraday::CompositeReadIO.new(parts)
-        env.request_headers[Faraday::Env::ContentLength] = body.length.to_s
-        body
+    def create_multipart(env, params)
+      boundary = env.request.boundary
+      parts = process_params(params) do |key, value|
+        Faraday::Parts::Part.new(boundary, key, value)
       end
+      parts << Faraday::Parts::EpiloguePart.new(boundary)
 
-      def part(boundary, key, value)
-        if value.respond_to?(:to_part)
-          value.to_part(boundary, key)
-        else
-          Faraday::Parts::Part.new(boundary, key, value)
-        end
-      end
+      body = Faraday::CompositeReadIO.new(parts)
+      env.request_headers[Faraday::Env::ContentLength] = body.length.to_s
+      return body
+    end
 
-      # @return [String]
-      def unique_boundary
-        "#{DEFAULT_BOUNDARY_PREFIX}-#{SecureRandom.hex}"
-      end
+    def unique_boundary
+      "#{DEFAULT_BOUNDARY_PREFIX}-#{SecureRandom.hex}"
+    end
 
-      # @param params [Hash]
-      # @param prefix [String]
-      # @param pieces [Array]
-      def process_params(params, prefix = nil, pieces = nil, &block)
-        params.inject(pieces || []) do |all, (key, value)|
-          key = "#{prefix}[#{key}]" if prefix
+    def process_params(params, prefix = nil, pieces = nil, &block)
+      params.inject(pieces || []) do |all, (key, value)|
+        key = "#{prefix}[#{key}]" if prefix
 
-          case value
-          when Array
-            values = value.inject([]) { |a, v| a << [nil, v] }
-            process_params(values, key, all, &block)
-          when Hash
-            process_params(value, key, all, &block)
-          else
-            # rubocop:disable Performance/RedundantBlockCall
-            all << block.call(key, value)
-            # rubocop:enable Performance/RedundantBlockCall
-          end
+        case value
+        when Array
+          values = value.inject([]) { |a,v| a << [nil, v] }
+          process_params(values, key, all, &block)
+        when Hash
+          process_params(value, key, all, &block)
+        else
+          all << block.call(key, value)
         end
       end
     end