faraday 1.0.0 → 2.9.0

data/lib/faraday/connection.rb

@@ -6,15 +6,16 @@ module Faraday
   #
   # @example
   #
-  #   conn = Faraday::Connection.new 'http://sushi.com'
+  #   conn = Faraday::Connection.new 'http://httpbingo.org'
   #
-  #   # GET http://sushi.com/nigiri
+  #   # GET http://httpbingo.org/nigiri
   #   conn.get 'nigiri'
   #   # => #<Faraday::Response>
   #
   class Connection
     # A Set of allowed HTTP verbs.
     METHODS = Set.new %i[get post put delete head patch options trace]
+    USER_AGENT = "Faraday v#{VERSION}".freeze
 
     # @return [Hash] URI query unencoded key/value pairs.
     attr_reader :params
@@ -26,7 +27,7 @@ module Faraday
     #   Connection. This includes a default host name, scheme, port, and path.
     attr_reader :url_prefix
 
-    # @return [Faraday::Builder] Builder for this Connection.
+    # @return [Faraday::RackBuilder] Builder for this Connection.
     attr_reader :builder
 
     # @return [Hash] SSL options.
@@ -63,7 +64,7 @@ module Faraday
       options = ConnectionOptions.from(options)
 
       if url.is_a?(Hash) || url.is_a?(ConnectionOptions)
-        options = options.merge(url)
+        options = Utils.deep_merge(options, url)
         url     = options.url
       end
 
@@ -73,6 +74,7 @@ module Faraday
       @options = options.request
       @ssl = options.ssl
       @default_parallel_manager = options.parallel_manager
+      @manual_proxy = nil
 
       @builder = options.builder || begin
         # pass an empty block to Builder so it doesn't assume default middleware
@@ -88,7 +90,7 @@ module Faraday
 
       yield(self) if block_given?
 
-      @headers[:user_agent] ||= "Faraday v#{VERSION}"
+      @headers[:user_agent] ||= USER_AGENT
     end
 
     def initialize_proxy(url, options)
@@ -115,7 +117,7 @@ module Faraday
 
     extend Forwardable
 
-    def_delegators :builder, :build, :use, :request, :response, :adapter, :app
+    def_delegators :builder, :use, :request, :response, :adapter, :app
 
     # Closes the underlying resources and/or connections. In the case of
     # persistent connections, this closes all currently open connections
@@ -128,10 +130,10 @@ module Faraday
     # Makes a GET HTTP request without a body.
     # @!scope class
     #
-    # @param url [String] The optional String base URL to use as a prefix for
+    # @param url [String, URI, nil] The optional String base URL to use as a prefix for
     #            all requests.  Can also be the options Hash.
-    # @param params [Hash] Hash of URI query unencoded key/value pairs.
-    # @param headers [Hash] unencoded HTTP header key/value pairs.
+    # @param params [Hash, nil] Hash of URI query unencoded key/value pairs.
+    # @param headers [Hash, nil] unencoded HTTP header key/value pairs.
     #
     # @example
     #   conn.get '/items', { page: 1 }, :accept => 'application/json'
@@ -150,10 +152,10 @@ module Faraday
     # Makes a HEAD HTTP request without a body.
     # @!scope class
     #
-    # @param url [String] The optional String base URL to use as a prefix for
+    # @param url [String, URI, nil] The optional String base URL to use as a prefix for
     #            all requests.  Can also be the options Hash.
-    # @param params [Hash] Hash of URI query unencoded key/value pairs.
-    # @param headers [Hash] unencoded HTTP header key/value pairs.
+    # @param params [Hash, nil] Hash of URI query unencoded key/value pairs.
+    # @param headers [Hash, nil] unencoded HTTP header key/value pairs.
     #
     # @example
     #   conn.head '/items/1'
@@ -165,10 +167,10 @@ module Faraday
     # Makes a DELETE HTTP request without a body.
     # @!scope class
     #
-    # @param url [String] The optional String base URL to use as a prefix for
+    # @param url [String, URI, nil] The optional String base URL to use as a prefix for
     #            all requests.  Can also be the options Hash.
-    # @param params [Hash] Hash of URI query unencoded key/value pairs.
-    # @param headers [Hash] unencoded HTTP header key/value pairs.
+    # @param params [Hash, nil] Hash of URI query unencoded key/value pairs.
+    # @param headers [Hash, nil] unencoded HTTP header key/value pairs.
     #
     # @example
     #   conn.delete '/items/1'
@@ -180,10 +182,10 @@ module Faraday
     # Makes a TRACE HTTP request without a body.
     # @!scope class
     #
