faraday 0.7.4 → 1.0.1

data/lib/faraday/middleware.rb

@@ -1,29 +1,21 @@
+# frozen_string_literal: true
+
 module Faraday
+  # Middleware is the basic base class of any Faraday middleware.
   class Middleware
-    class << self
-      attr_accessor :load_error, :supports_parallel_requests
-      alias supports_parallel_requests? supports_parallel_requests
-
-      # valid parallel managers should respond to #run with no parameters.
-      # otherwise, return a short wrapper around it.
-      def setup_parallel_manager(options = {})
-        nil
-      end
-    end
-
-    # Executes a block which should try to require and reference dependent libraries
-    def self.dependency(lib = nil)
-      lib ? require(lib) : yield
-    rescue LoadError, NameError => error
-      self.load_error = error
-    end
-
-    def self.loaded?
-      @load_error.nil?
-    end
+    extend MiddlewareRegistry
+    extend DependencyLoader
 
     def initialize(app = nil)
       @app = app
     end
+
+    def close
+      if @app.respond_to?(:close)
+        @app.close
+      else
+        warn "#{@app} does not implement \#close!"
+      end
+    end
   end
-end
+end

data/lib/faraday/middleware_registry.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require 'monitor'
+
+module Faraday
+  # Adds the ability for other modules to register and lookup
+  # middleware classes.
+  module MiddlewareRegistry
+    # Register middleware class(es) on the current module.
+    #
+    # @param autoload_path [String] Middleware autoload path
+    # @param mapping [Hash{
+    #          Symbol => Module,
+    #          Symbol => Array<Module, Symbol, String>,
+    #        }] Middleware mapping from a lookup symbol to a reference to the
+    #        middleware.
+    #        Classes can be expressed as:
+    #          - a fully qualified constant
+    #          - a Symbol
+    #          - a Proc that will be lazily called to return the former
+    #          - an array is given, its first element is the constant or symbol,
+    #            and its second is a file to `require`.
+    # @return [void]
+    #
+    # @example Lookup by a constant
+    #
+    #   module Faraday
+    #     class Whatever
+    #       # Middleware looked up by :foo returns Faraday::Whatever::Foo.
+    #       register_middleware foo: Foo
+    #     end
+    #   end
+    #
+    # @example Lookup by a symbol
+    #
+    #   module Faraday
+    #     class Whatever
+    #       # Middleware looked up by :bar returns
+    #       # Faraday::Whatever.const_get(:Bar)
+    #       register_middleware bar: :Bar
+    #     end
+    #   end
+    #
+    # @example Lookup by a symbol and string in an array
+    #
+    #   module Faraday
+    #     class Whatever
+    #       # Middleware looked up by :baz requires 'baz' and returns
+    #       # Faraday::Whatever.const_get(:Baz)
+    #       register_middleware baz: [:Baz, 'baz']
+    #     end
+    #   end
+    #
+    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
+
+    # Unregister a previously registered middleware class.
+    #
+    # @param key [Symbol] key for the registered middleware.
+    def unregister_middleware(key)
+      @registered_middleware.delete(key)
+    end
+
+    # Lookup middleware class with a registered Symbol shortcut.
+    #
+    # @param key [Symbol] key for the registered middleware.
+    # @return [Class] a middleware Class.
+    # @raise [Faraday::Error] if given key is not registered
+    #
+    # @example
+    #
+    #   module Faraday
+    #     class Whatever
+    #       register_middleware foo: Foo
+    #     end
+    #   end
+    #
+    #   Faraday::Whatever.lookup_middleware(:foo)
+    #   # => Faraday::Whatever::Foo
+    #
+    def lookup_middleware(key)
+      load_middleware(key) ||
+        raise(Faraday::Error, "#{key.inspect} is not registered on #{self}")
+    end
+
+    def middleware_mutex(&block)
+      @middleware_mutex ||= Monitor.new
+      @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
+end

data/lib/faraday/options/connection_options.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Faraday
+  # ConnectionOptions contains the configurable properties for a Faraday
+  # connection object.
+  class ConnectionOptions < Options.new(:request, :proxy, :ssl, :builder, :url,
+                                        :parallel_manager, :params, :headers,
+                                        :builder_class)
+
+    options request: RequestOptions, ssl: SSLOptions
+
+    memoized(:request) { self.class.options_for(:request).new }
+
+    memoized(:ssl) { self.class.options_for(:ssl).new }
+
+    memoized(:builder_class) { RackBuilder }
+
+    def new_builder(block)
+      builder_class.new(&block)
+    end
+  end
+end

