faraday 0.17.1 → 1.1.0

data/lib/faraday/rack_builder.rb

@@ -1,12 +1,21 @@
+# frozen_string_literal: true
+
+require 'ruby2_keywords'
+require 'faraday/adapter_registry'
+
 module Faraday
   # A Builder that processes requests into responses by passing through an inner
   # middleware stack (heavily inspired by Rack).
   #
-  #   Faraday::Connection.new(:url => 'http://sushi.com') do |builder|
+  # @example
+  #   Faraday::Connection.new(url: 'http://sushi.com') do |builder|
   #     builder.request  :url_encoded  # Faraday::Request::UrlEncoded
   #     builder.adapter  :net_http     # Faraday::Adapter::NetHttp
   #   end
   class RackBuilder
+    # Used to detect missing arguments
+    NO_ARGUMENT = Object.new
+
     attr_accessor :handlers
 
     # Error raised when trying to modify the stack after calling `lock!`
@@ -15,28 +24,28 @@ module Faraday
     # borrowed from ActiveSupport::Dependencies::Reference &
     # ActionDispatch::MiddlewareStack::Middleware
     class Handler
-      @@constants_mutex = Mutex.new
-      @@constants = Hash.new { |h, k|
-        value = k.respond_to?(:constantize) ? k.constantize : Object.const_get(k)
-        @@constants_mutex.synchronize { h[k] = value }
-      }
+      REGISTRY = Faraday::AdapterRegistry.new
 
       attr_reader :name
 
-      def initialize(klass, *args, &block)
+      ruby2_keywords def initialize(klass, *args, &block)
         @name = klass.to_s
-        if klass.respond_to?(:name)
-          @@constants_mutex.synchronize { @@constants[@name] = klass }
-        end
-        @args, @block = args, block
+        REGISTRY.set(klass) if klass.respond_to?(:name)
+        @args = args
+        @block = block
       end
 
-      def klass() @@constants[@name] end
-      def inspect() @name end
+      def klass
+        REGISTRY.get(@name)
+      end
+
+      def inspect
+        @name
+      end
 
       def ==(other)
         if other.is_a? Handler
-          self.name == other.name
+          name == other.name
         elsif other.respond_to? :name
           klass == other
         else
@@ -44,18 +53,19 @@ module Faraday
         end
       end
 
-      def build(app)
+      def build(app = nil)
         klass.new(app, *@args, &@block)
       end
     end
 
-    def initialize(handlers = [])
+    def initialize(handlers = [], adapter = nil, &block)
+      @adapter = adapter
       @handlers = handlers
       if block_given?
-        build(&Proc.new)
+        build(&block)
       elsif @handlers.empty?
         # default stack, if nothing else is configured
-        self.request :url_encoded
+        request :url_encoded
         self.adapter Faraday.default_adapter
       end
     end
@@ -64,13 +74,14 @@ module Faraday
       raise_if_locked
       @handlers.clear unless options[:keep]
       yield(self) if block_given?
+      adapter(Faraday.default_adapter) unless @adapter
     end
 
     def [](idx)
       @handlers[idx]
     end
 
-    # Locks the middleware stack to ensure no further modifications are possible.
+    # Locks the middleware stack to ensure no further modifications are made.
     def lock!
       @handlers.freeze
     end
@@ -79,46 +90,48 @@ module Faraday
       @handlers.frozen?
     end
 
-    def use(klass, *args, &block)
+    ruby2_keywords def use(klass, *args, &block)
       if klass.is_a? Symbol
         use_symbol(Faraday::Middleware, klass, *args, &block)
       else
         raise_if_locked
-        warn_middleware_after_adapter if adapter_set?
+        raise_if_adapter(klass)
         @handlers << self.class::Handler.new(klass, *args, &block)
       end
     end
 
-    def request(key, *args, &block)
+    ruby2_keywords def request(key, *args, &block)
       use_symbol(Faraday::Request, key, *args, &block)
     end
 
-    def response(key, *args, &block)
+    ruby2_keywords def response(key, *args, &block)
       use_symbol(Faraday::Response, key, *args, &block)
     end
 
-    def adapter(key, *args, &block)
-      use_symbol(Faraday::Adapter, key, *args, &block)
+    ruby2_keywords def adapter(klass = NO_ARGUMENT, *args, &block)
+      return @adapter if klass == NO_ARGUMENT
+
+      klass = Faraday::Adapter.lookup_middleware(klass) if klass.is_a?(Symbol)
+      @adapter = self.class::Handler.new(klass, *args, &block)
     end
 
     ## methods to push onto the various positions in the stack:
 
-    def insert(index, *args, &block)
+    ruby2_keywords def insert(index, *args, &block)
       raise_if_locked
       index = assert_index(index)
-      warn_middleware_after_adapter if inserting_after_adapter?(index)
       handler = self.class::Handler.new(*args, &block)
       @handlers.insert(index, handler)
     end
 
-    alias_method :insert_before, :insert
+    alias insert_before insert
 
-    def insert_after(index, *args, &block)
+    ruby2_keywords def insert_after(index, *args, &block)
       index = assert_index(index)
       insert(index + 1, *args, &block)
     end
 
-    def swap(index, *args, &block)
+    ruby2_keywords def swap(index, *args, &block)
       raise_if_locked
       index = assert_index(index)
       @handlers.delete_at(index)
@@ -133,13 +146,11 @@ module Faraday
     # Processes a Request into a Response by passing it through this Builder's
     # middleware stack.
     #