-    # @param url [String] The optional String base URL to use as a prefix for
+    # @param url [String, URI, nil] The optional String base URL to use as a prefix for
     #            all requests.  Can also be the options Hash.
-    # @param params [Hash] Hash of URI query unencoded key/value pairs.
-    # @param headers [Hash] unencoded HTTP header key/value pairs.
+    # @param params [Hash, nil] Hash of URI query unencoded key/value pairs.
+    # @param headers [Hash, nil] unencoded HTTP header key/value pairs.
     #
     # @example
     #   conn.connect '/items/1'
@@ -208,9 +210,9 @@ module Faraday
     #
     # @overload options(url, params = nil, headers = nil)
     #   Makes an OPTIONS HTTP request to the given URL.
-    #   @param url [String] String base URL to sue as a prefix for all requests.
-    #   @param params [Hash] Hash of URI query unencoded key/value pairs.
-    #   @param headers [Hash] unencoded HTTP header key/value pairs.
+    #   @param url [String, URI, nil] String base URL to sue as a prefix for all requests.
+    #   @param params [Hash, nil] Hash of URI query unencoded key/value pairs.
+    #   @param headers [Hash, nil] unencoded HTTP header key/value pairs.
     #
     # @example
     #   conn.options '/items/1'
@@ -218,7 +220,7 @@ module Faraday
     # @yield [Faraday::Request] for further request customizations
     # @return [Faraday::Response]
     def options(*args)
-      return @options if args.size.zero?
+      return @options if args.empty?
 
       url, params, headers = *args
       run_request(:options, url, nil, headers) do |request|
@@ -231,10 +233,10 @@ module Faraday
     # Makes a POST HTTP request with a body.
     # @!scope class
     #
-    # @param url [String] The optional String base URL to use as a prefix for
+    # @param url [String, URI, nil] The optional String base URL to use as a prefix for
     #            all requests.  Can also be the options Hash.
-    # @param body [String] body for the request.
-    # @param headers [Hash] unencoded HTTP header key/value pairs.
+    # @param body [String, nil] body for the request.
+    # @param headers [Hash, nil] unencoded HTTP header key/value pairs.
     #
     # @example
     #   conn.post '/items', data, content_type: 'application/json'
@@ -253,20 +255,19 @@ module Faraday
     # Makes a PUT HTTP request with a body.
     # @!scope class
     #
-    # @param url [String] The optional String base URL to use as a prefix for
+    # @param url [String, URI, nil] The optional String base URL to use as a prefix for
     #            all requests.  Can also be the options Hash.
-    # @param body [String] body for the request.
-    # @param headers [Hash] unencoded HTTP header key/value pairs.
+    # @param body [String, nil] body for the request.
+    # @param headers [Hash, nil] unencoded HTTP header key/value pairs.
     #
     # @example
-    #   # TODO: Make it a PUT example
-    #   conn.post '/items', data, content_type: 'application/json'
+    #   conn.put '/products/123', data, content_type: 'application/json'
     #
-    #   # Simple ElasticSearch indexing sample.
-    #   conn.post '/twitter/tweet' do |req|
-    #     req.headers[:content_type] = 'application/json'
-    #     req.params[:routing] = 'kimchy'
-    #     req.body = JSON.generate(user: 'kimchy', ...)
+    #   # Star a gist.
+    #   conn.put 'https://api.github.com/gists/GIST_ID/star' do |req|
+    #     req.headers['Accept'] = 'application/vnd.github+json'
+    #     req.headers['Authorization'] = 'Bearer <YOUR-TOKEN>'
+    #     req.headers['X-GitHub-Api-Version'] = '2022-11-28'
     #   end
     #
     # @yield [Faraday::Request] for further request customizations
@@ -281,62 +282,6 @@ module Faraday
       RUBY
     end
 