data/lib/faraday/options/env.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+module Faraday
+  # @!attribute method
+  #   @return [Symbol] HTTP method (`:get`, `:post`)
+  #
+  # @!attribute body
+  #   @return [String] The request body that will eventually be converted to a
+  #   string.
+  #
+  # @!attribute url
+  #   @return [URI] URI instance for the current request.
+  #
+  # @!attribute request
+  #   @return [Hash] options for configuring the request.
+  #   Options for configuring the request.
+  #
+  #   - `:timeout`  open/read timeout Integer in seconds
+  #   - `:open_timeout` - read timeout Integer in seconds
+  #   - `:on_data`      - Proc for streaming
+  #   - `:proxy`        - Hash of proxy options
+  #       - `:uri`        - Proxy Server URI
+  #       - `:user`       - Proxy server username
+  #       - `:password`   - Proxy server password
+  #
+  # @!attribute request_headers
+  #   @return [Hash] HTTP Headers to be sent to the server.
+  #
+  # @!attribute ssl
+  #   @return [Hash] options for configuring SSL requests
+  #
+  # @!attribute parallel_manager
+  #   @return [Object] sent if the connection is in parallel mode
+  #
+  # @!attribute params
+  #   @return [Hash]
+  #
+  # @!attribute response
+  #   @return [Response]
+  #
+  # @!attribute response_headers
+  #   @return [Hash] HTTP headers from the server
+  #
+  # @!attribute status
+  #   @return [Integer] HTTP response status code
+  #
+  # @!attribute reason_phrase
+  #   @return [String]
+  class Env < Options.new(:method, :request_body, :url, :request,
+                          :request_headers, :ssl, :parallel_manager, :params,
+                          :response, :response_headers, :status,
+                          :reason_phrase, :response_body)
+
+    # rubocop:disable Naming/ConstantName
+    ContentLength = 'Content-Length'
+    StatusesWithoutBody = Set.new [204, 304]
+    SuccessfulStatuses = (200..299).freeze
+    # rubocop:enable Naming/ConstantName
+
+    # A Set of HTTP verbs that typically send a body.  If no body is set for
+    # these requests, the Content-Length header is set to 0.
+    MethodsWithBodies = Set.new(Faraday::METHODS_WITH_BODY.map(&:to_sym))
+
+    options request: RequestOptions,
+            request_headers: Utils::Headers, response_headers: Utils::Headers
+
+    extend Forwardable
+
+    def_delegators :request, :params_encoder
+
+    # Build a new Env from given value. Respects and updates `custom_members`.
+    #
+    # @param value [Object] a value fitting Option.from(v).
+    # @return [Env] from given value
+    def self.from(value)
+      env = super(value)
+      if value.respond_to?(:custom_members)
+        env.custom_members.update(value.custom_members)
+      end
+      env
+    end
+
+    # @param key [Object]
+    def [](key)
+      return self[current_body] if key == :body
+
+      if in_member_set?(key)
+        super(key)
+      else
+        custom_members[key]
+      end
+    end
+
+    # @param key [Object]
+    # @param value [Object]
+    def []=(key, value)
+      if key == :body
+        super(current_body, value)
+        return
+      end
+
+      if in_member_set?(key)
+        super(key, value)
+      else
+        custom_members[key] = value
+      end
+    end
+
+    def current_body
+      !!status ? :response_body : :request_body
+    end
+
+    def body
+      self[:body]
+    end
+
+    def body=(value)
+      self[:body] = value
+    end
+
+    # @return [Boolean] true if status is in the set of {SuccessfulStatuses}.
+    def success?
+      SuccessfulStatuses.include?(status)
+    end
+
+    # @return [Boolean] true if there's no body yet, and the method is in the
+    # set of {MethodsWithBodies}.
+    def needs_body?
+      !body && MethodsWithBodies.include?(method)
+    end
+
+    # Sets content length to zero and the body to the empty string.
+    def clear_body
+      request_headers[ContentLength] = '0'
+      self.body = +''
+    end
+
+    # @return [Boolean] true if the status isn't in the set of
+    # {StatusesWithoutBody}.
+    def parse_body?
+      !StatusesWithoutBody.include?(status)
+    end
+
+    # @return [Boolean] true if there is a parallel_manager
+    def parallel?
+      !!parallel_manager
+    end
+
+    def inspect
+      attrs = [nil]
+      members.each do |mem|
+        if (value = send(mem))
+          attrs << "@#{mem}=#{value.inspect}"
+        end
+      end
+      attrs << "@custom=#{custom_members.inspect}" unless custom_members.empty?
+      %(#<#{self.class}#{attrs.join(' ')}>)
+    end
+
+    # @private
+    def custom_members
+      @custom_members ||= {}
+    end
+
+    # @private
+    if members.first.is_a?(Symbol)
+      def in_member_set?(key)
+        self.class.member_set.include?(key.to_sym)
+      end
+    else
+      def in_member_set?(key)
+        self.class.member_set.include?(key.to_s)
+      end
+    end
+
+    # @private
+    def self.member_set
+      @member_set ||= Set.new(members)
+    end
+  end
+end

data/lib/faraday/options/proxy_options.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Faraday
+  # ProxyOptions contains the configurable properties for the proxy
+  # configuration used when making an HTTP request.
+  class ProxyOptions < Options.new(:uri, :user, :password)
+    extend Forwardable
+    def_delegators :uri, :scheme, :scheme=, :host, :host=, :port, :port=,
+                   :path, :path=
+
+    def self.from(value)
+      case value
+      when String
+        value = { uri: Utils.URI(value) }
+      when URI
+        value = { uri: value }
+      when Hash, Options
+        if (uri = value.delete(:uri))
+          value[:uri] = Utils.URI(uri)
+        end
+      end
+      super(value)
+    end
+
+    memoized(:user) { uri&.user && Utils.unescape(uri.user) }
+    memoized(:password) { uri&.password && Utils.unescape(uri.password) }
+  end
+end

data/lib/faraday/options/request_options.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Faraday
+  # RequestOptions contains the configurable properties for a Faraday request.
+  class RequestOptions < Options.new(:params_encoder, :proxy, :bind,
+                                     :timeout, :open_timeout, :read_timeout,
+                                     :write_timeout, :boundary, :oauth,
+                                     :context, :on_data)
+
+    def []=(key, value)
+      if key && key.to_sym == :proxy
+        super(key, value ? ProxyOptions.from(value) : nil)
+      else
+        super(key, value)
+      end
+    end
+
+    def stream_response?
+      on_data.is_a?(Proc)
+    end
+  end
+end

data/lib/faraday/options/ssl_options.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Faraday
+  # SSL-related options.
+  #
+  # @!attribute verify
+  #   @return [Boolean] whether to verify SSL certificates or not
+  #
+  # @!attribute ca_file
+  #   @return [String] CA file
+  #
+  # @!attribute ca_path
+  #   @return [String] CA path
+  #
+  # @!attribute verify_mode
+  #   @return [Integer] Any `OpenSSL::SSL::` constant (see https://ruby-doc.org/stdlib-2.5.1/libdoc/openssl/rdoc/OpenSSL/SSL.html)
+  #
+  # @!attribute cert_store
+  #   @return [OpenSSL::X509::Store] certificate store
+  #
+  # @!attribute client_cert
+  #   @return [String, OpenSSL::X509::Certificate] client certificate
+  #
+  # @!attribute client_key
+  #   @return [String, OpenSSL::PKey::RSA, OpenSSL::PKey::DSA] client key
+  #
+  # @!attribute certificate
+  #   @return [OpenSSL::X509::Certificate] certificate (Excon only)
+  #
+  # @!attribute private_key
+  #   @return [OpenSSL::PKey::RSA, OpenSSL::PKey::DSA] private key (Excon only)
+  #
+  # @!attribute verify_depth
+  #   @return [Integer] maximum depth for the certificate chain verification
+  #
+  # @!attribute version
+  #   @return [String, Symbol] SSL version (see https://ruby-doc.org/stdlib-2.5.1/libdoc/openssl/rdoc/OpenSSL/SSL/SSLContext.html#method-i-ssl_version-3D)
+  #
+  # @!attribute min_version
+  #   @return [String, Symbol] minimum SSL version (see https://ruby-doc.org/stdlib-2.5.1/libdoc/openssl/rdoc/OpenSSL/SSL/SSLContext.html#method-i-min_version-3D)
+  #
+  # @!attribute max_version
+  #   @return [String, Symbol] maximum SSL version (see https://ruby-doc.org/stdlib-2.5.1/libdoc/openssl/rdoc/OpenSSL/SSL/SSLContext.html#method-i-max_version-3D)
+  class SSLOptions < Options.new(:verify, :ca_file, :ca_path, :verify_mode,
+                                 :cert_store, :client_cert, :client_key,
+                                 :certificate, :private_key, :verify_depth,
+                                 :version, :min_version, :max_version)
+
+    # @return [Boolean] true if should verify
+    def verify?
+      verify != false
+    end
+
+    # @return [Boolean] true if should not verify
+    def disable?
+      !verify?
+    end
+  end
+end

data/lib/faraday/options.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+module Faraday
+  # Subclasses Struct with some special helpers for converting from a Hash to
+  # a Struct.
+  class Options < Struct
+    # Public
+    def self.from(value)
+      value ? new.update(value) : new
+    end
+
+    # Public
+    def each
+      return to_enum(:each) unless block_given?
+
+      members.each do |key|
+        yield(key.to_sym, send(key))
+      end
+    end
+
+    # Public
+    def update(obj)
+      obj.each do |key, value|
+        sub_options = self.class.options_for(key)
+        if sub_options
+          new_value = sub_options.from(value) if value
+        elsif value.is_a?(Hash)
+          new_value = value.dup
+        else
+          new_value = value
+        end
+
+        send("#{key}=", new_value) unless new_value.nil?
+      end
+      self
+    end
+
+    # Public
+    def delete(key)
+      value = send(key)
+      send("#{key}=", nil)
+      value
+    end
+
+    # Public
+    def clear
+      members.each { |member| delete(member) }
+    end
+
+    # Public
+    def merge!(other)
+      other.each do |key, other_value|
+        self_value = send(key)
+        sub_options = self.class.options_for(key)
+        new_value = if self_value && sub_options && other_value
+                      self_value.merge(other_value)
+                    else
+                      other_value
+                    end
+        send("#{key}=", new_value) unless new_value.nil?
+      end
+      self
+    end
+
+    # Public
+    def merge(other)
+      dup.merge!(other)
+    end
+
+    # Public
+    def deep_dup
+      self.class.from(self)
+    end
+
+    # Public
+    def fetch(key, *args)
+      unless symbolized_key_set.include?(key.to_sym)
+        key_setter = "#{key}="
+        if !args.empty?
+          send(key_setter, args.first)
+        elsif block_given?
+          send(key_setter, yield(key))
+        else
+          raise self.class.fetch_error_class, "key not found: #{key.inspect}"
+        end
+      end
+      send(key)
+    end
+
+    # Public
+    def values_at(*keys)
+      keys.map { |key| send(key) }
+    end
+
+    # Public
+    def keys
+      members.reject { |member| send(member).nil? }
+    end
+
+    # Public
+    def empty?
+      keys.empty?
+    end
+
+    # Public
+    def each_key
+      return to_enum(:each_key) unless block_given?
+
+      keys.each do |key|
+        yield(key)
+      end
+    end
+
+    # Public
+    def key?(key)
+      keys.include?(key)
+    end
+
+    alias has_key? key?
+
+    # Public
+    def each_value
+      return to_enum(:each_value) unless block_given?
+
+      values.each do |value|
+        yield(value)
+      end
+    end
+
+    # Public
+    def value?(value)
+      values.include?(value)
+    end
+
+    alias has_value? value?
+
+    # Public
+    def to_hash
+      hash = {}
+      members.each do |key|
+        value = send(key)
+        hash[key.to_sym] = value unless value.nil?
+      end
+      hash
+    end
+
+    # Internal
+    def inspect
+      values = []
+      members.each do |member|
+        value = send(member)
+        values << "#{member}=#{value.inspect}" if value
+      end
+      values = values.empty? ? '(empty)' : values.join(', ')
+
+      %(#<#{self.class} #{values}>)
+    end
+
+    # Internal
+    def self.options(mapping)
+      attribute_options.update(mapping)
+    end
+
+    # Internal
+    def self.options_for(key)
+      attribute_options[key]
+    end
+
+    # Internal
+    def self.attribute_options
+      @attribute_options ||= {}
+    end
+
+    def self.memoized(key, &block)
+      unless block_given?
+        raise ArgumentError, '#memoized must be called with a block'
+      end
+
+      memoized_attributes[key.to_sym] = block
+      class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def #{key}() self[:#{key}]; end
+      RUBY
+    end
+
+    def self.memoized_attributes
+      @memoized_attributes ||= {}
+    end
+
+    def [](key)
+      key = key.to_sym
+      if (method = self.class.memoized_attributes[key])
+        super(key) || (self[key] = instance_eval(&method))
+      else
+        super
+      end
+    end
+
+    def symbolized_key_set
+      @symbolized_key_set ||= Set.new(keys.map(&:to_sym))
+    end
+
+    def self.inherited(subclass)
+      super
+      subclass.attribute_options.update(attribute_options)
+      subclass.memoized_attributes.update(memoized_attributes)
+    end
+
+    def self.fetch_error_class
+      @fetch_error_class ||= if Object.const_defined?(:KeyError)
+                               ::KeyError
+                             else
+                               ::IndexError
+                             end
+    end
+  end
+end
+
+require 'faraday/options/request_options'
+require 'faraday/options/ssl_options'
+require 'faraday/options/proxy_options'
+require 'faraday/options/connection_options'
+require 'faraday/options/env'