-    # connection - Faraday::Connection
-    # request    - Faraday::Request
+    # @param connection [Faraday::Connection]
+    # @param request [Faraday::Request]
     #
-    # Returns a Faraday::Response.
+    # @return [Faraday::Response]
     def build_response(connection, request)
-      warn 'WARNING: No adapter was configured for this request' unless adapter_set?
-
       app.call(build_env(connection, request))
     end
 
@@ -153,30 +164,30 @@ module Faraday
     def app
       @app ||= begin
         lock!
-        to_app(lambda { |env|
-          response = Response.new
-          env.response = response
-          response.finish(env) unless env.parallel?
-          response
-        })
+        to_app
       end
     end
 
-    def to_app(inner_app)
+    def to_app
       # last added handler is the deepest and thus closest to the inner app
-      @handlers.reverse.inject(inner_app) { |app, handler| handler.build(app) }
+      # adapter is always the last one
+      @handlers.reverse.inject(@adapter.build) do |app, handler|
+        handler.build(app)
+      end
     end
 
     def ==(other)
-      other.is_a?(self.class) && @handlers == other.handlers
+      other.is_a?(self.class) &&
+        @handlers == other.handlers &&
+        @adapter == other.adapter
     end
 
     def dup
-      self.class.new(@handlers.dup)
+      self.class.new(@handlers.dup, @adapter.dup)
     end
 
     # ENV Keys
-    # :method - a symbolized request method (:get, :post)
+    # :http_method - a symbolized request HTTP 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
@@ -192,45 +203,46 @@ module Faraday
     #     :password   - Proxy server password
     # :ssl - Hash of options for configuring SSL requests.
     def build_env(connection, request)
-      Env.new(request.method, request.body,
-        connection.build_exclusive_url(request.path, request.params, request.options.params_encoder),
-        request.options, request.headers, connection.ssl,
-        connection.parallel_manager)
+      exclusive_url = connection.build_exclusive_url(
+        request.path, request.params,
+        request.options.params_encoder
+      )
+
+      Env.new(request.http_method, request.body, exclusive_url,
+              request.options, request.headers, connection.ssl,
+              connection.parallel_manager)
     end
 
     private
 
+    LOCK_ERR = "can't modify middleware stack after making a request"
+
     def raise_if_locked
-      raise StackLocked, "can't modify middleware stack after making a request" if locked?
+      raise StackLocked, LOCK_ERR if locked?
     end
 
-    def warn_middleware_after_adapter
-      warn "WARNING: Unexpected middleware set after the adapter. " \
-        "This won't be supported from Faraday 1.0."
-    end
+    def raise_if_adapter(klass)
+      return unless is_adapter?(klass)
 
-    def adapter_set?
-      @handlers.any? { |handler| is_adapter?(handler) }
+      raise 'Adapter should be set using the `adapter` method, not `use`'
     end
 
-    def inserting_after_adapter?(index)
-      adapter_index = @handlers.find_index { |handler| is_adapter?(handler) }
-      return false if adapter_index.nil?
-
-      index > adapter_index
+    def adapter_set?
+      !@adapter.nil?
     end
 
-    def is_adapter?(handler)
-      handler.klass.ancestors.include? Faraday::Adapter
+    def is_adapter?(klass) # rubocop:disable Naming/PredicateName
+      klass <= Faraday::Adapter
     end
 
-    def use_symbol(mod, key, *args, &block)
+    ruby2_keywords def use_symbol(mod, key, *args, &block)
       use(mod.lookup_middleware(key), *args, &block)
     end
 
     def assert_index(index)
       idx = index.is_a?(Integer) ? index : @handlers.index(index)
       raise "No such handler: #{index.inspect}" unless idx
+
       idx
     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,25 +12,63 @@ module Faraday
   #     req.body = 'abc'
   #   end
   #
-  class Request < Struct.new(:method, :path, :params, :headers, :body, :options)
+  # @!attribute http_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(
+    :http_method, :path, :params, :headers, :body, :options
+  )
+    # rubocop:enable Style/StructInheritance
+
     extend MiddlewareRegistry
 
-    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']
+    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?
       end
     end
 
-    # Public: Replace params, preserving the existing hash type
+    def method
+      warn <<~TEXT
+        WARNING: `Faraday::Request##{__method__}` is deprecated; use `#http_method` instead. It will be removed in or after version 2.0.
+        `Faraday::Request##{__method__}` called from #{caller_locations(1..1).first}
+      TEXT
+      http_method
+    end
+
+    # Replace params, preserving the existing hash type.
+    #
+    # @param hash [Hash] new params
     def params=(hash)
       if params
         params.replace hash
@@ -36,7 +77,9 @@ module Faraday
       end
     end
 
-    # Public: Replace request headers, preserving the existing hash type
+    # Replace request headers, preserving the existing hash type.
+    #
+    # @param hash [Hash] new headers
     def headers=(hash)
       if headers
         headers.replace hash
@@ -45,9 +88,14 @@ 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
@@ -61,54 +109,48 @@ 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
+        http_method: http_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]
-      self.headers = serialised[:headers]
-      self.path    = serialised[:path]
-      self.params  = serialised[:params]
-      self.options = serialised[:options]
+      self.http_method = serialised[:http_method]
+      self.body        = serialised[:body]
+      self.headers     = serialised[:headers]
+      self.path        = serialised[:path]
+      self.params      = serialised[:params]
+      self.options     = serialised[:options]
     end
 
-    # 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.
+    # @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)
+      Env.new(http_method, body, connection.build_exclusive_url(path, params),
+              options, headers, connection.ssl, connection.parallel_manager)
     end
   end
 end
-