-    # Sets up the Authorization header with these credentials, encoded
-    # with base64.
-    #
-    # @param login [String] The authentication login.
-    # @param pass [String] The authentication password.
-    #
-    # @example
-    #
-    #   conn.basic_auth 'Aladdin', 'open sesame'
-    #   conn.headers['Authorization']
-    #   # => "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=="
-    #
-    # @return [void]
-    def basic_auth(login, pass)
-      set_authorization_header(:basic_auth, login, pass)
-    end
-
-    # Sets up the Authorization header with the given token.
-    #
-    # @param token [String]
-    # @param options [Hash] extra token options.
-    #
-    # @example
-    #
-    #   conn.token_auth 'abcdef', foo: 'bar'
-    #   conn.headers['Authorization']
-    #   # => "Token token=\"abcdef\",
-    #               foo=\"bar\""
-    #
-    # @return [void]
-    def token_auth(token, options = nil)
-      set_authorization_header(:token_auth, token, options)
-    end
-
-    # Sets up a custom Authorization header.
-    #
-    # @param type [String] authorization type
-    # @param token [String, Hash] token. A String value is taken literally, and
-    #         a Hash is encoded into comma-separated key/value pairs.
-    #
-    # @example
-    #
-    #   conn.authorization :Bearer, 'mF_9.B5f-4.1JqM'
-    #   conn.headers['Authorization']
-    #   # => "Bearer mF_9.B5f-4.1JqM"
-    #
-    #   conn.authorization :Token, token: 'abcdef', foo: 'bar'
-    #   conn.headers['Authorization']
-    #   # => "Token token=\"abcdef\",
-    #               foo=\"bar\""
-    #
-    # @return [void]
-    def authorization(type, token)
-      set_authorization_header(:authorization, type, token)
-    end
-
     # Check if the adapter is parallel-capable.
     #
     # @yield if the adapter isn't parallel-capable, or if no adapter is set yet.
@@ -403,11 +348,11 @@ module Faraday
     # @example
     #
     #   conn = Faraday::Connection.new { ... }
-    #   conn.url_prefix = "https://sushi.com/api"
+    #   conn.url_prefix = "https://httpbingo.org/api"
     #   conn.scheme      # => https
     #   conn.path_prefix # => "/api"
     #
-    #   conn.get("nigiri?page=2") # accesses https://sushi.com/api/nigiri
+    #   conn.get("nigiri?page=2") # accesses https://httpbingo.org/api/nigiri
     def url_prefix=(url, encoder = nil)
       uri = @url_prefix = Utils.URI(url)
       self.path_prefix = uri.path
@@ -416,9 +361,16 @@ module Faraday
       uri.query = nil
 
       with_uri_credentials(uri) do |user, password|
-        basic_auth user, password
+        set_basic_auth(user, password)
         uri.user = uri.password = nil
       end
+
+      @proxy = proxy_from_env(url) unless @manual_proxy
+    end
+
+    def set_basic_auth(user, password)
+      header = Faraday::Utils.basic_header_from(user, password)
+      headers[Faraday::Request::Authorization::KEY] = header
     end
 
     # Sets the path prefix and ensures that it always has a leading
@@ -429,7 +381,7 @@ module Faraday
     # @return [String] the new path prefix
     def path_prefix=(value)
       url_prefix.path = if value
-                          value = '/' + value unless value[0, 1] == '/'
+                          value = "/#{value}" unless value[0, 1] == '/'
                           value
                         end
     end
@@ -437,20 +389,20 @@ module Faraday
     # Takes a relative url for a request and combines it with the defaults
     # set on the connection instance.
     #
-    # @param url [String]
+    # @param url [String, URI, nil]
     # @param extra_params [Hash]
     #
     # @example
     #   conn = Faraday::Connection.new { ... }
-    #   conn.url_prefix = "https://sushi.com/api?token=abc"
+    #   conn.url_prefix = "https://httpbingo.org/api?token=abc"
     #   conn.scheme      # => https
     #   conn.path_prefix # => "/api"
     #
     #   conn.build_url("nigiri?page=2")
-    #   # => https://sushi.com/api/nigiri?token=abc&page=2
+    #   # => https://httpbingo.org/api/nigiri?token=abc&page=2
     #
     #   conn.build_url("nigiri", page: 2)
-    #   # => https://sushi.com/api/nigiri?token=abc&page=2
+    #   # => https://httpbingo.org/api/nigiri?token=abc&page=2
     #
     def build_url(url = nil, extra_params = nil)
       uri = build_exclusive_url(url)
@@ -470,10 +422,10 @@ module Faraday
     # Builds and runs the Faraday::Request.
     #
     # @param method [Symbol] HTTP method.
-    # @param url [String, URI] String or URI to access.
-    # @param body [Object] The request body that will eventually be converted to
+    # @param url [String, URI, nil] String or URI to access.
+    # @param body [String, nil] The request body that will eventually be converted to
     #             a string.
-    # @param headers [Hash] unencoded HTTP header key/value pairs.
+    # @param headers [Hash, nil] unencoded HTTP header key/value pairs.
     #
     # @return [Faraday::Response]
     def run_request(method, url, body, headers)
@@ -509,7 +461,7 @@ module Faraday
 
     # Build an absolute URL based on url_prefix.
     #
