faraday 0.16.0 → 0.17.0

data/lib/faraday/utils.rb

@@ -1,12 +1,193 @@
-# frozen_string_literal: true
-
-require 'faraday/utils/headers'
-require 'faraday/utils/params_hash'
+require 'thread'
 
 module Faraday
-  # Utils contains various static helper methods.
   module Utils
-    module_function
+    extend self
+
+    # Adapted from Rack::Utils::HeaderHash
+    class Headers < ::Hash
+      def self.from(value)
+        new(value)
+      end
+
+      def self.allocate
+        new_self = super
+        new_self.initialize_names
+        new_self
+      end
+
+      def initialize(hash = nil)
+        super()
+        @names = {}
+        self.update(hash || {})
+      end
+
+      def initialize_names
+        @names = {}
+      end
+
+      # on dup/clone, we need to duplicate @names hash
+      def initialize_copy(other)
+        super
+        @names = other.names.dup
+      end
+
+      # need to synchronize concurrent writes to the shared KeyMap
+      keymap_mutex = Mutex.new
+
+      # symbol -> string mapper + cache
+      KeyMap = Hash.new do |map, key|
+        value = if key.respond_to?(:to_str)
+          key
+        else
+          key.to_s.split('_').            # :user_agent => %w(user agent)
+            each { |w| w.capitalize! }.   # => %w(User Agent)
+            join('-')                     # => "User-Agent"
+        end
+        keymap_mutex.synchronize { map[key] = value }
+      end
+      KeyMap[:etag] = "ETag"
+
+      def [](k)
+        k = KeyMap[k]
+        super(k) || super(@names[k.downcase])
+      end
+
+      def []=(k, v)
+        k = KeyMap[k]
+        k = (@names[k.downcase] ||= k)
+        # join multiple values with a comma
+        v = v.to_ary.join(', ') if v.respond_to? :to_ary
+        super(k, v)
+      end
+
+      def fetch(k, *args, &block)
+        k = KeyMap[k]
+        key = @names.fetch(k.downcase, k)
+        super(key, *args, &block)
+      end
+
+      def delete(k)
+        k = KeyMap[k]
+        if k = @names[k.downcase]
+          @names.delete k.downcase
+          super(k)
+        end
+      end
+
+      def include?(k)
+        @names.include? k.downcase
+      end
+
+      alias_method :has_key?, :include?
+      alias_method :member?, :include?
+      alias_method :key?, :include?
+
+      def merge!(other)
+        other.each { |k, v| self[k] = v }
+        self
+      end
+      alias_method :update, :merge!
+
+      def merge(other)
+        hash = dup
+        hash.merge! other
+      end
+
+      def replace(other)
+        clear
+        @names.clear
+        self.update other
+        self
+      end
+
+      def to_hash() ::Hash.new.update(self) end
+
+      def parse(header_string)
+        return unless header_string && !header_string.empty?
+
+        headers = header_string.split(/\r\n/)
+
+        # Find the last set of response headers.
+        start_index = headers.rindex { |x| x.match(/^HTTP\//) } || 0
+        last_response = headers.slice(start_index, headers.size)
+
+        last_response.
+          tap  { |a| a.shift if a.first.index('HTTP/') == 0 }. # drop the HTTP status line
+          map  { |h| h.split(/:\s*/, 2) }.reject { |p| p[0].nil? }. # split key and value, ignore blank lines
+          each { |key, value|
+            # join multiple values with a comma
+            if self[key]
+              self[key] << ', ' << value
+            else
+              self[key] = value
+            end
+          }
+      end
+
+      protected
+
+      def names
+        @names
+      end
+    end
+
+    # hash with stringified keys
+    class ParamsHash < Hash
+      def [](key)
+        super(convert_key(key))
+      end
+
+      def []=(key, value)
+        super(convert_key(key), value)
+      end
+
+      def delete(key)
+        super(convert_key(key))
+      end
+
+      def include?(key)
+        super(convert_key(key))
+      end
+
+      alias_method :has_key?, :include?
+      alias_method :member?, :include?
+      alias_method :key?, :include?
+
+      def update(params)
+        params.each do |key, value|
+          self[key] = value
+        end
+        self
+      end
+      alias_method :merge!, :update
+
+      def merge(params)
+        dup.update(params)
+      end
+
+      def replace(other)
+        clear
+        update(other)
+      end
+
+      def merge_query(query, encoder = nil)
+        if query && !query.empty?
+          update((encoder || Utils.default_params_encoder).decode(query))
+        end
+        self
+      end
+
+      def to_query(encoder = nil)
+        (encoder || Utils.default_params_encoder).encode(self)
+      end
+
+      private
+
+      def convert_key(key)
+        key.to_s
+      end
+    end
 
     def build_query(params)
       FlatParamsEncoder.encode(params)
@@ -16,19 +197,17 @@ module Faraday
       NestedParamsEncoder.encode(params)
     end
 
-    ESCAPE_RE = /[^a-zA-Z0-9 .~_-]/.freeze
+    ESCAPE_RE = /[^a-zA-Z0-9 .~_-]/
 
-    def escape(str)
-      str.to_s.gsub(ESCAPE_RE) do |match|
+    def escape(s)
+      s.to_s.gsub(ESCAPE_RE) {|match|
         '%' + match.unpack('H2' * match.bytesize).join('%').upcase
-      end.tr(' ', '+')
+      }.tr(' ', '+')
     end
 
-    def unescape(str)
-      CGI.unescape str.to_s
-    end
+    def unescape(s) CGI.unescape s.to_s end
 
-    DEFAULT_SEP = /[&;] */n.freeze
+    DEFAULT_SEP = /[&;] */n
 
     # Adapted from Rack
     def parse_query(query)
@@ -47,18 +226,55 @@ module Faraday
       attr_writer :default_params_encoder
     end
 
+    # Stolen from Rack
+    def normalize_params(params, name, v = nil)
+      name =~ %r(\A[\[\]]*([^\[\]]+)\]*)
+      k = $1 || ''
+      after = $' || ''
+
+      return if k.empty?
+
+      if after == ""
+        if params[k]
+          params[k] = Array[params[k]] unless params[k].kind_of?(Array)
+          params[k] << v
+        else
+          params[k] = v
+        end
+      elsif after == "[]"
+        params[k] ||= []
+        raise TypeError, "expected Array (got #{params[k].class.name}) for param `#{k}'" unless params[k].is_a?(Array)
+        params[k] << v
+      elsif after =~ %r(^\[\]\[([^\[\]]+)\]$) || after =~ %r(^\[\](.+)$)
+        child_key = $1
+        params[k] ||= []
+        raise TypeError, "expected Array (got #{params[k].class.name}) for param `#{k}'" unless params[k].is_a?(Array)
+        if params[k].last.is_a?(Hash) && !params[k].last.key?(child_key)
+          normalize_params(params[k].last, child_key, v)
+        else
+          params[k] << normalize_params({}, child_key, v)
+        end
+      else
+        params[k] ||= {}
+        raise TypeError, "expected Hash (got #{params[k].class.name}) for param `#{k}'" unless params[k].is_a?(Hash)
+        params[k] = normalize_params(params[k], after, v)
+      end
+
+      return params
+    end
+
     # Normalize URI() behavior across Ruby versions
     #
     # url - A String or URI.
     #
     # Returns a parsed URI.
-    def URI(url) # rubocop:disable Naming/MethodName
+    def URI(url)
       if url.respond_to?(:host)
         url
       elsif url.respond_to?(:to_str)
         default_uri_parser.call(url)
       else
-        raise ArgumentError, 'bad argument (expected URI object or URI string)'
+        raise ArgumentError, "bad argument (expected URI object or URI string)"
       end
     end
 
@@ -71,28 +287,27 @@ module Faraday
 
     def default_uri_parser=(parser)
       @default_uri_parser = if parser.respond_to?(:call) || parser.nil?
-                              parser
-                            else
-                              parser.method(:parse)
-                            end
+        parser
+      else
+        parser.method(:parse)
+      end
     end
 
-    # Receives a String or URI and returns just
-    # the path with the query string sorted.
+    # Receives a String or URI and returns just the path with the query string sorted.
     def normalize_path(url)
       url = URI(url)
       (url.path.start_with?('/') ? url.path : '/' + url.path) +
-        (url.query ? "?#{sort_query_params(url.query)}" : '')
+      (url.query ? "?#{sort_query_params(url.query)}" : "")
     end
 
     # Recursive hash update
     def deep_merge!(target, hash)
       hash.each do |key, value|
-        target[key] = if value.is_a?(Hash) && target[key].is_a?(Hash)
-                        deep_merge(target[key], value)
-                      else
-                        value
-                      end
+        if Hash === value and Hash === target[key]
+          target[key] = deep_merge(target[key], value)
+        else
+          target[key] = value
+        end
       end
       target
     end
@@ -102,6 +317,8 @@ module Faraday
       deep_merge!(source.dup, hash)
     end
 
+    protected
+
     def sort_query_params(query)
       query.split('&').sort.join('&')
     end

data/lib/faraday.rb

@@ -1,153 +1,129 @@
-# frozen_string_literal: true
-
+require 'thread'
 require 'cgi'
 require 'set'
 require 'forwardable'
-require 'faraday/middleware_registry'
-require 'faraday/dependency_loader'
 
-# This is the main namespace for Faraday.
+# Public: This is the main namespace for Faraday.  You can either use it to
+# create Faraday::Connection objects, or access it directly.
 #
-# It provides methods to create {Connection} objects, and HTTP-related
-# methods to use directly.
+# Examples
 #
-# @example Helpful class methods for easy usage
 #   Faraday.get "http://faraday.com"
 #
-# @example Helpful class method `.new` to create {Connection} objects.
 #   conn = Faraday.new "http://faraday.com"
 #   conn.get '/'
 #
 module Faraday
-  VERSION = '0.16.0'
-  METHODS_WITH_QUERY = %w[get head delete connect trace].freeze
-  METHODS_WITH_BODY = %w[post put patch].freeze
+  VERSION = "0.17.0"
 
   class << self
-    # The root path that Faraday is being loaded from.
-    #
-    # This is the root from where the libraries are auto-loaded.
-    #
-    # @return [String]
+    # Public: Gets or sets the root path that Faraday is being loaded from.
+    # This is the root from where the libraries are auto-loaded from.
     attr_accessor :root_path
 
-    # Gets or sets the path that the Faraday libs are loaded from.
-    # @return [String]
+    # Public: Gets or sets the path that the Faraday libs are loaded from.
     attr_accessor :lib_path
 
-    # @overload default_adapter
-    #   Gets the Symbol key identifying a default Adapter to use
-    #   for the default {Faraday::Connection}. Defaults to `:net_http`.
-    #   @return [Symbol] the default adapter
-    # @overload default_adapter=(adapter)
-    #   Updates default adapter while resetting {.default_connection}.
-    #   @return [Symbol] the new default_adapter.
+    # Public: Gets or sets the Symbol key identifying a default Adapter to use
+    # for the default Faraday::Connection.
     attr_reader :default_adapter
 
-    # Documented below, see default_connection
+    # Public: Sets the default Faraday::Connection for simple scripts that
+    # access the Faraday constant directly.
+    #
+    #     Faraday.get "https://faraday.com"
     attr_writer :default_connection
 
-    # Tells Faraday to ignore the environment proxy (http_proxy).
-    # Defaults to `false`.
-    # @return [Boolean]
+    # Public: Tells faraday to ignore the environment proxy (http_proxy).
     attr_accessor :ignore_env_proxy
 
-    # Initializes a new {Connection}.
-    #
-    # @param url [String,Hash] The optional String base URL to use as a prefix
-    #           for all requests.  Can also be the options Hash. Any of these
-    #           values will be set on every request made, unless overridden
-    #           for a specific request.
-    # @param options [Hash]
-    # @option options [String] :url Base URL
-    # @option options [Hash] :params Hash of unencoded URI query params.
-    # @option options [Hash] :headers Hash of unencoded HTTP headers.
-    # @option options [Hash] :request Hash of request options.
-    # @option options [Hash] :ssl Hash of SSL options.
-    # @option options [Hash] :proxy Hash of Proxy options.
-    # @return [Faraday::Connection]
-    #
-    # @example With an URL argument
+    # Public: Initializes a new Faraday::Connection.
+    #
+    # url     - The optional String base URL to use as a prefix for all
+    #           requests.  Can also be the options Hash.
+    # options - The optional Hash used to configure this Faraday::Connection.
+    #           Any of these values will be set on every request made, unless
+    #           overridden for a specific request.
+    #           :url     - String base URL.
+    #           :params  - Hash of URI query unencoded key/value pairs.
+    #           :headers - Hash of unencoded HTTP header key/value pairs.
+    #           :request - Hash of request options.
+    #           :ssl     - Hash of SSL options.
+    #           :proxy   - Hash of Proxy options.
+    #
+    # Examples
+    #
     #   Faraday.new 'http://faraday.com'
-    #   # => Faraday::Connection to http://faraday.com
-    #
-    # @example With an URL argument and an options hash
-    #   Faraday.new 'http://faraday.com', params: { page: 1 }
-    #   # => Faraday::Connection to http://faraday.com?page=1
-    #
-    # @example With everything in an options hash
-    #   Faraday.new url: 'http://faraday.com',
-    #               params: { page: 1 }
-    #   # => Faraday::Connection to http://faraday.com?page=1
-    def new(url = nil, options = {}, &block)
-      options = default_connection_options.merge(options)
+    #
+    #   # http://faraday.com?page=1
+    #   Faraday.new 'http://faraday.com', :params => {:page => 1}
+    #
+    #   # same
+    #
+    #   Faraday.new :url => 'http://faraday.com',
+    #     :params => {:page => 1}
+    #
+    # Returns a Faraday::Connection.
+    def new(url = nil, options = nil)
+      block = block_given? ? Proc.new : nil
+      options = options ? default_connection_options.merge(options) : default_connection_options
       Faraday::Connection.new(url, options, &block)
     end
 
-    # @private
     # Internal: Requires internal Faraday libraries.
     #
-    # @param libs [Array] one or more relative String names to Faraday classes.
-    # @return [void]
+    # *libs - One or more relative String names to Faraday classes.
+    #
+    # Returns nothing.
     def require_libs(*libs)
       libs.each do |lib|
         require "#{lib_path}/#{lib}"
       end
     end
 
-    alias require_lib require_libs
-
-    # Documented elsewhere, see default_adapter reader
+    # Public: Updates default adapter while resetting
+    # #default_connection.
+    #
+    # Returns the new default_adapter.
     def default_adapter=(adapter)
       @default_connection = nil
       @default_adapter = adapter
     end
 
-    def respond_to_missing?(symbol, include_private = false)
+    alias require_lib require_libs
+
+    def respond_to?(symbol, include_private = false)
       default_connection.respond_to?(symbol, include_private) || super
     end
 
-    private
-
+  private
     # Internal: Proxies method calls on the Faraday constant to
-    # .default_connection.
+    # #default_connection.
     def method_missing(name, *args, &block)
-      if default_connection.respond_to?(name)
-        default_connection.send(name, *args, &block)
-      else
-        super
-      end
+      default_connection.send(name, *args, &block)
     end
   end
 
   self.ignore_env_proxy = false
-  self.root_path = File.expand_path __dir__
-  self.lib_path = File.expand_path 'faraday', __dir__
+  self.root_path = File.expand_path "..", __FILE__
+  self.lib_path = File.expand_path "../faraday", __FILE__
   self.default_adapter = :net_http
 
-  # @overload default_connection
-  #   Gets the default connection used for simple scripts.
-  #   @return [Faraday::Connection] a connection configured with
-  #   the default_adapter.
-  # @overload default_connection=(connection)
-  #   @param connection [Faraday::Connection]
-  #   Sets the default {Faraday::Connection} for simple scripts that
-  #   access the Faraday constant directly, such as
-  #   <code>Faraday.get "https://faraday.com"</code>.
+  # Gets the default connection used for simple scripts.
+  #
+  # Returns a Faraday::Connection, configured with the #default_adapter.
   def self.default_connection
     @default_connection ||= Connection.new(default_connection_options)
   end
 
-  # Gets the default connection options used when calling {Faraday#new}.
+  # Gets the default connection options used when calling Faraday#new.
   #
-  # @return [Faraday::ConnectionOptions]
+  # Returns a Faraday::ConnectionOptions.
   def self.default_connection_options
     @default_connection_options ||= ConnectionOptions.new
   end
 
-  # Sets the default options used when calling {Faraday#new}.
-  #
-  # @param options [Hash, Faraday::ConnectionOptions]
+  # Public: Sets the default options used when calling Faraday#new.
   def self.default_connection_options=(options)
     @default_connection = nil
     @default_connection_options = ConnectionOptions.from(options)
@@ -158,9 +134,115 @@ module Faraday
     Timer = Timeout
   end
 
-  require_libs 'utils', 'options', 'connection', 'rack_builder', 'parameters',
-               'middleware', 'adapter', 'request', 'response', 'error',
-               'file_part', 'param_part'
+  # Public: Adds the ability for other modules to register and lookup
+  # middleware classes.
+  module MiddlewareRegistry
+    # Public: Register middleware class(es) on the current module.
+    #
+    # mapping - A Hash mapping Symbol keys to classes. Classes can be expressed
+    #           as fully qualified constant, or a Proc that will be lazily
+    #           called to return the former.
+    #
+    # Examples
+    #
+    #   module Faraday
+    #     class Whatever
+    #       # Middleware looked up by :foo returns Faraday::Whatever::Foo.
+    #       register_middleware :foo => Foo
+    #
+    #       # Middleware looked up by :bar returns Faraday::Whatever.const_get(:Bar)
+    #       register_middleware :bar => :Bar
+    #
+    #       # Middleware looked up by :baz requires 'baz' and returns Faraday::Whatever.const_get(:Baz)
+    #       register_middleware :baz => [:Baz, 'baz']
+    #     end
+    #   end
+    #
+    # Returns nothing.
+    def register_middleware(autoload_path = nil, mapping = nil)
+      if mapping.nil?
+        mapping = autoload_path
+        autoload_path = nil
+      end
+      middleware_mutex do
+        @middleware_autoload_path = autoload_path if autoload_path
+        (@registered_middleware ||= {}).update(mapping)
+      end
+    end
 
-  require_lib 'autoload' unless ENV['FARADAY_NO_AUTOLOAD']
+    # Public: Lookup middleware class with a registered Symbol shortcut.
+    #
+    # key - The Symbol key for the registered middleware.
+    #
+    # Examples
+    #
+    #   module Faraday
+    #     class Whatever
+    #       register_middleware :foo => Foo
+    #     end
+    #   end
+    #
+    #   Faraday::Whatever.lookup_middleware(:foo)
+    #   # => Faraday::Whatever::Foo
+    #
+    # Returns a middleware Class.
+    def lookup_middleware(key)
+      load_middleware(key) ||
+        raise(Faraday::Error.new("#{key.inspect} is not registered on #{self}"))
+    end
+
+    def middleware_mutex(&block)
+      @middleware_mutex ||= begin
+        require 'monitor'
+        Monitor.new
+      end
+      @middleware_mutex.synchronize(&block)
+    end
+
+    def fetch_middleware(key)
+      defined?(@registered_middleware) && @registered_middleware[key]
+    end
+
+    def load_middleware(key)
+      value = fetch_middleware(key)
+      case value
+      when Module
+        value
+      when Symbol, String
+        middleware_mutex do
+          @registered_middleware[key] = const_get(value)
+        end
+      when Proc
+        middleware_mutex do
+          @registered_middleware[key] = value.call
+        end
+      when Array
+        middleware_mutex do
+          const, path = value
+          if root = @middleware_autoload_path
+            path = "#{root}/#{path}"
+          end
+          require(path)
+          @registered_middleware[key] = const
+        end
+        load_middleware(key)
+      end
+    end
+  end
+
+  def self.const_missing(name)
+    if name.to_sym == :Builder
+      warn "Faraday::Builder is now Faraday::RackBuilder."
+      const_set name, RackBuilder
+    else
+      super
+    end
+  end
+
+  require_libs "utils", "options", "connection", "rack_builder", "parameters",
+    "middleware", "adapter", "request", "response", "upload_io", "error"
+
+  if !ENV["FARADAY_NO_AUTOLOAD"]
+    require_lib 'autoload'
+  end
 end