-    # @param url [String, URI]
+    # @param url [String, URI, nil]
     # @param params [Faraday::Utils::ParamsHash] A Faraday::Utils::ParamsHash to
     #               replace the query values
     #          of the resulting url (default: nil).
@@ -517,18 +469,16 @@ module Faraday
     # @return [URI]
     def build_exclusive_url(url = nil, params = nil, params_encoder = nil)
       url = nil if url.respond_to?(:empty?) && url.empty?
-      base = url_prefix
-      if url && base.path && base.path !~ %r{/$}
-        base = base.dup
-        base.path = base.path + '/' # ensure trailing slash
+      base = url_prefix.dup
+      if url && !base.path.end_with?('/')
+        base.path = "#{base.path}/" # ensure trailing slash
       end
+      url = url.to_s.gsub(':', '%3A') if URI.parse(url.to_s).opaque
       uri = url ? base + url : base
       if params
         uri.query = params.to_query(params_encoder || options.params_encoder)
       end
-      # rubocop:disable Style/SafeNavigation
       uri.query = nil if uri.query && uri.query.empty?
-      # rubocop:enable Style/SafeNavigation
       uri
     end
 
@@ -560,40 +510,31 @@ module Faraday
       yield(Utils.unescape(uri.user), Utils.unescape(uri.password))
     end
 
-    def set_authorization_header(header_type, *args)
-      header = Faraday::Request
-               .lookup_middleware(header_type)
-               .header(*args)
-
-      headers[Faraday::Request::Authorization::KEY] = header
-    end
-
     def proxy_from_env(url)
       return if Faraday.ignore_env_proxy
 
       uri = nil
-      if URI.parse('').respond_to?(:find_proxy)
-        case url
-        when String
-          uri = Utils.URI(url)
-          uri = URI.parse("#{uri.scheme}://#{uri.hostname}").find_proxy
-        when URI
-          uri = url.find_proxy
-        when nil
-          uri = find_default_proxy
-        end
-      else
-        warn 'no_proxy is unsupported' if ENV['no_proxy'] || ENV['NO_PROXY']
+      case url
+      when String
+        uri = Utils.URI(url)
+        uri = if uri.host.nil?
+                find_default_proxy
+              else
+                URI.parse("#{uri.scheme}://#{uri.host}").find_proxy
+              end
+      when URI
+        uri = url.find_proxy
+      when nil
         uri = find_default_proxy
       end
       ProxyOptions.from(uri) if uri
     end
 
     def find_default_proxy
-      uri = ENV['http_proxy']
+      uri = ENV.fetch('http_proxy', nil)
       return unless uri && !uri.empty?
 
-      uri = 'http://' + uri if uri !~ /^http/i
+      uri = "http://#{uri}" unless uri.match?(/^http/i)
       uri
     end
 
@@ -608,7 +549,7 @@ module Faraday
     end
 
     def support_parallel?(adapter)
-      adapter&.respond_to?(:supports_parallel?) && adapter&.supports_parallel?
+      adapter.respond_to?(:supports_parallel?) && adapter&.supports_parallel?
     end
   end
 end

data/lib/faraday/encoders/flat_params_encoder.rb

@@ -33,9 +33,9 @@ module Faraday
           key = key.to_s if key.is_a?(Symbol)
           [key, value]
         end
-        # Useful default for OAuth and caching.
+
         # Only to be used for non-Array inputs. Arrays should preserve order.
-        params.sort!
+        params.sort! if @sort_params
       end
 
       # The params have form [['key1', 'value1'], ['key2', 'value2']].
@@ -94,5 +94,12 @@ module Faraday
         end
       end
     end
+
+    class << self
+      attr_accessor :sort_params
+    end
+
+    # Useful default for OAuth and caching.
+    @sort_params = true
   end
 end

data/lib/faraday/encoders/nested_params_encoder.rb

@@ -21,9 +21,9 @@ module Faraday
           key = key.to_s if key.is_a?(Symbol)
           [key, value]
         end
-        # Useful default for OAuth and caching.
+
         # Only to be used for non-Array inputs. Arrays should preserve order.
-        params.sort!
+        params.sort! if @sort_params
       end
 
       # The params have form [['key1', 'value1'], ['key2', 'value2']].
@@ -62,11 +62,17 @@ module Faraday
     end
 
     def encode_array(parent, value)
-      new_parent = "#{parent}%5B%5D"
-      return new_parent if value.empty?
+      return "#{parent}%5B%5D" if value.empty?
 
       buffer = +''
-      value.each { |val| buffer << "#{encode_pair(new_parent, val)}&" }
+      value.each_with_index do |val, index|
+        new_parent = if @array_indices
+                       "#{parent}%5B#{index}%5D"
+                     else
+                       "#{parent}%5B%5D"
+                     end
+        buffer << "#{encode_pair(new_parent, val)}&"
+      end
       buffer.chop
     end
   end
@@ -96,13 +102,13 @@ module Faraday
 
     protected
 
-    SUBKEYS_REGEX = /[^\[\]]+(?:\]?\[\])?/.freeze
+    SUBKEYS_REGEX = /[^\[\]]+(?:\]?\[\])?/
 
     def decode_pair(key, value, context)
       subkeys = key.scan(SUBKEYS_REGEX)
       subkeys.each_with_index do |subkey, i|
         is_array = subkey =~ /[\[\]]+\Z/
-        subkey = $` if is_array
+        subkey = Regexp.last_match.pre_match if is_array
         last_subkey = i == subkeys.length - 1
 
         context = prepare_context(context, subkey, is_array, last_subkey)
@@ -124,7 +130,7 @@ module Faraday
       value_type = is_array ? Array : Hash
       if context[subkey] && !context[subkey].is_a?(value_type)
         raise TypeError, "expected #{value_type.name} " \
-          "(got #{context[subkey].class.name}) for param `#{subkey}'"
+                         "(got #{context[subkey].class.name}) for param `#{subkey}'"
       end
 
       context[subkey] ||= value_type.new
@@ -161,10 +167,16 @@ module Faraday
   # for your requests.
   module NestedParamsEncoder
     class << self
+      attr_accessor :sort_params, :array_indices
+
       extend Forwardable
       def_delegators :'Faraday::Utils', :escape, :unescape
     end
 
+    # Useful default for OAuth and caching.
+    @sort_params = true
+    @array_indices = false
+
     extend EncodeMethods
     extend DecodeMethods
   end

data/lib/faraday/error.rb

@@ -6,7 +6,7 @@ module Faraday
   class Error < StandardError
     attr_reader :response, :wrapped_exception
 
-    def initialize(exc, response = nil)
+    def initialize(exc = nil, response = nil)
       @wrapped_exception = nil unless defined?(@wrapped_exception)
       @response = nil unless defined?(@response)
       super(exc_msg_and_response!(exc, response))
@@ -28,6 +28,24 @@ module Faraday
       %(#<#{self.class}#{inner}>)
     end
 
+    def response_status
+      return unless @response
+
+      @response.is_a?(Faraday::Response) ? @response.status : @response[:status]
+    end
+
+    def response_headers
+      return unless @response
+
+      @response.is_a?(Faraday::Response) ? @response.headers : @response[:headers]
+    end
+
+    def response_body
+      return unless @response
+
+      @response.is_a?(Faraday::Response) ? @response.body : @response[:body]
+    end
+
     protected
 
     # Pulls out potential parent exception and response hash, storing them in
@@ -38,6 +56,15 @@ module Faraday
     #              :headers - String key/value hash of HTTP response header
     #                         values.
     #              :body    - Optional string HTTP response body.
+    #              :request - Hash
+    #                           :method   - Symbol with the request HTTP method.
+    #                           :url      - URI object with the url requested.
+    #                           :url_path - String with the url path requested.
+    #                           :params   - String key/value hash of query params
+    #                                     present in the request.
+    #                           :headers  - String key/value hash of HTTP request
+    #                                     header values.
+    #                           :body     - String HTTP request body.
     #
     # If a subclass has to call this, then it should pass a string message
     # to `super`. See NilStatusError.
@@ -85,6 +112,10 @@ module Faraday
   class ProxyAuthError < ClientError
   end
 
+  # Raised by Faraday::Response::RaiseError in case of a 408 response.
+  class RequestTimeoutError < ClientError
+  end
+
   # Raised by Faraday::Response::RaiseError in case of a 409 response.
   class ConflictError < ClientError
   end
@@ -93,6 +124,10 @@ module Faraday
   class UnprocessableEntityError < ClientError
   end
 
+  # Raised by Faraday::Response::RaiseError in case of a 429 response.
+  class TooManyRequestsError < ClientError
+  end
+
   # Faraday server error class. Represents 5xx status responses.
   class ServerError < Error
   end
@@ -120,13 +155,7 @@ module Faraday
   class SSLError < Error
   end
 
-  # Raised by FaradayMiddleware::ResponseMiddleware
+  # Raised by middlewares that parse the response, like the JSON response middleware.
   class ParsingError < Error
   end
-
-  # Exception used to control the Retry middleware.
-  #
-  # @see Faraday::Request::Retry
-  class RetriableResponse < Error
-  end
 end